# 【修改接口·管理后台】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. 枚举 / 数据字典

> 接口里出现的枚举按字段分开列。本接口共 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；客户手机合法
- ❌ **不适用场景**：
  - 产品已下架 → `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`](https://git.1814.love:8443/wx/HL/src/branch/dev-v3/hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/OrderController.java#L70-L76)
- **ReqVO**: [`OrderCreateReqVO`](https://git.1814.love:8443/wx/HL/src/branch/dev-v3/hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/vo/OrderCreateReqVO.java)
- **RespVO**: [`OrderCreateRespVO`](https://git.1814.love:8443/wx/HL/src/branch/dev-v3/hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/vo/OrderCreateRespVO.java)
- **SRS / 设计文档**: `docs/order-v3/srs/order-cloud-v3-srs-v5.48.html` §1.0~§1.3

### 13.2 联系人

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