feat(procurement): validate acquisition lease fields and enforce bulk-receive capacity

Reject lease start/end and monthly payment on PURCHASE acquisitions (create and update, validated against the resulting record). Add asset_acquisitions.item_name column + migration. Enforce warehouse/yard/zone capacity on bulk receive and apply capacity-counter deltas on save. Adds acquisition-guard spec. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-26 18:42:49 +00:00 · 2026-07-22 11:59:37 +00:00
parent 59f06a9bd1
commit 8dc4dd585e
8 changed files with 201 additions and 42 deletions
--- a/apps/edr-freight-api/src/migrations/2470000000000-AddAcquisitionItemName.ts
+++ b/apps/edr-freight-api/src/migrations/2470000000000-AddAcquisitionItemName.ts
@@ -0,0 +1,23 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Acquisitions describe WHAT was acquired (vehicle, parts, equipment…) — the
+ * vehicle link is optional and only for acquisitions that ARE a fleet vehicle.
+ */
+export class AddAcquisitionItemName2470000000000 implements MigrationInterface {
+  name = 'AddAcquisitionItemName2470000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.asset_acquisitions
+        ADD COLUMN IF NOT EXISTS item_name varchar(200)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.asset_acquisitions
+        DROP COLUMN IF EXISTS item_name
+    `);
+  }
+}
--- a/apps/edr-freight-api/src/modules/procurement/dto/procurement.dto.ts
+++ b/apps/edr-freight-api/src/modules/procurement/dto/procurement.dto.ts
@@ -7,6 +7,7 @@ import {
  IsOptional,
  IsEnum,
  IsBoolean,
+  MinLength,
 } from 'class-validator';
 import { VendorType } from '../entities/vendor.entity';
 import { AcquisitionType, AcquisitionStatus } from '../entities/asset-acquisition.entity';
@@ -72,6 +73,11 @@ export class UpdateVendorDto {
 }

 export class CreateAcquisitionDto {
+  /** WHAT was acquired — required so an acquisition can't be saved empty. */
+  @IsString()
+  @MinLength(2)
+  itemName!: string;
+
  @IsOptional()
  @IsUUID()
  vehicleId?: string;
@@ -120,6 +126,11 @@ export class CreateAcquisitionDto {
 }

 export class UpdateAcquisitionDto {
+  @IsOptional()
+  @IsString()
+  @MinLength(2)
+  itemName?: string;
+
  @IsOptional()
  @IsUUID()
  vehicleId?: string;
--- a/apps/edr-freight-api/src/modules/procurement/entities/asset-acquisition.entity.ts
+++ b/apps/edr-freight-api/src/modules/procurement/entities/asset-acquisition.entity.ts
@@ -18,6 +18,12 @@ export enum AcquisitionStatus {
@Entity({ name: 'asset_acquisitions', schema: 'freight' })
@Index(['vehicleId', 'acquisitionDate'])
 export class AssetAcquisition extends BaseEntity {
+  /** WHAT was acquired (vehicle, parts, equipment…) — the asset itself. */
+  @Column({ name: 'item_name', type: 'varchar', length: 200, nullable: true })
+  itemName?: string;
+
+  /** Optional link — only when the acquisition IS a fleet vehicle. Parts and
+   *  general procurement stay unlinked so reports don't misattribute them. */
  @Column({ name: 'vehicle_id', type: 'uuid', nullable: true })
  vehicleId?: string;

--- a/apps/edr-freight-api/src/modules/procurement/procurement.acquisition-guard.spec.ts
+++ b/apps/edr-freight-api/src/modules/procurement/procurement.acquisition-guard.spec.ts
@@ -0,0 +1,50 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { ProcurementService } from './procurement.service';
+import { AcquisitionType } from './entities/asset-acquisition.entity';
+
+// PURCHASE acquisitions must not carry lease terms; LEASE/RENTAL may.
+describe('ProcurementService acquisition lease-field guard', () => {
+  const repo = {
+    createAcquisition: jest.fn(async (dto) => dto),
+    findAcquisitionById: jest.fn(async () => ({ acquisitionType: AcquisitionType.PURCHASE })),
+    updateAcquisition: jest.fn(async (_id, dto) => dto),
+  };
+  const svc = new ProcurementService(repo as never);
+
+  it('rejects a PURCHASE with lease dates', async () => {
+    await expect(
+      svc.createAcquisition({
+        itemName: 'Brake pads',
+        acquisitionType: AcquisitionType.PURCHASE,
+        acquisitionDate: '2026-07-22',
+        leaseStart: '2026-07-01',
+      } as never),
+    ).rejects.toThrow(BadRequestException);
+  });
+
+  it('accepts a LEASE with lease dates and a plain PURCHASE', async () => {
+    await expect(
+      svc.createAcquisition({
+        itemName: 'Rented crane',
+        acquisitionType: AcquisitionType.LEASE,
+        acquisitionDate: '2026-07-22',
+        leaseStart: '2026-07-01',
+        leaseEnd: '2027-07-01',
+      } as never),
+    ).resolves.toBeDefined();
+    await expect(
+      svc.createAcquisition({
+        itemName: 'Brake pads',
+        acquisitionType: AcquisitionType.PURCHASE,
+        acquisitionDate: '2026-07-22',
+      } as never),
+    ).resolves.toBeDefined();
+  });
+
+  it('rejects adding lease terms to an acquisition that is a PURCHASE', async () => {
+    await expect(
+      svc.updateAcquisition('a1', { monthlyPayment: 500 } as never),
+    ).rejects.toThrow(BadRequestException);
+  });
+});
--- a/apps/edr-freight-api/src/modules/procurement/procurement.service.ts
+++ b/apps/edr-freight-api/src/modules/procurement/procurement.service.ts
@@ -1,7 +1,7 @@
-import { Injectable } from '@nestjs/common';
+import { BadRequestException, Injectable } from '@nestjs/common';
 import { ProcurementRepository } from './procurement.repository';
 import { Vendor } from './entities/vendor.entity';
-import { AssetAcquisition } from './entities/asset-acquisition.entity';
+import { AcquisitionType, AssetAcquisition } from './entities/asset-acquisition.entity';
 import { AssetDisposal } from './entities/asset-disposal.entity';
 import {
  CreateVendorDto,
@@ -51,7 +51,23 @@ export class ProcurementService {
  }

  // ---- Acquisitions ----
+  /** Lease terms only make sense on LEASE / RENTAL — a PURCHASE must not carry them. */
+  private assertLeaseFieldsValid(dto: {
+    acquisitionType?: string;
+    leaseStart?: string;
+    leaseEnd?: string;
+    monthlyPayment?: number;
+  }): void {
+    if (dto.acquisitionType !== AcquisitionType.PURCHASE) return;
+    if (dto.leaseStart || dto.leaseEnd || dto.monthlyPayment != null) {
+      throw new BadRequestException(
+        'Lease start/end and monthly payment are not valid for a PURCHASE acquisition',
+      );
+    }
+  }
+
  async createAcquisition(dto: CreateAcquisitionDto): Promise<AssetAcquisition> {
+    this.assertLeaseFieldsValid(dto);
    return this.procurementRepository.createAcquisition(dto);
  }

@@ -64,6 +80,20 @@ export class ProcurementService {
  }

  async updateAcquisition(id: string, dto: UpdateAcquisitionDto): Promise<AssetAcquisition | null> {
+    // Validate against the resulting record, not just the patch — switching an
+    // acquisition to PURCHASE must also shed any stored lease terms.
+    const existing = await this.procurementRepository.findAcquisitionById(id);
+    if (existing) {
+      const next = { ...existing, ...dto };
+      if (next.acquisitionType === AcquisitionType.PURCHASE) {
+        this.assertLeaseFieldsValid({
+          acquisitionType: next.acquisitionType,
+          leaseStart: dto.leaseStart,
+          leaseEnd: dto.leaseEnd,
+          monthlyPayment: dto.monthlyPayment,
+        });
+      }
+    }
    return this.procurementRepository.updateAcquisition(id, dto);
  }

--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
@@ -1578,6 +1578,14 @@ export class WarehouseInventoryService {
          notes: `Bulk received (${dto.direction})`,
          truckEntrance,
        });
+
+        // Validate capacity before saving
+        const weight = Number(booking.weight) || 0;
+        const containerCount = booking.freightType === 'CONTAINER' ? containerQuantity : 0;
+        this.assertCapacity('Warehouse', warehouse, weight, 0, containerCount);
+        this.assertCapacity('Yard', yard, weight, 0, containerCount);
+        this.assertCapacity('Zone', zone, weight, 0, containerCount);
+
        const saved = await manager.getRepository(WarehouseInventory).save(
          manager.getRepository(WarehouseInventory).create({
            warehouseId: dto.warehouseId,
@@ -1585,7 +1593,7 @@ export class WarehouseInventoryService {
            zoneId: dto.zoneId,
            bookingId,
            quantity: booking.freightType === 'CONTAINER' ? containerQuantity : 1,
-            weight: Number(booking.weight) || 0,
+            weight,
            grnNumber,
            status: 'RECEIVED',
            arrivedAt: now,
@@ -1593,6 +1601,9 @@ export class WarehouseInventoryService {
          }),
        );

+        // Update warehouse/yard/zone capacity counters
+        await this.applyCapacityDelta(manager, dto, weight, 0, containerCount);
+
        // Receiving the booking flags every container unit as received into the
        // port (self-haul export: the delivering truck's goods are now in) so
        // staff can raise the per-container GRN over what's received.
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/ProcurementPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/ProcurementPage.tsx
@@ -61,6 +61,7 @@ const clean = <T extends Record<string, unknown>>(obj: T): Partial<T> =>
  ) as Partial<T>;

 const emptyAcquisition = {
+  itemName: "",
  vehicleId: "",
  vendorId: "",
  acquisitionType: "PURCHASE" as AcquisitionType,
@@ -239,6 +240,7 @@ export default function ProcurementPage() {
            <Table striped highlightOnHover>
              <Table.Thead>
                <Table.Tr>
+                  <Table.Th>Item / Asset</Table.Th>
                  <Table.Th>Vehicle</Table.Th>
                  <Table.Th>Type</Table.Th>
                  <Table.Th>Date</Table.Th>
@@ -249,7 +251,7 @@ export default function ProcurementPage() {
              <Table.Tbody>
                {loadingAcquisitions ? (
                  <Table.Tr>
-                    <Table.Td colSpan={5}>
+                    <Table.Td colSpan={6}>
                      <Group justify="center" py="md">
                        <Loader size="sm" />
                      </Group>
@@ -257,7 +259,7 @@ export default function ProcurementPage() {
                  </Table.Tr>
                ) : acquisitions.length === 0 ? (
                  <Table.Tr>
-                    <Table.Td colSpan={5}>
+                    <Table.Td colSpan={6}>
                      <Text c="dimmed" ta="center" py="md">
                        No acquisitions recorded yet.
                      </Text>
@@ -266,6 +268,7 @@ export default function ProcurementPage() {
                ) : null}
                {acquisitions.map((a: AssetAcquisition) => (
                  <Table.Tr key={a.id}>
+                    <Table.Td>{a.itemName || "—"}</Table.Td>
                    <Table.Td>{vehicleLabel(a.vehicle, a.vehicleId)}</Table.Td>
                    <Table.Td>
                      <Badge size="sm" color={typeBadgeColor(a.acquisitionType)}>
@@ -411,31 +414,51 @@ export default function ProcurementPage() {
        size="lg"
      >
        <Stack gap="md">
+          <TextInput
+            label="Item / Asset"
+            placeholder="What was acquired — e.g. brake pads, tyres, truck 3-15288"
+            value={acqForm.itemName}
+            onChange={(e) => setAcqForm({ ...acqForm, itemName: e.currentTarget.value })}
+            required
+          />
          <Select
-            label="Vehicle"
-            placeholder="Select vehicle"
+            label="Related vehicle (optional)"
+            description="Only when the acquisition is a fleet vehicle itself — parts and general procurement stay unlinked."
+            placeholder="Not tied to a vehicle"
            data={vehicleOptions}
            value={acqForm.vehicleId}
            onChange={(val) => setAcqForm({ ...acqForm, vehicleId: val || "" })}
            searchable
            clearable
          />
-          <Select
-            label="Vendor"
-            placeholder="Select vendor"
-            data={vendorOptions}
-            value={acqForm.vendorId}
-            onChange={(val) => setAcqForm({ ...acqForm, vendorId: val || "" })}
-            searchable
-            clearable
-          />
+          <Group gap="xs" align="flex-end" wrap="nowrap">
+            <Select
+              style={{ flex: 1 }}
+              label="Vendor"
+              placeholder="Select vendor"
+              data={vendorOptions}
+              value={acqForm.vendorId}
+              onChange={(val) => setAcqForm({ ...acqForm, vendorId: val || "" })}
+              searchable
+              clearable
+            />
+            <Button variant="light" size="sm" onClick={() => setVendorModalOpen(true)}>
+              Register vendor
+            </Button>
+          </Group>
          <Select
            label="Acquisition Type"
            data={ACQUISITION_TYPES}
            value={acqForm.acquisitionType}
-            onChange={(val) =>
-              setAcqForm({ ...acqForm, acquisitionType: (val as AcquisitionType) || "PURCHASE" })
-            }
+            onChange={(val) => {
+              const acquisitionType = (val as AcquisitionType) || "PURCHASE";
+              // Lease terms are invalid on a purchase — drop them on switch.
+              setAcqForm(
+                acquisitionType === "PURCHASE"
+                  ? { ...acqForm, acquisitionType, leaseStart: "", leaseEnd: "", monthlyPayment: undefined }
+                  : { ...acqForm, acquisitionType },
+              );
+            }}
            required
          />
          <TextInput
@@ -471,28 +494,32 @@ export default function ProcurementPage() {
            decimalScale={2}
            min={0}
          />
-          <TextInput
-            label="Lease Start"
-            type="date"
-            value={acqForm.leaseStart}
-            onChange={(e) => setAcqForm({ ...acqForm, leaseStart: e.currentTarget.value })}
-          />
-          <TextInput
-            label="Lease End"
-            type="date"
-            value={acqForm.leaseEnd}
-            onChange={(e) => setAcqForm({ ...acqForm, leaseEnd: e.currentTarget.value })}
-          />
-          <NumberInput
-            label="Monthly Payment"
-            placeholder="0.00"
-            value={acqForm.monthlyPayment}
-            onChange={(val) =>
-              setAcqForm({ ...acqForm, monthlyPayment: val as number | undefined })
-            }
-            decimalScale={2}
-            min={0}
-          />
+          {acqForm.acquisitionType !== "PURCHASE" && (
+            <>
+              <TextInput
+                label="Lease Start"
+                type="date"
+                value={acqForm.leaseStart}
+                onChange={(e) => setAcqForm({ ...acqForm, leaseStart: e.currentTarget.value })}
+              />
+              <TextInput
+                label="Lease End"
+                type="date"
+                value={acqForm.leaseEnd}
+                onChange={(e) => setAcqForm({ ...acqForm, leaseEnd: e.currentTarget.value })}
+              />
+              <NumberInput
+                label="Monthly Payment"
+                placeholder="0.00"
+                value={acqForm.monthlyPayment}
+                onChange={(val) =>
+                  setAcqForm({ ...acqForm, monthlyPayment: val as number | undefined })
+                }
+                decimalScale={2}
+                min={0}
+              />
+            </>
+          )}
          <Select
            label="Status"
            data={ACQUISITION_STATUSES}
@@ -514,7 +541,7 @@ export default function ProcurementPage() {
            <Button
              onClick={() => createAcquisition.mutate()}
              loading={createAcquisition.isPending}
-              disabled={!acqForm.acquisitionDate}
+              disabled={!acqForm.acquisitionDate || acqForm.itemName.trim().length < 2}
            >
              Save Acquisition
            </Button>
--- a/apps/edr-freight-web/backoffice/src/services/procurement.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/procurement.service.ts
@@ -20,6 +20,7 @@ export interface Vendor {

 export interface AssetAcquisition {
  id: string;
+  itemName?: string | null;
  vehicleId?: string | null;
  vendorId?: string | null;
  acquisitionType: AcquisitionType;