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:02 +08:00 · 2026-05-18 15:04:02 +08:00 · 0aee0ceddb
--- a/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md
+++ b/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md
@ -0,0 +1,353 @@
+# 【修改接口·管理后台】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 典型成功
+
+**请求**：
+
+```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
+- **前端对接（管理后台）**: 待指派