leaudit-platform-backend/docs/权限与地区隔离/角色去硬编码迁移清单.md

角色去硬编码迁移清单

适用范围：当前项目中所有直接依赖 super_admin/provincial_admin/admin/common/developer 的权限判断
文档定位：从“问题分析”进入“逐文件迁移清单”，指导研发按优先级拆改。

---

1. 迁移目标

本清单的目标不是把所有“角色”这个概念删掉，而是把“用角色名直接判断能力”的写法替换成下面三类正规来源：

1. permission_key
2. effective_scope
3. module policy / capability snapshot

保留角色本身作为“授权载体”，但不再让角色名直接主导业务逻辑。

---

2. 问题类型定义

为方便排期，先统一问题类型。

类型	含义
CTX	服务层上下文派生硬编码
ACT	服务层动作放行硬编码
UI	前端按钮/编辑态硬编码
GUARD	前端路由、guard、fallback、role mapping 硬编码
COMPAT	兼容层短期保留但必须收缩的旧逻辑

---

3. 后端迁移清单

3.1 P0：必须最先处理

文件	当前写法	问题类型	替换目标	优先级	风险	影响范围
fastapi_modules/fastapi_leaudit/services/impl/ragDatasetServiceImpl.py	多处 UserRole in ('provincial_admin','admin','super_admin')	ACT	改为 rag:* permission + RagPolicy + effective_scope	P0	高	RAG 管理接口、数据集文档接口
fastapi_modules/fastapi_leaudit/services/impl/ragChatServiceImpl.py	user_role == 'provincial_admin'、_app_visible 角色分支	ACT	改为 PUBLIC_MIXED 策略	P0	高	应用列表、默认应用、聊天入口
fastapi_modules/fastapi_leaudit/controllers/ragChatController.py	把 UserRole 透传给 service	ACT	改为透传 ScopeContext/CapabilitySnapshot	P0	中	所有 RAG 接口联动

3.2 P1：统一上下文能力层

文件	当前写法	问题类型	替换目标	优先级	风险	影响范围
fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py	_getCurrentUserContext() 中按 role_key IN (...) 生成 is_global/can_manage/is_super_admin	CTX	改为 PermissionDecisionService	P1	高	文档列表、详情、附件、确认、删除
fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py	通过 is_global/can_manage 控制 region/created_by	CTX	改为 GovdocPolicy	P1	高	公文详情、run、报告、下载
fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py	_getCurrentUserContext 中 role_key IN (...) 派生范围	CTX	改为 UsageStatsPolicy	P1	中高	概览、趋势、明细
fastapi_modules/fastapi_leaudit/services/impl/contractTemplateServiceImpl.py	is_global/can_manage/is_area_admin 依赖角色名	CTX	改为 ContractTemplatePolicy	P1	中	模板列表、搜索、创建、删除
fastapi_modules/fastapi_leaudit/services/impl/rbacAdminServiceImpl.py	bool_or(r.role_key IN (...)) 派生管理能力	CTX	改为 RbacAdminPolicy + rbac permission	P1	高	用户列表、组织树、角色分配
fastapi_modules/fastapi_leaudit/services/impl/homeServiceImpl.py	role_key = 'super_admin' => bypass_area	CTX	改为首页能力快照	P1	中	首页入口可见性

3.3 P2：默认角色与兼容角色清理

文件	当前写法	问题类型	替换目标	优先级	风险	影响范围
fastapi_modules/fastapi_leaudit/services/impl/authServiceImpl.py	用户无角色时自动补 common；回退主角色 common	COMPAT	保留默认角色机制，但从业务能力判断中剥离“common 特权假设”	P2	中	登录、初始化用户
fastapi_modules/fastapi_leaudit/services/impl/rbacServiceImpl.py	roleBucket = "admin" if any(role in {...}) else "common"	COMPAT	仅短期保留在菜单兼容层，逐步删除角色桶映射	P2	高	路由树、菜单 fallback
fastapi_modules/fastapi_leaudit/services/impl/rbacServiceImpl.py	静态蓝图 _COMPAT_ROUTE_BLUEPRINTS 以 admin/common 分桶	COMPAT	改为数据库路由兜底，不认角色桶	P2	中高	前端菜单

---

4. 前端迁移清单

4.1 P0：直接影响权限感知

文件	当前写法	问题类型	替换目标	优先级	风险	影响范围
legal-platform-frontend/components/dify-dataset-manager/index.tsx	provincial_admin/super_admin/admin 决定 canEditDataset	UI	改为读 rag 能力或 permission_map	P0	高	RAG 编辑按钮、详情编辑态
legal-platform-frontend/hooks/use-area-dataset-config.ts	roleCanManageDataset = provincial_admin/super_admin/admin	UI	改为纯 permission 决策	P0	高	知识库配置页全部操作
legal-platform-frontend/components/dify-dataset-manager/area-dataset-config.tsx	isProvincialAdmin、非省级自动填地区	UI	改为根据 effective_scope 与 allowed_areas 决定	P0	中高	地区选择器、创建编辑表单

4.2 P1：菜单与路由层

文件	当前写法	问题类型	替换目标	优先级	风险	影响范围
legal-platform-frontend/lib/auth/user-routes.ts	静态 FALLBACK_MENU_DATA.admin/common	GUARD	收敛为数据库路由兜底，不做角色桶映射	P1	高	主菜单
legal-platform-frontend/lib/api/legacy/auth/user-routes.ts	mapUserRoleToRoleKey() 中 provincial_admin -> admin、developer -> admin	GUARD	删除角色映射，直接使用后端返回路由与权限	P1	高	菜单缓存、路由授权
legal-platform-frontend/components/layout/Sidebar.tsx	按 userRole 拉路由、写 localStorage.user_role	GUARD	改为按登录态和后端返回能力渲染	P1	中高	侧边栏菜单、权限 map
legal-platform-frontend/lib/auth/cross-checking-access.ts	provincial_admin 自动补 省局 area 候选	GUARD	改为服务端返回 allowed_areas	P1	中	交叉评查入口展示
legal-platform-frontend/lib/auth/guard.ts	developer/provincial_admin 白名单进入设置页	GUARD	改为检查后台管理权限	P1	高	设置页访问

4.3 P2：页面级残留

文件	当前写法	问题类型	替换目标	优先级	风险	影响范围
legal-platform-frontend/app/(audit)/contract-template/list/ContractTemplateListClient.tsx	currentUser.role === "admin" 才能上传	UI	改为 contract_template:create:write	P2	中高	合同模板上传入口
legal-platform-frontend/app/(audit)/role-permissions/RolePermissionsClient.tsx	provincial_admin 禁删、coreRoles = ['provincial_admin','admin','common']、setIsCityAdmin(userRole==='admin')	UI/COMPAT	保留系统角色保护逻辑，但与角色名硬编码解耦	P2	中高	角色权限管理页
legal-platform-frontend/hooks/usePermission.tsx	默认 userRole = common，大量消费 localStorage.user_role	COMPAT	保留兼容字段，但新增能力快照来源，逐步弱化角色中心地位	P2	中	多页面基础权限钩子
legal-platform-frontend/components/layout/Layout.tsx	默认 userRole = developer，回退读取本地角色	COMPAT	改为显式会话能力初始化	P2	中	全局布局

---

5. 接口影响面清单

角色去硬编码不会只影响代码写法，还会影响接口行为。

5.1 后端接口影响

模块	受影响接口
RAG	/v3/rag/apps、/v3/rag/apps/default、/v3/rag/datasets/admin*、/v3/rag/datasets/{id}*
文档	/documents/list、/documents/{id}、/documents/status、/v3/review-points/*
公文	/govdoc/documents*、/govdoc/runs/*、/govdoc/documents/{id}/original
统计	/v3/usage-stats/*
RBAC	/v3/rbac/users*、/v3/rbac/roles/{id}/users、/v3/rbac/users/{id}/roles*
合同模板	/v3/contract-templates*
首页	首页入口模块加载逻辑

5.2 前端受影响页面

页面/模块	受影响点
侧边栏菜单	路由来源、权限 map 来源
知识库管理页	可编辑、可创建、地区选择范围
合同模板页	上传按钮、删除按钮
设置页	进入 guard
交叉评查入口	是否显示入口模块
角色权限管理页	系统角色保护、核心角色展示逻辑

---

6. 推荐替换模式

6.1 后端替换模式

不推荐：

if user_role in ("provincial_admin", "admin", "super_admin"):
    ...

推荐：

decision = await permissionDecisionService.decide(
    ScopeContext(
        user_id=current_user_id,
        permission_key="rag:dataset:update",
        module="rag",
        resource_id=dataset_id,
    )
)
if not decision.allowed:
    raise Forbidden()

6.2 前端替换模式

不推荐：

const canUpload = currentUser.role === "admin";

推荐：

const canUpload = hasPermission("contract_template:create:write");

或者：

const canManageDataset = capability.rag?.manage === true;

---

7. 兼容策略

并不是所有角色相关代码都要同一天删除。

建议分 3 类处理：

1. 立即删除
   • 服务层动作白名单
   • 前端页面按钮直接按角色判断
2. 先替换后删除
   • is_global/can_manage/bypass_area
3. 短期保留但冻结
   • 路由 fallback
   • 本地 user_role 兼容字段

“冻结”的意思是：

• 不再新增依赖
• 只允许向统一能力来源迁移

---

8. 风险说明

8.1 最大风险

如果只改后端，不改前端，会出现：

• 后端已经可用，但前端按钮还不显示
• 菜单还按旧角色展示
• 用户误以为权限失效

如果只改前端，不改后端，会出现：

• 前端展示放开
• 后端仍按旧角色拒绝
• 联调体验极差

8.2 第二风险

去硬编码后，如果没有统一能力快照，前端容易又发明一套新的本地推断规则。

所以必须同步提供：

• /auth/me 扩展能力
• 或专门的当前用户能力接口

---

9. 推荐执行顺序

建议按下面顺序推进：

1. ragDatasetServiceImpl.py
2. ragChatServiceImpl.py
3. RAG 前端 3 个文件
4. documentServiceImpl.py
5. govdocServiceImpl.py
6. usageStatsServiceImpl.py
7. rbacAdminServiceImpl.py
8. contractTemplateServiceImpl.py
9. homeServiceImpl.py
10. 菜单/guard/fallback 前端文件

原因：

• 先打掉最明显的双轨冲突
• 再统一高风险数据域
• 最后收口前端兼容层

---

10. 完成判定

角色去硬编码完成，不是指仓库里再也没有 admin 字符串，而是指：

1. 角色名不再直接决定业务动作是否允许
2. 角色名不再直接决定数据边界
3. 前端不再用角色名推断核心按钮与菜单
4. 新增自定义角色时，不需要全仓库搜角色名改逻辑

只有达到这 4 条，才算真正完成迁移。