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

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

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


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

    goods_id: str
    options: Mapping[str, str]
    quantity: int
    unit_price_cent: int
    total_price_cent: int
    irreversible_action_at: str
    order_submitted_at: str
    reconcile_started_at: str


@dataclass(frozen=True)
class PurchaseOrderCandidate:
    """订单列表中一个不含个人信息的只读候选。"""

    order_no: str = ""
    goods_id: str = ""
    options: Mapping[str, str] = field(default_factory=dict)
    quantity: int = 0
    total_price_cent: int = 0
    ordered_at: str = ""
    ordered_at_raw: str = ""
    payment_status: str = ""


@dataclass(frozen=True)
class PurchaseReconcileScan:
    """一次只读扫描结果；diagnostics 只能包含计数和错误摘要。"""

    candidates: Sequence[PurchaseOrderCandidate] = field(default_factory=tuple)
    diagnostics: Mapping[str, object] = field(default_factory=dict)


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

    @abstractmethod
    def read_order_candidates(
        self, query: PurchaseReconcileQuery
    ) -> PurchaseReconcileScan:
        """只读扫描订单候选；不得提交、取消或付款。"""

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