diff --git a/changelogs-v2/2026-06/24_4356_退款详情orderInfo补订单字段-修改接口-管理后台.md b/changelogs-v2/2026-06/24_4356_退款详情orderInfo补订单字段-修改接口-管理后台.md new file mode 100644 index 0000000..0b5c827 --- /dev/null +++ b/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 `） | +| **幂等** | 是（只读） | +| **限流** | 无特殊限流 | + +--- + +## ④ 接口入参 + +### 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 +``` + +**响应（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）