using System.Net.Sockets;
using WIDESEAWCS_QuartzJob;

namespace WIDESEAWCS_Tasks.Workflow.Abstractions
{
    /// <summary>
    /// Socket 客户端网关接口 - 封装 TcpSocketServer 的访问，使业务层不直接依赖底层通信实现
    /// </summary>
    /// <remarks>
    /// 该接口是业务层与底层 TCP 通信之间的抽象层。
    /// 通过依赖注入和使用接口，使上层代码不直接依赖 TcpSocketServer，
    /// 便于后续替换通信实现或进行单元测试。
    /// </remarks>
    public interface ISocketClientGateway
    {
        /// <summary>
        /// 异步发送消息到指定客户端
        /// </summary>
        /// <param name="clientId">目标客户端的 IP 地址</param>
        /// <param name="message">要发送的消息内容</param>
        /// <returns>发送是否成功</returns>
        Task<bool> SendToClientAsync(string clientId, string message);

        /// <summary>
        /// 通过 TcpClient 对象发送消息
        /// </summary>
        /// <remarks>
        /// 与 SendToClientAsync 的区别：此方法直接使用 TcpClient 对象，
        /// 适用于需要回写响应给发送方的场景。
        /// </remarks>
        /// <param name="client">TCP 客户端连接对象</param>
        /// <param name="message">要发送的消息内容</param>
        Task SendMessageAsync(TcpClient client, string message);

        /// <summary>
        /// 获取所有已连接客户端的 ID 列表
        /// </summary>
        /// <returns>客户端 IP 地址列表</returns>
        IReadOnlyList<string> GetClientIds();

        /// <summary>
        /// 异步处理客户端连接的消息循环
        /// </summary>
        /// <remarks>
        /// 启动后会持续接收客户端消息，直到连接断开或取消令牌被触发。
        /// 用于管理单个客户端的生命周期。
        /// </remarks>
        /// <param name="client">TCP 客户端连接</param>
        /// <param name="clientId">客户端标识（通常是 IP 地址）</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <param name="robotCrane">机器人状态对象</param>
        Task HandleClientAsync(TcpClient client, string clientId, CancellationToken cancellationToken, RobotSocketState robotCrane);
    }
}