// NotifyController
// 微信：成功返回 200 + 空 body，失败返回 500 → 微信会一直重投
// 支付宝：成功返回 "success"，失败返回 500 → 支付宝最多重试 25 小时

// chain-cloud-ms-trade-service handler/HandlerFactory.java
public class HandlerFactory {

    public static <T> T get(PayChannelEnum payChannel, Class<T> handler) {
        Map<String, T> beans = SpringUtil.getBeansOfType(handler);
        for (Map.Entry<String, T> entry : beans.entrySet()) {
            PayChannel payChannelAnnotation =
                    entry.getValue().getClass().getAnnotation(PayChannel.class);
            if (ObjectUtil.isNotEmpty(payChannelAnnotation)
                    && ObjectUtil.equal(payChannel, payChannelAnnotation.type())) {
                return entry.getValue();
            }
        }
        return null;      // ⚠️ 找不到渠道返回 null
    }
}

@PayChannel(PayChannelEnum.WECHAT_PAY)
public class WeChatJsapiPayHandler implements JsapiPayHandler { ... }

@PayChannel(PayChannelEnum.ALI_PAY)
public class AliJsapiPayHandler implements JsapiPayHandler { ... }

// chain-cloud-ms-trade-service JsapiPayServiceImpl#createJsapiTrading
@Override
public TradingEntity createJsapiTrading(TradingEntity tradingEntity) {
    // 1. 交易前置处理：检测交易单参数
    Boolean flag = beforePayHandler.checkCreateTrading(tradingEntity);
    if (!flag) throw new CCException(TradingEnum.NATIVE_PAY_FAIL);

    tradingEntity.setEnableFlag(Constants.YES);
    tradingEntity.setTradingType(TradingConstant.TRADING_TYPE_FK);

    // 2. 对交易订单加锁（同一 productOrderNo 串行）
    Long productOrderNo = tradingEntity.getProductOrderNo();
    String key = TradingCacheConstant.CREATE_PAY + productOrderNo;
    RLock lock = redissonClient.getFairLock(key);
    try {
        if (lock.tryLock(TradingCacheConstant.REDIS_WAIT_TIME, TimeUnit.SECONDS)) {
            // 3. 幂等性处理
            this.beforePayHandler.idempotentCreateTrading(tradingEntity);

            // 4. 调用不同渠道
            JsapiPayHandler jsapiPayHandler = HandlerFactory.get(
                    tradingEntity.getTradingChannel(), JsapiPayHandler.class);
            jsapiPayHandler.createJsapiTrading(tradingEntity);

            flag = this.tradingService.saveOrUpdate(tradingEntity);
            if (!flag) throw new CCException(TradingEnum.SAVE_OR_UPDATE_FAIL);
            return tradingEntity;
        }
        throw new CCException(TradingEnum.NATIVE_PAY_FAIL);
    } catch (CCException e) {
        throw e;
    } catch (Exception e) {
        log.error("Jsapi预创建异常: tradingDTO = {}", tradingEntity, e);
        throw new CCException(TradingEnum.NATIVE_PAY_FAIL);
    } finally {
        lock.unlock();      // ⚠️ 见亮点 7 坑 2
    }
}

// NotifyServiceImpl#updateTrading
private void updateTrading(Long tradingOrderNo, String resultMsg, String resultJson) {
    String key = TradingCacheConstant.CREATE_PAY + tradingOrderNo;
    RLock lock = redissonClient.getFairLock(key);
    try {
        if (lock.tryLock(TradingCacheConstant.REDIS_WAIT_TIME, TimeUnit.SECONDS)) {
            TradingEntity trading = this.tradingService.findTradByTradingOrderNo(tradingOrderNo);

            if (trading.getTradingState() == TradingStateEnum.YJS) {
                // 已付款 —— ★ 幂等短路：不重复发消息
                return;
            }

            trading.setTradingState(TradingStateEnum.YJS);
            trading.setQrCode("");                  // 清空二维码，避免被重复扫
            trading.setResultMsg(resultMsg);
            trading.setResultJson(resultJson);
            this.tradingService.saveOrUpdate(trading);

            // 发消息通知 OMS 更新订单支付状态
            TradeStatusMsg tradeStatusMsg = TradeStatusMsg.builder()
                    .tradingOrderNo(trading.getTradingOrderNo())
                    .productOrderNo(trading.getProductOrderNo())
                    .statusCode(TradingStateEnum.YJS.getCode())
                    .statusName(TradingStateEnum.YJS.name())
                    .build();
            String msg = JSONUtil.toJsonStr(Collections.singletonList(tradeStatusMsg));
            this.mqFeign.sendMsg(Constants.MQ.Exchanges.TRADE,
                    Constants.MQ.RoutingKeys.TRADE_UPDATE_STATUS, msg);
            return;
        }
    } catch (Exception e) {
        throw new CCException("处理业务失败");
    } finally {
        lock.unlock();      // ⚠️
    }
    throw new CCException("处理业务失败");
}

// handler/impl/BeforePayHandlerImpl#idempotentRefundTrading
public RefundRecordEntity idempotentRefundTrading(TradingEntity trading, BigDecimal refundAmount) {
    // 查询退款次数，不能大于 20 次
    List<RefundRecordEntity> recordList =
            this.refundRecordService.findListByTradingOrderNo(trading.getTradingOrderNo());
    int size = CollUtil.size(recordList);
    if (size >= 20) {
        return null;      // ← 返回 null 表示"超限"
    }

    RefundRecordEntity refundRecord = new RefundRecordEntity();
    refundRecord.setRefundNo(Convert.toLong(this.identifierGenerator.nextId(refundRecord)));
    refundRecord.setTradingOrderNo(trading.getTradingOrderNo());
    ...
    refundRecord.setRefundStatus(RefundStatusEnum.SENDING);     // 退款中
    refundRecord.setTotal(trading.getTradingAmount());
    refundRecord.setMemo(StrUtil.format("退款（{}）", size + 1));   // 备注：第几次
    return refundRecord;
}

// BasicPayServiceImpl#refundTrading
if (null == refundRecord) {
    return false;      // ← 退款次数超限
}
...
// BasicPayController
if (!result) {
    throw new CCException(TradingEnum.BASIC_REFUND_COUNT_OUT_FAIL);   // "退款次数超出限制，最多20次"
}

@Transactional
public Boolean refundTrading(String tradingOrderNo, BigDecimal refundAmount) {
    TradingEntity trading = this.tradingService.findTradByTradingOrderNo(tradingOrderNo);
    trading.setRefund(NumberUtil.add(refundAmount, trading.getRefund()));   // 累加已退金额
    this.beforePayHandler.checkRefundTrading(trading);     // 前置校验

    String key = TradingCacheConstant.REFUND_PAY + tradingOrderNo;
    RLock lock = redissonClient.getFairLock(key);
    if (lock.tryLock(TradingCacheConstant.REDIS_WAIT_TIME, TimeUnit.SECONDS)) {
        RefundRecordEntity refundRecord = this.beforePayHandler.idempotentRefundTrading(trading, refundAmount);
        if (null == refundRecord) return false;

        BasicPayHandler handler = HandlerFactory.get(refundRecord.getTradingChannel(), BasicPayHandler.class);
        Boolean result = handler.refundTrading(refundRecord);
        if (result) {
            this.refundRecordService.saveOrUpdate(refundRecord);
            trading.setIsRefund(Constants.YES);
            this.tradingService.saveOrUpdate(trading);
        }
        return true;
    }
    ...
}

// BeforePayHandlerImpl#checkRefundTrading
// 1. 必须已结算
if (tradingState != TradingStateEnum.YJS)  →  拒绝
// 2. 累计退款金额不能超过支付金额
if (refund > tradingAmount)  →  拒绝

// WeChatBasicPayHandler#refundTrading
POST /v3/refund/domestic/refunds
{
  "out_trade_no": 交易单号,
  "out_refund_no": refundNo,      // ★ 用退款单号做幂等键
  "refund": 退款金额 × 100,
  "total": 支付金额 × 100,
  "currency": "CNY"
}

// AliBasicPayHandler#refundTrading
Factory.Payment.Common()
    .optional("out_request_no", refundNo)
    .refund(tradingOrderNo, refundAmount);

// WeChatBasicPayHandler#queryTrading
String apiPath = StrUtil.format("/v3/pay/transactions/out-trade-no/{}", trading.getTradingOrderNo());
...
String tradeStatus = jsonObject.getStr("trade_state");

if (StrUtil.equalsAny(tradeStatus, TradingConstant.WECHAT_TRADE_CLOSED,
                                 TradingConstant.WECHAT_TRADE_REVOKED)) {
    trading.setTradingState(TradingStateEnum.QXDD);
} else if (StrUtil.equalsAny(tradeStatus, TradingConstant.WECHAT_REFUND_SUCCESS,
                                       TradingConstant.WECHAT_TRADE_REFUND)) {
    trading.setTradingState(TradingStateEnum.YJS);
} else if (StrUtil.equalsAny(tradeStatus, TradingConstant.WECHAT_TRADE_NOTPAY)) {
    // 未支付：判断时间，超过 2 小时未支付需要关闭订单
    long between = LocalDateTimeUtil.between(
            trading.getCreated(), LocalDateTimeUtil.now(), ChronoUnit.HOURS);
    if (between >= 2) {
        return this.closeTrading(trading);
    }
} else {
    return false;      // 非最终状态不处理
}

// chain-cloud-ms-trade-service job/TradeJob.java
@XxlJob("tradingJob")
public void tradingJob() {
    int shardIndex = NumberUtil.max(XxlJobHelper.getShardIndex(), 0);
    int shardTotal = NumberUtil.max(XxlJobHelper.getShardTotal(), 1);
    ...
    // 分片过滤：每个执行器只处理属于自己分片的数据
    if (trading.getTradingOrderNo() % shardTotal != shardIndex) {
        continue;
    }
}

// 把所有状态有变化的交易单组装成一个数组，一次性发
mqFeign.sendMsg(Exchanges.TRADE, RoutingKeys.TRADE_UPDATE_STATUS, msg);
// msg 是 List<TradeStatusMsg> 的 JSON

// oms MQListener
List<TradeStatusMsg> tradeStatusMsgList = JSONUtil.toBean(msg, new TypeReference<List<TradeStatusMsg>>() {}, false);
var msgList = tradeStatusMsgList.stream()
        .filter(v -> v.getStatusCode().equals(TradingStateEnum.YJS.getCode()))
        .collect(Collectors.toList());

// 第 1 层（已有）：锁 + 状态短路
if (trading.getTradingState() == TradingStateEnum.YJS) return;

// 第 2 层（建议加）：数据库条件更新做兜底
// UPDATE cc_trading SET trading_state = 'YJS' WHERE trading_order_no = ?
//   AND trading_state <> 'YJS'
// 影响行数为 0 → 说明已经被别人处理过了 → 直接返回
int rows = tradingMapper.markAsPaid(tradingOrderNo, ...);
if (rows == 0) {
    log.info("交易单 {} 已经是已结算状态，忽略重复回调", tradingOrderNo);
    return;
}

// 第 3 层（可选）：状态转换表（最彻底）
// 建一张 cc_trading_state_log(trading_order_no, from_status, to_status, created)
// 插入时用 (trading_order_no, from_status) 做唯一索引
// 这样任何一次状态变更都有唯一记录，重复变更直接被数据库挡住

// 不抽象的写法
public TradingEntity createJsapiTrading(TradingEntity e) {
    if (WECHAT.equals(e.getChannel())) {
        // 微信的逻辑
    } else if (ALI.equals(e.getChannel())) {
        // 支付宝的逻辑
    }
}

// 改进 1：HandlerFactory 返回 null 是个坑
// 调用方 HandlerFactory.get(channel, JsapiPayHandler.class).createJsapiTrading(...) 会 NPE
// 应该：
public static <T> T get(PayChannelEnum payChannel, Class<T> handler) {
    T result = null;
    for (T bean : SpringUtil.getBeansOfType(handler)) {
        PayChannel anno = AnnotationUtil.getAnnotation(bean.getClass(), PayChannel.class);
        if (anno != null && ObjectUtil.equal(payChannel, anno.type())) { result = bean; break; }
    }
    if (result == null) {
        throw new CCException(TradingEnum.PAY_CHANNEL_NOT_SUPPORT, payChannel);  // 明确的业务异常
    }
    return result;
}

// 改进 2：抽象层次再抽一层，把"渠道差异"和"业务流程"分离
// 签名/加解密这种纯技术差异，抽到 SDK 层或适配器层
// Handler 只表达业务流程
public interface JsapiPayHandler {
    /** 创建预支付交易，返回前端调起支付所需的参数 */
    JsapiPayParam createJsapiTrading(TradingEntity trading);
    /** 验签并解密回调，返回统一的支付结果 */
    NotifyResult verifyAndParseNotify(HttpServletRequest request);
}

DFK(1, 待付款) FKZ(2, 付款中) FKSB(3, 付款失败)
YJS(4, 已结算) QXDD(5, 取消订单) MD(6, 免单) GZ(7, 挂账)

// 1. 在枚举里定义合法流转
public enum TradingStateEnum {
    DFK(1, "待付款",   EnumSet.of(FKZ, QXDD, MD)),
    FKZ(2, "付款中",   EnumSet.of(YJS, FKSB, QXDD)),
    FKSB(3, "付款失败", EnumSet.of(FKZ, QXDD)),
    YJS(4, "已结算",   EnumSet.of()),        // 终态
    QXDD(5, "取消订单", EnumSet.of()),        // 终态
    MD(6, "免单",     EnumSet.of()),
    GZ(7, "挂账",     EnumSet.of(FKZ, YJS));

    private final Set<TradingStateEnum> allowedNext;
    public boolean canTransferTo(TradingStateEnum target) {
        return allowedNext.contains(target);
    }
}

// 2. 统一的状态变更入口，内部校验
public boolean changeStatus(Long id, TradingStateEnum target) {
    TradingEntity e = this.getById(id);
    if (!e.getTradingState().canTransferTo(target)) {
        throw new CCException(TradingEnum.ILLEGAL_STATUS_TRANSFER,
                e.getTradingState(), target);
    }
    // 条件更新：WHERE status = 当前状态，防止并发
    LambdaUpdateWrapper<TradingEntity> w = Wrappers.lambdaUpdate();
    w.eq(TradingEntity::getId, id)
     .eq(TradingEntity::getTradingState, e.getTradingState().getCode())
     .set(TradingEntity::getTradingState, target.getCode());
    return super.update(w);
}

// chain-cloud-ms-trade-service constant/TradingConstant.java
//【微信退款返回状态】
//SUCCESS：退款成功
public static final String WECHAT_REFUND_SUCCESS = "SUCCESS";
//CLOSED：退款关闭
public static final String WECHAT_REFUND_CLOSED = "CLOSED";
//PROCESSING：退款处理中
public static final String WECHAT_REFUND_PROCESSING = "PROCESSING";
//ABNORMAL：退款异常
public static final String WECHAT_REFUND_ABNORMAL = "TRADE_CLOSED";    // ★★ 错 ★★

// WeChatBasicPayHandler.java:90
throw new CCException(response.getBody(), NATIVE_REFUND_FAIL.getCode(),
                      NATIVE_REFUND_FAIL.getCode());
//                              ↑ 第三个参数应该是 getStatus()，这里传了 getCode()

public static <T> T get(PayChannelEnum payChannel, Class<T> handler) {
    ...
    return null;      // 找不到渠道返回 null
}

JsapiPayHandler jsapiPayHandler = HandlerFactory.get(channel, JsapiPayHandler.class);
jsapiPayHandler.createJsapiTrading(tradingEntity);       // ← null 会 NPE

BasicPayHandler handler = HandlerFactory.get(channel, BasicPayHandler.class);
Boolean result = handler.refundTrading(refundRecord);   // ← NPE

public static final String TRADING_CHANNEL_CASH_PAY = "CASH_PAY";
public static final String TRADING_CHANNEL_CREDIT_PAY = "CREDIT_PAY";

// PayChannelServiceImpl#findByEnterpriseId
@Override
public PayChannelEntity findByEnterpriseId(Long enterpriseId, String channelLabel) {
    LambdaQueryWrapper<PayChannelEntity> queryWrapper = new LambdaQueryWrapper<>();
    queryWrapper.eq(PayChannelEntity::getEnterpriseId, enterpriseId)
            .eq(PayChannelEntity::getChannelLabel, channelLabel)
            .eq(PayChannelEntity::getEnableFlag, Constants.YES);
    //TODO 缓存                                    ← 源码里就写着 TODO
    return super.getOne(queryWrapper);
}

public static final String PAY_CHANNEL_LIST = "trading:pay_channel_list&ttl=-1";

@Override
@Cacheable(value = "payChannel", key = "#enterpriseId + ':' + #channelLabel",
           unless = "#result == null")
public PayChannelEntity findByEnterpriseId(Long enterpriseId, String channelLabel) { ... }

// 渠道配置变更时主动失效
@CacheEvict(value = "payChannel", key = "#p.enterpriseId + ':' + #p.channelLabel")
public void saveOrUpdate(PayChannelDTO p) { ... }

// NotifyServiceImpl#wxPayNotify
try {
    client.createHttpClient();
    ...
    Notification notification = notificationHandler.parse(request);
    if (!StrUtil.equals("TRANSACTION.SUCCESS", notification.getEventType())) return;
    jsonData = JSONUtil.parseObj(notification.getDecryptData());
} catch (Exception e) {
    throw new CCException("验签失败");           // ← 所有异常都归为"验签失败"
}

// 1. 验签失败：区分"配置问题"和"请求问题"
} catch (Exception e) {
    log.error("微信回调处理异常", e);
    if (isConfigError(e)) {
        // 配置问题：告警 + 返回成功，避免无效重投
        return;
    }
    throw new CCException(TradingEnum.NOTIFY_VERIFY_FAILED);
}

// 2. 交易单不存在：明确拒绝，不再重投
TradingEntity trading = this.tradingService.findTradByTradingOrderNo(tradingOrderNo);
if (ObjectUtil.isEmpty(trading)) {
    log.error("回调对应的交易单不存在：{}", tradingOrderNo);
    throw new CCException(TradingEnum.TRADING_NOT_FOUND);   // 明确业务异常
}

// 3. 用条件更新做原子判断，而不是先查后改
// UPDATE ... SET trading_state='YJS' WHERE trading_order_no=? AND trading_state <> 'YJS'
// affected=0 → 已处理过 → 直接返回成功

// oms MQListener#listenTradeUpdatePayStatusMsg
@RabbitListener(bindings = @QueueBinding(
        value = @Queue(name = Constants.MQ.Queues.OMS_TRADE_UPDATE_STATUS),
        exchange = @Exchange(name = Constants.MQ.Exchanges.TRADE, type = ExchangeTypes.TOPIC),
        key = Constants.MQ.RoutingKeys.TRADE_UPDATE_STATUS))
public void listenTradeUpdatePayStatusMsg(String msg) {
    List<TradeStatusMsg> tradeStatusMsgList =
            JSONUtil.toBean(msg, new TypeReference<List<TradeStatusMsg>>() {}, false);
    // 只处理支付成功的
    var msgList = tradeStatusMsgList.stream()
            .filter(v -> v.getStatusCode().equals(TradingStateEnum.YJS.getCode()))
            .collect(Collectors.toList());
    if (CollUtil.isEmpty(msgList)) return;
    this.crudOrderService.updatePayStatus(msgList, OrderPaymentStatusEnum.PAID.getCode());
}

// 1. 业务唯一索引
// cc_trading_status_log(trading_order_no, status_code) 唯一
// 插入冲突 → DuplicateKeyException → 说明处理过 → 直接 ack

// 2. 或者条件更新
UPDATE cc_order SET payment_status = 'PAID'
WHERE id = ? AND payment_status = 'UNPAID'          // ← 关键
// affected = 0 → 已经付过了 → 忽略

-- 普通写法（不幂等）
UPDATE cc_trading SET trading_state = 'YJS' WHERE trading_order_no = ?;

-- 幂等写法
UPDATE cc_trading SET trading_state = 'YJS'
WHERE trading_order_no = ? AND trading_state <> 'YJS';

第一层：分布式锁（按 tradingOrderNo）
  → 保证同一笔交易的并发回调只有一个在处理

第二层：状态短路
  if (tradingState == 已结算) return;    ← ★ 这是关键
  → 保证重复投递（先后到达）被挡住

UPDATE cc_trading SET trading_state = 'YJS'
WHERE trading_order_no = ? AND trading_state <> 'YJS'

// 1. 次数上限
if (size >= 20) return null;            // idempotentRefundTrading

// 2. 金额上限
if (refund > tradingAmount) throw;      // checkRefundTrading

// 3. 每笔退款单有唯一 refundNo（雪花 ID）
//    作为微信的 out_refund_no 幂等键，保证不会重复退

场景 1：用户支付后直接关掉了页面
  → 回调还是会到的（微信服务器主动调），所以这种情况还好

场景 2：网络问题导致我们的回调接口收不到，或处理失败
  → 用户那边显示"支付成功"（微信 App 里有记录），但我们的库里还是"待付款"
  → ★ 这就是"钱付了但单没更新"，是最严重的对账差异

场景 3：我们主动发消息通知用户，但用户已经关了短信通道
  → 用户不知道要付钱