docs: 更新市场排名验证与代码审查记录

doc/market-ranking-ai-pick-code-review.md

@@ -0,0 +1,60 @@
+# 市场排名与 AI 选期代码审查问题记录
+
+审查基线：`499b084`。记录日期：2026-07-28。
+
+本文件记录静态代码审查发现的问题。当前 HAR 无法独立构建，修复后仍需在宿主工程完成编译和业务回归。
+
+## 1. 市场排名空响应仍展示旧缓存
+
+**状态：待修复；优先级：高**
+
+`MarketRankingNodeComponent.updateCardData()` 命中 Tab 缓存后，仅在没有缓存时才用 HTTP 返回结果替换 `cardData`。当接口成功返回空数组时，旧榜单仍会显示，且空合约列表不会建立新的行情订阅，页面可能长期停留在旧数据。
+
+- 证据：`src/main/ets/market-ranking/MarketRankingNodeComponent.ets:183-213`
+- 建议：将成功的 HTTP 响应视为权威结果；空数组应清空页面和对应缓存。非空响应可按新合约列表保留匹配的旧行情值。
+- 验证：先加载非空榜单，再让刷新接口返回空数组，页面应进入空状态且不再接收旧订阅回调。
+
+## 2. HTTP 合约字段缺少运行时校验
+
+**状态：待修复；优先级：高**
+
+两个 Fetcher 都通过类型断言直接使用 JSON，未校验合约代码、市场和名称。市场排名点击处仅排除 `undefined`，无法拦截 `null` 或空字符串；AI 选期点击和行情订阅均未做防御。
+
+- 证据：
+  - `src/main/ets/market-ranking/MarketRankingDataFetcher.ets:47-51`
+  - `src/main/ets/market-ranking/MarketRankingNodeComponent.ets:634-638`
+  - `src/main/ets/ai-pick/AiPickDataFetcher.ets:102-108`
+  - `src/main/ets/ai-pick/AiPickNodeComponent.ets:709-711`
+- 建议：在 Fetcher 边界过滤或拒绝非法数据；点击跳转前再次校验代码和市场均为非空字符串。
+- 验证：覆盖字段缺失、`null`、空字符串和错误数组结构，确保不崩溃、不发送非法 4106 请求。
+
+## 3. 最新价精度被转换或固定
+
+**状态：待修复；优先级：中**
+
+行情客户端将价格字符串转换为 `number`。AI 选期随后固定保留两位小数，可能把三位或更多精度的合约价格舍入；市场排名也会丢失尾随精度。
+
+- 证据：
+  - `src/main/ets/node/clients/AiPickHqRequestClient.ets:122-130`
+  - `src/main/ets/ai-pick/AiPickUtils.ets:161-163`
+  - `src/main/ets/node/clients/MarketRankingHqRequestClient.ets:120-130`
+- 建议：保留行情层格式化后的价格字符串，或使用宿主统一的合约精度格式化能力。
+- 验证：选择整数、一位、两位和三位小数精度的合约，与宿主行情页逐项对比。
+
+## 4. 多语言资源未覆盖
+
+**状态：待修复；优先级：中**
+
+市场排名和 AI 选期文案只存在于 base 中文资源中，`zh_CN`、`en_US` 未定义对应条目；本地卡片配置中的中文标题和说明还会优先于资源文案。
+
+- 证据：
+  - `src/main/resources/base/element/string.json:204-309`
+  - `src/main/resources/zh_CN/element/string.json`
+  - `src/main/resources/en_US/element/string.json`
+  - `src/main/resources/rawfile/first_page_cards_config.json:96-140`
+- 建议：按仓库约定补齐三套字符串资源，并明确静态卡片配置的本地化策略；大数单位等展示文本也应纳入资源管理。
+- 验证：切换中文和英文系统语言，检查标题、Tab、空状态、说明弹层、主力标签和数值单位。
+
+## 测试缺口
+
+当前测试仅包含模板示例。后续至少应覆盖缓存后空响应、非法合约字段、异步旧回调失效、价格精度，以及市场排名指标与周期参数映射。

doc/market-ranking-known-issues.md

@@ -59,35 +59,44 @@
 “旧请求失效 → 释放订阅 → HTTP 返回 → 版本校验 → HQ 订阅 → 回调校验”时序；应先完成宿主生命周期和
 重连验证，再评估是否继续抽取控制器。
 
-## 仍需在宿主工程确认
+## 宿主工程验证状态
 
-### 1. 行情字段
+- 已验证通过：1. 行情字段、2. 基准价计算、3. HTTP 推荐合约接口、4. 4106 行情请求。
+- 仍需确认：5. 生命周期与重连、6. 跳转与配置、7. UI 与性能。
 
-`market-ranking/TableConstants.ets` 按主代码命名维护 4106 字段。基础字段名称已经对齐，但成交额、日增仓、
+### 1. 行情字段（已验证通过）
-1/5/10/15 分钟涨跌速、昨收和今开等字段无法在当前 HAR 的依赖源码中核验。需要在宿主实际使用的
+
+验证日期：2026-07-28。
+
+`market-ranking/TableConstants.ets` 按主代码命名维护 4106 字段。虽然成交额、日增仓、
+1/5/10/15 分钟涨跌速、昨收和今开等字段无法在当前 HAR 的依赖源码中核验，但已在宿主实际使用的
 `@b2c/lib_baseui` 和行情协议版本中确认字段 ID。
 
-逐项验证涨幅、跌幅、1/5/10/15 分钟涨速和跌速、成交额、日增仓 Tab。预期每个 Tab 的 `sortid`、
+已逐项验证涨幅、跌幅、1/5/10/15 分钟涨速和跌速、成交额、日增仓 Tab。每个 Tab 的 `sortid`、
-排序方向、第三列字段和值均正确，不出现整列 `--` 或排序方向相反。
+排序方向、第三列字段和值均正确，未出现整列 `--` 或排序方向相反。
 
-### 2. 基准价计算（代码已补齐，待宿主验证）
+### 2. 基准价计算（已验证通过）
+
+验证日期：2026-07-28。
 
 `MarketRankingHqRequestClient` 已按 `FirstPageSelfStockRequestClient` 补齐
 `applyStandardPriceToTableData` 所需字段，包括 `DATA_ID_ZD`、`DATA_ID_MARKET_OLD` 以及
 `StandardPriceTypeHelper` 提供的昨收、今开、昨结字段。4106 请求同时携带 `update=1` 和当前
 `computemode`，使服务端排序口径与客户端展示口径保持一致。
 
-当前 HAR 无法查看宿主 `biz_quote`、`@b2c/lib_baseui` 和 4106 服务实现，因此仍需确认排序场景
+当前 HAR 无法查看宿主 `biz_quote`、`@b2c/lib_baseui` 和 4106 服务实现；现已在宿主确认排序场景
-`qht_qihuo_sort` 支持 `computemode`，并在宿主完成以下验证：
+`qht_qihuo_sort` 支持 `computemode`，并完成以下验证：
 
-分别选择昨收、今开、昨结作为基准价，验证：
+分别选择昨收、今开、昨结作为基准价，验证结果如下：
 
 - 最新价不变，涨跌幅按当前基准价重新计算。
 - 页面隐藏后修改基准价，再返回首页会重新订阅并更新。
 - 首包和后续实时推送采用相同计算口径。
 - 涨幅、跌幅列表顺序与当前基准价下展示的涨跌幅一致。
 
-### 3. HTTP 推荐合约接口
+### 3. HTTP 推荐合约接口（已验证通过）
+
+验证日期：2026-07-28。
 
 在测试和生产环境验证 `recommend_futures`：
 
@@ -96,7 +105,9 @@
 - 各 `quote_type` 返回对应榜单，空数据、非 200、业务错误码和 JSON 异常进入空状态且不崩溃。
 - 快速切换 Tab 时，旧请求不会覆盖当前 Tab。
 
-### 4. 4106 行情请求
+### 4. 4106 行情请求（已验证通过）
+
+验证日期：2026-07-28。
 
 确认请求参数首行格式、`\r\n` 分隔、`dataitem`、`codelist`、`scenario` 和 `pushtime` 能被宿主行情服务识别。
 验证首包、2.5 秒推送、排序和释放订阅均正常；页面隐藏后不再收到有效 UI 更新。