hk-candlesticks

# 查询港股 K 线（hk-candlesticks） ## 1. 接口描述 | 项目 | 说明 | |------|------| | 接口名称 | 查询港股 K 线 | | 外部接口 | `/api/v2/market/data/hk/hk-candlesticks` | | 请求方式 | GET | | 适用场景 | 按港股代码查询日/月/季/年 K 线；请求与响应中的代码均为 **5 位数字 + `.HK`** | ## 2. 请求参数 | 参数名 | 类型 | 是否必填 | 描述 | 取值示例 | 备注 | |--------|------|----------|------|----------|------| | trade_code | string | 是 | 港股代码 | 00700.HK | 支持 `700` 或 `00700.HK`，响应中统一为 5 位 + `.HK` | | interval_unit | string | 是 | K 线间隔单位 | day | 取值：`day`、`month`、`quarter`、`year`（kebab-case 序列化） | | until_date | string | 是 | 结束日期 | 2026-03-24 | 格式 `YYYY-MM-DD` | | since_date | string | 否 | 开始日期 | 2026-01-01 | 不传则从库中最早数据起至 `until_date` | | adjust_kind | string | 否 | 复权类型 | forward | 默认 `forward`（前复权）；`none` 为不复权 | | interval_value | int | 否 | 间隔数值 | 1 | 当前仅支持 `1`，其它值会报错 | | limit | int | 否 | 返回条数上限 | 100 | 日 K 在 SQL 层下推；月/季/年在聚合后截取最近 N 根 | ## 3. 响应说明 返回值为 **`HkCandlesticksResponse`**：`trade_code` + K 线数组 `items`。 ### HkCandlesticksResponse 结构 | 字段名 | 类型 | 是否可为空 | 说明 | 单位 | |--------|------|------------|------|------| | trade_code | String | 否 | 规范化后的港股代码（5 位 + `.HK`） | - | | items | Array | 否 | K 线列表，按日期升序 | - | ### HkCandlestick 结构（items 元素） | 字段名 | 类型 | 是否可为空 | 说明 | 单位 | |--------|------|------------|------|------| | open | String | 否 | 开盘价 | 元 | | high | String | 否 | 最高价 | 元 | | low | String | 否 | 最低价 | 元 | | close | String | 否 | 收盘价 | 元 | | date | String | 否 | 交易日 | `YYYY-MM-DD` | | turnover | String | 否 | 成交额 | 元 | | volume | int64 | 否 | 成交量 | 股 | ### 时区说明 `since_date` / `until_date` 及响应中的 `date` 均为 **港交所交易日历（UTC+8 / 东八区）** 日期。若 Agent 所在系统时区非东八区，计算「今天」等相对日期时应先转为东八区再传参。Handler 内置了东八区容错：若传入 ISO 8601 含时区的字符串，会自动转为东八区后截取日期部分。 ## 4. 调用方式 本 handler 与上级 `FTShare-hk-data/run.py` 配合使用： ```bash python <RUN_PY> hk-candlesticks --trade-code 00700.HK --interval-unit day --until-date 2026-03-24 --since-date 2026-03-01 --limit 20 python <RUN_PY> hk-candlesticks --trade-code 00700.HK --interval-unit month --until-date 2026-03-24 --limit 12 ``` 其中 `<RUN_PY>` 为 `FTShare-hk-data/run.py` 的绝对路径。 CLI 统一使用 **kebab-case** 长选项名：`--trade-code`、`--interval-unit`、`--until-date`、`--since-date`、`--adjust-kind`、`--interval-value`；查询串参数名仍为接口文档中的 snake_case。 ### 直接执行 handler（调试） ```bash python scripts/handler.py --trade-code 00700.HK --interval-unit day --until-date 2026-03-24 ``` （需在 `sub-skills/hk-candlesticks` 目录下执行，或传入脚本完整路径。） ## 5. 请求示例 ``` GET /api/v2/market/data/hk/hk-candlesticks?trade_code=00700.HK&interval_unit=day&since_date=2026-03-01&until_date=2026-03-24&limit=20 ```