127 lines
7.0 KiB
Markdown
127 lines
7.0 KiB
Markdown
# FEAT-MO-004 指数与板块详情分析页设计
|
||
|
||
## 目标
|
||
|
||
在市场综合概览首屏点击指数或板块后，进入可复盘的详情页，展示经过 TDX 校验的行情、交易日期、状态、K 线和可用的分时数据，并保持当前只读、无交易建议的数据边界。
|
||
|
||
## 已确认范围
|
||
|
||
- 第一版产品范围同时包含指数详情和板块详情。
|
||
- 实施采用两个纵向切片：先完成指数详情，再接入板块详情。
|
||
- 两类详情共用页面外壳、路由参数校验、数据状态、更新时间、数据来源、警告和图表容器。
|
||
- 首版不包含成分股排名、主力净流入、盘中新闻、AI 结论、交易操作、用户体系和订阅功能。
|
||
- 后端继续返回标准 UTC ISO `asOf`；Web 按 `Asia/Shanghai` 格式化展示。
|
||
|
||
## 设计原则
|
||
|
||
1. **真实数据优先**：TDX 未验证的字段显示不可用或延迟状态，不使用模拟数据或离线样本伪造实时行情。
|
||
2. **模块级降级**：详情数据失败不影响首页概览，K 线、分时和摘要分别保留状态。
|
||
3. **契约先行**：详情 API 独立于首页五个概览接口，不把详情数据追加到首页接口的大对象中。
|
||
4. **共享稳定边界**：指数和板块只共享详情外壳、时间/状态显示和图表输入契约；数据映射仍按 TDX 业务口径分别维护。
|
||
5. **只读安全**：详情请求只允许白名单代码、有限周期和有限数量，禁止把任意 TDX 方法名或原始字段暴露给 Web。
|
||
|
||
## 技术方案
|
||
|
||
### 页面与路由
|
||
|
||
新增一个详情页组件，根据类型和代码加载对应 API：
|
||
|
||
```text
|
||
/market-overview/indices/:code
|
||
/market-overview/sectors/:code
|
||
```
|
||
|
||
路由参数只接受已知格式：指数代码必须匹配已登记指数或 TDX 返回的合法指数代码；板块代码必须来自已登记一级行业目录。非法代码进入明确的不可用页面，不触发 TDX 请求。
|
||
|
||
详情页结构固定为：
|
||
|
||
1. 返回概览与标题区：名称、代码、TDX 来源、上海时间更新时间、交易日期和状态。
|
||
2. 核心行情区：最新价/涨跌幅（指数）或涨跌幅/强弱等级（板块），成交额按实际可用字段展示。
|
||
3. 图表区：K 线为首要视图；分时视图只有在 TDX 能力探测通过后启用，否则展示“当前数据源未提供分时数据”的边界说明。
|
||
4. 数据质量区：`fresh`、`delayed`、`partial`、`unavailable` 和 warnings 与首页一致。
|
||
5. 复盘摘要区：只展示事实型数据和规则计算结果，不产生买入、卖出、目标价或仓位建议。
|
||
|
||
### 后端接口
|
||
|
||
新增两个独立接口，参数和响应保持有限、可验证：
|
||
|
||
```text
|
||
GET /api/v1/market-overview/indices/:code/detail?period=1d&count=120
|
||
GET /api/v1/market-overview/sectors/:code/detail?period=1d&count=120
|
||
```
|
||
|
||
响应统一包含现有 `MarketOverviewMetaDto` 字段：
|
||
|
||
```text
|
||
snapshotId
|
||
asOf
|
||
source
|
||
status
|
||
warnings
|
||
data
|
||
```
|
||
|
||
`data` 最小结构：
|
||
|
||
```text
|
||
instrument: { code, name, type }
|
||
quote: { price, changePercent, direction, tradeDate }
|
||
series: [{ time, open, high, low, close, amount, volume }]
|
||
availableViews: { kline: boolean, intraday: boolean }
|
||
```
|
||
|
||
指数和板块的数据 DTO 可以共享 K 线点类型，但 `quote` 和摘要字段必须保持各自业务口径。`series` 的数量上限由服务端固定在 120 条以内，避免任意参数导致 TDX 响应膨胀。
|
||
|
||
### TDX 能力验证门
|
||
|
||
在实现详情 API 前先对当前 TDX 桥接执行只读能力探测并保存脱敏报告：
|
||
|
||
- 已验证的 `get_market_data` 日线数据继续作为 K 线来源。
|
||
- 探测分时方法、参数格式、响应日期/时间字段和单次返回上限。
|
||
- 如果分时能力未通过协议、字段完整性或稳定性检查，首版只发布 K 线，API 和 UI 明确返回 `intraday=false`，不创建假分时数据。
|
||
- 板块详情先验证一级行业代码在历史 K 线查询中的可用性，再实现板块图表。
|
||
|
||
### 前端 API 与图表
|
||
|
||
- 所有请求继续位于 `web/src/api/market-overview/index.ts` 或同域详情 API 文件，并通过 `web/src/utils/request.ts` 的 Axios 封装。
|
||
- `web/src/views/market-overview/detail/` 管理详情页、状态和图表输入适配；页面不得直接调用 Axios 或 TDX。
|
||
- 首选轻量图表库；在能力探测和依赖评估完成前不新增依赖。评估维度包括 K 线/分时能力、Vue 3 兼容性、包体积、许可证、无障碍、销毁重建、移动端性能和退出方案。
|
||
- 若新增图表依赖，必须在设计和 Review 中记录替代方案、许可证和包体积证据。
|
||
|
||
## 数据状态和错误处理
|
||
|
||
- `fresh`：数据完整且交易日期与上海当前日期一致。
|
||
- `delayed`：数据可用但交易日期不是上海当前日期，显示实际交易日期。
|
||
- `partial`：部分 K 线、摘要或视图不可用，保留有效数据并展示 warning。
|
||
- `unavailable`：代码不存在、TDX 不可达、协议错误或没有有效数据，页面不展示伪造图表。
|
||
- TDX 原始地址、请求体、凭据和原始异常不进入 Web 响应；错误只返回固定分类文案。
|
||
|
||
## 安全与性能
|
||
|
||
- 代码、周期和数量在 Controller/Service 双层校验；只允许已登记业务代码和 `1d` 等已验证周期。
|
||
- TDX 客户端继续使用超时、响应体上限、固定回环地址和错误脱敏。
|
||
- 单个详情请求最多读取 120 个 K 线点；不在首版引入数据库、Redis、RocketMQ 或后台任务。
|
||
- 图表数据在页面卸载时释放实例；加载状态固定容器尺寸，避免数据返回造成布局跳动。
|
||
- 性能目标：本地已验证 TDX 可达时详情首屏 P95 小于 2 秒；TDX 不可达时 10 秒内返回明确不可用状态。该目标不代表生产容量证明。
|
||
|
||
## 测试与验收
|
||
|
||
- TDX Client：超时、协议错误、过大响应、业务错误和请求参数白名单。
|
||
- Mapper：合法/非法日期、空序列、倒序序列、部分字段缺失、数量上限和方向计算。
|
||
- Service：指数/板块成功、延迟、部分、不可用和模块隔离。
|
||
- HTTP/OpenAPI：两个详情路由、参数校验、DTO nullable 和错误状态。
|
||
- Web：路由参数、加载/空/错误/延迟状态、上海时间显示、K 线数据输入和移动端无横向溢出。
|
||
- 浏览器：桌面和 390px 移动视口，详情入口可达，返回首页可用，图表容器非空或显示明确不可用状态。
|
||
|
||
## 发布与回退
|
||
|
||
- 首版只在开发内网启用，继续通过 Mac 本机 TDX 隧道访问，不把 TDX 暴露到局域网或公网。
|
||
- AKTools 不参与指数/板块详情主链路；生产默认关闭。
|
||
- 回退时删除详情路由和 API 注册或回到上一个完整发布目录，不修改数据库结构，不需要数据回滚。
|
||
|
||
## 未决但有边界的事项
|
||
|
||
- 分时数据是否纳入首版由 TDX 能力探测结果决定，不以 UI 需求强行反推协议。
|
||
- 图表库在探测完成后按依赖评估选择；若原生 SVG/Canvas 足以满足首版，则不新增图表依赖。
|
||
- 成分股、资金流、新闻和 AI 另立功能，不因详情页入口提前扩大范围。
|