namespace RobotNet10.FleetManager.Script;

/// <summary>
/// Service interface for managing map layouts, nodes, and stations.
/// Provides methods to retrieve map elements (nodes, stations) and actions from the layout database.
/// </summary>
public interface ILayoutManager
{
    /// <summary>
    /// Retrieves a station from the specified map by its name.
    /// </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="name">The name of the station to retrieve. Cannot be null or empty.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains the <see cref="IStation"/> matching the specified name within the given map,
    /// or throws an exception if no such station exists.
    /// </returns>
    Task<IStation> GetStation(string layout, string version, string level, string name);

    /// <summary>
    /// Retrieves a node from the specified map by its name.
    /// </summary>
    /// <remarks>
    /// This method performs an asynchronous operation to locate a node within the specified map.
    /// Ensure that the map and name parameters are valid and non-empty before calling this method.
    /// </remarks>
    /// <param name="layout">The identifier of the map from which to retrieve the node. 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="name">The name of the node to retrieve. Cannot be null or empty.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains the <see cref="INode"/> matching the specified name within the given map,
    /// or throws an exception if no such node exists.
    /// </returns>
    Task<INode> GetNode(string layout, string version, string level, string name);

    /// <summary>
    /// Retrieves a VDA5050 action configuration for a specific element (node or station) in the map.
    /// </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="name">The name of the element (node or station) for which to retrieve the action. Cannot be null or empty.</param>
    /// <param name="robotId">The identifier of the robot that will execute the action. Used for robot-specific action configuration. Cannot be null or empty.</param>
    /// <returns>
    /// A task that represents the asynchronous operation.
    /// The task result contains the VDA5050 <see cref="RobotNet.VDA5050.InstantAction.Action"/> configured for the specified element and robot,
    /// or throws an exception if no such action exists.
    /// </returns>
    Task<RobotNet.VDA5050.InstantAction.Action> GetAction(string layout, string version, string level, string name, string robotId);
}

/// <summary>
/// Represents a node (waypoint) in the map layout.
/// Nodes define points where robots can navigate to or pass through.
/// Conforms to VDMA LIF (Logistics Interface Format) standard.
/// </summary>
public interface INode
{
    /// <summary>
    /// Gets or sets the unique identifier of the node.
    /// </summary>
    public Guid Id { get; set; }

    /// <summary>
    /// Gets or sets the parent map identifier that contains this node.
    /// </summary>
    public Guid MapId { get; set; }

    /// <summary>
    /// Gets or sets the node identifier (VDMA LIF: nodeId).
    /// This is a required field and must be unique within the level.
    /// </summary>
    public string NodeId { get; set; }

    /// <summary>
    /// Gets or sets the node name (VDMA LIF: nodeName).
    /// This is an optional human-readable name for the node.
    /// </summary>
    public string? NodeName { get; set; }

    /// <summary>
    /// Gets or sets the node description (VDMA LIF: nodeDescription).
    /// This is an optional description providing additional information about the node.
    /// </summary>
    public string? NodeDescription { get; set; }

    /// <summary>
    /// Gets or sets the X coordinate of the node position in meters (VDMA LIF: nodePosition.x).
    /// This is a required field.
    /// </summary>
    public double X { get; set; }

    /// <summary>
    /// Gets or sets the Y coordinate of the node position in meters (VDMA LIF: nodePosition.y).
    /// This is a required field.
    /// </summary>
    public double Y { get; set; }
}

/// <summary>
/// Represents a station (workstation or loading/unloading point) in the map layout.
/// Stations are locations where robots can perform pick or drop operations.
/// Conforms to VDMA LIF (Logistics Interface Format) standard.
/// </summary>
public interface IStation
{
    /// <summary>
    /// Gets the unique identifier of the station.
    /// </summary>
    Guid Id { get; }

    /// <summary>
    /// Gets the identifier of the map that contains this station.
    /// </summary>
    Guid MapId { get; }

    /// <summary>
    /// Gets the identifiers of the nodes that this station is linked to.
    /// A station can be associated with one or more nodes for navigation purposes.
    /// </summary>
    Guid[] NodeId { get; }

    /// <summary>
    /// Gets the station identifier (VDMA LIF: stationId).
    /// This is a required field and must be unique within the level.
    /// </summary>
    public string StationId { get; } 

    /// <summary>
    /// Gets the station name (VDMA LIF: stationName).
    /// This is an optional human-readable name for the station.
    /// </summary>
    public string? StationName { get; }

    /// <summary>
    /// Gets the station description (VDMA LIF: stationDescription).
    /// This is an optional description providing additional information about the station.
    /// </summary>
    public string? StationDescription { get; }

    /// <summary>
    /// Gets the station height in meters (VDMA LIF: stationHeight).
    /// This is an optional field indicating the height of the station platform.
    /// </summary>
    public double? StationHeight { get; }

    /// <summary>
    /// Gets the X coordinate of the station position in meters (VDMA LIF: stationPosition.x).
    /// This is a required field.
    /// </summary>
    public double X { get; }

    /// <summary>
    /// Gets the Y coordinate of the station position in meters (VDMA LIF: stationPosition.y).
    /// This is a required field.
    /// </summary>
    public double Y { get; }

    /// <summary>
    /// Gets the theta orientation angle in radians (VDMA LIF: stationPosition.theta).
    /// This is an optional field indicating the orientation of the station.
    /// Range: [-Pi ... Pi]
    /// </summary>
    public double? Theta { get; }
}