# market-ranking 当前状态与待确认项

`src/main/ets/market-ranking/` 来自 `futures-homepage/CardHarmoyos` 参考工程，现已按首页主代码流程完成以下收口：

- 卡片配置并入 `rawfile/first_page_cards_config.json`，由 `FirstPageCardsConfigLoader` 统一读取。
- 推荐合约通过 `@kit.NetworkKit`、`buildHeader()` 和资源 URL 发起真实 HTTP 请求。
- 行情统一使用 `node/clients/MarketRankingHqRequestClient.ets`，接入 `TableRequestClient`、
  `RequestHelper`、`TableData` 和 `applyStandardPriceToTableData`。
- TCP 重连改用 `EmitterConstants.NETWORK_TCP_RECONNECT`，监听随首页可见性注册和注销。
- 页面隐藏、组件销毁、Tab 切换和下拉刷新都会释放旧行情订阅。
- 异步榜单请求和行情回调均有版本校验，避免旧 Tab 数据覆盖当前页面。
- HTTP 原始合约列表与 `@State cardData` 分开保存，重连不会因行情漏行丢失订阅标的。
- 行点击通过 `jumpToQuote()` 对齐 `futures-homepage` 的 `jumpToFenShi`。
- 已移除 Mock 行情客户端、Mock 榜单、自定义 TableData、自建事件总线和重复卡片配置模型。

## 后续优化设计：拆分 UI 与业务配置

当前 `MarketRankingConstant.ets` 的 `TAB_METRICS` / `PERIOD_RANGES` 同时包含 `$r()` 文案、HTTP
`quote_type` 和行情 `sortid`。因此 `MarketRankingDataFetcher` 与 `MarketRankingHqRequestClient`
间接依赖 UI 资源。

计划拆为两层：

1. `MarketRankingConfig.ets`：纯业务配置，不包含 `$r()` / `ResourceStr`。定义一级指标 ID、HTTP API
   参数、行情排序字段、排序方向、是否包含周期，以及二级周期的 API 参数和行情字段。
2. `MarketRankingUiConfig.ets`：只负责指标和周期 ID 到资源文案的映射，仅由
   `MarketRankingNodeComponent` 引用。

一级指标顺序必须只在 `MarketRankingConfig.ets` 维护一份。View 直接遍历该配置，并通过
`getMetricLabel(id)` / `getPeriodLabel(id)` 获取文案，避免 UI 数组和业务数组下标错位。

迁移时同步完成：

- 用枚举替代散落的 `'rise'`、`'fallSpeed'`、`'turnOver'` 等字符串判断。
- 将 `sortOrder` 写入指标配置，删除行情客户端对跌幅/跌速的硬编码判断。
- DataFetcher 仅使用 `api` / `hasPeriods`；行情客户端仅使用 `sortId` / `sortOrder`。
- 删除旧 `TabMetric.label`、`PeriodRange.label` 字段及相关 `ResourceStr` 依赖。

## 仍需在宿主工程确认

### 1. 行情字段

`market-ranking/TableConstants.ets` 按主代码命名维护 4106 字段。基础字段名称已经对齐，但成交额、日增仓、
1/5/10/15 分钟涨跌速、昨收和今开等字段无法在当前 HAR 的依赖源码中核验。需要在宿主实际使用的
`@b2c/lib_baseui` 和行情协议版本中确认字段 ID。

逐项验证涨幅、跌幅、1/5/10/15 分钟涨速和跌速、成交额、日增仓 Tab。预期每个 Tab 的 `sortid`、
排序方向、第三列字段和值均正确，不出现整列 `--` 或排序方向相反。

### 2. 基准价计算（高风险）

`MarketRankingHqRequestClient` 已接入 `applyStandardPriceToTableData`，但当前传入的 `fieldIds`
与仓库内 `FirstPageSelfStockRequestClient` 的基准价必需字段存在差异。市场排名当前未包含
`DATA_ID_ZD`、`DATA_ID_MARKET_OLD`，并且昨收、今开、昨结使用本地 `TableConstants` 字段，
没有使用 `StandardPriceTypeHelper.FIELD_ZUO_SHOU`、`FIELD_JIN_KAI`、`FIELD_ZUO_JIE`。

在无法查看宿主 `biz_quote` 和 `@b2c/lib_baseui` 实现的情况下，尚不能确认这些字段是否等价或可省略。
如果宿主实现依赖上述完整字段，用户切换基准价后可能出现涨跌幅未更新、计算口径错误或整列显示 `--`。
因此该项应按高风险处理，在字段要求得到确认并完成宿主验证前，不应认定市场排名的基准价功能可发布。

分别选择昨收、今开、昨结作为基准价，验证：

- 最新价不变，涨跌幅按当前基准价重新计算。
- 页面隐藏后修改基准价，再返回首页会重新订阅并更新。
- 首包和后续实时推送采用相同计算口径。
- 对照 `FirstPageSelfStockRequestClient` 确认必需字段集合，并优先复用宿主
  `TableConstants` / `StandardPriceTypeHelper`，避免维护重复字段 ID。

### 3. HTTP 推荐合约接口

在测试和生产环境验证 `recommend_futures`：

- UA、Cookie 和登录状态满足接口要求。
- 返回结构为 `{ code, data }`，`contract_code`、`contract_name`、`market` 类型正确。
- 各 `quote_type` 返回对应榜单，空数据、非 200、业务错误码和 JSON 异常进入空状态且不崩溃。
- 快速切换 Tab 时，旧请求不会覆盖当前 Tab。

### 4. 4106 行情请求

确认请求参数首行格式、`\r\n` 分隔、`dataitem`、`codelist`、`scenario` 和 `pushtime` 能被宿主行情服务识别。
验证首包、2.5 秒推送、排序和释放订阅均正常；页面隐藏后不再收到有效 UI 更新。

### 5. 生命周期与重连

验证以下操作不存在重复订阅、旧数据覆盖或资源泄漏：

- 首页前后台切换、Tab 页切换、组件销毁和重新创建。
- 下拉刷新过程中快速切换一级、二级 Tab。
- HTTP 请求未完成时隐藏或销毁页面。
- TCP 断开后重连；重连应使用完整的原始合约列表，而不是行情首包中的部分行。

### 6. 跳转与配置

- 行点击应与 `futures-homepage` 的 `jumpToFenShi` 一致，进入对应合约的分时页。
- 传入 `jumpToQuote()` 的代码、市场、名称列表顺序必须一致。
- 标题 `card_url` 在当前本地配置中为空；真实配置提供 Android URL 后再验证标题跳转和箭头显示。

### 7. UI 与性能

- 加载中、空数据和正常数据状态切换正确。
- 展开/收起只展示 3/5 行，行情更新后行内容及时刷新。
- 深浅色、说明弹层、长合约名和大数字格式正确。
- 连续行情推送下观察 `ForEach` 动态 Key 重建行的性能，确认无明显掉帧。

### 构建验证

本仓库缺少 `hvigorw`、`oh_modules` 和相邻 `biz_quote`，无法独立编译。最终需在宿主应用中验证 HTTP、
4106 首包/推送、TCP 重连、基准价切换、快速切换 Tab 和页面前后台切换。