From 9b093365389d2de77b4557a52b80ac9a9b952b49 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 20 Aug 2026 10:09:34 +0000 Subject: [PATCH] =?UTF-8?q?docs(house):=20=E9=85=8D=E6=88=BF=E8=A1=8C?= =?UTF-8?q?=E7=A8=8B=E6=A0=87=E8=AE=B0=E7=BB=88=E6=AD=A2=E6=9C=AA=E7=94=A8?= =?UTF-8?q?=E6=88=BF=E6=99=9A+=E5=BC=82=E5=B8=B8=E5=8E=9F=E5=9B=A0?= =?UTF-8?q?=E9=80=8F=E4=BC=A0=EF=BC=88#6111=20=E5=90=8E=E7=AB=AF=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude --- ...终止未用房晚与异常原因透传-修改接口-管理后台.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 changelogs-v2/2026-08/20_6111_配房行程标记终止未用房晚与异常原因透传-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/20_6111_配房行程标记终止未用房晚与异常原因透传-修改接口-管理后台.md b/changelogs-v2/2026-08/20_6111_配房行程标记终止未用房晚与异常原因透传-修改接口-管理后台.md new file mode 100644 index 0000000..6797c7a --- /dev/null +++ b/changelogs-v2/2026-08/20_6111_配房行程标记终止未用房晚与异常原因透传-修改接口-管理后台.md @@ -0,0 +1,91 @@ +--- +schema: "hl-changelog/v2" +ticket: "6111" +title: "配房行程标记终止未用房晚+异常原因透传" +consumer: "admin" +author: "wx" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "后端完成：PR #6116 已合并 dev-v3（squash 3dd65f62d）并部署 TEST（hl-order-service-v3 双实例 8086/8186，2026-08-20 17:49 重启）。行程接口响应 hotelGroup 新增异常原因 2 字段、配房行新增未用标记 2 字段（均可选只读，正常单为 null/不影响既有字段），前端按需取读即可。" +updated_at: "2026-08-20" +base: "dev-v3" +generated: "2026-08-20T17:55:00+08:00" +--- + +# 配房行程标记终止未用房晚+异常原因透传（#6111） + +## 背景 + +订单中止行程后，房务「配房行程」详情页看不到：(1) 哪几晚被运营在终止时勾选为「未用房晚」；(2) 异常桶旁的异常原因文案。本变更为房务侧补上这两个只读字段（纯新增，不影响既有字段）。 + +## 变更接口 + +| 接口 | 变更 | +| --- | --- | +| `GET /v3/admin/order/{id}/itinerary`（订单详情-行程安排） | **响应新增字段**（均可选只读，正常单为 null/false，不影响既有任何字段）：`hotelGroup.exceptionReason`（String，异常原因，仅 houseStatus=EXCEPTION 时有值）、`hotelGroup.exceptionReasonLabel`（String，同 exceptionReason 中文展示）、`hotelGroup.assignments[].unusedForTerminate`（Boolean，该晚是否终止勾选未用）、`hotelGroup.assignments[].unusedLabel`（String，未用标记文案「未用」，未标记为 null） | + +## 响应示例 + +`GET /v3/admin/order/{id}/itinerary` 返回（仅列本次新增字段，其余字段省略）： + +```json +{ + "code": 200, + "data": { + "hotelGroup": { + "houseStatus": "EXCEPTION", + "exceptionReason": "客户中止", + "exceptionReasonLabel": "客户中止", + "assignments": [ + { + "assignmentId": "2090093115967733761", + "dayNumber": 1, + "hotelName": "呼伦贝尔香格里拉大酒店", + "unusedForTerminate": true, + "unusedLabel": "未用" + }, + { + "assignmentId": "2090093115976122369", + "dayNumber": 2, + "hotelName": "呼伦贝尔香格里拉大酒店", + "unusedForTerminate": true, + "unusedLabel": "未用" + } + ] + } + } +} +``` + +说明：该单已终止且运营勾选两晚均未用，故两行 `unusedForTerminate=true`、`unusedLabel="未用"`；`houseStatus=EXCEPTION` 故 `exceptionReason` 透出终止原因。正常单（非终止）`exceptionReason/Label` 为 null、`unusedForTerminate=false`、`unusedLabel` 为 null。 + +## 行为口径 + +- 4 个字段均为**只读、可选**：正常单（未终止）`exceptionReason/Label` 为 null、`unusedForTerminate=false`、`unusedLabel` 为 null，接口不报错。 +- `unusedForTerminate=true` 的行即终止时运营勾选的「未用房晚」，前端可渲染「未用」标记 + 行级「资源释放」按钮。 +- **行级资源释放**复用现有 `DELETE /v3/admin/order/assignments/{id}`（软删+恢复库存，CONFIRMED 行自动解冻），前端按该行 `assignmentId` 调即可，**无新端点**。 +- `exceptionReason` 来源为终止行程原因，仅异常桶（houseStatus=EXCEPTION）有值。 + +## 前端动作 + +无必须动作。需要展示「未用」标记时读 `assignments[].unusedForTerminate/unusedLabel`；需要显示异常原因时读 `hotelGroup.exceptionReason(Label)`；需要行级释放按钮时对该行调 `DELETE /v3/admin/order/assignments/{assignmentId}`。 + +## 验证证据 + +- 单测：OrderDetailConverterTest 44 / TerminateRefundServiceTest 8 / OrderDetailServiceTest 88 全绿（新增 7 例覆盖命中/未命中/未终止/null 边界）。 +- 架构门禁：*ArchTest 44 全绿（跨子聚合走 Service 契约，零违规）。 +- 部署：PR #6116 squash 合并 dev-v3（merge commit `3dd65f62d`）；测试服 hl-order-service-v3 双实例 8086/8186 于 2026-08-20 17:49 滚动重启健康。 +- 网关实测（TEST，admin token）：终止单 `GET /v3/admin/order/2090093100083904514/itinerary` 返 200，`hotelGroup.exceptionReason="客户中止"`，两行配房 `unusedForTerminate=true`/`unusedLabel="未用"`；正常单（CUSTOMIZING）`exceptionReason=null`，符合「异常有值/正常 null」口径。 + +## 关联 / 联系人 + +- Issue：https://git.1814.love:8443/wx/HL/issues/6111 +- PR：https://git.1814.love:8443/wx/HL/pulls/6116 +- Commit（merge）：https://git.1814.love:8443/wx/HL/commit/3dd65f62d +- 后端负责人：wx