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

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

---

## 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` 当前上传接口默认：

```python
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](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/租户主数据模型设计.md)
2. [地区到租户编码映射清洗清单.md](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/地区到租户编码映射清洗清单.md)
3. [入口模块租户配置表迁移方案.md](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/入口模块租户配置表迁移方案.md)
4. [权限文档总导航与阅读顺序.md](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/权限文档总导航与阅读顺序.md)

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

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

---

## 13. 本文档解决什么问题

本文档主要解决：

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

建议阅读顺序：

1. [地区租户化与自定义租户扩展改造方案.md](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/地区租户化与自定义租户扩展改造方案.md)
2. [租户主数据模型设计.md](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/租户主数据模型设计.md)
3. [地区到租户编码映射清洗清单.md](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/地区到租户编码映射清洗清单.md)
4. [入口模块租户配置表迁移方案.md](/home/wren-dev/Porject/leaudit-platform/docs/权限与地区隔离/入口模块租户配置表迁移方案.md)