mirror of
https://ghfast.top/https://github.com/aeroxw/easy_tdx_max.git
synced 2026-09-12 18:04:20 +08:00
274 lines
17 KiB
Markdown
274 lines
17 KiB
Markdown
# 行业总览 / 概念总览 页面设计（v1 草案）
|
||
|
||
> 目标：在 WebUI 左侧导航新增「行业总览」「概念总览」两个栏目，提供全部行业/概念板块的行情总览、
|
||
> 实用统计与板块异动监控；点击板块复用首页 `BoardDialog` 弹窗（左：分时/日K，右：成分股列表）。
|
||
|
||
---
|
||
|
||
## 1. 现状盘点（设计依据，全部为已验证的现成能力）
|
||
|
||
### 1.1 后端可复用接口（`src/easy_tdx/web/routers/board_mac.py`，前缀 `/api/v1`）
|
||
|
||
| 端点 | 能给什么 | 成本 |
|
||
|---|---|---|
|
||
| `GET /board-mac/list?board_type=HY\|HY2\|GN\|FG\|DQ&sort_column=…` | 全量板块列表：`market, code(881xxx/885xxx), name, price, pre_close, sort_value, 领涨股6字段(symbol_*)`。行业(HY)约 86 个、概念(GN)约 270–500 个；每页 150，自动翻页。排序键支持 `SPEED / CHANGE_3D / 5D / 10D / 20D / 60D / YTD` | 低（1–2 页/次） |
|
||
| `GET /board-mac/members?board_symbol=881001&count=120&sort_type=CHANGE_PCT` | 板块成分股 + 全量报价（自动 80/页翻页），弹窗已在用 | 低 |
|
||
| `GET /board-mac/summary?board_symbol=…` | `member_count, amount, vol, main_net_amount, main_net_3d/5d, up_count, down_count, members` | 高（每板块一次，概念 300+ 不可全量） |
|
||
| `GET /board-mac/ranking?board_type=…&sort_by=main_net_amount&top_n=10` | 资金/成交/涨跌幅榜（内部逐板块 summary） | 中，必须限 `top_n` |
|
||
| `GET /board-mac/change-ranking?board_type=…&days=20` | N 日区间涨幅榜（走板块指数日K） | 低 |
|
||
| `GET /market/stat` | 全市场上涨/下跌/平盘/涨停/跌停家数（880005/880001/880006） | 低 |
|
||
| `GET /minute` `/bars`（SH+88xxxx） | 板块指数分时/日K，弹窗已在用；客户端已内置换机容错 | 低 |
|
||
| `GET /market/session` | 交易时段判定，用于启停自动刷新 | 低 |
|
||
|
||
**口径注意（Issue #53）**：`sort_column=CHANGE_PCT` 时 `sort_value` 恒为 0；当日涨跌幅必须由
|
||
`price / pre_close - 1` 自行计算。其余排序键的 `sort_value` 即该指标值。
|
||
|
||
### 1.2 前端可复用资产（`web-ui/src/`）
|
||
|
||
| 资产 | 位置 | 复用方式 |
|
||
|---|---|---|
|
||
| `BoardDialog.vue` 板块弹窗 | components | **原样复用**：头部 SSE 实时报价+加/移自选；左侧分时(`IntradayChart`)/日K(`StockKline`) tab；右侧成分股涨跌榜（用户所称"下拉框"），点成分股可再叠 `StockDialog` |
|
||
| `StockDialog.vue` 个股弹窗 | components | 原样复用（成分股点击穿透） |
|
||
| 自选股体系 | stores + `watchlist.py` | 已支持板块（WatchlistView 板块行开 BoardDialog），板块行可直接加"加自选"星标 |
|
||
| ECharts 封装 | `echarts-setup.ts` | 已注册 Bar/Heatmap 等；红涨绿跌 `UP_COLOR='#ef4146'` / `DOWN_COLOR='#18a058'` |
|
||
| API 封装 | `api.ts`（`BASE='/api/v1'` + 统一错误解析） | 新增 2–3 个 fetch 函数 |
|
||
| 导航/路由 | `App.vue:26-43` + `router.ts:21-40` | 「行情」分组下加两个 RouterLink + 两条路由 |
|
||
|
||
**结论：后端仅缺一个"多指标合并"端点，前端为本需求的全部工作量主体。**
|
||
|
||
---
|
||
|
||
## 2. 总体设计
|
||
|
||
```
|
||
路由与导航（行情分组）
|
||
/industries 行业总览 ─┐
|
||
/concepts 概念总览 ─┴─ 共用 BoardOverviewView.vue，路由 props 区分 board_type
|
||
行业页额外提供 HY(一级)/HY2(二级) 切换
|
||
```
|
||
|
||
新组件（建议 4 个，均放 `components/`）：
|
||
|
||
- `BoardStatStrip.vue` — 顶部统计条（板块广度 + 全市场涨跌家数 + 涨跌幅分布直方图）
|
||
- `BoardTiles.vue` — 热力图模式（CSS Grid 色块，不用 ECharts，500 块内 DOM 足够快）
|
||
- `BoardRankRail.vue` — 右侧栏：涨幅/跌幅/涨速(异动) 榜 + 翻红翻绿时间线 + 资金榜(懒加载)
|
||
- `BoardOverviewView.vue` — 主视图：统计条 + [热力图|表格] 切换 + 右栏 + 弹窗编排
|
||
|
||
主表格直接内嵌在 View 中（与 DashboardView 同风格），不再抽组件。
|
||
|
||
---
|
||
|
||
## 3. 功能设计
|
||
|
||
### 3.1 页面信息架构（自上而下）
|
||
|
||
1. **统计条**：一眼判断今天板块层面强弱
|
||
2. **工具行**：视图切换 / 排序 / 搜索 / 自动刷新开关
|
||
3. **主区**：热力图（默认）或 全量表
|
||
4. **右栏**：榜单 + 异动（热力图模式下承担"看榜"职责，表格模式下可折叠）
|
||
|
||
### 3.2 统计条（BoardStatStrip）
|
||
|
||
数据源：1 次 `/board-mac/list`（默认排序）+ 1 次 `/market/stat`，全部前端聚合。
|
||
|
||
| 指标 | 计算 | 说明 |
|
||
|---|---|---|
|
||
| 板块总数 / 上涨 / 下跌 / 平盘 | 按 `change_pct` 正负统计本类型板块 | 如「86 个板块 · 52▲ / 30▼ / 4—」 |
|
||
| 板块涨幅中位数 | median(change_pct) | 比均值抗极值 |
|
||
| 全市场涨停/跌停家数 | `/market/stat`（×10 还原） | 判断赚钱效应 |
|
||
| 涨幅分布直方图 | change_pct 分桶(±1% 一档，截断 ±5%) 小柱图 | ECharts Bar，点击桶可过滤主区（P2） |
|
||
|
||
### 3.3 主区一：热力图模式（默认）
|
||
|
||
- **布局**：CSS Grid 自适应列（tile 最小宽 ~104px），按当前排序降序排列。
|
||
- **着色**：红涨绿跌，透明度随 `|change_pct|` 分 5 档增强（复用 UP/DOWN_COLOR）。
|
||
- **tile 内容**：板块名（超长省略）+ 当日涨跌幅；≥140px 宽度时追加领涨股名+其涨幅。
|
||
- **交互**：hover 显示 tooltip（代码/价格/涨跌幅/领涨股）；**单击打开 BoardDialog**；
|
||
右键或 tile 上的 ★ 加自选（P2）。
|
||
- **概念页适配**：500 tile 时顶部加搜索框联动高亮/过滤，tile 缩小至 ~88px。
|
||
|
||
> 为什么不用 ECharts heatmap/treemap：treemap 未注册、treemap 按市值定容缺少廉价数据源
|
||
> （逐板块 summary 不可行），等宽色块已满足"扫一眼谁强谁弱"，且交互实现最简单。
|
||
|
||
### 3.4 主区二：表格模式（全量、可排序）
|
||
|
||
列定义（行业页）：
|
||
|
||
| 列 | 来源 | 备注 |
|
||
|---|---|---|
|
||
| 名称 / 代码 | list | 点击行 → BoardDialog |
|
||
| 最新价 | list.price | |
|
||
| **涨跌幅** | price/pre_close | 默认排序列，红绿色阶背景 |
|
||
| 涨速 | list(sort_column=SPEED).sort_value | 盘中异动核心 |
|
||
| 3日 / 5日 / 20日 / YTD | list(对应 sort_column).sort_value | 见 3.7 合并策略 |
|
||
| 轮动标签 | 前端规则（3.6） | 「反弹 / 走强 / 回调 / 补跌」 |
|
||
| 领涨股(+涨幅) | list.symbol_* | 点领涨股 → StockDialog（stopPropagation） |
|
||
| 主力净额 | `/board-mac/ranking` 合并（懒加载，见 3.7） | 可空 |
|
||
| ★ | 自选 | 复用 watchlist API（P2） |
|
||
|
||
表格排序纯前端（数据已全量在内存），不再发请求。行业 86 行、概念 ≤500 行，无需虚拟滚动。
|
||
|
||
### 3.5 右栏：榜单 + 板块异动（BoardRankRail）
|
||
|
||
1. **涨幅榜 Top10 / 跌幅榜 Top10**：前端内存排序，随刷新同步。
|
||
2. **涨速榜 Top10**（"板块异动"主入口）：`sort_column=SPEED` 的 `sort_value`，
|
||
`|speed| ≥ 0.5%/5min` 的条目加闪烁高亮；点击直达 BoardDialog。
|
||
3. **翻红/翻绿时间线**：前端对相邻两次快照做 diff，`change_pct` 由负转正记「翻红」、
|
||
正转负记「翻绿」，按时间倒序展示（保留最近 30 条）。这是最低成本的"板块轮动监控"。
|
||
4. **主力资金榜 Top10**（懒加载 tab）：首次展开才调 `/board-mac/ranking?sort_by=main_net_amount&top_n=10`，
|
||
每 5 分钟刷新一次（接口较贵）。
|
||
5. **轮动信号卡**（P2）：超跌反弹聚集度（当日↑ 且 20日↓ 的板块数）等汇总提示。
|
||
|
||
### 3.6 轮动标签规则（表格列 + tile 角标）
|
||
|
||
前端基于已合并的多周期涨幅做简单规则标注（阈值可调，初版取 1%）：
|
||
|
||
| 标签 | 条件 | 含义 |
|
||
|---|---|---|
|
||
| 超跌反弹 | 当日 > +1% 且 20日 < -3% | 前期弱势，今日异动 |
|
||
| 趋势走强 | 当日>0 且 3日>0 且 5日>0 | 多周期共振向上 |
|
||
| 高位回调 | 当日 < -1% 且 20日 > +5% | 强势板块补跌 |
|
||
| 趋势走弱 | 当日<0 且 3日<0 且 5日<0 | 多周期共振向下 |
|
||
|
||
规则透明、可解释，不引入额外请求。
|
||
|
||
### 3.7 数据获取与刷新策略
|
||
|
||
**合并请求（关键设计）**：页面一次刷新需要 6 种排序的 list（当日、涨速、3日、5日、20日、YTD）。
|
||
前端直连将产生 6–12 个 MAC 请求/次。因此新增一个后端聚合端点：
|
||
|
||
```
|
||
GET /api/v1/board-mac/overview?board_type=HY&metrics=speed,3d,5d,20d,ytd
|
||
→ {
|
||
board_type: "HY",
|
||
ts: 1725400000,
|
||
rows: [{
|
||
market: 1, code: "881106", name: "种植业",
|
||
price: 1039.93, pre_close: 1031.20, change_pct: 0.846, // 服务端算好
|
||
speed: 0.32, chg_3d: 2.1, chg_5d: -0.8, chg_20d: 6.3, chg_ytd: 14.2,
|
||
leader_code: "600xxx", leader_name: "xxx", leader_change_pct: 10.02
|
||
}, ...]
|
||
}
|
||
```
|
||
|
||
- 服务端并发拉取各 sort_column 的 list 后按 code 归并，任一指标缺失置 null（不阻塞整体）。
|
||
- **服务端缓存 15s**（TTL），多人/多页共享，保护 MAC 服务器。
|
||
- 前端 30s 轮询（仅交易时段，`/market/session` 判定），手动 ⟳ 随时可用；页面不可见时暂停
|
||
（`document.visibilitychange`）。
|
||
- 降级：`/board-mac/overview` 不可用时前端回退为直连 6 次 `/board-mac/list` 并归并（同口径函数复用）。
|
||
|
||
**懒加载项**：主力资金榜（首次展开）、板块弹窗内容（点击时，BoardDialog 自理）。
|
||
|
||
### 3.8 行业页 vs 概念页差异
|
||
|
||
| 维度 | 行业总览 (`HY`) | 概念总览 (`GN`) |
|
||
|---|---|---|
|
||
| 板块数量级 | ~86 | ~270–500 |
|
||
| 二级切换 | 一级(HY) / 二级(HY2) toggle | 无 |
|
||
| 搜索框 | 有（按名/代码） | **显著位置**，支持拼音/关键词过滤 |
|
||
| 热力图 tile | 104px | 88px |
|
||
| 其余（统计条/榜单/异动/弹窗/刷新） | 完全一致 | 完全一致 |
|
||
|
||
同一组件路由 props 驱动，后续 `FG`(风格)/`DQ`(地域) 仅需在 App.vue 加入口 + 传 props。
|
||
|
||
### 3.9 板块弹窗（点击板块）
|
||
|
||
**原样复用 `BoardDialog.vue`**（与首页体验一致）：
|
||
|
||
- 头部：板块名 + SSE 实时报价 + 加/移自选 + 关闭
|
||
- 左侧：分时（`/minute`，SH+881xxx/885xxx）/ 日K（`/bars`，MA/MACD/KDJ 等指标前端本地算）
|
||
- 右侧 330px 成分股涨跌榜：`/board-mac/members`，支持点击成分股叠加 `StockDialog`（五档盘口+K线）
|
||
|
||
增量增强（P2，可选）：弹窗右侧顶部补一行成分股广度（`up_count/down_count`，来自 summary，单板块成本可接受）。
|
||
|
||
---
|
||
|
||
## 4. UI 布局设计
|
||
|
||
### 4.1 线框
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────────────────┐
|
||
│ 行业总览 86个板块 52▲ 30▼ 4— │ 中位 +0.84% │ 涨停23 跌停5 │ ▂▄▆█▆▄▂ 分布图 │
|
||
├────────────────────────────────────────────────────────────────────────────┤
|
||
│ [热力图|表格] 排序[涨跌幅▾] [搜索____] HY/HY2 ⟳30s[ON] 上次刷新 14:32:05 │
|
||
├───────────────────────────────────────────────┬────────────────────────────┤
|
||
│ │ 涨幅榜 Top10 │
|
||
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌───────┐ │ 1 种植业 +3.21% │
|
||
│ │种植业 │ │渔业 │ │煤炭开采│ │... │ │ 2 ... │
|
||
│ │ +3.21% │ │ +2.88% │ │ +2.10% │ │ │ │ 跌幅榜 Top10 │
|
||
│ │领涨 xx │ │ │ │ │ │ │ │ 异动(涨速) Top10 ⚡闪烁 │
|
||
│ └────────┘ └────────┘ └────────┘ └───────┘ │ … │
|
||
│ ┌────────┐ ┌────────┐ ... │ ────────────────────── │
|
||
│ │概念名… │ │ │ │ 翻红/翻绿 时间线 │
|
||
│ └────────┘ └────────┘ │ 14:31 翻红 生物疫苗 │
|
||
│ │ 14:28 翻绿 房地产开发 │
|
||
│ （表格模式：3.4 节列定义，同区域替换） │ [资金榜 Top10 ▸懒加载] │
|
||
├───────────────────────────────────────────────┴────────────────────────────┤
|
||
│ 单击板块 → BoardDialog 弹窗（左 分时/日K ｜ 右 成分股涨跌榜 → StockDialog） │
|
||
└────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 交互与视觉细则
|
||
|
||
- **配色**：沿用全局主题变量与 `UP_COLOR/DOWN_COLOR`；色阶透明度 5 档：0–0.5% / 0.5–1 / 1–2 / 2–3 / >3%。
|
||
- **弹窗层级**：与首页一致（BoardDialog teleport to body，1280px 遮罩弹窗）；成分股→StockDialog 叠加。
|
||
- **空/错误态**：接口失败 → 顶部错误条（api.ts 统一 `{error,detail}` 解析）+ 重试按钮；
|
||
非交易时段显示"休市中，显示最近收盘数据"徽标。
|
||
- **响应式**：右栏 ≥1280px 常驻，<1280px 折叠为顶部横向 chips；主区 tile 自动换列。
|
||
- **localStorage 偏好**：视图模式 / 排序列 / 自动刷新开关（P2）。
|
||
|
||
---
|
||
|
||
## 5. 改动清单（实施落点）
|
||
|
||
### 后端（仅 1 个新端点）
|
||
|
||
| 文件 | 改动 |
|
||
|---|---|
|
||
| `src/easy_tdx/web/routers/board_mac.py` | 新增 `GET /board-mac/overview`：并发聚合多 sort_column 的 `MacClient.get_board_list`，计算 change_pct，按 code 归并；模块级 TTL 缓存(15s) |
|
||
| `tests/unit/test_board_mac_overview.py` | 单测：归并正确性 / 缺失指标置 null / 缓存命中（mock AsyncMacClient） |
|
||
|
||
### 前端
|
||
|
||
| 文件 | 改动 |
|
||
|---|---|
|
||
| `web-ui/src/App.vue` | 行情分组 +2 RouterLink（行业总览 `/industries`、概念总览 `/concepts`） |
|
||
| `web-ui/src/router.ts` | 两条路由 → `BoardOverviewView`，`props: { boardType: 'HY' \| 'GN' }` |
|
||
| `web-ui/src/types.ts` | `BoardOverviewRow / BoardOverviewResp / BoardRankRow` 类型 |
|
||
| `web-ui/src/api.ts` | `fetchBoardOverview(boardType, metrics)`；`fetchBoardRanking` 薄封装（复用现有错误处理） |
|
||
| `web-ui/src/views/BoardOverviewView.vue` | 主视图（统计条编排 / 工具行 / 热力图⇄表格 / 右栏 / 弹窗编排 / 轮询与 diff） |
|
||
| `web-ui/src/components/BoardStatStrip.vue` | 统计条 + 分布直方图 |
|
||
| `web-ui/src/components/BoardTiles.vue` | 热力图模式 |
|
||
| `web-ui/src/components/BoardRankRail.vue` | 榜单 + 翻红翻绿时间线 + 资金懒加载 |
|
||
|
||
---
|
||
|
||
## 6. 边界与风险
|
||
|
||
1. **MAC 服务器可用性**：`get_board_list` 依赖 MAC host（`get_mac_hosts`）；客户端已有故障转移，
|
||
overview 端点失败时前端展示错误条并可回退直连。
|
||
2. **板块指数 K 线缺数据**：部分服务器不给 88xxxx 日K——仅影响 `change-ranking`（本设计未依赖它做主指标，
|
||
多周期涨幅全部来自 board list），弹窗日K沿用现有换机容错。
|
||
3. **概念数量大**：500 个 tile / 行的渲染无压力；`/board-mac/ranking`（逐板块 summary）只允许 top_n 懒加载。
|
||
4. **盘中口径**：当日涨跌幅一律 `price/pre_close-1`，禁止使用 CHANGE_PCT 排序的 sort_value（恒 0，Issue #53）。
|
||
5. **刷新风暴**：TTL 缓存 + visibilitychange 暂停 + 30s 间隔，三重保护。
|
||
|
||
## 7. 分期计划
|
||
|
||
| 期 | 内容 | 预估 |
|
||
|---|---|---|
|
||
| **P1（MVP）** | 导航+路由、BoardOverviewView（热力图+表格+搜索）、统计条、右栏涨幅/跌幅/涨速榜、翻红翻绿时间线、30s 自动刷新、BoardDialog 复用、`/board-mac/overview` 端点+缓存+单测 | 1.5–2 天 |
|
||
| **P2** | 主力资金榜懒加载、轮动标签、tile ★加自选、直方图点击过滤、localStorage 偏好、HY2 切换打磨、休市徽标 | 1 天 |
|
||
| **P3（远期）** | FG/DQ 入口、板块间对比（多选叠加K线）、"点击板块过滤全市场个股"联动、板块轮动 AI 解读 | 另立项 |
|
||
|
||
## 8. 验收清单（P1）
|
||
|
||
- [ ] 左侧导航出现两个新栏目，路由/高亮/刷新兜底均正常
|
||
- [ ] 行业页展示全部 ~86 个行业（HY，且可切 HY2），概念页展示全部概念（≈300+），数量与 `/board-mac/list` 原始返回一致
|
||
- [ ] 当日涨跌幅与通达信客户端同口径（price/pre_close），排序、搜索、色阶正确
|
||
- [ ] 单击板块 tile/行 → BoardDialog：分时、日K、成分股榜、成分股→StockDialog 全链路可用
|
||
- [ ] 交易时段 30s 自动刷新且网络面板只有 1 个 overview 请求；休市自动停止
|
||
- [ ] 涨速榜闪烁、翻红/翻绿时间线在盘中可见事件产生
|
||
- [ ] 断开 MAC 服务器时出现错误条 + 重试，页面不白屏
|