From e4d3cda828fca347db2534d7465143384e430295 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 17 Jun 2026 16:44:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E7=94=A8=E6=88=B7=E6=9C=8D?= =?UTF-8?q?=E5=8A=A1=E6=8E=A5=E5=8F=A3=E5=A5=91=E7=BA=A6=E5=AE=A1=E8=AE=A1?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20(PR=20#3924,=20=E7=AE=A1=E7=90=86=E5=90=8E?= =?UTF-8?q?=E5=8F=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...复-错误码下移+MapToVO+守卫规范化-修改接口-管理后台.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 changelogs-v2/2026-06/17_3924_用户服务接口契约审计修复-错误码下移+MapToVO+守卫规范化-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/17_3924_用户服务接口契约审计修复-错误码下移+MapToVO+守卫规范化-修改接口-管理后台.md b/changelogs-v2/2026-06/17_3924_用户服务接口契约审计修复-错误码下移+MapToVO+守卫规范化-修改接口-管理后台.md new file mode 100644 index 0000000..75321b9 --- /dev/null +++ b/changelogs-v2/2026-06/17_3924_用户服务接口契约审计修复-错误码下移+MapToVO+守卫规范化-修改接口-管理后台.md @@ -0,0 +1,68 @@ +# 用户服务接口契约审计修复（错误码下移 Service + Map→VO + 角色守卫规范化）— 修改接口 — 管理后台 + +> 变更类型：⚠️ 部分行为收紧（错误码规范化 + 响应结构稳定化），无破坏性字段删除 +> 端类型：管理后台（用户/系统管理） +> 日期：2026-06-17 +> 服务：hl-user-service +> PR：https://git.1814.love:8443/wx/HL/pulls/3924 + +--- + +## ⚠️ 关键说明 + +用接口契约语义审计工作流全量扫描用户服务（hl-user-service）全部 Controller，逐端点比对「Swagger `@ApiOperation` 声明的契约 ⨯ 实际实现 ⨯ 业务规则」，对抗复核后修复一批「接口能跑但返回值/错误码/落库逻辑与契约不符」。已合并 dev-v3、部署测试服、网关 9443 + 真 admin token 实测（`/admin/role`、`/admin/menu/tree` 返回 VO 结构、双实例 totalCodes=282 健康）、本地全量 2793 单测零新增回归。 + +下面只列**与前端对接相关**的变更。最影响前端的是第 1 节（部分管理端接口的鉴权失败由裸 403/字符串改为业务错误码）。 + +--- + +## 1. 角色守卫规范化：非超管/非管理员失败改为业务错误码（前端按 Result.code 处理） + +平台 HTTP 始终 200，业务码在 `Result.code`。系统管理类接口此前部分用裸 403 / 字符串提示拦截越权，本次统一下移 Service 层并改为业务错误码，行为与 notes 文档对齐。 + +| 接口 | 方法 | 变更错误码 | 触发场景 | +|---|---|---|---| +| 完整菜单树 | GET `/admin/menu/tree` | **200307** | 非 SUPER_ADMIN 调用（原行为允许 ADMIN，现严格仅 SUPER_ADMIN，与 notes「仅 SUPER_ADMIN」一致） | +| 角色列表 | GET `/admin/role` | **200313** | 非 SUPER_ADMIN/非 ADMIN 调用（原裸 403，现业务码「仅管理员或超级管理员可执行」） | +| 创建/编辑/删除角色、分配菜单 | POST/PUT/DELETE `/admin/role/**` | **200307** | 非 SUPER_ADMIN（原裸 403，现业务码） | +| 删除内置角色 | DELETE `/admin/role/{roleId}` | **210104** | 删除 SUPER_ADMIN 等系统预置角色（兑现「内置角色不可删除」契约） | + +> 前端处理：以上接口鉴权/业务失败请按 `Result.code` 判断（200307=仅超管、200313=仅管理员或超管、210104=内置角色不可删除），不要再依赖 HTTP 403 或固定文案。 + +--- + +## 2. 系统字典/菜单：新增业务错误码（原 404/400 → 业务码） + +| 接口 | 方法 | 变更错误码 | 触发场景 | +|---|---|---|---| +| 字典数据编辑/删除/查询 | `/admin/dict/data/**` | **210404** | 字典数据项不存在（原 404，现业务码「字典数据不存在」） | +| 菜单创建/编辑（类型校验） | POST/PUT `/admin/menu/**` | **210204** | menuType 不在白名单（D/M/B），原通用错误，现稳定业务码 | +| 菜单创建/编辑（状态校验） | POST/PUT `/admin/menu/**` | **210205** | status 不属于 common_status 字典（ACTIVE/INACTIVE） | + +--- + +## 3. 响应结构稳定化：Map → 强类型 VO（字段名不变，类型更稳定） + +以下接口此前返回 `Map`，本次改为强类型 VO，**字段名与层级不变**，前端无需改动，仅类型更稳定可预期： + +| 接口 | 方法 | 响应类型 | +|---|---|---| +| 角色详情 | GET `/admin/role/{roleId}` | `Map` → `SysRoleDetailRespVO`（roleId/roleName/roleKey/sortOrder/status/menuIds 等） | +| 完整菜单树 / 角色菜单树 / 我的菜单 | GET `/admin/menu/tree`、`/tree/role/{id}`、`/my` | `List` → `List`（递归 children，含 menuType/path/component/icon/visible/isCache/status） | +| 角色列表 | GET `/admin/role` | 列表项统一为 `SysRoleRespVO` | + +> 大雪花 ID（roleId/menuId 等超 JS 安全范围的 Long）按平台口径以**字符串**返回（如 `"2049331915839700993"`），小 ID 仍为数字；前端按字符串/数字皆可解析处理。 + +--- + +## 4. 其它对齐（前端基本无感） + +- 部分响应 VO 字段名/null 语义/缺字段与 Swagger 契约对齐；金额类字段补 `@JsonSerialize(ToStringSerializer)` 输出字符串。 +- 安全：创建管理员/重置密码/登录接口的 Swagger notes 不再明文写出默认密码（仅文档措辞，接口行为不变）。 + +--- + +## 暂缓项（本次未改，留作后续） + +- 内部接口 `/internal/user/admin/info/{adminId}` 的错误码微调（404→业务码）暂缓，本期回退保持原行为。 +- 前端配置 `SECRET` 类型脱敏策略待产品确认，本期保持原行为（管理端详情/列表仍返真值供编辑）。