docs: reorganize by module

2026-05-09 20:04:08 +08:00
parent 29873eaecd
commit c9d7a693b8
23 changed files with 2161 additions and 197 deletions
@@ -0,0 +1,418 @@
+# 用户权限初始化 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`
+- `/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/权限与地区隔离/权限与地区隔离文档导航.md`
+- 本文：`docs/权限与地区隔离/用户权限与权限点清单.md`
+- SQL：`docs/权限与地区隔离/用户权限初始化SQL.sql`
+
+这四份组合起来，就是当前新系统用户权限方案的完整本地留档。