package org.dromara.rfid.service;

import org.dromara.rfid.domain.vo.DashboardVO;

import java.util.List;

/**
 * 看板数据服务接口
 * <p>
 * 提供三个独立接口：
 * <ul>
 *     <li>实时统计接口（按秒刷新）：顶部统计 + 告警列表</li>
 *     <li>设备状态接口（定时刷新）：设备树 + 设备最新读取记录</li>
 *     <li>成功率趋势接口（按小时统计）：成功率折线图</li>
 * </ul>
 * </p>
 *
 * @author zch
 * @date 2025-11-26
 */
public interface IDashboardService {

    /**
     * 【接口1】获取实时统计数据（按秒刷新）
     * <p>
     * 包含：顶部统计（设备数量、在线数量、离线数量、告警数量）+ 告警统计列表
     * </p>
     *
     * @param alarmLimit 告警列表限制数量
     * @return 实时统计数据
     */
    DashboardVO.RealtimeStats getRealtimeStats(Integer alarmLimit);

    /**
     * 【接口2】获取位置树（含设备信息）
     * <p>
     * 返回完整的位置树结构，用于前端构建设备树并滚动显示。
     * 位置类型为 3 时表示设备节点，包含设备信息。
     * 不返回读取记录数据，具体记录由 WebSocket 实时推送。
     * </p>
     *
     * @return 位置树列表（顶级节点列表）
     */
    List<DashboardVO.LocationTreeNode> getLocationTree();

    /**
     * 【接口3】获取成功率趋势（按小时统计）
     * <p>
     * 不需要频繁刷新，当前实现固定返回“今日+昨日”的成功率趋势，用于前端对比展示。
     * </p>
     *
     * @param type 预留参数，当前实现忽略，前端可不传
     * @return 成功率趋势数据
     */
    List<DashboardVO.SuccessRateTrend> getSuccessRateTrends(String type);

    // ==================== 以下为原有接口（保留） ====================

    /**
     * 获取统计概览
     *
     * @return 统计概览数据
     */
    DashboardVO.StatisticsOverview getOverview();

    /**
     * 获取告警统计列表
     *
     * @param limit 限制数量
     * @return 告警统计列表
     */
    List<DashboardVO.AlarmStatVO> getAlarmStats(Integer limit);

    /**
     * 获取完整看板数据
     *
     * @param locationId 位置ID（可选）
     * @return 完整看板数据
     */
    DashboardVO getDashboardData(Long locationId);
}
