soloforge 1.0.0 → 1.1.0

package/templates/scaffolds/spring-boot/PageResponse.java.hbs

@@ -3,27 +3,50 @@ package {{basePackage}}.dto;
 import java.util.List;
 
 /**
- * 分页响应封装
+ * {{ModuleName}} 分页响应封装 — 提供统一的分页数据结构。
+ * @param <T> 分页数据类型
  */
 public class {{ModuleName}}PageResponse<T> {
 
+    /** 当前页数据列表 */
     private List<T> records;
+
+    /** 总记录数 */
     private long total;
+
+    /** 当前页码，从 1 开始 */
     private int page;
+
+    /** 每页数量 */
     private int size;
+
+    /** 总页数 */
     private int totalPages;
 
+    /**
+     * 构造分页响应。
+     * @param records 当前页数据列表
+     * @param total   总记录数
+     * @param page    当前页码
+     * @param size    每页数量
+     */
     public {{ModuleName}}PageResponse(List<T> records, long total, int page, int size) {
         this.records = records;
         this.total = total;
         this.page = page;
         this.size = size;
+        // 向上取整计算总页数
         this.totalPages = (int) Math.ceil((double) total / size);
     }
 
+    /** 获取当前页数据列表 */
     public List<T> getRecords() { return records; }
+    /** 获取总记录数 */
     public long getTotal() { return total; }
+    /** 获取当前页码 */
     public int getPage() { return page; }
+    /** 获取每页数量 */
     public int getSize() { return size; }
+    /** 获取总页数 */
     public int getTotalPages() { return totalPages; }
 }

package/templates/scaffolds/spring-boot/Service.java.hbs

@@ -3,10 +3,42 @@ package {{basePackage}}.service;
 import {{basePackage}}.dto.{{ModuleName}}DTO;
 import java.util.List;
 
+/**
+ * {{ModuleName}} 服务接口 — 定义 {{moduleName}} 模块的业务操作契约。
+ */
 public interface {{ModuleName}}Service {
+
+    /**
+     * 查询所有 {{moduleName}}。
+     * @return {{moduleName}} DTO 列表
+     */
     List<{{ModuleName}}DTO> list();
+
+    /**
+     * 根据 ID 查询 {{moduleName}}。
+     * @param id 主键标识
+     * @return {{moduleName}} DTO，不存在时返回 null
+     */
     {{ModuleName}}DTO getById(Long id);
+
+    /**
+     * 创建 {{moduleName}}。
+     * @param dto 创建请求数据
+     * @return 创建后的 {{moduleName}} DTO
+     */
     {{ModuleName}}DTO create({{ModuleName}}DTO dto);
+
+    /**
+     * 更新 {{moduleName}}。
+     * @param id  主键标识
+     * @param dto 更新请求数据
+     * @return 更新后的 {{moduleName}} DTO
+     */
     {{ModuleName}}DTO update(Long id, {{ModuleName}}DTO dto);
+
+    /**
+     * 删除 {{moduleName}}。
+     * @param id 主键标识
+     */
     void delete(Long id);
 }

package/templates/scaffolds/spring-boot/ServiceImpl.java.hbs

@@ -8,6 +8,9 @@ import org.springframework.stereotype.Service;
 
 import java.util.List;
 
+/**
+ * {{ModuleName}} 服务实现 — 提供 {{moduleName}} 模块业务逻辑的具体实现。
+ */
 @Service
 public class {{ModuleName}}ServiceImpl implements {{ModuleName}}Service {
 
@@ -17,32 +20,47 @@ public class {{ModuleName}}ServiceImpl implements {{ModuleName}}Service {
         this.{{moduleName}}Mapper = {{moduleName}}Mapper;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public List<{{ModuleName}}DTO> list() {
-        // TODO: 实现列表查询
+        // TODO: 实现列表查询，将 Entity 转换为 DTO 返回
         return List.of();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public {{ModuleName}}DTO getById(Long id) {
-        // TODO: 实现单条查询
+        // TODO: 实现单条查询，ID 不存在时需抛出业务异常
         return null;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public {{ModuleName}}DTO create({{ModuleName}}DTO dto) {
-        // TODO: 实现创建
+        // TODO: 实现创建逻辑，DTO 转 Entity 后持久化
         return dto;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public {{ModuleName}}DTO update(Long id, {{ModuleName}}DTO dto) {
-        // TODO: 实现更新
+        // TODO: 实现更新逻辑，先查询存在性再更新
         return dto;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void delete(Long id) {
-        // TODO: 实现删除
+        // TODO: 实现删除逻辑，考虑是否使用软删除
     }
 }

package/templates/scaffolds/spring-boot/ServiceTest.java.hbs

@@ -8,15 +8,21 @@ import org.mockito.junit.jupiter.MockitoExtension;
 
 import static org.junit.jupiter.api.Assertions.*;
 
+/**
+ * {{ModuleName}} 服务单元测试 — 验证 {{moduleName}} 业务逻辑的正确性。
+ */
 @ExtendWith(MockitoExtension.class)
 class {{ModuleName}}ServiceTest {
 
     @InjectMocks
     private Object {{moduleName}}Service;
 
+    /**
+     * 验证 Spring 上下文加载正常。
+     */
     @Test
     void contextLoads() {
-        // TODO: 编写单元测试
+        // TODO: 编写单元测试，覆盖正常流程和边界场景
         assertNotNull({{moduleName}}Service);
     }
 }