namespace RobotNet10.FleetManager.Script;

/// <summary>
/// Defines the action types that can be performed at a station.
/// </summary>
public enum StationAction
{
    /// <summary>
    /// Pick up a load from the station.
    /// </summary>
    Pick,

    /// <summary>
    /// Drop off a load at the station.
    /// </summary>
    Drop,

    /// <summary>
    /// No action - robot moves to station without performing any load operation.
    /// </summary>
    None
}

/// <summary>
/// Interface for controlling an Autonomous Mobile Robot (AMR).
/// Provides methods to move the robot, execute actions, and query its current state.
/// </summary>
public interface IRobot
{
    /// <summary>
    /// Gets the unique identifier of the robot (serial number or unique identifier).
    /// </summary>
    string RobotId { get; }

    /// <summary>
    /// Gets the display name of the robot.
    /// </summary>
    string Name { get; }

    /// <summary>
    /// Gets the robot model identifier.
    /// </summary>
    Guid ModelId { get; }

    /// <summary>
    /// Gets the map identifier where the robot is currently operating, or <see langword="null"/> if not assigned to a map.
    /// </summary>
    Guid? MapId { get; }

    /// <summary>
    /// Gets the current state of the robot, including position, battery, loads, and operational status.
    /// </summary>
    RobotState State { get; }

    /// <summary>
    /// Moves the robot to a target node on the map without performing any end action.
    /// </summary>
    /// <param name="nodeName">The name of the target node. Cannot be null or empty.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains a <see cref="RobotResult"/> indicating success or failure of the movement command.
    /// </returns>
    Task<RobotResult> MoveToNode(string nodeName, CancellationToken cancellationToken);

    /// <summary>
    /// Moves the robot to a target node with a specific orientation at the endpoint.
    /// </summary>
    /// <param name="nodeName">The name of the target node. Cannot be null or empty.</param>
    /// <param name="lastAngle">The required orientation angle in radians at the endpoint. Range: [-Pi ... Pi].</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains a <see cref="RobotResult"/> indicating success or failure of the movement command.
    /// </returns>
    Task<RobotResult> MoveToNode(string nodeName, double lastAngle, CancellationToken cancellationToken);

    /// <summary>
    /// Moves the robot to a target station node and executes the specified action (pick, drop, or none).
    /// </summary>
    /// <param name="nodeName">The name of the target station node. Cannot be null or empty.</param>
    /// <param name="action">The action to perform at the station: <see cref="StationAction.Pick"/>, <see cref="StationAction.Drop"/>, or <see cref="StationAction.None"/>.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains a <see cref="RobotResult"/> indicating success or failure of the movement and action execution.
    /// </returns>
    Task<RobotResult> MoveToStation(string nodeName, StationAction action, CancellationToken cancellationToken);

    /// <summary>
    /// Aborts or cancels the ongoing robot movement action, if one exists.
    /// </summary>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// </returns>
    Task AbortMovement();

    /// <summary>
    /// Immediately executes an instant action on the robot, bypassing any waiting period.
    /// Instant actions are executed immediately without requiring the robot to be at a specific location.
    /// </summary>
    /// <param name="action">The VDA5050 instant action to execute. Cannot be null.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains a <see cref="RobotResult"/> indicating success or failure of the action execution.
    /// </returns>
    Task<RobotResult> Execute(RobotNet.VDA5050.InstantAction.Action action, CancellationToken cancellationToken);
}