feat(selection): 补充策略执行结果查询链路

2026-08-09 09:34:46 +08:00
parent e9d06df5de
commit 9c1a1eac23
31 changed files with 3566 additions and 14 deletions
@@ -81,3 +81,90 @@ first = next(category for category in categories if masks[category].iloc[-1])
 target_index = frame.index[frame["trade_date"] == target_trade_date][0]
 matched = tuple(category for category in signal_order if masks[category].iloc[target_index])
 ```
+
+## Scenario: 持久化策略执行结果与 HTTP 重跑
+
+### 1. Scope / Trigger
+
+- Trigger：为已有历史选股公式增加每日批次持久化、HTTP 触发/查询和 Web 轮询时，沿用
+  `selection` bounded context；不要让查询请求重新计算公式。
+- 触发入口是 `POST /api/v1/selection/runs`，结果读取入口是
+  `GET /api/v1/selection/runs/{run_id}` 和
+  `GET /api/v1/selection/results?strategy=...&target_trade_date=...`。
+
+### 2. Signatures
+
+- `SelectionUniverseReader.load_execution_source(strategy: str, target_trade_date: date) -> SelectionExecutionSource`
+- `SelectionRunStore.prepare_run(strategy, target_trade_date, source, *, rerun: bool) -> SelectionRun`
+- `POST /api/v1/selection/runs` 请求：
+  `{"strategy": "zhixing_b1", "target_trade_date": "YYYY-MM-DD", "rerun": false}`；成功返回
+  `202` 和 `{run_id, strategy, target_trade_date, status: "running"}`。
+- `selection_run` 的业务唯一键是 `(strategy, target_trade_date)`；
+  `selection_run_item` 的唯一键是 `(run_id, ts_code)`；
+  `selection_signal` 的唯一键是 `(run_id, ts_code, category)`。
+
+### 3. Contracts
+
+- `load_execution_source` 必须先确认目标日存在 `strategy_eligible=true` 且已完成的
+  `success`/`partial_success` 市场同步批次，并且股票为 active 且目标日 qfq bar/basic
+  完整；来源批次 ID、目标数、实际参与数和 coverage 写入 run。
+- 市场数据预检在删除旧结果之前执行。预检失败不得创建新 run，也不得破坏已有终态结果。
+- 同一策略同一目标日的重跑在一个短事务内使用 advisory transaction lock，删除旧 run
+  （依赖子表 `ON DELETE CASCADE`）并创建唯一的新 `running` run；长时间的逐股计算在
+  事务外执行。
+- 查询响应必须返回 run 状态、批次统计、coverage、失败股票和全部独立 signals；同一
+  股票同日的多 category 不能合并，并按 `ZHIXING_B1_SIGNAL_ORDER` 稳定排序。
+- 前端仅在首次无结果时直接触发；已有终态结果或失败重试必须先确认，再传
+  `rerun=true`。运行中重复请求返回冲突，不能创建第二个当前 run。
+
+### 4. Validation & Error Matrix
+
+| 条件 | 行为 |
+| --- | --- |
+| 不支持的策略、非法日期或缺少合格市场数据 | `422`，错误码 `market_data_not_ready`（输入校验仍使用 FastAPI 默认 `422`） |
+| 同策略同日已有 `running` run | `409`，错误码 `run_in_progress` |
+| 已有终态 run 且 `rerun=false` | `409`，错误码 `rerun_confirmation_required` |
+| PostgreSQL 读写失败 | `503`，错误码 `selection_storage_unavailable` |
+| run ID 不存在 | `404`，错误码 `run_not_found` |
+| 单只股票评估抛出异常 | 记录该 item 为 `data_error`，继续其他股票；批次最终为 `partial_success` 或 `failed` |
+| 全股票评估完成但没有命中 | 批次为 `success`、`signal_count=0`；前端显示“没有命中信号”，不是“无数据” |
+
+### 5. Good / Base / Bad Cases
+
+- Good：目标日已有合格同步批次，首次 POST 返回 `202`，轮询最终结果保留同一股票的
+  两个独立 category；确认重跑后旧 signals 随旧 run 级联清除。
+- Base：目标日没有结果时查询返回 `200 status=no_data`；查询不触发公式计算，用户可在
+  页面选择日期后发起首次执行。
+- Bad：在市场数据预检前删除旧 run；把多个 category OR 成一条 signal；用浏览器长连接
+  等待全股票池计算；或把进程异常留下的 `running` 伪装成成功。
+
+### 6. Tests Required
+
+- Domain/application：断言 source 预检先于 `prepare_run`、首次执行、多分类落盘、单股异常
+  继续执行、全部 no-signal 和失败计数/终态聚合。
+- PostgreSQL adapter：用 fake connection 断言 advisory lock、终态重跑删除后插入、运行中
+  冲突、JSONB details、级联删除契约和公式优先级排序。
+- HTTP：用 `TestClient(create_app())` 断言 `202`、`409` 两类冲突、`422` 数据未就绪、
+  `GET` 无数据、run 轮询和终态 signals。
+- Migration：在可用 PostgreSQL 中断言三张 selection 表、唯一键、索引、cascade 外键，
+  并验证 downgrade 顺序；无数据库时至少生成 offline upgrade/downgrade SQL。
+- Frontend：断言加载、查询失败、无数据、执行中、失败、部分成功、无命中、多 category，
+  以及重跑/失败重试确认取消不发 POST、确认发送 `rerun=true`。
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```python
+# 先清空旧结果，再去确认目标日输入是否可执行；预检失败会造成数据丢失。
+store.delete_current(strategy, target_trade_date)
+source = reader.load_execution_source(strategy, target_trade_date)
+```
+
+#### Correct
+
+```python
+# 先读取并验证来源快照，只有成功 claim 后才允许重跑清理事务。
+source = reader.load_execution_source(strategy, target_trade_date)
+run = store.prepare_run(strategy, target_trade_date, source, rerun=rerun)
+```
@@ -0,0 +1,10 @@
+{"file":".trellis/spec/backend/http-api-contracts.md","reason":"检查 HTTP 方法、状态码、Pydantic 响应和 /api/v1 路由组合是否符合项目契约。"}
+{"file":".trellis/spec/backend/error-handling.md","reason":"检查执行中冲突、重跑确认、失败状态和查询错误是否可观察且未吞异常。"}
+{"file":".trellis/spec/backend/selection.md","reason":"检查目标交易日、qfq 输入、独立子信号和评估状态在批次持久化中没有被破坏。"}
+{"file":".trellis/spec/backend/quality-guidelines.md","reason":"执行后端格式、lint、Pyright、pytest 和黑盒 HTTP 质量检查。"}
+{"file":".trellis/spec/frontend/hook-guidelines.md","reason":"检查 Query key、轮询、mutation 和 AbortSignal 的实现方式。"}
+{"file":".trellis/spec/frontend/state-management.md","reason":"检查服务器状态没有错误复制到全局 store，运行中状态使用局部/query 状态。"}
+{"file":".trellis/spec/frontend/type-safety.md","reason":"检查 API 类型和页面状态分支没有使用 any、无解释断言或重复响应形状。"}
+{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"执行前端格式、lint、类型、测试和构建门禁。"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"检查迁移、领域模型、HTTP JSON、前端类型与用户状态的端到端契约。"}
+{"file":"docs/adr/0004-tushare-six-year-snapshot-sync.md","reason":"检查策略执行是否只使用合格市场同步批次并携带覆盖率和失败信息。"}
@@ -0,0 +1,187 @@
+# 策略执行结果持久化、HTTP 触发与查询设计
+
+## 1. 设计目标
+
+在现有 `selection` bounded context 上补齐一条可重跑的每日策略结果链路：用户在
+Web 页面选择目标交易日并触发 `zhixing_b1`，HTTP 快速返回执行批次标识，服务端在
+当前进程的异步批次中完成全股票池评估并持久化结果，页面轮询状态后展示信号明细。
+
+一次重跑必须在同一数据库事务中清除指定“策略 + 目标交易日”的旧结果并创建新的
+运行记录，避免旧信号和新信号混在一起。执行中的重复请求只返回冲突，不得并发清理
+或重复计算同一批次。
+
+本期不引入独立任务队列、定时器或其他策略；HTTP 是触发入口，FastAPI 进程内的
+`BackgroundTasks` 是异步执行机制。
+
+## 2. 上下文边界与模块分工
+
+```text
+zhixing-server/src/zhixing_server/modules/selection/
+├── domain/
+│   ├── models.py                 # 已有行情、信号和单股评估模型
+│   ├── ports.py                  # 市场数据读取端口
+│   └── runs.py                   # 批次状态、持久化读写端口和执行结果模型
+├── application/
+│   ├── evaluate.py               # 已有单股评估用例
+│   └── run.py                    # 全股票池批次编排、重跑和失败收敛
+├── infrastructure/
+│   ├── postgres_reader.py        # 已有单股 qfq 历史读取，补充执行股票池读取
+│   └── postgres_runs.py          # selection 批次、item、signal 的 PostgreSQL 适配器
+└── presentation/
+    └── http.py                   # Pydantic 请求/响应和 HTTP 依赖
+```
+
+- `selection.domain` 不依赖 FastAPI、Psycopg 或 PostgreSQL JSON 类型。
+- `selection.application` 只依赖端口；批次执行负责逐股调用已有
+  `EvaluateZhixingB1`，不复制公式逻辑。
+- `selection.infrastructure` 负责事务、锁、SQL、JSONB 序列化和市场同步批次关联。
+- `selection.presentation.http` 只做边界校验、HTTP 状态映射和领域模型转换；由
+  `interfaces/http/router.py` 在 `/api/v1/selection` 下挂载。
+- 前端新增 `features/selection` 垂直切片；页面可以依赖 `HomeShell` 和 shared UI，
+  `shared` 不反向依赖 selection。
+
+## 3. 持久化模型与重跑事务
+
+新增 Alembic migration `0002_selection_results`，同时更新
+`modules/market_data/infrastructure/schema.py` 的 metadata。使用三张表：
+
+### 3.1 `selection_run`
+
+一行代表某个策略、目标交易日的一次当前执行尝试。
+
+- `id`：UUID 字符串主键，作为异步轮询的 `run_id`。
+- `strategy`、`target_trade_date`：业务身份；建立唯一约束，保证同一时点只有一条
+  当前尝试。
+- `market_sync_batch_id`：引用产生输入数据的市场同步批次标识；跨上下文先保存
+  稳定 ID，不改变市场数据 bounded context 的写入所有权。
+- `status`：`running`、`success`、`partial_success`、`failed`。
+- `target_count`、`eligible_count`、`evaluated_count`、`selected_stock_count`、
+  `signal_count`、`failed_count`：批次汇总计数。
+- `coverage`：从市场同步批次复制的覆盖率，使用 Numeric 保存精度。
+- `error_type`、`error_message`：批次级失败上下文，可空且不保存 traceback 或凭据。
+- `created_at`、`finished_at`：审计时间。
+
+`selection_run_item` 以 `(run_id, ts_code)` 为主键，保存每只参与股票的名称、
+评估状态、信号数量和可读原因。状态沿用领域评估状态：`selected`、`no_signal`、
+`insufficient_history`、`missing_target_bar`、`data_error`。
+
+`selection_signal` 以 `(run_id, ts_code, category)` 为主键，保存股票、目标日、
+策略、子信号分类、qfq 收盘价和 JSONB `details`。同一股票同日的多个 category
+分别落行，查询时按代码和公式优先级稳定排序。
+
+### 3.2 首次执行、重跑和并发
+
+`prepare_run(strategy, target_trade_date, rerun)` 在一个短事务中完成：
+
+1. 使用按策略和日期派生的 PostgreSQL advisory transaction lock，串行化同一业务键。
+2. 查询当前 `selection_run`。
+3. `running` 时拒绝请求，返回 `409 run_in_progress`。
+4. 已有终态且 `rerun=false` 时返回 `409 rerun_confirmation_required`；页面只有在
+   用户确认弹窗后才发送 `rerun=true`。
+5. `rerun=true` 时删除旧 run（子表使用 `ON DELETE CASCADE`），再插入新的 `running`
+   run；删除与创建同事务提交。
+6. 没有旧 run 时直接插入新的 `running` run。
+
+事务提交后才注册 `BackgroundTasks`。后台执行异常会把 run 收敛为 `failed`；单只
+股票异常记录到 `selection_run_item`，其余股票继续执行，最后根据失败数量和命中
+结果写入 `success`、`partial_success` 或 `failed`。
+
+进程在批次运行中崩溃会留下 `running` 状态；本期将其作为可见的执行中状态，并在
+后续恢复机制中再增加超时接管。该限制必须在运维风险中保留，不能伪装成成功结果。
+
+## 4. 执行数据流
+
+1. HTTP 收到策略、目标交易日和 `rerun`，边界只允许当前支持的 `zhixing_b1`。
+2. application 通过 selection 端口读取目标日最新的 `market_sync_batch`，只允许
+   `strategy_eligible=true` 的同步批次作为输入；没有可用批次则在任何清理/创建 run
+   事务之前返回 `422 market_data_not_ready`，不使用当前最新日期猜测目标日，也不破坏
+   已有的成功结果。
+3. 读取当前 `market_stock.is_active=true` 且目标日同时拥有 bar/basic 的有效股票
+   集合；`target_count` 和 `coverage` 来自同步批次，`eligible_count` 来自实际输入。
+4. 对每只股票调用已有 `PostgresMarketDataReader.load_history` 和
+   `EvaluateZhixingB1.execute`，将 item 状态和全部独立 signals 写入当前 run。
+5. 完成后一次更新 run 汇总和 `finished_at`；查询端只读取已提交的持久化状态。
+
+全股票池执行先使用现有“逐股票读取”的正确性优先方案，不在本任务引入并行化或
+缓存；若性能不足，后续再以批量历史读取为单独设计。
+
+## 5. HTTP 契约
+
+### 5.1 触发
+
+`POST /api/v1/selection/runs`
+
+请求：
+
+```json
+{
+  "strategy": "zhixing_b1",
+  "target_trade_date": "2026-08-08",
+  "rerun": false
+}
+```
+
+成功返回 `202`：
+
+```json
+{
+  "run_id": "<uuid>",
+  "strategy": "zhixing_b1",
+  "target_trade_date": "2026-08-08",
+  "status": "running"
+}
+```
+
+错误状态至少包括：
+
+- `409 run_in_progress`：同一策略和目标日已有运行中的批次；
+- `409 rerun_confirmation_required`：已有终态结果但请求没有 `rerun=true`；
+- `422`：策略、日期或市场数据资格不满足请求契约；
+- `503`：无法创建批次或数据库不可用。
+
+### 5.2 轮询与结果查询
+
+- `GET /api/v1/selection/runs/{run_id}`：按 run ID 返回批次状态；运行中返回汇总，
+  终态追加 item 失败列表和 signals。
+- `GET /api/v1/selection/results?strategy=zhixing_b1&target_trade_date=...`：按业务
+  键查询当前结果。目标日省略时取该策略最近一条当前 run；没有结果返回 `200` 的
+  `status=no_data`，不把“没有执行”伪装成 HTTP 异常。
+
+稳定响应包含策略、目标日、run ID、状态、市场同步批次、计数、coverage、错误/失败
+列表和 signal 明细。日期使用 ISO `date`，时间使用带时区的 ISO `datetime`。字段不
+直接暴露数据库列名以外的内部异常信息。
+
+## 6. 前端交互
+
+- 新增 `/selection` 路由，启用 `HomeShell` 的“选股策略”导航。
+- 页面提供目标交易日选择，默认查询最近持久化结果；策略下拉首期只显示“知行 B1”。
+- 首次无结果时显示“执行策略”；已有成功、部分成功或失败结果时显示“重新执行/
+  重试执行”，点击先打开确认 Dialog，取消不调用 POST，确认才发送 `rerun=true`。
+- POST 成功后保存 `run_id` 到组件局部状态，使用 React Query 轮询 run；运行中展示
+  状态和刷新提示，终态失效业务键查询并显示结果。
+- 页面明确区分加载中、查询错误、无数据、执行中、执行失败、无命中、部分成功和
+  成功；signals 以每个 category 一行或可辨认的标签展示，同一股票的多分类不能合并
+  成一条无分类记录。
+- API 类型、query key、mutation 和轮询逻辑全部位于 `features/selection/api/`，
+  页面不直接调用 `fetch`，不把服务器结果复制到 Zustand。
+
+## 7. 兼容性与回滚
+
+- 不修改 `market_stock`、行情事实表或现有同步批次的语义；只读取其
+  `strategy_eligible`、coverage 和目标日输入。
+- migration downgrade 按 signals → items → runs 删除新表；删除 selection 结果
+  不影响市场数据。
+- 如果异步机制或全市场性能不满足，保留已提交的迁移和领域契约，后续替换执行器；
+  不回退到即时查询或删除持久化结果。
+- 进程崩溃遗留 `running` 和当前实现逐股票读取是已知风险，作为后续任务候选记录。
+
+## 8. 验证策略
+
+- domain/application：Fake reader/repository 覆盖首次执行、重跑先清空、运行中冲突、
+  全部状态聚合、多分类落盘和单股失败继续执行。
+- infrastructure：fake psycopg connection 覆盖参数化查询、事务顺序、级联清理、
+  JSONB details、市场同步资格和稳定排序。
+- HTTP：`TestClient(create_app())` 覆盖 `202`、`409`、`422`、无数据查询、轮询和
+  终态响应；后台执行依赖通过 FastAPI override 或 fake service 注入。
+- frontend：页面测试覆盖初次执行、确认弹窗取消/确认、轮询状态、失败重试、无命中、
+  多分类和查询错误；运行格式、lint、类型、Vitest 和生产构建。
@@ -0,0 +1,17 @@
+{"file":".trellis/spec/backend/index.md","reason":"确认后端 bounded context、HTTP 入口和开发前检查。"}
+{"file":".trellis/spec/backend/directory-structure.md","reason":"按 selection 的 domain/application/infrastructure/presentation 边界组织持久化、执行和 HTTP 代码。"}
+{"file":".trellis/spec/backend/http-api-contracts.md","reason":"实现 /api/v1 路由目录、Pydantic 响应模型、依赖注入和 TestClient 契约。"}
+{"file":".trellis/spec/backend/error-handling.md","reason":"为重跑冲突、执行失败、查询失败和 FastAPI 边界建立稳定错误映射。"}
+{"file":".trellis/spec/backend/selection.md","reason":"复用 zhixing_b1 的目标日、qfq、独立子信号和评估状态契约。"}
+{"file":".trellis/spec/backend/quality-guidelines.md","reason":"遵守 Ruff、Pyright、pytest、公开类型和 HTTP 测试门禁。"}
+{"file":".trellis/spec/frontend/index.md","reason":"确认 React feature 垂直切片、同源 API 和前端质量检查。"}
+{"file":".trellis/spec/frontend/directory-structure.md","reason":"将 selection API、页面、路由和组件放入正确的 feature 边界。"}
+{"file":".trellis/spec/frontend/hook-guidelines.md","reason":"实现 React Query 查询、轮询和 mutation，不在页面直接 fetch。"}
+{"file":".trellis/spec/frontend/state-management.md","reason":"将运行状态和结果留在 React Query/局部状态，不复制到 Zustand。"}
+{"file":".trellis/spec/frontend/component-guidelines.md","reason":"实现可访问的结果页面、表格状态和重跑确认 Dialog。"}
+{"file":".trellis/spec/frontend/type-safety.md","reason":"保持后端响应类型、字面量状态和严格 TypeScript 一致。"}
+{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"执行前端格式、lint、测试和构建检查。"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"同步数据库、领域、HTTP、前端 API 类型和页面状态的跨层契约。"}
+{"file":"docs/adr/0001-bounded-context-first-modular-monolith.md","reason":"确认 selection 持久化与 HTTP 仍归属模块化单体的明确 bounded context。"}
+{"file":"docs/adr/0003-postgresql-as-market-data-store.md","reason":"确认 PostgreSQL 是策略输入事实源，CSV 不承担运行时结果查询。"}
+{"file":"docs/adr/0004-tushare-six-year-snapshot-sync.md","reason":"遵守策略批次关联市场同步批次、覆盖率和策略资格契约。"}
@@ -0,0 +1,137 @@
+# 策略执行结果持久化与查询实施计划
+
+## 实施原则
+
+- 只修改 `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 层做批量读
+  取；本任务不通过放宽历史数据或减少股票池来掩盖性能问题。
@@ -0,0 +1,83 @@
+# 补充策略执行结果查询接口和前端页面
+
+## Goal
+
+为已完成的知行 B1 历史选股逻辑提供可使用的查询入口，让研究人员能够在 Web
+页面选择目标交易日并查看策略命中的股票及子信号结果。
+
+## Background and confirmed facts
+
+- 上一个任务 `08-08-migrate-zhixing-b1` 已完成 `zhixing_b1` 策略领域逻辑、历史
+  qfq 行情读取适配器和单只股票评估用例。
+- 当前领域入口是
+  `EvaluateZhixingB1.execute(ts_code, target_trade_date)`，返回
+  `SelectionEvaluation`，状态包括 `selected`、`no_signal`、`insufficient_history`、
+  `missing_target_bar` 和 `data_error`。
+- `SelectionSignal` 已包含股票代码、名称、目标交易日、策略标识、七种独立子信号
+  分类、收盘价和可序列化详情；稳定身份为
+  `(ts_code, target_trade_date, strategy, category)`。
+- 当前没有选股结果数据库表、结果持久化、全市场批量执行用例或 selection HTTP
+  路由；selection presentation 包仍为空。
+- 后端 HTTP 通过 `/api/v1` 统一挂载，稳定响应使用 Pydantic 模型；前端按 feature
+  组织 API 类型、Query hook 和页面，并通过同源 `/api/v1/...` 请求后端。
+- 当前前端首页侧栏的“选股策略”入口仍是禁用按钮，路由树只有 `/` 首页。
+
+## Product decisions
+
+- 结果按每日策略批次持久化；页面查询已保存的策略执行批次，不在查询请求中重新
+  计算策略。
+- 策略执行通过 HTTP 触发，不新增 CLI 作为本任务的主要入口。
+- 当用户重复执行或重试失败批次时，服务端必须先清空指定目标交易日、指定策略的
+  旧结果，再执行一次；前端在每次重执行前弹窗确认，确认后才发起 HTTP 请求。
+- 执行接口需要能区分首次执行、已有结果的重复执行和执行中的冲突，不能因重复点击
+  产生重复信号或多个互相冲突的当前结果。
+- HTTP 采用异步批次模式：`POST` 只创建/清空并启动批次，返回 `202` 和 `run_id`；
+  前端通过 `GET` 轮询批次状态，完成后展示持久化结果。全股票池计算不得要求浏览器
+  长时间保持原始执行请求。
+
+## Requirements
+
+- 策略执行结果必须按目标交易日和策略批次持久化，并可被后续 HTTP 查询读取。
+- `zhixing_b1` 的多种独立子信号必须分别保存，不能因同一股票同日多分类而覆盖或
+  合并；结果身份继续遵循
+  `(ts_code, target_trade_date, strategy, category)`。
+- 查询页面展示已保存批次的执行状态、目标交易日、参与数量、命中数量以及股票和
+  子信号明细；查询失败、执行失败和无命中必须有可区分的用户可见状态。
+- 同一策略同一目标交易日重复执行必须具备幂等语义，不能产生重复信号或多个互相
+  冲突的“最新结果”；按用户确认的重跑规则，重跑前清空该日该策略旧结果。
+- 结果应关联产生它所依赖的市场数据同步批次，并保留实际参与股票数和数据覆盖率，
+  以便判断结果是否完整。
+- HTTP 应提供策略执行触发接口，支持指定目标交易日和策略；首次执行、重跑确认、
+  执行中冲突和失败重试应有明确响应语义。
+- HTTP 响应使用稳定的 Pydantic 契约；前端使用 feature API 类型、React Query 和
+  独立的策略结果页面，不在页面中直接发起 `fetch`。
+
+## Acceptance Criteria
+
+- [ ] 已执行的 `zhixing_b1` 批次及其信号结果可以写入 PostgreSQL，并能通过稳定
+  唯一身份幂等重跑；重跑不会残留上一次执行的信号。
+- [ ] HTTP 可以查询最新批次和/或指定目标交易日的持久化结果，响应包含批次状态、
+  覆盖率、命中统计和全部独立子信号明细。
+- [ ] HTTP 可以触发指定目标交易日和策略的执行；已有结果重跑和失败重试遵循清空后
+  重算规则，并对执行中的重复请求返回可识别冲突。
+- [ ] 前端“选股策略”入口可进入结果页面，能够查看加载中、无数据、执行失败、查询
+  失败、无命中和正常结果状态。
+- [ ] 前端每次重跑/失败重试都会先展示确认弹窗；取消不会发起执行请求，确认后能显示
+  执行中状态并刷新持久化结果。
+- [ ] 执行触发接口返回异步批次标识，前端可通过状态查询感知运行中、成功、无命中和
+  失败，并在结束后读取同一批次结果。
+- [ ] 结果页面的股票明细能区分同一股票同日命中的多个子信号，并展示目标交易日、
+  股票代码/名称、收盘价及关键详情。
+- [ ] 后端迁移、应用用例、HTTP 契约和前端页面测试覆盖成功、重复执行、无结果和
+  失败场景。
+
+## Out of scope
+
+- 不迁移其他选股策略，不改变 `zhixing_b1` 公式语义或市场数据同步规则。
+- 不实现收益率、持仓、交易撮合或实盘交易能力；本任务展示的是选股信号结果。
+- 不把执行调度扩展为独立任务队列或跨进程工作流；本期只提供 HTTP 触发和项目现有
+  运行边界内的异步批次执行机制。
+
+## Open questions
+
+无。
@@ -0,0 +1,26 @@
+{
+  "id": "strategy-execution-results",
+  "name": "strategy-execution-results",
+  "title": "补充策略执行结果查询接口和前端页面",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "yuxuanhui",
+  "assignee": "yuxuanhui",
+  "createdAt": "2026-08-08",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}