✨ feat(mes): 添加装箱单及装箱明细的 VO 和 Mapper 注释

为装箱单及装箱明细相关的 VO 和 Mapper 类添加了详细的注释，提升代码可读性和维护性。同时，修正了部分字段类型以确保一致性。

✨ feat(mes): 添加装箱单及装箱明细的 VO 和 Mapper 注释
为装箱单及装箱明细相关的 VO 和 Mapper 类添加了详细的注释，提升代码可读性和维护性。同时，修正了部分字段类型以确保一致性。
YunaiV
1 parent ff508c50
Showing 13 changed files with 147 additions and 97 deletions
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/MesWmPackageController.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/MesWmPackageLineController.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/vo/MesWmPackagePageReqVO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/vo/MesWmPackageRespVO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/vo/MesWmPackageSaveReqVO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/vo/line/MesWmPackageLinePageReqVO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/vo/line/MesWmPackageLineRespVO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/controller/admin/wm/packages/vo/line/MesWmPackageLineSaveReqVO.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/mysql/wm/packages/MesWmPackageLineMapper.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/dal/mysql/wm/packages/MesWmPackageMapper.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/enums/ErrorCodeConstants.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/packages/MesWmPackageLineServiceImpl.java
yudao-module-mes/src/main/java/cn/iocoder/yudao/module/mes/service/wm/packages/MesWmPackageServiceImpl.java
@@ -32,6 +32,10 @@ import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
 import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.convertSet;
 import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.convertSetByFlatMap;
+// TODO @AI：检查下 java 类，是不是 author 没加。
+/**
+ * MES 装箱单 Controller
+ */
 @Tag(name = "管理后台 - MES 装箱单")
 @RestController
 @RequestMapping("/mes/wm/package")
@@ -32,89 +32,97 @@ import java.util.Map;
 import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
 import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.convertSet;
+// TODO @AI：检查下，是不是代码缩进有问题
+/**
+ * MES 装箱明细 Controller
+ */
 @Tag(name = "管理后台 - MES 装箱明细")
 @RestController
 @RequestMapping("/mes/wm/package-line")
 @Validated
 public class MesWmPackageLineController {
-    @Resource
-    private MesWmPackageLineService packageLineService;
-    @Resource
-    private MesMdItemService itemService;
-    @Resource
-    private MesMdUnitMeasureService unitMeasureService;
-    @Resource
-    private MesProWorkOrderService workOrderService;
+        @Resource
+        private MesWmPackageLineService packageLineService;
+        @Resource
+        private MesMdItemService itemService;
+        @Resource
+        private MesMdUnitMeasureService unitMeasureService;
+        @Resource
+        private MesProWorkOrderService workOrderService;
-    @PostMapping("/create")
-    @Operation(summary = "创建装箱明细")
-    @PreAuthorize("@ss.hasPermission('mes:wm-package:create')")
-    public CommonResult<Long> createPackageLine(@Valid @RequestBody MesWmPackageLineSaveReqVO createReqVO) {
-        return success(packageLineService.createPackageLine(createReqVO));
-    }
+        @PostMapping("/create")
+        @Operation(summary = "创建装箱明细")
+        @PreAuthorize("@ss.hasPermission('mes:wm-package:create')")
+        public CommonResult<Long> createPackageLine(@Valid @RequestBody MesWmPackageLineSaveReqVO createReqVO) {
+                return success(packageLineService.createPackageLine(createReqVO));
+        }
-    @PutMapping("/update")
-    @Operation(summary = "修改装箱明细")
-    @PreAuthorize("@ss.hasPermission('mes:wm-package:update')")
-    public CommonResult<Boolean> updatePackageLine(@Valid @RequestBody MesWmPackageLineSaveReqVO updateReqVO) {
-        packageLineService.updatePackageLine(updateReqVO);
-        return success(true);
-    }
+        @PutMapping("/update")
+        @Operation(summary = "修改装箱明细")
+        @PreAuthorize("@ss.hasPermission('mes:wm-package:update')")
+        public CommonResult<Boolean> updatePackageLine(@Valid @RequestBody MesWmPackageLineSaveReqVO updateReqVO) {
+                packageLineService.updatePackageLine(updateReqVO);
+                return success(true);
+        }
-    @DeleteMapping("/delete")
-    @Operation(summary = "删除装箱明细")
-    @Parameter(name = "id", description = "编号", required = true)
-    @PreAuthorize("@ss.hasPermission('mes:wm-package:delete')")
-    public CommonResult<Boolean> deletePackageLine(@RequestParam("id") Long id) {
-        packageLineService.deletePackageLine(id);
-        return success(true);
-    }
+        @DeleteMapping("/delete")
+        @Operation(summary = "删除装箱明细")
+        @Parameter(name = "id", description = "编号", required = true)
+        @PreAuthorize("@ss.hasPermission('mes:wm-package:delete')")
+        public CommonResult<Boolean> deletePackageLine(@RequestParam("id") Long id) {
+                packageLineService.deletePackageLine(id);
+                return success(true);
+        }
-    @GetMapping("/get")
-    @Operation(summary = "获得装箱明细")
-    @Parameter(name = "id", description = "编号", required = true, example = "1024")
-    @PreAuthorize("@ss.hasPermission('mes:wm-package:query')")
-    public CommonResult<MesWmPackageLineRespVO> getPackageLine(@RequestParam("id") Long id) {
-        MesWmPackageLineDO line = packageLineService.getPackageLine(id);
-        if (line == null) {
-            return success(null);
+        @GetMapping("/get")
+        @Operation(summary = "获得装箱明细")
+        @Parameter(name = "id", description = "编号", required = true, example = "1024")
+        @PreAuthorize("@ss.hasPermission('mes:wm-package:query')")
+        public CommonResult<MesWmPackageLineRespVO> getPackageLine(@RequestParam("id") Long id) {
+                MesWmPackageLineDO line = packageLineService.getPackageLine(id);
+                if (line == null) {
+                        return success(null);
+                }
+                return success(buildRespVOList(Collections.singletonList(line)).get(0));
         }
-        return success(buildRespVOList(Collections.singletonList(line)).get(0));
-    }
-    @GetMapping("/page")
-    @Operation(summary = "获得装箱明细分页")
-    @PreAuthorize("@ss.hasPermission('mes:wm-package:query')")
-    public CommonResult<PageResult<MesWmPackageLineRespVO>> getPackageLinePage(
-            @Valid MesWmPackageLinePageReqVO pageReqVO) {
-        PageResult<MesWmPackageLineDO> pageResult = packageLineService.getPackageLinePage(pageReqVO);
-        return success(new PageResult<>(buildRespVOList(pageResult.getList()), pageResult.getTotal()));
-    }
+        @GetMapping("/page")
+        @Operation(summary = "获得装箱明细分页")
+        @PreAuthorize("@ss.hasPermission('mes:wm-package:query')")
+        public CommonResult<PageResult<MesWmPackageLineRespVO>> getPackageLinePage(
+                        @Valid MesWmPackageLinePageReqVO pageReqVO) {
+                PageResult<MesWmPackageLineDO> pageResult = packageLineService.getPackageLinePage(pageReqVO);
+                return success(new PageResult<>(buildRespVOList(pageResult.getList()), pageResult.getTotal()));
+        }
-    // ========== 私有方法 ==========
+        // ========== 私有方法 ==========
-    private List<MesWmPackageLineRespVO> buildRespVOList(List<MesWmPackageLineDO> list) {
-        if (CollUtil.isEmpty(list)) {
-            return Collections.emptyList();
+        private List<MesWmPackageLineRespVO> buildRespVOList(List<MesWmPackageLineDO> list) {
+                if (CollUtil.isEmpty(list)) {
+                        return Collections.emptyList();
+                }
+                // 批量查询物料
+                Map<Long, MesMdItemDO> itemMap = itemService
+                                .getItemMap(convertSet(list, MesWmPackageLineDO::getItemId));
+                // 批量查询计量单位
+                Map<Long, MesMdUnitMeasureDO> unitMeasureMap = unitMeasureService.getUnitMeasureMap(
+                                convertSet(itemMap.values(), MesMdItemDO::getUnitMeasureId));
+                // 批量查询工单
+                Map<Long, MesProWorkOrderDO> workOrderMap = workOrderService.getWorkOrderMap(
+                                convertSet(list, MesWmPackageLineDO::getWorkOrderId));
+                // 拼接数据
+                return BeanUtils.toBean(list, MesWmPackageLineRespVO.class, vo -> {
+                        MapUtils.findAndThen(itemMap, vo.getItemId(), item -> {
+                                vo.setItemCode(item.getCode()).setItemName(item.getName())
+                                                .setSpecification(item.getSpecification());
+                                MapUtils.findAndThen(unitMeasureMap, item.getUnitMeasureId(),
+                                                unit -> vo.setUnitMeasureName(unit.getName()));
+                        });
+                        MapUtils.findAndThen(workOrderMap, vo.getWorkOrderId(),
+                                        workOrder -> vo.setWorkOrderCode(workOrder.getCode())
+                                                        .setBatchCode(workOrder.getBatchCode()));
+                });
         }
-        // 批量查询物料
-        Map<Long, MesMdItemDO> itemMap = itemService.getItemMap(convertSet(list, MesWmPackageLineDO::getItemId));
-        // 批量查询计量单位
-        Map<Long, MesMdUnitMeasureDO> unitMeasureMap = unitMeasureService.getUnitMeasureMap(
-                convertSet(itemMap.values(), MesMdItemDO::getUnitMeasureId));
-        // 批量查询工单
-        Map<Long, MesProWorkOrderDO> workOrderMap = workOrderService.getWorkOrderMap(
-                convertSet(list, MesWmPackageLineDO::getWorkOrderId));
-        // 拼接数据
-        return BeanUtils.toBean(list, MesWmPackageLineRespVO.class, vo -> {
-            MapUtils.findAndThen(itemMap, vo.getItemId(), item -> {
-                vo.setItemCode(item.getCode()).setItemName(item.getName()).setSpecification(item.getSpecification());
-                MapUtils.findAndThen(unitMeasureMap, item.getUnitMeasureId(),
-                        unit -> vo.setUnitMeasureName(unit.getName()));});
-                MapUtils.findAndThen(workOrderMap, vo.getWorkOrderId(),
-                        workOrder -> vo.setWorkOrderCode(workOrder.getCode()).setBatchCode(workOrder.getBatchCode()));
-        });
-    }
 }
@@ -6,6 +6,9 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
+/**
+ * MES 装箱单分页 Request VO
+ */
 @Schema(description = "管理后台 - MES 装箱单分页 Request VO")
 @Data
 @EqualsAndHashCode(callSuper = true)
@@ -9,6 +9,9 @@ import lombok.experimental.Accessors;
 import java.math.BigDecimal;
 import java.time.LocalDateTime;
+/**
+ * MES 装箱单 Response VO
+ */
 @Schema(description = "管理后台 - MES 装箱单 Response VO")
 @Data
 @Accessors(chain = true)
@@ -8,6 +8,9 @@ import lombok.Data;
 import java.math.BigDecimal;
 import java.time.LocalDateTime;
+/**
+ * MES 装箱单新增/修改 Request VO
+ */
 @Schema(description = "管理后台 - MES 装箱单新增/修改 Request VO")
 @Data
 public class MesWmPackageSaveReqVO {
@@ -7,6 +7,9 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
+/**
+ * MES 装箱明细分页 Request VO
+ */
 @Schema(description = "管理后台 - MES 装箱明细分页 Request VO")
 @Data
 @EqualsAndHashCode(callSuper = true)
@@ -8,6 +8,9 @@ import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
+/**
+ * MES 装箱明细 Response VO
+ */
 @Schema(description = "管理后台 - MES 装箱明细 Response VO")
 @Data
 @Accessors(chain = true)
@@ -6,8 +6,11 @@ import jakarta.validation.constraints.NotNull;
 import lombok.Data;
 import java.math.BigDecimal;
-import java.time.LocalDate;
+import java.time.LocalDateTime;
+/**
+ * MES 装箱明细新增/修改 Request VO
+ */
 @Schema(description = "管理后台 - MES 装箱明细新增/修改 Request VO")
 @Data
 public class MesWmPackageLineSaveReqVO {
@@ -34,8 +37,9 @@ public class MesWmPackageLineSaveReqVO {
     @Schema(description = "生产工单 ID", example = "1")
     private Long workOrderId;
+    // TODO @AI：时间都是 LocalDateTIme；
     @Schema(description = "有效期")
-    private LocalDate expireDate;
+    private LocalDateTime expireDate;
     @Schema(description = "备注", example = "备注")
     private String remark;
@@ -7,8 +7,9 @@ import cn.iocoder.yudao.module.mes.controller.admin.wm.packages.vo.line.MesWmPac
 import cn.iocoder.yudao.module.mes.dal.dataobject.wm.packages.MesWmPackageLineDO;
 import org.apache.ibatis.annotations.Mapper;
-import java.util.List;
-
+/**
+ * MES 装箱明细 Mapper
+ */
 @Mapper
 public interface MesWmPackageLineMapper extends BaseMapperX<MesWmPackageLineDO> {
@@ -18,10 +19,6 @@ public interface MesWmPackageLineMapper extends BaseMapperX&lt;MesWmPackageLineDO&gt; 
                 .orderByDesc(MesWmPackageLineDO::getId));
     }
-    default List<MesWmPackageLineDO> selectListByPackageId(Long packageId) {
-        return selectList(MesWmPackageLineDO::getPackageId, packageId);
-    }
-
     default void deleteByPackageId(Long packageId) {
         delete(MesWmPackageLineDO::getPackageId, packageId);
     }
@@ -10,6 +10,9 @@ import org.apache.ibatis.annotations.Mapper;
 import java.util.List;
+/**
+ * MES 装箱单 Mapper
+ */
 @Mapper
 public interface MesWmPackageMapper extends BaseMapperX<MesWmPackageDO> {
@@ -519,6 +519,7 @@ public interface ErrorCodeConstants {
     ErrorCode WM_PACKAGE_PARENT_SELF = new ErrorCode(1_040_740_004, "不能选择自己作为父箱");
     ErrorCode WM_PACKAGE_CHILD_HAS_PARENT = new ErrorCode(1_040_740_005, "该装箱单已有父箱，不能重复添加");
     ErrorCode WM_PACKAGE_PARENT_IS_CHILD = new ErrorCode(1_040_740_006, "不能选择子箱的后代作为父箱，会形成环路");
+    ErrorCode WM_PACKAGE_CHILD_NOT_FINISHED = new ErrorCode(1_040_740_007, "子箱必须是已完成状态才能添加");
     ErrorCode WM_PACKAGE_LINE_NOT_EXISTS = new ErrorCode(1_040_740_100, "装箱明细不存在");
 }
@@ -12,11 +12,14 @@ import org.springframework.context.annotation.Lazy;
 import org.springframework.stereotype.Service;
 import org.springframework.validation.annotation.Validated;
-import java.util.List;
-
 import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
-import static cn.iocoder.yudao.module.mes.enums.ErrorCodeConstants.*;
+import static cn.iocoder.yudao.module.mes.enums.ErrorCodeConstants.WM_PACKAGE_LINE_NOT_EXISTS;
+/**
+ * MES 装箱明细 Service 实现类
+ *
+ * @author 芋道源码
+ */
 @Service
 @Validated
 public class MesWmPackageLineServiceImpl implements MesWmPackageLineService {
@@ -20,7 +20,11 @@ import java.util.Objects;
 import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
 import static cn.iocoder.yudao.module.mes.enums.ErrorCodeConstants.*;
-// TODO @AI：检查下，是不是相关的类，类注释都没加；
+/**
+ * MES 装箱单 Service 实现类
+ *
+ * @author 芋道源码
+ */
 @Service
 @Validated
 public class MesWmPackageServiceImpl implements MesWmPackageService {
@@ -67,6 +71,7 @@ public class MesWmPackageServiceImpl implements MesWmPackageService {
         packageMapper.deleteById(id);
         // 级联删除子箱
+        // TODO @AI：不能级联删除子箱；是删除的时候，如果有子箱子，不允许删除；
         List<MesWmPackageDO> children = packageMapper.selectListByParentId(id);
         if (CollUtil.isNotEmpty(children)) {
             for (MesWmPackageDO child : children) {
@@ -106,19 +111,8 @@ public class MesWmPackageServiceImpl implements MesWmPackageService {
         validatePackageExistsAndDraft(parentId);
         // 校验子箱存在
         MesWmPackageDO child = validatePackageExists(childId);
-        // 校验子箱没有父箱（parentId 为 0）
-        // TODO @AI：是不是可以类似 dept validateParentDept ；一样，写成一个统一的方法；
-        // DONE @AI：参考 validateParentDept 的实现；
-        if (ObjUtil.notEqual(child.getParentId(), MesWmPackageDO.PARENT_ID_ROOT)) {
-            throw exception(WM_PACKAGE_CHILD_HAS_PARENT);
-        }
-        // 不能将自己作为子箱
-        if (ObjUtil.equal(parentId, childId)) {
-            throw exception(WM_PACKAGE_PARENT_SELF);
-        }
-        // 递归校验：确保 parentId 不是 childId 的后代（避免形成环路）
-        validateNotChildOf(parentId, childId);
-        // TODO @AI：添加时，需要 child 是完成的；
+        // 校验添加子箱的合法性
+        validateAddChildPackage(parentId, child);
         // 设置子箱的 parentId
         packageMapper.updateById(new MesWmPackageDO().setId(childId).setParentId(parentId));
@@ -172,10 +166,31 @@ public class MesWmPackageServiceImpl implements MesWmPackageService {
     }
     /**
-     * 递归校验父箱不是子箱的后代，避免形成环路
+     * 校验添加子箱的合法性
      *
-     * 参考
-     * {@link cn.iocoder.yudao.module.system.service.dept.DeptServiceImpl#validateParentDept}
+     * @param parentId 父箱 ID
+     * @param child    子箱 DO
+     */
+    private void validateAddChildPackage(Long parentId, MesWmPackageDO child) {
+        // 1. 不能将自己作为子箱
+        if (ObjUtil.equal(parentId, child.getId())) {
+            throw exception(WM_PACKAGE_PARENT_SELF);
+        }
+        // 2. 子箱没有父箱（parentId 为 0）
+        if (ObjUtil.notEqual(child.getParentId(), MesWmPackageDO.PARENT_ID_ROOT)) {
+            throw exception(WM_PACKAGE_CHILD_HAS_PARENT);
+        }
+        // 3. 子箱必须是已完成状态
+        if (ObjUtil.notEqual(MesWmPackageStatusEnum.FINISHED.getStatus(), child.getStatus())) {
+            throw exception(WM_PACKAGE_CHILD_NOT_FINISHED);
+        }
+        // 4. 递归校验：确保 parentId 不是 childId 的后代（避免形成环路）
+        // TODO @AI：不搞独立方法，代码风格参考 validateParentDept
+        validateNotChildOf(parentId, child.getId());
+    }
+
+    /**
+     * 递归校验父箱不是子箱的后代，避免形成环路
      *
      * @param parentId 父箱 ID
      * @param childId  子箱 ID（不能是 parentId 的祖先）