退款待办列表出参新增团号/档位/人员数三字段（#4344，Closes #4343）
这个提交包含在：
yaosutu
父节点
43d55d0a4d
当前提交
a9e26fa47b
@ -0,0 +1,188 @@
|
||||
# 退款待办列表新增团号/档位/人员数字段
|
||||
|
||||
- **接口**：`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）
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户