docs: 添加市场排名设计说明

2026-07-24 15:40:27 +08:00
parent 2a8017860c
commit 0bff3eeb6b
1 changed files with 36 additions and 0 deletions
@@ -0,0 +1,36 @@
+# 市场排名卡片设计
+
+市场排名卡片采用视图、HTTP 数据和行情订阅分层设计：
+
+- `MarketRankingNodeComponent`：负责 UI、Tab 切换、页面可见性和订阅生命周期。
+- `MarketRankingDataFetcher`：根据当前排名类型获取 contracts，确定展示的合约及顺序。
+- `MarketRankingHqRequestClient`：使用 contracts 构建 4106 参数并订阅行情。
+- `MarketRankingTableData`：对齐真实行情返回结构，通过 `tableRows` 和
+  `row.get(fieldId)` 读取字段。
+- `HqFieldId`：统一维护行情字段 ID，避免业务代码硬编码。
+
+## 数据流
+
+```text
+切换 Tab
+→ HTTP 获取 contracts
+→ 生成合约占位列表
+→ 发起 4106 行情订阅
+→ TableData 转换为 CardData
+→ 更新 UI
+```
+
+HTTP 只负责返回 contracts；最新价、涨跌幅、成交额等动态字段由行情订阅补充。
+
+## 生命周期
+
+- 页面可见时获取数据并订阅行情。
+- 页面隐藏时停止行情订阅。
+- `refreshTrigger` 变化或 Tab 切换时重新获取 contracts，并在可见时重新订阅。
+- TCP 重连且页面可见时，停止旧订阅并重新订阅行情。
+- 组件消失时解绑 TCP 事件并释放行情订阅。
+
+当前 HTTP 和行情连接均为 Mock。接入真实环境时，主要替换 `MarketRankingDataFetcher`
+和 `MarketRankingHqRequestClient` 的内部实现，视图层数据结构和生命周期保持不变。
+
+具体 HTTP 与 4106 参数见 [市场排名接口文档](market-ranking-interfaces.md)。