using WIDESEAWCS_Model.Models;

namespace WIDESEAWCS_ITaskInfoRepository
{
    /// <summary>
    /// 机械手状态仓储接口
    /// </summary>
    /// <remarks>
    /// 定义机械手状态的数据库访问操作。
    /// 复杂对象（RobotCrane、CurrentTask、数组等）在调用方使用强类型，
    /// 在此接口层面以 Dt_RobotState 实体为操作单位。
    /// </remarks>
    public interface IRobotStateRepository
    {
        /// <summary>
        /// 根据 IP 地址获取机械手状态
        /// </summary>
        /// <param name="ipAddress">设备 IP 地址</param>
        /// <returns>状态实体，不存在则返回 null</returns>
        Dt_RobotState? GetByIp(string ipAddress);

        /// <summary>
        /// 获取或创建机械手状态
        /// </summary>
        /// <param name="ipAddress">设备 IP 地址</param>
        /// <param name="robotCrane">机器人设备信息，用于初始化新状态</param>
        /// <returns>状态实体</returns>
        Dt_RobotState GetOrCreate(string ipAddress, RobotCraneDevice robotCrane);

        /// <summary>
        /// 安全更新机械手状态（乐观锁）
        /// </summary>
        /// <param name="ipAddress">设备 IP 地址</param>
        /// <param name="newState">新状态实体（RowVersion 会被更新）</param>
        /// <param name="expectedRowVersion">期望的行版本号（更新前的版本）</param>
        /// <returns>是否更新成功；false 表示版本冲突或记录不存在</returns>
        bool TryUpdate(string ipAddress, Dt_RobotState newState, byte[] expectedRowVersion);

        /// <summary>
        /// 将 Dt_RobotState 实体转换为 RobotSocketState 内存对象
        /// </summary>
        /// <param name="entity">数据库实体</param>
        /// <returns>内存状态对象</returns>
        RobotSocketState ToSocketState(Dt_RobotState entity);

        /// <summary>
        /// 将 RobotSocketState 内存对象转换为 Dt_RobotState 实体
        /// </summary>
        /// <param name="state">内存状态对象</param>
        /// <returns>数据库实体</returns>
        Dt_RobotState ToEntity(RobotSocketState state);
    }
}