fix(FEAT-MO-001): 修复TDX数据完整性与状态展示

2026-08-18 19:30:34 +08:00
parent ff8ada8316
commit 49f6be9c43
20 changed files with 557 additions and 113 deletions
@@ -27,6 +27,7 @@
 - 对未注册桥接方法返回结构化原因，避免前端显示“实时”或空白数据。
 - 修复 Vue TypeScript 单文件组件未被 ESLint 正确解析的问题，并为 E2E 测试进程补齐必需的本机 TDX 配置边界。
 - 隔离应用外壳单测中的真实 Axios 请求，消除 JSDOM 网络错误噪声，保持页面测试只验证外壳职责。
+- 根据代码 Review 修复畸形 TDX 字段被折算为零、缺市场成交额误报三市、交易日错位跨日求和、空行业目录误报 `fresh`、前端隐藏 `partial/delayed` 警告和零变化使用上涨色等缺陷，并补齐对应回归测试。

 ## 未完成与延期项

@@ -41,9 +42,10 @@

 ## 验证证据

- GitNexus 已完成最终重新索引；提交前 CLI `detect-changes --scope staged` 映射 11 条概览/E2E 执行流并标记 high。高风险来自本功能修改核心概览服务和测试启动入口，已由定向单测、HTTP/OpenAPI、构建和 E2E 覆盖；未发现额外业务模块调用方。MCP context 在当前 worktree 未初始化，因此以 CLI 索引和静态调用证据补充记录。
+- GitNexus 已完成提交前重新索引；CLI `detect-changes --scope staged` 映射 16 条概览执行流并标记 critical。风险来自本功能修改核心概览服务、TDX 映射和前端数据面板，已由定向单测、HTTP/OpenAPI、前端状态回归、构建、浏览器视觉验证和 E2E 覆盖；未发现额外业务模块调用方。当前环境未暴露 GitNexus MCP 变更检测工具，因此使用同版本 CLI 并指定 worktree 绝对路径执行。
 - API 冒烟：`/breadth`、`/sectors`、`/funds` 均返回 `source=tdx,status=fresh`；完整结果和耗时见 `tdx-smoke-report.md`。
 - 前端单测、typecheck、build、后端 TDX/映射/服务/HTTP/OpenAPI 测试通过。
 - `pnpm verify:e2e`：4/4 通过（桌面和移动端各覆盖页面与健康契约）。
 - 浏览器桌面与 390px 移动视口验证无横向溢出，视角与引擎切换可用。
+- Review 首轮在 `ff8ada8` 发现 6 项重要问题；已在当前修复提交中逐项处置，需二次代码 Review 确认。
 - 开发 Schema 按用户确认跳过，沿用 `v0.0.10 captured_empty` 追溯边界，不读取生产库。
@@ -10,10 +10,10 @@ npx gitnexus detect-changes --repo "$PWD" --scope staged
 ## 结果

 - 索引：已完成最终增量更新。
- 暂存文件：38 个文件、87 个符号（包含完整功能档案）。
- 影响执行流：11 条，CLI 风险：high。
- 主要执行流：`GetSummary`、`GetBreadth`、`GetSectors`、`GetFunds` 和 `RunTestApi`。
+- 暂存文件：20 个文件、67 个符号；GitNexus 自动改写的 `AGENTS.md` 已明确排除。
+- 影响执行流：16 条，CLI 风险：critical。
+- 主要执行流：`GetSummary`、`GetIndices`、`GetBreadth`、`GetSectors` 和 `GetFunds`，以及对应映射和状态创建流程。

 ## 处置

-high 来自本功能新增并修改市场概览核心服务、共享快照元数据函数和 E2E 启动入口，不是未知跨业务扩散。已用 TDX 客户端/映射/服务/HTTP/OpenAPI 单测、边界测试、构建和 4/4 E2E 覆盖；未发现用户、消息、数据库或 Scheduler/Worker 业务调用方。MCP context 在当前 worktree 未初始化，未将其缺失误判为低风险。
+critical 来自本功能修改市场概览核心服务、TDX 映射和三个前端数据面板，不是未知跨业务扩散。已用 TDX 映射/服务/HTTP/OpenAPI 单测、前端状态回归、边界测试、构建、浏览器视觉验证和 4/4 E2E 覆盖；未发现用户、消息、数据库、Redis、RocketMQ、Scheduler、Worker、认证或部署调用方。当前环境未暴露 GitNexus MCP 变更检测工具，已使用同版本 CLI 并指定 worktree 绝对路径执行，没有将工具限制误判为低风险。
@@ -50,7 +50,7 @@

 ## 数据与口径

-首个切片由 Nest API 直接读取 TDX 只读桥接层。指数和摘要使用真实 TDX K 线映射；当前桥接层未提供市场宽度、板块排行和资金趋势方法，因此这些模块返回结构化 `unavailable`，不得用指数或离线样本冒充。所有响应仍包含交易日期、快照时间、来源状态、完整性和单位。
+首个切片由 Nest API 直接读取 TDX 只读桥接层。指数和摘要使用真实 TDX K 线映射；市场宽度使用三市场指数快照，板块使用一级行业目录与日行情，量能使用三市场指数成交额汇总。主力净流入和盘中新闻不在本切片 TDX 主链路中，必须保持明确的补充源边界，不得用指数或离线样本冒充。所有响应仍包含交易日期、快照时间、来源状态、完整性和单位。

 A 股使用红涨绿跌。成交额统一展示为亿元，比例明确使用百分比。历史数据和低频资金数据必须显示实际数据日期，旧数据不得标记为实时。

@@ -7,10 +7,13 @@

 ## 结果

- 通过：`document.documentElement.scrollWidth` 未超过视口宽度。
+- 通过：2026-08-18 使用本地 API/Web 实际页面复验；桌面视口为 `1440×900`，移动视口为 `390×844`。
+- 通过：桌面 `clientWidth=1440, scrollWidth=1440`，移动端 `clientWidth=390, scrollWidth=390`；移动端六个主要区块左右边界均位于 `14px~376px`，未发生页面级或区块级横向溢出。
 - 通过：综合、短线、中长线切换和规则/AI/混合/对照选择有可见状态。
- 通过：TDX 来源、更新时间和不可用原因可见，未把不可用模块渲染为空白。
+- 通过：实际切换到“综合”和“混合”后，按钮激活态和下拉选中项同步更新。
+- 通过：TDX 来源、更新时间和不可用原因可见；当前 `127.0.0.1:17710` 未监听时，摘要、指数、宽度、板块和成交额趋势均显示结构化不可用状态，没有空白或伪造实时数据。
+- 通过：移动端浏览器控制台无 `warning` 或 `error`。

 ## 残余项

-依据抽屉、指数/板块详情页和真实图表尚未立项，不作为本次首屏视觉验收项。
+依据抽屉、指数/板块详情页和真实图表尚未立项，不作为本次首屏视觉验收项。真实 TDX 数据展示的接口冒烟证据沿用 `tdx-smoke-report.md`；本次隧道未监听，因此没有覆盖或伪造新的真实行情截图。
@@ -4,10 +4,11 @@

 - 新增 TDX 直连的市场概览首屏和五个模块 API。
 - 支持综合、短线、中长线视角与规则、AI、混合、对照偏好选择。
- 明确显示 TDX 来源、快照时间、缺失能力和模块级错误。
+- 市场宽度、一级行业强弱和成交额趋势接入真实 TDX 数据，并对空数据、部分数据、日期不一致和延迟状态显示明确边界。
+- 明确显示 TDX 来源、快照时间、交易日期、市场覆盖数和模块级错误。

 ## 明确不包含

 - 不启用 MySQL、Redis、RocketMQ 或 AI 运行链路。
 - 不包含用户体系、详情页、依据抽屉、交易操作和荐股能力。
- 不包含板块、宽度和资金真实数据，直到 TDX 桥接层提供并验证对应方法。
+- 不包含主力净流入、盘中新闻、真实图表和详情页；这些能力需另立补充数据源和功能需求。
@@ -1,5 +1,22 @@
 # 代码 Review

+## 首轮独立 Review
+
+- 对比基线：`8261948`
+- 审查提交：`ff8ada8`
+- 结论：`Ready to merge: No`
+
+首轮发现及处置：
+
+1. 畸形 `UpHome/DownHome` 被折算为零并误标 `fresh`：改为有限、非负且成对校验，无效市场整体排除并按有效市场数返回 `fresh/partial/unavailable`。
+2. 成交额缺市场或交易日错位仍误标三市实时数据：只汇总非负金额和一致交易日，公开 `marketCount`、`tradeDate`、`previousTradeDate`，缺市场返回 `partial`。
+3. 空板块目录误标 `fresh`：一级行业为空时直接返回 `unavailable`，且只保留存在相邻两日收盘价和有效涨跌幅的板块。
+4. 前端隐藏 `partial/delayed` 警告：宽度、板块和成交额面板均展示非 `fresh` 状态提示，并展示板块与成交额真实交易日期。
+5. PRD、发布说明和 Review 文档残留旧口径：已同步更正为真实 TDX 宽度、一级行业与成交额趋势口径，主力净流入和新闻仍明确延期。
+6. 异常分支测试不足：新增畸形宽度、部分市场、错位交易日、空行业目录、额外字段隔离、前端状态提示和零变化中性色回归测试。
+
+次要问题也已同步处理：OpenAPI `required + nullable` 定义、板块 DTO 额外 `price` 字段泄露、成交额零变化上涨色和新增映射中文口径注释。
+
 ## 范围

 覆盖 TDX 客户端、市场概览后端模块、OpenAPI/前端契约、Axios API 封装、Vue 首屏组件和对应测试。
@@ -27,4 +44,8 @@
 - 未进行 7×24、断线重连和生产压测；TDX 宽度/板块/资金方法及详情页仍待独立功能。
 - ESLint 对 Vue 单文件组件仅保留 35 条既有风格 warning，无 error；格式、类型和构建门禁均通过。

-最终结论：passed
+## 二次 Review
+
+等待修复提交完成后执行独立二次 Review。
+
+最终结论：pending
@@ -15,4 +15,10 @@
 - 开发总结记录原始需求、范围变化、实际完成、修复缺陷、延期项、提交和验证证据。
 - QA、发布说明和回退说明与本功能档案保持同一功能编号。

-最终结论：passed
+## 首轮问题同步检查
+
+- 数据完整性、状态语义、OpenAPI nullable、DTO 输出边界和前端降级提示均已补齐回归测试。
+- PRD、发布说明、测试计划和开发总结已同步实际口径，避免实现与文档分叉。
+- 浏览器复验覆盖桌面与 `390×844` 移动视口；当前 TDX 隧道未监听时只确认结构化降级，历史真实行情冒烟证据保持独立。
+
+最终结论：pending（等待独立二次代码 Review 与完整门禁）
@@ -13,6 +13,8 @@
 - 前端 Vitest、typecheck、build：通过。
 - 后端 TDX 客户端、映射、服务、HTTP/OpenAPI 测试：通过。
 - `curl` 冒烟：`/breadth`、`/sectors`、`/funds` 均返回 `source=tdx,status=fresh`；分别验证 `UpHome/DownHome` 汇总、一级行业排序和成交额单位转换。
+- 异常映射：覆盖畸形涨跌家数字段、空一级行业目录、单根板块 K 线、成交额缺市场/交易日错位/负数，以及三市完整性状态。
+- 前端状态：覆盖宽度、板块和成交额模块的 `partial`/`delayed` 警告、真实交易日期和成交额零变化中性色。
 - 浏览器验证：桌面默认视口和 390px 移动视口无横向溢出；综合/短线切换和分析引擎选择可用。

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