FTShare-Lab 查询港股 K 线（hk-candlesticks）
1. 接口描述
| 项目 | 说明 |
|---|---|
| 接口名称 | 查询港股 K 线 |
| 外部接口 | /api/v2/market/data/hk/hk-candlesticks |
| 请求方式 | GET |
| 适用场景 | 按港股代码查询日/月/季/年 K 线（来源：hkshareeodprices）；请求与响应中的代码均为 5 位数字 + .HK，服务端会转换为库内 4 位 Wind 代码查询 |
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 配合使用：
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（调试）
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