From 1701cf7a2323e2a13084e6188be857e4bf5908f6 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 18 May 2026 15:44:12 +0800 Subject: [PATCH] =?UTF-8?q?docs(order-v3):=20=C2=A74/=C2=A75/=C2=A79/?= =?UTF-8?q?=C2=A711/=C2=A712/=C2=A713=20=E6=B8=85=E7=90=86=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E5=AE=9E=E7=8E=B0/=E6=B4=BE=E7=94=9F/=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=20use=20case=20=E5=A4=87=E6=B3=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 前端 changelog 只写接口契约（入参/出参/类型/枚举/错误码/边界/示例）。 本次砍掉 7 类无效内容： 1. 后端字段来源（JWT 派生 / 产品快照派生） 2. 后端实现细节（雪花 ID JSON String / DB 层 AES / 从 Nacos 拼接） 3. 后端 DB 字段（写入 order_main.room_count / order_tag tag_type=PERSONAL） 4. 后端运维（端口 / DDL / Redis key / 重启 / 回滚耗时） 5. 前端 use case（弹窗标题用 / 前端拼催款话术） 6. 其他接口跳转（出行人不在本接口传，调 §2 单独添加） 7. 影响其他后端服务 字段 +46 / -75 净减 29 行，聚焦接口契约。 --- .../18_test_订单创建-修改接口-管理后台.md | 121 +++++++----------- 1 file changed, 46 insertions(+), 75 deletions(-) diff --git a/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md b/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md index 6c5bfe2..a33514b 100644 --- a/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md +++ b/changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md @@ -42,16 +42,12 @@ v5.17 起入参扩展为 13 字段（新增 createSource / groupBatchId / roomCo | `youngChildCount` | Integer | ❌ | 幼儿数 | `@Min(0)`，默认 0 | | `babyCount` | Integer | ❌ | 婴儿数 | `@Min(0)`，默认 0 | | `customerName` | String | ✅ | 客户姓名 | `@NotBlank` | -| `customerPhone` | String | ✅ | 客户手机（明文传，DB 层 AES 加密） | `@NotBlank` | +| `customerPhone` | String | ✅ | 客户手机（明文传，11 位数字） | `@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 添加。 +| `createSource` | String | ❌ | 创建来源（不传默认 `CONSULTANT`） | `@Size(max=20)`，枚举见 §6.1 | +| `groupBatchId` | Long | ❌ | 拼团批次 ID（自由出团传空） | — | +| `roomCount` | Integer | ❌ | 房间数 | `@Min(1)` | +| `tags` | List\ | ❌ | 订单标签名列表 | — | ## 5. 出参（响应） @@ -59,27 +55,27 @@ v5.17 起入参扩展为 13 字段（新增 createSource / groupBatchId / roomCo | 字段 | 类型 | 说明 | |------|------|------| -| `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 合并） | +| `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 | 产品名称（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，回显，前端拼催款话术用）| +| `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. 枚举 / 数据字典 @@ -300,17 +296,19 @@ Content-Type: application/json ## 9. 业务边界 -- ✅ **适用场景**：产品状态 = 上架；档位有效；出发日期 ≥ 今天；总人数 ≥ 1；客户手机合法 -- ❌ **不适用场景**： +- ✅ **适用场景**：产品状态 = 上架；档位有效；出发日期 ≥ 今天；总人数 ≥ 1；客户手机合法（11 位数字） +- ❌ **拒绝场景**： - 产品已下架 → `510101` - - 出发日期是过去 → `510103` + - 出发日期早于今天 → `510103` + - 拼团批次过报名截止 → `510104` + - 拼团批次满员 → `510105` - 总人数为 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` 单独添加 + - `createSource` 枚举非法 → `510107` + - 客户手机格式非法 → `510108` +- ⚠️ **可选字段省略行为**： + - 不传 `createSource` → 接受，使用默认 `CONSULTANT` + - 不传 `roomCount` → 接受，返回的订单 `roomCount` 为 null + - 不传 `tags` → 接受，返回的 `tags` 仅含系统自动标签 ## 10. 修改前后对比 @@ -340,50 +338,23 @@ Content-Type: application/json | 行为 | v5.17 及之前 | v5.18 起 | |------|--------------|----------| -| 创单后弹窗信息 | 前端二次调详情接口拼 | 接口直接返 20 字段，前端零回调 | -| 催款话术拼接 | 缺 `customerName` / `payUrl` | 接口直返完整字段 | -| `room_count` 持久化 | `order_main` 表无该列 | 入库 `order_main.room_count` | +| 创单成功响应字段 | 9 字段（仅订单元数据） | 20 字段（含产品名 / 价格 / 支付 URL） | +| 是否需要二次调详情接口拿弹窗信息 | 是 | 否（响应已含全部弹窗字段） | -## 11. 影响评估 / 回滚 +## 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`） +- 前端可清理的历史 workaround： + - "创单后二次调详情接口拼弹窗" → 可撤；响应已含 20 字段 + - "按比例硬编码计算定金" → 可撤；响应直接返 `depositAmount` / `depositRatio` -## 13. 关联 / 联系人 - -### 13.1 链接 +## 13. 关联 - **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 联系人 - +- **设计文档**: `docs/order-v3/srs/order-cloud-v3-srs-v5.48.html` §1.0 ~ §1.3 - **后端负责人**: @yaosutu -- **前端对接（管理后台）**: 待指派