package com.dne.ems.service;

import java.util.List;
import java.util.Map;

import com.dne.ems.dto.AqiDistributionDTO;
import com.dne.ems.dto.AqiHeatmapPointDTO;
import com.dne.ems.dto.DashboardStatsDTO;
import com.dne.ems.dto.GridCoverageDTO;
import com.dne.ems.dto.HeatmapPointDTO;
import com.dne.ems.dto.PollutantThresholdDTO;
import com.dne.ems.dto.PollutionStatsDTO;
import com.dne.ems.dto.TaskStatsDTO;
import com.dne.ems.dto.TrendDataPointDTO;

/**
 * 仪表盘服务接口，提供各类环境监测数据的统计和可视化数据
 *
 * <p>主要功能：
 * <ul>
 *   <li>环境质量指标统计</li>
 *   <li>AQI数据分布和热力图</li>
 *   <li>污染物阈值管理</li>
 *   <li>任务完成情况统计</li>
 *   <li>各类趋势分析数据</li>
 * </ul>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2024-03
 */
public interface DashboardService {

    /**
     * 获取污染物统计数据
     *
     * <p>统计规则：
     * <ul>
     *   <li>按污染类型分组统计</li>
     *   <li>包含过去24小时数据</li>
     *   <li>按严重程度排序</li>
     * </ul>
     *
     * @return 污染物统计DTO列表
     * @see com.dne.ems.dto.PollutionStatsDTO
     */
    List<PollutionStatsDTO> getPollutionStats();

    /**
     * 获取任务完成统计数据
     *
     * <p>统计指标：
     * <ul>
     *   <li>任务总数</li>
     *   <li>已完成任务数</li>
     *   <li>超期任务数</li>
     *   <li>平均完成时间</li>
     * </ul>
     *
     * @return 任务统计DTO
     * @see com.dne.ems.dto.TaskStatsDTO
     */
    TaskStatsDTO getTaskCompletionStats();

    /**
     * 获取仪表盘核心统计数据
     *
     * <p>包含数据：
     * <ul>
     *   <li>实时AQI指数</li>
     *   <li>待处理反馈数</li>
     *   <li>待分配任务数</li>
     *   <li>网格覆盖率</li>
     *   <li>告警事件数</li>
     * </ul>
     *
     * @return 仪表盘统计DTO
     * @see com.dne.ems.dto.DashboardStatsDTO
     */
    DashboardStatsDTO getDashboardStats();

    /**
     * Gathers AQI distribution data for a pie/bar chart.
     *
     * @return A list of {@link AqiDistributionDTO} objects, each representing an AQI level and its count.
     */
    List<AqiDistributionDTO> getAqiDistribution();

    /**
     * Gathers data for the monthly air quality exceedance trend chart.
     *
     * @return A list of {@link TrendDataPointDTO} for the last 12 months.
     */
    List<TrendDataPointDTO> getMonthlyExceedanceTrend();

    /**
     * Gathers grid coverage data, grouped by city.
     *
     * @return A list of {@link GridCoverageDTO} objects, each representing a city and its grid count.
     */
    List<GridCoverageDTO> getGridCoverageByCity();

    /**
     * Gathers data for the pollution source heatmap.
     *
     * @return A list of {@link HeatmapPointDTO} objects, each representing a grid cell and its event intensity.
     */
    List<HeatmapPointDTO> getHeatmapData();

    /**
     * Gathers data for the AQI heatmap.
     *
     * @return A list of {@link AqiHeatmapPointDTO} objects.
     */
    List<AqiHeatmapPointDTO> getAqiHeatmapData();

    /**
     * 获取所有污染物的阈值设置
     * 
     * @return 污染物阈值列表
     */
    List<PollutantThresholdDTO> getPollutantThresholds();
    
    /**
     * 根据污染物名称获取阈值设置
     * 
     * @param pollutantName 污染物名称
     * @return 阈值设置，如果不存在则返回null
     */
    PollutantThresholdDTO getPollutantThreshold(String pollutantName);
    
    /**
     * 保存或更新污染物阈值设置
     * 
     * @param thresholdDTO 阈值设置
     * @return 保存后的阈值设置
     */
    PollutantThresholdDTO savePollutantThreshold(PollutantThresholdDTO thresholdDTO);

    /**
     * 获取每种污染物的月度趋势数据
     * 
     * @return 每种污染物的月度趋势数据
     */
    Map<String, List<TrendDataPointDTO>> getPollutantMonthlyTrends();
} 