hl-api-changelog/changelogs/2026-06/02_admin_order_switch_customizer.md

【管理后台·前端对接】订单「切换定制师」新接口(本人/超管可改,售后及退款审批中拦截)

类型: 后端新增接口(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 为数组,每项:

{
  "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] 订单接口」下可见 切换定制师 / 可选定制师列表。