From 0bff3eeb6bda1418eaf2212e2d8c51b4db44793b Mon Sep 17 00:00:00 2001
From: clz <fadinglight9291117@126.com>
Date: Fri, 24 Jul 2026 15:40:27 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=B8=82=E5=9C=BA?=
 =?UTF-8?q?=E6=8E=92=E5=90=8D=E8=AE=BE=E8=AE=A1=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 doc/market-ranking-design.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 doc/market-ranking-design.md

diff --git a/doc/market-ranking-design.md b/doc/market-ranking-design.md
new file mode 100644
index 0000000..de66b68
--- /dev/null
+++ b/doc/market-ranking-design.md
@@ -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)。