"""采购结果只读核对适配层。

该接口只允许读取订单候选，故意不提供商品选择、提交订单或付款方法。
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Mapping, Optional


@dataclass(frozen=True)
class PurchaseReconcileQuery:
    """从本地任务与执行记录构造的核对条件。"""

    goods_id: str
    options: Mapping[str, str]
    quantity: int
    irreversible_action_at: str


@dataclass(frozen=True)
class PurchaseReconcileObservation:
    """只读核对看到的结果。"""

    match_status: str
    order_no: Optional[str] = None
    ordered_at: Optional[str] = None
    diagnostics: Mapping[str, object] = field(default_factory=dict)

    def __post_init__(self) -> None:
        if self.match_status not in {
            "matched", "not_found", "ambiguous", "unknown"
        }:
            raise ValueError("采购核对结果无效")


class PddPurchaseReconcileAdapter(ABC):
    """已进入不可逆阶段后使用的只读订单核对会话。"""

    @abstractmethod
    def read_order_match(
        self, query: PurchaseReconcileQuery
    ) -> PurchaseReconcileObservation:
        """读取并核对订单候选；不得点击下单或付款。"""

    @abstractmethod
    def close(self) -> None:
        """释放读取会话；不得在此方法中产生点击。"""