# -*- coding: utf-8 -*-
# hub/ticket/application/ticket_application_api.py

"""Публичный application API модуля Ticket."""

from __future__ import annotations

from typing import Any, Mapping, Protocol, Sequence

from domain import TicketDocumentSnapshot, TicketTaskSnapshot


class TicketApplicationApi(Protocol):
    """Контракт orchestration-слоя между UI, state и сервисами."""

    def start(self) -> None:
        """Инициализировать application-слой Ticket."""

    def stop(self) -> None:
        """Остановить активные операции и освободить ресурсы."""

    def list_tasks(self) -> Sequence[TicketTaskSnapshot]:
        """Вернуть текущий срез задач для UI."""

    def list_active_tasks(self) -> Sequence[TicketTaskSnapshot]:
        """Вернуть активные задачи для UI."""

    def list_archived_tasks(self) -> Sequence[TicketTaskSnapshot]:
        """Вернуть архивные задачи для UI."""

    def get_task(self, task_id: int) -> TicketTaskSnapshot | None:
        """Вернуть задачу по идентификатору."""

    def handle_task_action(
        self,
        raw_action: Mapping[str, Any],
    ) -> TicketTaskSnapshot | None:
        """Обработать входящее действие от аппаратного или mock-шлюза."""

    def set_active_view(self, view_name: str) -> None:
        """Переключить активное представление Ticket."""

    def assign_specialist(
        self,
        task_id: int,
        specialist_name: str,
    ) -> TicketTaskSnapshot | None:
        """Назначить специалиста на задачу."""

    def list_specialists(self) -> Sequence[str]:
        """Вернуть список доступных специалистов."""

    def sign_report(
        self,
        task_id: int,
        report_type: str,
    ) -> TicketTaskSnapshot | None:
        """Подписать диагностический или ремонтный отчёт."""

    def sign_acceptance_report(self, task_id: int) -> TicketTaskSnapshot | None:
        """Подписать акт приёмки."""

    def archive_task(self, task_id: int) -> TicketTaskSnapshot | None:
        """Перевести задачу в архив."""

    def refuse_task(
        self,
        task_id: int,
        refusal_reason: str,
    ) -> TicketTaskSnapshot | None:
        """Перевести задачу в отказ."""

    def create_diagnostic_report(
        self,
        task_id: int,
        initial_cause: str,
        actual_cause: str,
    ) -> TicketDocumentSnapshot:
        """Создать и подписать диагностический отчёт."""

    def create_repair_report(
        self,
        task_id: int,
        work_done: str,
        used_parts: str,
        recommendations: str,
    ) -> TicketDocumentSnapshot:
        """Создать и подписать ремонтный отчёт."""

    def create_acceptance_report(
        self,
        task_id: int,
        work_description: str,
        executor_signature: str,
        customer_signature: str,
    ) -> TicketDocumentSnapshot:
        """Создать и подписать акт приёмки."""

    def list_documents(
        self,
        document_type: str | None = None,
    ) -> Sequence[TicketDocumentSnapshot]:
        """Вернуть список документов Ticket."""

    def can_advance_to_confirmation(self, task_id: int) -> bool:
        """Проверить готовность задачи к переходу в подтверждение."""

    def can_advance_to_completed(self, task_id: int) -> bool:
        """Проверить готовность задачи к переходу в выполненные."""

    def get_active_view(self) -> str:
        """Вернуть имя активного внутреннего представления Ticket."""

    def get_gateway_status(self):
        """Вернуть последний известный статус hardware gateway."""