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：腾讯财经适配器，负责估值字段更完整的实时快照。
• 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 调用示例

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 缓存。

运行方式：

pytest