# 订单列表出参新增 tripNights（行程晚数）— 修改接口 — 管理后台

> **变更类型**：修改接口（出参新增字段，✨ 向后兼容）
> **端类型**：管理后台
> **生效日期**：2026-06-18
> **影响接口数**：1 个（订单列表）

---

## 一、接口背景

订单详情接口（`GET /v3/admin/order/{id}`）一直同时返回 `tripDays`（行程天数）和 `tripNights`（行程晚数），而订单列表接口（`GET /v3/admin/order/list`）只返回了 `tripDays`，缺少 `tripNights`，导致前端列表页无法显示「X天Y晚」格式。

本次补齐列表口径，与详情保持一致（Issue #4002，PR #4003）。

---

## 二、变更清单

| 序号 | 端点 | 变更类型 | 影响字段 |
|---|---|---|---|
| 1 | `GET /v3/admin/order/list` | ✨ 出参新增字段 | 新增 `tripNights`（Integer，行程晚数） |

---

## 三、接口详情

### 3.1 订单列表

| 项目 | 说明 |
|---|---|
| 方法 | `GET` |
| 路径 | `/v3/admin/order/list` |
| 描述 | 管理后台订单列表，分页返回 `OrderListItemRespVO` |
| 认证 | 需要 JWT Token（管理后台登录态） |
| 幂等性 | 是（纯查询） |
| 限流 | 无特殊限流 |

---

## 四、接口入参

本次改动**不涉及入参变化**，入参略。

---

## 五、出参字段

以下为 `OrderListItemRespVO` 中行程时长字段组完整清单（列出全组便于前端核对）：

| 字段名 | 类型 | 必返 | 说明 |
|---|---|---|---|
| `tripDays` | Integer | 否（可 null） | 行程天数，数据源 `order_main.trip_days`；未定行程时为 null |
| `tripNights` | Integer | 否（可 null） | **【本次新增】** 行程晚数，数据源 `order_main.trip_nights`；未定行程时为 null |

> `tripDays` 与 `tripNights` 均来自订单主表，取值关系示例：4天行程 → `tripDays=4, tripNights=3`。

---

## 六、枚举 / 数据字典

无枚举变化。`tripNights` 为纯整数字段，无关联枚举。

---

## 七、错误码

本次改动无新增错误码。

---

## 八、示例

### 8.1 典型成功 — 列表项含行程晚数

请求：
```
GET /v3/admin/order/list?pageNo=1&pageSize=20
Authorization: Bearer <token>
```

响应（仅展示行程时长相关字段）：
```json
{
  "code": 200,
  "data": {
    "list": [
      {
        "id": "1234567890123456789",
        "tripDays": 4,
        "tripNights": 3
      }
    ],
    "total": 1
  }
}
```

### 8.2 边界情况 — 行程未确定（tripNights 为 null）

行程尚未落定时，`tripDays` 和 `tripNights` 均为 null：

```json
{
  "code": 200,
  "data": {
    "list": [
      {
        "id": "9876543210987654321",
        "tripDays": null,
        "tripNights": null
      }
    ],
    "total": 1
  }
}
```

前端渲染「X天Y晚」时需做 null 判断，两个字段同时有值才拼接展示。

### 8.3 业务失败 — 无相关错误码

本次为纯新增字段，不引入新的业务失败场景；接口鉴权失败沿用已有 401 / 403 行为，无新增错误码。

---

## 九、业务边界

**适用**：
- 所有状态的订单列表项均包含 `tripNights` 字段（字段存在，值可能为 null）

**不适用**：
- 无例外

**特殊边界**：
- `tripNights` 和 `tripDays` 同源（`order_main.trip_nights` / `trip_days`），两者要么同时有值，要么同时为 null；不存在一个有值一个为 null 的情况
- 前端拼接展示建议：`tripDays != null && tripNights != null` 时才渲染「`${tripDays}天${tripNights}晚`」，否则不渲染或渲染占位符

---

## 十、修改前后对比

### 字段级对比

| VO | 字段 | 变更前 | 变更后 |
|---|---|---|---|
| `OrderListItemRespVO`（列表项） | `tripDays` | 存在 | 存在（不变） |
| `OrderListItemRespVO`（列表项） | `tripNights` | **不存在** | **新增，Integer，可 null** |

### 行为级对比

| 项目 | 变更前 | 变更后 |
|---|---|---|
| 列表页展示行程时长 | 只能显示天数（如「4天」） | 可同时显示天数和晚数（如「4天3晚」） |
| 与详情口径是否一致 | 不一致（详情有 tripNights，列表没有） | 一致（列表和详情均含 tripNights） |

---

## 十一、影响评估 / 回滚

### 破坏兼容性

**否**。本次为纯新增字段，旧字段均保留，接口向后兼容。

### 前端需同步上线

**否（不强制）**。前端可按需消费 `tripNights`：
- 若需展示「X天Y晚」格式，接线 `tripNights` 字段即可
- 若暂不展示晚数，忽略该字段不影响已有渲染逻辑

### 回滚方案

如需回滚，后端 revert PR #4003，`tripNights` 字段从 `OrderListItemRespVO` 移除，列表响应恢复不含该字段。

---

## 十二、注意事项

1. **null 处理**：`tripNights` 未定行程时为 null，前端渲染「X天Y晚」需做 null 判断，不要直接字符串拼接
2. **与详情对齐**：详情接口（`GET /v3/admin/order/{id}`）的 `OrderMainVO` 早已含 `tripNights`，本次只是补齐列表，字段语义完全一致
3. **零 DDL**：`order_main.trip_nights` 列已存在，本次改动仅补了 VO 字段映射，数据库无变化

---

## 十三、关联 / 联系人

| 项目 | 链接 |
|---|---|
| Issue | https://git.1814.love:8443/wx/HL/issues/4002 |
| PR | https://git.1814.love:8443/wx/HL/pulls/4003 |
| 实现 commit | https://git.1814.love:8443/wx/HL/commit/727a0dfa4aee3a41d739bd6a4c3568d899ba7406 |
| 后端负责人 | 腰苏图（yaosutu） |