refactor: ResourceController 对齐全局接口契约 — POST + 动作后缀 + 表单参数

- GET /api/resources → GET /api/resources/list - POST /api/resources + @RequestBody → POST /api/resources/saveOrUpdate + 表单字段 - DELETE /api/resources/{id} → POST /api/resources/delete + @RequestParam - 前端对接文档同步更新
1 month ago · 170c16b226
2 changed files with 623 additions and 5 deletions
--- a/crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java
+++ b/crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java
@ -13,6 +13,7 @@ import java.util.List;

 /**
 * 统一权限资源树管理端接口（ADR-0011）
+ * <p>遵循全局接口契约：非严格 RESTful，写操作 POST + 动作后缀，表单字段收参</p>
 */
@RestController
@RequestMapping("/api/resources")
@ -23,20 +24,20 @@ public class ResourceController {
    private final IResourceService resourceService;

    /** 全量资源树（扁平数组，前端按 parentId 组树） */
-    @GetMapping
+    @GetMapping("/list")
    public Result<List<ResourceNode>> listAll() {
        return Result.success(resourceService.listAll());
    }

    /** 新增或编辑节点（含校验） */
-    @PostMapping
-    public Result<ResourceNode> save(@RequestBody ResourceNode node) {
+    @PostMapping("/saveOrUpdate")
+    public Result<ResourceNode> saveOrUpdate(ResourceNode node) {
        return Result.success(resourceService.save(node));
    }

    /** 删除节点（含子节点检查 + 级联清理） */
-    @DeleteMapping("/{id}")
-    public Result<Void> delete(@PathVariable Long id) {
+    @PostMapping("/delete")
+    public Result<Void> delete(@RequestParam Long id) {
        resourceService.delete(id);
        return Result.success();
    }
--- a/docs/frontend-integration-menu-permission.md
+++ b/docs/frontend-integration-menu-permission.md
@ -0,0 +1,617 @@
+# 菜单/权限点管理 — 前端对接文档
+
+> 遵循《业务中台产品接口说明书》全局契约  
+> 接口基础路径：`/api/resources`  
+> 权限要求：**管理员角色**（`ROLE_ADMIN`）
+
+---
+
+## 1. 接口总览
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| `GET` | `/api/resources/list` | 获取全量资源树（扁平数组） |
+| `POST` | `/api/resources/saveOrUpdate` | 新增或编辑节点 |
+| `POST` | `/api/resources/delete` | 删除节点 |
+| `POST` | `/api/resources/icon/upload` | 上传图标 |
+
+**认证方式**：所有接口需在请求头携带 `Authorization: Bearer {token}`，且 token 对应用户必须具有 `ROLE_ADMIN` 角色。
+
+**请求格式**：
+- `GET` 请求：参数放 URL query
+- `POST` 请求：`Content-Type: application/x-www-form-urlencoded`，参数为表单字段
+- 文件上传：`Content-Type: multipart/form-data`
+
+> ⚠️ 注意：POST 请求不使用 JSON body，复杂字段（对象/数组）各自 `JSON.stringify` 后作为普通表单字段传递。
+
+---
+
+## 2. 数据模型：ResourceNode
+
+```typescript
+interface ResourceNode {
+  id: string | null;           // 节点 ID（字符串），新增时不传，编辑时必传
+  parentId: string | null;     // 父节点 ID（字符串），根节点传 null 或 "0"
+  type: 'CATALOG' | 'MENU' | 'BUTTON';  // 节点类型
+  name: string;                // 显示名称（必填）
+  sort: number;                // 排序号，值越小越靠前（必填）
+  description?: string;        // 描述/备注
+
+  // —— menu 类型专用 ——
+  route?: string;              // 前端路由路径，menu 必填
+
+  // —— button 类型专用 ——
+  perms?: string;              // 权限码，格式 crm:<module>:<action>
+  denyBehavior?: string;      // 无权限时表现：'hide' | 'disable'
+  apiUrl?: string;            // 按钮对应的后端接口路径
+  status?: string;            // 权限点状态：'enabled' | 'disabled'
+
+  // —— catalog/menu 专用 ——
+  icon?: string;              // 图标预览 URL
+}
+```
+
+> ⚠️ **ID 一律按字符串收发**。后端返回的 id 是字符串（雪花 ID 超出 JS Number 安全范围），前端回传原样传字符串即可，不要转 Number。
+
+### 节点类型说明
+
+| 类型 | 枚举值 | 说明 | 可挂子节点 |
+|------|--------|------|-----------|
+| 菜单分组 | `CATALOG` | 收纳容器，不承载页面 | 只能挂 `MENU` |
+| 菜单页面 | `MENU` | 可导航的页面 | 只能挂 `BUTTON` |
+| 按钮/权限点 | `BUTTON` | 叶子节点，承载权限码 | 不可挂子节点 |
+
+### 层级约束
+
+```
+根节点（parentId=null/"0"）
+  ├── CATALOG（菜单分组）
+  │     └── MENU（菜单页面）
+  │           └── BUTTON（按钮/权限点）
+  └── MENU（菜单页面，一级菜单）
+        └── BUTTON（按钮/权限点）
+```
+
+**规则**：
+- 根节点只能挂 `CATALOG` 或 `MENU`
+- `CATALOG` 下只能挂 `MENU`（不能嵌套分组）
+- `MENU` 下只能挂 `BUTTON`
+- `BUTTON` 是叶子节点，不可再挂子节点
+
+---
+
+## 3. 接口详情
+
+### 3.1 获取全量资源树
+
+```
+GET /api/resources/list
+Authorization: Bearer {token}
+```
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "success": true,
+  "message": "success",
+  "data": [
+    {
+      "id": "1",
+      "parentId": "0",
+      "type": "CATALOG",
+      "name": "系统管理",
+      "sort": 1,
+      "description": null,
+      "icon": "https://cdn.example.com/icons/system.png"
+    },
+    {
+      "id": "10",
+      "parentId": "1",
+      "type": "MENU",
+      "name": "用户管理",
+      "sort": 1,
+      "route": "/system/user",
+      "icon": null
+    },
+    {
+      "id": "100",
+      "parentId": "10",
+      "type": "BUTTON",
+      "name": "查询用户",
+      "sort": 1,
+      "perms": "crm:user:list",
+      "denyBehavior": "hide",
+      "apiUrl": "/api/system/users/page",
+      "status": "enabled",
+      "description": "查询用户列表"
+    }
+  ]
+}
+```
+
+**前端处理**：后端返回扁平数组，前端通过 `parentId` 自行组树。
+
+```typescript
+// 组树示例
+function buildTree(nodes: ResourceNode[]): TreeNode[] {
+  const map = new Map<string, TreeNode>();
+  const roots: TreeNode[] = [];
+  
+  nodes.forEach(node => {
+    map.set(node.id!, { ...node, children: [] });
+  });
+  
+  nodes.forEach(node => {
+    const treeNode = map.get(node.id!)!;
+    const parentId = node.parentId || "0";
+    if (parentId === "0") {
+      roots.push(treeNode);
+    } else {
+      const parent = map.get(parentId);
+      parent?.children.push(treeNode);
+    }
+  });
+  
+  return roots.sort((a, b) => a.sort - b.sort);
+}
+```
+
+---
+
+### 3.2 新增/编辑节点
+
+```
+POST /api/resources/saveOrUpdate
+Content-Type: application/x-www-form-urlencoded
+Authorization: Bearer {token}
+```
+
+**表单参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | string | 编辑时必传 | 不传为新增，传为编辑 |
+| parentId | string | 是 | 父节点 ID，根节点传 `"0"` |
+| type | string | 是 | `CATALOG` / `MENU` / `BUTTON` |
+| name | string | 是 | 显示名称 |
+| sort | number | 是 | 排序号 |
+| description | string | 否 | 描述/备注 |
+| route | string | menu 必填 | 前端路由路径 |
+| perms | string | button 必填 | 权限码 |
+| denyBehavior | string | button 必填 | `hide` / `disable` |
+| apiUrl | string | button 必填 | 后端接口路径 |
+| status | string | button 必填 | `enabled` / `disabled` |
+| icon | string | catalog/menu 可选 | 图标预览 URL |
+
+**请求示例（新增菜单分组）**：
+
+```http
+POST /api/resources/saveOrUpdate
+Content-Type: application/x-www-form-urlencoded
+Authorization: Bearer eyJhbGciOi...
+
+parentId=0&type=CATALOG&name=业务管理&sort=10&description=CRM核心业务模块
+```
+
+**请求示例（新增按钮/权限点）**：
+
+```http
+POST /api/resources/saveOrUpdate
+Content-Type: application/x-www-form-urlencoded
+Authorization: Bearer eyJhbGciOi...
+
+parentId=1002&type=BUTTON&name=删除客户&sort=3&perms=crm:customer:delete&denyBehavior=disable&apiUrl=/api/crm/customer/delete&status=enabled&description=删除客户及其关联数据
+```
+
+**请求示例（编辑节点 — 改名）**：
+
+```http
+POST /api/resources/saveOrUpdate
+Content-Type: application/x-www-form-urlencoded
+Authorization: Bearer eyJhbGciOi...
+
+id=10&parentId=1&type=MENU&name=客户管理改&sort=1&route=/customer/list
+```
+
+**响应**：返回保存后的完整节点。
+
+```json
+{
+  "code": 0,
+  "success": true,
+  "message": "success",
+  "data": {
+    "id": "11",
+    "parentId": "1",
+    "type": "MENU",
+    "name": "客户管理",
+    "sort": 2,
+    "route": "/customer/list"
+  }
+}
+```
+
+**字段必填规则**（按类型）：
+
+| 字段 | CATALOG | MENU | BUTTON |
+|------|---------|------|--------|
+| name | ✅ 必填 | ✅ 必填 | ✅ 必填 |
+| sort | ✅ 必填 | ✅ 必填 | ✅ 必填 |
+| route | ❌ | ✅ 必填 | ❌ |
+| perms | ❌ | ❌ | ✅ 必填 |
+| denyBehavior | ❌ | ❌ | ✅ 必填 |
+| apiUrl | ❌ | ❌ | ✅ 必填 |
+| status | ❌ | ❌ | ✅ 必填 |
+| icon | 可选 | 可选 | ❌ |
+| description | 可选 | 可选 | 可选 |
+
+**编辑限制**：
+- `type` 字段创建后不可变更（编辑时传不同的 type 会被拒绝）
+- 编辑时 `route` 可不传，后端保留原有值（除非传新值覆盖）
+
+---
+
+### 3.3 删除节点
+
+```
+POST /api/resources/delete
+Content-Type: application/x-www-form-urlencoded
+Authorization: Bearer {token}
+```
+
+**表单参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | string | 是 | 要删除的节点 ID |
+
+**请求示例**：
+
+```http
+POST /api/resources/delete
+Content-Type: application/x-www-form-urlencoded
+Authorization: Bearer eyJhbGciOi...
+
+id=100
+```
+
+**校验规则**：
+- 节点必须存在
+- 节点下不能有子节点（有子节点会返回错误，需先删除子节点）
+- 删除时自动清理各角色对该节点的授权引用
+
+**成功响应**：
+
+```json
+{
+  "code": 0,
+  "success": true,
+  "message": "success"
+}
+```
+
+**失败响应示例**（有子节点）：
+
+```json
+{
+  "code": 61009,
+  "success": false,
+  "message": "节点下有 3 个子节点，请先删除子节点"
+}
+```
+
+---
+
+### 3.4 上传图标
+
+```
+POST /api/resources/icon/upload
+Content-Type: multipart/form-data
+Authorization: Bearer {token}
+```
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file | File | ✅ | 图片文件 |
+
+**限制**：
+- 格式：`png` / `jpg` / `jpeg` / `gif` / `svg` / `webp`
+- 大小：≤ 500KB
+
+**请求示例**：
+
+```http
+POST /api/resources/icon/upload
+Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
+Authorization: Bearer eyJhbGciOi...
+
+------WebKitFormBoundary
+Content-Disposition: form-data; name="file"; filename="icon.png"
+Content-Type: image/png
+
+(二进制内容)
+------WebKitFormBoundary--
+```
+
+**响应**：
+
+```json
+{
+  "code": 0,
+  "success": true,
+  "message": "success",
+  "data": {
+    "fileId": "1234567890",
+    "originalName": "icon.png",
+    "size": 12345,
+    "contentType": "image/png",
+    "bizDomain": "resources/icon"
+  }
+}
+```
+
+**前端处理流程**：
+
+```typescript
+async function uploadIcon(file: File): Promise<string> {
+  // 1. 上传图标，获取 fileId
+  const formData = new FormData();
+  formData.append('file', file);
+  
+  const uploadRes = await fetch('/api/resources/icon/upload', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}` },
+    body: formData,  // multipart/form-data 由浏览器自动设置
+  });
+  const { data: fileInfo } = await uploadRes.json();
+  
+  // 2. 通过 fileId 获取预览 URL
+  const previewRes = await fetch(`/api/file/preview-url?fileId=${fileInfo.fileId}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const { data: previewUrl } = await previewRes.json();
+  
+  // 3. 返回预览 URL，存入节点的 icon 字段
+  return previewUrl;
+}
+
+// 使用示例
+const iconUrl = await uploadIcon(selectedFile);
+// 然后在保存节点时将 iconUrl 作为 icon 表单字段传入
+await saveNode({ ...node, icon: iconUrl });
+```
+
+---
+
+## 4. 停用与启用权限点
+
+停用/启用权限点**没有单独的接口**，通过编辑节点（`POST /api/resources/saveOrUpdate`）更新 `status` 字段实现。
+
+### 操作方式
+
+```http
+POST /api/resources/saveOrUpdate
+Content-Type: application/x-www-form-urlencoded
+Authorization: Bearer eyJhbGciOi...
+
+id=1003&parentId=1002&type=BUTTON&name=删除客户&sort=3&perms=crm:customer:delete&denyBehavior=disable&apiUrl=/api/crm/customer/delete&status=disabled
+```
+
+| 操作 | status 值 | 说明 |
+|------|-----------|------|
+| 停用 | `disabled` | 权限点全局失效，所有用户均无法使用该权限 |
+| 启用 | `enabled` | 恢复权限点生效，原角色授权自动恢复 |
+
+### 业务语义
+
+- **停用**：即使角色已勾选授予该权限点，权限解析引擎也不将其 `perms` 纳入用户的权限码并集——相当于**全局断路**，无需逐角色取消授权
+- **启用**：重新启用后，原授权**自动恢复生效**，无需管理员重新到角色授权中勾选
+- **数据影响**：停用/启用只修改 `status` 字段，不涉及角色授权关系（`sys_role_menu`）的变动
+
+### 前端处理建议
+
+```typescript
+// 权限点状态切换
+async function togglePermissionStatus(nodeId: string, enabled: boolean) {
+  const node = await getNode(nodeId);
+  const params = new URLSearchParams();
+  params.append('id', node.id);
+  params.append('parentId', node.parentId);
+  params.append('type', node.type);
+  params.append('name', node.name);
+  params.append('sort', node.sort);
+  params.append('perms', node.perms);
+  params.append('denyBehavior', node.denyBehavior);
+  params.append('apiUrl', node.apiUrl);
+  params.append('status', enabled ? 'enabled' : 'disabled');
+  
+  await fetch('/api/resources/saveOrUpdate', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: params,
+  });
+}
+
+// 在 UI 上显示停用状态
+<Switch
+  checked={node.status === 'enabled'}
+  onChange={(checked) => togglePermissionStatus(node.id, checked)}
+/>
+```
+
+---
+
+## 5. 错误处理
+
+所有错误响应格式统一：
+
+```json
+{
+  "code": 61009,
+  "success": false,
+  "message": "具体错误信息"
+}
+```
+
+**判定规则**：判成功只看 `success === true`；判失败后的分支处理（跳登录、回填表单等）再看 `code`。
+
+**HTTP 状态码**：业务失败 HTTP 状态码仍是 200，通过 `success`/`code` 判断。仅以下场景 HTTP 状态码非 200：
+
+| HTTP | 场景 | 响应体 code |
+|------|------|-------------|
+| 401 | 未登录 / 登录过期 | 40103 |
+| 403 | 已登录但无权限 | 40301 |
+| 404 | 接口路径不存在 | 40401 |
+| 500 | 系统内部异常 | 50001 |
+
+即使 HTTP 状态码非 200，响应体仍然是统一信封结构。
+
+**资源管理接口常见错误**：
+
+| 消息 | 原因 |
+|------|------|
+| `节点名称不能为空` | name 字段为空 |
+| `节点类型不能为空` | type 字段为空 |
+| `menu 类型必须提供路由（route）` | MENU 类型缺少 route |
+| `button 类型必须提供权限码（perms）` | BUTTON 类型缺少 perms |
+| `button 类型必须提供无权限行为（denyBehavior）` | BUTTON 类型缺少 denyBehavior |
+| `button 类型必须提供接口 URL（apiUrl）` | BUTTON 类型缺少 apiUrl |
+| `button 类型必须提供状态（status）` | BUTTON 类型缺少 status |
+| `根节点不允许添加 button 类型` | 违反层级约束 |
+| `catalog 节点下只能添加 menu 类型` | 违反层级约束 |
+| `menu 节点下只能添加 button 类型` | 违反层级约束 |
+| `button 是叶子节点，不可添加子节点` | 违反层级约束 |
+| `节点类型不可变更` | 编辑时修改了 type |
+| `节点下有 N 个子节点，请先删除子节点` | 删除非叶子节点 |
+| `不支持的图标格式` | 上传非法格式 |
+| `图标大小不能超过 500KB` | 文件过大 |
+
+---
+
+## 6. 联调指南
+
+### 6.1 前置条件
+
+1. 确保后端服务已启动（Base URL 由后端另行下发）
+2. 使用管理员账号通过钉钉扫码登录获取 token
+3. 请求头统一添加 `Authorization: Bearer {token}`
+4. token 由后端滑动续期，前端无需定时刷新；收到 401（code=40103）时清除 token 跳登录页
+
+### 6.2 快速验证
+
+```bash
+# 1. 获取全量资源树
+curl -X GET "{baseUrl}/api/resources/list" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# 2. 新增一个菜单分组
+curl -X POST "{baseUrl}/api/resources/saveOrUpdate" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "parentId=0&type=CATALOG&name=测试分组&sort=99"
+
+# 3. 在分组下新增菜单
+curl -X POST "{baseUrl}/api/resources/saveOrUpdate" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "parentId={上一步返回的id}&type=MENU&name=测试菜单&sort=1&route=/test/menu"
+
+# 4. 在菜单下新增按钮
+curl -X POST "{baseUrl}/api/resources/saveOrUpdate" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "parentId={菜单id}&type=BUTTON&name=测试按钮&sort=1&perms=crm:test:action&denyBehavior=hide&apiUrl=/api/test/action&status=enabled"
+
+# 5. 删除节点
+curl -X POST "{baseUrl}/api/resources/delete" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "id={节点id}"
+```
+
+### 6.3 前端开发建议
+
+1. **树形组件**：推荐使用 `parentId` 在前端组树，后端返回扁平数组性能更好
+2. **表单提交**：使用 `URLSearchParams` 或 `qs` 库构造表单字段，不要用 `JSON.stringify` 整体打包
+3. **ID 处理**：所有 id 字段按字符串处理，不要 `parseInt` / `Number()`
+4. **表单校验**：根据节点类型动态显示必填字段
+   - CATALOG：name, sort
+   - MENU：name, sort, route
+   - BUTTON：name, sort, perms, denyBehavior, apiUrl, status
+5. **类型锁定**：编辑时 type 字段应置灰不可修改
+6. **图标上传**：先上传获取 URL，再保存节点
+7. **权限码格式**：建议提供下拉选择或自动补全，格式为 `crm:<module>:<action>`
+   - module: `lead`, `opportunity`, `customer`, `project`
+   - action: `add`, `edit`, `delete`, `export`, `transfer` 等
+
+### 6.4 调试技巧
+
+- 每个响应都带响应头 `X-Trace-Id`，报障时附上此 ID
+- 使用浏览器开发者工具 Network 面板查看请求/响应
+- 后端日志会打印保存的节点信息，便于排查
+- 403 错误检查 token 是否过期、用户是否有 ADMIN 角色
+- 61009 错误查看 message 字段获取具体原因
+
+---
+
+## 7. 权限码并集说明
+
+用户登录后，后端会自动计算其**权限码并集**（所有角色授权的启用状态按钮的 perms），注入到 Spring Security 上下文中。
+
+**前端使用**：
+- 登录后从 `GET /api/auth/me` 获取用户信息及 `authorities` 列表
+- 根据 `authorities` 控制按钮显示/隐藏
+
+```typescript
+// 示例：检查是否有某权限
+const hasPermission = (perm: string) => {
+  return userAuthorities.includes(perm);
+};
+
+// 使用
+{hasPermission('crm:customer:delete') && <DeleteButton />}
+```
+
+**停用权限点**：
+- 当按钮的 `status` 设为 `disabled` 时，即使角色已授权，该权限码也不会出现在用户权限并集中
+- 相当于全局断路，无需逐角色取消授权
+- 重新启用后原授权自动恢复
+
+---
+
+## 8. 与角色授权的集成
+
+资源树维护完成后，在**角色管理 → 授权**页面使用：
+
+1. 调用 `GET /api/resources/list` 获取全量资源树
+2. 渲染为勾选树（checkbox tree）
+3. 勾选节点即授予该角色对应权限
+4. 勾选菜单节点时，前端自动联动勾选其全部祖先节点（确保菜单可见）
+
+```typescript
+// 联动勾选祖先
+function collectAncestorIds(nodeId: string, tree: TreeNode[]): string[] {
+  const ancestors: string[] = [];
+  const findPath = (nodes: TreeNode[], target: string, path: string[]): boolean => {
+    for (const node of nodes) {
+      if (node.id === target) {
+        ancestors.push(...path);
+        return true;
+      }
+      if (findPath(node.children, target, [...path, node.id!])) {
+        return true;
+      }
+    }
+    return false;
+  };
+  findPath(tree, nodeId, []);
+  return ancestors;
+}
+```