diff --git a/README.md b/README.md index 52e21ec..3dc5a46 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,33 @@ # pyquantdata(CLI 名 `quantdata`) -单目录自包含、三市场(A/美/港)覆盖的量化数据中台:`init` 建库回填,`serve` 常驻更新 + FastAPI 对外服务,一切状态收敛在 `-d` 指定的 dbpath。 +[![PyPI](https://img.shields.io/pypi/v/pyquantdata)](https://pypi.org/project/pyquantdata/) +[![CI](https://github.com/openbot-coder/pyquantdata/actions/workflows/ci.yml/badge.svg)](https://github.com/openbot-coder/pyquantdata/actions/workflows/ci.yml) +[![Python](https://img.shields.io/pypi/pyversions/pyquantdata)](https://pypi.org/project/pyquantdata/) +[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/openbot-coder/pyquantdata/blob/main/LICENSE) -设计方案见 [docs/quantdata-design.md](https://github.com/openbot-coder/pyquantdata/blob/main/docs/quantdata-design.md)(v0.7,圆桌评审 45 条已采纳)。 +单目录自包含的量化数据中台:`init` 建库,`update` 回填,`query`/`export` 只读消费,`serve` 常驻 + FastAPI 对外服务——一切状态收敛在 `-d` 指定的 dbpath,可整体拷贝/备份。 -## 当前状态:M1 最小闭环 +**当前版本 0.1.0(M1 最小闭环)**,已发布 [PyPI](https://pypi.org/project/pyquantdata/)。设计方案见 [docs/quantdata-design.md](https://github.com/openbot-coder/pyquantdata/blob/main/docs/quantdata-design.md)(v0.7,圆桌评审 45 条已采纳)。 + +## 已实现功能(0.1.0) | 能力 | 说明 | |---|---| -| `init` | 建目录 + config.json + DuckDB schema(migrations:14 表 + 8 联邦视图)+ seed 导入 + 自检;`--estimate` 只算磁盘预算 | -| `serve` | 单写者锁(PID 三元判活)+ FastAPI 网关,恒前台常驻 | -| `update` | A股证券 / 交易日历 / 日K(主源 pytdxdata),整区替换幂等 | -| `query` | 本地只读直查(不开服务也可用),`--fmt table\|json\|csv\|parquet\|arrow` | +| `init` | 建目录 + config.json + DuckDB schema(**14 业务表 + 8 联邦视图**,migrations 版本化)+ seed 导入 + 自检;`--estimate` 只算磁盘预算不写库;幂等(重跑=续跑) | +| `serve` | 单写者锁(PID 三元判活)+ FastAPI 网关恒前台常驻;`--no-http` 纯批处理模式 | +| `update` | A股证券 / 交易日历 / 日K 三数据集(主源 pytdxdata),整区替换幂等、checkpoint 水位、重跑安全 | +| `query` | 本地只读直查(**不开服务也可用**,与 HTTP 同一套 SQL 闸);`--fmt table\|json\|csv\|parquet\|arrow` | | `export` | csv / parquet 落盘(恒 `exports/{job_id}/`,路径双判防穿越) | -| `status` | 水位 / 锁 / HTTP / 磁盘,`--json` 结构化输出 | - -**安全约束**(设计 §8.3 / §8.4): - -- SQL 闸 **fail-closed**:sqlglot 解析、根节点白名单、多语句拒绝、文件/网络表函数默认拒绝(`SELECT read_csv('/etc/passwd')` → 400); -- 查询走线程池,超时 = `connection.interrupt()` 真中断 → 504;并发信号量 4,超出排队 429; -- 只读连接断扩展自动加载(堵 httpfs 出站)+ `memory_limit`; -- 非 loopback 且 token 为空 → 拒绝启动(`--insecure` 显式放行)。 +| `status` | 水位 checkpoint / 锁 / schema 版本 / 磁盘占用,`--json` 结构化输出 | +| REST API | 8 端点:查询、导出、元数据、水位统计、市场状态机、liveness/readiness 探针 | +| 安全闸 | SQL fail-closed + Bearer 鉴权 + 非 loopback 无 token 拒绝启动 + 只读连接断扩展/限内存 | ## 安装 ```bash -uv sync # 开发安装(含 dev 依赖) -# 或 -uv pip install pyquantdata # PyPI 安装(发布后) +uv pip install pyquantdata # PyPI(0.1.0) +# 或开发模式 +git clone git@github.com:openbot-coder/pyquantdata.git && cd pyquantdata && uv sync ``` Python `>=3.11,<3.14`(3.14 在 Windows 上 asyncio socketpair 死锁,已排除)。 @@ -35,36 +35,133 @@ Python `>=3.11,<3.14`(3.14 在 Windows 上 asyncio socketpair 死锁,已排 ## 快速开始 ```bash -# 1. 建库(离线迷你 seed 演示;真实回填去掉 --skip-history) -uv run quantdata init -d tmp-db --skip-history --seed tests/fixtures/ci_seed_1d.parquet +# 1. 建库(离线迷你 seed 演示;真实回填去掉 --skip-history、接 --seed 或跑 update) +quantdata init -d tmp-db --skip-history --seed tests/fixtures/ci_seed_1d.parquet -# 2. 本地直查 -uv run quantdata query -d tmp-db "SELECT date, close FROM cn_stock_1d ORDER BY date DESC LIMIT 5" +# 2. 本地直查(不开服务) +quantdata query -d tmp-db "SELECT date, close FROM cn_stock_1d ORDER BY date DESC LIMIT 5" # 3. 起服务(默认 127.0.0.1:8765) -uv run quantdata serve -d tmp-db +quantdata serve -d tmp-db ``` ```bash -curl -s localhost:8765/healthz # {"status":"ok"} -curl -s localhost:8765/v1/ready # readiness:catalog/schema/磁盘 +curl -s localhost:8765/healthz # {"status":"ok"}(免鉴权) +curl -s localhost:8765/v1/ready # readiness:catalog/schema/磁盘(免鉴权) +curl -s localhost:8765/v1/meta -H "Authorization: Bearer $TOKEN" curl -s -X POST localhost:8765/v1/query \ - -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ -d '{"sql":"SELECT count(*) FROM cn_stock_1d"}' ``` -### REST 端点(前缀 `/v1`) +## CLI 命令参考 -| 端点 | 方法 | 用途 | +所有命令支持 `-d/--dbpath`(或环境变量 `QUANTDATA_HOME`)指定库目录。 + +| 命令 | 关键参数 | 说明 | |---|---|---| -| `/v1/query` | POST | `{sql, params, fmt: json\|arrow}` → 结果(arrow = Arrow IPC base64,pandas/polars 直吃) | -| `/v1/export` | POST | `{sql, fmt: csv\|parquet, filename}` → 文件流 + `exports/{job_id}/` 落盘 | -| `/v1/export/{job_id}` | GET | 导出任务状态 | -| `/v1/meta` / `/v1/stats` | GET | 字典结构 / 水位磁盘统计 | -| `/v1/state/{market}` | GET | 市场状态机(CLOSED/OPEN/LUNCH_BREAK…) | -| `/healthz` `/v1/ready` | GET | liveness / readiness 探针 | +| `init` | `--markets cn,us,hk`、`--seed `、`--skip-history`、`--estimate` | 建目录 + config + schema + seed 导入 + 自检 | +| `serve` | `--host`、`--port`、`--no-http`、`--insecure` | 单写者锁 + 网关,恒前台(Linux 交 supervisord) | +| `update` | `--dataset securities,calendar,bars_1d\|all`、`--market cn`、`--symbols sh600000,...`、`--start/--end` | 单次更新(cron 兜底),主源 pytdxdata,幂等 | +| `query` | `--fmt table\|json\|csv\|parquet\|arrow`、`-o `(文件格式必填) | 本地只读直查,纯 stdout JSON 可直接 `\| jq` | +| `export` | `--sql `、`--fmt csv\|parquet`、`-o `(必填) | 落盘导出 | +| `status` | `--json` | 水位 / 锁 / schema 版本 / 磁盘 | -Swagger UI:起服后访问 `http://127.0.0.1:8765/docs`(OpenAPI 免费得)。 +### 接 pandas / polars + +```bash +# 方式一:CLI 导出 Arrow IPC file 格式(footer 完整,可随机重开) +quantdata query -d tmp-db --fmt arrow -o out.arrow "SELECT * FROM cn_stock_1d" +``` + +```python +import polars as pl +df = pl.read_ipc("out.arrow") # 或 pyarrow.ipc.open_file("out.arrow").read_all() +``` + +```python +# 方式二:HTTP 拿 Arrow IPC **streaming** 格式 base64(字段名 b64_arrow) +import base64, json, urllib.request, pyarrow as pa +req = urllib.request.Request( + "http://127.0.0.1:8765/v1/query", + data=json.dumps({"sql": "SELECT * FROM cn_stock_1d", "fmt": "arrow"}).encode(), + headers={"Content-Type": "application/json", "Authorization": f"Bearer {TOKEN}"}, +) +b64 = json.load(urllib.request.urlopen(req))["b64_arrow"] +tbl = pa.ipc.open_stream(pa.py_buffer(base64.b64decode(b64))).read_all() +df = tbl.to_pandas() # polars: pl.from_arrow(tbl) +``` + +## REST API(前缀 `/v1`) + +| 端点 | 方法 | 鉴权 | 用途 | +|---|---|---|---| +| `/healthz` | GET | 免 | liveness 探针 | +| `/v1/ready` | GET | 免 | readiness:catalog / schema / 磁盘 | +| `/v1/query` | POST | Bearer | `{sql, params, fmt: json\|arrow, max_rows, timeout_ms}` → 结果;arrow 时字段为 `b64_arrow` | +| `/v1/export` | POST | Bearer | `{sql, fmt: csv\|parquet, filename, params, sync}` → 文件流 + 落盘 | +| `/v1/export/{job_id}` | GET | Bearer | 导出任务状态 | +| `/v1/meta` | GET | Bearer | 字典结构(表/列/视图) | +| `/v1/stats` | GET | Bearer | 水位 / 磁盘统计 | +| `/v1/state/{market}` | GET | Bearer | 市场状态机(CLOSED / OPEN / LUNCH_BREAK…) | + +- 鉴权:`Authorization: Bearer `(token 在 dbpath/`config.json` 的 `http.token`,支持 `${ENV}` 展开),缺失或错误 → 401。 +- Swagger UI:起服后访问 `http://127.0.0.1:8765/docs`(OpenAPI 免费得)。 +- 并发:查询走线程池,超时 = `connection.interrupt()` 真中断 → 504;信号量 4,超出排队 → 429。 + +## 数据模型(init 产物) + +**14 张业务表**(+ `schema_migrations` 版本表): + +| 分类 | 表 | +|---|---| +| 行情 | `bars_1d`(日K 物理表) | +| 参考数据 | `securities`、`calendar`、`exchanges`、`sw_industry`、`stock_status` | +| 公司行动 | `corp_actions`、`announcements` | +| 资讯/其它 | `news`、`reports`、`futures_meta` | +| 运维 | `etl_checkpoint`(水位)、`quality_reports`(质检)、`export_jobs`(导出任务) | + +**8 个联邦视图**(SQL 透明层,直接查视图名即可,无需关心物理表): + +| 市场 | 视图 | +|---|---| +| A股 | `cn_stock_1d`、`cn_index_1d`、`cn_etf_1d`、`cn_cbond_1d` | +| 美股 | `us_stock_1d`、`us_index_1d` | +| 港股 | `hk_stock_1d`、`hk_index_1d` | + +> M1 视图仅覆盖日K;1 分钟级与其它数据范围属 M2(设计 §4.2/§3.3)。 + +## dbpath 目录布局(§3.1) + +``` +/ +├── config.json # 配置(JSON、extra=forbid、${ENV} 展开) +├── catalog.duckdb # 元数据 + 数据(单文件可拷贝) +├── quantdata.lock # 单写者锁(PID + start_time + boot_id 三元判活) +├── data/ # 数据文件(parquet 分区) +├── exports/{job_id}/ # 导出落盘(恒在此前缀内,防穿越) +├── scripts/ # 用户脚本 +└── logs/ # 日志 +``` + +## 配置(dbpath/config.json) + +`init` 自动生成,`extra=forbid` 严格校验,字符串支持 `${ENV}` 展开。主要段: + +| 段 | 字段(节选) | +|---|---| +| `markets` | 每市场 `enabled` / `history_from`(cn 默认 2004-01-01,us/hk 2020-01-01) | +| `http` | `host` / `port`(默认 127.0.0.1:8765)/ `token` / `max_ws_conns` / `ws_queue_len` | +| `etl` | `bars` / `realtime` / `reference` / `news` / `fallback` / `cross_check` 等源开关 | +| `rate_limit` | `global` / `per_source` / `rate_limit_rps` | + +## 安全约束(设计 §8.3 / §8.4) + +- **SQL 闸 fail-closed**:sqlglot 解析 → 根节点白名单(仅 SELECT)→ 多语句拒绝 → 文件/网络表函数默认拒绝(`SELECT read_csv('/etc/passwd')` → 400);**本地 CLI 与 HTTP 同一套规则**。 +- 只读连接:禁扩展自动加载(堵 httpfs 出站)+ `memory_limit`。 +- **非 loopback 且 token 为空 → 拒绝启动**(`--insecure` 显式放行)。 +- 导出路径安全:输出恒 `exports/{job_id}/`,文件名白名单 + resolve 前缀双校验,杜绝 `../` 穿出 dbpath(符号链接兜底)。 +- 单写者锁:`serve` 独占写锁,PID + start_time + boot_id 三元判活,防误杀/误接管。 ## 测试与验收 @@ -76,7 +173,7 @@ uv run pytest --cov=pyquantdata --cov-report=term-missing --cov-fail-under=100 uv run python scripts/smoke_m1.py ``` -CI(GitHub Actions):Linux + Windows 矩阵 → lint → 覆盖率门禁 → fixture 一致性校验 → **真起服验收链**(init → serve → query → export → SQL 闸 400 → 端口释放)。 +**254 测试 / 100% 覆盖率**。CI(GitHub Actions)Linux + Windows 矩阵:lint → 覆盖率门禁 → fixture 一致性校验(`build_ci_fixture.py --check`)→ **真起服验收链**(init → serve → query → export → SQL 闸 400 → 停服端口释放断言)。 ## 项目结构 @@ -96,11 +193,13 @@ src/pyquantdata/ ## 路线图(设计 §15) -- **M1 ✅** 最小闭环(本仓库当前状态) +- **M1 ✅** 最小闭环(本仓库当前状态,v0.1.0) - **M2** 1m 回填 + compaction + 除权/ST/涨跌停 + 每日质检 + qlib/backtrader 导出 -- **M3** 美/港三市场 + WS 推流(快照/状态/新闻) +- **M3** 美/港三市场实际回填 + WS 推流(快照/状态/新闻) - **M4** 运维加固(supervisord 部署、doctor、薄 SDK) +> M1 明确未含:历史回填调度(`backfill`)、`doctor` 自愈、1 分钟 K 线、美/港数据实际写入(表与视图已建,`update` 主源为 A 股 pytdxdata)、WebSocket 推流。 + ## License MIT diff --git a/docs/quantdata-design.md b/docs/quantdata-design.md index 1bcfffc..bc4f523 100644 --- a/docs/quantdata-design.md +++ b/docs/quantdata-design.md @@ -8,6 +8,7 @@ **修订**: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 自动发布)。落地明细与功能清单见 §15 实现状态附记及 [README](https://github.com/openbot-coder/pyquantdata/blob/main/README.md)。 **定位**:单目录自包含、三市场(A/美/港)覆盖的量化数据中台 —— `init` 建库回填,`serve` 常驻更新 + 每日质检 + 通过 FastAPI(REST+WebSocket)对外服务。 --- @@ -662,9 +663,11 @@ news-integration collectors(RSS 等)→ 归一化(统一 NewsItem schema + ## 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 最小闭环** | 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` | +| **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` 全绿;覆盖率白名单复审 |