51 lines
2.0 KiB
Markdown
51 lines
2.0 KiB
Markdown
# Python sidecar 与 DuckDB 存储设计
|
||
|
||
## 目标
|
||
|
||
提供一个统一的数据获取和缓存接口，屏蔽 mootdx 与腾讯财经的字段差异，后续本地策略只依赖 `UnifiedDataService` 或 HTTP 接口，不直接访问外部数据源。
|
||
|
||
## 模块结构
|
||
|
||
- `sidecar/api.py`：FastAPI HTTP 接口，提供 `/health`、`/kline/{symbol}`、`/snapshot/{symbol}`。
|
||
- `sidecar/service.py`：统一数据服务，负责缓存命中、远端拉取、数据源降级。
|
||
- `sidecar/storage.py`：DuckDB 仓储，维护 `md.kline_bars` 与 `md.snapshots`。
|
||
- `sidecar/sources/mootdx_source.py`：mootdx 适配器，负责 K 线与备用快照。
|
||
- `sidecar/sources/tencent.py`：腾讯财经适配器，负责估值字段更完整的实时快照。
|
||
- `sidecar/models.py`：统一 K 线与快照模型。
|
||
|
||
## 数据源策略
|
||
|
||
- K 线：默认使用 mootdx，支持 `day/week/month/1m/5m/15m/30m/60m`。
|
||
- 快照：默认优先腾讯财经，失败后回退 mootdx。
|
||
- 腾讯财经字段校准：`39=PE_TTM`、`46=PB`、`52=PE 静态`，`43` 是振幅，不作为 PB 使用。
|
||
|
||
## DuckDB 缓存
|
||
|
||
- `md.kline_bars`：按 `symbol + period + trade_date` 覆盖写入，读取时返回最近 N 条并按交易日升序排列。
|
||
- `md.snapshots`：每个 `symbol` 只保留一条快照，使用 `expires_at` 控制短 TTL 缓存。
|
||
- 默认数据库路径为 `data/tortoise.duckdb`，可通过 `TORTOISE_DUCKDB_PATH` 配置。
|
||
|
||
## Python 调用示例
|
||
|
||
```python
|
||
from sidecar.config import load_config
|
||
from sidecar.service import create_default_service
|
||
|
||
service = create_default_service(load_config())
|
||
bars = service.get_kline("600000", period="day", limit=120)
|
||
snapshot = service.get_snapshot("600000")
|
||
```
|
||
|
||
## 测试用例
|
||
|
||
- `1-1`：验证腾讯财经 PB 使用索引 46，避免误用索引 43。
|
||
- `1-2`：验证腾讯财经原始响应可解析为字段列表。
|
||
- `2-1`：验证 K 线首次拉取后可从 DuckDB 缓存读取。
|
||
- `2-2`：验证快照在 TTL 内复用 DuckDB 缓存。
|
||
|
||
运行方式：
|
||
|
||
```bash
|
||
pytest
|
||
```
|