# 首期验收记录

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

## 自动化与运行实测

| 检查 | 结果与证据 |
| --- | --- |
| 后端静态检查 | `uv run ruff check app tests` 通过 |
| 后端自动化测试 | `uv run pytest -q`：31 项通过 |
| 前端类型与生产构建 | `pnpm build` 通过；React 19.2.8、Semi UI 19 2.103.0，含 React 19 adapter |
| 浏览器验收 | `pnpm test`：2 项端到端测试通过，使用 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` 中。

## 已覆盖行为

- 系统正确/错误登录、速率限制、未授权访问、退出失效、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 运行异常。

## 待真实环境验证

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

1. 当前 WorldQuant 账户的实际认证、人工验证页面及权限限制。
2. 真实账户的完整 Alpha 分页、实际 REGULAR/SUPER/PYTHON 字段和 PnL schema。
3. 真实域名的 DNS、ACME 证书签发/续期和公网 HTTPS 访问。

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

## 已知架构边界

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