# 中高低风险修复优化计划

> 适用范围：`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 全链路收口”阶段，而不是继续停留在兼容层阶段。