yuxuanhui
5.8 KiB
5.8 KiB
Tushare PostgreSQL 同步实施计划
实施原则
- 按以下顺序增量交付，每一步先写对应行为测试，再补最小实现。
- 不修改旧项目；不导入其带有最新市值回填的历史 CSV。
- 不在本任务中实现选股策略、HTTP 管理接口或宿主机 crontab 写入。
- schema、CSV 契约和批次状态一旦被后续步骤使用，变更时必须同步更新迁移、测试和设计文档。
1. 依赖、配置与迁移骨架
- 在
zhixing-server/pyproject.toml增加 Tushare、Psycopg 3、SQLAlchemy 和 Alembic 依赖并更新uv.lock。 - 扩展
bootstrap.config.Settings：数据库 URL、Tushare token、CSV 根目录、覆盖率阈值、并发/限流/重试参数；保持ZHIXING_前缀且不暴露秘密。 - 初始化 Alembic 配置和 metadata，创建股票、日线、每日指标、同步 batch/item 表及唯一约束、索引。
- 增加 migration 集成测试，验证空库 upgrade 到 head、唯一约束和必要索引。
验证：
cd zhixing-server
uv sync
uv run alembic upgrade head
uv run pytest tests/integration/test_market_data_migrations.py
回滚点：本阶段只建立 schema；若迁移失败，修正 migration 后重建测试库，不对生产卷执行手工 DDL。
2. 领域模型、规范化与端口
- 创建
modules/market_data四层目录和 bounded-context README。 - 定义
ts_code、目标交易日、六年窗口、bar、daily basic、batch/item 状态和值对象。 - 定义 Tushare 来源、快照存储、市场数据仓储、批次仓储和同步锁端口。
- 实现固定列、日期、小数、空值规范化，完整重叠区间 SHA-256 计算和变化分类。
- 先用纯领域测试覆盖：初次同步、仅新增日期、历史值变化、重叠区间缺行、输入顺序变化、空值/小数稳定性和窗口边界。
验证：
cd zhixing-server
uv run pytest tests/unit/market_data/test_fingerprint.py tests/unit/market_data/test_window.py
3. Tushare 与 CSV 适配器
- 封装
stock_basic、trade_cal、pro_bar(adj="qfq")和daily_basic(trade_date=...)，把 DataFrame 转为领域记录。 - 实现当前沪深非 ST 股票池过滤、请求退避/抖动和可配置并发限制。
- 实现 bar 按股票、daily basic 按日期、stock basic 当前版的临时 CSV 写入、校验、指纹读取、原子晋升和过期文件清理。
- 通过 fake Tushare 客户端与临时目录测试，不让普通单元测试访问真实网络。
验证：
cd zhixing-server
uv run pytest tests/unit/market_data/test_tushare_adapter.py tests/unit/market_data/test_csv_snapshot_store.py
回滚点：正式 CSV 只在数据库提交后晋升；适配器测试必须证明异常路径保留旧文件。
4. PostgreSQL 批量仓储
- 使用 Psycopg 连接/事务实现股票主数据、bar、daily basic、batch/item 和 advisory lock 适配器。
- 对 bar 和 daily basic 使用临时 staging +
COPY+ 集合式 upsert；通过IS DISTINCT FROM避免无意义 update。 - 实现 insert-only、新窗口完整修复、窗口内缺失删除和六年前数据清理。
- 集成测试覆盖幂等、更新计数、单股票回滚、日期事务回滚、并发锁以及数据库最终与快照一致。
验证：
cd zhixing-server
uv run pytest tests/integration/test_market_data_repository.py
5. 同步用例与失败重试
- 实现
SyncMarketData.execute()：解析目标交易日、刷新股票池、创建批次、回补/更新 daily basic、逐股票同步 bar、收敛状态和覆盖率。 - 初始化模式只回补缺失开市日；日常模式只获取目标日 daily basic，但每股始终拉六年 qfq。
- 实现父 batch 的失败股票和失败指标日期重试；成功项不回滚、不重复抓取。
- 用 fake 端口编排测试覆盖
success、partial_success、failed、99% 阈值、旧数据不得计入有效集合、CSV 发布失败和重试恢复。
验证：
cd zhixing-server
uv run pytest tests/unit/market_data/test_sync_market_data.py
6. CLI、Compose 与运维文档
- 增加 console script/CLI，支持普通同步、显式目标日期、初始化和按 batch 重试；输出批次摘要并返回稳定退出码。
- 在 dev/prod Compose 中增加 PostgreSQL、CSV 持久卷、
migrate和market-syncprofile Job，复用后端镜像和统一环境配置。 - 更新
.env.example与部署文档，提供 migration、手工运行、失败重试和宿主机 cron 示例；不自动写入 crontab。 - 验证正常
up不启动 Job，显式run --rm能连接数据库与 CSV 卷。
验证：
docker compose -f docker-compose.prod.yml config
docker compose -f docker-compose.dev.yml config
docker compose -f docker-compose.prod.yml --profile jobs config
7. 全链路验收与质量门禁
- 使用受控 fixture 或测试 Tushare 适配器完成空库初始化、无变化重跑、仅新增日期、历史 qfq 修订、单股票失败和定向重试场景。
- 核对 batch/item 计数、覆盖率、数据库内容、正式 CSV、六年清理和秘密脱敏。
- 若运行真实 Tushare smoke test，必须由显式环境开关启用，限制少量股票且不把 token 写入测试输出。
- 运行后端和根目录质量门禁；修复所有 Ruff、Pyright、pytest 与 Compose config 问题。
验证：
cd zhixing-server
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
cd ..
./dev.sh check
./dev.sh test
git diff --check
开始实施前检查
- 用户已在最终规划摘要之后明确批准实施。
prd.md、design.md、implement.md内容一致且无阻塞问题。implement.jsonl与check.jsonl各自至少包含一条真实规格/研究上下文。task.py validate tushare-postgres-sync通过。- 当前工作区已有改动已识别，实施不覆盖用户或其他任务的文件。