package com.jeesharp.business.modules.finance.api;

import com.jeesharp.business.modules.finance.api.dto.MerchantReceivableBriefDTO;
import com.jeesharp.business.modules.finance.merchantreceivable.vo.MerchantReceivableSettlementSummaryVO;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 商户应收账跨模块 API，供商城在支付成功时触发平台代收内部记账。
 *
 * @author jeesharp
 * @since 2026-06-11
 */
public interface MerchantReceivableApi {

    /**
     * 支付成功后为平台代收子单记应收（幂等）。
     *
     * @param financePayOrderId 财务支付单主键
     * @param payBatchId        商城合并支付批次主键，单商户支付可为空
     * @param transactionId     微信 transaction_id
     */
    void recordForMallPay(String financePayOrderId, String payBatchId, String transactionId);

    /**
     * 退款成功后记商户应收冲减（幂等）。
     *
     * @param payRefundOrderId 支付退款单主键
     */
    void recordForRefund(String payRefundOrderId);

    /**
     * 按商城子订单查询平台代收应收流水（支付应收 + 退款冲减）。
     *
     * @param mallOrderId 商城子订单主键
     */
    List<MerchantReceivableBriefDTO> listByMallOrderId(String mallOrderId);

    /**
     * 按指定商户与账期汇总应收（供平台生成结算单；不走登录 dataScope，仅按商户主键过滤）。
     */
    MerchantReceivableSettlementSummaryVO summarizeForSettlementBill(String merchantTenantId,
            LocalDateTime periodStart, LocalDateTime periodEnd);

    /**
     * 解析子单商户租户编码（与应收流水 tenant_code 对齐，供结算单落库）。
     */
    String resolveTenantCodeByMerchantTenantId(String merchantTenantId);
}
