chore(task): 归档 08-10 与 08-11 任务

2026-08-11 13:32:21 +08:00
parent 8f5f504368
commit dd04933d63
33 changed files with 788 additions and 5 deletions
@@ -0,0 +1,37 @@
+# 市场数据完整性检查 API 设计
+
+## 深模块接口
+
+`RunMarketIntegrityCheck` 对 HTTP 暴露 prepare/execute/query；调用方不需要知道流式 cursor、CSV
+布局、比较算法或检查表写入细节。真实 PostgreSQL/CSV adapters 与内存测试 adapters 落在既有 ports seam。
+
+## 数据模型
+
+新增 `IntegrityCheckRun`、`IntegrityIssue` 和分页结果。迁移 `0003_market_integrity_checks` 创建：
+
+- `market_integrity_check`：运行状态、窗口、target/checked/issue 计数、安全批次错误和时间；
+- `market_integrity_issue`：check id、稳定 issue key、item kind/key、issue type、安全 message；
+- running/created_at 和 issue check id 索引。
+
+检查表不参与首页 overview 或 selection source 查询。
+
+## 比较算法
+
+在同一 advisory lock 中：
+
+1. 读取最近已完成同步窗口和 active stock master；
+2. 比较 stock CSV；
+3. PostgreSQL 按 `(ts_code, trade_date)` 流式读取 bars，与逐股 CSV 归并比较；
+4. PostgreSQL 按 `(trade_date, ts_code)` 流式读取 daily_basic，与逐日 CSV 归并比较；
+5. 每完成一组更新 checked_count，问题分批写入；
+6. 无问题为 passed，有问题为 issues_found，批次异常为 failed。
+
+事实读取使用稳定快照且不执行 DML。CSV adapter 仅打开正式文件，不创建临时文件、不调用 publish。
+
+## HTTP 与恢复
+
+挂载 `/api/v1/market-data/integrity-checks`。POST 原子 claim 后通过 BackgroundTasks 执行；已有 running
+返回 409。查询端点返回 Pydantic 模型并限制 page size。
+
+prepare 时可把超过配置阈值且已不持有 advisory lock 的旧 running 标记为 failed；不能仅按页面刷新
+时间误杀仍在运行的任务。后台 execute 最外层保证异常落库。