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,5 @@
+{"file":".trellis/spec/backend/market-data-sync.md","reason":"检查只读审计没有破坏市场事实、CSV 或同步批次语义。"}
+{"file":".trellis/spec/backend/http-api-contracts.md","reason":"检查路由挂载、模型、状态码和同源路径。"}
+{"file":".trellis/spec/backend/quality-guidelines.md","reason":"检查迁移、类型、测试和禁止模式。"}
+{"file":".trellis/tasks/08-11-market-integrity-check-api/prd.md","reason":"逐条核对报告范围、只读性、冲突、分页和流式验收。"}
+{"file":".trellis/tasks/08-11-market-data-sync-performance-audit/design.md","reason":"检查没有污染首页/selection，并与并发子任务正确集成。"}
@@ -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 最外层保证异常落库。
@@ -0,0 +1,5 @@
+{"file":".trellis/spec/backend/market-data-sync.md","reason":"检查必须理解 PostgreSQL/CSV 快照布局、窗口和 advisory lock 契约。"}
+{"file":".trellis/spec/backend/http-api-contracts.md","reason":"实现 market_data 业务路由、Pydantic 响应和 FastAPI 错误映射。"}
+{"file":".trellis/spec/backend/error-handling.md","reason":"保证批次/问题错误安全、可识别且不吞异常。"}
+{"file":".trellis/tasks/08-11-market-data-sync-performance-audit/design.md","reason":"提供独立检查表、流式比较、HTTP 状态和只报告边界。"}
+{"file":".trellis/tasks/08-11-market-integrity-check-api/design.md","reason":"定义本子任务的领域接口、比较算法、迁移和恢复行为。"}
@@ -0,0 +1,13 @@
+# 实施计划
+
+1. 增加领域状态、run/issue/分页模型和 ports，先写 passed/issues/failed 应用测试。
+2. 增加 `0003_market_integrity_checks` 迁移并同步 `infrastructure/schema.py`。
+3. 扩充只读 CSV 能力：stock、bar、daily_basic 的列举/读取，不复用写入路径产生副作用。
+4. 实现 PostgreSQL 流式 snapshot reader 和 integrity check store，复用前置任务连接池。
+5. 实现分组 merge comparison、问题批量落库、进度与终态收敛。
+6. 实现同 advisory lock 冲突和陈旧 running 恢复。
+7. 增加 market_data HTTP presentation、router 挂载、202/查询/错误映射测试。
+8. 把经确认的只读检查契约列为 `.trellis/spec/` 更新候选；未经用户批准不直接提升。
+9. 运行 Ruff、Pyright、pytest；配置数据库时运行迁移与完整性集成测试。
+
+回滚点：迁移只新增检查表；应用回滚不影响事实表，downgrade 可独立删除检查表。
@@ -0,0 +1,38 @@
+# 实现市场数据完整性检查 API
+
+## Goal
+
+提供用户主动触发、可轮询的 PostgreSQL/CSV 完整性检查；检查不访问 Tushare、不修改市场事实，
+只持久化检查进度与安全问题报告。
+
+## Dependencies
+
+- 依赖 `08-11-market-sync-concurrency-storage` 的连接池和共享 advisory lock 契约完成。
+
+## Requirements
+
+- 检查 current stock master、六年 qfq bars 和六年 daily_basic 的 PostgreSQL/CSV 一致性。
+- 报告缺失、多余、解析失败、重复键、内容不一致和窗口越界；不把正常停牌误报为缺历史日期。
+- 使用流式/分组比较，不能一次加载全市场约 700 万行。
+- 使用独立检查表和状态 `running/passed/issues_found/failed`，不复用同步批次。
+- 检查与同步使用同一 advisory lock；已有检查运行时禁止重复触发。
+- `POST` 返回 202，`GET latest` 和 `GET by id` 返回进度、终态及分页问题。
+- 后台异常和失去 worker 的陈旧 running 记录必须能收敛为 failed。
+- 除检查表外，执行前后市场事实表内容和正式 CSV 必须完全不变。
+
+## Acceptance Criteria
+
+- [ ] 一致 fixture 得到 `passed`；各类不一致得到 `issues_found` 和稳定问题类型。
+- [ ] CSV 解析失败被报告且不会中断其余对象检查。
+- [ ] 检查只使用本地 DB/CSV adapters，测试能断言 Tushare port 未被构造或调用。
+- [ ] 大数据 fixture/迭代器测试证明比较按股票/交易日分组流式消费。
+- [ ] 同步持锁时检查安全失败，检查持锁时同步不能进入临界区。
+- [ ] HTTP 测试覆盖 202、409、404、503、latest/no_data、轮询进度和问题分页。
+- [ ] 迁移 upgrade/downgrade 和 schema metadata 一致；首页/selection 查询不选择检查记录。
+- [ ] 后端 Ruff、Pyright、pytest 全部通过。
+
+## Out of Scope
+
+- 不检查 Tushare 当日是否出数。
+- 不自动修复、重试或重新下载。
+- 不引入外部队列；沿用当前进程内 BackgroundTasks。
@@ -0,0 +1,26 @@
+{
+  "id": "market-integrity-check-api",
+  "name": "market-integrity-check-api",
+  "title": "实现市场数据完整性检查 API",
+  "description": "实现不访问 Tushare、不修改市场事实的 PostgreSQL/CSV 完整性检查批次和 HTTP 轮询接口。",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "yuxuanhui",
+  "assignee": "yuxuanhui",
+  "createdAt": "2026-08-11",
+  "completedAt": "2026-08-11",
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "08-11-market-data-sync-performance-audit",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}