Files
user-system/docs/team/PRODUCTION_CHECKLIST.md

234 lines
12 KiB
Markdown
Raw Normal View History

# 生产级发布清单
版本3.0
更新时间2026-04-02
本清单用于发布前、发布后和对外表述前的最后核查。
## 0. PR 提交前检查(必须通过)
### 0.1 分支与提交
- [ ] 功能分支从 `main` 最新状态拉取
- [ ] 每个提交是可独立验证的最小单元
- [ ] 提交信息格式:`类型: 简短描述`
### 0.2 代码审查
- [ ] 至少 1 人完成代码审查
- [ ] 所有 🔴 阻塞问题已修复
- [ ] 所有 🟡 建议问题已有修复计划
### 0.3 验证矩阵
- [ ] 后端:`go test ./... -count=1` 通过
- [ ] 后端:`go vet ./...` 通过
- [ ] 后端:`go build ./cmd/server` 通过
- [ ] 前端:`npm.cmd run lint` 通过
- [ ] 前端:`npm.cmd run build` 通过
- [ ] 前端:`npm.cmd run test -- --run` 全绿(如改动前端代码)
- [ ] 真实浏览器 E2E`npm.cmd run e2e:full:win` 通过(如涉及认证/导航/主流程)
### 0.4 文档
- [ ] PR 描述包含变更目的、验证命令及结果、影响范围
- [ ] API 文档已更新(如改动 API
- [ ] `docs/status/REAL_PROJECT_STATUS.md` 已同步更新(如改变真实结论)
---
## 1. 发布前必须完成
### 1.1 代码与构建
- [ ] `go test ./... -count=1`
- [ ] `go vet ./...`
- [ ] `go build ./cmd/server`
- [ ] `cd frontend/admin && npm.cmd run lint`
- [ ] `cd frontend/admin && npm.cmd run build`
### 1.2 真实浏览器验证
- [ ] `cd frontend/admin && npm.cmd run e2e:full:win`
- [ ] 本轮改动涉及认证、路由、导航、弹窗、防线或主流程时,不得跳过真实浏览器回归
### 1.3 运行时规则核查
- [ ] 非测试代码中无 `panic`
- [ ] 运行时无 mock provider / fake success 路径
- [ ] `smoke` 仅用于诊断,不是运行时依赖
- [ ] 敏感接口仍带 `no-store` 等防缓存头
- [ ] 邮件、短信、文件上传、外部调用均为 fail closed
### 1.4 配置与安全核查
- [ ] release 模式下无占位密钥
- [ ] release 模式下无 localhost OAuth 回调
- [ ] release 模式下无 `*` CORS 放行
- [ ] 真实密钥来自环境变量或密钥管理系统
## 2. 可选但建议同时检查
- [ ] `cd frontend/admin && npm.cmd run test:run`
- [ ] 已同步检查 `docs/status/REAL_PROJECT_STATUS.md`
- [ ] 已同步检查是否需要补证据文档
## 3. 不能夸大的结论
满足本清单,不等于自动满足以下结论:
- [ ] 完整 OS 级自动化已闭环
- [ ] 真实第三方 OAuth live 验证已闭环
- [ ] 外部 Secrets/KMS 已闭环
- [ ] 多环境 CI/CD 密钥分发已闭环
- [ ] 跨历史版本 schema downgrade 回滚证据已闭环
如果上述材料未齐备,必须在发布说明中明确列为剩余缺口。
## 4. 当前项目的主验收路径
当前受支持的真实浏览器主验收路径:
```powershell
cd D:\project\frontend\admin
npm.cmd run e2e:full:win
```
当前可诚实表述的边界:
- 已完成浏览器级真实 E2E 收口
- 未完成完整 OS 级自动化收口
## 5. 发布后 30 分钟内检查
- [ ] 核心登录/登出链路正常
- [ ] 后台主导航正常
- [ ] 关键日志无新增异常
- [ ] 无异常弹窗、popup、page error、401 回归
- [ ] 健康检查正常:
- `GET /health`
- `GET /health/live`
- `GET /health/ready`
## 6. 2026-04-10 多轮 Review 补充检查项
### 6.1 RBAC / 管理员治理改动
- [ ] 涉及 `GetUserRoles``AssignRoles``CreateAdmin``DeleteAdmin`、角色表单或管理员页的改动时,已验证越权读取失败、越权修改失败。
- [ ] 已验证不可自删管理员、不可删除最后一个管理员、不可把系统带入无管理员状态。
- [ ] 已验证角色赋权、管理员创建、管理员删除具备事务性;若失败,数据库状态可回滚到操作前。
- [ ] 已验证未引入绕过 bootstrap 或 service 校验链路的硬编码角色 ID 或默认角色假设。
### 6.2 主入口与测试洁净度
- [ ] 文档声明的主入口命令本身已跑通:`go test ./... -count=1``cd frontend/admin && npm.cmd run e2e:full:win`
- [ ] 若包装脚本、临时缓存、工作目录切换或环境注入失败,已按真实失败处理,而不是拿局部命令绿灯代替。
- [ ] `cd frontend/admin && npm.cmd run test:run``cd frontend/admin && npm.cmd run test:coverage` 运行后,无 `window.alert``window.confirm``window.prompt``window.open` 调用和 jsdom `Not implemented` 噪声。
- [ ] 如本轮改动把 stub、`not implemented` 或 mock 接口切换为 live 实现,已补充负向权限测试、边界条件测试、失败回滚测试。
## 2026-04-23 Latest Gate Snapshot
Use this section as the current release-facing snapshot for the workspace. If older notes elsewhere in this file conflict with this section, use this snapshot first.
### Re-verified Commands
- `cd frontend/admin && npm.cmd run test:run -- src/pages/admin/DevicesPage/DevicesPage.test.tsx`
- `cd frontend/admin && npm.cmd run test:run -- src/services/webhooks.test.ts`
- `cd frontend/admin && npm.cmd run test:run -- src/pages/admin/WebhooksPage/WebhooksPage.test.tsx`
- `cd frontend/admin && npm.cmd run test:run -- src/services/social-accounts.test.ts`
- `cd frontend/admin && npm.cmd run test:run -- src/services/settings.test.ts src/pages/admin/SettingsPage/SettingsPage.test.tsx src/pages/admin/ImportExportPage/ImportExportPage.test.tsx`
- `cd frontend/admin && npm.cmd run lint`
- `cd frontend/admin && npm.cmd run build`
- `cd frontend/admin && npm.cmd run e2e:full:win`
### Current Honest Release Conclusion
- The supported browser-level acceptance path `cd frontend/admin && npm.cmd run e2e:full:win` is green again in the current workspace.
- The latest green browser run included `admin-bootstrap`, `public-registration`, `email-activation`, `login-surface`, `auth-workflow`, `responsive-login`, `desktop-mobile-navigation`, `user-management-crud`, `user-management-batch`, `role-management-crud`, `device-management`, `login-logs`, `operation-logs`, `webhook-management`, `import-export`, `profile-and-security`, `settings`, and `dashboard-stats`.
- This evidence is sufficient for the supported browser-level gate, but it does not by itself replace the backend full matrix (`go test ./... -count=1`, `go vet ./...`, `go build ./cmd/server`).
- This snapshot also does not prove OS-level automation, live third-party OAuth validation, or external secrets/KMS delivery evidence.
## 2026-04-23 Additional Browser Gate Checks
- [ ] Cursor or list-page changes include a regression proving initial load does not self-trigger `next_cursor` pagination or burst extra requests.
- [ ] Frontend service changes against admin APIs verify exact response-envelope fields in service tests, not only page rendering.
- [ ] Frontend services using the shared HTTP client do not unwrap `data` twice; service tests reflect the real `request()` contract.
- [ ] Playwright selector changes prefer route, heading, role, or labeled-control locators over broad text searches.
- [ ] If suite retry reuses the same backend state, bootstrap or similar one-time preconditions are re-evaluated before rerunning browser scenarios.
- [ ] If a late-suite E2E failure blocks release, the release note records whether the root cause was product behavior, contract drift, selector drift, or browser-runtime instability.
## 2026-04-23 Password Reset Gate Snapshot
### Latest Green Evidence
- `go test ./... -count=1`
- `go vet ./...`
- `go build ./cmd/server`
- `cd frontend/admin && npm.cmd run test:run`
- `cd frontend/admin && npm.cmd run lint`
- `cd frontend/admin && npm.cmd run build`
- `cd frontend/admin && node --check ./scripts/run-playwright-cdp-e2e.mjs`
- `cd frontend/admin && npm.cmd run e2e:full:win`
### Current Honest Release Conclusion
- The current supported browser-level gate is green with `19` scenarios and now includes `password-reset`.
- The same branch state also re-proved the backend full matrix and the frontend unit/lint/build matrix.
- This still does not prove OS-level automation or live third-party OAuth/secrets delivery.
### Additional Checklist Items
- [ ] If a public auth route is conditionally mounted, `/api/v1/auth/capabilities` exposes the same availability bit from the same source of truth.
- [ ] A newly added auth or session browser flow is only accepted after both its targeted run and the full supported browser gate are green.
- [ ] When CDP loses the persistent page late in the suite, fix runner recovery before classifying the gate as inherently flaky.
## 2026-04-23 Permissions CRUD And Full Matrix Snapshot
Use this section first if earlier 2026-04-23 notes in this file conflict with it.
### Latest Green Evidence
- `go test ./... -count=1`
- `go vet ./...`
- `go build ./cmd/server`
- `cd frontend/admin && npm.cmd run test:run`
- `cd frontend/admin && npm.cmd run lint`
- `cd frontend/admin && npm.cmd run build`
- `cd frontend/admin && node --check ./scripts/run-playwright-cdp-e2e.mjs`
- `cd frontend/admin && $env:E2E_SCENARIOS='permissions-management-crud'; npm.cmd run e2e:full:win`
- `cd frontend/admin && npm.cmd run e2e:full:win`
### Current Honest Release Conclusion
- The current supported browser-level gate is green with `20` scenarios and now includes `permissions-management-crud`.
- The same branch state also re-proved the backend full matrix and the frontend unit, lint, and build matrix.
- This evidence proves the supported browser-level acceptance path in the current workspace. It still does not prove OS-level automation, live third-party OAuth validation, or external secrets or KMS delivery evidence.
### Additional Checklist Items
- [ ] If a frontend service normalizes backend enum values for UI consumption, tests cover the raw backend payload shape, the normalized frontend shape, and outbound write serialization.
- [ ] If a browser scenario succeeds in the page but CDP request or response observers miss the proxied call, runner-level proof records the real in-page fetch result before classifying the product as broken.
- [ ] If a modal-driven CRUD flow depends on an overlay leaving animation, the next user action waits for the modal to stop blocking interaction instead of relying on a broad hidden assertion alone.
- [ ] If `npm.cmd run build` depends on Vite native config loading on Windows, the supported config keeps HTML inputs under an explicit project root instead of relying on wrapper scripts to mask absolute-path errors.
## 2026-04-24 Profile Security Contract Recovery Snapshot
### Latest Green Evidence
- `cd frontend/admin && npm.cmd run test:run -- src/pages/admin/ProfileSecurityPage/ProfileSecurityPage.behavior.test.tsx src/services/profile.test.ts src/services/service_adapters_additional.test.ts`
- `cd frontend/admin && node --check ./scripts/run-playwright-cdp-e2e.mjs`
- `cd frontend/admin && npm.cmd run lint`
- `cd frontend/admin && npm.cmd run build`
- `cd frontend/admin && npm.cmd run e2e:full:win`
### Current Honest Release Conclusion
- The supported browser-level gate remains green with `20` scenarios after the real `profile-and-security` password-update contract fix.
- This round re-proved the directly affected frontend regression set, lint, build, and the supported browser gate on the same workspace state.
- This round did not re-run the backend full matrix, so backend-wide claims still rely on the latest earlier verified snapshot.
### Additional Checklist Items
- [ ] If a UI form shape differs from the backend write contract, the service adapter must serialize the backend field names explicitly and service tests must pin the exact outbound payload.
- [ ] If a browser runner waits on in-page fetch diagnostics, that wait must be created in the same control flow as the submit action and must not be allowed to outlive a failed click or fill step.