zhixing-system/docs/market-data-sync.md

市场数据同步 Job

market-data-sync 是外部调度器触发的一次性任务。FastAPI 进程不包含定时器；PostgreSQL 是策略查询事实源，market-data 卷中的 CSV 只作为 qfq 落地快照和恢复介质。

首次部署

先准备 .env，至少设置 ZHIXING_TUSHARE_TOKEN、PostgreSQL 凭据和 ZHIXING_DATABASE_URL，然后执行迁移：

docker compose -f docker-compose.prod.yml --profile jobs run --rm migrate

首次初始化会回补六年交易日指标，并为当前沪深非 ST A 股获取六年 qfq 行情：

docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync --initialize

日常收盘后同步默认解析最近的开市日；也可以显式指定日期：

docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync --trade-date 2026-08-05

success 返回 0；覆盖率低于配置阈值或出现部分失败返回 2；没有可用成功结果或基础设施失败返回 1。CLI 输出不包含 Tushare token 或数据库密码。

Cron 与重试

宿主机 cron 只负责启动临时容器，不写入容器内部的 crontab。下面的示例每天工作日 18:00 触发；交易日历、唯一约束和 PostgreSQL advisory lock 使周末、节假日、重复触发和重叠触发保持安全：

0 18 * * 1-5 cd /srv/zhixing-system && docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync >> /var/log/zhixing-market-sync.log 2>&1

部分成功批次的输出会包含 batch_id。修复凭据、网络或数据库问题后，只重试该批次失败的股票和指标日期：

docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync \
  --retry-batch-id <batch-id>

单只股票按数据库事务和 CSV 发布作为恢复边界。数据库提交失败时正式 CSV 不会替换；CSV 发布失败时数据库写入保持幂等，重试可以再次发布。成功批次完成后，数据库事实表和正式日期快照清理六年窗口起点以前的数据；失败对象保留上一次成功版本。

本地检查

docker compose -f docker-compose.dev.yml config
docker compose -f docker-compose.dev.yml --profile jobs config
docker compose -f docker-compose.prod.yml config
docker compose -f docker-compose.prod.yml --profile jobs config

真实 PostgreSQL 迁移和批量 upsert 集成测试使用 ZHIXING_TEST_DATABASE_URL 显式开启；普通单元测试不会访问网络、Tushare 或数据库。