diff --git a/changelogs-v2/2026-06/18_4002_订单列表补tripNights-修改接口-管理后台.md b/changelogs-v2/2026-06/18_4002_订单列表补tripNights-修改接口-管理后台.md new file mode 100644 index 0000000..8d26008 --- /dev/null +++ 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 +``` + +响应(仅展示行程时长相关字段): +```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) |