实现角色权限体系重构

本次提交完成了角色权限体系的重构，主要包括： 1. 数据库迁移 - 添加 tb_permission.platform 字段（all/web/h5） - 更新 tb_role.role_type 注释（1=平台角色，2=客户角色） 2. GORM 模型更新 - Permission 模型添加 Platform 字段 - Role 模型更新 RoleType 注释 3. 常量定义 - 新增角色类型常量（RoleTypePlatform, RoleTypeCustomer） - 新增权限端口常量（PlatformAll, PlatformWeb, PlatformH5） - 添加角色类型与用户类型匹配规则函数 4. Store 层实现 - Permission Store 支持按 platform 过滤 - Account Role Store 添加 CountByAccountID 方法 5. Service 层实现 - 角色分配支持类型匹配校验 - 角色分配支持数量限制（超级管理员0个，平台用户无限制，代理/企业1个） - Permission Service 支持 platform 过滤 6. 权限校验中间件 - 实现 RequirePermission、RequireAnyPermission、RequireAllPermissions - 支持 platform 字段过滤 - 支持跳过超级管理员检查 7. 测试用例 - 角色类型匹配规则单元测试 - 角色分配数量限制单元测试 - 权限 platform 过滤单元测试 - 权限校验中间件集成测试（占位） 8. 代码清理 - 删除过时的 subordinate 测试文件 - 移除 Account.ParentID 相关引用 - 更新 DTO 验证规则 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 09:51:52 +08:00
parent a36e4a79c0
commit 1b9080e3ab
31 changed files with 1767 additions and 607 deletions
--- a/openspec/changes/archive/2026-01-10-add-role-permission-system/design.md
+++ b/openspec/changes/archive/2026-01-10-add-role-permission-system/design.md
@@ -0,0 +1,247 @@
+# Design: 角色权限体系架构设计
+
+## Context
+
+### 背景
+
+根据用户需求，系统有两类角色：
+
+1. **平台角色**: 用于区分平台用户的不同职责（运营、客服、管理员等）
+2. **客户角色**: 用于决定代理/企业客户的能力边界（可以做什么操作）
+
+同时，权限需要按端口区分：
+- Web 后台：运营/代理可登录
+- H5/小程序（企业/代理）：企业/代理可登录
+- H5/小程序（个人）：个人客户可登录
+
+### 约束条件
+
+- 平台用户可以分配多个角色
+- 代理/企业账号只能分配一种角色
+- 个人客户没有角色
+- 某些接口会被复用（前端根据权限控制显示）
+- 权限既要控制接口访问，又要告诉前端展示哪些菜单/按钮
+
+## Goals / Non-Goals
+
+### Goals
+
+1. 重新定义角色类型，区分平台角色和客户角色
+2. 为权限添加端口属性，支持按端口过滤
+3. 实现账号-角色分配的数量限制
+4. 为前端提供权限列表用于菜单/按钮控制
+
+### Non-Goals
+
+1. 本提案不实现具体的权限校验中间件（已在 auth spec 中定义）
+2. 本提案不创建初始角色和权限数据（由业务初始化脚本处理）
+3. 本提案不处理个人客户的登录认证
+
+## Decisions
+
+### Decision 1: 角色类型重定义
+
+**决策**: 将 role_type 重新定义为：
+- `1` = 平台角色（适用于平台用户）
+- `2` = 客户角色（适用于代理/企业账号）
+
+**理由**:
+- 原设计的"超级/代理/企业"角色类型与用户类型耦合过紧
+- 新设计区分"角色的适用范围"而非"角色的所有者类型"
+- 客户角色可以同时适用于代理和企业，便于权限复用
+
+**变更**:
+- 原 role_type = 1（超级）→ 废弃（超级管理员不需要角色）
+- 原 role_type = 2（代理）→ role_type = 2（客户角色）
+- 原 role_type = 3（企业）→ 合并到 role_type = 2（客户角色）
+- 新增 role_type = 1（平台角色）
+
+### Decision 2: 权限端口字段
+
+**决策**: 在 Permission 表添加 `platform` 字段，类型为 varchar(20)，默认值 'all'。
+
+```go
+Platform string `gorm:"type:varchar(20);default:'all'"` // all-全部 web-Web后台 h5-H5端
+```
+
+**理由**:
+- 折中方案：不强制隔离，但提供灵活性
+- 前端可以根据 platform 过滤菜单
+- 后端校验时可以根据请求来源和权限的 platform 进行验证
+
+**使用场景**:
+- `all`: 通用权限，如"查看订单"、"创建客户"
+- `web`: 仅 Web 后台使用，如"导出报表"、"批量操作"
+- `h5`: 仅 H5 使用，如"扫码登录"、"微信支付"
+
+### Decision 3: 账号-角色数量限制
+
+**决策**: 在 Service 层实现角色数量限制，而非数据库约束。
+
+**实现逻辑**:
+```go
+func (s *AccountRoleService) AssignRole(accountID, roleID uint) error {
+    // 1. 查询账号信息
+    account := s.accountStore.GetByID(accountID)
+
+    // 2. 根据用户类型判断限制
+    switch account.UserType {
+    case constants.UserTypeSuperAdmin:
+        return errors.New("超级管理员不需要分配角色")
+    case constants.UserTypePlatform:
+        // 平台用户可分配多个角色，无限制
+    case constants.UserTypeAgent, constants.UserTypeEnterprise:
+        // 代理/企业只能分配一个角色，先检查是否已有角色
+        existingRoles := s.accountRoleStore.GetByAccountID(accountID)
+        if len(existingRoles) > 0 {
+            return errors.New("该账号类型只能分配一个角色")
+        }
+    }
+
+    // 3. 检查角色类型是否匹配用户类型
+    role := s.roleStore.GetByID(roleID)
+    if !s.isRoleTypeMatchUserType(role.RoleType, account.UserType) {
+        return errors.New("角色类型与账号类型不匹配")
+    }
+
+    // 4. 创建关联
+    return s.accountRoleStore.Create(accountID, roleID)
+}
+```
+
+**理由**:
+- 业务规则在 Service 层实现，便于修改和扩展
+- 数据库层面不加限制，保持灵活性
+- 错误信息更友好，便于前端展示
+
+### Decision 4: 角色类型与用户类型匹配规则
+
+**决策**: 定义角色类型与用户类型的匹配关系。
+
+| 用户类型 | 可分配的角色类型 |
+|---------|----------------|
+| 超级管理员 (1) | 无 |
+| 平台用户 (2) | 平台角色 (1) |
+| 代理账号 (3) | 客户角色 (2) |
+| 企业账号 (4) | 客户角色 (2) |
+
+**理由**:
+- 平台用户只能分配平台角色
+- 代理和企业可以共享客户角色（如"基础查看"、"高级操作"等）
+- 便于权限管理和角色复用
+
+### Decision 5: 权限校验流程
+
+**决策**: 权限校验分两步：
+1. **接口权限**: 中间件根据请求路径匹配权限编码，检查用户是否拥有该权限
+2. **端口权限**: 中间件根据请求来源（Web/H5）和权限的 platform 字段进行二次校验
+
+**流程**:
+```
+请求 → 认证中间件 → 权限中间件
+                      ↓
+               1. 解析请求路径，匹配权限编码
+               2. 查询用户的所有权限
+               3. 检查权限是否匹配
+               4. 检查权限的 platform 是否与请求来源匹配
+                      ↓
+               通过 / 拒绝
+```
+
+## Data Models
+
+### Role（角色）- 修改
+
+```go
+type Role struct {
+    gorm.Model
+    BaseModel `gorm:"embedded"`
+
+    RoleName string `gorm:"not null;size:50"`       // 角色名称
+    RoleDesc string `gorm:"size:255"`               // 角色描述
+    RoleType int    `gorm:"not null;index"`         // 角色类型 1=平台角色 2=客户角色
+    Status   int    `gorm:"not null;default:1"`     // 状态 0=禁用 1=启用
+}
+```
+
+### Permission（权限）- 修改
+
+```go
+type Permission struct {
+    gorm.Model
+    BaseModel `gorm:"embedded"`
+
+    PermName string  `gorm:"not null;size:50"`                    // 权限名称
+    PermCode string  `gorm:"uniqueIndex;size:100"`                // 权限编码
+    PermType int     `gorm:"not null;index"`                      // 权限类型 1=菜单 2=按钮
+    Platform string  `gorm:"type:varchar(20);default:'all'"`      // 适用端口 all=全部 web=Web后台 h5=H5端
+    URL      string  `gorm:"size:255"`                            // URL路径（可选）
+    ParentID *uint   `gorm:"index"`                               // 上级权限ID
+    Sort     int     `gorm:"not null;default:0"`                  // 排序
+    Status   int     `gorm:"not null;default:1"`                  // 状态 0=禁用 1=启用
+}
+```
+
+## API Design
+
+### 获取当前用户权限列表
+
+```
+GET /api/v1/account/permissions
+Query: platform=web|h5 (可选，过滤端口)
+
+Response:
+{
+    "code": 0,
+    "message": "success",
+    "data": {
+        "permissions": [
+            {
+                "perm_code": "order:view",
+                "perm_name": "查看订单",
+                "perm_type": 1,
+                "platform": "all"
+            }
+        ],
+        "menus": [
+            {
+                "id": 1,
+                "name": "订单管理",
+                "url": "/orders",
+                "children": [...]
+            }
+        ]
+    }
+}
+```
+
+## Risks / Trade-offs
+
+### Risk 1: 角色类型变更影响现有数据
+
+- **风险**: role_type 的含义变更可能影响现有角色数据
+- **缓解**: 当前系统无实际数据，可以直接重新定义
+
+### Risk 2: 权限端口字段的维护成本
+
+- **风险**: 新增权限时需要考虑端口属性，增加维护成本
+- **缓解**: 默认值为 'all'，只有特殊权限才需要设置
+
+### Risk 3: 角色数量限制的绕过
+
+- **风险**: 直接操作数据库可能绕过 Service 层的数量限制
+- **缓解**: 所有操作通过 API 进行，数据库直接操作需审批
+
+## Migration Plan
+
+1. 修改 `tb_role` 表：更新 role_type 的注释说明
+2. 修改 `tb_permission` 表：添加 `platform` 字段，默认值 'all'
+3. 更新 GORM 模型定义
+4. 添加常量定义（角色类型、权限端口）
+5. 实现 Service 层的角色分配逻辑
+6. 更新权限校验中间件
+
+## Open Questions
+
+1. ~~是否需要为不同端口创建独立的权限树？~~ - 不需要，使用 platform 字段过滤即可
+2. ~~客户角色是否需要进一步细分（代理专用/企业专用）？~~ - 暂不需要，共用客户角色
--- a/openspec/changes/archive/2026-01-10-add-role-permission-system/proposal.md
+++ b/openspec/changes/archive/2026-01-10-add-role-permission-system/proposal.md
@@ -0,0 +1,51 @@
+# Change: 重构角色权限体系
+
+## Why
+
+当前系统的角色权限模型（Role、Permission、AccountRole、RolePermission）需要适配新的用户组织体系。主要问题：
+
+1. 角色类型（role_type）需要与新的用户类型对应
+2. 权限缺少端口区分（某些权限只在 Web 后台有效，某些只在 H5 有效）
+3. 账号-角色关联规则需要调整（平台用户可多角色，代理/企业只能单角色）
+
+## What Changes
+
+### 修改现有模型
+
+- **Role**: 重新定义角色类型枚举（平台角色、客户角色）
+- **Permission**: 添加 `platform` 字段支持按端口区分权限（all/web/h5）
+- **AccountRole**: 添加角色数量限制逻辑
+
+### 业务规则
+
+1. **平台角色**: 用于区分平台用户的不同职责（运营、客服、管理等）
+2. **客户角色**: 用于决定代理/企业客户的能力边界
+3. **权限端口**:
+   - `all` - 通用权限（Web 和 H5 均可用）
+   - `web` - 仅 Web 后台使用
+   - `h5` - 仅 H5 端使用
+
+### 角色分配规则
+
+| 用户类型 | 可分配角色类型 | 角色数量限制 |
+|---------|--------------|-------------|
+| 超级管理员 | 无需角色 | 0 |
+| 平台用户 | 平台角色 | 多个 |
+| 代理账号 | 客户角色 | 1个 |
+| 企业账号 | 客户角色 | 1个 |
+| 个人客户 | 无角色 | 0 |
+
+## Impact
+
+- **Affected specs**: role-permission (新建), auth
+- **Affected code**:
+  - `internal/model/role.go` - 修改角色类型定义
+  - `internal/model/permission.go` - 添加 platform 字段
+  - `internal/store/postgres/account_role_store.go` - 添加角色数量校验
+  - `internal/service/` - 添加角色分配逻辑
+  - `migrations/` - 修改表结构迁移脚本
+  - `pkg/constants/` - 添加角色类型、权限端口常量
+
+## 依赖关系
+
+本提案依赖 **add-user-organization-model** 提案完成后执行，因为角色分配规则需要基于新的用户类型定义。
--- a/openspec/changes/archive/2026-01-10-add-role-permission-system/specs/role-permission/spec.md
+++ b/openspec/changes/archive/2026-01-10-add-role-permission-system/specs/role-permission/spec.md
@@ -0,0 +1,163 @@
+# Feature Specification: 角色权限体系
+
+**Feature Branch**: `add-role-permission-system`
+**Created**: 2026-01-09
+**Status**: Draft
+
+## ADDED Requirements
+
+### Requirement: 角色类型定义
+
+系统 SHALL 定义两种角色类型：平台角色（role_type=1）用于平台用户的职责区分，客户角色（role_type=2）用于代理和企业账号的能力边界控制。
+
+#### Scenario: 创建平台角色
+- **WHEN** 创建角色时指定 role_type = 1
+- **THEN** 系统创建平台角色，该角色只能分配给平台用户
+
+#### Scenario: 创建客户角色
+- **WHEN** 创建角色时指定 role_type = 2
+- **THEN** 系统创建客户角色，该角色可分配给代理账号或企业账号
+
+#### Scenario: 角色类型常量使用
+- **WHEN** 代码中需要判断角色类型
+- **THEN** 必须使用 constants.RoleTypePlatform、constants.RoleTypeCustomer 常量
+
+---
+
+### Requirement: 权限端口属性
+
+系统 SHALL 在权限表添加 platform 字段，用于标识权限的适用端口：all（全部）、web（仅Web后台）、h5（仅H5端）。默认值为 all。
+
+#### Scenario: 创建通用权限
+- **WHEN** 创建权限时 platform = 'all' 或未指定
+- **THEN** 该权限在 Web 后台和 H5 端均可用
+
+#### Scenario: 创建Web专用权限
+- **WHEN** 创建权限时 platform = 'web'
+- **THEN** 该权限仅在 Web 后台可用，H5 端无法使用
+
+#### Scenario: 创建H5专用权限
+- **WHEN** 创建权限时 platform = 'h5'
+- **THEN** 该权限仅在 H5 端可用，Web 后台无法使用
+
+#### Scenario: 按端口过滤权限列表
+- **WHEN** 前端请求用户权限列表时指定 platform 参数
+- **THEN** 系统返回 platform 为指定值或 'all' 的权限
+
+---
+
+### Requirement: 角色类型与用户类型匹配
+
+系统 SHALL 在分配角色时校验角色类型与用户类型的匹配关系：平台用户只能分配平台角色，代理/企业账号只能分配客户角色，超级管理员和个人客户不分配角色。
+
+#### Scenario: 平台用户分配平台角色
+- **WHEN** 为平台用户（user_type=2）分配平台角色（role_type=1）
+- **THEN** 系统允许分配
+
+#### Scenario: 平台用户分配客户角色
+- **WHEN** 为平台用户（user_type=2）分配客户角色（role_type=2）
+- **THEN** 系统拒绝分配并返回错误"角色类型与账号类型不匹配"
+
+#### Scenario: 代理账号分配客户角色
+- **WHEN** 为代理账号（user_type=3）分配客户角色（role_type=2）
+- **THEN** 系统允许分配
+
+#### Scenario: 代理账号分配平台角色
+- **WHEN** 为代理账号（user_type=3）分配平台角色（role_type=1）
+- **THEN** 系统拒绝分配并返回错误"角色类型与账号类型不匹配"
+
+#### Scenario: 企业账号分配客户角色
+- **WHEN** 为企业账号（user_type=4）分配客户角色（role_type=2）
+- **THEN** 系统允许分配
+
+#### Scenario: 超级管理员分配角色
+- **WHEN** 尝试为超级管理员（user_type=1）分配任何角色
+- **THEN** 系统拒绝分配并返回错误"超级管理员不需要分配角色"
+
+---
+
+### Requirement: 账号角色数量限制
+
+系统 SHALL 对不同用户类型实施角色数量限制：平台用户可分配多个角色，代理账号和企业账号只能分配一个角色。
+
+#### Scenario: 平台用户分配多个角色
+- **WHEN** 平台用户已有 N 个角色，再分配第 N+1 个角色
+- **THEN** 系统允许分配，该用户拥有 N+1 个角色
+
+#### Scenario: 代理账号分配第一个角色
+- **WHEN** 代理账号没有角色，分配第一个角色
+- **THEN** 系统允许分配
+
+#### Scenario: 代理账号分配第二个角色
+- **WHEN** 代理账号已有一个角色，尝试分配第二个角色
+- **THEN** 系统拒绝分配并返回错误"该账号类型只能分配一个角色"
+
+#### Scenario: 企业账号角色数量限制
+- **WHEN** 企业账号已有一个角色，尝试分配第二个角色
+- **THEN** 系统拒绝分配并返回错误"该账号类型只能分配一个角色"
+
+#### Scenario: 替换代理账号的角色
+- **WHEN** 代理账号已有一个角色，需要更换为另一个角色
+- **THEN** 系统需要先取消当前角色，再分配新角色
+
+---
+
+### Requirement: 权限端口校验
+
+系统 SHALL 在权限校验时考虑请求来源（Web/H5）和权限的 platform 属性，只有当权限的 platform 为 'all' 或与请求来源匹配时才允许访问。
+
+#### Scenario: Web请求访问通用权限
+- **WHEN** 来自 Web 后台的请求访问 platform='all' 的权限保护接口
+- **THEN** 权限校验通过（前提是用户拥有该权限）
+
+#### Scenario: Web请求访问Web权限
+- **WHEN** 来自 Web 后台的请求访问 platform='web' 的权限保护接口
+- **THEN** 权限校验通过（前提是用户拥有该权限）
+
+#### Scenario: Web请求访问H5权限
+- **WHEN** 来自 Web 后台的请求访问 platform='h5' 的权限保护接口
+- **THEN** 权限校验失败，返回错误"该权限不适用于当前端口"
+
+#### Scenario: H5请求访问Web权限
+- **WHEN** 来自 H5 端的请求访问 platform='web' 的权限保护接口
+- **THEN** 权限校验失败，返回错误"该权限不适用于当前端口"
+
+---
+
+### Requirement: 用户权限列表查询
+
+系统 SHALL 提供 API 供前端查询当前登录用户的权限列表，支持按端口过滤，并返回权限编码列表和菜单树结构。
+
+#### Scenario: 查询全部权限
+- **WHEN** 用户调用 GET /api/v1/account/permissions
+- **THEN** 系统返回用户拥有的所有权限（权限编码列表 + 菜单树）
+
+#### Scenario: 查询Web端权限
+- **WHEN** 用户调用 GET /api/v1/account/permissions?platform=web
+- **THEN** 系统返回 platform 为 'all' 或 'web' 的权限
+
+#### Scenario: 查询H5端权限
+- **WHEN** 用户调用 GET /api/v1/account/permissions?platform=h5
+- **THEN** 系统返回 platform 为 'all' 或 'h5' 的权限
+
+#### Scenario: 构建菜单树
+- **WHEN** 返回权限列表时
+- **THEN** 系统根据权限的 parent_id 关系构建层级菜单树结构
+
+---
+
+## Key Entities
+
+- **Role（角色）**: 权限角色，通过 role_type 区分平台角色和客户角色
+- **Permission（权限）**: 系统功能权限，通过 platform 字段标识适用端口
+- **AccountRole（账号-角色关联）**: 账号与角色的多对多关系，受用户类型和数量限制约束
+- **RolePermission（角色-权限关联）**: 角色与权限的多对多关系
+
+## Success Criteria
+
+- **SC-001**: Permission 表成功添加 platform 字段，默认值为 'all'
+- **SC-002**: 角色类型与用户类型匹配校验正确执行，不匹配时返回明确错误
+- **SC-003**: 平台用户可成功分配多个角色，代理/企业只能分配一个角色
+- **SC-004**: 权限校验正确考虑端口属性，Web 请求无法使用 H5 专用权限，反之亦然
+- **SC-005**: GET /api/v1/account/permissions 正确返回权限列表和菜单树
+- **SC-006**: 按端口过滤权限列表功能正常工作
--- a/openspec/changes/archive/2026-01-10-add-role-permission-system/tasks.md
+++ b/openspec/changes/archive/2026-01-10-add-role-permission-system/tasks.md
@@ -0,0 +1,136 @@
+# 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 可以并行