package cn.iocoder.yudao.module.aftersales.service.returnobj;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.aftersales.controller.admin.returnobj.vo.AfterSaleReturnPageReqVO;
import cn.iocoder.yudao.module.aftersales.controller.admin.returnobj.vo.AfterSaleReturnSaveReqVO;
import cn.iocoder.yudao.module.aftersales.dal.dataobject.returnobj.AfterSaleReturnDO;
import cn.iocoder.yudao.module.aftersales.dal.dataobject.returnobj.AfterSaleReturnItemDO;
import jakarta.validation.Valid;

import java.math.BigDecimal;
import java.util.Collection;
import java.util.List;

/**
 * 售后退货申请 Service 接口
 */
public interface AfterSaleReturnService {

    /**
     * 创建退货申请
     *
     * @param createReqVO 创建信息
     * @param userId      用户编号
     * @return 编号
     */
    Long createReturn(@Valid AfterSaleReturnSaveReqVO createReqVO, Long userId);

    /**
     * 审核通过（触发 MES 退货流程）
     *
     * @param id 退货申请编号
     */
    void approveReturn(Long id);

    /**
     * 获得退货申请
     *
     * @param id 编号
     * @return 退货申请
     */
    AfterSaleReturnDO getReturn(Long id);

    /**
     * 获得退货申请列表
     *
     * @param ids 编号列表
     * @return 退货申请列表
     */
    List<AfterSaleReturnDO> getReturnList(Collection<Long> ids);

    /**
     * 获得退货申请分页
     *
     * @param pageReqVO 分页查询
     * @param userId    用户编号
     * @return 退货申请分页
     */
    PageResult<AfterSaleReturnDO> getReturnPage(AfterSaleReturnPageReqVO pageReqVO, Long userId);

    /**
     * 获得退货明细行列表
     *
     * @param returnId 退货申请编号
     * @return 明细行列表
     */
    List<AfterSaleReturnItemDO> getReturnItemListByReturnId(Long returnId);

    /**
     * MES 质检完成回调
     *
     * @param returnId      退货申请编号
     * @param qualityResult 质检结论
     * @param reportUrl     质检报告 URL
     */
    void onQualityFinished(Long returnId, String qualityResult, String reportUrl);

    /**
     * MES 退货入库完成回调
     *
     * @param returnId 退货申请编号
     */
    void onInboundFinished(Long returnId);

    /**
     * ERP 退款完成回调
     *
     * @param returnId           退货申请编号
     * @param actualRefundPrice  实退金额
     */
    void onRefundCompleted(Long returnId, BigDecimal actualRefundPrice);

}