# RBAC 权限管理完整指南 v3.3

## 📋 文档说明

本文档是 v3.3 版本的 RBAC（基于角色的访问控制）和用户管理的**完整指南**，包含：
- ✅ 核心业务逻辑的详细说明
- ✅ 所有接口的完整定义和请求参数
- ✅ 实际数据库数据示例
- ✅ 权限控制和地区隔离规则
- ✅ 完整的前后端对接示例

**适用对象**：后端开发、前端开发、产品经理、测试人员

---

## 目录

- [1. 核心业务逻辑](#1-核心业务逻辑)
  - [1.1 设计理念](#11-设计理念)
  - [1.2 数据模型](#12-数据模型)
  - [1.3 权限控制规则](#13-权限控制规则)
- [2. 完整接口文档](#2-完整接口文档)
  - [2.1 角色管理接口](#21-角色管理接口)
  - [2.2 用户管理接口](#22-用户管理接口)
  - [2.3 角色分配接口](#23-角色分配接口)
- [3. 业务场景示例](#3-业务场景示例)
- [4. 数据库实际数据](#4-数据库实际数据)
- [5. 前端对接指南](#5-前端对接指南)

---

## 1. 核心业务逻辑

### 1.1 设计理念

#### 三层设计架构

```
┌─────────────────────────────────────────────────────────┐
│                   1. 角色层（全局统一）                  │
├─────────────────────────────────────────────────────────┤
│  - 角色是全局配置，不区分地区                             │
│  - 所有用户都能看到所有角色                               │
│  - 角色包括：provincial_admin, admin, common             │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                   2. 用户层（地区隔离）                  │
├─────────────────────────────────────────────────────────┤
│  - 用户按地区（area字段）隔离管理                         │
│  - 省级管理员可以操作所有地区用户                          │
│  - 市级管理员只能操作同地区用户                           │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                   3. 权限层（操作控制）                  │
├─────────────────────────────────────────────────────────┤
│  - 查看权限：所有登录用户                                │
│  - 分配权限：省级/市级管理员（受地区限制）                 │
│  - 修改配置：仅省级管理员                                │
└─────────────────────────────────────────────────────────┘
```

#### 核心原则

| 原则 | 说明 | 示例 |
|-----|------|------|
| **角色统一** | 角色是全局的，不分地区 | 梅州和云浮都使用相同的 admin 角色 |
| **用户隔离** | 用户按地区管理，市级管理员只能操作同地区用户 | 梅州管理员只能管理梅州的用户 |
| **权限分层** | 查看开放，修改受限 | 所有人能看角色列表，只有省级能改角色权限 |

---

### 1.2 数据模型

#### 数据库表结构

**1. roles 表（角色表）**

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `id` | integer | 角色ID（主键） | 1, 2, 52 |
| `role_key` | varchar(30) | 角色标识（唯一） | admin, common, provincial_admin |
| `role_name` | varchar(50) | 角色名称 | 市级管理员, 普通员工, 省级管理员 |
| `description` | varchar(200) | 角色描述 | 负责本地区的所有业务管理 |
| `is_system_role` | boolean | 是否系统角色 | true, false |
| `created_at` | timestamp | 创建时间 | 2025-01-15 10:30:00 |

**实际数据**：
```json
[
  {
    "id": 1,
    "role_key": "admin",
    "role_name": "市级管理员",
    "description": "负责本地区的所有业务管理，不包括系统设置和角色权限管理"
  },
  {
    "id": 2,
    "role_key": "common",
    "role_name": "普通员工",
    "description": "仅能操作自己的数据"
  },
  {
    "id": 52,
    "role_key": "provincial_admin",
    "role_name": "省级管理员",
    "description": "拥有全部权限，可以管理所有地区的评查点规则"
  }
]
```

---

**2. sso_users 表（用户表）**

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `id` | integer | 用户ID（主键） | 5, 6, 8 |
| `username` | varchar(255) | 用户名 | admin, 梅州烟草 |
| `nick_name` | varchar(255) | 昵称 | 张三, 李四 |
| `area` | varchar(255) | **地区**（用于权限隔离）⭐ | 梅州, 云浮, 揭阳, 潮州 |
| `ou_name` | varchar(255) | **部门名称**（用于组织划分） | 测试技术部, 研发部 |
| `ou_id` | varchar(255) | 组织单位ID | 0000000A1ML |
| `status` | smallint | 用户状态（0=正常） | 0 |

**实际数据（按地区分组）**：
```json
{
  "梅州": [
    {"id": 5, "username": "admin", "nick_name": "admin", "area": "梅州", "ou_name": "test"},
    {"id": 6, "username": "烟草科技", "nick_name": "烟草科技", "area": "梅州", "ou_name": "测试技术部"},
    {"id": 8, "username": "梅州烟草", "nick_name": "梅州烟草", "area": "梅州", "ou_name": "梅州管理员账号"},
    {"id": 19, "username": "test_admin", "nick_name": "测试管理员", "area": "梅州"},
    {"id": 20, "username": "test_normal", "nick_name": "测试普通用户", "area": "梅州"},
    {"id": 21, "username": "test_other", "nick_name": "测试其他用户", "area": "梅州"}
  ],
  "云浮": [
    {"id": 9, "username": "云浮烟草", "nick_name": "云浮烟草", "area": "云浮"},
    {"id": 22, "username": "OAuth已存在用户测试", "area": "云浮"}
  ],
  "揭阳": [
    {"id": 7, "username": "揭阳惠来烟草", "area": "揭阳"}
  ],
  "潮州": [
    {"id": 12, "username": "潮州烟草", "area": "潮州"}
  ]
}
```

**⚠️ 重要区分**：
- `area`：**地区**（省/市级别），用于**权限隔离**
- `ou_name`：**部门名称**（部门级别），用于**组织划分**

---

**3. user_role 表（用户角色关联表）**

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | integer | 主键 |
| `user_id` | integer | 用户ID（外键 → sso_users.id） |
| `role_id` | integer | 角色ID（外键 → roles.id） |
| `created_at` | timestamp | 分配时间 |

**实际数据**：
```json
[
  {"user_id": 5, "role_id": 52, "user": "admin", "role": "provincial_admin", "area": "梅州"},
  {"user_id": 6, "role_id": 1, "user": "烟草科技", "role": "admin", "area": "梅州"},
  {"user_id": 8, "role_id": 1, "user": "梅州烟草", "role": "admin", "area": "梅州"},
  {"user_id": 9, "role_id": 1, "user": "云浮烟草", "role": "admin", "area": "云浮"},
  {"user_id": 12, "role_id": 1, "user": "潮州烟草", "role": "admin", "area": "潮州"},
  {"user_id": 20, "role_id": 2, "user": "test_normal", "role": "common", "area": "梅州"},
  {"user_id": 21, "role_id": 2, "user": "test_other", "role": "common", "area": "梅州"}
]
```

---

### 1.3 权限控制规则

#### 规则矩阵表

| 操作 | 省级管理员 | 市级管理员 | 普通用户 |
|------|----------|----------|---------|
| **查看角色列表** | ✅ 所有角色 | ✅ 所有角色 | ✅ 所有角色 |
| **查看用户列表** | ✅ 所有地区用户 | ✅ 仅同地区用户 | ✅ 仅同地区用户 |
| **分配用户角色** | ✅ 所有地区用户 | ✅ 仅同地区用户 | ❌ 无权限 |
| **移除用户角色** | ✅ 所有地区用户 | ✅ 仅同地区用户 | ❌ 无权限 |
| **修改角色权限** | ✅ 可以修改 | ❌ 无权限 | ❌ 无权限 |

#### 地区隔离逻辑

**市级管理员的地区限制**：

```sql
-- 示例：梅州市级管理员（area='梅州'）

-- 查看用户列表
SELECT * FROM sso_users
WHERE status = 0
  AND area = '梅州'  -- ⭐强制过滤同地区

-- 分配用户角色（检查目标用户地区）
SELECT area FROM sso_users WHERE id = $1
-- 如果 target_area != '梅州' → 返回403错误

-- 移除用户角色（检查目标用户地区）
SELECT area FROM sso_users WHERE id = $1
-- 如果 target_area != '梅州' → 返回403错误
```

---

## 2. 完整接口文档

### 2.1 角色管理接口

#### 2.1.1 获取角色列表

**接口地址**：
```
GET /api/v3/rbac/roles
```

**权限要求**：
- 仅需登录（所有登录用户可访问）

**请求参数**：

| 参数名 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|------|--------|------|
| `page` | query | integer | 否 | 1 | 页码（从1开始） |
| `page_size` | query | integer | 否 | 20 | 每页数量（1-100） |
| `role_key` | query | string | 否 | - | 角色标识过滤（精确匹配） |
| `role_name` | query | string | 否 | - | 角色名称模糊搜索 |
| `include_system` | query | boolean | 否 | true | 是否包含系统角色 |

**请求示例**：

```bash
# 示例1：获取第1页，每页20条
curl -X GET "http://localhost:8073/api/v3/rbac/roles?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 示例2：搜索角色名称包含"管理"的角色
curl -X GET "http://localhost:8073/api/v3/rbac/roles?role_name=管理" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 示例3：查询特定角色
curl -X GET "http://localhost:8073/api/v3/rbac/roles?role_key=admin" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**返回格式**：

```json
{
  "total": 3,
  "page": 1,
  "page_size": 20,
  "data": [
    {
      "id": 52,
      "role_key": "provincial_admin",
      "role_name": "省级管理员",
      "description": "拥有全部权限，可以管理所有地区的评查点规则",
      "is_system": true,
      "created_at": "2025-01-15 10:30:00",
      "updated_at": "2025-01-20 14:20:00",
      "user_count": 1,
      "permission_count": 128
    },
    {
      "id": 1,
      "role_key": "admin",
      "role_name": "市级管理员",
      "description": "负责本地区的所有业务管理，不包括系统设置和角色权限管理",
      "is_system": false,
      "created_at": "2025-01-10 09:00:00",
      "updated_at": "2025-01-18 16:45:00",
      "user_count": 4,
      "permission_count": 85
    },
    {
      "id": 2,
      "role_key": "common",
      "role_name": "普通员工",
      "description": "仅能操作自己的数据",
      "is_system": false,
      "created_at": "2025-01-10 09:05:00",
      "updated_at": "2025-01-15 11:30:00",
      "user_count": 2,
      "permission_count": 32
    }
  ]
}
```

**字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `total` | integer | 总记录数 |
| `page` | integer | 当前页码 |
| `page_size` | integer | 每页大小 |
| `data` | array | 角色列表 |
| `data[].id` | integer | 角色ID |
| `data[].role_key` | string | 角色标识（唯一） |
| `data[].role_name` | string | 角色名称 |
| `data[].description` | string | 角色描述 |
| `data[].is_system` | boolean | 是否系统角色 |
| `data[].created_at` | string | 创建时间（北京时间） |
| `data[].updated_at` | string | 更新时间（北京时间） |
| `data[].user_count` | integer | 拥有该角色的用户数量 |
| `data[].permission_count` | integer | 该角色拥有的权限数量 |

**业务逻辑**：

```
1. JWT Token验证
   └─ 验证通过 → 解析用户信息

2. 构建查询条件
   ├─ 如果提供 role_key → 添加精确匹配条件
   ├─ 如果提供 role_name → 添加模糊搜索条件
   └─ 如果 include_system=false → 过滤系统角色

3. ⭐核心逻辑：所有人看到所有角色
   └─ 不进行用户角色过滤（角色是全局统一的）

4. 分页查询
   ├─ OFFSET = (page - 1) * page_size
   └─ LIMIT = page_size

5. 统计额外信息
   ├─ 查询每个角色的用户数量（COUNT）
   └─ 查询每个角色的权限数量（COUNT）

6. 返回结果
```

**错误响应**：

```json
{
  "detail": "Token已过期"
}
```

---

### 2.2 用户管理接口

#### 2.2.1 获取用户列表

**接口地址**：
```
GET /api/v2/users
```

**权限要求**：
- 仅需登录

**请求参数**：

| 参数名 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|------|--------|------|
| `page` | query | integer | 否 | 1 | 页码（从1开始） |
| `page_size` | query | integer | 否 | 20 | 每页数量（1-100） |
| `ou_id` | query | string | 否 | - | 组织单位ID过滤 |
| `is_leader` | query | boolean | 否 | - | 是否为领导过滤 |
| `status` | query | integer | 否 | 0 | 用户状态（0=正常） |
| `search` | query | string | 否 | - | 搜索关键词（用户名或昵称） |

**请求示例**：

```bash
# 示例1：获取第1页用户
curl -X GET "http://localhost:8073/api/v2/users?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 示例2：搜索用户名或昵称包含"张"的用户
curl -X GET "http://localhost:8073/api/v2/users?search=张" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 示例3：查询特定部门的用户
curl -X GET "http://localhost:8073/api/v2/users?ou_id=0000000A1ML" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**返回格式**：

```json
{
  "users": [
    {
      "id": 5,
      "username": "admin",
      "nick_name": "admin",
      "ou_id": "test",
      "ou_name": "test",
      "is_leader": false,
      "status": 0
    },
    {
      "id": 6,
      "username": "烟草科技",
      "nick_name": "烟草科技",
      "ou_id": "0000000A1ML",
      "ou_name": "测试技术部",
      "is_leader": false,
      "status": 0
    }
  ],
  "total": 6
}
```

**业务逻辑**：

```
1. JWT Token验证
   └─ 解析用户角色（user_role）和地区（area）

2. ⭐核心逻辑：地区数据隔离
   ├─ 如果 user_role == 'provincial_admin'
   │   └─ 查询所有地区用户（无地区过滤）
   └─ 否则（admin或其他用户）
       └─ 强制添加条件：WHERE area = current_user.area

3. 应用额外过滤条件
   ├─ 如果提供 ou_id → 添加 ou_id = {ou_id}
   ├─ 如果提供 is_leader → 添加 is_leader = {is_leader}
   └─ 如果提供 search → 添加 (username ILIKE %{search}% OR nick_name ILIKE %{search}%)

4. 分页查询
   ├─ OFFSET = (page - 1) * page_size
   └─ LIMIT = page_size

5. 查询总数（使用相同过滤条件）

6. 返回结果
```

**地区过滤示例**：

```sql
-- 省级管理员（user_role='provincial_admin'）
SELECT * FROM sso_users WHERE status = 0
-- 返回：所有地区的10个用户

-- 市级管理员（user_role='admin', area='梅州'）
SELECT * FROM sso_users WHERE status = 0 AND area = '梅州'
-- 返回：仅梅州的6个用户
```

---

### 2.3 角色分配接口

#### 2.3.1 分配用户到角色

**接口地址**：
```
POST /api/v3/rbac/users/{user_id}/roles
```

**权限要求**：
- 需要角色分配权限

**请求参数**：

| 参数名 | 位置 | 类型 | 必填 | 说明 |
|-------|------|------|------|------|
| `user_id` | path | integer | 是 | 用户ID |
| `role_ids` | body | array | 是 | 角色ID列表 |

**请求示例**：

```bash
# 给用户ID=20分配common角色（role_id=2）
curl -X POST "http://localhost:8073/api/v3/rbac/users/20/roles" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_ids": [2]
  }'
```

**请求Body示例**：

```json
{
  "role_ids": [2]
}
```

**返回格式**：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "user_id": 20,
    "username": "test_normal",
    "assigned_roles": [
      {
        "role_id": 2,
        "role_key": "common",
        "role_name": "普通员工"
      }
    ]
  }
}
```

**业务逻辑**：

```
1. JWT Token验证
   └─ 解析当前用户角色（current_user_role）和地区（current_user_area）

2. 查询目标用户信息
   └─ SELECT id, username, area FROM sso_users WHERE id = {user_id}

3. ⭐核心逻辑：地区检查
   ├─ 如果 current_user_role == 'provincial_admin'
   │   └─ 跳过地区检查（可操作所有地区用户）
   └─ 否则（admin或其他用户）
       ├─ 如果 target_area != current_user_area
       │   └─ 返回403错误："无权限给其他地区用户分配角色"
       └─ 否则，继续执行

4. 防止自己给自己分配角色
   └─ 如果 user_id == current_user_id → 返回403错误

5. 验证角色是否存在
   └─ SELECT * FROM roles WHERE id IN ({role_ids})

6. 检查provincial_admin角色限制
   └─ 只有省级管理员可以分配provincial_admin角色

7. 开始事务
   ├─ 插入 user_role 记录（批量）
   └─ 提交事务

8. 返回结果
```

**地区检查示例**：

```sql
-- 场景1：梅州市级管理员（area='梅州'）给梅州用户分配角色
target_user: {id: 20, area: '梅州'}
current_user: {role: 'admin', area: '梅州'}
检查结果: '梅州' == '梅州' → ✅ 允许

-- 场景2：梅州市级管理员尝试给云浮用户分配角色
target_user: {id: 9, area: '云浮'}
current_user: {role: 'admin', area: '梅州'}
检查结果: '云浮' != '梅州' → ❌ 返回403错误
```

**错误响应**：

```json
{
  "detail": "无权限给其他地区用户分配角色: target_area=云浮, your_area=梅州"
}
```

---

#### 2.3.2 移除用户角色

**接口地址**：
```
DELETE /api/v3/rbac/users/{user_id}/roles/{role_id}
```

**权限要求**：
- 需要角色分配权限

**请求参数**：

| 参数名 | 位置 | 类型 | 必填 | 说明 |
|-------|------|------|------|------|
| `user_id` | path | integer | 是 | 用户ID |
| `role_id` | path | integer | 是 | 角色ID |

**请求示例**：

```bash
# 移除用户ID=20的common角色（role_id=2）
curl -X DELETE "http://localhost:8073/api/v3/rbac/users/20/roles/2" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**返回格式**：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "user_id": 20,
    "role_id": 2,
    "message": "角色移除成功"
  }
}
```

**业务逻辑**：

```
1. JWT Token验证

2. 查询目标用户信息
   └─ SELECT id, username, area FROM sso_users WHERE id = {user_id}

3. ⭐核心逻辑：地区检查（同分配用户逻辑）
   ├─ 省级管理员 → 无限制
   └─ 市级管理员 → 只能操作同地区用户

4. 验证角色分配是否存在
   └─ SELECT * FROM user_role WHERE user_id = {user_id} AND role_id = {role_id}

5. 删除角色分配
   └─ DELETE FROM user_role WHERE user_id = {user_id} AND role_id = {role_id}

6. 返回结果
```

---

## 3. 业务场景示例

### 场景1：梅州市级管理员给本地用户分配角色

**前置条件**：
- 当前用户：梅州烟草（user_id=8, role=admin, area=梅州）
- 目标用户：test_normal（user_id=20, area=梅州）

**操作流程**：

```bash
# 步骤1：查看所有角色
GET /api/v3/rbac/roles

# 返回（所有人都能看到）：
{
  "data": [
    {"id": 1, "role_key": "admin", "role_name": "市级管理员"},
    {"id": 2, "role_key": "common", "role_name": "普通员工"},
    {"id": 52, "role_key": "provincial_admin", "role_name": "省级管理员"}
  ]
}

# 步骤2：查看可分配的用户列表
GET /api/v2/users

# 返回（只看到梅州的用户）：
{
  "users": [
    {"id": 5, "username": "admin", "area": "梅州"},
    {"id": 6, "username": "烟草科技", "area": "梅州"},
    {"id": 8, "username": "梅州烟草", "area": "梅州"},
    {"id": 19, "username": "test_admin", "area": "梅州"},
    {"id": 20, "username": "test_normal", "area": "梅州"},
    {"id": 21, "username": "test_other", "area": "梅州"}
  ],
  "total": 6
}

# 步骤3：给test_normal分配common角色
POST /api/v3/rbac/users/20/roles
{
  "role_ids": [2]
}

# 返回：
{
  "code": 200,
  "msg": "success",
  "data": {
    "user_id": 20,
    "username": "test_normal",
    "assigned_roles": [
      {"role_id": 2, "role_key": "common", "role_name": "普通员工"}
    ]
  }
}

# ✅ 成功！因为：
# 1. 角色列表可见（所有人都能看到所有角色）
# 2. 用户列表只显示梅州用户（地区过滤）
# 3. 分配成功（同地区用户）
```

---

### 场景2：梅州市级管理员尝试给云浮用户分配角色

**前置条件**：
- 当前用户：梅州烟草（user_id=8, role=admin, area=梅州）
- 目标用户：云浮烟草（user_id=9, area=云浮）

**操作流程**：

```bash
# 步骤1：查看用户列表
GET /api/v2/users

# 返回（只看到梅州的6个用户，看不到云浮烟草）：
{
  "users": [
    {"id": 5, "username": "admin", "area": "梅州"},
    {"id": 6, "username": "烟草科技", "area": "梅州"},
    ...
  ],
  "total": 6
}

# 步骤2：尝试直接调用API给云浮用户分配角色
POST /api/v3/rbac/users/9/roles
{
  "role_ids": [2]
}

# 返回：
{
  "detail": "无权限给其他地区用户分配角色: target_area=云浮, your_area=梅州"
}

# ❌ 失败！因为：
# 1. 地区检查：云浮 != 梅州
# 2. 后端强制拦截跨地区操作
```

---

### 场景3：省级管理员的完整权限

**前置条件**：
- 当前用户：admin（user_id=5, role=provincial_admin, area=梅州）

**操作流程**：

```bash
# 步骤1：查看所有角色
GET /api/v3/rbac/roles

# 返回（所有角色）：
{
  "data": [
    {"id": 1, "role_key": "admin"},
    {"id": 2, "role_key": "common"},
    {"id": 52, "role_key": "provincial_admin"}
  ]
}

# 步骤2：查看所有用户（包括所有地区）
GET /api/v2/users

# 返回（所有地区的10个用户）：
{
  "users": [
    {"id": 5, "area": "梅州"},
    {"id": 6, "area": "梅州"},
    {"id": 7, "area": "揭阳"},
    {"id": 8, "area": "梅州"},
    {"id": 9, "area": "云浮"},
    {"id": 12, "area": "潮州"},
    ...
  ],
  "total": 10
}

# 步骤3：给云浮用户分配角色（跨地区）
POST /api/v3/rbac/users/9/roles
{
  "role_ids": [1]
}

# 返回：
{
  "code": 200,
  "msg": "success"
}

# ✅ 成功！因为：
# 1. 省级管理员可以看到所有地区用户
# 2. 省级管理员可以操作所有地区用户
```

---

## 4. 数据库实际数据

### 4.1 角色数据

```sql
SELECT id, role_key, role_name, description
FROM roles
ORDER BY id;
```

| id | role_key | role_name | description |
|----|----------|-----------|-------------|
| 1 | admin | 市级管理员 | 负责本地区的所有业务管理 |
| 2 | common | 普通员工 | 仅能操作自己的数据 |
| 52 | provincial_admin | 省级管理员 | 拥有全部权限 |

---

### 4.2 用户数据（按地区分组）

```sql
SELECT id, username, nick_name, area, ou_name
FROM sso_users
WHERE status = 0
ORDER BY area, id;
```

**梅州（6人）**：

| id | username | nick_name | area | ou_name |
|----|----------|-----------|------|---------|
| 5 | admin | admin | 梅州 | test |
| 6 | 烟草科技 | 烟草科技 | 梅州 | 测试技术部 |
| 8 | 梅州烟草 | 梅州烟草 | 梅州 | 梅州管理员账号 |
| 19 | test_admin | 测试管理员 | 梅州 | 测试部门 |
| 20 | test_normal | 测试普通用户 | 梅州 | 测试部门 |
| 21 | test_other | 测试其他用户 | 梅州 | 测试部门 |

**云浮（2人）**：

| id | username | area |
|----|----------|------|
| 9 | 云浮烟草 | 云浮 |
| 22 | OAuth已存在用户测试 | 云浮 |

**揭阳（1人）**、**潮州（1人）**...

---

### 4.3 用户角色分配数据

```sql
SELECT
    u.id as user_id,
    u.username,
    u.area,
    r.role_key,
    r.role_name
FROM user_role ur
JOIN sso_users u ON ur.user_id = u.id
JOIN roles r ON ur.role_id = r.id
WHERE u.status = 0
ORDER BY u.area, u.id;
```

| user_id | username | area | role_key | role_name |
|---------|----------|------|----------|-----------|
| 5 | admin | 梅州 | provincial_admin | 省级管理员 |
| 6 | 烟草科技 | 梅州 | admin | 市级管理员 |
| 8 | 梅州烟草 | 梅州 | admin | 市级管理员 |
| 20 | test_normal | 梅州 | common | 普通员工 |
| 21 | test_other | 梅州 | common | 普通员工 |
| 9 | 云浮烟草 | 云浮 | admin | 市级管理员 |
| 12 | 潮州烟草 | 潮州 | admin | 市级管理员 |

---

## 5. 前端对接指南

### 5.1 角色权限管理页面

#### Vue 3 完整示例

```vue
<template>
  <div class="role-permission-page">
    <!-- 用户列表 -->
    <el-table :data="users" @selection-change="handleUserSelect">
      <el-table-column type="selection" width="55" />
      <el-table-column prop="username" label="用户名" />
      <el-table-column prop="nick_name" label="姓名" />
      <el-table-column prop="area" label="地区" />
      <el-table-column label="操作">
        <template #default="{ row }">
          <el-button size="small" @click="openAssignDialog(row)">
            分配角色
          </el-button>
        </template>
      </el-table-column>
    </el-table>

    <!-- 分配角色对话框 -->
    <el-dialog v-model="dialogVisible" title="分配角色">
      <el-form>
        <el-form-item label="选择角色">
          <el-checkbox-group v-model="selectedRoles">
            <el-checkbox
              v-for="role in roles"
              :key="role.id"
              :label="role.id"
            >
              {{ role.role_name }}
            </el-checkbox>
          </el-checkbox-group>
        </el-form-item>
      </el-form>
      <template #footer>
        <el-button @click="dialogVisible = false">取消</el-button>
        <el-button type="primary" @click="assignRoles">确定</el-button>
      </template>
    </el-dialog>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { ElMessage } from 'element-plus'

const users = ref([])
const roles = ref([])
const currentUser = ref(null)
const dialogVisible = ref(false)
const selectedRoles = ref([])

// 获取当前用户信息
const getCurrentUser = () => {
  const token = localStorage.getItem('token')
  if (token) {
    const payload = JSON.parse(atob(token.split('.')[1]))
    currentUser.value = {
      id: payload.user_id,
      role: payload.user_role,
      area: payload.area
    }
  }
}

// 获取角色列表（所有人都能看到所有角色）
const loadRoles = async () => {
  try {
    const response = await fetch('/api/v3/rbac/roles', {
      headers: {
        'Authorization': `Bearer ${localStorage.getItem('token')}`
      }
    })
    const result = await response.json()
    roles.value = result.data
  } catch (error) {
    ElMessage.error('加载角色列表失败')
  }
}

// 获取用户列表（自动按地区过滤）
const loadUsers = async () => {
  try {
    const response = await fetch('/api/v2/users?page=1&page_size=100', {
      headers: {
        'Authorization': `Bearer ${localStorage.getItem('token')}`
      }
    })
    const result = await response.json()
    users.value = result.users

    // 提示：市级管理员只能看到同地区用户
    if (currentUser.value.role === 'admin') {
      ElMessage.info(`当前显示 ${currentUser.value.area} 地区的 ${result.total} 个用户`)
    }
  } catch (error) {
    ElMessage.error('加载用户列表失败')
  }
}

// 打开分配对话框
const openAssignDialog = (user) => {
  currentUser.value.targetUser = user
  dialogVisible.value = true
}

// 分配角色
const assignRoles = async () => {
  const targetUser = currentUser.value.targetUser

  try {
    const response = await fetch(`/api/v3/rbac/users/${targetUser.id}/roles`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${localStorage.getItem('token')}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        role_ids: selectedRoles.value
      })
    })

    const result = await response.json()

    if (response.ok) {
      ElMessage.success('角色分配成功')
      dialogVisible.value = false
    } else if (response.status === 403) {
      ElMessage.error(result.detail || '权限不足：只能给同地区用户分配角色')
    } else {
      ElMessage.error(result.detail || '分配失败')
    }
  } catch (error) {
    ElMessage.error('分配失败：' + error.message)
  }
}

onMounted(() => {
  getCurrentUser()
  loadRoles()
  loadUsers()
})
</script>
```

### 5.2 关键要点

#### 1. Token解析

```javascript
// 解析JWT Token获取用户信息
const token = localStorage.getItem('token')
const payload = JSON.parse(atob(token.split('.')[1]))

// Payload包含：
{
  user_id: 8,
  username: "梅州烟草",
  user_role: "admin",          // 用户角色
  area: "梅州",                // 用户地区（⭐重要）
  exp: 1738036800
}
```

#### 2. 错误处理

```javascript
// 403错误：跨地区操作
if (response.status === 403) {
  ElMessage.error('权限不足：只能给同地区用户分配角色')
}

// 401错误：Token过期
if (response.status === 401) {
  ElMessage.error('登录已过期，请重新登录')
  router.push('/login')
}
```

#### 3. 地区提示

```javascript
// 市级管理员登录时，提示当前地区
if (user_role === 'admin') {
  ElMessage.info(`您当前管理的地区：${area}`)
}
```

---

## 附录

### A. 错误码对照表

| HTTP状态码 | 说明 | 常见原因 | 示例 |
|-----------|------|---------|------|
| 200 | 成功 | - | - |
| 400 | 请求参数错误 | 参数格式不正确 | `{"detail": "role_ids必须是数组"}` |
| 401 | 未认证 | Token无效或过期 | `{"detail": "Token已过期"}` |
| 403 | 无权限 | 跨地区操作或权限不足 | `{"detail": "无权限给其他地区用户分配角色"}` |
| 404 | 资源不存在 | 用户或角色不存在 | `{"detail": "用户不存在: user_id=999"}` |
| 500 | 服务器错误 | 后端异常 | `{"detail": "数据库连接失败"}` |

---

### B. JWT Token规范

**Header格式**：
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Payload字段**：

| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| `user_id` | integer | 是 | 用户ID | 8 |
| `username` | string | 是 | 用户名 | 梅州烟草 |
| `user_role` | string | 是 | 用户角色 | admin, provincial_admin, common |
| `area` | string | 是 | 用户地区（⭐用于权限隔离） | 梅州, 云浮, 揭阳, 潮州 |
| `exp` | integer | 是 | 过期时间（Unix时间戳） | 1738036800 |
| `aud` | string | 是 | 受众标识 | docauditai |

---

### C. 数据库字段重要说明

| 字段 | 表 | 用途 | 示例 | 说明 |
|------|-----|------|------|------|
| `area` | sso_users | **地区隔离**（权限控制） | 梅州, 云浮 | ⭐用于判断市级管理员的操作范围 |
| `ou_name` | sso_users | **部门划分**（组织结构） | 测试技术部, 研发部 | 仅用于显示，不用于权限控制 |
| `ou_id` | sso_users | 组织单位ID | 0000000A1ML | 用于组织树结构 |

**⚠️ 关键区别**：
- `area`：用于**权限隔离**（省/市级别）
- `ou_name`：用于**组织显示**（部门级别）

---

### D. 快速参考

#### 角色类型

| role_key | role_name | 说明 |
|----------|-----------|------|
| `provincial_admin` | 省级管理员 | 最高权限，可操作所有地区 |
| `admin` | 市级管理员 | 地区管理员，只能操作同地区用户 |
| `common` | 普通员工 | 基础权限 |

#### API端点速查

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v3/rbac/roles` | GET | 获取角色列表（所有人可见） |
| `/api/v2/users` | GET | 获取用户列表（按地区过滤） |
| `/api/v3/rbac/users/{id}/roles` | POST | 分配角色（地区检查） |
| `/api/v3/rbac/users/{id}/roles/{rid}` | DELETE | 移除角色（地区检查） |

---

**文档版本**: v3.3
**最后更新**: 2025-11-28
**维护者**: Backend Team
**反馈渠道**: backend-team@example.com