# 市场数据完整性检查 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 最外层保证异常落库。