merge: integrate alpha management with main and sequence migration 0005

README.md

@@ -1,6 +1,6 @@
 # WorldQuant Alpha 研究工作空间
 
-个人单账户系统。实现平台资料、Alpha 分组同步与查询、PnL 缓存、本地自相关检测、本地备注/标签/收藏/研究状态。平台接口只读，认证除外；不会回测、触发平台检查、回写属性或提交 Alpha。
+个人单账户系统，提供平台资料、Alpha 分组同步与查询、PnL 缓存、本地自相关检测、本地研究记录、数据目录、AI 助手及通用回测。回测支持 REGULAR + FASTEXPR；不触发平台检查、不回写属性、不正式提交 Alpha。
 
 需求与后续路线图见 [项目方案](docs/project-plan.md)，AI 助手范围见 [开发计划](docs/ai-chatbot-plan.md)。前端 React 19 + TypeScript + Semi Design，后端 Python 3.12 + FastAPI + HTTPX + SQLAlchemy，PostgreSQL 保存数据，Caddy 提供 Web 入口。前后端独立依赖、独立构建，所有部署文件位于根目录。
 
@@ -33,6 +33,20 @@ docker compose ps
 
 工作空间和 AI 交互统一采用紧凑的 Lark 样式。Alpha 列表只滚动表体，分页保持在可用区域底部；个人信息页独立滚动。
 
+## 数据集与数据字段
+
+从侧栏进入“数据集”，设置 Region、Universe、Delay 后手动同步目录。范围选项表示本版支持的组合，平台账户实际权限以同步结果为准；分类和子分类来自已同步数据。
+
+选中一个数据集后默认使用整集字段；首次使用先同步全部字段。字段列表、搜索、类型、覆盖率、排序及翻页均不改变输入范围，只有明确取消勾选才排除字段。表头选择作用于整个已完成集合，支持恢复全选。字段与详情采用 75% / 30% 的工作区右抽屉，窄屏展开为全宽；逐层关闭保留父层条件。抽屉顶部可打开 AI 助手，业务抽屉暂时隐藏，收起助手后恢复；不会发送字段或研究备注给模型。
+
+“用于 Alpha 模板”目前进入**保存输入草稿**，尚未接入模板编辑器或回测。草稿在服务端固定数据集、研究范围、集合版本、字段 ID 和字段类型，可通过“已保存输入”查看。后续同步不会改变旧草稿。
+
+数据集和字段备注单独保存，版本冲突保留当前草稿。字段同步沿用已有任务面板的进度、取消、重试、等待连接和人工验证；每页与检查点同事务保存。只有完整分页成功才发布新集合，失败或取消继续使用上一版；首次未完成时不可准备输入。异常字段归属、覆盖率单位或分页协议会失败，不以部分字段代替全集。
+
+增量迁移 `0003` 只增加目录、集合、备注与输入表，不改写旧迁移。`/api/v1/catalog` 提供带会话和来源校验的目录/字段查询、完整集合成员、备注、同步创建和输入草稿接口；创建目录同步返回任务 ID，查询、取消及重试仍使用 `/api/v1/sync-jobs`。新任务 `payload` 显式记录范围及数据集，保留旧 Alpha 任务契约。
+
+真实 WorldQuant 数据集 schema、字段所属数据集信息、0–1 覆盖率单位、范围权限和分页协议尚需只读联调。当前证据来自 HTTP 边界合成数据和隔离 PostgreSQL，不代表已验证真实平台兼容性。
+
 ## AI 研究助手
 
 1. 在“个人信息 → 大模型服务”填写 Base URL、API Key、模型标识，明确选择 Chat Completions 或 Responses。
@@ -47,7 +61,19 @@ docker compose ps
 
 面板收起、切换会话和网络断开不会停止后端执行。刷新后从服务端历史与快照恢复，活动执行每 3 秒更新；不提供逐 token 续传。“停止生成”请求后端取消，再关闭前端接收。服务重启会将生成中的轮次标记为中断，不自动重放；待确认记录在重新登录后仍可处理，但重新检查版本。模型配置变更后，旧的待确认轮次需停止并重新预览。
 
-模型不可用或未配置时，原有业务功能继续使用。API Key 仅加密存储于数据库，不返回浏览器；发送聊天时，相关本地业务结果会发送至你指定的模型服务。首版没有 MCP、知识检索、回测、多 Agent 或平台回写。
+模型不可用或未配置时，原有业务功能继续使用。API Key 仅加密存储于数据库，不返回浏览器；发送聊天时，相关本地业务结果会发送至你指定的模型服务。没有 MCP、知识检索、多 Agent 或平台属性回写。回测使用独立的固定集合确认，详见下文。
+
+## 通用回测
+
+在“回测”页录入表达式及明确参数，保存候选草稿或直接预览；支持逐项 JSON 输入。预览固定完整集合，显示分组、分批和历史重复提示；排除候选会生成新预览。确认启动立即返回运行，后台负责执行及收集。AI 使用同一预览与启动契约，每次运行确认一次；关闭聊天不终止回测。
+
+默认本地并发 3、每批最多 8 条，可在页面调整；并发影响后续补位，批大小在预览时固定。这是本系统调度配置，不是平台已验证额度。各研究来源轮转共享账户预算，同步仍能独立执行。
+
+暂停阻止尚未进入提交阶段的批次，停止把这些剩余项标为跳过；已经持久化提交意图的执行可能已发出，继续收集结果。详情失败通过“找回结果”补取原模拟；明确失败项通过新预览重跑。提交结果未知时不会自动重提，在执行记录中补入同一平台的原模拟 URL 后核对。无引用的未知执行保守占用预算。
+
+结果保存独立历史快照，后续同步不改写；缺失指标保持 null。基础页面不依赖模型。迁移 `0004` 新增回测表，保留已有数据。备份需包括草稿、预览、运行、执行尝试、结果和增量事件；恢复优先查询已知平台引用。
+
+公共接口位于 `/api/v1/backtests`，对接与验证记录见 [实施规格](.scratch/backtest/spec.md) 和 [回测验收记录](.scratch/backtest/verification.md)。真实平台权限、当前协议与限额尚未联调。
 
 ## 公网 HTTPS 部署
 
@@ -186,11 +212,12 @@ FastAPI 的 `/openapi.json` 与 `/docs` 可在后端开发端口访问；生产
 - `/api/v1/alphas/{id}/pnl`：只读缓存；刷新通过 `pnl_refresh` 任务。
 - `/api/v1/alphas/{id}/self-correlation`：读取本地检测结果；检测通过 `self_correlation` 任务。
 - `/api/v1/sync-jobs`：创建任务立即返回 202 和 ID，查询、取消与重试。
+- `/api/v1/backtests`：候选草稿、不可变预览、异步启动、运行/结果/事件分页、调度配置、暂停/继续/停止/找回及重跑预览。
 - `/api/v1/ai`：脱敏模型配置与测试、会话历史、SSE 执行、执行快照、取消及确认。新执行只接收 `request_id`、`message`、`context`；同一会话重复请求 ID 返回原运行，参数变化返回 409。
 
 研究记录 PATCH 现在必须提供读取时的 `version`；批量编辑必须提供每个目标 ID 的 `versions` 映射。`0002` 迁移给旧研究记录设置初始版本 1，不修改其内容。版本冲突返回 409。
 
-写请求需 `X-WQ-Request: 1`；浏览器跨站写入被拒绝。Alpha 平台快照、`research` 本地研究、`pnl_cache`、`self_correlations` 本地检测结果分开存储。`0003` 迁移只新增检测结果表。研究状态固定为 `inbox/candidate/optimizing/archived`；平台类型、语言、状态按原值显示。
+写请求需 `X-WQ-Request: 1`；浏览器跨站写入被拒绝。Alpha 平台快照、`research` 本地研究、`pnl_cache`、`self_correlations` 本地检测结果分开存储。`0005` 迁移只新增检测结果表。研究状态固定为 `inbox/candidate/optimizing/archived`；平台类型、语言、状态按原值显示。
 
 列表及导出支持 `submission=UNSUBMITTED|SUBMITTED`，平台状态缺失时不推断为已提交。`daily_sync` 必须提供分组及 `date_from` / `date_to`，每个 UTC 日期分别分页获取可见、隐藏记录；新建 `full_sync` 只同步已提交。旧的无分组全量任务保持原范围恢复。每页数据与检查点同事务提交，Alpha ID 幂等更新。失败任务保留进度，重试只处理剩余页或失败 ID。上游 `Retry-After` 等待可被取消。分页过程中平台记录移动可能造成重复或遗漏，通过 ID 去重和再次同步对应范围校正；单次没有查到不自动删除本地记录。