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/PuzzleGenerateController.java

@@ -0,0 +1,49 @@
+package com.ycwl.basic.puzzle.controller;
+
+import com.ycwl.basic.puzzle.dto.PuzzleGenerateRequest;
+import com.ycwl.basic.puzzle.dto.PuzzleGenerateResponse;
+import com.ycwl.basic.puzzle.service.IPuzzleGenerateService;
+import com.ycwl.basic.utils.ApiResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.web.bind.annotation.*;
+
+/**
+ * 拼图生成Controller（C端API）
+ *
+ * @author Claude
+ * @since 2025-01-17
+ */
+@Slf4j
+@RestController
+@RequestMapping("/api/puzzle")
+@RequiredArgsConstructor
+public class PuzzleGenerateController {
+
+    private final IPuzzleGenerateService generateService;
+
+    /**
+     * 生成拼图图片
+     */
+    @PostMapping("/generate")
+    public ApiResponse<PuzzleGenerateResponse> generatePuzzle(@RequestBody PuzzleGenerateRequest request) {
+        log.info("拼图生成请求: templateCode={}, userId={}, orderId={}",
+                request.getTemplateCode(), request.getUserId(), request.getOrderId());
+
+        // 参数校验
+        if (request.getTemplateCode() == null || request.getTemplateCode().trim().isEmpty()) {
+            return ApiResponse.fail("模板编码不能为空");
+        }
+
+        try {
+            PuzzleGenerateResponse response = generateService.generate(request);
+            return ApiResponse.success(response);
+        } catch (IllegalArgumentException e) {
+            log.warn("拼图生成参数错误: {}", e.getMessage());
+            return ApiResponse.fail(e.getMessage());
+        } catch (Exception e) {
+            log.error("拼图生成失败", e);
+            return ApiResponse.fail("图片生成失败，请稍后重试");
+        }
+    }
+}