package org.xyzh.api.crontab;

import org.xyzh.common.core.domain.ResultDomain;
import org.xyzh.common.core.page.PageParam;
import org.xyzh.common.dto.crontab.CreateTaskRequest;
import org.xyzh.common.dto.crontab.TbCrontabTask;
import org.xyzh.common.dto.crontab.TbCrontabLog;
import org.xyzh.common.vo.CrontabTaskVO;
import org.xyzh.common.vo.CrontabLogVO;

/**
 * @description 定时任务服务接口
 * @filename CrontabService.java
 * @author yslg
 * @copyright xyzh
 * @since 2025-10-25
 */
public interface CrontabService {

    // ----------------定时任务管理--------------------------------

    /**
     * @description 创建定时任务
     * @param task 任务对象
     * @return ResultDomain<TbCrontabTask> 创建结果
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> createTask(TbCrontabTask task);

    /**
     * @description 创建定时任务并绑定邮件接收人
     * @param request 创建任务请求（包含任务信息、是否使用默认接收人、额外接收人列表）
     * @return ResultDomain<TbCrontabTask> 创建结果
     * @author yslg
     * @since 2025-11-18
     */
    ResultDomain<TbCrontabTask> createTaskWithRecipients(CreateTaskRequest request);

    /**
     * @description 更新定时任务
     * @param task 任务对象
     * @return ResultDomain<TbCrontabTask> 更新结果
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> updateTask(TbCrontabTask task);

    /**
     * @description 更新定时任务并更新邮件接收人
     * @param request 更新任务请求（包含任务信息、是否使用默认接收人、额外接收人列表）
     * @return ResultDomain<TbCrontabTask> 更新结果
     * @author yslg
     * @since 2025-11-18
     */
    ResultDomain<TbCrontabTask> updateTaskWithRecipients(CreateTaskRequest request);

    /**
     * @description 删除定时任务
     * @param taskId 任务ID
     * @return ResultDomain<TbCrontabTask> 删除结果
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> deleteTask(String taskId);

    /**
     * @description 根据ID查询任务
     * @param taskId 任务ID
     * @return ResultDomain<TbCrontabTask> 任务信息
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> getTaskById(String taskId);

    /**
     * @description 根据过滤条件查询任务列表
     * @param filter 过滤条件
     * @return ResultDomain<TbCrontabTask> 任务列表
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> getTaskList(TbCrontabTask filter);

    /**
     * @description 分页查询任务列表
     * @param filter 过滤条件
     * @param pageParam 分页参数
     * @return ResultDomain<TbCrontabTask> 任务列表
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> getTaskPage(TbCrontabTask filter, PageParam pageParam);

    /**
     * @description 启动定时任务
     * @param taskId 任务ID
     * @return ResultDomain<TbCrontabTask> 启动结果
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> startTask(String taskId);

    /**
     * @description 暂停定时任务
     * @param taskId 任务ID
     * @return ResultDomain<TbCrontabTask> 暂停结果
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> pauseTask(String taskId);

    /**
     * @description 立即执行一次任务
     * @param taskId 任务ID
     * @return ResultDomain<TbCrontabTask> 执行结果
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabTask> executeTaskOnce(String taskId);

    /**
     * @description 验证Cron表达式
     * @param cronExpression Cron表达式
     * @return ResultDomain<String> 验证结果（返回下次执行时间）
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<String> validateCronExpression(String cronExpression);

    // ----------------定时任务日志--------------------------------

    /**
     * @description 根据任务ID查询执行日志
     * @param taskId 任务ID
     * @return ResultDomain<TbCrontabLog> 日志列表
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabLog> getLogsByTaskId(String taskId);

    /**
     * @description 根据过滤条件查询日志列表
     * @param filter 过滤条件
     * @return ResultDomain<TbCrontabLog> 日志列表
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabLog> getLogList(TbCrontabLog filter);

    /**
     * @description 分页查询日志列表
     * @param filter 过滤条件
     * @param pageParam 分页参数
     * @return ResultDomain<TbCrontabLog> 日志列表
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabLog> getLogPage(TbCrontabLog filter, PageParam pageParam);

    /**
     * @description 根据ID查询日志详情
     * @param logId 日志ID
     * @return ResultDomain<TbCrontabLog> 日志详情
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabLog> getLogById(String logId);

    /**
     * @description 清理指定天数之前的日志
     * @param days 天数
     * @return ResultDomain<Integer> 清理结果（返回清理条数）
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<Integer> cleanLogs(Integer days);

    /**
     * @description 删除任务执行日志
     * @param logId 日志ID
     * @return ResultDomain<TbCrontabLog> 删除结果
     * @author yslg
     * @since 2025-10-25
     */
    ResultDomain<TbCrontabLog> deleteLog(String logId);
}

