1398281322-a11y/java-backend-guardrails / skills/java-backend-guardrails/pay-refund-channel
pay-refund-channel
VerifiedUse when calling WeChat/Alipay 退款 API, refund notify, 部分退, stable refundNo, refund timeout query. Business aftersale flow is backend-refund-aftersale; do not mix the two files.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.4 KB |
SKILL.md
View on GitHub---
name: pay-refund-channel
description: Use when calling WeChat/Alipay 退款 API, refund notify, 部分退, stable refundNo, refund timeout query. Business aftersale flow is backend-refund-aftersale; do not mix the two files.
---
# 渠道退款
## When to Invoke
向微信/支付宝发起退款、退款异步通知、部分退、退款超时。面试:「退款怎么保证只退一次」。
## When NOT
售后审核、退货物流 → `refund-aftersale`。那是业务单;本文件是 **渠道资金退回**。对账 → `reconciliation`。
## 风险(面试考点)
退款 API 超时 ≠ 没退。再换 `refund_no` 会退两次。必须 **同一退款单号重试 + 查退款**。
退款也有异步通知,同样验签、幂等、金额校验。
部分退:累计退款不能超过原支付成功金额。多次部分退每笔一个 refund_no。
原路退回到支付渠道,不要默认退到余额除非产品就是钱包。
回调里同步调退款会把支付线程拖死,且可能和关单逻辑缠死。退款走独立任务。
## 方案选型(轻量优先)
```text
t_pay_refund
refund_no uk 我们生成,终身不变
out_trade_no
amount_fen
status CREATED → REFUNDING → SUCCESS | FAIL
```
```java
public void refund(PayRefund r) {
if (r.getStatus() == SUCCESS) return;
ChannelRefundResp resp = channel.refund(r.getRefundNo(), r.getOutTradeNo(), r.getAmountFen());
if (resp.acceptedOrSuccess()) {
markRefundingOrSuccess(r, resp);
} else if (resp.unknownOrTimeout()) {
// 保持 REFUNDING,补偿任务 queryRefund(refund_no)
} else {
markFail(r, resp.getMsg());
}
}
```
成功后才推进售后单 REFUNDED(消息通知 `refund-aftersale`)。渠道成功、售后单失败:对账补推进,不要再退一笔。
## 反例
错误:超时 newRefundNo 再调一次。
正确:同号重试 + queryRefund。
错误:退款通知不验签。
正确:与支付回调同等安全。
错误:部分退不记账已退金额,第三次把整单退超。
正确:`sum(success refund) + 本次 <= payAmount`。
## 验证
- 同一 refund_no 连调 5 次,渠道只受理一次,本地 SUCCESS 一次。
- 超时后补偿 query 能对上。
- 部分退累计不超过实付。
## 评审清单
- [ ] refund_no 稳定
- [ ] 超时查退款不是新单
- [ ] 有已退累计
- [ ] 与售后状态通过消息对齐,不在支付回调里同步退
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |