# 首页入口接口落地说明

## 1. 已落地内容

- 后端新增统一接口：`GET /api/home/entry-modules`
- 后端来源统一收口到：
  - `leaudit_entry_modules`
  - `leaudit_document_types`
  - `sys_routes + role_route`（仅做页面可见性补充校验）
- 前端首页改为只调用后端统一接口，不再直接查 PostgREST 的 `entry_modules + document_types`
- 前端首页不再手工注入“智慧法务助手”模块

## 2. 当前接口返回语义

返回结构：

```json
{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "name": "合同智能审查",
      "description": "合同类文档入口，进入合同检索与评查主页",
      "targetPath": "/contract-template/search",
      "routePath": "/contract-template/search",
      "iconPath": "entryModule/contract.png",
      "sortOrder": 10,
      "requiresDocumentTypes": true,
      "areas": [],
      "documentTypes": [
        {
          "id": 1,
          "name": "建设工程合同",
          "code": "contract.construction.general"
        }
      ]
    }
  ]
}
```

字段说明：

- `targetPath`
  - 首页点击后真正跳转的前端路由
- `routePath`
  - 当前阶段与 `targetPath` 同值
  - 预留给后续把“展示路径”和“权限判断路径”拆开
- `iconPath`
  - 模块图标路径
  - 若以 `/images/` 开头，前端按静态资源处理
  - 否则前端按 `DOCUMENT_URL + iconPath` 处理
- `requiresDocumentTypes`
  - `true`：模块必须挂文档类型才能进入
  - `false`：允许零文档类型直接进入
  - 当前兼容规则：
    - `/chat-with-llm/chat` → `false`
    - `/cross-checking` → `false`
    - 其他路径 → `true`

## 3. 当前过滤逻辑

后端按以下顺序过滤首页入口：

1. `leaudit_entry_modules.is_enabled = true`
2. `leaudit_entry_modules.deleted_at is null`
3. 地区过滤
   - `super_admin / provincial_admin` 跳过地区过滤
   - 其他用户按 `sso_users.area` 匹配 `leaudit_entry_modules.areas`
   - 若 `areas` 为空，则视为全地区可见
4. 页面权限过滤
   - 若 `sys_routes` 里存在与 `path` 相同的页面路由，则要求当前用户角色在 `role_route` 中已授权
   - 若 `sys_routes` 尚未配置该路由，则当前阶段放行，不阻塞首页展示

### 3.1 `/home` 路由补充说明（2026-04-29）

这次联调里出现过一个容易忘的问题：

- `leaudit_entry_modules` 里的 `内部公文` 入口配置本身是存在的
- 它当前配置的跳转路径是 `path = /home`
- 但如果当前角色在 `role_route` 里没有 `/home` 的启用记录，首页接口会把这个入口过滤掉

实际排查结论：

- 不是“内部公文入口模块丢了”
- 也不是“地区过滤没命中”
- 而是“入口模块目标路径存在，但角色没有对应页面路由授权”

本次已补充：

- 给 `provincial_admin` 角色补上 `/home` 的 `role_route`

因此后续如果再次出现“首页某个入口配置明明在库里，但前端没显示”，优先按下面顺序排查：

1. `leaudit_entry_modules` 里该入口是否存在且 `is_enabled = true`
2. 该入口 `areas` 是否覆盖当前用户地区
3. 该入口 `path` 对应的页面路由是否存在于 `sys_routes`
4. 当前角色是否在 `role_route` 中对该 `path` 有 `status = 1`

特别注意：

- `内部公文 -> /home` 这类首页型入口，对 `role_route` 很敏感
- 只配入口模块、不配页面路由授权，首页接口不会放出来

## 4. 当前表语义

### `leaudit_entry_modules`

当前阶段它只负责“首页业务入口配置”，核心字段语义如下：

- `name`：首页模块名称
- `description`：首页模块描述
- `path`：当前阶段同时承担 `targetPath / routePath`
- `icon_path`：首页卡片图标
- `areas`：地区可见范围
- `sort_order`：首页排序
- `is_enabled`：是否启用

### `leaudit_document_types`

- `entry_module_id`：文档类型归属的首页入口模块
- 首页进入某模块后，前端把该模块下的 `documentTypes[].id` 写入 `sessionStorage.documentTypeIds`
- 后续列表、首页统计、规则页面仍复用现有 `documentTypeIds` 逻辑

## 5. 前端改造点

已改造：

- `new_doc_review/app/api/home/home.ts`
  - 改为请求 `/home/entry-modules`
- `new_doc_review/app/routes/_index.tsx`
  - 直接使用后端返回的 `targetPath`
  - 直接使用后端返回的 `iconPath`
  - 按 `requiresDocumentTypes` 判断是否允许进入

未改造但仍兼容：

- 系统设置入口仍沿用现有 `getUserRoutesByRole()` 逻辑
- 交叉评查专属端口模式仍保留

## 6. 初始化数据

已补脚本：

- `scripts/seed_home_entry_modules.sql`

脚本内容：

- 按老系统真实数据初始化 5 个入口模块：
  - `合同管理`
  - `案卷智能评查`
  - `内部公文`
  - `智慧法务助手`
  - `交叉评查`
- 其中：
  - `path` 存前端跳转路由
  - `icon_path` 存老系统入口图片路径
- 自动把：
  - `contract.%` 绑定到 `合同管理`
  - `行政卷宗.%` 绑定到 `案卷智能评查`
  - `NBGW / internal.document` 绑定到 `内部公文`

## 7. 当前兼容性取舍

这次落地刻意没有直接改库结构新增：

- `module_key`
- `module_type`
- `allow_empty_types`
- `target_path`
- `route_path`

而是先用现有字段完成可运行版本：

- `path` 兼容成 `targetPath + routePath`
- 特殊模块是否允许空文档类型，先按路径规则判断

同时和老系统保持语义对齐：

- `icon_path` 承接老库 `entry_modules.path` 的图片路径语义

这样做的目的：

- 先把首页入口能力真正跑起来
- 不阻塞当前前后端联调
- 后续若需要长期治理，再补结构性字段升级