wren
636 lines
14 KiB
Markdown
636 lines
14 KiB
Markdown
# 地区租户化与自定义租户扩展改造方案
|
||
|
||
> 适用范围：当前系统把“地区”同时当作数据隔离键、入口模块分配维度、部分公共资源维度使用的场景
|
||
> 文档定位：针对“地区其实已经在承担租户语义，但现在是固定死的、没法新增”的问题，给出完整扩展改造方案。
|
||
|
||
---
|
||
|
||
## 1. 结论先行
|
||
|
||
你指出的问题是准确的，而且不是局部问题。
|
||
|
||
当前系统表面上叫“地区隔离”，但从实际代码和数据模型看，`area` 已经在多个地方承担了“租户”语义：
|
||
|
||
1. 用户归属
|
||
2. 文档归属
|
||
3. 合同模板归属
|
||
4. RAG 数据集和应用归属
|
||
5. 首页入口模块可见范围
|
||
6. 交叉评查参与地区展示
|
||
7. RBAC 用户管理范围
|
||
8. 部分统计口径和筛选口径
|
||
|
||
但是当前系统没有真正的“租户主数据模型”，导致出现 4 个结构性问题：
|
||
|
||
1. 允许在数据表里写任意 `area` 字符串，但没有统一租户字典
|
||
2. 前端多处把可选地区硬编码成 `梅州 / 云浮 / 揭阳 / 潮州 / 省局`
|
||
3. 入口模块 `areas` 只是自由 JSON，缺乏租户主数据约束，新增租户后无法统一分配
|
||
4. “省局 / 省级 / 空字符串 / default” 混杂使用，公共范围语义不统一
|
||
|
||
所以这次问题不应该只修“入口模块新增租户没地方选”，而是应该把“地区”正式收敛为“租户维度主数据 + 兼容地区展示名”的模型。
|
||
|
||
---
|
||
|
||
## 2. 当前现状深度分析
|
||
|
||
## 2.1 数据层已经把 area 当租户键用了
|
||
|
||
已确认：
|
||
|
||
- `sso_users.area`
|
||
- `leaudit_documents.region`
|
||
- `contract_templates.region`
|
||
- `rag datasets/apps area`
|
||
- `entry_modules.areas`
|
||
|
||
这些字段虽然命名不同，但本质都在表达：
|
||
|
||
- 这条数据属于哪个业务边界域
|
||
|
||
这个“业务边界域”就是租户。
|
||
|
||
## 2.2 入口模块是当前最明显的断点
|
||
|
||
入口模块表：
|
||
|
||
- `leaudit_entry_modules.areas JSONB`
|
||
|
||
当前后端：
|
||
|
||
- 允许写任意 JSON `[{ area, enabled, sort_order }]`
|
||
- 不校验这些 `area` 是否属于合法主数据
|
||
|
||
当前前端：
|
||
|
||
- 新建页把地区选项硬编码成：
|
||
- `梅州`
|
||
- `云浮`
|
||
- `揭阳`
|
||
- `潮州`
|
||
- `省局`
|
||
|
||
这意味着：
|
||
|
||
- 后端理论上能存新租户字符串
|
||
- 但前端没有入口选择它
|
||
- 首页也没有统一租户主数据做可见性计算
|
||
|
||
## 2.3 首页入口可见性已经严重依赖 area
|
||
|
||
`homeServiceImpl.py` 当前做法：
|
||
|
||
- 直接按 `user_area` 匹配 `em.areas[].area`
|
||
- `super_admin` 特判 `bypass_area`
|
||
- 还把 `default` 当成兜底 area
|
||
|
||
这说明首页可见性已经是租户配置功能，而不是简单地区展示。
|
||
|
||
## 2.4 交叉评查入口又叠了一层前端租户别名
|
||
|
||
`cross-checking-access.ts` 当前做法：
|
||
|
||
- `AREA_ALIASES = ["梅州", "云浮", "揭阳", "潮州", "省局"]`
|
||
- 角色是 `provincial_admin` 就自动补 `省局`
|
||
|
||
这说明前端为了适配没有租户主数据，只能自己发明一套：
|
||
|
||
- 别名识别
|
||
- 角色补值
|
||
- 入口匹配
|
||
|
||
这类逻辑会随着新租户持续失控。
|
||
|
||
## 2.5 RAG 和合同模板已经有“公共租户”语义，但不统一
|
||
|
||
RAG 当前：
|
||
|
||
- `area in (user_area, '省级', '') or is_public`
|
||
|
||
合同模板当前：
|
||
|
||
- 多处用 `省级` 作为公共范围
|
||
|
||
入口模块当前：
|
||
|
||
- 用 `省局`
|
||
|
||
首页当前：
|
||
|
||
- 还支持 `default`
|
||
|
||
这说明“公共租户”语义现在至少有 4 种写法：
|
||
|
||
1. `省局`
|
||
2. `省级`
|
||
3. `''`
|
||
4. `default`
|
||
|
||
这是后续扩展新租户时最大的数据一致性风险。
|
||
|
||
---
|
||
|
||
## 3. 真实问题不止入口模块
|
||
|
||
你已经发现入口模块新增租户无法分配，但如果继续深挖，至少还有下面这些隐含问题。
|
||
|
||
## 3.1 新租户无法稳定出现在前端筛选中
|
||
|
||
已确认存在固定地区名单或地区别名逻辑的地方：
|
||
|
||
- 入口模块新建页
|
||
- 入口模块列表页
|
||
- 交叉评查入口访问逻辑
|
||
- RAG 地区配置页
|
||
- 合同模板地区展示
|
||
- 使用统计地区筛选
|
||
|
||
结果是：
|
||
|
||
- 后端有新租户数据
|
||
- 前端很多页面也未必看得见或选得到
|
||
|
||
## 3.2 新租户无法作为“入口可见范围主数据”统一管理
|
||
|
||
目前入口模块的地区可见性完全靠：
|
||
|
||
- 每个模块自己存一份 `areas JSON`
|
||
|
||
但没有：
|
||
|
||
- 可复用的租户字典
|
||
- 可禁用租户
|
||
- 可排序租户
|
||
- 可标识是否公共租户/总部租户
|
||
|
||
后果：
|
||
|
||
- 每个入口模块都可能写出不同拼法
|
||
- 例如：`省局` / `省级` / `广东省局`
|
||
|
||
## 3.3 用户归属和入口可见性没有共享主数据
|
||
|
||
当前用户主归属在：
|
||
|
||
- `sso_users.area`
|
||
|
||
入口模块配置在：
|
||
|
||
- `leaudit_entry_modules.areas[].area`
|
||
|
||
二者之间没有外键，没有主数据表，没有统一编码。
|
||
|
||
所以只要字符串不完全相同，用户就可能：
|
||
|
||
- 有租户
|
||
- 但首页看不到对应入口
|
||
|
||
## 3.4 统计、RAG、模板的“公共租户”语义无法扩展
|
||
|
||
如果以后新增：
|
||
|
||
- 总部租户
|
||
- 试点租户
|
||
- 集团公共租户
|
||
|
||
当前模型无法优雅表达。
|
||
|
||
因为现在公共语义散在：
|
||
|
||
- `省局`
|
||
- `省级`
|
||
- 空串
|
||
- `is_public`
|
||
- `default`
|
||
|
||
没有统一的“租户类型”字段。
|
||
|
||
## 3.5 文档和公文本身的 `region` 注释仍带旧代码语义
|
||
|
||
`leauditDocument.py` 里还写着：
|
||
|
||
- `所属地区: mz/yf/jy/cz/default`
|
||
|
||
这已经明显说明模型和代码注释都还把可选租户想成固定集合。
|
||
|
||
这类地方如果不统一改，后面团队会默认：
|
||
|
||
- 新租户不在支持范围内
|
||
|
||
---
|
||
|
||
## 4. 为什么不能只在前端把地区下拉改成可配置
|
||
|
||
因为问题不是 UI，而是模型。
|
||
|
||
只改前端下拉，只能解决：
|
||
|
||
- 用户能选一个新租户字符串
|
||
|
||
但解决不了：
|
||
|
||
1. 这个租户是否合法
|
||
2. 这个租户的展示名、编码、排序、启用状态是什么
|
||
3. 这个租户是不是公共租户
|
||
4. 这个租户能不能被入口模块使用
|
||
5. 这个租户和 `sso_users.area` 是否一致
|
||
6. 旧数据里的 `省局/省级/default` 怎么兼容
|
||
|
||
所以必须建租户主数据。
|
||
|
||
---
|
||
|
||
## 5. 推荐目标模型
|
||
|
||
## 5.1 核心结论
|
||
|
||
建议把当前“地区字段”升级为：
|
||
|
||
- `tenant_code`
|
||
- `tenant_name`
|
||
|
||
其中：
|
||
|
||
- `tenant_code` 用于内部引用和匹配
|
||
- `tenant_name` 用于展示
|
||
|
||
当前 `area/region` 先作为兼容展示字段保留，不立即强拆。
|
||
|
||
## 5.2 推荐新增主数据表
|
||
|
||
建议新增：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS sys_tenants (
|
||
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
|
||
tenant_code VARCHAR(64) NOT NULL UNIQUE,
|
||
tenant_name VARCHAR(128) NOT NULL,
|
||
tenant_type VARCHAR(32) NOT NULL DEFAULT 'REGIONAL',
|
||
parent_tenant_code VARCHAR(64),
|
||
is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
|
||
is_public BOOLEAN NOT NULL DEFAULT FALSE,
|
||
sort_order INTEGER NOT NULL DEFAULT 0,
|
||
metadata JSONB,
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ DEFAULT NOW(),
|
||
deleted_at TIMESTAMPTZ
|
||
);
|
||
```
|
||
|
||
建议 `tenant_type`：
|
||
|
||
- `HEADQUARTERS`
|
||
- `REGIONAL`
|
||
- `PUBLIC`
|
||
- `TEST`
|
||
|
||
## 5.3 推荐字段语义
|
||
|
||
| 字段 | 作用 |
|
||
| --- | --- |
|
||
| `tenant_code` | 稳定编码，例如 `mz`、`yf`、`jy`、`cz`、`hq` |
|
||
| `tenant_name` | 展示名，例如 `梅州`、`云浮`、`揭阳`、`潮州`、`省局` |
|
||
| `tenant_type` | 租户类别 |
|
||
| `is_public` | 是否属于公共资源可见租户 |
|
||
| `parent_tenant_code` | 可选，用于总部-地区树 |
|
||
|
||
---
|
||
|
||
## 6. 推荐兼容演进路径
|
||
|
||
## 6.1 第一阶段：不强拆 area/region
|
||
|
||
第一阶段不建议立刻把所有业务表从 `area/region` 改成 `tenant_id`。
|
||
|
||
原因：
|
||
|
||
- 当前系统大量 SQL 直接用字符串比较
|
||
- 一次性切换成本过高
|
||
|
||
第一阶段建议：
|
||
|
||
1. 新增 `sys_tenants`
|
||
2. 在所有“配置与入口层”先改成认租户主数据
|
||
3. 业务数据层先继续使用原 `area/region`
|
||
4. 通过 `tenant_code/tenant_name` 映射兼容旧值
|
||
|
||
## 6.2 第二阶段：入口和配置域先租户化
|
||
|
||
优先改：
|
||
|
||
1. 入口模块
|
||
2. 首页入口可见性
|
||
3. 前端地区下拉
|
||
4. 交叉评查入口地区判断
|
||
5. RAG 地区配置页
|
||
|
||
## 6.3 第三阶段：业务资源逐步 tenant_code 化
|
||
|
||
后续再逐步考虑：
|
||
|
||
- `sso_users.area -> tenant_code`
|
||
- `leaudit_documents.region -> tenant_code`
|
||
- `contract_templates.region -> tenant_code`
|
||
|
||
但这一步可以晚于权限执行器改造。
|
||
|
||
---
|
||
|
||
## 7. 入口模块改造方案
|
||
|
||
入口模块是本次租户化最优先的模块。
|
||
|
||
## 7.1 当前问题
|
||
|
||
当前：
|
||
|
||
- 表里 `areas` 是自由 JSON
|
||
- 前端是固定地区多选框
|
||
- 首页用 `user_area` 直接匹配 JSON 里的 `area`
|
||
|
||
## 7.2 推荐改法
|
||
|
||
新增入口模块租户配置表：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS leaudit_entry_module_tenants (
|
||
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
|
||
entry_module_id BIGINT NOT NULL REFERENCES leaudit_entry_modules(id) ON DELETE CASCADE,
|
||
tenant_code VARCHAR(64) NOT NULL,
|
||
enabled BOOLEAN NOT NULL DEFAULT TRUE,
|
||
sort_order INTEGER NOT NULL DEFAULT 0,
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ DEFAULT NOW(),
|
||
UNIQUE(entry_module_id, tenant_code)
|
||
);
|
||
```
|
||
|
||
说明：
|
||
|
||
- 不建议继续把入口租户配置长期保留在 JSON
|
||
- JSON 适合作为兼容字段，不适合作为主配置结构
|
||
|
||
## 7.3 兼容策略
|
||
|
||
短期可以：
|
||
|
||
1. 保留 `leaudit_entry_modules.areas`
|
||
2. 新增 `leaudit_entry_module_tenants`
|
||
3. 后端优先读新表
|
||
4. 若新表为空，再回退读旧 JSON
|
||
|
||
## 7.4 前端改法
|
||
|
||
入口模块新建/编辑页不再使用固定 `AREA_OPTIONS`，改为：
|
||
|
||
1. 先调用租户列表接口
|
||
2. 渲染启用租户多选
|
||
3. 允许选择新增租户
|
||
|
||
---
|
||
|
||
## 8. 首页入口改造方案
|
||
|
||
## 8.1 当前问题
|
||
|
||
`homeServiceImpl.py` 当前按：
|
||
|
||
- `user_area`
|
||
- `em.areas[].area`
|
||
- `default`
|
||
- `super_admin bypass`
|
||
|
||
混合判定。
|
||
|
||
## 8.2 推荐改法
|
||
|
||
引入：
|
||
|
||
- `current_user.tenant_code`
|
||
- `entry_module_tenants.tenant_code`
|
||
|
||
首页判断改为：
|
||
|
||
1. 用户可见租户集合
|
||
2. 模块绑定租户集合
|
||
3. 交集判断
|
||
|
||
公共模块单独处理：
|
||
|
||
- 通过 `sys_tenants.is_public`
|
||
- 或入口模块配置的公共租户绑定
|
||
|
||
## 8.3 不要再用 `default`
|
||
|
||
建议：
|
||
|
||
- `default` 语义废弃
|
||
- 若是“公共可见”，显式建公共租户
|
||
|
||
---
|
||
|
||
## 9. 前端固定地区名单改造方案
|
||
|
||
## 9.1 当前固定名单热点
|
||
|
||
已确认典型位置：
|
||
|
||
- `EntryModuleNewClient.tsx`
|
||
- `EntryModulesClient.tsx`
|
||
- `cross-checking-access.ts`
|
||
- `RAG` 地区配置相关页面
|
||
- 其他地区筛选组件
|
||
|
||
## 9.2 推荐统一方案
|
||
|
||
新增前端租户 API：
|
||
|
||
- `GET /api/v3/tenants`
|
||
|
||
返回：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"tenant_code": "mz",
|
||
"tenant_name": "梅州",
|
||
"tenant_type": "REGIONAL",
|
||
"is_public": false,
|
||
"is_enabled": true,
|
||
"sort_order": 10
|
||
}
|
||
]
|
||
```
|
||
|
||
前端所有租户下拉统一改成：
|
||
|
||
- 用这个接口拉
|
||
- 不再本地硬编码
|
||
|
||
## 9.3 别名逻辑收缩
|
||
|
||
`cross-checking-access.ts` 这类 `AREA_ALIASES` 逻辑建议删除，改成：
|
||
|
||
- 使用 `tenant_code`
|
||
- `tenant_name` 只展示，不参与判断
|
||
|
||
---
|
||
|
||
## 10. 用户模型改造建议
|
||
|
||
## 10.1 当前情况
|
||
|
||
用户当前有：
|
||
|
||
- `area`
|
||
- `tenant_name`
|
||
|
||
但这两个字段并不等价：
|
||
|
||
- `area` 更像当前业务租户边界
|
||
- `tenant_name` 更像组织树分组信息
|
||
|
||
## 10.2 推荐方向
|
||
|
||
建议新增：
|
||
|
||
- `sso_users.tenant_code`
|
||
|
||
并定义：
|
||
|
||
- `tenant_code`：业务租户边界
|
||
- `tenant_name`：组织展示名称，可保留
|
||
- `area`：兼容旧字段，逐步弱化
|
||
|
||
## 10.3 为什么不能直接复用 tenant_name
|
||
|
||
因为现有 `tenant_name` 明显被当作组织分组字段在用：
|
||
|
||
- RBAC 组织树
|
||
- 用户管理分组
|
||
- 交叉评查成员展示
|
||
|
||
它不适合作为稳定权限租户编码。
|
||
|
||
---
|
||
|
||
## 11. RAG、合同模板、统计的联动影响
|
||
|
||
## 11.1 RAG
|
||
|
||
当前：
|
||
|
||
- `省级`
|
||
- `''`
|
||
- `is_public`
|
||
|
||
混合表达公共范围。
|
||
|
||
建议改造：
|
||
|
||
1. 引入公共租户
|
||
2. 统一 `PUBLIC_MIXED` 的租户集合来源
|
||
3. 不再靠字符串字面值 `省级`
|
||
|
||
## 11.2 合同模板
|
||
|
||
当前：
|
||
|
||
- `省级` 被当作公共模板归属
|
||
|
||
建议：
|
||
|
||
- 用 `public tenant` 或 `headquarters tenant`
|
||
- 不再把展示名硬编码进判断逻辑
|
||
|
||
## 11.3 使用统计
|
||
|
||
统计筛选当前虽然不是入口配置，但未来如果租户扩展：
|
||
|
||
- 地区筛选必须改成租户筛选
|
||
- area 文本不能再假定固定集合
|
||
|
||
---
|
||
|
||
## 12. 交叉评查的潜在影响
|
||
|
||
交叉评查主权限模型是成员关系，不是地区模型。
|
||
|
||
但它仍会受租户化影响：
|
||
|
||
1. 入口模块可见性
|
||
2. 任务参与地区展示
|
||
3. 成员树的租户展示
|
||
|
||
所以它不是第一优先改造对象，但必须纳入兼容分析。
|
||
|
||
---
|
||
|
||
## 13. 数据治理问题
|
||
|
||
在进入租户化之前，必须先做一次脏数据巡检。
|
||
|
||
建议巡检：
|
||
|
||
1. `sso_users.area` 去重值
|
||
2. `leaudit_documents.region` 去重值
|
||
3. `contract_templates.region` 去重值
|
||
4. `rag datasets/apps area` 去重值
|
||
5. `entry_modules.areas[].area` 去重值
|
||
|
||
目的：
|
||
|
||
- 找出 `省局 / 省级 / default / 空串 / 其他历史拼法`
|
||
|
||
只有先做这一步，后续租户映射表才能准确建立。
|
||
|
||
---
|
||
|
||
## 14. 推荐新增文档与接口
|
||
|
||
建议后续再补：
|
||
|
||
1. `租户主数据模型设计.md`
|
||
2. `地区到租户编码映射清洗清单.md`
|
||
3. `入口模块租户配置表迁移方案.md`
|
||
|
||
建议新增接口：
|
||
|
||
1. `GET /v3/tenants`
|
||
2. `POST /v3/tenants`
|
||
3. `PUT /v3/tenants/{TenantCode}`
|
||
4. `GET /v3/tenants/options`
|
||
|
||
其中 `options` 可专门给前端下拉用。
|
||
|
||
---
|
||
|
||
## 15. 推荐实施顺序
|
||
|
||
建议按下面顺序做，而不是一次性全改：
|
||
|
||
1. 建 `sys_tenants`
|
||
2. 做租户脏数据巡检
|
||
3. 入口模块改成租户主数据驱动
|
||
4. 首页入口可见性改成租户集合判断
|
||
5. 前端所有固定地区下拉改成租户接口
|
||
6. 交叉评查/RAG/合同模板里的字符串公共语义收口
|
||
7. 再评估业务主表是否逐步从 `area/region` 迁到 `tenant_code`
|
||
|
||
---
|
||
|
||
## 16. 最终建议
|
||
|
||
当前系统不应再把“地区”视为一个永远固定的枚举集合。
|
||
|
||
从代码和业务实际上看，它已经是“租户边界”了，只是还没有主数据模型支撑。
|
||
|
||
如果现在不做这层抽象，后面每新增一个租户，都会反复踩同一类问题：
|
||
|
||
1. 前端没地方选
|
||
2. 入口模块分配不了
|
||
3. 首页看不到
|
||
4. 公共范围语义冲突
|
||
5. 老字符串拼法继续扩散
|
||
|
||
因此，建议把“地区租户化”作为权限架构之后的下一优先级平台改造项，且入口模块应作为第一落点。
|