my-home/worldquant-alpha-system
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add scoped alpha sync and local self-correlation

Browse Source
This commit is contained in:
yuxuanhui
2026-09-08 10:40:49 +08:00
parent 404a4d8a04
commit d2ccd94721
28 changed files with 1656 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+11 -8
View File
@@ -1,6 +1,6 @@
# WorldQuant Alpha 研究工作空间
个人单账户系统。首期实现平台资料、Alpha 同步与查询、PnL 缓存、本地备注/标签/收藏/研究状态。平台接口只读，认证除外；不会回测、触发检查、回写属性或提交 Alpha。
个人单账户系统。实现平台资料、Alpha 分组同步与查询、PnL 缓存、本地自相关检测、本地备注/标签/收藏/研究状态。平台接口只读，认证除外；不会回测、触发平台检查、回写属性或提交 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 入口。前后端独立依赖、独立构建，所有部署文件位于根目录。
@@ -22,8 +22,10 @@ docker compose ps
1. 登录系统，在“个人信息”保存 WorldQuant 邮箱和密码，点击“连接 WorldQuant”。
2. 如平台要求人工验证，在显示的入口完成操作，再点击“继续验证”；后台保留同一挑战会话。
3. 在“Alpha 管理”手动同步平台数据，或导入指定 Alpha ID。任务面板显示进度、错误、取消和重试。
4. 点击 Alpha 打开详情。研究记录保存在本地；PnL 点击获取后缓存。下次同步会更新平台数据并保留本地研究记录。
3. 在“Alpha 管理”切换“待提交 / 已提交”。待提交先选创建日期范围，按天同步；已提交可选提交日期范围按天同步，或全量同步。相同起止日期表示单日，日期边界为 UTC，均包含隐藏记录。也可导入指定 Alpha ID。任务面板显示当前日期、进度、错误、取消和重试。
4. 点击 Alpha 打开详情。研究记录保存在本地；PnL 点击获取后缓存。详情的“本地自相关”可发起检测，列表也可选中最多 100 条批量检测。建议先全量同步已提交 Alpha，建立比较基准。下次同步会更新平台数据并保留本地研究记录。
本地自相关只与本地已同步、同地区的已提交 Alpha 比较，排除自身。使用累计 PnL 的日变化，在目标最新数据日往前四年的共同窗口计算 Pearson 相关系数，至少需要 30 个共同有效样本；带符号最大值达到 0.7 时提示相关性偏高。这是本地规则，不等同于平台检查。PnL 缓存缺失时自动补取；样本不足、常量序列和不可用基准会明确显示，不能当作通过。结果独立保存，相关 PnL、地区或基准成员变化后标记为“待重算”。
平台未返回的资料与指标保留为空。数值筛选采用平台原始单位，例如 Turnover `0.15` 表示 15%。日期筛选边界为 UTC；时间显示采用个人页的时区偏好。
@@ -100,7 +102,7 @@ docker compose logs --tail=100 backend
## 备份与恢复
以下为本机配置命令；公网统一补上 `-f compose.public.yaml`，自定义项目名时保持相同 `-p`。数据库备份包括平台快照、研究记录及版本、账户密文、模型配置密文、AI 会话/消息/执行/工具确认记录和同步任务。备份文件仍属于私有数据。
以下为本机配置命令；公网统一补上 `-f compose.public.yaml`，自定义项目名时保持相同 `-p`。数据库备份包括平台快照、研究记录及版本、本地自相关结果、账户密文、模型配置密文、AI 会话/消息/执行/工具确认记录和同步任务。备份文件仍属于私有数据。
```bash
mkdir -p backups
@@ -148,7 +150,7 @@ pnpm exec playwright install chromium
pnpm test
```
浏览器测试自动启动临时数据库、模拟平台 API 和 Vite，使用 620 条明确标记 `TEST` 的合成 Alpha。不会向正式数据库写入样例。测试验证模型配置、查询卡片、修改预览及确认、草稿冲突、收起及刷新恢复、取消，以及系统登录、账户连接、多页同步、SUPER 详情、备注与收藏在刷新后保留、PnL、超过 500 条 CSV 及退出。截图写入忽略目录 `output/playwright/`。
浏览器测试自动启动临时数据库、模拟平台 API 和 Vite，使用 620 条明确标记 `TEST` 的合成 Alpha。不会向正式数据库写入样例。测试验证模型配置、查询卡片、修改预览及确认、草稿冲突、收起及刷新恢复、取消，以及系统登录、账户连接、双 Tab、按日及全量同步、本地自相关保存、SUPER 详情、备注与收藏保留、PnL、分组 CSV 导出及退出。截图写入忽略目录 `output/playwright/`。
需要重跑 Docker 持久化和备份验收时，创建独立测试环境，并在测试 env 文件中选择空闲 `LOCAL_PORT`（例如 18089），无需停止正式实例。以下脚本只接受 `wq-alpha-acceptance*` 项目名：
@@ -182,14 +184,15 @@ FastAPI 的 `/openapi.json` 与 `/docs` 可在后端开发端口访问；生产
- `/api/v1/account`：偏好、加密凭据、连接/验证/断开/资料刷新。
- `/api/v1/alphas`：服务端筛选与排序、详情、本地研究记录、批量编辑、流式 CSV。
- `/api/v1/alphas/{id}/pnl`：只读缓存；刷新通过 `pnl_refresh` 任务。
- `/api/v1/alphas/{id}/self-correlation`：读取本地检测结果；检测通过 `self_correlation` 任务。
- `/api/v1/sync-jobs`：创建任务立即返回 202 和 ID，查询、取消与重试。
- `/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` 分开存储。研究状态固定为 `inbox/candidate/optimizing/archived`；平台类型、语言、状态按原值显示。
写请求需 `X-WQ-Request: 1`；浏览器跨站写入被拒绝。Alpha 平台快照、`research` 本地研究、`pnl_cache`、`self_correlations` 本地检测结果分开存储。`0003` 迁移只新增检测结果表。研究状态固定为 `inbox/candidate/optimizing/archived`；平台类型、语言、状态按原值显示。
同步按“未提交/已提交 × 可见/隐藏”分页，每页数据与检查点同事务提交，Alpha ID 幂等更新。失败任务保留进度，重试只处理剩余页或失败 ID。上游 `Retry-After` 等待可被取消。分页过程中平台记录移动可能造成重复或遗漏，通过 ID 去重和再次全量同步校正；单次没有查到不自动删除本地记录。
列表及导出支持 `submission=UNSUBMITTED|SUBMITTED`，平台状态缺失时不推断为已提交。`daily_sync` 必须提供分组及 `date_from` / `date_to`，每个 UTC 日期分别分页获取可见、隐藏记录；新建 `full_sync` 只同步已提交。旧的无分组全量任务保持原范围恢复。每页数据与检查点同事务提交，Alpha ID 幂等更新。失败任务保留进度，重试只处理剩余页或失败 ID。上游 `Retry-After` 等待可被取消。分页过程中平台记录移动可能造成重复或遗漏，通过 ID 去重和再次同步对应范围校正；单次没有查到不自动删除本地记录。
## 日志排查与验证边界
@@ -205,4 +208,4 @@ curl -f http://localhost:8080/api/v1/health
AI 模型兼容性由模拟 Chat Completions/Responses HTTP 流与真实 SDK 适配器验证；未配置真实供应商前，不能保证其工具选择质量、模型权限或网关兼容性。真实联调请分别记录流式回答与业务工具调用是否成功。
实现使用旧项目已知请求形态并对模拟上游做自动化验证。WorldQuant 当前真实账号权限、人工验证页面行为、实际数据 schema、真实账户全量同步及公网证书签发，均需要在自己的账户/域名完成只读联调；未取得该证据前不宣称已验证。验收实测结果见 [验收记录](docs/verification.md)。
实现参考旧项目请求形态，并对模拟上游做自动化验证。新增日期筛选参数、WorldQuant 当前真实账号权限、人工验证页面行为、实际数据 schema、真实账户同步及公网证书签发，均需要在自己的账户/域名完成只读联调；未取得该证据前不宣称已验证。验收实测结果见 [验收记录](docs/verification.md)。