# 入口模块租户配置表迁移方案

> 适用范围：首页入口模块、入口模块管理页、首页可见性判定、交叉评查入口等依赖 `leaudit_entry_modules.areas` 的场景  
> 文档定位：把当前入口模块的 `areas JSONB` 从自由字符串配置升级为“租户关系表 + 主数据校验”的落地方案。

---

## 1. 结论先行

当前入口模块是整个“地区租户化”里最明显、最优先、最适合先落地的切入点。

原因有 4 个：

1. 问题最直观，用户已经明确感知到“新租户没法分配入口”
2. 当前设计最脆弱，`areas JSONB` 没有主数据约束
3. 前后端都存在固定地区假设
4. 首页和交叉评查都依赖它做可见性判断

因此建议先把入口模块从：

1. `leaudit_entry_modules + areas JSONB`

升级为：

1. `leaudit_entry_modules`
2. `leaudit_entry_module_tenants`
3. `sys_tenants`

---

## 2. 当前问题深挖

## 2.1 现有表结构问题

当前表：

```sql
leaudit_entry_modules(
  id,
  name,
  description,
  path,
  icon_path,
  areas JSONB,
  sort_order,
  is_enabled
)
```

问题：

1. `areas` 是自由 JSON
2. `area` 值没有外键约束
3. `enabled/sort_order` 与租户主数据重复
4. 无法防止写入不存在的租户
5. 无法直接做关系查询和索引优化

## 2.2 后端当前风险

当前 `EntryModuleAdminServiceImpl.py`：

1. 创建和更新时直接把前端传入 `areas` 序列化成 JSON
2. 没有合法租户校验
3. 没有和用户租户主数据对齐

当前 `homeServiceImpl.py`：

1. 直接按 `user_area = area_item->>'area'`
2. 支持 `default` 兜底
3. `super_admin` 特判 bypass

这意味着：

1. 可见性规则绑定在脏字符串上
2. 新租户即使进库，首页也可能因为字符串不一致看不到

## 2.3 前端当前风险

当前 `EntryModuleNewClient.tsx`：

1. 地区候选列表硬编码为固定 5 项

当前 `cross-checking-access.ts`：

1. 用固定地区别名数组判断入口可见性
2. `provincial_admin` 自动补 `省局`

这意味着：

1. 后端就算支持新租户，前端也无法选择
2. 首页入口和交叉评查入口会出现不一致

---

## 3. 目标数据模型

## 3.1 保留主表

保留：

1. `leaudit_entry_modules`

用于表达模块本身：

1. 名称
2. 描述
3. 跳转路径
4. 图标
5. 排序
6. 启用状态

## 3.2 新增关系表

建议新增：

```sql
CREATE TABLE IF NOT EXISTS leaudit_entry_module_tenants (
    id              BIGSERIAL PRIMARY KEY,
    entry_module_id BIGINT NOT NULL REFERENCES leaudit_entry_modules(id),
    tenant_code     VARCHAR(64) NOT NULL,
    is_enabled      BOOLEAN NOT NULL DEFAULT TRUE,
    sort_order      INT NOT NULL DEFAULT 0,
    visibility_scope VARCHAR(32) NOT NULL DEFAULT 'TENANT',
    ext             JSONB NOT NULL DEFAULT '{}'::jsonb,
    created_at      TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMP NOT NULL DEFAULT NOW(),
    deleted_at      TIMESTAMP NULL,
    UNIQUE (entry_module_id, tenant_code)
);
```

## 3.3 为什么关系表足够

关系表解决了当前 JSON 方案的关键缺陷：

1. 可按 `tenant_code` 精确筛选
2. 可直接做唯一约束
3. 可扩展更多可见性字段
4. 可做索引和分页查询
5. 能和租户主数据自然联表

---

## 4. 字段设计建议

## 4.1 `tenant_code`

必须来自 `sys_tenants.tenant_code`，不允许任意字符串。

## 4.2 `is_enabled`

表示该入口是否对该租户生效。

说明：

1. 模块总开关在 `leaudit_entry_modules.is_enabled`
2. 租户粒度开关在 `leaudit_entry_module_tenants.is_enabled`

## 4.3 `sort_order`

表示该模块在该租户视角下的局部排序。

如果当前不需要租户级排序，也建议先保留，因为后续：

1. 不同租户首页布局可能不同
2. 试点租户可能需要不同优先级

## 4.4 `visibility_scope`

建议预留：

1. `TENANT`
2. `PUBLIC`
3. `HEADQUARTER_ONLY`

当前先以 `TENANT` 为主，但保留扩展空间，避免以后再次改表。

---

## 5. 接口改造建议

## 5.1 管理端列表接口

当前：

1. `GET /api/v3/entry-modules?area=...`

建议后续改为：

1. `GET /api/v3/entry-modules?tenant_code=...`

兼容期：

1. `area` 仍可保留，但后端先归一成 `tenant_code`

## 5.2 管理端创建/更新接口

当前请求体：

```json
{
  "name": "交叉评查",
  "route_path": "/cross-checking",
  "areas": [
    {"area": "梅州", "enabled": true, "sort_order": 1}
  ]
}
```

建议升级为：

```json
{
  "name": "交叉评查",
  "route_path": "/cross-checking",
  "tenants": [
    {"tenant_code": "MZ", "enabled": true, "sort_order": 1}
  ]
}
```

兼容策略：

1. 后端 DTO 同时接收 `areas` 和 `tenants`
2. 兼容期内优先使用 `tenants`
3. `areas` 走别名归一后再写关系表

## 5.3 首页获取入口接口

当前：

1. `HomeServiceImpl.GetEntryModules(UserId)`

建议内部改造为：

1. 先解析用户 `tenant_code`
2. 再根据 `leaudit_entry_module_tenants` 判断可见性

SQL 方向应改成：

1. 联表 `leaudit_entry_module_tenants`
2. 不再扫描 `jsonb_array_elements`

---

## 6. 前端改造建议

## 6.1 入口模块新建页

当前问题：

1. `AREA_OPTIONS` 写死

建议：

1. 页面加载时调用租户主数据接口
2. 用 `tenant_code` 作为 value
3. 用 `tenant_name` 作为 label
4. 表单字段从 `selectedAreas` 改为 `selectedTenantCodes`

## 6.2 入口模块列表页筛选

建议：

1. 筛选条件改为租户下拉
2. 后端接收 `tenant_code`
3. 列表展示使用租户名称而非裸字符串

## 6.3 交叉评查入口判定

当前 `cross-checking-access.ts` 不应再：

1. 猜测地区别名
2. `includes("省")`
3. 针对 `provincial_admin` 自动补 `省局`

建议：

1. 登录态透出 `tenant_code`
2. 首页接口直接返回“当前用户可见模块”
3. 前端不再做租户匹配推断

---

## 7. 迁移策略

## 7.1 第一步：建新表，不改老表

先新增：

1. `leaudit_entry_module_tenants`

此时：

1. 旧 `areas JSONB` 继续存在
2. 新服务层支持双写

## 7.2 第二步：把历史 JSON 展开入新表

迁移逻辑：

1. 读取 `leaudit_entry_modules.areas`
2. 对每个 `area` 执行租户归一
3. 写入 `leaudit_entry_module_tenants`
4. 对映射失败的值输出复核清单

## 7.3 第三步：服务层读新表

顺序建议：

1. 管理端详情/列表先从新表组装返回
2. 首页可见性改为读新表
3. 交叉评查入口依赖首页接口结果，不再本地推断

## 7.4 第四步：前端提交新结构

前端提交统一改成 `tenant_code` 后：

1. `areas` 字段只保留兼容
2. 新表成为唯一写入目标

## 7.5 第五步：下线旧 JSON

待所有读写都切到新表后：

1. `areas` 字段可以保留为快照
2. 或在后续版本彻底废弃

---

## 8. 兼容期设计

## 8.1 DTO 兼容

建议 DTO 增加：

1. `tenants: list[EntryModuleTenantDTO] | None`

保留：

1. `areas: list[EntryModuleAreaDTO] | None`

优先级：

1. `tenants` 优先
2. `areas` 仅用于历史前端兼容

## 8.2 VO 兼容

接口返回建议同时包含：

1. `tenants`
2. `areas`

其中：

1. `tenants` 是标准结构
2. `areas` 是兼容展示结构

避免一次性打崩旧页面。

## 8.3 SQL seed 兼容

当前：

1. `seed_home_entry_modules.sql`
2. `seed_govdoc_entry_module.sql`

都直接写死 `areas JSONB`。

建议：

1. 先保留旧插入
2. 新增对应关系表 seed
3. 后续把内置入口的租户分配从 JSON 迁到关系表

---

## 9. 需要同步改的代码点

后端重点：

1. `entryModuleDto.py`
2. `entryModuleAdminServiceImpl.py`
3. `homeServiceImpl.py`
4. `entryModuleController.py`
5. 相关 VO 定义

前端重点：

1. `EntryModuleNewClient.tsx`
2. `entry-modules` API 封装
3. 首页入口 hooks
4. `cross-checking-access.ts`

数据重点：

1. `schema_v2_add_evaluation_tables.sql`
2. `seed_home_entry_modules.sql`
3. `seed_govdoc_entry_module.sql`

---

## 10. 风险清单

## 10.1 首页入口可能瞬时丢失

如果首页先切新表，但历史数据尚未迁入新关系表，会导致所有入口不可见。

所以顺序必须是：

1. 先迁数据
2. 再切读逻辑

## 10.2 新旧字段并存期可能双写不一致

必须规定：

1. 标准源为新关系表
2. 旧 `areas` 只做兼容输出或快照

## 10.3 交叉评查入口可能与首页结果不一致

因为当前它自己做了一套前端地区推断。

必须同步下线这套本地逻辑。

## 10.4 自定义新租户仍可能被旧 seed 覆盖

如果后续还执行写死地区的 seed，会把新租户体系重新拉回旧模型。

---

## 11. 验收标准

入口模块迁移完成后，至少应满足：

1. 新增租户后，无需改前端常量即可在管理页被选中
2. 管理端不能给不存在的租户分配入口
3. 首页入口仅按 `tenant_code` 判断，不再比对中文地区字符串
4. 交叉评查入口不再依赖固定地区别名数组
5. 历史入口模块在旧租户下可见性与迁移前一致
6. 新租户创建后，可以直接分配现有入口模块

---

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

本文档主要解决：

1. 入口模块为什么是租户化第一改造点
2. 当前 `areas JSONB` 设计具体哪里不够
3. 关系表应该怎么建
4. 首页和交叉评查为什么会被连带影响
5. 迁移顺序应该怎么安排

建议联动阅读：

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)