package com.dne.ems.service;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.web.multipart.MultipartFile;

import com.dne.ems.dto.TaskDetailDTO;
import com.dne.ems.dto.TaskSubmissionRequest;
import com.dne.ems.dto.TaskSummaryDTO;
import com.dne.ems.model.enums.TaskStatus;

import java.util.List;

/**
 * 网格员任务服务接口，处理网格员的任务管理操作
 *
 * <p>主要功能：
 * <ul>
 *   <li>查询分配的任务列表</li>
 *   <li>处理任务状态流转</li>
 *   <li>提交任务完成情况</li>
 *   <li>获取任务详情</li>
 * </ul>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2024-03
 */
public interface GridWorkerTaskService {

    /**
     * 获取分配给指定网格员的任务列表
     *
     * <p>查询规则：
     * <ul>
     *   <li>只返回分配给该网格员的任务</li>
     *   <li>可按任务状态过滤</li>
     *   <li>默认按截止时间升序排序</li>
     * </ul>
     *
     * @param workerId 网格员ID
     * @param status 任务状态过滤条件(可选)
     * @param pageable 分页参数
     * @return 任务摘要分页列表
     * @see com.dne.ems.dto.TaskSummaryDTO
     * @see com.dne.ems.model.enums.TaskStatus
     */
    Page<TaskSummaryDTO> getAssignedTasks(Long workerId, TaskStatus status, Pageable pageable);

    /**
     * 网格员接受任务
     *
     * <p>状态流转：
     * <ul>
     *   <li>ASSIGNED -> IN_PROGRESS</li>
     *   <li>验证任务确实分配给该网格员</li>
     *   <li>记录接受时间</li>
     * </ul>
     *
     * @param taskId 任务ID
     * @param workerId 网格员ID(用于验证)
     * @return 更新后的任务摘要
     * @throws ResourceNotFoundException 如果任务不存在
     * @throws InvalidOperationException 如果任务状态不允许接受
     * @see com.dne.ems.dto.TaskSummaryDTO
     */
    TaskSummaryDTO acceptTask(Long taskId, Long workerId);
    /**
     * 提交任务完成情况
     *
     * <p>状态流转：
     * <ul>
     *   <li>IN_PROGRESS -> PENDING_REVIEW</li>
     *   <li>验证任务确实分配给该网格员</li>
     *   <li>记录提交时间和完成说明</li>
     * </ul>
     *
     * @param taskId 任务ID
     * @param workerId 网格员ID(用于验证)
     * @param request 包含完成详情的请求
     * @return 更新后的任务摘要
     * @throws ResourceNotFoundException 如果任务不存在
     * @throws InvalidOperationException 如果任务状态不允许提交
     * @see com.dne.ems.dto.TaskSubmissionRequest
     * @see com.dne.ems.dto.TaskSummaryDTO
     */
    TaskSummaryDTO submitTaskCompletion(Long taskId, Long workerId, TaskSubmissionRequest request);

    /**
     * Submits the completion details for a task, including file attachments.
     *
     * @param taskId The ID of the task.
     * @param workerId The ID of the worker submitting the task.
     * @param request The task submission details.
     * @param files A list of files attached to the submission.
     * @return A summary of the updated task.
     */
    TaskSummaryDTO submitTaskCompletion(Long taskId, Long workerId, TaskSubmissionRequest request, List<MultipartFile> files);

    /**
     * Retrieves the details of a specific task assigned to a worker.
     *
     * @param taskId The ID of the task.
     * @param workerId The ID of the worker requesting the details, for validation.
     * @return The full details of the task.
     */
    TaskDetailDTO getTaskDetails(Long taskId, Long workerId);
} 