fix(HEL-190): 按真实交易日历补齐最近60日快照，修复断档后只显示当天

保留连续性过滤，新增可审计补档工具与备份步骤；周末/节假日与真缺档分开处理，支持重复执行与部分失败续跑。 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>
2026-08-27 14:50:32 +00:00
parent 8a5e78f022
commit 7ad445bc9f
10 changed files with 974 additions and 31 deletions
@@ -0,0 +1,69 @@
+# 行情历史补档（最近 60 个交易日）
+
+用于修复 `dashboard_snapshots` 断档导致情绪周期 / 主题轮动 / 智能选股只剩当天的问题。
+保留 `latest_contiguous_history` 连续性规则；通过真实交易日历回补缺失交易日快照。
+
+## 适用场景
+
+- 库中已有稀疏历史快照，但最近一个真实交易日缺失，接口 `available_days=1`。
+- 需要可重复执行、可审计、可回退的补档，而不是迁库或放宽算法。
+
+## 前置
+
+1. 使用与线上一致的代码分支。
+2. 管理员账号已配置可用的公共 Tushare Token。
+3. 只操作目标环境自己的 `data/review.db`；禁止 `.36` 与 `.11` 互拷。
+
+## 上线步骤（总工执行）
+
+在应用根目录：
+
+```bash
+# 1) 只读规划：区分已有、真正缺档；不会写入
+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
+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` 精确删除新增行：
+
+```sql
+DELETE FROM dashboard_snapshots WHERE trade_date IN ('YYYYMMDD', ...);
+```
+
+2. 若需整库回退，停止写入后用补档前备份覆盖：
+
+```bash
+# 示例：把 data/backups/review-pre-recent-backfill-YYYYMMDD-HHMMSS.db
+# 复制回 data/review.db 后重启容器
+```
+
+3. 代码回退：对该提交执行 Git revert 后重新部署镜像。
+
+## 验收要点
+
+- dry-run 与正式执行可重复跑；已有交易日默认跳过。
+- 周末、节假日出现在 `skipped_non_trading_days`，不计入失败。
+- 部分交易日同步失败时，其他日期仍会继续，并在审计结果中标 `failed`。
+- 情绪周期、主题轮动 9 列、智能选股置信度随连续交易日恢复。