diff --git a/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md b/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md deleted file mode 100644 index a33514b..0000000 --- a/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md +++ /dev/null @@ -1,360 +0,0 @@ -# 【修改接口·管理后台】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\ | ❌ | 订单标签名列表 | — | - -## 5. 出参（响应） - -### 5.1 响应字段（`Result`，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\ | 标签列表（含入参 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 典型成功 - -**请求**： - -```http -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 客户", "二次复购"] -} -``` - -**响应**： - -```json -{ - "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` 均省略。 - -**请求**： - -```json -{ - "productId": 30001234567, - "tierSeq": 2, - "departureDate": "2026-12-31", - "adultCount": 1, - "customerName": "李四", - "customerPhone": "13912340001" -} -``` - -**响应**（关注 `groupBatchName=null` / `tags` 仅含系统标签 / `paymentMode=FULL` / `depositRatio=100`）： - -```json -{ - "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` 指向已满批次） - -```json -{ - "productId": 30001234567, - "tierSeq": 1, - "departureDate": "2026-06-01", - "adultCount": 2, - "customerName": "王五", - "customerPhone": "13700001234", - "groupBatchId": 80001999999999 -} -``` - -**响应**： - -```json -{ - "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