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

import com.jeesharp.business.modules.finance.merchantreceivable.entity.MerchantReceivable;
import com.jeesharp.business.modules.finance.merchantreceivable.vo.MerchantReceivableQueryVO;
import com.jeesharp.business.modules.finance.merchantreceivable.vo.MerchantReceivableSettlementQueryVO;
import com.jeesharp.business.modules.finance.merchantreceivable.vo.MerchantReceivableSettlementSummaryVO;
import com.jeesharp.business.modules.finance.merchantreceivable.vo.PlatformCommissionPeriodSummaryVO;
import com.jeesharp.business.modules.finance.platformrevenue.vo.PlatformRevenueRollupAggregateVO;
import com.jeesharp.framework.mybatis.core.service.BaseInterface;

import java.util.List;

/**
 * 商户应收账流水领域服务接口。
 *
 * @author jeesharp
 * @since 2026-06-11
 */
public interface MerchantReceivableService extends BaseInterface<MerchantReceivable, MerchantReceivableQueryVO> {

    /**
     * 按子单与流水类型查询（幂等校验）。
     */
    MerchantReceivable findByMallOrderIdAndEntryType(String mallOrderId, String entryType);

    /**
     * 按退款单查询冲减流水（幂等校验）。
     */
    MerchantReceivable findByPayRefundOrderId(String payRefundOrderId);

    /**
     * 按商户与账期汇总。
     */
    List<MerchantReceivableSettlementSummaryVO> summarizeByMerchant(MerchantReceivableSettlementQueryVO query);

    /**
     * 按日或按月汇总平台佣金。
     */
    List<PlatformCommissionPeriodSummaryVO> summarizePlatformCommissionByPeriod(
            MerchantReceivableSettlementQueryVO query);

    /**
     * 按商城子订单查询全部应收流水，按业务时间倒序。
     */
    List<MerchantReceivable> findListByMallOrderId(String mallOrderId);

    /**
     * 平台收入日汇总源数据聚合（全平台代收、无 dataScope）。
     */
    PlatformRevenueRollupAggregateVO summarizeForDailyRollup(java.time.LocalDateTime windowStart,
            java.time.LocalDateTime windowEnd);

    /**
     * 平台生成结算单：按商户与账期汇总，不应用 dataScope。
     */
    MerchantReceivableSettlementSummaryVO summarizeByMerchantForSettlement(String merchantTenantId,
            java.time.LocalDateTime periodStart, java.time.LocalDateTime periodEnd);

    /**
     * 取商户最近一条应收流水的 tenant_code。
     */
    String resolveTenantCodeByMerchantTenantId(String merchantTenantId);

    /**
     * 账期内尚未被结算单占用的应收流水（生成结算单用）。
     */
    List<MerchantReceivable> listUnsettledForSettlement(String merchantTenantId,
            java.time.LocalDateTime periodStart, java.time.LocalDateTime periodEnd);

    /**
     * 批量绑定结算单占用。
     */
    void batchBindSettlementBill(List<String> receivableIds, String settlementBillId, String settlementBillNo);

    /**
     * 作废结算单时释放占用。
     */
    void clearSettlementBillByBillId(String settlementBillId);
}
