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
@@ -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`