package cn.iocoder.yudao.module.mes.service.wm.batch;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.mes.controller.admin.wm.batch.vo.MesWmBatchGenerateReqVO;
import cn.iocoder.yudao.module.mes.controller.admin.wm.batch.vo.MesWmBatchPageReqVO;
import cn.iocoder.yudao.module.mes.controller.admin.wm.batch.vo.MesWmBatchProcessTraceRespVO;
import cn.iocoder.yudao.module.mes.controller.admin.wm.batch.vo.MesWmBatchPurchaseSourceRespVO;
import cn.iocoder.yudao.module.mes.controller.admin.wm.batch.vo.MesWmBatchSalesTargetRespVO;
import cn.iocoder.yudao.module.mes.dal.dataobject.pro.batch.MesProBatchDO;
import cn.iocoder.yudao.module.mes.dal.dataobject.wm.batch.MesWmBatchDO;

import java.util.List;

/**
 * 批次管理 Service 接口
 *
 * @author 超级管理员
 */
public interface MesWmBatchService {

    /**
     * 获得批次分页
     *
     * @param pageReqVO 分页查询
     * @return 批次分页
     */
    PageResult<MesWmBatchDO> getBatchPage(MesWmBatchPageReqVO pageReqVO);

    /**
     * 获得批次
     *
     * @param id 批次编号
     * @return 批次记录
     */
    MesWmBatchDO getBatch(Long id);

    /**
     * 根据批次号获得批次
     *
     * @param code 批次号
     * @return 批次记录
     */
    MesWmBatchDO getBatchByCode(String code);

    /**
     * 获取或生成批次编码
     * <p>
     * 根据物料批次配置，查询或生成批次记录
     *
     * @param reqVO 批次参数（包含 itemId 及其他可选属性）
     * @return 批次记录（如果物料未启用批次管理则返回 null）
     */
    MesWmBatchDO getOrGenerateBatchCode(MesWmBatchGenerateReqVO reqVO);

    /**
     * 批次向前追溯（递归查询）
     * <p>
     * 查询当前批次被哪些工单的哪些批次产品消耗
     *
     * @param code 批次编码
     * @return 批次列表
     */
    List<MesWmBatchDO> getForwardBatchList(String code);

    /**
     * 批次向后追溯（递归查询）
     * <p>
     * 查询当前批次的产品使用了哪些批次的物资
     *
     * @param code 批次编码
     * @return 批次列表
     */
    List<MesWmBatchDO> getBackwardBatchList(String code);

    /**
     * 校验批次存在，并校验批次与物料的归属关系
     *
     * @param batchId 批次ID
     * @param itemId  物料ID
     * @return 批次记录
     */
    MesWmBatchDO validateBatchExists(Long batchId, Long itemId);

    /**
     * 校验批次存在，并校验批次与物料、客户/供应商的归属关系
     *
     * @param batchId  批次ID
     * @param itemId   物料ID
     * @param clientId 客户ID（可选，不为空时校验）
     * @param vendorId 供应商ID（可选，不为空时校验）
     * @return 批次记录
     */
    MesWmBatchDO validateBatchExists(Long batchId, Long itemId, Long clientId, Long vendorId);

    /**
     * 获取指定工具的批次数量
     *
     * @param toolId 工具编号
     * @return 批次数量
     */
    Long getBatchCountByToolId(Long toolId);

    /**
     * 获得批次采购来源（采购入库单 + IQC）
     *
     * @param code 批次号
     * @return 采购来源列表
     */
    List<MesWmBatchPurchaseSourceRespVO> getPurchaseSourceList(String code);

    /**
     * 获得批次销售去向（销售出库单 + OQC）
     *
     * @param code 批次号
     * @return 销售去向列表
     */
    List<MesWmBatchSalesTargetRespVO> getSalesTargetList(String code);

    /**
     * 获得批次工序流转（产出/投入事件）
     *
     * @param code 批次号
     * @return 工序流转列表
     */
    List<MesWmBatchProcessTraceRespVO> getProcessTraceList(String code);

    /**
     * 根据 SN 码获得批次
     *
     * @param sn SN 码
     * @return 批次记录（未命中返回 null）
     */
    MesWmBatchDO getBatchBySn(String sn);

    /**
     * 根据生产批次获取或创建仓库批次（打通生产批次体系与仓库批次体系）
     * <p>
     * 生产线扫码入库、销售出库、质检转合格等流程，库存与流水统一挂在仓库批次（mes_wm_batch）上，
     * 通过生产批次号（mes_pro_batch.code）桥接，已存在则直接复用，否则新建。
     *
     * @param proBatch 生产批次
     * @return 仓库批次（含 id）
     */
    MesWmBatchDO getOrCreateByProBatch(MesProBatchDO proBatch);

}