# 当前系统权限模型收口方案

## 1. 当前角色与地区范围

### 1.1 角色定义

- `common`: 普通用户，仅用于查看和使用。
- `admin`: 市级管理员，只应管理本地区资源。
- `provincial_admin`: 省级管理员，可管理全省资源。
- `super_admin`: 超级管理员，可管理全部资源。

### 1.2 知识库查看范围

当前后端 `RAG` 知识库查看逻辑：

- `provincial_admin` / `super_admin`
  - 可查看全部启用中的知识库。
- 其他角色
  - 可查看 `自己地区 + 省级 + 空地区 + 公共知识库`。

对应业务含义：

- 梅州用户只能看到梅州、`省级`、空地区和公共知识库。
- 潮州用户只能看到潮州、`省级`、空地区和公共知识库。
- 省级管理员可看到全部地区知识库。

## 2. 当前真实生效矩阵

| 角色 | 查看知识库 | 创建知识库 | 编辑知识库 | 删除知识库 | 上传/重处理文档 | 编辑分段 | 聊天 | 消息反馈 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `common` | 仅限可见范围 | 否 | 否 | 否 | 否 | 否 | 取决于 `rag:chat:use` | 取决于 `rag:message:feedback` |
| `admin` | 本地区 + 省级 + 空地区 + 公共 | 是，但仅本地区 | 是，但仅本地区 | 是，但仅本地区且非默认库 | 是，但仅本地区 | 是，但仅本地区 | 取决于权限键 | 取决于权限键 |
| `provincial_admin` | 全部 | 是 | 是 | 是，但默认库不可直接删 | 是 | 是 | 取决于权限键 | 取决于权限键 |
| `super_admin` | 全部 | 是 | 是 | 是，但默认库不可直接删 | 是 | 是 | 取决于权限键 | 取决于权限键 |

## 3. 现状问题

### 3.1 前后端权限键不统一

历史上前端混用了 `dify:*` 和 `rag:*`，后端主要检查 `rag:*`，导致：

- 前端按钮可见性与后端接口放行口径不一致。
- 管理页可能“看得到但提交失败”，或者“前端隐藏了但后端其实能改”。

### 3.2 前端存在硬编码放行

旧逻辑存在两类兜底：

- `admin / provincial_admin / super_admin` 角色直接视为全部有权限。
- 所有 `:read` 权限默认放行。

这会绕过数据库中的精细化 `GRANT / DENY` 配置。

### 3.3 `admin` 只在前端限制地区，后端未强校验

旧逻辑里市级管理员在界面上只能点自己地区，但后端没有统一限制，存在跨地区管理风险。

## 4. 本次收口目标

### 4.1 知识库统一使用 RAG 权限键

知识库管理统一采用以下权限键：

- `rag:dataset:read`: 查看知识库与文档
- `rag:dataset:manage`: 查看知识库配置管理页
- `rag:dataset:create`: 创建知识库
- `rag:dataset:update`: 更新知识库、设置、文档、分段
- `rag:dataset:delete`: 删除知识库、文档、分段

### 4.2 前端权限判断原则

前端只允许以下来源决定权限：

- 当前路由的 `permissionMap`
- 登录态携带的 `globalPermissions`

明确移除：

- 角色直接等于全权限
- `:read` 默认放行

### 4.3 后端地区校验原则

后端 service 层强制执行：

- `admin` 只能管理自己地区知识库
- `provincial_admin` / `super_admin` 可跨地区管理
- `common` 不能执行知识库管理操作

## 5. 前后端分工

### 5.1 前端负责

- 按真实权限控制菜单、页签、按钮显隐
- 对无权限操作给出提示
- 不再使用角色硬编码做兜底

### 5.2 后端负责

- 接口最终鉴权
- 地区范围最终鉴权
- 默认知识库不可直接删除等业务规则校验

## 6. 迁移建议

### 6.1 角色授权建议

建议角色权限配置如下：

- `common`
  - `rag:dataset:read`
  - `rag:app:read`
  - `rag:chat:use`
  - `rag:conversation:read`
  - `rag:message:feedback`
- `admin`
  - 在 `common` 基础上增加：
  - `rag:dataset:manage`
  - `rag:dataset:create`
  - `rag:dataset:update`
  - `rag:dataset:delete`
- `provincial_admin`
  - 同 `admin`，但地区范围为全省
- `super_admin`
  - 同 `provincial_admin`

### 6.2 数据配置建议

除代码收口外，还需要同步确认：

- 角色是否已经实际分配 `rag:dataset:manage/create/update/delete`
- `/chat-with-llm` 路由是否已配置给需要访问知识库管理的人群
- 旧 `dify:*` 权限是否仍在数据库中使用，若有则需制定清理计划

## 7. 文档落点

本方案文档固定存放于：

- `docs/RAG/当前系统权限模型收口方案.md`