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

docs(changelog): 撤回 #3451 settleType 入参 changelog（用户决定暂不推）

浏览代码 
Revert f78430a。内容备份在 D:\tmp\changelog_3451_settleType_backup.md，需要时可重推。
这个提交包含在：
yaosutu 2026-06-04 15:54:41 +08:00
父节点 f78430a11f
当前提交 29ac2669cb
共有 1 个文件被更改，包括 0 次插入 和 346 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

346
changelogs-v2/2026-06/04_3451_核单住宿行入参settleType-修改接口-管理后台.md
查看文件

@ -1,346 +0,0 @@
# 二期 v3：核单 Step 1 住宿录入 —— 新增入参 settleType，派生行不再自动派生 paymentMethod
> **服务**: hl-order-service-v3 | **端**: 管理后台
> **接口**: `PUT /v3/admin/order/{orderId}/settlement/step1`
> **Issue**: [#3451](https://git.1814.love:8443/wx/HL/issues/3451) | **PR**: [#3452](https://git.1814.love:8443/wx/HL/pulls/3452)
> **日期**: 2026-06-04
> **影响**: ⚠️ **破坏性** —— 派生行（hotelAssignmentId 非空）原先可不传 paymentMethod，后端自动派生；改后必须传 settleType 或 paymentMethod，否则报错。
---
## 一、接口背景
核单 Step 1「录住宿明细」接口用于保存一批住宿核单行（全量替换语义）。
行分两类：
- **派生行**：`hotelAssignmentId` 非空，从房务配房记录派生基础字段
- **临时行**：`hotelAssignmentId` 为 null，完全手填
原逻辑：派生行的 `paymentMethod`（付款方式）由后端查 house 配房记录的 `settleType` 自动填充，前端可不传。
本次变更：**删除后端自动派生逻辑**，前端必须在每行明确传入 `settleType`（或直接传 `paymentMethod`），后端不再主动查库派生。
---
## 二、变更清单
| 变更类型 | 字段 / 行为 | 说明 |
|---|---|---|
| ✨ 新增入参字段 | `items[].settleType` | 结算类型简码（cash / sign / company），与 paymentMethod 二选一，新增优先入口 |
| 🔧 行为变更 | 派生行 paymentMethod 不再自动派生 | 后端不再查配房记录自动填充；前端必须显式传 settleType 或 paymentMethod |
| ⚠️ 删除错误码 | 584004 | 原「配房记录不存在」码删除，不再有此分支 |
| ⚠️ 删除错误码 | 584063 | 原「无法派生 paymentMethod」码删除 |
| ⚠️ 新增错误场景 | 584062 | 派生行/临时行既未传 settleType 又未传 paymentMethod 时触发 |
| ✨ 新增错误码校验 | 584064 | settleType 字典值非法（非 cash/sign/company）时触发 |
---
## 三、接口详情
| 属性 | 值 |
|---|---|
| 方法 | `PUT` |
| 路径 | `/v3/admin/order/{orderId}/settlement/step1` |
| 接口名 | Step 1 录住宿核单明细 |
| 认证 | Bearer Token（管理后台 JWT） |
| 幂等性 | 全量替换语义，相同请求体重复提交安全（幂等） |
| 限流 | 无特殊限流 |
| Content-Type | `application/json` |
---
## 四、接口入参
### 4.1 路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `orderId` | Long | 是 | 订单 ID |
### 4.2 请求体字段
**顶层**
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `items` | Array\<HotelItemVO\> | 是 | 住宿明细行数组（全量替换） |
**HotelItemVO 字段**
| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| `id` | Long | 否 | — | 已存在行 ID（更新）；空表示新增 |
| `hotelAssignmentId` | Long | 否 | — | 派生行配房 assignment ID；临时行为 null |
| `stayDate` | String (date) | 是 | 格式 `yyyy-MM-dd` | 入住日期 |
| `hotelName` | String | 是 | 最长 200 字符 | 酒店名（派生行拷贝自配房，临时行手填） |
| `roomType` | String | 否 | 最长 64 字符 | 房型（多房型可填"混合"或留空） |
| `roomCount` | Integer | 是 | ≥ 1 | 总间数 |
| `plannedCost` | BigDecimal | 是 | ≥ 0，单位元 | 计划成本 |
| `actualCost` | BigDecimal | 是 | ≥ 0，单位元 | 实际成本 |
| `settleType` | String | 条件必填 | cash / sign / company | **新增字段**。结算类型简码，后端映射为 paymentMethod；当 paymentMethod 未传时必填 |
| `paymentMethod` | String | 条件必填 | CASH_PAID / SIGNED / COMPANY_PAID | 付款方式枚举值；若传则直接使用，优先级高于 settleType |
| `remark` | String | 否 | 最长 500 字符 | 备注 |
**条件必填规则**（全类型行统一适用）：
| 情况 | 规则 |
|---|---|
| `paymentMethod` 非空 | 直接使用，settleType 忽略 |
| `paymentMethod` 为空，`settleType` 非空 | 后端按映射表转换为 paymentMethod |
| `paymentMethod` 和 `settleType` 都为空 | 报 584062 |
---
## 五、出参字段
**顶层返回 `Result<SettlementHotelSaveRespVO>`**
| 字段 | 类型 | 说明 |
|---|---|---|
| `addedIds` | Array\<Long\> | 本次新增行的 ID 列表 |
| `updatedIds` | Array\<Long\> | 本次更新行的 ID 列表 |
| `deletedIds` | Array\<Long\> | 本次软删行的 ID 列表（全量替换时缺失的行） |
| `totalActualCost` | BigDecimal | 保存后当前订单住宿核单 actual_cost 汇总值（元） |
---
## 六、枚举 / 数据字典
### settleType（入参，本次新增字段）
| 值 | 中文含义 |
|---|---|
| `cash` | 现付 |
| `sign` | 签单 |
| `company` | 公司支付 |
### paymentMethod（入参，原有字段）
| 值 | 中文含义 | 对应 settleType |
|---|---|---|
| `CASH_PAID` | 现付 | `cash` |
| `SIGNED` | 签单 | `sign` |
| `COMPANY_PAID` | 公司支付 | `company` |
**settleType → paymentMethod 映射关系**
| settleType | 映射为 paymentMethod |
|---|---|
| `cash` | `CASH_PAID` |
| `sign` | `SIGNED` |
| `company` | `COMPANY_PAID` |
---
## 七、错误码
| 错误码 | 含义 | 触发场景 |
|---|---|---|
| 584062 | 必须指定 paymentMethod（无配房关联/未提供结算类型） | 任意行既未传 settleType 又未传 paymentMethod 时 |
| 584064 | settleType 字典值非法 | settleType 不在 cash/sign/company 范围内 |
| 400 | 参数校验失败 | paymentMethod 不在 SIGNED/COMPANY_PAID/CASH_PAID 范围内；roomCount/plannedCost/actualCost 为 null 等 Bean Validation 报错 |
**删除的错误码**（本次移除，前端不必再处理）：
| 已删错误码 | 原含义 |
|---|---|
| 584004 | 配房记录不存在 |
| 584063 | 无法派生 paymentMethod |
---
## 八、示例
### 8.1 典型成功 —— 派生行 + 临时行混合
**请求**
```
PUT /v3/admin/order/1900000000001/settlement/step1
Authorization: Bearer <token>
Content-Type: application/json
```
```json
{
"items": [
{
"id": 9100000000010,
"hotelAssignmentId": 8800000000001,
"stayDate": "2026-07-10",
"hotelName": "布达拉宫酒店",
"roomType": "标准间",
"roomCount": 2,
"plannedCost": 800.00,
"actualCost": 880.00,
"settleType": "sign",
"remark": ""
},
{
"hotelAssignmentId": null,
"stayDate": "2026-07-11",
"hotelName": "临时酒店（自定义）",
"roomType": null,
"roomCount": 1,
"plannedCost": 300.00,
"actualCost": 300.00,
"paymentMethod": "CASH_PAID",
"remark": "临时加行"
}
]
}
```
**响应**
```json
{
"code": 200,
"msg": "success",
"data": {
"addedIds": [9100000000088],
"updatedIds": [9100000000010],
"deletedIds": [],
"totalActualCost": 1180.00
}
}
```
---
### 8.2 边界情况 —— paymentMethod 和 settleType 同时传（paymentMethod 优先）
**请求（paymentMethod 优先，settleType 被忽略）**
```json
{
"items": [
{
"hotelAssignmentId": 8800000000002,
"stayDate": "2026-07-10",
"hotelName": "测试酒店",
"roomCount": 1,
"plannedCost": 0.00,
"actualCost": 0.00,
"settleType": "cash",
"paymentMethod": "COMPANY_PAID"
}
]
}
```
**响应**（paymentMethod 直接用 COMPANY_PAID，settleType 忽略）
```json
{
"code": 200,
"msg": "success",
"data": {
"addedIds": [9100000000099],
"updatedIds": [],
"deletedIds": [],
"totalActualCost": 0.00
}
}
```
---
### 8.3 业务失败 —— 未传 settleType 也未传 paymentMethod
**请求**
```json
{
"items": [
{
"hotelAssignmentId": 8800000000003,
"stayDate": "2026-07-10",
"hotelName": "布达拉宫酒店",
"roomCount": 2,
"plannedCost": 600.00,
"actualCost": 600.00
}
]
}
```
**响应**
```json
{
"code": 584062,
"msg": "（无配房关联/未提供结算类型）必须指定 paymentMethod",
"data": null
}
```
---
## 九、业务边界
**适用场景**
- 管理员在核单流程第 1 步保存住宿明细
- 可多次调用（草稿模式，全量替换，最后一次调用数据生效）
- 支持派生行（关联配房记录）和临时行（完全手填）混合提交
**不适用场景**
- 订单已完成核单提交（Step 6 执行后），此时行锁定，Step 1 接口不可再调用
- 订单不在「待核单」状态下调用将被业务校验拦截
**特殊边界**
- `items` 为空数组 `[]` 时，等同于清空全部住宿明细行（软删所有现存行）
- 全量替换：请求里没有的 `id` 对应现存行将被软删，`deletedIds` 返回被删的 ID 列表
- 派生行的 `hotelName` / `stayDate` / `roomType` 由前端从配房列表取值后传入（后端不再从配房记录二次查库填充）
---
## 十、修改前后对比
### 字段级
| 字段 | 改前 | 改后 |
|---|---|---|
| `items[].settleType` | **不存在** | ✨ 新增，String，枚举 cash/sign/company |
| `items[].paymentMethod`（派生行） | 可不传，后端自动从配房记录 settleType 派生 | 必须传（或通过 settleType 间接传），后端不再自动查库 |
### 行为级
| 行为 | 改前 | 改后 |
|---|---|---|
| 派生行 paymentMethod 来源 | 后端查 house 配房记录 settleType 自动派生 | 前端从配房列表取 settleType 传入，后端映射 |
| 未传 paymentMethod 时 | 派生行：后端静默补充；临时行：报 584004 → 584063 | 无论派生行还是临时行：报 **584062** |
---
## 十一、影响评估 / 回滚
**影响评估**
- 前端**必须**在构造 Step 1 请求时，为每一行（含派生行）提供 `settleType`（推荐）或 `paymentMethod`
- `settleType` 的值来源：调用房务配房列表接口，取配房记录的 `settleType` 字段
- 改动为破坏性变更，但当前处于开发阶段，无需向后兼容，直接硬切换
**是否破坏兼容**：是（派生行原有 `paymentMethod` 不传的调用会报 584062）
**前端是否需同步上线**：是，前端必须补传 `settleType` 后才能正常调用
**回滚方案**：开发阶段，老订单可删，无需回滚保护；如需回滚，重新部署旧版 hl-order-service-v3 即可
---
## 十二、注意事项
1. `settleType` 是**字符串小写简码**（cash/sign/company），与现有 `paymentMethod` 枚举大写风格不同，注意区分
2. 推荐前端统一使用 `settleType` 传入（更直观），让后端做映射；`paymentMethod` 字段保留兼容直传
3. 房务配房列表接口返回的 `settleType` 字段即为此处入参的来源，两者枚举值一致
4. 全量替换语义：每次调用请带上**全部**行（包括未改动行），否则缺失行会被软删
---
## 十三、关联 / 联系人
- **Issue**: [#3451 核单 saveHotel 入参新增 settleType 字段](https://git.1814.love:8443/wx/HL/issues/3451)
- **PR**: [#3452](https://git.1814.love:8443/wx/HL/pulls/3452)
- **后端负责人**: yst