leaudit-platform-backend/docs/入口模块/入口模块绑定最终设计方案.md

# 入口模块绑定最终设计方案

> 适用项目：`leaudit-platform`
>
> 参考来源：
> - 老系统：`/home/wren-dev/Porject/docauditai`
> - 新前端：`/home/wren-dev/Porject/leaudit-platform/new_doc_review`
> - 新后端：`/home/wren-dev/Porject/leaudit-platform/fastapi_modules`

---

## 1. 这份文档解决什么问题

本方案要解决的是：

1. 老系统“入口模块”到底是什么语义
2. 新系统里 `entry_modules / document_types / sys_routes / role_route` 各自该负责什么
3. 首页入口模块应该由谁来组装
4. 现有逻辑有哪些遗漏和隐患
5. 下一步如何把它收口成一套稳定方案

这份文档的目标不是直接讲实现细节，而是先把**边界、语义、数据流、遗漏点**固定下来，避免后续继续前后端双写规则。

---

## 2. 结论先行

### 2.1 核心结论

老系统里的“入口模块”**不是权限系统**，而是**首页业务入口编排系统**。

它的职责是：

- 决定首页显示哪些入口卡片
- 给每个入口卡片绑定一组文档类型
- 按地区启用/禁用入口

它**不负责**：

- 控制用户是否可以访问某个页面
- 控制用户是否可以调用某个 API
- 替代 RBAC 路由菜单系统

真正的权限系统始终是：

- `sys_routes`
- `role_route`
- `permissions`
- `role_permissions`

### 2.2 新系统必须收口的总原则

新系统应该明确分成三层：

1. **首页入口层**
   - 数据源：`leaudit_entry_modules`
   - 作用：决定首页显示什么入口

2. **业务归类层**
   - 数据源：`leaudit_document_types.entry_module_id`
   - 作用：决定某入口下挂哪些文档类型

3. **权限控制层**
   - 数据源：`sys_routes / role_route / permissions / role_permissions`
   - 作用：决定用户是否真的能访问页面和动作

### 2.3 当前已落地接口口径

当前首页入口已经统一走：

- `GET /api/home/entry-modules`

当前返回结构核心字段包括：

- `id`
- `name`
- `description`
- `targetPath`
- `routePath`
- `iconPath`
- `sortOrder`
- `requiresDocumentTypes`
- `areas`
- `documentTypes`

当前过滤顺序为：

1. `leaudit_entry_modules.is_enabled = true`
2. `leaudit_entry_modules.deleted_at is null`
3. 地区过滤
4. 若目标页面已存在于 `sys_routes`，则继续做 `role_route` 权限过滤

这意味着首页入口已经不是前端自己拼装，而是后端统一组装后返回。

---

## 3. 老系统深度分析结论

## 3.1 首页入口不是从 sys_routes 直接来

老系统首页入口不是直接根据 RBAC 路由树生成，而是单独查询入口模块配置。

对应证据：

- 老系统入口模块服务：
  - `/home/wren-dev/Porject/docauditai/app/services/entry_module_service.py`
- 老系统入口模块路由：
  - `/home/wren-dev/Porject/docauditai/app/routes/entry_modules.py`
- 老系统文档类型服务：
  - `/home/wren-dev/Porject/docauditai/app/services/document_type_service.py`

### 实际链路

老系统首页逻辑本质是：

1. 查 `entry_modules`
2. 按 `areas` 做地区过滤
3. 对每个入口模块，再查 `document_types where entry_module_id = module.id`
4. 拼成首页卡片
5. 点击卡片后跳转目标页面
6. 目标页面再走 RBAC 校验

所以首页入口和页面权限本来就是两套体系。

---

## 3.2 老系统中 entry_modules 的真实职责

老系统 `entry_modules` 本质上存的是“首页业务入口卡片配置”。

典型字段语义：

- `id`：入口模块主键
- `name`：入口名称
- `description`：说明
- `path`：旧系统里语义不稳定，常被当成资源/图片路径使用
- `areas`：地区配置
- `created_at / updated_at`

### 关键观察

老系统里 `path` 不是一个稳定可靠的“点击后跳转路由字段”。

也就是说：

- 它并不总是纯前端路由
- 它常常承担资源路径、展示配置、模块图片等混合语义

这也是老系统最容易让后续维护者误解的地方之一。

---

## 3.3 文档类型和入口模块的关系

老系统文档类型是通过 `entry_module_id` 绑定到入口模块的。

这说明：

- 一个入口模块下面挂很多文档类型
- 一个文档类型归属于一个入口模块

这个设计本身是合理的，属于“业务归类关系”，不属于“权限关系”。

### 当前判断

除非未来明确出现“一个文档类型必须出现在多个入口模块”的业务需求，否则：

- 新系统应继续保留 `entry_module_id`
- 没必要提前拆成中间表

---

## 3.4 真正的页面权限来自 RBAC

老系统页面权限来源一直是：

- `sys_routes`
- `role_route`

动作/API 权限来源是：

- `permissions`
- `role_permissions`

这意味着在老系统中可能出现：

1. 首页能看到某个入口模块
2. 点击后跳到某个页面
3. 页面又因为 RBAC 不通过而拒绝访问

这是老系统长期存在的结构性问题，不是 Bug，而是设计分层没有被清楚说明。

---

## 4. 新系统最终语义边界

## 4.1 `leaudit_entry_modules`

### 负责

- 首页显示哪些业务入口
- 每个入口的名称、图标、排序、地区启用规则
- 每个入口点击后去哪

### 不负责

- 页面访问权限
- API 权限
- 替代路由表

---

## 4.2 `leaudit_document_types`

### 负责

- 定义系统支持的文档类型
- 通过 `entry_module_id` 归属到某个入口模块

### 不负责

- 决定首页是否展示入口模块
- 决定菜单权限

---

## 4.3 `sys_routes / role_route`

### 负责

- 页面路由菜单权限
- 用户可访问哪些页面

### 不负责

- 首页模块展示编排
- 文档类型归类

---

## 4.4 `permissions / role_permissions`

### 负责

- API 权限
- 动作按钮权限
- 数据范围权限

### 不负责

- 首页入口展示
- 文档类型归属

---

## 5. 新系统最终数据模型建议

## 5.1 `leaudit_entry_modules` 建议字段

当前表建议正式化为以下语义：

- `id`
- `module_key`
- `name`
- `description`
- `icon_path`
- `target_path`
- `route_path`
- `module_type`
- `allow_empty_types`
- `areas`
- `sort_order`
- `is_enabled`
- `create_time`
- `update_time`

### 字段解释

#### `module_key`

稳定的业务标识，用于程序判断，不可依赖 `name`。

示例：

- `contract`
- `case_review`
- `assistant`
- `cross_review`

#### `icon_path`

首页卡片图标/图片路径。

应从旧的 `path` 语义中剥离出来，单独承担展示职责。

#### `target_path`

用户点击首页卡片后实际跳转的前端路径。

示例：

- `/contract-template/search`
- `/home`
- `/chat-with-llm/chat`
- `/cross-checking`

#### `route_path`

与 RBAC 路由树关联的目标页面路径，用于做“当前用户是否真的有访问权限”的判断。

通常可与 `target_path` 相同，但不强制必须相同。

#### `module_type`

建议枚举：

- `document`
- `assistant`
- `cross_review`
- `settings_link`

#### `allow_empty_types`

控制“没有绑定文档类型时是否仍然允许显示”。

建议：

- 文档类模块：`false`
- 助手类模块：`true`
- 交叉评查类模块：`true`

---

## 5.2 `leaudit_document_types`

继续保留：

- `entry_module_id`

表示“该文档类型归属哪个入口模块”。

### 当前不建议做的事

暂不建议改成：

- `leaudit_entry_module_document_type_bindings`

因为当前没有明确“一种文档类型要同时挂多个入口”的需求。

---

## 6. 首页统一接口最终设计

建议新增：

- `GET /api/home/entry-modules`

由后端直接根据当前登录用户返回首页入口列表。

前端不再自己拼 `entry_modules + document_types + area + 跳转规则`。

---

## 6.1 接口职责

后端统一完成：

1. 识别当前用户
2. 读取用户角色
3. 读取用户地区
4. 查询可用入口模块
5. 按地区过滤
6. 按页面权限做一次 RBAC 二次过滤
7. 挂载该入口下的文档类型
8. 返回最终首页可见入口列表

---

## 6.2 建议返回结构

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": 1,
        "moduleKey": "contract",
        "name": "合同管理",
        "description": "合同智能审核与模板管理",
        "iconPath": "static/modules/contract.png",
        "targetPath": "/contract-template/search",
        "routePath": "/contract-template/search",
        "moduleType": "document",
        "allowEmptyTypes": false,
        "sortOrder": 10,
        "documentTypes": [
          {
            "id": 9,
            "code": "contract.sale",
            "name": "买卖合同"
          }
        ]
      }
    ]
  }
}
```

---

## 7. 首页统一接口的推荐过滤规则

## 7.1 基础过滤

必须满足：

- `is_enabled = true`

---

## 7.2 地区过滤

### 省级管理员

- `provincial_admin` 可查看所有启用入口模块

### 地市管理员 / 普通用户

- `admin`
- `common`

仅可看到 `areas` 中当前 `user.area` 且 `enabled = true` 的模块。

### 重要约束

地区过滤必须在后端完成，不能信前端传 area。

---

## 7.3 RBAC 二次过滤

如果入口模块配置了 `route_path`，则需要再检查当前用户是否有该页面的访问权限。

### 目的

避免出现：

- 首页看得到入口
- 点进去却被 RBAC 拒绝

### 推荐做法

基于当前用户角色集合，查询：

- `sys_routes.route_path = route_path`
- 是否被 `role_route` 授权

若未授权，则该入口模块不返回。

---

## 7.4 文档类型过滤

### 对 `module_type = document`

必须至少有一个启用中的文档类型，否则不返回。

### 对 `module_type = assistant / cross_review`

允许没有文档类型，只要模块本身启用并通过权限检查即可返回。

---

## 7.5 排序规则

建议优先级：

1. `areas[].sort_order`（如果当前地区有配置）
2. `leaudit_entry_modules.sort_order`
3. `id`

---

## 8. 前端必须删掉的旧逻辑

## 8.1 不能再由前端自己查 `entry_modules`

当前旧逻辑：

- 前端查入口模块
- 前端按地区过滤
- 前端再查文档类型

这会导致规则散落在前端，不利于后端统一治理。

应改为：

- 前端只调用 `GET /api/home/entry-modules`

---

## 8.2 不能再按模块名硬编码跳转

当前风险逻辑：

- 模块名包含“合同” -> `/contract-template/search`
- 模块名是“智慧法务助手” -> `/chat-with-llm/chat`

这类逻辑必须移除。

应改为直接使用后端返回的：

- `targetPath`

---

## 8.3 不能再在前端默认硬塞特殊模块

例如：

- “智慧法务助手”

不应再由前端强行 `push()` 到入口列表里。

必须和普通模块一样进入 `leaudit_entry_modules` 正式配置。

这样做的好处：

- 权限统一
- 排序统一
- 是否启用统一
- 图标统一
- 后台管理统一

---

## 9. 当前逻辑遗漏点深度检查

下面是本次分析中确认存在或高概率会出现的遗漏点。

## 9.1 首页可见 ≠ 页面可访问

这是老系统就存在的问题。

如果首页只按 `entry_modules` 过滤，不按 RBAC 再过滤，就会出现：

- 首页看到入口
- 点进去又被页面权限拦住

### 结论

首页接口必须做 RBAC 二次过滤。

---

## 9.2 `path` 字段语义不稳定

老系统里 `entry_modules.path` 混杂：

- 图片路径
- 资源路径
- 可能被误当成前端路由

### 结论

新系统不能继续复用一个 `path` 字段承担两种含义。

必须拆成：

- `icon_path`
- `target_path`

---

## 9.3 特殊模块没有文档类型时会被误过滤

如果首页统一规则是“模块下必须有文档类型”，那么：

- 智慧法务助手
- 交叉评查

这类模块会被错误隐藏。

### 结论

必须引入：

- `module_type`
- `allow_empty_types`

---

## 9.4 省级管理员是否应该看到所有模块

这个规则必须固定，不然以后省级账号行为会不一致。

### 建议

- `provincial_admin` 看全部已启用入口
- 但仍需受目标页面 RBAC 权限约束

---

## 9.5 文档类型全部停用后，文档类入口是否显示

如果一个“合同管理”模块下面一个启用文档类型都没有，继续显示没有意义。

### 建议

- `module_type = document` 且无可用文档类型 -> 不显示
- `assistant / cross_review` 不受此规则影响

---

## 9.6 入口模块与左侧菜单不是同一概念

首页入口模块是“业务入口卡片”，左侧菜单是“页面路由树”。

如果不写清楚，后面会经常出现误解：

- 为什么首页有入口，但侧边栏没有？
- 为什么有路由权限，但首页不显示？

### 结论

文档中必须明确：

- 首页入口 = 业务编排
- 左侧菜单 = RBAC 路由

---

## 9.7 交叉评查专属模式不应混入入口模块业务规则

当前前端已有：

- `CROSS_CHECKING_ONLY_MODE`

它本质上是部署态开关，不是入口模块自身规则。

### 结论

该逻辑应作为部署模式单独处理，不要污染 `entry_modules` 基础语义。

---

## 9.8 首页入口上下文仍然需要保留

即使首页入口最终完全由后端返回，前端仍然建议保留：

- `selectedModuleId`
- `selectedModuleName`
- `documentTypeIds`

写入 `sessionStorage`

### 原因

后续页面仍然需要知道：

- 当前用户是从哪个入口进入的
- 当前模块下允许哪些文档类型

---

## 10. 新系统最终推荐方案

## 10.1 强约束

新系统正式规则建议固定如下：

1. 首页入口只认 `leaudit_entry_modules`
2. 文档类型归属只认 `leaudit_document_types.entry_module_id`
3. 页面访问权限只认 `sys_routes + role_route`
4. API/动作权限只认 `permissions + role_permissions`
5. 首页入口列表必须由后端统一接口生成
6. 前端只能消费最终结果，不再自己拼规则

---

## 10.2 最终推荐模型

### 模块主数据

- `leaudit_entry_modules`

### 文档类型归属

- `leaudit_document_types.entry_module_id`

### 页面访问权限

- `sys_routes`
- `role_route`

### 动作/API 权限

- `permissions`
- `role_permissions`

---

## 10.3 首页统一接口

- `GET /api/home/entry-modules`

由后端返回：

- 当前用户可见的入口模块
- 每个入口模块的目标跳转路径
- 每个入口模块挂载的文档类型列表

---

## 11. 后续代码改造建议

本次先定方案，代码实现建议按以下顺序推进。

### 阶段 1：后端收口

1. 新增首页入口接口
2. 后端实现地区过滤
3. 后端实现 RBAC 二次过滤
4. 后端挂载 `document_types`

### 阶段 2：前端收口

1. 首页改为只调用后端统一接口
2. 删除前端拼 `entry_modules + document_types` 的逻辑
3. 删除按模块名硬编码跳转
4. 删除前端默认注入“智慧法务助手”

### 阶段 3：表结构正式化

1. 给 `leaudit_entry_modules` 增加：
   - `module_key`
   - `target_path`
   - `route_path`
   - `module_type`
   - `allow_empty_types`
2. 若历史字段 `path` 仍在使用，则明确其迁移方向：
   - 老 `path` -> `icon_path`

---

## 12. 当前审阅建议

本方案建议你重点审阅以下 5 个点：

1. 是否同意“入口模块不是权限系统”的边界
2. 是否同意首页入口改为后端统一生成
3. 是否同意给 `entry_modules` 新增 `module_key / target_path / route_path / module_type / allow_empty_types`
4. 是否同意“智慧法务助手”这类特殊入口也必须正式落表
5. 是否同意“首页可见”和“页面可访问”保留两层校验，但由后端首页接口统一兜一次

---

## 13. 一句话版最终结论

新系统应把“首页入口模块”正式定义为**首页业务入口编排层**，把“文档类型绑定”定义为**业务归类层**，把“页面/API权限”继续留在 **RBAC 层**，并由后端统一输出首页入口列表，彻底结束前端自己拼入口、自己判地区、自己硬编码跳转的旧模式。