worldquant-alpha-system/.scratch/backtest/spec.md

WorldQuant 通用回测模块

Status: ready-for-agent

用户已确认实施：长期仅 WorldQuant，首版 REGULAR + FASTEXPR，核心 + 基础页面 + AI，每次固定研究运行确认一次。实现进度与验证见 issues/01-implementation.md。

能力与边界

保留候选草稿、固定集合预览、来源归组、兼容参数分组切批、账户共享补位、暂停继续、逐项结果与错误找回、持久历史。模板采样、密度评估、减枝和下一轮生成由调用方承担。无旧库迁移、CLI/MCP、多平台、SUPER/PYTHON、AST 语义检查、平台属性回写或正式提交。

契约与可靠性

BacktestRun 记录确认后的固定集合；BacktestItem 保存表达式及完整 settings；SimulationAttempt 保存提交阶段、成员与平台引用；BacktestResult 保存独立历史快照并关联 Alpha。候选草稿与不可变预览分开，启动请求幂等，重复实验仅提示不复用。来源可关联业务批次、模板输入、研究执行和 AI 会话。

公共业务模块供 REST /api/v1/backtests、AI 及后续研究流程共用。支持配置、草稿、预览、启动、运行/结果/增量事件查询、暂停、继续、停止剩余项、恢复及生成重跑预览。所有真实模拟由已确认运行驱动。

同步与回测通道共用运行时和账户会话；所有回测来源共用单账户调度。按运行轮转补位，不跨运行混批。初始本地并发 3、每批 8，持久化调整，非平台额度声明。按 region/delay/language/instrumentType 分组。

先持久化提交意图，再发送；提交结果未知不得重提。已知 progress URL 继续查询，详情与保存失败只补取/补存。不能按成功数组位置配对：按完整输入匹配，证据不足待核对。暂停停止后续提交，停止跳过尚未提交项；两者均继续收集远端结果。不宣称远端取消。

平台状态、收集状态和持久化状态分离，缺失指标 null；Alpha 更新、结果关联、增量事件同事务。历史快照不随日后 Alpha 同步变化。每日 10000 展示值不用于配额判断。

页面与 AI

scope_sketch：回测运行表格、候选编辑/固定预览、结果详情；紧凑研究工作区。 lark_style_recipe：沿用现有白色工作区、浅色导航、蓝色主操作、4px 间距、轻边框、正文常规字重。 ud_control_coverage：Semi Button/Input/TextArea/Select/Table/SideSheet/Pagination/Tag；不添加装饰图片和图标。 layout_signature_usage：复用左导航与顶部栏；操作位于内容顶部，详情按需展开；不新增 Hero/KPI 墙。 right_rail_policy：窄屏 AI 与业务抽屉互斥，保留候选编辑草稿。 emphasis_budget：标题 500–600，正文/表格/操作 400。 media_decision：纯研究操作页面不需要插画或媒体；新增功能使用文字操作。

AI 通过同一业务接口准备固定预览、请求一次确认并创建运行；不循环等待，不自动开展下一轮。返回服务端引用、分页摘要、单位与来源时间；停止生成不取消回测。模型未配置时页面独立可用。

验证

在平台 HTTP 边界模拟：混合分组、单/批响应、轮转、部分成功/乱序/缺失、重复启动和确认、暂停停止、动态并发、429/认证/超时/未知提交、结果补取、重启和数据库失败。页面串联真实业务与数据库验证草稿→预览→确认→结果，AI 确认前无运行，重复确认唯一执行。回归原后端、前端、浏览器，验证迁移及持久化。真实平台联调单独获授权，不以模拟测试宣称实际协议和限额已验证。

对接约定

1. GET /capabilities 读取支持类型、参数 schema 和本地限制。POST /previews 接受 inline: {name, source, candidates}，或 draft_id 与 draft_version；每个候选提供唯一 client_item_id、expression、完整 settings。
2. 分页 GET /previews/{id} 核对固定输入；POST /previews/{id}/subset 用 exclude_ids 创建新预览，不修改原集合。
3. POST /runs 提交 preview_id、version、idempotency_key，返回 202 和 backtest_run_id。同一预览只能启动一次；再次实验创建新预览，重复指纹不复用历史结果。
4. GET /runs/{id}/results 读取逐项快照；GET /runs/{id}/events?after=0&limit=100 增量读取，保存 next_cursor，按 has_more 继续。事件与结果同事务，事件携带变化引用，消费者按引用读取结果。
5. POST /runs/{id}/control 提供 action 与当前运行 version；动作包括 pause/resume/stop/recover。明确失败项使用 POST /runs/{id}/rerun-preview 和 item_ids 准备新实验。

所有路径均带 /api/v1/backtests 前缀，沿用管理员会话和 X-WQ-Request: 1。完整参数类型由 backend/app/backtests/contracts.py 和 OpenAPI 提供。AI 仅启动与控制需要确认，准备预览不发起模拟；大集合使用草稿/预览引用。

提交阶段以持久化 submitting 为分界：暂停/停止只处理 queued，已进入 submitting 的请求不能承诺撤销。重启时没有平台引用的 submitting 进入 needs_review；用户可在页面补入原模拟 URL，服务端限制同源并核对输入。不确定执行保守占用远端槽位，已确认所有子项终态则释放槽位，即使详情补取失败。

相同完整输入拆到不同执行尝试，避免平台返回同一表达式时不能唯一配对；不同输入批量返回按表达式与 settings 证据匹配，不采用数组位置。缺失子引用可重新读取父模拟，保留已保存结果。BacktestResult.complete 表示已取得详情快照，不表示所有指标存在或研究筛选通过。