# 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`：腾讯财经适配器，负责日/周/月 K 线与估值字段更完整的实时快照。
- `sidecar/models.py`：统一 K 线与快照模型。

## 数据源策略

- K 线：`day/week/month` 默认优先腾讯财经，失败后回退 mootdx；`1m/5m/15m/30m/60m` 使用 mootdx；腾讯财经 K 线使用未复权接口以对齐 mootdx 原始价格。
- 快照：默认优先腾讯财经，失败后回退 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`：验证腾讯财经原始响应可解析为字段列表。
- `1-3`：验证腾讯财经 K 线 JSON 可转换为统一 K 线。
- `2-1`：验证 K 线首次拉取后可从 DuckDB 缓存读取。
- `2-2`：验证快照在 TTL 内复用 DuckDB 缓存。
- `2-3`：验证日/周/月 K 线优先使用主源。
- `2-4`：验证主源异常时 K 线自动回退备用源。
- `2-5`：验证分钟周期 K 线直接使用备用源。
- `3-4`：验证 mootdx 与腾讯财经的上证指数、深证成指、创业板指 K 线价格随机 100 个 OHLC 值基本一致；成交量单位不同不参与比较。
- `3-5`：验证三大指数代表成分股贵州茅台、平安银行、宁德时代的 K 线价格随机 100 个 OHLC 值基本一致。

运行方式：

```bash
pytest
```