docs: document /home route fix and entry-module troubleshooting guide

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.
2026-04-30 10:35:18 +08:00
parent 3a58f19d6c
commit 19c70d23be
3 changed files with 327 additions and 2 deletions
@@ -14,6 +14,9 @@
 - `新系统版_documents_list接口.md`
 - `用户权限与权限点清单.md`
 - `用户权限初始化SQL.sql`
+- `老用户迁移脚本说明.md`
+- `首页入口接口落地说明.md`
+- `系统设置入口恢复说明.md`

 建议阅读顺序：

@@ -21,5 +24,6 @@
 2. 再看 `新系统版_documents_list接口.md`
 3. 再看 `用户权限与权限点清单.md`
 4. 如果要初始化角色与权限数据，再执行 `用户权限初始化SQL.sql`
-5. 如果要理解 worker 并发执行，再结合 `docs/规则编辑/worker并发执行改造方案.md`
-6. 如果要理解底层数据结构，再看 `docs/leaudit/document_schema_design.md`
+5. 如果要迁移老系统用户，再看 `老用户迁移脚本说明.md`
+6. 如果要理解 worker 并发执行，再结合 `docs/规则编辑/worker并发执行改造方案.md`
+7. 如果要理解底层数据结构，再看 `docs/leaudit/document_schema_design.md`
@@ -0,0 +1,133 @@
+# 系统设置入口恢复说明
+
+## 本次恢复范围
+
+本轮不是把整个旧“系统设置域”一次性全部接回，而是先恢复最关键的两块：
+
+- `入口模块管理`：`/entry-modules`
+- `角色权限管理`：`/role-permissions`
+
+同时恢复首页右上角 `系统设置` 入口，但当前只会进入上述两个已经承接的新能力。
+
+## 当前策略
+
+### 1. 首页与菜单
+
+- 后端 `/api/rbac/user/routes` 已重新返回 `/settings`
+- `/settings` 当前子路由只保留：
+  - `/entry-modules`
+  - `/role-permissions`
+- `config-lists / document-types / prompts` 仍未重新放开
+
+### 2. 入口模块管理
+
+已承接后端接口：
+
+- `GET /api/v3/entry-modules`
+- `GET /api/v3/entry-modules/{id}`
+- `POST /api/v3/entry-modules`
+- `PUT /api/v3/entry-modules/{id}`
+- `DELETE /api/v3/entry-modules/{id}`
+- `POST /api/v3/entry-modules/{id}/image`
+
+数据源：
+
+- 表：`leaudit_entry_modules`
+- 图标：OSS `leaudit` 桶
+
+说明：
+
+- 前端展示字段 `path` 现在对应数据库 `icon_path`
+- 前端编辑页面中的跳转路径仍走数据库 `path`
+
+### 3. 角色权限管理
+
+已承接后端接口：
+
+- `GET /api/v3/rbac/roles`
+- `POST /api/v3/rbac/roles`
+- `PUT /api/v3/rbac/roles/{roleId}`
+- `DELETE /api/v3/rbac/roles/{roleId}`
+- `GET /api/v3/rbac/users`
+- `POST /api/v3/rbac/users/{userId}/roles`
+- `DELETE /api/v3/rbac/users/{userId}/roles/{roleId}`
+- `GET /api/v3/rbac/users/{userId}/roles`
+- `GET /api/rbac/roles/{roleId}/routes`
+- `PUT /api/rbac/roles/{roleId}/routes`
+- `GET /api/v3/rbac/role-permissions`
+- `POST /api/v3/rbac/role-permissions`
+- `GET /api/v3/routes`
+- `GET /api/v3/routes/{routeId}/permissions`
+
+数据源：
+
+- `roles`
+- `sso_users`
+- `user_role`
+- `sys_routes`
+- `role_route`
+- `permissions`
+- `role_permissions`
+
+## 自动补种策略
+
+为避免当前数据库里的 `sys_routes / permissions` 与现前端路由结构不一致，这次后端在 RBAC 管理接口里增加了“按需补种”：
+
+- 自动补齐最小可用路由：
+  - `/home`
+  - `/chat-with-llm`
+  - `/files`
+  - `/files/upload`
+  - `/documents`
+  - `/settings`
+  - `/entry-modules`
+  - `/role-permissions`
+- 自动补齐入口模块管理、角色权限管理所需的权限定义
+
+这样做的目的，是先把“入口模块 + 权限架构”真正跑通，不再依赖旧系统那套不匹配的 `sys_routes` 种子。
+
+## 首页入口联动提醒
+
+入口模块管理恢复后，首页入口是否显示，不只取决于 `leaudit_entry_modules` 本身，还取决于：
+
+- 入口模块 `path`
+- `sys_routes`
+- `role_route`
+
+例如这次的真实案例：
+
+- `内部公文` 入口模块配置存在
+- 其跳转路径是 `/home`
+- 但 `provincial_admin` 之前没有 `/home` 的 `role_route` 授权
+- 所以首页接口不会返回该入口
+
+已处理动作：
+
+- 2026-04-29 已补充 `provincial_admin -> /home` 路由授权
+
+后续如果首页入口“配置了却不显示”，先不要只盯 `leaudit_entry_modules`，要连同下面三层一起查：
+
+1. `leaudit_entry_modules.path`
+2. `sys_routes.route_path`
+3. `role_route(role_id, route_id, status)`
+
+## 暂未恢复项
+
+以下仍未在本轮开放：
+
+- `config-lists`
+- `document-types`
+- `prompts`
+
+原因：
+
+- 当前数据库里没有旧 `configurations` 表
+- `document-types / prompts` 仍依赖另一批尚未承接完的后台能力
+
+## 下一步建议
+
+后续按这个顺序继续最稳：
+
+1. 先联调验证 `入口模块管理` 与 `角色权限管理`
+2. 再补 `config-lists` 新表与新接口
+3. 最后恢复 `document-types / prompts`
@@ -0,0 +1,188 @@
+# 首页入口接口落地说明
+
+## 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` 的图片路径语义
+
+这样做的目的：
+
+- 先把首页入口能力真正跑起来
+- 不阻塞当前前后端联调
+- 后续若需要长期治理，再补结构性字段升级