# 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