"""Persistence contract for the temporary TaskCOP task bridge.

The legacy situation-overview frontend distinguishes the global task list from
"my tasks". Task data is shared, while ``created_by`` is retained for the
per-user filter and as an audit field.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from datetime import datetime
from typing import Any

TASK_STATUS_ANALYSIS_COMPLETED = 25


class TaskCopTaskStore(ABC):
    @abstractmethod
    async def create_task(self, data: dict[str, Any]) -> dict[str, Any]:
        """Persist one task and return its legacy-compatible record."""
        raise NotImplementedError

    @abstractmethod
    async def upsert_task(self, data: dict[str, Any]) -> tuple[dict[str, Any], bool]:
        """Create or completely replace one task identified by ``data['id']``.

        Returns the legacy-compatible record and whether a new row was created.
        """
        raise NotImplementedError

    @abstractmethod
    async def list_tasks(
        self,
        *,
        created_by: str | None = None,
        keyword: str = "",
        task_direction: str | None = None,
        task_statuses: set[int] | None = None,
        start_time: datetime | None = None,
        end_time: datetime | None = None,
        page_num: int = 1,
        page_size: int = 10,
    ) -> tuple[int, list[dict[str, Any]]]:
        """Return ``(total, records)`` using TaskCOP list semantics."""
        raise NotImplementedError

    @abstractmethod
    async def get_task(self, task_id: str) -> dict[str, Any] | None:
        """Return a legacy-compatible task record, or ``None`` when absent."""
        raise NotImplementedError

    @abstractmethod
    async def delete_task(self, task_id: str) -> bool:
        """Delete one task and return whether it existed."""
        raise NotImplementedError

    @abstractmethod
    async def mark_analysis_completed(self, task_id: str) -> bool:
        """Move an existing task to the completed-analysis status (25)."""
        raise NotImplementedError