"""语音确认服务访问会话状态的端口协议。

把 `VoiceConfirmationService` 对 `CameraSessionManager` 的强依赖解耦为
`PendingConfirmationStore` 协议；便于单元测试用 fake，并为后续拆分会话管理器
（`SurgerySessionRegistry` 等）保留切换点。
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from app.services.video.session_manager import PendingConsumableConfirmation


@runtime_checkable
class PendingConfirmationStore(Protocol):
    """语音确认链路需要的最小会话接口。"""

    def get_pending_confirmation_by_id(
        self,
        surgery_id: str,
        confirmation_id: str,
    ) -> "PendingConsumableConfirmation | None":
        ...

    def get_surgery_candidate_consumables(self, surgery_id: str) -> list[str]:
        ...

    async def record_voice_parse_failure(
        self,
        surgery_id: str,
        confirmation_id: str,
    ) -> tuple[int, int]:
        ...

    async def resolve_pending_confirmation(
        self,
        surgery_id: str,
        confirmation_id: str,
        *,
        chosen_label: str | None,
        rejected: bool,
    ) -> None:
        ...

    def record_voice_trace(
        self,
        surgery_id: str,
        *,
        asr_text: str | None,
        error: str | None,
    ) -> None:
        ...