wx/hl-api-changelog

派生 0

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

2026-06-23 17:06:40 +08:00

12 KiB

原始文件 Blame 文件历史

退款待办列表状态 Tab 后端驱动（PR #4303/#4308）

端类型：管理后台
变更类型：修改接口
日期：2026-06-23
关联 Issue：#4303
PR：#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>

响应

{
  "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"，数组项仍然返回（不缺项）：

{ "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>

响应

{
  "code": 400,
  "msg": "参数错误：statusGroup 枚举值不合法",
  "data": null
}

⑨ 业务边界

适用场景：

管理后台退款待办工作台 Tab 切换与角标显示。
顶部「本月已退款」金额卡片。

不适用场景：

小程序端（无此工作台）。
REJECTED / CANCELLED 状态的申请不在任何 Tab 中，若需展示历史归档申请请单独传 status=REJECTED 或 status=CANCELLED 参数。

特殊边界：

FAILED 判定依赖最新退款记录状态，与申请单自身的 status 字段不完全对应。点击「失败待处理」Tab 时后端已按此口径过滤，前端无需再做二次判断来决定哪些展示在该 Tab。
ALL Tab 中包含 FAILED 的申请，前端展示全部时如需区分失败/正常退款中，可读申请单内的退款记录列表字段。

⑩ 修改前后对比

接口 1：统计接口出参结构对比

旧出参（已废弃，前端需移除）：

{
  "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
  }
}

新出参（当前版本）：

{
  "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 参数为可选，后端回滚直接忽略此参数，前端不受影响。

⑫ 注意事项

金额字段均为 String（元，2 位小数），如 "1234.50"。禁止用 Number() / parseFloat() 解析后再做展示（防 JS 精度丢失）。直接展示即可。
count 字段为 long（整数），无需特殊处理。
数组顺序由后端固定，前端按顺序渲染 Tab 即可，无需按 code 排序。
FAILED 口径：最新退款记录失败即归入，与申请单 status 不完全对等，不要用 status === "REFUNDING" 来判断是否是「退款中」Tab（因为 FAILED 单的 status 也可能是 REFUNDING）。
分页接口新增的 statusGroup 与既有 status 多选是 AND 关系，避免同时传两者造成无结果（如 statusGroup=PENDING&status=REFUNDING 必然为空）。

⑬ 关联 / 联系人

Issue：https://git.1814.love:8443/wx/HL/issues/4303
PR：https://git.1814.love:8443/wx/HL/pulls/4308
后端负责人：yaosutu

12 KiB 原始文件 Blame 文件历史 Unescape Escape

退款待办列表状态 Tab 后端驱动（PR #4303/#4308）

① 接口背景

② 变更清单

③ 接口详情

接口 1：退款待办统计

接口 2：退款申请分页

④ 接口入参

接口 1：GET /v3/admin/refund/application/stats

接口 2：GET /v3/admin/refund/application/page

4.1 Query 参数（全量，新增字段用 ✨ 标注）

⑤ 出参字段

接口 1：GET /v3/admin/refund/application/stats

接口 2：GET /v3/admin/refund/application/page

⑥ 枚举 / 数据字典

statusGroup 枚举（新增，接口 1 和接口 2 共用同一套口径）

⑦ 错误码

⑧ 示例

8.1 典型成功：获取统计数组

8.2 边界情况：某 Tab 无数据

8.3 业务失败：statusGroup 传了非法值

⑨ 业务边界

⑩ 修改前后对比

接口 1：统计接口出参结构对比

接口 2：分页接口入参对比

⑪ 影响评估 / 回滚

⑫ 注意事项

⑬ 关联 / 联系人

12 KiB

原始文件 Blame 文件历史

接口 1：`GET /v3/admin/refund/application/stats`

接口 2：`GET /v3/admin/refund/application/page`

接口 1：`GET /v3/admin/refund/application/stats`

接口 2：`GET /v3/admin/refund/application/page`

`statusGroup` 枚举（新增，接口 1 和接口 2 共用同一套口径）