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

GET /v3/admin/order/list 的 OrderListItemRespVO 补齐 tripNights（行程晚数），
与订单详情口径一致，前端可展示「X天Y晚」格式。

2026-06-18 17:10:24 +08:00

5.4 KiB

原始文件 Blame 文件历史

订单列表出参新增 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>

响应（仅展示行程时长相关字段）：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": "1234567890123456789",
        "tripDays": 4,
        "tripNights": 3
      }
    ],
    "total": 1
  }
}

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

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

{
  "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 移除，列表响应恢复不含该字段。

十二、注意事项

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

十三、关联 / 联系人

项目	链接
Issue	wx/HL#4002
PR	wx/HL#4003
实现 commit	`727a0dfa4a`
后端负责人	腰苏图（yaosutu）

5.4 KiB 原始文件 Blame 文件历史 Unescape Escape