long-agent
5b6bd93179
整理内容: - 删除 60+ 临时测试输出文件 (*.txt) - 移动二进制文件到 bin/ 目录 - 移动 Shell 脚本到 scripts/ 目录 - scripts/dev/: check_gitea.sh, check_sub2api.sh, run_tests.sh - scripts/deploy/: deploy_*.sh, simple_deploy.sh - scripts/ops/: fix_nginx.sh, fix_ssl.sh, install_docker.sh - scripts/test/: test_*.sh, test_*.bat - 移动批处理文件到 scripts/ - 移动 Python 脚本到 tools/ - 清理临时日志文件 保留根目录必要文件: - go.mod, go.sum, go.work - Makefile, docker-compose.yml - .env.example, .gitignore - README.md, AGENTS.md, DEPLOY_GUIDE.md 验证: go build ./... && go test ./... 通过
112 lines
6.8 KiB
Markdown
112 lines
6.8 KiB
Markdown
# 项目长期记忆
|
||
|
||
## 项目概况
|
||
- **项目类型**：用户管理系统（UMS）
|
||
- **后端**：Go + `internal/` 目录
|
||
- **前端**：`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`
|
||
- **问题分级**: P0（4h修复）、P1（当天）、P2（本周）、P3（下Sprint）
|
||
- **通过标准**: 所有 P0/P1 已解决，测试通过率 ≥ 95%
|
||
|
||
## 前端状态（截至 2026-04-02）
|
||
- ✅ 全部 13 个页面已实现，构建通过，5/5 单元测试通过
|
||
- ❌ 未实现：批量操作、系统设置页、全局设备管理页、管理员管理页、登录日志导出
|
||
- ⚠️ 半接线：设备信任链路（密码登录传 device_id，但前端为随机值，邮箱/SMS登录不带设备信息）
|
||
|
||
## PRD 缺口状态（截至 2026-04-02 Sprint 14 后）
|
||
- GAP-01（角色继承）：✅ 已确认完整实现（循环检测+深度限制+middleware权限汇总）
|
||
- GAP-02（SMS密码重置）：✅ 已完整修复（时序泄漏 + 密码历史 + doResetPassword）
|
||
- GAP-03（设备信任）：✅ 全链路闭环（密码/SMS/邮件验证码登录均接 device_id + localStorage持久化）
|
||
- GAP-04（CAS/SAML SSO）：❌ PRD 标注"可选"，推迟 v2.0
|
||
- GAP-05（异常检测）：✅ AnomalyDetector 已在 main.go 接线
|
||
- GAP-07（SDK）：❌ 推迟 v2.0
|
||
- 密码历史记录：✅ ChangePassword + doResetPassword 均已接线
|
||
|
||
## 代码审查状态（最新：2026-04-03 Sprint 16 完成）
|
||
- 代码审查评分：**10/10**（Sprint 16 彻底解决所有遗留问题）
|
||
- 🔴 阻塞级问题：0 个
|
||
- 🟡 建议级问题：0 个
|
||
- 🟢 未修复安全问题：0 个（SEC-04/06/08 已全部修复）
|
||
- E2E 测试通过率：100% (17/17)
|
||
- Sprint 15 修复清单：
|
||
- BUG-01: Goroutine 中使用已回收的 gin context（auth_handler.go、sms_handler.go）
|
||
- BUG-02: 密码历史 goroutine 使用裸 context.Background()（user_service.go、password_reset.go）
|
||
- BUG-03: 登录日志 goroutine 使用裸 context.Background()（auth.go）
|
||
- BUG-04: handleError 所有错误一律返回 500（auth_handler.go）
|
||
- BUG-05: Logout 不使 Token 失效（auth_handler.go）
|
||
- BUG-06: GetCSRFToken 返回 not_implemented（auth_handler.go）
|
||
- 报告：`docs/sprints/SPRINT_15_CODE_REVIEW_REPORT.md`
|
||
- Sprint 16 修复清单：
|
||
- P1: E2E 测试中 exportHandler 未初始化，导致 2 个测试失败
|
||
- SEC-04: JTI 时间戳防枚举（格式：timestamp + random）
|
||
- SEC-08: Refresh Token 滚动轮换防无限流（Token Rotation）
|
||
- 报告：`docs/sprints/SPRINT_16_FINAL_ISSUE_RESOLUTION.md`
|
||
|
||
## 关键 API 路由
|
||
- 登录: `POST /api/v1/auth/login`（参数: account/username/email/phone, password, device_id, device_name, device_browser, device_os）
|
||
- 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`
|
||
|
||
## 默认管理员
|
||
- username: `admin`，password: `Admin@123456`（config.yaml 中配置）
|
||
- 注意：数据库密码哈希需要通过 `go run reset_admin_pwd.go` 重置后才能匹配
|
||
|
||
## Sprint 执行记录
|
||
- Sprint 12（2026-04-01）：建立前后端联调评审机制 + 修复 ValidateRecoveryCode 时序泄漏
|
||
- Sprint 13（2026-04-02）：GAP-02 SMS重置时序泄漏 + 密码历史 doResetPassword + GAP-03 设备信任链路主路径补齐
|
||
- Sprint 14（2026-04-02 续）：彻底收口所有遗留问题（邮件验证码登录stub/ActivateEmail stub/device_id稳定化/R6-01/R6-02死代码）
|
||
- Sprint 15（2026-04-03）：完整代码审查，修复 6 个严重 BUG（goroutine context、错误处理、token 管理）
|
||
- Sprint 16（2026-04-03）：彻底解决所有遗留问题（P1 + SEC-04/06/08），E2E 测试 100% 通过
|
||
- Sprint 17（2026-04-05）：SRE 全面审查 + 执行优化
|
||
- 第一轮：识别 5 个 CRIT 问题（评分 4.5/10），产出 SRE_SOLUTION.md
|
||
- 第二轮：修复 CRIT-01/02/03/04，全量测试 34 包 100% 通过，评分升至 7.2/10
|
||
- 第三轮：修复 WARN-01/02/03，评分升至 **8.0/10**（最终）
|
||
- 新建文件：`internal/monitoring/collector.go`（系统指标采集）、`internal/api/middleware/trace_id.go`（追踪ID）、`.env.example`
|
||
- 报告：`docs/sre/SRE_REVIEW_ROUND3.md`（三轮完整记录）
|
||
- Sprint 18（2026-04-07）：Cursor 游标分页全栈优化（完整实施+验证通过）
|
||
- 新建 `internal/pagination/cursor.go`（游标编解码工具包）
|
||
- Repository 层 4 个 ListCursor 方法（LoginLog/OperationLog/Device/User），keyset 模式 O(limit)
|
||
- Service 层 4 个 Cursor 方法 + CursorResult 统一响应结构
|
||
- Handler 层双路路由（cursor/size → 游标路径；page/page_size → offset 回退兼容）
|
||
- 前端 DevicesPage cursor 分页集成（CursorPaginatedData 类型 + 状态管理 + Table 兼容）
|
||
- 规模测试：LL P99=53ms, OPLOG P99=55ms（SLA<100ms），比 offset 快 2.3x
|
||
- 编译：go build ✅, tsc --noEmit ✅
|
||
|
||
## 下一步候选（低优先级）
|
||
- ❌ 已完成：SEC-04/06/08 所有安全问题已修复
|
||
- 性能优化：数据库查询优化、缓存策略优化
|
||
- 功能增强：批量操作、系统设置页、全局设备管理页、管理员管理页、登录日志导出
|
||
- 安全加固：OAuth 2.0 第三方登录集成、SAML SSO 集成
|
||
|
||
## 执行计划文档
|
||
- 系统性实施计划：`docs/plans/SYSTEMATIC_IMPLEMENTATION_PLAN.md`
|
||
- 前端执行方案（唯一有效）：`docs/plans/ADMIN_FRONTEND_EXECUTION_PLAN.md`
|
||
- 前后端联调实施指南：`docs/processes/FRONTEND_BACKEND_REVIEW_IMPLEMENTATION_GUIDE.md`
|
||
|
||
## 技术经验积累
|
||
- replace_in_file 操作要确保不会重复插入内容
|
||
- Ant Design Menu 受控/非受控模式切换：受控模式（openKeys）与CSS冲突，改用 defaultOpenKeys
|
||
- 前端 CSS：`:root` 不是 `::root`，`::-webkit-scrollbar` 不是 `:::-webkit-scrollbar`
|
||
- 后端循环依赖排查：先用 `go build` 查是否能通过，再查循环导入链
|
||
- go test 在 Windows PowerShell 不能用 `| tail`，改用 `| Select-Object -Last N`
|