package com.youlai.boot.device.service;

import com.youlai.boot.device.model.vo.DeviceOnlineVO;

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

/**
 * 设备在线状态服务
 * <p>
 * 基于 Redis 记录设备在线/离线状态：
 * <ul>
 *     <li>设备周期性上报心跳（经 MQTT 到达 {@code MqttMessageHandler}），每上报一次刷新 Redis key 的 TTL；</li>
 *     <li>Redis key 使用带过期时间的 {@code SET key value EX timeout}，超时未上报则 key 自动过期，即判定设备离线；</li>
 *     <li>查询时 key 存在 = 在线，不存在 = 离线。</li>
 * </ul>
 *
 * @author TongTongStudio
 * @since 2026/8/8
 */
public interface DeviceOnlineService {

    /**
     * 设备上报心跳，记录在线状态（刷新 Redis TTL）
     *
     * @param sn 设备序列号
     * @param ip 设备 IP（可为空）
     */
    void reportHeartbeat(String sn, String ip);

    /**
     * 设备上报心跳，记录在线状态（刷新 Redis TTL）
     *
     * @param sn          设备序列号
     * @param ip          设备 IP（可为空）
     * @param screenState 屏幕状态(1:亮屏;0:熄屏;null:未知)，可为空
     */
    void reportHeartbeat(String sn, String ip, Integer screenState);

    /**
     * 设备主动离线（如 MQTT Last Will / 关机通知）
     *
     * @param sn 设备序列号
     */
    void markOffline(String sn);

    /**
     * 查询单个设备是否在线
     *
     * @param sn 设备序列号
     * @return true=在线, false=离线
     */
    boolean isOnline(String sn);

    /**
     * 获取单个设备在线状态信息
     *
     * @param sn 设备序列号
     * @return 在线状态信息（离线时 online=0）
     */
    DeviceOnlineVO getOnlineInfo(String sn);

    /**
     * 批量查询设备在线状态
     *
     * @param sns 设备序列号集合
     * @return key 为 SN，value 为在线状态信息
     */
    Map<String, DeviceOnlineVO> getOnlineStatusBySns(List<String> sns);

}