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

733 lines
73 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](https://github.com/openbot-coder/pyquantdata/blob/main/README.md)。
**定位**:单目录自包含、三市场(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 摘要)
```sql
-- 参考数据 --------------------------------------------------------------
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 协议
```python
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 设计
```bash
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
# 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` 限速/超时/重试)。
```json
{
"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](https://github.com/openbot-coder/pyquantdata/blob/main/README.md) 为准。
| 里程碑 | 交付物 | 验收标准 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **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:核心接口示例
```bash
# 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}
```
```json
// 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 只出干净原始数据,特征与因子归它们 |