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`，然后执行迁移：

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

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

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

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

```bash
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 使周末、节假日、重复触发和重叠触发保持安全：

```cron
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`。修复凭据、网络或数据库问题后，只重试该批次失败的股票和指标日期：

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

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

## 本地检查

```bash
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 或数据库。