junhong_cmp_fiber/openspec/changes/archive/2026-01-10-add-role-permission-system/tasks.md

Tasks: 角色权限体系实现任务

前置依赖

• 0.1 确认 add-user-organization-model 提案已完成

1. 数据库迁移脚本

• 1.1 修改 tb_permission 表迁移脚本（添加 platform 字段）
• 1.2 更新 tb_role 表的 role_type 注释说明
• 1.3 执行数据库迁移并验证表结构（✅ 已完成：迁移版本从 2 升级到 3）

2. GORM 模型修改

• 2.1 修改 internal/model/permission.go - 添加 Platform 字段
• 2.2 修改 internal/model/role.go - 更新 RoleType 注释
• 2.3 验证模型与数据库表结构一致

3. 常量定义

• 3.1 在 pkg/constants/ 添加角色类型常量（RoleTypePlatform, RoleTypeCustomer）
• 3.2 添加权限端口常量（PlatformAll, PlatformWeb, PlatformH5）
• 3.3 添加角色类型与用户类型匹配规则函数

4. Store 层更新

• 4.1 修改 internal/store/postgres/permission_store.go
  • 4.1.1 添加按 platform 过滤的 List 方法
  • 4.1.2 获取用户权限时支持 platform 过滤（添加 GetByPlatform 方法）
• 4.2 修改 internal/store/postgres/account_role_store.go
  • 4.2.1 添加 GetByAccountID 方法（查询账号的角色）- 已存在
  • 4.2.2 添加 CountByAccountID 方法（统计账号的角色数量）

5. Service 层实现

• 5.1 创建/修改 internal/service/role_service.go
  • 5.1.1 创建角色（校验角色类型）- 已存在
  • 5.1.2 更新角色信息 - 已存在
  • 5.1.3 获取角色列表（按类型过滤）- 已存在，支持按 role_type 过滤
• 5.2 创建/修改 internal/service/account_role_service.go
  • 5.2.1 分配角色（校验用户类型匹配、数量限制）- 已在 account/service.go 中实现
  • 5.2.2 取消角色分配 - 已存在（RemoveRole）
  • 5.2.3 获取账号的角色列表 - 已存在（GetRoles）
• 5.3 创建/修改 internal/service/permission_service.go
  • 5.3.1 创建权限（含 platform 字段）
  • 5.3.2 获取用户权限列表（按端口过滤）- List 方法已支持 platform 过滤
  • 5.3.3 构建权限菜单树 - 已存在（GetTree, buildPermissionTree）

6. 中间件更新

• 6.1 修改权限校验中间件
  • 6.1.1 添加 pkg/middleware/permission.go 实现权限校验中间件
  • 6.1.2 支持 RequirePermission、RequireAnyPermission、RequireAllPermissions 三种模式
  • 6.1.3 权限校验时考虑 platform 字段
  • 6.1.4 添加 PermissionChecker 接口，支持 Service 层实现
  • 6.1.5 完善 CheckPermission 方法的完整实现（需要注入 AccountRoleStore 和 RolePermissionStore）

7. Handler 层实现

• 7.1 角色管理 API（已验证完整支持新字段）
  • 7.1.1 POST /api/v1/roles - 创建角色（支持 role_type 字段，验证范围 1-2）
  • 7.1.2 PUT /api/v1/roles/:id - 更新角色
  • 7.1.3 GET /api/v1/roles - 获取角色列表（支持按 role_type 过滤）
  • 7.1.4 GET /api/v1/roles/:id - 获取角色详情
• 7.2 账号角色管理 API（已验证完整支持新逻辑）
  • 7.2.1 POST /api/v1/accounts/:id/roles - 分配角色（支持类型匹配和数量限制）
  • 7.2.2 DELETE /api/v1/accounts/:id/roles/:roleId - 取消角色
  • 7.2.3 GET /api/v1/accounts/:id/roles - 获取账号角色
• 7.3 权限查询 API（已验证完整支持新字段）
  • 7.3.1 所有权限 API 都支持 platform 字段（创建、更新、查询、树形结构）

8. 测试

• 8.1 角色类型与用户类型匹配规则单元测试
  • 创建 tests/unit/role_type_matching_test.go
  • 测试 IsRoleTypeMatchUserType 函数
  • 测试 GetMaxRolesForUserType 函数
• 8.2 角色分配数量限制单元测试
  • 创建 tests/unit/role_assignment_limit_test.go
  • 测试平台用户可分配多个角色（无限制）
  • 测试代理账号只能分配一个角色
  • 测试企业账号只能分配一个角色
  • 测试超级管理员不允许分配角色
• 8.3 权限端口过滤单元测试
  • 创建 tests/unit/permission_platform_filter_test.go
  • 测试按 platform 过滤权限列表
  • 测试创建权限时默认 platform 为 all
  • 测试创建权限时指定 platform
  • 测试权限树包含 platform 字段
• 8.4 权限校验中间件集成测试
  • 创建 tests/integration/permission_middleware_test.go
  • 添加 Mock PermissionChecker 实现
  • 添加测试占位符和实现指南（待完整实现 CheckPermission 后补充）

备注

已完成的工作

• ✅ 数据库迁移脚本（添加 platform 字段、更新 role_type 注释）
• ✅ 数据库迁移执行（版本从 2 升级到 3，耗时 800ms）
• ✅ GORM 模型更新（Permission.Platform、Role.RoleType）
• ✅ 常量定义（RoleTypePlatform、RoleTypeCustomer、PlatformAll/Web/H5）
• ✅ Store 层实现（支持 platform 过滤、CountByAccountID）
• ✅ Service 层实现（角色类型匹配、数量限制、platform 支持）
• ✅ Handler 层验证（所有 API 支持新字段和业务逻辑）
• ✅ 权限校验中间件框架（RequirePermission、RequireAnyPermission、RequireAllPermissions）
• ✅ 测试用例补充（角色匹配规则、数量限制、platform 过滤、中间件占位）
• ✅ 修复编译错误（ParentID 引用移除、RoleTypeSuper → RoleTypePlatform）
• ✅ DTO 验证规则更新（role_type 范围改为 1-2）

待完成的工作

• ⏳ 完善 Permission Service 的 CheckPermission 方法（需要注入 AccountRoleStore 和 RolePermissionStore）
• ⏳ 完善权限校验中间件的集成测试（待 CheckPermission 实现后补充）

重要变更说明

• 角色类型重新定义：1=平台角色（适用于平台用户），2=客户角色（适用于代理/企业账号）
• 权限新增 platform 字段：all=全端，web=Web后台，h5=H5端
• 角色分配规则：
  • 超级管理员：不需要角色（0个）
  • 平台用户：可分配多个平台角色（无限制）
  • 代理/企业账号：只能分配1个客户角色
• 旧测试文件中的 ParentID 引用已移除（Account 模型通过 ShopID/EnterpriseID 关联组织）
• 删除了不再适用的 subordinate 测试文件（上下级关系现在通过 Shop 表维护）

依赖关系

0.x (前置依赖) → 1.x (迁移) → 2.x (模型) → 3.x (常量) → 4.x (Store) → 5.x (Service) → 6.x (中间件) → 7.x (Handler) → 8.x (测试)

并行任务

以下任务可以并行执行：

• 4.1, 4.2 可以并行
• 5.1, 5.2, 5.3 可以并行（5.2 依赖 5.1 的部分逻辑）
• 7.1, 7.2, 7.3 可以并行
• 8.1, 8.2, 8.3, 8.4 可以并行