xiaobai-review/docs/maintenance/行情历史补档.md

行情历史补档（最近 60 个交易日）

用于修复 dashboard_snapshots 断档导致情绪周期 / 主题轮动 / 智能选股只剩当天的问题。 保留 latest_contiguous_history 连续性规则；通过真实交易日历回补缺失交易日快照。

适用场景

• 库中已有稀疏历史快照，但最近一个真实交易日缺失，接口 available_days=1。
• 需要可重复执行、可审计、可回退的补档，而不是迁库或放宽算法。

前置

1. 使用与线上一致的代码分支。
2. 管理员账号已配置可用的公共 Tushare Token。
3. 只操作目标环境自己的 data/review.db；禁止 .36 与 .11 互拷。

上线步骤（总工执行）

在目标环境容器内执行（应用根目录；宿主机也可直接跑，脚本已自带仓库根 sys.path 引导）：

# 1) 只读规划：区分已有、真正缺档；不会写入
docker compose exec xiaobai-review python tools/backfill_recent_snapshots.py --account <管理员账号> --lookback 60 --dry-run --json

# 2) 正式补档：先走 SQLite backup API 写 data/backups/review-pre-recent-backfill-*.db
#    再对缺失交易日调用现有 sync_dashboard
docker compose exec xiaobai-review python tools/backfill_recent_snapshots.py --account <管理员账号> --lookback 60 --json

# 3) 验证
#    GET /api/sentiment/history?trade_date=YYYY-MM-DD&limit=60
#    期望 available_days >= 20，且不再只有 1 天

管理端日期区间回补（/api/backfill）已改为只处理交易日历中的开市日，周末/节假日会进入 skipped_non_trading_days，不再当成错误；单次仍限制 15 个交易日。最近 60 日请用本工具。

写入边界

只会通过现有同步路径写入：

• dashboard_snapshots
• 同步审计表 sync_runs
• 必要时的 data_snapshots（仅当请求日被解析到其他交易日）

不得改动用户、Token、模型绑定或系统配置表。

回滚

1. 优先按审计结果的 created_dates 精确删除新增行：

DELETE FROM dashboard_snapshots WHERE trade_date IN ('YYYYMMDD', ...);

2. 若需整库回退，停止写入后用补档前备份覆盖：

# 示例：把 data/backups/review-pre-recent-backfill-YYYYMMDD-HHMMSS.db
# 复制回 data/review.db 后重启容器

3. 代码回退：对该提交执行 Git revert 后重新部署镜像。

验收要点

• dry-run 与正式执行可重复跑；已有交易日默认跳过。
• 周末、节假日出现在 skipped_non_trading_days，不计入失败。
• 部分交易日同步失败时，其他日期仍会继续，并在审计结果中标 failed。
• 情绪周期、主题轮动 9 列、智能选股置信度随连续交易日恢复。