# 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` 依赖。

## 后续优化设计：拆分 MarketRankingNodeComponent

`MarketRankingNodeComponent.ets` 当前同时负责页面状态、生命周期、HTTP 请求编排、HQ 订阅、TCP 重连、
跳转参数、展示计算和 UI 构建。后续按以下职责拆分：

- `MarketRankingNodeComponent.ets`：继续作为唯一状态拥有者，保留 `@State`、生命周期、请求/订阅版本保护、
  Tab 选择、跳转和子组件回调编排。
- `MarketRankingDisplayHelper.ets`：承载第三列标题、值、颜色、展示行数和空状态高度等纯展示计算。
- `components/MarketRankingTitleBar.ets`：标题、说明入口和展开/收起交互。
- `components/MarketRankingTabBar.ets`：一级/二级 Tab，以及滚动宽度、偏移量和右侧渐变等局部 UI 状态。
- `components/MarketRankingTable.ets`：表头、加载/空状态、行情行和行点击回调。
- `components/MarketRankingExplainSheet.ets`：说明弹层内容；`bindSheet` 显隐状态仍由主组件控制。

分阶段实施，避免重构时破坏行情时序：

1. 先拆业务/UI 配置和纯展示计算，不改变请求及订阅流程。
2. 再拆 `TabBar` 和 `Table`，主组件通过明确参数和回调传递状态。
3. 最后清理无效 `isDarkMode` 状态、未使用回调参数、重复布局常量及命名不一致。

暂不把 HTTP、HQ、请求版本、页面可见性和 TCP 重连拆入多个 ViewModel/Controller。这些逻辑存在严格的
“旧请求失效 → 释放订阅 → HTTP 返回 → 版本校验 → HQ 订阅 → 回调校验”时序；应先完成宿主生命周期和
重连验证，再评估是否继续抽取控制器。

## 仍需在宿主工程确认

### 1. 行情字段

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

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

### 2. 基准价计算（代码已补齐，待宿主验证）

`MarketRankingHqRequestClient` 已按 `FirstPageSelfStockRequestClient` 补齐
`applyStandardPriceToTableData` 所需字段，包括 `DATA_ID_ZD`、`DATA_ID_MARKET_OLD` 以及
`StandardPriceTypeHelper` 提供的昨收、今开、昨结字段。4106 请求同时携带 `update=1` 和当前
`computemode`，使服务端排序口径与客户端展示口径保持一致。

当前 HAR 无法查看宿主 `biz_quote`、`@b2c/lib_baseui` 和 4106 服务实现，因此仍需确认排序场景
`qht_qihuo_sort` 支持 `computemode`，并在宿主完成以下验证：

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

- 最新价不变，涨跌幅按当前基准价重新计算。
- 页面隐藏后修改基准价，再返回首页会重新订阅并更新。
- 首包和后续实时推送采用相同计算口径。
- 涨幅、跌幅列表顺序与当前基准价下展示的涨跌幅一致。

### 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 和页面前后台切换。