feat: add tenant-scoped rule and permission management

2026-05-21 22:03:08 +08:00
parent a2c2bf1969
commit 1f1bccf3b3
193 changed files with 64463 additions and 1771 deletions
@@ -0,0 +1,325 @@
+# 自定义租户功能连带影响深度补充
+
+> 适用范围：新增自定义租户、扩展新地区、入口模块租户化、权限执行器接租户边界的全链路影响分析  
+> 文档定位：补齐“入口模块之外，还有哪些地方会因为自定义租户而出问题”的深度清单，避免只修表面能力。
+
+---
+
+## 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)