package com.jeesharp.business.modules.finance.payorder.service;

import com.jeesharp.business.modules.finance.payorder.entity.PayOrder;
import com.jeesharp.business.modules.finance.payorder.vo.PayOrderQueryVO;
import com.jeesharp.framework.mybatis.core.service.BaseInterface;

/**
 * 支付单领域服务接口，定义按商户单号查询与批量关闭未终态意图等扩展能力。
 *
 * @author jeesharp
 * @since 2026-05-08
 */
public interface PayOrderService extends BaseInterface<PayOrder, PayOrderQueryVO> {

    /**
     * 按微信商户订单号（out_trade_no）查询一条有效支付单。
     */
    PayOrder getByOutTradeNo(String outTradeNo);

    /**
     * 关闭同一业务单下仍处于「待预支付 / 已生成预支付」的支付单。
     */
    void closePendingByBiz(String bizOrderId, String bizScene);

    /**
     * 查询同一业务单下最近一条待预支付/已生成预支付的支付单。
     */
    PayOrder findLatestPendingForBiz(String bizOrderId, String bizScene);

    /**
     * 显式插入支付单（避免 preset 主键走 saveOrUpdate 误 UPDATE 或未 INSERT）。
     */
    void insertPayOrder(PayOrder entity);

    /**
     * 查询同一业务单下最近一条支付成功的支付单。
     */
    PayOrder findLatestSuccessByBiz(String bizOrderId, String bizScene);

    /**
     * 按合单商户订单号查询一条有效支付单。
     */
    PayOrder getByCombineOutTradeNo(String combineOutTradeNo);

    /**
     * 查询同一业务单下所有待预支付/已生成预支付的支付单（关单前调微信 API 用）。
     */
    java.util.List<PayOrder> findPendingListByBiz(String bizOrderId, String bizScene);
}
