From a9e26fa47beb5e3d4ddbbbd65d515b280104dbf0 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Wed, 24 Jun 2026 16:11:58 +0800 Subject: [PATCH] =?UTF-8?q?=E9=80=80=E6=AC=BE=E5=BE=85=E5=8A=9E=E5=88=97?= =?UTF-8?q?=E8=A1=A8=E5=87=BA=E5=8F=82=E6=96=B0=E5=A2=9E=E5=9B=A2=E5=8F=B7?= =?UTF-8?q?/=E6=A1=A3=E4=BD=8D/=E4=BA=BA=E5=91=98=E6=95=B0=E4=B8=89?= =?UTF-8?q?=E5=AD=97=E6=AE=B5=EF=BC=88#4344=EF=BC=8CCloses=20#4343?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...列表新增团号档位人员数-修改接口-管理后台.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 changelogs-v2/2026-06/24_4343_退款列表新增团号档位人员数-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/24_4343_退款列表新增团号档位人员数-修改接口-管理后台.md b/changelogs-v2/2026-06/24_4343_退款列表新增团号档位人员数-修改接口-管理后台.md new file mode 100644 index 0000000..c3b8351 --- /dev/null +++ b/changelogs-v2/2026-06/24_4343_退款列表新增团号档位人员数-修改接口-管理后台.md @@ -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 `） | +| **幂等** | 是（只读） | +| **限流** | 无特殊限流 | + +--- + +## ④ 接口入参 + +入参无任何变化，完整入参见原有接口契约（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 +``` + +**响应（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）