package com.jeesharp.business.modules.trade.service;

import com.jeesharp.business.modules.trade.dto.TradeOrderCreateDTO;
import com.jeesharp.business.modules.trade.entity.TradeOrder;
import com.jeesharp.business.modules.trade.vo.TradeOrderQueryVO;
import com.jeesharp.framework.mybatis.core.service.BaseInterface;

/**
 * 统一交易订单主单领域服务接口，承载待支付建单、支付落账、取消等规则与持久化。
 *
 * @author jeesharp
 * @since 2026-05-08
 */
public interface TradeOrderService extends BaseInterface<TradeOrder, TradeOrderQueryVO> {

    /**
     * 校验入参并创建待支付主单及可选明细行，返回落库后的主单（含明细场景下会再查主单）。
     */
    TradeOrder createPendingPayOrder(TradeOrderCreateDTO dto);

    /**
     * 支付成功：待支付 → 已支付，并记录支付单号与渠道。
     */
    void markPaid(String orderId, String payOrderId, String payChannel);

    /**
     * 待支付取消。
     */
    void cancelPending(String orderId);

    /**
     * 已支付/待支付预约单取消（统一单置为已取消，用于 reserve 等免在线支付场景）。
     */
    void markCancelled(String orderId);

    /**
     * 已支付订单关闭（核销完成等场景，小程序统一订单展示为已完成）。
     */
    void markClosed(String orderId);

    /**
     * 快递发货等：已支付 → 履约中（幂等）。
     */
    void markFulfilling(String orderId);

    /**
     * 确认收货/自提核销等：已支付或履约中 → 已完成（幂等）。
     */
    void markFulfilled(String orderId);
}
