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

2026-04-02 11:22:17 +08:00
parent 4718980ab5
commit bbeeb63dfa
396 changed files with 165018 additions and 0 deletions
--- a/docs/team/FIX_REPORT_2026-03-22.md
+++ b/docs/team/FIX_REPORT_2026-03-22.md
@@ -0,0 +1,268 @@
+# 前端问题修复报告
+
+> 日期: 2026-03-22
+> 修复人: 资深开发工程师
+> 状态: 已完成
+
+## 一、问题概述
+
+用户反馈：
+1. 前端菜单不能点击
+2. 浏览器控制台有报错
+
+经过系统性诊断，发现以下问题并修复：
+
+## 二、发现的问题
+
+### 问题1: CSS语法错误（严重）
+
+**位置**: `frontend/admin/src/styles/tokens.css` 第7行
+
+**错误代码**:
+```css
+::root {  /* 错误：多了一个冒号 */
+  --color-primary: #0e5a6a;
+}
+```
+
+**正确代码**:
+```css
+:root {  /* 正确：伪类选择器只需一个冒号 */
+  --color-primary: #0e5a6a;
+}
+```
+
+**影响**: CSS变量全部失效，导致样式错乱，可能影响菜单点击区域
+
+---
+
+### 问题2: CSS伪元素语法错误（严重）
+
+**位置**: `frontend/admin/src/styles/global.css` 第50-69行
+
+**错误代码**:
+```css
+:::-webkit-scrollbar { }      /* 错误：三个冒号 */
+:::-webkit-scrollbar-track { } /* 错误：三个冒号 */
+::selection { }               /* 错误：三个冒号 */
+```
+
+**正确代码**:
+```css
+::-webkit-scrollbar { }       /* 正确：两个冒号 */
+::-webkit-scrollbar-track { }  /* 正确：两个冒号 */
+::selection { }                /* 正确：两个冒号 */
+```
+
+**影响**: 滚动条和选中文本样式失效，虽然不直接影响功能，但属于明显错误
+
+---
+
+### 问题3: 循环依赖（中等）
+
+**位置**: `frontend/admin/src/lib/http/csrf.ts`
+
+**问题描述**:
+```typescript
+// csrf.ts 导入 client.ts 的 get
+import { get as httpGet } from './client'
+
+// client.ts 又导入 csrf.ts 的 getCSRFHeaders
+import { getCSRFHeaders, CSRF_PROTECTED_METHODS } from './csrf'
+```
+
+**影响**: 
+- 可能导致模块加载顺序不确定
+- 在某些构建配置下可能引发运行时错误
+- 代码架构不清晰
+
+**修复方案**: 
+- 在 `csrf.ts` 中使用原生 `fetch` 替代导入的 `get`
+- 复制必要的 URL 构建逻辑到 `csrf.ts`
+
+---
+
+### 问题4: 字段名不匹配（中等）
+
+**位置**: `frontend/admin/src/lib/http/csrf.ts` 第97行
+
+**问题描述**:
+- 后端返回: `{ code: 0, data: { csrf_token: "xxx" } }`
+- 前端读取: `result.data.token`
+
+**影响**: CSRF Token 获取失败，虽然系统仍能运行（有降级逻辑），但安全保护机制未生效
+
+**修复**: 将 `result.data.token` 改为 `result.data.csrf_token`
+
+---
+
+## 三、修复详情
+
+### 3.1 修复文件列表
+
+| 文件 | 问题 | 修复方式 |
+|-----|------|---------|
+| `src/styles/tokens.css` | CSS语法错误 | 重写文件，修复:root选择器 |
+| `src/styles/global.css` | CSS语法错误 | 重写文件，修复伪元素选择器 |
+| `src/lib/http/csrf.ts` | 循环依赖+字段名不匹配 | 重写文件，使用原生fetch，修正字段名 |
+
+### 3.2 验证结果
+
+```bash
+# 1. 构建验证
+npm run build        # ✅ 通过
+
+# 2. 代码检查
+npm run lint         # ✅ 通过（仅coverage目录警告）
+
+# 3. 单元测试
+npm run test:run     # ✅ 5/5 测试通过
+
+# 4. TypeScript检查
+npx tsc --noEmit     # ✅ 无错误
+```
+
+### 3.3 追加修复（2026-03-22 16:00）
+
+用户反馈菜单仍然无法点击，追加以下修复：
+
+#### 问题5: CSS pointer-events 问题
+
+**位置**: `frontend/admin/src/layouts/AdminLayout/AdminLayout.module.css`
+
+**修复内容**:
+- 添加 `pointer-events: auto !important` 确保菜单项可点击
+- 添加 `cursor: pointer !important` 确保鼠标样式正确
+- 调整 `z-index` 层级确保菜单不被遮挡
+
+#### 问题6: CSS语法错误恢复
+
+**位置**: `frontend/admin/src/styles/tokens.css` 和 `global.css`
+
+**问题**: 之前修复的CSS语法错误被恢复
+
+**修复**: 重新修复 `::root` → `:root` 和 `:::-webkit-scrollbar` → `::-webkit-scrollbar`
+
+### 3.4 第三次修复（2026-03-22 16:15）
+
+用户反馈菜单仍然无法点击。
+
+**根本原因分析**:
+CSS语法错误导致整个CSS文件解析失败，CSS变量全部失效，但这不是菜单无法点击的直接原因。
+
+**实际修复**:
+1. 再次修复 `tokens.css` 中的 `::root` → `:root`
+2. 再次修复 `global.css` 中的 `:::-webkit-scrollbar` → `::-webkit-scrollbar` 和 `:::selection` → `::selection`
+3. 合并 `AdminLayout.module.css` 中重复的CSS规则
+4. 添加 `pointer-events: auto !important` 到菜单项样式
+
+### 3.5 第四次修复（2026-03-22 16:18）
+
+用户反馈菜单仍然无法点击。
+
+**调试措施**:
+1. 将 `openKeys` 改为 `defaultOpenKeys` 避免受控组件问题
+2. 在Menu组件上添加内联样式 `style={{ pointerEvents: 'auto' }}`
+3. 在 `handleMenuClick` 中添加 `console.log` 调试日志
+
+**验证方法**:
+1. 刷新浏览器
+2. 按F12打开开发者工具
+3. 点击左侧菜单
+4. 查看Console面板是否有 "Menu clicked: xxx" 日志输出
+5. 如果没有日志，说明点击事件未触发，需要检查CSS或DOM结构
+6. 如果有日志但页面未跳转，说明navigate有问题
+
+### 3.6 第五次修复（2026-03-22 17:56）
+
+**菜单点击问题已解决！**
+
+**根本原因**: Ant Design的Menu组件在使用 `openKeys`（受控模式）时，与CSS样式冲突导致点击事件被拦截。
+
+**解决方案**: 将 `openKeys` 改为 `defaultOpenKeys`（非受控模式），并添加内联样式确保 `pointer-events: auto`。
+
+**额外修复**:
+1. **React Router警告**: 在 `createBrowserRouter` 中添加 `future: { v7_startTransition: true }` 配置
+2. **Ant Design警告**: 将 `AssignRolesModal.tsx` 中的 `destroyOnClose` 改为 `destroyOnHidden`
+3. 删除调试日志
+
+### 3.7 第六次修复（2026-03-22 20:46）
+
+**问题**: 刷新后出现500错误 `GET http://localhost:3000/src/app/router.tsx net::ERR_ABORTED 500`
+
+**根本原因**: `router.tsx` 文件内容重复，第172-288行是重复的路由配置，导致JavaScript语法错误。
+
+**解决方案**: 删除重复内容，恢复正确的文件结构。
+
+**教训**: 使用 `replace_in_file` 时要小心，确保不会意外插入重复内容。
+
+## 四、根因分析
+
+### 为什么会出现这些问题？
+
+1. **缺乏代码审查**: CSS语法错误应该在审查阶段被发现
+2. **缺少自动化检查**: 没有配置Stylelint来检查CSS语法
+3. **测试覆盖不足**: 没有集成测试来验证CSRF流程
+4. **API契约不清晰**: 前后端字段名没有对齐
+
+### 如何预防？
+
+1. **代码审查清单**: 添加CSS语法检查项
+2. **自动化工具**: 配置Stylelint + ESLint
+3. **API文档**: 使用Swagger/OpenAPI明确字段名
+4. **集成测试**: 添加端到端测试验证关键流程
+
+## 五、团队改进建议
+
+### 5.1 立即行动
+
+- [ ] 配置Stylelint检查CSS语法
+- [ ] 添加CSS代码审查检查项
+- [ ] 对齐前后端API字段名文档
+
+### 5.2 短期改进
+
+- [ ] 添加集成测试覆盖CSRF流程
+- [ ] 配置CI/CD自动化检查
+- [ ] 建立API变更通知机制
+
+### 5.3 长期建设
+
+- [ ] 引入Storybook进行UI组件测试
+- [ ] 建立端到端测试套件
+- [ ] 完善开发文档和最佳实践
+
+## 六、经验总结
+
+### 6.1 技术层面
+
+1. **CSS语法要严格**: 伪类(:)和伪元素(::)的区别
+2. **避免循环依赖**: 模块间依赖要清晰
+3. **API契约要对齐**: 前后端字段名要一致
+4. **测试要全面**: 不仅是单元测试，还要集成测试
+
+### 6.2 流程层面
+
+1. **代码审查不能省**: 即使小改动也要审查
+2. **自动化检查要完善**: 人工检查容易遗漏
+3. **问题要追根溯源**: 不只修复表象，要解决根因
+4. **经验要沉淀**: 把教训转化为文档和流程
+
+## 七、附录
+
+### 7.1 相关文档
+
+- [代码质量标准](QUALITY_STANDARD.md)
+- [生产验证清单](PRODUCTION_CHECKLIST.md)
+- [技术提升指南](TECHNICAL_GUIDE.md)
+
+### 7.2 参考链接
+
+- [CSS伪类和伪元素区别](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Pseudo-classes)
+- [JavaScript循环依赖](https://nodejs.org/api/modules.html#modules_cycles)
+- [OWASP CSRF防护](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
+
+---
+
+**报告完成时间**: 2026-03-22 13:00
+**下次回顾**: 2026-03-29
--- a/docs/team/FRONTEND_STATUS_AUDIT_2026-03-22.md
+++ b/docs/team/FRONTEND_STATUS_AUDIT_2026-03-22.md
@@ -0,0 +1,207 @@
+# 前端实现状态审计报告
+
+**审计时间**: 2026-03-22  
+**审计依据**: `docs/plans/ADMIN_FRONTEND_EXECUTION_PLAN.md`  
+**当前状态**: 13个页面已实现，但存在功能缺口和UI规范问题
+
+---
+
+## 1. 功能实现状态
+
+### 1.1 已完成的页面 (13/13)
+
+| 页面 | 路由 | 状态 | 备注 |
+|------|------|------|------|
+| 登录页 | `/login` | ✅ | 支持密码、邮箱、短信登录 |
+| 忘记密码 | `/forgot-password` | ✅ | - |
+| 重置密码 | `/reset-password` | ✅ | - |
+| 总览 | `/dashboard` | ✅ | 统计卡片已实现 |
+| 用户管理 | `/users` | ⚠️ | **缺少创建用户功能** |
+| 角色管理 | `/roles` | ✅ | - |
+| 权限管理 | `/permissions` | ✅ | - |
+| 登录日志 | `/logs/login` | ✅ | - |
+| 操作日志 | `/logs/operation` | ✅ | - |
+| Webhooks | `/webhooks` | ✅ | - |
+| 导入导出 | `/import-export` | ✅ | - |
+| 个人资料 | `/profile` | ✅ | - |
+| 安全设置 | `/profile/security` | ✅ | - |
+
+### 1.2 功能缺口（与执行计划对比）
+
+#### 用户管理页 (`/users`)
+
+**执行计划明确不做（后端不支持）**:
+- ❌ 新建用户 - 后端没有 `POST /api/v1/users` 接口
+- ❌ 批量操作 - 后端没有批量接口
+- ❌ 管理员代改他人密码 - `PUT /users/:id/password` 只允许本人修改
+- ❌ 为其他用户上传头像 - 头像上传只支持当前用户
+
+**当前实现状态**:
+- ✅ 用户列表、分页、筛选
+- ✅ 查看用户详情
+- ✅ 编辑用户资料
+- ✅ 删除用户
+- ✅ 修改用户状态
+- ✅ 分配角色
+- ❌ **创建用户按钮缺失**（符合执行计划，但用户体验不完整）
+
+**建议**: 虽然执行计划明确不做，但从用户体验角度，应该添加一个提示说明，告知用户为何不能创建用户。
+
+---
+
+## 2. UI规范检查
+
+### 2.1 设计Tokens检查
+
+**规范文件**: `docs/design/admin-ui-tokens.css`
+
+| Token | 规范值 | 当前状态 | 问题 |
+|-------|--------|----------|------|
+| `--color-canvas` | `#f4f1ea` | ✅ | - |
+| `--color-layout` | `#e9e3d5` | ✅ | - |
+| `--color-surface` | `#ffffff` | ✅ | - |
+| `--color-primary` | `#0e5a6a` | ✅ | - |
+| `--radius-sm` | `10px` | ⚠️ | 部分页面使用Ant Design默认值 |
+| `--shadow-card` | `0 10px 30px rgba(23, 33, 43, 0.06)` | ⚠️ | 部分卡片未使用统一阴影 |
+
+### 2.2 页面布局一致性
+
+**问题发现**:
+
+1. **页面标题不统一**
+   - 有些页面使用 `PageHeader` 组件
+   - 有些页面直接使用 `<h1>` 或 `<Title>`
+   - 建议：所有页面统一使用 `PageHeader` 组件
+
+2. **操作按钮位置不统一**
+   - 有些页面在右上角
+   - 有些页面在表格上方
+   - 建议：统一放在表格右上方
+
+3. **筛选表单样式不统一**
+   - 有些页面使用 Card 包裹
+   - 有些页面直接放在页面中
+   - 建议：统一使用 Card 包裹或统一不使用
+
+### 2.3 表格样式一致性
+
+**问题**:
+- 表格列宽未统一
+- 操作列按钮样式不一致（有的用图标，有的用文字）
+- 状态标签颜色未完全统一
+
+---
+
+## 3. 代码质量问题
+
+### 3.1 已修复的问题
+
+1. ✅ CSS语法错误 (`::root` → `:root`)
+2. ✅ CSS伪元素错误 (`:::-webkit-scrollbar` → `::-webkit-scrollbar`)
+3. ✅ 循环依赖问题 (`csrf.ts` 与 `client.ts`)
+4. ✅ 字段名不匹配 (`token` vs `csrf_token`)
+5. ✅ 菜单点击问题 (改为 `defaultOpenKeys`)
+6. ✅ React Router警告 (添加 `v7_startTransition`)
+7. ✅ Ant Design警告 (`destroyOnClose` → `destroyOnHidden`)
+8. ✅ `router.tsx` 文件重复问题
+
+### 3.2 待改进的代码质量
+
+1. **错误处理不一致**
+   - 有些页面使用 `getErrorMessage()`
+   - 有些页面直接显示 `error.message`
+   - 建议：统一使用 `getErrorMessage()`
+
+2. **加载状态处理**
+   - 有些页面使用 `PageEmpty` 和 `PageError` 组件
+   - 有些页面直接内联处理
+   - 建议：统一使用反馈组件
+
+---
+
+## 4. 建议修复清单
+
+### 高优先级（影响用户体验）
+
+1. **统一页面标题组件**
+   ```tsx
+   // 所有页面统一使用
+   <PageHeader title="用户管理" subtitle="管理系统用户账户" />
+   ```
+
+2. **统一操作按钮位置**
+   ```tsx
+   // 统一放在表格右上方
+   <div className={styles.tableActions}>
+     <Button type="primary">导出</Button>
+   </div>
+   ```
+
+3. **统一筛选表单样式**
+   ```tsx
+   // 统一使用 Card 包裹或不使用
+   <Card className={styles.filterCard}>
+     {/* 筛选表单 */}
+   </Card>
+   ```
+
+### 中优先级（提升代码质量）
+
+4. **统一错误处理**
+   ```tsx
+   // 统一使用
+   import { getErrorMessage } from '@/lib/errors'
+   message.error(getErrorMessage(err))
+   ```
+
+5. **统一加载状态**
+   ```tsx
+   // 统一使用反馈组件
+   import { PageEmpty, PageError, PageLoading } from '@/components/feedback'
+   ```
+
+### 低优先级（优化体验）
+
+6. **添加用户创建提示**
+   虽然后端不支持创建用户，但可以在用户管理页添加提示：
+   ```tsx
+   <Alert 
+     type="info" 
+     message="用户创建功能暂不可用，请联系系统管理员" 
+   />
+   ```
+
+---
+
+## 5. 执行计划延期项确认
+
+以下功能执行计划明确标注为**延期或不实现**，当前状态正确：
+
+| 功能 | 状态 | 原因 |
+|------|------|------|
+| 用户创建 | ❌ 未实现 | 后端无 `POST /api/v1/users` 接口 |
+| 批量操作 | ❌ 未实现 | 后端无批量接口 |
+| 管理员重置密码 | ❌ 未实现 | 后端只允许本人修改密码 |
+| 系统设置 | ❌ 未实现 | 后端无配置接口 |
+| 全局设备管理 | ❌ 未实现 | 后端只有当前用户设备接口 |
+| 社交登录 | ❌ 未实现 | OAuth回调非SPA友好格式 |
+
+---
+
+## 6. 总结
+
+### 当前状态
+- **页面数量**: 13个页面已全部实现 ✅
+- **功能完整性**: 基本功能完整，但缺少用户创建 ✅
+- **UI一致性**: 存在不一致问题 ⚠️
+- **代码质量**: 已修复关键问题，仍有改进空间 ⚠️
+
+### 建议行动
+1. **短期**: 统一UI组件使用方式，提升一致性
+2. **中期**: 统一错误处理和加载状态
+3. **长期**: 推动后端补齐 `POST /api/v1/users` 接口
+
+### 风险点
+- 用户管理缺少创建功能，管理员体验不完整
+- UI不一致影响产品专业感
+- 代码风格不统一增加维护成本
--- a/docs/team/PRODUCTION_CHECKLIST.md
+++ b/docs/team/PRODUCTION_CHECKLIST.md
@@ -0,0 +1,79 @@
+# 生产级发布清单
+
+版本：2.0  
+更新时间：2026-03-25
+
+本清单用于发布前、发布后和对外表述前的最后核查。
+
+## 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`
--- a/docs/team/PROJECT_EXPERIENCE_SUMMARY.md
+++ b/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 级自动化证据
--- a/docs/team/QUALITY_STANDARD.md
+++ b/docs/team/QUALITY_STANDARD.md
@@ -0,0 +1,120 @@
+# 项目工程规则
+
+版本：2.0  
+更新时间：2026-03-25
+
+本规则是当前项目的真实工程约束，不是泛化建议。
+
+## 1. 基本原则
+
+- 结论必须可验证，不能靠口头“已完成”。
+- 优先真实闭环，拒绝 fake success、临时掩盖和只过局部样例。
+- 任何上线结论都必须区分：
+  - 浏览器级真实验证
+  - OS 级自动化
+  - 外部交付治理证据
+
+## 2. 后端规则
+
+### 2.1 运行时安全
+
+- 非测试代码禁止保留 `panic` 作为常规失败路径。
+- 配置不合法时应在启动期失败，不要运行后再暴露风险。
+- 外部依赖缺失时必须显式禁用能力或启动失败，不能返回假成功。
+
+### 2.2 错误处理
+
+- 必须保留真实错误语义，不能吞错。
+- 优先使用显式错误分类：
+  - 例如 rate limit
+  - validation
+  - internal failure
+- 禁止长期依赖字符串子串判断错误类型。
+
+### 2.3 分层设计
+
+- service 层依赖接口能力，不依赖具体 repository 类型断言。
+- repository 负责持久化细节，service 负责业务编排和错误分级。
+- 外部副作用必须 fail closed，并处理回滚。
+
+### 2.4 安全与配置
+
+- 敏感值不得硬编码到配置模板。
+- release 模式必须限制：
+  - 占位密钥
+  - localhost OAuth 回调
+  - `*` CORS 放行
+  - 不安全 JWT 配置
+
+## 3. 前端规则
+
+### 3.1 浏览器行为
+
+- 原生弹窗和 popup 不是“可以接受的小问题”，而是验收失败信号。
+- 必须阻断并记录：
+  - `alert`
+  - `confirm`
+  - `prompt`
+  - `open`
+
+### 3.2 主链路要求
+
+- 登录页、后台主导航、路由守卫、认证状态恢复必须进入真实浏览器回归。
+- 认证能力展示必须跟随后端 `capabilities`，不能前端硬编码。
+
+### 3.3 smoke 边界
+
+- `smoke` 只允许存在于测试或诊断层。
+- 任何产品运行时逻辑都不得依赖 `smoke`。
+
+## 4. 验证规则
+
+### 4.1 后端最低门槛
+
+```powershell
+go test ./... -count=1
+go vet ./...
+go build ./cmd/server
+```
+
+### 4.2 前端最低门槛
+
+```powershell
+cd frontend/admin
+npm.cmd run lint
+npm.cmd run build
+```
+
+### 4.3 真实浏览器最低门槛
+
+以下改动必须执行：
+
+```powershell
+cd frontend/admin
+npm.cmd run e2e:full:win
+```
+
+适用改动：
+
+- 认证
+- 会话
+- OAuth
+- 登录页
+- 路由守卫
+- 主导航
+- `window` 防线
+- 用户主流程
+
+## 5. 文档规则
+
+- 真实状态变化后必须更新 `docs/status/REAL_PROJECT_STATUS.md`。
+- 团队长期规则变化后必须更新本文件和 `docs/team/PRODUCTION_CHECKLIST.md`。
+- 形成阶段性经验后必须沉淀到 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`。
+
+## 6. 禁止项
+
+- 禁止“只跑单个用例就宣布收口”。
+- 禁止“因为环境受限就把诊断脚本包装成主验收路径”。
+- 禁止“为了通过测试保留运行时 mock provider”。
+- 禁止“服务层通过具体仓储断言完成业务”。
+- 禁止“因为终端乱码就把乱码字面量继续扩散到业务逻辑”。
--- a/docs/team/TECHNICAL_GUIDE.md
+++ b/docs/team/TECHNICAL_GUIDE.md
@@ -0,0 +1,61 @@
+# 技术指南
+
+更新时间：2026-03-25
+
+本文件不再承载泛化培训内容，改为当前项目的技术入口索引。
+
+## 1. 先读什么
+
+建议阅读顺序：
+
+1. `README.md`
+2. `docs/status/REAL_PROJECT_STATUS.md`
+3. `docs/team/QUALITY_STANDARD.md`
+4. `docs/team/PRODUCTION_CHECKLIST.md`
+5. `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`
+
+## 2. 当前项目最重要的真实结论
+
+- 主验收路径是 `cd frontend/admin && npm.cmd run e2e:full:win`
+- 当前闭环的是浏览器级真实 E2E，不是完整 OS 级自动化
+- `smoke` 仅用于诊断，不是运行时依赖
+- 非测试代码中的 `panic`、fake success、mock runtime provider 都应视为缺陷
+
+## 3. 常用命令
+
+### 后端
+
+```powershell
+go test ./... -count=1
+go vet ./...
+go build ./cmd/server
+```
+
+### 前端
+
+```powershell
+cd frontend/admin
+npm.cmd run lint
+npm.cmd run build
+```
+
+### 真实浏览器
+
+```powershell
+cd frontend/admin
+npm.cmd run e2e:full:win
+```
+
+## 4. 常见工程经验
+
+- 如果结论依赖真实用户流程，就不要只跑单元测试。
+- 如果终端出现乱码，不要把乱码文本继续复制进业务逻辑。
+- 如果错误分级依赖字符串子串，后续大概率会回归；优先改成显式错误类型。
+- 如果 service 依赖具体 repository 类型断言，后续替换实现或测试 mock 会变脆。
+
+## 5. 文档维护规则
+
+- 状态变更：更新 `docs/status/REAL_PROJECT_STATUS.md`
+- 规则变更：更新 `docs/team/QUALITY_STANDARD.md`
+- 发布门槛变更：更新 `docs/team/PRODUCTION_CHECKLIST.md`
+- 阶段性经验：更新 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`