hl-api-changelog/changelogs-v2/2026-08/21_6111_配房行程页待渲染未用房晚标记异常原因与行级释放按钮-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	6111	终止行程订单配房行程页待渲染：未用房晚标记+异常原因+行级释放按钮（后端字段已上线）	admin	wx(GIT)	修改接口	deployed	verified	verified	mmg	9172700f			后端 #6116 已合并 dev-v3 并部署 TEST，行程接口已返回 houseStatus=EXCEPTION 时的 exceptionReason(Label) 与 assignments[].unusedForTerminate/unusedLabel 4 个只读字段（网关实测已验证，订单 26-9250）。本条为前端向告知：配房行程页需补渲染「未用房晚标记」「异常原因文案」「行级资源释放按钮」三处，字段已具备，前端按需取读即可。	2026-08-21	dev-v3

终止行程订单配房行程页待渲染：未用房晚标记+异常原因+行级释放按钮（#6111）

存放目录: 二期(v3, order-v3 工单) → changelogs-v2/2026-08/

服务: hl-order-service-v3 (端口 8086/8186) PR: #6116 Issue: #6111 日期: 2026-08-21 影响范围: 管理后台-订单详情-配房行程页（仅终止行程/异常单）

---

⚠️ 关键变化

订单终止行程后，配房行程页当前看不到：哪几晚被运营勾选为「未用房晚」、异常桶旁的异常原因、行级「资源释放」入口。后端字段已全部上线（网关实测订单 26-9250 已返回），本条告知前端按下方「待渲染清单」接入即可，无需后端再改动。

---

一、背景

运营在终止行程时会勾选「未用房晚」，房务侧据此判断哪些房晚可释放资源；异常桶也需要向房务展示终止原因。这两块信息后端在 #6116 已透传到行程接口，但前端配房行程页尚未渲染，导致房务看不到「未用」标记与异常原因，也没有行级释放入口。

测试服实测（订单 26-9250，已终止，houseStatus=EXCEPTION）接口返回：

字段	实测值	说明
hotelGroup.houseStatus	EXCEPTION（Label「异常」）	异常桶
hotelGroup.exceptionReason / exceptionReasonLabel	客户家中急事	终止原因 ✅ 已返回
assignments[0]（第1晚）	unusedForTerminate=false，unusedLabel=null	已入住，不标未用
assignments[1]（第2晚）	unusedForTerminate=true，unusedLabel=未用	✅ 该标「未用」

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	订单详情-行程安排	GET	/v3/admin/order/{orderId}/itinerary	响应新增字段（已上线）	新增 4 个只读字段，正常单为 null/false，不影响既有字段
2	行级资源释放	DELETE	/v3/admin/order/assignments/{assignmentId}	复用现有端点（无新增）	软删+恢复库存，CONFIRMED 行自动解冻

---

三、接口详情

1. 订单详情-行程安排 GET /v3/admin/order/{orderId}/itinerary

本次前端需读取的新增字段（均可选只读，正常单为 null/false）：

出参（仅列本次新增字段，其余字段省略）

字段	位置	类型	说明
houseStatus	data.hotelGroup	String	房务状态机值。终止行程后 = EXCEPTION（异常）
exceptionReason	data.hotelGroup	String	异常原因，仅 houseStatus=EXCEPTION 时有值，否则 null
exceptionReasonLabel	data.hotelGroup	String	exceptionReason 中文展示，否则 null
unusedForTerminate	data.hotelGroup.assignments[]	Boolean	该晚是否终止勾选未用，正常单为 false
unusedLabel	data.hotelGroup.assignments[]	String	未用标记文案「未用」，未标记为 null
assignmentId	data.hotelGroup.assignments[]	String	行级释放时调 DELETE 端点用此 id

响应示例

{
  "code": 200,
  "data": {
    "hotelGroup": {
      "houseStatus": "EXCEPTION",
      "houseStatusLabel": "异常",
      "exceptionReason": "客户家中急事",
      "exceptionReasonLabel": "客户家中急事",
      "assignments": [
        {
          "assignmentId": "2089945850783346690",
          "dayNumber": 1,
          "hotelName": "呼伦贝尔香格里拉大酒店",
          "unusedForTerminate": false,
          "unusedLabel": null
        },
        {
          "assignmentId": "2089945850842066945",
          "dayNumber": 2,
          "hotelName": "呼伦贝尔香格里拉大酒店",
          "unusedForTerminate": true,
          "unusedLabel": "未用"
        }
      ]
    }
  },
  "success": true
}

2. 行级资源释放 DELETE /v3/admin/order/assignments/{assignmentId}

• 对 unusedForTerminate=true 的行，按该行 assignmentId 调本端点。
• 行为：软删该晚配房行 + 恢复对应库存；CONFIRMED 行自动解冻。
• 无新端点，复用现有删除接口。

---

四、前端待渲染清单（houseStatus === "EXCEPTION" 时）

待渲染项	数据来源	处理
异常原因文案	hotelGroup.exceptionReasonLabel	异常桶旁显示终止原因（如「客户家中急事」）
未用房晚标记	assignments[].unusedForTerminate / unusedLabel	为 true 的行渲染「未用」标记
行级「资源释放」按钮	该行 assignmentId	仅对 unusedForTerminate=true 的行显示，点击调 DELETE /v3/admin/order/assignments/{assignmentId}

正常订单（houseStatus 非 EXCEPTION）上述字段为 null/false，渲染逻辑不触发，既有页面不受影响。

---

五、边界行为

• 正常单（未终止）→ exceptionReason(Label) 为 null、unusedForTerminate=false、unusedLabel 为 null，接口不报错、页面不渲染。
• 已入住房晚（如 26-9250 第1晚）→ unusedForTerminate=false，不标「未用」、不出释放按钮。
• 字段缺失（老数据）→ 视为 null/false，不异常。

---

六、影响评估

• 是否破坏向后兼容: 否（纯新增只读字段，正常单为 null/false）
• 前端是否必须同步上线: 否（不接入不影响既有功能；接入后房务才能看到未用标记/异常原因/释放入口）
• 前端 workaround 清理点: 无

---

七、不影响范围

• 仅影响: 管理后台-订单详情-配房行程页（终止行程/异常单）
• 零影响:
  • 订单详情读取的既有字段
  • 正常进行中订单的配房行程渲染
  • C 端行程接口
  • 车务侧（车辆执行段「释放车辆/司机占用」已在 #6107/#6114 接入，与本条独立）

---

八、测试环境已验证

真实网关调用（TEST，admin token）：

GET /v3/admin/order/2089945804415315969/itinerary  → 200 ✓
  hotelGroup.houseStatus=EXCEPTION / houseStatusLabel=异常 ✓
  hotelGroup.exceptionReason=客户家中急事 / exceptionReasonLabel=客户家中急事 ✓
  assignments[0](第1晚) unusedForTerminate=false / unusedLabel=null ✓（已入住不标）
  assignments[1](第2晚) unusedForTerminate=true / unusedLabel=未用 ✓

验证订单： order_id=2089945804415315969（团号 26-9250，行程中客户03，已终止）

---

九、相关历史 PR

PR	Issue	说明	是否仍有效
#6116	#6111	后端补 4 个只读字段（exceptionReason/unusedForTerminate 等）	✅ 有效（已上线 TEST）
—（前端向）	#6111	本条：告知前端接入配房行程页三处渲染	✅ 最新

---

十、相关文档

• 关联 Issue: wx/HL#6111
• 关联 PR: wx/HL#6116
• 同工单配套（纯前端按钮禁用，已 verified）: changelogs-v2/2026-08/20_6111_终止行程订单配房三按钮禁用-修改接口-管理后台.md

关联 / 联系人

链接

• Issue: #6111
• PR: #6116
• Merge commit: 3dd65f62d

联系人

• 后端负责人: @wx