csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

实现角色权限体系重构

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

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>
This commit is contained in:
huang
2026-01-10 09:51:52 +08:00
parent a36e4a79c0
commit 1b9080e3ab
31 changed files with 1767 additions and 607 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
openspec/changes/archive/2026-01-10-add-role-permission-system/design.md Normal file
View File

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

51
openspec/changes/archive/2026-01-10-add-role-permission-system/proposal.md Normal file
View File

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

163
openspec/changes/archive/2026-01-10-add-role-permission-system/specs/role-permission/spec.md Normal file
View File

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

136
openspec/changes/archive/2026-01-10-add-role-permission-system/tasks.md Normal file
View File

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

145
openspec/specs/role-permission/spec.md Normal file
View File

@@ -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 关系构建层级菜单树结构
---