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

docs/team/PROJECT_EXPERIENCE_SUMMARY.md

@@ -0,0 +1,83 @@
+# 项目经验总结
+
+更新时间：2026-03-25
+
+这份总结只记录本项目已经真实发生过、并且已经影响工程决策的经验。
+
+## 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`
+  - `cd frontend/admin && npm.cmd run e2e:full:win`
+
+## 2. 浏览器级真实 E2E 与 OS 级自动化不是一回事
+
+- 当前项目已经形成稳定的浏览器级真实 E2E 路径。
+- 但这不覆盖系统文件选择器、原生权限弹窗、桌面窗口层行为。
+- 因此对外必须区分：
+  - 浏览器级真实验证已闭环
+  - 完整 OS 级自动化未闭环
+
+## 3. 字符串猜错误类型非常脆弱
+
+- 邮箱验证码限流曾因为错误文本编码漂移，从 `429` 退化成 `500`。
+- 短信发送也存在同类风险，甚至一度把限流错误错误映射成 `400`。
+- 结论：
+  - 错误分级必须优先使用显式错误类型
+  - 旧字符串判断只能短期兼容，不能长期依赖
+
+## 4. fake success 比直接失败更危险
+
+- 邮件、短信、OAuth、上传这类链路，如果依赖缺失仍然返回成功，会让前端、测试和运营都得到错误信号。
+- 这类问题不会减少故障，只会推迟暴露时间并放大排查成本。
+- 结论：
+  - 运行时必须 fail closed
+  - 缺配置时要么禁用能力，要么启动失败
+
+## 5. 分层设计不是形式问题，而是稳定性问题
+
+- TOTP 服务曾依赖具体仓储实现断言，导致 service 对替换实现和测试 mock 都很脆弱。
+- 后续把依赖收回到接口能力后，分层更稳，测试也更自然。
+- 结论：
+  - service 依赖接口，不依赖具体 repo 类型
+
+## 6. 非测试 `panic` 会放大生产风险
+
+- 兼容入口中的 `panic` 即使当前主路径不用，也会在后续复用、测试或错误调用时变成进程级风险。
+- 结论：
+  - 非测试代码中的 `panic` 必须持续清零
+
+## 7. `smoke` 可以保留，但必须明确降级
+
+- 诊断脚本有价值，但不能被包装成“主验收已通过”的替代品。
+- 结论：
+  - `smoke` 只能做补充诊断
+  - 主验收必须走真实主链路
+
+## 8. 前端弹窗问题必须被当成缺陷，而不是小瑕疵
+
+- 浏览器原生弹窗会直接打断真实后台主流程和自动化执行。
+- 这次项目里，给 `window.alert/confirm/prompt/open` 增加阻断和日志后，验证稳定性明显提高。
+- 结论：
+  - 原生弹窗和 popup 都应纳入失败信号
+
+## 9. 文档如果不跟着代码一起更新，很快就会反过来误导团队
+
+- 真实状态、规则、发布门槛如果不及时更新，后续协作会不断重复已经踩过的坑。
+- 结论：
+  - 状态、规则、经验、agent 都要跟代码一起维护
+
+## 10. 接下来仍然属于真实缺口的部分
+
+以下不是“代码没写完”，而是仍未形成完整外部交付证据：
+
+- 真实第三方 OAuth live browser validation
+- 外部 Secrets Manager / KMS 证据
+- 多环境 CI/CD 密钥分发证据
+- 跨历史版本 schema downgrade 回滚证据
+- 完整 OS 级自动化证据