wren
19c70d23be
Record the internal-document entry module issue where /home was missing from role_route, causing the entry to be filtered out. Add troubleshooting order and cross-reference between entry modules, sys_routes, and role_route.
189 lines
5.6 KiB
Markdown
189 lines
5.6 KiB
Markdown
# 首页入口接口落地说明
|
||
|
||
## 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` 的图片路径语义
|
||
|
||
这样做的目的：
|
||
|
||
- 先把首页入口能力真正跑起来
|
||
- 不阻塞当前前后端联调
|
||
- 后续若需要长期治理，再补结构性字段升级
|