数据调用示例

本文档提供数据管理系统的常见使用场景和 API 调用示例。

前置准备

所有数据管理接口默认需要管理员权限（require_admin 依赖）。

# 登录获取 token（请使用管理员账号，严禁在文档中写入真实凭据）
curl -X POST http://localhost:6789/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<admin-user>","password":"<admin-password>"}'

# 后续请求携带 token
TOKEN="<返回的 access_token>"
AUTH="Authorization: Bearer $TOKEN"
BASE="http://localhost:6789/api/v1/datamgr"

场景一：自选股管理完整流程

1. 导入自选股（Excel）

curl -X POST "$BASE/portfolio/import" \
  -H "$AUTH" \
  -F "file=@my_stocks.xlsx"

响应（经 EnvelopeMiddleware 包裹，results 为原始返回，total 被提升为 stats.total）:

{
  "ok": true,
  "schema_version": 1,
  "results": {"status": "success", "saved": 18, "skipped": 2, "message": "成功导入 18 条自选股数据（跳过 2 行）"},
  "stats": {"total": 20}
}

2. 批量下载核心数据

curl -X POST "$BASE/download-batch" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "codes": ["600519", "000001", "300750"],
    "taskTypes": ["kline", "quote", "finance", "valuation", "fund_flow"]
  }'

3. 检查数据完整性

# 全局统计（50 张受监控表）
curl "$BASE/stats" -H "$AUTH"

# 单只股票完整状态（26 类维度）
curl "$BASE/stats/600519/full" -H "$AUTH"

4. 检查数据新鲜度

# 52 类关键维度新鲜度
curl "$BASE/stats/freshness" -H "$AUTH"

响应示例（数据过期）——该端点响应体没有 items/results/data 键， EnvelopeMiddleware 会把整个 payload 放进 results：

{
  "ok": true,
  "schema_version": 1,
  "query_time": "2026-09-21T19:30:00",
  "results": {
    "isFresh": false,
    "staleDimensions": ["fox_kline_daily", "fox_fund_flow_daily"],
    "details": {
      "fox_kline_daily": {"latestDate": "2026-09-18", "cutoff": "2026-09-21", "isStale": true}
    }
  },
  "data_availability": {"kline": false, "valuation": false, "moneyflow": false, "quote": false, "finance": false},
  "disclaimer": "数据仅供参考，不构成投资建议。"
}

场景二：个股深度数据获取

下载全部类型

# 全量下载（38 种数据；types 可选值见 Swagger /docs 中该参数的枚举描述）
curl -X POST "$BASE/download/600519?types=all" -H "$AUTH"

按需选择性下载

# 仅下载 K线 + 行情
curl -X POST "$BASE/download/600519?types=kline" -H "$AUTH"

# 下载基本面数据
curl -X POST "$BASE/download/600519?types=finance" -H "$AUTH"

# 下载龙虎榜 + 大宗交易（晚间披露）
curl -X POST "$BASE/download/600519?types=dragon_tiger" -H "$AUTH"
curl -X POST "$BASE/download/600519?types=block_trade" -H "$AUTH"

# 下载公告和新闻
curl -X POST "$BASE/download/600519?types=announcements" -H "$AUTH"
curl -X POST "$BASE/download/600519?types=news" -H "$AUTH"

# 下载量化数据
curl -X POST "$BASE/download/600519?types=fin_indicator" -H "$AUTH"

获取实时行情（不入库）

# 实时盘口
curl "$BASE/realtime/600519/quote" -H "$AUTH"

# 分钟K线（5分钟级别）
curl "$BASE/realtime/600519/minute-kline?period=5" -H "$AUTH"

# 分钟资金流向
curl "$BASE/realtime/600519/fund-flow-minute" -H "$AUTH"

场景三：全A股数据浏览与更新

浏览全A股（`fox_stock_wide` 融合宽表）

# 分页查询
curl "$BASE/stock-base/list?page=1&pageSize=50" -H "$AUTH"

# 按行业筛选（腾讯三级口径）
curl "$BASE/stock-base/list?industry=白酒" -H "$AUTH"

# 按申万一级/二级行业代码筛选（801010 / 801012）
curl "$BASE/stock-base/list?sw_l1=801010" -H "$AUTH"

# 按关键字搜索
curl "$BASE/stock-base/list?keyword=茅台" -H "$AUTH"

全A股数据更新（fox 融合层）

stock-base 写端点已废弃

/stock-base/import、/stock-base/sync、/stock-base/sync-tencent、/stock-base/sync-tdx、 /stock-base/sync-full、/stock-base/backfill、/stock-base/backfill-stock-info、 /stock-base/fetch-staging、/stock-base/promote、/finance/sync-tdx 等写端点依赖的 stock_base_info 表已于 2026-08-22 移除，现恒返回 {"status": "deprecated"}；数据更新统一走 fox 融合链路。

# 全市场全量融合（21 类，后台线程执行，立即返回 202，进度查 /fox/status）
curl -X POST "$BASE/fox/sync" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{}'

# 指定股票融合（≤500 只，快）
curl -X POST "$BASE/fox/sync" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"codes":["600519"]}'

# 查看融合状态 / 宽表
curl "$BASE/fox/status" -H "$AUTH"
curl "$BASE/fox/stock/600519" -H "$AUTH"

全市场模式需同时持有三域锁，任一被占 → HTTP 409（避免与 16:00/16:20 定时融合并发写同一批表）
日常全市场增量由定时任务承担（fox_kline_sync 15:40 / fox_daily_sync 16:00 / fox_wide_sync 16:20），无需手动调用

场景四：市场级数据获取

# 全市场涨跌统计（实时，TDX TCP）
curl "$BASE/market/stat" -H "$AUTH"

# 行业涨跌排名
curl "$BASE/market/industry-ranking?top_n=20" -H "$AUTH"

# 北向资金实时
curl "$BASE/realtime/northbound" -H "$AUTH"

# 东财 7x24 滚动快讯
curl "$BASE/market/global-news?page_size=50" -H "$AUTH"

# 同花顺强势股 + 题材
curl "$BASE/market/hot-stocks" -H "$AUTH"

场景五：数据维护与清理

清理历史数据

# 清理所有时序表超过 365 天的旧数据（days 为显式参数，按需调整；
# 定时任务 data_cleanup 的默认保留期是 3 年，此处不传 days 会用 API 默认 365 天）
curl -X POST "$BASE/cleanup" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"days": 365}'

# 按表清理（如只清理K线）
curl -X POST "$BASE/cleanup" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"table": "fox_kline_daily", "days": 180}'

查看同步日志

curl "$BASE/sync-logs?limit=30" -H "$AUTH"

系统探针（18 项数据源连通性 + 熔断器状态）

curl "$BASE/probe-all" -H "$AUTH"

场景六：定时任务管理

# 查看任务列表
curl "$BASE/schedule" -H "$AUTH"

# 查看调度器运行状态
curl "$BASE/schedule/status" -H "$AUTH"

# 手动触发某个任务
curl -X POST "$BASE/schedule/eod_core/run" -H "$AUTH"

# 启用/禁用任务
curl -X PUT "$BASE/schedule/eod_core" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# 修改触发时间（如改为 16:00）
curl -X PUT "$BASE/schedule/eod_core" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"triggerHm": 1600}'

Python 调用示例

import requests

BASE = "http://localhost:6789/api/v1/datamgr"
TOKEN = "<your_token>"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# 批量下载自选股数据
def sync_portfolio_stocks():
    # 1. 获取自选股列表
    resp = requests.get(f"{BASE}/portfolio", headers=HEADERS)
    stocks = resp.json()["stocks"]
    codes = [s["code"] for s in stocks]

    # 2. 批量下载
    resp = requests.post(
        f"{BASE}/download-batch",
        headers=HEADERS | {"Content-Type": "application/json"},
        json={
            "codes": codes,
            "taskTypes": ["kline", "quote", "finance", "valuation"]
        }
    )
    print(f"批量下载结果: {resp.json()}")

    # 3. 检查新鲜度
    resp = requests.get(f"{BASE}/stats/freshness", headers=HEADERS)
    freshness = resp.json()
    if not freshness["isFresh"]:
        print(f"⚠️ 数据过期维度: {freshness['staleDimensions']}")
    else:
        print("✅ 数据新鲜")

# 周期性全市场更新（走 fox 融合层）
def daily_update():
    # 触发全市场融合（后台执行，202 立即返回）
    resp = requests.post(f"{BASE}/fox/sync", headers=HEADERS, json={})
    print(f"融合触发: {resp.json()['status']} mode={resp.json()['mode']}")

    # 查融合状态（各表行数/质量/最近任务）
    resp = requests.get(f"{BASE}/fox/status", headers=HEADERS)
    status = resp.json()
    print(f"融合表: {list(status.get('tables', {}).keys())[:5]} ...")

错误处理

/api/v1/datamgr/* 的 JSON 响应统一经 EnvelopeMiddleware 包裹（白名单除外）：

// 成功（原裸对象被包进 results，其余顶层键合并到信封）
{
  "ok": true,
  "schema_version": 1,
  "query_time": "2026-09-21T16:30:00",
  "results": {"kline": {"status": "success", "saved": 120}, "...": "..."},
  "data_availability": {"kline": true, "valuation": false, "moneyflow": false, "quote": false, "finance": false},
  "disclaimer": "数据仅供参考，不构成投资建议。"
}

// 失败（4xx/5xx 直接透传，不包裹）
{"detail": "未知类型: xxx"}

约定要点：

规则	说明
`{ok: true}`	端点未自带 `ok` 字段时才包裹；已带 `ok` 的响应原样透传
`results` 提取	原响应含 `items`/`results`/`data` 键时提升为信封 `results`，否则整个对象放进 `results`
`stats.total`	原响应含 `total`/`count` 时提取到 `stats`
4xx/5xx	不包裹，按 FastAPI 默认 `{"detail": ...}` 返回（避免错误被误判为成功）
白名单	`/datamgr/stock-base/list`、`/tasks/runs
鉴权	401 = 未登录/Token 过期；403 = 非管理员

数据库不可用时，下载类端点返回 status: "failed" + message（如 "数据库不可用"），HTTP 状态码仍为 200。

前置准备​

场景一：自选股管理完整流程​

1. 导入自选股（Excel）​

2. 批量下载核心数据​

3. 检查数据完整性​

4. 检查数据新鲜度​

场景二：个股深度数据获取​

下载全部类型​

按需选择性下载​

获取实时行情（不入库）​

场景三：全A股数据浏览与更新​

浏览全A股（fox_stock_wide 融合宽表）​

全A股数据更新（fox 融合层）​

场景四：市场级数据获取​

场景五：数据维护与清理​

清理历史数据​

查看同步日志​

系统探针（18 项数据源连通性 + 熔断器状态）​

场景六：定时任务管理​

Python 调用示例​

错误处理​

相关文档​