yuxuanhui
84 lines
5.1 KiB
Markdown
84 lines
5.1 KiB
Markdown
# 补充策略执行结果查询接口和前端页面
|
||
|
||
## 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
|
||
|
||
无。
|