BQP/srcs/RobotNet10/FleetManager/RobotNet10.FleetManager/Services/TrafficControl/ITrafficControlService.cs

using RobotNet10.FleetManager.Services.TrafficControl.Models;

namespace RobotNet10.FleetManager.Services.TrafficControl;

/// <summary>
/// Service for traffic control and conflict management between robots
/// </summary>
public interface ITrafficControlService
{
    /// <summary>
    /// Plans a route from start node to goal node for a robot
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="startNodeId">Start node ID</param>
    /// <param name="goalNodeId">Goal node ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>RobotRoute if successful, null otherwise</returns>
    Task<RobotRoute?> PlanRouteAsync(
        string robotId,
        Guid startNodeId,
        Guid goalNodeId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Plans a route with optional constraints (angle, startDirection, finalDirection)
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="startNodeId">Start node ID</param>
    /// <param name="goalNodeId">Goal node ID</param>
    /// <param name="goalAngle">Optional goal angle in degrees</param>
    /// <param name="startDirection">Optional start direction constraint</param>
    /// <param name="finalDirection">Optional final direction constraint</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>RobotRoute if successful, null otherwise</returns>
    Task<RobotRoute?> PlanRouteAsync(
        string robotId,
        Guid startNodeId,
        Guid goalNodeId,
        double? goalAngle,
        RobotNet10.GlobalPathPlanner.Model.Orientation? startDirection,
        RobotNet10.GlobalPathPlanner.Model.Orientation? finalDirection,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Plans a route from current position (x, y, theta) to goal node
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="x">Current X position</param>
    /// <param name="y">Current Y position</param>
    /// <param name="theta">Current orientation in degrees</param>
    /// <param name="goalNodeId">Goal node ID</param>
    /// <param name="goalAngle">Optional goal angle in degrees</param>
    /// <param name="startDirection">Optional start direction constraint</param>
    /// <param name="finalDirection">Optional final direction constraint</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>RobotRoute if successful, null otherwise</returns>
    Task<RobotRoute?> PlanRouteFromPositionAsync(
        string robotId,
        double x,
        double y,
        double theta,
        Guid goalNodeId,
        double? goalAngle,
        RobotNet10.GlobalPathPlanner.Model.Orientation? startDirection,
        RobotNet10.GlobalPathPlanner.Model.Orientation? finalDirection,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Plan route from current position (x, y, theta) to goal node
    /// </summary>
    Task<RobotRoute?> PlanRouteFromPositionACSTrafficAsync(
        string robotId,
        double x,
        double y,
        double theta,
        Guid goalNodeId,
        double? goalAngle,
        RobotNet10.GlobalPathPlanner.Model.Orientation? startDirection,
        RobotNet10.GlobalPathPlanner.Model.Orientation? finalDirection,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Detects all conflicts between active robots
    /// </summary>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>List of detected conflicts</returns>
    Task<List<Conflict>> DetectConflictsAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Resolves a conflict
    /// </summary>
    /// <param name="conflict">Conflict to resolve</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if resolved successfully</returns>
    Task<bool> ResolveConflictAsync(Conflict conflict, CancellationToken cancellationToken = default);

    /// <summary>
    /// Releases horizon segments into base when safe
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="segmentCount">Number of segments to release</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if released successfully</returns>
    Task<bool> ReleaseHorizonSegmentAsync(
        string robotId,
        int segmentCount,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates robot route (typically for rerouting)
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="newRoute">New route</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if updated successfully</returns>
    Task<bool> UpdateRobotRouteAsync(
        string robotId,
        RobotRoute newRoute,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all active routes for all robots
    /// </summary>
    /// <returns>Dictionary of robot ID to RobotRoute</returns>
    Task<Dictionary<string, RobotRoute>> GetAllActiveRoutesAsync();

    /// <summary>
    /// Gets route for a specific robot
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <returns>RobotRoute if exists, null otherwise</returns>
    Task<RobotRoute?> GetRobotRouteAsync(string robotId);

    /// <summary>
    /// Sets priority for a robot
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="priority">Priority information</param>
    /// <returns>True if set successfully</returns>
    Task<bool> SetRobotPriorityAsync(string robotId, RobotPriority priority);

    /// <summary>
    /// Gets priority for a robot
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <returns>RobotPriority (default if not set)</returns>
    Task<RobotPriority> GetRobotPriorityAsync(string robotId);

    /// <summary>
    /// Removes priority for a robot (resets to default)
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <returns>True if removed successfully</returns>
    Task<bool> RemoveRobotPriorityAsync(string robotId);

    /// <summary>
    /// Evaluates conflicts for resolution optimization
    /// </summary>
    /// <param name="conflicts">List of conflicts to evaluate</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Sorted list of conflicts by priority</returns>
    Task<List<Conflict>> EvaluateConflictsForResolutionAsync(
        List<Conflict> conflicts,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Sends OrderUpdate to robot with new segments
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="newSegments">New segments to add to order</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if sent successfully</returns>
    Task<bool> SendOrderUpdateAsync(
        string robotId,
        List<RouteSegment> newSegments,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Reserves edges for a robot's route segments
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="orderId">Order ID</param>
    /// <param name="segments">Route segments containing edges to reserve</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if reserved successfully</returns>
    Task<bool> ReserveEdgesAsync(
        string robotId,
        string orderId,
        List<RouteSegment> segments,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all reservations for a specific edge
    /// </summary>
    /// <param name="edgeId">Edge ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>List of edge reservations</returns>
    Task<List<EdgeReservation>> GetEdgeReservationsAsync(
        Guid edgeId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks if an edge is available during a time period
    /// </summary>
    /// <param name="edgeId">Edge ID</param>
    /// <param name="fromTime">Start time</param>
    /// <param name="toTime">End time</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if available, false otherwise</returns>
    Task<bool> IsEdgeAvailableAsync(
        Guid edgeId,
        DateTime fromTime,
        DateTime toTime,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Releases all reservations for a robot's order
    /// </summary>
    /// <param name="robotId">Robot ID</param>
    /// <param name="orderId">Order ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if released successfully</returns>
    Task<bool> ReleaseReservationsAsync(
        string robotId,
        string orderId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks and releases horizon segments for robots near end of Base
    /// </summary>
    /// <param name="robotId">Optional: specific robot ID, null for all robots</param>
    /// <param name="cancellationToken">Cancellation token</param>
    Task CheckAndReleaseHorizonsAsync(
        string? robotId = null,
        CancellationToken cancellationToken = default);
}