"""
JobStore - 任务作业类的配置存储抽象

包含 Job（任务定义/调度模板）的配置管理，以及 JobTask 的调度相关操作。
来自 schema/jobs.py
"""

from abc import ABC, abstractmethod
from typing import Optional, List
from datetime import datetime
from turbo_agent_core.schema.jobs import Job, JobTask, TaskSpec


class JobStore(ABC):
    """
    任务作业类的配置存储抽象类。
    
    所有方法均支持 **kwargs 参数，用于实现侧传入鉴权信息。
    """

    # ========== Job CRUD（任务定义/调度模板）==========
    @abstractmethod
    async def get_job(self, job_id: str, **kwargs) -> Optional[Job]:
        """
        根据 ID 获取 Job（任务定义）。

        Args:
            job_id: Job 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id, project_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_job(self, job: Job, **kwargs) -> str:
        """
        保存 Job，返回 Job ID。

        Args:
            job: Job 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_jobs(
        self, 
        project_id: Optional[str] = None,
        skip: int = 0, 
        limit: int = 20, 
        **kwargs
    ) -> List[Job]:
        """
        列出 Jobs。

        Args:
            project_id: 可选的项目ID过滤
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_job(self, job_id: str, **kwargs) -> bool:
        """
        删除 Job。

        Args:
            job_id: Job 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== JobTask 调度相关操作 ==========
    @abstractmethod
    async def get_job_task(self, task_id: str, **kwargs) -> Optional[JobTask]:
        """
        根据 ID 获取 JobTask（任务执行实例）。

        Args:
            task_id: Task 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_job_task(self, task: JobTask, **kwargs) -> str:
        """
        保存 JobTask，返回 Task ID。

        Args:
            task: JobTask 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_job_tasks(
        self, 
        job_id: Optional[str] = None, 
        status: Optional[str] = None, 
        skip: int = 0, 
        limit: int = 20, 
        **kwargs
    ) -> List[JobTask]:
        """
        列出 JobTasks。

        Args:
            job_id: 可选的 Job ID 过滤
            status: 可选的状态过滤
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def find_job_task(
        self, 
        job_id: str, 
        expected_start_time: datetime, 
        **kwargs
    ) -> Optional[JobTask]:
        """
        根据 Job ID 和预期开始时间查找 JobTask。

        Args:
            job_id: Job 唯一标识
            expected_start_time: 预期开始时间
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_due_job_tasks(self, limit: int = 50, **kwargs) -> List[JobTask]:
        """
        列出已到期需要执行的任务（供调度器使用）。

        Args:
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def update_job_task_status(
        self, 
        task_id: str, 
        status: str, 
        **kwargs
    ) -> bool:
        """
        更新 JobTask 的状态。

        Args:
            task_id: Task 唯一标识
            status: 新状态
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== TaskSpec（任务规格/运行时请求）==========
    @abstractmethod
    async def save_task_spec(self, spec: TaskSpec, **kwargs) -> str:
        """
        保存 TaskSpec（临时存储在队列中），返回 Spec ID。

        Args:
            spec: TaskSpec 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def get_task_spec(self, spec_id: str, **kwargs) -> Optional[TaskSpec]:
        """
        根据 ID 获取 TaskSpec。

        Args:
            spec_id: Spec 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_task_spec(self, spec_id: str, **kwargs) -> bool:
        """
        删除 TaskSpec。

        Args:
            spec_id: Spec 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass
