feat: add versioned research templates and alpha variants

2026-09-08 21:29:21 +08:00
parent b604e6050e
commit f89ae211d2
55 changed files with 5650 additions and 435 deletions
@@ -0,0 +1,39 @@
+# 第一阶段验收：模板与变体闭环
+
+日期：2026-09-08。状态：实现完成，本地验收通过；真实 WorldQuant 协议联调尚未完成，原因见末尾。
+
+## 交付内容
+
+- 数据与素材、研究实验、研究成果分组导航；数据目录、算子库、模板工坊、Alpha 变体、原回测研究和 Alpha 管理可直接进入。保留当前侧栏折叠、最近访问、快捷导航和全局助手。
+- 算子目录及独立本地收藏/备注；合法设置快照；字段详情可查询可用范围。字段级证据无法确认目标范围时不允许直接回测。
+- 模板稳定 ID、不可变版本、编辑/采样/展开、旧格式导入预览和同名冲突保护。随机采样直接访问组合空间，不先穷举。
+- 结构与字段变体、市场与设置变体；保存种子、输入、改动、模板版本及模型生成依据。每个候选保留实际输入引用，回测结果通过实验 ID 与 client_item_id 追溯。
+- 基线与候选比较：表达式、设置、指标快照、共同日期窗口 PnL；缺失指标不当作零。
+- 页面和 AI 共用研究服务；原 Chatbox 绑定使用共用表达式展开及语法/类型校验。所有手工回测继续先生成固定预览，再由用户确认。
+
+## 验收步骤与结果
+
+| 验收 | 步骤 | 结果 |
+|---|---|---|
+| 后端回归 | `backend/.venv/bin/pytest -q --tb=short` | 176 项通过；包含新增研究及原账户、目录、AI、回测、Alpha 测试 |
+| 追加类型边界 | 直接 VECTOR、非聚合算子使用 VECTOR、局部 VECTOR 后显式聚合；重跑研究相关测试 | 44 项研究相关测试通过；修复仅收紧本地类型校验 |
+| 组合空间 | 重复占位符；100^20 组合取 50 个随机候选；相同随机种子重复生成 | 数量受限、结果可复现；全组合超限返回错误 |
+| 版本与导入 | 保存 v1、更新 v2、重新读取 v1；并发旧版本写入；旧占位符转换及同名导入 | 历史不变，冲突返回 409，同名不覆盖 |
+| 生成与来源 | 固定输入→模板候选→原预览→合成模拟→Alpha 来源；父实验及目标市场输入 | 来源保留，可由实验 ID + 候选 ID 找到输入版本与种子 |
+| 字段和范围 | 未知字段、错误字段类型、跨市场独立输入、局部变量、字段级证据与目录矛盾 | 无法核实的候选保持待核实；不进入选定候选回测预览 |
+| 模型接口 | PydanticAI FunctionModel 返回结构化模板 | 单次请求；模型/配置版本/用量/输入上下文保存在模板版本，未调用真实模型 |
+| 比较 | 两条 Alpha 使用不同设置、缺失 Sharpe、部分重叠 PnL 日期 | 保留 null；仅共同日期且窗口起点归零；不同设置明确标识 |
+| 前端构建 | `pnpm --dir frontend build`、TypeScript 检查 | 通过；依赖 lottie-web 的既有 eval 提示不阻塞构建 |
+| 浏览器回归 | 项目 17 项 Playwright 用例，全新临时 SQLite、合成平台、独立 localhost 端口 | 17 项通过，覆盖账户、菜单、配置、AI、目录、回测、Alpha、多尺寸与恢复 |
+| 页面闭环 | 浏览器固定 TEST_FIN 输入，创建“阶段一浏览器验收模板”v1，生成两个候选，确认回测，查看结果后返回原实验 | 2/2 结果已保存，来源返回原实验及关联回测；创建候选时运行数量仍为 0 |
+| 算子备注 | 浏览器收藏 rank、保存备注、同步算子、重新选择 rank | 平台定义刷新后，本地备注和收藏仍在 |
+| PostgreSQL | 专用 PostgreSQL 17 容器中执行 `backend/tests/research_postgres.py`：0005→0006、Alembic schema check、旧研究备注、并发版本写入、重复回测启动 | 通过；旧备注/版本保留，两个并发启动返回同一运行 |
+| 备份恢复 | 专用库 pg_dump，恢复至新库；核对模板版本、实验、回测数量和旧备注 | 通过；未操作个人工作数据库 |
+
+## 交付边界与未完成验证
+
+本阶段没有上线部署、正式提交 Alpha、回写平台属性或调用真实模型。新增生成和模拟限定 REGULAR / FASTEXPR / EQUITY；其他已有 Alpha 展示不受影响。
+
+真实 WorldQuant 联调脚本已准备：仅向官方 API 认证，读取算子、OPTIONS 设置及字段可用性，不保存凭据。沙箱内请求返回 network_error；提权执行被自动审批两次拒绝，理由为审批器未认可任务目标记录中的外部账户授权。已在当前对话发出明确授权确认问题，等待回复。本报告不把合成协议测试视为真实平台联调通过。
+
+可用性协议无法识别时明确标为待核实。完整的目标范围目录及独立固定输入可以提供字段存在证据；若存在额外字段级证据，则要求同时满足。原始时间序列离线特征计算、官方检查/提交、旧运行搬迁均不在本阶段范围。
@@ -0,0 +1,17 @@
+# 四阶段研究迁移实现
+
+Status: ready-for-agent
+
+## 阶段
+
+- [x] 一：算子、模板、表达式模块、两类变体与回测来源闭环。
+- [ ] 二：特征方案、保存视图、关系、比较和评估。
+- [ ] 三：固定自动研究、预算、持久步骤、恢复。
+- [ ] 四：原生 QuantFlow 画布与共用执行。
+- [ ] 验证：后端、前端、浏览器、PostgreSQL 迁移与恢复。
+
+## Comments
+
+开始实现。工作区原有侧栏、配置抽屉、Alpha 页面及测试改动保留；主代理负责所有代码修改和最终验证。
+
+第一阶段已通过本地后端、浏览器和 PostgreSQL 验收；报告见 `../acceptance/stage-1.md`。真实 WorldQuant 联调因自动审批未认可已有授权而等待当前对话确认，不将合成测试记为真实联调。
@@ -0,0 +1,26 @@
+# 研究功能迁移
+
+Status: ready-for-agent
+
+用户于 2026-09-08 明确授权实现对话中的四阶段迁移方案。范围为模板与变体闭环、特征及成果管理、预算内自动研究、原生 QuantFlow。保留单账户、单进程、现有平台快照与回测契约。追加要求：逐阶段完成、每阶段提交代码并提供验收报告；允许读取 account.json 进行真实 WorldQuant 联调与模拟回测。不得输出凭据。不部署；不进行正式 Alpha 提交或平台属性回写。
+
+## 产品与接口
+
+侧栏按数据与素材（数据目录、算子库、模板工坊）、研究实验（特征工程、Alpha 变体、回测研究）、研究编排（研究流水线、QuantFlow）、研究成果（Alpha 管理）分组。个人信息走用户菜单。新增功能有完整业务后才公开入口。
+
+统一表达式解析、类型化变量、有限组合与可复现采样；模板稳定 ID、不可变版本和导入差异预览；变体记录种子、改动与多输入快照；评估保留规则、证据、模型建议及缺失项；研究产物以数据库引用传递。原生流程共用业务节点与现有回测调度，固定配方和画布共用运行实现。
+
+新增 `/api/v1/research` 与 catalog 元数据接口；保留旧 Chatbox 与回测接口。研究授权由服务端保存并核验，含有限轮数、模拟条目、模型调用预算及固定范围/方法/版本。每轮保存不可变回测预览。停止不承诺远端取消；未知提交不重提。新研究候选不直接创建平台 Alpha。
+
+## 界面约定
+
+scope_sketch: 紧凑研究页面，素材编辑、候选预览、结果和运行控制；空状态指向真实输入准备。
+lark_style_recipe: 沿用现有白色工作区、浅色侧栏、蓝色主操作及 4px 基准，复用 Semi 控件。
+ud_control_coverage: Button、Input、Select、Tabs、Table、Modal、SideSheet、Tag、Banner。
+right_rail_policy: 沿用现有 AI 与业务面板互斥规则，跨页保留草稿。
+icon_plan: 保留现有侧栏图标系统；新增页面以文字与原生控件为主，不新增装饰图标。
+media_decision: 不需要图片；QuantFlow 以可交互节点和连线表达流程。
+
+## 验证
+
+表达式边界、输入归属及跨市场可用性、不可变版本、导入冲突、基线及来源、规则不被模型覆盖；固定回测确认、预算扣减、重复启动、暂停恢复、未知提交、流程连接与事件幂等。隔离 HTTP/数据库测试、前端构建与浏览器闭环、PostgreSQL 迁移和备份恢复。真实上游协议另行联调。