597096129b
GET /v3/admin/refund/application/{id} 出参 orderInfo 块原恒为 null，
本次修复接通 OrderService 后正常填充，并新增 teamNo / tierName / peopleSummary
三字段，与退款列表接口（PR #4344）保持口径一致。非破坏性变更。
Issue: wx/HL#4356
PR: wx/HL#4359
255 行
9.7 KiB
Markdown
255 行
9.7 KiB
Markdown
# 退款详情 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）
|