# feat(下单/支付): 请求体 customizerId 接受 adminId 别名(分享下单绑定定制师全链路打通)

> **类型**: feat(放宽入参 key,向后兼容)
> **关联 PR**: #3030(Closes #3028);绑定逻辑 Issue #1814 早已存在
> **日期**: 2026-05-26
> **影响接口**: `POST /mp/order/create`(下单) + `POST /mp/payment/prepay`(支付预下单)
> **接收方**: mmg
> **前端**: **可选**(原 `customizerId` 仍可用;现在也可直接传 `adminId`)

---

## 🎯 背景

定制师把产品分享给 C 端用户(分享 URL 带 `?adminId=xxx`,以及登录响应 #3022/#3024 返回的 `adminId`),用户通过分享下单时,订单要绑定到该定制师。

后端绑定逻辑早已齐全(Issue #1814),但请求体读的字段名是 `customizerId`,与前端到处用的 `adminId` 不一致。本次让这两个接口的请求体**同时接受 `adminId` 这个 key**,前端直接传 `adminId` 即可绑定,不必再手动改名成 `customizerId`。

---

## 📋 字段说明

`POST /mp/order/create` 和 `POST /mp/payment/prepay` 的请求体:

| key | 类型 | 说明 |
|-----|------|------|
| `adminId` 或 `customizerId`(二选一,等价) | number 或 **string** \| null | 分享来源定制师的 adminId。两个 key 后端都认(`adminId` 是 `customizerId` 的别名) |

要点(⚠️ 此前本篇写「必须 number / 需 Number() 转换」是错的,已更正):
- **adminId 是雪花 ID,请用字符串传**(JS number 超过 2^53 会丢精度!)。后端按字符串精确解析为 Long、不丢精度。**不要在前端把它转成 number**。number 形式也接受(小 ID 无碍),但雪花一律走 string 才安全。
- 选填。不传 / 传 null / 传 0 / 传无效或非定制师 → 不报错,走兜底分配(见下)。
- 两个 key 都传时以 Jackson 解析为准(不要同时传,避免歧义)。

---

## 🔗 分享下单绑定定制师 — 完整行为(后端既有逻辑)

下单时按以下优先级确定订单定制师:

1. **显式 adminId/customizerId**(分享 URL 透传)→ 校验「该 admin 为 `ACTIVE` 且持 `CUSTOMIZER` 角色」→ 通过则锁定该定制师。
2. 未传 adminId 但传了 `sharerOpenid` → 后端用 openid 反查定制师(openid → 手机号 → admin)→ 校验通过则锁定。
3. 都没有 / 都无效 → 兜底:先取运营配置的默认定制师,没有再随机分配一名活跃定制师。

**支付预下单**(`/mp/payment/prepay`)同样接受 adminId:用户从不同定制师的分享链接进入再支付时,若传入的 adminId 校验通过且与订单当前定制师不同,会回写修正(漂移修正,Issue #1814)。

---

## ⚠️ 前端说明

1. 分享下单:把分享来源的 `adminId`(**字符串**,雪花)放进下单请求体的 `adminId`(或 `customizerId`)字段即可,后端自动校验 + 绑定。
2. 校验不通过(非定制师 / 已禁用 / adminId 不存在)**不会让下单失败**,只是走兜底分配,前端无需特殊处理。
3. 非分享场景不传该字段即可(别传空字符串 `""`;要么不传,要么传字符串形式的 adminId)。

---

## 🔧 部署状态

测试服 `hl-mp-service` 已部署最新 dev(双实例滚动)。
- 经测试服网关实测:`POST /mp/order/create` body `{"adminId": -1}` 已能触发 `customizerId` 校验(证明 `adminId` 已被后端识别并映射),`{"customizerId": -1}` 同样生效(向后兼容)。
- 别名映射 + 序列化不变(mp→order-v2 透传不受影响)已由单测覆盖。
