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>

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;

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;
 

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);
+  });
+});

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);
   }