leaudit-platform-backend/docs/权限与地区隔离/中高低风险修复优化计划.md

中高低风险修复优化计划

适用范围：leaudit-platform 当前权限、租户、地区隔离、多租户入口模块改造收尾阶段
更新日期：2026-05-20
文档定位：把当前“哪些地方还没收口”转成可执行的风险分级修复计划，作为后续逐步开发、联调、验收的直接依据。

---

1. 总体原则

本轮改造后续一律按下面 5 条原则推进：

1. 所有“归属租户”语义统一收口到 tenant_code
2. tenant_name 只负责展示，不再承担主键语义
3. area / region / default / 省级 / 公共 只允许存在于兼容层、历史数据清洗层、展示层
4. 所有 service 内部查询、写入、权限边界判断优先走 tenant_code
5. 所有角色判断最终要迁到“权限点 + 数据范围 + 租户能力”，不能长期保留 admin/provincial_admin/common/super_admin 业务硬编码

---

2. 风险分级标准

2.1 高风险

满足任一条件即归为高风险：

1. 会直接导致“查错数据、落错租户、串版本、越权访问”
2. 底层数据表没有 tenant_code 主字段，当前仍靠 area/region 做真实过滤
3. 查询链路和写入链路不一致，容易出现“写到 A，查按 B”
4. 会影响多个下游模块的主数据域

2.2 中风险

满足任一条件即归为中风险：

1. 不一定立刻串数据，但会造成前后端边界不一致
2. 前端仍按旧角色、旧地区字段判断，和后端真实权限模型不一致
3. 业务能跑，但兼容层和正式模型混用，后续维护成本高且容易继续扩散

2.3 低风险

满足任一条件即归为低风险：

1. 不直接影响数据正确性与权限边界
2. 主要影响可维护性、一致性、可理解性、页面上手体验
3. 适合在主链稳定后统一清理

---

3. 高风险修复计划

3.1 范围

当前高风险模块如下：

1. 文档模块 T2
2. 内部公文模块 T3
3. 合同模板模块 T6
4. 系统使用统计模块 T7
5. 核心业务表 tenant_code 缺失与历史 area/region 主过滤残留

3.2 当前问题

这些模块虽然已经接了 TenantResolver 或兼容入参，但底层仍存在以下问题：

1. 业务表未落真实 tenant_code
2. SQL 过滤主条件仍是 region/area
3. 接口表面支持 tenant_code，但只是转译成中文地区再去查
4. 历史公共范围仍散落为 default / 公共 / 省级
5. 统计快照字段还没有完整记录 tenant_code

3.3 修复目标

高风险阶段必须达成：

1. 核心业务表具备 tenant_code
2. 列表、详情、上传、删除、运行、版本链、统计聚合统一按 tenant_code
3. region/area 退化为兼容展示字段
4. PUBLIC / PROVINCIAL 变成规范租户编码，不再以中文和 default 直接参与 SQL

3.4 执行顺序

H1 数据库主链补齐

目标：

1. 识别仍缺 tenant_code 的核心业务表
2. 补字段、索引、必要约束
3. 设计历史数据回填脚本

优先表：

1. leaudit_documents
2. contract_templates
3. usage_login_events
4. rag_dataset
5. rag_chat_app
6. 评估内部公文相关主表是否需单独补 tenant_code，还是直接复用 leaudit_documents.tenant_code

H2 文档模块收口

目标：

1. 上传写入 tenant_code
2. 列表/详情/附件/删除/版本链按 tenant_code 查询
3. _resolve_document_region 降级为兼容展示方法

H3 内部公文模块收口

目标：

1. 上传、列表、详情、运行、结果统一基于 tenant_code
2. 公文版本链、运行链、路径链路不再以 region 作为真实归属键

H4 合同模板模块收口

目标：

1. 去掉 '' AS tenant_code 这类伪租户返回
2. 列表、详情、搜索、上传统一改成真实 tenant_code
3. region 只保留中文展示与兼容输入

当前进展：

1. 第一轮高风险已完成
2. 上传权限、列表/详情/搜索 scope、公共/省级查询口径已收口为 tenant_code 优先
3. 旧数据仍允许按 region 兜底命中，但不再把 region 当新数据真实归属键

H5 统计模块收口

目标：

1. 登录/上传/运行等事件记录租户快照
2. 聚合统计按 tenant_code 计算
3. 页面展示再映射为 tenant_name

3.5 高风险验收标准

1. 任意核心业务记录都能明确看到 tenant_code
2. 同名文档、模板、公文在不同租户之间不会串数据
3. 非本租户用户无法通过列表、详情、附件、运行、统计明细绕过边界
4. 公共/省级范围由规范租户编码统一表达
5. 即使 tenant_name 被修改，历史归属和查询边界也不受影响

3.6 高风险阶段不做的事

1. 不在这个阶段追求完全去掉所有 region/area 字段
2. 不在这个阶段大面积重构统一权限执行器
3. 不在这个阶段优先做页面视觉优化

---

4. 中风险修复计划

4.1 范围

当前中风险模块如下：

1. T4 RAG 知识库模块
2. T1 RBAC 管理域剩余角色/范围硬编码
3. T10 前端菜单、守卫、按钮显隐中的旧角色判断
4. 交叉评查入口与可见性判断残留的 area/region/provincial_admin 分支

4.2 当前问题

1. 前后端都还存在“认角色名”的逻辑
2. RAG 底层还是 area 主模型
3. 前端可见性和后端鉴权未完全同构
4. 某些页面已经接了租户接口，但按钮是否显示仍按 admin/provincial_admin

4.3 修复目标

1. RAG 数据集、应用改用 tenant_code
2. 前端从“角色名驱动”迁到“权限点 + 能力 + 租户归属”
3. RBAC 页面中的核心角色保护、系统角色识别改为后端权威字段或配置
4. 菜单守卫与接口鉴权口径保持一致

4.4 执行顺序

M1 RAG 数据模型和服务收口

目标：

1. rag_dataset、rag_chat_app 补 tenant_code
2. service 查询、创建、编辑、删除统一按 tenant_code
3. 公共知识库策略从角色判断改为标准租户能力规则

M2 前端角色硬编码收口

目标：

1. user-routes
2. guard
3. cross-checking-access
4. role-permissions
5. contract-template
6. dify-dataset-manager

统一改成：

1. 按权限点判断能否访问
2. 按租户归属判断能否管理
3. 仅保留极少数系统级保底兼容

M3 RBAC 边界统一

目标：

1. 系统角色识别不再由前端手工猜
2. 角色删除保护由后端统一返回是否允许删除
3. 页面展示不再写死 provincial_admin/admin/common

4.5 中风险验收标准

1. 自定义角色只要拿到权限，前端就能正确显示入口与按钮
2. 没有权限时，即使角色名叫 admin 也不能误显示能力
3. 前端守卫、菜单、按钮显隐与接口 403 结果一致
4. RAG 不再依赖 area 作为真实归属字段

---

5. 低风险修复计划

5.1 范围

当前低风险事项如下：

1. 页面 UI 风格统一
2. 旧命名清理
3. 兼容字段对外返回口径统一
4. 文档导航与开发说明补齐

5.2 当前问题

1. 租户管理页和角色权限页视觉系统还不完全统一
2. 前端大量 area-*、region-*、tenant-* 命名混用
3. 部分返回结构里主字段和兼容字段同时存在，但优先级不够明确

5.3 修复目标

1. 租户管理、角色权限、入口模块等后台页风格统一
2. 新接口主输出统一为 tenant_code / tenant_name
3. 旧字段仅作为兼容字段保留，并在类型和注释中明确标记
4. 文档导航和执行进度持续更新

5.4 执行顺序

L1 角色权限页样式统一

目标：

1. 完成 RolePermissionsClient.tsx 新结构对应 CSS
2. 与租户管理页保持同一后台设计语言

L2 命名清理

目标：

1. 新增代码不再出现新的 area-* 命名
2. 旧 area/region 命名逐步迁到 tenant-*

L3 文档与注释补充

目标：

1. 更新总导航
2. 更新当前进度
3. 为新迁移脚本和关键兼容点补说明

5.5 低风险验收标准

1. 页面风格统一、上手成本降低
2. 新代码可读性显著提升
3. 后续开发者能明确知道哪些字段是主字段、哪些只是兼容字段

---

6. 推荐执行计划

建议按下面顺序推进：

1. 先完成高风险 H1-H5
2. 再完成中风险 M1-M3
3. 最后完成低风险 L1-L3

原因：

1. 先保数据和边界正确
2. 再保权限模型一致
3. 最后做视觉、命名、文档收尾

---

7. 本轮立即启动项

本轮开始直接执行以下两件事：

1. 先补“高风险数据库迁移清单”，明确哪些表要加 tenant_code
2. 然后从 T2/T3/T6 主链开始，把文档、公文、合同模板改成 tenant_code 主过滤

这两步完成后，项目才算真正进入“tenant_code 全链路收口”阶段，而不是继续停留在兼容层阶段。