index-list-paginated

# 指数分页列表 - 分页、排序、筛选 ## 1. 接口描述 | 项目 | 说明 | |------|------| | 接口名称 | 指数列表（分页、排序、筛选） | | 外部接口 | `GET /api/v1/market/data/daec/indices` | | 请求方式 | GET | | 适用场景 | 分页获取 A 股指数列表，支持按字段排序、按条件筛选、按需返回字段（masks）；不传分页参数时返回全部（先筛选、排序后再截断） | ## 2. 请求参数 说明：所有参数均为可选项。不传 `order_by` 且不传 `ob` 时默认按 `change_rate desc` 排序；不传分页时返回满足条件的全部指数。 | 参数名 | 类型 | 是否必填 | 描述 | 取值示例 | 备注 | |--------|------|----------|------|----------|------| | order_by | string | 否 | 排序方式，格式为「字段 方向」，多字段用逗号分隔 | change_rate desc、name asc | 方向：asc/a 升序，desc/d 降序；字段为 Index 字段名（如 change_rate、name、latest） | | ob | string | 否 | 与 order_by 同义 | 同 order_by | 与 order_by 二选一，同时传以 order_by 为准 | | filter | string | 否 | 过滤条件表达式 | change_rate != null | 对 Index 字段做条件过滤；可为 _B64: 开头 Base64 编码；语法见下方 filter 取值说明 | | masks | string | 否 | 字段掩码，逗号分隔的字段名，仅返回这些字段 | name,symkey,latest,change_rate | 不传则返回全部字段；字段名须匹配正则 `^[a-zA-Z_][a-zA-Z0-9_]*$`，非法字段名会报错 | | page_size | int | 否 | 每页条数 | 20 | 不传则不分页 | | page_no | int | 否 | 页码，从 1 开始 | 1 | 不传且传了 page_size 时默认为 1 | **filter 取值说明**（表达式语法，对应代码 crates/dom/src/core/filter.rs）： - **基本形式**：`字段 操作符 值`。字段为 Index 的字段名（与 order_by、masks 一致，如 change_rate、name、latest、symkey）。 - **比较操作符**：`=`、`!=`、`>`、`>=`、`<`、`<=`。 - **其它操作符**：`~` 子串包含（左为字段、右为字符串）；`:` 包含（具体以实现为准）。 - **逻辑组合**：`AND`、`OR`、`NOT`，可用括号 `()` 分组。例：`(change_rate >= 0 AND change_rate <= 0.05) OR name ~ "上证"`。 - **值**：`null`、`true`、`false`、数字、双引号字符串（内部双引号用 `\"` 转义）。 - **Base64**：整段表达式做 Base64 编码后以 `_B64:` 开头传入。 示例：`change_rate != null`、`latest > 3000`、`name ~ "上证"`。 ## 3. 响应说明 返回分页后的指数列表及总数，与代码 `ListIndicesReply` 一致。列表中每项为单只指数对象（结构同单只指数详情）；不传 `masks` 时每只指数返回全部字段，传 `masks` 时仅返回指定字段。 ```json { "total_size": 500, "indices": [ { "name": "上证指数", "symkey": "000001.XSHG", "latest": 3252.30, "change_rate": 0.0020 }, { "name": "深证成指", "symkey": "399001.XSHE", "latest": 10580.50, "change_rate": -0.0015 } ] } ``` ### 根字段 | 字段名 | 类型 | 是否可为空 | 说明 | |--------|------|------------|------| | total_size | int | 否 | 满足筛选条件的指数总数（分页前） | | indices | array | 否 | 当前页的指数列表；单条结构见下表 | ### 单条结构（indices 元素，对应 Index） 以下为部分常用字段；完整字段见代码 Index，点位类保留 4 位小数。 | 字段名 | 类型 | 是否可为空 | 说明 | 单位 | |--------|------|------------|------|------| | name | string | 是 | 指数名称 | — | | symkey | string | 是 | 标的键 | — | | symbol_id | string | 是 | 标的 ID | — | | ex_id | string | 是 | 市场 ID | — | | latest | float | 是 | 最新点位 | 点 | | close | float | 是 | 收盘点位 | 点 | | open | float | 是 | 开盘点位 | 点 | | high | float | 是 | 最高点位 | 点 | | low | float | 是 | 最低点位 | 点 | | prev_close | float | 是 | 昨收点位 | 点 | | change | float | 是 | 涨跌点位 | 点 | | change_rate | float | 是 | 涨跌幅 | % | | volume | long | 是 | 成交量 | — | | turnover | float | 是 | 成交额 | 元 | | amplitude | float | 是 | 振幅 | % | | change_rate_5d | float | 是 | 5 日涨跌幅 | % | | change_rate_10d | float | 是 | 10 日涨跌幅 | % | | change_rate_20d | float | 是 | 20 日涨跌幅 | % | | change_rate_60d | float | 是 | 60 日涨跌幅 | % | | change_rate_120d | float | 是 | 120 日涨跌幅 | % | | change_rate_6m | float | 是 | 6 月涨跌幅 | % | | change_rate_1y | float | 是 | 1 年涨跌幅 | % | | change_rate_2y | float | 是 | 2 年涨跌幅 | % | | change_rate_3y | float | 是 | 3 年涨跌幅 | % | | change_rate_ytd | float | 是 | 今年至今涨跌幅 | % | ## 4. 用法 通过主目录 `run.py` 调用（参数均可选）： ```bash python <RUN_PY> index-list-paginated python <RUN_PY> index-list-paginated --order_by "change_rate desc" --page_size 20 --page_no 1 python <RUN_PY> index-list-paginated --order_by "name asc" --masks name,symkey,latest,change_rate --page_size 50 python <RUN_PY> index-list-paginated --filter "change_rate >= 0 AND change_rate <= 0.05" ``` 或在子 skill 目录下执行：`python scripts/handler.py` 加上上述参数。脚本输出 JSON，请求头已内置 `X-Client-Name: ft-claw`。 ## 5. 请求示例 ``` GET /api/v1/market/data/daec/indices?order_by=change_rate%20desc&page_size=20&page=1 ``` ### 完整请求示例（curl） ```bash curl -X GET "<BASE_URL>/api/v1/market/data/daec/indices?order_by=change_rate%20desc&page_size=20&page=1" \ -H 'X-Client-Name: ft-claw' \ -H 'Content-Type: application/json' ``` ## 6. 注意事项 - 涨跌幅等比率字段可能为小数形式，展示时按需乘以 100 转为百分比 - 不传 `page_size`/`page_no` 时返回全部满足条件的指数，数据量大时注意响应体积 - 完整字段以代码 Index 为准