K 线 + 实时快照查询

来源同步：/Users/mac/Projects/chatgpt-codex/doc/api_Kline.md

所属接口集：K 线数据

请求 URL

GET /v1/api/kline/with_realtime

认证方式

Bearer Token（详见 认证与签名）

接口概述

返回历史 K 线并拼接当日最新一条实时分时快照。第一页（page=1）优先从 Redis 读取最多 100 条首屏缓存；若缓存缺失则从 MySQL 拉取最新 100 条并写入 Redis（TTL 36 小时）。第二页及以后统一从 MySQL 分页读取。实时数据来自 Redis 1 分钟分时序列的最新记录。

请求参数

参数	类型	必填	说明
code	string	是	股票代码，支持带市场后缀（如 600000.SH）或纯数字（如 600000）。市场识别规则同 KlineView
freq	string	是	K 线频率，仅允许 D、1m、5m
page	int	否	页码，默认 1，最小 1。第一页走 Redis 缓存，第二页起走 MySQL
page_size	int	否	每页条数，默认 100，最大 500。第一页实际返回 min(page_size, 100) 条历史

接口说明

1. code 和 freq 为必填；freq 仅允许 D、1m、5m，否则返回 400。
2. 第一页（page=1）：
3. 先尝试从 Redis 读取首屏缓存键 stockapi:kline:with_rt:hist:{freq}:{YYYYMMDD}:{code6}.{market}:page1:100。
4. 缓存命中则直接使用；未命中则从 MySQL 拉取最新 100 条（按 ts 降序），写入 Redis（TTL 36 小时）。
5. 日线（freq=D）会排除当天数据，仅返回历史日线。
6. 第二页及以后：
7. 直接从 MySQL 分页查询，按 (page-1)*page_size 偏移读取。
8. 实时快照：
9. 仅 page=1 时拼接。从 Redis stockapi:intraday:kline:1m:series:{YYYYMMDD}:{code6} 取最新一条分时记录构建快照。
10. 上证指数 000001.SH 使用 1A0001 作为分时序列别名。
11. 日线模式下，非交易日不生成快照。
12. 快照字段：ts、open、high、low、close、volume、pre_close、change、pct_chg、amount、turnover_rate。
13. 快照插在 data 数组最前面。
14. 扩展字段（仅 freq=D）：
15. bigorder_net_shares：大单净量（股）。当天从 Redis 逐笔明细计算或回退到聚合桶；历史日从 TrendMetricsDaily 表读取。
16. bigorder_net_ratio：大单净比 = bigorder_net_shares / free_float_shares。
17. ma5/ma10/ma20/ma60/ma180：均线。当天从 Redis bigdata 哈希读取，历史日从 TrendMetricsDaily 读取。
18. daily_vol_ratio：量比。当天从 Redis 读取，历史日从 TrendMetricsDaily 读取。
19. price_speed_ratio：价速比。当天从 Redis 读取或按 价格涨跌幅 / 量比 计算，历史日从 TrendMetricsDaily 读取。
20. trend_strength：趋势强度（0~1），综合大单净量 EMA、换手率 Z-score、涨幅 RPS 加权计算。当天优先从 Redis/静态化结果取，否则实时计算；历史日从 TrendMetricsDaily 读取。
21. turnover_rate：换手率。历史日从 MySQL KlineData 表补充；当天按 state.volume / free_float_shares × 100 计算。

响应格式示例

{
  "code": 1,
  "message": "success",
  "data": [
    {
      "ts": "2026-01-15 15:00:00",
      "open": 7.5,
      "high": 7.6,
      "low": 7.4,
      "close": 7.55,
      "volume": 1000000,
      "pre_close": 7.48,
      "change": 0.07,
      "pct_chg": 0.94,
      "amount": 7550000.0,
      "turnover_rate": 0.1234,
      "bigorder_net_shares": 50000,
      "bigorder_net_ratio": 0.00062,
      "ma5": 7.52,
      "ma10": 7.50,
      "ma20": 7.48,
      "ma60": 7.45,
      "ma180": 7.40,
      "daily_vol_ratio": 1.23,
      "price_speed_ratio": 0.56,
      "trend_strength": 0.68
    }
  ]
}

返回状态

状态码	说明
200	成功
400	code 或 freq 缺失，或 freq 不在 D/1m/5m 范围内
401	未认证
403	无权限

---