"""图像后端抽象接口（可插拔）。

- print(prompt, base_image, out_path, negative, extra_images)：
  以 base_image 为底图（+ extra_images 多参考图，按顺序追加）按 prompt 生成成品图。
  product 流水线用法：
    * 纯印花设计稿 → generate()
    * 平铺服装图（底图+印花）→ print(base=底图, extra=[设计稿])
    * 三图模特合成 → print(base=模特图, extra=[设计稿, 底图])（图1=模特, 图2=印花, 图3=底图）
- generate(prompt, out_path, negative)：纯文生图（无参考图），用于生成白底纯印花设计稿。
"""
from abc import ABC, abstractmethod
from typing import Optional, Sequence


class ImageBackend(ABC):
    name: str = "base"

    @abstractmethod
    def print(self, prompt: str, base_image: str, out_path: str, negative: str = "",
              extra_images: Optional[Sequence[str]] = None, size: str = "") -> str:
        """返回生成的成品图路径。实现内部应处理调用失败/超时并抛异常由调用方兜底。
        size: 显式尺寸覆盖（如 "1536x2048"）；留空则用后端配置的 size。"""
        raise NotImplementedError

    def generate(self, prompt: str, out_path: str, negative: str = "", size: str = "") -> str:
        """纯文生图（无参考图），默认退化为 print 不支持则抛异常。
        size: 显式尺寸覆盖；留空则用后端配置的 size。"""
        raise NotImplementedError(f"{self.name} 后端不支持纯文生图（generate）")