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

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'。

Platform string `gorm:"type:varchar(20);default:'all'"` // all-全部 web-Web后台 h5-H5端

理由:

• 折中方案：不强制隔离，但提供灵活性
• 前端可以根据 platform 过滤菜单
• 后端校验时可以根据请求来源和权限的 platform 进行验证

使用场景:

• all: 通用权限，如"查看订单"、"创建客户"
• web: 仅 Web 后台使用，如"导出报表"、"批量操作"
• h5: 仅 H5 使用，如"扫码登录"、"微信支付"

Decision 3: 账号-角色数量限制

决策: 在 Service 层实现角色数量限制，而非数据库约束。

实现逻辑:

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（角色）- 修改

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（权限）- 修改

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