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

import cn.iocoder.yudao.module.mes.dal.dataobject.wm.materialstock.MesWmMaterialStockDO;
import cn.iocoder.yudao.module.mes.dal.dataobject.wm.materialstockbag.MesWmMaterialStockBagDO;
import cn.iocoder.yudao.module.mes.service.wm.transaction.dto.MesWmTransactionSaveReqDTO;

/**
 * MES 库存袋码明细 Service 接口
 *
 * 统一封装袋码库存明细的建立、迁移、出库、报废逻辑，供所有带袋码的库存变动入口复用。
 * 每个袋码在同一时间只有一条在库明细（唯一约束 bag_code），流转通过更新明细位置/状态实现。
 */
public interface MesWmMaterialStockBagService {

    /**
     * 入库：建立或激活活动袋码明细。
     * <p>
     * 袋码首次入库时新建明细；已出库/已报废的袋码再次入库时激活为在库并更新位置；已在库则视为重复入库抛出异常。
     *
     * @param reqDTO        事务请求
     * @param stock         目标库存汇总记录
     * @param transactionId 本笔事务 ID
     * @return 袋码明细
     */
    MesWmMaterialStockBagDO inbound(MesWmTransactionSaveReqDTO reqDTO, MesWmMaterialStockDO stock, Long transactionId);

    /**
     * 出库：将指定袋码明细置为已出库。
     *
     * @param reqDTO        事务请求（需携带 bagCode/bagCodeId）
     * @param transactionId 本笔事务 ID
     */
    void outbound(MesWmTransactionSaveReqDTO reqDTO, Long transactionId);

    /**
     * 移入/迁移：更新活动袋码明细的位置与库存状态（移库、调拨、质检合格迁移）。
     *
     * @param reqDTO        事务请求（需携带 bagCode）
     * @param targetStock   目标库存汇总记录
     * @param transactionId 本笔事务 ID
     */
    void moveIn(MesWmTransactionSaveReqDTO reqDTO, MesWmMaterialStockDO targetStock, Long transactionId);

    /**
     * 报废：将指定袋码明细置为报废。
     *
     * @param reqDTO        事务请求（需携带 bagCode）
     * @param transactionId 本笔事务 ID
     */
    void scrap(MesWmTransactionSaveReqDTO reqDTO, Long transactionId);

    /**
     * 根据库存汇总 ID 查询在库袋码明细。
     *
     * @param materialStockId 库存汇总 ID
     * @return 袋码明细（无则 null）
     */
    MesWmMaterialStockBagDO getActiveByMaterialStockId(Long materialStockId);
}