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

#### 响应示例

```json
{
  "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](https://git.1814.love:8443/wx/HL/issues/6111)
- 关联 PR: [wx/HL#6116](https://git.1814.love:8443/wx/HL/pulls/6116)
- 同工单配套（纯前端按钮禁用，已 verified）: `changelogs-v2/2026-08/20_6111_终止行程订单配房三按钮禁用-修改接口-管理后台.md`

## 关联 / 联系人

### 链接

- **Issue**: [#6111](https://git.1814.love:8443/wx/HL/issues/6111)
- **PR**: [#6116](https://git.1814.love:8443/wx/HL/pulls/6116)
- **Merge commit**: [3dd65f62d](https://git.1814.love:8443/wx/HL/commit/3dd65f62d)

### 联系人

- **后端负责人**: @wx