"""JobRepository 端口接口 — Phase 8 任务 2.10."""

from __future__ import annotations

from typing import Protocol

from packages.domain.job import Job, JobStatus, JobType


class JobRepository(Protocol):
    """异步任务仓储接口。"""

    def create(self, job: Job) -> Job:
        """持久化一个新任务。"""
        ...

    def get(self, job_id: str) -> Job | None:
        """根据 ID 获取任务。"""
        ...

    def update(self, job: Job) -> Job:
        """更新任务状态。"""
        ...

    def list_by_project(
        self,
        project_id: str,
        *,
        job_type: JobType | str | None = None,
        status: JobStatus | str | None = None,
        limit: int = 50,
        offset: int = 0,
    ) -> list[Job]:
        """按项目列出任务，支持类型和状态过滤。"""
        ...

    def list_by_user(
        self,
        user_id: str,
        *,
        job_type: JobType | str | None = None,
        status: JobStatus | str | None = None,
        limit: int = 50,
        offset: int = 0,
    ) -> list[Job]:
        """按创建人列出任务。"""
        ...

    def count_by_project(
        self,
        project_id: str,
        *,
        status: JobStatus | str | None = None,
    ) -> int:
        """按项目统计任务数量。"""
        ...

    def find_active_by_source(
        self,
        source_id: str,
        job_type: JobType | str,
    ) -> Job | None:
        """查找关联同一业务实体的活跃任务（pending/running）。"""
        ...