wren
326 lines
9.1 KiB
Markdown
326 lines
9.1 KiB
Markdown
# 自定义租户功能连带影响深度补充
|
|
|
|
> 适用范围：新增自定义租户、扩展新地区、入口模块租户化、权限执行器接租户边界的全链路影响分析
|
|
> 文档定位：补齐“入口模块之外，还有哪些地方会因为自定义租户而出问题”的深度清单，避免只修表面能力。
|
|
|
|
---
|
|
|
|
## 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)
|