zhixing-system/.trellis/tasks/archive/2026-08/08-08-strategy-execution-results/implement.md

策略执行结果持久化与查询实施计划

实施原则

• 只修改 zhixing-system；保留用户已有的 CONTEXT.md 和 ADR 工作区变更。
• 先锁定数据库事务、批次状态和 HTTP 响应测试，再接入前端交互。
• 复用已有 EvaluateZhixingB1、PostgresMarketDataReader 和 shared UI，不复制公式 逻辑或网络 transport。
• 任何重跑都必须通过“策略 + 目标日”业务键清空旧结果；不要用插入多版本结果来 规避唯一约束。
• 后台任务只承担当前进程内异步执行；不得在本任务擅自引入任务队列、定时器或新的 外部服务。

1. 规划复核与数据库契约

• 将 prd.md、design.md、本文件从头读一遍，确认产品决策、验收标准和实现 细节没有重复或冲突。
• 阅读 .trellis/spec/backend、.trellis/spec/frontend 及 cross-layer guide， 确认 migration、HTTP、前端类型和测试边界。
• 设计并实现 0002_selection_results：selection_run、selection_run_item、 selection_signal、唯一约束、状态索引、JSONB details 和安全 downgrade。
• 更新 modules/market_data/infrastructure/schema.py metadata，使 Alembic 离线/在线上下文包含新表。

验证：

cd zhixing-server
uv run alembic check
uv run pytest tests/integration/test_market_data_migration.py

回滚点：migration 或 schema metadata 不一致时只回滚新 migration 和 selection 表， 不修改 0001_market_data。

2. 领域端口与 PostgreSQL 适配器

• 在 selection domain 增加批次状态、股票 item、持久化查询模型和明确端口协议。
• 为 PostgresMarketDataReader 增加读取当前有效执行股票集合的能力，使用目标日、 market_sync_batch.strategy_eligible、active stock 和 bar/basic 完整性约束。
• 在清理旧结果前完成市场同步资格预检；目标日没有可用合格同步批次时返回 market_data_not_ready，保留已有结果不做破坏性变更。
• 新增 selection PostgreSQL repository：短事务创建/删除/完成 run、记录 item 和 signal、按 run 或业务键读取；写入 details 时保持 JSON 可序列化。
• 以 advisory transaction lock、终态检查和 rerun 参数实现首次执行、重复执行、 运行中冲突；清理和创建必须在同一事务。

验证：

cd zhixing-server
uv run pytest tests/unit/selection/test_postgres_runs.py
uv run pytest tests/unit/selection/test_postgres_reader.py

回滚点：若 SQL 适配器无法通过 fake connection 测试，保留纯领域端口和 migration， 先修适配器，不触碰已有市场数据写入代码。

3. 全股票池执行用例与异步服务

• 实现 RunZhixingB1：准备 run、读取有效股票、逐只调用已有评估用例、保存 item 和全部信号、汇总并完成 run。
• 为 selected/no_signal/insufficient_history/missing_target_bar/data_error 建立 明确计数和终态映射；单股失败不影响其他股票，批次级异常收敛为 failed。
• 为后台执行提供可注入的 service/worker 入口，确保 HTTP 响应提交后才调度，异常 时更新持久化状态；避免把数据库连接对象跨请求/跨线程复用。
• 为首次执行、重跑清理、重复运行冲突、失败重试和多分类信号编写应用测试。

验证：

cd zhixing-server
uv run pytest tests/unit/selection/test_run.py
uv run pytest tests/unit/selection/test_evaluate.py

4. HTTP 接口与后端契约测试

• 在 selection/presentation/http.py 定义请求和响应 Pydantic 模型，稳定声明日期、 状态、计数、coverage、失败 item 和 signal details。
• 实现 POST /api/v1/selection/runs，成功返回 202 + run_id；将 run_in_progress、rerun_confirmation_required、输入错误和数据库错误映射为稳定 HTTP 响应。
• 实现 GET /api/v1/selection/runs/{run_id} 和按策略/日期查询结果的 GET 端点； 无当前结果返回 status=no_data，不要制造假的成功结果。
• 在顶层 router 挂载 selection router，保持 /api/v1 唯一目录入口；依赖使用 Settings 注入并提供测试 override。
• 用 TestClient(create_app()) 覆盖真实路由、202、冲突、无数据、轮询和终态 JSON。

验证：

cd zhixing-server
uv run pytest tests/test_selection_http.py

5. 前端 feature 与交互

• 新增 features/selection/api/selection.types.ts、selection.api.ts、 selection.query.ts，实现结果查询、run 查询/轮询和触发 mutation。
• 新增 selection 页面及结果表/统计卡片/重跑确认 Dialog，覆盖初次执行、成功、 无命中、失败、部分成功、查询错误和运行中状态。
• 为“选股策略”启用 /selection 路由和导航，保持 HomeShell 的布局及可访问性； 不让未实现的其他导航入口误显为可用。
• 重跑或失败重试按钮只打开确认框；取消不调用 POST，确认后才传 rerun=true， 并在返回的 run 完成后刷新结果查询。
• 同一股票多 category 用独立 badge/行展示，details 只显示后端稳定字段。
• 更新页面测试和路由相关测试，使用 query hook mock，不依赖真实后端。

验证：

cd zhixing-web
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build

6. 全量质量检查与交付门禁

• 运行后端 Ruff、Pyright、pytest；运行前端格式、lint、typecheck、test、build。
• 检查 rg -n "except Exception|fetch\(|xg_composite"，确认没有吞异常、页面直 接请求或旧策略运行时依赖。
• 检查 migration downgrade、重复执行事务、run status 与前端轮询是否一致。
• 使用 task.py validate 校验任务清单和上下文 manifests，再由 trellis-check 做最终规格/跨层检查。

风险与回滚点

• 新表/适配器失败：只回滚 0002_selection_results 和 selection 新代码，不撤销市场 数据 migration 或用户既有修改。
• 后台任务进程崩溃：当前 run 可能停在 running；必须在页面可见并记录为后续恢复 机制，不将其当作成功。
• 全股票池逐只读取过慢：保留结果契约和端口，后续在 reader/application 层做批量读 取；本任务不通过放宽历史数据或减少股票池来掩盖性能问题。