jackyu66gitandClaude Opus 4.6
21378c4f6d
Parquet + DuckDB storage with REST/WebSocket APIs for Chinese A-share market data. Supports 9 K-line frequencies with dual backend (East Money / Sina) and auto-fallback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
187 lines
5.4 KiB
Markdown
187 lines
5.4 KiB
Markdown
# A-Share Data Platform
|
||
|
||
A股全量数据服务 — Parquet + DuckDB 存储，REST + WebSocket 双协议。
|
||
|
||
## 支持的 K 线周期
|
||
|
||
| 周期 | 代码 | 数据范围 | 来源 |
|
||
|------|------|----------|------|
|
||
| 1 分钟 | `1m` | 近 1-3 月（需每日盘后积累） | AKShare |
|
||
| 5 分钟 | `5m` | 同上 | AKShare |
|
||
| 15 分钟 | `15m` | 同上 | AKShare |
|
||
| 30 分钟 | `30m` | 同上 | AKShare |
|
||
| 1 小时 | `1h` | 同上 | AKShare |
|
||
| 2 小时 | `2h` | 从 `1h` 实时推导 | DuckDB |
|
||
| 日线 | `1d` | 全部历史（1990 年起） | AKShare |
|
||
| 周线 | `1w` | 从日线推导 | DuckDB |
|
||
| 月线 | `1M` | 从日线推导 | DuckDB |
|
||
|
||
分钟线数据受限于上游 API 只保留近 1-3 个月，必须通过**每日盘后自动拉取**持续积累。日线/周线/月线可随时回填全部历史。
|
||
|
||
## 架构
|
||
|
||
```
|
||
AKShare (East Money / Sina)
|
||
→ AKShareClient (dual backend, auto-fallback)
|
||
→ BackfillPipeline / EODPipeline
|
||
→ Parquet (Hive-partitioned, Zstd compressed)
|
||
→ DuckDB (metadata + read_parquet queries)
|
||
→ FastAPI (REST + WebSocket)
|
||
```
|
||
|
||
- **存储**: Parquet 列存（Zstd 压缩 ~80%），Hive 分区 `year=YYYY/month=MM/day=DD/data.parquet`
|
||
- **查询**: DuckDB 内嵌 OLAP，`read_parquet()` 直接读取，支持分区裁剪和谓词下推
|
||
- **数据源**: AKShare 封装，双后端自动切换（East Money 国内优先，Sina 全球可访问）
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
### 配置
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 按需调整参数
|
||
```
|
||
|
||
### 初始化数据库 + 导入股票列表
|
||
|
||
```bash
|
||
ashare-dp backfill init
|
||
```
|
||
|
||
### 回填历史数据
|
||
|
||
```bash
|
||
# 回填全部日线/周线/月线
|
||
ashare-dp backfill daily --workers 10
|
||
|
||
# 回填指定股票指定日期范围
|
||
ashare-dp backfill daily --start 2025-01-01 --end 2026-05-16 --symbols 000001,600000
|
||
|
||
# 回填近 30 天分钟数据
|
||
ashare-dp backfill minute --days 30 --workers 5
|
||
```
|
||
|
||
### 启动 API 服务
|
||
|
||
```bash
|
||
ashare-dp serve start --port 8000
|
||
```
|
||
|
||
启动后访问 `http://localhost:8000/` 查看文档，`http://localhost:8000/docs` 查看 Swagger。
|
||
|
||
### 命令行查询
|
||
|
||
```bash
|
||
ashare-dp query kline 1d 000001.SZ --start 2026-01-01
|
||
ashare-dp query latest --freq 1d --ts-code 000001.SZ
|
||
ashare-dp query stats
|
||
ashare-dp query stocks --exchange SH
|
||
```
|
||
|
||
## API 端点
|
||
|
||
所有 REST 端点前缀 `/api/v1`。
|
||
|
||
### 股票查询
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/stocks` | 分页列表，可按交易所/板块筛选 |
|
||
| GET | `/stocks/search?q=平安` | 名称/代码模糊搜索 |
|
||
| GET | `/stocks/{ts_code}` | 单只股票详情 |
|
||
|
||
### K 线查询
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/klines/{freq}?ts_code=&start_date=&end_date=` | 单只 K 线查询 |
|
||
| POST | `/klines/{freq}/batch` | 批量 K 线查询 |
|
||
| GET | `/klines/{freq}/latest?ts_code=` | 最新交易日数据 |
|
||
| GET | `/klines/available-freqs` | 支持的频率列表 |
|
||
|
||
### 实时行情
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/realtime/spot?codes=000001.SZ,600000.SH` | 实时快照 |
|
||
| GET | `/realtime/market-state` | 市场状态 |
|
||
|
||
### 交易日历
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/calendar/trading-days?start=&end=` | 区间内交易日 |
|
||
| GET | `/calendar/is-trading-day?date=` | 判断交易日 |
|
||
| GET | `/calendar/next-trading-day?date=` | 下一个交易日 |
|
||
|
||
### WebSocket
|
||
|
||
```
|
||
ws://localhost:8000/ws/realtime
|
||
```
|
||
|
||
交易时段每 5 秒推送订阅股票的实时行情。连接后发送 JSON 控制消息：
|
||
|
||
```json
|
||
{"action": "subscribe", "codes": ["000001.SZ", "600519.SH"]}
|
||
{"action": "unsubscribe", "codes": ["000001.SZ"]}
|
||
{"action": "unsubscribe_all"}
|
||
```
|
||
|
||
### 其他
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/health` | 健康检查 |
|
||
| GET | `/stats` | 数据库统计（各周期记录数、日期范围） |
|
||
|
||
## CLI 命令
|
||
|
||
```
|
||
ashare-dp version # 显示版本
|
||
ashare-dp backfill init # 初始化数据库
|
||
ashare-dp backfill daily [...] # 回填日线/周线/月线
|
||
ashare-dp backfill minute [...] # 回填分钟线
|
||
ashare-dp serve start [...] # 启动 API 服务
|
||
ashare-dp query kline ... # 查询 K 线
|
||
ashare-dp query latest ... # 最新数据
|
||
ashare-dp query stocks ... # 股票列表
|
||
ashare-dp query stats # 数据统计
|
||
```
|
||
|
||
## 配置参数
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `DATA_DIR` | `data` | 数据目录 |
|
||
| `DUCKDB_PATH` | `data/duckdb/ashare.db` | DuckDB 文件路径 |
|
||
| `API_HOST` | `0.0.0.0` | API 绑定地址 |
|
||
| `API_PORT` | `8000` | API 绑定端口 |
|
||
| `BACKFILL_WORKERS` | `10` | 回填并发线程数 |
|
||
| `AKSHARE_MAX_RETRIES` | `3` | API 调用重试次数 |
|
||
| `AKSHARE_RETRY_DELAY` | `1.0` | 重试基础延迟（指数退避） |
|
||
| `AKSHARE_BACKEND` | `auto` | 数据后端: `auto`, `em` (East Money), `sina` |
|
||
| `REALTIME_POLL_INTERVAL` | `5` | 实时行情轮询间隔（秒） |
|
||
| `LOG_LEVEL` | `INFO` | 日志级别 |
|
||
|
||
## 部署说明
|
||
|
||
- **国内服务器**: 配置 `AKSHARE_BACKEND=em` 使用 East Money 后端（数据质量更好）
|
||
- **海外服务器**: 保持 `auto`，客户端会自动检测并降级到 Sina 后端
|
||
- **分钟线积累**: 盘后拉取任务（15:05 北京时间）必须稳定运行，否则分钟线历史会出现缺口
|
||
- **存储估算**: 约 12 GB / ~3,300 文件（全部历史 + 所有频率），建议 SSD
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
pip install -e ".[dev]"
|
||
pytest
|
||
ruff check src/
|
||
```
|