236 lines
12 KiB
Markdown
236 lines
12 KiB
Markdown
# 项目长期记忆
|
||
|
||
## 项目概况
|
||
- **项目类型**：用户管理系统（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单元测试通过
|