hl-api-changelog/changelogs-v2/2026-06/24_4356_退款详情orderInfo补订单字段-修改接口-管理后台.md

退款详情 orderInfo 补订单字段（原恒为 null，本次接通并扩 3 字段）

• 接口：GET /v3/admin/refund/application/{id}
• 变更类型：修改接口（出参 orderInfo 块由恒为 null 修复为正常填充，并新增 3 字段；非破坏性，其余字段不变）
• 日期：2026-06-24
• 端类型：管理后台
• Issue：wx/HL#4356
• PR：wx/HL#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 节选）

{
  "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 节选）

{
  "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 节选）

{
  "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：wx/HL#4356
• PR：wx/HL#4359
• 退款列表同期关联 PR：wx/HL#4344（退款列表新增相同三字段，口径对齐）
• 后端负责人：腰苏图（yst）