补充核单Step1数据来源提交约定

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 联系人