Tortoise/doc/sidecar.md

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 调用示例

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 值基本一致。

运行方式：

pytest