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

docs/PROJECT_REVIEW_REPORT_APPENDIX_20260324.md

@@ -0,0 +1,52 @@
+# 项目严格 Review 报告补充（2026-03-24）
+
+## 本轮新增收口
+
+- 头像上传链路已补齐失败回滚与假状态治理：
+  - 头像存储目录初始化失败不再静默忽略
+  - 随机文件名生成失败改为 fail closed
+  - 原图写入失败时会清理半成品文件
+  - `UpdateAvatar(...)` 失败时会回滚原图与缩略图
+  - 仅当缩略图真实生成成功时才返回 `thumbnail`
+- 新增 handler 回归测试：
+  - `UpdateAvatar(...)` 失败后的文件回滚
+  - 缩略图生成失败时不再返回假 `thumbnail`
+  - 随机源失败时请求直接失败且不落盘
+- E2E 脚本收口：
+  - `run-playwright-cdp-e2e.mjs` 增加 closed-target 场景级重试
+  - `run-cdp-smoke.ps1` 增加浏览器路径与 CDP ready 诊断输出
+  - 默认浏览器选择恢复到当前已验证稳定的 Playwright 缓存 `chrome-headless-shell.exe`
+
+## 本轮真实结论
+
+- 当前 Windows 环境下，稳定可复现通过的全量真实浏览器 E2E 主路径仍然是：
+  - `frontend/admin` 下的 `npm.cmd run e2e:full:win`
+  - 浏览器启动由 `frontend/admin/scripts/run-cdp-smoke.ps1` 驱动
+  - 默认稳定浏览器为 Playwright 缓存 `chrome-headless-shell.exe`
+- 本轮已明确验证的真实边界：
+  - 桌面 Chrome / Edge 在当前 PowerShell 启动器下没有形成稳定可支持的 CDP-ready 路径
+  - 直接由 Node 启动浏览器会命中 `spawn EPERM`，因此不能替代当前 PowerShell 启动器
+  - 因此，当前不能对外表述为“桌面 Chrome/Edge 已成为本环境默认稳定 E2E 浏览器”
+
+## 本轮验证结果
+
+- 通过：
+  - `go test ./internal/api/handler -count=1`
+  - `go test ./... -count=1`
+  - `go build ./cmd/server`
+  - `npm.cmd run e2e:full:win`
+  - `1..2 | ForEach-Object { npm.cmd run e2e:full:win }`
+- 最近三次默认主路径 E2E 连续通过场景：
+  - `PASS login-surface`
+  - `PASS auth-workflow`
+  - `PASS responsive-login`
+  - `PASS desktop-mobile-navigation`
+
+## 对外表述修正
+
+- 可以诚实表述为：
+  - 项目当前已完成本地可验证的头像上传失败回滚收口，并完成当前受限 Windows 环境下的浏览器级真实 E2E 收口。
+  - 受支持的默认验证路径仍是 `Playwright library + external chrome-headless-shell + CDP`。
+- 不应夸大表述为：
+  - 桌面 Chrome/Edge 已在该环境下成为默认稳定 E2E 浏览器
+  - Node 直拉浏览器已可替代当前 PowerShell 启动器