feat(puzzle): 实现拼图生成功能模块

- 新增拼图生成控制器 PuzzleGenerateController，支持 /api/puzzle/generate 接口
- 新增拼图模板管理控制器 PuzzleTemplateController，提供完整的 CRUD 和元素管理功能
- 定义拼图相关 DTO 类，包括模板、元素、生成请求与响应等数据传输对象
- 创建拼图相关的实体类 PuzzleTemplateEntity、PuzzleElementEntity 和 PuzzleGenerationRecordEntity
- 实现 Mapper 接口用于数据库操作，支持模板和元素的增删改查及生成记录管理
- 开发 PuzzleGenerateServiceImpl 服务，完成从模板渲染到图片上传的完整流程
- 提供 PuzzleTemplateServiceImpl 服务，实现模板及其元素的全生命周期管理
- 引入 PuzzleImageRenderer 工具类负责图像合成渲染逻辑
- 支持将生成结果上传至 OSS 并记录生成过程的日志和元数据

src/main/java/com/ycwl/basic/puzzle/controller/PuzzleTemplateController.java

@@ -0,0 +1,134 @@
+package com.ycwl.basic.puzzle.controller;
+
+import com.ycwl.basic.puzzle.dto.ElementCreateRequest;
+import com.ycwl.basic.puzzle.dto.PuzzleElementDTO;
+import com.ycwl.basic.puzzle.dto.PuzzleTemplateDTO;
+import com.ycwl.basic.puzzle.dto.TemplateCreateRequest;
+import com.ycwl.basic.puzzle.service.IPuzzleTemplateService;
+import com.ycwl.basic.utils.ApiResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+
+/**
+ * 拼图模板管理Controller（管理后台）
+ *
+ * @author Claude
+ * @since 2025-01-17
+ */
+@Slf4j
+@RestController
+@RequestMapping("/api/puzzle/admin")
+@RequiredArgsConstructor
+public class PuzzleTemplateController {
+
+    private final IPuzzleTemplateService templateService;
+
+    /**
+     * 创建模板
+     */
+    @PostMapping("/templates")
+    public ApiResponse<Long> createTemplate(@RequestBody TemplateCreateRequest request) {
+        log.info("创建模板请求: code={}, name={}", request.getCode(), request.getName());
+        Long templateId = templateService.createTemplate(request);
+        return ApiResponse.success(templateId);
+    }
+
+    /**
+     * 更新模板
+     */
+    @PutMapping("/templates/{id}")
+    public ApiResponse<Void> updateTemplate(@PathVariable Long id,
+                                            @RequestBody TemplateCreateRequest request) {
+        log.info("更新模板请求: id={}", id);
+        templateService.updateTemplate(id, request);
+        return ApiResponse.success(null);
+    }
+
+    /**
+     * 删除模板
+     */
+    @DeleteMapping("/templates/{id}")
+    public ApiResponse<Void> deleteTemplate(@PathVariable Long id) {
+        log.info("删除模板请求: id={}", id);
+        templateService.deleteTemplate(id);
+        return ApiResponse.success(null);
+    }
+
+    /**
+     * 获取模板详情
+     */
+    @GetMapping("/templates/{id}")
+    public ApiResponse<PuzzleTemplateDTO> getTemplateDetail(@PathVariable Long id) {
+        log.debug("获取模板详情: id={}", id);
+        PuzzleTemplateDTO template = templateService.getTemplateDetail(id);
+        return ApiResponse.success(template);
+    }
+
+    /**
+     * 获取模板列表
+     */
+    @GetMapping("/templates")
+    public ApiResponse<List<PuzzleTemplateDTO>> listTemplates(
+            @RequestParam(required = false) Long scenicId,
+            @RequestParam(required = false) String category,
+            @RequestParam(required = false) Integer status) {
+        log.debug("查询模板列表: scenicId={}, category={}, status={}", scenicId, category, status);
+        List<PuzzleTemplateDTO> templates = templateService.listTemplates(scenicId, category, status);
+        return ApiResponse.success(templates);
+    }
+
+    /**
+     * 为模板添加单个元素
+     */
+    @PostMapping("/elements")
+    public ApiResponse<Long> addElement(@RequestBody ElementCreateRequest request) {
+        log.info("添加元素请求: templateId={}, elementKey={}", request.getTemplateId(), request.getElementKey());
+        Long elementId = templateService.addElement(request);
+        return ApiResponse.success(elementId);
+    }
+
+    /**
+     * 为模板批量添加元素
+     */
+    @PostMapping("/templates/{templateId}/elements")
+    public ApiResponse<Void> batchAddElements(@PathVariable Long templateId,
+                                              @RequestBody List<ElementCreateRequest> elements) {
+        log.info("批量添加元素请求: templateId={}, count={}", templateId, elements.size());
+        templateService.batchAddElements(templateId, elements);
+        return ApiResponse.success(null);
+    }
+
+    /**
+     * 更新元素
+     */
+    @PutMapping("/elements/{id}")
+    public ApiResponse<Void> updateElement(@PathVariable Long id,
+                                           @RequestBody ElementCreateRequest request) {
+        log.info("更新元素请求: id={}", id);
+        templateService.updateElement(id, request);
+        return ApiResponse.success(null);
+    }
+
+    /**
+     * 删除元素
+     */
+    @DeleteMapping("/elements/{id}")
+    public ApiResponse<Void> deleteElement(@PathVariable Long id) {
+        log.info("删除元素请求: id={}", id);
+        templateService.deleteElement(id);
+        return ApiResponse.success(null);
+    }
+
+    /**
+     * 获取元素详情
+     */
+    @GetMapping("/elements/{id}")
+    public ApiResponse<PuzzleElementDTO> getElementDetail(@PathVariable Long id) {
+        log.debug("获取元素详情: id={}", id);
+        PuzzleElementDTO element = templateService.getElementDetail(id);
+        return ApiResponse.success(element);
+    }
+}