开发指南
测试
分层执行契约、单元、Workers、API 和桌面/移动 E2E，验证编译后的 Worker。
分清验证层级
类型通过不代表接口可用；本地 Worker 通过不代表真实支付或邮件已经验收。记录每次运行对应的源码提交、命令、结果和未验证项，不能沿用旧提交的通过数字证明新版本。
本地准备
使用 Node 22.12+、pnpm 10.26.2，先执行：
pnpm install --frozen-lockfile
pnpm muse:initAPI 与浏览器测试使用初始化后的本地应用，测试配置默认 http://localhost:3000。已有本地开发服务可以被复用；确认它来自当前仓库与提交。单元和 Workers 测试不应偷偷请求真实支付或远程 AI。
按顺序执行
pnpm check:contracts
pnpm check:error
pnpm test:unit
pnpm test:workers
pnpm build
pnpm type-check
pnpm test:api
pnpm test:e2e| 命令 | 证明什么 |
|---|---|
| check:contracts | 受保护合约和仓库约束未被意外破坏 |
| check:error | Biome 规范检查 |
| test:unit | 配置、业务函数及边界行为 |
| test:workers | 本地 Worker runtime 与隔离 D1 行为 |
| build | Vite / TanStack / Cloudflare 编译及生成产物 |
| type-check | TypeScript；首次拉取时先 build 生成路由与 Paraglide |
| test:api | HTTP、权限与服务响应 |
| test:e2e | Desktop 与 Chromium 移动视口交互 |
首次 type-check 缺生成模块时先完成 build，而不是手工补一份空文件。Workers 测试使用隔离数据库，不应指向生产 D1。
验证编译后的 Worker
停止自己启动的 3000 端口开发服务，构建后在 PowerShell 执行：
$env:FLARE_TEST_PREVIEW = '1'
pnpm exec playwright test
Remove-Item Env:FLARE_TEST_PREVIEW测试配置会启动 pnpm preview，并禁用复用普通 dev 服务。不要占着同一端口再运行 preview，也不要误把 dev 的通过记录成编译产物通过。若显式设置 FLARE_TEST_URL，则测试使用该地址而不启动服务；除非有明确验收授权，不要将测试指向公共演示或真实生产。
必测交互
- 默认邮箱验证码登录、新邮箱注册、密码入口、重置、OAuth 和两步验证。
- 两个用户的文件/订单/任务隔离，Key 创建、调用及删除后失效。
- 文件上传、下载、删除、大小/MIME/配额失败。
- AI 逐段输出、余额不足、摘要任务、失败补偿与重复投递。
- 管理员表格在已加载范围内筛选分页，角色、退款、重放与确认对象。
- 中英文、浅色/深色/系统、键盘操作、移动抽屉与整页溢出。
场景定义见源码 tests/e2e/SCENARIOS.md；修改行为时同步场景与断言，不写只复述组件实现的测试。
真实服务验收
单独记录自己的部署 origin、health 环境、HTTPS 回调、真实邮件收件、每个已启用网关的 sandbox 支付和 Webhook、真实 AI 与队列结果。CLI smokePassed 与人工 verified 是不同字段。