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

import com.jeesharp.business.modules.mall.dto.MallConfirmPayDTO;
import com.jeesharp.business.modules.mall.entity.MallOrder;
import com.jeesharp.business.modules.mall.entity.MallOrderItem;
import com.jeesharp.business.modules.mall.vo.MallOrderExportVO;
import com.jeesharp.business.modules.mall.vo.MallOrderQueryVO;
import com.jeesharp.framework.mybatis.core.service.BaseInterface;

import java.util.Date;
import java.util.List;

/**
 * 订单领域服务接口，含 C 端预支付与支付确认。
 *
 * @author jeesharp
 * @since 2026-05-08
 */
public interface MallOrderService extends BaseInterface<MallOrder, MallOrderQueryVO> {

    void createOrder(MallOrder order);

    void updateOrder(MallOrder order);

    /**
     * 校验订单是否可发起预支付（须待支付且会员一致）。
     */
    void assertPayPreparable(MallOrder order, String memberId);

    /**
     * 标记订单进入预支付准备中（写入支付渠道）。
     */
    void markPayPreparing(MallOrder order, String payChannel);

    /**
     * 支付成功确认（领域层，微信回调入口）：待支付订单置为已支付；自提单生成核销码。
     * <p>幂等：已是 PAID 则直接返回（微信可能重复通知）。</p>
     */
    void confirmPaySuccess(MallConfirmPayDTO dto);

    /**
     * 0 元订单免支付确认：垂直单置为已支付并生成自提核销码（如适用）。
     *
     * @param orderId 商城订单主键
     */
    void confirmZeroAmountPay(String orderId);

    /**
     * 到店自提核销：校验配送方式、支付状态与核销码，成功后订单完结。
     *
     * @param verifyCode     支付成功后生成的自提核销码
     * @param verifyBy       核销人ID（sys_user）
     * @param verifyByName   核销人姓名
     */
    /**
     * @return 核销后的订单
     */
    MallOrder verifyPickupByVerifyCode(String verifyCode, String verifyBy, String verifyByName);

    /**
     * 创建待支付商城订单并写入明细、扣减库存（同一事务）。
     *
     * @param order 主单（无 id），金额与收货信息等须已填充
     * @param items 明细行（无 id、无 orderId），须已填充 sku、价格、数量、小计
     */
    void createPendingMobileOrder(MallOrder order, List<MallOrderItem> items);

    /**
     * 管理端导出数据（与列表筛选条件一致，不分页全量）。
     *
     * @param query 查询条件
     * @return 导出行
     */
    List<MallOrderExportVO> findExportList(MallOrderQueryVO query);

    /**
     * 管理端快递发货：已支付待发货订单填写物流信息并置为履约中。
     *
     * @param orderId           订单主键
     * @param logisticsCompany  物流公司名称
     * @param logisticsNo       运单号
     * @param shipTime          发货时间
     * @return 更新后的订单
     */
    MallOrder shipDeliveryOrder(String orderId, String logisticsCompany, String logisticsNo, Date shipTime);

    /**
     * 会员取消待支付商城订单：回补库存并置为已取消。
     *
     * @param orderId      商城订单主键
     * @param memberId     当前会员，须与订单 member_id 一致
     */
    MallOrder cancelPendingMobileOrder(String orderId, String memberId);

    /**
     * 系统取消待支付订单（支付超时等，不校验会员身份）。
     */
    MallOrder cancelPendingOrderBySystem(String orderId);

    /**
     * 查询超时的待支付订单。
     */
    java.util.List<MallOrder> listExpiredPendingPayOrders(Integer status, java.util.Date createBefore, int limit);

    /**
     * 按支付批次查询子单列表。
     */
    List<MallOrder> listByPayBatchId(String payBatchId);

    /**
     * 会员确认收货：履约中快递订单置为已完成。
     *
     * @param orderId  商城订单主键
     * @param memberId 当前会员
     * @return 更新后的订单
     */
    MallOrder confirmReceiveByMember(String orderId, String memberId);
}
