leaudit-platform-backend/docs/权限与地区隔离/权限改造实施任务拆解与排期.md

权限改造实施任务拆解与排期

适用范围：权限统一改造项目实施阶段
文档定位：把权限方案拆成可执行、可排期、可协作、可验收的阶段任务。

---

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. 详情/下载/导出专项回归通过

如果只完成其中一部分，只能算“阶段性接入”，不能算权限架构改造完成。