package com.seer.teach.mall.app.order.service;

import com.seer.teach.common.exception.CommonException;
import com.seer.teach.mall.entity.OrderEntity;
import com.seer.teach.mall.request.OrderReq;
import com.seer.teach.mall.request.OrderSettlementReq;
import com.seer.teach.mall.request.OrderUpdateReq;
import com.seer.teach.mall.response.OrderSettlementRespVO;

import java.util.List;

/**
 * <p>
 * 服务类
 * </p>
 *
 * @author Captain
 * @since 2025-06-10
 */
public interface IAppOrderService {

    /**
     * 获取订单结算信息
     *
     * 此方法用于处理订单结算请求，根据请求中的参数，计算并返回订单的结算信息
     * 包括但不限于订单总价、优惠信息、实付金额等
     *
     * @param orderSettlementReq 订单结算请求对象，包含结算所需的订单信息和参数
     * @return OrderSettlementRespVO 返回订单结算响应对象，包含结算结果和相关信息
     */
    OrderSettlementRespVO getSettlementOrderDetail(OrderSettlementReq orderSettlementReq);

    /**
     * 创建订单
     *
     * @param order 订单请求对象，包含订单的详细信息
     * @return 如果订单创建成功，则返回true；否则返回false
     */
    String createOrder(OrderReq order) throws CommonException;

    /**
     * 更新订单信息
     *
     * 仅在代发货状态可以更新订单的收件人信息，如收货人信息、手机号码、地址等信息
     *
     * @param orderReq 包含更新信息的订单请求对象
     * @return 返回一个布尔值，表示订单更新是否成功 true表示成功，false表示失败
     */
    boolean updateOrder(OrderReq orderReq);

    /**
     * 取消订单
     *
     * @param orderSn 订单编号，用于标识特定的订单
     * @return 如果订单取消成功，则返回true；否则返回false
     */
    boolean cancelOrder(String orderSn);

    /**
     * 取消子订单
     *
     * @param childOrderSn 子订单Sn
     * @return 如果子订单取消成功，则返回true；否则返回false
     */
    boolean cancelChildOrder(String childOrderSn);

    /**
     * 删除指定订单
     * <p>
     * 用于删除系统中的一个指定订单通过订单编号（orderSn）来定位订单
     *
     * @param orderUpdateReq 订单编号，用于标识一个唯一的订单
     * @return 如果订单删除成功，则返回true；如果删除失败或订单不存在，则返回false
     */
    boolean deleteOrder(OrderUpdateReq orderUpdateReq);

    /**
     * 确认订单收货
     * <p>
     * 用于确认订单收货，通过订单编号（orderSn）来定位订单
     *
     * @param orderUpdateReq 订单编号，用于标识一个唯一的订单
     * @return 如果订单确认收货成功，则返回true；如果确认收货失败或订单不存在，则返回false
     */
    boolean receiveOrder(OrderUpdateReq orderUpdateReq);

    /**
     * 获取未付款的订单列表
     *
     * @return 返回一个订单列表，包含所有未付款的订单信息
     */
    List<OrderEntity> getUnpaidOrders();

    /**
     * 订单过期处理
     *
     * @param order 订单
     */
    void expireOrder(OrderEntity order);

    /**
     * 获取超过指定天数为确认收货的订单列表
     *
     * @param autoConfirmReceiveDays 自动确认收货天数
     * @return 订单列表
     */
    List<OrderEntity> getOverdueOrders(int autoConfirmReceiveDays);

    /**
     * 仓库发货，只有经销商的仓管才使用此接口
     *
     * @param orderUpdateReq 订单编号，用于标识一个唯一的订单
     * @return 如果订单发货成功，则返回true；如果发货失败或订单不存在，则返回false
     */
    boolean deliveryOrder(OrderUpdateReq orderUpdateReq);


}