# 前复权 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 示例

检查服务：

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

提交单股日线补数：

```bash
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"
  }'
```

提交小范围分钟线补数：

```bash
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 单月分钟线补数：

```bash
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"
  }'
```

查询任务状态：

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

查询最近任务：

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

查询覆盖统计：

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

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

```bash
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

查单股日线：

```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;
```

查单股分钟线：

```sql
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 分钟线：

```sql
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 日线覆盖：

```sql
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';
```

查某月分钟线覆盖：

```sql
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;
```

查覆盖不足日期：

```sql
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` 表，不要混用旧的不复权表。