7.0 KiB
7.0 KiB
FEAT-MO-004 指数与板块详情分析页设计
目标
在市场综合概览首屏点击指数或板块后，进入可复盘的详情页，展示经过 TDX 校验的行情、交易日期、状态、K 线和可用的分时数据，并保持当前只读、无交易建议的数据边界。
已确认范围
- 第一版产品范围同时包含指数详情和板块详情。
- 实施采用两个纵向切片：先完成指数详情，再接入板块详情。
- 两类详情共用页面外壳、路由参数校验、数据状态、更新时间、数据来源、警告和图表容器。
- 首版不包含成分股排名、主力净流入、盘中新闻、AI 结论、交易操作、用户体系和订阅功能。
- 后端继续返回标准 UTC ISO
asOf；Web 按Asia/Shanghai格式化展示。
设计原则
- 真实数据优先：TDX 未验证的字段显示不可用或延迟状态，不使用模拟数据或离线样本伪造实时行情。
- 模块级降级：详情数据失败不影响首页概览，K 线、分时和摘要分别保留状态。
- 契约先行：详情 API 独立于首页五个概览接口，不把详情数据追加到首页接口的大对象中。
- 共享稳定边界：指数和板块只共享详情外壳、时间/状态显示和图表输入契约；数据映射仍按 TDX 业务口径分别维护。
- 只读安全：详情请求只允许白名单代码、有限周期和有限数量，禁止把任意 TDX 方法名或原始字段暴露给 Web。
技术方案
页面与路由
新增一个详情页组件，根据类型和代码加载对应 API：
/market-overview/indices/:code
/market-overview/sectors/:code
路由参数只接受已知格式：指数代码必须匹配已登记指数或 TDX 返回的合法指数代码；板块代码必须来自已登记一级行业目录。非法代码进入明确的不可用页面，不触发 TDX 请求。
详情页结构固定为：
- 返回概览与标题区：名称、代码、TDX 来源、上海时间更新时间、交易日期和状态。
- 核心行情区：最新价/涨跌幅（指数）或涨跌幅/强弱等级（板块），成交额按实际可用字段展示。
- 图表区：K 线为首要视图；分时视图只有在 TDX 能力探测通过后启用，否则展示“当前数据源未提供分时数据”的边界说明。
- 数据质量区：
fresh、delayed、partial、unavailable和 warnings 与首页一致。 - 复盘摘要区：只展示事实型数据和规则计算结果，不产生买入、卖出、目标价或仓位建议。
后端接口
新增两个独立接口，参数和响应保持有限、可验证：
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 字段：
snapshotId
asOf
source
status
warnings
data
data 最小结构：
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 另立功能，不因详情页入口提前扩大范围。