From 0aee0ceddbf45afb9fbb62eb8a61a1288728a53f Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 18 May 2026 15:04:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(order-v3):=20=E8=AE=A2=E5=8D=95=E5=88=9B?= =?UTF-8?q?=E5=BB=BA=E6=8E=A5=E5=8F=A3=20v3=20admin=20POST=20/v3/admin/ord?= =?UTF-8?q?er=20=E6=8E=A5=E5=8F=A3=E7=8E=B0=E7=8A=B6=E5=BF=AB=E7=85=A7?= =?UTF-8?q?=EF=BC=88=E6=B5=8B=E8=AF=95=20v2=20=E7=9B=AE=E5=BD=95=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 启用 changelogs-v2/ 新目录，前端 v3 项目仓库后续从此目录读 changelog。 此份为 v3 admin 订单创建接口（OrderController.createOrder）的 v5.18 完整快照， 含 13 节固定模板（入参 13 字段 / 出参 20 字段 / 枚举 21 项 / 错误码 9 个 / 3 组示例）。 --- .../18_test_订单创建-修改接口-管理后台.md | 353 ++++++++++++++++++ 1 file changed, 353 insertions(+) create mode 100644 changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md diff --git a/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md b/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md new file mode 100644 index 0000000..d4caa7e --- /dev/null +++ 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\ | ❌ | 订单标签名列表（v5.17 新增，写入 `order_tag`，`tag_type=PERSONAL`） | — | + +> 后端从 JWT 派生：`adminId`、`consultantId`、`realName`，前端不传。 +> 行程时间字段 `returnDate` / `tripDays` / `tripNights` 由后端从产品快照 + `departureDate` 派生。 +> **出行人不在创单接口里传**，创建后按 §2 traveler 模块单独 API 添加。 + +## 5. 出参（响应） + +### 5.1 响应字段（`Result`，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\ | 系统自动打的标签（如 "二次复购"，与入参 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 +- **前端对接（管理后台）**: 待指派