From 3e002710829195c29a8d457e8b8a93782de0b5f9 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 23 Jun 2026 17:06:40 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E9=80=80=E6=AC=BE?= =?UTF-8?q?=E5=BE=85=E5=8A=9E=E7=BB=9F=E8=AE=A1=E6=8E=A5=E5=8F=A3=E5=87=BA?= =?UTF-8?q?=E5=8F=82=E6=94=B9=E6=95=B0=E7=BB=84+=E5=88=86=E9=A1=B5?= =?UTF-8?q?=E6=96=B0=E5=A2=9EstatusGroup=E5=8F=82=E6=95=B0=EF=BC=88#4303/#?= =?UTF-8?q?4308=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...待办列表状态Tab后端驱动-修改接口-管理后台.md | 309 ++++++++++++++++++ 1 file changed, 309 insertions(+) create mode 100644 changelogs-v2/2026-06/23_4303_退款待办列表状态Tab后端驱动-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/23_4303_退款待办列表状态Tab后端驱动-修改接口-管理后台.md b/changelogs-v2/2026-06/23_4303_退款待办列表状态Tab后端驱动-修改接口-管理后台.md new file mode 100644 index 0000000..aaefc22 --- /dev/null +++ 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>` + +数组元素 `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>`），本次无出参字段变化，不赘述。 + +--- + +## ⑥ 枚举 / 数据字典 + +### `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 +``` + +**响应** +```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 +``` + +**响应** +```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