完整性辅助 API

以下端点支撑数据完整性与时间对齐，均需 token（/health 除外，公开）。

/api/v1/calendar — 交易日历

返回交易日列表，是所有时间对齐的基准。

当前数据仅覆盖 SSE（上交所）日历，exchange=SZSE 等会返回空结果。

GET /api/v1/calendar

参数

参数	类型	说明
exchange	string	交易所（SSE/SZSE，默认 SSE）。
start_date / end_date	YYYYMMDD	日历区间。
is_open	int	是否开市（1/0），不传返回全部。

响应

GET /api/v1/calendar?exchange=SSE&is_open=1&start_date=20240102&end_date=20240108
{
  "exchange": "SSE",
  "days": [
    {"exchange": "SSE", "cal_date": "20240102", "is_open": 1},
    {"exchange": "SSE", "cal_date": "20240103", "is_open": 1},
    {"exchange": "SSE", "cal_date": "20240108", "is_open": 1}
  ],
  "data_version": "2026-08-14T22:50:21+00:00"
}

r = requests.get(f"{BASE}/api/v1/calendar",
                 params={"exchange": "SSE", "is_open": 1, "start_date": "20240101"},
                 headers=H)
days = [d["cal_date"] for d in r.json()["days"]]

/api/v1/calendar/shift — 交易日偏移

求某交易日向前/向后第 n 个交易日（n 为负 = 向前，如 -1 取前一交易日，支撑 T+1 成交与信号对齐）。

当前数据仅覆盖 SSE 日历，exchange 仅支持 SSE。

GET /api/v1/calendar/shift

参数

参数	类型	说明
date	YYYYMMDD	基准交易日（必须是交易日）。
n	int	偏移天数（正=向后，负=向前，不能为 0）。
exchange	string	交易所（默认 SSE）。

响应

GET /api/v1/calendar/shift?date=20240103&n=-1
{
  "date": "20240103",
  "n": -1,
  "exchange": "SSE",
  "result": "20240102"
}

# T+1：信号日 T 的成交日 = 下一交易日
r = requests.get(f"{BASE}/api/v1/calendar/shift",
                 params={"date": "20240103", "n": 1}, headers=H)
next_day = r.json()["result"]

/api/v1/entities/{entity}/gaps — 数据缺口

返回某实体的数据缺口区间，支撑回测前完整性自检。

GET /api/v1/entities/{entity}/gaps

参数

参数	类型	说明
start_date / end_date	YYYYMMDD	缺口区间过滤（可选）。
ts_code	string	单票过滤（可选）。

响应

GET /api/v1/entities/daily/gaps
{
  "entity": "daily",
  "gaps": [
    {"entity": "daily", "ts_code": null, "gap_start": "20240103", "gap_end": "20240103", "kind": "timeout"}
  ]
}

r = requests.get(f"{BASE}/api/v1/entities/daily/gaps", headers=H)
gaps = r.json()["gaps"]
if gaps:
    print("存在数据缺口，回测前请处理：", gaps)

/api/v1/meta — 数据目录与版本

返回 26 实体清单 + 每实体数据起止/行数/可用性 + 全局 data_version。研究快照存 data_version 可实现可复现。

GET /api/v1/meta

响应

GET /api/v1/meta
{
  "data_version": "2026-08-14T22:50:21+00:00",
  "entities": {
    "daily":      {"entity": "daily", "available": true,  "data_start": "20090105", "data_end": "20260814", "rows": 14637333},
    "income":     {"entity": "income", "available": true, "data_start": "19941231", "data_end": "20260331", "rows": 317099},
    "index_daily": {"entity": "index_daily", "available": true, "data_start": "20090105", "data_end": "20260814", "rows": 29390762}
  }
}

import requests
r = requests.get(f"{BASE}/api/v1/meta", headers=H)
meta = r.json()
print("数据版本:", meta["data_version"])
for k, v in meta["entities"].items():
    if v["available"]:
        print(k, v.get("data_start"), "→", v.get("data_end"), f"{v.get('rows')} 行")

/health — 存活与就绪

公开端点（无需 token）。返回服务状态、当前 data_version 与各分库连接状态。

GET /health

响应

{
  "status": "ok",
  "data_version": "2026-08-14T22:50:21+00:00",
  "databases": {"market": true, "auction": true, "reports": true, "reference": true,
                "state": true, "finance": true, "index": true}
}