diff --git a/changelogs-v2/2026-07/18_5043_核单Step1住宿成本字段-修改接口-管理后台.md b/changelogs-v2/2026-07/18_5043_核单Step1住宿成本字段-修改接口-管理后台.md index 140351f..cd942f5 100644 --- a/changelogs-v2/2026-07/18_5043_核单Step1住宿成本字段-修改接口-管理后台.md +++ b/changelogs-v2/2026-07/18_5043_核单Step1住宿成本字段-修改接口-管理后台.md @@ -1,11 +1,44 @@ # 【修改接口·管理后台】核单 Step1 住宿成本字段 (#5043) -> **PR**: #5047 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-18 16:50 +> **PR**: #5047 / #5162 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-23 09:53 ## 1. 接口背景 核单 Step1 住宿成本明细需要对齐原型里的酒店资源、房型资源、核算单价、来源和确认状态展示。现有接口保留原路径,在 `GET/PUT /v3/admin/order/{orderId}/settlement/step1` 上做兼容增强。 +### 1.1 2026-07-23 前端对接补充(数据来源提交约定) + +`sourceType` 只用于区分住宿明细的数据来源,不决定行是否可编辑。行的可编辑性继续由 `settlementConfirmStatus` 控制,本次不新增 `deletable` 或 `sourceFieldsEditable` 字段。 + +| 数据来源 | GET 返回 / PUT 回传的 `sourceType` | PUT 回传的 `sourceId` | PUT 回传的 `hotelAssignmentId` | +|----------|------------------------------------------|----------------------------|---------------------------------------| +| 后台配房自动行 | `HOUSE_ASSIGNMENT` | 原样回传 GET 返回的配房记录 ID | 原样回传 GET 返回的配房记录 ID | +| 前端手动新增行 | `MANUAL` | `null` | `null` | + +`sourceType` 当前仍为非必填字段:未传时,后端可根据 `hotelAssignmentId` 推断数据来源。为了稳定保留来源信息,前端保存时应按上表显式回传。 + +**后台配房自动行 PUT 关键字段**: + +```json +{ + "sourceType": "HOUSE_ASSIGNMENT", + "sourceId": "2077233886282088401", + "hotelAssignmentId": "2077233886282088401", + "settlementConfirmStatus": "UNCONFIRMED" +} +``` + +**前端手动新增行 PUT 关键字段**: + +```json +{ + "sourceType": "MANUAL", + "sourceId": null, + "hotelAssignmentId": null, + "settlementConfirmStatus": "UNCONFIRMED" +} +``` + ## 2. 变更清单 | # | 接口 | 方法 | 路径 | 变更类型 | 说明 | @@ -43,7 +76,7 @@ |------|------|------|------|----------| | `items` | array | 是 | 住宿成本明细行数组,全量替换保存 | 不允许为 `null` | | `items[].id` | string | 否 | 已存在行 ID;全量替换保存时可不传 | 长整型字符串 | -| `items[].hotelAssignmentId` | string/null | 否 | 配房 assignment ID;手工行可为 `null` | 长整型字符串或 `null` | +| `items[].hotelAssignmentId` | string/null | 否 | 配房 assignment ID;后台配房自动行应原样回传,手动行传 `null` | 长整型字符串或 `null` | | `items[].hotelId` | string/null | 否 | 酒店资源 ID;本次新增 | 长整型字符串或 `null` | | `items[].roomTypeId` | string/null | 否 | 房型资源 ID;本次新增 | 长整型字符串或 `null` | | `items[].stayDate` | string | 是 | 入住日期 | `yyyy-MM-dd`,不能早于订单出发日 | @@ -57,9 +90,9 @@ | `items[].paymentMethod` | string | 否 | 付款方式;与 `settleType` 二选一 | `SIGNED` / `COMPANY_PAID` / `CASH_PAID` | | `items[].paymentMethodName` | string | 否 | 付款方式中文名,仅展示字段;保存时可不传;本次新增 | 最大 32 字符 | | `items[].settleType` | string | 否 | 配房结算类型;与 `paymentMethod` 二选一 | `cash` / `sign` / `company` | -| `items[].sourceType` | string | 否 | 来源类型;本次新增;不传时按是否有 `hotelAssignmentId` 派生 | `HOUSE_ASSIGNMENT` / `MANUAL` / `TEMPLATE` | +| `items[].sourceType` | string | 否 | 仅标识数据来源;后台配房行回传 `HOUSE_ASSIGNMENT`,手动行传 `MANUAL`;不传时后端按 `hotelAssignmentId` 推断 | `HOUSE_ASSIGNMENT` / `MANUAL` / `TEMPLATE` | | `items[].sourceTypeName` | string | 否 | 来源类型中文名,仅展示字段;保存时可不传;本次新增 | 最大 32 字符 | -| `items[].sourceId` | string/null | 否 | 来源业务 ID;本次新增;配房来源默认等于 `hotelAssignmentId` | 长整型字符串或 `null` | +| `items[].sourceId` | string/null | 否 | 来源业务 ID;后台配房自动行应原样回传配房记录 ID,手动行传 `null` | 长整型字符串或 `null` | | `items[].settlementConfirmStatus` | string | 否 | 核单确认状态;本次新增;不传默认 `CONFIRMED` | `UNCONFIRMED` / `CONFIRMED` | | `items[].settlementConfirmStatusName` | string | 否 | 核单确认状态中文名,仅展示字段;保存时可不传;本次新增 | 最大 32 字符 | | `items[].remark` | string/null | 否 | 备注 | 最大 500 字符 | @@ -294,8 +327,10 @@ Content-Type: application/json ## 9. 业务边界 - `PUT` 是全量替换保存;前端保存时应提交页面当前完整明细列表。 -- `hotelAssignmentId` 有值时通常表示配房来源;`hotelAssignmentId` 为空时通常表示手工补充行。 +- GET 返回的后台配房自动行,PUT 保存时应原样回传 `sourceType=HOUSE_ASSIGNMENT`、`sourceId` 和 `hotelAssignmentId`,两个 ID 都是对应配房记录 ID。 +- 前端手动新增行,PUT 保存时传 `sourceType=MANUAL`、`sourceId=null`、`hotelAssignmentId=null`。 - `sourceType` 不传时,`hotelAssignmentId` 有值默认 `HOUSE_ASSIGNMENT`,否则默认 `MANUAL`。 +- `sourceType` 只区分数据来源,不决定可编辑性;可编辑性继续由 `settlementConfirmStatus` 控制。 - `sourceId` 不传且 `sourceType=HOUSE_ASSIGNMENT` 时,默认使用 `hotelAssignmentId`;其他来源可为 `null`。 - `unitPrice` 不传且 `roomCount > 0`、`actualCost` 有值时,返回时会按 `actualCost / roomCount` 保留 2 位小数。 - `settlementConfirmStatus` 不传时默认 `CONFIRMED`。 @@ -353,6 +388,9 @@ Content-Type: application/json - **Issue**: [#5043](https://git.1814.love:8443/wx/HL/issues/5043) - **PR**: [#5047](https://git.1814.love:8443/wx/HL/pulls/5047) - **Merge commit**: [0a9e83b39](https://git.1814.love:8443/wx/HL/commit/0a9e83b390d135c05b43bc18afe1b190329bf85c) +- **对接补充 Issue**: [#5157](https://git.1814.love:8443/wx/HL/issues/5157) +- **对接补充 PR**: [#5162](https://git.1814.love:8443/wx/HL/pulls/5162) +- **对接补充 Merge commit**: [bc5669fd5](https://git.1814.love:8443/wx/HL/commit/bc5669fd5) ### 13.2 联系人