namespace SHH.Contracts
{
    /// <summary>
    /// 通用指令执行结果 (Response)
    /// </summary>
    public class CommandResult
    {
        #region --- 核心匹配信息 ---

        /// <summary>
        /// 回执 ID (必须与请求包的 RequestId 一致)
        /// <para>客户端靠这个 ID 来找到对应的 await Task</para>
        /// </summary>
        public string RequestId { get; set; }

        #endregion

        #region --- 执行结果 ---

        /// <summary>
        /// 执行是否成功
        /// </summary>
        public bool Success { get; set; }

        /// <summary>
        /// 结果消息 (成功提示或错误原因)
        /// </summary>
        public string Message { get; set; }

        /// <summary>
        /// 返回的数据 (JSON 或 Base64 字符串)
        /// <para>示例: 截图的 Base64，或者查询到的设备列表 JSON</para>
        /// </summary>
        public string Data { get; set; }

        #endregion

        #region --- 性能统计 ---

        /// <summary>
        /// 全链路耗时 (毫秒)
        /// <para>从客户端发出指令，到收到服务端回执的总时长</para>
        /// <para>注意：该字段由客户端收到回执后自动计算填充，服务端不需要赋值</para>
        /// </summary>
        public double ElapsedMilliseconds { get; set; }

        #endregion

        #region --- 快捷构造方法 ---

        /// <summary>
        /// 快速创建一个成功的回执
        /// </summary>
        public static CommandResult Ok(string msg = "OK", string data = null)
            => new CommandResult { Success = true, Message = msg, Data = data };

        /// <summary>
        /// 快速创建一个失败的回执
        /// </summary>
        public static CommandResult Fail(string msg)
            => new CommandResult { Success = false, Message = msg };

        #endregion
    }
}