Merge pull request #138 from Sea-Haven-Industries/feat/ab/sh-353-dashboard-kpis-stacked

SH-353: Expose dashboard KPI counts

Api.SeaHavenIndustries.Tests/DashboardControllerTests.cs

@@ -0,0 +1,54 @@
+using System.Security.Claims;
+using Api.SeaHavenIndustries.Controllers;
+using FluentAssertions;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Moq;
+using SeaHaven.Services.DTOs;
+using SeaHaven.Services.Interfaces;
+using Xunit;
+
+namespace Api.SeaHavenIndustries.Tests;
+
+public class DashboardControllerTests
+{
+    private static object Prop(object source, string name) =>
+        source.GetType().GetProperty(name)!.GetValue(source)!;
+
+    private static DashboardController NewController(Mock<IDashboardService> service) =>
+        new(service.Object)
+        {
+            ControllerContext = new ControllerContext
+            {
+                HttpContext = new DefaultHttpContext()
+            }
+        };
+
+    // Guards the Stats wire object, not the service DTO. GetKpiCountsAsync and
+    // DashboardStatsDTO already carried these three counts; the regression this
+    // pins is the controller's anonymous response silently dropping them, which
+    // is what left the tiles with nothing to read.
+    [Fact]
+    public async Task GetStats_SerialisesKpiCountsOnWireObject()
+    {
+        var service = new Mock<IDashboardService>();
+        service.Setup(s => s.GetStatsAsync(
+                It.IsAny<ClaimsPrincipal>(),
+                It.IsAny<DashboardStatsQueryDTO>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new DashboardStatsDTO
+            {
+                ScheduledTomorrow = 3,
+                PendingUplifts = 5,
+                AvetaPending = 7
+            });
+
+        var result = await NewController(service).GetStats(
+            new DashboardStatsQueryDTO(), CancellationToken.None);
+
+        var body = result.Should().BeOfType<OkObjectResult>().Subject.Value!;
+        ((int)Prop(body, "scheduledTomorrow")).Should().Be(3);
+        ((int)Prop(body, "pendingUplifts")).Should().Be(5);
+        ((int)Prop(body, "avetaPending")).Should().Be(7);
+    }
+}

Api.SeaHavenIndustries.Tests/DashboardServiceTests.cs

@@ -99,6 +99,55 @@ public class DashboardServiceTests
         stats.Completed.Should().Be(1);
     }
 
+    [Fact]
+    public async Task GetStatsAsync_ExposesKpiCounts_PendingUpliftsCountsPendingStatusOnly()
+    {
+        using var ctx = NewContext();
+        var today = DashboardBusinessTime.Today();
+        var tomorrow = today.AddDays(1);
+
+        // Scheduled-tomorrow tile: one account-1 order scheduled for tomorrow.
+        ctx.workOrders.Add(new WorkOrder
+        {
+            AccountId = 1,
+            LifecycleStatus = Data.SeaHavenIndustries.Enums.LifecycleStatus.Scheduled,
+            ScheduledDate = tomorrow.ToDateTime(TimeOnly.MinValue)
+        });
+
+        // Aveta-pending tile: Aveta-required order in the today/tomorrow window
+        // with no Aveta attachment. Its Dispatch anchors the uplift requests below.
+        var avetaOrder = new WorkOrder
+        {
+            AccountId = 1,
+            AvetaRequired = true,
+            LifecycleStatus = Data.SeaHavenIndustries.Enums.LifecycleStatus.Scheduled,
+            ScheduledDate = today.ToDateTime(TimeOnly.MinValue)
+        };
+        ctx.workOrders.Add(avetaOrder);
+        ctx.SaveChanges();
+
+        var dispatch = new Dispatch { WorkOrderId = avetaOrder.Id, IsDeleted = false };
+        ctx.Set<Dispatch>().Add(dispatch);
+        ctx.SaveChanges();
+
+        // Pending-uplifts tile: only Status == "Pending" is an outstanding uplift
+        // awaiting an approval decision. This test pins the behaviour the code
+        // ships today: a "ChangesRequested" request has been sent back to the
+        // vendor, so it is NOT counted. Whether pendingUplifts should also include
+        // ChangesRequested is an open product call, not a settled review decision.
+        ctx.Set<DispatchUpliftRequest>().AddRange(
+            new DispatchUpliftRequest { DispatchId = dispatch.Id, Status = "Pending", IsDeleted = false },
+            new DispatchUpliftRequest { DispatchId = dispatch.Id, Status = "ChangesRequested", IsDeleted = false });
+        ctx.SaveChanges();
+
+        var stats = await NewService(ctx).GetStatsAsync(
+            AccountUser(1), new DashboardStatsQueryDTO(), CancellationToken.None);
+
+        stats.ScheduledTomorrow.Should().Be(1);
+        stats.AvetaPending.Should().Be(1);
+        stats.PendingUplifts.Should().Be(1);
+    }
+
     [Fact]
     public async Task GetStatsAsync_MissingScopeFailsClosed()
     {

Api.SeaHavenIndustries.Tests/LocationControllerTests.cs

@@ -26,7 +26,7 @@ public class LocationControllerTests
     public async Task GetLocationList_ReturnsPaginationEnvelopeWithServiceData()
     {
         var service = new Mock<ILocationService>();
-        service.Setup(s => s.GetLocationListPagedAsync(1, 10, "a", null, It.IsAny<CancellationToken>()))
+        service.Setup(s => s.GetLocationListPagedAsync(1, 10, "a", null, It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
                .ReturnsAsync(new PagedResult<LocationDTO>
                {
                    Items = new List<LocationDTO> { new() { Id = 1, Name = "Site" } },
@@ -49,7 +49,7 @@ public class LocationControllerTests
     public async Task GetLocationList_PassesStatesFilterToService()
     {
         var service = new Mock<ILocationService>();
-        service.Setup(s => s.GetLocationListPagedAsync(1, 10, null, "tx, mo", It.IsAny<CancellationToken>()))
+        service.Setup(s => s.GetLocationListPagedAsync(1, 10, null, "tx, mo", It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
                .ReturnsAsync(new PagedResult<LocationDTO>
                {
                    Items = new List<LocationDTO>(),
@@ -58,7 +58,7 @@ public class LocationControllerTests
                    PageSize = 10
                });
 
-        var result = await NewController(service).GetLocationList(null, 1, 10, "tx, mo", CancellationToken.None);
+        var result = await NewController(service).GetLocationList(null, 1, 10, "tx, mo", cancellationToken: CancellationToken.None);
 
         result.Should().BeOfType<OkObjectResult>();
         service.VerifyAll();
@@ -68,13 +68,13 @@ public class LocationControllerTests
     public async Task GetLocationList_WhenStatesInvalid_ReturnsExistingValidationErrorShape()
     {
         var service = new Mock<ILocationService>();
-        service.Setup(s => s.GetLocationListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<string?>(), It.IsAny<CancellationToken>()))
+        service.Setup(s => s.GetLocationListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<string?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
                .ThrowsAsync(new ValidationException(new[]
                {
                    new ValidationFailure("states", "states must be valid US postal abbreviations: ZZ.")
                }));
 
-        var result = await NewController(service).GetLocationList(null, 1, 10, "ZZ", CancellationToken.None);
+        var result = await NewController(service).GetLocationList(null, 1, 10, "ZZ", cancellationToken: CancellationToken.None);
 
         var bad = result.Should().BeOfType<BadRequestObjectResult>().Subject;
         var response = bad.Value.Should().BeOfType<Response>().Subject;
@@ -200,4 +200,90 @@ public class LocationControllerTests
         var notFound = result.Should().BeOfType<NotFoundObjectResult>().Subject;
         notFound.Value.Should().BeOfType<Response>().Subject.Message.Should().Be("Location not found");
     }
+
+    [Fact]
+    public async Task GetLocationList_ForwardsSortParamsToService()
+    {
+        var service = new Mock<ILocationService>();
+        service.Setup(s => s.GetLocationListPagedAsync(1, 10, "", null, It.IsAny<CancellationToken>(), "city", "desc"))
+               .ReturnsAsync(new PagedResult<LocationDTO> { Items = new List<LocationDTO>(), TotalCount = 0, Page = 1, PageSize = 10 });
+
+        await NewController(service).GetLocationList(sortBy: "city", sortDirection: "desc", cancellationToken: CancellationToken.None);
+
+        service.Verify(s => s.GetLocationListPagedAsync(1, 10, "", null, It.IsAny<CancellationToken>(), "city", "desc"), Times.Once);
+    }
+
+    [Fact]
+    public async Task GetLocationList_WhenSortInvalid_ReturnsExistingValidationErrorShape()
+    {
+        var service = new Mock<ILocationService>();
+        service.Setup(s => s.GetLocationListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<string?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
+               .ThrowsAsync(new ValidationException(new[]
+               {
+                   new ValidationFailure("sortBy", "sortBy must be one of: code, client, address, city, state, poc.")
+               }));
+
+        var result = await NewController(service).GetLocationList(sortBy: "nope", cancellationToken: CancellationToken.None);
+
+        var bad = result.Should().BeOfType<BadRequestObjectResult>().Subject;
+        var response = bad.Value.Should().BeOfType<Response>().Subject;
+        response.Status.Should().Be("Validation Error");
+        response.Message.Should().Contain("sortBy");
+    }
+
+    [Fact]
+    public async Task GetLocationList_ProjectsClientAccountNameAndSiteFields()
+    {
+        var service = new Mock<ILocationService>();
+        service.Setup(s => s.GetLocationListPagedAsync(1, 10, "", null, It.IsAny<CancellationToken>(), null, null))
+               .ReturnsAsync(new PagedResult<LocationDTO>
+               {
+                   Items = new List<LocationDTO>
+                   {
+                       new()
+                       {
+                           Id = 1,
+                           Name = "STL8",
+                           Address1 = "9 River Rd",
+                           City = "St. Louis",
+                           State = "MO",
+                           Zip = "63101",
+                           PhoneNumber = "555-0100",
+                           Email = "poc@example.com",
+                           AccountId = 3,
+                           AccountName = "Acme Co",
+                           Contacts = new List<SiteContactResponseDTO>
+                           {
+                               new() { Id = 10, Name = "Cara Lane", Phone = "555-0100" },
+                               new() { Id = 11, Name = "Alan Ford", Phone = "555-0101" }
+                           }
+                       }
+                   },
+                   TotalCount = 1,
+                   Page = 1,
+                   PageSize = 10
+               });
+
+        var result = await NewController(service).GetLocationList(cancellationToken: CancellationToken.None);
+
+        var ok = result.Should().BeOfType<OkObjectResult>().Subject;
+        using var json = System.Text.Json.JsonSerializer.SerializeToDocument(ok.Value);
+        var row = json.RootElement.GetProperty("Data").EnumerateArray().Single();
+
+        row.GetProperty("Name").GetString().Should().Be("STL8", "the site code is the legacy Name field");
+        row.GetProperty("Address").GetString().Should().Be("9 River Rd");
+        row.GetProperty("City").GetString().Should().Be("St. Louis");
+        row.GetProperty("State").GetString().Should().Be("MO");
+        row.GetProperty("ZipCode").GetString().Should().Be("63101");
+        row.GetProperty("Phone").GetString().Should().Be("555-0100");
+        row.GetProperty("ContactEmail").GetString().Should().Be("poc@example.com");
+        row.GetProperty("Contact").GetString().Should().Be("Cara Lane", "the first ordered contact is the legacy Contact field");
+        row.GetProperty("AccountId").GetInt32().Should().Be(3);
+        row.GetProperty("ClientName").GetString().Should().Be("Acme Co");
+        row.GetProperty("AccountName").GetString().Should().Be("Acme Co");
+        var contacts = row.GetProperty("Contacts");
+        contacts.GetArrayLength().Should().Be(2);
+        contacts[0].GetProperty("Name").GetString().Should().Be("Cara Lane");
+        contacts[1].GetProperty("Name").GetString().Should().Be("Alan Ford");
+    }
 }

Api.SeaHavenIndustries.Tests/LocationDataServiceTests.cs

@@ -86,4 +86,129 @@ public class LocationDataServiceTests
         totalCount.Should().Be(2);
         items.Select(l => l.State).Should().BeEquivalentTo("indiana", "MO");
     }
+
+    private static async Task SeedRegistryAsync(ApplicationDbContext ctx)
+    {
+        ctx.Accounts.AddRange(
+            new Accounts { Id = 1, Name = "Acme Co", IsDeleted = false },
+            new Accounts { Id = 2, Name = "Borealis LLC", IsDeleted = false });
+        ctx.Locations.AddRange(
+            new Locations { Id = 10, Name = "STL8", Address1 = "9 River Rd", City = "St. Louis", State = "MO", AccountId = 1 },
+            new Locations { Id = 11, Name = "DFW8", Address1 = "2 Prairie Ave", City = "Dallas", State = "TX", AccountId = 2 },
+            new Locations { Id = 12, Name = "IND9", Address1 = "5 Circle Blvd", City = "Indianapolis", State = "IN", AccountId = 1 },
+            new Locations { Id = 13, Name = "MIA2", Address1 = "1 Bay Dr", City = "Miami", State = "FL", AccountId = 2 });
+        ctx.Contacts.AddRange(
+            new Contacts { Id = 100, LocationId = 10, SiteContactOrder = 0, FirstName = "Cara Lane", PhoneNumber = "555-0001" },
+            new Contacts { Id = 101, LocationId = 10, SiteContactOrder = 1, FirstName = "Alan Ford", PhoneNumber = "555-0002" },
+            new Contacts { Id = 102, LocationId = 11, SiteContactOrder = 1, FirstName = "Zoe Park", PhoneNumber = "555-0003" },
+            new Contacts { Id = 103, LocationId = 11, SiteContactOrder = 0, FirstName = "Removed Poc", PhoneNumber = "555-0004", IsDeleted = true },
+            new Contacts { Id = 104, LocationId = 12, SiteContactOrder = 0, FirstName = "Bob Quinn", PhoneNumber = "555-0005" });
+        await ctx.SaveChangesAsync();
+    }
+
+    [Theory]
+    [InlineData("STL", new[] { 10 }, "site code")]
+    [InlineData("Borealis", new[] { 11, 13 }, "client name")]
+    [InlineData("Prairie", new[] { 11 }, "street address")]
+    [InlineData("Miami", new[] { 13 }, "city")]
+    public async Task GetListPagedAsync_SearchMatchesCodeClientAddressAndCity(string term, int[] expectedIds, string becauseField)
+    {
+        await using var ctx = NewContext();
+        await SeedRegistryAsync(ctx);
+
+        var (items, totalCount) = await new LocationDataService(ctx)
+            .GetListPagedAsync(1, 10, term, null, CancellationToken.None);
+
+        totalCount.Should().Be(expectedIds.Length, $"search must match the {becauseField}");
+        items.Select(l => l.Id).Should().BeEquivalentTo(expectedIds);
+    }
+
+    [Theory]
+    [InlineData("code", 11, 12, 13, 10)]
+    [InlineData("client", 10, 12, 11, 13)]
+    [InlineData("address", 13, 11, 12, 10)]
+    [InlineData("city", 11, 12, 13, 10)]
+    [InlineData("state", 13, 12, 10, 11)]
+    [InlineData("poc", 13, 12, 10, 11)]
+    public async Task GetListPagedAsync_SortByAllowlistedColumn_OrdersAscending_WithIdTiebreak(
+        string sortBy, params int[] expectedIds)
+    {
+        await using var ctx = NewContext();
+        await SeedRegistryAsync(ctx);
+
+        var (items, _) = await new LocationDataService(ctx)
+            .GetListPagedAsync(1, 10, null, null, CancellationToken.None, sortBy, "asc");
+
+        items.Select(l => l.Id).Should().ContainInOrder(expectedIds);
+    }
+
+    [Fact]
+    public async Task GetListPagedAsync_SortByPoc_IgnoresDeletedContacts_AndSortsByFirstActiveContact()
+    {
+        await using var ctx = NewContext();
+        await SeedRegistryAsync(ctx);
+
+        var (items, _) = await new LocationDataService(ctx)
+            .GetListPagedAsync(1, 10, null, null, CancellationToken.None, "poc", "asc");
+
+        // DFW8's order-0 row is soft deleted, so its POC is "Zoe Park" (order 1) and it must
+        // sort last; including the deleted row ("Removed Poc") would instead place it second.
+        items.Select(l => l.Id).Should().ContainInOrder(13, 12, 10, 11);
+    }
+
+    [Fact]
+    public async Task GetListPagedAsync_SortByClient_Desc_ReversesAccountOrder()
+    {
+        await using var ctx = NewContext();
+        await SeedRegistryAsync(ctx);
+
+        var (items, _) = await new LocationDataService(ctx)
+            .GetListPagedAsync(1, 10, null, null, CancellationToken.None, "client", "desc");
+
+        items.Select(l => l.Id).Should().ContainInOrder(new[] { 11, 13, 10, 12 });
+    }
+
+    [Fact]
+    public async Task GetListPagedAsync_UnknownSortColumn_FallsBackToLegacyCodeOrder()
+    {
+        await using var ctx = NewContext();
+        await SeedRegistryAsync(ctx);
+
+        var (items, _) = await new LocationDataService(ctx)
+            .GetListPagedAsync(1, 10, null, null, CancellationToken.None, "not-a-column", "sideways");
+
+        items.Select(l => l.Name).Should().ContainInOrder("DFW8", "IND9", "MIA2", "STL8");
+    }
+
+    [Fact]
+    public async Task GetListPagedAsync_EqualSortValues_BreakTiesById_AcrossPages()
+    {
+        await using var ctx = NewContext();
+        ctx.Locations.AddRange(
+            new Locations { Id = 20, Name = "HOU1", City = "Dallas" },
+            new Locations { Id = 21, Name = "AUS3", City = "Dallas" },
+            new Locations { Id = 22, Name = "ELP4", City = "Dallas" });
+        await ctx.SaveChangesAsync();
+
+        var service = new LocationDataService(ctx);
+
+        var (page1, totalCount) = await service.GetListPagedAsync(1, 2, null, null, CancellationToken.None, "city", "asc");
+        var (page2, _) = await service.GetListPagedAsync(2, 2, null, null, CancellationToken.None, "city", "asc");
+
+        totalCount.Should().Be(3);
+        page1.Select(l => l.Id).Should().ContainInOrder(20, 21);
+        page2.Select(l => l.Id).Should().ContainInOrder(22);
+    }
+
+    [Fact]
+    public async Task GetListPagedAsync_ListLoadIncludesAccountNameForProjection()
+    {
+        await using var ctx = NewContext();
+        await SeedRegistryAsync(ctx);
+
+        var (items, _) = await new LocationDataService(ctx)
+            .GetListPagedAsync(1, 10, null, null, CancellationToken.None);
+
+        items.Single(l => l.Id == 10).Account!.Name.Should().Be("Acme Co");
+    }
 }

Api.SeaHavenIndustries.Tests/LocationServiceTests.cs

@@ -131,8 +131,8 @@ public class LocationServiceTests
     {
         var data = new Mock<ILocationDataService>();
         IReadOnlyCollection<string>? captured = default;
-        data.Setup(d => d.GetListPagedAsync(1, 10, null, It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>()))
-            .Callback<int, int, string?, IReadOnlyCollection<string>?, CancellationToken>((_, _, _, states, _) => captured = states)
+        data.Setup(d => d.GetListPagedAsync(1, 10, null, It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
+            .Callback<int, int, string?, IReadOnlyCollection<string>?, CancellationToken, string?, string?>((_, _, _, states, _, _, _) => captured = states)
             .ReturnsAsync((new List<Locations>(), 0));
 
         await NewServiceWithSpy(data.Object).GetLocationListPagedAsync(1, 10, null, " tx , Mo ,,TX,  ", CancellationToken.None);
@@ -149,8 +149,8 @@ public class LocationServiceTests
         {
             var data = new Mock<ILocationDataService>();
             IReadOnlyCollection<string>? captured = default;
-            data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>()))
-                .Callback<int, int, string?, IReadOnlyCollection<string>?, CancellationToken>((_, _, _, stateFilter, _) => captured = stateFilter)
+            data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
+                .Callback<int, int, string?, IReadOnlyCollection<string>?, CancellationToken, string?, string?>((_, _, _, stateFilter, _, _, _) => captured = stateFilter)
                 .ReturnsAsync((new List<Locations>(), 0));
 
             var page = await NewServiceWithSpy(data.Object).GetLocationListPagedAsync(1, 10, "search", states, CancellationToken.None);
@@ -173,14 +173,14 @@ public class LocationServiceTests
                 && e.ErrorMessage.Contains("ZZ")
                 && e.ErrorMessage.Contains("QQ")
                 && !e.ErrorMessage.Contains("TX"));
-        data.Verify(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>()), Times.Never);
+        data.Verify(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 
     [Fact]
     public async Task GetLocationListPagedAsync_AcceptsAllFiftyStateCodes()
     {
         var data = new Mock<ILocationDataService>();
-        data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>()))
+        data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
             .ReturnsAsync((new List<Locations>(), 0));
 
         var allStates = string.Join(",", SeaHaven.Services.Helpers.UsStateCodes.All);
@@ -533,4 +533,97 @@ public class LocationServiceTests
         again.Should().BeFalse();
         ctx.Locations.Should().BeEmpty();
     }
+
+    [Fact]
+    public async Task GetLocationListPagedAsync_NormalizesAndForwardsSortToDataService()
+    {
+        var data = new Mock<ILocationDataService>();
+        string? capturedSort = "sentinel";
+        string? capturedDirection = "sentinel";
+        data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
+            .Callback<int, int, string?, IReadOnlyCollection<string>?, CancellationToken, string?, string?>((_, _, _, _, _, sortBy, sortDirection) =>
+            {
+                capturedSort = sortBy;
+                capturedDirection = sortDirection;
+            })
+            .ReturnsAsync((new List<Locations>(), 0));
+
+        await NewServiceWithSpy(data.Object).GetLocationListPagedAsync(1, 10, null, cancellationToken: CancellationToken.None, sortBy: " POC ", sortDirection: " DESC ");
+
+        capturedSort.Should().Be("poc");
+        capturedDirection.Should().Be("desc");
+    }
+
+    [Theory]
+    [InlineData(null, null)]
+    [InlineData("", "  ")]
+    public async Task GetLocationListPagedAsync_BlankOrDefaultSort_PassesNormalizedDefaults(
+        string? sortBy,
+        string? sortDirection)
+    {
+        var data = new Mock<ILocationDataService>();
+        string? capturedSort = "sentinel";
+        string? capturedDirection = "sentinel";
+        data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
+            .Callback<int, int, string?, IReadOnlyCollection<string>?, CancellationToken, string?, string?>((_, _, _, _, _, s, d) =>
+            {
+                capturedSort = s;
+                capturedDirection = d;
+            })
+            .ReturnsAsync((new List<Locations>(), 0));
+
+        await NewServiceWithSpy(data.Object).GetLocationListPagedAsync(1, 10, null, cancellationToken: CancellationToken.None, sortBy: sortBy, sortDirection: sortDirection);
+
+        capturedSort.Should().BeNull("a blank sort column must keep the legacy ordering");
+        capturedDirection.Should().Be("asc");
+    }
+
+    [Theory]
+    [InlineData("rating")]
+    [InlineData("password; drop table locations")]
+    public async Task GetLocationListPagedAsync_InvalidSortBy_ThrowsValidationAndNeverQueries(string sortBy)
+    {
+        var data = new Mock<ILocationDataService>();
+
+        var act = () => NewServiceWithSpy(data.Object).GetLocationListPagedAsync(1, 10, null, cancellationToken: CancellationToken.None, sortBy: sortBy);
+
+        (await act.Should().ThrowAsync<FluentValidation.ValidationException>())
+            .Which.Errors.Should().ContainSingle(e =>
+                e.PropertyName == "sortBy"
+                && e.ErrorMessage.Contains("code")
+                && e.ErrorMessage.Contains("poc"));
+        data.Verify(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+    }
+
+    [Theory]
+    [InlineData("ascending")]
+    [InlineData("DESC; drop table locations")]
+    public async Task GetLocationListPagedAsync_InvalidSortDirection_ThrowsValidationAndNeverQueries(string sortDirection)
+    {
+        var data = new Mock<ILocationDataService>();
+
+        var act = () => NewServiceWithSpy(data.Object).GetLocationListPagedAsync(1, 10, null, cancellationToken: CancellationToken.None, sortBy: "city", sortDirection: sortDirection);
+
+        (await act.Should().ThrowAsync<FluentValidation.ValidationException>())
+            .Which.Errors.Should().ContainSingle(e =>
+                e.PropertyName == "sortDirection"
+                && e.ErrorMessage.Contains("asc")
+                && e.ErrorMessage.Contains("desc"));
+        data.Verify(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task GetLocationListPagedAsync_MapsClientAccountNameIntoRows()
+    {
+        using var ctx = NewContext();
+        SeedAccount(ctx, 9, "Acme Co");
+        SeedLocation(ctx, "Alpha Site", "Austin").AccountId = 9;
+        await ctx.SaveChangesAsync();
+
+        var page = await NewService(ctx).GetLocationListPagedAsync(1, 10, null, cancellationToken: CancellationToken.None);
+
+        var row = page.Items.Should().ContainSingle().Subject;
+        row.AccountId.Should().Be(9);
+        row.AccountName.Should().Be("Acme Co");
+    }
 }

Api.SeaHavenIndustries.Tests/LocationSiteContactsTests.cs

@@ -430,7 +430,7 @@ public class LocationSiteContactsTests
     public async Task List_LoadsPageContactsInSingleBatchedRead()
     {
         var data = new Mock<ILocationDataService>();
-        data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>()))
+        data.Setup(d => d.GetListPagedAsync(It.IsAny<int>(), It.IsAny<int>(), It.IsAny<string?>(), It.IsAny<IReadOnlyCollection<string>?>(), It.IsAny<CancellationToken>(), It.IsAny<string?>(), It.IsAny<string?>()))
             .ReturnsAsync((new List<Locations>
             {
                 new() { Id = 1, Name = "One" },

Api.SeaHavenIndustries/Controllers/DashboardController.cs

@@ -30,6 +30,9 @@ namespace Api.SeaHavenIndustries.Controllers
                 open = stats.Open,
                 notDispatched = stats.NotDispatched,
                 completed = stats.Completed,
+                scheduledTomorrow = stats.ScheduledTomorrow,
+                pendingUplifts = stats.PendingUplifts,
+                avetaPending = stats.AvetaPending,
                 breakdown = stats.Breakdown,
                 dueCount = stats.DueCount,
                 completedDueCount = stats.CompletedDueCount,

Api.SeaHavenIndustries/Controllers/LocationController.cs

@@ -36,11 +36,11 @@ namespace Api.SeaHavenIndustries.Controllers
         }
 
         [HttpGet("GetLocationList")]
-        public async Task<IActionResult> GetLocationList(string? search = "", int page = 1, int pageSize = 10, string? states = null, CancellationToken cancellationToken = default)
+        public async Task<IActionResult> GetLocationList(string? search = "", int page = 1, int pageSize = 10, string? states = null, string? sortBy = null, string? sortDirection = null, CancellationToken cancellationToken = default)
         {
             try
             {
-                var pagedResult = await _locationService.GetLocationListPagedAsync(page, pageSize, search, states, cancellationToken);
+                var pagedResult = await _locationService.GetLocationListPagedAsync(page, pageSize, search, states, cancellationToken, sortBy, sortDirection);
 
                 var data = pagedResult.Items.Select(l => new
                 {
@@ -58,6 +58,8 @@ namespace Api.SeaHavenIndustries.Controllers
                     ContactEmail = l.Email,
                     Status = l.Status,
                     AccountId = l.AccountId,
+                    ClientName = l.AccountName,
+                    AccountName = l.AccountName,
                     Contacts = l.Contacts?.Select(c => new { c.Id, c.Name, c.Phone }).ToList()
                 });
 

SeaHaven.DataServices/Implementation/DashboardDataService.cs

@@ -88,6 +88,70 @@ namespace SeaHaven.DataServices.Implementation
                 .ToListAsync(cancellationToken);
         }
 
+        public async Task<DashboardKpiCounts> GetKpiCountsAsync(
+            int? accountId,
+            string? dispatcherId,
+            DateOnly today,
+            CancellationToken cancellationToken)
+        {
+            var tomorrow = today.AddDays(1);
+            var dayAfterTomorrow = tomorrow.AddDays(1);
+            var workOrders = WorkOrderBoardQueryFilters.ApplyBaseScope(_context.workOrders.AsNoTracking());
+            if (accountId is int scopedAccountId)
+                workOrders = WorkOrderBoardQueryFilters.ApplyAccountScope(workOrders, scopedAccountId);
+            if (dispatcherId != null)
+                workOrders = workOrders.Where(w => w.AssignTo == dispatcherId);
+
+            var scheduledTomorrow = await workOrders
+                .Where(w => w.ScheduledDate >= tomorrow.ToDateTime(TimeOnly.MinValue)
+                    && w.ScheduledDate < dayAfterTomorrow.ToDateTime(TimeOnly.MinValue))
+                .CountAsync(cancellationToken);
+
+            var avetaPending = await workOrders
+                .Where(w => w.ScheduledDate >= today.ToDateTime(TimeOnly.MinValue)
+                    && w.ScheduledDate < dayAfterTomorrow.ToDateTime(TimeOnly.MinValue)
+                    && w.AvetaRequired
+                    && w.LifecycleStatus != LifecycleStatus.Completed
+                    && w.LifecycleStatus != LifecycleStatus.Canceled
+                    && (w.LifecycleStatus != null
+                        || ((w.LegacyStatus ?? w.Status) != "Done"
+                            && (w.LegacyStatus ?? w.Status) != "Completed"
+                            && (w.LegacyStatus ?? w.Status) != "Complete"
+                            && (w.LegacyStatus ?? w.Status) != "Closed"
+                            && (w.LegacyStatus ?? w.Status) != "Canceled"
+                            && (w.LegacyStatus ?? w.Status) != "Cancelled"))
+                    && !w.workOrderAttachments!.Any(attachment =>
+                        (attachment.IsDeleted == null || attachment.IsDeleted == false)
+                        && attachment.Category == WorkOrderMediaCategory.Aveta))
+                .CountAsync(cancellationToken);
+
+            var pendingUplifts = _context.DispatchUpliftRequests
+                .AsNoTracking()
+                .Where(request => request.Status == "Pending"
+                    && (request.IsDeleted == null || request.IsDeleted == false)
+                    && request.Dispatch != null
+                    && (request.Dispatch.IsDeleted == null || request.Dispatch.IsDeleted == false));
+            if (accountId is int account)
+            {
+                pendingUplifts = pendingUplifts.Where(request =>
+                    (request.Dispatch!.WorkOrder != null && request.Dispatch.WorkOrder.AccountId == account)
+                    || request.Dispatch.DispatchWorkOrders!.Any(link =>
+                        link.WorkOrder != null && link.WorkOrder.AccountId == account));
+            }
+            if (dispatcherId != null)
+            {
+                pendingUplifts = pendingUplifts.Where(request =>
+                    (request.Dispatch!.WorkOrder != null && request.Dispatch.WorkOrder.AssignTo == dispatcherId)
+                    || request.Dispatch.DispatchWorkOrders!.Any(link =>
+                        link.WorkOrder != null && link.WorkOrder.AssignTo == dispatcherId));
+            }
+
+            return new DashboardKpiCounts(
+                scheduledTomorrow,
+                await pendingUplifts.CountAsync(cancellationToken),
+                avetaPending);
+        }
+
         public async Task<IReadOnlyList<DashboardDispatcherWorkload>> GetDispatcherWorkloadAsync(
             int? accountId,
             string? dispatcherId,

SeaHaven.DataServices/Implementation/LocationDataService.cs

@@ -136,15 +136,21 @@ namespace SeaHaven.DataServices.Implementation
             int pageSize,
             string? search,
             IReadOnlyCollection<string>? states,
-            CancellationToken cancellationToken)
+            CancellationToken cancellationToken,
+            string? sortBy = null,
+            string? sortDirection = null)
         {
-            var query = _context.Locations.AsNoTracking();
+            IQueryable<Locations> query = _context.Locations
+                .AsNoTracking()
+                .Include(l => l.Account);
 
             if (!string.IsNullOrWhiteSpace(search))
             {
                 query = query.Where(l =>
                     l.Name!.Contains(search) ||
-                    l.City!.Contains(search));
+                    l.Address1!.Contains(search) ||
+                    l.City!.Contains(search) ||
+                    l.Account != null && l.Account.Name!.Contains(search));
             }
 
             if (states is { Count: > 0 })
@@ -152,9 +158,10 @@ namespace SeaHaven.DataServices.Implementation
                 query = query.Where(l => l.State != null && states.Contains(l.State.Trim().ToUpper()));
             }
 
+            query = ApplyListSort(query, sortBy, sortDirection);
+
             var totalCount = await query.CountAsync(cancellationToken);
             var items = await query
-                .OrderBy(l => l.Name)
                 .Skip((page - 1) * pageSize)
                 .Take(pageSize)
                 .ToListAsync(cancellationToken);
@@ -162,6 +169,33 @@ namespace SeaHaven.DataServices.Implementation
             return (items, totalCount);
         }
 
+        private static IQueryable<Locations> ApplyListSort(IQueryable<Locations> query, string? sortBy, string? sortDirection)
+        {
+            var descending = string.Equals(sortDirection?.Trim(), "desc", StringComparison.OrdinalIgnoreCase);
+            IOrderedQueryable<Locations> ordered = (sortBy?.Trim().ToLowerInvariant()) switch
+            {
+                "code" => descending ? query.OrderByDescending(l => l.Name) : query.OrderBy(l => l.Name),
+                "client" => descending ? query.OrderByDescending(l => l.Account!.Name) : query.OrderBy(l => l.Account!.Name),
+                "address" => descending ? query.OrderByDescending(l => l.Address1) : query.OrderBy(l => l.Address1),
+                "city" => descending ? query.OrderByDescending(l => l.City) : query.OrderBy(l => l.City),
+                "state" => descending ? query.OrderByDescending(l => l.State) : query.OrderBy(l => l.State),
+                "poc" => descending
+                    ? query.OrderByDescending(FirstActiveContactName)
+                    : query.OrderBy(FirstActiveContactName),
+                _ => query.OrderBy(l => l.Name)
+            };
+
+            return ordered.ThenBy(l => l.Id);
+        }
+
+        private static readonly System.Linq.Expressions.Expression<Func<Locations, string?>> FirstActiveContactName =
+            l => l.Contacts
+                .Where(c => c.IsDeleted != true)
+                .OrderBy(c => c.SiteContactOrder)
+                .ThenBy(c => c.Id)
+                .Select(c => c.FirstName)
+                .FirstOrDefault();
+
         public async Task<Locations?> GetDetailByIdAsync(int id, CancellationToken cancellationToken)
         {
             return await _context.Locations

SeaHaven.DataServices/Interfaces/IDashboardDataService.cs

@@ -8,6 +8,12 @@ namespace SeaHaven.DataServices.Interfaces
             int? accountId,
             CancellationToken cancellationToken);
 
+        Task<DashboardKpiCounts> GetKpiCountsAsync(
+            int? accountId,
+            string? dispatcherId,
+            DateOnly today,
+            CancellationToken cancellationToken);
+
         Task<IReadOnlyList<DashboardWorkOrder>> GetDashboardWorkOrdersAsync(
             int? accountId,
             string? dispatcherId,
@@ -53,4 +59,9 @@ namespace SeaHaven.DataServices.Interfaces
         public int NotDispatched { get; set; }
         public int Completed { get; set; }
     }
+
+    public sealed record DashboardKpiCounts(
+        int ScheduledTomorrow,
+        int PendingUplifts,
+        int AvetaPending);
 }

SeaHaven.DataServices/Interfaces/ILocationDataService.cs

@@ -34,7 +34,11 @@ namespace SeaHaven.DataServices.Interfaces
         Task<bool> ExistsAsync(int id);
         Task<int> CountAsync();
 
-        Task<(List<Locations> Items, int TotalCount)> GetListPagedAsync(int page, int pageSize, string? search, IReadOnlyCollection<string>? states, CancellationToken cancellationToken);
+        /// <summary>
+        /// Sort keys are validated upstream; unknown or null keys fall back to the legacy code order.
+        /// Sort options trail the token so existing call sites stay source-compatible.
+        /// </summary>
+        Task<(List<Locations> Items, int TotalCount)> GetListPagedAsync(int page, int pageSize, string? search, IReadOnlyCollection<string>? states, CancellationToken cancellationToken, string? sortBy = null, string? sortDirection = null);
         Task<Locations?> GetDetailByIdAsync(int id, CancellationToken cancellationToken);
         Task<Locations?> GetByIdForUpdateAsync(int id, CancellationToken cancellationToken);
 

SeaHaven.Services/DTOs/DashboardDTOs.cs

@@ -100,6 +100,9 @@ namespace SeaHaven.Services.DTOs
         public int Open { get; set; }
         public int NotDispatched { get; set; }
         public int Completed { get; set; }
+        public int ScheduledTomorrow { get; set; }
+        public int PendingUplifts { get; set; }
+        public int AvetaPending { get; set; }
         public DashboardBreakdownDTO Breakdown { get; set; } = new();
         public int DueCount { get; set; }
         public int CompletedDueCount { get; set; }

SeaHaven.Services/DTOs/LocationDTOs.cs

@@ -14,6 +14,7 @@ namespace SeaHaven.Services.DTOs
         public string? Email { get; set; }
         public string? Status { get; set; }
         public int? AccountId { get; set; }
+        public string? AccountName { get; set; }
         public DateTime? CreatedDate { get; set; }
         public string? CreatedBy { get; set; }
 

SeaHaven.Services/Implementation/DashboardService.cs

@@ -35,6 +35,11 @@ namespace SeaHaven.Services.Implementation
                 throw new WorkOrderBoardValidationException("Forbidden", "Dispatcher identity is required.");
 
             var counts = await _dataService.GetWorkOrderCountsAsync(accountId, cancellationToken);
+            var kpis = await _dataService.GetKpiCountsAsync(
+                accountId,
+                dispatcherId,
+                DashboardBusinessTime.Today(),
+                cancellationToken);
             var workOrders = await _dataService.GetDashboardWorkOrdersAsync(
                 accountId,
                 dispatcherId,
@@ -51,6 +56,9 @@ namespace SeaHaven.Services.Implementation
                 Open = useMetrics ? metrics.Open : counts.Open,
                 NotDispatched = useMetrics ? metrics.NotDispatched : counts.NotDispatched,
                 Completed = useMetrics ? metrics.Completed : counts.Completed,
+                ScheduledTomorrow = kpis.ScheduledTomorrow,
+                PendingUplifts = kpis.PendingUplifts,
+                AvetaPending = kpis.AvetaPending,
                 Breakdown = metrics.Breakdown,
                 DueCount = metrics.DueCount,
                 CompletedDueCount = metrics.CompletedDueCount,

SeaHaven.Services/Implementation/LocationService.cs

@@ -166,11 +166,15 @@ namespace SeaHaven.Services.Implementation
             int pageSize,
             string? search,
             string? states = null,
-            CancellationToken cancellationToken = default)
+            CancellationToken cancellationToken = default,
+            string? sortBy = null,
+            string? sortDirection = null)
         {
             var stateFilter = NormalizeStateFilter(states);
             var storageStateFilter = stateFilter == null ? null : UsStateCodes.ExpandStorageValues(stateFilter);
-            var (items, totalCount) = await _locationDataService.GetListPagedAsync(page, pageSize, search, storageStateFilter, cancellationToken);
+            var sort = NormalizeSortColumn(sortBy);
+            var direction = NormalizeSortDirection(sortDirection);
+            var (items, totalCount) = await _locationDataService.GetListPagedAsync(page, pageSize, search, storageStateFilter, cancellationToken, sort, direction);
 
             // SH-138: one bounded contact read for the whole page, never per row.
             var contactsByLocation = await GetSiteContactsByLocationIdsAsync(items, cancellationToken);
@@ -184,6 +188,42 @@ namespace SeaHaven.Services.Implementation
             };
         }
 
+        internal static readonly IReadOnlyCollection<string> SortableColumns = new[] { "code", "client", "address", "city", "state", "poc" };
+
+        internal static string? NormalizeSortColumn(string? sortBy)
+        {
+            if (string.IsNullOrWhiteSpace(sortBy))
+                return null;
+
+            var normalized = sortBy.Trim().ToLowerInvariant();
+            if (!SortableColumns.Contains(normalized))
+            {
+                throw new ValidationException(new[]
+                {
+                    new ValidationFailure("sortBy", $"sortBy must be one of: {string.Join(", ", SortableColumns)}.")
+                });
+            }
+
+            return normalized;
+        }
+
+        internal static string NormalizeSortDirection(string? sortDirection)
+        {
+            if (string.IsNullOrWhiteSpace(sortDirection))
+                return "asc";
+
+            var normalized = sortDirection.Trim().ToLowerInvariant();
+            if (normalized != "asc" && normalized != "desc")
+            {
+                throw new ValidationException(new[]
+                {
+                    new ValidationFailure("sortDirection", "sortDirection must be asc or desc.")
+                });
+            }
+
+            return normalized;
+        }
+
         internal static IReadOnlyCollection<string>? NormalizeStateFilter(string? states)
         {
             if (string.IsNullOrWhiteSpace(states))
@@ -503,6 +543,7 @@ namespace SeaHaven.Services.Implementation
                 Email = location.Email,
                 Status = location.Status,
                 AccountId = location.AccountId,
+                AccountName = location.Account?.Name,
                 CreatedDate = location.CreatedDate,
                 CreatedBy = location.createdby,
                 Contacts = contactsByLocation != null && contactsByLocation.TryGetValue(location.Id, out var contacts)

SeaHaven.Services/Interfaces/ILocationService.cs

@@ -19,7 +19,7 @@ namespace SeaHaven.Services.Interfaces
         Task<bool> LocationExistsAsync(int id);
         Task<int> GetTotalLocationCountAsync();
 
-        Task<PagedResult<LocationDTO>> GetLocationListPagedAsync(int page, int pageSize, string? search, string? states = null, CancellationToken cancellationToken = default);
+        Task<PagedResult<LocationDTO>> GetLocationListPagedAsync(int page, int pageSize, string? search, string? states = null, CancellationToken cancellationToken = default, string? sortBy = null, string? sortDirection = null);
         Task<LocationDTO?> GetLocationDetailAsync(int id, CancellationToken cancellationToken);
         Task CreateLocationFromRequestAsync(LocationCreateRequestDTO request, ClaimsPrincipal user, CancellationToken cancellationToken);
         Task UpdateLocationFromRequestAsync(int id, LocationUpdateRequestDTO request, ClaimsPrincipal user, CancellationToken cancellationToken);

SeaHavenIndustries.Tests/WorkOrderAccountScopeTests.cs

@@ -835,8 +835,8 @@ public class WorkOrderAccountScopeTests
         public Task<bool> ExistsAsync(int id) => _inner.ExistsAsync(id);
         public Task<int> CountAsync() => _inner.CountAsync();
         public Task<(List<Locations> Items, int TotalCount)> GetListPagedAsync(
-            int page, int pageSize, string? search, IReadOnlyCollection<string>? states, CancellationToken cancellationToken)
-            => _inner.GetListPagedAsync(page, pageSize, search, states, cancellationToken);
+            int page, int pageSize, string? search, IReadOnlyCollection<string>? states, CancellationToken cancellationToken, string? sortBy = null, string? sortDirection = null)
+            => _inner.GetListPagedAsync(page, pageSize, search, states, cancellationToken, sortBy, sortDirection);
         public Task<Locations?> GetDetailByIdAsync(int id, CancellationToken cancellationToken)
             => _inner.GetDetailByIdAsync(id, cancellationToken);
         public Task<Locations?> GetByIdForUpdateAsync(int id, CancellationToken cancellationToken)