user-system/docs/team/PRODUCTION_CHECKLIST.md

生产级发布清单

版本：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. 当前项目的主验收路径

当前受支持的真实浏览器主验收路径：

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.