"""与服务商无关的生成能力抽象。

上层（HTTP 端点、将来的 Java 侧契约）只对着本接口编程。新增一家供应商 = 实现
本接口 + 在注册表登记，**不动上层一行**。

为什么是「submit + fetch」两个方法而不是一个 `generate`：
Java↔Python 边界一律异步（ADR-023 §4）。`submit` 立即返回厂商任务 ID，`fetch`
查进度。同步型供应商（一次长连接出图）由其适配层在内部消化这个差异，**绝不能
让它渗透到这个接口上**——否则客户端契约、等待态设计、E2E 都要分两套。
"""

from __future__ import annotations

from abc import ABC, abstractmethod

from app.domain.generation import GenerationRequest, GenerationResult, MediaKind


class GenerationProvider(ABC):
    """一家供应商的一种生成能力。"""

    @property
    @abstractmethod
    def provider_code(self) -> str:
        """与 `creation.generation_models.provider_code` 同值。

        Java 侧按任务行冻结的 `provider_code_snapshot` 找适配器，**不按当前目录**
        ——目录可能被改指向或禁用，而在途任务必须仍由当初提交它的适配器轮询。
        """

    @property
    @abstractmethod
    def media_kind(self) -> MediaKind:
        """本适配器负责的产物类型。"""

    @abstractmethod
    def submit(self, request: GenerationRequest) -> str:
        """提交任务，返回厂商任务 ID。

        **不得阻塞等待生成完成。** 调用方会在上游产生任何计费动作之前把返回的 ID
        落库——那是超时后唯一能判断「是否已提交」的依据。

        :raises app.providers.volcengine.client.ArkError: 或其他供应商的等价异常，
            均携带已分类的 `Failure`。
        """

    @abstractmethod
    def fetch(self, provider_request_id: str) -> GenerationResult:
        """查询任务当前状态。"""