junhong_cmp_fiber/openspec/changes/archive/2026-01-16-implement-permission-check/tasks.md

Implementation Tasks

1. 核心实现

• 1.1 在 PermissionService 结构体中添加 accountRoleStore 和 rolePermStore 字段
• 1.2 修改 New() 构造函数签名，注入新的 Store 依赖
• 1.3 实现 CheckPermission() 方法核心逻辑：
  • 1.3.1 检查用户类型，超级管理员返回 true
  • 1.3.2 查询用户的角色 ID 列表 (accountRoleStore.GetRoleIDsByAccountID)
  • 1.3.3 查询角色的权限 ID 列表 (rolePermStore.GetPermIDsByRoleIDs)
  • 1.3.4 查询权限详情列表 (permissionStore.GetByIDs)
  • 1.3.5 遍历权限列表，匹配 permCode 和 platform
  • 1.3.6 返回匹配结果（true/false）
• 1.4 更新 internal/bootstrap/services.go 中的 Permission Service 初始化，传入新的依赖

2. 错误处理

• 2.1 处理数据库查询错误（角色查询失败、权限查询失败）
• 2.2 空角色列表返回 false（用户无角色，无权限）
• 2.3 空权限列表返回 false（角色无权限）
• 2.4 添加详细的错误日志（使用 logger）

3. 单元测试

• 3.1 创建 tests/unit/permission_check_test.go（项目测试在 tests/unit/ 目录）
• 3.2 测试场景：
  • 3.2.1 超级管理员权限检查（应返回 true）
  • 3.2.2 有权限的用户检查（应返回 true）
  • 3.2.3 无权限的用户检查（应返回 false）
  • 3.2.4 用户无角色检查（应返回 false）
  • 3.2.5 角色无权限检查（应返回 false）
  • 3.2.6 platform 过滤测试（web/h5/all）
  • 3.2.7 数据库查询错误处理（通过 fmt.Errorf 包装错误）

4. 集成测试

• 4.1 更新 tests/integration/permission_middleware_test.go
• 4.2 测试权限中间件功能：
  • 4.2.1 单个权限检查 (RequirePermission)
  • 4.2.2 任意权限检查 (RequireAnyPermission)
  • 4.2.3 全部权限检查 (RequireAllPermissions)
  • 4.2.4 超级管理员跳过检查
  • 4.2.5 平台过滤 (web/h5/all)
  • 4.2.6 未认证用户拒绝访问

5. 文档更新

• 5.1 在 docs/ 中创建权限检查使用文档
• 5.2 提供路由权限配置示例
• 5.3 更新 README.md，标记权限检查功能已完成（已在 RBAC 权限系统条目中添加权限检查说明和文档链接）

6. 性能优化（Redis 缓存）

• 6.1 添加 Redis 缓存层存储用户权限列表
  • 在 pkg/constants/redis.go 添加 RedisUserPermissionsKey 函数
  • 在 PermissionService 添加 Redis 客户端依赖
  • 在 CheckPermission 方法中实现缓存查询和写入逻辑
  • 缓存 TTL 设置为 30 分钟
• 6.2 实现缓存失效机制（角色变更时）
  • 在 AccountRoleStore 的 Create/Delete 方法中添加缓存清除
  • 在 RolePermissionStore 的 Create/Delete 方法中添加缓存清除
  • 清除逻辑：查询角色关联的用户，批量删除缓存
• 6.3 添加缓存性能测试
  • 测试首次查询缓存未命中场景
  • 测试后续查询缓存命中场景
  • 测试缓存 TTL 正确性
  • 更新文档说明缓存机制

Validation

• 所有单元测试通过 (8/8 passed)
• 所有集成测试通过 (6/6 passed)
• API 编译成功 (go build ./cmd/api/)
• golangci-lint run 无错误
• 手动测试权限中间件在实际路由中正常工作

实现总结

完成状态

✅ 核心实现: 完整的 CheckPermission 逻辑（5步查询链） ✅ 错误处理: 完善的错误处理和日志记录 ✅ 单元测试: 8个测试用例，全部通过 ✅ 集成测试: 6个测试用例，全部通过 ✅ 代码质量: golangci-lint 检查通过 ✅ 文档完善: 使用指南 + API 示例

测试覆盖

• 超级管理员自动跳过检查 ✅
• 有权限用户访问成功 ✅
• 无权限用户访问失败 ✅
• 用户无角色返回 false ✅
• 角色无权限返回 false ✅
• Platform 过滤 (all/web/h5) ✅
• 单个/任意/全部权限检查 ✅
• 未认证用户拒绝访问 ✅

性能指标

• 查询次数: 3次数据库查询
• 预估耗时: < 10ms (本地) / < 20ms (远程)
• 优化措施: 批量查询 + 自动去重

文档

• 使用指南
• 设计文档
• 提案文档