Files
pyquantdata/docs/quantdata-design.md
T
openbot 96d1e0ccef chore: bump 0.1.1(arrow 落盘修复 + README 全量补全随版发布)
pyproject/__init__/uv.lock 三处版本对齐 0.1.1;README 当前版本与
安装示例同步,设计文档实现状态补 0.1.1 记录。255 passed / 100%。
2026-09-29 08:40:06 +08:00

73 KiB
Raw Permalink Blame History

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,视图名≠物理表名)。
实现状态:2026-09-24 M1 已交付,发布 PyPI pyquantdata==0.1.0(254 测试 100% 覆盖、CI 双平台真起服验收链绿、release.yml OIDC 自动发布)。2026-09-29 升 0.1.1(修复 query --fmt arrow -o 落盘崩溃 + README 全量补全已实现功能,255 测试 100%)。落地明细与功能清单见 §15 实现状态附记及 README。
定位:单目录自包含、三市场(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 目标(来自需求)

  1. 初始化:quantdata init -d /xxx/dbpath/ —— 自动建目录结构、建元数据库、按配置回填各市场历史数据,断点可续。
  2. 日常更新:quantdata serve -d /xxx/dbpath/ —— 常驻进程:盘中增量更新、收盘后日频任务、每日数据质量校验,并常驻对外服务。
  3. 对外服务(HTTP + WebSocket):
    • query_sql:执行 SQL 查询(请求/响应);
    • export:导出 backtrader / qlib / pandas / polars / csv 等格式;
    • 订阅:股票实时行情、市场状态变化(开盘/收盘/午休等)、分钟级新闻推流。
  4. 数据范围:A股(指数、股票、期货、可转债、ETF/LOF、REITS、期权的证券信息、交易日历、1m K、日K、除权除息、公告、研报、申万行业、ST、停牌、涨跌停);美股、港股(指数、股票、期货、ETF/LOF、REITS 等证券信息、交易日历、1m K、日K)。
  5. 对外服务协议:默认 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 + 用户脚本,事件循环是稀缺资源,硬约束三条:

  1. DuckDB 调用一律出循环:query/export/ETL 的 DuckDB 执行全部走专用线程池(asyncio.to_thread / 独立 executor),事件循环内只做编排与分发;查询超时 = 线程内 connection.interrupt() 真中断(asyncio wait_for 只放弃等待,同步调用仍会烧 CPU —— 由此解决);
  2. scripts 任务宿主 = 线程池:scripts/*.py 是热加载的用户外部代码,同步阻塞不可接受 —— Scheduler 一律丢线程池执行,绝不作 loop 内协程直跑;
  3. 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 必须有闸)

  1. 只读 + 断网:DuckDB read_only=true(serve 写连接与查询连接分离);SET autoinstall_known_extensions=false, autoload_known_extensions=false(堵 httpfs 自动加载出站);
  2. 语句白名单(sqlglot):fail-closed(解析失败一律拒绝)、显式 dialect="duckdb"、按 AST 根节点判定(非字符串前缀)、parse_all 长度必须 =1;拒绝 ATTACH/COPY/PRAGMA/多语句/DDL/DML;sqlglot 进 lock pin 版本,升级须过 SQL 闸回归测试(绕过样例:分号多语句、CTE 套 INSERT、EXPLAIN 变体、注释混淆 —— 全部入单测);
  3. 函数/表函数白名单 —— 默认拒绝、显式放行(评审 P0):默认只放行纯计算函数 + 库内已注册视图;显式拒绝 read_csv / read_parquet / *_scan / glob 等文件与网络表函数(否则 SELECT read_csv('/etc/passwd') = 任意文件读、read_csv('http://169.254.169.254/…') = SSRF);sql.allow_functions 语义 = 额外放行清单(不是「清空即全放行」的总开关);
  4. 结果上限:默认 max_rows=1,000,000、Arrow 结果 ≤64MB,超限报错并提示改走 export;
  5. 超时与并发闸:超时默认 30s,查询在线程池执行、到点 connection.interrupt() 真中断(§7.6);全局查询信号量默认 4(超出排队,等 >5s 返 429),查询连接设 memory_limit —— 查询风暴不许饿死调度器;
  6. 防御参数: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.quality warning,<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 csv CI 必绿;
  • [夜间/发布层]:真数据回填与全量对齐,独立 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. 分阶段路线图

实现状态(2026-09-24 更新):M1 已交付并发布 PyPI pyquantdata==0.1.0(GitHub Actions release.yml 自动构建 + OIDC Trusted Publishing)。落地对照:CLI 六命令(init/serve/update/query/export/status,比原计划多出 export 与 status 独立命令)、14 业务表 + 8 联邦视图、REST 8 端点(原计划的 query/export 外,meta/stats/state/ready/export-job 均已实现)、Bearer 鉴权、SQL 闸本地/HTTP 同规则、254 测试 100% 覆盖率、CI 双平台真起服验收链。M1 未含(对应下方 M2–M4):backfill/doctor 命令、1m 数据、美/港实际写入、WS 推流。功能清单以 README 为准。

里程碑 交付物 验收标准
M1 最小闭环 ✅ 已交付(v0.1.0) 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 —— 达成:254 passed / 100% / CI 双平台绿
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 只出干净原始数据,特征与因子归它们