feat(api): add GET /api/orders/stuck endpoint (BD-694)

- Add OrdersController with stuck orders endpoint
- Implement StuckOrderService for business logic
- Add filters: statusId, status, minHours, maxHours
- Add pagination: limit (default 100), offset
- Register services in DI container
- Add comprehensive unit tests (23 new tests)

TDD: Tests written first, 63 total tests passing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ranganathan2020

src/OrderMonitor.Api/Controllers/OrdersController.cs

@@ -0,0 +1,77 @@
+using Microsoft.AspNetCore.Mvc;
+using OrderMonitor.Core.Interfaces;
+using OrderMonitor.Core.Models;
+
+namespace OrderMonitor.Api.Controllers;
+
+/// <summary>
+/// Controller for order monitoring endpoints.
+/// </summary>
+[ApiController]
+[Route("api/[controller]")]
+[Produces("application/json")]
+public class OrdersController : ControllerBase
+{
+    private readonly IStuckOrderService _stuckOrderService;
+    private readonly ILogger<OrdersController> _logger;
+
+    public OrdersController(IStuckOrderService stuckOrderService, ILogger<OrdersController> logger)
+    {
+        _stuckOrderService = stuckOrderService ?? throw new ArgumentNullException(nameof(stuckOrderService));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <summary>
+    /// Gets all orders currently stuck beyond their threshold.
+    /// </summary>
+    /// <param name="statusId">Filter by specific status ID</param>
+    /// <param name="status">Filter by status name (partial match)</param>
+    /// <param name="minHours">Minimum hours stuck</param>
+    /// <param name="maxHours">Maximum hours stuck</param>
+    /// <param name="limit">Maximum results to return (default: 100)</param>
+    /// <param name="offset">Pagination offset (default: 0)</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>List of stuck orders with pagination info</returns>
+    /// <response code="200">Returns the list of stuck orders</response>
+    /// <response code="500">If an internal error occurs</response>
+    [HttpGet("stuck")]
+    [ProducesResponseType(typeof(StuckOrdersResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status500InternalServerError)]
+    public async Task<ActionResult<StuckOrdersResponse>> GetStuckOrders(
+        [FromQuery] int? statusId = null,
+        [FromQuery] string? status = null,
+        [FromQuery] int? minHours = null,
+        [FromQuery] int? maxHours = null,
+        [FromQuery] int limit = 100,
+        [FromQuery] int offset = 0,
+        CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            _logger.LogInformation(
+                "Getting stuck orders with filters: StatusId={StatusId}, Status={Status}, MinHours={MinHours}, MaxHours={MaxHours}, Limit={Limit}, Offset={Offset}",
+                statusId, status, minHours, maxHours, limit, offset);
+
+            var queryParams = new StuckOrderQueryParams
+            {
+                StatusId = statusId,
+                Status = status,
+                MinHours = minHours,
+                MaxHours = maxHours,
+                Limit = limit,
+                Offset = offset
+            };
+
+            var response = await _stuckOrderService.GetStuckOrdersAsync(queryParams, cancellationToken);
+
+            _logger.LogInformation("Found {Total} stuck orders", response.Total);
+
+            return Ok(response);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Error getting stuck orders");
+            return StatusCode(StatusCodes.Status500InternalServerError, new { error = "An error occurred while retrieving stuck orders" });
+        }
+    }
+}

src/OrderMonitor.Core/Services/StuckOrderService.cs

@@ -0,0 +1,111 @@
+using OrderMonitor.Core.Configuration;
+using OrderMonitor.Core.Interfaces;
+using OrderMonitor.Core.Models;
+
+namespace OrderMonitor.Core.Services;
+
+/// <summary>
+/// Service for detecting and managing stuck orders.
+/// </summary>
+public class StuckOrderService : IStuckOrderService
+{
+    private readonly IOrderRepository _orderRepository;
+
+    public StuckOrderService(IOrderRepository orderRepository)
+    {
+        _orderRepository = orderRepository ?? throw new ArgumentNullException(nameof(orderRepository));
+    }
+
+    /// <inheritdoc />
+    public async Task<StuckOrdersResponse> GetStuckOrdersAsync(
+        StuckOrderQueryParams queryParams,
+        CancellationToken cancellationToken = default)
+    {
+        var stuckOrders = await _orderRepository.GetStuckOrdersAsync(queryParams, cancellationToken);
+        var ordersList = stuckOrders.ToList();
+
+        return new StuckOrdersResponse
+        {
+            Total = ordersList.Count,
+            Items = ordersList,
+            GeneratedAt = DateTime.UtcNow
+        };
+    }
+
+    /// <inheritdoc />
+    public async Task<StuckOrdersSummary> GetStuckOrdersSummaryAsync(CancellationToken cancellationToken = default)
+    {
+        var totalCount = await _orderRepository.GetStuckOrdersCountAsync(cancellationToken);
+
+        // Get all stuck orders for grouping (with high limit for summary)
+        var allStuckOrders = await _orderRepository.GetStuckOrdersAsync(
+            new StuckOrderQueryParams { Limit = 10000, Offset = 0 },
+            cancellationToken);
+
+        var ordersList = allStuckOrders.ToList();
+
+        // Group by threshold type
+        var byThreshold = new Dictionary<string, int>
+        {
+            ["PrepStatuses (6h)"] = ordersList.Count(o => OrderStatusConfiguration.IsPrepStatus(o.StatusId)),
+            ["FacilityStatuses (48h)"] = ordersList.Count(o => OrderStatusConfiguration.IsFacilityStatus(o.StatusId))
+        };
+
+        // Group by status category
+        var categories = OrderStatusConfiguration.GetStatusCategories();
+        var byCategory = new Dictionary<string, int>();
+        foreach (var category in categories)
+        {
+            var categoryStatusIds = category.Value.Select(s => s.StatusId).ToHashSet();
+            var count = ordersList.Count(o => categoryStatusIds.Contains(o.StatusId));
+            if (count > 0)
+            {
+                byCategory[category.Key] = count;
+            }
+        }
+
+        // Top statuses
+        var topStatuses = ordersList
+            .GroupBy(o => new { o.StatusId, o.Status })
+            .Select(g => new StatusCount
+            {
+                StatusId = g.Key.StatusId,
+                Status = g.Key.Status,
+                Count = g.Count()
+            })
+            .OrderByDescending(s => s.Count)
+            .Take(10)
+            .ToList();
+
+        return new StuckOrdersSummary
+        {
+            TotalStuckOrders = totalCount,
+            ByThreshold = byThreshold,
+            ByStatusCategory = byCategory,
+            TopStatuses = topStatuses,
+            GeneratedAt = DateTime.UtcNow
+        };
+    }
+
+    /// <inheritdoc />
+    public async Task<OrderStatusHistoryResponse> GetOrderStatusHistoryAsync(
+        string orderId,
+        CancellationToken cancellationToken = default)
+    {
+        var history = await _orderRepository.GetOrderStatusHistoryAsync(orderId, cancellationToken);
+
+        return new OrderStatusHistoryResponse
+        {
+            OrderId = orderId,
+            History = history
+        };
+    }
+
+    /// <inheritdoc />
+    public bool IsOrderStuck(int statusId, DateTime statusUpdatedAt)
+    {
+        var thresholdHours = OrderStatusConfiguration.GetThresholdHours(statusId);
+        var hoursInStatus = (DateTime.UtcNow - statusUpdatedAt).TotalHours;
+        return hoursInStatus > thresholdHours;
+    }
+}

src/OrderMonitor.Infrastructure/DependencyInjection.cs

@@ -1,6 +1,7 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using OrderMonitor.Core.Interfaces;
+using OrderMonitor.Core.Services;
 using OrderMonitor.Infrastructure.Data;
 
 namespace OrderMonitor.Infrastructure;
@@ -26,6 +27,9 @@ public static IServiceCollection AddInfrastructure(
         // Register repositories
         services.AddScoped<IOrderRepository, OrderRepository>();
 
+        // Register services
+        services.AddScoped<IStuckOrderService, StuckOrderService>();
+
         return services;
     }
 }