leaudit-platform-backend/docs/老系统_docauditai_用户权限架构深度分析.md

# 老系统 `docauditai` 用户权限架构深度分析

本文档用于系统性梳理老项目：

- `/home/wren-dev/Porject/docauditai`

中的用户、认证、角色、路由、权限、地区、数据范围逻辑。

目标不是简单列表，而是明确回答：

- 老系统真实的用户权限架构是什么
- 它依赖哪些表和哪些业务规则
- 新系统应该继承什么、舍弃什么、升级什么

---

## 1. 结论先行

老系统并不是一个“只有 6 张 RBAC 表”的简单权限系统。

它真实的架构是：

- 统一登录入口：OAuth + 账密登录
- 用户主表：`sso_users`
- 角色体系：`roles + user_role`
- 菜单路由：`sys_routes + role_route`
- 权限点：`permissions + role_permissions`
- 数据权限：`role_permissions.data_scope`
- 地区隔离：大量业务依赖 `sso_users.area`
- 组织同步：登录时通过 MQ / 组织表同步 `area / tenant / dep`

也就是说，老系统本质上是：

- `RBAC + area-based data scope`

而不是纯粹的：

- `用户 - 角色 - 菜单`

---

## 2. 核心表与模块

从代码实际使用看，老系统核心不只是以下 6 张表：

- `sys_routes`
- `sso_users`
- `roles`
- `role_route`
- `role_permissions`
- `user_role`

还必须加上：

- `permissions`
- `route_permission`
- 业务表中的 `area` 字段
- `roles.data_scope`
- `role_permissions.data_scope`

相关代码位置：

- 认证：`app/routes/auth.py`
- JWT：`app/auth/auth.py`
- 路由权限：`app/rbac/route_permission.py`
- 权限检查：`app/rbac/permission_checker_v2.py`
- 数据范围：`app/rbac/data_scope_injector_v2.py`
- RBAC API：`app/routes/v3/rbac.py`

---

## 3. 登录架构

## 3.1 统一登录入口

老系统登录主入口是：

- `POST /auth/login`

代码：

- `app/routes/auth.py`

统一登录入口自动识别两种模式：

- OAuth 登录
- 账号密码登录

识别规则：

- 请求体包含 `userInfo.sub` → OAuth 登录
- 请求体包含 `username + password` → 账密登录

对应代码：

- `app/routes/auth.py:111`
- `app/routes/auth.py:154`
- `app/routes/auth.py:158`

这说明老系统在登录入口设计上已经做到了统一。

---

## 3.2 OAuth 登录逻辑

OAuth 登录处理函数：

- `app/routes/auth.py:_handle_oauth_login`

主要流程：

1. 读取前端传入的 `userInfo`
2. 通过 `sub` 查询 `sso_users`
3. 如果用户不存在，则自动创建用户
4. 如果用户已存在，则更新用户基本资料
5. 查询用户角色
6. 生成 JWT
7. 返回统一登录响应

对应代码位置：

- `app/routes/auth.py:412`
- `app/routes/auth.py:451`
- `app/routes/auth.py:518`
- `app/routes/auth.py:563`
- `app/routes/auth.py:601`
- `app/routes/auth.py:611`

### OAuth 用户创建规则

当用户不存在时：

- 自动插入 `sso_users`
- 自动分配默认角色 `common`

对应代码：

- `app/routes/auth.py:471`
- `app/routes/auth.py:512`

这意味着：

- 老系统支持 OAuth 首登自动建号
- 并且会自动授予最低默认权限

---

## 3.3 账号密码登录逻辑

密码登录处理函数：

- `app/routes/auth.py:_handle_password_login`

主要流程：

1. 根据 `username/sub` 查询 `sso_users`
2. 校验密码
3. 校验状态 / 删除标记
4. 同步组织信息（如果有）
5. 查询角色
6. 生成 JWT
7. 返回统一响应

对应代码：

- `app/routes/auth.py:655`
- `app/routes/auth.py:689`
- `app/routes/auth.py:723`
- `app/routes/auth.py:745`
- `app/routes/auth.py:756`
- `app/routes/auth.py:798`

可以看出，老系统并没有把账密登录和 OAuth 登录做成两套完全不同的人群模型。

它们最终都归并到：

- `sso_users`
- `user_role`
- `roles`
- JWT

这是一个非常重要的架构特征。

---

## 4. JWT 模型

JWT 逻辑在：

- `app/auth/auth.py`

JWT Payload 中实际携带的关键字段有：

- `user_id`
- `username`
- `user_role`
- `permissions`（可选）
- `sub`
- `nick_name`
- `email`
- `phone_number`
- `ou_id`
- `ou_name`
- `is_leader`
- `area`

对应代码：

- `app/auth/auth.py:61`
- `app/auth/auth.py:94`
- `app/auth/auth.py:101`
- `app/auth/auth.py:106`

JWT 解码后，同样会恢复成：

- `User`
- `TokenData`

对应：

- `app/auth/auth.py:24`
- `app/auth/auth.py:46`
- `app/auth/auth.py:119`
- `app/auth/auth.py:171`

### 结论

老系统 JWT 不只是认证 token，它还承担了：

- 用户身份
- 用户角色
- 用户地区
- 组织基础信息

其中 `area` 是最关键的业务字段之一。

---

## 5. 用户地区到底怎么来的

这是老系统最关键的逻辑之一。

### 5.1 不是靠前端端口

老系统的地区不是通过前端访问端口推断。

它主要通过组织主数据反查得到。

### 5.2 OAuth 登录时的地区来源

OAuth 登录会调用：

- `_get_user_org_info_from_mq`

位置：

- `app/routes/auth.py:280`

查询流程：

1. 用 `ou_id + nickname` 查询 `um_personinfo`
2. 获取：
   - `tenant_uuid`
   - `dep_uuid`
   - `org_uuid`
3. 再查：
   - `um_tenant`
   - `um_department`
4. 最终组装：
   - `area`
   - `tenant_name`
   - `dep_name`
   - `dep_short_name`
   - `ou_name`

其中 `area` 的来源是：

- `tenant_short_name`
- 或 `tenant_name`

对应代码：

- `app/routes/auth.py:206`
- `app/routes/auth.py:263`
- `app/routes/auth.py:280`
- `app/routes/auth.py:380`
- `app/routes/auth.py:435`

### 5.3 用户首次创建时

新用户创建时，组织信息会直接写入 `sso_users`：

- `area`
- `tenant_name`
- `dep_name`
- `dep_short_name`
- `ou_name`

对应：

- `app/routes/auth.py:471`
- `app/routes/auth.py:480`
- `app/routes/auth.py:512`

### 5.4 老用户每次登录时

如果用户已存在，每次 OAuth 登录仍会同步这些字段：

- `area`
- `tenant_name`
- `dep_name`
- `dep_short_name`
- `ou_name`

对应：

- `app/routes/auth.py:518`
- `app/routes/auth.py:543`
- `app/routes/auth.py:552`
- `app/routes/auth.py:593`

### 结论

老系统对地区的真实定义是：

- 地区是组织主数据的一部分
- 地区由后端通过 MQ/组织系统同步
- 登录时会把地区同步进 `sso_users.area`
- 之后大量业务依赖这个 `area`

这说明：

- 老系统是“后端主数据决定地区”
- 不是“前端端口决定地区”

---

## 6. 用户主表 `sso_users` 的真实角色

从代码实际用法来看，`sso_users` 不只是登录表。

它承担了：

- 统一身份映射表
- 用户基础档案表
- 地区信息存储表
- 组织信息缓存表
- 登录失败次数 / 锁定状态记录表

常见使用字段：

- `id`
- `sub`
- `username`
- `nick_name`
- `phone_number`
- `email`
- `ou_id`
- `ou_name`
- `is_leader`
- `status`
- `deleted_at`
- `password`
- `try_count`
- `try_login_time`
- `area`
- `tenant_name`
- `dep_name`
- `dep_short_name`

对应代码位置：

- `app/routes/auth.py:451`
- `app/routes/auth.py:689`
- `app/routes/auth.py:914`

### 结论

老系统把 `sso_users` 作为了：

- 用户唯一主表
- 认证与组织信息的汇聚中心

这一点新系统应该继承。

---

## 7. 角色体系是什么

角色相关表：

- `roles`
- `user_role`

### 7.1 用户和角色关系

一个用户可以拥有多个角色。

角色查询通常通过：

- `user_role -> roles`

对应代码：

- `app/routes/auth.py:840`
- `app/routes/auth.py:852`
- `app/routes/auth.py:862`

### 7.2 OAuth 新用户默认角色

新用户默认自动分配：

- `common`

对应代码：

- `app/routes/auth.py:512`

### 7.3 角色本身带数据范围

老系统 `roles` 表本身带：

- `data_scope`

在 RBAC API 中大量出现：

- `RoleService.list_roles`
- `RoleService.get_role`

对应代码：

- `app/services/rbac/role_service.py:98`
- `app/services/rbac/role_service.py:171`
- `app/services/rbac/user_role_service.py:217`

### 结论

老系统角色不只是页面访问角色，它还是：

- 权限角色
- 数据范围角色

也就是说：

- 一个角色同时决定功能权限和数据权限

---

## 8. 菜单 / 路由权限模型

### 8.1 路由表和角色路由表

老系统页面菜单权限主要基于：

- `sys_routes`
- `role_route`

主逻辑在：

- `app/rbac/route_permission.py`

### 8.2 `get_user_routes(user_id)` 的真实行为

流程：

1. 查用户所有角色
2. 用角色查 `role_route`
3. join `sys_routes`
4. 只返回启用路由
5. 组装成树形结构
6. 还会把该路由相关的权限点附在 `permissions` 字段里

对应：

- `app/rbac/route_permission.py:22`
- `app/rbac/route_permission.py:47`
- `app/rbac/route_permission.py:63`
- `app/rbac/route_permission.py:100`
- `app/rbac/route_permission.py:127`

### 8.3 路由不仅是菜单，还带权限上下文

老系统会在返回路由树时，把页面对应的权限点也挂上去。

这意味着前端不是只拿“菜单”，而是拿：

- 菜单结构
- 页面权限上下文

这是很成熟的一种设计。

---

## 9. 功能权限模型

### 9.1 老系统不是只有 `role_permissions`

真正的功能权限核心是：

- `permissions`
- `role_permissions`

其中：

- `permissions`：权限定义表
- `role_permissions`：角色授权表

### 9.2 权限检查器 V2

代码：

- `app/rbac/permission_checker_v2.py`

它的逻辑是：

1. 查用户所有角色
2. 通过 `role_permissions` 找到权限
3. join `permissions`
4. 读 `permission_key`
5. 支持：
   - 精确匹配
   - 通配符权限
   - `GRANT`
   - `DENY`

对应：

- `app/rbac/permission_checker_v2.py:61`
- `app/rbac/permission_checker_v2.py:147`
- `app/rbac/permission_checker_v2.py:199`

### 9.3 权限键格式

权限键采用：

- `module:resource:action`

例如：

- `document:list:read`
- `document:delete:delete`
- `dify:dataset:read`
- `system:rbac:manage`

这套结构非常清晰，推荐新系统继续保留。

### 结论

老系统功能权限的真实设计是：

- `permissions.permission_key` 做标准权限定义
- `role_permissions` 决定角色拥有哪些权限
- 路由权限只是页面层，不能替代 `permissions`

---

## 10. 数据权限模型

这是老系统最关键但最容易被忽略的一层。

### 10.1 数据权限来源

数据权限核心在：

- `role_permissions.data_scope`
- `roles.data_scope`
- 用户 `area`

### 10.2 数据范围注入器

代码：

- `app/rbac/data_scope_injector_v2.py`

定义了三种数据范围：

- `ALL`
- `DEPT`
- `SELF`

对应：

- `app/rbac/data_scope_injector_v2.py:24`

### 10.3 三种范围含义

#### `ALL`

- 查看全部数据
- 不加过滤条件

#### `DEPT`

- 查看本地区数据
- 实现方式是：按 `area` 过滤

#### `SELF`

- 只能查看本人数据
- 实现方式是：按 `user_id` 过滤

对应：

- `app/rbac/data_scope_injector_v2.py:170`
- `app/rbac/data_scope_injector_v2.py:228`

### 10.4 本地区的真实含义

老系统里 `DEPT` 虽然名称叫部门范围，但实际很多地方是：

- 按地区 `area` 过滤

也就是说：

- 它更像“本地市范围”
- 而不是严格的部门树范围

这说明老系统的数据权限其实是：

- `ALL / 地区 / 本人`

而不是严格组织树。

---

## 11. `area` 在老系统中的真实地位

### 11.1 `area` 是核心业务字段

老系统中，`area` 被用于：

- 用户归属地区
- 数据权限过滤条件
- 业务记录写入默认地区
- Dify 知识库选择
- Dify 对话应用过滤
- 评查点地区隔离

### 11.2 Dify 知识库访问

代码：

- `app/routes/v3/dify_area_dataset.py`

逻辑：

- 普通用户：按 `current_user.area` 查本地区知识库
- 省级管理员：可看全部

对应：

- `app/routes/v3/dify_area_dataset.py:39`
- `app/routes/v3/dify_area_dataset.py:57`
- `app/routes/v3/dify_area_dataset.py:67`

### 11.3 Dify 对话应用过滤

代码：

- `app/routes/v3/dify_chat_apps.py`

逻辑：

- 根据 `current_user.area` 返回本地区应用
- 同时可以返回省级应用

对应：

- `app/routes/v3/dify_chat_apps.py:29`
- `app/routes/v3/dify_chat_apps.py:60`

### 11.4 PostgREST 转发层的 area 注入

代码：

- `app/exceptions/global_exc.py`

老系统在某些写操作中，甚至会自动把用户 `area` 写进业务数据。

典型例子：

- `evaluation_points` 表写入时自动填充 `area`

并且：

- `provincial_admin` 会被硬编码成 `省级`

对应代码：

- `app/exceptions/global_exc.py:250`
- `app/exceptions/global_exc.py:292`
- `app/exceptions/global_exc.py:307`

### 结论

在老系统中：

- `area` 不是附属字段
- 而是整套业务隔离体系的核心字段之一

---

## 12. 中间件与鉴权行为

### 12.1 JWT 中间件

代码：

- `app/middleware/jwt_auth.py`

行为：

- 白名单路径跳过
- 其他请求必须有 Bearer Token
- 中间件先做基础校验
- 然后将当前用户信息塞进：
  - `request.state.current_user`

塞入字段包括：

- `user_id`
- `username`
- `nick_name`
- `email`
- `phone_number`
- `ou_id`
- `ou_name`
- `is_leader`
- `user_role`
- `area`

对应：

- `app/middleware/jwt_auth.py:49`
- `app/middleware/jwt_auth.py:75`
- `app/middleware/jwt_auth.py:88`
- `app/middleware/jwt_auth.py:89`

### 12.2 路由层再做细粒度权限校验

真正功能权限由：

- `require_permission_v2`

处理，位置：

- `app/rbac/decorators_v2.py`

它会：

- 从 `request.state.current_user` 取 `user_id`
- 调 `PermissionCheckerV2.check_permission`
- 无权限则 403

对应：

- `app/rbac/decorators_v2.py:56`
- `app/rbac/decorators_v2.py:92`

### 结论

老系统是两层鉴权：

- 中间件：验 token
- 装饰器/依赖：验功能权限

这个分层设计是合理的。

---

## 13. 老系统角色体系的实际业务语义

根据代码表现，老系统大致存在以下角色层次：

- `provincial_admin`
- `admin`
- `common`
- 以及其他业务角色

### 13.1 `provincial_admin`

特点：

- 高权限角色
- 数据范围通常为 `ALL`
- 某些业务场景会被特殊处理为“省级”
- 可访问全部地区的数据 / 配置

体现位置：

- `app/exceptions/global_exc.py:292`
- `app/routes/v3/dify_area_dataset.py:67`

### 13.2 `admin`

特点：

- 更像市级管理员
- 数据范围通常为本地区
- 很多场景按 `area` 做限制

体现位置：

- `app/services/rbac/user_role_service.py:91`
- `app/exceptions/global_exc.py:229`

### 13.3 `common`

特点：

- 默认普通用户
- 新用户自动分配
- 权限最低
- 数据范围通常为 `SELF` 或较弱的本地区权限

体现位置：

- `app/routes/auth.py:512`
- `app/routes/auth.py:601`

---

## 14. 老系统真实的架构图

如果按实际行为抽象，老系统可以概括为：

### 14.1 用户身份层

- `sso_users`
- `sub`
- OAuth / 本地账密登录

### 14.2 角色层

- `roles`
- `user_role`

### 14.3 页面菜单层

- `sys_routes`
- `role_route`

### 14.4 功能权限层

- `permissions`
- `role_permissions`
- `permission_key`
- `grant_type`

### 14.5 数据权限层

- `role_permissions.data_scope`
- `roles.data_scope`
- 用户 `area`
- 业务表 `area`

### 14.6 组织归属层

- `ou_id`
- `ou_name`
- `tenant_name`
- `dep_name`
- `dep_short_name`
- 通过 MQ / 组织表同步

### 结论

老系统不是简单 RBAC，而是：

- `RBAC + 地区数据隔离 + 组织同步`

---

## 15. 老系统优点

### 15.1 登录入口统一

OAuth 和账密最终走同一条认证主链。

### 15.2 用户主数据集中

所有用户最终都汇总到：

- `sso_users`

### 15.3 路由权限设计成熟

- `sys_routes + role_route`
- 支持树形菜单
- 支持隐藏路由
- 支持角色路由缓存

### 15.4 功能权限设计成熟

- `permissions`
- `role_permissions`
- `grant / deny`
- 通配符匹配

### 15.5 数据范围是正式模型，不是临时过滤

虽然比较粗糙，但已经有：

- `ALL`
- `DEPT`
- `SELF`

### 15.6 地区来自后端主数据

老系统地区来源比“前端端口推断”可靠得多。

---

## 16. 老系统缺点

### 16.1 `area` 过载过重

`area` 同时承担：

- 用户地区
- 数据权限过滤条件
- 业务默认地区
- 规则隔离条件
- 知识库分配条件

语义过重。

### 16.2 数据范围表达力不足

只有三档：

- `ALL`
- `DEPT`
- `SELF`

无法优雅表达：

- 多地区访问
- 指定地区集合
- 复杂跨区权限

### 16.3 大量业务写死 `area` 逻辑

导致：

- 架构耦合重
- 后续改动成本高
- 组织逻辑与业务逻辑混杂

### 16.4 存在角色硬编码

例如：

- `provincial_admin -> 省级`

这类逻辑写死在业务层，不够优雅。

### 16.5 `DEPT` 实际上更像地区范围，不是部门范围

命名容易误导。

---

## 17. 对新系统的启示

## 17.1 必须继承的部分

新系统应继承老系统的这些优点：

- 统一登录入口
- OAuth / 账密统一落主用户表
- `sys_routes + role_route`
- `permissions + role_permissions`
- 标准 `permission_key`
- `grant / deny`
- 数据范围模型概念
- 组织同步决定地区

## 17.2 必须升级的部分

新系统不能原样照搬老系统的缺点。

必须升级为：

- 不再只有一个 `area` 字段承载所有数据权限语义
- 把用户默认地区和可访问地区分开
- 把数据权限从 `DEPT` 升级为正式 `region scope`
- 把组织同步保留，但不要在各业务层到处散写地区逻辑

---

## 18. 新系统设计应如何继承老系统

从老系统出发，新系统最合理的方向不是推翻，而是升级：

### 18.1 保留骨架

- `sso_users`
- `roles`
- `user_role`
- `sys_routes`
- `role_route`
- `permissions`
- `role_permissions`

### 18.2 替换数据权限实现

将老系统：

- `ALL / DEPT / SELF`

升级为：

- `ALL`
- `SELF`
- `HOME_REGION`
- `CUSTOM_REGIONS`
- `PROVINCIAL`

### 18.3 组织同步仍保留

地区来源仍然应该以后端组织主数据为准，而不是前端推断。

### 18.4 将 `area` 升级为正式 `region_code`

业务表中的地区字段建议统一收口成稳定 code，而不是直接到处使用中文字符串。

---

## 19. 一句话总结

老系统 `docauditai` 的真实用户权限架构不是“6 张表的简单角色系统”，而是：

- 以 `sso_users` 为用户主数据中心
- 通过 OAuth / 账密统一登录
- 通过组织系统同步 `area / tenant / dep`
- 用 `roles + user_role + sys_routes + role_route + permissions + role_permissions`
  管功能权限
- 用 `data_scope + area`
  管数据权限

本质是：

- `RBAC + 地区数据权限 + 组织同步`

这就是新系统设计时真正应该继承的老逻辑骨架。