docs(changelog): 订单切换定制师新接口对接说明 (#3348)

changelogs/2026-06/02_admin_order_switch_customizer.md

@@ -0,0 +1,73 @@
+# 【管理后台·前端对接】订单「切换定制师」新接口(本人/超管可改,售后及退款审批中拦截)
+
+> **类型**: 后端新增接口(hl-admin 管理后台对接)
+> **仓库**: hl-admin(管理后台前端)
+> **日期**: 2026-06-02
+> **工单**: #3348 ｜ **PR**: #3349 + #3350(路由修复)
+> **状态**: ✅ 已合并 dev → 同步 dev-v3 → 部署测试服 → **测试服 API 已实测通过**
+> **背景**: 前端新增「切换定制师」弹窗,需要专门的切换接口 + 候选定制师下拉。
+
+---
+
+## 一、两个接口(均走网关 `/admin/order/**`,已实测可达)
+
+### 1. 候选定制师列表(弹窗下拉)
+
+```
+GET /admin/order/customizer-candidates
+```
+
+- 返回所有**活跃(ACTIVE)的 CUSTOMIZER 角色**管理员,供弹窗下拉选择新定制师。
+- 响应 `data` 为数组,每项:
+
+```json
+{
+  "customizerId": "2021059720172838914",   // 定制师管理员ID(雪花ID, 字符串)
+  "customizerName": "王骁",                  // 显示名(优先企微昵称, 兜底用户名)
+  "avatarUrl": "https://.../avatar.jpg"      // 头像URL, 可能为 null
+}
+```
+
+> 注:`customizerId` 是雪花 Long,JSON 里以**字符串**返回(避免 JS 精度丢失),回传时按字符串/数字均可。
+
+### 2. 切换定制师
+
+```
+PUT /admin/order/{orderId}/switch-customizer
+Content-Type: application/json
+
+{ "customizerId": 1002 }
+```
+
+> ⚠️ **路径是 `/switch-customizer`,不是 `/customizer`**。
+> `PUT /admin/order/{orderId}/customizer` 是**已有的「转派定制师」(待办模块)**接口,无权限/退款校验,本次**不要**用它。新弹窗请用 `/switch-customizer`。
+
+- 成功:`code=200`。订单 `customizerId` / `customizerName` 更新,相关定制师待办自动重新分配,并写入订单时间线。
+
+## 二、业务规则(后端强制,前端按提示展示即可)
+
+| 规则 | 行为 | 错误码 |
+|------|------|--------|
+| 权限 | 仅**原定制师本人**或**超级管理员(SUPER_ADMIN)**可切换 | `502503` 无权切换定制师,仅原定制师本人或超级管理员可操作 |
+| 售后/退款拦截 | 订单**售后中**或**有进行中退款审批(退款申请/退款申诉)**时禁止切换 | `502504` 订单售后中或有退款审批进行中,不能切换定制师 |
+| 其余状态 | 待支付/已支付/旅行中/已完成/已取消 等**均可**切换 | — |
+| 必填 | `customizerId` 不传 | `400` customizerId 不能为空 |
+
+- 前端建议:对**非本人且非超管**的用户隐藏/置灰「切换定制师」按钮(后端也会兜底拦截 502503)。
+- 订单处于售后/退款审批中时,按钮可置灰或点击后展示 502504 文案。
+
+## 三、测试服实测结果(2026-06-02)
+
+| 用例 | 结果 |
+|------|------|
+| GET 候选列表 | ✅ 200,返回 19 个活跃定制师(id/名称/头像) |
+| 超管切换「已完成」订单 | ✅ 200,订单 customizerId/Name 已更新并持久化 |
+| 切换「退款中」订单 | ✅ 502504 拦截 |
+| customizerId 缺失 | ✅ 400「customizerId 不能为空」 |
+
+> 权限「非本人非超管→502503」「原定制师本人→成功」由后端单元测试覆盖(测试环境仅有超管账号,API 层未单独跑该两条)。
+
+## 四、联调地址
+
+- 网关:`https://api.test.1814.love:9443`
+- Knife4j 文档同地址,tag「[admin] 订单接口」下可见 `切换定制师` / `可选定制师列表`。