TanWenyan/leaudit-platform-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
leaudit-platform-frontend/auth_doc/RBAC_API_GUIDE_V3.4.md
T
LiangShiyong 3d1dbb3f97 all in
2025-12-05 00:09:32 +08:00

31 KiB
Raw Permalink Blame History

RBAC 权限管理 API 接口文档 v3.4

最后更新: 2025-01-29 API 版本: v3 Base URL: /api/v3/rbac

📋 目录

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：

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 否 角色名称过滤（模糊搜索） -

请求示例:

GET /api/v3/rbac/roles?page=1&page_size=20&role_name=管理员

响应示例:

{
  "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

请求示例:

GET /api/v3/rbac/roles/1

响应示例:

{
  "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:

{
  "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对象

响应示例:

{
  "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 (所有字段可选):

{
  "role_name": "更新后的角色名",
  "description": "更新后的描述",
  "data_scope": "ALL",
  "metadata": {
    "updated": true
  }
}

响应示例:

{
  "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

请求示例:

DELETE /api/v3/rbac/roles/10

响应示例:

{
  "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）

请求示例:

GET /api/v3/rbac/permissions?module=system

响应示例 (树形结构):

{
  "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

请求示例:

GET /api/v3/rbac/permissions/2

响应示例:

{
  "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:

{
  "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对象

响应示例:

{
  "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 (所有字段可选):

{
  "display_name": "查看所有合同",
  "description": "更新后的描述",
  "permission_type": "API",
  "parent_id": 1,
  "sort_order": 20,
  "metadata": {
    "updated": true
  }
}

响应示例:

{
  "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

请求示例:

DELETE /api/v3/rbac/permissions/50

响应示例:

{
  "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

请求示例:

GET /api/v3/rbac/role-permissions?role_id=1

响应示例:

{
  "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:

{
  "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

响应示例:

{
  "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:

{
  "grant_type": "DENY",
  "data_scope": "SELF"
}

字段说明:

字段 类型 必填 说明
grant_type string 否 授权类型（GRANT/DENY）
data_scope string 否 数据范围（ALL/DEPT/SELF）

请求示例:

PUT /api/v3/rbac/role-permissions?role_id=5&permission_id=10
Content-Type: application/json

{
  "grant_type": "DENY",
  "data_scope": "SELF"
}

响应示例:

{
  "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

请求示例:

DELETE /api/v3/rbac/role-permissions?role_id=5&permission_id=10

响应示例:

{
  "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 否 用户名模糊搜索 -

请求示例:

GET /api/v3/rbac/roles/1/users?page=1&page_size=20&area=梅州

响应示例:

{
  "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

请求示例:

GET /api/v3/rbac/users/10/roles

响应示例:

{
  "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:

{
  "role_ids": [2, 5, 8]
}

字段说明:

字段 类型 必填 说明
role_ids array 是 角色ID列表（至少1个）

请求示例:

POST /api/v3/rbac/users/10/roles
Content-Type: application/json

{
  "role_ids": [2, 5]
}

响应示例:

{
  "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. 防止自我提权 - 任何用户不能给自己分配角色

错误示例:

// 市级管理员尝试分配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

请求示例:

DELETE /api/v3/rbac/users/10/roles/5

响应示例:

{
  "code": 200,
  "message": "角色移除成功",
  "data": {
    "user_id": 10,
    "role_id": 5,
    "removed": true
  }
}

注意事项:

  • 如果用户没有该角色，会返回 404 错误

7. 数据模型 Schema

7.1 角色相关 Schema

RoleListItem（角色列表项）

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（角色详情）

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（权限列表项，树形）

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（角色权限项）

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（角色用户项）

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（用户角色项）

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 业务错误码

统一响应格式：

{
  "code": 400,
  "message": "错误描述",
  "detail": "详细错误信息（可选）"
}

常见错误示例：

// 参数验证错误
{
  "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 权限检查流程

// 前端示例：检查用户是否有 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 批量分配权限示例

// 完全替换角色权限
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 地区数据隔离示例

// 获取角色用户时，自动按地区过滤
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 错误处理示例

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

Reference in New Issue View Git Blame Copy Permalink