//! DeviceBackend trait — 设备后端抽象层
//!
//! 定义统一的设备操作接口，支持多平台实现。

use crate::core::message::{DeviceCapability, DeviceCommand, DeviceResponse};
use anyhow::Result;

/// 设备后端 trait
///
/// 所有平台的设备后端都需要实现此 trait，提供统一的设备操作接口。
/// DevicePlugin 通过此 trait 与具体平台的设备交互，实现跨平台支持。
///
/// # 实现要求
/// - 必须是 Send，以便在多线程环境中使用
/// - 所有方法都应该是非阻塞的或快速返回的
/// - 错误处理应该返回 Result，而不是 panic
///
/// # 示例
/// ```ignore
/// struct MyBackend;
///
/// impl DeviceBackend for MyBackend {
///     fn name(&self) -> &str {
///         "my-backend"
///     }
///
///     fn init(&mut self, config: &serde_json::Value) -> Result<()> {
///         // 初始化设备
///         Ok(())
///     }
///
///     fn handle_command(&mut self, cmd: DeviceCommand) -> Result<DeviceResponse> {
///         // 处理设备命令
///         Ok(DeviceResponse::Ok)
///     }
///
///     fn capabilities(&self) -> Vec<DeviceCapability> {
///         vec![DeviceCapability::Display]
///     }
///
///     fn shutdown(&mut self) -> Result<()> {
///         // 清理资源
///         Ok(())
///     }
/// }
/// ```
pub trait DeviceBackend: Send {
    /// 返回后端名称
    ///
    /// 用于日志记录和调试，应该返回一个简短的标识符。
    /// 例如："linux-arm64", "macos", "windows"
    fn name(&self) -> &str;

    /// 初始化后端
    ///
    /// 在插件启动时调用，用于初始化设备资源、读取配置等。
    ///
    /// # 参数
    /// - `config`: 后端配置（JSON 格式），可以为空对象
    ///
    /// # 返回
    /// - `Ok(())`: 初始化成功
    /// - `Err(e)`: 初始化失败，包含错误信息
    fn init(&mut self, config: &serde_json::Value) -> Result<()>;

    /// 处理设备命令
    ///
    /// 接收来自业务插件的设备命令，执行相应操作并返回响应。
    /// 这是后端的核心方法，所有设备操作都通过此方法完成。
    ///
    /// # 参数
    /// - `cmd`: 设备命令（如 GetDisplayInfo, SetBrightness 等）
    ///
    /// # 返回
    /// - `Ok(DeviceResponse)`: 命令执行成功，返回响应数据
    /// - `Err(e)`: 命令执行失败，包含错误信息
    ///
    /// # 注意
    /// - 不支持的命令应该返回 `DeviceResponse::Error("Not implemented")`
    /// - 方法应该快速返回，避免长时间阻塞
    fn handle_command(&mut self, cmd: DeviceCommand) -> Result<DeviceResponse>;

    /// 返回后端支持的设备能力列表
    ///
    /// 用于声明后端支持哪些设备功能，业务插件可以根据此列表
    /// 判断是否可以使用某个功能。
    ///
    /// # 返回
    /// 支持的设备能力列表（如 Display, Touch, Battery 等）
    fn capabilities(&self) -> Vec<DeviceCapability>;

    /// 关闭后端
    ///
    /// 在插件停止时调用，用于清理资源、停止子进程等。
    ///
    /// # 返回
    /// - `Ok(())`: 关闭成功
    /// - `Err(e)`: 关闭失败，包含错误信息
    fn shutdown(&mut self) -> Result<()>;
}
