feat(puzzle): 添加拼图素材版本缓存优化重复生成

- 新增 puzzleSourceVersionCache 缓存用于记录拼图素材版本
- 实现 isPuzzleSourceChanged 方法判断素材是否变化
- 添加 markPuzzleSourceVersion 方法标记当前素材版本
- 实现 invalidatePuzzleSourceVersion 方法清除指定人脸缓存
- 在人脸关系变更时自动清除相关拼图素材版本缓存
- 重构 AppPuzzleController 使用 PuzzleRepository 替代直接访问 Mapper
- 添加生成记录缓存机制，包括按人脸ID和记录ID的缓存
- 实现素材版本缓存命中时复用历史记录功能
- 优化重复内容检测逻辑，添加缓存标记机制
- 在各种生成流程中添加缓存清除逻辑确保数据一致性

src/main/java/com/ycwl/basic/biz/FaceStatusManager.java

@@ -42,6 +42,13 @@ public class FaceStatusManager {
      */
     private final Cache<String, Integer> templateRenderCache;
 
+    /**
+     * 拼图素材版本缓存
+     * 键：faceId:puzzleTemplateId -> 当时的图片源数量
+     * 用于判断拼图模板的素材是否发生变化，避免重复生成
+     */
+    private final Cache<String, Integer> puzzleSourceVersionCache;
+
     @Autowired
     private TaskMapper taskMapper;
 
@@ -61,6 +68,11 @@ public class FaceStatusManager {
                 .expireAfterWrite(DEFAULT_EXPIRE_SECONDS, TimeUnit.SECONDS)
                 .maximumSize(10000)
                 .build();
+
+        this.puzzleSourceVersionCache = Caffeine.newBuilder()
+                .expireAfterWrite(DEFAULT_EXPIRE_SECONDS, TimeUnit.SECONDS)
+                .maximumSize(10000)
+                .build();
     }
 
     // ==================== 切片状态相关方法 ====================
@@ -293,4 +305,80 @@ public class FaceStatusManager {
             log.debug("批量删除模板渲染状态缓存: faceId={}, count={}", faceId, count);
         }
     }
+
+    // ==================== 拼图素材版本相关方法 ====================
+
+    /**
+     * 标记拼图素材版本（记录当前的图片源数量）
+     * 在拼图生成成功后调用，用于后续判断素材是否变化
+     *
+     * @param faceId           人脸ID
+     * @param puzzleTemplateId 拼图模板ID（全局唯一）
+     * @param sourceCount      当前的图片源数量
+     */
+    public void markPuzzleSourceVersion(Long faceId, Long puzzleTemplateId, int sourceCount) {
+        if (faceId == null || puzzleTemplateId == null) {
+            log.warn("标记拼图素材版本参数为空: faceId={}, puzzleTemplateId={}", faceId, puzzleTemplateId);
+            return;
+        }
+        String key = faceId + ":" + puzzleTemplateId;
+        puzzleSourceVersionCache.put(key, sourceCount);
+        log.debug("标记拼图素材版本: faceId={}, puzzleTemplateId={}, sourceCount={}", faceId, puzzleTemplateId, sourceCount);
+    }
+
+    /**
+     * 判断拼图素材是否发生变化
+     * 通过比较当前的图片源数量与缓存中记录的数量
+     *
+     * @param faceId             人脸ID
+     * @param puzzleTemplateId   拼图模板ID（全局唯一）
+     * @param currentSourceCount 当前的图片源数量
+     * @return true=素材已变化（需要重新生成），false=素材未变化（可以跳过生成）
+     */
+    public boolean isPuzzleSourceChanged(Long faceId, Long puzzleTemplateId, int currentSourceCount) {
+        if (faceId == null || puzzleTemplateId == null) {
+            log.warn("判断拼图素材变化参数为空: faceId={}, puzzleTemplateId={}", faceId, puzzleTemplateId);
+            return true; // 参数不合法时默认认为有变化
+        }
+
+        String key = faceId + ":" + puzzleTemplateId;
+        Integer cachedCount = puzzleSourceVersionCache.getIfPresent(key);
+
+        if (cachedCount == null) {
+            // 缓存不存在，认为有变化（首次生成或缓存过期）
+            log.debug("拼图素材版本缓存不存在，需要生成: faceId={}, puzzleTemplateId={}", faceId, puzzleTemplateId);
+            return true;
+        }
+
+        boolean changed = !cachedCount.equals(currentSourceCount);
+        if (changed) {
+            log.debug("拼图素材已变化: faceId={}, puzzleTemplateId={}, cachedCount={}, currentCount={}",
+                    faceId, puzzleTemplateId, cachedCount, currentSourceCount);
+        } else {
+            log.debug("拼图素材未变化，可跳过生成: faceId={}, puzzleTemplateId={}, sourceCount={}",
+                    faceId, puzzleTemplateId, currentSourceCount);
+        }
+
+        return changed;
+    }
+
+    /**
+     * 使指定人脸的所有拼图素材版本缓存失效
+     * 当人脸的图片关联发生变化时调用（如人脸匹配后新增了关联）
+     *
+     * @param faceId 人脸ID
+     */
+    public void invalidatePuzzleSourceVersion(Long faceId) {
+        if (faceId == null) {
+            return;
+        }
+        String prefix = faceId + ":";
+        long count = puzzleSourceVersionCache.asMap().keySet().stream()
+                .filter(key -> key.startsWith(prefix))
+                .peek(puzzleSourceVersionCache::invalidate)
+                .count();
+        if (count > 0) {
+            log.debug("批量使拼图素材版本缓存失效: faceId={}, count={}", faceId, count);
+        }
+    }
 }