- CLI:init/serve/update/query/export/status(typer + rich),单写者锁三元判活 - 存储:DuckDB schema migrations(14 表 + 8 联邦视图,语句元组逐条执行) - ETL:A股证券/日历/日K,整区替换幂等;日历全年补全(calendar 语义唯一) - 网关:POST /v1/query(线程池 + interrupt 超时 504)、/v1/export、meta/stats/state、healthz/ready - 安全:SQL 闸 sqlglot fail-closed(文件/网络表函数默认拒)、非 loopback 空 token 拒启、导出路径双判 - 验收:254 测试全绿、1265 语句 100% 覆盖、[CI] 真起服验收链、smoke_m1.py 交付自检 - 文档:设计文档 v0.7(圆桌 45 条采纳 + 3 条实施校准),README 重写 - 发布:release.yml Trusted Publishing(OIDC 免密钥),action refs 已核验
72 KiB
pyquantdata(CLI 名 quantdata)设计方案
版本:v0.7(M1 实施校准版)
日期:2026-09-23
修订:v0.2 —— ①数据源调整(去 tqcenter,加 yfinance 参考 + akshare 摘抄/primp 兜底,不安装 akshare)②调度任务脚本化(dbpath/scripts/ 每任务一脚本)③config.json 扩展(抓取时间/代理服务器/数据源要求)
评审:v0.3 —— 八项开放问题全部拍板(§16 转为决策记录):质量校验确认 / 起始年限 cn2004·us2020·hk2020 / 暂缓品类走可扩展结构 / 研报·申万=akshare 摘抄 / 3s 快照够用 / nats-server 随库自带不依赖预装 / 部署=Linux / 加 union 视图
修订:v0.4 —— NATS 去掉 local/remote/none 三模式(宝爷提议):客户端只剩 servers(默认 nats://127.0.0.1:4222)+ autostart(仅本机且无监听才拉起 bin/nats-server)+ enabled(false=纯 CLI)
修订:v0.5 —— 放弃 NATS(宝爷拍板 A 方案):对外服务改为 serve 进程内 FastAPI —— REST 管 query/export/meta/stats,WebSocket /v1/stream 管订阅推送(quote/state/news/flow/ev);--no-http 纯 CLI
修订:v0.6 —— 圆桌评审 45 条全采纳(6 席全票「修改后可实施」):新增 §7.6 事件循环隔离、SQL 函数默认拒绝、compaction 两阶段 .trash 协议、覆盖率排除白名单、验收数据两层、qlib 测试两层、news 表 DDL、复权口径、WS 统一时序、export 同步/异步归位
修订:v0.7 —— M1 实施校准 3 条(实施阶段才暴露、评审阶段发现不了的):DP-1 §11 锁判活从「三元一致」改为可实现的「PID 存活 + 三元全可读且一致」,后两项降为补强证据、取不到即接管(否则锁死库);DP-2 §14 白名单「CI 自己真起服」表述纠偏 —— CI 的真是用 CLI 起真 serve + 真端口 curl(用户面全覆盖),仅 runtime.py uvicorn/socket 段 pragma 豁免,真起服交付自检交每周 smoke;DP-3 §14 验收 fixture 表名笔误(cn_stock_1d 实为 bars_1d,视图名≠物理表名)。
定位:单目录自包含、三市场(A/美/港)覆盖的量化数据中台 —— init 建库回填,serve 常驻更新 + 每日质检 + 通过 FastAPI(REST+WebSocket)对外服务。
0. 结论摘要(TL;DR)
| 维度 | 决策 | 理由 |
|---|---|---|
| 形态 | 单一 Python 包 pyquantdata,入口命令 quantdata;一切状态收敛在 -d 指定的 dbpath;dbpath/config.json 统一配置抓取数据时间、代理服务器、数据源要求 |
换机器 = 拷一个目录;与 pytdxdata/pywestockdata 同风格(uv + src-layout) |
| 存储 | DuckDB(参考数据、日K、公告研报、元数据)+ Parquet 分区文件(1分钟K线),查询层用统一视图联邦 | 1m 数据是几十亿行量级,Parquet 分区不可变文件最适合"每日增量追加";DuckDB 负责小表事务与秒查;两层用视图缝合,SQL 无感 |
| 写入模型 | 单写者:只有 serve(或一次性 update/backfill)持有写锁;查询/导出一律只读 |
DuckDB 单写多读 + Parquet 不可变文件,天然无并发写冲突 |
| 服务协议 | FastAPI 进程内网关(REST + WebSocket):serve 单进程同起 uvicorn(默认 127.0.0.1:8765);/v1/query 等 REST 管请求-响应,/v1/stream WebSocket 管订阅推送;--no-http = 纯本地仅 CLI |
一条进程零外部依赖;开内网只改 host(+token) |
| 对外服务 | 三类:① REST POST /v1/query / POST /v1/export / GET /v1/meta;② WS /v1/stream 行情快照 + 自选股逐笔;③ WS 事件流 市场状态 / 分钟新闻 / 公告研报 / ETL进度 / 质检报告 |
对应你列的三种服务形式,全部走 HTTP 路径 + WS topic 分层 |
| 数据源 | pytdxdata 为主(三市场K线/行情/复权/期货/期权),pywestockdata 为辅(A股实时与财务交叉验证、公告分红),美/港参考 yfinance;长尾兜底移植 akshare 源码(摘抄其实现、改用 primp 发请求过反爬,不安装 akshare 库);日历/状态机吸收 market-event-driver;新闻采集脚本归入 dbpath/scripts/ | 不重造轮子,全部是已有项目 |
| 历史回填 | 支持 seed 导入:直接把 stock_prediction 已有的 A股 1m(2004 至今)搬进库,避免重复回填 22 年 | 手上有现成数据 |
| 容量 | 默认口径估算 数据 300–400 GB + 运行 buffer ≥200GB(预算口径 ~600GB,见 §3.4);起始年限已确认 cn=2004 / us=2020 / hk=2020 | 建库前先给用户看到磁盘预算 |
1. 目标、非目标、假设
1.1 目标(来自需求)
- 初始化:
quantdata init -d /xxx/dbpath/—— 自动建目录结构、建元数据库、按配置回填各市场历史数据,断点可续。 - 日常更新:
quantdata serve -d /xxx/dbpath/—— 常驻进程:盘中增量更新、收盘后日频任务、每日数据质量校验,并常驻对外服务。 - 对外服务(HTTP + WebSocket):
query_sql:执行 SQL 查询(请求/响应);export:导出 backtrader / qlib / pandas / polars / csv 等格式;- 订阅:股票实时行情、市场状态变化(开盘/收盘/午休等)、分钟级新闻推流。
- 数据范围:A股(指数、股票、期货、可转债、ETF/LOF、REITS、期权的证券信息、交易日历、1m K、日K、除权除息、公告、研报、申万行业、ST、停牌、涨跌停);美股、港股(指数、股票、期货、ETF/LOF、REITS 等证券信息、交易日历、1m K、日K)。
- 对外服务协议:默认 serve 进程内 FastAPI(REST + WebSocket),零外部依赖;NATS 方案已放弃(v0.5 拍板)。
1.2 非目标(明确边界,防止范围膨胀)
- ❌ 因子计算 / 特征工程 —— 归 factor-pipeline / vxdata,quantdata 只负责把干净的原始数据喂出去;
- ❌ 回测引擎 / 交易执行 —— export 成 backtrader/qlib 格式供那边用;
- ❌ 逐笔撮合级实时行情 —— 实时层是 秒级快照 + 自选股 tick,不是 Level-2;
- ❌ 多租户权限体系 —— v1 是单用户/内网工具,认证靠可选
http.token(默认空 = 内网免认证)。
1.3 评审已确认事项(2026-09-23 拍板)
| 事项 | 决策 |
|---|---|
| "每日对数据进行…" | ✅ 每日数据质量校验(gap / OHLC / 涨跌停 / 复权对账 / 双源抽查 1%),见 §7.5 |
| 各市场起始年限 | ✅ cn=2004、us=2020、hk=2020 |
| 美股可转债 / LOF 等无零售级数据源的品类 | ✅ 先放空,走可扩展结构:结构预留、需要时写一个 scripts/ 采集脚本即可接入(机制见 §4.2) |
| 研报 / 申万行业数据源 | ✅ akshare 对应接口(研报 choices 等),摘抄源码 + primp 重写请求,不安装 akshare |
| 实时行情精度 | ✅ 3 秒快照 + 自选 tick,不做逐笔 |
| 对外服务协议 | ✅ v0.5 改判:放弃 NATS —— serve 进程内 FastAPI:REST 管 query/export,WS /v1/stream 管订阅;一条进程全包 |
| 部署目标 | ✅ Linux 服务器长期常驻(supervisord),Windows 仅开发用 |
| 跨市场 union 视图 | ✅ 加 bars_1m_all(见 §3.3) |
2. 总体架构
┌────────────────────────────────────────────────┐
quantdata init │ 本机 / 服务器 │
quantdata serve │ │
quantdata query ──▶ CLI (typer+rich) │
quantdata export │ │
│ ┌───────────── 应用层(serve 常驻)───────────┐ │
│ │ Scheduler 调度器(任务=dbpath/scripts/*.py 每任务一脚本,META 声明触发时机) │ │
│ │ ├─ IntradayUpdater 盘中 1m/快照 增量 │ │
│ │ ├─ DailyJob 收盘后日频任务链 │ │
│ │ ├─ QualityChecker 每日质检 │ │
│ │ ├─ StateEngine 市场状态机(开盘/午休…) │ │
│ │ ├─ QuotePoller 实时行情轮询→推流 │ │
│ │ └─ NewsBridge 新闻采集→分钟窗口推流 │ │
│ └────────────────────────────────────────────┘ │
│ ┌────────── 服务网关(FastAPI 同进程)─────────┐ │
│ │ REST: /v1/query /v1/export /v1/meta /stats │ │
│ │ WS: /v1/stream (quote state news flow ev) │ │
│ │ --no-http 可关;Swagger 自带 /docs │ │
│ └────────────────────────────────────────────┘ │
│ ┌───────────── 存储层 ───────────────────────┐ │
│ │ catalog.duckdb 参考数据/日K/公告/元数据 │ │
│ │ data/**/*.parquet 1m K线(分区、不可变) │ │
│ │ exports/ logs/ tmp/ quantdata.lock │ │
│ └────────────────────────────────────────────┘ │
└───────────────────────┬────────────────────────┘
│ SourceAdapter 协议
┌───────────────────────┴────────────────────────┐
│ pytdxdata(主:三市场K线/行情/复权/期货/期权) │
│ pywestockdata(辅:A股实时/财务/公告/分红/交叉源) │
│ yfinance(美/港参考) 静态节假日表(日历兜底) │
│ akshare 兜底(摘抄源码+primp 请求,不装库) │
│ 新闻采集 = dbpath/scripts/fetch_news.py │
└────────────────────────────────────────────────┘
│
┌───────────────────────▼────────────────────────┐
│ 消费端:curl / 任意 HTTP 客户端 / WebSocket 订阅 │
│ (脚本、notebook、下游服务皆可直连 serve 端口) │
└────────────────────────────────────────────────┘
**分层原则**:
| 层 | 职责 | 关键约束 |
| ---- | --------------------------- | --------------------------------- |
| CLI | 命令解析、进度展示、本地直查 | 任何命令都可离线跑(`--no-http` 时服务层降级为无) |
| 应用层 | 调度、ETL、质检、状态机、推流 | 全部幂等:重复执行不产生重复数据;DuckDB/脚本走线程池(§7.6) |
| 服务网关 | FastAPI REST + WebSocket 协议实现 | 路径带版本号 `/v1`,WS 帧带 envelope |
| 存储层 | DuckDB + Parquet + 视图联邦 | 单写者、原子替换、checkpoint 可续 |
| 源适配层 | 统一 `SourceAdapter` 接口对接各数据源 | 限速、重试、录制回放 fixtures 供测试 |
---
## 3. 存储设计
### 3.1 dbpath 目录布局
/xxx/dbpath/ ├── config.json # 库配置(init 生成,可改;JSON 格式) ├── catalog.duckdb # 元数据库:参考数据+日K+公告研报+checkpoint+jobs ├── data/ # 大数据:Parquet 分区(仅 1m K线) │ ├── cn/ │ │ ├── stock/symbol=sh600000/year=2026/month=09/20260923.parquet # 当日段(新写) │ │ │ .../month=09.parquet # 月度合并(compaction 后) │ │ ├── index/… fut/… cbond/… etf/… reits/… opt/… │ ├── us/… │ └── hk/… ├── scripts/ # 抓取/更新任务脚本(每任务一文件,文件内 META 声明触发时机) │ ├── update_bars_1d.py # 示例:日K日频更新 │ ├── update_bars_1m.py # 示例:1m 盘中增量 │ └── fetch_news.py # 示例:新闻采集(news-integration 逻辑迁入) ├── exports/ # export 任务输出(按 job_id 分目录) ├── logs/ # serve 日志(按天滚动,JSON lines) ├── tmp/ # 原子写中转(写完 os.replace 到位) └── quantdata.lock # 单写者锁(PID + 启动时间)
**1m 写入策略(LSM 风格,兼顾"每日增量"与"文件数可控")**:
1. **盘中/每日增量**:每 symbol 每交易日写一个新段文件 `…/month=MM/YYYYMMDD.parquet` —— 不重写任何旧文件;
2. **月度 compaction**:每月 1 号把上月的日段合并成 `month=MM.parquet`(单 symbol 单月约 5–10k 行,合并成本毫秒级)——多文件切换走两阶段协议(见下);
3. **年度归并(可选开关)**:把 12 个月文件并成年文件,冷数据文件数从 `symbol×12×年数` 降到 `symbol×年数`。
> 1m 数据只追加新文件、不改旧文件 → 只读并发永远安全。**注意:compaction 是「写1个月段+移走12个日段」的多文件操作,`os.replace` 只保护单文件**(评审 P0),切换走两阶段协议:
> ① 月段在 tmp 合并 → `os.replace` **先入位**(此刻月段与残余日段并存);
> ② 日段 **rename 进 `.trash/` 子目录**(立即移出 glob 范围)→ **延迟 7 天再 unlink**(已枚举打开的读句柄不致 ENOENT);
> ③ 查询撞上枚举竞态(TOCTOU IO 错误)→ **自动重试一次**即恢复;compaction 后行数守恒质检照跑(§7.5),另监控「compaction 窗口内查询失败计数」。
### 3.2 为什么是 DuckDB + Parquet,而不是单选一个
| 方案 | 优点 | 放弃的原因 |
| ------------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------- |
| 全 DuckDB 单文件 | 最简单、事务完整 | 1m 全历史约 50 亿行/百 GB 级单文件,备份=整文件复制;"每日追加"要反复重写大文件;一旦损坏爆炸半径大 |
| 全 Parquet + 无引擎 | 零依赖 | 参考数据的 upsert、公告去重、checkpoint 事务都要自己造 |
| ClickHouse | 超强聚合 | 多一个常驻服务,违背"一个目录自包含";factor-pipeline 已覆盖 ClickHouse 场景 |
| **DuckDB + Parquet(选定)** | 小表事务 + 大文件追加各取所长;DuckDB 原生 `read_parquet` 联邦查询,视图缝合后 SQL 无感;与 vxdata 技术栈一致 | — |
### 3.3 联邦视图(SQL 透明层)
```sql
-- catalog.duckdb 内注册的典型视图(Hive 分区自动识别)
CREATE OR REPLACE VIEW cn_stock_1m AS
SELECT symbol, ts, date, open, high, low, close, volume, amount
FROM read_parquet('data/cn/stock/**/*.parquet', hive_partitioning = true);
CREATE OR REPLACE VIEW cn_stock_1d AS -- 日K直接物理表在 DuckDB 内
SELECT * FROM bars_1d WHERE market = 'cn' AND category = 'stock';
-- 跨层查询示例(query_sql 直接支持)
SELECT d.date, d.close, m.industry_l1
FROM cn_stock_1d d
JOIN securities s USING (symbol)
JOIN sw_industry m USING (symbol)
WHERE d.symbol = 'sh600000' AND d.date >= '2026-01-01';
-- 跨市场统一视图(评审已确认):带 market 列的 union,偷懒查询用
-- 三支一律显式列名(禁 *):float 列错位不报错,只可靠列集恒等测试拦(评审 P1)
CREATE OR REPLACE VIEW bars_1m_all AS
SELECT 'cn' AS market, symbol, ts, date, open, high, low, close, volume, amount FROM cn_stock_1m
UNION ALL SELECT 'us', symbol, ts, date, open, high, low, close, volume, amount FROM us_stock_1m
UNION ALL SELECT 'hk', symbol, ts, date, open, high, low, close, volume, amount FROM hk_stock_1m;
-- 1m 复权 = 查询期计算(bars_1m 不存因子,口径见 §4.3)
SELECT b.ts, b.close * d.adj_factor AS close_hfq
FROM cn_stock_1m b JOIN bars_1d d USING (symbol, date)
WHERE b.symbol = 'sh600000';
1m 视图按市场×品类共约 20 个,另加跨市场 union 视图
bars_1m_all(已确认);DuckDB 对symbol/year/month分区做谓词下推,单股多年查询只读命中文件。跨市场全扫时建议带 date 过滤,剪枝交给 DuckDB。 视图 schema 演进(评审 P1):全部联邦视图 DDL 纳入schema_migrations版本化(改表必同步改视图);parquet 加列 = 新列只在新段出现、历史段读为 NULL,视图COALESCE兜底,需要真回填时走一次性backfill --rewrite-schema(按需启用)。 union 列对齐:bars_1m_all三支显式列名(禁*),集成测试断言三市场视图列集/列序恒等。
3.4 容量估算(init 前提示磁盘预算)
| 数据 | 估算口径 | 行数量级 | 体积(zstd parquet / duckdb) |
|---|---|---|---|
| A股 1m | ~5000 股 × 240 行 × 243 日 × 22 年(2004→今,均摊约 60% 上市率) | ~45 亿行 | 150–200 GB |
| 美股 1m | ~4500 股 × 390 行 × 252 日 × 默认 6 年 | ~27 亿行 | ~90 GB |
| 港股 1m | ~2600 股 × 330 行 × 245 日 × 默认 6 年 | ~12 亿行 | ~45 GB |
| 三市场日K + 参考数据 + 公告研报 | — | <1 亿行 | <10 GB |
| 合计 | ~300–400 GB(默认口径) |
- 各市场
history_from已确认:cn=2004、us=2020、hk=2020(默认 1m 与日K 同起点);日K 可用history_from_bars_1d独立放宽(美/港日K 放到 2010 仅 +数 GB,长周期回测够用),历史随时backfill --from往前增量补; - 运行放大系数(评审 P1):上表 = 数据终态;另计 DuckDB WAL/日频重写临时空间、compaction 当刻 tmp 2× 峰值、
exports/(qlib 全量 float32 可达 ~100GB)、备份副本 —— 合计 +≥200GB buffer; init --estimate只算不写,按 终态 + buffer ≈ 600GB 口径报预算;export.out_dir可指到独立盘。
4. 数据模型
4.1 catalog.duckdb 核心表(DDL 摘要)
-- 参考数据 --------------------------------------------------------------
exchanges (exchange_code PK, name, market, timezone, session_json) -- 交易时段规则
securities (market, symbol, name, category, exchange, list_date, delist_date,
currency, lot_size, underlying, strike, maturity, ... , PK(market, symbol))
-- category: index/stock/future/cbond/etf/lof/reits/option
calendar (market, trade_date, is_open, note, PK(market, trade_date))
corp_actions (market, symbol, ex_date, type, ratio, cash_div, ... , PK(...)) -- 除权除息
sw_industry (version, symbol, l1, l2, l3, effective_from, effective_to) -- 申万SCD2:官方发新版/追溯修订→开新version,effective_from=官方生效日
stock_status (symbol, date, is_st, st_reason, is_suspended,
limit_up, limit_down, pct_limit, source, PK(symbol, date)) -- ST/停牌/涨跌停 合表
futures_meta (symbol, contract, multiplier, expiry, daily_limit_rule, ...) -- 期货合约要素
-- 行情(日K;1m 在 parquet)------------------------------------------------
bars_1d (market, category, symbol, date, open, high, low, close,
volume, amount, turnover, adj_factor, PK(market, category, symbol, date))
-- 信息流 ------------------------------------------------------------------
announcements (id PK, symbol, title, category, publish_ts, url, source, hash)
reports (id PK, symbol, org, analyst, rating, title, publish_ts, url, source)
news (id PK, ts, source, market, symbols_json, level, title, url, hash) -- 分钟新闻(NewsBridge 落库;断线补偿游标)
-- 运行时元数据 ------------------------------------------------------------
etl_checkpoint (dataset, market, scope, watermark, rows, status, updated_at, PK(前三个))
export_jobs (job_id PK, spec_json, fmt, path, rows, bytes, state, created_at, finished_at)
quality_reports (date, market, check_name, result, detail_json, PK(date, market, check_name))
schema_migrations(version PK, applied_at)
4.2 三市场 × 数据范围矩阵(✅ 有 / ⚠️ 有条件 / ❌ 无)
| 数据 | A股 | 美股 | 港股 | 主数据源 |
|---|---|---|---|---|
| 证券信息(指数/股票/期货/可转债/ETF/REITS/期权) | ✅ 全品类 | ⚠️ 无美债转、无 LOF、期权/期货看 TDX 覆盖 | ⚠️ 可转债/期权看 TDX 覆盖 | pytdxdata(+westock 补 A股字段) |
| 交易日历 + 交易时段 | ✅ | ✅ | ✅ | 静态节假日 + TDX 交易日 + exchange 表 |
| 1分钟K线 | ✅ | ✅ | ✅ | pytdxdata(seed:stock_prediction 现成 A股 1m) |
| 日K线 | ✅ | ✅ | ✅ | pytdxdata + pywestockdata 交叉验证 |
| 除权除息 | ✅ | ⚠️ 复权因子走 TDX | ⚠️ 同左 | TDX gbbq / westock 分红 |
| 公告信息 | ✅ | ⚠️ 覆盖面待验证 | ⚠️ 同左 | pywestockdata(东财) |
| 研报信息 | ✅ akshare 摘抄 | ⏸ 暂缓(可扩展) | ⏸ 暂缓(可扩展) | akshare 研报接口(choices 等)源码移植 + primp |
| 申万行业分类 | ✅(A股专属) | ❌ | ❌ | akshare 申万行业接口源码移植 + primp |
| ST / 停牌 / 涨跌停 | ✅ 日状态合表 | ❌(无 ST 制度) | ⚠️ 停牌✅ | westock 状态 + 规则推导(10/20/30% 分板块) |
| 实时行情 | ✅ 秒级快照 | ✅ | ✅ | pytdxdata quotes / westock 全市场 <500ms |
| 市场状态事件 | ✅ | ✅ | ✅ | StateEngine 本地推导(日历+时钟,确定性) |
| 分钟新闻 | ✅ | ✅(global feed) | ✅ | news-integration → NewsBridge |
品类可扩展机制(已确认):⏸ 暂缓品类 = 结构预留、先放空,绝不塞假数据。接入一个新品类只需三步 —— ①
config.json的 categories 加一项 → ②写一个scripts/采集脚本(META 声明)→ ③注册一条CREATE VIEW,核心代码零改动。
4.3 统一 K 线 schema
symbol: str # 规范代码:cn 用 sh600000/sz000001/bj430047,us 用 AAPL,hk 用 00700(与 pytdxdata 一致)
ts: datetime64[ns, UTC] # 1m 用 UTC 毫秒存 + exchange 本地日期做分区键(美/港跨时区不乱)
date: date32 # 交易所本地交易日(分区、日K主键)
open/high/low/close: float64
volume: float64 # A股=股/张,期货=手(在 futures_meta 有乘数)
amount: float64 # 成交额(元)
时间与复权口径(全格式统一约定,评审 P1):
- 存储一律 UTC;REST/WS JSON 时间字段一律 ISO8601 带
Z,状态类 payload 另带session_tz(如"Asia/Shanghai")标明交易所本地; - 导出(feather/csv)的 datetime 列 = tz-naive 交易所本地时间(backtrader/qlib 惯例);
- bars_1m / bars_1d 一律存不复权原始价,复权是查询期计算;source of truth =
corp_actions(TDX gbbq / westock 分红只是输入,对账以 corp_actions 重算为准);1m 取因子JOIN bars_1d USING (symbol, date)(视图示例见 §3.3),export 的 fq 参数在导出期施加;除权日无需重算历史 bars(存的就是不复权价);因子被源站修正 → 质检「复权连续性」告警并提示下游重导出。
5. 数据源适配层
5.1 SourceAdapter 协议
class SourceAdapter(Protocol):
name: str
capabilities: set[str] # {"bars_1d","bars_1m","realtime","announcements",...}
async def fetch_securities(self, market: str) -> list[Security]: ...
async def fetch_bars(self, market, category, symbol, freq, start, end) -> list[Bar]: ...
async def fetch_realtime(self, symbols: list[str]) -> list[Quote]: ...
async def fetch_calendar(self, market, year: int) -> list[CalendarDay]: ...
# 其余能力按 capabilities 声明,调度器只调度声明过的能力
5.2 源分工与交叉验证
| 能力 | 主源 | 备源(抽查 1% 对账,不一致记 quality_reports) |
|---|---|---|
| 三市场 K 线/复权/日历 | pytdxdata | pywestockdata(仅 A股日K) |
| A股实时快照 | pytdxdata quotes | pywestockdata(全市场 <500ms,作为快照源更快) |
| A股财务/分红/公告 | pywestockdata | — |
| 期货要素/行情 | pytdxdata | yfinance(参考对账) |
| 新闻 | news-integration(RSS 统一采集器) | — |
| 节假日 | 静态 holidays(market-event-driver 吸收) | TDX 交易日回调校验 |
| 研报(A股) | akshare 研报接口(choices 等,摘抄源码+primp) | — |
| 申万行业 | akshare 申万行业接口(摘抄源码+primp) | — |
| 长尾兜底 | akshare 源码移植(摘抄实现、primp 发请求,不安装 akshare) | pytdxdata/pywestockdata 优先 |
5.3 工程规则
- 限速:每源独立令牌桶(配置驱动),被限流指数退避重试;
- 断点:所有 fetch→write 以
(dataset, market, scope)为粒度写etl_checkpoint,重启续跑; - 可测试:适配层带录制模式(fixtures 标注录制日期),单测/集成测试离线回放;nightly record job 打真网重录 diff —— 生命周期规则见 §14;
- 连接级容错:TDX 断连/坏节点的重连与多服务器切换由 pytdxdata 内建,适配层只管限速与指数退避(故障注入测试见 §14);
- 代理:代理服务器在 config.json 配置(全局 + per-source 覆盖),akshare 移植源的请求一律走 primp(与 pywestockdata 同款反爬栈);
- 合规:只用公开接口与已有本地数据,遵守源站频率约定;不安装 akshare 库,只摘抄其实现逻辑。
6. CLI 设计
quantdata init -d /xxx/dbpath/ [--markets cn,us,hk] [--years-cn 22 --years-us 6 --years-hk 6]
[--seed /path/to/old_1m] [--estimate] [--skip-history]
quantdata serve -d /xxx/dbpath/ [--host 127.0.0.1] [--port 8765] [--no-http] [--insecure] # 恒前台常驻,无 daemon 模式
quantdata update -d /xxx/dbpath/ [--dataset bars_1d] [--date 2026-09-22] # 单次更新,cron 兜底
quantdata backfill -d /xxx/dbpath/ --dataset bars_1m --market cn [--from 2004] [--resume]
quantdata query -d /xxx/dbpath/ "SELECT ..." [--fmt table|csv|json|parquet] [-o out] # 本地直查,不开服务也可用
quantdata export -d /xxx/dbpath/ --fmt qlib|backtrader|csv|parquet --sql "..." -o out/
quantdata status -d /xxx/dbpath/ # 水位、锁、HTTP 服务、最近质检、磁盘占用
quantdata doctor -d /xxx/dbpath/ # 手动触发全量质检 + 修复建议
# Python 客户端标准路径(pandas 用户,评审 P1 补齐)
import httpx, base64 as b64, pyarrow as pa
r = httpx.post("http://127.0.0.1:8765/v1/query", json={
"sql": "SELECT date, close FROM cn_stock_1d WHERE symbol=? ORDER BY date DESC LIMIT 5",
"params": ["sh600000"], "fmt": "arrow"}).json()
tbl = pa.ipc.open_stream(pa.BufferReader(b64.b64decode(r["b64_arrow"]))).read_all()
df = tbl.to_pandas() # dtypes 可用 r["dtypes"] 校验
# WS 订阅:连上即收初帧(state + snapshot),断线重连=重新收初帧;新闻补偿走 query 游标
# import websockets / httpx-ws:ws://127.0.0.1:8765/v1/stream?topics=quote.snapshot,state,news.minute&market=cn
| 命令 | 行为要点 |
|---|---|
init |
①建目录+config.json ②建 DuckDB schema(schema_migrations 管版本)③拉参考数据 ④回填历史(有 --seed 先导入再增量补齐)⑤自检输出报告。幂等:重跑=续跑,不破坏已有数据 |
serve |
拿 quantdata.lock(拿不到→报已有实例 PID 后退出)→ 起调度器 → 起 FastAPI 网关(uvicorn 挂同一事件循环;bind 失败=打印占用者 PID 后非零退出,交 supervisord 退避重试)→ 前台常驻(Linux 交 supervisord,恒前台) |
query/export |
本地直连只读 DuckDB,不开服务也能用;与 serve 并存靠"单写多读"(§11) |
status/doctor |
运维入口,输出全部是结构化 JSON(--json)便于脚本化 |
全局约定:-d 可用环境变量 QUANTDATA_HOME 兜底;所有命令支持 --json 输出;进度条用 rich。
7. serve 常驻设计
7.1 组件与生命周期
serve 启动
├─ 1. 获取写锁 quantdata.lock(失败即退出;判活 = PID 存活且 start time/boot_id 可读并一致,任一取不到→陈旧锁接管,见 §11)
├─ 2. 打开 catalog.duckdb(读写)+ 校验 schema 版本(自动跑 migration;schema 版本 > 代码已知最高版 → 报错退出)
├─ 3. 启动 Scheduler(asyncio 单进程多任务;DuckDB 与 scripts 一律走线程池,见 §7.6)
├─ 4. 起服务网关:--no-http 跳过;否则 Server.serve() 挂同一事件循环起 uvicorn(默认 127.0.0.1:8765)
│ 启动校验:监听地址非 loopback 且 http.token 为空 → 拒绝启动(除非显式 --insecure,打醒目告警)
│ bind 失败(端口占用)→ 打印占用者 PID 后非零退出
├─ 5. 循环运行直到 SIGTERM:优雅关闭 = 停接新任务 → 等当前任务落 checkpoint(总预算 30s,超时主动释放锁再退出)
│ → 关 HTTP(断开 WS)→ 释放锁;supervisord 侧 stopwaitsecs=60 兜底
└─ 任意组件崩溃 ≠ 进程退出:内部 supervisor 拉起 + WS 广播 ev.update fail + 日志告警;
同一组件连续 5 次拉起失败 → 进程自杀非零退出(把故障暴露给外部监控,不许闷声吞)
7.2 调度(显式绑定 Asia/Shanghai,不读系统时区)
任务脚本化:每个抓取/更新任务是
dbpath/scripts/下的独立 Python 文件(一个任务一个脚本),文件内声明META = {"cron": "...", "dataset": "...", "market": "..."};Scheduler 启动时扫描 scripts/ 并按 META 触发,支持热加载(改脚本不用重启 serve)。用户可自行增删脚本扩展任务,无需改核心代码。config.json 的schedule段配置默认抓取时间,脚本 META 可覆盖。时区与时钟(评审 P1):调度时区显式绑定
schedule.timezone(默认Asia/Shanghai,不读系统 TZ —— 容器默认 UTC 也不会让日频链移位);每个 cron 槽记录最近触发时间戳,时钟回拨后跳过重复槽并在ev.update告警(幂等 §7.3 兜数据正确性,这里兜「跑没跑」的可观测)。
| 任务 | 触发 | 内容 |
|---|---|---|
| 盘中 1m 增量 | 各市场交易时段内每 60–120s | 拉当段 1m → 写日段文件 → 更新 checkpoint |
| 快照推流 QuotePoller | 交易时段每 3s(cn 全市场;us/hk 按 watchlist+指数) | 归一化 → WS topic=quote.snapshot(market 字段区分);watchlist 另发 topic=quote.tick |
| 状态机 StateEngine | 每秒 tick(按 exchange.session_json 确定性推导) | 状态迁移时向 WS 推一次 topic=state(不刷屏;重连对齐时序统一见 §8.2 客户端模式) |
| 收盘日频链(A股) | 15:05 起:日K定稿 → 复权因子 → ST/停牌/涨跌停 → 证券主数据 → 行业 → 公告/研报增量 | 每步写 checkpoint,失败从该步续 |
| 收盘日频链(港股) | 16:10 起同上 | |
| 收盘日频链(美股) | 次日 04:30(16:00 ET = 04:00/05:00 CST 次日,含夏令时表) | |
| 质量校验 QualityChecker | 每日各市场收盘链完成后 | 见 §7.5,产出 quality_reports + WS topic=ev.quality 事件 |
| 月度 compaction | 每月 1 号 07:00 | 合并上月 1m 日段(§3.1) |
| 新闻 NewsBridge | 常驻 collector + 每分钟窗口 | 见 §10.3 |
7.3 日频任务链的幂等模式
每个任务定义为 step(dataset, market, date):执行 = 以 (market, date) 为粒度 整分区替换(DuckDB DELETE+INSERT 同事务 / Parquet 重写 tmp 后 os.replace)。重跑任意次数结果一致 → 调度重试、手工 update --date 重放都安全。
盘中增量是另一条路径(评审 P1):交易时段内每 60–120s 只 os.replace 当日日段文件,不碰历史分区(天然幂等);「整分区 DELETE+重写」仅用于日频链与手工重放。各 symbol 当日段替换非原子 —— 读端短暂见「部分股新、部分股旧」可接受(旧段 = 略早快照、单调变新),跨股严格同刻不在 v1 承诺内。
7.4 断点与水位
etl_checkpoint.watermark 语义:bars_1m 存"最后完整交易日"(按日为粒度,不做分钟级水位——K线按日整段写,日粒度幂等最简单);公告/研报存 publish_ts 游标 + content hash:主键保持 id,改稿走 INSERT ... ON CONFLICT(id) DO UPDATE WHERE excluded.hash <> hash(同 id 改稿可进库);hash 只做内容比对,不与主键语义混用。
7.5 每日质检清单(假设 = 需求中截断的"每日对数据进行…")
| 检查 | 逻辑 | 失败动作 |
|---|---|---|
| 交易日 gap | 日历声明开盘但该日 0 行 | ev.quality critical + 自动重拉一次 |
| OHLC 合理性 | H≥max(O,C)、L≤min(O,C)、L≥0、volume≥0 | 隔离异常行到 quarantine 表,记 detail |
| 涨跌停越界 | close 相对昨收超出 stock_status 声明的 limit(新股/除权日豁免) | warning + 抽样人工 |
| 复权连续性 | adj_factor 单调性/跳变与 corp_actions 对账 | critical(错复权是最隐蔽的脏数据) |
| 行数环比 | 当日行数 vs 前 5 日中位数偏离 >30% | warning |
| 双源抽查 | 随机 1% symbol 的日K收盘价 tdx vs westock | 不一致记 report,连续 3 天同标的不一致升级 critical |
| 文件完整性 | compaction 后行数守恒、无孤立 tmp | 自动修复(重合并) |
7.6 执行模型(事件循环隔离 —— 评审 P0)
单进程里跑着调度器 + FastAPI + 用户脚本,事件循环是稀缺资源,硬约束三条:
- DuckDB 调用一律出循环:query/export/ETL 的 DuckDB 执行全部走专用线程池(
asyncio.to_thread/ 独立 executor),事件循环内只做编排与分发;查询超时 = 线程内connection.interrupt()真中断(asynciowait_for只放弃等待,同步调用仍会烧 CPU —— 由此解决); - scripts 任务宿主 = 线程池:
scripts/*.py是热加载的用户外部代码,同步阻塞不可接受 —— Scheduler 一律丢线程池执行,绝不作 loop 内协程直跑; - uvicorn 挂同一循环:用
Server(config).serve()协程方式挂入调度器所在 event loop(不用uvicorn.run()自建循环),WS 推送、调度 tick、状态机共用一个 loop 且全部非阻塞。
8. 对外服务协议(FastAPI:REST + WebSocket)
8.1 服务形态(serve 进程内,零外部依赖)
| 配置 / 参数 | 默认 | 行为 |
|---|---|---|
--host / http.host |
127.0.0.1 |
监听地址:默认仅本机(安全默认);0.0.0.0 开放内网访问 |
--port / http.port |
8765 |
监听端口 |
http.enabled(CLI 开关 --no-http) |
true |
两语义拆清:配置默认 true(起网关);--no-http 的作用 = 把 enabled 置 false(flag 本身默认不触发)。false = 纯 CLI 批处理,不起网关(本地 query/export 不受影响) |
http.token |
空 = 不校验 | 非空时 REST 带 Authorization: Bearer <token>;WS 优先握手 Header 同款,?token= 仅兼容降级(会进日志);非 loopback 且 token 空 → 拒绝启动(除非 --insecure,见 §8.4) |
实现分工(相对原 NATS 方案的变化):
- FastAPI + uvicorn 是 pyquantdata 的普通 pip 依赖,随包安装 —— 无二进制、无子进程、无外部服务,
bin/目录整个取消;- REST 与 WebSocket 挂在同一个 app 上,共享依赖注入(只读 DuckDB 连接池、进程内事件总线);
- Swagger UI 自带
/docs、OpenAPI 在/openapi.json—— 外部接入零文档成本(NATS 方案要自己维护 subject 文档);- 订阅语义:WS 连接即订阅(
topics过滤);推送发生在同进程内 —— Scheduler/QuotePoller 产出事件 → asyncio 广播到各 WS 连接,不经任何外部 broker;dbpath/scripts/只放抓取/更新任务脚本,与服务网关无关;- 背压与扇出(评审 P1):每 WS 连接一条有界队列(
ws_queue_len=256 帧) —— 快照类溢出丢最旧保最新、事件类超限直接断开该连接;全局连接数上限max_ws_conns=64;全市场快照帧序列化一次、N 连接共享同一 bytes(禁止 per-connection 重复json.dumps);队列深度纳入 §13 指标告警。
8.2 REST 端点 + WebSocket Topic 总表(前缀 /v1)
REST(请求-响应)
| 端点 | 方法 | 用途 |
|---|---|---|
/v1/query |
POST | query_sql:body {sql, params, fmt: arrow|json, max_rows, timeout_ms} → {columns, dtypes, b64_arrow 或 rows, row_count, elapsed_ms, truncated};fmt=arrow = Arrow IPC streaming format(JSON 内 base64,解码路径见附录 A) |
/v1/export |
POST | export:body {fmt, sql|dataset spec, opts, sync?} → 小导出(<100MB 或 sync=true)直接回文件流;大导出 → {job_id, state: queued|running|done|failed, path, rows, bytes} |
/v1/export/{job_id} |
GET | 导出任务状态/结果;下载 GET /v1/export/{job_id}/file(长任务进度同时走 WS ev.export) |
/v1/meta |
GET | 字典查询:日历、证券列表、view 列结构(每 view 附 row_count、min/max date、最新分区、3 个样例 symbol)、库版本 |
/v1/stats |
GET | 水位、磁盘、任务队列、质检摘要(status 命令的远程版) |
/v1/state/{market} |
GET | 当前市场状态(REST-only 客户端的对齐入口;WS 客户端收初帧即可) |
/healthz |
GET | Liveness:进程活着即 200(supervisord / 容器探针) |
/v1/ready |
GET | Readiness:写锁 / schema 版本 / 调度器 / 磁盘余量,异常 503 |
WebSocket /v1/stream?topics=…&market=cn&symbols=sh600000
| Topic | 节奏 | 用途 |
|---|---|---|
quote.snapshot |
每 3s | 全市场快照批 {ts, n, rows:[[sym,price,pct,vol,…列序号表]]}(列字典在 /v1/meta,批消息不重复带列名) |
quote.tick |
1s | 自选股逐笔/高频(symbols= 参数指定,服务端 watchlist 同步维护) |
state |
迁移时 | 市场状态迁移 {state, ts, next_at, reason};状态集见 §10.2 |
news.minute |
每 60s | 分钟新闻批 {window_start, items:[{id, ts, source, market, symbols, level, title, url}], count} |
flow.announce / flow.report |
增量 | 公告/研报增量(结构同新闻单条) |
ev.update |
事件 | ETL 进度/完成/失败 {dataset, step, date, rows, state} |
ev.quality |
每日 | 质检结果 {date, market, pass, fails:[…]} |
ev.export |
事件 | 导出任务进度 {job_id, state, rows, bytes} |
Envelope 统一首部(WS 帧):{v:1, msg_id, ts, producer:"quantdata/0.1", topic, payload…} —— 与日志事件同构;REST 响应不套 envelope,直接回 payload。ts 一律 ISO8601 UTC(带 Z),状态类 payload 另带 session_tz。
客户端模式(统一时序 —— 全文唯一定义,其它章节引用本段): ① WS 一连上,服务端必发初帧 = 当前
state+quote.snapshot(REST-only 客户端才用GET /v1/state/{market}对齐)→ 之后才是增量; ② 断线客户端自动重连,重连即重新收初帧,无需手动 GET; ③ 新闻/公告类 topic 断线期间不重放 —— 补偿走/v1/query按 ts 游标(SELECT * FROM news WHERE ts > ? ORDER BY ts)。重连三步 = 收初帧 → 按需 query 补偿 → 收流。
8.3 query_sql 安全约束(对外开 SQL 必须有闸)
- 只读 + 断网:DuckDB
read_only=true(serve 写连接与查询连接分离);SET autoinstall_known_extensions=false, autoload_known_extensions=false(堵 httpfs 自动加载出站); - 语句白名单(sqlglot):fail-closed(解析失败一律拒绝)、显式
dialect="duckdb"、按 AST 根节点判定(非字符串前缀)、parse_all长度必须 =1;拒绝 ATTACH/COPY/PRAGMA/多语句/DDL/DML;sqlglot 进 lock pin 版本,升级须过 SQL 闸回归测试(绕过样例:分号多语句、CTE 套 INSERT、EXPLAIN 变体、注释混淆 —— 全部入单测); - 函数/表函数白名单 —— 默认拒绝、显式放行(评审 P0):默认只放行纯计算函数 + 库内已注册视图;显式拒绝
read_csv/read_parquet/*_scan/glob等文件与网络表函数(否则SELECT read_csv('/etc/passwd')= 任意文件读、read_csv('http://169.254.169.254/…')= SSRF);sql.allow_functions语义 = 额外放行清单(不是「清空即全放行」的总开关); - 结果上限:默认
max_rows=1,000,000、Arrow 结果 ≤64MB,超限报错并提示改走export; - 超时与并发闸:超时默认 30s,查询在线程池执行、到点
connection.interrupt()真中断(§7.6);全局查询信号量默认 4(超出排队,等 >5s 返 429),查询连接设memory_limit—— 查询风暴不许饿死调度器; - 防御参数:
SET max_expression_depth等预设。
8.4 认证
- 默认只监听
127.0.0.1:本机可信,不设认证; - 启动强制校验(fail-fast):监听地址非
127.0.0.1/::1且http.token为空 → 拒绝启动;确要裸奔须显式--insecure,打醒目告警日志 —— 文字约定不算数(评审 P1); - 凭证传递:REST 用
Authorization: Bearer;WS 优先握手 Header 同款,?token=仅兼容降级;日志对 token 统一脱敏(只留前 4 位,uvicorn access log 同样处理,入测试断言); - WS 与 REST 共用同一鉴权中间件(含
ev.*topic,不给 WS 开旁路); - v1 不做多租户与细粒度权限(见 §1.2 非目标)。
9. 导出格式设计
| 格式 | 产物 | 细节 |
|---|---|---|
csv |
exports/{job}/XXX.csv |
按 symbol 分文件或单文件可选;ISO 日期、UTF-8 |
parquet |
单文件或按 symbol 分区目录 | 默认输出,qlib/backtrader 之外的一切下游首选 |
pandas |
不属于 export —— 归 /v1/query?fmt=arrow 消费端(b64_arrow → Arrow → DataFrame,10 行示例见附录 A) |
本地 CLI query --fmt pandas 同理;export 只管落盘格式(csv/parquet/qlib/backtrader) |
polars |
同 pandas(Arrow streaming 直吃) | 列类型映射在 meta 公布 |
backtrader |
exports/{job}/feather/{symbol}.feather(+ 可选 csv)+ loader.py |
用 bt.feathers.GenericPandasData 可直接吃的列(datetime/open/…/volume/openinterest,volume 补 0);loader 提供 load_feeds(spec) -> list[bt.feeds];复权可选(fq=qfq/hfq/none);1m feed 显式 timeframe=Minutes、fill_missing,datetime 列 tz-naive 交易所本地(§4.3 约定) |
qlib |
标准 qlib 数据目录:calendars/(day.bin, minute.bin, float32)、instruments/*.txt、features/{market}/{symbol}/{freq}/{field}.bin(float32 序列) |
实现方式=自写 dump_bin 兼容写入器(numpy tofile),运行时不依赖安装 qlib;测试两层(评审 P0):①核心 = 按 dump_bin 布局字节级/数值级读回断言(CI 必绿、不装 qlib);②qlib extra 可选集成 job(装 qlib 真跑 qlib.init(),单独标记不阻塞主链) |
Export 任务流:POST /v1/export 进来 → 校验 spec → 写 export_jobs → worker = 独立线程池(默认 2 并发 + 排队上限 8;只读连接从池独占获取,让路日频链) → 进度走 WS topic=ev.export + GET /v1/export/{job_id} 轮询 → 完成回 path;小导出(<100MB 或 sync=true)直接回文件流不建 job。job 结果按 spec hash 缓存 24h,重复导出直接回缓存路径。
路径安全(评审 P1):输出根恒为 exports/{job_id}/(job_id 服务端生成);请求带来的名称字段(symbol/目录段)白名单字符过滤 + resolve() 后必须仍在 exports/ 前缀内;opts 为显式字段枚举,禁止自由 path 键 —— 杜绝 ../ 穿出 dbpath 再经 /file 回读。
10. 实时与推流设计
10.1 行情 QuotePoller
- 源:cn 全市场快照 pywestockdata(<500ms 拉全量)或 pytdxdata quotes;us/hk 走 pytdxdata;
- 节奏:快照 3s 一批;watchlist(WS 连接参数
symbols=指定,默认指数+自选)1s tick; - 归一化:各源字段映射到统一列字典(§8.2),消息体只发列序号数组省带宽;
- 状态:非交易时段自动停poll(状态机驱动),WS 断线由客户端自动重连,重连即收服务端初帧(state + snapshot)——统一时序见 §8.2 客户端模式。
10.2 市场状态机 StateEngine
状态集(每市场一套):
CLOSED → PRE_OPEN_AUCTION → OPEN → LUNCH_BREAK → OPEN → CLOSED
(A股 09:15-09:25 集合竞价;港股 09:00-09:30;美股无午休、有盘后 AH 可扩展)
驱动:exchange.session_json(时段规则) + calendar(节假日) + 本地时钟 —— 纯本地确定性推导,
不依赖任何上游"开市通知",断网也准;夏令时用 zoneinfo 按年表算。
迁移才推消息;WS 客户端收初帧即得当前态,REST-only 客户端用 `GET /v1/state/{market}`(时序统一见 §8.2)。
10.3 分钟新闻 NewsBridge
news-integration collectors(RSS 等)→ 归一化(统一 NewsItem schema + hash 去重)
→ 60s 滚动窗口攒批 → WS `topic=news.minute`(一帧一批,不逐条发)
→ 同步落库 news 表(§4.1 DDL;断线补偿 = /v1/query 按 ts 游标补齐)
过滤:level(important/normal)、market 关联(关键词→symbol 映射表)、黑名单源。
11. 并发、锁与一致性
| 问题 | 方案 |
|---|---|
| 双实例写坏库 | quantdata.lock(PID + 进程 start time + boot_id 三元判活,防 PID 复用误判;发现陈旧锁先备份再接管并记日志)。后两项是「补强证据」而非判活前提 —— 任一取不到(权限 deny / psutil 缺失 / 非同一 boot)即视为不匹配、按时旧锁接管;判活 = PID 存活 且 三元全部可读且一致(DP-1 v0.7);serve/update/backfill/init 互斥,query/export 只读无需锁 |
| serve 写、CLI 查询并存 | DuckDB 单写多读跨进程成立;查询连接固定 read_only=true;Parquet 段文件不可变 + compaction 按 §3.1 两阶段 .trash 协议(月段先入位、日段延迟 unlink、查询竞态重试一次)消除丢段/重复窗口 |
| Windows 文件语义 | 一律 os.replace(同卷原子);tmp 与 data 同盘;启动时扫残留 tmp 清理 |
| 重复更新产生重复行 | 日粒度整分区替换(§7.3);1m 段文件按日期命名天然幂等(重写=同名覆盖) |
| 公告/研报重复抓取 | 主键 id + content hash:ON CONFLICT(id) DO UPDATE WHERE excluded.hash <> hash(改稿可进库,见 §7.4) |
| schema 演进 | schema_migrations 版本表,serve 启动自动升级(版本 > 代码已知最高版 → 报错退出,不带病跑;migration 包事务、失败回滚);视图 DDL 同步纳入 migration(§3.3);升级流程 = 停 serve → 备份 catalog.duckdb → 换包 → 启动 |
| 回填与 serve 抢锁 | 同一把锁:backfill 中途起 serve 会明确报错,不静默并发写 |
12. 配置文件(dbpath/config.json)
config.json 统一承载三类配置:抓取数据时间(
schedule默认值,可被scripts/各脚本 META 覆盖)、代理服务器(proxy全局 + per-source)、数据源要求(sources主备源、fetch限速/超时/重试)。
{
"version": 1,
"dbpath_created": "2026-09-23T10:40:00+08:00",
"markets": {
"cn": { "enabled": true, "history_from": "2004-01-01", "history_from_bars_1d": null },
"us": { "enabled": true, "history_from": "2020-01-01", "history_from_bars_1d": null },
"hk": { "enabled": true, "history_from": "2020-01-01", "history_from_bars_1d": null }
},
"categories": { "cn": ["index","stock","future","cbond","etf","reits","option"],
"us": ["index","stock","future","etf","reits"],
"hk": ["index","stock","future","etf","reits"] },
"sources": {
"bars": "tdx", "realtime": "westock", "reference": ["tdx","westock"],
"futures": ["tdx","yfinance"], "news": ["scripts/fetch_news.py"],
"fallback": ["akshare_port"],
"cross_check": true, "cross_check_ratio": 0.01
},
"proxy": { "global": "", "per_source": { "akshare_port": "http://127.0.0.1:7890", "yfinance": "" } },
"fetch": { "rate_limit_rps": { "akshare_port": 3, "yfinance": 2 }, "timeout_ms": 10000, "max_retry": 3 },
"http": {
"enabled": true,
"host": "127.0.0.1",
"port": 8765,
"token": "",
"max_ws_conns": 64,
"ws_queue_len": 256
},
"schedule": {
"timezone": "Asia/Shanghai",
"cn_intraday_interval_s": 90, "snapshot_interval_s": 3,
"daily_chain": { "cn": "15:05", "hk": "16:10", "us": "04:30" },
"compaction": "monthly"
},
"quality": { "enabled": true, "checks": ["gap","ohlc","limit","adj","rowcount","dualsource"] },
"sql": { "max_rows": 1000000, "timeout_ms": 30000, "max_arrow_bytes": 67108864, "max_concurrent": 4, "allow_functions": [] },
"export": { "out_dir": "exports", "cache_ttl_h": 24, "keep_days": 7, "formats": ["csv","parquet","qlib","backtrader"] },
"log": { "level": "INFO", "keep_days": 30 }
}
http.token支持${ENV}展开,不明文入库亦可;格式保持 JSON(你的约定)。sql.allow_functions= 额外放行清单(默认拒绝策略见 §8.3,清空 ≠ 放开表函数);export.keep_days:exports/ 按 job 保留天数,日频链自动清理;markets.*.history_from_bars_1d为 null 时跟随history_from(日K 可独立放宽,见 §3.4)。
13. 可观测性与运维
- 日志:
logs/serve-YYYYMMDD.jsonl(事件字段与 WS envelope 同构);token 脱敏(query 参数只留前 4 位,含 uvicorn access log); - 指标:进程内计数器(更新行数、延迟、HTTP 往返、WS 连接数、队列深度、磁盘余量),经
GET /v1/stats查询(v1 不引 Prometheus,接口留好);磁盘余量 <10% →ev.qualitywarning,<5% 硬阈值拒写(任务失败退避、不 crash loop);另给/healthz(liveness)与/v1/ready(readiness,锁/schema/调度器/磁盘); - 质检即看板:
status --json/quality_reports表 = 最近一次体检; - 备份:DuckDB 必须走只读连接(
ATTACH ... READ_ONLY/EXPORT DATABASE出快照)—— 热拷文件 = 损坏快照;Parquet 段不可变先 rsync;备份窗口内暂停 compaction(或备份后跑行数守恒校验 §7.5),防 rsync×os.replace 竞态拷到半套月段;v1 只给文档不给命令; - 部署(已确认 = Linux 服务器长期常驻):supervisord 加一个 program,常驻
quantdata serve(恒前台)+ stopwaitsecs=60(优雅退出预算 30s 的兜底);探针挂/healthz+/v1/ready;exports/清理由export.keep_days日频链执行;Windows 仅开发/临时使用(计划任务可选)。
14. 测试策略(对齐 100% 覆盖率要求)
| 层 | 手段 |
|---|---|
| 纯逻辑(状态机、调度、幂等分区、质检规则、SQL 闸) | pytest 单测,分支全覆盖 —— 全部设计成无网络纯函数/可注入时钟,是拿满覆盖率的关键 |
| 源适配层 | 录制 fixtures 回放(contract test)不打真网;另加故障注入:mock transport 编排错误序列(429→500→成功),fake clock 断言退避时序与重试上限,断言 checkpoint 半途失败后 resume 不重不漏;令牌桶用注入时钟做纯逻辑单测 |
| 存储层 | tmp_path 建迷你库:init→update→compact→query 全链路集成测试(含 compaction 两阶段协议的竞态注入) |
| 服务网关协议 | FastAPI TestClient/httpx:REST 往返、WS 推送、envelope 版本、token 鉴权(含日志脱敏断言)、断线重连初帧时序 |
| qlib/backtrader 导出 | 两层(评审 P0):①核心 = dump_bin 布局字节级/数值级读回断言(不装 qlib,CI 必绿)+ feather 喂 backtrader 跑一根 K 线;②qlib extra 可选集成 job(装 qlib 真 qlib.init(),单独标记) |
| 质检元测试 | golden 脏数据样本集:每类规则 ≥1 阳性 + 1 阴性 + 1 边界豁免(除权日涨跌停),断言 quality_reports 输出;「失败动作」回路(自动重拉/重合并)写回路测试;双源抽查固定随机种子保 CI 可复现 |
| CI | GitHub Actions(同 pytdxdata 模板):Linux+Windows 矩阵,--cov-fail-under=100 + 排除白名单(下表);--no-http 路径必绿,HTTP/WS 用 TestClient;[CI] 验收链用 CLI 起真 serve + 真端口 curl(覆盖 cli.serve → run_serve → Server.serve() 编排层),runtime.py 真 uvicorn/socket 段按白名单豁免(DP-2 v0.7);fastapi/uvicorn/sqlglot 全部 lock pin + Renovate 跟进,sqlglot 升级过 SQL 闸回归 |
async 测试策略(评审 P1):
- 调度器抽象
Clock/ticker接口,cron 判定写成纯函数 —— 参数化构造时间点测全部边界(夏令时切换日、时钟回拨跳槽); - pytest-asyncio 显式 mode;集成测试中调度器与 FastAPI app 共用同一事件循环(与 §7.6 执行模型一致),用可控 ticker 驱动「到点 → 写 checkpoint → WS 广播 ev.update」确定性链路;
- 线程池路径用同步 mock 断言「事件循环内零阻塞调用」。
验收数据两层(评审 P0 —— CI 跑不了真回填):
- [CI 层]:
init --skip-history+ 随仓库迷你 seed fixture(tests/fixtures/ci_seed_1d.parquet:2 symbols × 10 交易日日K,落到bars_1d;生成脚本build_ci_fixture.py固化,CI 先--check校验一致性)→ M1 链init → serve → POST /v1/query → export csvCI 必绿; - [夜间/发布层]:真数据回填与全量对齐,独立 workflow,不计入覆盖率、不阻塞 PR。
fixture 生命周期(评审 P1):每个 fixture 标注录制日期与源接口版本;nightly record job 打真网重录 + diff 报告(失败开 issue、不入必绿项);超 90 天未刷新在 CI 给 warning。
覆盖率排除白名单(评审 P0 —— 验收前一次拍板):
| 排除项 | 理由 | 替代验证 |
|---|---|---|
| uvicorn 真起服 / socket 层 | 平台相关、CI 不稳(本机踩过 socketpair 死锁) | 每周 smoke workflow + M1 交付自检:真 serve + 真端口 curl /healthz、/v1/ready、POST /v1/query、/v1/export、SQL 闸 400。CI 验收链的用户面同上(用 CLI 起真 serve + curl),仅 runtime.py 内 uvicorn/socket 段 pragma 豁免(DP-2 v0.7) |
| WS 多连接扇出 / 3s 节奏 | TestClient 只测单连接帧语义 | 冒烟脚本 4 连接收帧计数 |
| supervisord 模板 / Windows 计划任务 | 非 Python 代码 | 模板渲染单测 + 手工部署检查表(§15 [手工]) |
| 300GB 真数据导入路径 | 数据量不可进 CI | [夜间/发布层] workflow |
用户自定义 scripts/*.py 本体 |
运行时热加载的外部代码 | 核心只测加载器与 META 解析 |
15. 分阶段路线图
| 里程碑 | 交付物 | 验收标准 |
|---|---|---|
| M1 最小闭环 | CLI 骨架(init/serve/query/update/status)、目录规范、schema+migrations、A股证券信息+日历+日K、FastAPI + POST /v1/query、csv/parquet/pandas 导出 |
[CI] init --skip-history+迷你 seed → CLI 起真 serve → 真端口 POST /v1/query 查到日K → export csv 一条链必绿(含 SQL 闸 400 fail-closed 断言);单测覆盖核心逻辑 + --cov-fail-under=100 |
| M2 A股完整 | 1m 回填(seed 导入 + 断点续传)、compaction、除权/ST/停牌/涨跌停/申万行业、公告研报、每日质检、qlib+backtrader 导出、市场状态机 | A股数据矩阵全 ✅ [夜间];qlib extra job 实读 + backtrader 单测 [CI];质检连续 7 天绿 [手工] |
| M3 三市场+推流 | 美/港股日线+1m(时区调度)、快照/tick WS 推流、分钟新闻桥、token 鉴权开放内网、export 远端下载 | 三市场矩阵定稿;三市场 1m 回填完成度 ≥99% 交易日 [夜间];从另一台机器完成 query/订阅/导出全流程演练 [手工] |
| M4 运维加固 | 陈旧锁恢复、stats 完整化、备份文档、Linux supervisord 部署物(主)+ Windows 本机跑法(次)、README/协议文档、双源对账常态化、quantdata-client 薄 SDK + GET /v1/bars 糖(可选) |
连续运行 2 周无人工干预 [手工];doctor 全绿;覆盖率白名单复审 |
先 M1 跑通再谈后面的:每个里程碑都保持"能用的完整切片",不铺一次性大坑。 验收标签:
[CI]= GitHub Actions 必绿、计入 100% 覆盖率;[夜间]= 独立 workflow 不阻塞 PR;[手工]= 发布检查表签收项。100% 覆盖率只约束[CI]项(白名单见 §14)。
16. 评审决策记录(2026-09-23 已拍板)
| # | 问题 | 决策 | 落点 |
|---|---|---|---|
| 1 | "每日对数据进行…"截断 | ✅ 每日质量校验(gap/OHLC/涨跌停/复权对账/双源抽查 1%) | §1.3、§7.5 |
| 2 | 起始年限 / 磁盘 | ✅ cn=2004、us=2020、hk=2020;dbpath 落位由部署时 -d 指定(容量 §3.4,建议大盘) |
§1.3、§3.4 |
| 3 | 美股可转债/LOF 等品类 | ✅ 先放空,走可扩展结构(config+脚本+视图三步接入,核心零改动) | §1.3、§4.2 |
| 4 | 研报 / 申万行业数据源 | ✅ akshare 接口(研报 choices 等),摘抄源码 + primp 重写(不安装 akshare) | §1.3、§4.2、§5.2 |
| 5 | 实时行情精度 | ✅ 3 秒快照 + 自选 tick,不做逐笔 | §1.3、§10.1 |
| 6 | 对外服务协议 | ✅ v0.5 改判:放弃 NATS —— serve 进程内 FastAPI(REST + WebSocket 订阅),--no-http 纯 CLI;v0.4 的 servers/autostart/bin 设计作废 |
§1.3、§7.1、§8 |
| 7 | 部署目标 | ✅ Linux 服务器长期常驻(supervisord),Windows 仅开发用 | §1.3、§13、§15 |
| 8 | 跨市场 union 视图 | ✅ 加 bars_1m_all(market 列 + UNION ALL) |
§1.3、§3.3 |
| 9 | news-integration 批注归属 | 未另行指示 → 维持默认:采集逻辑迁入 dbpath/scripts/fetch_news.py |
§2、§3.1、附录B |
| 10 | v0.6 圆桌评审 45 条 | ✅ 全部采纳(6 席全票「修改后可实施」,P0×6 / P1×24 / P2×15):事件循环隔离、SQL 函数默认拒绝、compaction 两阶段、覆盖率白名单、验收两层、qlib 两层、news 表、复权口径、WS 时序统一、export 归位 | §7.6、§8.3、§3.1、§14 等 |
剩余风险(非阻塞):①akshare 类接口源站结构变动频繁,摘抄+primp 的移植代码需在质检中加 schema 漂移检测(列名/结构突变即告警),M2 跑通后观察两周;②按 ~600GB(数据 300–400GB + buffer ≥200GB)确认落位盘符。
附录 A:核心接口示例
# query —— REST 直接调
curl -s http://127.0.0.1:8765/v1/query -H 'Content-Type: application/json' \
-d '{"sql":"SELECT date, close FROM cn_stock_1d WHERE symbol=? ORDER BY date DESC LIMIT 5",
"params":["sh600000"],"fmt":"json"}'
→ {"columns":["date","close"],"dtypes":["date32","float64"],
"rows":[["2026-09-22",32.15],["2026-09-21",31.98]],"row_count":5,"elapsed_ms":12,"truncated":false}
// WebSocket 帧示例:ws://127.0.0.1:8765/v1/stream?topics=state,news.minute&market=cn
{"v":1,"msg_id":"...","topic":"state","payload":{"market":"cn","state":"LUNCH_BREAK",
"ts":"2026-09-23T03:30:00Z","next_at":"2026-09-23T05:00:00Z","session_tz":"Asia/Shanghai","reason":"session_rule"}}
{"v":1,"msg_id":"...","topic":"news.minute","payload":{"window_start":"2026-09-23T02:39:00Z","count":3,
"items":[{"id":"h1","ts":"...","source":"rss1","market":"cn","symbols":["sh600000"],
"level":"important","title":"...","url":"..."}]}}
附录 B:已有资产复用映射
| 已有项目 | 在 quantdata 中的角色 |
|---|---|
| pytdxdata(PyPI 0.6.0,三市场 K 线/行情/复权/tick) | 主数据源适配器(bars/realtime/ticks/futures/options) |
| pywestockdata(腾讯/东财 SDK,全市场 <500ms) | A股快照源 + 财务/分红/公告 + 日K双源对账 |
| stock_prediction 的 A股 1m(2004→今) | init --seed 直接导入,省 22 年回填 |
| market-event-driver(holidays.py / markets.py) | 日历与交易时段规则吸收为 exchange.session + 静态节假日表 |
| news-integration(RSS 统一采集器) | 采集逻辑迁入 dbpath/scripts/fetch_news.py,NewsBridge 消费其输出 |
| yfinance(参考源) | 美/港数据参考对账 |
| akshare 源码(只摘抄,不安装) | 研报(choices 等)、申万行业、长尾兜底:摘抄实现、请求层用 primp 重写过反爬 |
| nats-supervisor / event_center(三节点集群、TLS、supervisord 模板) | ❌ v0.5 起不再需要(NATS 已放弃);supervisord 部署模板仍可参考 |
| vxdata / factor-pipeline | 下游邻居:quantdata 只出干净原始数据,特征与因子归它们 |