feat(puzzle): 添加模板分页查询功能并优化DTO序列化

- 在PuzzleTemplateController中新增pageTemplates接口支持分页查询
- 为ElementCreateRequest和PuzzleElementDTO添加@JsonProperty注解优化JSON序列化
- 实现PuzzleTemplateServiceImpl中的pageTemplates分页逻辑
- 使用PageHelper实现分页查询并限制最大页面大小为100
- 在IPuzzleTemplateService接口中定义pageTemplates方法签名及文档说明
- 添加参数校验确保page和pageSize的有效性
- 返回PageResponse对象封装分页结果供前端使用

src/main/java/com/ycwl/basic/puzzle/service/IPuzzleTemplateService.java

@@ -1,5 +1,6 @@
 package com.ycwl.basic.puzzle.service;
 
+import com.ycwl.basic.integration.common.response.PageResponse;
 import com.ycwl.basic.puzzle.dto.ElementCreateRequest;
 import com.ycwl.basic.puzzle.dto.PuzzleElementDTO;
 import com.ycwl.basic.puzzle.dto.PuzzleTemplateDTO;
@@ -45,6 +46,19 @@ public interface IPuzzleTemplateService {
      */
     List<PuzzleTemplateDTO> listTemplates(Long scenicId, String category, Integer status);
 
+    /**
+     * 分页获取模板列表
+     *
+     * @param page     页码(从1开始)
+     * @param pageSize 每页大小
+     * @param scenicId 景区ID(可选)
+     * @param category 模板分类(可选)
+     * @param status   状态(可选): 0-禁用 1-启用
+     * @return 分页结果
+     */
+    PageResponse<PuzzleTemplateDTO> pageTemplates(Integer page, Integer pageSize,
+                                                   Long scenicId, String category, Integer status);
+
     /**
      * 为模板添加元素
      */

src/main/java/com/ycwl/basic/puzzle/service/impl/PuzzleTemplateServiceImpl.java

@@ -3,6 +3,7 @@ import cn.hutool.core.util.StrUtil;
 import com.ycwl.basic.puzzle.util.ElementConfigHelper;
 
 import cn.hutool.core.bean.BeanUtil;
+import com.ycwl.basic.integration.common.response.PageResponse;
 import com.ycwl.basic.puzzle.dto.ElementCreateRequest;
 import com.ycwl.basic.puzzle.dto.PuzzleElementDTO;
 import com.ycwl.basic.puzzle.dto.PuzzleTemplateDTO;
@@ -134,6 +135,44 @@ public class PuzzleTemplateServiceImpl implements IPuzzleTemplateService {
                 .collect(Collectors.toList());
     }
 
+    @Override
+    public PageResponse<PuzzleTemplateDTO> pageTemplates(Integer page, Integer pageSize,
+                                                          Long scenicId, String category, Integer status) {
+        log.debug("分页查询拼图模板: page={}, pageSize={}, scenicId={}, category={}, status={}",
+                page, pageSize, scenicId, category, status);
+
+        // 参数校验
+        if (page == null || page < 1) {
+            page = 1;
+        }
+        if (pageSize == null || pageSize < 1) {
+            pageSize = 10;
+        }
+        if (pageSize > 100) {
+            pageSize = 100; // 限制最大页面大小
+        }
+
+        // 使用PageHelper进行分页
+        com.github.pagehelper.Page<PuzzleTemplateEntity> pageResult =
+                com.github.pagehelper.PageHelper.startPage(page, pageSize)
+                        .doSelectPage(() -> templateMapper.list(scenicId, category, status));
+
+        // 转换为DTO
+        List<PuzzleTemplateDTO> dtoList = pageResult.getResult().stream()
+                .map(this::convertToDTO)
+                .collect(Collectors.toList());
+
+        // 构建分页响应
+        PageResponse<PuzzleTemplateDTO> response = new PageResponse<>();
+        response.setList(dtoList);
+        response.setTotal((int) pageResult.getTotal());
+        response.setPage(page);
+        response.setPageSize(pageSize);
+
+        log.debug("分页查询完成: total={}, currentSize={}", pageResult.getTotal(), dtoList.size());
+        return response;
+    }
+
     @Override
     @Transactional(rollbackFor = Exception.class)
     public Long addElement(ElementCreateRequest request) {