worldquant-alpha-system/docs/verification.md

# 项目与 AI 助手验收记录

日期：2026-09-07。验证范围为本地实现、模拟 WorldQuant 上游、实际 PostgreSQL/Docker。未访问真实 WorldQuant 账户，没有调用平台回测、检查、属性修改或提交接口。

## 自动化与运行实测

| 检查 | 结果与证据 |
| --- | --- |
| 后端静态检查 | `uv run ruff check app tests` 通过 |
| 后端自动化测试 | `uv run pytest -q`：68 项通过 |
| 前端类型与生产构建 | `pnpm build` 通过；React 19.2.8、Semi UI 19 2.103.0，含 React 19 adapter |
| 浏览器验收 | `pnpm test`：4 项端到端测试通过，使用 620 条合成记录 |
| 空库部署与迁移 | Docker `web + backend + db` 从新卷启动成功，`alembic upgrade head` 成功 |
| 迁移与模型一致性 | PostgreSQL 上 `alembic check` 返回 `No new upgrade operations detected` |
| 持久化 | 强制替换三个容器后，服务端登录会话、Alpha、备注、标签与研究状态保留 |
| 备份恢复 | `pg_dump -Fc` 备份恢复到独立数据库，研究记录内容一致 |
| 数据库中断 | 后端不重启，单独停止/启动 PostgreSQL 后仍能消费新任务 |
| 公网配置 | 独立 Compose 正确配置 HTTPS Origin、Secure Cookie；db/backend 无宿主机端口；Caddy 配置校验通过 |
| 本机隔离 | Web 仅绑定 `127.0.0.1:8080`，数据库与后端只有容器网络端口 |

Docker 运行检查脚本为 `backend/tests/docker_acceptance.py`，仅允许操作独立 `wq-alpha-acceptance*` 项目。测试容器与测试卷已清理；合成数据不进入正式本机实例。

此前首期验收时，正式本机项目 `wq-alpha` 已启动于 `http://localhost:8080`，空库登录/退出、迁移一致性和健康检查通过；Alpha 与任务表初始均为 0，WorldQuant 尚未配置。初始凭据保存在权限为 `0600` 的项目 `.env` 中。本次 AI 开发未修改或重新部署该正式实例。

## 已覆盖行为

- 系统正确/错误登录、速率限制、未授权访问、退出失效、Cookie 到期、HttpOnly/SameSite/Secure、请求来源校验。
- WorldQuant 密码密文保存、不返回认证信息；嵌套 raw 业务数据过滤常见 token/cookie/secret 字段。
- 平台认证、Cookie 失效后共享重新认证、人工验证保留同一挑战会话、拒绝访问、网络错误、429/5xx、Retry-After 与数据准备等待。
- 多页同步、重叠 ID 去重、已有指标更新、每页检查点、部分失败/重试、取消、断开暂停、进程恢复及数据库恢复。
- 平台快照更新后，本地备注、标签、收藏、研究状态不变。固定状态与平台状态分别展示。
- REGULAR/SUPER、FASTEXPR/PYTHON、Selection/Combo、完整 settings、IS/OS、已有检查结果、缺失指标为 null。
- 不同 PnL 列顺序、对象型 schema、对象记录、毫秒时间戳、空值保留、未知 schema 报错；浏览器实际获取并绘制缓存曲线。
- 筛选、排序、分页与导出共用查询逻辑；后端筛选导出 599 条、浏览器下载 620 条，均不受列表页大小限制；CSV 文本公式转义。
- 批量标签、列显隐、固定列、分页、个人偏好保存与页面刷新保留；同步后台更新不会覆盖详情里尚未保存的备注。
- OpenAPI 记录 Cookie 鉴权和响应类型，包括错误、CSV、任务与 PnL。

## 页面核验

通过浏览器实际检查登录页、Alpha 列表、详情/PnL、个人信息页。截图在忽略目录 `output/playwright/`，截图中的 `TEST` Alpha、测试邮箱和统计数均为合成数据。生产 Web 使用 Caddy 提供构建后的静态文件。

构建仍有 Semi 间接依赖 `lottie-web` 的 `eval` 提示，构建成功；当前页面不使用该表达式动画能力，未放宽生产 CSP 的 `script-src`。端到端测试未发现 JavaScript 运行异常。

## AI 助手追加验收

AI SDK UI `6.0.277` / `@ai-sdk/react 3.0.280`、Pydantic AI slim `1.97.0` 均锁定精确版本；两种适配器使用锁定的 OpenAI SDK。新增范围与代码落点见 [AI Chatbot 开发计划](ai-chatbot-plan.md)。

| 检查 | 实际验证 |
| --- | --- |
| 两种模型协议 | 用真实 Pydantic AI/OpenAI SDK 适配器访问 HTTPX 模拟 SSE，分别通过回答、流式输出及随机标记工具往返 |
| 供应商错误 | 两种协议覆盖 401、404、429、超时、损坏帧、缺少结束帧、缺失工具能力；公开错误和测试日志未包含测试密钥或供应商错误正文 |
| 历史与授权 | Cookie 鉴权、过期确认拒绝、伪造历史/确认参数拒绝、相同请求 ID 去重与冲突、重新登录处理待确认记录 |
| 确认事务 | 研究修改、创建/取消/重试同步任务在确认前不写入，重复确认只执行一次；两次连续 deferred 确认能正确续答 |
| 冲突与批量 | 页面保存和 AI 确认使用版本 CAS；冲突不覆盖新记录；批量无效 ID 与部分版本冲突无部分写入 |
| 失败恢复 | 断开 SSE 不取消运行；显式取消、超时、请求预算；生成中断不重放，已提交操作即使续答失败仍保留在下一轮上下文 |
| 本地读取 | 搜索、详情、筛选选项、任务和 PnL 摘要；来源、时间和单位明确返回，空指标保留 null，缺失 PnL 可解释，完整序列不进入模型上下文 |
| 浏览器 | 配置、测试并启用；当前详情指代、筛选 15% 转为 0.15、固定结果卡片与应用筛选、确认后刷新并保留人工草稿、历史刷新恢复、页面切换/收起继续执行、窄屏、Esc、停止及退出失效 |
| 独立 Docker | 项目 `wq-alpha-acceptance-ai`，入口 `127.0.0.1:18089`，隔离 PostgreSQL 17；模拟模型仅在测试容器内监听，不调用真实供应商或 WorldQuant |
| Caddy SSE | 读取到文本帧时后端运行仍为 running；关闭连接后后台运行完成 |
| 跨重启确认 | 保存待确认记录后重建全部容器，配置密文及能力测试状态保留，确认可继续处理；重复确认版本只递增一次 |
| 备份与升级 | 自定义格式备份恢复到独立库，AI 会话/运行/工具确认/配置密文存在；仅对该测试恢复库降至 0001 再升级 head，原备注保持、version 初始化为 1，Alembic check 无差异 |

截图已人工查看：`output/playwright/ai-approval.png` 展示详情和聊天并排、修改差异及确认；`ai-query.png` 展示业务结果卡片和筛选操作。自动化使用合成文本，**没有验证真实模型的自然语言理解质量或真实供应商兼容性**。供应商不返回完整用量时显示“用量未提供”，不估算费用。测试快照与数据库备份均在忽略目录内。

## 待真实环境验证

这些项目需要用户自己的账户或域名，尚未取得实测证据：

1. 当前 WorldQuant 账户的实际认证、人工验证页面及权限限制。
2. 真实账户的完整 Alpha 分页、实际 REGULAR/SUPER/PYTHON 字段和 PnL schema。
3. 真实域名的 DNS、ACME 证书签发/续期和公网 HTTPS 访问。
4. 用户自定义供应商的真实 Base URL、API Key、模型权限、两种协议的兼容性以及工具选择效果。

真实模型联调步骤：保存自己的模型配置，分别检查回答、流式输出、测试工具；启用后对一个已同步 Alpha 做只读查询，再预览一次本地备注修改。核对目标和差异后确认，记录模型返回与业务结果。未配置之前不开展有费用的模型联调。

只读联调步骤：在正式本机页面登录并配置 WorldQuant，连接成功后先刷新个人资料、导入一个已知 Alpha ID、获取其 PnL，再执行全量同步。对一条记录保存本地备注后再次刷新，并重启后检查记录和任务。未完成上述步骤前，不把模拟测试结论视为真实平台兼容性保证。

## 已知架构边界

首期只有一个任务执行进程。长 Retry-After 会让后续任务排队，任务面板显示下次尝试时间并支持取消；不会为了缩短等待而提前请求平台。offset 分页遇到平台记录移动时可能遗漏，后续全量同步校正，单次未见记录不自动删除。数据库保存原始业务快照，后续研究、回测和 MCP 能力尚未实现。