package com.dne.ems.service;
import java.time.LocalDate;

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

import com.dne.ems.dto.FeedbackResponseDTO;
import com.dne.ems.dto.FeedbackStatsResponse;
import com.dne.ems.dto.FeedbackSubmissionRequest;
import com.dne.ems.dto.ProcessFeedbackRequest;
import com.dne.ems.dto.PublicFeedbackRequest;
import com.dne.ems.model.Feedback;
import com.dne.ems.model.enums.FeedbackStatus;
import com.dne.ems.model.enums.PollutionType;
import com.dne.ems.model.enums.SeverityLevel;
import com.dne.ems.security.CustomUserDetails;

/**
 * 反馈服务接口，处理环境问题反馈的提交和管理
 *
 * <p>主要功能：
 * <ul>
 *   <li>用户反馈提交(认证用户和匿名用户)</li>
 *   <li>反馈信息查询与过滤</li>
 *   <li>反馈数据统计分析</li>
 * </ul>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2024
 */
public interface FeedbackService {

    /**
     * 提交用户反馈(认证用户)
     *
     * <p>流程：
     * <ol>
     *   <li>从安全上下文获取用户信息</li>
     *   <li>创建反馈记录</li>
     *   <li>生成唯一事件ID</li>
     *   <li>触发AI初步处理</li>
     * </ol>
     *
     * @param request 包含反馈信息的请求体
     * @param files 上传的附件(可选)
     * @return 新创建的反馈实体
     * @throws ResourceNotFoundException 如果用户不存在
     */
    Feedback submitFeedback(FeedbackSubmissionRequest request, MultipartFile[] files);

    /**
     * 获取所有反馈(多条件过滤)
     *
     * <p>支持以下过滤条件组合查询：
     * <ul>
     *   <li>状态：PENDING_REVIEW/PROCESSED/REJECTED</li>
     *   <li>污染类型：AIR/WATER/SOIL/NOISE等</li>
     *   <li>严重程度：LOW/MEDIUM/HIGH/CRITICAL</li>
     *   <li>地理位置：城市/区县</li>
     *   <li>时间范围：开始日期至结束日期</li>
     *   <li>关键词：标题/描述模糊匹配</li>
     * </ul>
     *
     * @param userDetails 当前认证用户信息
     * @param status 反馈状态
     * @param pollutionType 污染类型
     * @param severityLevel 严重程度
     * @param cityName 城市名称
     * @param districtName 区县名称
     * @param startDate 开始日期(包含)
     * @param endDate 结束日期(包含)
     * @param keyword 关键词(标题/描述模糊匹配)
     * @param pageable 分页参数(页号从0开始)
     * @return 分页反馈列表(按创建时间降序)
     * @see com.dne.ems.model.Feedback 反馈实体
     * @see com.dne.ems.model.enums.FeedbackStatus 反馈状态枚举
     * @see com.dne.ems.model.enums.PollutionType 污染类型枚举
     * @see com.dne.ems.model.enums.SeverityLevel 严重程度枚举
     */
    Page<FeedbackResponseDTO> getFeedback(
            CustomUserDetails userDetails,
            FeedbackStatus status, 
            PollutionType pollutionType, 
            SeverityLevel severityLevel,
            String cityName,
            String districtName,
            LocalDate startDate, 
            LocalDate endDate, 
            String keyword, 
            Pageable pageable);
    
    /**
     * 根据ID获取反馈详情
     * @param id 反馈ID
     * @return 反馈详情
     */
    Feedback getFeedbackById(Long id);

    /**
     * 根据ID获取反馈详情DTO
     * @param id 反馈ID
     * @return 反馈详情DTO
     */
    FeedbackResponseDTO getFeedbackDetail(Long id);
    
    /**
     * 获取反馈统计数据
     * @param userDetails 当前认证用户信息
     * @return 反馈统计响应
     */
    FeedbackStatsResponse getFeedbackStats(CustomUserDetails userDetails);

    /**
     * 提交公共反馈(匿名用户)
     *
     * <p>流程：
     * <ol>
     *   <li>创建匿名反馈记录</li>
     *   <li>生成唯一事件ID</li>
     *   <li>触发AI初步处理</li>
     * </ol>
     *
     * @param request 包含反馈信息的请求体
     * @param files 上传的附件(可选)
     * @return 新创建的反馈实体
     */
    Feedback createPublicFeedback(PublicFeedbackRequest request, MultipartFile[] files);

    FeedbackResponseDTO processFeedback(Long id, ProcessFeedbackRequest request);
} 