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

import com.jeesharp.business.modules.trade.dto.TradeOrderCreateDTO;
import com.jeesharp.business.modules.trade.entity.TradeOrder;
import com.jeesharp.business.modules.trade.entity.TradeOrderItem;
import com.jeesharp.business.modules.trade.vo.TradeOrderQueryVO;
import com.jeesharp.framework.pojo.Page;

import java.util.List;

/**
 * 统一交易订单跨模块门面 API；垂直域 Application 通过本接口编排，禁止依赖 {@code business-order-service}。
 *
 * @author jeesharp
 * @since 2026-06-08
 */
public interface TradeOrderFacadeApi {

    /**
     * 创建待支付统一订单。
     *
     * @return 新建统一单主键
     */
    String createPendingPayOrder(TradeOrderCreateDTO dto);

    void markPaid(String orderId, String payOrderId, String payChannel);

    void markCancelled(String orderId);

    /**
     * 待支付取消（垂直单超时/用户取消待支付场景）。
     */
    void cancelPending(String orderId);

    /**
     * 到店核销完成后同步统一单为已关闭。
     */
    void markClosed(String orderId);

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

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

    TradeOrder get(String id);

    Page<TradeOrder> findPage(Page<TradeOrder> page, TradeOrderQueryVO query);

    /**
     * 按统一单主键批量查询明细行（供商城等读切换/列表回退展示）。
     */
    List<TradeOrderItem> findItemsByTradeOrderIds(List<String> tradeOrderIds);
}
