feat(market-ranking): 完善数据请求与行情订阅

2026-07-23 11:01:31 +08:00
parent 7c807fcd30
commit 0b90b3fa21
9 changed files with 725 additions and 121 deletions
@@ -0,0 +1,104 @@
+# 市场排名接口文档
+
+本文记录 `MarketRanking` 卡片使用的合约榜单 HTTP 接口及 4106 行情订阅协议。当前实现位于
+`entry/src/main/ets/market-ranking/MarketRankingDataFetcher.ets`。
+
+## 合约榜单 HTTP 接口
+
+### 请求
+
+```text
+GET {API_HOST}futgwapi/api/market/homepage/v1/recommend_futures
+```
+
+| 构建模式 | API_HOST |
+| --- | --- |
+| Debug | `https://futures-test.10jqka.com.cn/` |
+| Release | `https://ftapi.10jqka.com.cn/` |
+
+查询参数：
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `quote_type` | string | 当前排行榜维度 |
+| `number` | number | 返回数量，固定为 `50` |
+
+`quote_type` 示例：
+
+- 涨幅：`rise_percent`
+- 跌幅：`fall_percent`
+- 成交额：`turnover`
+- 日增仓：`increase_position`
+- 5 分钟涨速：`five_minute_rise_percent`
+- 10 分钟跌速：`ten_minute_fall_percent`
+
+### 响应
+
+```json
+{
+  "code": 0,
+  "data": [
+    {
+      "contract_code": "CU2501",
+      "contract_name": "沪铜2501",
+      "market": "70"
+    }
+  ]
+}
+```
+
+该接口只确定榜单合约及顺序；价格、涨跌幅等数据由行情订阅补充。
+
+## 4106 行情订阅
+
+行情通过客户端统一行情协议订阅，不是普通 HTTP 请求。
+
+```json
+{
+  "protocolId": "4106",
+  "pageId": "2201",
+  "onlineId": "marketRankingData",
+  "columnOrder": "55|10|4|36103|34818|6|7|66",
+  "requestDic": "sortid=34818\r\nsortorder=0\r\npush=1\r\ndataitem=55,10,4,36103,34818,6,7,66,\r\ncodelist=70(CU2501,RB2505,);\r\nscenario=qht_qihuo_sort\r\nprecision=1\r\npushtime=2.5\r\n"
+}
+```
+
+关键参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `sortid` | 当前 Tab 对应的行情字段 ID |
+| `sortorder` | 跌幅、跌速为 `1`，其余为 `0` |
+| `push` | `1` 表示持续推送 |
+| `dataitem` | 本次需要返回的字段 ID |
+| `codelist` | 按市场分组的合约列表 |
+| `pushtime` | 推送间隔，`2.5` 秒 |
+
+### 行情字段
+
+| 字段 | ID | 使用场景 |
+| --- | ---: | --- |
+| `name` | 55 | 始终 |
+| `price` | 10 | 始终 |
+| `code` | 4 | 始终 |
+| `market` | 36103 | 始终 |
+| `price_chg` | 34818 | 始终 |
+| `pre_price` | 6 | 始终 |
+| `open_price` | 7 | 始终 |
+| `pre_settle_price` | 66 | 始终 |
+| `turnover` | 19 | 成交额 |
+| `incre_posit` | 34355 | 日增仓 |
+| `chg_speed_1min` | 34874 | 1 分钟涨跌速 |
+| `chg_speed_5min` | 34325 | 5 分钟涨跌速 |
+| `chg_speed_10min` | 34875 | 10 分钟涨跌速 |
+| `chg_speed_15min` | 34876 | 15 分钟涨跌速 |
+
+原始推送为“字段 ID → 数组”的分列结构，相同数组下标表示同一合约。Fetcher 将其合并为
+`RankItem[]`，再通过完整替换 `CardData` 刷新 UI。
+
+## 当前 Mock 行为
+
+- HTTP：使用 `@ohos.net.http` 构造 GET URL 和请求选项，但不调用 `request()`。
+- 行情：构造并输出完整 4106 参数，不连接真实行情桥。
+- Mock 行情每 `2500ms` 推送一次，与 `pushtime=2.5` 保持一致。
+- 每次请求及订阅参数均使用 `[MarketRanking]` 前缀输出到控制台。