hl-api-changelog/changelogs-v2/2026-05/18_2355_admin-order-v3-create-sharer-customizer.md

⚠️✨ 管理端代下单接口 v3 新增分享追踪字段 + consultantSource 枚举新增 SHARED

服务: hl-order-service-v3 接口: POST /admin/v3/orders PR: #2565 refactor(order-v3): [Agency PR-4 / PR-1] 订单创建补 5 项基础逻辑 日期: 2026-05-18 23:55 影响页面: 管理后台「代下单」流程 + 小程序下单（通过 hl-mp-service 透传同接口）

---

变了什么（前端视角）

1. 请求体新增 2 个非必填字段

POST /admin/v3/orders 的请求 body 新增以下字段，不传或传 null 行为与改造前完全一致：

字段	类型	必填	说明
sharerOpenid	String	否	分享人微信 openid，用于 C 端裂变追踪 / 佣金归属。落表 order_info.sharer_openid，admin 代下单时通常不传
customizerId	Long	否	C 端分享归因：从分享链接中带入的定制师 adminId。校验通过则锁定为该定制师（consultantSource = SHARED），校验失败兜底系统默认定制师

注意：customizerId 类型必须是 number（Long），不能传 string。

2. 响应体枚举 consultantSource 新增值 SHARED

OrderCreateRespVO 中 consultantSource 字段的枚举值新增 SHARED：

枚举值	含义	何时出现
DEFAULT_ASSIGNED	系统默认定制师	C 端下单，customizerId 为空或校验不通过，且有系统默认定制师
LINK_BOUND	链接绑定定制师	历史逻辑（v2 遗留）
MANUAL	admin 手动指定	admin 代下单时由 JWT adminId 指定
SHARED（新增）	C 端分享锁定定制师	C 端下单，customizerId 校验通过

3. 新增可能抛出的错误码

code	message	触发场景
581035	订金金额不得超过订单总额	DEPOSIT 模式下订金金额 > 订单总额时触发

4. 行为收紧（字段名不变，错误码变化）

场景	旧行为	新行为
Agency 无默认 mchId	抛 MCH_RESOLVE_FAILED	抛 AGENCY_NO_DEFAULT_MCHID
customerName / customerRemark 含 HTML 标签	原样入库	XSS 过滤后入库（前端无感，被清掉的标签不会报错）

---

前端要改的地方

管理后台 B 端

1. consultantSource 展示标签：若订单详情 / 列表有按 consultantSource 显示来源文案的地方，需补 SHARED 的 case，建议展示文案为**"分享锁定"**：

   // 建议
   const consultantSourceLabel = {
     DEFAULT_ASSIGNED: '系统分配',
     LINK_BOUND: '链接绑定',
     MANUAL: '手动指定',
     SHARED: '分享锁定',   // 新增
   }
   

2. 错误码监控 / 提示：若代下单流程中有按错误码展示错误提示，建议给 581035 加 case，文案直接透传后端 message："订金金额不得超过订单总额"。

   若之前有对 MCH_RESOLVE_FAILED 的特殊提示逻辑，需同步改为 AGENCY_NO_DEFAULT_MCHID。

小程序 C 端（通过 hl-mp-service 透传）

3. 分享链接带 customizerId 下单：从分享 URL 取出 adminId，下单时透传为 customizerId（参考 07_feat_share_lock_customizer.md 详细步骤）：

   const customizerId = uni.getStorageSync('share_customizer_id') || null
   // 放入 POST /mp/order/create 或 POST /admin/v3/orders 的请求体
   

4. 分享追踪 sharerOpenid：若小程序有分享溯源需求（如显示"由 XXX 分享"），可在下单时透传 sharerOpenid；不传也不影响下单流程。

---

接口详细定义

POST /admin/v3/orders — 管理端 / C 端创建订单

• 使用场景：管理后台代客户下单，或 C 端小程序通过 hl-mp-service 创建订单
• 方法: POST
• 路径: /admin/v3/orders（通过 gateway 路由到 hl-order-service-v3）

请求参数（Body JSON）

字段	类型	必填	说明
productId	Long	是	产品 ID
productType	String	是	产品类型（CORE / ACTIVITY 等）
startDate	String	是	出发日期，格式 yyyy-MM-dd
adultCount	Integer	是	成人人数，≥ 1
childCount	Integer	否	儿童人数，默认 0
customerName	String	是	客户姓名（会走 XSS 过滤，HTML 标签会被清除）
customerPhone	String	是	客户手机号
customerRemark	String	否	客户备注（会走 XSS 过滤）
sharerOpenid	String	否	[新增] 分享人微信 openid，C 端裂变追踪用
customizerId	Long	否	[新增] 分享人定制师 adminId，校验通过则锁定为本单定制师

请求示例（含新增字段）

{
  "productId": 10001,
  "productType": "CORE",
  "startDate": "2026-06-01",
  "adultCount": 2,
  "childCount": 0,
  "customerName": "张三",
  "customerPhone": "13800138000",
  "customerRemark": "需要靠窗座位",
  "sharerOpenid": "oXXXXXXXXXXX",
  "customizerId": 50001
}

响应结构

{
  "code": 200,
  "msg": "success",
  "data": {
    "orderId": "202605181234567890",
    "orderNo": "HL202605181234",
    "totalAmount": 9800,
    "depositAmount": 2000,
    "consultantId": 50001,
    "consultantName": "李定制师",
    "consultantSource": "SHARED"
  }
}

响应字段说明

字段	类型	说明
orderId	String	雪花 ID，前端按字符串处理（Long 精度问题）
orderNo	String	可读订单号
totalAmount	Integer	订单总额（分）
depositAmount	Integer	订金金额（分），DEPOSIT 模式下有值
consultantId	Long	绑定的定制师 adminId
consultantName	String	定制师姓名
consultantSource	String	定制师来源枚举，见下表

consultantSource 枚举值完整列表

值	中文展示建议	触发场景
DEFAULT_ASSIGNED	系统分配	C 端下单，customizerId 无效或未传，有系统默认定制师
LINK_BOUND	链接绑定	历史逻辑（v2 遗留，v3 基本不再出现）
MANUAL	手动指定	admin 代下单，由登录态 JWT adminId 指定
SHARED	分享锁定	C 端下单，customizerId 校验通过（定制师有效且角色正确）

---

错误码完整列表（本接口可能返回）

code	message	处理建议
200	success	正常
400	参数校验失败	检查必填字段
581035	订金金额不得超过订单总额	[新增] 直接 toast 后端 message
AGENCY_NO_DEFAULT_MCHID	Agency 未配置默认收款账号	联系运营配置 agency 默认 mchId

---

兼容性

• 请求字段仅新增非必填字段，向后兼容（旧版前端不传新字段行为不变）
• 响应枚举仅新增值不删值，向后兼容
• 无 DDL 变更，无需数据迁移
• 只需重启 hl-order-service-v3，hl-mp-service 无需重启

---

customizerId 校验兜底语义（前端无需实现）

后端 CustomizerValidator 校验失败时全部静默兜底为系统默认定制师，不报错：

失败原因	触发条件	前端表现
ADMIN_NOT_FOUND	adminId 不存在 / 已删除	兜底随机，静默
INACTIVE_STATUS	admin status ≠ ACTIVE	兜底随机，静默
WRONG_ROLE	admin roleKey ≠ CUSTOMIZER	兜底随机，静默
FEIGN_ERROR	user-service Feign 调用失败	兜底随机，静默
INVALID_INPUT	customizerId == null / ≤ 0	兜底随机，静默

前端不需要对这些失败场景做任何处理。