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

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

---

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

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