wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

docs(order-v3): §4/§5/§9/§11/§12/§13 清理后端实现/派生/前端 use case 备注

浏览代码 
前端 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 行，聚焦接口契约。
这个提交包含在：
yaosutu 2026-05-18 15:44:12 +08:00
父节点 2a3ffb7737
当前提交 1701cf7a23
共有 1 个文件被更改，包括 46 次插入 和 75 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

121
changelogs-v2/2026-05/18_test_订单创建-修改接口-管理后台.md
查看文件

@ -42,16 +42,12 @@ v5.17 起入参扩展为 13 字段（新增 createSource / groupBatchId / roomCo
| `youngChildCount` | Integer | ❌ | 幼儿数 | `@Min(0)`，默认 0 | | `youngChildCount` | Integer | ❌ | 幼儿数 | `@Min(0)`，默认 0 |
| `babyCount` | Integer | ❌ | 婴儿数 | `@Min(0)`，默认 0 | | `babyCount` | Integer | ❌ | 婴儿数 | `@Min(0)`，默认 0 |
| `customerName` | String | ✅ | 客户姓名 | `@NotBlank` | | `customerName` | String | ✅ | 客户姓名 | `@NotBlank` |
| `customerPhone` | String | ✅ | 客户手机（明文传，DB 层 AES 加密） | `@NotBlank` | | `customerPhone` | String | ✅ | 客户手机（明文传，11 位数字） | `@NotBlank` |
| `customerRemark` | String | ❌ | 客户备注 | `@Size(max=500)` | | `customerRemark` | String | ❌ | 客户备注 | `@Size(max=500)` |
| `createSource` | String | ❌ | 创建来源（v5.17 新增，不传默认 `CONSULTANT`） | `@Size(max=20)`，枚举见 §6 | | `createSource` | String | ❌ | 创建来源（不传默认 `CONSULTANT`） | `@Size(max=20)`，枚举见 §6.1 |
| `groupBatchId` | Long | ❌ | 拼团批次 ID（v5.17 新增，自由出团为空） | — | | `groupBatchId` | Long | ❌ | 拼团批次 ID（自由出团传空） | — |
| `roomCount` | Integer | ❌ | 房间数（v5.17 新增，写入 `order_main.room_count`） | `@Min(1)` | | `roomCount` | Integer | ❌ | 房间数 | `@Min(1)` |
| `tags` | List\<String\> | ❌ | 订单标签名列表（v5.17 新增，写入 `order_tag`，`tag_type=PERSONAL`） | — | | `tags` | List\<String\> | ❌ | 订单标签名列表 | — |
> 后端从 JWT 派生：`adminId`、`consultantId`、`realName`，前端不传。
> 行程时间字段 `returnDate` / `tripDays` / `tripNights` 由后端从产品快照 + `departureDate` 派生。
> **出行人不在创单接口里传**，创建后按 §2 traveler 模块单独 API 添加。
## 5. 出参（响应） ## 5. 出参（响应）
@ -59,27 +55,27 @@ v5.17 起入参扩展为 13 字段（新增 createSource / groupBatchId / roomCo
| 字段 | 类型 | 说明 | | 字段 | 类型 | 说明 |
|------|------|------| |------|------|------|
| `id` | String | 订单主键（雪花 ID，JSON 序列化为 String 防精度丢失）| | `id` | String | 订单主键 |
| `orderNo` | String | 订单号（创单瞬间生成，永不变，例 `HL20260510143025001`）| | `orderNo` | String | 订单号，格式 `HL{yyyyMMddHHmmss}{3 位序号}`，例 `HL20260510143025001` |
| `displayOrderNo` | String | 展示订单号 = `orderNo + teamNo`（创单时 `teamNo` 为空，等同 `orderNo`）| | `displayOrderNo` | String | 展示订单号 = `orderNo + teamNo`；`teamNo` 为空时等同 `orderNo` |
| `orderStatus` | String | 粗状态（创单后固定为 `待支付`，枚举见 §6） | | `orderStatus` | String | 订单粗状态，创单后固定 `待支付`（枚举见 §6.2） |
| `flowStatus` | String | 细状态（创单后固定为 `待支付订金`，枚举见 §6） | | `flowStatus` | String | 订单细状态，创单后固定 `待支付订金`（枚举见 §6.3） |
| `consultantId` | String | 实际绑定的定制师 ID（雪花，JSON String）| | `consultantId` | String | 实际绑定的定制师 ID |
| `consultantSource` | String | 定制师来源（`DEFAULT_ASSIGNED` / `LINK_BOUND` / `MANUAL`，见 §6） | | `consultantSource` | String | 定制师来源（枚举见 §6.4） |
| `tags` | List\<String\> | 系统自动打的标签（如 "二次复购"，与入参 tags 合并） | | `tags` | List\<String\> | 标签列表（含入参 tags + 系统自动标签，如 "含儿童"、"二次复购"） |
| `createdAt` | LocalDateTime | 创单时间 | | `createdAt` | LocalDateTime | 创单时间 |
| `productName` | String | 产品名称（v5.18，弹窗标题用）| | `productName` | String | 产品名称 |
| `tierName` | String | 档位名（v5.18，弹窗副标题用）| | `tierName` | String | 档位名 |
| `groupBatchName` | String | 拼团批次名（v5.18，可空，自由出团 null）| | `groupBatchName` | String | 拼团批次名（自由出团时 null） |
| `departureDate` | LocalDate | 出发日（v5.18）| | `departureDate` | LocalDate | 出发日 |
| `returnDate` | LocalDate | 返团日（v5.18，后端派生）| | `returnDate` | LocalDate | 返团日 |
| `totalAmount` | BigDecimal | 订单总价（v5.18，元，2 位小数）| | `totalAmount` | BigDecimal | 订单总价（元，2 位小数） |
| `depositAmount` | BigDecimal | 建议定金金额（v5.18，元，2 位小数）| | `depositAmount` | BigDecimal | 建议定金金额（元，2 位小数） |
| `depositRatio` | Integer | 定金比例百分比（v5.18，DEPOSIT 模式有值；FULL 模式为 100）| | `depositRatio` | Integer | 定金比例百分比（`DEPOSIT` 模式有值；`FULL` 模式恒为 100） |
| `paymentMode` | String | 支付模式（v5.18，`DEPOSIT` / `FULL`）| | `paymentMode` | String | 支付模式（枚举见 §6.5） |
| `expiryMinutes` | Integer | 支付时限分钟数（v5.18，默认 1440 = 24h）| | `expiryMinutes` | Integer | 支付时限分钟数，默认 1440（=24h） |
| `payUrl` | String | 支付页绝对 URL（v5.18，后端从 Nacos 配置 base + orderNo 拼接） | | `payUrl` | String | 支付页绝对 URL |
| `customerName` | String | 客户姓名（v5.18，回显，前端拼催款话术用）| | `customerName` | String | 客户姓名（回显） |
## 6. 枚举 / 数据字典 ## 6. 枚举 / 数据字典
@ -300,17 +296,19 @@ Content-Type: application/json
## 9. 业务边界 ## 9. 业务边界
- ✅ **适用场景**：产品状态 = 上架；档位有效；出发日期 ≥ 今天；总人数 ≥ 1；客户手机合法 - ✅ **适用场景**：产品状态 = 上架；档位有效；出发日期 ≥ 今天；总人数 ≥ 1；客户手机合法（11 位数字）
- ❌ **不适用场景**： - ❌ **拒绝场景**：
- 产品已下架 → `510101` - 产品已下架 → `510101`
- 出发日期是过去 → `510103` - 出发日期早于今天 → `510103`
- 拼团批次过报名截止 → `510104`
- 拼团批次满员 → `510105`
- 总人数为 0（4 个 count 都是 0 或 null）→ `510106` - 总人数为 0（4 个 count 都是 0 或 null）→ `510106`
- 拼团批次过了报名截止 → `510104` - `createSource` 枚举非法 → `510107`
- ⚠️ **特殊边界**： - 客户手机格式非法 → `510108`
- **不传 `createSource`** → 后端默认 `CONSULTANT`（不返错） - ⚠️ **可选字段省略行为**：
- **不传 `roomCount`** → 写入 `order_main.room_count = NULL`，后续配房环节再补 - 不传 `createSource` → 接受，使用默认 `CONSULTANT`
- **不传 `tags`** → 仅保留系统自动标签（如"含儿童"、"二次复购"） - 不传 `roomCount` → 接受，返回的订单 `roomCount` 为 null
- **出行人不在本接口传** → 创单成功后调 §2 traveler 模块的 `POST /v3/admin/order/{id}/traveler/add` 单独添加 - 不传 `tags` → 接受，返回的 `tags` 仅含系统自动标签
## 10. 修改前后对比 ## 10. 修改前后对比
@ -340,50 +338,23 @@ Content-Type: application/json
| 行为 | v5.17 及之前 | v5.18 起 | | 行为 | v5.17 及之前 | v5.18 起 |
|------|--------------|----------| |------|--------------|----------|
| 创单后弹窗信息 | 前端二次调详情接口拼 | 接口直接返 20 字段，前端零回调 | | 创单成功响应字段 | 9 字段（仅订单元数据） | 20 字段（含产品名 / 价格 / 支付 URL） |
| 催款话术拼接 | 缺 `customerName` / `payUrl` | 接口直返完整字段 | | 是否需要二次调详情接口拿弹窗信息 | 是 | 否（响应已含全部弹窗字段） |
| `room_count` 持久化 | `order_main` 表无该列 | 入库 `order_main.room_count` |
## 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. 注意事项 ## 12. 注意事项
- 上线时间：随 `hl-order-service-v3` 主服务一起发布，端口 `8086` - 前端可清理的历史 workaround：
- 前端 workaround 清理点： - "创单后二次调详情接口拼弹窗" → 可撤；响应已含 20 字段
- 老前端"创单后再拉详情拼弹窗"的 workaround 可以撤了，本接口直接返 20 字段 - "按比例硬编码计算定金" → 可撤；响应直接返 `depositAmount` / `depositRatio`
- 老前端"按比例硬编码计算定金"的逻辑可以撤，本接口直接返 `depositAmount` / `depositRatio`
- 关联 DDL：`order_main` 表 v5.17 新增列 `room_count INT NULL`
- 关联 Redis key：`pay_url_base`（Nacos 配，本接口拼 `payUrl` 用）
- 重启服务：是（升级 `hl-order-service-v3`）
## 13. 关联 / 联系人 ## 13. 关联
### 13.1 链接
- **Issue**: 无（测试 changelog，验证 changelogs-v2/ 目录推送流程） - **Issue**: 无（测试 changelog，验证 changelogs-v2/ 目录推送流程）
- **PR**: 无 - **PR**: 无
- **服务**: `hl-order-service-v3` - **设计文档**: `docs/order-v3/srs/order-cloud-v3-srs-v5.48.html` §1.0 ~ §1.3
- **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 - **后端负责人**: @yaosutu
- **前端对接（管理后台）**: 待指派