leaudit-platform-backend/docs/接口/用户权限与权限点清单.md

# 用户权限初始化 SQL 与权限点清单

这份文档对应：`docs/接口/用户权限初始化SQL.sql`

用途只有两个：

- 帮你快速初始化当前新系统最小可用的用户权限体系
- 帮后续自己看代码、配角色、排查越权时不再忘记“每个权限点到底是干什么的”

当前这版严格按你确认过的业务收口：

- 只做 `RBAC + 单地区隔离`
- 用户地区只认 `sso_users.area`
- 角色只认 `provincial_admin`、`admin`、`common`
- `super_admin` 仅作为可选系统维护角色
- 数据范围只认 `ALL / DEPT / SELF`

---

## 1. 本次交付文件

- SQL：`docs/接口/用户权限初始化SQL.sql`
- 说明：`docs/接口/用户权限与权限点清单.md`

---

## 2. SQL 初始化了什么

这份 SQL 会初始化 5 类内容：

1. `roles` 角色基础数据
2. `sys_routes` 菜单 / 页面路由基础数据
3. `permissions` 权限点基础数据
4. `role_route` 角色可见菜单授权
5. `role_permissions` 角色权限点授权

它的定位不是“把所有未来功能一次性配满”，而是：

- 先把当前 `leaudit-platform` 已经稳定的核心能力配起来
- 后续有新接口，再继续增量追加权限点

---

## 3. 当前正式角色

## 3.1 `provincial_admin`

- 省级管理员
- 默认数据范围：`ALL`
- 能看全省文档、任务、评查结果、规则配置、用户与角色配置

## 3.2 `admin`

- 地区管理员
- 默认数据范围：`DEPT`
- 实际含义是“同地区”，不是组织部门
- 只能处理 `region = 当前用户.area` 的业务数据

## 3.3 `common`

- 普通用户
- 默认数据范围：`SELF`
- 通常只能看自己上传 / 自己触发 / 自己归属的数据
- 对部分只读接口，可以单独放宽到 `DEPT`

## 3.4 `super_admin`

- 可选系统超级管理员
- 默认数据范围：`ALL`
- 只建议用来做系统维护、初始化、排障
- 不建议参与日常业务权限设计

---

## 4. 数据范围解释

## 4.1 `ALL`

- 不做地区过滤
- 可看全部数据

## 4.2 `DEPT`

- 在本项目里，正式定义为“同地区”
- 一般等价于：`业务表.region = sso_users.area`

## 4.3 `SELF`

- 只能看自己的数据
- 一般等价于：
  - `created_by = 当前用户.id`
  - 或 `uploaded_by = 当前用户.id`
  - 或 `owner_id = 当前用户.id`

## 4.4 生效优先级

后端建议统一这样算：

1. 先看当前接口是否命中某条 `role_permissions`
2. 若该条有 `data_scope`，优先用它
3. 若该条没有 `data_scope`，回退到 `roles.data_scope`
4. 多角色命中时，取可见范围最大的那个：`ALL > DEPT > SELF`

---

## 5. 当前菜单建议

SQL 里初始化了以下核心菜单：

- `/documents`
- `/documents/list`
- `/rules`
- `/rules/sets`
- `/audit`
- `/audit/runs`
- `/system`
- `/system/users`
- `/system/roles`

这套菜单不是说前端必须完全一模一样，而是作为当前后台权限建模的“标准路径集合”。

---

## 6. 当前权限点清单

下面是当前已经纳入初始化 SQL 的权限点。

## 6.1 认证类

### `auth.me`

- 接口：`GET /api/auth/me`
- 用途：获取当前登录用户信息
- 建议角色：全部登录用户都可访问

---

## 6.2 文档类

### `documents.upload`

- 接口：`POST /api/upload`
- 用途：上传文档，可选自动触发评查
- `provincial_admin`：`ALL`
- `admin`：`DEPT`
- `common`：`SELF`

### `documents.list`

- 接口：`GET /api/documents/list`
- 用途：查看文档列表
- `provincial_admin`：全量文档
- `admin`：本地区文档
- `common`：自己的文档

### `documents.detail`

- 接口：`GET /api/documents/{documentId}`
- 用途：查看文档详情
- 数据范围逻辑应和 `documents.list` 保持一致

### `documents.history`

- 接口：`GET /api/documents/{documentId}/versions`
- 用途：查看同名文档历史版本
- 数据范围逻辑应和文档主记录一致

### `documents.delete`

- 接口：`DELETE /api/documents/{documentId}`
- 用途：删除文档
- 建议只开放给 `provincial_admin` 和 `admin`

---

## 6.3 评查类

### `audit.run`

- 接口：`POST /api/audit/run`
- 用途：手动触发评查
- `provincial_admin`：可发起任意地区 run
- `admin`：只能发起本地区 run
- `common`：只能发起自己可见文档的 run

### `audit.run.status`

- 接口：`GET /api/audit/run/{runId}`
- 用途：查看 run 当前执行状态

### `audit.result`

- 接口：`GET /api/audit/result/{runId}`
- 用途：查看评查结果

这两个接口都要跟随文档 / run 的归属范围过滤，不能因为知道 `runId` 就越权读取。

---

## 6.4 规则类

### `rules.list`

- 接口：`GET /api/rule-sets`
- 用途：查看规则集列表

### `rules.version.list`

- 接口：`GET /api/rule-sets/{ruleType}/versions`
- 用途：查看某规则集的版本列表

### `rules.content`

- 接口：`GET /api/rule-sets/versions/{versionId}/content`
- 用途：查看规则 YAML 正文

### `rules.validate`

- 接口：`POST /api/rule-sets/{ruleType}/validate`
- 用途：校验规则 YAML

### `rules.version.create`

- 接口：`POST /api/rule-sets/{ruleType}/versions`
- 用途：创建规则版本
- 建议开放给 `provincial_admin`
- 如确有地区自管需求，再按地区规则放给 `admin`

### `rules.publish`

- 接口：`POST /api/rule-sets/{ruleType}/publish`
- 用途：发布规则版本
- 建议只开放给 `provincial_admin`

### `rules.rollback`

- 接口：`POST /api/rule-sets/{ruleType}/rollback`
- 用途：规则回滚
- 建议只开放给 `provincial_admin`

### `rules.binding.list`

- 接口：`GET /api/rule-sets/bindings`
- 用途：查看规则绑定

### `rules.binding.create`

- 接口：`POST /api/rule-sets/{ruleType}/bindings`
- 用途：创建规则绑定

### `rules.binding.update`

- 接口：`PUT /api/rule-sets/bindings/{bindingId}`
- 用途：更新规则绑定

### `rules.binding.delete`

- 接口：`DELETE /api/rule-sets/bindings/{bindingId}`
- 用途：删除规则绑定

---

## 6.5 用户类

### `users.list`

- 接口：`GET /api/users/list`
- 用途：查看用户列表
- `provincial_admin`：全部用户
- `admin`：本地区用户
- `common`：通常不开放

### `users.create`

- 接口：`POST /api/users`
- 用途：创建用户
- 建议只开放给 `provincial_admin`

### `users.update`

- 接口：`PUT /api/users/{userId}`
- 用途：修改用户信息
- `admin` 仅能维护本地区用户

### `users.disable`

- 接口：`PUT /api/users/{userId}/disable`
- 用途：禁用 / 启用用户
- 建议只开放给 `provincial_admin`

### `users.roles.assign`

- 接口：`POST /api/users/{userId}/roles`
- 用途：为用户分配角色
- 建议只开放给 `provincial_admin`

---

## 6.6 RBAC 管理类

### `rbac.roles.list`

- 接口：`GET /api/rbac/roles`
- 用途：查看角色列表

### `rbac.roles.update`

- 接口：`PUT /api/rbac/roles/{roleId}`
- 用途：修改角色定义

### `rbac.permissions.list`

- 接口：`GET /api/rbac/permissions`
- 用途：查看权限点列表

### `rbac.role_permissions.assign`

- 接口：`POST /api/rbac/roles/{roleId}/permissions`
- 用途：给角色分配权限点

### `rbac.role_routes.assign`

- 接口：`PUT /api/rbac/roles/{roleId}/routes`
- 用途：给角色分配菜单

这些建议默认只给：

- `provincial_admin`
- `super_admin`

---

## 7. 角色默认授权概览

## 7.1 `provincial_admin`

建议拥有：

- 全部当前权限点
- 数据范围全部 `ALL`

## 7.2 `admin`

建议拥有：

- 文档上传、列表、详情、删除
- 评查触发、进度查看、结果查看
- 规则查看、校验、部分绑定维护
- 本地区用户列表与部分用户维护
- 数据范围多数为 `DEPT`

## 7.3 `common`

建议拥有：

- 当前用户信息
- 文档上传
- 自己文档列表 / 详情 / 历史版本
- 自己触发的评查任务与结果
- 部分规则只读查看
- 数据范围多数为 `SELF`

---

## 8. 后端接入要求

权限初始化 SQL 只是把“数据字典”配起来，真正生效还要靠后端统一遵守下面规则：

### 8.1 JWT 必须能拿到这些信息

至少要能拿到：

- `user_id`
- `area`
- `roles`
- `permissions`

### 8.2 接口先做功能权限，再做数据过滤

不要只做页面隐藏，必须后端实际校验：

1. 有没有权限点
2. 命中哪条 `data_scope`
3. 按 `ALL / DEPT / SELF` 注入查询条件

### 8.3 前端传入的地区不能覆盖后端数据权限

例如：

- `GET /api/documents/list?region=省局`

如果当前用户只是潮州 `admin`，后端仍然只能返回潮州数据，不能因为前端传了别的地区就放开。

---

## 9. 建议你怎么用这份 SQL

建议按这个顺序：

1. 先在测试库执行 `docs/接口/用户权限初始化SQL.sql`
2. 检查 `roles / permissions / role_permissions / role_route` 是否初始化成功
3. 给几个测试账号分别挂 `provincial_admin / admin / common`
4. 再用接口实际验证：
   - 文档列表是否按地区隔离
   - 当前用户信息是否正确返回 `area`
   - 上传 / 评查是否存在越权

---

## 10. 当前文档与总设计文档的关系

如果你后面忘了这套体系总原则，看这里：

- 总设计：`docs/用户与地区权限完整设计方案.md`
- 老系统分析：`docs/老系统_docauditai_用户权限架构深度分析.md`
- 本文：`docs/接口/用户权限与权限点清单.md`
- SQL：`docs/接口/用户权限初始化SQL.sql`

这四份组合起来，就是当前新系统用户权限方案的完整本地留档。