feat(FEAT-MO-001): 接入TDX市场宽度板块与成交额趋势

2026-08-18 17:37:36 +08:00
parent 82619489a9
commit ff8ada8316
21 changed files with 616 additions and 69 deletions
@@ -5,8 +5,11 @@
 ## 数据可用性

 - `summary` 和 `indices`：使用 TDX K 线真实响应，展示来源、快照时间和指数涨跌。
- `breadth`、`sectors`、`funds`：桥接层暂未注册对应方法，使用 `unavailable` 响应和明确原因。
- 页面不把不可用指标降级为模拟值；后续补齐桥接方法时只替换后端映射，不改变前端契约。
+- `breadth`：使用 TDX 指数快照的 `UpHome`、`DownHome` 汇总上证、深证和北证市场宽度；未返回的 `unchanged` 明确为 `null`，不得用总数推算。
+- `sectors`：使用 TDX 系统分类中的一级行业（`get_stock_list(market=16)`）和批量日行情，按涨跌幅排序后展示重点强弱板块。
+- `funds`：模块名称和口径为“成交额趋势”，使用核心交易所指数日行情的 `Amount` 汇总当前与前一交易日成交额；这不是主力净流入。
+- 主力净流入和盘中新闻不在本次 TDX 首屏主链路中，后续通过独立补充数据源适配器接入，并在响应中标记来源与数据质量。
+- 页面不把缺失或权限不足的指标降级为模拟值；单个来源失败只影响对应模块。

 ## 运行边界

@@ -8,7 +8,7 @@

 - 数据源从早期“确定性模拟快照”调整为 TDX 只读直连，Nest API 访问本机 `127.0.0.1:17710`，Vue 不直接访问 TDX。
 - API 按摘要、指数、市场宽度、板块和资金拆分，避免把整个首屏塞入单个接口。
- 当前 TDX 桥接层仅确认 `get_market_data` 可用；宽度、板块和资金方法未注册，因此对应模块明确返回 `unavailable`。
+- 当前 TDX 桥接已确认 `get_market_snapshot`、`get_stock_list` 和批量 `get_market_data` 可用；市场宽度、一级行业板块和成交额趋势改为真实 TDX 映射。主力净流入字段虽存在但当前实测为零值，盘中新闻无官方行情接口，因此两者延期到补充源功能。
 - MySQL、Redis、RocketMQ 和 AI 仍不进入本切片运行链路；它们保留为后续基础设施边界。

 ## 实际完成需求
@@ -18,6 +18,7 @@
 - 完成结论、驱动与风险、核心指数、市场宽度、板块、资金趋势模块，以及加载/错误/不可用状态。
 - 完成分析视角和分析引擎切换，本地保存用户偏好。
 - 真实 TDX 指数和摘要已通过本机隧道冒烟；未用指数或离线样本伪造缺失指标。
+- 真实 TDX 市场宽度、一级行业和成交额趋势已通过本机桥接冒烟；资金模块明确使用成交额口径，不宣称主力净流入。

 ## 修复缺陷

@@ -29,7 +30,7 @@

 ## 未完成与延期项

- TDX 桥接层补齐市场宽度、板块排行、资金趋势方法后再实现真实图表和口径。
+- 主力净流入的权限/数据质量验证、盘中新闻补充源、真实图表和口径仍延期。
 - “查看依据”抽屉、指数/板块详情页、AI 请求和用户体系另立功能。
 - 本地验证不代表生产 7×24 采集稳定性、商业授权或公网部署安全性。

@@ -41,7 +42,7 @@
 ## 验证证据

 - GitNexus 已完成最终重新索引；提交前 CLI `detect-changes --scope staged` 映射 11 条概览/E2E 执行流并标记 high。高风险来自本功能修改核心概览服务和测试启动入口，已由定向单测、HTTP/OpenAPI、构建和 E2E 覆盖；未发现额外业务模块调用方。MCP context 在当前 worktree 未初始化，因此以 CLI 索引和静态调用证据补充记录。
- API 冒烟：`/summary`、`/indices` 返回 `source=tdx,status=fresh`。
+- API 冒烟：`/breadth`、`/sectors`、`/funds` 均返回 `source=tdx,status=fresh`；完整结果和耗时见 `tdx-smoke-report.md`。
 - 前端单测、typecheck、build、后端 TDX/映射/服务/HTTP/OpenAPI 测试通过。
 - `pnpm verify:e2e`：4/4 通过（桌面和移动端各覆盖页面与健康契约）。
 - 浏览器桌面与 390px 移动视口验证无横向溢出，视角与引擎切换可用。
@@ -6,4 +6,6 @@
 4. ~~实现指数、宽度、板块和资金模块；不可用指标使用结构化状态。~~ 已完成。
 5. ~~实现分析偏好菜单和本地持久化。~~ 已完成；依据抽屉和详情页入口延期至独立功能。
 6. ~~完成单元测试、类型检查、构建、接口冒烟、浏览器桌面/移动端视觉验证。~~ 已完成。
-7. 补齐 TDX 桥接层的宽度、板块和资金方法后，再单独更新对应数据口径和图表需求。
+7. ~~补齐 TDX 市场宽度、一级行业板块和成交额趋势映射。~~ 已确认官方接口和本机桥接可用；主力净流入与盘中新闻保留为补充源需求。
+8. 更新 DTO、OpenAPI 类型和前端组件，使真实数据状态、单位和 `unchanged=null` 口径可见。
+9. 完成 TDX 真实响应夹具、错误隔离、类型、构建和浏览器视觉验证；Review 后再收口功能档案。
@@ -93,3 +93,4 @@ A 股使用红涨绿跌。成交额统一展示为亿元，比例明确使用百

 - 0.1：建立首版 PRD，补充结论优先、分析偏好和异常状态。
 - 0.2：根据 TDX 实连验证修正数据源、可用性边界和未接入基础设施范围。
+- 0.3：核对官方行情接口后确认市场宽度、一级行业板块和成交额趋势可由 TDX 直接提供；主力净流入与盘中新闻保留补充源边界。
@@ -2,11 +2,12 @@

 首屏为“市场概览”模块中的综合概览，采用结论优先。市场概览内部通过轻量分析状态入口切换综合、短线和中长线视角，并支持规则、AI、混合与对照分析。

-当前切片开发 Vue 3 可交互首屏，Nest API 通过 TDX 只读桥接层提供真实指数和摘要；市场宽度、板块和资金接口保留结构化不可用状态，不使用离线样本。不接用户体系，也不启用 MySQL、Redis、RocketMQ 或 AI 运行链路。
+当前切片开发 Vue 3 可交互首屏，Nest API 通过 TDX 只读桥接层提供真实指数、市场宽度、板块和成交额趋势；主力净流入与盘中新闻不作为本次 TDX 主链路指标，不使用离线样本。不接用户体系，也不启用 MySQL、Redis、RocketMQ 或 AI 运行链路。

 ## 本次实际范围

 - 已完成综合、短线、中长线视角切换，以及规则、AI、混合、对照偏好选择；偏好只保存于浏览器本地。
 - 已完成按摘要、指数、宽度、板块、资金拆分的五个 HTTP 接口和前端 API 封装。
 - 已完成 TDX 请求超时、响应大小限制、错误脱敏和模块级失败隔离。
+- 已确认并接入 TDX 市场宽度、一级行业板块和成交额趋势；资金模块明确不等同于主力净流入，`unchanged` 无可靠总数时返回 `null`。
 - 详情页和“查看依据”抽屉只保留入口，另立需求实现，不在本次发布范围内。
@@ -1,22 +1,24 @@
 # FEAT-MO-001 TDX 只读冒烟报告

- 验证时间：2026-08-18 13:04 CST
- 网络场景：外出 Tailscale + SSH 隧道
+- 验证时间：2026-08-18 17:21 CST
+- 网络场景：本机回环桥接（TDX 服务可达）
 - 本机业务入口：`127.0.0.1:17710`
- 请求方式：HTTP POST JSON
- 请求类型：单只公开行情 K 线只读请求
+- API 入口：`127.0.0.1:3000/api/v1/market-overview`
+- 请求方式：HTTP GET（业务 API）及桥接层 HTTP POST JSON
+- 请求类型：市场宽度、一级行业板块、成交额趋势只读请求
 - 原始载荷：未保存

 ## 结果

- HTTP 请求成功。
- TDX 业务 `ErrorId` 为 `0`。
- 返回字段完整性满足当前协议基线。
- 响应包含：股票代码键、K 线日期、开盘价、最高价、最低价、收盘价、成交额、成交量、复权因子和分页元数据。
- 未调用交易、账户、自选、写入或批量接口。
+- 三条业务接口均返回 HTTP `200`，响应状态均为 `fresh`，`source` 均为 `tdx`。
+- `/breadth`：成功汇总上证、深证和北证指数快照中的 `UpHome`、`DownHome`；`unchanged` 返回 `null`，未进行总数推算。
+- `/sectors`：成功读取一级行业目录并批量获取日行情，按涨跌幅排序返回前 8 项。
+- `/funds`：成功汇总三个交易所指数日行情 `Amount`，按万元转换为亿元并计算较前一交易日变化；该指标展示为“成交额趋势”，不宣称主力净流入。
+- 端到端耗时：市场宽度约 `0.11s`，一级行业约 `0.27s`，成交额趋势约 `0.12s`（单次本机冒烟，不代表生产 SLA）。
+- 未调用交易、账户、自选、写入接口；未保存真实行情原始载荷。

 ## 脱敏与限制

 - 报告不保存真实价格、成交量、家庭网络地址、Tailscale 地址、SSH 用户、密钥或完整响应。
- 本报告只证明当前开发机到 TDX 的只读协议可达，不证明 7×24 生产采集、商业再分发授权或所有板块/资金方法已经可用。
- 后续接口实现必须继续以小批量只读请求验证板块、宽度和资金字段，并在映射测试中固定字段口径。
+- 本报告只证明当前开发机到 TDX 的只读接口和本次映射可达，不证明 7×24 生产采集、商业再分发授权、主力净流入口径或盘中新闻接口已经可用。
+- 主力净流入和盘中新闻继续保留为补充数据源需求；后续接入必须单独记录来源、权限、口径和数据质量。
@@ -4,7 +4,7 @@
 - 分析状态可以临时切换并保存默认值。
 - 依据抽屉能够打开和关闭。
 - 五个模块并行请求，一个模块失败不阻断其他模块。
- 真实 TDX 指数和摘要响应可映射，未提供的方法返回 `unavailable`，不伪造行情。
+- 真实 TDX 指数、市场宽度、一级行业板块和成交额趋势响应可映射；主力净流入与盘中新闻不以占位值伪造。
 - 加载、部分数据、过期和错误状态具有明确文案。
 - 桌面和窄窗口不出现阻断核心内容的溢出。

@@ -12,14 +12,14 @@

 - 前端 Vitest、typecheck、build：通过。
 - 后端 TDX 客户端、映射、服务、HTTP/OpenAPI 测试：通过。
- `curl` 冒烟：`/summary`、`/indices` 返回 `source=tdx,status=fresh`；`/breadth`、`/sectors`、`/funds` 返回结构化不可用状态。
+- `curl` 冒烟：`/breadth`、`/sectors`、`/funds` 均返回 `source=tdx,status=fresh`；分别验证 `UpHome/DownHome` 汇总、一级行业排序和成交额单位转换。
 - 浏览器验证：桌面默认视口和 390px 移动视口无横向溢出；综合/短线切换和分析引擎选择可用。

 ## 安全、性能与残余风险

 - 安全：TDX 地址固定为本机回环桥接端口；请求超时、响应 1 MiB 上限、错误脱敏；只读行情，不接受用户输入拼接请求。
 - 性能：五个模块并行请求，单次 TDX 请求受超时保护；本切片不引入数据库、缓存或消息负载，未进行持续压测。
- 残余风险：桥接层尚未提供宽度、板块和资金方法；详情页、依据抽屉和 AI 运行时需另立功能；市场数据授权和生产 7×24 稳定性未由本地冒烟证明。
+- 残余风险：主力净流入字段当前桥接实测为零值，需权限和口径专项验证；盘中新闻仍需补充源；详情页、依据抽屉和 AI 运行时需另立功能；市场数据授权和生产 7×24 稳定性未由本地冒烟证明。

 ## 安全验证