1431 lines
31 KiB
Markdown
1431 lines
31 KiB
Markdown
# RBAC 权限管理 API 接口文档 v3.4
|
||
|
||
**最后更新**: 2025-01-29
|
||
**API 版本**: v3
|
||
**Base URL**: `/api/v3/rbac`
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
- [1. 概述](#1-概述)
|
||
- [2. 认证说明](#2-认证说明)
|
||
- [3. 角色管理 API (5个)](#3-角色管理-api)
|
||
- [4. 权限管理 API (5个)](#4-权限管理-api)
|
||
- [5. 角色权限关联 API (4个)](#5-角色权限关联-api)
|
||
- [6. 用户角色管理 API (4个)](#6-用户角色管理-api)
|
||
- [7. 数据模型 Schema](#7-数据模型-schema)
|
||
- [8. 错误码说明](#8-错误码说明)
|
||
- [9. 最佳实践](#9-最佳实践)
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
RBAC（基于角色的访问控制）系统提供完整的角色和权限管理功能。
|
||
|
||
### 1.1 核心概念
|
||
|
||
- **角色（Role）**: 用户权限的集合，如 `provincial_admin`、`admin`、`user`
|
||
- **权限（Permission）**: 具体的操作权限，如 `system:rbac:manage`
|
||
- **角色权限关联**: 角色拥有哪些权限
|
||
- **用户角色关联**: 用户拥有哪些角色
|
||
|
||
### 1.2 权限检查机制
|
||
|
||
所有 RBAC 管理接口（除查询外）都需要 `system:rbac:manage` 权限。
|
||
|
||
**权限验证流程**:
|
||
1. **实时数据库查询** - 每次请求都从数据库实时查询用户权限，**不使用缓存**
|
||
2. **JWT Token验证** - 验证Token有效性和用户身份
|
||
3. **权限匹配** - 检查用户是否拥有所需权限（支持通配符匹配）
|
||
4. **DENY优先** - DENY权限优先级高于GRANT权限
|
||
|
||
**权限即时生效** ⭐:
|
||
- ✅ 授予权限后**立即生效**（无需等待）
|
||
- ✅ 取消权限后**立即失效**（用户立即失去相应操作权限）
|
||
- ❌ **不存在**权限缓存导致的延迟问题
|
||
|
||
**重要说明**:
|
||
如果取消用户的RBAC管理权限后，该用户的下一次操作请求会立即被拒绝（返回403错误）。如果出现"取消权限后仍能操作"的现象，可能的原因：
|
||
1. 前端未刷新页面（前端可能缓存了权限状态）
|
||
2. 使用了旧的API响应（浏览器缓存）
|
||
3. 多个浏览器Tab页面未同步
|
||
|
||
**建议**:
|
||
- 修改权限后，建议用户刷新页面或重新登录
|
||
- 前端应在每次关键操作前检查权限（调用API时后端会验证）
|
||
|
||
### 1.3 地区数据隔离（v3.3+）
|
||
|
||
| 角色类型 | 数据范围 | 说明 |
|
||
|---------|---------|------|
|
||
| **省级管理员** (`provincial_admin`) | 全部地区 | 可查看和管理所有地区数据 |
|
||
| **市级管理员** (`admin`) | 本地区 | 只能查看和管理本地区（area）数据 |
|
||
| **普通用户** | 本地区 | 只能查看本地区数据 |
|
||
|
||
**地区过滤规则**:
|
||
- 后端根据用户的 `area` 和 `user_role` 字段自动过滤数据
|
||
- 市级管理员尝试访问其他地区数据时返回 403 错误
|
||
|
||
### 1.4 权限升级限制（v3.4+）⭐
|
||
|
||
为保证权限安全，系统实施严格的角色升级控制：
|
||
|
||
| 当前角色 | 可分配角色范围 | 不可分配角色 | 说明 |
|
||
|---------|--------------|-------------|------|
|
||
| **省级管理员** | 全部角色 | 无限制 | 拥有最高权限 |
|
||
| **市级管理员** | 普通用户角色 | `admin`, `provincial_admin` | 不能提升用户为管理员 |
|
||
| **普通用户** | 无 | 全部 | 无角色管理权限 |
|
||
|
||
**安全规则**:
|
||
1. ✅ 省级管理员可以分配任何角色（包括其他省级管理员、市级管理员）
|
||
2. ❌ 市级管理员**不能**将普通用户提升为市级管理员或省级管理员
|
||
3. ❌ 市级管理员只能管理**本地区**普通用户的角色
|
||
4. ❌ 任何用户**不能**给自己分配角色（防止自我提权）
|
||
5. ❌ 取消用户的RBAC管理权限后，该用户**立即失去**所有RBAC操作权限
|
||
|
||
**典型场景**:
|
||
```
|
||
场景1：市级管理员为本地区用户分配普通角色 ✅
|
||
- 当前用户：admin (梅州)
|
||
- 目标用户：普通用户 (梅州)
|
||
- 分配角色：auditor（审计员）
|
||
- 结果：成功
|
||
|
||
场景2：市级管理员尝试提升用户为管理员 ❌
|
||
- 当前用户：admin (梅州)
|
||
- 目标用户：普通用户 (梅州)
|
||
- 分配角色：admin（市管理员）
|
||
- 结果：失败 - "只有省级管理员可以分配市管理员角色"
|
||
|
||
场景3：市级管理员尝试操作其他地区用户 ❌
|
||
- 当前用户：admin (梅州)
|
||
- 目标用户：普通用户 (云浮)
|
||
- 分配角色：auditor（审计员）
|
||
- 结果：失败 - "无权限给其他地区用户分配角色"
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 认证说明
|
||
|
||
### 2.1 请求头
|
||
|
||
所有接口都需要携带 JWT Token：
|
||
|
||
```http
|
||
Authorization: Bearer YOUR_JWT_TOKEN
|
||
```
|
||
|
||
### 2.2 Token 获取
|
||
|
||
通过登录接口获取：`POST /api/v1/auth/login`
|
||
|
||
---
|
||
|
||
## 3. 角色管理 API
|
||
|
||
### 3.1 获取角色列表
|
||
|
||
**接口**: `GET /api/v3/rbac/roles`
|
||
|
||
**权限要求**: 仅需登录
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 | 默认值 |
|
||
|------|------|------|------|--------|
|
||
| page | integer | 否 | 页码 | 1 |
|
||
| page_size | integer | 否 | 每页数量 | 20 |
|
||
| role_key | string | 否 | 角色标识过滤（模糊搜索） | - |
|
||
| role_name | string | 否 | 角色名称过滤（模糊搜索） | - |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
GET /api/v3/rbac/roles?page=1&page_size=20&role_name=管理员
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 5,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"role_key": "provincial_admin",
|
||
"role_name": "省级管理员",
|
||
"description": "拥有系统所有权限",
|
||
"data_scope": "ALL",
|
||
"is_system": true,
|
||
"user_count": 3,
|
||
"permission_count": 25,
|
||
"created_at": "2025-01-15T10:00:00",
|
||
"updated_at": "2025-01-15T10:00:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"role_key": "admin",
|
||
"role_name": "市级管理员",
|
||
"description": "市级管理权限",
|
||
"data_scope": "DEPT",
|
||
"is_system": true,
|
||
"user_count": 8,
|
||
"permission_count": 15,
|
||
"created_at": "2025-01-15T10:00:00",
|
||
"updated_at": "2025-01-15T10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 获取角色详情
|
||
|
||
**接口**: `GET /api/v3/rbac/roles/{role_id}`
|
||
|
||
**权限要求**: 仅需登录
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| role_id | integer | 角色ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
GET /api/v3/rbac/roles/1
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"role_key": "provincial_admin",
|
||
"role_name": "省级管理员",
|
||
"description": "拥有系统所有权限",
|
||
"data_scope": "ALL",
|
||
"is_system": true,
|
||
"permissions": [
|
||
{
|
||
"id": 1,
|
||
"permission_id": 10,
|
||
"permission_key": "system:rbac:manage",
|
||
"display_name": "RBAC管理权限",
|
||
"grant_type": "GRANT",
|
||
"data_scope": "ALL"
|
||
}
|
||
],
|
||
"metadata": {},
|
||
"created_at": "2025-01-15T10:00:00",
|
||
"updated_at": "2025-01-15T10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 创建角色
|
||
|
||
**接口**: `POST /api/v3/rbac/roles`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Request Body**:
|
||
|
||
```json
|
||
{
|
||
"role_key": "custom_admin",
|
||
"role_name": "自定义管理员",
|
||
"description": "自定义的管理员角色",
|
||
"data_scope": "DEPT",
|
||
"metadata": {
|
||
"custom_field": "value"
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 | 限制 |
|
||
|------|------|------|------|------|
|
||
| role_key | string | 是 | 角色标识（唯一） | 只能包含小写字母、数字、下划线，必须以字母开头 |
|
||
| role_name | string | 是 | 角色名称 | 最大200字符 |
|
||
| description | string | 否 | 角色描述 | - |
|
||
| data_scope | string | 否 | 数据范围 | ALL/DEPT/SELF，默认SELF |
|
||
| metadata | object | 否 | 元数据 | JSON对象 |
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "角色创建成功",
|
||
"data": {
|
||
"id": 10,
|
||
"role_key": "custom_admin",
|
||
"role_name": "自定义管理员",
|
||
"description": "自定义的管理员角色",
|
||
"data_scope": "DEPT",
|
||
"is_system": false,
|
||
"created_at": "2025-01-29T14:30:00",
|
||
"updated_at": "2025-01-29T14:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 更新角色
|
||
|
||
**接口**: `PUT /api/v3/rbac/roles/{role_id}`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| role_id | integer | 角色ID |
|
||
|
||
**Request Body** (所有字段可选):
|
||
|
||
```json
|
||
{
|
||
"role_name": "更新后的角色名",
|
||
"description": "更新后的描述",
|
||
"data_scope": "ALL",
|
||
"metadata": {
|
||
"updated": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "角色更新成功",
|
||
"data": {
|
||
"id": 10,
|
||
"role_key": "custom_admin",
|
||
"role_name": "更新后的角色名",
|
||
"description": "更新后的描述",
|
||
"data_scope": "ALL",
|
||
"is_system": false,
|
||
"updated_at": "2025-01-29T14:35:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 系统角色（is_system=true）不可修改
|
||
- role_key 不可修改（唯一标识）
|
||
|
||
---
|
||
|
||
### 3.5 删除角色
|
||
|
||
**接口**: `DELETE /api/v3/rbac/roles/{role_id}`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| role_id | integer | 角色ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
DELETE /api/v3/rbac/roles/10
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "角色删除成功",
|
||
"data": {
|
||
"role_id": 10,
|
||
"deleted": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 系统角色（is_system=true）不可删除
|
||
- 删除角色会自动删除相关的角色权限关联和用户角色关联
|
||
|
||
---
|
||
|
||
## 4. 权限管理 API
|
||
|
||
### 4.1 获取权限列表（树形）
|
||
|
||
**接口**: `GET /api/v3/rbac/permissions`
|
||
|
||
**权限要求**: 仅需登录
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| module | string | 否 | 按模块过滤 |
|
||
| resource | string | 否 | 按资源过滤 |
|
||
| permission_type | string | 否 | 按类型过滤（API/MENU/BUTTON） |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
GET /api/v3/rbac/permissions?module=system
|
||
```
|
||
|
||
**响应示例** (树形结构):
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"permission_key": "system:*:*",
|
||
"display_name": "系统全部权限",
|
||
"description": "系统所有权限",
|
||
"module": "system",
|
||
"resource": "*",
|
||
"action": "*",
|
||
"permission_type": "API",
|
||
"is_system": true,
|
||
"parent_id": null,
|
||
"sort_order": 0,
|
||
"children": [
|
||
{
|
||
"id": 2,
|
||
"permission_key": "system:rbac:manage",
|
||
"display_name": "RBAC管理",
|
||
"description": "角色权限管理",
|
||
"module": "system",
|
||
"resource": "rbac",
|
||
"action": "manage",
|
||
"permission_type": "API",
|
||
"is_system": true,
|
||
"parent_id": 1,
|
||
"sort_order": 1,
|
||
"children": []
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 获取权限详情
|
||
|
||
**接口**: `GET /api/v3/rbac/permissions/{permission_id}`
|
||
|
||
**权限要求**: 仅需登录
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| permission_id | integer | 权限ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
GET /api/v3/rbac/permissions/2
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 2,
|
||
"permission_key": "system:rbac:manage",
|
||
"display_name": "RBAC管理",
|
||
"description": "角色权限管理",
|
||
"module": "system",
|
||
"resource": "rbac",
|
||
"action": "manage",
|
||
"permission_type": "API",
|
||
"is_system": true,
|
||
"parent_id": 1,
|
||
"sort_order": 1,
|
||
"metadata": {},
|
||
"created_at": "2025-01-15T10:00:00",
|
||
"updated_at": "2025-01-15T10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 创建权限
|
||
|
||
**接口**: `POST /api/v3/rbac/permissions`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Request Body**:
|
||
|
||
```json
|
||
{
|
||
"permission_key": "document:contract:view",
|
||
"display_name": "查看合同",
|
||
"description": "查看合同文档权限",
|
||
"module": "document",
|
||
"resource": "contract",
|
||
"action": "view",
|
||
"permission_type": "API",
|
||
"parent_id": null,
|
||
"sort_order": 10,
|
||
"metadata": {}
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 | 格式/限制 |
|
||
|------|------|------|------|-----------|
|
||
| permission_key | string | 是 | 权限键 | 格式: `module:resource:action` |
|
||
| display_name | string | 是 | 显示名称 | 最大200字符 |
|
||
| description | string | 否 | 权限描述 | - |
|
||
| module | string | 是 | 模块 | 最大50字符 |
|
||
| resource | string | 是 | 资源 | 最大50字符 |
|
||
| action | string | 是 | 操作 | 最大50字符 |
|
||
| permission_type | string | 否 | 权限类型 | API/MENU/BUTTON，默认API |
|
||
| parent_id | integer | 否 | 父级权限ID | - |
|
||
| sort_order | integer | 否 | 排序 | 默认0 |
|
||
| metadata | object | 否 | 元数据 | JSON对象 |
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "权限创建成功",
|
||
"data": {
|
||
"id": 50,
|
||
"permission_key": "document:contract:view",
|
||
"display_name": "查看合同",
|
||
"created_at": "2025-01-29T14:40:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 更新权限
|
||
|
||
**接口**: `PUT /api/v3/rbac/permissions/{permission_id}`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| permission_id | integer | 权限ID |
|
||
|
||
**Request Body** (所有字段可选):
|
||
|
||
```json
|
||
{
|
||
"display_name": "查看所有合同",
|
||
"description": "更新后的描述",
|
||
"permission_type": "API",
|
||
"parent_id": 1,
|
||
"sort_order": 20,
|
||
"metadata": {
|
||
"updated": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "权限更新成功",
|
||
"data": {
|
||
"id": 50,
|
||
"permission_key": "document:contract:view",
|
||
"display_name": "查看所有合同",
|
||
"updated_at": "2025-01-29T14:45:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 系统权限（is_system=true）不可修改
|
||
- permission_key、module、resource、action 不可修改
|
||
|
||
---
|
||
|
||
### 4.5 删除权限
|
||
|
||
**接口**: `DELETE /api/v3/rbac/permissions/{permission_id}`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| permission_id | integer | 权限ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
DELETE /api/v3/rbac/permissions/50
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "权限删除成功",
|
||
"data": {
|
||
"permission_id": 50,
|
||
"deleted": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 系统权限（is_system=true）不可删除
|
||
- 删除权限会级联删除所有子权限和相关的角色权限关联
|
||
|
||
---
|
||
|
||
## 5. 角色权限关联 API
|
||
|
||
### 5.1 获取角色的所有权限
|
||
|
||
**接口**: `GET /api/v3/rbac/role-permissions`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| role_id | integer | 是 | 角色ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
GET /api/v3/rbac/role-permissions?role_id=1
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"permission_id": 10,
|
||
"permission_key": "system:rbac:manage",
|
||
"display_name": "RBAC管理",
|
||
"grant_type": "GRANT",
|
||
"data_scope": "ALL"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"permission_id": 11,
|
||
"permission_key": "document:*:view",
|
||
"display_name": "查看文档",
|
||
"grant_type": "GRANT",
|
||
"data_scope": "DEPT"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 批量分配角色权限
|
||
|
||
**接口**: `POST /api/v3/rbac/role-permissions`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Request Body**:
|
||
|
||
```json
|
||
{
|
||
"role_id": 5,
|
||
"permissions": [
|
||
{
|
||
"permission_id": 10,
|
||
"grant_type": "GRANT",
|
||
"data_scope": "ALL"
|
||
},
|
||
{
|
||
"permission_id": 11,
|
||
"grant_type": "GRANT",
|
||
"data_scope": "DEPT"
|
||
},
|
||
{
|
||
"permission_id": 12,
|
||
"grant_type": "DENY",
|
||
"data_scope": null
|
||
}
|
||
],
|
||
"replace": true
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| role_id | integer | 是 | 角色ID |
|
||
| permissions | array | 是 | 权限列表 |
|
||
| permissions[].permission_id | integer | 是 | 权限ID |
|
||
| permissions[].grant_type | string | 否 | 授权类型（GRANT/DENY），默认GRANT |
|
||
| permissions[].data_scope | string | 否 | 数据范围（ALL/DEPT/SELF） |
|
||
| replace | boolean | 否 | 是否替换全部权限（true=替换，false=追加），默认false |
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功替换权限",
|
||
"data": {
|
||
"role_id": 5,
|
||
"assigned_count": 3,
|
||
"deleted_count": 5,
|
||
"mode": "replace"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- `replace=true`: 删除现有所有权限，插入新权限
|
||
- `replace=false`: 保留现有权限，追加新权限（跳过重复）
|
||
- `provincial_admin` 角色的核心权限不可移除（即使 replace=true）
|
||
|
||
---
|
||
|
||
### 5.3 更新单个角色权限
|
||
|
||
**接口**: `PUT /api/v3/rbac/role-permissions`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| role_id | integer | 是 | 角色ID |
|
||
| permission_id | integer | 是 | 权限ID |
|
||
|
||
**Request Body**:
|
||
|
||
```json
|
||
{
|
||
"grant_type": "DENY",
|
||
"data_scope": "SELF"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| grant_type | string | 否 | 授权类型（GRANT/DENY） |
|
||
| data_scope | string | 否 | 数据范围（ALL/DEPT/SELF） |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
PUT /api/v3/rbac/role-permissions?role_id=5&permission_id=10
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"grant_type": "DENY",
|
||
"data_scope": "SELF"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "权限更新成功",
|
||
"data": {
|
||
"id": 15,
|
||
"role_id": 5,
|
||
"permission_id": 10,
|
||
"grant_type": "DENY",
|
||
"data_scope": "SELF",
|
||
"updated_at": "2025-01-29T15:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.4 移除角色权限
|
||
|
||
**接口**: `DELETE /api/v3/rbac/role-permissions`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| role_id | integer | 是 | 角色ID |
|
||
| permission_id | integer | 是 | 权限ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
DELETE /api/v3/rbac/role-permissions?role_id=5&permission_id=10
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "权限移除成功",
|
||
"data": {
|
||
"role_id": 5,
|
||
"permission_id": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- `provincial_admin` 角色的核心权限不可移除（system:rbac:manage、system:*:*）
|
||
|
||
---
|
||
|
||
## 6. 用户角色管理 API
|
||
|
||
### 6.1 获取角色的所有用户
|
||
|
||
**接口**: `GET /api/v3/rbac/roles/{role_id}/users`
|
||
|
||
**权限要求**: 仅需登录（地区数据隔离）
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| role_id | integer | 角色ID |
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 | 默认值 |
|
||
|------|------|------|------|--------|
|
||
| page | integer | 否 | 页码 | 1 |
|
||
| page_size | integer | 否 | 每页数量 | 20 |
|
||
| area | string | 否 | 按地区过滤 | - |
|
||
| username | string | 否 | 用户名模糊搜索 | - |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
GET /api/v3/rbac/roles/1/users?page=1&page_size=20&area=梅州
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 8,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"items": [
|
||
{
|
||
"user_id": 10,
|
||
"username": "zhangsan",
|
||
"nick_name": "张三",
|
||
"area": "梅州",
|
||
"ou_name": "技术部",
|
||
"phone_number": "13800138000",
|
||
"email": "zhangsan@example.com",
|
||
"assigned_at": "2025-01-20T10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**地区过滤规则**:
|
||
- 省级管理员：可查看所有地区用户
|
||
- 市级管理员：只能查看本地区用户
|
||
- 普通用户：只能查看本地区用户
|
||
|
||
---
|
||
|
||
### 6.2 获取用户的所有角色
|
||
|
||
**接口**: `GET /api/v3/rbac/users/{user_id}/roles`
|
||
|
||
**权限要求**: 仅需登录（地区数据隔离）
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| user_id | integer | 用户ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
GET /api/v3/rbac/users/10/roles
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"user_id": 10,
|
||
"username": "zhangsan",
|
||
"roles": [
|
||
{
|
||
"role_id": 2,
|
||
"role_key": "admin",
|
||
"role_name": "市级管理员",
|
||
"data_scope": "DEPT",
|
||
"assigned_at": "2025-01-20T10:00:00"
|
||
},
|
||
{
|
||
"role_id": 5,
|
||
"role_key": "auditor",
|
||
"role_name": "审计员",
|
||
"data_scope": "SELF",
|
||
"assigned_at": "2025-01-22T11:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.3 为用户分配角色
|
||
|
||
**接口**: `POST /api/v3/rbac/users/{user_id}/roles`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| user_id | integer | 用户ID |
|
||
|
||
**Request Body**:
|
||
|
||
```json
|
||
{
|
||
"role_ids": [2, 5, 8]
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| role_ids | array | 是 | 角色ID列表（至少1个） |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
POST /api/v3/rbac/users/10/roles
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"role_ids": [2, 5]
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "角色分配成功",
|
||
"data": {
|
||
"user_id": 10,
|
||
"assigned_count": 2,
|
||
"skipped_count": 0,
|
||
"roles": [
|
||
{
|
||
"role_id": 2,
|
||
"role_key": "admin",
|
||
"role_name": "市级管理员"
|
||
},
|
||
{
|
||
"role_id": 5,
|
||
"role_key": "auditor",
|
||
"role_name": "审计员"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 会跳过用户已有的角色（不会重复分配）
|
||
- 所有 role_id 必须存在且有效
|
||
|
||
**权限升级限制** ⭐ v3.4:
|
||
1. **省级管理员** - 可以分配任何角色（包括其他省级/市级管理员）
|
||
2. **市级管理员** - 只能分配普通用户角色，**不能**分配 `admin` 或 `provincial_admin` 角色
|
||
3. **地区限制** - 市级管理员只能给**本地区**用户分配角色
|
||
4. **防止自我提权** - 任何用户不能给自己分配角色
|
||
|
||
**错误示例**:
|
||
```json
|
||
// 市级管理员尝试分配admin角色
|
||
{
|
||
"code": 403,
|
||
"message": "只有省级管理员可以分配市管理员角色，市管理员只能管理普通用户角色"
|
||
}
|
||
|
||
// 市级管理员尝试操作其他地区用户
|
||
{
|
||
"code": 403,
|
||
"message": "无权限给其他地区用户分配角色: target_area=云浮, your_area=梅州"
|
||
}
|
||
|
||
// 给自己分配角色
|
||
{
|
||
"code": 403,
|
||
"message": "禁止给自己分配角色"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.4 移除用户角色
|
||
|
||
**接口**: `DELETE /api/v3/rbac/users/{user_id}/roles/{role_id}`
|
||
|
||
**权限要求**: `system:rbac:manage`
|
||
|
||
**Path 参数**:
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| user_id | integer | 用户ID |
|
||
| role_id | integer | 角色ID |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
DELETE /api/v3/rbac/users/10/roles/5
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "角色移除成功",
|
||
"data": {
|
||
"user_id": 10,
|
||
"role_id": 5,
|
||
"removed": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 如果用户没有该角色，会返回 404 错误
|
||
|
||
---
|
||
|
||
## 7. 数据模型 Schema
|
||
|
||
### 7.1 角色相关 Schema
|
||
|
||
#### RoleListItem（角色列表项）
|
||
|
||
```typescript
|
||
interface RoleListItem {
|
||
id: number; // 角色ID
|
||
role_key: string; // 角色标识（唯一）
|
||
role_name: string; // 角色名称
|
||
description: string | null; // 角色描述
|
||
data_scope: string; // 数据范围（ALL/DEPT/SELF）
|
||
is_system: boolean; // 是否系统角色
|
||
user_count: number; // 拥有该角色的用户数
|
||
permission_count: number; // 该角色的权限数
|
||
created_at: string; // 创建时间（ISO 8601）
|
||
updated_at: string; // 更新时间（ISO 8601）
|
||
}
|
||
```
|
||
|
||
#### RoleDetail（角色详情）
|
||
|
||
```typescript
|
||
interface RoleDetail {
|
||
id: number;
|
||
role_key: string;
|
||
role_name: string;
|
||
description: string | null;
|
||
data_scope: string;
|
||
is_system: boolean;
|
||
permissions: RolePermissionItem[]; // 角色拥有的权限列表
|
||
metadata: Record<string, any>; // 元数据
|
||
created_at: string;
|
||
updated_at: string;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7.2 权限相关 Schema
|
||
|
||
#### PermissionListItem（权限列表项，树形）
|
||
|
||
```typescript
|
||
interface PermissionListItem {
|
||
id: number; // 权限ID
|
||
permission_key: string; // 权限键（module:resource:action）
|
||
display_name: string; // 显示名称
|
||
description: string | null; // 权限描述
|
||
module: string; // 模块
|
||
resource: string; // 资源
|
||
action: string; // 操作
|
||
permission_type: string; // 权限类型（API/MENU/BUTTON）
|
||
is_system: boolean; // 是否系统权限
|
||
parent_id: number | null; // 父级权限ID
|
||
sort_order: number; // 排序
|
||
children: PermissionListItem[]; // 子权限（树形）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7.3 角色权限关联 Schema
|
||
|
||
#### RolePermissionItem（角色权限项）
|
||
|
||
```typescript
|
||
interface RolePermissionItem {
|
||
id: number; // 关联ID
|
||
permission_id: number; // 权限ID
|
||
permission_key: string; // 权限键
|
||
display_name: string; // 显示名称
|
||
grant_type: string; // 授权类型（GRANT/DENY）
|
||
data_scope: string | null; // 数据范围（ALL/DEPT/SELF）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7.4 用户角色关联 Schema
|
||
|
||
#### RoleUserItem（角色用户项）
|
||
|
||
```typescript
|
||
interface RoleUserItem {
|
||
user_id: number; // 用户ID
|
||
username: string; // 用户名
|
||
nick_name: string; // 昵称
|
||
area: string | null; // 地区
|
||
ou_name: string | null; // 组织单位名称
|
||
phone_number: string | null; // 手机号
|
||
email: string | null; // 邮箱
|
||
assigned_at: string; // 分配时间（ISO 8601）
|
||
}
|
||
```
|
||
|
||
#### UserRoleItem（用户角色项）
|
||
|
||
```typescript
|
||
interface UserRoleItem {
|
||
role_id: number; // 角色ID
|
||
role_key: string; // 角色标识
|
||
role_name: string; // 角色名称
|
||
data_scope: string; // 数据范围
|
||
assigned_at: string; // 分配时间（ISO 8601）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 错误码说明
|
||
|
||
### 8.1 HTTP 状态码
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证（Token无效或过期） |
|
||
| 403 | 权限不足 |
|
||
| 404 | 资源不存在 |
|
||
| 409 | 资源冲突（如role_key重复） |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 8.2 业务错误码
|
||
|
||
统一响应格式：
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "错误描述",
|
||
"detail": "详细错误信息（可选）"
|
||
}
|
||
```
|
||
|
||
常见错误示例：
|
||
|
||
```json
|
||
// 参数验证错误
|
||
{
|
||
"code": 400,
|
||
"message": "role_key只能包含小写字母、数字、下划线，且必须以字母开头"
|
||
}
|
||
|
||
// 权限不足
|
||
{
|
||
"code": 403,
|
||
"message": "权限不足: 需要 system:rbac:manage 权限"
|
||
}
|
||
|
||
// 资源不存在
|
||
{
|
||
"code": 404,
|
||
"message": "角色不存在: role_id=999"
|
||
}
|
||
|
||
// 系统角色保护
|
||
{
|
||
"code": 400,
|
||
"message": "系统角色不可删除"
|
||
}
|
||
|
||
// 核心权限保护
|
||
{
|
||
"code": 400,
|
||
"message": "provincial_admin 角色的核心权限不可移除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 最佳实践
|
||
|
||
### 9.1 权限检查流程
|
||
|
||
```javascript
|
||
// 前端示例：检查用户是否有 RBAC 管理权限
|
||
async function checkRbacPermission() {
|
||
try {
|
||
const response = await fetch('/api/v3/rbac/roles', {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
});
|
||
|
||
if (response.status === 403) {
|
||
// 没有权限，隐藏管理功能
|
||
return false;
|
||
}
|
||
|
||
return true;
|
||
} catch (error) {
|
||
console.error('权限检查失败', error);
|
||
return false;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9.2 批量分配权限示例
|
||
|
||
```javascript
|
||
// 完全替换角色权限
|
||
async function replaceRolePermissions(roleId, permissions) {
|
||
const response = await fetch('/api/v3/rbac/role-permissions', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
role_id: roleId,
|
||
permissions: permissions,
|
||
replace: true // 替换模式
|
||
})
|
||
});
|
||
|
||
return response.json();
|
||
}
|
||
|
||
// 追加权限（不删除已有权限）
|
||
async function addRolePermissions(roleId, newPermissions) {
|
||
const response = await fetch('/api/v3/rbac/role-permissions', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
role_id: roleId,
|
||
permissions: newPermissions,
|
||
replace: false // 追加模式
|
||
})
|
||
});
|
||
|
||
return response.json();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9.3 地区数据隔离示例
|
||
|
||
```javascript
|
||
// 获取角色用户时，自动按地区过滤
|
||
async function getRoleUsers(roleId) {
|
||
// 后端会根据当前用户的 area 和 user_role 自动过滤
|
||
// 省级管理员：看到所有地区
|
||
// 市级管理员：只看到本地区
|
||
const response = await fetch(`/api/v3/rbac/roles/${roleId}/users`, {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
});
|
||
|
||
return response.json();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9.4 错误处理示例
|
||
|
||
```javascript
|
||
async function createRole(roleData) {
|
||
try {
|
||
const response = await fetch('/api/v3/rbac/roles', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify(roleData)
|
||
});
|
||
|
||
const result = await response.json();
|
||
|
||
if (!response.ok) {
|
||
// 根据状态码处理不同错误
|
||
switch (response.status) {
|
||
case 400:
|
||
console.error('参数错误:', result.message);
|
||
break;
|
||
case 401:
|
||
console.error('未登录，请重新登录');
|
||
// 跳转到登录页
|
||
break;
|
||
case 403:
|
||
console.error('权限不足:', result.message);
|
||
break;
|
||
case 409:
|
||
console.error('角色标识已存在');
|
||
break;
|
||
case 500:
|
||
console.error('服务器错误:', result.message);
|
||
break;
|
||
}
|
||
throw new Error(result.message);
|
||
}
|
||
|
||
return result.data;
|
||
} catch (error) {
|
||
console.error('创建角色失败:', error);
|
||
throw error;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 完整接口清单
|
||
|
||
### 接口总览（18个）
|
||
|
||
| 分类 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| **角色管理** | GET | `/api/v3/rbac/roles` | 获取角色列表 |
|
||
| | GET | `/api/v3/rbac/roles/{role_id}` | 获取角色详情 |
|
||
| | POST | `/api/v3/rbac/roles` | 创建角色 |
|
||
| | PUT | `/api/v3/rbac/roles/{role_id}` | 更新角色 |
|
||
| | DELETE | `/api/v3/rbac/roles/{role_id}` | 删除角色 |
|
||
| **权限管理** | GET | `/api/v3/rbac/permissions` | 获取权限列表（树形） |
|
||
| | GET | `/api/v3/rbac/permissions/{permission_id}` | 获取权限详情 |
|
||
| | POST | `/api/v3/rbac/permissions` | 创建权限 |
|
||
| | PUT | `/api/v3/rbac/permissions/{permission_id}` | 更新权限 |
|
||
| | DELETE | `/api/v3/rbac/permissions/{permission_id}` | 删除权限 |
|
||
| **角色权限** | GET | `/api/v3/rbac/role-permissions` | 获取角色权限 ⭐ |
|
||
| | POST | `/api/v3/rbac/role-permissions` | 批量分配权限 ⭐ |
|
||
| | PUT | `/api/v3/rbac/role-permissions` | 更新单个权限 ⭐ |
|
||
| | DELETE | `/api/v3/rbac/role-permissions` | 移除权限 ⭐ |
|
||
| **用户角色** | GET | `/api/v3/rbac/roles/{role_id}/users` | 获取角色用户 |
|
||
| | GET | `/api/v3/rbac/users/{user_id}/roles` | 获取用户角色 |
|
||
| | POST | `/api/v3/rbac/users/{user_id}/roles` | 分配用户角色 |
|
||
| | DELETE | `/api/v3/rbac/users/{user_id}/roles/{role_id}` | 移除用户角色 |
|
||
|
||
---
|
||
|
||
## 11. 联系方式
|
||
|
||
如有疑问，请联系后端开发团队。
|
||
|
||
**文档版本**: v3.4
|
||
**最后更新**: 2025-01-29
|
||
**维护者**: Claude AI Assistant
|