docs: project docs, scripts, deployment configs, and evidence

docs/guides/TESTING.md

@@ -0,0 +1,162 @@
+# 测试指南
+
+更新日期：2026-03-24
+
+本文档只描述当前项目已落地、已验证的测试路径。
+
+## 1. 环境要求
+
+- Go 1.25+
+- Node.js 20+
+- Windows PowerShell 环境下，如 `npm.ps1` 被策略拦截，请使用 `npm.cmd`
+
+如果本机 Go 全局缓存目录受限，建议在执行 Go 命令前显式指定本地缓存目录：
+
+```powershell
+$env:GOMODCACHE = "D:\project\.cache\gomod"
+$env:GOPATH = "D:\project\.cache\gopath"
+$env:GOCACHE = "D:\project\.cache\go-build"
+```
+
+## 2. 后端验证
+
+### 单元与集成测试
+
+```powershell
+go test ./... -count=1
+```
+
+如需执行默认回归之外的大并发压力测试，请显式开启：
+
+```powershell
+$env:RUN_STRESS_TESTS = "1"
+go test ./... -count=1
+```
+
+### 静态检查
+
+```powershell
+go vet ./...
+```
+
+### 构建验证
+
+```powershell
+go build ./cmd/server
+```
+
+### 健康检查验证
+
+启动服务后可验证：
+
+```powershell
+curl http://localhost:8080/health
+curl http://localhost:8080/health/live
+curl http://localhost:8080/health/ready
+```
+
+说明：
+
+- `/health` 兼容历史探针，语义等同 readiness
+- `/health/live` 只验证进程存活
+- `/health/ready` 会检查数据库可用性
+
+## 3. 前端验证
+
+在 [`frontend/admin`](/D:/project/frontend/admin) 下执行：
+
+```powershell
+npm.cmd run test:run
+npm.cmd run lint
+npm.cmd run build
+```
+
+当前已补充并验证的前端重点包括：
+
+- 认证服务契约测试
+- 登录页按 `auth/capabilities` 动态展示登录方式
+- 忘记密码入口按 `password_reset` 能力显隐
+
+## 4. 真实浏览器验证
+
+当前环境下 `playwright test` runner 会因 `spawn EPERM` 受限，因此真实浏览器验证主路径不是 runner，而是“外部启动真实浏览器 + Playwright 库经 CDP 接管”。
+当前 CDP 验证脚本会把以下信号视为失败：
+
+- console error
+- native dialog
+- popup page
+- page error
+- request failure
+- `401` 响应
+- 被前端 `window` guard 拦截的 `alert/confirm/prompt/open`
+
+Windows 下 `e2e:full:win` 与 `e2e:auth-smoke:win` 都会自动把 Go 缓存写到 `%TEMP%\\ums-e2e-cache`，避免工作区权限问题。
+
+### 全量真实浏览器 E2E
+
+```powershell
+cd D:\project\frontend\admin
+npm.cmd run e2e:full:win
+```
+
+当前覆盖：
+
+- `login-surface`
+  - 登录页能力展示
+  - 未登录访问受保护路由重定向
+- `auth-workflow`
+  - 真实登录
+  - 用户列表
+  - 用户详情抽屉
+  - 分配角色弹窗
+  - 角色页
+  - 分配权限弹窗
+  - Dashboard
+  - 真实登出与登出后重定向
+- `responsive-login`
+  - desktop / tablet / mobile 视口渲染与横向溢出检查
+- `desktop-mobile-navigation`
+  - 桌面侧边导航
+  - 移动端抽屉导航
+
+### 补充页面与路由 smoke
+
+```powershell
+cd D:\project\frontend\admin
+npm.cmd run e2e:smoke:win
+```
+
+当前覆盖：
+
+- 未登录访问 `/dashboard`、`/users` 会重定向到 `/login`
+- 登录页按后端能力动态显示可用登录方式
+- 忘记密码入口按能力显隐
+- 多视口下页面可正常渲染
+
+### 补充真实认证链路 smoke
+
+```powershell
+cd D:\project\frontend\admin
+npm.cmd run e2e:auth-smoke:win
+```
+
+当前覆盖：
+
+- 从受保护路由跳转到登录页
+- 真实登录后回到目标页面
+- 用户列表加载
+- 用户详情抽屉打开
+- 分配角色弹窗打开
+- 角色管理页跳转
+- 分配权限弹窗打开
+- Dashboard 加载
+- 真实登出后再次访问受保护页面会被重定向到登录页
+
+## 5. 边界说明
+
+- 当前支持的 CDP 路径已经是浏览器级真实验证，不是 DOM mock。
+- 当前支持的 CDP 路径不是完整 OS 级自动化。
+  - 不覆盖系统文件选择器、原生桌面弹窗、操作系统级权限窗口等行为。
+- `e2e:full:win` 是当前受支持的主验收路径；`smoke` 脚本保留为补充诊断，不代表产品运行时仍依赖 smoke。
+- 测试层的 smoke 脚本和 mock helper 是允许的，但它们不应继续进入产品运行时。
+- 认证相关接口当前会统一返回 `Cache-Control: no-store` 等响应头；如果在抓包或浏览器开发者工具中看不到缓存命中，这是预期行为。