# WorldQuant Alpha 研究系统

确认日期：2026-09-07。项目位于 `wq-alpha-system`，面向个人单个 WorldQuant 账户。

## 已确认范围

- 首期：个人信息与会话、Alpha 列表与详情、本地研究记录、可靠同步、Docker 部署。
- 当前扩展：全局右侧 AI 研究助手，自定义模型服务，通过查询工具及用户确认操作业务；具体范围见 [AI Chatbot 开发计划](ai-chatbot-plan.md)。
- 界面统一遵循 Lark Design Prototype，保留紧凑个人信息与登录体验；白色工作区、浅色导航、蓝色主操作及 4px 间距基准同样适用于 AI 面板、设置、结果与确认。
- Python + React + TypeScript + Semi Design，前后端分别位于 backend/ 和 frontend/，独立依赖与测试。
- PostgreSQL 存储数据，FastAPI 提供 OpenAPI 契约，HTTPX 统一异步调用 WorldQuant。
- React 19 使用 @douyinfe/semi-ui-19。Caddy 提供静态资源、API 代理与公网 HTTPS。
- 根目录包含两套完整 Compose、Dockerfile、Caddyfile、环境模板和部署说明。
- 从 WorldQuant 重新建立数据，不迁移旧库，不承担旧系统的兼容或维护。
- 平台数据只读；不回测、不触发检查、不修改平台属性、不正式提交。

## 首期产品能力

### 个人信息

系统登录与平台连接分开。单管理员，无开放注册；部署时设置初始密码，服务端哈希保存，HttpOnly Cookie 管理会话。
在个人页配置平台邮箱及密码，连接、重新连接、人工验证、断开与刷新资料。
平台凭据加密存储，解密密钥独立配置，不在前端持久化，也不进入日志或响应。
展示平台 ID、昵称、邮箱、身份与权限（以返回字段为准）、连接状态、最后同步时间。
展示平台会话剩余时长、提交与模拟活动、Alpha 数量概览；模拟每日 10,000 次为本地展示额度，按美东日期计算，缺失当日活动时不估算余额。已配置的连接表单默认收起。
提供本地显示名称、主题、时区和分页偏好，默认中文、浅色、Asia/Shanghai、25 条/页。
缺失资料显示“未提供”，不得虚构数据。

### Alpha 管理

- 主界面为侧栏、筛选区、可排序分页表格、列显隐、多选、详情抽屉；任务进度在独立面板查看。
- 列表以完整 flex 高度链填充可用区域，仅表体滚动，分页固定在底部；聊天展开后按剩余空间布局，保留编辑草稿。
- 全量同步已提交/未提交、隐藏/可见 Alpha；指定 ID 导入及选中刷新；仅手动触发。
- 筛选 ID/名称/表达式、地区、Universe、类型、语言、平台状态、隐藏、日期、核心指标、本地标签/状态/收藏。
- 展示 REGULAR/SUPER、FASTEXPR/PYTHON、Selection/Combo、完整 settings、IS/OS、已有 checks。
- PnL 按需获取、缓存、曲线展示、刷新；可打开 BRAIN 原页面。
- 本地备注、标签、收藏与研究状态单独保存，同步不能覆盖。研究状态：inbox/candidate/optimizing/archived。
- 批量加减标签及改研究状态；CSV 按当前筛选与排序导出全部结果，不限制为 500 条。
- 指标缺失保留 null，不伪装成零；本地研究状态与平台状态、检查结果分开。

### AI 研究助手

React + Semi Design + AI SDK UI 提供可调整宽度的聊天面板；FastAPI + Pydantic AI 管理独立异步执行，PostgreSQL 保存模型密文、会话、消息、执行及确认审计。用户明确选择 Chat Completions 或 Responses，能力测试通过后启用。AI 工具仅通过 `business.py` 共用业务模块读取本地数据、预览研究修改和同步操作；写入必须通过持久化确认，研究记录使用版本检查。会话历史由服务端决定，断线通过快照恢复，生成中断不重放写操作。

不引入 MCP、知识检索、多 Agent、向量库、Redis、额外容器、回测或平台回写。单管理员、单后端进程约束保持。模型不可用时现有业务仍可用。

## 模块与接口

模块为账户、Alpha、同步任务、WorldQuant 集成、AI 和数据目录。Alpha 与任务控制进入 `business.py`；范围化目录、研究备注和输入草稿进入 `catalog/service.py`，共用现有任务执行器。所有上游认证、会话、分页和退避集中封装。
页面读取本地数据库。`/api/v1/auth` 管理登录，`/account` 管理配置与资料，`/alphas` 管理查询及研究记录，`/alphas/{id}/pnl` 读取缓存，`/sync-jobs` 创建、查询、取消和重试任务。
长任务返回 job ID；前端轮询。首期单后端进程运行异步任务，任务及分页检查点持久化。
每页原子落库、按 Alpha ID 更新、失败重试及重启恢复；429 遵守 Retry-After，其余暂时性错误有界退避。
原始业务响应与结构化摘要分别保存，不存认证敏感字段。上游数据移动可能影响 offset 分页，通过 ID 去重及再次全量同步校正，不因一次未查到就删除本地记录。

## 路线图

| 阶段 | 能力 | 依据 |
| --- | --- | --- |
| 一 | 账户、列表、研究记录、同步、部署 | 本文件首期范围 |
| 一扩展 | AI 聊天、模型配置、只读业务工具、修改确认闭环 | [AI Chatbot 开发计划](ai-chatbot-plan.md) |
| 二 | 数据集/字段/算子、模板、批次队列、AST 校验、实验去重、暂停恢复 | 旧系统采样→密度→深度回测，以及 [回测台账](https://mail.google.com/mail/#all/19ea68a7dde5ceaa) |
| 三 | PnL 稳定性、比较、相关性、稳健性、跨区变体、Super Alpha 组合 | 旧系统有效分析能力 |
| 四 | 假设与实验记录、CLI/MCP、论坛检索与进一步的研究编排 | [决策摘要](https://mail.google.com/mail/#all/19fc16ce3f17311c)、[可复盘流程](https://mail.google.com/mail/#all/1a00ee69df671d4c) |
| 后续 | 平台回写、检查、提交、顾问表现 | 另行确认业务范围 |

AI 复用系统接口，不直接写数据库，模型可替换。论坛效果与阈值必须验证后才可成为规则。首期不提前建设后续空模块。

## 验收

1. 登录成功/失败、退出、越权防护；凭据不泄露，公网 HTTPS。
2. 平台连接、过期、人工验证、拒绝及网络错误。
3. 多页、重复、更新、429、部分失败、取消与重启恢复；同步保留本地研究记录。
4. 各 Alpha/语言类型、缺失指标和不同 PnL schema。
5. 筛选、分页、排序、批量编辑和超 500 条 CSV 导出一致。
6. Docker 空环境启动、重建持久化、备份恢复。
7. 模拟上游自动化测试后，使用真实账户只读联调；未验证部分如实记录。

完成标准：空部署后连接个人账户、同步 Alpha、查询和查看详情、维护本地研究记录，重启与再次同步后数据仍然可靠。