Merge branch 'dev' of github.com:Tria-plc/edr-platform into freight/hot_fix

apps/edr-freight-api/src/modules/first-mile/dto/allocate-containers.dto.ts

@@ -0,0 +1,8 @@
+export class FirstMileContainerAllocationDto {
+  containerId!: string;
+  vehicleId!: string;
+}
+
+export class AllocateFirstMileContainersDto {
+  allocations!: FirstMileContainerAllocationDto[];
+}

apps/edr-freight-api/src/modules/first-mile/entities/first-mile-container-allocation.entity.ts

@@ -0,0 +1,36 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+
+import { FirstMile } from './first-mile.entity';
+import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+
+@Entity({ name: 'first_mile_container_allocations', schema: 'freight' })
+@Index(['firstMileId'])
+@Index(['vehicleId'])
+export class FirstMileContainerAllocation extends BaseEntity {
+  @Column({ name: 'first_mile_id', type: 'uuid' })
+  firstMileId!: string;
+
+  @ManyToOne(() => FirstMile, (firstMile) => firstMile.containerAllocations, {
+    nullable: false,
+    eager: false,
+  })
+  @JoinColumn({ name: 'first_mile_id' })
+  firstMile?: FirstMile;
+
+  @Column({ name: 'container_id', type: 'uuid' })
+  containerId!: string;
+
+  @Column({ name: 'vehicle_id', type: 'uuid', nullable: true })
+  vehicleId?: string | null;
+
+  @ManyToOne(() => Vehicle, { nullable: true, eager: false })
+  @JoinColumn({ name: 'vehicle_id' })
+  vehicle?: Vehicle | null;
+
+  @Column({ name: 'container_type', type: 'text' })
+  containerType!: string;
+
+  @Column({ name: 'quantity', type: 'int', default: 1 })
+  quantity!: number;
+}

apps/edr-freight-api/src/modules/first-mile/entities/first-mile.entity.ts

@@ -1,8 +1,9 @@
 import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
 
 import { Booking } from '../../bookings/entities/booking.entity';
 import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+import { FirstMileContainerAllocation } from './first-mile-container-allocation.entity';
 
 export const FIRST_MILE_STATUSES = [
   'PAYMENT_PENDING',
@@ -50,4 +51,11 @@ export class FirstMile extends BaseEntity {
   @ManyToOne(() => Vehicle, { nullable: true, eager: false })
   @JoinColumn({ name: 'vehicle_id' })
   vehicle?: Vehicle | null;
+
+  @OneToMany(
+    () => FirstMileContainerAllocation,
+    (containerAllocation) => containerAllocation.firstMile,
+    { eager: false },
+  )
+  containerAllocations!: FirstMileContainerAllocation[];
 }

apps/edr-freight-api/src/modules/first-mile/first-mile-invoice.service.ts

@@ -0,0 +1,106 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Freight } from '@edr/types';
+
+import {
+  BillingService,
+  InvoiceEventPayload,
+} from '../billing/billing.service';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { FirstMileRepository } from './first-mile.repository';
+import { FirstMile } from './entities/first-mile.entity';
+
+/**
+ * Owns the first-mile ⇄ invoice mapping — the one place that knows how a
+ * first-mile record turns into invoices, which type to use, and how it
+ * advances when paid. First-mile records are billable entities, so they
+ * generate their own invoices directly via {@link BillingService}.
+ */
+@Injectable()
+export class FirstMileInvoiceService {
+  private readonly logger = new Logger(FirstMileInvoiceService.name);
+
+  constructor(
+    private readonly billing: BillingService,
+    private readonly firstMileRepo: FirstMileRepository,
+  ) {}
+
+  /**
+   * Ensure the first-mile record has its invoice, generating one from the
+   * remaining payment if absent. Called when a first-mile record reaches a
+   * billable state. Idempotent — returns the existing open invoice instead
+   * of a duplicate. Returns `null` (and logs) when the record is not billable:
+   * no company to bill.
+   */
+  async ensureInvoiceFor(record: FirstMile): Promise<Invoice | null> {
+    const existing = await this.billing.findPayable(
+      'first_mile' as Freight.InvoiceSource,
+      record.id,
+      'DELIVERY_FEE',
+    );
+    if (existing) return existing;
+
+    if (!record.bookingId) {
+      this.logger.warn(
+        `Skipping invoice for first-mile record ${record.id}: no booking to reference.`,
+      );
+      return null;
+    }
+
+    // Fetch the booking to get the companyId and companyProfileId
+    const fm = record.booking ? record : (await this.firstMileRepo.findById(record.bookingId, { relations: { booking: true } }));
+    if (!fm) return null;
+    if (!fm.booking?.companyId) {
+      this.logger.warn(
+        `Skipping invoice for first-mile record ${record.id}: no company to bill.`,
+      );
+      return null;
+    }
+
+    const totalAmount = record.remainingPayment || 0;
+    if (!Number.isFinite(totalAmount) || totalAmount <= 0) {
+      this.logger.warn(
+        `Skipping invoice for first-mile record ${record.id}: no remaining payment.`,
+      );
+      return null;
+    }
+
+    return this.billing.generateInvoice({
+      source: 'first_mile' as Freight.InvoiceSource,
+      sourceId: record.id,
+      type: 'DELIVERY_FEE',
+      companyId: fm.booking!.companyId,
+      companyProfileId: fm.booking!.companyProfileId || '',
+      currency: 'ETB',
+      lines: [
+        {
+          chargeType: 'DELIVERY',
+          description: 'First-mile delivery',
+          quantity: 1,
+          unitRate: totalAmount,
+          amount: totalAmount,
+        },
+      ],
+      totalAmount,
+    });
+  }
+
+  /**
+   * React to a first-mile invoice being paid — the settlement branch point.
+   * Mark the first-mile record as having completed post-payment processing.
+   */
+  @OnEvent('first_mile.invoice.paid')
+  async onPaid(payload: InvoiceEventPayload): Promise<void> {
+    if (payload.type === 'DELIVERY_FEE') {
+      const record = await this.firstMileRepo.findById(payload.sourceId);
+      if (!record) {
+        this.logger.warn(
+          `Cannot mark unknown first-mile record ${payload.sourceId} as paid.`,
+        );
+        return;
+      }
+
+      this.logger.log(`First-mile invoice paid for record ${payload.sourceId}.`);
+    }
+  }
+}

apps/edr-freight-api/src/modules/first-mile/first-mile.controller.ts

@@ -17,15 +17,20 @@ import { TrainSchedulingManage, TrainSchedulingView } from '../../common/booking
 
 import { CreateFirstMileDto } from './dto/create-first-mile.dto';
 import { UpdateFirstMileDto } from './dto/update-first-mile.dto';
+import { AllocateFirstMileContainersDto } from './dto/allocate-containers.dto';
 import { FirstMileStatus } from './entities/first-mile.entity';
 import { FirstMileService } from './first-mile.service';
+import { FirstMileInvoiceService } from './first-mile-invoice.service';
 
 @ApiTags('first-mile')
 @ApiBearerAuth()
 @Controller('first-mile')
 @TrainSchedulingView()
 export class FirstMileController {
-  constructor(private readonly firstMileService: FirstMileService) {}
+  constructor(
+    private readonly firstMileService: FirstMileService,
+    private readonly firstMileInvoiceService: FirstMileInvoiceService,
+  ) {}
 
   @Get()
   @ApiOperation({ summary: 'List first-mile legs' })
@@ -72,8 +77,13 @@ export class FirstMileController {
   @Patch(':id')
   @TrainSchedulingManage()
   @ApiOperation({ summary: 'Update a first-mile leg' })
-  update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateFirstMileDto) {
-    return this.firstMileService.update(id, dto);
+  async update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateFirstMileDto) {
+    const record = await this.firstMileService.update(id, dto);
+    // Auto-generate invoice if distance or payment was updated
+    if (dto.exactKm !== undefined || dto.remainingPayment !== undefined) {
+      await this.firstMileInvoiceService.ensureInvoiceFor(record);
+    }
+    return record;
   }
 
   @Delete(':id')
@@ -83,4 +93,14 @@ export class FirstMileController {
   remove(@Param('id', ParseUUIDPipe) id: string) {
     return this.firstMileService.remove(id);
   }
+
+  @Post(':firstMileId/allocate-containers')
+  @TrainSchedulingManage()
+  @ApiOperation({ summary: 'Allocate containers to vehicles for a first-mile leg' })
+  allocateContainers(
+    @Param('firstMileId', ParseUUIDPipe) firstMileId: string,
+    @Body() dto: AllocateFirstMileContainersDto,
+  ) {
+    return this.firstMileService.allocateContainers(firstMileId, dto.allocations);
+  }
 }

apps/edr-freight-api/src/modules/first-mile/first-mile.module.ts

@@ -1,25 +1,29 @@
 import { Module, forwardRef } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
+import { BillingModule } from '../billing/billing.module';
 import { BookingsModule } from '../bookings/bookings.module';
 import { DriversModule } from '../drivers/drivers.module';
 import { NotificationsModule } from '../notifications/notifications.module';
 import { VehiclesModule } from '../vehicles/vehicles.module';
 import { FirstMile } from './entities/first-mile.entity';
+import { FirstMileContainerAllocation } from './entities/first-mile-container-allocation.entity';
 import { FirstMileController } from './first-mile.controller';
+import { FirstMileInvoiceService } from './first-mile-invoice.service';
 import { FirstMileRepository } from './first-mile.repository';
 import { FirstMileService } from './first-mile.service';
 
 @Module({
   imports: [
-    TypeOrmModule.forFeature([FirstMile]),
+    TypeOrmModule.forFeature([FirstMile, FirstMileContainerAllocation]),
+    BillingModule,
     forwardRef(() => BookingsModule),
     VehiclesModule,
     DriversModule,
     NotificationsModule,
   ],
   controllers: [FirstMileController],
-  providers: [FirstMileRepository, FirstMileService],
-  exports: [FirstMileRepository, FirstMileService],
+  providers: [FirstMileRepository, FirstMileService, FirstMileInvoiceService],
+  exports: [FirstMileRepository, FirstMileService, FirstMileInvoiceService],
 })
 export class FirstMileModule {}

apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts

@@ -1,5 +1,7 @@
 import { BadRequestException, ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { FindOptionsWhere } from 'typeorm';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { DataSource } from 'typeorm';
 
 import { BookingsRepository } from '../bookings/bookings.repository';
 import { DriversService } from '../drivers/drivers.service';
@@ -8,6 +10,7 @@ import { VehiclesService } from '../vehicles/vehicles.service';
 import { CreateFirstMileDto } from './dto/create-first-mile.dto';
 import { UpdateFirstMileDto } from './dto/update-first-mile.dto';
 import { FirstMile, FirstMileStatus } from './entities/first-mile.entity';
+import { FirstMileContainerAllocation } from './entities/first-mile-container-allocation.entity';
 import { FirstMileRepository } from './first-mile.repository';
 
 type FirstMileListFilter = {
@@ -32,6 +35,7 @@ export class FirstMileService {
   private readonly logger = new Logger(FirstMileService.name);
 
   constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
     private readonly firstMileRepository: FirstMileRepository,
     private readonly bookingsRepository: BookingsRepository,
     private readonly vehiclesService: VehiclesService,
@@ -273,4 +277,35 @@ export class FirstMileService {
     await this.findById(id);
     await this.firstMileRepository.softDelete(id);
   }
+
+  async allocateContainers(
+    firstMileId: string,
+    allocations: Array<{ containerId: string; vehicleId: string }>,
+  ) {
+    const firstMile = await this.findById(firstMileId);
+    if (!firstMile) {
+      throw new NotFoundException(`First-mile record ${firstMileId} not found`);
+    }
+
+    await this.dataSource.transaction(async (manager) => {
+      for (const allocation of allocations) {
+        await manager.delete(FirstMileContainerAllocation, {
+          firstMileId,
+          containerId: allocation.containerId,
+        });
+        await manager.insert(FirstMileContainerAllocation, {
+          firstMileId,
+          containerId: allocation.containerId,
+          vehicleId: allocation.vehicleId,
+          containerType: 'CONTAINER',
+          quantity: 1,
+        });
+      }
+    });
+
+    return {
+      success: true,
+      allocated: allocations.length,
+    };
+  }
 }