From 997998dcb2b7530f7ad4837afb51791b60c1d72b Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Mon, 10 Aug 2026 23:30:18 +0300
Subject: [PATCH] feat(wagons): enforce wagon availability limits in transfer
 requests

---
 .../wagons/dto/create-transfer-request.dto.ts |  3 +-
 .../wagon-transfer-requests.service.spec.ts   | 42 ++++++++++++-
 .../wagons/wagon-transfer-requests.service.ts | 23 +++++--
 .../wagons/WagonYardWorkspaceModal.tsx        | 16 +++--
 .../pages/wagons/TransferRequestModals.tsx    | 61 +++++++++++++++++--
 5 files changed, 127 insertions(+), 18 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts b/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
index e747b69f2..85c879f70 100644
--- a/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
+++ b/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
@@ -14,7 +14,8 @@ import {
  * A count-only wagon-transfer request. The requester picks source yard, wagon
  * type, destination yard and HOW MANY — never the specific wagons; OCC hand-picks
  * those at fulfilment. The quantity may not exceed the AVAILABLE wagons of that
- * type currently in the source yard, and a reason is mandatory.
+ * type currently in the source yard (enforced in the service, which is the only
+ * layer that can count them), and a reason is mandatory.
  */
 export class CreateTransferRequestDto {
   @IsUUID()
diff --git a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
index 205d86450..8f7457b37 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
@@ -199,7 +199,7 @@ describe('WagonTransferRequestsService — partial fulfilment', () => {
   });
 
   describe('createRequest', () => {
-    it('accepts a count larger than what the yard holds today', async () => {
+    it('accepts a count up to what the yard holds today', async () => {
       wagonRepo.count.mockResolvedValue(20);
 
       await service.createRequest(
@@ -207,14 +207,50 @@ describe('WagonTransferRequestsService — partial fulfilment', () => {
           fromYardId: 'yard-a',
           toYardId: 'yard-b',
           wagonTypeId: 'type-1',
-          quantity: 50,
+          quantity: 20,
           reason: 'Grain campaign',
         },
         'user-1',
       );
 
       expect(requestRepo.save).toHaveBeenCalled();
-      expect(stored.quantity).toBe(50);
+      expect(stored.quantity).toBe(20);
+    });
+
+    it('refuses a count larger than what the yard holds today', async () => {
+      wagonRepo.count.mockResolvedValue(20);
+
+      await expect(
+        service.createRequest(
+          {
+            fromYardId: 'yard-a',
+            toYardId: 'yard-b',
+            wagonTypeId: 'type-1',
+            quantity: 50,
+            reason: 'Grain campaign',
+          },
+          'user-1',
+        ),
+      ).rejects.toThrow(/only 20 wagon\(s\).*available/i);
+      expect(requestRepo.save).not.toHaveBeenCalled();
+    });
+
+    it('refuses when the yard has nothing of that type available', async () => {
+      wagonRepo.count.mockResolvedValue(0);
+
+      await expect(
+        service.createRequest(
+          {
+            fromYardId: 'yard-a',
+            toYardId: 'yard-b',
+            wagonTypeId: 'type-1',
+            quantity: 1,
+            reason: 'Grain campaign',
+          },
+          'user-1',
+        ),
+      ).rejects.toThrow(/no available wagons/i);
+      expect(requestRepo.save).not.toHaveBeenCalled();
     });
 
     it('still refuses a same-yard move', async () => {
diff --git a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
index 8d4159726..6b63460ad 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
@@ -75,10 +75,11 @@ export class WagonTransferRequestsService {
   ) {}
 
   /**
-   * Record a PENDING request. Count-only — no wagons are picked here, and the
-   * count is NOT capped by what the source yard holds today: OCC fulfils in
-   * instalments, so asking for 50 while only 20 sit there is a normal, useful
-   * request. A reason is mandatory and is shown on the OCC queue.
+   * Record a PENDING request. Count-only — no wagons are picked here, but the
+   * count IS capped by what the source yard can hand over right now: a request
+   * may not exceed the AVAILABLE, uncoupled wagons of that type in the source
+   * yard (the same number the yard desk shows). A reason is mandatory and is
+   * shown on the OCC queue.
    */
   async createRequest(
     dto: CreateTransferRequestDto,
@@ -89,6 +90,20 @@ export class WagonTransferRequestsService {
         'Source and destination yard must be different',
       );
     }
+    const available = await this.countAvailable(
+      dto.fromYardId,
+      dto.wagonTypeId,
+    );
+    if (available === 0) {
+      throw new BadRequestException(
+        'No available wagons of this type in the source yard',
+      );
+    }
+    if (dto.quantity > available) {
+      throw new BadRequestException(
+        `Only ${available} wagon(s) of this type are available in the source yard — cannot request ${dto.quantity}`,
+      );
+    }
     const request = this.requestRepo.create({
       fromYardId: dto.fromYardId,
       toYardId: dto.toYardId,
diff --git a/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx b/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
index 4a92695ca..cb9fdf86b 100644
--- a/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
@@ -44,9 +44,8 @@ const clampInt = (v: number | string, max: number): number => {
 
 /**
  * NumberInput + Slider + All/Half presets, kept in sync. `max` bounds the field
- * for actions that move real wagons; omit it for a transfer REQUEST, which may
- * legitimately ask for more than the yard holds today (OCC fulfils it in
- * instalments) — the slider then just tracks the current value.
+ * to the wagons on hand; omitting it leaves the field unbounded and the slider
+ * simply tracks the current value.
  */
 const QuantityField = ({
   value,
@@ -434,9 +433,14 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
                           {availableCount} available
                         </Badge>
                       </Group>
-                      {/* No max: the request may exceed what the yard holds
-                          today — OCC fulfils it in instalments. */}
-                      <QuantityField value={transferQty} onChange={setTransferQty} />
+                      {/* Capped at the wagons actually available in this yard
+                          right now (uncoupled + Available) — a request may not
+                          ask for more than the yard can hand over. */}
+                      <QuantityField
+                        value={transferQty}
+                        onChange={setTransferQty}
+                        max={availableCount}
+                      />
                     </div>
                     <Select
                       label="Destination yard"
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
index df90a7683..a58d49bf1 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
@@ -1,3 +1,4 @@
+import { Freight } from "@edr/types";
 import {
   Alert,
   Button,
@@ -41,6 +42,30 @@ function useTransferOptions(enabled: boolean) {
   };
 }
 
+/**
+ * Wagons the source yard can hand over right now — AVAILABLE and not coupled to
+ * a built train. Mirrors `countAvailable` on the API, which rejects any request
+ * asking for more than this, so the field must not let one be filed.
+ */
+function useAvailableCount(
+  enabled: boolean,
+  fromYardId: string | null,
+  wagonTypeId: string | null,
+) {
+  const { data: wagons = [] } = useQuery({
+    ...api.wagons.list.queryOptions({ input: {} }),
+    enabled: enabled && Boolean(fromYardId && wagonTypeId),
+  });
+  if (!fromYardId || !wagonTypeId) return null;
+  return wagons.filter(
+    (w) =>
+      w.currentYardId === fromYardId &&
+      w.wagonTypeId === wagonTypeId &&
+      w.status === Freight.WagonStatus.Available &&
+      !w.trainId,
+  ).length;
+}
+
 export interface TransferRequestFormModalProps {
   opened: boolean;
   onClose: () => void;
@@ -54,9 +79,9 @@ export interface TransferRequestFormModalProps {
 }
 
 /**
- * File a wagon-transfer request. The count is deliberately NOT capped by what
- * the source yard holds today — OCC fulfils in instalments, so asking for 50
- * where 20 sit is a normal request.
+ * File a wagon-transfer request. The count is capped by what the source yard
+ * has available right now; the API enforces the same ceiling, so a larger ask
+ * is rejected rather than queued.
  */
 export function TransferRequestFormModal({
   opened,
@@ -83,10 +108,23 @@ export function TransferRequestFormModal({
 
   const create = useMutation(api.wagonTransferRequests.create.mutationOptions());
 
+  const available = useAvailableCount(opened, fromYardId, wagonTypeId);
+
+  // A prefilled outstanding count (or a count typed before the yard was picked)
+  // can exceed what the chosen source yard actually has — pull it back down so
+  // the field never holds a value the API would reject.
+  useEffect(() => {
+    if (available == null) return;
+    setQuantity((q) => (Number(q) > available ? available : q));
+  }, [available]);
+
   const sameYard = Boolean(fromYardId && fromYardId === toYardId);
+  const overAvailable = available != null && Number(quantity) > available;
   const valid =
     Boolean(fromYardId && toYardId && wagonTypeId && reason.trim()) &&
     !sameYard &&
+    !overAvailable &&
+    available !== 0 &&
     Number(quantity) >= 1;
 
   const submit = async () => {
@@ -155,10 +193,25 @@ export function TransferRequestFormModal({
         />
         <NumberInput
           label="How many"
-          description="Can exceed what the yard holds today — OCC delivers in instalments"
+          description={
+            available == null
+              ? "Pick a source yard and wagon type to see what is available"
+              : `${available} wagon(s) available in the source yard`
+          }
           min={1}
+          max={available ?? undefined}
+          clampBehavior={available == null ? "none" : "strict"}
+          allowNegative={false}
           value={quantity}
           onChange={setQuantity}
+          disabled={available === 0}
+          error={
+            available === 0
+              ? "This yard has no wagons of that type available"
+              : overAvailable
+                ? `Only ${available} available`
+                : undefined
+          }
           required
         />
         <Textarea