实现角色权限体系重构

本次提交完成了角色权限体系的重构，主要包括：

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>

internal/model/permission.go

@@ -9,13 +9,14 @@ type Permission struct {
 	gorm.Model
 	BaseModel `gorm:"embedded"`
 
-	PermName string `gorm:"column:perm_name;not null;size:50" json:"perm_name"`
-	PermCode string `gorm:"column:perm_code;uniqueIndex:idx_permission_code,where:deleted_at IS NULL;not null;size:100" json:"perm_code"`
-	PermType int    `gorm:"column:perm_type;not null;index" json:"perm_type"` // 1=菜单, 2=按钮
-	URL      string `gorm:"column:url;size:255" json:"url,omitempty"`
-	ParentID *uint  `gorm:"column:parent_id;index" json:"parent_id,omitempty"`
-	Sort     int    `gorm:"column:sort;not null;default:0" json:"sort"`
-	Status   int    `gorm:"column:status;not null;default:1" json:"status"`
+	PermName string `gorm:"column:perm_name;not null;size:50;comment:权限名称" json:"perm_name"`
+	PermCode string `gorm:"column:perm_code;uniqueIndex:idx_permission_code,where:deleted_at IS NULL;not null;size:100;comment:权限编码" json:"perm_code"`
+	PermType int    `gorm:"column:perm_type;not null;index;comment:权限类型 1=菜单 2=按钮" json:"perm_type"`
+	Platform string `gorm:"column:platform;type:varchar(20);default:'all';comment:适用端口 all=全部 web=Web后台 h5=H5端" json:"platform"`
+	URL      string `gorm:"column:url;size:255;comment:URL路径" json:"url,omitempty"`
+	ParentID *uint  `gorm:"column:parent_id;index;comment:上级权限ID" json:"parent_id,omitempty"`
+	Sort     int    `gorm:"column:sort;not null;default:0;comment:排序" json:"sort"`
+	Status   int    `gorm:"column:status;not null;default:1;comment:状态 0=禁用 1=启用" json:"status"`
 }
 
 // TableName 指定表名

internal/model/permission_dto.go

@@ -5,6 +5,7 @@ type CreatePermissionRequest struct {
 	PermName string `json:"perm_name" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"权限名称"`
 	PermCode string `json:"perm_code" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"权限编码"`
 	PermType int    `json:"perm_type" validate:"required,min=1,max=2" required:"true" minimum:"1" maximum:"2" description:"权限类型 (1:菜单, 2:按钮)"`
+	Platform string `json:"platform" validate:"omitempty,oneof=all web h5" description:"适用端口 (all:全部, web:Web后台, h5:H5端)，默认为 all"`
 	URL      string `json:"url" validate:"omitempty,max=255" maxLength:"255" description:"请求路径"`
 	ParentID *uint  `json:"parent_id" description:"父权限ID"`
 	Sort     int    `json:"sort" validate:"omitempty,min=0" minimum:"0" description:"排序值"`
@@ -14,6 +15,7 @@ type CreatePermissionRequest struct {
 type UpdatePermissionRequest struct {
 	PermName *string `json:"perm_name" validate:"omitempty,min=1,max=50" minLength:"1" maxLength:"50" description:"权限名称"`
 	PermCode *string `json:"perm_code" validate:"omitempty,min=1,max=100" minLength:"1" maxLength:"100" description:"权限编码"`
+	Platform *string `json:"platform" validate:"omitempty,oneof=all web h5" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
 	URL      *string `json:"url" validate:"omitempty,max=255" maxLength:"255" description:"请求路径"`
 	ParentID *uint   `json:"parent_id" description:"父权限ID"`
 	Sort     *int    `json:"sort" validate:"omitempty,min=0" minimum:"0" description:"排序值"`
@@ -33,6 +35,7 @@ type PermissionListRequest struct {
 	PermName string `json:"perm_name" query:"perm_name" validate:"omitempty,max=50" maxLength:"50" description:"权限名称模糊查询"`
 	PermCode string `json:"perm_code" query:"perm_code" validate:"omitempty,max=100" maxLength:"100" description:"权限编码模糊查询"`
 	PermType *int   `json:"perm_type" query:"perm_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"权限类型"`
+	Platform string `json:"platform" query:"platform" validate:"omitempty,oneof=all web h5" description:"适用端口"`
 	ParentID *uint  `json:"parent_id" query:"parent_id" description:"父权限ID"`
 	Status   *int   `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"1" description:"状态"`
 }
@@ -43,6 +46,7 @@ type PermissionResponse struct {
 	PermName  string `json:"perm_name" description:"权限名称"`
 	PermCode  string `json:"perm_code" description:"权限编码"`
 	PermType  int    `json:"perm_type" description:"权限类型"`
+	Platform  string `json:"platform" description:"适用端口"`
 	URL       string `json:"url,omitempty" description:"请求路径"`
 	ParentID  *uint  `json:"parent_id,omitempty" description:"父权限ID"`
 	Sort      int    `json:"sort" description:"排序值"`
@@ -67,6 +71,7 @@ type PermissionTreeNode struct {
 	PermName string                `json:"perm_name" description:"权限名称"`
 	PermCode string                `json:"perm_code" description:"权限编码"`
 	PermType int                   `json:"perm_type" description:"权限类型"`
+	Platform string                `json:"platform" description:"适用端口"`
 	URL      string                `json:"url,omitempty" description:"请求路径"`
 	Sort     int                   `json:"sort" description:"排序值"`
 	Children []*PermissionTreeNode `json:"children,omitempty" description:"子权限列表"`

internal/model/role.go

@@ -9,10 +9,10 @@ type Role struct {
 	gorm.Model
 	BaseModel `gorm:"embedded"`
 
-	RoleName string `gorm:"column:role_name;not null;size:50" json:"role_name"`
-	RoleDesc string `gorm:"column:role_desc;size:255" json:"role_desc"`
-	RoleType int    `gorm:"column:role_type;not null;index" json:"role_type"` // 1=超级, 2=代理, 3=企业
-	Status   int    `gorm:"column:status;not null;default:1" json:"status"`
+	RoleName string `gorm:"column:role_name;not null;size:50;comment:角色名称" json:"role_name"`
+	RoleDesc string `gorm:"column:role_desc;size:255;comment:角色描述" json:"role_desc"`
+	RoleType int    `gorm:"column:role_type;not null;index;comment:角色类型 1=平台角色 2=客户角色" json:"role_type"`
+	Status   int    `gorm:"column:status;not null;default:1;comment:状态 0=禁用 1=启用" json:"status"`
 }
 
 // TableName 指定表名

internal/model/role_dto.go

@@ -4,7 +4,7 @@ package model
 type CreateRoleRequest struct {
 	RoleName string `json:"role_name" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"角色名称"`
 	RoleDesc string `json:"role_desc" validate:"omitempty,max=255" maxLength:"255" description:"角色描述"`
-	RoleType int    `json:"role_type" validate:"required,min=1,max=3" required:"true" minimum:"1" maximum:"3" description:"角色类型 (1:超级管理员, 2:普通管理员, 3:操作员)"`
+	RoleType int    `json:"role_type" validate:"required,min=1,max=2" required:"true" minimum:"1" maximum:"2" description:"角色类型 (1:平台角色, 2:客户角色)"`
 }
 
 // UpdateRoleRequest 更新角色请求
@@ -25,7 +25,7 @@ type RoleListRequest struct {
 	Page     int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
 	PageSize int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
 	RoleName string `json:"role_name" query:"role_name" validate:"omitempty,max=50" maxLength:"50" description:"角色名称模糊查询"`
-	RoleType *int   `json:"role_type" query:"role_type" validate:"omitempty,min=1,max=3" minimum:"1" maximum:"3" description:"角色类型"`
+	RoleType *int   `json:"role_type" query:"role_type" validate:"omitempty,min=1,max=2" minimum:"1" maximum:"2" description:"角色类型 (1:平台角色, 2:客户角色)"`
 	Status   *int   `json:"status" query:"status" validate:"omitempty,min=0,max=1" minimum:"0" maximum:"1" description:"状态"`
 }
 

internal/service/account/service.go

@@ -218,7 +218,7 @@ func (s *Service) AssignRoles(ctx context.Context, accountID uint, roleIDs []uin
 	}
 
 	// 检查账号存在
-	_, err := s.accountStore.GetByID(ctx, accountID)
+	account, err := s.accountStore.GetByID(ctx, accountID)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return nil, errors.New(errors.CodeAccountNotFound, "账号不存在")
@@ -226,15 +226,46 @@ func (s *Service) AssignRoles(ctx context.Context, accountID uint, roleIDs []uin
 		return nil, fmt.Errorf("获取账号失败: %w", err)
 	}
 
-	// 验证所有角色存在
+	// 检查用户类型是否允许分配角色
+	maxRoles := constants.GetMaxRolesForUserType(account.UserType)
+	if maxRoles == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "该用户类型不需要分配角色")
+	}
+
+	// 检查角色数量限制
+	existingCount, err := s.accountRoleStore.CountByAccountID(ctx, accountID)
+	if err != nil {
+		return nil, fmt.Errorf("统计现有角色数量失败: %w", err)
+	}
+
+	// 计算将要分配的新角色数量（排除已存在的）
+	newRoleCount := 0
 	for _, roleID := range roleIDs {
-		_, err := s.roleStore.GetByID(ctx, roleID)
+		exists, _ := s.accountRoleStore.Exists(ctx, accountID, roleID)
+		if !exists {
+			newRoleCount++
+		}
+	}
+
+	// 检查角色数量限制（-1 表示无限制）
+	if maxRoles != -1 && int(existingCount)+newRoleCount > maxRoles {
+		return nil, errors.New(errors.CodeInvalidParam, fmt.Sprintf("该用户类型最多只能分配 %d 个角色", maxRoles))
+	}
+
+	// 验证所有角色存在并检查角色类型是否匹配
+	for _, roleID := range roleIDs {
+		role, err := s.roleStore.GetByID(ctx, roleID)
 		if err != nil {
 			if err == gorm.ErrRecordNotFound {
 				return nil, errors.New(errors.CodeRoleNotFound, fmt.Sprintf("角色 %d 不存在", roleID))
 			}
 			return nil, fmt.Errorf("获取角色失败: %w", err)
 		}
+
+		// 检查角色类型与用户类型是否匹配
+		if !constants.IsRoleTypeMatchUserType(role.RoleType, account.UserType) {
+			return nil, errors.New(errors.CodeInvalidParam, "角色类型与账号类型不匹配")
+		}
 	}
 
 	// 创建关联

internal/service/permission/service.go

@@ -61,12 +61,18 @@ func (s *Service) Create(ctx context.Context, req *model.CreatePermissionRequest
 		PermName: req.PermName,
 		PermCode: req.PermCode,
 		PermType: req.PermType,
+		Platform: req.Platform,
 		URL:      req.URL,
 		ParentID: req.ParentID,
 		Sort:     req.Sort,
 		Status:   constants.StatusEnabled,
 	}
 
+	// 如果未指定 platform，默认为 all
+	if permission.Platform == "" {
+		permission.Platform = constants.PlatformAll
+	}
+
 	if err := s.permissionStore.Create(ctx, permission); err != nil {
 		return nil, fmt.Errorf("创建权限失败: %w", err)
 	}
@@ -119,6 +125,9 @@ func (s *Service) Update(ctx context.Context, id uint, req *model.UpdatePermissi
 		}
 		permission.PermCode = *req.PermCode
 	}
+	if req.Platform != nil {
+		permission.Platform = *req.Platform
+	}
 	if req.URL != nil {
 		permission.URL = *req.URL
 	}
@@ -188,6 +197,9 @@ func (s *Service) List(ctx context.Context, req *model.PermissionListRequest) ([
 	if req.PermType != nil {
 		filters["perm_type"] = *req.PermType
 	}
+	if req.Platform != "" {
+		filters["platform"] = req.Platform
+	}
 	if req.ParentID != nil {
 		filters["parent_id"] = *req.ParentID
 	}
@@ -220,6 +232,7 @@ func buildPermissionTree(permissions []*model.Permission) []*model.PermissionTre
 			PermName: p.PermName,
 			PermCode: p.PermCode,
 			PermType: p.PermType,
+			Platform: p.Platform,
 			URL:      p.URL,
 			Sort:     p.Sort,
 			Children: make([]*model.PermissionTreeNode, 0),
@@ -242,3 +255,25 @@ func buildPermissionTree(permissions []*model.Permission) []*model.PermissionTre
 
 	return roots
 }
+
+// CheckPermission 检查用户是否拥有指定权限（实现 PermissionChecker 接口）
+// userID: 用户ID
+// permCode: 权限编码
+// platform: 端口类型 (all/web/h5)
+func (s *Service) CheckPermission(ctx context.Context, userID uint, permCode string, platform string) (bool, error) {
+	// 查询用户的所有权限（通过角色获取）
+	// 1. 先获取用户的角色列表
+	// 2. 再获取角色的权限列表
+	// 3. 检查是否包含指定权限编码，并且 platform 匹配
+
+	// 注意：这个方法需要访问 AccountRoleStore 和 RolePermissionStore
+	// 但为了避免循环依赖，我们可以：
+	// 方案1: 在 Service 中注入这些 Store（推荐）
+	// 方案2: 在 PermissionStore 中添加一个查询方法
+	// 方案3: 使用缓存层（Redis）来存储用户权限映射
+
+	// 这里先返回一个占位实现
+	// TODO: 实现完整的权限检查逻辑
+	// 需要在构造函数中注入 AccountRoleStore 和 RolePermissionStore
+	return false, errors.New(errors.CodeInternalError, "权限检查功能尚未完全实现")
+}

internal/store/postgres/account_role_store.go

@@ -76,3 +76,15 @@ func (s *AccountRoleStore) Exists(ctx context.Context, accountID, roleID uint) (
 	}
 	return count > 0, nil
 }
+
+// CountByAccountID 统计账号的角色数量
+func (s *AccountRoleStore) CountByAccountID(ctx context.Context, accountID uint) (int64, error) {
+	var count int64
+	if err := s.db.WithContext(ctx).
+		Model(&model.AccountRole{}).
+		Where("account_id = ?", accountID).
+		Count(&count).Error; err != nil {
+		return 0, err
+	}
+	return count, nil
+}

internal/store/postgres/permission_store.go

@@ -69,6 +69,9 @@ func (s *PermissionStore) List(ctx context.Context, opts *store.QueryOptions, fi
 	if permType, ok := filters["perm_type"].(int); ok {
 		query = query.Where("perm_type = ?", permType)
 	}
+	if platform, ok := filters["platform"].(string); ok && platform != "" {
+		query = query.Where("platform = ?", platform)
+	}
 	if parentID, ok := filters["parent_id"].(uint); ok {
 		query = query.Where("parent_id = ?", parentID)
 	}
@@ -120,3 +123,20 @@ func (s *PermissionStore) GetAll(ctx context.Context) ([]*model.Permission, erro
 	}
 	return permissions, nil
 }
+
+// GetByPlatform 根据端口获取权限列表
+// platform: 端口类型（all/web/h5），如果为空则返回所有权限
+func (s *PermissionStore) GetByPlatform(ctx context.Context, platform string) ([]*model.Permission, error) {
+	var permissions []*model.Permission
+	query := s.db.WithContext(ctx).Where("status = ?", 1) // 只获取启用的权限
+
+	if platform != "" {
+		// 获取指定端口的权限或通用权限（platform='all'）
+		query = query.Where("platform = ? OR platform = ?", platform, "all")
+	}
+
+	if err := query.Order("sort ASC, id ASC").Find(&permissions).Error; err != nil {
+		return nil, err
+	}
+	return permissions, nil
+}

migrations/000003_add_permission_platform_field.down.sql

@@ -0,0 +1,6 @@
+-- 删除 platform 字段
+ALTER TABLE tb_permission
+DROP COLUMN IF EXISTS platform;
+
+-- 恢复原 role_type 注释
+COMMENT ON COLUMN tb_role.role_type IS '角色类型: 1=超级, 2=代理, 3=企业';

migrations/000003_add_permission_platform_field.up.sql

@@ -0,0 +1,8 @@
+-- 添加 platform 字段到 tb_permission 表
+ALTER TABLE tb_permission
+ADD COLUMN platform VARCHAR(20) DEFAULT 'all';
+
+COMMENT ON COLUMN tb_permission.platform IS '适用端口: all-全部, web-Web后台, h5-H5端';
+
+-- 更新 tb_role 表的 role_type 字段注释
+COMMENT ON COLUMN tb_role.role_type IS '角色类型: 1=平台角色, 2=客户角色';

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. ~~客户角色是否需要进一步细分（代理专用/企业专用）？~~ - 暂不需要，共用客户角色

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** 提案完成后执行，因为角色分配规则需要基于新的用户类型定义。

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**: 按端口过滤权限列表功能正常工作

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 可以并行

openspec/specs/role-permission/spec.md

@@ -0,0 +1,145 @@
+# role-permission Specification
+
+## Purpose
+TBD - created by archiving change add-role-permission-system. Update Purpose after archive.
+## 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 关系构建层级菜单树结构
+
+---
+

pkg/constants/constants.go

@@ -60,9 +60,8 @@ const (
 
 // RBAC 角色类型常量
 const (
-	RoleTypeSuper      = 1 // 超级角色
-	RoleTypeAgent      = 2 // 代理角色
-	RoleTypeEnterprise = 3 // 企业角色
+	RoleTypePlatform = 1 // 平台角色（适用于平台用户）
+	RoleTypeCustomer = 2 // 客户角色（适用于代理/企业账号）
 )
 
 // RBAC 权限类型常量
@@ -71,6 +70,13 @@ const (
 	PermissionTypeButton = 2 // 按钮权限
 )
 
+// RBAC 权限端口常量
+const (
+	PlatformAll = "all" // 全部端口（Web + H5）
+	PlatformWeb = "web" // Web 后台
+	PlatformH5  = "h5"  // H5 端
+)
+
 // RBAC 状态常量
 const (
 	StatusDisabled = 0 // 禁用

pkg/constants/rbac.go

@@ -0,0 +1,37 @@
+package constants
+
+// IsRoleTypeMatchUserType 检查角色类型是否与用户类型匹配
+// 返回 true 表示匹配，false 表示不匹配
+func IsRoleTypeMatchUserType(roleType, userType int) bool {
+	switch userType {
+	case UserTypeSuperAdmin:
+		// 超级管理员不需要角色
+		return false
+	case UserTypePlatform:
+		// 平台用户只能分配平台角色
+		return roleType == RoleTypePlatform
+	case UserTypeAgent, UserTypeEnterprise:
+		// 代理/企业账号只能分配客户角色
+		return roleType == RoleTypeCustomer
+	default:
+		return false
+	}
+}
+
+// GetMaxRolesForUserType 获取用户类型允许的最大角色数量
+// 返回 0 表示不允许分配角色，-1 表示无限制
+func GetMaxRolesForUserType(userType int) int {
+	switch userType {
+	case UserTypeSuperAdmin:
+		// 超级管理员不需要角色
+		return 0
+	case UserTypePlatform:
+		// 平台用户可分配多个角色，无限制
+		return -1
+	case UserTypeAgent, UserTypeEnterprise:
+		// 代理/企业账号只能分配一个角色
+		return 1
+	default:
+		return 0
+	}
+}

pkg/middleware/permission.go

@@ -0,0 +1,184 @@
+package middleware
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/gofiber/fiber/v2"
+)
+
+// PermissionChecker 权限检查器接口
+// 用于查询用户的权限列表
+type PermissionChecker interface {
+	// CheckPermission 检查用户是否拥有指定权限
+	// userID: 用户ID
+	// permCode: 权限编码
+	// platform: 端口类型 (all/web/h5)
+	CheckPermission(ctx context.Context, userID uint, permCode string, platform string) (bool, error)
+}
+
+// PermissionConfig 权限校验中间件配置
+type PermissionConfig struct {
+	// PermissionChecker 权限检查器
+	PermissionChecker PermissionChecker
+
+	// Platform 端口类型 (all/web/h5)
+	// 如果为空，默认为 "all"
+	Platform string
+
+	// SkipSuperAdmin 是否跳过超级管理员的权限检查
+	// 默认为 true
+	SkipSuperAdmin bool
+}
+
+// RequirePermission 权限校验中间件
+// 检查当前用户是否拥有指定权限
+// 如果没有权限，返回 403 错误
+func RequirePermission(permCode string, config PermissionConfig) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		// 获取用户信息
+		userID := GetUserIDFromContext(c.UserContext())
+		if userID == 0 {
+			return errors.New(errors.CodeUnauthorized, "未认证的请求")
+		}
+
+		// 如果配置为跳过超级管理员，且当前用户是超级管理员，则跳过权限检查
+		if config.SkipSuperAdmin {
+			userType := GetUserTypeFromContext(c.UserContext())
+			if userType == constants.UserTypeSuperAdmin {
+				return c.Next()
+			}
+		}
+
+		// 确定端口类型
+		platform := config.Platform
+		if platform == "" {
+			platform = constants.PlatformAll
+		}
+
+		// 检查权限检查器是否已配置
+		if config.PermissionChecker == nil {
+			return errors.New(errors.CodeInternalError, "权限检查器未配置")
+		}
+
+		// 检查用户是否拥有该权限
+		hasPermission, err := config.PermissionChecker.CheckPermission(c.UserContext(), userID, permCode, platform)
+		if err != nil {
+			// 如果是 AppError，直接返回
+			if appErr, ok := err.(*errors.AppError); ok {
+				return appErr
+			}
+			// 否则包装为 AppError
+			return errors.Wrap(errors.CodeInternalError, "权限检查失败", err)
+		}
+
+		if !hasPermission {
+			return errors.New(errors.CodeForbidden, "无权限访问该资源")
+		}
+
+		return c.Next()
+	}
+}
+
+// RequireAnyPermission 检查用户是否拥有指定权限列表中的任意一个权限
+// 如果没有任何权限，返回 403 错误
+func RequireAnyPermission(permCodes []string, config PermissionConfig) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		// 获取用户信息
+		userID := GetUserIDFromContext(c.UserContext())
+		if userID == 0 {
+			return errors.New(errors.CodeUnauthorized, "未认证的请求")
+		}
+
+		// 如果配置为跳过超级管理员，且当前用户是超级管理员，则跳过权限检查
+		if config.SkipSuperAdmin {
+			userType := GetUserTypeFromContext(c.UserContext())
+			if userType == constants.UserTypeSuperAdmin {
+				return c.Next()
+			}
+		}
+
+		// 确定端口类型
+		platform := config.Platform
+		if platform == "" {
+			platform = constants.PlatformAll
+		}
+
+		// 检查权限检查器是否已配置
+		if config.PermissionChecker == nil {
+			return errors.New(errors.CodeInternalError, "权限检查器未配置")
+		}
+
+		// 检查用户是否拥有任意一个权限
+		for _, permCode := range permCodes {
+			hasPermission, err := config.PermissionChecker.CheckPermission(c.UserContext(), userID, permCode, platform)
+			if err != nil {
+				// 如果是 AppError，直接返回
+				if appErr, ok := err.(*errors.AppError); ok {
+					return appErr
+				}
+				// 否则包装为 AppError
+				return errors.Wrap(errors.CodeInternalError, "权限检查失败", err)
+			}
+
+			// 如果拥有任意一个权限，则放行
+			if hasPermission {
+				return c.Next()
+			}
+		}
+
+		return errors.New(errors.CodeForbidden, "无权限访问该资源")
+	}
+}
+
+// RequireAllPermissions 检查用户是否拥有指定权限列表中的所有权限
+// 如果缺少任意一个权限，返回 403 错误
+func RequireAllPermissions(permCodes []string, config PermissionConfig) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		// 获取用户信息
+		userID := GetUserIDFromContext(c.UserContext())
+		if userID == 0 {
+			return errors.New(errors.CodeUnauthorized, "未认证的请求")
+		}
+
+		// 如果配置为跳过超级管理员，且当前用户是超级管理员，则跳过权限检查
+		if config.SkipSuperAdmin {
+			userType := GetUserTypeFromContext(c.UserContext())
+			if userType == constants.UserTypeSuperAdmin {
+				return c.Next()
+			}
+		}
+
+		// 确定端口类型
+		platform := config.Platform
+		if platform == "" {
+			platform = constants.PlatformAll
+		}
+
+		// 检查权限检查器是否已配置
+		if config.PermissionChecker == nil {
+			return errors.New(errors.CodeInternalError, "权限检查器未配置")
+		}
+
+		// 检查用户是否拥有所有权限
+		for _, permCode := range permCodes {
+			hasPermission, err := config.PermissionChecker.CheckPermission(c.UserContext(), userID, permCode, platform)
+			if err != nil {
+				// 如果是 AppError，直接返回
+				if appErr, ok := err.(*errors.AppError); ok {
+					return appErr
+				}
+				// 否则包装为 AppError
+				return errors.Wrap(errors.CodeInternalError, "权限检查失败", err)
+			}
+
+			// 如果缺少任意一个权限，则拒绝访问
+			if !hasPermission {
+				return errors.New(errors.CodeForbidden, "无权限访问该资源")
+			}
+		}
+
+		return c.Next()
+	}
+}

tests/integration/account_role_test.go

@@ -97,7 +97,7 @@ func TestAccountRoleAssociation_AssignRoles(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "单角色测试",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -127,7 +127,7 @@ func TestAccountRoleAssociation_AssignRoles(t *testing.T) {
 		for i := 0; i < 3; i++ {
 			roles[i] = &model.Role{
 				RoleName: "多角色测试_" + string(rune('A'+i)),
-				RoleType: constants.RoleTypeSuper,
+				RoleType: constants.RoleTypePlatform,
 				Status:   constants.StatusEnabled,
 			}
 			db.Create(roles[i])
@@ -154,7 +154,7 @@ func TestAccountRoleAssociation_AssignRoles(t *testing.T) {
 		// 创建并分配角色
 		role := &model.Role{
 			RoleName: "获取角色列表测试",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -183,7 +183,7 @@ func TestAccountRoleAssociation_AssignRoles(t *testing.T) {
 		// 创建并分配角色
 		role := &model.Role{
 			RoleName: "移除角色测试",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -216,7 +216,7 @@ func TestAccountRoleAssociation_AssignRoles(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "重复分配测试",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -238,7 +238,7 @@ func TestAccountRoleAssociation_AssignRoles(t *testing.T) {
 	t.Run("账号不存在时分配角色失败", func(t *testing.T) {
 		role := &model.Role{
 			RoleName: "账号不存在测试",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -322,7 +322,7 @@ func TestAccountRoleAssociation_SoftDelete(t *testing.T) {
 
 		role := &model.Role{
 			RoleName: "恢复角色测试",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)

tests/integration/account_test.go

@@ -187,7 +187,6 @@ func TestAccountAPI_Create(t *testing.T) {
 			Phone:    "13800000001",
 			Password: "Password123",
 			UserType: constants.UserTypePlatform,
-			ParentID: &rootAccount.ID,
 		}
 
 		jsonBody, _ := json.Marshal(reqBody)
@@ -216,7 +215,6 @@ func TestAccountAPI_Create(t *testing.T) {
 			Phone:    "13800000002",
 			Password: "hashedpassword",
 			UserType: constants.UserTypePlatform,
-			ParentID: &rootAccount.ID,
 			Status:   constants.StatusEnabled,
 		}
 		createTestAccount(t, env.db, existingAccount)
@@ -227,7 +225,6 @@ func TestAccountAPI_Create(t *testing.T) {
 			Phone:    "13800000003",
 			Password: "Password123",
 			UserType: constants.UserTypePlatform,
-			ParentID: &rootAccount.ID,
 		}
 
 		jsonBody, _ := json.Marshal(reqBody)
@@ -476,7 +473,7 @@ func TestAccountAPI_AssignRoles(t *testing.T) {
 	// 创建测试角色
 	testRole := &model.Role{
 		RoleName: "测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)
@@ -527,7 +524,7 @@ func TestAccountAPI_GetRoles(t *testing.T) {
 	// 创建并分配角色
 	testRole := &model.Role{
 		RoleName: "获取角色测试",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)
@@ -580,7 +577,7 @@ func TestAccountAPI_RemoveRole(t *testing.T) {
 	// 创建并分配角色
 	testRole := &model.Role{
 		RoleName: "移除角色测试",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)

tests/integration/api_regression_test.go

@@ -230,7 +230,7 @@ func TestAPIRegression_RouteModularization(t *testing.T) {
 		// 创建测试数据
 		role := &model.Role{
 			RoleName: "回归测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		env.db.Create(role)

tests/integration/permission_middleware_test.go

@@ -0,0 +1,130 @@
+package integration
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+)
+
+// MockPermissionChecker 模拟权限检查器
+type MockPermissionChecker struct {
+	permissions map[uint]map[string]bool // userID -> permCode -> hasPermission
+}
+
+func NewMockPermissionChecker() *MockPermissionChecker {
+	return &MockPermissionChecker{
+		permissions: make(map[uint]map[string]bool),
+	}
+}
+
+func (m *MockPermissionChecker) GrantPermission(userID uint, permCode string) {
+	if m.permissions[userID] == nil {
+		m.permissions[userID] = make(map[string]bool)
+	}
+	m.permissions[userID][permCode] = true
+}
+
+func (m *MockPermissionChecker) CheckPermission(ctx context.Context, userID uint, permCode string, platform string) (bool, error) {
+	if m.permissions[userID] == nil {
+		return false, nil
+	}
+	return m.permissions[userID][permCode], nil
+}
+
+// TestPermissionMiddleware_RequirePermission 测试权限校验中间件（单个权限）
+// TODO: 完整实现需要启动 Fiber 应用并模拟 HTTP 请求
+func TestPermissionMiddleware_RequirePermission(t *testing.T) {
+	t.Skip("TODO: 需要完整的 Fiber 集成测试环境")
+
+	// 占位测试：验证 PermissionChecker 接口可以被 mock
+	checker := NewMockPermissionChecker()
+	checker.GrantPermission(1, "user:read")
+
+	ctx := context.Background()
+	hasPermission, err := checker.CheckPermission(ctx, 1, "user:read", constants.PlatformAll)
+	assert.NoError(t, err)
+	assert.True(t, hasPermission)
+
+	hasPermission, err = checker.CheckPermission(ctx, 1, "user:write", constants.PlatformAll)
+	assert.NoError(t, err)
+	assert.False(t, hasPermission)
+}
+
+// TestPermissionMiddleware_RequireAnyPermission 测试权限校验中间件（多个权限任一）
+func TestPermissionMiddleware_RequireAnyPermission(t *testing.T) {
+	t.Skip("TODO: 需要完整的 Fiber 集成测试环境")
+}
+
+// TestPermissionMiddleware_RequireAllPermissions 测试权限校验中间件（多个权限全部）
+func TestPermissionMiddleware_RequireAllPermissions(t *testing.T) {
+	t.Skip("TODO: 需要完整的 Fiber 集成测试环境")
+}
+
+// TestPermissionMiddleware_SkipSuperAdmin 测试超级管理员跳过权限检查
+func TestPermissionMiddleware_SkipSuperAdmin(t *testing.T) {
+	t.Skip("TODO: 需要完整的 Fiber 集成测试环境")
+}
+
+// TestPermissionMiddleware_PlatformFiltering 测试按 platform 过滤权限
+func TestPermissionMiddleware_PlatformFiltering(t *testing.T) {
+	t.Skip("TODO: 需要完整的 Fiber 集成测试环境")
+
+	// 测试场景：
+	// 1. Web 端请求需要 Web 权限
+	// 2. H5 端请求需要 H5 权限
+	// 3. all 权限在所有端口都有效
+}
+
+// TestPermissionMiddleware_Unauthorized 测试未认证用户访问受保护路由
+func TestPermissionMiddleware_Unauthorized(t *testing.T) {
+	t.Skip("TODO: 需要完整的 Fiber 集成测试环境")
+}
+
+// 集成测试实现指南:
+//
+// 完整的集成测试应该：
+// 1. 启动 Fiber 应用
+// 2. 注册受权限保护的路由：
+//    - 使用 middleware.RequirePermission("user:read", config)
+//    - 使用 middleware.RequireAnyPermission([]string{"user:read", "user:write"}, config)
+//    - 使用 middleware.RequireAllPermissions([]string{"user:read", "user:write"}, config)
+// 3. 模拟不同用户的 HTTP 请求
+// 4. 验证权限检查结果（200 OK 或 403 Forbidden）
+//
+// 示例代码结构：
+//
+// func TestPermissionMiddleware_Integration(t *testing.T) {
+//     // 1. 初始化数据库和 Redis
+//     db, redisClient := testutils.SetupTestDB(t)
+//     defer testutils.TeardownTestDB(t, db, redisClient)
+//
+//     // 2. 创建测试数据（用户、角色、权限）
+//     // ...
+//
+//     // 3. 初始化 Service 和 Middleware
+//     permissionService := permission.New(permissionStore)
+//     config := middleware.PermissionConfig{
+//         PermissionChecker: permissionService,
+//         Platform:          constants.PlatformWeb,
+//         SkipSuperAdmin:    true,
+//     }
+//
+//     // 4. 创建 Fiber 应用并注册路由
+//     app := fiber.New()
+//     app.Get("/protected",
+//         middleware.RequirePermission("user:read", config),
+//         func(c *fiber.Ctx) error {
+//             return c.JSON(fiber.Map{"message": "success"})
+//         },
+//     )
+//
+//     // 5. 模拟请求并验证响应
+//     req := httptest.NewRequest("GET", "/protected", nil)
+//     // 设置认证信息...
+//     resp, err := app.Test(req)
+//     require.NoError(t, err)
+//     assert.Equal(t, fiber.StatusOK, resp.StatusCode)
+// }

tests/integration/role_permission_test.go

@@ -70,7 +70,7 @@ func TestRolePermissionAssociation_AssignPermissions(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "单权限测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -96,7 +96,7 @@ func TestRolePermissionAssociation_AssignPermissions(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "多权限测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -124,7 +124,7 @@ func TestRolePermissionAssociation_AssignPermissions(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "获取权限列表测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -152,7 +152,7 @@ func TestRolePermissionAssociation_AssignPermissions(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "移除权限测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -184,7 +184,7 @@ func TestRolePermissionAssociation_AssignPermissions(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "重复权限测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -228,7 +228,7 @@ func TestRolePermissionAssociation_AssignPermissions(t *testing.T) {
 	t.Run("权限不存在时分配失败", func(t *testing.T) {
 		role := &model.Role{
 			RoleName: "权限不存在测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -276,7 +276,7 @@ func TestRolePermissionAssociation_SoftDelete(t *testing.T) {
 		// 创建测试数据
 		role := &model.Role{
 			RoleName: "恢复权限测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -312,7 +312,7 @@ func TestRolePermissionAssociation_SoftDelete(t *testing.T) {
 		// 创建测试角色
 		role := &model.Role{
 			RoleName: "批量权限测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)
@@ -383,7 +383,7 @@ func TestRolePermissionAssociation_Cascade(t *testing.T) {
 		// 创建角色和权限
 		role := &model.Role{
 			RoleName: "级联测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		db.Create(role)

tests/integration/role_test.go

@@ -167,7 +167,7 @@ func TestRoleAPI_Create(t *testing.T) {
 		reqBody := model.CreateRoleRequest{
 			RoleName: "测试角色",
 			RoleDesc: "这是一个测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 		}
 
 		jsonBody, _ := json.Marshal(reqBody)
@@ -224,7 +224,7 @@ func TestRoleAPI_Get(t *testing.T) {
 	// 创建测试角色
 	testRole := &model.Role{
 		RoleName: "获取测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)
@@ -269,7 +269,7 @@ func TestRoleAPI_Update(t *testing.T) {
 	// 创建测试角色
 	testRole := &model.Role{
 		RoleName: "更新测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)
@@ -312,7 +312,7 @@ func TestRoleAPI_Delete(t *testing.T) {
 		// 创建测试角色
 		testRole := &model.Role{
 			RoleName: "删除测试角色",
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		env.db.Create(testRole)
@@ -347,7 +347,7 @@ func TestRoleAPI_List(t *testing.T) {
 	for i := 1; i <= 5; i++ {
 		role := &model.Role{
 			RoleName: fmt.Sprintf("列表测试角色_%d", i),
-			RoleType: constants.RoleTypeSuper,
+			RoleType: constants.RoleTypePlatform,
 			Status:   constants.StatusEnabled,
 		}
 		env.db.Create(role)
@@ -382,7 +382,7 @@ func TestRoleAPI_AssignPermissions(t *testing.T) {
 	// 创建测试角色
 	testRole := &model.Role{
 		RoleName: "权限分配测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)
@@ -432,7 +432,7 @@ func TestRoleAPI_GetPermissions(t *testing.T) {
 	// 创建测试角色
 	testRole := &model.Role{
 		RoleName: "获取权限测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)
@@ -482,7 +482,7 @@ func TestRoleAPI_RemovePermission(t *testing.T) {
 	// 创建测试角色
 	testRole := &model.Role{
 		RoleName: "移除权限测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	env.db.Create(testRole)

tests/unit/account_model_test.go

@@ -37,32 +37,7 @@ func TestAccountModel_Create(t *testing.T) {
 		assert.NotZero(t, account.UpdatedAt)
 	})
 
-	t.Run("创建带 parent_id 的账号", func(t *testing.T) {
-		// 先创建父账号
-		parent := &model.Account{
-			Username: "parent_user",
-			Phone:    "13800000002",
-			Password: "hashed_password",
-			UserType: constants.UserTypePlatform,
-			Status:   constants.StatusEnabled,
-		}
-		err := store.Create(ctx, parent)
-		require.NoError(t, err)
-
-		// 创建子账号
-		child := &model.Account{
-			Username: "child_user",
-			Phone:    "13800000003",
-			Password: "hashed_password",
-			UserType: constants.UserTypeAgent,
-			ParentID: &parent.ID,
-			Status:   constants.StatusEnabled,
-		}
-		err = store.Create(ctx, child)
-		require.NoError(t, err)
-		assert.NotZero(t, child.ID)
-		assert.Equal(t, parent.ID, *child.ParentID)
-	})
+	// 注意：parent_id 字段已被移除，层级关系通过 shop_id 和 enterprise_id 维护
 
 	t.Run("创建带 shop_id 的账号", func(t *testing.T) {
 		shopID := uint(100)

tests/unit/permission_platform_filter_test.go

@@ -0,0 +1,209 @@
+package unit
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/service/permission"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/tests/testutils"
+)
+
+// TestPermissionPlatformFilter_List 测试权限列表按 platform 过滤
+func TestPermissionPlatformFilter_List(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	permissionStore := postgres.NewPermissionStore(db)
+	service := permission.New(permissionStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	// 创建不同 platform 的权限
+	permissions := []*model.Permission{
+		{PermName: "全端菜单", PermCode: "menu:all", PermType: constants.PermissionTypeMenu, Platform: constants.PlatformAll, Status: constants.StatusEnabled},
+		{PermName: "Web菜单", PermCode: "menu:web", PermType: constants.PermissionTypeMenu, Platform: constants.PlatformWeb, Status: constants.StatusEnabled},
+		{PermName: "H5菜单", PermCode: "menu:h5", PermType: constants.PermissionTypeMenu, Platform: constants.PlatformH5, Status: constants.StatusEnabled},
+		{PermName: "Web按钮", PermCode: "button:web", PermType: constants.PermissionTypeButton, Platform: constants.PlatformWeb, Status: constants.StatusEnabled},
+		{PermName: "H5按钮", PermCode: "button:h5", PermType: constants.PermissionTypeButton, Platform: constants.PlatformH5, Status: constants.StatusEnabled},
+	}
+	for _, perm := range permissions {
+		require.NoError(t, db.Create(perm).Error)
+	}
+
+	// 测试查询全部权限（不过滤）
+	t.Run("查询全部权限", func(t *testing.T) {
+		req := &model.PermissionListRequest{
+			Page:     1,
+			PageSize: 10,
+		}
+		perms, total, err := service.List(ctx, req)
+		require.NoError(t, err)
+		assert.Equal(t, int64(5), total)
+		assert.Len(t, perms, 5)
+	})
+
+	// 测试只查询 all 权限
+	t.Run("只查询all端口权限", func(t *testing.T) {
+		req := &model.PermissionListRequest{
+			Page:     1,
+			PageSize: 10,
+			Platform: constants.PlatformAll,
+		}
+		perms, total, err := service.List(ctx, req)
+		require.NoError(t, err)
+		assert.Equal(t, int64(1), total)
+		assert.Len(t, perms, 1)
+		assert.Equal(t, "全端菜单", perms[0].PermName)
+	})
+
+	// 测试只查询 web 权限
+	t.Run("只查询web端口权限", func(t *testing.T) {
+		req := &model.PermissionListRequest{
+			Page:     1,
+			PageSize: 10,
+			Platform: constants.PlatformWeb,
+		}
+		perms, total, err := service.List(ctx, req)
+		require.NoError(t, err)
+		assert.Equal(t, int64(2), total)
+		assert.Len(t, perms, 2)
+		// 验证都是 web 端口的权限
+		for _, perm := range perms {
+			assert.Equal(t, constants.PlatformWeb, perm.Platform)
+		}
+	})
+
+	// 测试只查询 h5 权限
+	t.Run("只查询h5端口权限", func(t *testing.T) {
+		req := &model.PermissionListRequest{
+			Page:     1,
+			PageSize: 10,
+			Platform: constants.PlatformH5,
+		}
+		perms, total, err := service.List(ctx, req)
+		require.NoError(t, err)
+		assert.Equal(t, int64(2), total)
+		assert.Len(t, perms, 2)
+		// 验证都是 h5 端口的权限
+		for _, perm := range perms {
+			assert.Equal(t, constants.PlatformH5, perm.Platform)
+		}
+	})
+}
+
+// TestPermissionPlatformFilter_CreateWithDefaultPlatform 测试创建权限时默认 platform 为 all
+func TestPermissionPlatformFilter_CreateWithDefaultPlatform(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	permissionStore := postgres.NewPermissionStore(db)
+	service := permission.New(permissionStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	// 创建权限时不指定 platform
+	req := &model.CreatePermissionRequest{
+		PermName: "测试权限",
+		PermCode: "test:permission",
+		PermType: constants.PermissionTypeMenu,
+		// Platform 字段为空
+	}
+
+	perm, err := service.Create(ctx, req)
+	require.NoError(t, err)
+	assert.Equal(t, constants.PlatformAll, perm.Platform, "未指定 platform 时应默认为 all")
+}
+
+// TestPermissionPlatformFilter_CreateWithSpecificPlatform 测试创建权限时指定 platform
+func TestPermissionPlatformFilter_CreateWithSpecificPlatform(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	permissionStore := postgres.NewPermissionStore(db)
+	service := permission.New(permissionStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	tests := []struct {
+		name     string
+		platform string
+		expected string
+	}{
+		{name: "指定为all", platform: constants.PlatformAll, expected: constants.PlatformAll},
+		{name: "指定为web", platform: constants.PlatformWeb, expected: constants.PlatformWeb},
+		{name: "指定为h5", platform: constants.PlatformH5, expected: constants.PlatformH5},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := &model.CreatePermissionRequest{
+				PermName: "测试权限_" + tt.platform,
+				PermCode: "test:" + tt.platform,
+				PermType: constants.PermissionTypeMenu,
+				Platform: tt.platform,
+			}
+
+			perm, err := service.Create(ctx, req)
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, perm.Platform)
+		})
+	}
+}
+
+// TestPermissionPlatformFilter_Tree 测试权限树包含 platform 字段
+func TestPermissionPlatformFilter_Tree(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	permissionStore := postgres.NewPermissionStore(db)
+	service := permission.New(permissionStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	// 创建层级权限
+	parent := &model.Permission{
+		PermName: "系统管理",
+		PermCode: "system:manage",
+		PermType: constants.PermissionTypeMenu,
+		Platform: constants.PlatformWeb,
+		Status:   constants.StatusEnabled,
+	}
+	require.NoError(t, db.Create(parent).Error)
+
+	child := &model.Permission{
+		PermName: "用户管理",
+		PermCode: "user:manage",
+		PermType: constants.PermissionTypeMenu,
+		Platform: constants.PlatformWeb,
+		ParentID: &parent.ID,
+		Status:   constants.StatusEnabled,
+	}
+	require.NoError(t, db.Create(child).Error)
+
+	// 获取权限树
+	tree, err := service.GetTree(ctx)
+	require.NoError(t, err)
+	require.Len(t, tree, 1)
+
+	// 验证父节点
+	root := tree[0]
+	assert.Equal(t, "系统管理", root.PermName)
+	assert.Equal(t, constants.PlatformWeb, root.Platform)
+
+	// 验证子节点
+	require.Len(t, root.Children, 1)
+	childNode := root.Children[0]
+	assert.Equal(t, "用户管理", childNode.PermName)
+	assert.Equal(t, constants.PlatformWeb, childNode.Platform)
+}

tests/unit/role_assignment_limit_test.go

@@ -0,0 +1,179 @@
+package unit
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/service/account"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/tests/testutils"
+)
+
+// TestRoleAssignmentLimit_PlatformUser 测试平台用户可以分配多个角色（无限制）
+func TestRoleAssignmentLimit_PlatformUser(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	accountStore := postgres.NewAccountStore(db, redisClient)
+	roleStore := postgres.NewRoleStore(db)
+	accountRoleStore := postgres.NewAccountRoleStore(db)
+	service := account.New(accountStore, roleStore, accountRoleStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	// 创建平台用户
+	platformUser := &model.Account{
+		Username: "platform_user",
+		Phone:    "13800000001",
+		Password: "hashedpassword",
+		UserType: constants.UserTypePlatform,
+		Status:   constants.StatusEnabled,
+	}
+	require.NoError(t, db.Create(platformUser).Error)
+
+	// 创建 3 个平台角色
+	roles := []*model.Role{
+		{RoleName: "运营", RoleType: constants.RoleTypePlatform, Status: constants.StatusEnabled},
+		{RoleName: "客服", RoleType: constants.RoleTypePlatform, Status: constants.StatusEnabled},
+		{RoleName: "财务", RoleType: constants.RoleTypePlatform, Status: constants.StatusEnabled},
+	}
+	for _, role := range roles {
+		require.NoError(t, db.Create(role).Error)
+	}
+
+	// 为平台用户分配 3 个角色（应该成功，因为平台用户无限制）
+	roleIDs := []uint{roles[0].ID, roles[1].ID, roles[2].ID}
+	ars, err := service.AssignRoles(ctx, platformUser.ID, roleIDs)
+	require.NoError(t, err)
+	assert.Len(t, ars, 3)
+}
+
+// TestRoleAssignmentLimit_AgentUser 测试代理账号只能分配一个角色
+func TestRoleAssignmentLimit_AgentUser(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	accountStore := postgres.NewAccountStore(db, redisClient)
+	roleStore := postgres.NewRoleStore(db)
+	accountRoleStore := postgres.NewAccountRoleStore(db)
+	service := account.New(accountStore, roleStore, accountRoleStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	// 创建代理账号
+	agentAccount := &model.Account{
+		Username: "agent_user",
+		Phone:    "13800000002",
+		Password: "hashedpassword",
+		UserType: constants.UserTypeAgent,
+		Status:   constants.StatusEnabled,
+	}
+	require.NoError(t, db.Create(agentAccount).Error)
+
+	// 创建 2 个客户角色
+	roles := []*model.Role{
+		{RoleName: "一级代理", RoleType: constants.RoleTypeCustomer, Status: constants.StatusEnabled},
+		{RoleName: "二级代理", RoleType: constants.RoleTypeCustomer, Status: constants.StatusEnabled},
+	}
+	for _, role := range roles {
+		require.NoError(t, db.Create(role).Error)
+	}
+
+	// 先分配第一个角色（应该成功）
+	ars, err := service.AssignRoles(ctx, agentAccount.ID, []uint{roles[0].ID})
+	require.NoError(t, err)
+	assert.Len(t, ars, 1)
+
+	// 尝试分配第二个角色（应该失败，超过数量限制）
+	_, err = service.AssignRoles(ctx, agentAccount.ID, []uint{roles[1].ID})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "最多只能分配 1 个角色")
+}
+
+// TestRoleAssignmentLimit_EnterpriseUser 测试企业账号只能分配一个角色
+func TestRoleAssignmentLimit_EnterpriseUser(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	accountStore := postgres.NewAccountStore(db, redisClient)
+	roleStore := postgres.NewRoleStore(db)
+	accountRoleStore := postgres.NewAccountRoleStore(db)
+	service := account.New(accountStore, roleStore, accountRoleStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	// 创建企业账号
+	enterpriseAccount := &model.Account{
+		Username: "enterprise_user",
+		Phone:    "13800000003",
+		Password: "hashedpassword",
+		UserType: constants.UserTypeEnterprise,
+		Status:   constants.StatusEnabled,
+	}
+	require.NoError(t, db.Create(enterpriseAccount).Error)
+
+	// 创建 2 个客户角色
+	roles := []*model.Role{
+		{RoleName: "企业普通", RoleType: constants.RoleTypeCustomer, Status: constants.StatusEnabled},
+		{RoleName: "企业高级", RoleType: constants.RoleTypeCustomer, Status: constants.StatusEnabled},
+	}
+	for _, role := range roles {
+		require.NoError(t, db.Create(role).Error)
+	}
+
+	// 先分配第一个角色（应该成功）
+	ars, err := service.AssignRoles(ctx, enterpriseAccount.ID, []uint{roles[0].ID})
+	require.NoError(t, err)
+	assert.Len(t, ars, 1)
+
+	// 尝试分配第二个角色（应该失败，超过数量限制）
+	_, err = service.AssignRoles(ctx, enterpriseAccount.ID, []uint{roles[1].ID})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "最多只能分配 1 个角色")
+}
+
+// TestRoleAssignmentLimit_SuperAdmin 测试超级管理员不允许分配角色
+func TestRoleAssignmentLimit_SuperAdmin(t *testing.T) {
+	db, redisClient := testutils.SetupTestDB(t)
+	defer testutils.TeardownTestDB(t, db, redisClient)
+
+	accountStore := postgres.NewAccountStore(db, redisClient)
+	roleStore := postgres.NewRoleStore(db)
+	accountRoleStore := postgres.NewAccountRoleStore(db)
+	service := account.New(accountStore, roleStore, accountRoleStore)
+
+	ctx := context.Background()
+	ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeSuperAdmin, 0)
+
+	// 创建超级管理员
+	superAdmin := &model.Account{
+		Username: "superadmin",
+		Phone:    "13800000004",
+		Password: "hashedpassword",
+		UserType: constants.UserTypeSuperAdmin,
+		Status:   constants.StatusEnabled,
+	}
+	require.NoError(t, db.Create(superAdmin).Error)
+
+	// 创建一个平台角色
+	role := &model.Role{
+		RoleName: "测试角色",
+		RoleType: constants.RoleTypePlatform,
+		Status:   constants.StatusEnabled,
+	}
+	require.NoError(t, db.Create(role).Error)
+
+	// 尝试为超级管理员分配角色（应该失败）
+	_, err := service.AssignRoles(ctx, superAdmin.ID, []uint{role.ID})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "不需要分配角色")
+}

tests/unit/role_type_matching_test.go

@@ -0,0 +1,111 @@
+package unit
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+)
+
+// TestIsRoleTypeMatchUserType 测试角色类型与用户类型匹配规则
+func TestIsRoleTypeMatchUserType(t *testing.T) {
+	tests := []struct {
+		name     string
+		roleType int
+		userType int
+		expected bool
+	}{
+		{
+			name:     "超级管理员不需要角色",
+			roleType: constants.RoleTypePlatform,
+			userType: constants.UserTypeSuperAdmin,
+			expected: false,
+		},
+		{
+			name:     "平台用户匹配平台角色",
+			roleType: constants.RoleTypePlatform,
+			userType: constants.UserTypePlatform,
+			expected: true,
+		},
+		{
+			name:     "平台用户不匹配客户角色",
+			roleType: constants.RoleTypeCustomer,
+			userType: constants.UserTypePlatform,
+			expected: false,
+		},
+		{
+			name:     "代理账号匹配客户角色",
+			roleType: constants.RoleTypeCustomer,
+			userType: constants.UserTypeAgent,
+			expected: true,
+		},
+		{
+			name:     "代理账号不匹配平台角色",
+			roleType: constants.RoleTypePlatform,
+			userType: constants.UserTypeAgent,
+			expected: false,
+		},
+		{
+			name:     "企业账号匹配客户角色",
+			roleType: constants.RoleTypeCustomer,
+			userType: constants.UserTypeEnterprise,
+			expected: true,
+		},
+		{
+			name:     "企业账号不匹配平台角色",
+			roleType: constants.RoleTypePlatform,
+			userType: constants.UserTypeEnterprise,
+			expected: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := constants.IsRoleTypeMatchUserType(tt.roleType, tt.userType)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+// TestGetMaxRolesForUserType 测试用户类型的最大角色数量限制
+func TestGetMaxRolesForUserType(t *testing.T) {
+	tests := []struct {
+		name     string
+		userType int
+		expected int
+	}{
+		{
+			name:     "超级管理员不需要角色",
+			userType: constants.UserTypeSuperAdmin,
+			expected: 0,
+		},
+		{
+			name:     "平台用户无角色数量限制",
+			userType: constants.UserTypePlatform,
+			expected: -1, // -1 表示无限制
+		},
+		{
+			name:     "代理账号最多一个角色",
+			userType: constants.UserTypeAgent,
+			expected: 1,
+		},
+		{
+			name:     "企业账号最多一个角色",
+			userType: constants.UserTypeEnterprise,
+			expected: 1,
+		},
+		{
+			name:     "未知用户类型不允许角色",
+			userType: 999,
+			expected: 0,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := constants.GetMaxRolesForUserType(tt.userType)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}

tests/unit/soft_delete_test.go

@@ -78,7 +78,7 @@ func TestRoleSoftDelete(t *testing.T) {
 	role := &model.Role{
 		RoleName: "test_role",
 		RoleDesc: "测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	err := roleStore.Create(ctx, role)
@@ -169,7 +169,7 @@ func TestAccountRoleSoftDelete(t *testing.T) {
 	role := &model.Role{
 		RoleName: "ar_role",
 		RoleDesc: "测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	err = roleStore.Create(ctx, role)
@@ -228,7 +228,7 @@ func TestRolePermissionSoftDelete(t *testing.T) {
 	role := &model.Role{
 		RoleName: "rp_role",
 		RoleDesc: "测试角色",
-		RoleType: constants.RoleTypeSuper,
+		RoleType: constants.RoleTypePlatform,
 		Status:   constants.StatusEnabled,
 	}
 	err := roleStore.Create(ctx, role)

tests/unit/subordinate_cache_test.go

@@ -1,276 +0,0 @@
-package unit
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	"github.com/bytedance/sonic"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
-	"github.com/break/junhong_cmp_fiber/internal/model"
-	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
-	"github.com/break/junhong_cmp_fiber/pkg/constants"
-	"github.com/break/junhong_cmp_fiber/tests/testutils"
-)
-
-// TestGetSubordinateIDs_CacheHit 测试 Redis 缓存命中
-func TestGetSubordinateIDs_CacheHit(t *testing.T) {
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建测试账号
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	accountB := &model.Account{
-		Username: "user_b",
-		Phone:    "13800000002",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountA.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountB).Error)
-
-	// 第一次查询（缓存未命中，会写入缓存）
-	ids1, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids1, 2)
-
-	// 验证缓存已写入
-	cacheKey := constants.RedisAccountSubordinatesKey(accountA.ID)
-	cached, err := redisClient.Get(ctx, cacheKey).Result()
-	require.NoError(t, err)
-	var cachedIDs []uint
-	require.NoError(t, sonic.Unmarshal([]byte(cached), &cachedIDs))
-	assert.Equal(t, ids1, cachedIDs)
-
-	// 第二次查询（缓存命中，不查询数据库）
-	ids2, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Equal(t, ids1, ids2)
-}
-
-// TestGetSubordinateIDs_CacheExpiry 测试缓存过期
-func TestGetSubordinateIDs_CacheExpiry(t *testing.T) {
-	if testing.Short() {
-		t.Skip("跳过缓存过期测试")
-	}
-
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建测试账号
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	// 第一次查询（写入缓存）
-	ids1, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-
-	// 验证缓存 TTL（应该是 30 分钟）
-	cacheKey := constants.RedisAccountSubordinatesKey(accountA.ID)
-	ttl, err := redisClient.TTL(ctx, cacheKey).Result()
-	require.NoError(t, err)
-	assert.Greater(t, ttl, 29*time.Minute)
-	assert.LessOrEqual(t, ttl, 30*time.Minute)
-
-	// 模拟缓存过期（手动删除）
-	require.NoError(t, redisClient.Del(ctx, cacheKey).Err())
-
-	// 再次查询（缓存未命中，重新查询数据库）
-	ids2, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Equal(t, ids1, ids2)
-
-	// 验证缓存已重新写入
-	cached, err := redisClient.Get(ctx, cacheKey).Result()
-	require.NoError(t, err)
-	var cachedIDs []uint
-	require.NoError(t, sonic.Unmarshal([]byte(cached), &cachedIDs))
-	assert.Equal(t, ids2, cachedIDs)
-}
-
-// TestClearSubordinatesCache 测试清除指定账号的缓存
-func TestClearSubordinatesCache(t *testing.T) {
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建测试账号
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	// 查询以写入缓存
-	_, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-
-	// 验证缓存存在
-	cacheKey := constants.RedisAccountSubordinatesKey(accountA.ID)
-	exists, err := redisClient.Exists(ctx, cacheKey).Result()
-	require.NoError(t, err)
-	assert.Equal(t, int64(1), exists)
-
-	// 清除缓存
-	err = store.ClearSubordinatesCache(ctx, accountA.ID)
-	require.NoError(t, err)
-
-	// 验证缓存已删除
-	exists, err = redisClient.Exists(ctx, cacheKey).Result()
-	require.NoError(t, err)
-	assert.Equal(t, int64(0), exists)
-}
-
-// TestClearSubordinatesCacheForParents 测试递归清除上级缓存
-func TestClearSubordinatesCacheForParents(t *testing.T) {
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建层级结构: A -> B -> C
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	accountB := &model.Account{
-		Username: "user_b",
-		Phone:    "13800000002",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountA.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountB).Error)
-
-	accountC := &model.Account{
-		Username: "user_c",
-		Phone:    "13800000003",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountB.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountC).Error)
-
-	// 查询所有账号以写入缓存
-	_, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	_, err = store.GetSubordinateIDs(ctx, accountB.ID)
-	require.NoError(t, err)
-	_, err = store.GetSubordinateIDs(ctx, accountC.ID)
-	require.NoError(t, err)
-
-	// 验证所有缓存存在
-	cacheKeyA := constants.RedisAccountSubordinatesKey(accountA.ID)
-	cacheKeyB := constants.RedisAccountSubordinatesKey(accountB.ID)
-	cacheKeyC := constants.RedisAccountSubordinatesKey(accountC.ID)
-
-	exists, _ := redisClient.Exists(ctx, cacheKeyA).Result()
-	assert.Equal(t, int64(1), exists)
-	exists, _ = redisClient.Exists(ctx, cacheKeyB).Result()
-	assert.Equal(t, int64(1), exists)
-	exists, _ = redisClient.Exists(ctx, cacheKeyC).Result()
-	assert.Equal(t, int64(1), exists)
-
-	// 清除 C 的缓存（应该递归清除 B 和 A 的缓存）
-	err = store.ClearSubordinatesCacheForParents(ctx, accountC.ID)
-	require.NoError(t, err)
-
-	// 验证所有上级缓存已删除
-	exists, _ = redisClient.Exists(ctx, cacheKeyA).Result()
-	assert.Equal(t, int64(0), exists, "A 的缓存应该被清除")
-	exists, _ = redisClient.Exists(ctx, cacheKeyB).Result()
-	assert.Equal(t, int64(0), exists, "B 的缓存应该被清除")
-	exists, _ = redisClient.Exists(ctx, cacheKeyC).Result()
-	assert.Equal(t, int64(0), exists, "C 的缓存应该被清除")
-}
-
-// TestCacheInvalidationOnCreate 测试创建账号时清除父账号缓存
-func TestCacheInvalidationOnCreate(t *testing.T) {
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建父账号
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	// 查询 A 的下级（只有自己），写入缓存
-	ids1, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids1, 1)
-
-	// 验证缓存存在
-	cacheKey := constants.RedisAccountSubordinatesKey(accountA.ID)
-	exists, _ := redisClient.Exists(ctx, cacheKey).Result()
-	assert.Equal(t, int64(1), exists)
-
-	// 创建子账号 B（应该清除 A 的缓存）
-	accountB := &model.Account{
-		Username: "user_b",
-		Phone:    "13800000002",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountA.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountB).Error)
-
-	// 注意：缓存清除逻辑在 Service 层，这里模拟清除
-	err = store.ClearSubordinatesCacheForParents(ctx, accountA.ID)
-	require.NoError(t, err)
-
-	// 验证缓存已清除
-	exists, _ = redisClient.Exists(ctx, cacheKey).Result()
-	assert.Equal(t, int64(0), exists, "创建子账号后，父账号的缓存应该被清除")
-
-	// 再次查询（缓存未命中，重新查询数据库，应该包含 B）
-	ids2, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids2, 2, "应该包含 A 和 B")
-	assert.Contains(t, ids2, accountA.ID)
-	assert.Contains(t, ids2, accountB.ID)
-}

tests/unit/subordinate_query_test.go

@@ -1,252 +0,0 @@
-package unit
-
-import (
-	"context"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
-	"github.com/break/junhong_cmp_fiber/internal/model"
-	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
-	"github.com/break/junhong_cmp_fiber/pkg/constants"
-	"github.com/break/junhong_cmp_fiber/tests/testutils"
-)
-
-// TestGetSubordinateIDs_SingleLevel 测试单层下级查询
-func TestGetSubordinateIDs_SingleLevel(t *testing.T) {
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建层级结构: A -> B, C
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	accountB := &model.Account{
-		Username: "user_b",
-		Phone:    "13800000002",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountA.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountB).Error)
-
-	accountC := &model.Account{
-		Username: "user_c",
-		Phone:    "13800000003",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountA.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountC).Error)
-
-	// 查询 A 的所有下级（应该包含 A, B, C）
-	ids, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids, 3)
-	assert.Contains(t, ids, accountA.ID)
-	assert.Contains(t, ids, accountB.ID)
-	assert.Contains(t, ids, accountC.ID)
-}
-
-// TestGetSubordinateIDs_MultiLevel 测试多层递归查询
-func TestGetSubordinateIDs_MultiLevel(t *testing.T) {
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建层级结构: A -> B -> C -> D -> E (5层)
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	accountB := &model.Account{
-		Username: "user_b",
-		Phone:    "13800000002",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountA.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountB).Error)
-
-	accountC := &model.Account{
-		Username: "user_c",
-		Phone:    "13800000003",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountB.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountC).Error)
-
-	accountD := &model.Account{
-		Username: "user_d",
-		Phone:    "13800000004",
-		Password: "hashed_password",
-		UserType: constants.UserTypeEnterprise,
-		ParentID: &accountC.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountD).Error)
-
-	accountE := &model.Account{
-		Username: "user_e",
-		Phone:    "13800000005",
-		Password: "hashed_password",
-		UserType: constants.UserTypeEnterprise,
-		ParentID: &accountD.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountE).Error)
-
-	// 查询 A 的所有下级（应该包含所有 5 个账号）
-	ids, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids, 5)
-
-	// 查询 B 的所有下级（应该包含 B, C, D, E）
-	ids, err = store.GetSubordinateIDs(ctx, accountB.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids, 4)
-
-	// 查询 E 的所有下级（只有自己）
-	ids, err = store.GetSubordinateIDs(ctx, accountE.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids, 1)
-	assert.Equal(t, accountE.ID, ids[0])
-}
-
-// TestGetSubordinateIDs_WithSoftDeleted 测试包含软删除账号的递归查询
-func TestGetSubordinateIDs_WithSoftDeleted(t *testing.T) {
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建层级结构: A -> B -> C
-	accountA := &model.Account{
-		Username: "user_a",
-		Phone:    "13800000001",
-		Password: "hashed_password",
-		UserType: constants.UserTypePlatform,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	accountB := &model.Account{
-		Username: "user_b",
-		Phone:    "13800000002",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountA.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountB).Error)
-
-	accountC := &model.Account{
-		Username: "user_c",
-		Phone:    "13800000003",
-		Password: "hashed_password",
-		UserType: constants.UserTypeAgent,
-		ParentID: &accountB.ID,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountC).Error)
-
-	// 软删除 B
-	require.NoError(t, db.Delete(accountB).Error)
-
-	// 查询 A 的所有下级（应该仍然包含 B 和 C，因为递归查询包含软删除账号）
-	ids, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	require.NoError(t, err)
-	assert.Len(t, ids, 3)
-	assert.Contains(t, ids, accountB.ID)
-	assert.Contains(t, ids, accountC.ID)
-}
-
-// TestGetSubordinateIDs_Performance 测试递归查询性能
-func TestGetSubordinateIDs_Performance(t *testing.T) {
-	if testing.Short() {
-		t.Skip("跳过性能测试")
-	}
-
-	db, redisClient := testutils.SetupTestDB(t)
-	defer testutils.TeardownTestDB(t, db, redisClient)
-
-	store := postgres.NewAccountStore(db, redisClient)
-	ctx := context.Background()
-
-	// 创建 5 层层级，每层 3 个分支（共 121 个账号）
-	// 层级 1: 1 个账号
-	accountA := &model.Account{
-		Username: "user_root",
-		Phone:    "13800000000",
-		Password: "hashed_password",
-		UserType: constants.UserTypeSuperAdmin,
-		Status:   constants.StatusEnabled,
-	}
-	require.NoError(t, db.Create(accountA).Error)
-
-	// 层级 2: 3 个账号
-	var level2IDs []uint
-	for i := 1; i <= 3; i++ {
-		acc := &model.Account{
-			Username: testutils.GenerateUsername("level2", i),
-			Phone:    testutils.GeneratePhone("138", i),
-			Password: "hashed_password",
-			UserType: constants.UserTypePlatform,
-			ParentID: &accountA.ID,
-			Status:   constants.StatusEnabled,
-		}
-		require.NoError(t, db.Create(acc).Error)
-		level2IDs = append(level2IDs, acc.ID)
-	}
-
-	// 层级 3: 9 个账号
-	var level3IDs []uint
-	for _, parentID := range level2IDs {
-		for i := 1; i <= 3; i++ {
-			acc := &model.Account{
-				Username: testutils.GenerateUsername("level3", int(parentID)*10+i),
-				Phone:    testutils.GeneratePhone("139", int(parentID)*10+i),
-				Password: "hashed_password",
-				UserType: constants.UserTypeAgent,
-				ParentID: &parentID,
-				Status:   constants.StatusEnabled,
-			}
-			require.NoError(t, db.Create(acc).Error)
-			level3IDs = append(level3IDs, acc.ID)
-		}
-	}
-
-	// 测试查询性能（应该 < 50ms）
-	start := testutils.Now()
-	ids, err := store.GetSubordinateIDs(ctx, accountA.ID)
-	duration := testutils.Since(start)
-
-	require.NoError(t, err)
-	assert.GreaterOrEqual(t, len(ids), 13) // 至少包含 1 + 3 + 9 个账号
-
-	// 验证性能要求
-	assert.Less(t, duration.Milliseconds(), int64(50), "递归查询应在 50ms 内完成")
-}