feat(FEAT-MO-004): 实现指数板块详情分析页

2026-08-25 00:16:43 +08:00
parent f8f4da93dc
commit 0131f863b6
32 changed files with 2262 additions and 8 deletions
@@ -0,0 +1,10 @@
+# FEAT-MO-004 设计说明
+
+设计基线为 `docs/superpowers/specs/2026-08-24-index-sector-detail-design.md`。
+
+后端新增详情 Controller/Service/Mapper，复用现有 TDX Client 的超时、响应体上限和错误脱敏边界；指数和板块使用独立代码白名单和数据口径。前端新增详情路由、独立 Axios API 文件、共享详情页和轻量 SVG K 线图，概览按钮仅负责导航。
+
+详情数据失败采用模块级降级，页面仍保留标题、来源、更新时间和 warning。分时能力不通过探测时不返回假数据，UI 只展示明确的不可用边界。
+
+安全策略：Controller/Service 双层参数校验、代码白名单、固定周期、数量上限、响应字段白名单和错误脱敏。性能策略：单次最多 120 点、固定图表尺寸、页面卸载释放图表状态，不新增数据库和缓存热点。
+
@@ -0,0 +1,28 @@
+# GitNexus 开发前基线
+
+- 功能编号：FEAT-MO-004
+- 记录时间：2026年8月24日 GMT+8 23:37:42
+- 分支：main
+- 基线提交：f8f4da93dc8f
+
+## 工作区
+
+```text
+?? "SRMS3.6.0\345\270\270\350\247\201\351\227\256\351\242\230\346\265\213\350\257\204\351\242\230.2csv"
+?? docs/features/FEAT-MO-004-index-sector-detail/
+?? docs/superpowers/plans/2026-08-24-index-sector-detail.md
+```
+
+## GitNexus 状态
+
+```text
+Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
+Indexed: 8/24/2026, 11:37:41 PM
+Indexed commit: f8f4da9
+Current commit: f8f4da9
+Status: ✅ up-to-date
+```
+
+## 后续人工分析
+
+在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
@@ -0,0 +1,37 @@
+# GitNexus 开发前影响计划
+
+- 功能编号：FEAT-MO-004
+- 总体风险：MEDIUM（既有概览服务扩展会触及 Controller、模块、服务测试和 OpenAPI 导出；无 HIGH/CRITICAL）
+
+## 直接与间接影响
+
+### 查询与上下文
+
+- GitNexus 仓库：`a-share-analysis`，开发前索引与 `f8f4da9` 一致且 up-to-date。
+- 影响目标：`MarketOverviewController`、`MarketOverviewService`、`createTdxClient`、`createAppRouter`。
+- `MarketOverviewController` upstream：3 个直接文件消费者（概览 E2E、OpenAPI 导出、模块注册），总影响 7 个文件，风险 LOW。
+- `MarketOverviewService` upstream：5 个直接文件消费者（概览 E2E、服务测试、OpenAPI 导出、Controller、模块），总影响 9 个文件，风险 MEDIUM。
+- `createTdxClient` upstream：TDX Client 单元测试 1 个直接消费者，风险 LOW；详情复用其稳定 `request<T>()` 边界，不修改协议实现。
+- `createAppRouter` upstream：`App.test.ts` 1 个直接消费者，风险 LOW；新增路由需要补充路由测试和根路径回归。
+- `MarketOverviewPage` 未被索引为符号，按文件级人工检查确认只消费概览 composable 和两个选择事件；新增导航不改变概览请求契约。
+- 执行流：详情是新增只读 HTTP 流程；既有首页五个概览流程仅通过模块注册和共享 TDX Client 间接关联，需回归验证。
+
+## 跨模块同步修改
+
+| 范围 | 判断 | 同步动作 |
+| --- | --- | --- |
+| HTTP/OpenAPI | 需要 | 新增两个详情路由、DTO、生成 OpenAPI 并校验 |
+| Web API | 需要 | 新增详情 Axios 文件与类型适配 |
+| 消息契约 | 不需要 | 只读同步请求，不产生消息 |
+| 数据库/Redis | 不需要 | 不持久化、不缓存，且不触碰生产库 |
+| API 进程 | 需要 | 注册详情 Controller/Service，复用已校验 TDX Client |
+| Scheduler/Worker | 不需要 | 无异步任务或定时采集 |
+| 配置/部署 | 不需要 | 继续使用现有 TDX 配置和内网隧道，不新增环境变量 |
+| 测试 | 需要 | Mapper、Service、HTTP、Web 路由/状态、视觉和全量门禁 |
+| 文档 | 需要 | 功能档案、TDX 探测、开发总结、Review、QA、GitNexus 前后对比 |
+
+### 设计决策
+
+1. 不扩展首页接口大对象，详情接口独立，降低既有消费者的契约风险。
+2. 不修改 `createTdxClient`，只复用其超时、响应体上限和错误脱敏；分时能力未验证时明确返回不可用。
+3. 指数和板块共享页面外壳与 K 线点类型，但保留各自白名单和业务摘要映射。
@@ -0,0 +1,6 @@
+# FEAT-MO-004 实施记录
+
+详细实施计划见 [`docs/superpowers/plans/2026-08-24-index-sector-detail.md`](../../../superpowers/plans/2026-08-24-index-sector-detail.md)。
+
+执行顺序：开发前 Schema/GitNexus 门禁 → TDX 能力探测 → Mapper → Service/Controller → Web 路由和详情页 → 契约、测试、视觉验证、Review 和治理收尾。
+
@@ -0,0 +1,9 @@
+featureId: FEAT-MO-004
+slug: index-sector-detail
+name: 指数与板块详情分析页
+status: in_progress
+release: unreleased
+source: tdx
+scope: internal_lan_only
+createdAt: 2026-08-24
+
@@ -0,0 +1,29 @@
+# FEAT-MO-004 指数与板块详情分析页 PRD
+
+## 原始需求
+
+市场综合概览中的指数、板块可点击进入详细分析页，支持使用 TDX 真实数据进行复盘查看。
+
+## 用户与场景
+
+- 个人用户在概览页发现指数或强势板块后，进入详情确认交易日期、价格变化和 K 线走势。
+- 内网开发环境优先，TDX 通过当前 Mac 本机隧道访问；不把 TDX 暴露到公网。
+
+## V1 范围
+
+- 指数详情和一级行业板块详情。
+- 共享详情页外壳、数据状态、更新时间、来源、警告和 K 线图。
+- 分时视图由 TDX 能力探测结果决定，未通过时明确不可用。
+- 事实型数据和规则计算结果，不提供买卖建议、目标价、仓位建议或交易操作。
+
+## 非目标
+
+成分股排名、主力净流入、盘中新闻、AI 结论、用户体系、订阅付费和数据库/Redis/RocketMQ 持久化均不在本版本。
+
+## 验收标准
+
+1. 点击概览中的指数或板块可进入对应详情 URL，非法代码不触发 TDX 请求。
+2. API 返回 `instrument`、`quote`、`series`、`availableViews` 和统一元数据，K 线不超过 120 点。
+3. TDX 不可达、交易日延迟、字段缺失和空序列分别显示明确状态，不伪造图表。
+4. Web 显示上海时间，桌面和 390px 视口无横向溢出，图表容器尺寸稳定。
+
@@ -0,0 +1,23 @@
+# FEAT-MO-004 需求与约束
+
+## 功能需求
+
+- FR-001：提供指数详情 HTTP API。
+- FR-002：提供一级行业板块详情 HTTP API。
+- FR-003：详情 API 只接受登记代码、`period=1d` 和 `1..120` 的 `count`。
+- FR-004：详情响应包含 K 线序列、报价、交易日期、状态、来源和警告。
+- FR-005：概览指数和板块按钮导航到详情页，详情页可返回概览。
+- FR-006：分时仅在 TDX 探测通过后启用，未启用时返回 `intraday=false`。
+
+## 非功能需求
+
+- NFR-001：TDX 原始异常和地址不得暴露给 Web。
+- NFR-002：本机 TDX 可达时详情首屏 P95 目标小于 2 秒；不可达时 10 秒内返回不可用状态。
+- NFR-003：详情请求失败不影响首页五个概览模块。
+- NFR-004：API `asOf` 使用 UTC ISO，Web 使用 `Asia/Shanghai` 展示。
+- NFR-005：前端请求只能经过 Axios 封装，后端 DTO 作为 OpenAPI 契约来源。
+
+## 约束判断
+
+消息、数据库、Redis、Scheduler、Worker 和部署配置无需同步修改；详情为只读实时查询，不产生异步任务或持久化数据。OpenAPI、Web API、前端路由、测试和文档需要同步更新。
+
@@ -0,0 +1,6 @@
+# FEAT-MO-004 回退说明
+
+详情功能为无数据库结构变更的只读模块。若发布后出现问题，先回退前端详情路由和概览导航，再回退后端详情 Controller/Service 注册；首页已有五个概览接口不依赖详情模块。回退不执行生产数据库操作、不删除 TDX 配置、不修改用户数据。
+
+回退验证包括：`GET /api/v1/market-overview/indices`、`sectors` 仍返回 200；Web 根路径可加载；OpenAPI 与生成契约重新生成并通过边界测试。
+
@@ -0,0 +1,29 @@
+# FEAT-MO-004 TDX 能力探测报告
+
+- 探测日期：2026-08-24（开发环境）
+- 数据源：TDX 开发隧道（地址和请求体按安全规则不记录）
+- 探测方式：只读 JSON-RPC 请求，输出仅保留状态码、耗时、字段名和脱敏代码。
+
+## 已通过能力
+
+| 能力 | 方法 | 结果 | 观测 |
+| --- | --- | --- | --- |
+| 指数日 K 线 | `get_market_data` | 通过 | HTTP 200，业务 `ErrorId=0`，返回 `Value` 及分页元数据；两条核心指数请求耗时约 56ms |
+| 一级行业目录 | `get_stock_list` | 通过 | HTTP 200，业务 `ErrorId=0`，返回数组，首个脱敏记录代码为 `881001.SH` |
+| 一级行业日 K 线 | `get_market_data` | 通过 | 对目录首个代码请求 5 条日线，HTTP 200，业务 `ErrorId=0`，返回对应 `Value`；耗时约 47ms |
+
+## 未通过能力
+
+| 能力 | 候选方法 | 结果 | 处理 |
+| --- | --- | --- | --- |
+| 分时 | `get_minute_data` | 未通过 | 服务返回协议错误，未暴露原始错误内容；V1 返回 `availableViews.intraday=false` |
+| 分时 | `get_minute_data_ex` | 未通过 | 服务返回协议错误；不继续猜测参数或伪造分时序列 |
+| 历史分时 | `get_history_minute_data` | 未通过 | 服务返回协议错误；延期到独立能力验证 |
+
+## 安全和稳定性结论
+
+- 所有探测均为固定只读方法，未调用交易、账户、自选或写入接口。
+- 日 K 线字段沿用已验证的 `Date/Open/High/Low/Close/Amount/Volume`；详情服务仍会二次校验字段长度、日期和数量上限。
+- 真实响应只用于能力判断，不作为提交到仓库的原始样本；报告不包含地址、请求体、凭据或原始异常。
+- 本次观测不代表生产容量证明；详情页仍按单请求最多 120 点和现有 TDX 超时配置执行。
+