【代码评审】IoT：OTA 的实现

YunaiV
1 parent 08ff69d5
Showing 15 changed files with 73 additions and 59 deletions
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/IotOtaFirmwareUpdateReqVO.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/IotOtaFirmwareDO.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/plugin/IotPluginInstanceMapper.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
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/service/ota/IotOtaUpgradeRecordService.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/service/ota/IotOtaUpgradeRecordServiceImpl.java
yudao-module-iot/yudao-module-iot-biz/src/main/java/cn/iocoder/yudao/module/iot/service/ota/IotOtaUpgradeTaskServiceImpl.java
yudao-module-iot/yudao-module-iot-biz/src/main/resources/mapper/ota/IotOtaUpgradeRecordMapper.xml
@@ -27,6 +27,7 @@ public class IotOtaFirmwareCreateReqVO {
     private String productId;
     @Schema(description = "签名方式", example = "MD5")
+    // TODO @li：是不是必传哈
     private String signMethod;
     @Schema(description = "固件文件 URL", requiredMode = REQUIRED, example = "https://www.iocoder.cn/yudao-firmware.zip")
@@ -7,7 +7,7 @@ import lombok.Data;
 import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
-@Schema(description = "管理后台 - OTA固件更新 Request VO")
+@Schema(description = "管理后台 - OTA 固件更新 Request VO")
 @Data
 public class IotOtaFirmwareUpdateReqVO {
@@ -15,6 +15,7 @@ public class IotOtaFirmwareUpdateReqVO {
     @NotNull(message = "固件编号不能为空")
     private Long id;
+    // TODO @li：name 是不是可以飞必传哈
     @Schema(description = "固件名称", requiredMode = REQUIRED, example = "智能开关固件")
     @NotEmpty(message = "固件名称不能为空")
     private String name;
@@ -8,16 +8,17 @@ import lombok.Data;
 import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
 @Data
-@Schema(description = "管理后台 - OTA升级记录分页 Request VO")
+@Schema(description = "管理后台 - OTA 升级记录分页 Request VO")
 public class IotOtaUpgradeRecordPageReqVO extends PageParam {
+    // TODO @li：已经有注解，不用重复注释
     /**
      * 升级任务编号字段。
      * <p>
      * 该字段用于标识升级任务的唯一编号，不能为空。
      */
-    @NotNull(message = "升级任务编号不能为空")
     @Schema(description = "升级任务编号", requiredMode = REQUIRED, example = "1024")
+    @NotNull(message = "升级任务编号不能为空")
     private Long taskId;
     /**
@@ -14,9 +14,12 @@ import java.util.List;
 import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
 @Data
-@Schema(description = "管理后台 - OTA升级任务创建/修改 Request VO")
+@Schema(description = "管理后台 - OTA 升级任务创建/修改 Request VO")
 public class IotOtaUpgradeTaskSaveReqVO {
+    // TODO @li：已经有注解，不用重复注释
+    // TODO @li： @Schema 写在参数校验前面。先有定义；其他的，也检查下；
+
     /**
      * 任务名称
      */
-package cn.iocoder.yudao.module.iot.convert.ota;
-
-import org.mapstruct.Mapper;
-import org.mapstruct.factory.Mappers;
-
-@Mapper
-public interface IotOtaUpgradeRecordConvert {
-
-    IotOtaUpgradeRecordConvert INSTANCE = Mappers.getMapper(IotOtaUpgradeRecordConvert.class);
-
-}
@@ -46,6 +46,7 @@ public class IotOtaFirmwareDO extends BaseDO {
      *
      * 关联 {@link cn.iocoder.yudao.module.iot.dal.dataobject.product.IotProductDO#getId()}
      */
+    // TODO @li：帮我改成 Long 哈，写错了
     private String productId;
     /**
      * 产品标识
@@ -9,11 +9,7 @@ import org.apache.ibatis.annotations.Mapper;
 import java.util.List;
-/**
- * OTA固件 Mapper
- *
- * @author Shelly
- */
+// TODO @li：参考 IotOtaUpgradeRecordMapper 的写法
 @Mapper
 public interface IotOtaFirmwareMapper extends BaseMapperX<IotOtaFirmwareDO> {
@@ -13,14 +13,10 @@ import org.apache.ibatis.annotations.Select;
 import java.util.List;
 import java.util.Map;
-/**
- * OTA 升级记录 Mapper
- *
- * @author Shelly
- */
 @Mapper
 public interface IotOtaUpgradeRecordMapper extends BaseMapperX<IotOtaUpgradeRecordDO> {
+    // TODO @li：selectByFirmwareIdAndTaskIdAndDeviceId；让方法自解释
     /**
      * 根据条件查询单个OTA升级记录
      *
@@ -37,6 +33,7 @@ public interface IotOtaUpgradeRecordMapper extends BaseMapperX&lt;IotOtaUpgradeReco
                 .eqIfPresent(IotOtaUpgradeRecordDO::getDeviceId, deviceId));
     }
+    // TODO @li：这个是不是 groupby status 就 ok 拉？
     /**
      * 根据任务ID和设备名称查询OTA升级记录的状态统计信息。
      * 该函数通过SQL查询统计不同状态（0到5）的记录数量，并返回一个包含统计结果的Map列表。
@@ -75,19 +72,23 @@ public interface IotOtaUpgradeRecordMapper extends BaseMapperX&lt;IotOtaUpgradeReco
             "where firmware_id = #{firmwareId}")
     List<Map<String, Object>> selectOtaUpgradeRecordStatistics(Long firmwareId);
+    // TODO @li：这里的注释，可以去掉哈
     /**
      * 根据分页查询条件获取IOT OTA升级记录的分页结果
      *
      * @param pageReqVO 分页查询请求参数，包含设备名称、任务ID等查询条件
      * @return 返回分页查询结果，包含符合条件的IOT OTA升级记录列表
      */
+    // TODO @li：selectPage 就 ok 拉。
     default PageResult<IotOtaUpgradeRecordDO> selectUpgradeRecordPage(IotOtaUpgradeRecordPageReqVO pageReqVO) {
+        // TODO @li：这里的注释，可以去掉哈；然后下面的“如果”。。。也没必要注释
         // 使用LambdaQueryWrapperX构建查询条件，并根据请求参数动态添加查询条件
         return selectPage(pageReqVO, new LambdaQueryWrapperX<IotOtaUpgradeRecordDO>()
                 .likeIfPresent(IotOtaUpgradeRecordDO::getDeviceName, pageReqVO.getDeviceName()) // 如果设备名称存在，则添加模糊查询条件
                 .eqIfPresent(IotOtaUpgradeRecordDO::getTaskId, pageReqVO.getTaskId())); // 如果任务ID存在，则添加等值查询条件
     }
+    // TODO @li：这里的注释，可以去掉哈
     /**
      * 根据任务ID和状态更新升级记录的状态
      * <p>
@@ -97,6 +98,7 @@ public interface IotOtaUpgradeRecordMapper extends BaseMapperX&lt;IotOtaUpgradeReco
      * @param taskId      要更新的升级记录对应的任务ID，类型为Long
      * @param whereStatus 用于筛选升级记录的当前状态值，类型为Integer
      */
+    // TODO @li：改成 updateByTaskIdAndStatus(taskId, status, IotOtaUpgradeRecordDO) 更通用一些。
     default void updateUpgradeRecordStatusByTaskIdAndStatus(Integer setStatus, Long taskId, Integer whereStatus) {
         // 使用LambdaUpdateWrapper构建更新条件，将指定状态的记录更新为指定状态
         update(new LambdaUpdateWrapper<IotOtaUpgradeRecordDO>()
@@ -106,6 +108,7 @@ public interface IotOtaUpgradeRecordMapper extends BaseMapperX&lt;IotOtaUpgradeReco
         );
     }
+    // TODO @li：参考上面的建议，调整下这个方法
     /**
      * 根据状态查询符合条件的升级记录列表
      * <p>
@@ -120,6 +123,7 @@ public interface IotOtaUpgradeRecordMapper extends BaseMapperX&lt;IotOtaUpgradeReco
                 .eq(IotOtaUpgradeRecordDO::getStatus, state));
     }
+    // TODO @li：参考上面的建议，调整下这个方法
     /**
      * 更新升级记录状态
      * <p>
@@ -137,6 +141,7 @@ public interface IotOtaUpgradeRecordMapper extends BaseMapperX&lt;IotOtaUpgradeReco
         );
     }
+    // TODO @li：参考上面的建议，调整下这个方法
     /**
      * 根据任务ID查询升级记录列表
      * <p>
@@ -8,6 +8,7 @@ import org.apache.ibatis.annotations.Mapper;
 import java.time.LocalDateTime;
 import java.util.List;
+// TODO @li：参考 IotOtaUpgradeRecordMapper 的写法
 @Mapper
 public interface IotPluginInstanceMapper extends BaseMapperX<IotPluginInstanceDO> {
@@ -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：注释写的有点冗余，可以看看别的模块哈。= = AI 生成的注释，有的时候太啰嗦了，需要处理下的哈
 /**
  * OTA 固件管理 Service
  *
@@ -15,7 +16,7 @@ import jakarta.validation.Valid;
 public interface IotOtaFirmwareService {
     /**
-     * 创建OTA固件
+     * 创建 OTA 固件
      *
      * @param saveReqVO OTA固件保存请求对象，包含固件的相关信息
      * @return 返回新创建的固件的ID
@@ -23,14 +24,14 @@ public interface IotOtaFirmwareService {
     Long createOtaFirmware(@Valid IotOtaFirmwareCreateReqVO saveReqVO);
     /**
-     * 更新OTA固件信息
+     * 更新 OTA 固件信息
      *
      * @param updateReqVO OTA固件保存请求对象，包含需要更新的固件信息
      */
     void updateOtaFirmware(@Valid IotOtaFirmwareUpdateReqVO updateReqVO);
     /**
-     * 根据ID获取OTA固件信息
+     * 根据 ID 获取 OTA 固件信息
      *
      * @param id OTA固件的唯一标识符
      * @return 返回OTA固件的详细信息对象
@@ -38,7 +39,7 @@ public interface IotOtaFirmwareService {
     IotOtaFirmwareDO getOtaFirmware(Long id);
     /**
-     * 分页查询OTA固件信息
+     * 分页查询 OTA 固件信息
      *
      * @param pageReqVO 包含分页查询条件的请求对象
      * @return 返回分页查询结果，包含固件信息列表和分页信息
@@ -46,7 +47,7 @@ public interface IotOtaFirmwareService {
     PageResult<IotOtaFirmwareDO> getOtaFirmwarePage(@Valid IotOtaFirmwarePageReqVO pageReqVO);
     /**
-     * 验证物联网OTA固件是否存在
+     * 验证物联网 OTA 固件是否存在
      *
      * @param id 固件的唯一标识符
      *           该方法用于检查系统中是否存在与给定ID关联的物联网OTA固件信息
@@ -39,13 +39,14 @@ public class IotOtaFirmwareServiceImpl implements IotOtaFirmwareService {
     public Long createOtaFirmware(IotOtaFirmwareCreateReqVO saveReqVO) {
         // 1. 校验固件产品 + 版本号不能重复
         validateProductAndVersionDuplicate(saveReqVO.getProductId(), saveReqVO.getVersion());
+
         // 2.1.转化数据格式，准备存储到数据库中
         IotOtaFirmwareDO firmware = BeanUtils.toBean(saveReqVO, IotOtaFirmwareDO.class);
         // 2.2.查询ProductKey
+        // TODO @li：productService.getProduct(Convert.toLong(firmware.getProductId())) 放到 1. 后面，先做参考校验。逻辑两段：1）先参数校验；2）构建对象 + 存储
         IotProductDO product = productService.getProduct(Convert.toLong(firmware.getProductId()));
         firmware.setProductKey(Objects.requireNonNull(product).getProductKey());
         // TODO @芋艿: 附件、附件签名等属性的计算
-
         otaFirmwareMapper.insert(firmware);
         return firmware.getId();
     }
@@ -79,6 +80,7 @@ public class IotOtaFirmwareServiceImpl implements IotOtaFirmwareService {
         return firmware;
     }
+    // TODO @li：注释有点冗余
     /**
      * 验证产品和版本号是否重复
      * <p>
@@ -8,6 +8,7 @@ import jakarta.validation.Valid;
 import java.util.List;
 import java.util.Map;
+// TODO @li：注释写的有点冗余，可以看看别的模块哈。= = AI 生成的注释，有的时候太啰嗦了，需要处理下的哈
 /**
  * IotOtaUpgradeRecordService 接口定义了与物联网设备OTA升级记录相关的操作。
  * 该接口提供了创建、更新、查询、统计和重试升级记录的功能。
@@ -15,7 +16,7 @@ import java.util.Map;
 public interface IotOtaUpgradeRecordService {
     /**
-     * 批量创建OTA升级记录。
+     * 批量创建 OTA 升级记录
      * 该函数用于为指定的设备列表、固件ID和升级任务ID创建OTA升级记录。
      *
      * @param deviceIds     设备ID列表，表示需要升级的设备集合。
@@ -25,7 +26,7 @@ public interface IotOtaUpgradeRecordService {
     void createOtaUpgradeRecordBatch(List<Long> deviceIds, Long firmwareId, Long upgradeTaskId);
     /**
-     * 获取OTA升级记录的数量统计。
+     * 获取 OTA 升级记录的数量统计
      *
      * @return 返回一个 Map，其中键为状态码，值为对应状态的升级记录数量
      */
@@ -39,14 +40,14 @@ public interface IotOtaUpgradeRecordService {
     Map<Integer, Long> getOtaUpgradeRecordStatistics(Long firmwareId);
     /**
-     * 重试指定的OTA升级记录。
+     * 重试指定的 OTA 升级记录
      *
      * @param id 需要重试的升级记录的ID。
      */
     void retryUpgradeRecord(Long id);
     /**
-     * 获取指定ID的OTA升级记录的详细信息。
+     * 获取指定 ID 的 OTA 升级记录的详细信息。
      *
      * @param id 需要查询的升级记录的ID。
      * @return 返回包含升级记录详细信息的响应对象。
@@ -54,7 +55,7 @@ public interface IotOtaUpgradeRecordService {
     IotOtaUpgradeRecordDO getUpgradeRecord(Long id);
     /**
-     * 分页查询OTA升级记录。
+     * 分页查询 OTA 升级记录。
      *
      * @param pageReqVO 包含分页查询条件的请求对象，必须经过验证。
      * @return 返回包含分页查询结果的响应对象。
@@ -62,7 +63,7 @@ public interface IotOtaUpgradeRecordService {
     PageResult<IotOtaUpgradeRecordDO> getUpgradeRecordPage(@Valid IotOtaUpgradeRecordPageReqVO pageReqVO);
     /**
-     * 根据任务ID取消升级记录。
+     * 根据任务 ID 取消升级记录
      * <p>
      * 该函数用于根据给定的任务ID，取消与该任务相关的升级记录。通常用于在任务执行失败或用户手动取消时，
      * 清理或标记相关的升级记录为取消状态。
@@ -71,6 +72,7 @@ public interface IotOtaUpgradeRecordService {
      */
     void cancelUpgradeRecordByTaskId(Long taskId);
+    // TODO @li：不要的方法，可以删除下哈。
     /**
      * 根据升级状态获取升级记录列表
      *
@@ -25,8 +25,8 @@ import java.util.stream.Collectors;
 import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
 import static cn.iocoder.yudao.module.iot.enums.ErrorCodeConstants.*;
-import static cn.iocoder.yudao.module.iot.enums.ota.IotOtaUpgradeRecordStatusEnum.CANCELED;
+// TODO @li：@Service、@Validated、@Slf4j，先用关键注解；2）类注释，简单写
 @Slf4j
 @Service
 @Validated
@@ -34,6 +34,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
     @Resource
     private IotOtaUpgradeRecordMapper upgradeRecordMapper;
+    // TODO @li：1）@Resource 写在 @Lazy 之前，先用关键注解；2）有必要的情况下，在写 @Lazy 注解。
     @Lazy
     @Resource
     private IotDeviceService deviceService;
@@ -46,8 +47,10 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
     @Override
     public void createOtaUpgradeRecordBatch(List<Long> deviceIds, Long firmwareId, Long upgradeTaskId) {
-        // 1.校验升级记录信息是否存在，并且已经取消的任务可以重新开始
+        // 1. 校验升级记录信息是否存在，并且已经取消的任务可以重新开始
+        // TODO @li：批量查询。。
         deviceIds.forEach(deviceId -> validateUpgradeRecordDuplicate(firmwareId, upgradeTaskId, String.valueOf(deviceId)));
+
         // 2.初始化OTA升级记录列表信息
         IotOtaUpgradeTaskDO upgradeTask = upgradeTaskService.getUpgradeTask(upgradeTaskId);
         IotOtaFirmwareDO firmware = firmwareService.getOtaFirmware(firmwareId);
@@ -70,6 +73,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
     }
+    // TODO @li：1）方法注释，简单写；2）父类写了注释，子类就不用写了。。。
     /**
      * 获取OTA升级记录的数量统计。
      * 该方法根据传入的查询条件，统计不同状态的OTA升级记录数量，并返回一个包含各状态数量的映射。
@@ -87,10 +91,10 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
         Objects.requireNonNull(upgradeRecordCountMap);
         return upgradeRecordCountMap.entrySet().stream().collect(Collectors.toMap(
                 entry -> Convert.toInt(entry.getKey()),
-                entry -> Convert.toLong(entry.getValue())
-        ));
+                entry -> Convert.toLong(entry.getValue())));
     }
+    // TODO @li：1）方法注释，简单写；2）父类写了注释，子类就不用写了。。。
     /**
      * 获取指定固件ID的OTA升级记录统计信息。
      * 该方法通过查询数据库，统计不同状态的OTA升级记录数量，并返回一个包含各状态数量的映射。
@@ -107,8 +111,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
         Objects.requireNonNull(upgradeRecordStatisticsMap);
         return upgradeRecordStatisticsMap.entrySet().stream().collect(Collectors.toMap(
                 entry -> Convert.toInt(entry.getKey()),
-                entry -> Convert.toLong(entry.getValue())
-        ));
+                entry -> Convert.toLong(entry.getValue())));
     }
     @Override
@@ -118,7 +121,8 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
         // 1.2.校验升级记录是否可以重新升级
         validateUpgradeRecordCanRetry(upgradeRecord);
-        // 2.将一些数据重置，这样定时任务轮询就可以重启任务
+        // 2. 将一些数据重置，这样定时任务轮询就可以重启任务
+        // TODO @li：更新的时候，wherestatus；
         upgradeRecordMapper.updateById(new IotOtaUpgradeRecordDO()
                 .setId(upgradeRecord.getId()).setProgress(0)
                 .setStatus(IotOtaUpgradeRecordStatusEnum.PENDING.getStatus()));
@@ -136,9 +140,9 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
     @Override
     public void cancelUpgradeRecordByTaskId(Long taskId) {
-        // 暂定只有待推送的升级记录可以取消
+        // 暂定只有待推送的升级记录可以取消 TODO @芋艿：可以看看阿里云，哪些可以取消
         upgradeRecordMapper.updateUpgradeRecordStatusByTaskIdAndStatus(
-                CANCELED.getStatus(), taskId,
+                IotOtaUpgradeRecordStatusEnum.CANCELED.getStatus(), taskId,
                 IotOtaUpgradeRecordStatusEnum.PENDING.getStatus());
     }
@@ -175,6 +179,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
         return upgradeRecord;
     }
+    // TODO @li：注释有点冗余
     /**
      * 校验固件升级记录是否重复。
      * <p>
@@ -189,13 +194,17 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
         // 根据条件查询升级记录
         IotOtaUpgradeRecordDO upgradeRecord = upgradeRecordMapper.selectByConditions(firmwareId, taskId, deviceId);
         // 如果查询到升级记录且状态不是已取消，则抛出异常
+        // TODO @li：if return，减少括号层级；
+        // TODO @li：ObjUtil.notEquals，尽量不用 ！取否逻辑；
         if (upgradeRecord != null) {
-            if (!CANCELED.getStatus().equals(upgradeRecord.getStatus())) {
+            if (!IotOtaUpgradeRecordStatusEnum.CANCELED.getStatus().equals(upgradeRecord.getStatus())) {
+                // TODO @li：提示的时候，需要把 deviceName 给提示出来，不然用户不知道哪个重复啦。
                 throw exception(OTA_UPGRADE_RECORD_DUPLICATE);
             }
         }
     }
+    // TODO @li：注释有点冗余
     /**
      * 验证升级记录是否可以重试。
      * <p>
@@ -205,6 +214,7 @@ public class IotOtaUpgradeRecordServiceImpl implements IotOtaUpgradeRecordServic
      * @param upgradeRecord 需要验证的升级记录对象，类型为 IotOtaUpgradeRecordDO
      * @throws cn.iocoder.yudao.framework.common.exception.ServiceException，则抛出 OTA_UPGRADE_RECORD_CANNOT_RETRY 异常
      */
+    // TODO @li：这种一次性的方法（不复用的），其实一步一定要抽成小方法；
     private void validateUpgradeRecordCanRetry(IotOtaUpgradeRecordDO upgradeRecord) {
         // 检查升级记录的状态是否为 PENDING、PUSHED 或 UPGRADING
         if (ObjectUtils.equalsAny(upgradeRecord.getStatus(),
@@ -27,6 +27,7 @@ import java.util.stream.Collectors;
 import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
 import static cn.iocoder.yudao.module.iot.enums.ErrorCodeConstants.*;
+// TODO @li：完善注释、注解顺序
 @Slf4j
 @Service
 @Validated
@@ -54,9 +55,11 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
         IotOtaFirmwareDO firmware = firmwareService.validateFirmwareExists(createReqVO.getFirmwareId());
         // 1.3 补全设备范围信息，并且校验是否又设备可以升级，如果没有设备可以升级，则报错
         validateScopeAndDevice(createReqVO.getScope(), createReqVO.getDeviceIds(), firmware.getProductId());
+
         // 2. 保存 OTA 升级任务信息到数据库
         IotOtaUpgradeTaskDO upgradeTask = initOtaUpgradeTask(createReqVO, firmware.getProductId());
         upgradeTaskMapper.insert(upgradeTask);
+
         // 3. 生成设备升级记录信息并存储，等待定时任务轮询
         upgradeRecordService.createOtaUpgradeRecordBatch(upgradeTask.getDeviceIds(), firmware.getId(), upgradeTask.getId());
         return upgradeTask.getId();
@@ -68,15 +71,16 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
         // 1.1 校验升级任务是否存在
         IotOtaUpgradeTaskDO upgradeTask = validateUpgradeTaskExists(id);
         // 1.2 校验升级任务是否可以取消
-        // 检查升级任务的状态是否为进行中，只有此状态下的任务才允许取消
+        // TODO @li：ObjUtil notequals
         if (!Objects.equals(upgradeTask.getStatus(), IotOtaUpgradeTaskStatusEnum.IN_PROGRESS.getStatus())) {
-            // 只有进行中的任务才可以取消
             throw exception(OTA_UPGRADE_TASK_CANNOT_CANCEL);
         }
+
         // 2. 更新 OTA 升级任务状态为已取消
         upgradeTaskMapper.updateById(IotOtaUpgradeTaskDO.builder()
                 .id(id).status(IotOtaUpgradeTaskStatusEnum.CANCELED.getStatus())
                 .build());
+
         // 3. 更新 OTA 升级记录状态为已取消
         upgradeRecordService.cancelUpgradeRecordByTaskId(id);
     }
@@ -98,11 +102,10 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
     @Override
     public void updateUpgradeTaskStatus(Long id, Integer status) {
-        upgradeTaskMapper.updateById(IotOtaUpgradeTaskDO.builder()
-                .id(id).status(status)
-                .build());
+        upgradeTaskMapper.updateById(IotOtaUpgradeTaskDO.builder().id(id).status(status).build());
     }
+    // TODO @li：注释有点冗余
     /**
      * 校验固件升级任务是否重复
      * <p>
@@ -123,6 +126,7 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
         }
     }
+    // TODO @li：注释有点冗余
     /**
      * 验证升级任务的范围和设备列表的有效性。
      * <p>
@@ -135,6 +139,7 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
      * @throws cn.iocoder.yudao.framework.common.exception.ServiceException，抛出相应的异常
      */
     private void validateScopeAndDevice(Integer scope, List<Long> deviceIds, String productId) {
+        // TODO @li：if return
         // 验证范围为“选择设备”时，设备列表不能为空
         if (Objects.equals(scope, IotOtaUpgradeTaskScopeEnum.SELECT.getScope())) {
             if (CollUtil.isEmpty(deviceIds)) {
@@ -149,6 +154,7 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
         }
     }
+    // TODO @li：注释有点冗余
     /**
      * 验证升级任务是否存在
      * <p>
@@ -167,6 +173,7 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
         return upgradeTask;
     }
+    // TODO @li：注释有点冗余
     /**
      * 初始化升级任务
      * <p>
@@ -177,6 +184,7 @@ public class IotOtaUpgradeTaskServiceImpl implements IotOtaUpgradeTaskService {
      * @param createReqVO 升级任务保存请求对象，包含创建升级任务所需的信息
      * @return 返回初始化后的升级任务对象
      */
+    // TODO @li：一次性的方法，不用特别抽小方法
     private IotOtaUpgradeTaskDO initOtaUpgradeTask(IotOtaUpgradeTaskSaveReqVO createReqVO, String productId) {
         // 将请求参数转换为升级任务对象
         IotOtaUpgradeTaskDO upgradeTask = BeanUtils.toBean(createReqVO, IotOtaUpgradeTaskDO.class);
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE mapper
-        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
-        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
-<mapper namespace="cn.iocoder.yudao.module.iot.dal.mysql.ota.IotOtaUpgradeRecordMapper">
-
-</mapper>
 \ No newline at end of file