docs: README 重写补全 0.1.0 已实现功能 + 设计文档实现状态标注

README(PyPI 页面同源):徽章、CLI 六命令参数表、REST 8 端点含鉴权、
14 表 + 8 视图清单、dbpath 布局、config 段说明、pandas/polars 两种接入
(CLI IPC file / HTTP b64_arrow streaming)、安全约束、M1 未含清单。
设计文档:头部 + §15 标注 M1 已交付 v0.1.0 与落地对照。
相对链接=0(PyPI 规则)。
This commit is contained in:
openbot committed 2026-09-28 15:34:50 +08:00
1 parent b5f0ae3204
commit 10af5c98ce
2 files changed
+141 -39

No files matched your search

+137 -38
View File
@@ -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 <parquet/csv>`、`--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 <file>`(文件格式必填) | 本地只读直查,纯 stdout JSON 可直接 `\| jq` |
| `export` | `--sql <SQL>`、`--fmt csv\|parquet`、`-o <file>`(必填) | 落盘导出 |
| `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>`(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)
```
<dbpath>/
├── 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