【代码评审】IoT：固件管理

YunaiV
1 parent ebfe35c7
Showing 29 changed files with 128 additions and 82 deletions
yudao-module-iot/yudao-module-iot-api/src/main/java/cn/iocoder/yudao/module/iot/enums/ErrorCodeConstants.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/IotOtaFirmwareController.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/IotOtaUpgradeRecordController.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/IotOtaUpgradeTaskController.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/vo/firmware/IotOtaFirmwareCommonReqVO.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/vo/firmware/IotOtaFirmwareCreateReqVO.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/vo/firmware/IotOtaFirmwarePageReqVO.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/vo/firmware/IotOtaFirmwareRespVO.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/vo/upgrade/record/IotOtaUpgradeRecordPageReqVO.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/controller/admin/ota/vo/upgrade/task/IotOtaUpgradeTaskSaveReqVO.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/convert/ota/IotOtaUpgradeRecordConvert.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/dal/dataobject/ota/IotOtaUpgradeTaskDO.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/dal/mysql/device/IotDeviceMapper.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/dal/mysql/ota/IotOtaFirmwareMapper.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/dal/mysql/ota/IotOtaUpgradeRecordMapper.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/dal/mysql/ota/IotOtaUpgradeTaskMapper.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/job/ota/IotOtaUpgradeRecordJob.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/job/ota/IotOtaUpgradeTaskJob.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/service/ota/IotOtaFirmwareService.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/service/ota/IotOtaFirmwareServiceImpl.java
@@ -52,14 +52,17 @@ public interface ErrorCodeConstants {
     // ========== 插件实例 1-050-007-000 ==========
     // ========== 固件相关 1-050-008-000 ==========
+
     ErrorCode OTA_FIRMWARE_NOT_EXISTS = new ErrorCode(1_050_008_000, "固件信息不存在");
     ErrorCode OTA_FIRMWARE_PRODUCT_VERSION_DUPLICATE = new ErrorCode(1_050_008_001, "产品版本号重复");
+    // TODO @li：1_050_008_100，这样有点间隔？
     ErrorCode OTA_UPGRADE_TASK_NOT_EXISTS = new ErrorCode(1_050_008_002, "升级任务不存在");
     ErrorCode OTA_UPGRADE_TASK_NAME_DUPLICATE = new ErrorCode(1_050_008_003, "升级任务名称重复");
     ErrorCode OTA_UPGRADE_TASK_PARAMS_INVALID = new ErrorCode(1_050_008_004, "升级任务参数无效");
     ErrorCode OTA_UPGRADE_TASK_CANNOT_CANCEL = new ErrorCode(1_050_008_005, "升级任务不能取消");
+    // TODO @li：1_050_008_200
     ErrorCode OTA_UPGRADE_RECORD_NOT_EXISTS = new ErrorCode(1_050_008_006, "升级记录不存在");
     ErrorCode OTA_UPGRADE_RECORD_DUPLICATE = new ErrorCode(1_050_008_007, "升级记录重复");
     ErrorCode OTA_UPGRADE_RECORD_CANNOT_RETRY = new ErrorCode(1_050_008_008, "升级记录不能重试");
@@ -21,7 +21,7 @@ import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
 @Validated
 @RestController
-@Tag(name = "管理后台 - IoT OTA固件")
+@Tag(name = "管理后台 - IoT OTA 固件")
 @RequestMapping("/iot/ota-firmware")
 public class IotOtaFirmwareController {
@@ -29,14 +29,14 @@ public class IotOtaFirmwareController {
     private IotOtaFirmwareService otaFirmwareService;
     @PostMapping("/create")
-    @Operation(summary = "创建OTA固件")
+    @Operation(summary = "创建 OTA 固件")
     @PreAuthorize("@ss.hasPermission('iot:ota-firmware:create')")
     public CommonResult<Long> createOtaFirmware(@Valid @RequestBody IotOtaFirmwareCreateReqVO createReqVO) {
         return success(otaFirmwareService.createOtaFirmware(createReqVO));
     }
     @PutMapping("/update")
-    @Operation(summary = "更新OTA固件")
+    @Operation(summary = "更新 OTA 固件")
     @PreAuthorize("@ss.hasPermission('iot:ota-firmware:update')")
     public CommonResult<Boolean> updateOtaFirmware(@Valid @RequestBody IotOtaFirmwareUpdateReqVO updateReqVO) {
         otaFirmwareService.updateOtaFirmware(updateReqVO);
@@ -44,7 +44,7 @@ public class IotOtaFirmwareController {
     }
     @GetMapping("/get")
-    @Operation(summary = "获得OTA固件")
+    @Operation(summary = "获得 OTA 固件")
     @PreAuthorize("@ss.hasPermission('iot:ota-firmware:query')")
     public CommonResult<IotOtaFirmwareRespVO> getOtaFirmware(@RequestParam("id") Long id) {
         IotOtaFirmwareDO otaFirmware = otaFirmwareService.getOtaFirmware(id);
@@ -52,7 +52,7 @@ public class IotOtaFirmwareController {
     }
     @GetMapping("/page")
-    @Operation(summary = "获得OTA固件分页")
+    @Operation(summary = "获得 OTA 固件分页")
     @PreAuthorize("@ss.hasPermission('iot:ota-firmware:query')")
     public CommonResult<PageResult<IotOtaFirmwareRespVO>> getOtaFirmwarePage(@Valid IotOtaFirmwarePageReqVO pageReqVO) {
         PageResult<IotOtaFirmwareDO> pageResult = otaFirmwareService.getOtaFirmwarePage(pageReqVO);
@@ -22,21 +22,13 @@ import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
 @Validated
 @RestController
-@Tag(name = "管理后台 - OTA升级记录")
+@Tag(name = "管理后台 - OTA 升级记录")
 @RequestMapping("/iot/ota-upgrade-record")
 public class IotOtaUpgradeRecordController {
     @Resource
     private IotOtaUpgradeRecordService upgradeRecordService;
-    @GetMapping("/get-count")
-    @Operation(summary = "获得升级记录 分页 tab count")
-    @PreAuthorize("@ss.hasPermission('iot:ota-upgrade-record:query')")
-    public CommonResult<Map<Integer, Long>> getOtaUpgradeRecordCount(
-            @Valid IotOtaUpgradeRecordPageReqVO pageReqVO) {
-        return success(upgradeRecordService.getOtaUpgradeRecordCount(pageReqVO));
-    }
-
     @GetMapping("/get-statistics")
     @Operation(summary = "固件升级设备统计")
     @PreAuthorize("@ss.hasPermission('iot:ota-upgrade-record:query')")
@@ -46,6 +38,14 @@ public class IotOtaUpgradeRecordController {
         return success(upgradeRecordService.getOtaUpgradeRecordStatistics(firmwareId));
     }
+    @GetMapping("/get-count")
+    @Operation(summary = "获得升级记录分页 tab 数量")
+    @PreAuthorize("@ss.hasPermission('iot:ota-upgrade-record:query')")
+    public CommonResult<Map<Integer, Long>> getOtaUpgradeRecordCount(
+            @Valid IotOtaUpgradeRecordPageReqVO pageReqVO) {
+        return success(upgradeRecordService.getOtaUpgradeRecordCount(pageReqVO));
+    }
+
     @GetMapping("/page")
     @Operation(summary = "获得升级记录分页")
     @PreAuthorize("@ss.hasPermission('iot:ota-upgrade-record:query')")
@@ -64,6 +64,7 @@ public class IotOtaUpgradeRecordController {
         return success(BeanUtils.toBean(upgradeRecord, IotOtaUpgradeRecordRespVO.class));
     }
+    // TODO @li：使用 Putmapping
     @PostMapping("/retry")
     @Operation(summary = "重试升级记录")
     @PreAuthorize("@ss.hasPermission('iot:ota-upgrade-record:retry')")
@@ -44,6 +44,7 @@ public class IotOtaUpgradeTaskController {
         return success(true);
     }
+    // TODO @li：get 接口，不是 @RequestBody 哈
     @GetMapping("/page")
     @Operation(summary = "获得升级任务分页")
     @PreAuthorize(value = "@ss.hasPermission('iot:ota-upgrade-task:query')")
@@ -6,6 +6,7 @@ import lombok.Data;
 import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
+// TODO @li：因为 create 和 update 可以公用的字段比较少，建议不用 IotOtaFirmwareCommonReqVO
 @Data
 @Schema(description = "管理后台 - OTA固件信息 Request VO")
 public class IotOtaFirmwareCommonReqVO {
@@ -7,10 +7,13 @@ import lombok.Data;
 import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
-@Data
+// TODO @li：中英文之间，有个空格。中文写作习惯哈。
 @Schema(description = "管理后台 - OTA固件创建 Request VO")
+@Data
 public class IotOtaFirmwareCreateReqVO extends IotOtaFirmwareCommonReqVO {
+    // TODO @li：因为有了注解，注释可以不写哈
+    // TODO @li：swagger 注解，写在 validator 注解之前，保持项目统一哈。
     /**
      * 版本号
      */
@@ -27,6 +30,7 @@ public class IotOtaFirmwareCreateReqVO extends IotOtaFirmwareCommonReqVO {
     @Schema(description = "产品编号", requiredMode = REQUIRED, example = "1024")
     private String productId;
+    // TODO @li：productId 即可，而 productKey 通过 productId 查询
     /**
      * 产品标识
      * <p>
@@ -44,6 +48,8 @@ public class IotOtaFirmwareCreateReqVO extends IotOtaFirmwareCommonReqVO {
     @Schema(description = "签名方式", example = "MD5")
     private String signMethod;
+    // TODO @li：fileSign、fileSize 通过后端下载文件，计算出来。对前端屏蔽这个细节。
+
     /**
      * 固件文件签名
      */
@@ -5,7 +5,7 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 @Data
-@Schema(description = "管理后台 - OTA固件分页 Request VO")
+@Schema(description = "管理后台 - OTA 固件分页 Request VO")
 public class IotOtaFirmwarePageReqVO extends PageParam {
     /**
@@ -10,7 +10,7 @@ import lombok.Data;
 import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
 @Data
-@Schema(description = "管理后台 - OTA固件 Response VO")
+@Schema(description = "管理后台 - OTA 固件 Response VO")
 public class IotOtaFirmwareRespVO implements VO {
     /**
@@ -11,6 +11,7 @@ import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
 @Schema(description = "管理后台 - OTA升级记录分页 Request VO")
 public class IotOtaUpgradeRecordPageReqVO extends PageParam {
+    // TODO @li：使用 IotOtaUpgradeRecordStatusEnum 枚举哈
     /**
      * 待处理状态
      */
@@ -57,6 +57,7 @@ public class IotOtaUpgradeTaskSaveReqVO {
     @Schema(description = "选中的设备编号数组", requiredMode = REQUIRED, example = "[1,2,3,4]")
     private List<Long> deviceIds;
+    // TODO @li：通过 deviceIds 查询 deviceNames，前端不传递哈
     /**
      * 选中的设备名字数组
      * <p>
@@ -5,7 +5,7 @@ import cn.iocoder.yudao.module.iot.dal.dataobject.device.IotDeviceDO;
 import cn.iocoder.yudao.module.iot.dal.dataobject.ota.IotOtaFirmwareDO;
 import cn.iocoder.yudao.module.iot.dal.dataobject.ota.IotOtaUpgradeTaskDO;
 import cn.iocoder.yudao.module.iot.enums.ota.IotOtaUpgradeRecordStatusEnum;
-import cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record.IotOtaUpgradeRecordCreateReqBO;
+import cn.iocoder.yudao.module.iot.service.ota.bo.IotOtaUpgradeRecordCreateReqBO;
 import org.mapstruct.Mapper;
 import org.mapstruct.factory.Mappers;
@@ -16,6 +16,7 @@ public interface IotOtaUpgradeRecordConvert {
     IotOtaUpgradeRecordConvert INSTANCE = Mappers.getMapper(IotOtaUpgradeRecordConvert.class);
+    // TODO @li：一般情况下，这种 convert 直接写 service 就好啦。不用特别写一个哈
     default List<IotOtaUpgradeRecordCreateReqBO> convertBOList(IotOtaUpgradeTaskDO upgradeTask, IotOtaFirmwareDO firmware, List<IotDeviceDO> deviceList) {
         return deviceList.stream().map(device -> {
             IotOtaUpgradeRecordCreateReqBO createReqBO = new IotOtaUpgradeRecordCreateReqBO();
@@ -70,6 +70,8 @@ public class IotOtaUpgradeTaskDO extends BaseDO {
      */
     @TableField(typeHandler = JacksonTypeHandler.class)
     private List<Long> deviceIds;
+
+    // TODO @li：这个通过查询，不用冗余
     /**
      * 选中的设备名字数组
      * <p>
@@ -66,8 +66,7 @@ public interface IotDeviceMapper extends BaseMapperX&lt;IotDeviceDO&gt; {
     default Long selectCountByGroupId(Long groupId) {
         return selectCount(new LambdaQueryWrapperX<IotDeviceDO>()
-                .apply("FIND_IN_SET(" + groupId + ",group_ids) > 0")
-                .orderByDesc(IotDeviceDO::getId));
+                .apply("FIND_IN_SET(" + groupId + ",group_ids) > 0"));
     }
 }
 \ No newline at end of file
@@ -9,6 +9,7 @@ import org.apache.ibatis.annotations.Mapper;
 import java.util.List;
+// TODO @li：这里的注释，可以去掉哈，多了点点
 /**
  * IotOtaFirmwareMapper 接口用于操作 IotOtaFirmwareDO 实体类对应的数据库表。
  * 该接口继承自 BaseMapperX，提供了基本的 CRUD 操作，并扩展了特定查询方法。
@@ -24,9 +25,8 @@ public interface IotOtaFirmwareMapper extends BaseMapperX&lt;IotOtaFirmwareDO&gt; {
      * @return 返回符合条件的固件信息列表。
      */
     default List<IotOtaFirmwareDO> selectByProductIdAndVersion(String productId, String version) {
-        return selectList(new LambdaQueryWrapperX<IotOtaFirmwareDO>()
-                .eq(IotOtaFirmwareDO::getProductId, productId)
-                .eq(IotOtaFirmwareDO::getVersion, version));
+        return selectList(IotOtaFirmwareDO::getProductId, productId,
+                IotOtaFirmwareDO::getVersion, version);
     }
     /**
@@ -36,11 +36,10 @@ public interface IotOtaFirmwareMapper extends BaseMapperX&lt;IotOtaFirmwareDO&gt; {
      * @return 返回分页查询结果，包含符合条件的固件信息列表。
      */
     default PageResult<IotOtaFirmwareDO> selectPage(IotOtaFirmwarePageReqVO pageReqVO) {
-        return selectPage(pageReqVO,
-                new LambdaQueryWrapperX<IotOtaFirmwareDO>()
-                        .likeIfPresent(IotOtaFirmwareDO::getName, pageReqVO.getName())
-                        .eqIfPresent(IotOtaFirmwareDO::getProductId, pageReqVO.getProductId())
-                        .orderByDesc(IotOtaFirmwareDO::getCreateTime));
+        return selectPage(pageReqVO, new LambdaQueryWrapperX<IotOtaFirmwareDO>()
+                .likeIfPresent(IotOtaFirmwareDO::getName, pageReqVO.getName())
+                .eqIfPresent(IotOtaFirmwareDO::getProductId, pageReqVO.getProductId())
+                .orderByDesc(IotOtaFirmwareDO::getCreateTime));
     }
 }
@@ -12,8 +12,9 @@ import org.apache.ibatis.annotations.Param;
 import java.util.List;
+// TODO @li：这里的注释，可以去掉哈，多了点点
 /**
- * OTA升级记录 Mapper 接口
+ * OTA 升级记录 Mapper 接口
  */
 @Mapper
 public interface IotOtaUpgradeRecordMapper extends BaseMapperX<IotOtaUpgradeRecordDO> {
@@ -78,6 +79,7 @@ public interface IotOtaUpgradeRecordMapper extends BaseMapperX&lt;IotOtaUpgradeReco
      */
     default void cancelUpgradeRecordByTaskId(Long taskId) {
         // 使用LambdaUpdateWrapper构建更新条件，将状态为“待处理”的记录更新为“已取消”
+        // TODO @li：哪些可以更新，通过 service 传递。mapper 尽量不要有逻辑
         update(new LambdaUpdateWrapper<IotOtaUpgradeRecordDO>()
                 .set(IotOtaUpgradeRecordDO::getStatus, IotOtaUpgradeRecordStatusEnum.CANCELED.getStatus())
                 .eq(IotOtaUpgradeRecordDO::getTaskId, taskId)
@@ -9,6 +9,7 @@ import org.apache.ibatis.annotations.Mapper;
 import java.util.List;
+// TODO @li：这里的注释，可以去掉哈，多了点点
 /**
  * IotOtaUpgradeTaskMapper 接口用于操作 IotOtaUpgradeTaskDO 数据库表。
  * 该接口继承自 BaseMapperX，提供了基本的数据库操作方法。
@@ -46,13 +47,11 @@ public interface IotOtaUpgradeTaskMapper extends BaseMapperX&lt;IotOtaUpgradeTaskDO
      * <p>
      * 该函数通过传入的任务状态，查询数据库中符合条件的升级任务列表。
      *
-     * @param state 任务状态，用于筛选升级任务的状态值
+     * @param status 任务状态，用于筛选升级任务的状态值
      * @return 返回符合条件的升级任务列表，列表中的每个元素为 IotOtaUpgradeTaskDO 对象
      */
-    default List<IotOtaUpgradeTaskDO> selectUpgradeTaskByState(Integer state) {
-        // 使用 LambdaQueryWrapperX 构建查询条件，筛选出状态等于指定值的升级任务
-        return selectList(new LambdaQueryWrapperX<IotOtaUpgradeTaskDO>()
-                .eq(IotOtaUpgradeTaskDO::getStatus, state));
+    default List<IotOtaUpgradeTaskDO> selectUpgradeTaskByState(Integer status) {
+        return selectList(IotOtaUpgradeTaskDO::getStatus, status);
     }
@@ -19,13 +19,14 @@ public class IotOtaUpgradeRecordJob implements JobHandler {
     @Override
     @TenantJob
     public String execute(String param) throws Exception {
-        // 1.查询待处理的升级记录
+        // 1. 查询待处理的升级记录
         List<IotOtaUpgradeRecordDO> upgradeRecords = upgradeRecordService
                 .getUpgradeRecordListByState(IotOtaUpgradeRecordStatusEnum.PENDING.getStatus());
         // TODO @芋艿 2.执行升级动作
+        // TODO @li：应该是逐条 push，逐条更新。不用批量哈
-        // 3.最终，更新升级记录状态
+        // 3. 最终，更新升级记录状态
         List<Long> ids = upgradeRecords.stream().map(IotOtaUpgradeRecordDO::getId).toList();
         upgradeRecordService.updateUpgradeRecordStatus(ids, IotOtaUpgradeRecordStatusEnum.PUSHED.getStatus());
         return "";
@@ -15,6 +15,7 @@ import org.springframework.stereotype.Component;
 import java.util.List;
+// TODO @li：也不用通过 job 去统计。可以通过 record update status 后，主动去更新 task 的状态。
 @Slf4j
 @Component
 public class IotOtaUpgradeTaskJob implements JobHandler {
@@ -7,6 +7,7 @@ import cn.iocoder.yudao.module.iot.controller.admin.ota.vo.firmware.IotOtaFirmwa
 import cn.iocoder.yudao.module.iot.dal.dataobject.ota.IotOtaFirmwareDO;
 import jakarta.validation.Valid;
+// TODO @li：类、方法注释有点冗余，可以参考别的模块哈
 /**
  * OTA固件管理服务接口
  * 提供OTA固件的创建、更新和查询等功能
@@ -29,18 +29,22 @@ public class IotOtaFirmwareServiceImpl implements IotOtaFirmwareService {
     @Override
     public Long createOtaFirmware(IotOtaFirmwareCreateReqVO saveReqVO) {
-        // 1.校验固件产品id+版本号不能重复
+        // 1. 校验固件产品 + 版本号不能重复
+        // TODO @li：需要考虑设备也存在
         validateProductAndVersionDuplicate(saveReqVO.getProductId(), saveReqVO.getVersion());
+
         // 2.转化数据格式，准备存储到数据库中
-        IotOtaFirmwareDO otaFirmware = BeanUtils.toBean(saveReqVO, IotOtaFirmwareDO.class);
-        otaFirmwareMapper.insert(otaFirmware);
-        return otaFirmware.getId();
+        IotOtaFirmwareDO firmware = BeanUtils.toBean(saveReqVO, IotOtaFirmwareDO.class);
+        otaFirmwareMapper.insert(firmware);
+        return firmware.getId();
     }
     @Override
     public void updateOtaFirmware(IotOtaFirmwareUpdateReqVO updateReqVO) {
+        // TODO @li：如果序号只有一个，直接写 1. 更好哈
         // 1.1. 校验存在
         validateFirmwareExists(updateReqVO.getId());
+
         // 2. 更新数据
         IotOtaFirmwareDO updateObj = BeanUtils.toBean(updateReqVO, IotOtaFirmwareDO.class);
         otaFirmwareMapper.updateById(updateObj);
@@ -58,11 +62,11 @@ public class IotOtaFirmwareServiceImpl implements IotOtaFirmwareService {
     @Override
     public IotOtaFirmwareDO validateFirmwareExists(Long id) {
-        IotOtaFirmwareDO otaFirmware = otaFirmwareMapper.selectById(id);
-        if (otaFirmware == null) {
+        IotOtaFirmwareDO firmware = otaFirmwareMapper.selectById(id);
+        if (firmware == null) {
             throw exception(OTA_FIRMWARE_NOT_EXISTS);
         }
-        return otaFirmware;
+        return firmware;
     }
     /**
@@ -80,6 +84,7 @@ public class IotOtaFirmwareServiceImpl implements IotOtaFirmwareService {
         // 查询数据库中是否存在具有相同产品ID和版本号的固件信息
         List<IotOtaFirmwareDO> list = otaFirmwareMapper.selectByProductIdAndVersion(productId, version);
         // 如果查询结果非空且不为null，则抛出异常，提示固件信息已存在
+        // TODO @li：使用 isNotEmpty 这种 方法，简化
         if (Objects.nonNull(list) && !list.isEmpty()) {
             throw exception(OTA_FIRMWARE_PRODUCT_VERSION_DUPLICATE);
         }
@@ -3,8 +3,8 @@ package cn.iocoder.yudao.module.iot.service.ota;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.module.iot.controller.admin.ota.vo.upgrade.record.IotOtaUpgradeRecordPageReqVO;
 import cn.iocoder.yudao.module.iot.dal.dataobject.ota.IotOtaUpgradeRecordDO;
-import cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record.IotOtaUpgradeRecordCreateReqBO;
-import cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record.IotOtaUpgradeRecordUpdateReqBO;
+import cn.iocoder.yudao.module.iot.service.ota.bo.IotOtaUpgradeRecordCreateReqBO;
+import cn.iocoder.yudao.module.iot.service.ota.bo.IotOtaUpgradeRecordUpdateReqBO;
 import jakarta.validation.Valid;
 import java.util.List;
@@ -16,18 +16,21 @@ import java.util.Map;
  */
 public interface IotOtaUpgradeRecordService {
+    // TODO @createOtaUpgradeRecordBatch 哈，需要补充方法里，缺少 Ota 关键字的
+
     /**
      * 批量创建物联网OTA升级记录
      * <p>
      * 该函数用于处理一组物联网OTA升级记录的创建请求，并将这些记录批量保存到系统中。
      *
-     * @param saveList 包含多个物联网OTA升级记录创建请求的列表，每个请求对象都经过校验（@Valid注解确保）
+     * @param createList 包含多个物联网OTA升级记录创建请求的列表，每个请求对象都经过校验（@Valid注解确保）
      *                 列表中的每个元素都是IotOtaUpgradeRecordCreateReqBO类型的对象，表示一个独立的升级记录创建请求。
      */
-    void createUpgradeRecordBatch(@Valid List<IotOtaUpgradeRecordCreateReqBO> saveList);
+    void createUpgradeRecordBatch(@Valid List<IotOtaUpgradeRecordCreateReqBO> createList);
+    // TODO @li：尽量避免写比较大的通用 update。而是根据场景提供，这样才能收敛
     /**
-     * 更新现有的OTA升级记录。
+     * 更新现有的 OTA 升级记录
      *
      * @param updateReqBO 包含更新升级记录所需信息的请求对象，必须经过验证。
      */
@@ -36,14 +39,14 @@ public interface IotOtaUpgradeRecordService {
     /**
      * 获取OTA升级记录的数量统计。
      *
-     * @return 返回一个Map，其中键为状态码，值为对应状态的升级记录数量。
+     * @return 返回一个 Map，其中键为状态码，值为对应状态的升级记录数量
      */
     Map<Integer, Long> getOtaUpgradeRecordCount(@Valid IotOtaUpgradeRecordPageReqVO pageReqVO);
     /**
-     * 获取OTA升级记录的统计信息。
+     * 获取 OTA 升级记录的统计信息。
      *
-     * @return 返回一个Map，其中键为状态码，值为对应状态的升级记录统计信息。
+     * @return 返回一个 Map，其中键为状态码，值为对应状态的升级记录统计信息
      */
     Map<Integer, Long> getOtaUpgradeRecordStatistics(Long firmwareId);
@@ -68,8 +71,7 @@ public interface IotOtaUpgradeRecordService {
      * @param pageReqVO 包含分页查询条件的请求对象，必须经过验证。
      * @return 返回包含分页查询结果的响应对象。
      */
-    PageResult<IotOtaUpgradeRecordDO> getUpgradeRecordPage(
-            @Valid IotOtaUpgradeRecordPageReqVO pageReqVO);
+    PageResult<IotOtaUpgradeRecordDO> getUpgradeRecordPage(@Valid IotOtaUpgradeRecordPageReqVO pageReqVO);
     /**
      * 根据任务ID取消升级记录。
@@ -7,8 +7,8 @@ import cn.iocoder.yudao.module.iot.controller.admin.ota.vo.upgrade.record.IotOta
 import cn.iocoder.yudao.module.iot.dal.dataobject.ota.IotOtaUpgradeRecordDO;
 import cn.iocoder.yudao.module.iot.dal.mysql.ota.IotOtaUpgradeRecordMapper;
 import cn.iocoder.yudao.module.iot.enums.ota.IotOtaUpgradeRecordStatusEnum;
-import cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record.IotOtaUpgradeRecordCreateReqBO;
-import cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record.IotOtaUpgradeRecordUpdateReqBO;
+import cn.iocoder.yudao.module.iot.service.ota.bo.IotOtaUpgradeRecordCreateReqBO;
+import cn.iocoder.yudao.module.iot.service.ota.bo.IotOtaUpgradeRecordUpdateReqBO;
 import jakarta.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
@@ -30,21 +30,22 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
     private IotOtaUpgradeRecordMapper upgradeRecordMapper;
     @Override
-    public void createUpgradeRecordBatch(List<IotOtaUpgradeRecordCreateReqBO> saveList) {
+    public void createUpgradeRecordBatch(List<IotOtaUpgradeRecordCreateReqBO> createList) {
         // 1. 批量校验参数信息
-        saveList.forEach(saveBO -> validateUpgradeRecordDuplicate(saveBO.getFirmwareId(), saveBO.getTaskId(), saveBO.getDeviceId()));
-        // 2.将数据转化成数据库存储的格式
-        List<IotOtaUpgradeRecordDO> upgradeRecords = BeanUtils.toBean(saveList, IotOtaUpgradeRecordDO.class);
-        // 3.将数据批量存储到数据库里
+        createList.forEach(saveBO -> validateUpgradeRecordDuplicate(saveBO.getFirmwareId(), saveBO.getTaskId(), saveBO.getDeviceId()));
+
+        // 2. 将数据批量存储到数据库里
+        List<IotOtaUpgradeRecordDO> upgradeRecords = BeanUtils.toBean(createList, IotOtaUpgradeRecordDO.class);
         upgradeRecordMapper.insertBatch(upgradeRecords);
     }
     @Override
     @Transactional
     public void updateUpgradeRecord(IotOtaUpgradeRecordUpdateReqBO updateReqBO) {
-        // 1.校验升级记录信息是否存在
+        // 1. 校验升级记录信息是否存在
         validateUpgradeRecordExists(updateReqBO.getId());
-        // 2.将数据转化成数据库存储的格式
+
+        // 2. 将数据转化成数据库存储的格式
         IotOtaUpgradeRecordDO updateRecord = BeanUtils.toBean(updateReqBO, IotOtaUpgradeRecordDO.class);
         upgradeRecordMapper.updateById(updateRecord);
         // TODO @芋艿: 更新升级记录触发的其他Action
@@ -61,6 +62,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
     @Transactional
     public Map<Integer, Long> getOtaUpgradeRecordCount(IotOtaUpgradeRecordPageReqVO pageReqVO) {
         // 分别查询不同状态的OTA升级记录数量
+        // TODO @li: 通过 groupby 统计下；
         Long pending = upgradeRecordMapper.getOtaUpgradeRecordCount(pageReqVO.getTaskId(), pageReqVO.getDeviceName(), IotOtaUpgradeRecordStatusEnum.PENDING.getStatus());
         Long pushed = upgradeRecordMapper.getOtaUpgradeRecordCount(pageReqVO.getTaskId(), pageReqVO.getDeviceName(), IotOtaUpgradeRecordStatusEnum.PUSHED.getStatus());
         Long upgrading = upgradeRecordMapper.getOtaUpgradeRecordCount(pageReqVO.getTaskId(), pageReqVO.getDeviceName(), IotOtaUpgradeRecordStatusEnum.UPGRADING.getStatus());
@@ -68,6 +70,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
         Long failure = upgradeRecordMapper.getOtaUpgradeRecordCount(pageReqVO.getTaskId(), pageReqVO.getDeviceName(), IotOtaUpgradeRecordStatusEnum.FAILURE.getStatus());
         Long canceled = upgradeRecordMapper.getOtaUpgradeRecordCount(pageReqVO.getTaskId(), pageReqVO.getDeviceName(), IotOtaUpgradeRecordStatusEnum.CANCELED.getStatus());
         // 将各状态的数量封装到Map中返回
+        // TODO @li：使用 MapUtil，因为 Map.of 是 jdk9 才有，后续不好同步到 master 的 jdk8；
         return Map.of(IotOtaUpgradeRecordPageReqVO.PENDING, pending,
                 IotOtaUpgradeRecordPageReqVO.PUSHED, pushed,
                 IotOtaUpgradeRecordPageReqVO.UPGRADING, upgrading,
@@ -87,6 +90,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
     @Transactional
     public Map<Integer, Long> getOtaUpgradeRecordStatistics(Long firmwareId) {
         // 查询并统计不同状态的OTA升级记录数量
+        // TODO @li: 通过 groupby 统计下；
         Long pending = upgradeRecordMapper.getOtaUpgradeRecordStatistics(firmwareId, IotOtaUpgradeRecordStatusEnum.PENDING.getStatus());
         Long pushed = upgradeRecordMapper.getOtaUpgradeRecordStatistics(firmwareId, IotOtaUpgradeRecordStatusEnum.PUSHED.getStatus());
         Long upgrading = upgradeRecordMapper.getOtaUpgradeRecordStatistics(firmwareId, IotOtaUpgradeRecordStatusEnum.UPGRADING.getStatus());
@@ -108,6 +112,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
         IotOtaUpgradeRecordDO upgradeRecord = validateUpgradeRecordExists(id);
         // 1.2.校验升级记录是否可以重新升级
         validateUpgradeRecordCanRetry(upgradeRecord);
+
         // 2.将一些数据重置，这样定时任务轮询就可以重启任务
         upgradeRecordMapper.updateById(new IotOtaUpgradeRecordDO()
                 .setId(upgradeRecord.getId()).setProgress(0)
@@ -8,6 +8,7 @@ import jakarta.validation.Valid;
 import java.util.List;
+// TODO @li：类、方法注释有点冗余，可以参考别的模块哈
 /**
  * IoT OTA升级任务服务接口
  * 提供OTA升级任务的创建、取消和查询功能
@@ -13,7 +13,7 @@ import cn.iocoder.yudao.module.iot.dal.mysql.ota.IotOtaUpgradeTaskMapper;
 import cn.iocoder.yudao.module.iot.enums.ota.IotOtaUpgradeTaskScopeEnum;
 import cn.iocoder.yudao.module.iot.enums.ota.IotOtaUpgradeTaskStatusEnum;
 import cn.iocoder.yudao.module.iot.service.device.IotDeviceService;
-import cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record.IotOtaUpgradeRecordCreateReqBO;
+import cn.iocoder.yudao.module.iot.service.ota.bo.IotOtaUpgradeRecordCreateReqBO;
 import jakarta.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.context.annotation.Lazy;
@@ -34,31 +34,37 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
     @Resource
     private IotOtaUpgradeTaskMapper upgradeTaskMapper;
-    @Lazy
+
     @Resource
-    private IotDeviceService deviceService;
     @Lazy
+    private IotDeviceService deviceService;
     @Resource
-    private IotOtaFirmwareService firmwareService;
     @Lazy
+    private IotOtaFirmwareService firmwareService;
     @Resource
+    @Lazy
     private IotOtaUpgradeRecordService upgradeRecordService;
     @Override
     @Transactional(rollbackFor = Exception.class)
     public Long createUpgradeTask(IotOtaUpgradeTaskSaveReqVO createReqVO) {
-        // 1.1.校验同一固件的升级任务名称不重复
+        // 1.1 校验同一固件的升级任务名称不重复
         validateFirmwareTaskDuplicate(createReqVO.getFirmwareId(), createReqVO.getName());
-        // 1.2.校验固件信息是否存在
+        // 1.2 校验固件信息是否存在
         IotOtaFirmwareDO firmware = firmwareService.validateFirmwareExists(createReqVO.getFirmwareId());
-        // 1.3.校验升级范围=2(指定设备时),deviceIds deviceNames不为空并且长度相等
+        // 1.3 校验升级范围=2(指定设备时),deviceIds deviceNames不为空并且长度相等
+        // TODO @li：deviceNames 应该后端查询
         validateScopeAndDevice(createReqVO.getScope(), createReqVO.getDeviceIds(), createReqVO.getDeviceNames());
-        // 2.初始化OTA升级任务信息
+        // TODO @li：如果全部范围，但是没设备可以升级，需要报错
+
+        // 2. 保存 OTA 升级任务信息到数据库
         IotOtaUpgradeTaskDO upgradeTask = initUpgradeTask(createReqVO, firmware.getProductId());
-        // 3.保存OTA升级任务信息到数据库
         upgradeTaskMapper.insert(upgradeTask);
-        // 4.生成设备升级记录信息并存储，等待定时任务轮询
-        List<IotOtaUpgradeRecordCreateReqBO> upgradeRecordList = initUpgradeRecordList(upgradeTask, firmware, createReqVO.getDeviceIds());
+
+        // 3. 生成设备升级记录信息并存储，等待定时任务轮询
+        List<IotOtaUpgradeRecordCreateReqBO> upgradeRecordList = initUpgradeRecordList(
+                upgradeTask, firmware, createReqVO.getDeviceIds());
+        // TODO @li：只需要传递 deviceIds、firewareId、剩余的 upgradeRecordService 里面自己处理；这样，后续 record 加字段，都不需要透传太多；解耦
         upgradeRecordService.createUpgradeRecordBatch(upgradeRecordList);
         // TODO @芋艿: 创建任务触发的其他Action
         return upgradeTask.getId();
@@ -67,15 +73,17 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
     @Override
     @Transactional(rollbackFor = Exception.class)
     public void cancelUpgradeTask(Long id) {
-        // 1.1.校验升级任务是否存在
+        // 1.1 校验升级任务是否存在
         IotOtaUpgradeTaskDO upgradeTask = validateUpgradeTaskExists(id);
-        // 1.2.校验升级任务是否可以取消
+        // 1.2 校验升级任务是否可以取消
+        // TODO @li：这种一次性的，可以不考虑拆分方法
         validateUpgradeTaskCanCancel(upgradeTask);
-        // 2.更新OTA升级任务状态为已取消
+
+        // 2. 更新 OTA 升级任务状态为已取消
         upgradeTaskMapper.updateById(IotOtaUpgradeTaskDO.builder()
                 .id(id).status(IotOtaUpgradeTaskStatusEnum.CANCELED.getStatus())
                 .build());
-        // 3.更新OTA升级记录状态为已取消
+        // 3. 更新 OTA 升级记录状态为已取消
         upgradeRecordService.cancelUpgradeRecordByTaskId(id);
         // TODO @芋艿: 取消任务触发的其他Action
     }
@@ -176,6 +184,7 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
         }
     }
+    // TODO @li：一次性，不复用的，可以直接写在对应的逻辑里；
     /**
      * 初始化升级任务
      * <p>
@@ -189,6 +198,7 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
     private IotOtaUpgradeTaskDO initUpgradeTask(IotOtaUpgradeTaskSaveReqVO createReqVO, String productId) {
         // 配置各项参数
         IotOtaUpgradeTaskDO upgradeTask = IotOtaUpgradeTaskDO.builder()
+                // TODO @li：不用每个占一行。最好相同类型的，放在一行里；
                 .name(createReqVO.getName())
                 .description(createReqVO.getDescription())
                 .firmwareId(createReqVO.getFirmwareId())
@@ -219,7 +229,10 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
      * @param deviceIds   设备ID列表，仅在升级任务范围为选择设备时使用
      * @return 升级记录请求对象列表，包含每个设备的升级记录信息
      */
-    private List<IotOtaUpgradeRecordCreateReqBO> initUpgradeRecordList(IotOtaUpgradeTaskDO upgradeTask, IotOtaFirmwareDO firmware, List<Long> deviceIds) {
+    private List<IotOtaUpgradeRecordCreateReqBO> initUpgradeRecordList(
+            IotOtaUpgradeTaskDO upgradeTask, IotOtaFirmwareDO firmware, List<Long> deviceIds) {
+        // TODO @li：需要考虑，如果创建多个任务，相互之间不能重复；
+        // 1）指定设备的时候，进行校验；2）如果是全部，则过滤其它已经发起的；；；；；另外，需要排除掉 cancel 的哈。因为 cancal 之后，还可以发起
         // 根据升级任务的范围确定设备列表
         List<IotDeviceDO> deviceList;
         if (Objects.equals(upgradeTask.getScope(), IotOtaUpgradeTaskScopeEnum.SELECT.getScope())) {
-package cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record;
+package cn.iocoder.yudao.module.iot.service.ota.bo;
 import cn.iocoder.yudao.module.iot.dal.dataobject.device.IotDeviceDO;
 import cn.iocoder.yudao.module.iot.dal.dataobject.ota.IotOtaFirmwareDO;
-package cn.iocoder.yudao.module.iot.service.ota.bo.upgrade.record;
+package cn.iocoder.yudao.module.iot.service.ota.bo;
 import cn.iocoder.yudao.framework.common.validation.InEnum;
 import cn.iocoder.yudao.module.iot.enums.ota.IotOtaUpgradeRecordStatusEnum;
@@ -11,6 +11,7 @@ import java.time.LocalDateTime;
 import static cn.iocoder.yudao.framework.common.util.date.DateUtils.FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND;
+// TODO @li：这个类，貌似没用？
 @Data
 public class IotOtaUpgradeRecordUpdateReqBO {
-package cn.iocoder.yudao.module.iot.service.ota.bo;
 \ No newline at end of file
-package cn.iocoder.yudao.module.iot.service.ota.bo.upgrade;
 \ No newline at end of file
@@ -4,6 +4,7 @@
         "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
 <mapper namespace="cn.iocoder.yudao.module.iot.dal.mysql.ota.IotOtaUpgradeRecordMapper">
+    <!-- TODO @li：看看是不是可以通过 mybatis plus 写哈，更好适配多 db -->
     <select id="getOtaUpgradeRecordCount" resultType="java.lang.Long">
         select count(*)
         from iot_ota_upgrade_record
@@ -12,6 +13,7 @@
           and status = #{status}
     </select>
+    <!-- TODO @li：看看是不是可以通过 mybatis plus 写哈，更好适配多 db -->
     <select id="getOtaUpgradeRecordStatistics" resultType="java.lang.Long">
         select count(*)
         from iot_ota_upgrade_record