using System.Linq.Expressions;

namespace RobotNet10.FleetManager.Script;

/// <summary>
/// Robot management service interface for FleetManager scripts.
/// Provides methods to retrieve, query, and manage robots in the fleet.
/// </summary>
public interface IRobotManager
{
    /// <summary>
    /// Retrieves a robot controller by its unique identifier.
    /// </summary>
    /// <param name="robotId">The unique identifier of the robot. Cannot be null or empty.</param>
    /// <returns>
    /// A task that represents the asynchronous operation. 
    /// The task result contains the <see cref="IRobot"/> instance if found, or <see langword="null"/> if the robot does not exist or is not available.
    /// </returns>
    Task<IRobot?> GetRobotById(string robotId);

    /// <summary>
    /// Gets the current state of a robot by its identifier.
    /// </summary>
    /// <param name="robotId">The unique identifier of the robot. Cannot be null or empty.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains the <see cref="RobotState"/> if the robot is found and connected, or <see langword="null"/> otherwise.
    /// </returns>
    Task<RobotState?> GetRobotState(string robotId);

    /// <summary>
    /// Searches for robots on a specific map by layout, version, level, and model.
    /// </summary>
    /// <param name="layout">The identifier of the map/layout. Cannot be null or empty.</param>
    /// <param name="version">The version of the map. Cannot be null or empty.</param>
    /// <param name="level">The level identifier within the map. Cannot be null or empty.</param>
    /// <param name="model">The robot model identifier to filter by. Cannot be null or empty.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains a collection of robot IDs that match the specified criteria.
    /// </returns>
    Task<IEnumerable<string>> SearchRobots(string layout, string version, string level, string model);

    /// <summary>
    /// Searches for robots on a specific map with additional state-based filtering conditions.
    /// </summary>
    /// <param name="layout">The identifier of the map/layout. Cannot be null or empty.</param>
    /// <param name="version">The version of the map. Cannot be null or empty.</param>
    /// <param name="level">The level identifier within the map. Cannot be null or empty.</param>
    /// <param name="model">The robot model identifier to filter by. Cannot be null or empty.</param>
    /// <param name="expr">A lambda expression that defines additional filtering conditions based on <see cref="RobotState"/>.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains a collection of robot IDs that match all specified criteria including the state filter.
    /// </returns>
    /// <example>
    /// <code>
    /// // Find all ready robots with battery voltage above 24V
    /// var robots = await RobotManager.SearchRobots("layout1", "v1", "level1", "model1", tate => state.IsReady, state.Voltage > 24.0);
    /// </code>
    /// </example>
    Task<IEnumerable<string>> SearchRobots(string layout, string version, string level, string model, Expression<Func<RobotState, bool>> expr);
    
    /// <summary>
    /// Gets the current order status of a robot.
    /// </summary>
    /// <param name="robotId">The unique identifier of the robot. Cannot be null or empty.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains the <see cref="RobotOrderStatus"/> indicating the current order processing state of the robot.
    /// </returns>
    Task<RobotOrderStatus> GetRobotOrderStatus(string robotId);
}