feat: 角色等级体系与权限管控实施

- 数据库：auth_roles 表新增 level 字段（1=超管, 10=管理员, 100=普通用户） - 后端：新增 GetAllRoles/GetUserMaxLevel/SetUserRoles/FindByCodeList DAO 方法 - 后端：SetRolesRequest 替换 AssignRoleRequest，AdminUserInfo.Roles 改为 []RoleInfo - 后端：所有管理操作（禁用/启用/角色分配/创建用户）强制层级权限校验 - 后端：PUT /users/:id/roles（批量设置角色）+ GET /roles（角色列表） - 前端：角色管理改为 Checkbox Group 多选，高等级角色禁用 - 前端：禁用/启用按钮受角色层级约束，列表页操作按钮权限管控 - 前端：创建用户对话框角色选项根据操作者等级动态过滤 - 文档：API 文档、设计方案、集成规范、进度文档同步更新 Made-with: Cursor
2026-03-02 15:40:02 +08:00
parent dd84e50429
commit fa6f1e5c58
18 changed files with 771 additions and 279 deletions
--- a/docs/api/admin/user.md
+++ b/docs/api/admin/user.md
@@ -11,9 +11,10 @@
 |------|------|------|------|
 | GET | /api/v1/admin/users | admin | 获取用户列表 |
 | GET | /api/v1/admin/users/:id | admin | 获取用户详情 |
-| PUT | /api/v1/admin/users/:id/status | admin | 更新用户状态 |
-| PUT | /api/v1/admin/users/:id/role | admin / super_admin | 分配用户角色 |
+| PUT | /api/v1/admin/users/:id/status | admin | 更新用户状态（受角色等级约束） |
+| PUT | /api/v1/admin/users/:id/roles | admin / super_admin | 批量设置用户角色（受角色等级约束） |
 | POST | /api/v1/admin/users | admin | 管理员创建用户 |
+| GET | /api/v1/admin/roles | admin | 获取所有角色列表（含 level） |
 | GET | /api/v1/admin/users/:id/meetings | admin | 获取用户会议记录（Phase 3 实现） |

 ---
@@ -51,7 +52,10 @@
                "phone": "13800138000",
                "status": 1,
                "status_text": "正常",
-                "roles": ["user"],
+                "roles": [
+                    { "code": "user", "name": "普通用户", "level": 100 }
+                ],
+                "max_level": 100,
                "last_login_at": "2026-02-27 10:00:00",
                "last_login_ip": "192.168.1.100",
                "created_at": "2026-02-20 08:00:00",
@@ -85,7 +89,10 @@
        "phone": "13800138000",
        "status": 1,
        "status_text": "正常",
-        "roles": ["user"],
+        "roles": [
+            { "code": "user", "name": "普通用户", "level": 100 }
+        ],
+        "max_level": 100,
        "last_login_at": "2026-02-27 10:00:00",
        "last_login_ip": "192.168.1.100",
        "created_at": "2026-02-20 08:00:00",
@@ -111,6 +118,7 @@
 **说明：**
 - 禁用用户后，该用户的所有活跃 Token 将被清除
 - 不能禁用自己的账号（返回 400）
+- 操作者权限等级必须高于目标用户（level 数值更小），否则返回 403
 - 禁用后用户尝试登录将返回 403

 **成功响应：**
@@ -125,9 +133,9 @@

 ---

-## 4. 分配用户角色
+## 4. 批量设置用户角色

-`PUT /api/v1/admin/users/:id/role`
+`PUT /api/v1/admin/users/:id/roles`

 **权限：** admin / super_admin

@@ -135,11 +143,49 @@

 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| role_code | string | 是 | 角色代码：user / admin / super_admin |
+| role_codes | string[] | 是 | 角色代码列表，如 `["user", "admin"]` |
+
+**权限管控规则：**
+- 操作者权限等级（level）必须严格高于目标用户（数值更小），否则返回 403
+- 不能分配等级高于或等于操作者自身的角色，否则返回 403
+- 角色列表为全量覆盖（先清除再设置）
+- 注：`super_admin` 角色（level=1）不可通过 API 分配（任何人的 level 都 >= 1），超管只能通过数据库直接创建
+
+**成功响应：**
+```json
+{
+    "code": 0,
+    "message": "success"
+}
+```
+
+**错误响应：**
+- 403：`权限不足，无法操作更高等级的用户` 或 `不能分配高于自身等级的角色`

 ---

-## 5. 管理员创建用户
+## 5. 获取所有角色列表
+
+`GET /api/v1/admin/roles`
+
+**权限：** admin
+
+**成功响应：**
+```json
+{
+    "code": 0,
+    "message": "success",
+    "data": [
+        { "code": "super_admin", "name": "超级管理员", "level": 1 },
+        { "code": "admin", "name": "管理员", "level": 10 },
+        { "code": "user", "name": "普通用户", "level": 100 }
+    ]
+}
+```
+
+---
+
+## 6. 管理员创建用户

 `POST /api/v1/admin/users`

@@ -155,6 +201,14 @@
 | nickname | string | 否 | 昵称（默认使用用户名） |
 | role_code | string | 否 | 指定角色，默认为 user |

+**权限管控规则：**
+- 不能为新用户分配等级高于或等于操作者自身的角色，否则返回 403
+- 例：admin（level=10）只能分配 level > 10 的角色（如 user），不能分配 admin 或 super_admin
+
+**错误响应：**
+- 400：`用户名或邮箱已被注册` / `无效的角色代码`
+- 403：`不能分配高于自身等级的角色`
+
 **成功响应：**
 ```json
 {
@@ -169,7 +223,10 @@
        "gender": 0,
        "status": 1,
        "status_text": "正常",
-        "roles": ["user"],
+        "roles": [
+            { "code": "user", "name": "普通用户", "level": 100 }
+        ],
+        "max_level": 100,
        "created_at": "2026-03-02 11:12:33",
        "updated_at": "2026-03-02 11:12:33"
    },
@@ -180,7 +237,7 @@

 ---

-## 6. 获取用户会议记录
+## 7. 获取用户会议记录

 `GET /api/v1/admin/users/:id/meetings`

--- a/docs/conventions/frontend-backend-integration.md
+++ b/docs/conventions/frontend-backend-integration.md
@@ -265,3 +265,50 @@ JWT Token 的 Claims 中包含 `client_type` 字段，用于：
 - [ ] JWT Claims 中包含 client_type 字段
 - [ ] 登出时只删除对应 clientType 的 Token
 - [ ] Token 刷新时保持原 clientType 不变
+
+---
+
+## 7. 角色等级与权限管控规范
+
+### 7.1 角色等级设计
+
+`auth_roles` 表 `level` 字段，值越小权限越高，预留间隔：
+
+| 角色 | Code | Level | 说明 |
+|------|------|-------|------|
+| 超级管理员 | super_admin | 1 | 最高权限 |
+| 管理员 | admin | 10 | 后台管理 |
+| 普通用户 | user | 100 | 基础权限 |
+
+用户可拥有多个角色，取**最小 level 值**作为有效权限等级。
+
+### 7.2 权限管控规则
+
+**核心原则：操作者的 level 必须严格小于目标用户的 level，才能执行管理操作。**
+
+1. **更新用户状态（禁用/启用）**：操作者 level < 目标用户 level
+2. **设置用户角色**：操作者 level < 目标用户 level，且不能分配 level <= 自身的角色
+3. **前端管控**：禁用/启用按钮对高等级用户隐藏，高等级角色 checkbox 禁用
+
+### 7.3 API 响应变更
+
+`AdminUserInfo` 的 `roles` 字段从 `[]string` 改为 `[]RoleInfo`：
+
+```json
+{
+    "roles": [
+        { "code": "admin", "name": "管理员", "level": 10 },
+        { "code": "user", "name": "普通用户", "level": 100 }
+    ],
+    "max_level": 10
+}
+```
+
+### 7.4 检查清单
+
+涉及用户管理操作时，必须确认：
+
+- [ ] 后端 Service 层调用 `checkPermissionLevel` 进行等级校验
+- [ ] 权限不足时返回 403（`ErrInsufficientPermission`）
+- [ ] 前端通过比较 `adminMaxLevel` 和 `targetMaxLevel` 控制 UI 可见性
+- [ ] 角色分配使用全量覆盖模式（`SetUserRoles`），非追加模式
--- a/docs/plans/2026-02-27-echochat-system-design.md
+++ b/docs/plans/2026-02-27-echochat-system-design.md
@@ -81,6 +81,8 @@

 - 前台用户和后台管理员共用 `auth_users` 表
 - 通过 `auth_roles` 和 `auth_user_roles` 区分角色（user / admin / super_admin）
+- `auth_roles.level` 字段实现角色等级层级管控（值越小权限越高：1=超管, 10=管理员, 100=用户）
+- 管理操作强制执行"高等级管理低等级"规则（操作者 level 必须 < 目标用户 level）
 - 前台 API 路由：`/api/v1/auth/*` — 仅需 JWT 验证
 - 后台 API 路由：`/api/v1/admin/*` — JWT 验证 + 角色检查双重中间件

@@ -235,6 +237,7 @@ CREATE TABLE auth_roles (
    id          SERIAL PRIMARY KEY,
    code        VARCHAR(50) UNIQUE NOT NULL,
    name        VARCHAR(50) NOT NULL,
+    level       INT NOT NULL DEFAULT 100,
    description VARCHAR(200) DEFAULT '',
    created_at  TIMESTAMP NOT NULL DEFAULT NOW()
 );
@@ -243,14 +246,15 @@ COMMENT ON TABLE  auth_roles             IS '角色表，定义系统中所有
 COMMENT ON COLUMN auth_roles.id          IS '角色唯一标识，自增主键';
 COMMENT ON COLUMN auth_roles.code        IS '角色代码，唯一标识：user=普通用户，admin=管理员，super_admin=超级管理员';
 COMMENT ON COLUMN auth_roles.name        IS '角色显示名称，如"普通用户""管理员""超级管理员"';
+COMMENT ON COLUMN auth_roles.level       IS '角色等级，值越小权限越高：1=超管, 10=管理员, 100=普通用户，预留间隔便于扩展';
 COMMENT ON COLUMN auth_roles.description IS '角色描述说明';
 COMMENT ON COLUMN auth_roles.created_at  IS '创建时间';

-- 预置角色数据
-INSERT INTO auth_roles (code, name, description) VALUES
-    ('user',        '普通用户',   '系统普通用户，可以使用聊天、会议等功能'),
-    ('admin',       '管理员',    '后台管理员，可以管理用户、监控会议等'),
-    ('super_admin', '超级管理员', '最高权限管理员，可以管理角色和系统配置');
+-- 预置角色数据（level 值越小权限越高）
+INSERT INTO auth_roles (code, name, level, description) VALUES
+    ('user',        '普通用户',   100, '系统普通用户，可以使用聊天、会议等功能'),
+    ('admin',       '管理员',     10,  '后台管理员，可以管理用户、监控会议等'),
+    ('super_admin', '超级管理员', 1,   '最高权限管理员，可以管理角色和系统配置');

 -- ============================================================
 -- auth_user_roles: 用户角色关联表
@@ -265,8 +269,8 @@ CREATE TABLE auth_user_roles (

 #### 权限扩展规划（后期迭代）

-> 当前 MVP 阶段使用粗粒度 3 角色（user / admin / super_admin）即可满足需求。
-> 后期管理员增多、需要区分职责时，引入细粒度权限点机制，扩展如下两张表：
+> 当前已实现：3 角色 + level 等级层级管控（super_admin=1, admin=10, user=100），所有管理操作受层级约束。
+> 后期管理员增多、需要区分职责时，引入细粒度权限点机制，扩展如下两张表（level 字段天然支持排序和层级融合）：

 ```sql
 -- 预留：权限点表（后期扩展）
@@ -714,8 +718,9 @@ POST   /api/v1/admin/auth/login
 GET    /api/v1/admin/users
 GET    /api/v1/admin/users/:id
 PUT    /api/v1/admin/users/:id/status
-PUT    /api/v1/admin/users/:id/role
+PUT    /api/v1/admin/users/:id/roles
 POST   /api/v1/admin/users
+GET    /api/v1/admin/roles
 GET    /api/v1/admin/users/:id/meetings

 # 会议管理
--- a/docs/plans/2026-02-27-phase1-foundation-and-auth.md
+++ b/docs/plans/2026-02-27-phase1-foundation-and-auth.md
@@ -3,6 +3,7 @@
 > **状态：✅ Phase 1 全部完成**（2026-03-02）
 > 11 个 Task 全部通过端到端验证和代码审查。
 > 分支：`feature/phase1-foundation-and-auth`
+> **补充：角色等级体系与权限管控已实施**（2026-03-02）— `auth_roles.level` 字段 + 层级权限 + 多选角色分配

 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

--- a/docs/progress/CURRENT_STATUS.md
+++ b/docs/progress/CURRENT_STATUS.md
@@ -1,6 +1,6 @@
 # EchoChat 项目开发进度

-> **最后更新**：2026-03-02（前后端错误处理规范统一 + 安全加固）
+> **最后更新**：2026-03-02（角色等级体系与权限管控实施）
 > **当前阶段**：Phase 1 - 基础设施与用户认证
 > **当前分支**：`feature/phase1-foundation-and-auth`
 > **实施计划**：`docs/plans/2026-02-27-phase1-foundation-and-auth.md`
@@ -35,6 +35,7 @@
 5. **API 响应格式**：统一 `{ "code": 0, "message": "success", "data": ... }`
 6. **常量命名**：Go camelCase（`UserStatusActive`），非大写下划线
 7. **模块路由**：模块内自注册 + 中央 router 聚合
+8. **角色等级体系**：`auth_roles.level` 字段（值越小权限越高：1=超管, 10=管理员, 100=普通用户），所有管理操作强制执行"高等级管理低等级"规则

 ### 前台用户端（frontend/）
 1. **框架**：uni-app 3.0（Vue 3.4.21 框架锁定）
@@ -151,7 +152,7 @@ cd frontend && npm run dev:h5

 ### 可测试功能

- **管理端**：登录 → 仪表盘 → 用户列表 → 搜索/筛选 → 用户详情 → 禁用/启用 → 分配角色 → 创建用户
+- **管理端**：登录 → 仪表盘 → 用户列表 → 搜索/筛选 → 用户详情 → 禁用/启用（受角色等级约束） → 批量设置角色（Checkbox 多选 + 等级管控） → 创建用户
 - **前台 H5**：注册 → 登录 → 个人中心 → 修改资料 → 退出登录
 - **API**：`GET http://localhost:8085/health`（健康检查）