feat(changelog): 订单列表接口新增出参字段 tripNights（Issue #4002，PR #4003）

GET /v3/admin/order/list 的 OrderListItemRespVO 补齐 tripNights（行程晚数），与订单详情口径一致，前端可展示「X天Y晚」格式。
2026-06-18 17:10:24 +08:00 · 2026-06-18 17:10:24 +08:00 · ab83944191
--- a/changelogs-v2/2026-06/18_4002_订单列表补tripNights-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/18_4002_订单列表补tripNights-修改接口-管理后台.md
@ -0,0 +1,192 @@
+# 订单列表出参新增 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） |