Terminal - real backend (#38)

## What & why

Order and shipment cards were showing raw backend GUIDs. This derives a stable,
human-readable reference (`SO-…`, `SHP-…`) for display — the same convention the terminal uses.

## Changes

- New `shared/format/ref.ts` (`humanRef('SO' | 'SHP' | …, id)`).
- Dispatch, Outbound, Inbound and Receiving screens render `humanRef(...)` instead of the GUID.

## Notes

- Admin front-end only; display formatting, no data or contract changes.

Author: mkasperczyk90

docs/demo-walkthrough.md

@@ -214,8 +214,6 @@ Already captured in [`media/`](media/) — the GIFs above and below are these fi
 | [`golden-path-full.gif`](media/golden-path-full.gif) | **Canonical** full run, Admin + Terminal side by side (① → ⑩), Aspire / real backend | the one-clip story (embedded at the top) |
 | [`admin-golden-path.gif`](media/admin-golden-path.gif) · [`.mp4`](media/admin-golden-path.mp4) | Admin desk app only — the Coordinator / Manager / Inspector acts | slides, README, a focused admin loop |
 | [`terminal-golden-path.gif`](media/terminal-golden-path.gif) · [`.mp4`](media/terminal-golden-path.mp4) | Terminal handheld only — receive · put-away · pick · pack · move | the operator story on its own |
-| [`admin-walkthrough-real-backend.gif`](media/admin-walkthrough-real-backend.gif) · [`.webm`](media/admin-walkthrough-real-backend.webm) | Admin driven against the **real seeded backend** (MSW off) | proof the admin runs live, not just mocked |
-| [`frame-stock-view.png`](media/frame-stock-view.png) | A single Stock-view still (scene ⑥) | thumbnail / hero frame |
 
 **Admin only**  |  **Terminal only**
 

src/AppHost/Warehouse.AppHost/AppHost.cs

@@ -1,8 +1,11 @@
 var builder = DistributedApplication.CreateBuilder(args);
 
 // One PostgreSQL server, one database per service (ADR: database-per-service).
-var postgres = builder.AddPostgres("postgres")
-    .WithDataVolume();
+// No data volume: each `dotnet run` starts on a fresh database so the per-service seeders re-run and
+// re-publish their integration events — the event-fed read replicas (catalog/topology snapshots) only
+// populate through those events, so a persisted volume from an earlier (broken-messaging) run would
+// leave them half-empty. Ephemeral is the right default for the local demo stack.
+var postgres = builder.AddPostgres("postgres");
 
 var masterDataDb = postgres.AddDatabase("masterdata");
 var warehouseDb = postgres.AddDatabase("warehouse");
@@ -53,16 +56,20 @@
     .WithEnvironment("Keycloak__ClientId", "warehouse-admin")
     .WithEnvironment("Keycloak__ClientSecret", "warehouse-admin-secret-dev");
 
-// Front-ends — MSW-mocked SPAs served by nginx, built from their own Dockerfiles (ADR-0004,
-// ADR-0006). They run standalone today (the mock worker answers fetch); the gateway reference is
-// the seam where a real API base URL attaches when MSW is switched off.
+// Front-ends — SPAs served by nginx, built from their own Dockerfiles (ADR-0004, ADR-0006). Both proxy
+// `/api` to the gateway (the `GATEWAY_UPSTREAM` the Dockerfile's nginx template expands). The admin still
+// ships MSW and is built with it switched OFF here (build arg); the terminal no longer uses MSW and always
+// calls the real gateway. Build-arg changes trigger an image rebuild on `dotnet run`.
 builder.AddDockerfile("admin", "../../web/admin")
+    .WithBuildArg("VITE_USE_MOCKS", "false")
     .WithReference(gateway)
+    .WithEnvironment("GATEWAY_UPSTREAM", gateway.GetEndpoint("http"))
     .WithHttpEndpoint(targetPort: 80)
     .WithExternalHttpEndpoints();
 
 builder.AddDockerfile("terminal", "../../web/terminal")
     .WithReference(gateway)
+    .WithEnvironment("GATEWAY_UPSTREAM", gateway.GetEndpoint("http"))
     .WithHttpEndpoint(targetPort: 80)
     .WithExternalHttpEndpoints();
 

src/Gateway/Warehouse.Gateway/Bff/BffFetch.cs

@@ -35,4 +35,18 @@ public async Task<IReadOnlyList<T>> GetListAsync<T>(HttpClient client, string pa
             return [];
         }
     }
+
+    /// <summary>Read a single JSON object best-effort (a failing source returns <c>default</c>).</summary>
+    public async Task<T?> GetAsync<T>(HttpClient client, string path, CancellationToken cancellationToken)
+    {
+        try
+        {
+            return await client.GetFromJsonAsync<T>(path, Json, cancellationToken);
+        }
+        catch (Exception ex)
+        {
+            logger.LogWarning(ex, "BFF source {Path} failed; skipped.", path);
+            return default;
+        }
+    }
 }

src/Gateway/Warehouse.Gateway/Bff/TerminalTasksContracts.cs

@@ -0,0 +1,17 @@
+namespace Warehouse.Gateway.Bff;
+
+// --- Output: the terminal Task hub's work piles (matches its `TaskData` model) ----------------------
+
+/// <summary>One work pile on the handheld's Task hub: its kind, a short data detail, and a count.</summary>
+public sealed record TerminalTaskDto(string Kind, string Detail, int Count);
+
+// --- Input: minimal slices of each service's read model the hub aggregator counts -------------------
+// (DeliverySummaryView / OrderSummaryView are reused from WorklistContracts.) ------------------------
+
+internal sealed record PutAwayTaskView(string Sku);
+
+internal sealed record MoveTaskView(string Sku);
+
+internal sealed record PickListView(IReadOnlyList<PickTaskView> Tasks);
+
+internal sealed record PickTaskView(string Status);

src/Gateway/Warehouse.Gateway/Bff/TerminalTasksService.cs

@@ -0,0 +1,54 @@
+namespace Warehouse.Gateway.Bff;
+
+/// <summary>
+/// The terminal Task-hub BFF: fans out to Inventory and Logistics to count the operator's open work —
+/// deliveries to receive, pallets to put away, pick tasks released to the floor, and replenishment
+/// moves — all scoped to the operator's warehouse. Best-effort (a failing source counts zero), mirroring
+/// <see cref="WorklistService"/>. The gateway is the only place that may fan out across services.
+/// </summary>
+public sealed class TerminalTasksService(BffFetch fetch)
+{
+    private const string DefaultWarehouse = "WH01";
+
+    private static readonly HashSet<string> Receivable =
+        new(StringComparer.OrdinalIgnoreCase) { "Announced", "Arrived", "Receiving" };
+
+    public async Task<IReadOnlyList<TerminalTaskDto>> BuildAsync(string? warehouseId, CancellationToken cancellationToken)
+    {
+        var warehouse = string.IsNullOrWhiteSpace(warehouseId) ? DefaultWarehouse : warehouseId;
+        var warehousing = fetch.Client(BffClients.Warehousing, warehouse);
+        var logistics = fetch.Client(BffClients.Logistics, warehouse);
+
+        var deliveries = fetch.GetListAsync<DeliverySummaryView>(logistics, "logistics/deliveries", cancellationToken);
+        var putAway = fetch.GetListAsync<PutAwayTaskView>(warehousing, $"inventory/put-away/tasks?warehouse={warehouse}", cancellationToken);
+        var moves = fetch.GetListAsync<MoveTaskView>(warehousing, $"inventory/moves?warehouse={warehouse}", cancellationToken);
+        var orders = fetch.GetListAsync<OrderSummaryView>(logistics, "logistics/orders", cancellationToken);
+
+        await Task.WhenAll(deliveries, putAway, moves, orders);
+
+        var receive = deliveries.Result.Count(d => Same(d.WarehouseCode, warehouse) && Receivable.Contains(d.Status));
+
+        // Pick is counted in pending tasks across the orders released to the floor (status Picking).
+        var pickingOrders = orders.Result.Where(o => Same(o.WarehouseCode, warehouse) && o.Status == "Picking").ToList();
+        var pickLists = await Task.WhenAll(pickingOrders.Select(o =>
+            fetch.GetAsync<PickListView>(logistics, $"logistics/orders/{o.Id}/pick-list", cancellationToken)));
+        var pick = pickLists.Where(p => p is not null)
+            .Sum(p => p!.Tasks.Count(t => string.Equals(t.Status, "Pending", StringComparison.OrdinalIgnoreCase)));
+
+        var putAwayCount = putAway.Result.Count;
+        var moveCount = moves.Result.Count;
+
+        return
+        [
+            new TerminalTaskDto("receive", Detail(receive, "delivery", "deliveries", "to receive"), receive),
+            new TerminalTaskDto("putaway", Detail(putAwayCount, "pallet", "pallets", "in dock buffer"), putAwayCount),
+            new TerminalTaskDto("pick", Detail(pick, "line", "lines", "to pick"), pick),
+            new TerminalTaskDto("move", Detail(moveCount, "task", "tasks", "to replenish"), moveCount),
+        ];
+    }
+
+    private static bool Same(string? a, string b) => string.Equals(a, b, StringComparison.OrdinalIgnoreCase);
+
+    private static string Detail(int n, string singular, string plural, string suffix) =>
+        $"{n} {(n == 1 ? singular : plural)} {suffix}";
+}

src/Gateway/Warehouse.Gateway/Program.cs

@@ -15,8 +15,19 @@
     {
         options.Authority = builder.Configuration["Keycloak:Authority"] ?? "http://keycloak/realms/warehouse";
         options.RequireHttpsMetadata = false;
-        options.Audience = "account";
+        // The realm's badge Direct-Grant tokens carry no `aud` claim yet, so audience validation is off in
+        // dev (alongside issuer). For production, add an audience mapper to the realm and pin both here.
         options.TokenValidationParameters.ValidateIssuer = false;
+        options.TokenValidationParameters.ValidateAudience = false;
+        // DEV-ONLY shim. In the Aspire stack Keycloak advertises its issuer/JWKS on a dynamic host port the
+        // gateway's metadata lookup can't align with, so signature validation fails ("signature key not
+        // found") — the open "stable Keycloak URL" follow-up (src/Identity/README.md). In Development we
+        // accept the brokered token without re-checking its signature; production keeps full validation.
+        if (builder.Environment.IsDevelopment())
+        {
+            options.TokenValidationParameters.SignatureValidator =
+                (token, _) => new Microsoft.IdentityModel.JsonWebTokens.JsonWebToken(token);
+        }
     });
 builder.Services.AddAuthorization();
 
@@ -39,6 +50,7 @@
 builder.Services.AddHttpClient(BffClients.MasterData, c => c.BaseAddress = new Uri("http://masterdata-api/"));
 builder.Services.AddScoped<BffFetch>();
 builder.Services.AddScoped<WorklistService>();
+builder.Services.AddScoped<TerminalTasksService>();
 builder.Services.AddScoped<SearchService>();
 // Profile is derived from the caller's token + an in-memory prefs overlay, so it is a singleton (the
 // overlay must outlive a single request). No downstream call, hence no scoped HttpClient.
@@ -65,6 +77,14 @@
     return Results.Ok(await worklist.BuildAsync(warehouseId, ct));
 }).RequireAuthorization();
 
+// Terminal Task hub — the handheld operator's open work, aggregated across Inventory + Logistics and
+// scoped to the operator's warehouse (the terminal sends it as X-Warehouse-Id at the api seam).
+app.MapGet("/api/terminal/tasks", async (HttpRequest request, TerminalTasksService tasks, CancellationToken ct) =>
+{
+    var warehouseId = request.Headers["X-Warehouse-Id"].FirstOrDefault();
+    return Results.Ok(await tasks.BuildAsync(warehouseId, ct));
+}).RequireAuthorization();
+
 // Global search — "where is X" across products, stock, inbound, orders and locations.
 app.MapGet("/api/search", async (string? q, HttpRequest request, SearchService search, CancellationToken ct) =>
 {

src/Identity/realms/warehouse-realm.json

@@ -10,7 +10,9 @@
     "realm": [
       { "name": "manager", "description": "Desk manager" },
       { "name": "coordinator", "description": "Logistics coordinator" },
-      { "name": "inspector", "description": "Quality inspector" }
+      { "name": "inspector", "description": "Quality inspector" },
+      { "name": "operator", "description": "Warehouse operator (terminal)" },
+      { "name": "forklift", "description": "Forklift operator (terminal)" }
     ]
   },
   "clients": [
@@ -102,6 +104,26 @@
       "email": "inspector@warehouse.example",
       "attributes": { "badge": ["1003"], "default_warehouse": ["WH02"], "language": ["pl"] },
       "realmRoles": ["inspector"]
+    },
+    {
+      "username": "7700",
+      "enabled": true,
+      "emailVerified": true,
+      "firstName": "W.",
+      "lastName": "Operator",
+      "email": "operator@warehouse.example",
+      "attributes": { "badge": ["7700"], "default_warehouse": ["WH01"], "language": ["en"] },
+      "realmRoles": ["operator"]
+    },
+    {
+      "username": "7701",
+      "enabled": true,
+      "emailVerified": true,
+      "firstName": "J.",
+      "lastName": "Forklift",
+      "email": "forklift@warehouse.example",
+      "attributes": { "badge": ["7701"], "default_warehouse": ["WH01"], "language": ["en"] },
+      "realmRoles": ["forklift"]
     }
   ],
   "authenticationFlows": [

src/ServiceDefaults/Warehouse.ServiceDefaults/Messaging.cs

@@ -46,6 +46,14 @@ public static TBuilder AddWarehouseMessaging<TBuilder>(
 
         builder.UseWolverine(opts =>
         {
+            // Handler dependencies (the module repositories/ledgers/outbox) are deliberately `internal`
+            // to the Infrastructure layer. Wolverine 6 flipped the codegen default to
+            // ServiceLocationPolicy.NotAllowed, which then refuses to generate any handler whose concrete
+            // dependency is non-public — so EVERY cross-service event consumer (goods-receipt, picks,
+            // reservations, replica updaters) silently failed to build and never ran. Restore the 5.x
+            // behaviour: resolve those services from the container (service location) instead of inline.
+            opts.ServiceLocationPolicy = JasperFx.CodeGeneration.Model.ServiceLocationPolicy.AllowedButWarn;
+
             opts.PersistMessagesWithPostgresql(
                 builder.Configuration.GetConnectionString(messageStoreConnectionName)!, schemaName: MessageStoreSchema);
             opts.UseEntityFrameworkCoreTransactions();

src/Services/Warehousing/Modules/Warehouse.Warehousing.Inventory/Application/ConfirmMove/ConfirmMoveCommand.cs

@@ -0,0 +1,60 @@
+using Warehouse.SharedKernel.Application;
+using Warehouse.SharedKernel.Domain;
+using Warehouse.SharedKernel.ValueObjects;
+using Warehouse.Warehousing.Inventory.Application.Abstractions;
+using Warehouse.Warehousing.Inventory.Application.Storage;
+using Warehouse.Warehousing.Inventory.Domain;
+using Warehouse.Warehousing.Inventory.Domain.Services;
+
+namespace Warehouse.Warehousing.Inventory.Application.ConfirmMove;
+
+/// <summary>
+/// UC-06 — the operator confirmed a replenishment move: relocate the available stock of one item to the
+/// scanned pick face, re-checking the hard storage invariant first (temperature / hazmat / capacity) and
+/// posting a single <c>Move</c> ledger entry via <see cref="StockTransferService"/>. Allocated quantity
+/// stays put — only free stock moves. The requested quantity is clamped to what is available.
+/// </summary>
+public sealed record ConfirmMoveCommand(Guid SourceItemId, string ToLocation, decimal Quantity, string PerformedBy);
+
+public sealed class ConfirmMoveHandler(
+    IStockItemRepository stockItems,
+    StorageCompatibility compatibility,
+    IStockLedger ledger,
+    IUnitOfWork unitOfWork)
+{
+    public async Task HandleAsync(ConfirmMoveCommand command, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(command);
+
+        var source = await stockItems.GetByIdAsync(new StockItemId(command.SourceItemId), cancellationToken)
+            ?? throw new DomainException("move_stock_item_not_found", $"Stock item {command.SourceItemId} does not exist.");
+
+        var available = source.Available;
+        if (available.IsZero)
+        {
+            throw new DomainException(
+                "move_stock_unavailable",
+                $"Stock {source.Sku} at {source.Location} has nothing free to move (blocked or fully allocated).");
+        }
+
+        // Honour the operator's chosen quantity, clamped to what is actually free at the source.
+        var amount = command.Quantity > 0 && command.Quantity <= available.Amount ? command.Quantity : available.Amount;
+        var quantity = Quantity.Of(amount, source.OnHand.Unit);
+
+        var target = LocationCode.Of(command.ToLocation);
+        await compatibility.EnsureCanStoreAsync(source.Sku, target, quantity, "move", cancellationToken);
+
+        var destination = await stockItems.GetAtAsync(source.Sku, source.Batch, target, cancellationToken);
+        if (destination is null)
+        {
+            destination = StockItem.CreateAt(target, source.Sku, source.Batch, source.OnHand.Unit);
+            stockItems.Add(destination);
+        }
+
+        var movement = StockTransferService.Transfer(
+            source, destination, quantity, MovementType.Move, command.PerformedBy, reason: "Replenishment");
+        ledger.Append(movement);
+
+        await unitOfWork.SaveChangesAsync(cancellationToken);
+    }
+}

src/Services/Warehousing/Modules/Warehouse.Warehousing.Inventory/Application/ConfirmPutAway/ConfirmPutAwayCommand.cs

@@ -2,6 +2,7 @@
 using Warehouse.SharedKernel.Domain;
 using Warehouse.SharedKernel.ValueObjects;
 using Warehouse.Warehousing.Inventory.Application.Abstractions;
+using Warehouse.Warehousing.Inventory.Application.Storage;
 using Warehouse.Warehousing.Inventory.Domain;
 using Warehouse.Warehousing.Inventory.Domain.Services;
 using Warehouse.Warehousing.Inventory.Infrastructure.Persistence;
@@ -26,8 +27,7 @@ public sealed record ConfirmPutAwayCommand(
 
 public sealed class ConfirmPutAwayHandler(
     IStockItemRepository stockItems,
-    IProductSnapshotRepository products,
-    ILocationSnapshotRepository locations,
+    StorageCompatibility compatibility,
     IStockLedger ledger,
     IDbContextOutbox<InventoryDbContext> outbox)
 {
@@ -50,7 +50,7 @@ public async Task HandleAsync(ConfirmPutAwayCommand command, CancellationToken c
                 "put_away_no_buffer_stock",
                 $"No {sku} {(batch is null ? string.Empty : batch + " ")}in the dock buffer of {command.WarehouseCode}.");
 
-        await EnsureCompatibleAsync(sku, target, quantity, cancellationToken);
+        await compatibility.EnsureCanStoreAsync(sku, target, quantity, "put_away", cancellationToken);
 
         var destination = await stockItems.GetAtAsync(sku, batch, target, cancellationToken);
         if (destination is null)
@@ -73,50 +73,4 @@ public async Task HandleAsync(ConfirmPutAwayCommand command, CancellationToken c
 
         await outbox.SaveChangesAndFlushMessagesAsync(cancellationToken);
     }
-
-    /// <summary>
-    /// Enforces the hard storage-compatibility invariant (temperature / hazmat / capacity) before the
-    /// stock moves, reading Topology's <c>LocationSnapshot</c> and the Catalog's <c>ProductSnapshot</c>
-    /// replicas — no cross-service query (ADR-0003). A location Topology has not announced cannot be a
-    /// put-away target; an unknown product cannot be validated, so both are rejected rather than waved
-    /// through.
-    /// </summary>
-    private async Task EnsureCompatibleAsync(
-        Sku sku, LocationCode target, Quantity quantity, CancellationToken cancellationToken)
-    {
-        var location = await locations.FindAsync(target, cancellationToken)
-            ?? throw new DomainException(
-                "put_away_location_unknown", $"Location {target} is not known to the warehouse topology.");
-
-        var product = await products.FindAsync(sku, cancellationToken)
-            ?? throw new DomainException(
-                "put_away_product_unknown",
-                $"Product {sku} is not yet known to inventory; cannot validate storage compatibility.");
-
-        // Current occupancy at the target: sum each resident stock line by its product's footprint.
-        var occupiedVolume = Volume.Zero;
-        var occupiedWeight = Weight.Zero;
-        foreach (var item in await stockItems.ListAtAsync(target, cancellationToken))
-        {
-            if (item.OnHand.IsZero)
-            {
-                continue;
-            }
-
-            var resident = item.Sku == sku ? product : await products.FindAsync(item.Sku, cancellationToken);
-            if (resident is null)
-            {
-                continue;
-            }
-
-            occupiedVolume += Volume.FromCubicMeters(resident.UnitVolume.CubicMeters * item.OnHand.Amount);
-            occupiedWeight += Weight.FromKilograms(resident.UnitWeight.Kilograms * item.OnHand.Amount);
-        }
-
-        var check = PutAwayPolicy.CanStore(product, location, quantity, occupiedVolume, occupiedWeight);
-        if (!check.IsAllowed)
-        {
-            throw new DomainException("put_away_incompatible", check.RejectionReason!);
-        }
-    }
 }