edit | blame | history | raw

前复权 K 线补数服务 HTTP 与 MySQL 使用说明

  • 适用对象：内部同事通过 HTTP 触发补数任务，并通过 MySQL 读取前复权 K 线数据。
  • HTTP 外部地址：http://317w7246e5.vicp.fun:12181
  • MySQL 外部地址：317w7246e5.vicp.fun:50176
  • MySQL 数据库：trading_xuntou
  • MySQL 用户：root
  • MySQL 密码：请向服务负责人获取，正式文档不写明文密码。

1. 使用原则

  1. HTTP 接口只用于提交任务、查询任务状态、查询覆盖率、触发修复和触发 60 分钟线派生。
  2. 行情数据读取以 MySQL 为主，不建议通过 HTTP 查询大批量行情。
  3. 当前 K 线主表均为前复权口径，优先使用 *_front 表。
  4. 分钟线任务数据量很大，禁止随意提交全 A 多年分钟线任务。
  5. 大范围分钟线补数建议按月份执行，参数使用 download_policy=missing。
  6. 轮询任务状态建议间隔 10-30 秒，不要高频请求。

2. HTTP 接口清单

方法 路径 用途
GET /health 检查服务是否在线
POST /jobs 提交补数或校验任务
GET /jobs 查询最近任务列表
GET /jobs/{job_id} 查询单个任务状态
GET /coverage 查询覆盖统计
POST /repair 提交缺口修复任务
POST /derive_60m 从本地 1m 派生 60m

3. 常用 HTTP 示例

检查服务：

curl "http://317w7246e5.vicp.fun:12181/health"

提交单股日线补数：

curl -X POST "http://317w7246e5.vicp.fun:12181/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "history_backfill",
    "periods": ["1d"],
    "start_date": "2026-05-01",
    "end_date": "2026-05-26",
    "symbols": ["600519.SH"],
    "batch_size": 1,
    "download_policy": "missing",
    "reason": "manual_single_symbol_daily"
  }'

提交小范围分钟线补数：

curl -X POST "http://317w7246e5.vicp.fun:12181/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "history_backfill",
    "periods": ["1m"],
    "start_date": "2026-05-20",
    "end_date": "2026-05-20",
    "symbols": ["600519.SH", "000001.SZ"],
    "batch_size": 50,
    "workers": 1,
    "download_policy": "missing",
    "reason": "manual_small_minute_patch"
  }'

提交全 A 单月分钟线补数：

curl -X POST "http://317w7246e5.vicp.fun:12181/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "history_backfill",
    "periods": ["1m"],
    "start_date": "2026-05-01",
    "end_date": "2026-05-31",
    "batch_size": 50,
    "workers": 2,
    "download_policy": "missing",
    "reason": "manual_full_a_month_1m"
  }'

查询任务状态：

curl "http://317w7246e5.vicp.fun:12181/jobs/FKL_xxx"

查询最近任务：

curl "http://317w7246e5.vicp.fun:12181/jobs?limit=20"

查询覆盖统计：

curl "http://317w7246e5.vicp.fun:12181/coverage?period=1m&start_date=2026-05-01&end_date=2026-05-31&limit=200"

触发本地 1m -> 60m 派生：

curl -X POST "http://317w7246e5.vicp.fun:12181/derive_60m" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-05-20",
    "end_date": "2026-05-20",
    "symbols": ["600519.SH"],
    "batch_size": 50,
    "reason": "manual_derive_60m"
  }'

4. POST /jobs 参数说明

参数 类型 说明 推荐值
mode string 任务模式 history_backfill、incremental、validate
periods array 粒度 ["1d"]、["1m"]、["60m"]
start_date string 开始日期 YYYY-MM-DD
end_date string 结束日期 YYYY-MM-DD
symbols array/string 股票列表；不传表示全 A 小任务建议显式传
batch_size int 每批股票数 1m 建议 50
workers int 批次并发数 1 或 2
download_policy string 下载策略 建议 missing
reason string 任务说明 建议填写

download_policy 说明：

值 含义
none 不主动下载，直接读取迅投本地已有数据
force 强制调用迅投下载
missing 先查本地 MySQL，已有足够数据就跳过，不足再下载

5. 任务状态说明

字段 说明
job_id 任务 ID，后续查询状态使用
status pending、running、success、partial_success、failed、cancelled
total_batches 总批次数
completed_batches 已完成批次数
failed_batches 失败批次数
rows_written 写入影响行数
last_error 最近错误
batch_errors 批次错误列表

6. MySQL 主表说明

6.1 日线表

表名：cn_stock_kline_1d_front

用途：前复权日 K 线。

核心字段：

字段 说明
symbol 股票代码，例如 600519.SH
trade_date 交易日
open 前复权开盘价
high 前复权最高价
low 前复权最低价
close 前复权收盘价
pre_close 前复权昨收
volume 成交量
amount 成交额
turnover 迅投返回的换手/成交相关字段
source_batch_id 写入批次

6.2 分钟线表

表名：cn_stock_kline_1m_front

用途：前复权 1 分钟 K 线。

核心字段：

字段 说明
symbol 股票代码
bar_time 分钟时间
open 前复权开盘价
high 前复权最高价
low 前复权最低价
close 前复权收盘价
volume 成交量
amount 成交额
turnover 迅投返回字段
source_batch_id 写入批次

6.3 60 分钟线表

表名：cn_stock_kline_60m_front

用途：前复权 60 分钟 K 线；可以由迅投直接提供，也可以从本地 1m 派生。

字段与 cn_stock_kline_1m_front 基本一致，时间字段同为 bar_time。

6.4 覆盖统计表

表名：cn_stock_kline_front_coverage_daily

用途：按交易日和粒度统计覆盖情况，判断是否补齐。

核心字段：

字段 说明
period 1d、1m、60m
trade_date 交易日
table_name 对应物理表
row_count 当天该粒度总行数
symbol_count 当天覆盖股票数
expected_symbol_count 期望股票数
coverage_ratio 覆盖率
min_bar_time 分钟/60 分钟最早时间
max_bar_time 分钟/60 分钟最晚时间

7. 常用 SQL

查单股日线：

SELECT symbol, trade_date, open, high, low, close, pre_close, volume, amount
FROM cn_stock_kline_1d_front
WHERE symbol = '600519.SH'
  AND trade_date BETWEEN '2026-05-01' AND '2026-05-26'
ORDER BY trade_date;

查单股分钟线：

SELECT symbol, bar_time, open, high, low, close, volume, amount
FROM cn_stock_kline_1m_front
WHERE symbol = '600519.SH'
  AND bar_time >= '2026-05-20 00:00:00'
  AND bar_time <  '2026-05-21 00:00:00'
ORDER BY bar_time;

查单股 60 分钟线：

SELECT symbol, bar_time, open, high, low, close, volume, amount, source
FROM cn_stock_kline_60m_front
WHERE symbol = '600519.SH'
  AND bar_time >= '2026-05-20 00:00:00'
  AND bar_time <  '2026-05-21 00:00:00'
ORDER BY bar_time;

查某日全 A 日线覆盖：

SELECT period, trade_date, row_count, symbol_count, expected_symbol_count, coverage_ratio
FROM cn_stock_kline_front_coverage_daily
WHERE period = '1d'
  AND trade_date = '2026-05-20';

查某月分钟线覆盖：

SELECT period, trade_date, row_count, symbol_count, expected_symbol_count, coverage_ratio, min_bar_time, max_bar_time
FROM cn_stock_kline_front_coverage_daily
WHERE period = '1m'
  AND trade_date BETWEEN '2026-05-01' AND '2026-05-31'
ORDER BY trade_date;

查覆盖不足日期：

SELECT period, trade_date, row_count, symbol_count, expected_symbol_count, coverage_ratio
FROM cn_stock_kline_front_coverage_daily
WHERE period = '1m'
  AND trade_date BETWEEN '2026-05-01' AND '2026-05-31'
  AND (expected_symbol_count IS NULL OR symbol_count < expected_symbol_count)
ORDER BY trade_date;

8. 推荐工作流

  1. 先用 HTTP /health 确认服务在线。
  2. 用 MySQL 覆盖统计表确认目标日期和粒度是否已有数据。
  3. 如果缺数据，再通过 HTTP /jobs 或 /repair 触发补数。
  4. 用 GET /jobs/{job_id} 每 10-30 秒查看任务状态。
  5. 任务完成后，再从 MySQL 主表读取数据。
  6. 如果任务产生 still_missing_after_download，由服务负责人根据 gap_records.csv 统一补缺。

9. 注意事项

  1. symbols 不传表示全 A，会产生大任务。
  2. 1m 数据量最大，建议按单日、单月或明确股票集合补。
  3. workers 建议不超过 2。
  4. 1m 的 batch_size 建议使用 50。
  5. 服务依赖本机迅投客户端、MySQL 和补数服务进程同时在线。
  6. MySQL 查询大表时必须带 symbol 和日期范围，避免全表扫描。
  7. 外部同事读取数据时优先读 *_front 表，不要混用旧的不复权表。