package com.ruoyi.device.domain.api;

import com.ruoyi.device.domain.model.thingsboard.AttributeMap;
import com.ruoyi.device.domain.model.thingsboard.DeviceInfo;
import com.ruoyi.device.domain.model.thingsboard.TelemetryMap;

import java.util.List;

/**
 * ThingsBoard设备服务接口
 * 提供类型安全的设备查询功能
 */
public interface IThingsBoardDomain {

    /**
     * 获取所有设备的迭代器
     * 每次迭代返回一页设备列表
     *
     * @return 设备迭代器
     */
    Iterable<List<DeviceInfo>> getAllDevices();

    /**
     * 获取所有网关设备的迭代器
     * 每次迭代返回一页网关设备列表
     * 只返回 additionalInfo.gateway = true 的设备
     *
     * @return 网关设备迭代器
     */
    Iterable<List<DeviceInfo>> getAllGatewayDevices();

    /**
     * 根据设备ID获取设备信息
     *
     * @param deviceId 设备ID
     * @return 设备信息，如果设备不存在则返回 null
     */
    DeviceInfo getDeviceInfo(String deviceId);

    /**
     * 根据设备ID获取设备的所有属性
     * 只返回已注册的属性键对应的数据，未注册的键会被忽略
     *
     * @param deviceId 设备ID
     * @return 类型安全的属性映射
     */
    AttributeMap getDeviceAttributes(String deviceId);

    /**
     * 根据设备ID获取设备的所有遥测数据
     * 只返回已注册的遥测键对应的数据，未注册的键会被忽略
     *
     * @param deviceId 设备ID
     * @return 类型安全的遥测数据映射
     */
    TelemetryMap getDeviceTelemetry(String deviceId);

    /**
     * 根据设备ID获取设备的预定义属性
     * 只返回在 DeviceAttributes 中预定义的属性
     *
     * @param deviceId 设备ID
     * @return 类型安全的属性映射，只包含预定义的属性
     */
    AttributeMap getPredefinedDeviceAttributes(String deviceId);

    /**
     * 根据设备ID获取设备的预定义遥测数据
     * 只返回在 DeviceTelemetry 中预定义的遥测数据
     *
     * @param deviceId 设备ID
     * @return 类型安全的遥测数据映射，只包含预定义的遥测数据
     */
    TelemetryMap getPredefinedDeviceTelemetry(String deviceId);

    /**
     * 获取设备所属的网关设备ID
     * 通过 ThingsBoard 的 EntityRelation 查询设备与网关的 "Contains" 关系
     *
     * @param deviceId 设备ID
     * @return 网关设备ID，如果设备不属于任何网关则返回 null
     */
    @Deprecated
    String getDeviceGatewayId(String deviceId);

    /**
     * 获取网关设备的所有子设备ID列表
     * 通过 ThingsBoard 的 EntityRelation 查询网关的 "Contains" 关系
     *
     * @param gatewayDeviceId 网关设备ID
     * @return 子设备ID列表，如果网关没有子设备则返回空列表
     */
    List<String> getGatewayChildDevices(String gatewayDeviceId);
}