# 退款详情 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）