long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1cba56ea85e27b602109db6395cbf7fb2fb31ea2
user-system/.workbuddy/memory/MEMORY.md

12 KiB
Raw Blame History

项目长期记忆

项目概况

  • 项目类型：用户管理系统（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 设为"系统管理员"，角色权限绑定完整

前端修复

  1. RequireAdmin 守卫：加入 isLoading 检查，会话恢复中返回 null 防止误跳转
  2. 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单元测试通过
Reference in New Issue View Git Blame Copy Permalink