实现系统管理菜单树增强接口

2026-07-16 11:57:25 +07:00
parent 93ecfb08a9
commit 5390b8f71b
12 changed files with 1042 additions and 10 deletions
--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -71,7 +71,7 @@
 | `GET/POST/PUT /api/admin/users...` | 系统管理用户维护 | 需要 Bearer token 和 `SYSTEM_USER_MANAGE`；用户 ID 返回字符串；禁用用户会撤销其 ACTIVE session。 |
 | `GET/POST/PUT /api/admin/roles...` | 系统管理角色权限维护 | 需要 `SYSTEM_ROLE_MANAGE`；内置角色只读，自定义角色可新增、编辑和分配权限。 |
 | `GET /api/admin/permissions` | 权限码只读列表 | 需要 `SYSTEM_ROLE_MANAGE`；前端只展示和选择已有权限码，不自行造权限码。 |
-| `GET/POST/PUT /api/admin/menus...` | 系统管理菜单维护 | 需要 `SYSTEM_MENU_MANAGE`；允许保存未知路由，前端必须有未知路由兜底页。 |
+| `GET/POST/PUT /api/admin/menus...` | 系统管理菜单维护 | 需要 `SYSTEM_MENU_MANAGE`；允许保存未知路由，前端必须有未知路由兜底页；已提供完整菜单树查询和批量树排序保存。 |
 | `GET/POST/PUT /api/admin/hotels...` | 系统管理酒店维护 | 需要 `HOTEL_MANAGE`；新增酒店默认 `DISABLED`，单酒店阶段不能启用第二家 `ACTIVE`。 |
 | `GET /api/admin/audits` | 系统管理操作审计 | 需要 `SYSTEM_ADMIN_CONSOLE_ACCESS`；用于查看管理后台写操作审计，不包含密码、token、secret。 |

@@ -330,6 +330,8 @@ run_label: 可选调试标签
 - 内置角色 `system_builtin=true` 时只读，前端应禁用编辑和权限分配按钮；后端仍会返回 409 兜底。
 - 新增自定义角色后，用户需要重新登录或刷新 `/api/auth/me` 才能拿到最新权限上下文。
 - 新增菜单允许未知路由；未知路由可以保存，但正式开放可见前要确认前端页面已经存在或兜底页可接受。
+- 菜单管理交互升级已提供 `GET /api/admin/menus/tree` 和 `PUT /api/admin/menus/tree-order`：前者返回完整菜单树，后者批量保存 `parent_id` 和 `sort_order`。这两个接口仍属于 `/api/admin/menus/**`，必须带 Bearer token，并需要 `SYSTEM_MENU_MANAGE`。
+- `PUT /api/admin/menus/tree-order` 只能修改菜单父级和排序，不能顺带修改菜单名称、路由、权限码、可见性或状态；后端会校验父级存在、自引用和循环树，并写入 `platform_admin_audit_log`。`sort_order` 可为空；为空时后端按请求 `items[]` 顺序生成 `100`、`200`、`300`... 的稳定排序号。
 - 新增酒店默认 `DISABLED`，`hotel_id` 新增后不能修改。
 - 单酒店阶段只允许一家 `ACTIVE` 酒店，后端会拒绝启用第二家 `ACTIVE`，也会拒绝禁用最后一家 `ACTIVE`。
 - 系统管理写操作会写入 `platform_admin_audit_log`；审计接口 `GET /api/admin/audits` 可按 `target_type`、`target_id`、`action` 查询。
--- a/docs/project/frontend-backend/frontend-to-backend-api-requests.md
+++ b/docs/project/frontend-backend/frontend-to-backend-api-requests.md
@@ -19,6 +19,7 @@
 | P1 | S10/S99 源邮件只读通知卡与旧 S000/S999 兼容 | 任务列表、任务详情来源邮件查看 | 已完成第一版：旧 S000/S999 兼容，新结构化 S10/S99 可入站并在任务列表 / 详情只读展示 |
 | P1 | type-known manual review 同卡复核解阻 | 任务详情复核 | 已完成第一版：原业务任务卡复核、字段修正、订单归属确认、READY 流转 |
 | P1 | 任务卡前端字段白名单元数据接口 | 字段白名单调试、版本对齐 | 未完成；若任务详情已透出完整元数据，可后置 |
+| P1 | 系统管理菜单树增强接口 | 系统设置 / 菜单管理树形交互 | 已完成：完整菜单树查询、批量保存父级和排序 |
 | 后置 | 普通任务切换订单接口 | 任务详情订单归属调整 | 未完成；已确认后置 |

 ## 2.1 后端当前接口完成度核对
@@ -765,7 +766,134 @@ V3 S10 结构化详情当前增量：

 前端注意：这两个数组不是任务队列，不提供编辑、确认、执行 OPERA 或重试入口；只用于解释为什么同一封邮件中的某些 event 没有变成业务任务。

-## 10. 任务卡前端字段白名单元数据接口
+## 10. 系统管理菜单树增强接口
+
+为支持系统设置中“菜单管理”从表格交互升级为“左侧菜单树 + 右侧配置面板”，前端希望后端补两个增强接口。该能力仍属于系统管理后台 `/api/admin/menus/**`，不改变菜单可见性和后端接口权限的边界。
+
+### 10.1 完整菜单树查询
+
+建议路径：
+
+```text
+GET /api/admin/menus/tree
+```
+
+权限要求：
+
+| 要求 | 说明 |
+| --- | --- |
+| 登录 | 必须携带 `Authorization: Bearer <access_token>` |
+| 权限 | 需要 `SYSTEM_MENU_MANAGE` |
+| 审计 | 只读查询不需要写管理审计 |
+
+查询行为：
+
+- 返回完整菜单树，不分页。
+- 默认返回全部菜单，包括 `ACTIVE` / `DISABLED`、`visible=true` / `false`。
+- 按 `parent_id` 组树，根节点 `parent_id=null`。
+- 同级按 `sort_order` 升序，其次按 `menu_name` 或 `id` 稳定排序。
+- `BIGINT` ID 继续以字符串返回。
+- 如果存在脏数据，例如 `parent_id` 指向不存在菜单，应 fail-safe：该节点作为根级异常节点返回，或在响应中提供 `warnings[]`，不要导致接口 500。
+
+建议返参：
+
+```json
+{
+  "items": [
+    {
+      "id": "10001",
+      "parent_id": null,
+      "menu_code": "SYSTEM_SETTINGS",
+      "menu_name": "系统设置",
+      "menu_type": "PAGE",
+      "route_path": "/system",
+      "component_key": "system",
+      "icon_key": "pi pi-cog",
+      "permission_code": "SYSTEM_ADMIN_CONSOLE_ACCESS",
+      "sort_order": 900,
+      "visible": true,
+      "menu_status": "ACTIVE",
+      "known_route": true,
+      "created_at": "2026-07-16T00:00:00Z",
+      "updated_at": "2026-07-16T00:00:00Z",
+      "children": []
+    }
+  ],
+  "warnings": []
+}
+```
+
+### 10.2 批量调整菜单父级和排序
+
+建议路径：
+
+```text
+PUT /api/admin/menus/tree-order
+```
+
+权限要求：
+
+| 要求 | 说明 |
+| --- | --- |
+| 登录 | 必须携带 `Authorization: Bearer <access_token>` |
+| 权限 | 需要 `SYSTEM_MENU_MANAGE` |
+| 审计 | 写操作必须写 `platform_admin_audit_log` |
+
+请求体建议：
+
+```json
+{
+  "items": [
+    {
+      "menu_id": "10002",
+      "parent_id": "10001",
+      "sort_order": 100
+    }
+  ]
+}
+```
+
+后端要求：
+
+- 只允许修改 `parent_id` 和 `sort_order`，不允许顺带修改 `menu_name`、`route_path`、`permission_code`、`visible`、`menu_status`。
+- 使用事务保存。
+- 校验 `menu_id` 必须存在。
+- 校验 `parent_id` 为空或存在。
+- 禁止把自己设为自己的父级。
+- 禁止形成循环菜单树。
+- `sort_order` 可为空；为空时后端按请求 `items[]` 顺序生成 `100`、`200`、`300`... 的稳定排序号。
+- 成功后返回更新后的完整菜单树，方便前端立即刷新。
+- 审计中记录调整前后的 `parent_id` / `sort_order`，不记录 token、secret 或敏感信息。
+
+建议成功返参：
+
+```json
+{
+  "items": [
+    {
+      "id": "10001",
+      "parent_id": null,
+      "menu_code": "SYSTEM_SETTINGS",
+      "menu_name": "系统设置",
+      "sort_order": 900,
+      "visible": true,
+      "menu_status": "ACTIVE",
+      "known_route": true,
+      "children": []
+    }
+  ],
+  "warnings": []
+}
+```
+
+前端接入注意：
+
+- 前端菜单树管理页优先使用 `GET /api/admin/menus/tree`，不再依赖分页菜单列表拼完整树。
+- `GET /api/admin/menus` 仍保留给表格分页、搜索和兼容页面使用。
+- `PUT /api/admin/menus/{menuId}` 仍用于单条菜单基础字段编辑。
+- `PUT /api/admin/menus/tree-order` 只用于批量保存树结构和排序。
+
+## 11. 任务卡前端字段白名单元数据接口

 是否需要该接口待确认。如果任务详情接口 `fields[]` 已透出 3.0 所需元数据，则第一版可以不做独立白名单接口；如果后续需要字段矩阵调试页、版本对齐页或前端预加载全部任务卡配置，再补独立接口。

@@ -803,7 +931,7 @@ GET /api/reservation/task-card-field-whitelist
 }
 ```

-## 11. 已确认后置接口
+## 12. 已确认后置接口

 普通任务切换订单接口继续后置，前端暂不开发提交能力。后续如果恢复开发，建议另行确认：

@@ -832,7 +960,7 @@ POST /api/reservation/tasks/{taskId}/order-binding
 }
 ```

-## 12. 待确认问题
+## 13. 待确认问题

 - 订单列表、任务列表当前统一使用 `items + page` 分页结构；邮件会话详情不分页，返回同一会话全部邮件。
 - 邮件会话详情接口已优先使用 `GET /api/source-messages/{sourceMessageId}/conversation`。
@@ -841,3 +969,4 @@ POST /api/reservation/tasks/{taskId}/order-binding
 - 邮件会话全文读取的审计策略由后端内部处理；前端不保存原文读取 key。
 - `GET /api/reservation/tasks` 结构化 S10/S99 行的 `task_type` 返回值请后端最终确认：前端已兼容 `SOURCE_MESSAGE_ONLY` 和 `MESSAGE_NOTIFICATION`，但文档口径最好稳定一个。
 - `manual-review-resolutions` 成功响应中的 `opera_operations[]` 数量请后端最终确认；前端不写死两条，只按返回内容刷新展示。
+- 系统管理菜单树增强接口已完成：`GET /api/admin/menus/tree`、`PUT /api/admin/menus/tree-order`。