yaosutu 0aee0ceddb docs(order-v3): 订单创建接口 v3 admin POST /v3/admin/order 接口现状快照（测试 v2 目录）

启用 changelogs-v2/ 新目录，前端 v3 项目仓库后续从此目录读 changelog。
此份为 v3 admin 订单创建接口（OrderController.createOrder）的 v5.18 完整快照，
含 13 节固定模板（入参 13 字段 / 出参 20 字段 / 枚举 21 项 / 错误码 9 个 / 3 组示例）。

2026-05-18 15:04:12 +08:00

15 KiB

原始文件 Blame 文件历史

【修改接口·管理后台】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	✅	客户手机（明文传，DB 层 AES 加密）	`@NotBlank`
`customerRemark`	String	❌	客户备注	`@Size(max=500)`
`createSource`	String	❌	创建来源（v5.17 新增，不传默认 `CONSULTANT`）	`@Size(max=20)`，枚举见 §6
`groupBatchId`	Long	❌	拼团批次 ID（v5.17 新增，自由出团为空）	—
`roomCount`	Integer	❌	房间数（v5.17 新增，写入 `order_main.room_count`）	`@Min(1)`
`tags`	List<String>	❌	订单标签名列表（v5.17 新增，写入 `order_tag`，`tag_type=PERSONAL`）	—

后端从 JWT 派生：adminId、consultantId、realName，前端不传。行程时间字段 returnDate / tripDays / tripNights 由后端从产品快照 + departureDate 派生。 出行人不在创单接口里传，创建后按 §2 traveler 模块单独 API 添加。

5. 出参（响应）

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

字段	类型	说明
`id`	String	订单主键（雪花 ID，JSON 序列化为 String 防精度丢失）
`orderNo`	String	订单号（创单瞬间生成，永不变，例 `HL20260510143025001`）
`displayOrderNo`	String	展示订单号 = `orderNo + teamNo`（创单时 `teamNo` 为空，等同 `orderNo`）
`orderStatus`	String	粗状态（创单后固定为 `待支付`，枚举见 §6）
`flowStatus`	String	细状态（创单后固定为 `待支付订金`，枚举见 §6）
`consultantId`	String	实际绑定的定制师 ID（雪花，JSON String）
`consultantSource`	String	定制师来源（`DEFAULT_ASSIGNED` / `LINK_BOUND` / `MANUAL`，见 §6）
`tags`	List<String>	系统自动打的标签（如 "二次复购"，与入参 tags 合并）
`createdAt`	LocalDateTime	创单时间
`productName`	String	产品名称（v5.18，弹窗标题用）
`tierName`	String	档位名（v5.18，弹窗副标题用）
`groupBatchName`	String	拼团批次名（v5.18，可空，自由出团 null）
`departureDate`	LocalDate	出发日（v5.18）
`returnDate`	LocalDate	返团日（v5.18，后端派生）
`totalAmount`	BigDecimal	订单总价（v5.18，元，2 位小数）
`depositAmount`	BigDecimal	建议定金金额（v5.18，元，2 位小数）
`depositRatio`	Integer	定金比例百分比（v5.18，DEPOSIT 模式有值；FULL 模式为 100）
`paymentMode`	String	支付模式（v5.18，`DEPOSIT` / `FULL`）
`expiryMinutes`	Integer	支付时限分钟数（v5.18，默认 1440 = 24h）
`payUrl`	String	支付页绝对 URL（v5.18，后端从 Nacos 配置 base + orderNo 拼接）
`customerName`	String	客户姓名（v5.18，回显，前端拼催款话术用）

6. 枚举 / 数据字典

所属字段	枚举类	值	中文	说明
`createSource`	OrderCreateSource	`CUSTOMER`	客户自助	客户在小程序自助下单
`createSource`	OrderCreateSource	`CONSULTANT`	定制师代下单	默认值，B 端代下单
`createSource`	OrderCreateSource	`OTA`	OTA 渠道	携程 / 美团等 OTA 引流
`createSource`	OrderCreateSource	`WALK_IN`	门店步入	线下门店现场下单
`createSource`	OrderCreateSource	`B2B`	B2B 渠道	旅行社代下单
`createSource`	OrderCreateSource	`VIP_REPURCHASE`	VIP 复购	老客户回购通道
`createSource`	OrderCreateSource	`REFERRAL`	老客户转介绍	—
`createSource`	OrderCreateSource	`PROMOTION`	营销活动	—
`createSource`	OrderCreateSource	`INTERNAL`	内部测试	不计入业绩
`orderStatus`	OrderStatus	`待支付`	—	创单后默认状态
`orderStatus`	OrderStatus	`待完善`	—	订金到账后进入
`orderStatus`	OrderStatus	`定制中`	—	出行人 + 房车齐后
`orderStatus`	OrderStatus	`已确认`	—	—
`orderStatus`	OrderStatus	`出行中`	—	—
`orderStatus`	OrderStatus	`已完成`	—	—
`orderStatus`	OrderStatus	`已取消`	—	—
`flowStatus`	OrderFlowStatus	`待支付订金`	—	创单后默认细状态
`consultantSource`	ConsultantSource	`DEFAULT_ASSIGNED`	系统默认分配	走轮询规则
`consultantSource`	ConsultantSource	`LINK_BOUND`	链接绑定	客户扫了定制师专属码
`consultantSource`	ConsultantSource	`MANUAL`	手动指定	B 端 admin 强制指派
`paymentMode`	PaymentMode	`DEPOSIT`	定金模式	30% 定金 + 余款
`paymentMode`	PaymentMode	`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；客户手机合法
❌ 不适用场景：
- 产品已下架 → 510101
- 出发日期是过去 → 510103
- 总人数为 0（4 个 count 都是 0 或 null）→ 510106
- 拼团批次过了报名截止 → 510104
⚠️ 特殊边界：
- 不传 createSource → 后端默认 CONSULTANT（不返错）
- 不传 roomCount → 写入 order_main.room_count = NULL，后续配房环节再补
- 不传 tags → 仅保留系统自动标签（如"含儿童"、"二次复购"）
- 出行人不在本接口传 → 创单成功后调 §2 traveler 模块的 POST /v3/admin/order/{id}/traveler/add 单独添加

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 起
创单后弹窗信息	前端二次调详情接口拼	接口直接返 20 字段，前端零回调
催款话术拼接	缺 `customerName` / `payUrl`	接口直返完整字段
`room_count` 持久化	`order_main` 表无该列	入库 `order_main.room_count`

11. 影响评估 / 回滚

11.1 影响评估

是否破坏向后兼容：否（v5.17 新增的 4 字段全为可选；v5.18 出参字段为追加，老前端忽略即可）
前端是否必须同步上线：否（不升前端 = 出参多字段不读，旧行为照常）
影响的其他后端服务：
- hl-product-service-v2（拉取产品快照、档位、定价；产品下架时返 510101）
- hl-user-service（默认定制师轮询）
影响已有数据：无（新增列 room_count 历史行 NULL，业务层兼容）

11.2 回滚方案

回滚方式：revert 对应 PR，恢复 v5.16 接口签名
回滚后清理：order_main.room_count 列保留（不影响业务），order_tag 表本次新建标签保留不清理
回滚耗时：≤ 5 分钟（mvn 重打包 + Nacos 配置不变）

12. 注意事项

上线时间：随 hl-order-service-v3 主服务一起发布，端口 8086
前端 workaround 清理点：
- 老前端"创单后再拉详情拼弹窗"的 workaround 可以撤了，本接口直接返 20 字段
- 老前端"按比例硬编码计算定金"的逻辑可以撤，本接口直接返 depositAmount / depositRatio
关联 DDL：order_main 表 v5.17 新增列 room_count INT NULL
关联 Redis key：pay_url_base（Nacos 配，本接口拼 payUrl 用）
重启服务：是（升级 hl-order-service-v3）

13. 关联 / 联系人

13.1 链接

Issue: 无（测试 changelog，验证 changelogs-v2/ 目录推送流程）
PR: 无
服务: hl-order-service-v3
Controller: OrderController.createOrder
ReqVO: OrderCreateReqVO
RespVO: OrderCreateRespVO
SRS / 设计文档: docs/order-v3/srs/order-cloud-v3-srs-v5.48.html §1.0~§1.3

13.2 联系人

后端负责人: @yaosutu
前端对接（管理后台）: 待指派

15 KiB 原始文件 Blame 文件历史 Unescape Escape