using System.Threading;
using System.Threading.Tasks;

namespace Aging.Infrastructure.Contracts
{
    /// <summary>
    /// 设备命令执行结果
    /// </summary>
    public sealed class DeviceCommandResult
    {
        /// <summary>
        /// 命令是否执行成功
        /// </summary>
        public bool Success { get; set; }

        /// <summary>
        /// 设备原始响应字符串
        /// </summary>
        public string? RawResponse { get; set; }

        /// <summary>
        /// 回读值（解析后的有效数据）
        /// </summary>
        public string? Readback { get; set; }

        /// <summary>
        /// 错误代码
        /// </summary>
        public string? ErrorCode { get; set; }

        /// <summary>
        /// 错误信息
        /// </summary>
        public string? ErrorMessage { get; set; }

        /// <summary>
        /// 命令执行延迟（毫秒）
        /// </summary>
        public double LatencyMs { get; set; }
    }

    /// <summary>
    /// 设备服务接口。
    /// 提供基于资源预约的命令执行和安全关机功能，协调资源管理和设备驱动。
    /// </summary>
    public interface IDeviceService
    {
        /// <summary>
        /// 异步执行设备命令。
        /// 需要有效的资源预约才能执行。
        /// </summary>
        /// <param name="deviceId">设备标识符</param>
        /// <param name="command">命令字符串</param>
        /// <param name="owner">所有者令牌</param>
        /// <param name="ct">取消令牌</param>
        /// <returns>命令执行结果</returns>
        Task<DeviceCommandResult> ExecuteCommandAsync(
            string deviceId, string command, ResourceOwnerToken owner, CancellationToken ct);

        /// <summary>
        /// 异步执行设备查询。
        /// 需要有效的资源预约才能执行。
        /// </summary>
        /// <param name="deviceId">设备标识符</param>
        /// <param name="query">查询字符串</param>
        /// <param name="owner">所有者令牌</param>
        /// <param name="ct">取消令牌</param>
        /// <returns>命令执行结果</returns>
        Task<DeviceCommandResult> ExecuteQueryAsync(
            string deviceId, string query, ResourceOwnerToken owner, CancellationToken ct);

        /// <summary>
        /// 异步安全关闭设备。
        /// 执行设备特定的关机序列，确保设备处于安全状态。
        /// </summary>
        /// <param name="deviceId">设备标识符</param>
        /// <param name="owner">所有者令牌</param>
        /// <param name="ct">取消令牌</param>
        Task SafeShutdownAsync(string deviceId, ResourceOwnerToken owner, CancellationToken ct);
    }
}