"""示例适配器数据契约与基类。

复制本目录为 ``<domain>_adapter/``，按 ADAPTER.md 实现各档位。
业务逻辑只依赖 ``base`` 里的接口，不感知 mock / sim_rpa / real_* 差异。
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional


@dataclass
class ExampleItem:
    """单条业务输入（示例）。"""

    id: str
    label: str


@dataclass
class ExampleResult:
    """批量操作结果（以批为单位返回）。"""

    ok: bool
    serial_no: Optional[str]
    error_msg: Optional[str]
    artifacts: Dict[str, Any] = field(default_factory=dict)


class AdapterBase:
    """四档 adapter 统一接口；子类实现 ``do_batch``。"""

    name = "base"

    def do_batch(self, target: str, items: List[ExampleItem]) -> ExampleResult:
        raise NotImplementedError