hl-api-changelog/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md

【修改接口·管理后台】v3 admin 订单创建（测试 changelog）

PR: 无（测试 changelog） | 服务: hl-order-service-v3 | 更新时间: 2026-05-18 22:00

1. 接口背景

定制师在 B 端管理后台代客户下单的入口。客户通过电话 / 微信 / 线下渠道委托定制师下单，定制师选好产品档位 + 团期 + 出行人数 + 客户信息后调用本接口生成订单，订单进入「待支付」状态，同时返回支付页 URL 用于催款。

v5.17 起入参扩展为 13 字段（新增 createSource / groupBatchId / roomCount / tags），v5.18 起出参扩展为 20 字段（增加 productName / depositAmount / payUrl 等弹窗渲染所需字段）。

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	创建订单	POST	/v3/admin/order	修改接口	v5.17 入参 + v5.18 出参扩展；服务从 v2 切到 hl-order-service-v3

3. 接口详情

3.1 创建订单

• 使用场景：定制师 B 端代下单（电话 / 微信 / 线下渠道委托场景）
• 认证：JWT（admin 角色，Gateway 校验）
• 幂等性：否（同一定制师重复点击会创建多笔订单，前端按钮防抖兜底）
• 限流：无（B 端低频）
• 响应时间预期：P95 ≤ 500ms

4. 接口入参

4.1 路径参数 / Query 参数

无

4.2 请求体字段（OrderCreateReqVO，共 13 字段）

字段	类型	必填	说明	校验规则
productId	Long	✅	产品 ID	@NotNull
tierSeq	Integer	✅	档位序号	@NotNull
departureDate	LocalDate	✅	出发日期	@NotNull（v4.9 改必填）
adultCount	Integer	✅	成人数	@NotNull @Min(1)
childCount	Integer	❌	儿童数	@Min(0)，默认 0
youngChildCount	Integer	❌	幼儿数	@Min(0)，默认 0
babyCount	Integer	❌	婴儿数	@Min(0)，默认 0
customerName	String	✅	客户姓名	@NotBlank
customerPhone	String	✅	客户手机（明文传，11 位数字）	@NotBlank
customerRemark	String	❌	客户备注	@Size(max=500)
createSource	String	❌	创建来源（不传默认 CONSULTANT）	@Size(max=20)，枚举见 §6.1
groupBatchId	Long	❌	拼团批次 ID（自由出团传空）	—
roomCount	Integer	❌	房间数	@Min(1)
tags	List<String>	❌	订单标签名列表	—

5. 出参（响应）

5.1 响应字段（Result<OrderCreateRespVO>，data 共 20 字段）

字段	类型	说明
id	String	订单主键
orderNo	String	订单号，格式 HL{yyyyMMddHHmmss}{3 位序号}，例 HL20260510143025001
displayOrderNo	String	展示订单号 = orderNo + teamNo；teamNo 为空时等同 orderNo
orderStatus	String	订单粗状态，创单后固定 待支付（枚举见 §6.2）
flowStatus	String	订单细状态，创单后固定 待支付订金（枚举见 §6.3）
consultantId	String	实际绑定的定制师 ID
consultantSource	String	定制师来源（枚举见 §6.4）
tags	List<String>	标签列表（含入参 tags + 系统自动标签，如 "含儿童"、"二次复购"）
createdAt	LocalDateTime	创单时间
productName	String	产品名称
tierName	String	档位名
groupBatchName	String	拼团批次名（自由出团时 null）
departureDate	LocalDate	出发日
returnDate	LocalDate	返团日
totalAmount	BigDecimal	订单总价（元，2 位小数）
depositAmount	BigDecimal	建议定金金额（元，2 位小数）
depositRatio	Integer	定金比例百分比（DEPOSIT 模式有值；FULL 模式恒为 100）
paymentMode	String	支付模式（枚举见 §6.5）
expiryMinutes	Integer	支付时限分钟数，默认 1440（=24h）
payUrl	String	支付页绝对 URL
customerName	String	客户姓名（回显）

6. 枚举 / 数据字典

接口里出现的枚举按字段分开列。本接口共 5 个枚举字段。

6.1 createSource（OrderCreateSource）

所属字段：入参 createSource | 类型：String | 必填：❌（不传默认 CONSULTANT）

值	中文	说明
CUSTOMER	客户自助	客户在小程序自助下单
CONSULTANT	定制师代下单	默认值，B 端代下单
OTA	OTA 渠道	携程 / 美团等 OTA 引流
WALK_IN	门店步入	线下门店现场下单
B2B	B2B 渠道	旅行社代下单
VIP_REPURCHASE	VIP 复购	老客户回购通道
REFERRAL	老客户转介绍	—
PROMOTION	营销活动	—
INTERNAL	内部测试	不计入业绩

6.2 orderStatus（OrderStatus）

所属字段：出参 orderStatus（订单粗状态）| 类型：String

值	中文	说明
待支付	待支付	创单后默认状态
待完善	待完善	订金到账后进入
定制中	定制中	出行人 + 房车齐后
已确认	已确认	—
出行中	出行中	—
已完成	已完成	—
已取消	已取消	—

6.3 flowStatus（OrderFlowStatus）

所属字段：出参 flowStatus（订单细状态）| 类型：String

值	中文	说明
待支付订金	待支付订金	创单后默认细状态

本节仅列创单接口能返回的细状态值；完整 flowStatus 枚举见订单状态机文档。

6.4 consultantSource（ConsultantSource）

所属字段：出参 consultantSource（定制师分配来源）| 类型：String

值	中文	说明
DEFAULT_ASSIGNED	系统默认分配	走轮询规则
LINK_BOUND	链接绑定	客户扫了定制师专属码
MANUAL	手动指定	B 端 admin 强制指派

6.5 paymentMode（PaymentMode）

所属字段：出参 paymentMode（支付模式）| 类型：String

值	中文	说明
DEPOSIT	定金模式	30% 定金 + 余款
FULL	全款模式	100% 一次付清

7. 错误码

code	含义	触发场景
510101	产品不存在 / 已下架	资源域反查 productId 失败
510102	档位不存在	tierSeq 与产品 pricing_tier 表不匹配
510103	出发日期早于今天	departureDate < LocalDate.now()
510104	出发日期超过报名截止	拼团模式 departureDate < batch.signupDeadline
510105	拼团批次不存在 / 已满员	groupBatchId 反查失败或剩余人数不足
510106	总人数 = 0	adultCount + childCount + youngChildCount + babyCount == 0
510107	createSource 枚举非法	不在 §6 9 个值范围内
510108	客户手机格式非法	非 11 位数字
510109	系统未配置默认定制师	DEFAULT_ASSIGNED 时轮询池为空

只写契约，不写前端处理建议（前端建议属于消费方决策）

8. 示例（3 组：典型 / 边界 / 异常）

8.1 典型成功

请求：

POST /v3/admin/order
Authorization: Bearer {admin_jwt}
Content-Type: application/json

{
  "productId": 30001234567,
  "tierSeq": 1,
  "departureDate": "2026-06-01",
  "adultCount": 2,
  "childCount": 1,
  "youngChildCount": 0,
  "babyCount": 0,
  "customerName": "张三",
  "customerPhone": "13800002046",
  "customerRemark": "希望住朝阳房",
  "createSource": "CONSULTANT",
  "groupBatchId": 80001234567890,
  "roomCount": 2,
  "tags": ["VIP 客户", "二次复购"]
}

响应：

{
  "code": 200,
  "data": {
    "id": "60123456789012",
    "orderNo": "HL20260518220000001",
    "displayOrderNo": "HL20260518220000001",
    "orderStatus": "待支付",
    "flowStatus": "待支付订金",
    "consultantId": "50001234567890",
    "consultantSource": "DEFAULT_ASSIGNED",
    "tags": ["VIP 客户", "二次复购", "含儿童"],
    "createdAt": "2026-05-18T22:00:00",
    "productName": "小蒙马夏季亲子营",
    "tierName": "经典档",
    "groupBatchName": "第 2 期",
    "departureDate": "2026-06-01",
    "returnDate": "2026-06-06",
    "totalAmount": 140800.00,
    "depositAmount": 42240.00,
    "depositRatio": 30,
    "paymentMode": "DEPOSIT",
    "expiryMinutes": 1440,
    "payUrl": "https://pay.hulalv.com/pay/HL20260518220000001",
    "customerName": "张三"
  },
  "msg": "success"
}

8.2 边界情况

场景说明：自由出团（无拼团批次）+ 全款模式 + 无标签 + 无备注。groupBatchId / customerRemark / tags / roomCount 均省略。

请求：

{
  "productId": 30001234567,
  "tierSeq": 2,
  "departureDate": "2026-12-31",
  "adultCount": 1,
  "customerName": "李四",
  "customerPhone": "13912340001"
}

响应（关注 groupBatchName=null / tags 仅含系统标签 / paymentMode=FULL / depositRatio=100）：

{
  "code": 200,
  "data": {
    "id": "60123456789013",
    "orderNo": "HL20260518220500001",
    "displayOrderNo": "HL20260518220500001",
    "orderStatus": "待支付",
    "flowStatus": "待支付订金",
    "consultantId": "50001234567890",
    "consultantSource": "DEFAULT_ASSIGNED",
    "tags": [],
    "createdAt": "2026-05-18T22:05:00",
    "productName": "小蒙马夏季亲子营",
    "tierName": "VIP 档",
    "groupBatchName": null,
    "departureDate": "2026-12-31",
    "returnDate": "2027-01-05",
    "totalAmount": 18800.00,
    "depositAmount": 18800.00,
    "depositRatio": 100,
    "paymentMode": "FULL",
    "expiryMinutes": 1440,
    "payUrl": "https://pay.hulalv.com/pay/HL20260518220500001",
    "customerName": "李四"
  },
  "msg": "success"
}

8.3 业务失败（异常）

场景说明：拼团批次已满员（510105）

请求：（同 8.1，但 groupBatchId 指向已满批次）

{
  "productId": 30001234567,
  "tierSeq": 1,
  "departureDate": "2026-06-01",
  "adultCount": 2,
  "customerName": "王五",
  "customerPhone": "13700001234",
  "groupBatchId": 80001999999999
}

响应：

{
  "code": 510105,
  "data": null,
  "msg": "拼团批次不存在或已满员"
}

9. 业务边界

• ✅ 适用场景：产品状态 = 上架；档位有效；出发日期 ≥ 今天；总人数 ≥ 1；客户手机合法（11 位数字）
• ❌ 拒绝场景：
  • 产品已下架 → 510101
  • 出发日期早于今天 → 510103
  • 拼团批次过报名截止 → 510104
  • 拼团批次满员 → 510105
  • 总人数为 0（4 个 count 都是 0 或 null）→ 510106
  • createSource 枚举非法 → 510107
  • 客户手机格式非法 → 510108
• ⚠️ 可选字段省略行为：
  • 不传 createSource → 接受，使用默认 CONSULTANT
  • 不传 roomCount → 接受，返回的订单 roomCount 为 null
  • 不传 tags → 接受，返回的 tags 仅含系统自动标签

10. 修改前后对比

测试 changelog，对比口径以 v5.16 → v5.18 跨度展示。

10.1 字段级对比

入参：

字段	v5.16 及之前	v5.17 起
createSource	❌ 无	✅ 新增（可选）
groupBatchId	❌ 无	✅ 新增（可选）
roomCount	❌ 无	✅ 新增（可选）
tags	❌ 无	✅ 新增（可选）

出参：

字段	v5.17 及之前	v5.18 起
productName / tierName / groupBatchName	❌ 无	✅ 新增
departureDate / returnDate	❌ 无	✅ 新增
totalAmount / depositAmount / depositRatio / paymentMode	❌ 无	✅ 新增
expiryMinutes / payUrl / customerName	❌ 无	✅ 新增

10.2 行为级对比

行为	v5.17 及之前	v5.18 起
创单成功响应字段	9 字段（仅订单元数据）	20 字段（含产品名 / 价格 / 支付 URL）
是否需要二次调详情接口拿弹窗信息	是	否（响应已含全部弹窗字段）

11. 影响评估

• 是否破坏向后兼容：否（入参新增字段全可选；出参字段为追加）
• 前端是否必须同步上线：否（旧前端忽略新出参字段，行为不变）

12. 注意事项

• 前端可清理的历史 workaround：
  • "创单后二次调详情接口拼弹窗" → 可撤；响应已含 20 字段
  • "按比例硬编码计算定金" → 可撤；响应直接返 depositAmount / depositRatio

13. 关联

• Issue: 无（测试 changelog，验证 changelogs-v2/ 目录推送流程）
• PR: 无
• 设计文档: docs/order-v3/srs/order-cloud-v3-srs-v5.48.html §1.0 ~ §1.3
• 后端负责人: @yaosutu