package com.ycwl.basic.puzzle.service;

import com.ycwl.basic.puzzle.dto.PuzzleGenerateRequest;
import com.ycwl.basic.puzzle.dto.PuzzleGenerateResponse;

/**
 * 拼图图片生成服务接口
 *
 * @author Claude
 * @since 2025-01-17
 */
public interface IPuzzleGenerateService {

    /**
     * 生成拼图图片（默认同步模式）
     *
     * @param request 生成请求
     * @return 生成结果（包含图片URL等信息）
     */
    PuzzleGenerateResponse generate(PuzzleGenerateRequest request);

    /**
     * 同步生成拼图图片
     * <p>立即执行并阻塞等待结果返回</p>
     *
     * @param request 生成请求
     * @return 生成结果（包含图片URL等信息）
     */
    PuzzleGenerateResponse generateSync(PuzzleGenerateRequest request);

    /**
     * 异步生成拼图图片
     * <p>提交到队列，由固定大小的线程池异步处理，不等待结果</p>
     * <p>队列满时会降级为同步执行（CallerRunsPolicy）</p>
     *
     * @param request 生成请求
     * @return 生成记录ID（可用于后续追踪状态）
     */
    Long generateAsync(PuzzleGenerateRequest request);
}