package com.dne.ems.service;

import java.time.LocalDate;
import java.util.List;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import com.dne.ems.dto.TaskApprovalRequest;
import com.dne.ems.dto.TaskAssignmentRequest;
import com.dne.ems.dto.TaskCreationRequest;
import com.dne.ems.dto.TaskDetailDTO;
import com.dne.ems.dto.TaskFromFeedbackRequest;
import com.dne.ems.dto.TaskHistoryDTO;
import com.dne.ems.dto.TaskSummaryDTO;
import com.dne.ems.event.TaskReadyForAssignmentEvent;
import com.dne.ems.model.Feedback;
import com.dne.ems.model.enums.PollutionType;
import com.dne.ems.model.enums.SeverityLevel;
import com.dne.ems.model.enums.TaskStatus;

/**
 * 任务管理服务接口，处理任务全生命周期管理
 *
 * <p>主要功能：
 * <ul>
 *   <li>任务创建与分配</li>
 *   <li>任务状态管理</li>
 *   <li>任务审核与审批</li>
 *   <li>从反馈创建任务</li>
 * </ul>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2024
 */
public interface TaskManagementService {

    /**
     * 获取任务分页列表(支持多条件过滤)
     *
     * @param status 任务状态过滤条件
     * @param assigneeId 分配人ID过滤条件
     * @param severity 严重程度过滤条件
     * @param pollutionType 污染类型过滤条件
     * @param startDate 开始日期过滤条件(yyyy-MM-dd)
     * @param endDate 结束日期过滤条件(yyyy-MM-dd)
     * @param pageable 分页参数
     * @return 任务分页列表
     */
    Page<TaskSummaryDTO> getTasks(
            TaskStatus status,
            Long assigneeId,
            SeverityLevel severity,
            PollutionType pollutionType,
            LocalDate startDate,
            LocalDate endDate,
            Pageable pageable
    );

    /**
     * 分配任务给网格工作人员
     *
     * @param taskId 任务ID
     * @param request 包含分配信息的请求体
     * @return 更新后的任务摘要
     * @throws ResourceNotFoundException 如果任务或分配人不存在
     * @throws InvalidOperationException 如果任务状态不允许分配
     */
    TaskSummaryDTO assignTask(Long taskId, TaskAssignmentRequest request);

    /**
     * Retrieves the full details of a specific task.
     *
     * @param taskId The ID of the task to retrieve.
     * @return A {@link TaskDetailDTO} containing the task's details.
     */
    TaskDetailDTO getTaskDetails(Long taskId);

    /**
     * Processes an administrator's approval or rejection of a submitted task.
     *
     * @param taskId The ID of the task to review.
     * @param request The approval request.
     * @return The updated task details.
     */
    TaskDetailDTO reviewTask(Long taskId, TaskApprovalRequest request);

    /**
     * Cancels a task.
     *
     * @param taskId The ID of the task to cancel.
     * @return The updated task details.
     */
    TaskDetailDTO cancelTask(Long taskId);

    /**
     * Retrieves the history of a specific task.
     *
     * @param taskId The ID of the task.
     * @return A list of {@link TaskHistoryDTO} objects representing the task's history.
     */
    List<TaskHistoryDTO> getTaskHistory(Long taskId);

    /**
     * 创建新任务
     *
     * @param request 包含任务信息的请求体
     * @return 创建的任务详情
     */
    TaskDetailDTO createTask(TaskCreationRequest request);

    /**
     * 获取待处理的反馈列表
     *
     * @return 待处理反馈列表
     */
    List<Feedback> getPendingFeedback();

    /**
     * 从反馈创建任务
     *
     * @param feedbackId 反馈ID
     * @param request 包含任务信息的请求体
     * @return 创建的任务详情
     * @throws ResourceNotFoundException 如果反馈不存在
     * @throws InvalidOperationException 如果反馈状态不允许创建任务
     */
    TaskDetailDTO createTaskFromFeedback(Long feedbackId, TaskFromFeedbackRequest request);

    void handleTaskReadyForAssignment(TaskReadyForAssignmentEvent event);

    /**
     * 批准已提交的任务
     *
     * @param taskId 任务ID
     * @return 更新后的任务详情
     */
    TaskDetailDTO approveTask(Long taskId);

    /**
     * 拒绝已提交的任务
     *
     * @param taskId 任务ID
     * @param reason 拒绝理由
     * @return 更新后的任务详情
     */
    TaskDetailDTO rejectTask(Long taskId, String reason);
} 