# 退款待办列表新增团号/档位/人员数字段

- **接口**：`GET /v3/admin/refund/application/page`
- **变更类型**：修改接口（出参新增 3 字段，非破坏性，原字段全部保留）
- **日期**：2026-06-24
- **端类型**：管理后台
- **Issue**：https://git.1814.love:8443/wx/HL/issues/4343
- **PR**：https://git.1814.love:8443/wx/HL/pulls/4344
- **负责人**：腰苏图（yst）

---

## ① 接口背景

退款待办列表（`/v3/admin/refund/application/page`）原本已返回订单号、产品名、客户名、定制师名等订单基础信息。本次在 `records[]` 每条记录中补充团号、规格档位、人员数描述三个字段，便于定制师在退款工作台快速识别退款所属团期及人员规模，无需再跳转订单详情页核对。

---

## ② 变更清单

| 变更 | 类型 | 说明 |
|---|---|---|
| `records[].teamNo` 新增 | ✨ 出参新增字段 | 订单所属团号，无团号时为 null |
| `records[].tierName` 新增 | ✨ 出参新增字段 | 订单规格/套餐档位名称，无档位时为 null |
| `records[].peopleSummary` 新增 | ✨ 出参新增字段 | 人员数描述，后端已拼接好中文字符串（如 `2成人1儿童`），前端直接展示 |

**无破坏性变更**：入参不变，原有出参字段（orderNo / productName / customerName / consultantName 等）不变，枚举值不变，错误码不变。

---

## ③ 接口详情

| 项 | 说明 |
|---|---|
| **方法** | GET |
| **路径** | `/v3/admin/refund/application/page` |
| **功能** | 退款申请待办列表分页查询 |
| **认证** | 需要管理后台 JWT（`Authorization: Bearer <token>`） |
| **幂等** | 是（只读） |
| **限流** | 无特殊限流 |

---

## ④ 接口入参

入参无任何变化，完整入参见原有接口契约（statusGroup、pageNo、pageSize 等字段保持不变）。

---

## ⑤ 出参字段

### 新增字段（位于 `data.records[]` 每条记录内）

| 字段名 | 类型 | 可为 null | 说明 |
|---|---|---|---|
| `teamNo` | string | ✅ 是 | 订单所属团号；订单无团号（非团期订单）时返回 null |
| `tierName` | string | ✅ 是 | 订单规格/套餐档位名称；无档位时返回 null |
| `peopleSummary` | string | ✅ 是 | 人员数描述，格式如 `2成人1儿童`、`1成人2儿童1幼儿`；仅含非零人数段，顺序固定为成人→儿童→幼儿→婴儿；各人数全为 0 时返回 null |

### 已有字段（保持不变，供参考）

| 字段名 | 类型 | 说明 |
|---|---|---|
| `orderNo` | string | 订单号 |
| `productName` | string | 产品名称 |
| `customerName` | string | 客户姓名 |
| `consultantName` | string | 定制师姓名 |
| `applicationNo` | string | 退款申请单号 |
| `status` | string | 退款申请状态（枚举值不变） |
| ... | ... | 其余字段均保持不变 |

**说明**：`teamNo` / `tierName` / `peopleSummary` 三字段与 `orderNo` / `productName` 等字段同样通过订单服务批量查询填充。若订单已被删除或查询不到，这三个新字段连同 `orderNo` / `productName` / `customerName` / `consultantName` 均返回 null，退款申请自身字段正常返回，不影响列表展示。

---

## ⑥ 枚举 / 数据字典

无新增或变更枚举值。

---

## ⑦ 错误码

无新增或变更错误码。本次为纯出参扩展，不引入新的业务校验路径。

---

## ⑧ 示例

### 8.1 典型成功（团期订单，含完整三字段）

**请求**
```
GET /v3/admin/refund/application/page?pageNo=1&pageSize=20
Authorization: Bearer <token>
```

**响应（records[] 节选一条）**
```json
{
  "code": 200,
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "total": 5,
    "records": [
      {
        "applicationNo": "RF2026062400001",
        "orderNo": "ORD20260624000123",
        "productName": "云南深度7日游",
        "teamNo": "GB260710",
        "tierName": "标准大床房",
        "peopleSummary": "2成人1儿童",
        "customerName": "张三",
        "consultantName": "李定制",
        "status": "PENDING_REVIEW",
        "refundAmount": "1200.00"
      }
    ]
  },
  "msg": "success"
}
```

### 8.2 边界情况（非团期订单 / 人数全 0 / 无档位）

**响应（records[] 节选一条）**
```json
{
  "applicationNo": "RF2026062400002",
  "orderNo": "ORD20260624000456",
  "productName": "西藏定制5日",
  "teamNo": null,
  "tierName": null,
  "peopleSummary": null,
  "customerName": "王五",
  "consultantName": "赵定制",
  "status": "PENDING_REVIEW",
  "refundAmount": "3500.00"
}
```

> `teamNo`/`tierName`/`peopleSummary` 均为 null 属正常，前端渲染时做空值保护（不展示 / 展示占位符均可）。

### 8.3 业务失败（statusGroup 参数非法）

**请求**
```
GET /v3/admin/refund/application/page?statusGroup=INVALID_GROUP&pageNo=1&pageSize=20
```

**响应**
```json
{
  "code": 400,
  "data": null,
  "msg": "参数校验失败"
}
```

---

## ⑨ 业务边界

**适用**：
- 退款待办工作台所有 Tab（statusGroup 筛选不影响新字段的填充逻辑）
- 团期订单：`teamNo` 有值，`tierName` 视产品是否配置档位
- 非团期（CORE/ROUTE/CUSTOM）订单：`teamNo` 恒为 null

**不适用 / 特殊边界**：
- 订单已删除或异常查询不到时，三字段同其他订单摘要字段一并返回 null，退款申请数据不受影响
- `peopleSummary` 的人数统计口径为订单创建时记录的 adult/child/youngChild/baby 字段；若订单出行人后续有改动，summary 展示的是订单主表快照值，非实时出行人计数

---

## ⑫ 注意事项

1. **前端渲染空值保护**：三个新字段均可能为 null，渲染时务必做 null 判断，避免显示 `null` 字符串或崩溃。
2. **`peopleSummary` 直接展示**：后端已按「非零段顺序拼接 + 中文单位」格式组装完毕，前端不需要自己拼接，直接 `v-if="item.peopleSummary"` 渲染即可。
3. **非破坏性变更**：无需改动已有字段的读取逻辑，只需在列表 UI 中选择性展示三个新字段即可。

---

## ⑬ 关联 / 联系人

- **Issue**：https://git.1814.love:8443/wx/HL/issues/4343
- **PR**：https://git.1814.love:8443/wx/HL/pulls/4344
- **后端负责人**：腰苏图（yst）