wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

docs(refund): 退款详情 orderInfo 补订单字段（#4356 修改接口-管理后台）

浏览代码 
GET /v3/admin/refund/application/{id} 出参 orderInfo 块原恒为 null，
本次修复接通 OrderService 后正常填充，并新增 teamNo / tierName / peopleSummary
三字段，与退款列表接口（PR #4344）保持口径一致。非破坏性变更。

Issue: wx/HL#4356
PR:    wx/HL#4359
这个提交包含在：
yaosutu 2026-06-24 17:47:00 +08:00
父节点 d06d8ed6b4
当前提交 597096129b
共有 1 个文件被更改，包括 254 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

254
changelogs-v2/2026-06/24_4356_退款详情orderInfo补订单字段-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,254 @@
# 退款详情 orderInfo 补订单字段（原恒为 null，本次接通并扩 3 字段）
- **接口**：`GET /v3/admin/refund/application/{id}`
- **变更类型**：修改接口（出参 orderInfo 块由恒为 null 修复为正常填充，并新增 3 字段；非破坏性，其余字段不变）
- **日期**：2026-06-24
- **端类型**：管理后台
- **Issue**：https://git.1814.love:8443/wx/HL/issues/4356
- **PR**：https://git.1814.love:8443/wx/HL/pulls/4359
- **负责人**：腰苏图（yst）
---
## ① 接口背景
退款申请详情接口（`GET /v3/admin/refund/application/{id}`）的出参包含一个 `orderInfo` 嵌套对象，用于展示退款所属订单的概要快照（订单号、产品名、出发日期、联系人等）。
此前由于后端未正确接通 OrderService，`orderInfo` 字段**恒为 null**，导致详情页无法展示任何订单信息。本次修复接通 OrderService，`orderInfo` 现可正常填充；同时与退款列表接口（`/application/page`，PR #4344）保持口径一致，补充了团号、规格档位、人员数描述三个字段。
---
## ② 变更清单
| 变更 | 类型 | 说明 |
|---|---|---|
| `orderInfo` 由恒为 null 修复为正常填充 | 🔧 行为修复 | 后端已接通 OrderService，原有 orderInfo 字段（orderNo / productName / departureDate / contactName / contactPhone）现可正常返回 |
| `orderInfo.teamNo` 新增 | ✨ 出参新增字段 | 订单所属团号，无团号时为 null |
| `orderInfo.tierName` 新增 | ✨ 出参新增字段 | 订单规格/套餐档位名称，无档位时为 null |
| `orderInfo.peopleSummary` 新增 | ✨ 出参新增字段 | 人员数描述，后端已拼接好中文字符串（如 `2成人2儿童`），全为 0 时 null |
**无破坏性变更**：入参不变，顶层出参其余字段不变，枚举值不变，错误码不变。
---
## ③ 接口详情
| 项 | 说明 |
|---|---|
| **方法** | GET |
| **路径** | `/v3/admin/refund/application/{id}` |
| **功能** | 退款申请详情查询 |
| **认证** | 需要管理后台 JWT（`Authorization: Bearer <token>`） |
| **幂等** | 是（只读） |
| **限流** | 无特殊限流 |
---
## ④ 接口入参
### 4.1 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | long | ✅ | 退款申请 ID |
无请求体，无 Query 参数变化。
---
## ⑤ 出参字段
### orderInfo 对象（修复后完整字段列表）
位于 `data.orderInfo`，订单查不到时整个对象返回 null。
| 字段名 | 类型 | 可为 null | 说明 | 本次变化 |
|---|---|---|---|---|
| `orderNo` | string | ✅ | 订单号 | 原有字段，修复前恒 null，现正常返回 |
| `productName` | string | ✅ | 产品名称 | 原有字段，修复前恒 null，现正常返回 |
| `departureDate` | string (yyyy-MM-dd) | ✅ | 出发日期 | 原有字段，修复前恒 null，现正常返回 |
| `contactName` | string | ✅ | 联系人姓名（管理端明文） | 原有字段，修复前恒 null，现正常返回 |
| `contactPhone` | string | ✅ | 联系电话（管理端明文） | 原有字段，修复前恒 null，现正常返回 |
| `teamNo` | string | ✅ | 订单所属团号；非团期订单为 null | **本次新增** |
| `tierName` | string | ✅ | 规格/套餐档位名称；无档位为 null | **本次新增** |
| `peopleSummary` | string | ✅ | 人员数描述，如 `2成人2儿童`；各人数全为 0 时为 null | **本次新增** |
> 注意：详情顶层出参（`data` 根节点）另有一个独立的 `departureDate` 字段，为退款申请自身的快照值，与 `data.orderInfo.departureDate`（从订单实时查询）含义不同，本次未改。
### 顶层出参其余字段（保持不变）
| 字段名 | 类型 | 说明 |
|---|---|---|
| `id` | long | 退款申请 ID |
| `applicationNo` | string | 退款申请单号 |
| `orderId` | long | 关联订单 ID |
| `status` | string | 退款申请状态枚举 |
| `refundAmount` | number | 退款金额（分） |
| `reason` | string | 退款原因 |
| `departureDate` | string (yyyy-MM-dd) | 退款申请快照出发日期（非 orderInfo 内的字段） |
| `createTime` | string (datetime) | 申请创建时间 |
| `travelerList` | array | 出行人列表 |
| `timeline` | array | 审批时间线 |
| ... | ... | 其余字段均保持不变 |
---
## ⑥ 枚举 / 数据字典
无新增或变更枚举值。
---
## ⑦ 错误码
无新增错误码。以下为原有通用错误码：
| 错误码 | 说明 | 前端处理建议 |
|---|---|---|
| 200 | 成功 | — |
| 404 / 业务错误码 | 退款申请不存在 | 提示「退款申请不存在」并返回列表页 |
> `orderInfo` 为 null 不触发接口报错，仅表示关联订单查不到，前端需对 `orderInfo` 做空判断后再读取内部字段。
---
## ⑧ 示例
### 8.1 典型成功（orderInfo 正常填充）
**请求**
```
GET /v3/admin/refund/application/1234567890123456789
Authorization: Bearer <admin-token>
```
**响应（data 节选）**
```json
{
"code": 200,
"data": {
"id": 1234567890123456789,
"applicationNo": "RF2026062400001",
"orderId": 9876543210987654321,
"status": "PENDING_REVIEW",
"refundAmount": 99800,
"reason": "行程取消",
"departureDate": "2026-08-10",
"orderInfo": {
"orderNo": "ORD20260601001",
"productName": "呼籁·云南深度7日游",
"departureDate": "2026-08-10",
"contactName": "张三",
"contactPhone": "13800138000",
"teamNo": "GB20260801001",
"tierName": "豪华双人间",
"peopleSummary": "2成人2儿童"
},
"travelerList": [],
"timeline": []
}
}
```
### 8.2 边界情况（非团期订单，teamNo 为 null；无档位，tierName 为 null；全为成人，peopleSummary 有值）
**响应（orderInfo 节选）**
```json
{
"orderInfo": {
"orderNo": "ORD20260602002",
"productName": "定制私家团",
"departureDate": "2026-09-01",
"contactName": "李四",
"contactPhone": "13900139000",
"teamNo": null,
"tierName": null,
"peopleSummary": "3成人"
}
}
```
### 8.3 业务失败（订单已删除，orderInfo 整体为 null）
> 此情况接口不报错，HTTP 200 正常返回，仅 orderInfo 为 null。
**响应（data 节选）**
```json
{
"code": 200,
"data": {
"id": 1234567890000000001,
"applicationNo": "RF2026062400002",
"orderId": 9999999999999999999,
"status": "PENDING_REVIEW",
"refundAmount": 50000,
"orderInfo": null
}
}
```
---
## ⑨ 业务边界
**适用**
- 退款申请 ID 有效，关联订单存在时，`orderInfo` 正常填充所有字段。
- 订单为团期订单时，`teamNo` 填充团号；否则为 null。
- 订单有规格档位时，`tierName` 填充档位名称；否则为 null。
- `peopleSummary` 仅包含非零人数段（成人→儿童→幼儿→婴儿顺序），各人数全为 0 时返回 null。
**不适用 / 特殊边界**
- 关联订单已删除或 orderId 为空时，`orderInfo` 整体返回 null，接口不报错，前端需做空判断。
- `data.departureDate`（顶层）与 `data.orderInfo.departureDate` 含义不同：前者是退款申请创建时的快照，后者来自订单实时查询，两者可能不一致，前端不可混用。
---
## ⑩ 修改前后对比
### 字段级对比
| 字段 | 修改前 | 修改后 |
|---|---|---|
| `orderInfo` | 恒为 `null`（后端未接通 OrderService） | 正常对象，订单查不到时才为 null |
| `orderInfo.orderNo` | 不可用（整体 null） | 订单号字符串 |
| `orderInfo.productName` | 不可用（整体 null） | 产品名称字符串 |
| `orderInfo.departureDate` | 不可用（整体 null） | `yyyy-MM-dd` 格式日期字符串 |
| `orderInfo.contactName` | 不可用（整体 null） | 联系人姓名（管理端明文） |
| `orderInfo.contactPhone` | 不可用（整体 null） | 联系电话（管理端明文） |
| `orderInfo.teamNo` | 字段不存在 | **新增**，无团号时 null |
| `orderInfo.tierName` | 字段不存在 | **新增**，无档位时 null |
| `orderInfo.peopleSummary` | 字段不存在 | **新增**，全 0 时 null |
### 行为级对比
| 维度 | 修改前 | 修改后 |
|---|---|---|
| 退款详情订单信息可用性 | 完全不可用（恒 null） | 正常可用 |
| 与退款列表口径一致性 | 不一致（列表有订单信息，详情没有） | 一致（新增三字段与列表 PR #4344 对齐） |
---
## ⑪ 影响评估 / 回滚
**兼容性**：非破坏性变更。`orderInfo` 从 null 变为有值，不影响前端已有的空判断逻辑；新增三字段前端不读即无感知。
**前端同步上线**：无需同步上线。但建议前端在退款详情页接入 `orderInfo` 内的订单信息展示（原先恒 null 导致该区块无法显示），本次修复后数据已可用。
**回滚方案**：若需回滚，后端回退 PR #4359 即可。`orderInfo` 恢复为 null，前端已有空判断逻辑不受影响。
---
## ⑫ 注意事项
1. **双 departureDate 区分**：出参顶层 `data.departureDate` 是退款申请快照日期；`data.orderInfo.departureDate` 是订单侧出发日期，二者含义不同，前端读取时注意字段路径。
2. **orderInfo 空判断**：订单查不到时 `orderInfo` 整体为 null，前端需在读取 `orderInfo` 内任意字段前先做非空判断，否则会报 NPE。
3. **peopleSummary 格式**：字符串由后端拼接，格式固定为中文（如 `2成人1儿童`），前端直接展示无需再做格式化。
---
## ⑬ 关联 / 联系人
- **Issue**：https://git.1814.love:8443/wx/HL/issues/4356
- **PR**：https://git.1814.love:8443/wx/HL/pulls/4359
- **退款列表同期关联 PR**：https://git.1814.love:8443/wx/HL/pulls/4344（退款列表新增相同三字段，口径对齐）
- **后端负责人**：腰苏图（yst）