TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
leaudit-platform-backend/docs/权限与地区隔离/角色硬编码与接口影响专项补充分析.md
T

15 KiB
Raw Permalink Blame History

角色硬编码与接口影响专项补充分析

适用范围：leaudit-platform 当前角色权限与地区隔离体系
文档定位：从主方案中拆出的专项补充稿，专门分析“硬编码角色如何改”和“哪些接口会被联动影响”。

1. 结论先行

当前项目里的角色硬编码不是零散问题，而是已经渗透到：

  • 后端服务层能力派生
  • 后端服务层动作放行
  • 前端 UI 可见性和可编辑性
  • 前端 guard、fallback、role mapping

因此，这类改造不能只改某一个 service，也不能只改权限表配置。

如果只改一部分，会出现 3 类典型问题：

  1. 后端 permission 已放行，但服务层仍按角色名拒绝
  2. 后端边界已收敛，但前端仍按旧角色逻辑展示按钮或入口
  3. 菜单、页面、接口、详情、下载这些边界继续不一致

正确做法是：

  1. 先识别所有硬编码角色位置
  2. 再区分它们的职责类型
  3. 最后按“能力抽象 -> 服务层替换 -> 前端去角色化”的顺序渐进改造

2. 当前硬编码角色的 4 种形态

2.1 服务层上下文派生型

这类代码并不直接判断某个 permission，而是把角色名先转成派生能力：

  • is_global
  • can_manage
  • is_super_admin
  • is_area_admin
  • bypass_area

典型位置：

  • documentServiceImpl.py
  • govdocServiceImpl.py
  • usageStatsServiceImpl.py
  • contractTemplateServiceImpl.py
  • rbacAdminServiceImpl.py
  • homeServiceImpl.py

典型模式：

  • role_key IN ('super_admin', 'provincial_admin') => is_global
  • role_key IN ('super_admin', 'provincial_admin', 'admin') => can_manage
  • role_key = 'super_admin' => is_super_admin / bypass_area

本质问题：

  • 角色名被直接当成能力模型
  • 一旦出现新领域管理员，所有上下文派生逻辑都要重复改

2.2 服务层动作白名单型

这类代码直接按角色名决定某个业务动作是否允许。

典型位置：

  • ragDatasetServiceImpl.py
  • ragChatServiceImpl.py

典型模式：

  • UserRole not in ("provincial_admin", "admin", "super_admin")
  • user_role == "provincial_admin"
  • UserRole == "admin"

本质问题：

  • 控制器层已经做 permission 校验
  • 服务层又加了角色白名单
  • 结果会出现“有权限但角色名不对仍被拒绝”

这是当前最需要优先清理的硬编码类型。

2.3 前端 UI 能力硬编码型

这类代码不是后端鉴权，但会直接影响用户感知边界。

典型位置：

  • components/dify-dataset-manager/index.tsx
  • components/dify-dataset-manager/area-dataset-config.tsx
  • hooks/use-area-dataset-config.ts

典型模式：

  • provincial_admin 可编辑全部
  • super_admin 可编辑全部
  • admin 仅可编辑本地区

本质问题：

  • 前端自己在解释“谁能管理”
  • 即使后端以后完成去角色化，前端仍可能展示旧权限状态

2.4 前端兼容层硬编码型

这类代码主要存在于路由、guard 和迁移兼容层。

典型位置：

  • legal-platform-frontend/lib/auth/user-routes.ts
  • legal-platform-frontend/lib/api/legacy/auth/user-routes.ts
  • legal-platform-frontend/lib/auth/guard.ts
  • legal-platform-frontend/lib/auth/cross-checking-access.ts

典型模式：

  • provincial_admin -> admin
  • super_admin -> admin
  • developer -> admin
  • provincial_admin 自动获得“省局 area”候选

本质问题：

  • 前端把真实角色体系压缩成少数桶位
  • 继续保留会让权限模型越来越难以统一

3. 为什么不能直接删掉所有角色硬编码

不是所有角色硬编码都应该同一天删除，因为它们承担职责不同。

3.1 可优先替换的

优先替换：

  • 服务层动作白名单
  • RAG 管理动作角色白名单

原因：

  • 这些逻辑已经和 permission 决策重复
  • 删除后收益最大，副作用相对可控

3.2 需要先抽象再替换的

需要先抽象：

  • is_global
  • can_manage
  • is_super_admin
  • is_area_admin

原因：

  • 它们已经被多个模块用于拼接 SQL 过滤条件
  • 直接删会导致大量数据边界逻辑断裂

正确做法：

  • 先统一沉淀为能力派生层
  • 再逐步把“角色名判断”替换为“能力决策”

3.3 可以保留为兼容层但必须收缩边界的

允许短期保留：

  • route fallback
  • role mapping
  • 某些旧前端 guard

但必须满足：

  1. 只存在于适配层
  2. 不再扩散到新业务代码
  3. 后续有明确移除计划

4. 推荐的替换目标

当前很多角色语义，其实应该改写成能力语义。

建议的替换关系如下：

  • super_admin 全局绕过 替换为：is_super_admin
  • provincial_admin => 全省可见 替换为：effective_scope == ALL
  • admin => 本地区管理 替换为：effective_scope == DEPT + domain manage permission
  • common => 自己的数据 替换为：effective_scope == SELF
  • provincial_admin/admin/super_admin 共用白名单 替换为：显式 create/update/delete/manage permission

这一步的本质，是把“角色名”换成“能力决策”。

5. 建议新增的统一能力层

建议新增统一能力派生对象，例如：

  • is_super_admin
  • has_global_scope
  • has_area_scope
  • can_manage_rbac
  • can_manage_rag_dataset
  • can_manage_contract_templates
  • can_view_usage_stats
  • can_bypass_home_area

这些能力不应直接写死在角色名上，而应由以下信息共同决策：

  • roles
  • permissions
  • data_scope
  • 可选 condition_filter

建议新增两层统一能力：

  1. ScopeContextProvider
  2. AdminCapabilityResolver

前者负责“当前用户的通用数据边界”，后者负责“某个业务域是否具备管理能力”。

6. 当前高风险冲突区

6.1 RAG 是最典型的双轨冲突区

当前链路是：

  1. 控制器层按 permission 校验
  2. 服务层又按 UserRole 白名单校验
  3. 最终管理能力同时受 permission 和角色名双重控制

风险：

  • 未来新增 rag_manager 这类角色时，即使给了 rag:dataset:manage/create/update/delete，服务层仍会拒绝

优先级：

  • 最高

6.2 RBAC 管理域存在“角色管理能力”和“权限管理能力”双重耦合

当前链路是：

  1. _assertManagePermission 依赖 can_manage
  2. _assertPermission 再校验具体权限点

风险：

  • 如果未来某用户拥有 rbac:* 权限，但主角色不是 admin/provincial_admin/super_admin，仍可能被挡在第一层

优先级：

  • 高

6.3 文档 / 公文 / 统计存在共性上下文派生复制

这些模块并没有直接角色白名单放行，但都重复实现了：

  • is_global
  • can_manage
  • is_super_admin

风险：

  • 改一个模块不改另一个，边界会漂移

优先级：

  • 高

6.4 前端知识库管理仍在自行解释角色

风险：

  • 后端已经 permission 化后，前端仍会显示不该显示的按钮
  • 或相反，后端已允许，前端仍不展示入口

优先级：

  • 高

7. 受影响接口分析

下面重点回答“其他接口会不会影响到”。

答案是：会，而且影响面不小。

7.1 文档模块

受影响接口包括：

  • POST /api/upload
  • GET /api/documents/list
  • GET /api/documents/status
  • GET /api/documents/{DocumentId}
  • GET /api/v3/review-points/{DocumentId}
  • PATCH /api/v3/review-points/{ReviewPointResultId}/audit
  • PATCH /api/v3/documents/{DocumentId}/confirm
  • POST /api/documents/{DocumentId}/attachments
  • PUT /api/documents/{DocumentId}
  • DELETE /api/documents/{DocumentId}

影响原因：

  • 这些接口都依赖文档服务里的用户上下文派生和数据范围过滤
  • 一旦 is_global/can_manage 的计算逻辑变化，全部都会联动

7.2 公文模块

受影响接口包括：

  • POST /api/govdoc/documents
  • GET /api/govdoc/documents
  • GET /api/govdoc/documents/{documentId}
  • PATCH /api/govdoc/documents/{documentId}
  • DELETE /api/govdoc/documents/{documentId}
  • POST /api/govdoc/runs
  • GET /api/govdoc/runs/{runId}
  • GET /api/govdoc/runs/{runId}/result
  • GET /api/govdoc/runs/{runId}/findings
  • GET /api/govdoc/runs/{runId}/entities
  • GET /api/govdoc/runs/{runId}/structure
  • GET /api/govdoc/runs/{runId}/outline
  • GET /api/govdoc/runs/{runId}/paragraphs
  • GET /api/govdoc/runs/{runId}/report/html
  • GET /api/govdoc/runs/{runId}/report/docx
  • GET /api/govdoc/documents/{documentId}/original

影响原因：

  • 公文模块也使用了同构的上下文派生
  • 尤其结果、报告、下载类接口最容易出现“资源详情边界未同步”的问题

7.3 统计模块

受影响接口包括：

  • GET /api/v3/usage-stats/overview
  • GET /api/v3/usage-stats/trends
  • GET /api/v3/usage-stats/by-users
  • GET /api/v3/usage-stats/by-departments
  • GET /api/v3/usage-stats/by-areas
  • GET /api/v3/usage-stats/details

影响原因：

  • 当前统计接口对管理员可见性有明显上下文派生依赖
  • 去角色化后，这些接口需要统一切到“统计域 permission + scope”模型

7.4 RAG 模块

受影响接口包括：

  • GET /api/v3/rag/apps
  • GET /api/v3/rag/apps/default
  • GET /api/v3/rag/datasets/my
  • GET /api/v3/rag/datasets/admin
  • POST /api/v3/rag/datasets/admin
  • PUT /api/v3/rag/datasets/admin/{DatasetId}
  • DELETE /api/v3/rag/datasets/admin/{DatasetId}
  • GET /api/v3/rag/datasets/{DatasetId}
  • PATCH /api/v3/rag/datasets/{DatasetId}
  • 各类 /datasets/{DatasetId}/documents
  • 各类 /datasets/{DatasetId}/segments
  • 各类检索测试接口
  • POST /api/v3/rag/chat/messages
  • 会话、消息反馈、会话重命名、删除等接口

影响原因：

  • 控制器层和服务层当前存在双轨权限逻辑
  • 这是最典型的“permission 改了，接口仍会被角色名卡住”的模块

7.5 RBAC 管理模块

受影响接口包括：

  • GET /api/v3/rbac/roles
  • POST /api/v3/rbac/roles
  • PUT /api/v3/rbac/roles/{RoleId}
  • DELETE /api/v3/rbac/roles/{RoleId}
  • GET /api/v3/rbac/users
  • GET /api/admin/users/organizations/tree
  • GET /api/v3/rbac/roles/{RoleId}/users
  • POST /api/v3/rbac/users/{UserId}/roles
  • DELETE /api/v3/rbac/users/{UserId}/roles/{RoleId}
  • GET /api/v3/rbac/users/{UserId}/roles
  • GET /api/v3/routes
  • GET/PUT /api/rbac/roles/{RoleId}/routes
  • GET/POST /api/v3/rbac/role-permissions
  • POST /api/v3/rbac/roles/{RoleId}/access
  • GET /api/v3/routes/{RouteId}/permissions

影响原因：

  • 当前同时依赖 _assertManagePermission 和 _assertPermission
  • 第一层还是角色派生管理能力

7.6 首页入口模块

受影响接口：

  • GET /api/home/entry-modules

影响原因：

  • 当前首页入口存在 super_admin 的 area bypass 语义
  • 这类入口可见性也属于权限边界的一部分

7.7 合同模板模块

受影响接口包括：

  • GET /api/v3/contract-templates/categories
  • GET /api/v3/contract-templates
  • POST /api/v3/contract-templates
  • GET /api/v3/contract-templates/search
  • GET /api/v3/contract-templates/{TemplateId}
  • DELETE /api/v3/contract-templates/{TemplateId}

影响原因：

  • 当前业务语义明确写着“地区管理员才能上传”
  • 如果只去角色化、不补合同模板域显式权限，这类能力会失焦

7.8 中影响模块

中影响但必须纳入联调范围的还有：

  • 交叉评查模块
  • 评查点模块
  • 评查点分组模块
  • 规则配置模块

原因：

  • 它们虽然不一定都直接依赖角色名白名单
  • 但仍依赖 permission、route、入口和关系访问逻辑
  • 一旦整体权限能力模型调整，也必须回归验证

8. 前端联动影响

不能只看后端接口，前端也会同步受影响。

8.1 菜单与路由

受影响位置：

  • Sidebar.tsx
  • user-routes.ts
  • check-route-permission.ts
  • fallback route mapping

风险：

  • 菜单可见性与真实接口权限继续分叉
  • 某些角色被映射压扁后，真实权限无法完整反映

8.2 RAG 管理页面

受影响位置：

  • components/dify-dataset-manager/*
  • hooks/use-area-dataset-config.ts

风险：

  • 后端能力已收敛，前端仍按旧角色名展示编辑入口

8.3 页面 guard

受影响位置：

  • lib/auth/guard.ts
  • lib/auth/cross-checking-access.ts
  • lib/auth/session-user.ts
  • lib/auth/jwt.ts

风险：

  • user_role 被继续当成完整权限模型使用

9. 推荐改造顺序

建议按下面顺序推进，避免同时炸开所有联动面。

9.1 第一阶段

先做平台能力层：

  • PermissionDecisionService
  • ScopeContextProvider
  • AdminCapabilityResolver

目标：

  • 不先改业务接口行为，只先统一决策能力

9.2 第二阶段

优先改 RAG：

  • 清理服务层角色白名单
  • 改为 permission + scope/policy 决策

原因：

  • 这是最典型、收益也最大的双轨冲突区

9.3 第三阶段

接入共用上下文模块：

  • 文档
  • 公文
  • 统计

原因：

  • 它们共享大量上下文派生逻辑
  • 最适合沉淀统一 QueryScopeBuilder

9.4 第四阶段

处理管理域：

  • RBAC 管理
  • 首页入口
  • 合同模板

目标：

  • 把“管理能力”从角色名迁移到领域 permission

9.5 第五阶段

清理前端角色解释层：

  • role mapping
  • fallback route
  • guard
  • UI 编辑能力判断

目标：

  • 前端不再自行解释“谁是管理员”

10. 必做回归清单

建议单独维护一份“角色去硬编码回归清单”，至少覆盖：

  1. 用户拥有 permission，但主角色不是 admin/provincial_admin 时，接口是否仍能正确访问
  2. 用户获得某领域管理权限后，是否无需改代码即可生效
  3. 菜单、按钮、接口、详情、下载、导出边界是否一致
  4. 前端是否仍存在基于 user_role 的旧判断放大或缩小能力
  5. RAG 管理接口是否已完全摆脱角色白名单
  6. RBAC 管理接口是否已从“角色管理能力”切换到“权限管理能力”
  7. 文档、公文、统计是否仍存在模块间边界不一致

11. 最终建议

这次专项分析的核心结论只有一句话：

角色硬编码改造，本质上不是“替换几个 if”，而是把整套权限系统从“角色名驱动”升级为“能力决策驱动”。

如果只做局部替换，问题会更隐蔽。

如果按下面顺序推进，风险最低：

  1. 先抽象能力层
  2. 先处理 RAG 双轨冲突
  3. 再统一文档/公文/统计上下文派生
  4. 再处理 RBAC 管理域和首页入口
  5. 最后清理前端角色解释和 fallback

这样改完之后，项目才能真正从：

  • “角色名决定能力”

走向：

  • “权限点 + 数据范围 + 模块 policy 决定能力”

这才是后续权限平台可持续演进的正确方向。

Reference in New Issue View Git Blame Copy Permalink