docs(changelog-v2): 退款待办统计接口出参改数组+分页新增statusGroup参数（#4303/#4308）

2026-06-23 17:06:40 +08:00 · 2026-06-23 17:06:40 +08:00 · 3e00271082
--- a/changelogs-v2/2026-06/23_4303_退款待办列表状态Tab后端驱动-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/23_4303_退款待办列表状态Tab后端驱动-修改接口-管理后台.md
@ -0,0 +1,309 @@
+# 退款待办列表状态 Tab 后端驱动（PR #4303/#4308）
+
+- **端类型**：管理后台
+- **变更类型**：修改接口
+- **日期**：2026-06-23
+- **关联 Issue**：[#4303](https://git.1814.love:8443/wx/HL/issues/4303)
+- **PR**：[#4308](https://git.1814.love:8443/wx/HL/pulls/4308)
+- **后端负责人**：yaosutu
+
+---
+
+## ① 接口背景
+
+退款待办工作台新增「分 Tab 展示」能力。统计接口出参由旧版扁平字段对象改为数组（每项含 code/name/count/amount），分页接口新增 `statusGroup` 入参，支持按 Tab 口径过滤。
+
+前端改造要点：
+- 统计接口出参结构已**破坏性变更**（旧字段全部废弃），前端读法必须修改。
+- 分页接口新增可选参数 `statusGroup`，点 Tab 时传对应值即可，与既有 `status` 多选参数可并存（AND 关系）。
+
+---
+
+## ② 变更清单
+
+| # | 接口 | 变更类型 | 影响 |
+|---|------|----------|------|
+| 1 | `GET /v3/admin/refund/application/stats` | ⚠️ 破坏性修改——出参由扁平对象改为数组 | 前端必须修改 |
+| 2 | `GET /v3/admin/refund/application/page` | ✨ 新增可选入参 `statusGroup` | 前端按需传参 |
+
+---
+
+## ③ 接口详情
+
+### 接口 1：退款待办统计
+
+| 字段 | 值 |
+|---|---|
+| 方法 | GET |
+| 路径 | `/v3/admin/refund/application/stats` |
+| 描述 | 退款待办各状态分组统计（数量 + 金额），用于列表 Tab 角标与顶部卡片 |
+| 认证 | 需要 JWT（管理后台 Bearer Token） |
+| 幂等性 | 只读，天然幂等 |
+| 限流 | 无特殊限流 |
+
+### 接口 2：退款申请分页
+
+| 字段 | 值 |
+|---|---|
+| 方法 | GET |
+| 路径 | `/v3/admin/refund/application/page` |
+| 描述 | 退款申请分页列表，新增 `statusGroup` 参数支持 Tab 口径过滤 |
+| 认证 | 需要 JWT（管理后台 Bearer Token） |
+| 幂等性 | 只读，天然幂等 |
+| 限流 | 无特殊限流 |
+
+---
+
+## ④ 接口入参
+
+### 接口 1：`GET /v3/admin/refund/application/stats`
+
+无入参（Query 参数为空）。
+
+---
+
+### 接口 2：`GET /v3/admin/refund/application/page`
+#### 4.1 Query 参数（全量，新增字段用 ✨ 标注）
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `pageNo` | Integer | 是 | 页码，从 1 开始 |
+| `pageSize` | Integer | 是 | 每页条数 |
+| `statusGroup` | String | 否 | ✨ Tab 分组过滤，取值见枚举表。不传则不约束（等同全部）。与 `status` 多选参数 AND 叠加 |
+| `status` | String[] | 否 | 精确状态多选，取值见 `RefundApplicationStatus` 枚举 |
+| `keyword` | String | 否 | 关键词搜索（订单号/申请单号/客人姓名） |
+| `createTimeStart` | String | 否 | 申请时间起，格式 `yyyy-MM-dd HH:mm:ss` |
+| `createTimeEnd` | String | 否 | 申请时间止，格式 `yyyy-MM-dd HH:mm:ss` |
+
+---
+
+## ⑤ 出参字段
+
+### 接口 1：`GET /v3/admin/refund/application/stats`
+
+**返回类型**：`Result<List<RefundStatItemVO>>`
+
+数组元素 `RefundStatItemVO`：
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| `code` | String | 分组唯一标识，见枚举表 |
+| `name` | String | 分组中文名，可直接展示为 Tab 文案 |
+| `count` | long | 该分组申请单数量 |
+| `amount` | String | 该分组退款金额合计（元，2 位小数，如 `"1234.50"`） |
+
+数组顺序固定，共 6 项：
+
+| 顺序 | code | name |
+|------|------|------|
+| 1 | ALL | 全部 |
+| 2 | PENDING | 待审批 |
+| 3 | REFUNDING | 退款中 |
+| 4 | FAILED | 失败待处理 |
+| 5 | COMPLETED | 已完成 |
+| 6 | CURRENT_MONTH_REFUNDED | 本月已退款 |
+
+**前端使用建议**：列表 Tab 角标取前 5 项（ALL/PENDING/REFUNDING/FAILED/COMPLETED），顶部金额卡片另取第 6 项（CURRENT_MONTH_REFUNDED）。
+
+---
+
+### 接口 2：`GET /v3/admin/refund/application/page`
+
+返回类型与原来相同（`Result<PageResult<RefundApplicationRespVO>>`），本次无出参字段变化，不赘述。
+
+---
+
+## ⑥ 枚举 / 数据字典
+
+### `statusGroup` 枚举（新增，接口 1 和接口 2 共用同一套口径）
+
+| code | 中文名 | 后端过滤口径 |
+|------|--------|-------------|
+| `ALL` | 全部 | status ∈ (PENDING, APPROVED, REFUNDING, REFUNDED)，**排除** REJECTED（已驳回）和 CANCELLED（已取消） |
+| `PENDING` | 待审批 | status = PENDING |
+| `REFUNDING` | 退款中 | status ∈ (APPROVED, REFUNDING)，**且**最新退款记录不为失败 |
+| `FAILED` | 失败待处理 | 最新退款记录 = 失败（优先级最高，从退款中挪出；重发成功后不再算失败） |
+| `COMPLETED` | 已完成 | status = REFUNDED |
+| `CURRENT_MONTH_REFUNDED` | 本月已退款 | status = REFUNDED，且退款完成时间在本自然月内 |
+
+**说明**：
+- 五组互斥（ALL/PENDING/REFUNDING/FAILED/COMPLETED），ALL = 其余四组之和。
+- FAILED 优先级最高：一笔申请只要最新退款记录是失败，无论 status 是 REFUNDING 还是 APPROVED，都归入 FAILED 而不在 REFUNDING 中计数。
+- ALL 列表**包含** FAILED 的申请（status=REFUNDING 但最新记录失败），前端如需对失败单标红，自行判断最新退款记录状态。
+- REJECTED（已驳回）和 CANCELLED（已取消）**不进**任何 Tab，属于终态归档，不在待办范围内。
+---
+
+## ⑦ 错误码
+
+| 错误码 | 含义 | 触发条件 |
+|--------|------|----------|
+| `400` | 参数校验失败 | `statusGroup` 传了非法枚举值 |
+| `401` | 未登录 | JWT 缺失或过期 |
+| `403` | 无权限 | 非管理后台角色 |
+
+---
+
+## ⑧ 示例
+
+### 8.1 典型成功：获取统计数组
+
+**请求**
+```
+GET /v3/admin/refund/application/stats
+Authorization: Bearer <token>
+```
+
+**响应**
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": [
+    { "code": "ALL",                    "name": "全部",       "count": 38, "amount": "52340.00" },
+    { "code": "PENDING",                "name": "待审批",     "count": 5,  "amount": "8800.00"  },
+    { "code": "REFUNDING",              "name": "退款中",     "count": 12, "amount": "17200.00" },
+    { "code": "FAILED",                 "name": "失败待处理", "count": 3,  "amount": "4100.00"  },
+    { "code": "COMPLETED",              "name": "已完成",     "count": 18, "amount": "22240.00" },
+    { "code": "CURRENT_MONTH_REFUNDED", "name": "本月已退款", "count": 11, "amount": "13500.00" }
+  ]
+}
+```
+
+---
+
+### 8.2 边界情况：某 Tab 无数据
+
+当 FAILED 分组无数据时，count=0、amount="0.00"，数组项仍然返回（不缺项）：
+
+```json
+{ "code": "FAILED", "name": "失败待处理", "count": 0, "amount": "0.00" }
+```
+
+---
+
+### 8.3 业务失败：statusGroup 传了非法值
+
+**请求**
+```
+GET /v3/admin/refund/application/page?statusGroup=UNKNOWN&pageNo=1&pageSize=10
+Authorization: Bearer <token>
+```
+
+**响应**
+```json
+{
+  "code": 400,
+  "msg": "参数错误：statusGroup 枚举值不合法",
+  "data": null
+}
+```
+---
+
+## ⑨ 业务边界
+
+**适用场景**：
+- 管理后台退款待办工作台 Tab 切换与角标显示。
+- 顶部「本月已退款」金额卡片。
+
+**不适用场景**：
+- 小程序端（无此工作台）。
+- `REJECTED` / `CANCELLED` 状态的申请不在任何 Tab 中，若需展示历史归档申请请单独传 `status=REJECTED` 或 `status=CANCELLED` 参数。
+
+**特殊边界**：
+- `FAILED` 判定依赖最新退款记录状态，与申请单自身的 `status` 字段不完全对应。点击「失败待处理」Tab 时后端已按此口径过滤，前端无需再做二次判断来决定哪些展示在该 Tab。
+- `ALL` Tab 中包含 `FAILED` 的申请，前端展示全部时如需区分失败/正常退款中，可读申请单内的退款记录列表字段。
+
+---
+
+## ⑩ 修改前后对比
+
+### 接口 1：统计接口出参结构对比
+
+**旧出参（已废弃，前端需移除）**：
+```json
+{
+  "code": 200,
+  "data": {
+    "pendingCount": 5,
+    "pendingAmount": "8800.00",
+    "refundingCount": 12,
+    "refundingAmount": "17200.00",
+    "failedCount": 3,
+    "failedAmount": "4100.00",
+    "completedCount": 18,
+    "completedAmount": "22240.00",
+    "currentMonthRefundedAmount": "13500.00",
+    "currentMonthRefundedCount": 11
+  }
+}
+```
+
+**新出参（当前版本）**：
+```json
+{
+  "code": 200,
+  "data": [
+    { "code": "ALL",                    "name": "全部",       "count": 38, "amount": "52340.00" },
+    { "code": "PENDING",                "name": "待审批",     "count": 5,  "amount": "8800.00"  },
+    { "code": "REFUNDING",              "name": "退款中",     "count": 12, "amount": "17200.00" },
+    { "code": "FAILED",                 "name": "失败待处理", "count": 3,  "amount": "4100.00"  },
+    { "code": "COMPLETED",              "name": "已完成",     "count": 18, "amount": "22240.00" },
+    { "code": "CURRENT_MONTH_REFUNDED", "name": "本月已退款", "count": 11, "amount": "13500.00" }
+  ]
+}
+```
+
+字段级对比：
+
+| 旧字段 | 新位置 | 说明 |
+|--------|--------|------|
+| `pendingCount` | `data[code=PENDING].count` | 已移至数组元素 |
+| `pendingAmount` | `data[code=PENDING].amount` | 已移至数组元素 |
+| `refundingCount` | `data[code=REFUNDING].count` | 已移至数组元素 |
+| `refundingAmount` | `data[code=REFUNDING].amount` | 已移至数组元素 |
+| `failedCount` | `data[code=FAILED].count` | 已移至数组元素 |
+| `failedAmount` | `data[code=FAILED].amount` | 已移至数组元素 |
+| `completedCount` | `data[code=COMPLETED].count` | 已移至数组元素 |
+| `completedAmount` | `data[code=COMPLETED].amount` | 已移至数组元素 |
+| `currentMonthRefundedAmount` | `data[code=CURRENT_MONTH_REFUNDED].amount` | 已移至数组元素 |
+| `currentMonthRefundedCount` | `data[code=CURRENT_MONTH_REFUNDED].count` | 已移至数组元素 |
+| —（新增） | `data[code=ALL].count/amount` | 新增「全部」汇总项（旧版无此项） |
+
+### 接口 2：分页接口入参对比
+
+| 字段 | 变化 | 说明 |
+|------|------|------|
+| `statusGroup` | 新增（可选） | 新增 Tab 口径过滤参数，不传等同旧行为 |
+| 其余参数 | 不变 | 保持向后兼容 |
+---
+
+## ⑪ 影响评估 / 回滚
+
+**破坏兼容**：
+- 接口 1 出参结构**已破坏兼容**。旧代码读 `data.pendingCount` 等扁平字段将返回 `undefined`，Tab 角标全部显示为空。**前端必须同步改造**。
+
+**前端同步上线**：
+- 接口 1 读取逻辑需改为遍历数组，按 `code` 取值。
+- 接口 2 点击 Tab 时加 `statusGroup` 参数，旧版不传时行为不变，**可兼容部署**（接口 2 无破坏）。
+
+**回滚方案**：
+- 若需回滚接口 1，后端可恢复旧版扁平结构；前端需配合回滚。
+- 接口 2 的 `statusGroup` 参数为可选，后端回滚直接忽略此参数，前端不受影响。
+
+---
+
+## ⑫ 注意事项
+
+1. **金额字段均为 String**（元，2 位小数），如 `"1234.50"`。禁止用 `Number()` / `parseFloat()` 解析后再做展示（防 JS 精度丢失）。直接展示即可。
+2. **count 字段为 long（整数）**，无需特殊处理。
+3. 数组顺序由后端固定，前端按顺序渲染 Tab 即可，无需按 code 排序。
+4. `FAILED` 口径：最新退款记录失败即归入，与申请单 `status` 不完全对等，不要用 status === "REFUNDING" 来判断是否是「退款中」Tab（因为 FAILED 单的 status 也可能是 REFUNDING）。
+5. 分页接口新增的 `statusGroup` 与既有 `status` 多选是 AND 关系，避免同时传两者造成无结果（如 `statusGroup=PENDING&status=REFUNDING` 必然为空）。
+
+---
+
+## ⑬ 关联 / 联系人
+
+- **Issue**：[https://git.1814.love:8443/wx/HL/issues/4303](https://git.1814.love:8443/wx/HL/issues/4303)
+- **PR**：[https://git.1814.love:8443/wx/HL/pulls/4308](https://git.1814.love:8443/wx/HL/pulls/4308)
+- **后端负责人**：yaosutu