TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add tenant-scoped rule and permission management

Browse Source
This commit is contained in:
wren
2026-05-21 22:03:08 +08:00
parent a2c2bf1969
commit 1f1bccf3b3
193 changed files with 64463 additions and 1771 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/权限与地区隔离/权限字段映射与SQL改造规范.md
+830
View File
@@ -0,0 +1,830 @@
# 权限字段映射与 SQL 改造规范
> 适用范围：`leaudit-platform` 后端权限改造中的查询语句、资源详情、导出下载、统计聚合、管理列表
> 文档定位：为统一数据范围执行器的接入提供字段映射标准、SQL 拼接规范、资源回溯规范和反模式约束。
---
## 1. 文档目标
这份文档解决的是一个非常具体的问题：
统一数据范围执行器设计出来以后，后端各模块到底怎么把它安全、稳定地接到现有 SQL 上。
当前项目最大风险不是“不会写 scope”，而是：
1. 同一个模块里不同查询使用了不同字段口径
2. 列表、详情、下载、导出没有复用同一主资源边界
3. 各 service 自己拼 `1 = 0`、`region`、`created_by`，可维护性很差
4. 多表 join 时，究竟该按 `u.area` 还是 `d.region`，目前没有统一规范
所以这份文档的目标是：
1. 定义统一字段映射标准
2. 定义统一 alias 规范
3. 定义统一 scope 子句拼接方式
4. 定义详情、下载、导出等派生资源的“主资源回溯”规则
5. 定义改造时哪些 SQL 能保留，哪些必须重构
---
## 2. 当前代码里已经暴露出的典型问题
结合现有实现，已经确认有以下模式：
- `documentServiceImpl` / `govdocServiceImpl`
- 通过 `d.region` + `f.created_by` 控制范围
- `usageStatsServiceImpl`
- 有时按 `u.area`
- 有时按 `d.region`
- 有时还要按 `e.area_snapshot`
- `contractTemplateServiceImpl`
- 既有 `t.region`
- 又有 `t.created_by`
- 还混入“省级模板可见”
- `rbacAdminServiceImpl`
- 用户列表、组织树本质上按 `u.area`
这说明项目不是“没有规则”，而是规则散了。
---
## 3. 核心原则
## 3.1 先确定主资源，再确定 scope 字段
SQL 改造第一步不是拼条件，而是先回答：
- 这个接口的主资源是谁？
例如：
- 文档列表：主资源是 `document`
- 文档状态：主资源仍是 `document`
- 公文报告下载：主资源不是 `report_artifact`，而是 `govdoc document`
- RAG 文档分段列表：主资源不是 `segment`，而是 `dataset`
- 交叉评查提案导出：主资源不是 `proposal`，而是“用户参与的任务文档”
只有先确定主资源，scope 才不会跑偏。
## 3.2 范围条件必须挂在主资源口径上
同一个接口里如果出现多表：
- `document d`
- `document_file f`
- `sso_users u`
必须先规定：
- area 看哪个表
- self 看哪个表
不能在同一个模块里一会儿 `u.area`，一会儿 `d.region`，又没有解释。
## 3.3 列表、详情、删除、下载、导出必须继承同一套 scope
这条必须强制执行。
不允许出现：
- 列表按文档范围过滤
- 详情直接按 `id`
- 下载直接按附件 `id`
- 导出直接按 run `id`
凡是派生资源，都必须回溯主资源。
---
## 4. 统一字段映射标准
## 4.1 标准字段分类
建议统一按 5 类字段管理：
1. `area_field`
2. `creator_field`
3. `owner_field`
4. `user_field`
5. `public_field`
建议结构：
```python
@dataclass
class ScopeFieldMapping:
area_field: str | None = None
creator_field: str | None = None
owner_field: str | None = None
user_field: str | None = None
public_field: str | None = None
```
## 4.2 字段语义定义
### `area_field`
表示资源的地区归属字段。
例如：
- `d.region`
- `t.region`
- `dataset.area`
- `app.area`
- `u.area`
### `creator_field`
表示“创建该资源的用户”。
例如：
- `f.created_by`
- `t.created_by`
- `proposal.created_by`
### `owner_field`
表示“资源所有者”，和创建者不一定相同。
如果当前项目没有成熟 owner 模型，可以先不启用。
### `user_field`
用于用户本身或用户快照类数据。
例如：
- `u.id`
- `e.user_id`
### `public_field`
表示是否公共可见。
例如：
- `dataset.is_public`
- `app.is_public`
---
## 5. 各模块字段映射表
## 5.1 文档模块
主资源：`leaudit_documents d`
推荐映射：
| 类型 | 字段 |
| --- | --- |
| `area_field` | `d.region` |
| `creator_field` | `f.created_by` |
| `owner_field` | 暂无 |
| `user_field` | `f.created_by` |
说明：
- 当前代码事实口径就是 `d.region + f.created_by`
- 文档的“自己数据”不建议改成 `d.created_by`，因为现有实现明显依赖文件记录
## 5.2 公文模块
主资源：`govdoc document / leaudit_documents d`
推荐映射：
| 类型 | 字段 |
| --- | --- |
| `area_field` | `d.region` |
| `creator_field` | `f.created_by` |
| `user_field` | `f.created_by` |
说明：
- 公文 run、报告、原文都必须回溯到 `d.region` 和 `f.created_by`
## 5.3 使用统计模块
这块必须拆成两个口径。
### 用户口径统计
主资源：`sso_users u` 或 `usage_login_events e`
推荐映射：
| 类型 | 字段 |
| --- | --- |
| `area_field` | `u.area` 或 `e.area_snapshot` |
| `user_field` | `u.id` 或 `e.user_id` |
### 文档口径统计
主资源：文档上传/评查事件
推荐映射：
| 类型 | 字段 |
| --- | --- |
| `area_field` | `d.region` |
| `creator_field` | `f.created_by` |
| `user_field` | `f.created_by` |
说明：
- `areaScope=user` 和 `areaScope=document` 本质上是两套字段映射切换
- 不能在一个 builder 里靠字符串替换硬凑
## 5.4 合同模板模块
主资源：`contract_template t`
推荐映射：
| 类型 | 字段 |
| --- | --- |
| `area_field` | `t.region` |
| `creator_field` | `t.created_by` |
| `public_field` | 暂无；如后续有省级公共模板逻辑，应单独建模 |
说明：
- 当前模块有“省级模板 + 本地区模板”可见语义
- 这不是 `is_public`
- 应在 `ContractTemplatePolicy` 中定义成“系统公共范围”，不要混同布尔公开字段
## 5.5 RBAC 用户管理
主资源：`sso_users u`
推荐映射：
| 类型 | 字段 |
| --- | --- |
| `area_field` | `u.area` |
| `user_field` | `u.id` |
说明：
- 角色对象本身不按 area
- 但“查看哪个用户、给谁分配角色”按 `u.area`
## 5.6 RAG 模块
### 数据集
主资源：`dataset`
| 类型 | 字段 |
| --- | --- |
| `area_field` | `dataset.area` |
| `creator_field` | `dataset.created_by` |
| `public_field` | `dataset.is_public` |
### 聊天应用
主资源：`app`
| 类型 | 字段 |
| --- | --- |
| `area_field` | `app.area` |
| `public_field` | `dataset.is_public` 或显式 `app.is_public` |
说明：
- 如果 app 的公开性来自关联 dataset，就要在 policy 层明确写清，不要分散在查询里隐式推断
## 5.7 交叉评查
主资源：任务关系，而不是单表字段。
推荐映射：
| 类型 | 字段 |
| --- | --- |
| `user_field` | `tm.user_id` |
| `creator_field` | `proposal.created_by` |
说明：
- 交叉评查以 `RELATION` 模型处理
- 这块不强制要求 `area_field`
---
## 6. Alias 统一规范
统一执行器要稳定接入，SQL alias 必须统一。
建议标准：
| 资源 | 推荐 alias |
| --- | --- |
| 文档主表 | `d` |
| 文档文件表 | `f` |
| 用户表 | `u` |
| 审查运行表 | `r` |
| 统计登录事件表 | `e` |
| 合同模板表 | `t` |
| RAG 数据集 | `dataset` |
| RAG 应用 | `app` |
| 交叉评查任务 | `task` |
| 交叉评查成员 | `tm` |
| 交叉评查提案 | `proposal` |
目的不是强迫重命名所有 SQL，而是：
- 新增或重构 SQL 时尽量统一
- `QueryScopeBuilder` 和 `ModulePolicy` 才能更容易复用
---
## 7. 参数命名规范
当前代码里已经有：
- `requested_region`
- `scope_region`
- `scope_user_id`
- `requested_user_id`
建议固化为统一标准：
| 参数 | 含义 |
| --- | --- |
| `requested_area` | 请求方传入的地区过滤 |
| `scope_area` | 当前 scope 决策后的有效地区 |
| `requested_user_id` | 请求方显式筛选的用户 |
| `scope_user_id` | scope 决策后的当前用户 ID |
| `resource_id` | 主资源 ID |
| `visible_areas` | `PUBLIC_MIXED` 或公共范围列表 |
不建议再混用：
- `query_area`
- `user_area`
- `region`
- `scope_region`
除非当前模块确实已经固定使用 `region` 作为数据库字段名，而不是参数名。
建议规则：
- 参数命名一律使用 `area`
- 数据库字段保留 `region/area` 原名
即：
```sql
COALESCE(d.region, '') = :scope_area
```
而不是：
```sql
COALESCE(d.region, '') = :scope_region
```
这样更利于统一执行器复用。
---
## 8. 标准 SQL 子句模板
## 8.1 `ALL`
无地区限制时：
```sql
1 = 1
```
带请求地区过滤时：
```sql
COALESCE({area_field}, '') = :requested_area
```
## 8.2 `DEPT`
```sql
COALESCE({area_field}, '') = :scope_area
```
并且在进入 SQL 前先做规则：
- 若 `requested_area` 非空且不等于 `scope_area`，直接拒绝或生成 `1 = 0`
## 8.3 `SELF`
```sql
{creator_field} = :scope_user_id
```
若请求还传了 `requested_user_id`：
- 与 `scope_user_id` 不相等时直接拒绝
## 8.4 `PUBLIC_MIXED`
```sql
(
COALESCE({area_field}, '') IN :visible_areas
OR {public_field} = TRUE
)
```
推荐 `visible_areas` 至少包含：
- 当前用户地区
- `省级`
- `''`
具体由 `RagPolicy` 决定。
## 8.5 `RELATION`
不建议硬编码为通用模板。
应由 `CrossReviewPolicy` 输出，例如：
```sql
EXISTS (
SELECT 1
FROM leaudit_cross_review_task_member tm
WHERE tm.task_id = task.id
AND tm.user_id = :scope_user_id
AND tm.deleted_at IS NULL
)
```
---
## 9. 主资源回溯规范
这是本轮 SQL 改造里最重要的一条。
## 9.1 什么叫主资源回溯
当接口操作的不是主资源表，而是主资源衍生物时，必须回溯到主资源做 scope 判断。
## 9.2 必须回溯的场景
### 文档状态
虽然接口直接拿文档 ID 列表查状态，但本质仍是文档资源。
必须回溯：
- `document`
- `file`
### 公文 run / report / original
不能只按：
- `run_id`
- `artifact_id`
- `document_id`
直接查。
必须回溯到：
- `govdoc document d`
- `original file f`
### RAG dataset document / segment
不能只按：
- `document_id`
- `segment_id`
直接做可见性判断。
必须回溯到：
- `dataset`
### 交叉评查 proposal export
不能只按 `DocumentId` 导出。
必须回溯到：
- 当前用户是否属于该任务关系链
---
## 10. 推荐接入方式
## 10.1 列表接口
推荐模式：
1. 构造基础查询
2. 获取 `PermissionDecision`
3. 由 `QueryScopeBuilder` 生成 `scope_clause`
4. 将 `scope_clause.sql` 注入 `WHERE`
5. 业务筛选条件作为附加条件继续追加
示意：
```python
decision = await permissionScopeFacade.require(...)
scope_clause = queryScopeBuilder.build_by_mapping(...)
where_clauses = [
"d.deleted_at IS NULL",
scope_clause.sql,
]
params = {
**scope_clause.params,
}
```
## 10.2 详情接口
推荐模式：
不要先查，再判断。
而要直接：
```sql
SELECT ...
FROM ...
WHERE id = :resource_id
AND {scope_clause.sql}
```
这样天然避免“查到了但后面忘记拒绝”的风险。
## 10.3 删除/更新接口
推荐两种方式：
### 方式 A：先用带 scope 的 SELECT 锁定资源
```sql
SELECT id
FROM ...
WHERE id = :resource_id
AND {scope_clause.sql}
FOR UPDATE
```
### 方式 B：直接带 scope 执行 UPDATE/DELETE
```sql
UPDATE ...
SET ...
WHERE id = :resource_id
AND {scope_clause.sql}
```
建议优先用方式 A，更利于错误提示和审计。
## 10.4 下载/导出接口
推荐模式：
1. 先回溯主资源并带 scope 查出合法记录
2. 再根据合法记录生成下载地址或导出文件
不允许：
1. 先按附件 ID 或 artifact ID 取到 OSS URL
2. 再事后补判断
---
## 11. 统计聚合改造规范
统计类 SQL 最容易出错，因为不是简单查明细。
## 11.1 先收 scope，再聚合
推荐：
```sql
WITH scoped_docs AS (
SELECT d.id, d.region, f.created_by
FROM ...
WHERE ...
AND {scope_clause.sql}
)
SELECT ...
FROM scoped_docs
GROUP BY ...
```
不推荐：
先全量聚合，再在外层做地区过滤。
原因：
- 易错
- 性能差
- `SELF` 范围很容易被漏掉
## 11.2 用户口径和文档口径必须拆分
不要写一个函数同时隐式支持：
- `u.area`
- `d.region`
- `e.area_snapshot`
建议明确：
- `build_user_area_scope_clause()`
- `build_document_area_scope_clause()`
- `build_login_snapshot_scope_clause()`
或者在 `UsageStatsPolicy` 内按口径分发。
---
## 12. 反模式清单
以下写法在本轮改造中应视为禁用或逐步清理对象。
## 12.1 反模式：角色名直接拼 SQL 范围
```sql
bool_or(r.role_key IN ('super_admin', 'provincial_admin'))
```
问题：
- 角色名直接耦合能力
- 新角色无法扩展
## 12.2 反模式：详情先查后判
```python
row = await session.execute(...)
if row and current_user["can_manage"]:
...
```
问题：
- 非法资源已经被读出来
- 派生接口最容易漏判
## 12.3 反模式：用 `1 = 0` 到处散落表达拒绝
`1 = 0` 可以作为最终 SQL 结果，但不应成为业务逻辑表达方式。
更推荐：
- 在决策层直接拒绝
- 或由 builder 明确返回 `denied clause`
## 12.4 反模式：同一模块 area 字段口径漂移
例如：
- 文档列表按 `u.area`
- 文档详情按 `d.region`
这种写法必须统一。
## 12.5 反模式：下载 URL 先取后判
尤其是：
- 原文下载
- 报告下载
- 导出文件
必须先判 scope，再产出 URL。
---
## 13. 索引建议
统一执行器接入后，范围过滤会更集中，需要补齐索引。
建议优先确认以下索引：
### 文档/公文
- `documents(region)`
- `document_files(created_by)`
- `document_files(document_id, created_by)`
### 用户
- `sso_users(area)`
- `sso_users(status, deleted_at, area)`
### 合同模板
- `contract_templates(region)`
- `contract_templates(created_by)`
### RAG
- `rag_datasets(area, is_public)`
- `rag_apps(area)`
### 交叉评查
- `task_member(task_id, user_id)`
- `proposal(document_id, created_by)`
说明：
- 索引不是这轮文档的主体，但如果没有，会直接影响统一执行器上线后的查询性能
---
## 14. 推荐代码组织
建议新增或统一下面这类方法：
```python
build_scope_clause_for_document(...)
build_scope_clause_for_user(...)
build_scope_clause_for_dataset(...)
resolve_primary_resource_scope(...)
```
更推荐的最终形态是：
```python
decision = await permissionDecisionService.decide(ctx)
scope_clause = modulePolicy.build_clause(ctx, decision)
```
这样业务 service 只负责：
1. 自身业务查询
2. 接入 scope 子句
3. 做结果组装
而不是自己解释权限模型。
---
## 15. 分模块改造建议
## 15.1 文档与公文
优先动作：
1. 抽出统一 `DocumentScopeMapping`
2. 统一 `d.region + f.created_by`
3. 所有详情/状态/run/report/download 统一回溯主文档
## 15.2 使用统计
优先动作：
1. 拆分用户口径和文档口径
2. 不再通过字符串替换实现 `area_snapshot`
3. 将 `SELF` 范围明确化
## 15.3 合同模板
优先动作：
1. 把“省级模板可见”收敛为 policy
2. 列表/搜索/详情共享同一范围规则
## 15.4 RBAC 用户管理
优先动作：
1. 用户列表、组织树、角色分配统一按 `u.area`
2. 角色元数据接口不强加 area scope
## 15.5 RAG
优先动作：
1. `PUBLIC_MIXED` 统一化
2. dataset 子资源全部回溯 dataset
---
## 16. 最终要求
后续所有权限改造相关 SQL，应满足以下要求：
1. 能明确说清主资源是谁
2. 能明确说清 `area_field` 和 `creator_field` 是哪个
3. 能明确说清详情/下载/导出是否回溯主资源
4. 不再依赖角色名派生范围
5. 新增接口时可以直接挂到统一执行器，而不是复制旧判断
如果做不到这 5 条，即使逻辑暂时跑通，也不算完成“统一权限架构”的 SQL 层落地。