leaudit-platform-backend/docs/权限与地区隔离/自定义租户功能连带影响深度补充.md

自定义租户功能连带影响深度补充

适用范围：新增自定义租户、扩展新地区、入口模块租户化、权限执行器接租户边界的全链路影响分析
文档定位：补齐“入口模块之外，还有哪些地方会因为自定义租户而出问题”的深度清单，避免只修表面能力。

---

1. 结论先行

“新增一个租户”在当前系统里绝对不是只增加一条主数据。

如果只完成：

1. 建一条租户记录
2. 入口模块页面能选到它

但不继续处理其他连带点，系统仍会在多个模块出现隐性故障。

已确认至少有 8 条受影响链路：

1. 首页入口可见性
2. 交叉评查入口判定
3. 文档上传默认归属
4. 文档列表与评查数据隔离
5. RAG 数据集与聊天应用归属
6. 合同模板公共范围与地区筛选
7. 使用统计地区口径
8. RBAC 用户组织树与租户分组

此外还有两类经常被忽略的次生问题：

1. SQL seed 和注释仍然写死旧地区集合
2. OSS/对象路径里残留旧地区缩写

---

2. 首页入口链路影响

2.1 首页入口不是展示问题，而是权限边界入口

homeServiceImpl.py 当前会根据：

1. user_area
2. em.areas[].area
3. default
4. super_admin bypass

决定用户能看到什么入口。

这意味着：

1. 新租户若没有被标准化到首页入口可见性链路，用户登录后首页就是残缺的
2. 入口模块即使在后台配置成功，也可能对新租户不可见

2.2 首页最容易出现的 3 个问题

1. 用户已属于新租户，但首页没有任何业务入口
2. 新租户误看到了旧公共入口
3. 公共入口被错误地限定成某个租户专属入口

---

3. 交叉评查链路影响

3.1 前端自带固定地区推断

cross-checking-access.ts 当前做法：

1. 写死固定地区别名数组
2. 通过字符串包含关系猜测地区
3. provincial_admin 自动追加 省局

这套逻辑对自定义租户天然不兼容。

3.2 为什么这是高风险点

交叉评查不是普通菜单，而是：

1. 首页入口
2. 路由授权
3. 业务流程入口

三者叠加的模块。

只要其中一层还依赖旧地区字符串，新租户就会出现：

1. 首页看得见但点不进
2. 有路由权限但首页没有入口
3. 能进入页面但实际数据域不对

---

4. 文档上传与文档主表影响

4.1 上传接口默认 region=default

documentController.py 当前上传接口默认：

region: str = Form("default")

这意味着：

1. 前端没显式传租户时，新文档会直接落成 default
2. 新租户用户上传的文档，很可能不会自动归属到该租户

4.2 模型注释仍然固化旧地区集合

leauditDocument.py 注释仍写：

1. mz/yf/jy/cz/default

这说明当前代码心智模型依然认为系统只支持固定几个地区。

4.3 连带后果

如果不改：

1. 新租户用户上传文档后，列表可能查不到
2. 评查结果可能落在公共域
3. 统计会把新租户数据混入默认域

---

5. RAG 链路影响

5.1 RAG 管理接口直接把 area 当租户键

ragDatasetServiceImpl.py 当前：

1. 管理端筛选按 d.area
2. 创建知识库要求传 area
3. 权限范围由 UserArea 和 UserRole 控制

5.2 RAG 聊天应用按 UserArea 找默认应用

ragChatServiceImpl.py 的应用加载逻辑也依赖：

1. UserArea
2. UserRole

5.3 当前最容易出的问题

1. 新租户创建了知识库，但聊天应用找不到默认 app
2. 新租户能进 RAG 页面，但筛选和管理列表不正确
3. 省级 / is_public / 空 area 仍混用，导致公共知识库对新租户不可预期

5.4 前端 RAG 配置页也会被连带影响

use-area-dataset-config.ts 和 area-dataset-config.tsx 当前仍以 area 为中心：

1. 获取可用地区
2. 表单字段用 area
3. 标签把 省级 当特殊样式

所以即使后端引入 tenant_code，前端不一起改也会继续污染数据。

---

6. 合同模板链路影响

6.1 模板表仍把 省级 当公共模板域

当前 contract_templates.region 默认值和注释都围绕 省级 展开。

这对新租户有两个风险：

1. 新租户专属模板无法稳定区分于公共模板
2. 公共模板可能被省局租户语义吞掉

6.2 模板搜索与列表筛选都会受影响

如果新租户使用 tenant_code，但模板查询还按 region 中文值和旧别名判断，就会出现：

1. 模板创建成功但列表查不到
2. 公共模板展示范围不一致

---

7. 统计链路影响

7.1 登录统计快照仍然存 area_snapshot

usageStatsServiceImpl.py 当前会在登录事件写入：

1. area_snapshot

如果新增租户后只改用户主数据，不改快照口径，统计层会出现：

1. 历史值一套
2. 新值一套

最后同一租户可能被拆成两列。

7.2 文档 / 评查 / 登录三类统计口径会继续分裂

统计服务本质上在汇总：

1. 登录行为
2. 文档上传
3. 评查执行

如果三条链路用的租户字段不统一，最终的“按地区统计”会完全失真。

---

8. RBAC 与组织树链路影响

8.1 当前系统已存在 tenant_name 分组语义

rbacAdminServiceImpl.py 当前已经用：

1. tenant_name
2. dep_name
3. ou_name

构建组织树和筛选。

8.2 自定义租户会冲击两个维度

1. 用户主归属租户
2. 组织树中的租户分组

如果只是新增 tenant_code，但 RBAC 管理页仍按旧 tenant_name 展示，会导致：

1. 用户租户边界和管理树分组不一致
2. 新租户看起来像“未分组租户”

8.3 为什么这里不能只靠展示修补

因为 RBAC 管理域后面还会接数据范围执行器。
如果组织树仍然不是标准租户主数据驱动，后面权限执行器就拿不到稳定边界。

---

9. SQL seed 与初始化脚本影响

9.1 当前 seed 里大量写死旧地区集合

已确认：

1. seed_home_entry_modules.sql
2. seed_govdoc_entry_module.sql
3. 相关 schema 注释

都写了固定地区列表。

9.2 为什么这是隐藏高风险点

因为即使主代码改完，只要后续：

1. 重建环境
2. 补跑 seed
3. 初始化新库

系统又会被旧脚本拉回固定地区模型。

所以迁移方案必须覆盖脚本层。

---

10. OSS 路径与资源命名影响

entryModuleAdminServiceImpl.py 当前上传 Logo 路径：

1. documents/mz/static/img/...

这里虽然当前更像历史路径约定，不一定直接参与权限判定，但它暴露出两个问题：

1. 资源路径命名仍带旧地区缩写
2. 后续如果按租户做静态资源隔离，会被旧路径模型阻碍

建议：

1. 不把这类路径直接当权限边界
2. 后续新资源路径使用中性命名或 tenant_code

---

11. 最容易漏掉的影响点

除了主要业务链路，还应补查以下项目：

1. 前端下拉缓存是否写死地区列表
2. 导出报表文件名是否拼接地区文本
3. 定时任务或离线脚本是否按 region='default' 取数
4. OpenAPI/DTO 描述是否仍写“地区”
5. 单元测试与集成测试是否仍断言 省局/省级/default
6. 文案、帮助文档、操作说明是否仍默认地区固定

---

12. 建议新增的配套文档

基于当前分析，还建议保留下面 4 份文档作为完整闭环：

1. 租户主数据模型设计.md
2. 地区到租户编码映射清洗清单.md
3. 入口模块租户配置表迁移方案.md
4. 权限文档总导航与阅读顺序.md

如果后续还要继续补文档，优先级建议是：

1. 租户接口设计与返回结构规范
2. 统一租户解析器与兼容层设计
3. 入口模块/RAG/模板三大模块的详细 SQL 迁移脚本说明

---

13. 本文档解决什么问题

本文档主要解决：

1. 自定义租户除了入口模块还会影响哪些地方
2. 哪些链路只是 UI 问题，哪些链路本质是数据边界问题
3. 为什么文档、RAG、模板、统计、RBAC 都必须一起纳入改造范围
4. 哪些隐藏点最容易在改造后继续埋雷

建议阅读顺序：

1. 地区租户化与自定义租户扩展改造方案.md
2. 租户主数据模型设计.md
3. 地区到租户编码映射清洗清单.md
4. 入口模块租户配置表迁移方案.md