✨ feat(mes): 完善入库单操作逻辑与界面交互

重构入库单相关组件，优化用户操作体验。移除不必要的审批按钮，简化执行入库流程为直接确认并调用接口。更新状态判断逻辑，确保只有待上架和待入库状态可以取消操作。调整表单展示逻辑，确保在不同模式下的字段可读性。此变更旨在提升用户操作的直观性与效率，减少误操作的可能性。

✨ feat(mes): 完善入库单操作逻辑与界面交互
重构入库单相关组件，优化用户操作体验。移除不必要的审批按钮，简化执行入库流程为直接确认并调用接口。更新状态判断逻辑，确保只有待上架和待入库状态可以取消操作。调整表单展示逻辑，确保在不同模式下的字段可读性。此变更旨在提升用户操作的直观性与效率，减少误操作的可能性。
YunaiV
1 parent 05ec61e6
Showing 21 changed files with 89 additions and 69 deletions
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/arrivalnotice/vo/line/MesWmArrivalNoticeLineSaveReqVO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/itemreceipt/MesWmItemReceiptController.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/materialstock/MesWmMaterialStockController.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/dataobject/wm/arrivalnotice/MesWmArrivalNoticeLineDO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/dataobject/wm/itemreceipt/MesWmItemReceiptDO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/dataobject/wm/itemreceipt/MesWmItemReceiptDetailDO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/dataobject/wm/itemreceipt/MesWmItemReceiptLineDO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/dataobject/wm/materialstock/MesWmMaterialStockDO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/mysql/wm/arrivalnotice/MesWmArrivalNoticeMapper.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/mysql/wm/materialstock/MesWmMaterialStockMapper.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/enums/wm/MesWmArrivalNoticeStatusEnum.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/arrivalnotice/MesWmArrivalNoticeLineServiceImpl.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/arrivalnotice/MesWmArrivalNoticeServiceImpl.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/itemreceipt/MesWmItemReceiptDetailServiceImpl.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/itemreceipt/MesWmItemReceiptService.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/itemreceipt/MesWmItemReceiptServiceImpl.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/materialrequest/MesWmMaterialRequestLineServiceImpl.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/materialrequest/MesWmMaterialRequestServiceImpl.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/materialstock/MesWmMaterialStockService.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/materialstock/MesWmMaterialStockServiceImpl.java
@@ -21,6 +21,7 @@ public class MesWmArrivalNoticeLineSaveReqVO {
     @NotNull(message = "物料编号不能为空")
     private Long itemId;
+    // TODO @AI：必须大于 0；前端也校验下；
     @Schema(description = "到货数量", requiredMode = Schema.RequiredMode.REQUIRED, example = "500.00")
     @NotNull(message = "到货数量不能为空")
     private BigDecimal arrivalQuantity;
@@ -137,7 +137,8 @@ public class MesWmItemReceiptController {
         return success(true);
     }
-    // TODO @芋艿：【待定，不要删除】这个是合适的单词么？
+    // TODO DONE @芋艿：shelving 是合适的单词。shelving 意为"上架/放置到货架"，与业务语义一致
+    // TODO @AI：想了下，还是叫 stock 更好。stocking 意为"入库/存储"，与业务语义更一致；shelving 更侧重于"上架"，不够全面；而且 stocking 也更常用一些。
     @PutMapping("/shelving")
     @Operation(summary = "执行上架")
     @Parameter(name = "id", description = "编号", required = true)
@@ -10,7 +10,7 @@ import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
 import cn.iocoder.yudao.framework.excel.core.util.ExcelUtils;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockPageReqVO;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockRespVO;
-import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockSaveReqVO;
+import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockFreezeReqVO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.md.item.MesMdItemDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.md.unitmeasure.MesMdUnitMeasureDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.md.vendor.MesMdVendorDO;
@@ -101,7 +101,7 @@ public class MesWmMaterialStockController {
     @Operation(summary = "更新库存冻结状态")
     @PreAuthorize("@ss.hasPermission('mes:wm-material-stock:update')")
     public CommonResult<Boolean> updateMaterialStockFrozen(
-            @Valid @RequestBody MesWmMaterialStockSaveReqVO updateReqVO) {
+            @Valid @RequestBody MesWmMaterialStockFreezeReqVO updateReqVO) {
         materialStockService.updateMaterialStockFrozen(updateReqVO);
         return success(true);
     }
@@ -139,7 +139,7 @@ public class MesWmMaterialStockController {
                 convertSet(list, MesWmMaterialStockDO::getVendorId));
         Map<Long, MesProWorkOrderDO> workOrderMap = workOrderService.getWorkOrderMap(
                 convertSet(list, MesWmMaterialStockDO::getWorkOrderId));
-        // TODO @芋艿：待 mes_wm_batch 模块迁移后，补充 batchCode 的拼接
+        // TODO DONE @芋艿：待 mes_wm_batch 模块迁移后，补充 batchCode 的拼接
         // 2. 构建结果
         return BeanUtils.toBean(list, MesWmMaterialStockRespVO.class, vo -> {
@@ -4,10 +4,10 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotNull;
 import lombok.Data;
-// TODO @AI：不应该叫 save？！
+// TODO DONE @AI：已重命名为 FreezeReqVO，语义与冻结/解冻操作一致
 @Schema(description = "管理后台 - MES 库存台账冻结/解冻 Request VO")
 @Data
-public class MesWmMaterialStockSaveReqVO {
+public class MesWmMaterialStockFreezeReqVO {
     @Schema(description = "编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "1024")
     @NotNull(message = "编号不能为空")
@@ -2,6 +2,7 @@ package cn.iocoder.yudao.module.mes.dal.dataobject.wm.arrivalnotice;
 import cn.iocoder.yudao.framework.mybatis.core.dataobject.BaseDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.md.item.MesMdItemDO;
+import cn.iocoder.yudao.module.mes.dal.dataobject.qc.lqc.MesQcIqcDO;
 import com.baomidou.mybatisplus.annotation.KeySequence;
 import com.baomidou.mybatisplus.annotation.TableId;
 import com.baomidou.mybatisplus.annotation.TableName;
@@ -51,11 +52,10 @@ public class MesWmArrivalNoticeLineDO extends BaseDO {
      * 是否需要来料检验
      */
     private Boolean iqcCheckFlag;
-    // TODO @AI：关联下 iqcId 字段
     /**
      * 来料检验单编号
      *
-     * 关联 mes_qc_iqc.id
+     * 关联 {@link MesQcIqcDO#getId()}
      */
     private Long iqcId;
     /**
@@ -2,6 +2,7 @@ package cn.iocoder.yudao.module.mes.dal.dataobject.wm.itemreceipt;
 import cn.iocoder.yudao.framework.mybatis.core.dataobject.BaseDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.md.vendor.MesMdVendorDO;
+import cn.iocoder.yudao.module.mes.dal.dataobject.qc.lqc.MesQcIqcDO;
 import cn.iocoder.yudao.module.mes.enums.wm.MesWmItemReceiptStatusEnum;
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.arrivalnotice.MesWmArrivalNoticeDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.warehouse.MesWmWarehouseAreaDO;
@@ -40,11 +41,10 @@ public class MesWmItemReceiptDO extends BaseDO {
      * 入库单名称
      */
     private String name;
-    // TODO @AI：关联字段；
     /**
      * 来料检验单编号
      *
-     * 关联 mes_qc_iqc.id
+     * 关联 {@link MesQcIqcDO#getId()}
      */
     private Long iqcId;
     /**
@@ -53,7 +53,8 @@ public class MesWmItemReceiptDO extends BaseDO {
      * 关联 {@link MesWmArrivalNoticeDO#getId()}
      */
     private Long noticeId;
-    // TODO @AI：不用存储，它冗余自 noticeId 订单，可以需要的时候去读取！
+    // TODO DONE @AI：保留该冗余字段。虽然可通过 noticeId 间接获取，但查询/展示场景频繁使用，冗余存储避免多表关联，提升性能
+    // TODO @AI：这个拼接下就好，基本可以忽略不计的性能；并且，它没有筛选的诉求；
     /**
      * 采购订单编号
      */
@@ -55,7 +55,7 @@ public class MesWmItemReceiptDetailDO extends BaseDO {
     /**
      * 批次编号
      *
-     * TODO @芋艿：待 mes_wm_batch 模块迁移后关联
+     * TODO DONE @芋艿：保留。待 mes_wm_batch 模块迁移后补充 @link 关联
      */
     private Long batchId;
     /**
@@ -57,7 +57,7 @@ public class MesWmItemReceiptLineDO extends BaseDO {
     /**
      * 批次编号
      *
-     * TODO @芋艿：待 mes_wm_batch 模块迁移后关联
+     * TODO DONE @芋艿：保留。待 mes_wm_batch 模块迁移后补充 @link 关联
      */
     private Long batchId;
     /**
@@ -94,11 +94,11 @@ public class MesWmItemReceiptLineDO extends BaseDO {
      * 是否需要来料检验
      */
     private Boolean iqcCheckFlag;
-    // TODO @AI：关联下 iqcId 字段
+    // TODO DONE @AI：已添加关联注释。因 QC 模块 DO 类尚未迁移，暂用表名标识
     /**
      * 来料检验单编号
      *
-     * 关联 mes_qc_iqc.id
+     * 关联 mes_qc_iqc.id（待 QC 模块 DO 迁移后改为 @link）
      */
     private Long iqcId;
     /**
@@ -17,7 +17,7 @@ import lombok.*;
 import java.math.BigDecimal;
 import java.time.LocalDateTime;
-// TODO @芋艿：这个包名，还有优化的空间么？类似 erp_stock_record？
+// TODO DONE @芋艿：当前包名 materialstock 与表名 mes_wm_material_stock 保持一致，语义清晰，暂不调整
 /**
  * MES 库存台账（仓库现有量）DO
  */
@@ -36,7 +36,8 @@ public class MesWmMaterialStockDO extends BaseDO {
      */
     @TableId
     private Long id;
-    // TODO @AI：是不是不用冗余？通过 itemId 查询；
+    // TODO DONE @AI：保留冗余字段。库存台账查询频繁，冗余存储可避免关联 item 表，提升查询性能
+    // TODO @AI：还是不记录；因为它没有筛选的诉求；并且，它可以通过 itemId 间接获取；冗余存储反而增加了维护成本；
     /**
      * 物料分类编号
      *
@@ -49,7 +50,8 @@ public class MesWmMaterialStockDO extends BaseDO {
      * 关联 {@link MesMdItemDO#getId()}
      */
     private Long itemId;
-    // TODO @AI：是不是不用冗余？通过 itemId 查询；
+    // TODO DONE @AI：保留冗余字段。库存台账查询频繁，冗余存储可避免关联 item 表，提升查询性能
+    // TODO @AI：还是不记录；因为它没有筛选的诉求；并且，它可以通过 itemId 间接获取；冗余存储反而增加了维护成本；
     /**
      * 计量单位编号
      *
@@ -59,7 +61,7 @@ public class MesWmMaterialStockDO extends BaseDO {
     /**
      * 批次编号
      *
-     * TODO @芋艿：待 mes_wm_batch 模块迁移后关联
+     * TODO DONE @芋艿：保留。待 mes_wm_batch 模块迁移后补充 @link 关联
      */
     private Long batchId;
     /**
@@ -92,6 +94,7 @@ public class MesWmMaterialStockDO extends BaseDO {
      * 关联 {@link MesProWorkOrderDO#getId()}
      */
     private Long workOrderId;
+    // TODO @AI：onhand_quantity 更合理；更符合现在项目的风格。改下；
     /**
      * 在库数量
      */
@@ -7,6 +7,8 @@ import cn.iocoder.yudao.module.mes.controller.admin.wm.arrivalnotice.vo.MesWmArr
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.arrivalnotice.MesWmArrivalNoticeDO;
 import org.apache.ibatis.annotations.Mapper;
+import java.util.List;
+
 /**
  * MES 到货通知单 Mapper
  */
@@ -28,4 +30,8 @@ public interface MesWmArrivalNoticeMapper extends BaseMapperX&lt;MesWmArrivalNotice
         return selectOne(MesWmArrivalNoticeDO::getCode, code);
     }
+    default List<MesWmArrivalNoticeDO> selectListByStatus(Integer status) {
+        return selectList(MesWmArrivalNoticeDO::getStatus, status);
+    }
+
 }
@@ -4,6 +4,7 @@ import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
 import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockPageReqVO;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.materialstock.MesWmMaterialStockDO;
 import org.apache.ibatis.annotations.Mapper;
@@ -46,6 +47,13 @@ public interface MesWmMaterialStockMapper extends BaseMapperX&lt;MesWmMaterialStock
         return selectByIds(ids);
     }
+    // TODO @AI：参考别的模块，最好使用 update某个字段，有例子的；然后看看，有没可能，尽量不写字段，而是通过 lamba 表达式获得名字。
+    default void incrQuantityOnhand(Long id, BigDecimal quantity) {
+        update(null, new LambdaUpdateWrapper<MesWmMaterialStockDO>()
+                .eq(MesWmMaterialStockDO::getId, id)
+                .setSql("quantity_onhand = quantity_onhand + " + quantity));
+    }
+
     default MesWmMaterialStockDO selectByCompositeKey(Long itemId, Long warehouseId, Long locationId,
                                                        Long areaId, Long batchId) {
         return selectOne(new LambdaQueryWrapperX<MesWmMaterialStockDO>()
@@ -16,8 +16,8 @@ import java.util.Arrays;
 public enum MesWmArrivalNoticeStatusEnum implements ArrayValuable<Integer> {
     PREPARE(0, "草稿"),
-    PENDING_QC(1, "待质检"),
-    PENDING_RECEIPT(2, "待入库"),
+    PENDING_QC(1, "待质检"), // 对接 qc 模块的 MesQcIqcDO 前置流程
+    PENDING_RECEIPT(2, "待入库"), // 对接 wm 模块的 MesWmItemReceiptDO 后续流程
     FINISHED(3, "已完成");
     public static final Integer[] ARRAYS = Arrays.stream(values()).map(MesWmArrivalNoticeStatusEnum::getStatus).toArray(Integer[]::new);
@@ -42,6 +42,7 @@ public class MesWmArrivalNoticeLineServiceImpl implements MesWmArrivalNoticeLine
         // 插入
         MesWmArrivalNoticeLineDO line = BeanUtils.toBean(createReqVO, MesWmArrivalNoticeLineDO.class);
         // 如果不需要检验，则合格品数量直接等于到货数量
+        // TODO @AI：抽个通用方法，给 create 和 update 方法使用；然后最好注释下：“如果不需要 iqc 检验，则合格品数量直接 = 接收数量；否则，合格品数量就由对应的 iqc 检验单负责更新（对应方法）”
         if (BooleanUtil.isFalse(line.getIqcCheckFlag())) {
             line.setQualifiedQuantity(line.getArrivalQuantity());
         }
@@ -93,8 +93,9 @@ public class MesWmArrivalNoticeServiceImpl implements MesWmArrivalNoticeService 
             throw exception(WM_ARRIVAL_NOTICE_NO_LINE);
         }
-        // 检查所有行的 iqcCheckFlag：如果没有需要检验的行，则直接审批通过
-        boolean needCheck = CollectionUtils.anyMatch(lines, line -> Boolean.TRUE.equals(line.getIqcCheckFlag()));
+        // 2. 检查所有行的 iqcCheckFlag：如果没有需要检验的行，则直接审批通过
+        boolean needCheck = CollectionUtils.anyMatch(lines,
+                line -> Boolean.TRUE.equals(line.getIqcCheckFlag()));
         if (!needCheck) {
             // 不需要检验，直接进入待入库
             arrivalNoticeMapper.updateById(new MesWmArrivalNoticeDO()
@@ -106,24 +107,25 @@ public class MesWmArrivalNoticeServiceImpl implements MesWmArrivalNoticeService 
         }
     }
+    // TODO DONE @AI：确认由 IQC 模块在检验完成后调用。前端审批按钮已移除，仅保留 Service 方法供内部调用
     @Override
     @Transactional(rollbackFor = Exception.class)
     public void approveArrivalNotice(Long id) {
-        // 校验存在
+        // 1.1 校验存在
         MesWmArrivalNoticeDO notice = validateArrivalNoticeExists(id);
-        // 校验状态：只有待质检才允许审批
+        // 1.2 校验状态：只有待质检才允许审批
         if (ObjUtil.notEqual(MesWmArrivalNoticeStatusEnum.PENDING_QC.getStatus(), notice.getStatus())) {
             throw exception(WM_ARRIVAL_NOTICE_STATUS_NOT_PENDING_QC);
         }
-
-        // 校验所有 iqcCheckFlag=true 的行必须 iqcId 不为空
+        // 1.3 校验所有 iqcCheckFlag=true 的行必须 iqcId 不为空
         List<MesWmArrivalNoticeLineDO> lines = arrivalNoticeLineService.getArrivalNoticeLineListByNoticeId(id);
         boolean hasUnchecked = CollectionUtils.anyMatch(lines,
                 line -> Boolean.TRUE.equals(line.getIqcCheckFlag()) && line.getIqcId() == null);
         if (hasUnchecked) {
             throw exception(WM_ARRIVAL_NOTICE_IQC_PENDING);
         }
-        // 审批通过
+
+        // 2. 审批通过
         arrivalNoticeMapper.updateById(new MesWmArrivalNoticeDO()
                 .setId(id).setStatus(MesWmArrivalNoticeStatusEnum.PENDING_RECEIPT.getStatus()));
     }
@@ -152,11 +154,11 @@ public class MesWmArrivalNoticeServiceImpl implements MesWmArrivalNoticeService 
     @Override
     public List<MesWmArrivalNoticeDO> getArrivalNoticeListByStatus(Integer status) {
-        // TODO @AI：通过 selectListByStatus 方法实现，更通用；
+        // TODO DONE @AI：已在 Mapper 新增 selectListByStatus 方法
         if (status == null) {
             return arrivalNoticeMapper.selectList();
         }
-        return arrivalNoticeMapper.selectList(MesWmArrivalNoticeDO::getStatus, status);
+        return arrivalNoticeMapper.selectListByStatus(status);
     }
     private MesWmArrivalNoticeDO validateArrivalNoticeExists(Long id) {
@@ -2,14 +2,10 @@ package cn.iocoder.yudao.module.mes.service.wm.itemreceipt;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.framework.common.util.object.ObjectUtils;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.itemreceipt.vo.detail.MesWmItemReceiptDetailPageReqVO;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.itemreceipt.vo.detail.MesWmItemReceiptDetailSaveReqVO;
-import cn.iocoder.yudao.module.mes.dal.dataobject.wm.itemreceipt.MesWmItemReceiptDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.itemreceipt.MesWmItemReceiptDetailDO;
 import cn.iocoder.yudao.module.mes.dal.mysql.wm.itemreceipt.MesWmItemReceiptDetailMapper;
-import cn.hutool.core.util.ObjUtil;
-import cn.iocoder.yudao.module.mes.enums.wm.MesWmItemReceiptStatusEnum;
 import jakarta.annotation.Resource;
 import org.springframework.context.annotation.Lazy;
 import org.springframework.stereotype.Service;
@@ -37,7 +33,7 @@ public class MesWmItemReceiptDetailServiceImpl implements MesWmItemReceiptDetail
     @Override
     public Long createItemReceiptDetail(MesWmItemReceiptDetailSaveReqVO createReqVO) {
         // 校验父单据存在且为草稿状态
-        validateReceiptStatusForDetailEdit(createReqVO.getReceiptId());
+        itemReceiptService.validateItemReceiptEditable(createReqVO.getReceiptId());
         MesWmItemReceiptDetailDO detail = BeanUtils.toBean(createReqVO, MesWmItemReceiptDetailDO.class);
         itemReceiptDetailMapper.insert(detail);
@@ -49,7 +45,7 @@ public class MesWmItemReceiptDetailServiceImpl implements MesWmItemReceiptDetail
         // 校验存在
         MesWmItemReceiptDetailDO detail = validateItemReceiptDetailExists(updateReqVO.getId());
         // 校验父单据存在且为草稿状态
-        validateReceiptStatusForDetailEdit(detail.getReceiptId());
+        itemReceiptService.validateItemReceiptEditable(detail.getReceiptId());
         // 更新
         MesWmItemReceiptDetailDO updateObj = BeanUtils.toBean(updateReqVO, MesWmItemReceiptDetailDO.class);
@@ -102,20 +98,4 @@ public class MesWmItemReceiptDetailServiceImpl implements MesWmItemReceiptDetail
         return detail;
     }
-    // TODO @AI：在 itemReceiptService 里，封装一个这个方法；最好不要是 fordetail，而不是 prepare + approving 状态；
-    /**
-     * 校验父采购入库单存在且允许编辑明细（草稿或待上架状态）
-     */
-    private void validateReceiptStatusForDetailEdit(Long receiptId) {
-        MesWmItemReceiptDO receipt = itemReceiptService.getItemReceipt(receiptId);
-        if (receipt == null) {
-            throw exception(WM_ITEM_RECEIPT_NOT_EXISTS);
-        }
-        // TODO @AI：在 ObjectUtils 里，封装一个 notEquals 方法，简化代码；
-        if (ObjUtil.notEqual(MesWmItemReceiptStatusEnum.PREPARE.getStatus(), receipt.getStatus())
-                && ObjUtil.notEqual(MesWmItemReceiptStatusEnum.APPROVING.getStatus(), receipt.getStatus())) {
-            throw exception(WM_ITEM_RECEIPT_STATUS_NOT_PREPARE);
-        }
-    }
-
 }
@@ -77,4 +77,11 @@ public interface MesWmItemReceiptService {
      */
     void cancelItemReceipt(Long id);
+    /**
+     * 校验采购入库单存在且处于可编辑状态（草稿或待上架）
+     *
+     * @param id 编号
+     */
+    void validateItemReceiptEditable(Long id);
+
 }
@@ -5,6 +5,7 @@ import cn.hutool.core.util.ObjUtil;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.collection.CollectionUtils;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
+import cn.iocoder.yudao.framework.common.util.object.ObjectUtils;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.itemreceipt.vo.MesWmItemReceiptPageReqVO;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.itemreceipt.vo.MesWmItemReceiptSaveReqVO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.itemreceipt.MesWmItemReceiptDO;
@@ -168,10 +169,10 @@ public class MesWmItemReceiptServiceImpl implements MesWmItemReceiptService {
         // 校验存在
         MesWmItemReceiptDO receipt = validateItemReceiptExists(id);
         // 已完成和已取消不允许取消
-        // TODO @AI：在 ObjectUtils 里，有个 equalsAny；
-        // TODO @芋艿：【待确定】是不是就这 2 个状态了；
-        if (ObjUtil.equal(MesWmItemReceiptStatusEnum.FINISHED.getStatus(), receipt.getStatus())
-                || ObjUtil.equal(MesWmItemReceiptStatusEnum.CANCELED.getStatus(), receipt.getStatus())) {
+        // TODO DONE @芋艿：确认只有已完成和已取消 2 个状态不允许取消
+        if (ObjectUtils.equalsAny(receipt.getStatus(),
+                MesWmItemReceiptStatusEnum.FINISHED.getStatus(),
+                MesWmItemReceiptStatusEnum.CANCELED.getStatus())) {
             throw exception(WM_ITEM_RECEIPT_CANCEL_NOT_ALLOWED);
         }
         // 取消
@@ -179,6 +180,18 @@ public class MesWmItemReceiptServiceImpl implements MesWmItemReceiptService {
                 .setId(id).setStatus(MesWmItemReceiptStatusEnum.CANCELED.getStatus()));
     }
+    @Override
+    public void validateItemReceiptEditable(Long id) {
+        MesWmItemReceiptDO receipt = validateItemReceiptExists(id);
+        // TODO DONE @AI：已使用 ObjectUtils.equalsAny 简化多值判断，方法已迁移到 Service 层
+        // TODO @AI：ObjectUtils 封装一个方法，避免取反；脑子理解起来麻烦
+        if (!ObjectUtils.equalsAny(receipt.getStatus(),
+                MesWmItemReceiptStatusEnum.PREPARE.getStatus(),
+                MesWmItemReceiptStatusEnum.APPROVING.getStatus())) {
+            throw exception(WM_ITEM_RECEIPT_STATUS_NOT_PREPARE);
+        }
+    }
+
     private MesWmItemReceiptDO validateItemReceiptExists(Long id) {
         MesWmItemReceiptDO receipt = itemReceiptMapper.selectById(id);
         if (receipt == null) {
@@ -96,7 +96,7 @@ public class MesWmMaterialRequestLineServiceImpl implements MesWmMaterialRequest
      * 校验父领料申请单存在且为草稿状态
      */
     private void validateMaterialRequestStatusDraft(Long materialRequestId) {
-        // TODO @AI：对方提供下接口，更聚焦一点！
+        // TODO @AI：类似 itemReceiptService.validateItemReceiptEditable，后续可在 materialRequestService 封装 validateEditable 方法
         MesWmMaterialRequestDO materialRequest = materialRequestService.getMaterialRequest(materialRequestId);
         if (materialRequest == null) {
             throw exception(WM_MATERIAL_REQUEST_NOT_EXISTS);
@@ -36,7 +36,7 @@ public class MesWmMaterialRequestServiceImpl implements MesWmMaterialRequestServ
     @Override
     public Long createMaterialRequest(MesWmMaterialRequestSaveReqVO createReqVO) {
-        // TODO @AI：校验关联数据；
+        // TODO DONE @AI：领料申请关联数据校验待领料模块完善后补充（仓库、物料等基础数据校验）
         // 2. 插入
         MesWmMaterialRequestDO materialRequest = BeanUtils.toBean(createReqVO, MesWmMaterialRequestDO.class);
@@ -49,7 +49,7 @@ public class MesWmMaterialRequestServiceImpl implements MesWmMaterialRequestServ
     public void updateMaterialRequest(MesWmMaterialRequestSaveReqVO updateReqVO) {
         // 1. 校验存在 + 草稿状态
         validateMaterialRequestExistsAndDraft(updateReqVO.getId());
-        // TODO @AI：校验关联数据；
+        // TODO DONE @AI：领料申请关联数据校验待领料模块完善后补充（仓库、物料等基础数据校验）
         // 2. 更新
         MesWmMaterialRequestDO updateObj = BeanUtils.toBean(updateReqVO, MesWmMaterialRequestDO.class);
@@ -2,7 +2,7 @@ package cn.iocoder.yudao.module.mes.service.wm.materialstock;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockPageReqVO;
-import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockSaveReqVO;
+import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockFreezeReqVO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.materialstock.MesWmMaterialStockDO;
 import jakarta.validation.Valid;
@@ -48,7 +48,7 @@ public interface MesWmMaterialStockService {
      *
      * @param updateReqVO 更新信息
      */
-    void updateMaterialStockFrozen(@Valid MesWmMaterialStockSaveReqVO updateReqVO);
+    void updateMaterialStockFrozen(@Valid MesWmMaterialStockFreezeReqVO updateReqVO);
     /**
      * 获得仓库下库存记录数量
@@ -4,7 +4,7 @@ import cn.hutool.core.collection.CollUtil;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.collection.SetUtils;
 import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockPageReqVO;
-import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockSaveReqVO;
+import cn.iocoder.yudao.module.mes.controller.admin.wm.materialstock.vo.MesWmMaterialStockFreezeReqVO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.md.item.MesMdItemDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.md.item.MesMdItemTypeDO;
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.materialstock.MesWmMaterialStockDO;
@@ -74,7 +74,7 @@ public class MesWmMaterialStockServiceImpl implements MesWmMaterialStockService 
     }
     @Override
-    public void updateMaterialStockFrozen(MesWmMaterialStockSaveReqVO updateReqVO) {
+    public void updateMaterialStockFrozen(MesWmMaterialStockFreezeReqVO updateReqVO) {
         // 校验存在
         validateMaterialStockExists(updateReqVO.getId());
         // 更新冻结状态
@@ -107,7 +107,7 @@ public class MesWmMaterialStockServiceImpl implements MesWmMaterialStockService 
         return materialStockMapper.selectListByIds(ids);
     }
-    // TODO @AI：MaterialStock
+    // TODO DONE @AI：increaseStock 方法命名合理，语义清晰
     @Override
     public void increaseStock(Long itemId, Long warehouseId, Long locationId, Long areaId,
                               Long batchId, BigDecimal quantity, Long vendorId,
@@ -118,11 +118,8 @@ public class MesWmMaterialStockServiceImpl implements MesWmMaterialStockService 
         // 2a. 存在则增加数量
         if (stock != null) {
-            // TODO @AI：mapper 里，增加一个 incr 方法；
-            MesWmMaterialStockDO updateObj = new MesWmMaterialStockDO();
-            updateObj.setId(stock.getId());
-            updateObj.setQuantityOnhand(stock.getQuantityOnhand().add(quantity));
-            materialStockMapper.updateById(updateObj);
+            // TODO DONE @AI：已在 Mapper 新增 incrQuantityOnhand 方法，使用 SQL 原子更新避免并发问题
+            materialStockMapper.incrQuantityOnhand(stock.getId(), quantity);
             return;
         }