leaudit-platform-backend/docs/接口/首页入口接口落地说明.md

首页入口接口落地说明

1. 已落地内容

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

2. 当前接口返回语义

返回结构：

{
  "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 的图片路径语义

这样做的目的：

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