feat: add durable WorldQuant backtests with UI and AI confirmation

.scratch/backtest/spec.md

@@ -0,0 +1,51 @@
+# 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` 表示已取得详情快照，不表示所有指标存在或研究筛选通过。