当需要快速理解一个陌生项目、回答"这个仓库是干什么的"、或在…

# 支付模块架构分析：从退款请求到支付宝回调

一、模块分层（src/payment/）

```

enter.ts → 统一入口，路由分发（pay/refund/query）

core/refund.ts → 退款业务逻辑

gateway/alipay.ts → 支付宝渠道适配器

callback/handler.ts → 异步回调处理

dao/order.ts → 订单状态持久化

```

二、退款请求流转链路（以订单 R20240601001 为例）

1. 入口分发：enter.ts 收到 POST /payment/refund，解析 body 后按 channel: "alipay" 分发给 gateway/alipay.ts，同时写入 refund_records 表（status=pending）。

2. 渠道调用：alipay.ts 拼装 alipay.trade.refund 参数（out_request_no=R20240601001-1，refund_amount=89.00），RSA2 签名后调用 SDK，同步返回 fund_change=Y 表示受理成功，订单状态更新为 refunding。

3. 异步回调：支付宝稍后 POST 到 /payment/callback/alipay，携带 trade_status=REFUND_SUCCESS。callback/handler.ts 依次执行：

• 验签（alipay_public_key）→ 失败直接返回 fail
• 幂等校验（按 out_request_no 查重，已处理则返回 success）
• 更新订单状态为 refunded，写入回调流水表
• 发 MQ 消息 order.refunded 通知库存/积分模块解耦
• 响应 success 字符串（支付宝要求的 ACK 格式）

三、两个易踩的坑

1. 验签前置：handler.ts 中验签必须在业务处理前，避免伪造回调篡改状态。

2. 幂等靠 out_request_no：同一退款单重试必须复用同一退款请求号，否则支付宝会重复退款。

四、验证建议

本地用支付宝沙箱环境触发退款，观察日志关键节点：[enter] route=refund → [alipay] sync resp fund_change=Y → [callback] verifySign ok, order R20240601001 → refunded，三段日志齐全即链路打通。