# 市场排名接口文档

本文记录 `MarketRankingNodeComponent` 卡片使用的合约榜单 HTTP 接口及 4106 行情订阅协议。HTTP
实现位于 `MarketRankingDataFetcher.ets`，行情实现位于 `MarketRankingHqRequestClient.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 分钟涨跌速 |

鸿蒙原始推送为 `TableData` 行式结构。`tableRows` 中每个 Row 代表一份合约行情，通过
`row.get(字段 ID)` 读取对应值。`MarketRankingHqRequestClient` 将其转换为 `RankItem[]`，再通过
完整替换 `CardData` 刷新 UI。

## 当前 Mock 行为

- HTTP：使用 `@ohos.net.http` 构造 GET URL 和请求选项，但不调用 `request()`。
- 行情：构造并输出完整 4106 参数，不连接真实行情桥；Mock 使用 `tableRows + row.get(id)` 模拟回调。
- Mock 行情每 `2500ms` 推送一次，与 `pushtime=2.5` 保持一致。
- 每次请求及订阅参数均使用 `[MarketRanking]` 前缀输出到控制台。