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

## 前置依赖

- [x] 0.1 确认 add-user-organization-model 提案已完成

## 1. 数据库迁移脚本

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

## 2. GORM 模型修改

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

## 3. 常量定义

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

## 4. Store 层更新

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

## 5. Service 层实现

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

## 6. 中间件更新

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

## 7. Handler 层实现

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

## 8. 测试

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