181 行
8.8 KiB
Markdown
181 行
8.8 KiB
Markdown
# 【行为变更·管理后台】订单调整保留配房与房务驳回定制师待办（#4907）
|
||
|
||
> 服务：`hl-order-service-v3`
|
||
>
|
||
> 生效分支：`dev-v3`
|
||
>
|
||
> 接口结构：新增“单条配房晚次与资源原子调整”接口；其余沿用订单调整、房务详情、最终确认和房务驳回现有接口
|
||
>
|
||
> 后端状态：PR [#4915](https://git.1814.love:8443/wx/HL/pulls/4915) 已合并；测试环境部署任务 `b60dccde` 成功，`8086/8186` 双实例 UP
|
||
>
|
||
> 联调证据：2026-07-12 网关三场景探针通过，覆盖跨晚次原子移动、订单改期库存迁移、库存不足补偿和房务驳回待办
|
||
|
||
## 1. 订单调整后的房务口径
|
||
|
||
定制师通过以下接口修改行程天数、出发日期或出行人数：
|
||
|
||
```http
|
||
POST /v3/admin/order/{orderId}/adjustment/submit
|
||
```
|
||
|
||
后端现在按最新行程重新对齐住宿需求逐晚结构。既有配房不会被自动删除；真正改出发日期时，仍在新行程晚数范围内的配房会按 `dayNumber` 自动平移入住日期：
|
||
|
||
| 调整项 | 前端应展示的结果 |
|
||
|---|---|
|
||
| 增加行程天数 | 原晚次配房保持；新增夜显示待配房 |
|
||
| 减少行程天数 | 需求夜数减少；多余旧配房继续显示，等待房务人工清空/替换 |
|
||
| 修改出发日期 | `stayDate = 新出发日期 + dayNumber - 1`；酒店、房型、房间数、价格、扣库存选择和备注原样保留；配房退回询房中重新确认 |
|
||
| 同时改日期和天数 | 新行程范围内的配房自动平移；新增夜为空待配；超出新晚数的旧配房不自动删除 |
|
||
| 修改出行人数 | 原配房继续显示；完整配房回到待最终确认，不完整则回配房中 |
|
||
|
||
新增夜允许空候选占位，`roomCount` 未填或为 `0` 均可提交；负数仍会被后端拒绝。前端不要为了绕过校验自行填造假的间数。
|
||
|
||
### 改期库存原子性
|
||
|
||
- `deductInventory=false`：只平移订单配房快照，不操作资源库存。
|
||
- `deductInventory=true`：后端先逐晚预占新日期库存；全部成功后才修改订单、行程、需求和配房日期，并释放旧日期库存。
|
||
- 任意新日期库存不足或日历缺失：整次订单调整返回 `808901`；订单日期、需求版本、配房和旧库存全部保持原样，已临时预占的新日期库存自动补偿。
|
||
- 前端收到 `808901` 时只提示库存不足，不得将本地表单当作已保存。
|
||
|
||
### 房务人工修改单条配房
|
||
|
||
当前前端仅在 `ItineraryPanel.vue` 只读显示日期，并通过整晚 `POST assignments` 做“配房/替换”。这不能安全实现“把 6 月 1 日的既有配房移动到 6 月 5 日”：若前端组合调用新增目标行和删除原行，中间任一步失败都会造成配房或库存半套。
|
||
|
||
请为每条既有配房增加“调整”入口，统一调用以下原子接口：
|
||
|
||
```http
|
||
PUT /v3/admin/order/hotel-requirements/{requirementId}/assignments/{assignmentId}/placement
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"dayNumber": 5,
|
||
"hotelId": "200001",
|
||
"roomTypeId": "300001",
|
||
"roomCategory": "DELUXE",
|
||
"roomCount": 2,
|
||
"protoPrice": "520.00",
|
||
"settlementPrice": "480.00",
|
||
"settleType": "sign",
|
||
"deductInventory": true,
|
||
"syncProtocolPrice": false,
|
||
"syncSettlementPrice": false,
|
||
"syncSettleType": false,
|
||
"remark": "改期后重新询房"
|
||
}
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": null,
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
字段规则：
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `dayNumber` | 是 | 目标晚次，从当前详情 `days[]` 选择。必须按当前行程映射：若出发日已从 6 月 1 日改为 6 月 5 日，则 6 月 5 日是当前第 1 晚，传 `1`，不是按“日期中的 5”传 `5` |
|
||
| `hotelId` | 是 | 目标酒店 ID，字符串透传 |
|
||
| `roomTypeId` | 是 | 目标房型 ID，字符串透传 |
|
||
| `roomCategory` | 是 | 房型字典 code |
|
||
| `roomCount` | 是 | 目标房间数，必须大于 0 |
|
||
| `deductInventory` | 是 | 是否扣系统库存；缺失返回 `808124` |
|
||
| `protoPrice` / `settlementPrice` | 否 | 不传时按目标房型和目标入住日读取资源价格日历；金额按字符串提交 |
|
||
| `settleType` | 否 | `cash` / `sign` / `company` |
|
||
| 三个 `sync*` | 否 | 仅用户明确选择同步时传 `true` |
|
||
| `remark` | 否 | 不传时保留原备注 |
|
||
|
||
前端交互要求：
|
||
|
||
1. 目标日期不是自由输入框。下拉选项来自当前详情的有效住宿晚次，展示“第 N 晚 / 日期 / 城市”，提交其 `dayNumber`；不要提交 `stayDate`。
|
||
如果订单已改期但某条历史配房仍显示 6 月 1 日，当前行程第 1 晚已是 6 月 5 日，则房务选择“第 1 晚 / 6 月 5 日”提交；后端会把同一配房 ID 的 `stayDate` 更正为 6 月 5 日。
|
||
2. 同一弹窗必须允许同时修改目标晚次、酒店、房型、房间数、是否扣库存、协议价、结算价、支付方式和备注。
|
||
3. 后端按当前 `order_itinerary_day` 推导并保存 `stayDate`。旧配房 ID 不变，成功后该行退回 `INQUIRING`，前端关闭弹窗并重新加载详情。
|
||
4. 扣库存场景由后端先占目标库存、提交后释放原库存；失败时原配房和原库存不变。前端禁止再组合调用“目标晚新增 + 原晚删除”。
|
||
5. 现有整晚 `POST /v3/admin/order/hotel-requirements/{requirementId}/assignments` 继续用于新增候选和同晚整组对账，不替代本接口的跨晚次原子移动。
|
||
|
||
主要错误码：
|
||
|
||
| code | 处理 |
|
||
|---|---|
|
||
| `808102` | 目标晚次已不在当前行程，刷新详情后重选 |
|
||
| `808117` | 目标晚已有同酒店、同房型、同库存口径配房，提示合并房间数 |
|
||
| `808124` | 未选择是否扣库存 |
|
||
| `808125` | 配房或行程被并发修改，刷新详情后重试 |
|
||
| `808126` | 原配房声明扣库存但缺少可释放的持有日志；禁止继续调整，需先核对库存 |
|
||
| `808130` | 目标房间数小于已录入的家庭分房条数 |
|
||
| `808901` | 目标日期资源库存不足；保留原页面数据 |
|
||
|
||
## 2. 最终确认
|
||
|
||
```http
|
||
POST /admin/house/assignments/requirements/{requirementId}/finalize
|
||
```
|
||
|
||
- 没有任何配房时允许最终确认，用于客人自行解决住宿的场景。
|
||
- 一旦存在任意配房，所有 active 配房必须已确认，并按晚次精确覆盖当前行程住宿日期。
|
||
- 缺夜、多余夜、日期不匹配或存在未确认配房返回：
|
||
|
||
```json
|
||
{
|
||
"code": 808181,
|
||
"message": "已有配房与当前行程不一致，请先补配、替换或清空",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
前端收到该错误后保留当前配房数据，提示房务逐日处理；不得清空页面状态或隐藏超出新行程的旧配房。
|
||
|
||
## 3. 房务驳回后的定制师待办
|
||
|
||
```http
|
||
POST /v3/admin/order/{orderId}/hotel-requirement/supplier-reject
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"returnRemark": "酒店无法满足当前房型，请重新确认需求"
|
||
}
|
||
```
|
||
|
||
驳回成功后，后端会为原定制师显式创建一条待办：
|
||
|
||
```json
|
||
{
|
||
"todoType": "ASSIGN_ROOM",
|
||
"todoLabel": "房型需求 · 已打回",
|
||
"status": "PENDING",
|
||
"assigneeRoleKey": "CUSTOMIZER",
|
||
"relatedBizType": "HOTEL_REQUIREMENT",
|
||
"relatedBizId": "2075933198734303233"
|
||
}
|
||
```
|
||
|
||
该待办与订单当前是否仍处于“补出行人资料”阶段无关。定制师待办页按现有待办接口正常展示并跳转订单调整即可。
|
||
|
||
## 4. 前端验收
|
||
|
||
1. 增天后原配房不消失，新增夜可单独配房；不再出现 `roomCount 必须 > 0`。
|
||
2. 改期后原配房按晚次自动平移日期，酒店、房型、房间数和价格快照不变，状态退回询房中。
|
||
3. 改期同时增减天数时，新范围内配房平移、新增夜为空、超范围旧配房保留。
|
||
4. 房务可把单条既有配房原子移动到另一当前有效晚次，并同时修改酒店、房型、房间数和库存口径；日期始终与目标晚次一致。
|
||
5. 扣库存配房改期成功时旧库存释放、新库存扣减；任一晚不足时整单不变。
|
||
6. 减天后的多余旧配房继续显示，最终确认被后端阻断，直到人工清空/替换。
|
||
7. 修改人数后已有配房保持，房务重新最终确认。
|
||
8. 零配房订单允许最终确认。
|
||
9. 房务驳回后，原定制师能看到“房型需求 · 已打回”待办。
|
||
10. 历史需求和旧配房均继续展示，不得只渲染当前需求而丢失历史证据。
|
||
|
||
## 5. 后端验证证据
|
||
|
||
- PR：`wx/HL#4910`、`wx/HL#4911`、`wx/HL#4913`
|
||
- 测试环境部署任务：`440ed4d1`，`8086/8186` 双实例均 UP
|
||
- 模块全量：5499 项；与 clean baseline 相同的既有 5 项失败，无新增回归
|
||
- 网关全流程报告：`D:/work2/HL-v3/.tmp/house-adjustment-flow-probe-20260712-024715.json`
|
||
- 实测通过：增晚、减晚、人数变化、改期+增晚同次提交、酒店/房型/房间数替换、入住日期对齐、人工清空、零配房最终确认、房务驳回待办、库存成功迁移、库存不足整单回滚
|
||
|