按代码规范检查整改实体注释、Service Javadoc 与分层边界

yeg

2026-09-29 b78295e8da96c3e5e76befeef9582ce5273dbb74

 battery-business/src/main/java/com/battery/business/service/impl/TBatteryGroupTemplateServiceImpl.java

@@ -29,6 +29,13 @@
    @Autowired
    private TBatteryGroupTemplateMapper batteryGroupTemplateMapper;

    /**
     * 按主键读取电池组模板，并装配模板的字段关系与显示顺序。
     *
     * @param templateId 模板主键
     * @return 模板及其字段关系
     * @throws ServiceException 模板ID为空或模板不存在
     */
    @Override
    public TBatteryGroupTemplate selectBatteryGroupTemplateById(Long templateId)
    {
@@ -45,12 +52,27 @@
        return template;
    }

    /**
     * 返回正常状态的模板选项，供电池组选择字段模板。
     *
     * @return 模板选项列表；没有可用模板时为空列表
     */
    @Override
    public List<TBatteryGroupTemplate> selectBatteryGroupTemplateOptions()
    {
        return batteryGroupTemplateMapper.selectBatteryGroupTemplateOptions();
    }

    /**
     * 新增电池组模板，在同一事务内写入模板主记录与字段关系。
     *
     * <p>前置条件：模板名称在当前数据中唯一，字段不能为空且不能重复，字段须启用，
     * 排序数量与字段数量一致。字段关系整体按提交的字段与顺序写入。</p>
     *
     * @param template 模板配置，含字段主键与可选的显示顺序
     * @return 写入的模板主记录行数
     * @throws ServiceException 模板信息为空、名称重复、字段为空或重复、字段不存在或已禁用、排序不合法
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public int insertBatteryGroupTemplate(TBatteryGroupTemplate template)
@@ -62,11 +84,23 @@
            template.setUpdateBy(template.getCreateBy());
        }
        template.setCreateTime(new Date());
        // STEP 1: 写入模板主记录，字段关系依赖本次生成的主键。
        int rows = batteryGroupTemplateMapper.insertBatteryGroupTemplate(template);
        // STEP 2: 在同一事务内整体写入字段关系与显示顺序。
        replaceFields(template);
        return rows;
    }

    /**
     * 修改电池组模板，字段关系按提交内容整体替换。
     *
     * <p>前置条件：模板存在，模板名称不与其它模板重复（允许与自身同名），
     * 字段与排序的校验要求同新增。已有电池组引用的只是字段定义，模板变更不改写电池组当前字段值。</p>
     *
     * @param template 模板配置，须带模板主键
     * @return 更新的模板主记录行数
     * @throws ServiceException 模板ID为空、模板不存在、名称重复或字段与排序校验不通过
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public int updateBatteryGroupTemplate(TBatteryGroupTemplate template)
@@ -82,7 +116,9 @@
        validateTemplate(template, true);
        template.setTemplateName(trimToNull(template.getTemplateName()));
        template.setUpdateTime(new Date());
        // STEP 1: 更新模板主记录。
        int rows = batteryGroupTemplateMapper.updateBatteryGroupTemplate(template);
        // STEP 2: 字段关系整体替换：先清理旧关系再按提交顺序写入。
        replaceFields(template);
        return rows;
    }