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

> **类型**: 后端新增接口(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] 订单接口」下可见 `切换定制师` / `可选定制师列表`。