wren
521 lines
11 KiB
Markdown
521 lines
11 KiB
Markdown
# 权限改造实施任务拆解与排期
|
||
|
||
> 适用范围：权限统一改造项目实施阶段
|
||
> 文档定位：把权限方案拆成可执行、可排期、可协作、可验收的阶段任务。
|
||
|
||
---
|
||
|
||
## 1. 项目目标
|
||
|
||
本轮改造的项目目标不是“再补几个权限判断”，而是完成下面 5 件事：
|
||
|
||
1. 建立统一数据范围执行器
|
||
2. 清理后端服务层角色硬编码，尤其是 RAG 双轨冲突
|
||
3. 将文档、公文、统计、合同模板、RBAC 管理域纳入统一 scope 决策
|
||
4. 将前端菜单、按钮、guard 从“认角色”迁移到“认权限/能力”
|
||
5. 建立完整回归矩阵，确保详情、下载、导出不再越权
|
||
|
||
---
|
||
|
||
## 2. 实施原则
|
||
|
||
## 2.1 不推翻重做
|
||
|
||
保留现有：
|
||
|
||
- `roles`
|
||
- `permissions`
|
||
- `role_permissions`
|
||
- `sys_routes`
|
||
- `role_route`
|
||
- `sso_users.area`
|
||
|
||
本轮主做执行层、接入层、迁移层。
|
||
|
||
## 2.2 先能力层，后业务层
|
||
|
||
顺序必须是：
|
||
|
||
1. 统一决策能力
|
||
2. 模块接入
|
||
3. 前端去角色化
|
||
4. 回收 fallback
|
||
|
||
不能一边没有统一执行器，一边直接改所有业务。
|
||
|
||
## 2.3 先高风险模块
|
||
|
||
优先级顺序：
|
||
|
||
1. RAG
|
||
2. 文档、公文、统计
|
||
3. RBAC 管理域、合同模板、首页
|
||
4. 前端兼容层收口
|
||
|
||
---
|
||
|
||
## 3. 阶段总览
|
||
|
||
建议分 5 个 Phase。
|
||
|
||
| Phase | 名称 | 目标 | 建议周期 |
|
||
| --- | --- | --- | --- |
|
||
| `P1` | 能力层建设 | 建统一执行器与权限决策能力 | 1 周 |
|
||
| `P2` | RAG 双轨治理 | 清理 controller/service 双轨与角色白名单 | 1 周 |
|
||
| `P3` | 文档、公文、统计接入 | 核心数据模块统一 scope 化 | 1.5 周 |
|
||
| `P4` | RBAC、合同模板、首页接入 | 管理域与配置域边界收敛 | 1 周 |
|
||
| `P5` | 前端去角色化与验收收口 | 菜单、guard、按钮、fallback 收口 | 1 周 |
|
||
|
||
总建议周期：`5.5 周`
|
||
|
||
如果人力有限，可压缩到 `4 周`，但风险会明显上升。
|
||
|
||
---
|
||
|
||
## 4. Phase 1：能力层建设
|
||
|
||
## 4.1 目标
|
||
|
||
提供统一执行器和统一能力快照，形成后续所有模块的接入底座。
|
||
|
||
## 4.2 任务拆解
|
||
|
||
### `P1-T1` 统一权限决策模型
|
||
|
||
产出：
|
||
|
||
- `ScopeContext`
|
||
- `PermissionGrant`
|
||
- `PermissionDecision`
|
||
- `ScopeClause`
|
||
|
||
交付标准：
|
||
|
||
- 支持返回 `allowed + effective_scope + matched_roles`
|
||
|
||
### `P1-T2` 扩展 PermissionService
|
||
|
||
任务：
|
||
|
||
- 在 `PermissionServiceImpl` 基础上新增“返回授权明细”的接口
|
||
- 保留现有 `CheckPermission()` 兼容接口
|
||
|
||
交付标准：
|
||
|
||
- 不破坏现有 controller 调用
|
||
- 能返回 `grant_type/data_scope`
|
||
|
||
### `P1-T3` DataScopeResolver
|
||
|
||
任务：
|
||
|
||
- 实现 `role_permissions.data_scope > roles.data_scope > 默认值`
|
||
- 实现多角色范围合并
|
||
- 实现 `DENY` 优先
|
||
|
||
交付标准：
|
||
|
||
- 覆盖 `ALL/DEPT/SELF/GROUP(兼容)`
|
||
|
||
### `P1-T4` QueryScopeBuilder
|
||
|
||
任务：
|
||
|
||
- 实现通用字段映射拼接
|
||
- 支持 `ALL/DEPT/SELF`
|
||
- 为模块策略预留扩展入口
|
||
|
||
### `P1-T5` ModulePolicyRegistry
|
||
|
||
任务：
|
||
|
||
- 定义 `ModulePolicy` 接口
|
||
- 接入首批策略骨架：
|
||
- `DocumentPolicy`
|
||
- `GovdocPolicy`
|
||
- `UsageStatsPolicy`
|
||
- `RagPolicy`
|
||
- `CrossReviewPolicy`
|
||
- `RbacAdminPolicy`
|
||
|
||
### `P1-T6` 能力快照接口
|
||
|
||
任务：
|
||
|
||
- 为 `/auth/me` 或新能力接口补充当前用户有效权限/能力摘要
|
||
|
||
目的：
|
||
|
||
- 给前端去角色化提供统一来源
|
||
|
||
## 4.3 风险
|
||
|
||
- 范围优先级定义不清，后续模块接入会反复返工
|
||
- 若仍只返回布尔权限，后续模块无法平台化
|
||
|
||
## 4.4 验收
|
||
|
||
- 能独立跑通一条“给用户某 permission + data_scope -> 生成 scope clause”的链路
|
||
|
||
---
|
||
|
||
## 5. Phase 2：RAG 双轨治理
|
||
|
||
## 5.1 目标
|
||
|
||
优先清理最突出的“controller 按 permission，service 按角色名”双轨问题。
|
||
|
||
## 5.2 范围
|
||
|
||
后端：
|
||
|
||
- `ragChatController.py`
|
||
- `ragDatasetServiceImpl.py`
|
||
- `ragChatServiceImpl.py`
|
||
|
||
前端：
|
||
|
||
- `components/dify-dataset-manager/index.tsx`
|
||
- `components/dify-dataset-manager/area-dataset-config.tsx`
|
||
- `hooks/use-area-dataset-config.ts`
|
||
|
||
## 5.3 任务拆解
|
||
|
||
### `P2-T1` 去除 RAG service 中角色白名单
|
||
|
||
任务：
|
||
|
||
- 去除 `UserRole in (...)`
|
||
- 改为 `permission + PermissionDecision + RagPolicy`
|
||
|
||
### `P2-T2` 建立 `PUBLIC_MIXED` 策略
|
||
|
||
任务：
|
||
|
||
- 统一 `app/dataset` 可见规则：
|
||
- 本地区
|
||
- 省级
|
||
- 公共
|
||
|
||
### `P2-T3` 管理接口 scope 化
|
||
|
||
任务：
|
||
|
||
- `/datasets/admin`
|
||
- `create/update/delete`
|
||
- dataset 文档上传/更新/删除
|
||
|
||
统一按数据集属地判定。
|
||
|
||
### `P2-T4` 前端知识库管理去角色化
|
||
|
||
任务：
|
||
|
||
- 删除 `provincial_admin/super_admin/admin` 作为唯一判断条件
|
||
- 改为读取权限/能力快照
|
||
|
||
### `P2-T5` 联调与专项回归
|
||
|
||
重点回归：
|
||
|
||
- 自定义角色拥有 RAG 管理权限时，能正常使用
|
||
- 角色名是 `admin` 但无权限时，必须拒绝
|
||
|
||
## 5.4 风险
|
||
|
||
- RAG 前端历史兼容逻辑较多
|
||
- 现有接口命名有 `my/admin` 混合语义，需避免前后不一致
|
||
|
||
## 5.5 验收
|
||
|
||
- RAG 管理域不再依赖角色名
|
||
- 所有 `/datasets/admin*` 接口仅按 permission + scope 生效
|
||
|
||
---
|
||
|
||
## 6. Phase 3：文档、公文、统计接入
|
||
|
||
## 6.1 目标
|
||
|
||
把项目最核心的数据域统一纳入执行器，解决“范围逻辑分散”和“派生接口越权风险”。
|
||
|
||
## 6.2 范围
|
||
|
||
- `documentServiceImpl.py`
|
||
- `govdocServiceImpl.py`
|
||
- `usageStatsServiceImpl.py`
|
||
|
||
## 6.3 任务拆解
|
||
|
||
### `P3-T1` 文档模块接入统一执行器
|
||
|
||
任务：
|
||
|
||
- 替换 `_getCurrentUserContext`
|
||
- 替换 `_buildDocumentScopeFilters`
|
||
- 对列表、详情、状态、确认、附件、删除统一使用 `DocumentPolicy`
|
||
|
||
### `P3-T2` 公文模块接入统一执行器
|
||
|
||
任务：
|
||
|
||
- 统一文档级 scope
|
||
- 所有 `run/result/report/original` 通过文档回溯校验
|
||
|
||
### `P3-T3` 使用统计模块接入统一执行器
|
||
|
||
任务：
|
||
|
||
- 抽离 `_build_user_scope_condition`
|
||
- 把 `areaScope=user/document` 切换逻辑平台化
|
||
|
||
### `P3-T4` 补权限点缺口
|
||
|
||
任务：
|
||
|
||
- 对当前未显式 permission 化的接口补充 permission_key 定义
|
||
|
||
### `P3-T5` 补日志与审计
|
||
|
||
任务：
|
||
|
||
- 对权限拒绝原因打结构化日志
|
||
- 至少记录：
|
||
- `user_id`
|
||
- `permission_key`
|
||
- `scope_mode`
|
||
- `resource_id`
|
||
|
||
## 6.4 风险
|
||
|
||
- 文档与公文都存在大量派生接口，若只改列表极易留下侧门
|
||
- 统计模块口径复杂，需先确定 `SELF` 用户是否允许部分汇总
|
||
|
||
## 6.5 验收
|
||
|
||
- 列表、详情、下载、导出、删除链路边界一致
|
||
- `details`、`report/docx`、`original` 等高风险接口通过专项回归
|
||
|
||
---
|
||
|
||
## 7. Phase 4：RBAC、合同模板、首页接入
|
||
|
||
## 7.1 目标
|
||
|
||
收敛管理域、配置域和入口域中的角色派生逻辑。
|
||
|
||
## 7.2 范围
|
||
|
||
- `rbacAdminServiceImpl.py`
|
||
- `contractTemplateServiceImpl.py`
|
||
- `homeServiceImpl.py`
|
||
|
||
## 7.3 任务拆解
|
||
|
||
### `P4-T1` RBAC 管理域去上下文硬编码
|
||
|
||
任务：
|
||
|
||
- 替换 `bool_or(role_key IN (...))` 得到的 `is_global/can_manage`
|
||
- 统一用管理域权限和 scope 决策
|
||
|
||
### `P4-T2` 用户管理接口 scope 化
|
||
|
||
任务：
|
||
|
||
- 用户列表
|
||
- 角色用户列表
|
||
- 用户角色查询
|
||
- 用户角色分配/移除
|
||
|
||
全部走 `RbacAdminPolicy`
|
||
|
||
### `P4-T3` 合同模板模块接入
|
||
|
||
任务：
|
||
|
||
- 替换 `is_global/can_manage/created_by`
|
||
- 统一列表、搜索、详情、创建、删除边界
|
||
|
||
### `P4-T4` 首页入口 area 能力收敛
|
||
|
||
任务：
|
||
|
||
- 替换 `bypass_area`
|
||
- 统一入口可见性与用户能力快照
|
||
|
||
## 7.4 风险
|
||
|
||
- RBAC 管理域影响系统管理操作，错误边界会直接影响后台可用性
|
||
- 合同模板前端已有明显角色硬编码，需要同步推进
|
||
|
||
## 7.5 验收
|
||
|
||
- RBAC 用户管理只按 permission + scope 生效
|
||
- 合同模板创建不再依赖前端角色名
|
||
|
||
---
|
||
|
||
## 8. Phase 5：前端去角色化与收口
|
||
|
||
## 8.1 目标
|
||
|
||
让前端从“角色猜能力”迁移为“服务端返回权限/能力，前端只消费结果”。
|
||
|
||
## 8.2 范围
|
||
|
||
- `Sidebar.tsx`
|
||
- `lib/auth/user-routes.ts`
|
||
- `lib/api/legacy/auth/user-routes.ts`
|
||
- `guard.ts`
|
||
- `cross-checking-access.ts`
|
||
- RAG 相关前端
|
||
- 合同模板页
|
||
- 角色权限管理页中的兼容逻辑
|
||
|
||
## 8.3 任务拆解
|
||
|
||
### `P5-T1` 菜单能力统一来源
|
||
|
||
任务：
|
||
|
||
- 菜单只认数据库路由和 permission_map
|
||
- 收缩静态 `FALLBACK_MENU_DATA`
|
||
|
||
### `P5-T2` guard 去 developer/provincial_admin 白名单
|
||
|
||
任务：
|
||
|
||
- `requireDeveloper` 改为认对应后台 permission
|
||
|
||
### `P5-T3` 交叉评查入口可见性去角色化
|
||
|
||
任务：
|
||
|
||
- 继续保留 route + entry module 双条件
|
||
- 删除 `provincial_admin -> 省局` 这类特殊派生
|
||
|
||
### `P5-T4` 页面按钮去角色化
|
||
|
||
任务：
|
||
|
||
- RAG 页面
|
||
- 合同模板上传
|
||
- RBAC 页部分核心角色写死逻辑
|
||
|
||
### `P5-T5` fallback 收口
|
||
|
||
任务：
|
||
|
||
- 明确哪些 fallback 允许暂留
|
||
- 明确哪些在本期必须移除
|
||
|
||
## 8.4 风险
|
||
|
||
- 前端 localStorage 中仍存 `user_role`
|
||
- 若后端能力接口不先给到位，前端改造会停在一半
|
||
|
||
## 8.5 验收
|
||
|
||
- 自定义角色用户在前端能正确看到菜单和按钮
|
||
- 前端不再要求“必须是 admin/provincial_admin 才能操作”
|
||
|
||
---
|
||
|
||
## 9. 建议排期
|
||
|
||
建议以周为单位：
|
||
|
||
| 周期 | 任务 |
|
||
| --- | --- |
|
||
| 第 1 周 | `P1` 能力层建设 |
|
||
| 第 2 周 | `P2` RAG 双轨治理 |
|
||
| 第 3 周上半 | `P3` 文档、公文接入 |
|
||
| 第 3 周下半 | `P3` 统计接入 + 回归 |
|
||
| 第 4 周 | `P4` RBAC、合同模板、首页 |
|
||
| 第 5 周 | `P5` 前端去角色化 + 全量回归 |
|
||
| 第 5.5 周 | 灰度观察与问题收口 |
|
||
|
||
---
|
||
|
||
## 10. 人力建议
|
||
|
||
建议最少投入：
|
||
|
||
1. 后端 2 人
|
||
2. 前端 1 人
|
||
3. 测试 1 人
|
||
|
||
更稳妥的配置：
|
||
|
||
1. 平台/后端 1 人负责统一执行器
|
||
2. 业务后端 1 人负责文档、公文、统计接入
|
||
3. 业务后端 1 人负责 RAG、RBAC、合同模板
|
||
4. 前端 1 人负责菜单、guard、页面按钮去角色化
|
||
5. 测试 1 人负责权限矩阵与回归
|
||
|
||
---
|
||
|
||
## 11. 依赖关系
|
||
|
||
必须严格遵守下面依赖：
|
||
|
||
1. `P1` 不完成，`P2-P4` 只能局部试改，无法稳定落地
|
||
2. `P2` 必须优先于前端 RAG 去角色化
|
||
3. `P3` 完成后才能开展核心数据域全量回归
|
||
4. `P5` 必须依赖能力快照/统一路由权限接口
|
||
|
||
---
|
||
|
||
## 12. 回滚策略
|
||
|
||
每个 Phase 都要有可回滚边界。
|
||
|
||
建议：
|
||
|
||
- `P1`：新增能力，不替换旧逻辑，可回滚
|
||
- `P2-P4`：模块按开关切换新旧 scope 执行器
|
||
- `P5`：前端保留短期兼容 fallback，但只做兜底，禁止新增依赖
|
||
|
||
建议增加配置开关：
|
||
|
||
- `PERMISSION_SCOPE_EXECUTOR_ENABLED`
|
||
- `PERMISSION_SCOPE_EXECUTOR_MODULES`
|
||
|
||
支持按模块灰度：
|
||
|
||
- `rag`
|
||
- `documents`
|
||
- `govdoc`
|
||
- `usage_stats`
|
||
- `rbac_admin`
|
||
- `contract_templates`
|
||
|
||
---
|
||
|
||
## 13. 交付物清单
|
||
|
||
本轮最终交付应包括：
|
||
|
||
1. 统一执行器代码
|
||
2. 模块策略代码
|
||
3. 权限接口矩阵文档
|
||
4. 权限测试与回归文档
|
||
5. 角色去硬编码迁移清单
|
||
6. 灰度开关与日志方案
|
||
7. 回归测试记录
|
||
|
||
---
|
||
|
||
## 14. 完成定义
|
||
|
||
只有满足以下条件，才能认为本轮权限改造完成：
|
||
|
||
1. RAG 不再按角色白名单决策
|
||
2. 文档、公文、统计已接统一执行器
|
||
3. RBAC 用户管理和合同模板已去主要角色硬编码
|
||
4. 前端菜单/按钮不再依赖核心旧角色名
|
||
5. 详情/下载/导出专项回归通过
|
||
|
||
如果只完成其中一部分，只能算“阶段性接入”，不能算权限架构改造完成。
|