yuxuanhui
138 lines
6.4 KiB
Markdown
138 lines
6.4 KiB
Markdown
# 策略执行结果持久化与查询实施计划
|
||
|
||
## 实施原则
|
||
|
||
- 只修改 `zhixing-system`；保留用户已有的 `CONTEXT.md` 和 ADR 工作区变更。
|
||
- 先锁定数据库事务、批次状态和 HTTP 响应测试，再接入前端交互。
|
||
- 复用已有 `EvaluateZhixingB1`、`PostgresMarketDataReader` 和 shared UI，不复制公式
|
||
逻辑或网络 transport。
|
||
- 任何重跑都必须通过“策略 + 目标日”业务键清空旧结果；不要用插入多版本结果来
|
||
规避唯一约束。
|
||
- 后台任务只承担当前进程内异步执行；不得在本任务擅自引入任务队列、定时器或新的
|
||
外部服务。
|
||
|
||
## 1. 规划复核与数据库契约
|
||
|
||
- [x] 将 `prd.md`、`design.md`、本文件从头读一遍，确认产品决策、验收标准和实现
|
||
细节没有重复或冲突。
|
||
- [x] 阅读 `.trellis/spec/backend`、`.trellis/spec/frontend` 及 cross-layer guide，
|
||
确认 migration、HTTP、前端类型和测试边界。
|
||
- [x] 设计并实现 `0002_selection_results`：`selection_run`、`selection_run_item`、
|
||
`selection_signal`、唯一约束、状态索引、JSONB details 和安全 downgrade。
|
||
- [x] 更新 `modules/market_data/infrastructure/schema.py` metadata，使 Alembic
|
||
离线/在线上下文包含新表。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
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 适配器
|
||
|
||
- [x] 在 selection domain 增加批次状态、股票 item、持久化查询模型和明确端口协议。
|
||
- [x] 为 `PostgresMarketDataReader` 增加读取当前有效执行股票集合的能力，使用目标日、
|
||
`market_sync_batch.strategy_eligible`、active stock 和 bar/basic 完整性约束。
|
||
- [x] 在清理旧结果前完成市场同步资格预检；目标日没有可用合格同步批次时返回
|
||
`market_data_not_ready`，保留已有结果不做破坏性变更。
|
||
- [x] 新增 selection PostgreSQL repository：短事务创建/删除/完成 run、记录 item 和
|
||
signal、按 run 或业务键读取；写入 details 时保持 JSON 可序列化。
|
||
- [x] 以 advisory transaction lock、终态检查和 `rerun` 参数实现首次执行、重复执行、
|
||
运行中冲突；清理和创建必须在同一事务。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
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. 全股票池执行用例与异步服务
|
||
|
||
- [x] 实现 `RunZhixingB1`：准备 run、读取有效股票、逐只调用已有评估用例、保存 item
|
||
和全部信号、汇总并完成 run。
|
||
- [x] 为 selected/no_signal/insufficient_history/missing_target_bar/data_error 建立
|
||
明确计数和终态映射；单股失败不影响其他股票，批次级异常收敛为 failed。
|
||
- [x] 为后台执行提供可注入的 service/worker 入口，确保 HTTP 响应提交后才调度，异常
|
||
时更新持久化状态；避免把数据库连接对象跨请求/跨线程复用。
|
||
- [x] 为首次执行、重跑清理、重复运行冲突、失败重试和多分类信号编写应用测试。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest tests/unit/selection/test_run.py
|
||
uv run pytest tests/unit/selection/test_evaluate.py
|
||
```
|
||
|
||
## 4. HTTP 接口与后端契约测试
|
||
|
||
- [x] 在 `selection/presentation/http.py` 定义请求和响应 Pydantic 模型，稳定声明日期、
|
||
状态、计数、coverage、失败 item 和 signal details。
|
||
- [x] 实现 `POST /api/v1/selection/runs`，成功返回 `202 + run_id`；将
|
||
`run_in_progress`、`rerun_confirmation_required`、输入错误和数据库错误映射为稳定
|
||
HTTP 响应。
|
||
- [x] 实现 `GET /api/v1/selection/runs/{run_id}` 和按策略/日期查询结果的 GET 端点；
|
||
无当前结果返回 `status=no_data`，不要制造假的成功结果。
|
||
- [x] 在顶层 router 挂载 selection router，保持 `/api/v1` 唯一目录入口；依赖使用
|
||
`Settings` 注入并提供测试 override。
|
||
- [x] 用 `TestClient(create_app())` 覆盖真实路由、202、冲突、无数据、轮询和终态 JSON。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest tests/test_selection_http.py
|
||
```
|
||
|
||
## 5. 前端 feature 与交互
|
||
|
||
- [x] 新增 `features/selection/api/selection.types.ts`、`selection.api.ts`、
|
||
`selection.query.ts`，实现结果查询、run 查询/轮询和触发 mutation。
|
||
- [x] 新增 selection 页面及结果表/统计卡片/重跑确认 Dialog，覆盖初次执行、成功、
|
||
无命中、失败、部分成功、查询错误和运行中状态。
|
||
- [x] 为“选股策略”启用 `/selection` 路由和导航，保持 HomeShell 的布局及可访问性；
|
||
不让未实现的其他导航入口误显为可用。
|
||
- [x] 重跑或失败重试按钮只打开确认框；取消不调用 POST，确认后才传 `rerun=true`，
|
||
并在返回的 run 完成后刷新结果查询。
|
||
- [x] 同一股票多 category 用独立 badge/行展示，details 只显示后端稳定字段。
|
||
- [x] 更新页面测试和路由相关测试，使用 query hook mock，不依赖真实后端。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-web
|
||
pnpm format:check
|
||
pnpm lint
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
## 6. 全量质量检查与交付门禁
|
||
|
||
- [x] 运行后端 Ruff、Pyright、pytest；运行前端格式、lint、typecheck、test、build。
|
||
- [x] 检查 `rg -n "except Exception|fetch\(|xg_composite"`，确认没有吞异常、页面直
|
||
接请求或旧策略运行时依赖。
|
||
- [x] 检查 migration downgrade、重复执行事务、run status 与前端轮询是否一致。
|
||
- [x] 使用 `task.py validate` 校验任务清单和上下文 manifests，再由 `trellis-check`
|
||
做最终规格/跨层检查。
|
||
|
||
## 风险与回滚点
|
||
|
||
- 新表/适配器失败：只回滚 `0002_selection_results` 和 selection 新代码，不撤销市场
|
||
数据 migration 或用户既有修改。
|
||
- 后台任务进程崩溃：当前 run 可能停在 `running`；必须在页面可见并记录为后续恢复
|
||
机制，不将其当作成功。
|
||
- 全股票池逐只读取过慢：保留结果契约和端口，后续在 reader/application 层做批量读
|
||
取；本任务不通过放宽历史数据或减少股票池来掩盖性能问题。
|