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

.workbuddy/memory/MEMORY.md

@@ -0,0 +1,235 @@
+# 项目长期记忆
+
+## 项目概况
+- **项目类型**：用户管理系统（UMS）
+- **后端**：Go + `internal/` 目录，已通过 `go build/vet/test`
+- **前端**：`frontend/admin/`，React 18 + TypeScript + Vite + Ant Design 5
+
+## 前端技术栈（唯一执行方案）
+- 框架：React 18 + TypeScript（严格模式）
+- 路由：React Router 6（createBrowserRouter）
+- UI：Ant Design 5
+- 请求：浏览器原生 fetch，自建 `lib/http/client.ts`
+- 状态：React Context（仅会话），不引入 Redux/Zustand
+- 构建：Vite（配置文件为 vite.config.js，非 .ts）
+
+## 关键架构决策
+- AuthProvider 必须在 RootLayout.tsx 中包裹（在 Router 内部），否则 useNavigate/useLocation 报错
+- access_token 保存在内存（auth-session.ts），refresh_token 持久化到 localStorage
+- 401 处理：单次刷新机制 + 并发刷新锁（refreshPromise）
+- 路由守卫：RequireAuth（src/components/guards/）+ RequireAdmin
+
+## 前后端联调评审机制（2026-04-01 新增）
+- **评审流程**: `docs/processes/FRONTEND_BACKEND_REVIEW.md`
+- **检查清单**: `docs/checklists/FRONTEND_BACKEND_CHECKLIST.md`
+- **覆盖范围**: API 接口、认证授权、业务逻辑、性能、安全、错误处理、兼容性、测试、文档、部署、上线前检查
+- **问题分级**: P0（立即修复 4h）、P1（当天修复）、P2（本周修复）、P3（下 Sprint 处理）
+- **通过标准**: 所有 P0/P1 问题已解决，测试通过率 ≥ 95%，性能达标，安全测试通过
+
+## 前端完成状态（2026-03-21 核查）
+✅ 全部 13 个页面已实现，构建通过，5/5 单元测试通过
+
+## 前端缺口与延期项（2026-04-01 前端核查后修正）
+- 社交登录/绑定：前端 UI 已实现（`LoginPage` + `OAuthCallbackPage` + `ProfileSecurityPage`），剩余风险主要在后端协议/真实联调，不再属于“前端缺页面”
+- 用户创建：前端已实现（`UsersPage` 内 `CreateUserModal`），不再属于延期项
+- 批量操作：前端仍未实现
+- 系统设置页：前端仍未实现
+- 全局设备管理页：前端仍未实现；当前只有 `ProfileSecurityPage` 中的“我的设备”
+- 管理员管理页：前端仍未实现（虽然后端 API 已有）
+- 登录日志导出：前端仍未实现
+- 设备信任链路：前端已半接线；密码登录会提交设备字段，但 `device_id` 为随机值且邮箱/短信验证码登录不带设备信息，当前体验不可靠
+
+
+## 代码审查
+- 代码审查标准：`docs/code-review/CODE_REVIEW_STANDARD.md`（v1.1，2026-04-01 更新）
+- PRD 差异验证报告：`docs/code-review/PRD_GAP_VERIFICATION_REPORT.md`（2026-03-29 新增）
+- PRD 差异补充报告：`docs/code-review/PRD_GAP_SUPPLEMENTAL_REPORT.md`（2026-03-29 新增）
+- 代码审查报告 03-30：`docs/code-review/CODE_REVIEW_REPORT_2026-03-30.md`（2026-03-30 新增）
+- 代码审查报告 03-31：`docs/code-review/CODE_REVIEW_REPORT_2026-03-31.md`（2026-03-31 新增，最终报告）
+- **最新审查报告：`docs/code-review/CODE_REVIEW_REPORT_2026-04-01-V2.md`（2026-04-01，第六次审查）**
+- **PRD 缺口精确分析：`docs/code-review/PRD_GAP_DESIGN_PLAN.md`（2026-04-01，最新版）**
+- **最新综合验证报告：`docs/code-review/VALIDATION_REPORT_2026-04-01.md`（2026-04-01，测试专家 + 用户专家双视角）**
+- 代码审查评分：**9.0/10**（聚焦代码质量与存量问题）
+- 最新综合验证评分：**8.4/10**（受前端测试失败与 E2E 主链路复跑失败影响）
+- 🔴 阻塞级问题（0个）：上轮 2 个阻塞已全部修复
+- 🟡 建议级问题（2个）：R6-01 recordDelivery context.Background、R6-02 SlidingWindowLimiter 清理死代码
+- 💭 挑剔级问题（1个）：stats N+5 查询
+- 历史问题修复率：82%（↑8.5%）
+- **最新验证状态**：后端 go vet/build/test 通过；前端 lint/build 通过；Vitest 仍有 3 个失败点；`e2e:full:win` 本轮卡在后端健康检查未就绪
+
+
+## PRD 缺口精确状态（2026-04-01 逐行核查后更新）
+
+- GAP-01（角色继承）：⚠️ 部分实现；角色层级、继承权限汇总、UpdateRole 循环检测已在代码中，仍需补足按 PRD 口径的边界验证与真实验收证据
+- GAP-02（SMS 密码重置）：✅ 已完整实现（此条可关闭）
+- GAP-03（设备信任）：⚠️ 部分实现；CRUD API 与部分登录接线已在，但设备标识不稳定且未覆盖所有登录方式
+- GAP-04（CAS/SAML SSO）：❌ PRD 标注"可选"，推迟 v2.0
+- GAP-05/06（异地/设备检测）：⚠️ 部分实现；AnomalyDetector 已注入 main.go，但完整真实验收证据仍不足
+- GAP-07（SDK）：❌ 推迟 v2.0
+- 密码历史记录：✅ 已接线（repository、service、main 注入链路均已到位）
+
+
+## 2026-03-29 PRD 差异验证与代码审查标准制定
+
+### 第一次审查结果
+- 验证了 PRD_IMPLEMENTATION_GAP_ANALYSIS.md 文档中的 34 个问题
+- 确认准确率：82%（28 个完全确认，4 个部分确认，2 个已修复）
+
+### 第二次深度审查结果
+- 再次验证 PRD 文档中的 34 个问题
+- 确认准确率：**97%**（33 个完全确认，1 个位置描述有误）
+- 新发现问题：**8 个**（2 个高危、1 个中危、5 个低危）
+
+### 新增安全问题确认（修复状态）
+- SEC-01: OAuth ValidateToken 始终返回 true（oauth.go:445）✅ 已修复
+- SEC-02: 敏感操作验证绕过（auth.go:1101）✅ 已修复
+- SEC-03: 恢复码明文存储（auth.go:1119）✅ 已修复
+- SEC-04: TOTP 使用 SHA1（totp.go:25）❌ 未修复
+- SEC-05: X-Forwarded-For IP 伪造风险（ip_filter.go:50）✅ 已修复
+- SEC-06: JTI 包含可预测时间戳（jwt.go:65）❌ 未修复
+- SEC-07: OAuth State TOCTOU 竞态（oauth_utils.go:43-62）✅ 已修复
+- SEC-08: refresh 接口无限流（router.go:108）❌ 未修复
+- **NEW-SEC-01**: Webhook SSRF 风险（webhook.go:181）✅ 已修复
+- **NEW-SEC-02**: Webhook 使用 context.Background（webhook.go:255）❌ 未修复
+- **NEW-SEC-03**: 邮件发送 goroutine context 问题（auth_email.go:86）❌ 未修复
+
+### 第三次审查结果（2026-03-30）
+- 检查问题修复状态
+- **修复率：35%**（34 个问题中 12 个已修复）
+- **高危问题修复率：75%**（8 个高危问题中 6 个已修复）
+- 剩余未修复：**22 个**（2 个高危 + 5 个中危 + 15 个低危）
+
+### 创建的文档
+1. `docs/code-review/CODE_REVIEW_STANDARD.md` - 代码审查标准与流程规范
+2. `docs/code-review/PRD_GAP_VERIFICATION_REPORT.md` - PRD 差异验证报告（第一次）
+3. `docs/code-review/PRD_GAP_SUPPLEMENTAL_REPORT.md` - PRD 差异补充报告（第二次）
+4. `docs/code-review/CODE_REVIEW_REPORT_2026-03-30.md` - 代码审查报告（第三次，含修复状态）
+
+## 执行计划文档
+`docs/plans/ADMIN_FRONTEND_EXECUTION_PLAN.md` — 唯一有效执行方案，任何实现以此为准
+
+## 2026-03-22 系统性修复完成（全部10个问题已修复）
+
+### 后端修复
+1. **登录日志**：`auth.go` 注入 `loginLogRepo`，`Login()/LoginByCode()/LoginByEmailCode()` 均写入 login_logs（成功+失败）
+2. **权限数据**：`db.go initDefaultData()` 增加 `createDefaultPermissions()`，新装自动初始化17个权限；旧库通过 `ensurePermissions()` 升级补种
+3. **CSRF 端点**：`GET /api/v1/auth/csrf-token` 已实现，返回随机32位hex token
+4. **管理员增删**：新增 `GET/POST /api/v1/admin/admins` 和 `DELETE /api/v1/admin/admins/:id`；防止删除自身和最后一个管理员
+5. **bootstrap 健壮化**：admin.nickname 设为"系统管理员"，角色权限绑定完整
+
+### 前端修复
+6. **RequireAdmin 守卫**：加入 `isLoading` 检查，会话恢复中返回 null 防止误跳转
+7. **download/upload Token 刷新**：完整实现 Token 过期自动刷新 + 401 重试流程
+
+### 数据库状态（2026-03-22 修复后）
+- login_logs: 11条（成功5条 + 失败6条，测试期间产生）
+- permissions: 17条，role_permissions: 20条（admin:17 + user:3）
+- users: 2条，roles: 2条（均正常）
+
+### 默认管理员
+- username: `admin`，password: `Admin@123456`（config.yaml 中配置）
+- 注意：数据库密码哈希需要通过 `go run reset_admin_pwd.go` 重置后才能匹配
+
+## 2026-03-22 功能测试完成
+
+### API 测试结果（17项测试）
+| # | 测试项 | 结果 |
+|---|--------|------|
+| 1 | 管理员登录 | ✅ 通过 |
+| 2 | CSRF Token 获取 | ✅ 通过 |
+| 3 | 当前用户信息 | ✅ 通过 |
+| 4 | 管理员列表 | ✅ 通过 |
+| 5 | 权限列表（17项） | ✅ 通过 |
+| 6 | 用户列表 | ✅ 通过 |
+| 7 | 角色列表 | ✅ 通过 |
+| 8 | 登录日志 | ✅ 通过 |
+| 9 | 无效密码拒绝 | ✅ 通过 |
+| 10 | 未认证访问拒绝 | ✅ 通过 |
+| 11 | 创建新管理员 | ✅ 通过 |
+| 12 | 新管理员登录 | ⚠️ 需要用户名匹配 |
+| 13 | 权限受限测试 | ⚠️ 依赖上一项 |
+| 14 | 删除新管理员 | ✅ 通过 |
+| 15 | 防止删除自己 | ✅ 通过 |
+| 16 | 密码修改 | ✅ 通过 |
+| 17 | 权限树 | ✅ 通过 |
+
+### 关键API路由
+- 登录: `POST /api/v1/auth/login` (参数: account, password)
+- CSRF: `GET /api/v1/auth/csrf-token`
+- 用户信息: `GET /api/v1/auth/userinfo`
+- 管理员管理: `/api/v1/admin/admins`
+- 用户管理: `/api/v1/users`
+- 角色管理: `/api/v1/roles`
+- 权限管理: `/api/v1/permissions`
+- 登录日志: `/api/v1/logs/login`
+
+## 2026-03-21 安全与质量优化
+
+### 后端 (Go) 优化:
+1. **SanitizeSQL/SanitizeXSS** - 改用正则表达式替代简单字符串替换，增强安全防护
+2. **IP 验证** - 使用 net.ParseIP 支持所有 IPv6 格式（包括压缩格式 ::1, fe80::1 等）
+3. **OAuth 用户名生成** - 添加唯一性检查和冲突处理（最多100次重试）
+4. **LIKE 搜索** - 添加 escapeLikePattern 转义 % 和 _ 特殊字符
+5. **权限检查 N+1 查询** - 添加批量查询方法替代循环查询
+6. **JWT JTI** - 改用 crypto/rand 生成密码学安全的随机数
+
+### 前端 (React) 优化:
+1. **HTTP 请求超时** - 添加 30 秒超时控制，使用 AbortController
+2. **App.tsx** - 删除未使用的 Vite 模板文件
+3. **CSRF 保护** - 添加 CSRF Token 管理模块和保护机制
+
+### 新增文件:
+- `frontend/admin/src/lib/http/csrf.ts` - CSRF Token 管理模块
+
+### 新增 Repository 批量查询方法:
+- `role.GetByIDs()` - 批量获取角色
+- `permission.GetByIDs()` - 批量获取权限
+- `rolePermission.GetPermissionIDsByRoleIDs()` - 批量获取权限ID
+
+## 2026-03-22 前端问题修复与团队技术提升
+
+### 修复的前端问题
+1. **CSS语法错误**: `tokens.css` 中 `::root` 应为 `:root`
+2. **CSS伪元素错误**: `global.css` 中 `:::-webkit-scrollbar` 应为 `::-webkit-scrollbar`
+3. **循环依赖**: `csrf.ts` 与 `client.ts` 相互导入
+4. **字段名不匹配**: CSRF Token 字段 `token` vs `csrf_token`
+
+### 创建的文档
+- `docs/team/QUALITY_STANDARD.md` - 团队代码质量标准
+- `docs/team/PRODUCTION_CHECKLIST.md` - 生产环境全面验证清单
+- `docs/team/TECHNICAL_GUIDE.md` - 技术能力提升指南
+- `docs/team/FIX_REPORT_2026-03-22.md` - 本次修复报告
+
+### 验证结果
+- ✅ 构建通过
+- ✅ ESLint通过
+- ✅ 5/5单元测试通过
+- ✅ TypeScript检查通过
+
+### 2026-03-22 第三次修复
+- 再次修复CSS语法错误（文件被恢复）
+- 合并AdminLayout.module.css中重复的CSS规则
+- 添加pointer-events确保菜单可点击
+
+### 2026-03-22 菜单点击问题最终解决
+- **根本原因**: Ant Design Menu组件的openKeys（受控模式）与CSS样式冲突
+- **解决方案**: 改为defaultOpenKeys（非受控模式）+ 内联pointer-events样式
+- **额外修复**: 
+  - React Router警告：添加v7_startTransition配置
+  - Ant Design警告：destroyOnClose改为destroyOnHidden
+- **验证**: 菜单点击正常，控制台警告消除
+
+### 2026-03-22 router.tsx文件重复问题
+- **问题**: 刷新后出现500错误，router.tsx文件内容重复
+- **原因**: replace_in_file操作不当导致内容重复插入
+- **解决**: 重写router.tsx文件，删除重复内容
+- **教训**: 使用replace_in_file时要确保不会插入重复内容
+
+### 2026-03-22 UI一致性系统性修复
+- **问题**: 前端页面UI不统一，筛选区域、表格样式、空状态等不一致
+- **解决方案**: 
+  1. 创建统一布局组件：`PageLayout`, `FilterCard`, `TableCard`, `TreeCard`, `ContentCard`
+  2. 改造所有管理页面使用统一布局组件
+  3. 统一空状态组件使用 `PageEmpty`
+- **改造页面**: UsersPage, RolesPage, PermissionsPage, DashboardPage, LoginLogsPage, OperationLogsPage, WebhooksPage, ImportExportPage, ProfilePage, ProfileSecurityPage
+- **验证**: 构建通过，5/5单元测试通过