Merge pull request #243 from Tria-plc/freight_feature/profile

Freight feature/profile

apps/edr-freight-api/src/modules/booking-orders/booking-orders.controller.ts

@@ -0,0 +1,53 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+} from '@nestjs/common';
+import { CurrentUser } from '@edr/api-common';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { BookingOrdersService } from './booking-orders.service';
+import { CreateBookingOrderDto } from './dto/create-booking-order.dto';
+import { GeneralContractService } from './general-contract.service';
+
+@ApiTags('Booking Orders')
+@Controller('booking-orders')
+export class BookingOrdersController {
+  constructor(
+    private readonly ordersService: BookingOrdersService,
+    private readonly generalContractService: GeneralContractService,
+  ) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Place a drawdown order against a general contract' })
+  async create(
+    @Body() dto: CreateBookingOrderDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.ordersService.create(dto, user?.id);
+  }
+
+  @Get()
+  @ApiOperation({ summary: 'List orders placed against a contract' })
+  async list(@Query('contractBookingId', ParseUUIDPipe) contractBookingId: string) {
+    return this.ordersService.listByContract(contractBookingId);
+  }
+
+  @Get('contract/:id/pool')
+  @ApiOperation({
+    summary: 'Contracted / ordered / remaining quantities for a general contract',
+  })
+  async pool(@Param('id', ParseUUIDPipe) id: string) {
+    return this.generalContractService.getQuantityLines(id);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get a single booking order' })
+  async findOne(@Param('id', ParseUUIDPipe) id: string) {
+    return this.ordersService.findById(id);
+  }
+}

apps/edr-freight-api/src/modules/booking-orders/booking-orders.module.ts

@@ -0,0 +1,30 @@
+import { forwardRef, Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { BookingsModule } from '../bookings/bookings.module';
+import { CompaniesModule } from '../companies/companies.module';
+import { DropdownSettingsModule } from '../dropdown-settings/dropdown-settings.module';
+import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.module';
+import { BookingOrdersController } from './booking-orders.controller';
+import { BookingOrdersRepository } from './booking-orders.repository';
+import { BookingOrdersService } from './booking-orders.service';
+import { BookingOrder } from './entities/booking-order.entity';
+import { BookingOrderLine } from './entities/booking-order-line.entity';
+import { GeneralContractService } from './general-contract.service';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([BookingOrder, BookingOrderLine]),
+    BookingsModule,
+    CompaniesModule,
+    DropdownSettingsModule,
+    forwardRef(() => TrainSchedulingModule),
+  ],
+  controllers: [BookingOrdersController],
+  providers: [
+    BookingOrdersService,
+    BookingOrdersRepository,
+    GeneralContractService,
+  ],
+  exports: [BookingOrdersService, GeneralContractService],
+})
+export class BookingOrdersModule {}

apps/edr-freight-api/src/modules/booking-orders/booking-orders.repository.ts

@@ -0,0 +1,41 @@
+import { BaseRepository } from '@edr/api-common';
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { BookingOrder } from './entities/booking-order.entity';
+
+@Injectable()
+export class BookingOrdersRepository extends BaseRepository<BookingOrder> {
+  constructor(
+    @InjectRepository(BookingOrder)
+    repository: Repository<BookingOrder>,
+  ) {
+    super(repository);
+  }
+
+  /** Orders placed against a given contract, newest first, with their lines. */
+  findByContract(contractBookingId: string): Promise<BookingOrder[]> {
+    return this.repository.find({
+      where: { contractBookingId },
+      relations: { lines: { containerType: true }, booking: true },
+      order: { createdAt: 'DESC' },
+    });
+  }
+
+  override findById(id: string): Promise<BookingOrder | null> {
+    return this.repository.findOne({
+      where: { id },
+      relations: { lines: { containerType: true }, booking: true, contractBooking: true },
+    });
+  }
+
+  /** Count this calendar year's orders, for reference generation. */
+  async countByYear(year: number): Promise<number> {
+    const start = new Date(Date.UTC(year, 0, 1));
+    const end = new Date(Date.UTC(year + 1, 0, 1));
+    return this.repository
+      .createQueryBuilder('o')
+      .where('o.createdAt >= :start AND o.createdAt < :end', { start, end })
+      .getCount();
+  }
+}

apps/edr-freight-api/src/modules/booking-orders/booking-orders.service.ts

@@ -0,0 +1,293 @@
+import {
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { BookingsRepository } from '../bookings/bookings.repository';
+import { Booking } from '../bookings/entities/booking.entity';
+import { BookingContainer } from '../bookings/entities/booking-container.entity';
+import { CompaniesService } from '../companies/companies.service';
+import { ContainerType } from '../rule-engine/entities/container-type.entity';
+import { BookingBatchService } from '../train-scheduling/booking-batch.service';
+import { TrainSchedulingService } from '../train-scheduling/train-scheduling.service';
+import { eatDay } from '../train-scheduling/batch-window.util';
+import { BookingOrdersRepository } from './booking-orders.repository';
+import { CreateBookingOrderDto } from './dto/create-booking-order.dto';
+import { BookingOrder } from './entities/booking-order.entity';
+import { BookingOrderLine } from './entities/booking-order-line.entity';
+import { GeneralContractService } from './general-contract.service';
+
+@Injectable()
+export class BookingOrdersService {
+  private readonly logger = new Logger(BookingOrdersService.name);
+
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly ordersRepository: BookingOrdersRepository,
+    private readonly bookingsRepository: BookingsRepository,
+    private readonly companiesService: CompaniesService,
+    private readonly generalContractService: GeneralContractService,
+    @Inject(forwardRef(() => BookingBatchService))
+    private readonly bookingBatchService: BookingBatchService,
+    @Inject(forwardRef(() => TrainSchedulingService))
+    private readonly trainSchedulingService: TrainSchedulingService,
+  ) {}
+
+  /** Orders placed against a contract, with their lines and child booking. */
+  listByContract(contractBookingId: string): Promise<BookingOrder[]> {
+    return this.ordersRepository.findByContract(contractBookingId);
+  }
+
+  findById(id: string): Promise<BookingOrder | null> {
+    return this.ordersRepository.findById(id);
+  }
+
+  /**
+   * Place a drawdown order against an ACTIVE general contract.
+   *
+   * Validates the requested quantities against the remaining pool, then spawns a
+   * ONE_TIME child Booking (PAID + FULLY_EXECUTED, inheriting the contract's
+   * route/cargo/service) so it flows through the existing train-scheduling
+   * pipeline. The order row is the ledger entry linking contract → child booking.
+   */
+  async create(
+    dto: CreateBookingOrderDto,
+    userId?: string,
+  ): Promise<BookingOrder> {
+    const contract = await this.bookingsRepository.findById(dto.contractBookingId);
+    if (!contract) {
+      throw new NotFoundException(`Contract ${dto.contractBookingId} not found`);
+    }
+    if (!this.generalContractService.isGeneralContract(contract)) {
+      throw new BadRequestException('Booking is not a general contract');
+    }
+    if (contract.status !== 'CONTRACT_ACTIVE') {
+      throw new BadRequestException(
+        `Contract is ${contract.status} — orders can only be placed against an ACTIVE contract`,
+      );
+    }
+    if (contract.expiresAt && contract.expiresAt.getTime() <= Date.now()) {
+      throw new BadRequestException('Contract ordering window has expired');
+    }
+
+    // The customer placing the order must own the contract.
+    if (userId && !(await this.userOwnsContract(userId, contract))) {
+      throw new BadRequestException('You do not have access to this contract');
+    }
+
+    // Validate the route has a departure on the chosen day.
+    const day = eatDay(new Date(dto.scheduledDate));
+    const hasDeparture =
+      await this.trainSchedulingService.existsOpenScheduleOnRouteDay(
+        contract.originYardId,
+        contract.destinationYardId,
+        day,
+      );
+    if (!hasDeparture) {
+      throw new BadRequestException(
+        'No departures available on the selected day for this route',
+      );
+    }
+
+    // Validate each line against the remaining pool.
+    const poolLines = await this.generalContractService.getQuantityLines(
+      contract.id,
+    );
+    const isContainer = contract.freightType === 'CONTAINER';
+    for (const line of dto.lines) {
+      if (line.quantity <= 0) {
+        throw new BadRequestException('Order quantities must be greater than zero');
+      }
+      const key = isContainer ? (line.containerTypeId ?? '') : '';
+      const poolLine = poolLines.find((p) => (p.containerTypeId ?? '') === key);
+      if (!poolLine) {
+        throw new BadRequestException(
+          isContainer
+            ? `Container type ${line.containerTypeId} is not part of this contract`
+            : 'This contract has no matching quantity pool',
+        );
+      }
+      if (line.quantity > poolLine.remainingQuantity) {
+        throw new BadRequestException(
+          `Requested ${line.quantity} exceeds remaining ${poolLine.remainingQuantity}` +
+            (poolLine.containerTypeName ? ` for ${poolLine.containerTypeName}` : ''),
+        );
+      }
+    }
+
+    // Persist the order + its child shipment booking atomically.
+    const order = await this.dataSource.transaction(async (manager) => {
+      const childBooking = await this.spawnChildBooking(contract, dto, manager);
+
+      const reference = await this.generateReference();
+      const orderRow = manager.create(BookingOrder, {
+        reference,
+        contractBookingId: contract.id,
+        bookingId: childBooking.id,
+        companyId: contract.companyId ?? null,
+        scheduledDate: new Date(dto.scheduledDate),
+        status: 'PAID',
+        schedulingStatus: 'NOT_SCHEDULED',
+      });
+      const savedOrder = await manager.save(orderRow);
+
+      const lines = dto.lines.map((l) =>
+        manager.create(BookingOrderLine, {
+          orderId: savedOrder.id,
+          containerTypeId: isContainer ? (l.containerTypeId ?? null) : null,
+          quantity: l.quantity,
+        }),
+      );
+      await manager.save(lines);
+      savedOrder.lines = lines;
+      return savedOrder;
+    });
+
+    // Feed the child booking into the day-pool batch so it allocates to a train.
+    try {
+      await this.bookingBatchService.processRouteDay({
+        originYardId: contract.originYardId,
+        destinationYardId: contract.destinationYardId,
+        day,
+      });
+    } catch (err) {
+      this.logger.error(
+        `Batch fill after order ${order.reference} failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    // Close the contract once its pool is exhausted.
+    if (await this.generalContractService.isExhausted(contract.id)) {
+      await this.dataSource
+        .getRepository(Booking)
+        .update(contract.id, { status: 'CONTRACT_CLOSED' });
+      this.logger.log(
+        `Contract ${contract.reference} CLOSED — quantity exhausted`,
+      );
+    }
+
+    return (await this.ordersRepository.findById(order.id)) ?? order;
+  }
+
+  /**
+   * Create the ONE_TIME child booking for an order, inheriting the contract's
+   * shipment context and entering the queue already PAID + FULLY_EXECUTED.
+   */
+  private async spawnChildBooking(
+    contract: Booking,
+    dto: CreateBookingOrderDto,
+    manager: import('typeorm').EntityManager,
+  ): Promise<Booking> {
+    const reference = await this.generateChildBookingReference();
+    const now = new Date();
+    const isContainer = contract.freightType === 'CONTAINER';
+
+    // Sum line quantities × the contract's per-unit weight for the child total.
+    const containerByType = new Map(
+      (contract.bookingContainers ?? []).map((c) => [c.containerTypeId, c]),
+    );
+    let totalWeight = 0;
+    if (isContainer) {
+      for (const line of dto.lines) {
+        const src = containerByType.get(line.containerTypeId ?? '');
+        const vgmPerUnit = src ? Number(src.vgmPerUnitTons) : 0;
+        totalWeight += vgmPerUnit * line.quantity;
+      }
+    } else {
+      totalWeight = dto.lines.reduce((sum, l) => sum + l.quantity, 0);
+    }
+
+    const child = manager.create(Booking, {
+      reference,
+      companyId: contract.companyId ?? null,
+      companyProfileId: contract.companyProfileId ?? null,
+      isGovernment: contract.isGovernment,
+      governmentInstitution: contract.governmentInstitution ?? null,
+      contractType: contract.contractType,
+      previousContractId: contract.id,
+      serviceTypeId: contract.serviceTypeId,
+      firstMilePickupAddress: contract.firstMilePickupAddress ?? null,
+      lastMileDeliveryAddress: contract.lastMileDeliveryAddress ?? null,
+      equipmentReturn: contract.equipmentReturn,
+      originYardId: contract.originYardId,
+      destinationYardId: contract.destinationYardId,
+      tradeDirection: contract.tradeDirection,
+      freightType: contract.freightType,
+      cargoTypeId: contract.cargoTypeId ?? null,
+      cargoFreeText: contract.cargoFreeText ?? null,
+      shippingLineId: contract.shippingLineId ?? null,
+      cargoTotalWeightVgm: totalWeight,
+      isHazardous: contract.isHazardous,
+      paymentCurrency: contract.paymentCurrency,
+      bookingType: 'ONE_TIME',
+      scheduledDate: new Date(dto.scheduledDate),
+      // Already covered by the contract's one-time payment: enter the pool ready
+      // and paid so the batch engine reserves → allocates it immediately.
+      status: 'FULLY_EXECUTED',
+      paymentStatus: 'PAID',
+      fullyExecutedAt: now,
+      customerSignedAt: now,
+      priorityScore: contract.priorityScore,
+      totalAmount: 0,
+      allowConsolidation: false,
+      schedulingStatus: 'NOT_SCHEDULED',
+    });
+    const savedChild = await manager.save(child);
+
+    if (isContainer) {
+      for (const line of dto.lines) {
+        const src = containerByType.get(line.containerTypeId ?? '');
+        const ct = line.containerTypeId
+          ? await manager.getRepository(ContainerType).findOne({
+              where: { id: line.containerTypeId },
+            })
+          : null;
+        const wagonsPerUnit = ct ? Number(ct.wagonsPerUnit) : 1;
+        const vgmPerUnit = src ? Number(src.vgmPerUnitTons) : 0;
+        const row = manager.create(BookingContainer, {
+          bookingId: savedChild.id,
+          containerTypeId: line.containerTypeId ?? null,
+          quantity: line.quantity,
+          vgmPerUnitTons: vgmPerUnit,
+          totalVgmTons: vgmPerUnit * line.quantity,
+          wagonsRequired: Math.ceil(line.quantity * wagonsPerUnit),
+          isOverweight: false,
+        });
+        await manager.save(row);
+      }
+    }
+
+    return savedChild;
+  }
+
+  private async userOwnsContract(
+    userId: string,
+    contract: Booking,
+  ): Promise<boolean> {
+    if (!contract.companyId) return true; // government / staff-created
+    try {
+      const { company } = await this.companiesService.getCompanyInfoByUserId(
+        userId,
+      );
+      return company.id === contract.companyId;
+    } catch {
+      return false;
+    }
+  }
+
+  private async generateReference(): Promise<string> {
+    const year = new Date().getFullYear();
+    const count = await this.ordersRepository.countByYear(year);
+    return `ORD-${year}-${String(count + 1).padStart(6, '0')}`;
+  }
+
+  private async generateChildBookingReference(): Promise<string> {
+    const year = new Date().getFullYear();
+    const count = await this.bookingsRepository.countByYear(year);
+    return `BK-${year}-${String(count + 1).padStart(6, '0')}`;
+  }
+}

apps/edr-freight-api/src/modules/booking-orders/dto/contract-view.dto.ts

@@ -0,0 +1,23 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { CargoUnitOfMeasure } from '@edr/types';
+
+/** A single contracted/ordered/remaining pool line for a general contract. */
+export class ContractQuantityLineView {
+  @ApiProperty({ nullable: true, description: 'Container type id (null for bulk/break-bulk)' })
+  containerTypeId!: string | null;
+
+  @ApiProperty({ nullable: true })
+  containerTypeName!: string | null;
+
+  @ApiProperty({ enum: CargoUnitOfMeasure, nullable: true })
+  unitOfMeasure!: CargoUnitOfMeasure | null;
+
+  @ApiProperty()
+  contractedQuantity!: number;
+
+  @ApiProperty()
+  orderedQuantity!: number;
+
+  @ApiProperty()
+  remainingQuantity!: number;
+}

apps/edr-freight-api/src/modules/booking-orders/dto/create-booking-order.dto.ts

@@ -0,0 +1,45 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Transform, Type } from 'class-transformer';
+import {
+  ArrayMinSize,
+  IsArray,
+  IsDateString,
+  IsNumber,
+  IsOptional,
+  IsUUID,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+
+export class CreateBookingOrderLineDto {
+  @ApiPropertyOptional({
+    format: 'uuid',
+    description: 'Container type for this line (CONTAINER contracts). Omit for bulk/break-bulk.',
+  })
+  @IsOptional()
+  @IsUUID()
+  containerTypeId?: string;
+
+  @ApiProperty({ description: 'Quantity to draw down (containers, tons, or items)', minimum: 0 })
+  @IsNumber()
+  @Min(0)
+  @Transform(({ value }) => Number(value))
+  quantity!: number;
+}
+
+export class CreateBookingOrderDto {
+  @ApiProperty({ format: 'uuid', description: 'The general contract to draw down from' })
+  @IsUUID()
+  contractBookingId!: string;
+
+  @ApiProperty({ example: '2026-07-01T00:00:00.000Z', description: 'Shipment day for this order' })
+  @IsDateString()
+  scheduledDate!: string;
+
+  @ApiProperty({ type: [CreateBookingOrderLineDto] })
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => CreateBookingOrderLineDto)
+  lines!: CreateBookingOrderLineDto[];
+}

apps/edr-freight-api/src/modules/booking-orders/entities/booking-order-line.entity.ts

@@ -0,0 +1,30 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
+import { ContainerType } from '../../rule-engine/entities/container-type.entity';
+import { BookingOrder } from './booking-order.entity';
+
+/**
+ * One drawn-down quantity line of an order. For CONTAINER contracts there is one
+ * line per container type (matching the contract's pools); for BULK/BREAK_BULK a
+ * single line with a null containerTypeId carries the tons/items.
+ */
+@Entity({ schema: 'freight', name: 'booking_order_lines' })
+export class BookingOrderLine extends BaseEntity {
+  @Column({ name: 'order_id', type: 'uuid' })
+  orderId!: string;
+
+  @ManyToOne(() => BookingOrder, (order) => order.lines, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'order_id' })
+  order?: BookingOrder;
+
+  @Column({ name: 'container_type_id', type: 'uuid', nullable: true })
+  containerTypeId?: string | null;
+
+  @ManyToOne(() => ContainerType, { nullable: true })
+  @JoinColumn({ name: 'container_type_id' })
+  containerType?: ContainerType | null;
+
+  /** Containers (count), tons, or items depending on the contract's freight/UoM. */
+  @Column({ name: 'quantity', type: 'numeric', precision: 12, scale: 3 })
+  quantity!: number;
+}

apps/edr-freight-api/src/modules/booking-orders/entities/booking-order.entity.ts

@@ -0,0 +1,62 @@
+import { BaseEntity } from '@edr/api-common';
+import { SchedulingStatus } from '@edr/types';
+import { Column, Entity, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
+import { Booking } from '../../bookings/entities/booking.entity';
+import { Company } from '../../companies/entities/company.entity';
+import { BookingOrderLine } from './booking-order-line.entity';
+
+/**
+ * A single drawdown against a general contract. Each order spawns its own
+ * ONE_TIME child Booking (the shipment that enters the train scheduling
+ * pipeline); this row is the ledger entry linking the contract to that
+ * shipment and recording the drawn-down quantities.
+ */
+@Entity({ schema: 'freight', name: 'booking_orders' })
+export class BookingOrder extends BaseEntity {
+  @Column({ name: 'reference', type: 'varchar', length: 64, unique: true })
+  reference!: string;
+
+  /** The general contract (a Booking with bookingType = GENERAL_CONTRACT). */
+  @Column({ name: 'contract_booking_id', type: 'uuid' })
+  contractBookingId!: string;
+
+  @ManyToOne(() => Booking)
+  @JoinColumn({ name: 'contract_booking_id' })
+  contractBooking?: Booking;
+
+  /** The ONE_TIME child shipment booking spawned for this order. */
+  @Column({ name: 'booking_id', type: 'uuid', nullable: true })
+  bookingId?: string | null;
+
+  @ManyToOne(() => Booking, { nullable: true })
+  @JoinColumn({ name: 'booking_id' })
+  booking?: Booking | null;
+
+  /** Denormalized from the contract for fast company-scoped filtering. */
+  @Column({ name: 'company_id', type: 'uuid', nullable: true })
+  companyId?: string | null;
+
+  @ManyToOne(() => Company, { nullable: true })
+  @JoinColumn({ name: 'company_id' })
+  company?: Company | null;
+
+  @Column({ name: 'scheduled_date', type: 'timestamptz' })
+  scheduledDate!: Date;
+
+  @Column({ name: 'status', type: 'varchar', length: 40, default: 'PAID' })
+  status!: string;
+
+  @Column({
+    name: 'scheduling_status',
+    type: 'varchar',
+    length: 30,
+    default: SchedulingStatus.NotScheduled,
+  })
+  schedulingStatus!: string;
+
+  @Column({ name: 'train_schedule_id', type: 'uuid', nullable: true })
+  trainScheduleId?: string | null;
+
+  @OneToMany(() => BookingOrderLine, (line) => line.order, { cascade: true })
+  lines?: BookingOrderLine[];
+}

apps/edr-freight-api/src/modules/booking-orders/general-contract.service.ts

@@ -0,0 +1,161 @@
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { BookingType, CargoUnitOfMeasure } from '@edr/types';
+import { DataSource } from 'typeorm';
+import { DropdownSettingsService } from '../dropdown-settings/dropdown-settings.service';
+import { Booking } from '../bookings/entities/booking.entity';
+import { BookingOrder } from './entities/booking-order.entity';
+import { ContractQuantityLineView } from './dto/contract-view.dto';
+
+/** Setting code holding the global ordering window (in months) for general contracts. */
+export const CONTRACT_PERIOD_SETTING_CODE = 'general_contract_period';
+/** Fallback when the setting is missing or unparseable. */
+export const DEFAULT_CONTRACT_PERIOD_MONTHS = 3;
+
+/**
+ * Owns general-contract concerns that sit alongside the generic booking flow:
+ * the configurable ordering period, post-payment activation, and computing the
+ * remaining drawdown pool per contract.
+ */
+@Injectable()
+export class GeneralContractService {
+  private readonly logger = new Logger(GeneralContractService.name);
+
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly dropdownSettings: DropdownSettingsService,
+  ) {}
+
+  isGeneralContract(booking: Pick<Booking, 'bookingType'>): boolean {
+    return booking.bookingType === BookingType.GeneralContract;
+  }
+
+  /** The configured ordering window in months (defaults to 3). */
+  async getPeriodMonths(): Promise<number> {
+    try {
+      const setting = await this.dropdownSettings.getByCode(
+        CONTRACT_PERIOD_SETTING_CODE,
+      );
+      const raw = setting.children?.[0]?.value;
+      const months = Number(raw);
+      if (Number.isFinite(months) && months > 0) return months;
+    } catch {
+      // Setting not seeded yet — fall back to the default.
+    }
+    return DEFAULT_CONTRACT_PERIOD_MONTHS;
+  }
+
+  /**
+   * Called when a general contract's payment succeeds: mark it ACTIVE (instead of
+   * entering the train queue like a one-time booking) and stamp the ordering
+   * window. Idempotent.
+   */
+  async activateAfterPayment(bookingId: string): Promise<void> {
+    const repo = this.dataSource.getRepository(Booking);
+    const booking = await repo.findOne({ where: { id: bookingId } });
+    if (!booking || !this.isGeneralContract(booking)) return;
+    if (booking.status === 'CONTRACT_ACTIVE' || booking.status === 'CONTRACT_CLOSED') {
+      return;
+    }
+
+    const months = await this.getPeriodMonths();
+    const expiresAt = new Date();
+    expiresAt.setMonth(expiresAt.getMonth() + months);
+
+    await repo.update(bookingId, {
+      status: 'CONTRACT_ACTIVE',
+      paymentStatus: 'PAID',
+      expiresAt,
+    });
+    this.logger.log(
+      `General contract ${booking.reference} ACTIVE — ordering window ${months} month(s) (expires ${expiresAt.toISOString()})`,
+    );
+  }
+
+  /**
+   * The drawdown pool for a contract: contracted vs. ordered vs. remaining,
+   * per container type for CONTAINER contracts, or a single total line for
+   * BULK/BREAK_BULK (keyed on a null container type).
+   */
+  async getQuantityLines(
+    contractBookingId: string,
+  ): Promise<ContractQuantityLineView[]> {
+    const booking = await this.dataSource.getRepository(Booking).findOne({
+      where: { id: contractBookingId },
+      relations: { bookingContainers: { containerType: true }, cargoType: true },
+    });
+    if (!booking) throw new NotFoundException(`Contract ${contractBookingId} not found`);
+
+    const ordered = await this.orderedByContainerType(contractBookingId);
+
+    if (booking.freightType === 'CONTAINER') {
+      return (booking.bookingContainers ?? []).map((c) => {
+        const orderedQty = ordered.get(c.containerTypeId ?? '') ?? 0;
+        const contracted = Number(c.quantity);
+        return {
+          containerTypeId: c.containerTypeId ?? null,
+          containerTypeName: c.containerType?.label ?? null,
+          unitOfMeasure: null,
+          contractedQuantity: contracted,
+          orderedQuantity: orderedQty,
+          remainingQuantity: Math.max(0, contracted - orderedQty),
+        };
+      });
+    }
+
+    // BULK / BREAK_BULK — a single pool keyed on the contracted total weight/items.
+    const orderedQty = ordered.get('') ?? 0;
+    const contracted = Number(booking.cargoTotalWeightVgm);
+    const uom: CargoUnitOfMeasure | null =
+      (booking.cargoType?.unitOfMeasure as CargoUnitOfMeasure | undefined) ??
+      CargoUnitOfMeasure.PerTon;
+    return [
+      {
+        containerTypeId: null,
+        containerTypeName: null,
+        unitOfMeasure: uom,
+        contractedQuantity: contracted,
+        orderedQuantity: orderedQty,
+        remainingQuantity: Math.max(0, contracted - orderedQty),
+      },
+    ];
+  }
+
+  /** Sum of non-cancelled order line quantities, keyed by container type id ('' = bulk). */
+  private async orderedByContainerType(
+    contractBookingId: string,
+  ): Promise<Map<string, number>> {
+    const rows = await this.dataSource
+      .getRepository(BookingOrder)
+      .createQueryBuilder('o')
+      .innerJoin('o.lines', 'line')
+      .select('COALESCE(line.container_type_id::text, :empty)', 'key')
+      .addSelect('SUM(line.quantity)', 'total')
+      .where('o.contract_booking_id = :contractBookingId', { contractBookingId })
+      .andWhere(`o.status NOT IN ('CANCELLED', 'REJECTED')`)
+      .setParameter('empty', '')
+      .groupBy('key')
+      .getRawMany<{ key: string; total: string }>();
+
+    const map = new Map<string, number>();
+    for (const row of rows) map.set(row.key ?? '', Number(row.total));
+    return map;
+  }
+
+  /** Convenience: how many units remain for a given container type ('' = bulk). */
+  async remainingFor(
+    contractBookingId: string,
+    containerTypeKey: string,
+  ): Promise<number> {
+    const lines = await this.getQuantityLines(contractBookingId);
+    const line = lines.find(
+      (l) => (l.containerTypeId ?? '') === containerTypeKey,
+    );
+    return line?.remainingQuantity ?? 0;
+  }
+
+  /** True once every contracted line is fully drawn down. */
+  async isExhausted(contractBookingId: string): Promise<boolean> {
+    const lines = await this.getQuantityLines(contractBookingId);
+    return lines.every((l) => l.remainingQuantity <= 0);
+  }
+}

apps/edr-freight-api/src/modules/bookings/booking-pricing.service.spec.ts

@@ -28,15 +28,15 @@ describe('BookingPricingService — domestic corridor', () => {
   let service: BookingPricingService;
   let bookingsRepository: { calculateWagonCount: jest.Mock };
   let ratesService: { findLiveRates: jest.Mock };
-  let cbeExchangeService: { getUsdToEtbRate: jest.Mock };
+  let exchangeService: { getRate: jest.Mock };
 
   beforeEach(() => {
     bookingsRepository = { calculateWagonCount: jest.fn().mockResolvedValue(2) };
     ratesService = {
       findLiveRates: jest.fn().mockResolvedValue([intercityBulkUsd, intercityContainerUsd]),
     };
-    cbeExchangeService = {
-      getUsdToEtbRate: jest.fn().mockResolvedValue(MOCK_CBE_RATE),
+    exchangeService = {
+      getRate: jest.fn().mockResolvedValue(MOCK_CBE_RATE),
     };
 
     service = new BookingPricingService(
@@ -45,7 +45,7 @@ describe('BookingPricingService — domestic corridor', () => {
       {} as never,
       ratesService as never,
       {} as never,
-      cbeExchangeService as never,
+      exchangeService as never,
     );
   });
 

apps/edr-freight-api/src/modules/bookings/booking-pricing.service.ts

@@ -4,7 +4,7 @@ import { ContainerTypesService } from '../rule-engine/services/container-types.s
 import { RatesService } from '../rule-engine/services/rates.service';
 import { ServiceTypesService } from '../rule-engine/services/service-types.service';
 import { Rate } from '../rule-engine/entities/rate.entity';
-import { CbeExchangeService } from '../cbe-exchange/cbe-exchange.service';
+import { ExchangeService } from '@edr/api-common';
 import {
   AppliedCargoModifier,
   BookingEvaluationInput,
@@ -41,7 +41,7 @@ export class BookingPricingService {
     private readonly containerTypesService: ContainerTypesService,
     private readonly ratesService: RatesService,
     private readonly serviceTypesService: ServiceTypesService,
-    private readonly cbeExchangeService: CbeExchangeService,
+    private readonly exchangeService: ExchangeService,
   ) {}
 
   async generatePrice(bookingId: string): Promise<GeneratePriceResponseDto> {
@@ -84,7 +84,7 @@ export class BookingPricingService {
 
     const paymentCurrency = booking.paymentCurrency;
     const isEtbBooking = paymentCurrency === 'ETB';
-    const usdToEtb = isEtbBooking ? await this.cbeExchangeService.getUsdToEtbRate() : 1;
+    const usdToEtb = isEtbBooking ? await this.exchangeService.getRate('USD', 'ETB') : 1;
 
     const lineItems: PriceLineItemDto[] = [];
     let total = 0;
@@ -285,7 +285,7 @@ export class BookingPricingService {
     const liveRates = await this.ratesService.findLiveRates();
     const paymentCurrency = booking.paymentCurrency;
     const isEtbBooking = paymentCurrency === 'ETB';
-    const usdToEtb = isEtbBooking ? await this.cbeExchangeService.getUsdToEtbRate() : 1;
+    const usdToEtb = isEtbBooking ? await this.exchangeService.getRate('USD', 'ETB') : 1;
     const isBulk = booking.freightType === 'BULK';
 
     const rateType =

apps/edr-freight-api/src/modules/bookings/booking-reference-data.service.ts

@@ -59,6 +59,7 @@ export function buildCargoTypeTree(
           name: child.cargoTypeName,
           code: child.code,
           show_free_text_box: child.showFreeTextBox,
+          unit_of_measure: child.unitOfMeasure ?? null,
         }),
       );
 

apps/edr-freight-api/src/modules/bookings/bookings.controller.ts

@@ -132,8 +132,31 @@ export class BookingsController {
     const companyId =
       await this.bookingsService.resolveCustomerCompanyId(userId);
     // No linked company yet → no bookings to show (avoids leaking all bookings).
-    if (!companyId) return { items: [], total: 0 };
-    return this.bookingsService.findAll(filter, companyId);
+    if (!companyId) {
+      const page = filter.page ?? 1;
+      const pageSize = filter.pageSize ?? 20;
+      return {
+        items: [],
+        total: 0,
+        meta: {
+          page,
+          pageSize,
+          total: 0,
+          totalPages: 0,
+          hasNextPage: false,
+          hasPreviousPage: false,
+        },
+      };
+    }
+    // Scope to the active operational profile (importer/exporter) when one
+    // resolves; otherwise fall back to company-level scoping.
+    const companyProfileId =
+      await this.bookingsService.resolveActiveCompanyProfileId(userId);
+    return this.bookingsService.findAll(
+      filter,
+      companyId,
+      companyProfileId ?? undefined,
+    );
   }
 
   @Get('list-summary')

apps/edr-freight-api/src/modules/bookings/bookings.module.ts

@@ -1,5 +1,7 @@
 import { Module, forwardRef } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
 import { TypeOrmModule } from '@nestjs/typeorm';
+import { ExchangeModule, ExchangeOptions } from '@edr/api-common';
 
 // import { CustomersModule } from '../customers/customers.module';
 import { CompaniesModule } from '../companies/companies.module';
@@ -31,7 +33,6 @@ import { ContractTemplateResolver } from '../../contracts/contract-template.reso
 import { ContractViewModelBuilder } from '../../contracts/contract-view-model.builder';
 import { PaymentModule } from '../payment/payment.module';
 import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.module';
-import { CbeExchangeService } from '../cbe-exchange/cbe-exchange.service';
 
 @Module({
   imports: [
@@ -52,6 +53,11 @@ import { CbeExchangeService } from '../cbe-exchange/cbe-exchange.service';
     // CustomersModule,
     RuleEngineModule,
     SignaturesModule,
+    ExchangeModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService): ExchangeOptions =>
+        config.get<ExchangeOptions>('app.cbeExchange') ?? {},
+    }),
   ],
   controllers: [BookingsController, PayController],
   providers: [
@@ -68,7 +74,6 @@ import { CbeExchangeService } from '../cbe-exchange/cbe-exchange.service';
     ContractPricingScheduleBuilder,
     ContractRendererService,
     ContractPdfService,
-    CbeExchangeService,
   ],
   exports: [BookingsService, BookingsRepository],
 })

apps/edr-freight-api/src/modules/bookings/bookings.repository.ts

@@ -25,14 +25,18 @@ export interface BookingListFilterOptions {
   schedulingStatuses?: string[];
   assignedToSchedule?: 'true' | 'false';
   companyId?: string;
+  companyProfileId?: string;
   contractType?: string;
   serviceTypeId?: string;
   cargoTypeId?: string;
   freightType?: string;
+  bookingType?: string;
   tradeDirection?: string;
   paymentCurrency?: string;
   paymentStatus?: string;
   excludePaymentStatus?: string;
+  createdFrom?: string;
+  createdTo?: string;
   allowConsolidation?: boolean;
   consolidationPaired?: string;
 }
@@ -434,7 +438,18 @@ export class BookingsRepository extends BaseRepository<Booking> {
     pageSize: number;
     sortBy?: string;
     sortOrder?: 'ASC' | 'DESC';
-  }): Promise<{ items: Booking[]; total: number }> {
+  }): Promise<{
+    items: Booking[];
+    total: number;
+    meta: {
+      page: number;
+      pageSize: number;
+      total: number;
+      totalPages: number;
+      hasNextPage: boolean;
+      hasPreviousPage: boolean;
+    };
+  }> {
     const page = options.page;
     const pageSize = options.pageSize;
 
@@ -481,7 +496,22 @@ export class BookingsRepository extends BaseRepository<Booking> {
       }
     }
 
-    return { items, total };
+    const totalPages = pageSize > 0 ? Math.ceil(total / pageSize) : 0;
+    // Return both the flat `total` (consumed by the backoffice list) and a
+    // `meta` block (consumed by the portal, matching PaginationMeta) so neither
+    // app needs to change its read shape.
+    return {
+      items,
+      total,
+      meta: {
+        page,
+        pageSize,
+        total,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    };
   }
 
   async getStatusCounts(): Promise<Record<string, number>> {
@@ -559,6 +589,11 @@ export class BookingsRepository extends BaseRepository<Booking> {
         companyId: options.companyId,
       });
     }
+    if (options.companyProfileId) {
+      qb.andWhere('booking.company_profile_id = :companyProfileId', {
+        companyProfileId: options.companyProfileId,
+      });
+    }
     if (options.contractType) {
       qb.andWhere('booking.contract_type = :contractType', {
         contractType: options.contractType,
@@ -579,6 +614,22 @@ export class BookingsRepository extends BaseRepository<Booking> {
         freightType: options.freightType,
       });
     }
+    if (options.bookingType) {
+      qb.andWhere('booking.booking_type = :bookingType', {
+        bookingType: options.bookingType,
+      });
+    }
+    if (options.createdFrom) {
+      qb.andWhere('booking.created_at >= :createdFrom', {
+        createdFrom: options.createdFrom,
+      });
+    }
+    if (options.createdTo) {
+      // Inclusive end-of-day: callers pass a date; include the whole day.
+      qb.andWhere('booking.created_at <= :createdTo', {
+        createdTo: options.createdTo,
+      });
+    }
     if (options.tradeDirection) {
       qb.andWhere('booking.trade_direction = :tradeDirection', {
         tradeDirection: options.tradeDirection,

apps/edr-freight-api/src/modules/bookings/bookings.service.ts

@@ -10,6 +10,7 @@ import {
 import { Freight, SchedulingStatus } from '@edr/types';
 // import { CustomersService } from '../customers/customers.service';
 import { CompaniesService } from '../companies/companies.service';
+import { ProfileType } from '../companies/entities/company-profile.entity';
 import { TrainSchedulingService } from '../train-scheduling/train-scheduling.service';
 import { eatDay } from '../train-scheduling/batch-window.util';
 import { FilesService } from '../files/files.service';
@@ -41,6 +42,20 @@ import {
 import { Booking } from './entities/booking.entity';
 import { FileRecord } from '../files/entities/file.entity';
 
+/** Paginated booking list: flat `total` (backoffice) + `meta` block (portal). */
+export interface PaginatedBookings {
+  items: Booking[];
+  total: number;
+  meta: {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+  };
+}
+
 const URGENT_PRIORITY_THRESHOLD = 1000;
 const NEEDS_ACTION_STATUSES = [
   'SUBMITTED',
@@ -257,6 +272,7 @@ export class BookingsService {
     // }
 
     const isGovernment = dto.isGovernment === true;
+    const isGeneralContract = dto.bookingType === 'GENERAL_CONTRACT';
 
     let companyId: string | null | undefined = dto.companyId;
     if (isGovernment) {
@@ -291,11 +307,12 @@ export class BookingsService {
       ) {
         throw new BadRequestException('Selected schedule is not on the booking route');
       }
-    } else {
+    } else if (!isGeneralContract) {
       // Day-level pool: the customer picked a DAY — require that the route has at
       // least one OPEN departure on that EAT day. The batch engine assigns the
-      // train later.
-      const day = eatDay(new Date(dto.scheduledDate));
+      // train later. General contracts skip this — they have no shipment date at
+      // creation; each drawdown order validates its own day.
+      const day = eatDay(new Date(dto.scheduledDate!));
       const hasDeparture =
         await this.trainSchedulingService.existsOpenScheduleOnRouteDay(
           dto.originYardId,
@@ -323,6 +340,29 @@ export class BookingsService {
       dto.tradeDirection,
     );
 
+    // Stamp the operational profile this booking belongs to (importer/exporter)
+    // so the customer portal can scope lists/KPIs to the active mode. Best-effort
+    // for non-government bookings with a resolved company; never blocks creation.
+    let companyProfileId: string | null = null;
+    if (!isGovernment && companyId) {
+      let fallbackType: ProfileType | null = null;
+      if (userId) {
+        try {
+          const { profile } =
+            await this.companiesService.getCompanyInfoByUserId(userId);
+          fallbackType = profile.activeProfileType ?? null;
+        } catch {
+          // No profile (e.g. staff creating on behalf) — fall back to mapping.
+        }
+      }
+      companyProfileId =
+        await this.companiesService.resolveCompanyProfileIdForBooking(
+          companyId,
+          tradeDirection,
+          fallbackType,
+        );
+    }
+
     const allowConsolidation =
       dto.freightType === 'CONTAINER'
         ? await this.resolveConsolidation(containers, dto.allowConsolidation)
@@ -348,6 +388,7 @@ export class BookingsService {
     const booking = await this.bookingsRepository.create({
       reference,
       companyId: companyId ?? null,
+      companyProfileId,
       isGovernment,
       governmentInstitution: isGovernment ? dto.governmentInstitution!.trim() : null,
       trainId: dto.trainId,
@@ -370,7 +411,8 @@ export class BookingsService {
       paymentCurrency: dto.paymentCurrency,
       pnrCode: dto.pnrCode,
       financialTerms: dto.financialTerms,
-      scheduledDate: new Date(dto.scheduledDate),
+      bookingType: isGeneralContract ? 'GENERAL_CONTRACT' : 'ONE_TIME',
+      scheduledDate: dto.scheduledDate ? new Date(dto.scheduledDate) : null,
       startDate: dto.startDate ? new Date(dto.startDate) : undefined,
       endDate: dto.endDate ? new Date(dto.endDate) : undefined,
       status: 'DRAFT',
@@ -504,6 +546,22 @@ export class BookingsService {
       priorityScore: ruleResult.priorityScore,
       tradeDirection,
     };
+    // If the route (hence trade direction) changed, re-stamp the operational
+    // profile so an edited draft doesn't get stranded under the wrong profile.
+    if (
+      tradeDirection !== existing.tradeDirection &&
+      !existing.isGovernment &&
+      existing.companyId
+    ) {
+      updates.companyProfileId =
+        await this.companiesService.resolveCompanyProfileIdForBooking(
+          existing.companyId,
+          tradeDirection,
+          existing.companyProfileId
+            ? undefined
+            : (existing.companyProfile?.type as ProfileType | undefined),
+        );
+    }
     if (dto.scheduledDate) updates.scheduledDate = new Date(dto.scheduledDate);
     if (dto.startDate) updates.startDate = new Date(dto.startDate);
     if (dto.endDate) updates.endDate = new Date(dto.endDate);
@@ -583,7 +641,8 @@ export class BookingsService {
   async findAll(
     filter: FilterBookingDto,
     forceCompanyId?: string,
-  ): Promise<{ items: Booking[]; total: number }> {
+    forceCompanyProfileId?: string,
+  ): Promise<PaginatedBookings> {
     const page = filter.page ?? 1;
     const pageSize = filter.pageSize ?? 20;
     const statusFilter = this.parseStatusFilter(filter);
@@ -597,14 +656,20 @@ export class BookingsService {
       assignedToSchedule: filter.assignedToSchedule,
       // A forced company scope (portal/customer) overrides any caller-provided
       // companyId so a customer can only ever see their own company's bookings.
-      companyId: forceCompanyId ?? filter.companyId,
+      // When an active profile resolves, scope to it; otherwise fall back to the
+      // company so nothing breaks for not-yet-onboarded customers.
+      companyId: forceCompanyProfileId ? undefined : forceCompanyId ?? filter.companyId,
+      companyProfileId: forceCompanyProfileId,
       contractType: filter.contractType,
       serviceTypeId: filter.serviceTypeId,
       cargoTypeId: filter.cargoTypeId,
       freightType: filter.freightType,
+      bookingType: filter.bookingType,
       tradeDirection: filter.tradeDirection,
       paymentCurrency: filter.paymentCurrency,
       paymentStatus: filter.paymentStatus,
+      createdFrom: filter.createdFrom,
+      createdTo: filter.createdTo,
       allowConsolidation: filter.allowConsolidation,
       consolidationPaired: filter.consolidationPaired,
       sortBy: filter.sortBy,
@@ -627,15 +692,20 @@ export class BookingsService {
   async findMyPayable(
     userId: string,
     filter: FilterBookingDto,
-  ): Promise<{ items: Booking[]; total: number }> {
+  ): Promise<PaginatedBookings> {
     const { company } = await this.companiesService.getCompanyInfoByUserId(userId);
+    // Scope to the active operational profile when one resolves; fall back to
+    // company-level so not-yet-onboarded customers still see their payables.
+    const companyProfileId =
+      await this.companiesService.resolveActiveCompanyProfileId(userId);
 
     return this.bookingsRepository.findAllPaginated({
       page: filter.page ?? 1,
       pageSize: filter.pageSize ?? 20,
       statuses: BookingsService.PAYABLE_STATUSES,
       excludePaymentStatus: 'PAID',
-      companyId: company.id,
+      companyId: companyProfileId ? undefined : company.id,
+      companyProfileId: companyProfileId ?? undefined,
       sortBy: filter.sortBy,
       sortOrder: filter.sortOrder,
     });
@@ -655,6 +725,15 @@ export class BookingsService {
     }
   }
 
+  /**
+   * Resolve the active company_profile id a customer's bookings should be
+   * scoped to (importer/exporter mode). Null when not onboarded — callers fall
+   * back to company-level scoping.
+   */
+  async resolveActiveCompanyProfileId(userId: string): Promise<string | null> {
+    return this.companiesService.resolveActiveCompanyProfileId(userId);
+  }
+
   /**
    * Authorize a customer's access to a single booking. Staff are scoped at the
    * controller (they pass `isStaff`); for a customer, the booking must belong
@@ -756,9 +835,12 @@ export class BookingsService {
       serviceTypeId: filter.serviceTypeId,
       cargoTypeId: filter.cargoTypeId,
       freightType: filter.freightType,
+      bookingType: filter.bookingType,
       tradeDirection: filter.tradeDirection,
       paymentCurrency: filter.paymentCurrency,
       paymentStatus: filter.paymentStatus,
+      createdFrom: filter.createdFrom,
+      createdTo: filter.createdTo,
       allowConsolidation: filter.allowConsolidation,
       consolidationPaired: filter.consolidationPaired,
     };

apps/edr-freight-api/src/modules/bookings/dto/booking-reference-data.dto.ts

@@ -1,4 +1,5 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { CargoUnitOfMeasure } from '@edr/types';
 
 export class BookingReferenceYardDto {
   @ApiProperty({ format: 'uuid' })
@@ -73,6 +74,9 @@ export class BookingReferenceCargoTypeChildDto {
 
   @ApiProperty()
   show_free_text_box!: boolean;
+
+  @ApiProperty({ enum: CargoUnitOfMeasure, nullable: true, required: false })
+  unit_of_measure?: CargoUnitOfMeasure | null;
 }
 
 export class BookingReferenceCargoTypeGroupDto {

apps/edr-freight-api/src/modules/bookings/dto/create-booking.dto.ts

@@ -17,7 +17,7 @@ import {
   ValidateIf,
   ValidateNested,
 } from 'class-validator';
-import { BOOKING_STATUSES, FREIGHT_TYPES } from '../entities/booking.entity';
+import { BOOKING_STATUSES, BOOKING_TYPES, FREIGHT_TYPES } from '../entities/booking.entity';
 import { BookingFreightShapeConstraint } from './validators/booking-freight.validator';
 
 const CONTRACT_TYPES = ['NEW', 'RENEWAL'] as const;
@@ -27,6 +27,7 @@ const PAYMENT_CURRENCIES = ['ETB', 'USD'] as const;
 
 export {
   BOOKING_STATUSES,
+  BOOKING_TYPES,
   CONTRACT_TYPES,
   EQUIPMENT_RETURNS,
   FREIGHT_TYPES,
@@ -105,10 +106,24 @@ export class CreateBookingDto {
   @IsUUID()
   trainScheduleId?: string;
 
-  /** The day the customer wants to ship (the pool day key). */
-  @ApiProperty({ example: '2026-06-15T00:00:00.000Z' })
+  @ApiPropertyOptional({
+    enum: BOOKING_TYPES,
+    default: 'ONE_TIME',
+    description:
+      'ONE_TIME (default) for a normal booking; GENERAL_CONTRACT for an umbrella contract drawn down by orders.',
+  })
+  @IsOptional()
+  @IsIn([...BOOKING_TYPES])
+  bookingType?: string;
+
+  /**
+   * The day the customer wants to ship (the pool day key). Required for one-time
+   * bookings; omitted for general contracts, which pick the date per order.
+   */
+  @ApiPropertyOptional({ example: '2026-06-15T00:00:00.000Z' })
+  @ValidateIf((o) => o.bookingType !== 'GENERAL_CONTRACT')
   @IsDateString()
-  scheduledDate!: string;
+  scheduledDate?: string;
 
   @ApiProperty({ enum: CONTRACT_TYPES })
   @IsIn([...CONTRACT_TYPES])

apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts

@@ -1,8 +1,9 @@
 import { ApiPropertyOptional } from '@nestjs/swagger';
 import { Transform } from 'class-transformer';
-import { IsIn, IsOptional, IsUUID } from 'class-validator';
+import { IsDateString, IsIn, IsOptional, IsUUID } from 'class-validator';
 import {
   BOOKING_STATUSES,
+  BOOKING_TYPES,
   FREIGHT_TYPES,
   PAYMENT_CURRENCIES,
   TRADE_DIRECTIONS,
@@ -56,6 +57,21 @@ export class FilterBookingDto {
   @IsIn([...FREIGHT_TYPES])
   freightType?: string;
 
+  @ApiPropertyOptional({ enum: BOOKING_TYPES, description: 'ONE_TIME or GENERAL_CONTRACT' })
+  @IsOptional()
+  @IsIn([...BOOKING_TYPES])
+  bookingType?: string;
+
+  @ApiPropertyOptional({ description: 'Filter bookings created on/after this date (ISO)' })
+  @IsOptional()
+  @IsDateString()
+  createdFrom?: string;
+
+  @ApiPropertyOptional({ description: 'Filter bookings created on/before this date (ISO)' })
+  @IsOptional()
+  @IsDateString()
+  createdTo?: string;
+
   @ApiPropertyOptional({ enum: TRADE_DIRECTIONS })
   @IsOptional()
   @IsIn([...TRADE_DIRECTIONS])

apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts

@@ -3,6 +3,7 @@ import { SchedulingStatus } from '@edr/types';
 import { Column, Entity, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
 // import { Customer } from '../../customers/entities/customer.entity';
 import { Company } from '../../companies/entities/company.entity';
+import { CompanyProfile } from '../../companies/entities/company-profile.entity';
 import { CargoType } from '../../rule-engine/entities/cargo-type.entity';
 import { ServiceType } from '../../rule-engine/entities/service-type.entity';
 import { ShippingLine } from '../../rule-engine/entities/shipping-line.entity';
@@ -40,10 +41,15 @@ export const BOOKING_STATUSES = [
   'CANCELLED',
   'PENDING_CONSOLIDATION',
   'CONSOLIDATED',
+  'CONTRACT_ACTIVE',
+  'CONTRACT_CLOSED',
 ] as const;
 
 export type BookingStatus = (typeof BOOKING_STATUSES)[number];
 
+export const BOOKING_TYPES = ['ONE_TIME', 'GENERAL_CONTRACT'] as const;
+export type BookingTypeValue = (typeof BOOKING_TYPES)[number];
+
 export const PAYMENT_STATUSES = [
   'PENDING',
   'PNR_GENERATED',
@@ -92,6 +98,20 @@ export class Booking extends BaseEntity {
   @JoinColumn({ name: 'company_id' })
   company?: Company | null;
 
+  /**
+   * The operational profile (importer/exporter/forwarder) this booking belongs
+   * to. Stamped at creation from the booking's trade direction (IMPORT→importer,
+   * EXPORT→exporter) or the user's active profile for DOMESTIC/forwarder.
+   * Customer portal lists and dashboard KPIs are scoped by this. Nullable for
+   * legacy/government/staff-created bookings.
+   */
+  @Column({ name: 'company_profile_id', type: 'uuid', nullable: true })
+  companyProfileId?: string | null;
+
+  @ManyToOne(() => CompanyProfile, { nullable: true })
+  @JoinColumn({ name: 'company_profile_id' })
+  companyProfile?: CompanyProfile | null;
+
   @Column({ name: 'is_government', type: 'boolean', default: false })
   isGovernment!: boolean;
 
@@ -110,8 +130,28 @@ export class Booking extends BaseEntity {
   @Column({ name: 'status', type: 'varchar', length: 40, default: 'DRAFT' })
   status!: string;
 
-  @Column({ name: 'scheduled_date', type: 'timestamptz' })
-  scheduledDate!: Date;
+  /**
+   * ONE_TIME for a normal single-shipment booking; GENERAL_CONTRACT for an
+   * umbrella contract that is signed/paid once and then drawn down by many
+   * orders (each order spawns its own ONE_TIME child booking).
+   */
+  @Column({ name: 'booking_type', type: 'varchar', length: 20, default: 'ONE_TIME' })
+  bookingType!: string;
+
+  /**
+   * Nullable: general contracts have no shipment date at creation — the date is
+   * chosen per drawdown order. One-time bookings always set this (the pool day key).
+   */
+  @Column({ name: 'scheduled_date', type: 'timestamptz', nullable: true })
+  scheduledDate?: Date | null;
+
+  /**
+   * General contracts only: when the ordering window closes, computed from the
+   * global CONTRACT_PERIOD_MONTHS setting at activation. Null for one-time
+   * bookings and for contracts that are not yet active.
+   */
+  @Column({ name: 'expires_at', type: 'timestamptz', nullable: true })
+  expiresAt?: Date | null;
 
   @Column({ name: 'total_amount', type: 'numeric', precision: 14, scale: 2, default: 0 })
   totalAmount!: number;

apps/edr-freight-api/src/modules/cbe-exchange/cbe-exchange.service.ts

@@ -1,106 +0,0 @@
-import { Injectable, Logger } from '@nestjs/common';
-import { ConfigService } from '@nestjs/config';
-
-const DEFAULT_SCRAPE_URL = 'https://ethio.forex/bank/CBET';
-
-/** Matches USD buying/selling embedded in ethio.forex CBET page HTML (after entity unescape). */
-const USD_RATE_REGEX =
-  /currency_code":\[0,"USD"\],"currency_name":\[0,"US DOLLAR"\],"buying":\[0,([\d.]+)\],"selling":\[0,([\d.]+)\]/;
-
-@Injectable()
-export class CbeExchangeService {
-  private readonly logger = new Logger(CbeExchangeService.name);
-  private cachedRate: number | null = null;
-  private cacheExpiresAt = 0;
-
-  constructor(private readonly configService: ConfigService) {}
-
-  /**
-   * Returns the current CBE USD→ETB **selling** rate scraped from ethio.forex.
-   * Cached for CBE_EXCHANGE_CACHE_TTL_MS; falls back to CBE_EXCHANGE_FALLBACK_RATE on failure.
-   */
-  async getUsdToEtbRate(): Promise<number> {
-    const now = Date.now();
-
-    if (this.cachedRate !== null && now < this.cacheExpiresAt) {
-      return this.cachedRate;
-    }
-
-    const scrapeUrl = this.getScrapeUrl();
-    const fallbackRate =
-      this.configService.get<number>('app.cbeExchange.fallbackRate') ?? 130;
-    const cacheTtlMs =
-      this.configService.get<number>('app.cbeExchange.cacheTtlMs') ?? 3_600_000;
-
-    try {
-      const response = await fetch(scrapeUrl, {
-        signal: AbortSignal.timeout(8_000),
-        headers: { 'User-Agent': 'Mozilla/5.0' },
-      });
-
-      if (!response.ok) {
-        throw new Error(`CBE scrape responded with status ${response.status}`);
-      }
-
-      const html = await response.text();
-      const rates = this.parseScrapedRates(html);
-
-      if (!rates) {
-        throw new Error('USD rate not found in ethio.forex page HTML');
-      }
-
-      const rate = rates.selling;
-      if (!Number.isFinite(rate) || rate <= 0) {
-        throw new Error(`Invalid selling rate parsed: ${rate}`);
-      }
-
-      this.cachedRate = rate;
-      this.cacheExpiresAt = now + cacheTtlMs;
-      this.logger.log(
-        `CBE USD→ETB rate refreshed from ethio.forex — buying=${rates.buying} selling=${rate}`,
-      );
-      return rate;
-    } catch (err) {
-      this.logger.error(
-        `Failed to scrape CBE exchange rate — using fallback ${fallbackRate} ETB/USD. Error: ${(err as Error).message}`,
-      );
-
-      if (this.cachedRate !== null) {
-        this.logger.warn(`Using previously cached CBE rate: ${this.cachedRate}`);
-        return this.cachedRate;
-      }
-
-      return fallbackRate;
-    }
-  }
-
-  private getScrapeUrl(): string {
-    const configured =
-      this.configService.get<string>('app.cbeExchange.scrapeUrl') ??
-      this.configService.get<string>('app.cbeExchange.apiUrl');
-    return configured?.trim() || DEFAULT_SCRAPE_URL;
-  }
-
-  private parseScrapedRates(
-    html: string,
-  ): { buying: number; selling: number } | null {
-    const decoded = this.unescapeHtml(html);
-    const match = USD_RATE_REGEX.exec(decoded);
-    if (!match) return null;
-
-    const buying = Number(match[1]);
-    const selling = Number(match[2]);
-    if (!Number.isFinite(buying) || !Number.isFinite(selling)) return null;
-
-    return { buying, selling };
-  }
-
-  private unescapeHtml(html: string): string {
-    return html
-      .replace(/&quot;/g, '"')
-      .replace(/&#34;/g, '"')
-      .replace(/&amp;/g, '&')
-      .replace(/&lt;/g, '<')
-      .replace(/&gt;/g, '>');
-  }
-}

apps/edr-freight-api/src/modules/companies/companies.controller.ts

@@ -24,15 +24,22 @@ import { UpdateCompanyDto } from "./dto/update-company.dto";
 import { CreateExternalProfileDto } from "./dto/create-external-profile.dto";
 import { CreateCompanyWithProfileDto } from "./dto/create-company-with-profile.dto";
 import { AddCompanyProfilesDto } from "./dto/add-company-profiles.dto";
+import { CreateCompanyProfileDto } from "./dto/create-company-profile.dto";
+import { SetActiveModeDto } from "./dto/set-active-mode.dto";
+import { SetOnboardingStepDto } from "./dto/set-onboarding-step.dto";
+import { StartOnboardingDto } from "./dto/start-onboarding.dto";
 import {
   ResponseCompanyDto,
   ResponseCompanyProfileDto,
 } from "./dto/response-company.dto";
+import { BusinessLicenseFile } from "./entities/company-profile.entity";
 import { ResponseExternalProfileDto } from "./dto/response-external-profile.dto";
 import { CompanyInfoResponseDto } from "./dto/company-info-response.dto";
 import { UpdateProfileDto } from "./dto/update-profile.dto";
 import { ProfileResponseDto } from "./dto/profile-response.dto";
 import { DashboardSummaryResponseDto } from "./dto/dashboard-summary-response.dto";
+import { FetchETradeDto } from "./dto/fetch-etrade.dto";
+import { ETradeResponseDto } from "./dto/etrade-response.dto";
 
 interface CurrentIamUser {
   id: string;
@@ -80,6 +87,15 @@ export class CompaniesController {
     return this.companiesService.getDashboardSummary(user.id);
   }
 
+  @Post("fetch-etrade-info")
+  @ApiOperation({ summary: "Fetch company info from eTrade by TIN" })
+  async fetchETradeInfo(
+    @Body() dto: FetchETradeDto,
+  ): Promise<ETradeResponseDto> {
+    const data = await this.companiesService.fetchETradeData(dto.tin);
+    return new ETradeResponseDto(data);
+  }
+
   @Patch("profile")
   @ApiOperation({ summary: "Update profile (flattened settings page)" })
   async updateProfile(
@@ -105,6 +121,113 @@ export class CompaniesController {
     return profiles.map((p) => new ResponseCompanyProfileDto(p));
   }
 
+  @Post("onboarding/start")
+  @ApiOperation({
+    summary:
+      "Begin onboarding: create a draft company + profile + role(s) so later steps can save incrementally",
+  })
+  async startOnboarding(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: StartOnboardingDto,
+  ): Promise<CompanyInfoResponseDto> {
+    const nameParts = (user.name?.en ?? "").split(" ");
+    const { profile, company } = await this.companiesService.startOnboarding(
+      {
+        userId: user.id,
+        firstName: nameParts[0] || "",
+        lastName: nameParts.slice(-1)[0] || "",
+        email: user.email ?? "",
+        phone: user.phoneNumber ?? "",
+      },
+      dto.companyType,
+      dto.roles,
+      dto.nationality,
+    );
+    return new CompanyInfoResponseDto(profile, company);
+  }
+
+  @Post("company-profile")
+  @ApiOperation({
+    summary:
+      "Create a single operational profile for the current user's company and make it the active mode",
+  })
+  async createCompanyProfile(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: CreateCompanyProfileDto,
+  ): Promise<ResponseCompanyProfileDto> {
+    const profile = await this.companiesService.createCompanyProfileForUser(
+      user.id,
+      dto.type,
+      dto.businessLicense,
+    );
+    return new ResponseCompanyProfileDto(profile);
+  }
+
+  @Post("company-profiles/:profileId/license")
+  @UseInterceptors(AnyFilesInterceptor())
+  @ApiConsumes("multipart/form-data")
+  @ApiOperation({
+    summary:
+      "Upload business-license document(s) for one of the current user's company profiles",
+  })
+  async uploadProfileLicense(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("profileId", ParseUUIDPipe) profileId: string,
+    @UploadedFiles() files: Array<Express.Multer.File>,
+  ): Promise<BusinessLicenseFile[]> {
+    return this.companiesService.uploadProfileLicenseFiles(
+      user.id,
+      profileId,
+      files,
+    );
+  }
+
+  @Get("company-profiles/:profileId/license")
+  @ApiOperation({
+    summary: "List business-license documents for a company profile",
+  })
+  async listProfileLicense(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("profileId", ParseUUIDPipe) profileId: string,
+  ): Promise<BusinessLicenseFile[]> {
+    return this.companiesService.listProfileLicenseFiles(user.id, profileId);
+  }
+
+  @Patch("active-mode")
+  @ApiOperation({
+    summary: "Switch the current user's active operational mode (importer/exporter)",
+  })
+  async setActiveMode(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: SetActiveModeDto,
+  ): Promise<CompanyInfoResponseDto> {
+    const { profile, company } = await this.companiesService.setActiveMode(
+      user.id,
+      dto.type,
+    );
+    return new CompanyInfoResponseDto(profile, company);
+  }
+
+  @Patch("onboarding-step")
+  @ApiOperation({ summary: "Persist the user's current onboarding wizard step" })
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async setOnboardingStep(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: SetOnboardingStepDto,
+  ): Promise<void> {
+    await this.companiesService.setOnboardingStep(user.id, dto.step);
+  }
+
+  @Post("onboarding/complete")
+  @ApiOperation({ summary: "Mark the current user's onboarding as complete" })
+  async completeOnboarding(
+    @CurrentUser() user: CurrentIamUser,
+  ): Promise<CompanyInfoResponseDto> {
+    const { profile, company } =
+      await this.companiesService.markOnboardingComplete(user.id);
+    return new CompanyInfoResponseDto(profile, company);
+  }
+
   // Used by portal
   @Post("create")
   @ApiOperation({

apps/edr-freight-api/src/modules/companies/companies.module.ts

@@ -1,6 +1,8 @@
 import { Module } from "@nestjs/common";
 import { TypeOrmModule } from "@nestjs/typeorm";
+import { HttpModule } from "@nestjs/axios";
 import { FilesModule } from "../files/files.module";
+import { MinioModule } from "../minio/minio.module";
 import { CompaniesController } from "./companies.controller";
 import { CompaniesService } from "./companies.service";
 import { CompaniesRepository } from "./companies.repository";
@@ -11,11 +13,14 @@ import { ExternalProfile } from "./entities/external-profile.entity";
 import { CompanyProfile } from "./entities/company-profile.entity";
 import { Booking } from "../bookings/entities/booking.entity";
 import { CompanyProfileRepository } from "./company-profile.repository";
+import { ETradeService } from "./services/etrade.service";
 
 @Module({
   imports: [
     TypeOrmModule.forFeature([Company, ExternalProfile, CompanyProfile, Booking]),
+    HttpModule,
     FilesModule,
+    MinioModule,
   ],
   controllers: [CompaniesController],
   providers: [
@@ -24,6 +29,7 @@ import { CompanyProfileRepository } from "./company-profile.repository";
     ExternalProfileRepository,
     CompanyProfileRepository,
     CompanyDashboardRepository,
+    ETradeService,
   ],
   exports: [CompaniesService],
 })

apps/edr-freight-api/src/modules/companies/companies.service.ts

@@ -8,6 +8,9 @@ import { CompaniesRepository } from "./companies.repository";
 import { CompanyProfileRepository } from "./company-profile.repository";
 import { ExternalProfileRepository } from "./external-profile.repository";
 import { CompanyDashboardRepository } from "./company-dashboard.repository";
+import { MinioService } from "../minio/minio.service";
+import { ETradeService } from "./services/etrade.service";
+import { normalizeE164 } from "../../common/validators/is-phone-number.validator";
 import { CreateCompanyDto } from "./dto/create-company.dto";
 import { UpdateCompanyDto } from "./dto/update-company.dto";
 import { CreateExternalProfileDto } from "./dto/create-external-profile.dto";
@@ -15,9 +18,15 @@ import { CreateCompanyWithProfileDto } from "./dto/create-company-with-profile.d
 import { UpdateProfileDto } from "./dto/update-profile.dto";
 import { ProfileResponseDto } from "./dto/profile-response.dto";
 import { DashboardSummaryResponseDto } from "./dto/dashboard-summary-response.dto";
-import { Company } from "./entities/company.entity";
+import {
+  Company,
+  CompanyNationality,
+  CompanyStatus,
+  CompanyType,
+} from "./entities/company.entity";
 import { ExternalProfile } from "./entities/external-profile.entity";
 import {
+  BusinessLicenseFile,
   CompanyProfile,
   ProfileType,
   ProfileStatus,
@@ -38,6 +47,8 @@ export class CompaniesService {
     private readonly companyProfilesRepo: CompanyProfileRepository,
     private readonly profilesRepo: ExternalProfileRepository,
     private readonly dashboardRepo: CompanyDashboardRepository,
+    private readonly minioService: MinioService,
+    private readonly etradeService: ETradeService,
   ) { }
 
   async createCompany(dto: CreateCompanyDto): Promise<Company> {
@@ -76,20 +87,34 @@ export class CompaniesService {
       fanNumber: dto.fanNumber ?? null,
       country: dto.companyLocation ?? "Ethiopia",
       address: dto.companyAddress ?? null,
-      phone: dto.companyPhone ?? null,
+      phone: normalizeE164(dto.companyPhone) ?? null,
       email: dto.companyEmail ?? null,
       attributes: dto.attributes ?? null,
     });
 
+    // Default active mode from the chosen role(s): importer wins when both are
+    // picked, otherwise the first allowed type chosen.
+    const allowedTypes = this.getProfileTypeForCompanyType(company.type);
+    const chosenTypes = (dto.companyProfiles ?? [])
+      .map((p) => p.type)
+      .filter((t) => allowedTypes.includes(t));
+    const activeProfileType =
+      chosenTypes.find((t) => t === ProfileType.importer) ??
+      chosenTypes[0] ??
+      allowedTypes[0] ??
+      null;
+
     const profile = await this.profilesRepo.create({
       userId: identity.userId,
       companyId: company.id,
       firstName: identity.firstName,
       lastName: identity.lastName,
       email: identity.email,
-      phone: identity.phone,
+      phone: normalizeE164(identity.phone) ?? identity.phone,
       jobTitle: dto.jobTitle ?? null,
       isPrimaryContact: dto.isPrimaryContact ?? true,
+      activeProfileType,
+      onboardingStep: 'company',
     });
 
     // Persist the operational role(s) chosen during onboarding. Types are
@@ -123,6 +148,118 @@ export class CompaniesService {
     return { company, profile };
   }
 
+  /**
+   * Begin onboarding: create a DRAFT company + the user's external profile + the
+   * chosen operational role(s) up front, so every subsequent wizard step can
+   * save incrementally (PATCH /profile, /onboarding-step) against existing rows.
+   *
+   * Idempotent: if the user already has a profile, returns it unchanged (only
+   * adding any newly-chosen roles). The draft company carries a placeholder TIN
+   * (the real one is filled on the Company Information step) and stays
+   * status=pending / onboardingCompleted=false until the wizard finishes.
+   */
+  async startOnboarding(
+    identity: UserIdentity,
+    companyType: CompanyType,
+    roles: ProfileType[],
+    nationality?: CompanyNationality,
+  ): Promise<{ profile: ExternalProfile; company: Company }> {
+    // Already started — reuse the existing draft, just ensure roles exist and
+    // keep the nationality up to date if it was (re)selected.
+    const existing = await this.profilesRepo.findByUserId(identity.userId);
+    if (existing) {
+      const companyId = existing.company?.id ?? existing.companyId;
+      await this.ensureCompanyProfiles(companyId, companyType, roles);
+      if (nationality) {
+        await this.companiesRepo.update(companyId, { nationality });
+      }
+      return this.getCompanyInfoByUserId(identity.userId);
+    }
+
+    // A profile may exist for the same email under a different IAM id — block
+    // duplicates as the final create does.
+    const byEmail = await this.profilesRepo.findByEmail(identity.email);
+    if (byEmail) {
+      throw new ConflictException(
+        `Profile with email ${identity.email} already exists`,
+      );
+    }
+
+    const allowedTypes = this.getProfileTypeForCompanyType(companyType);
+    const chosenTypes = roles.filter((t) => allowedTypes.includes(t));
+    const activeProfileType =
+      chosenTypes.find((t) => t === ProfileType.importer) ??
+      chosenTypes[0] ??
+      allowedTypes[0] ??
+      null;
+
+    const company = await this.companiesRepo.create({
+      name: identity.firstName
+        ? `${identity.firstName}'s company`
+        : "New company",
+      type: companyType,
+      tin: await this.generateDraftTin(),
+      country: "Ethiopia",
+      nationality: nationality ?? CompanyNationality.Ethiopian,
+      status: CompanyStatus.Pending,
+    });
+
+    await this.profilesRepo.create({
+      userId: identity.userId,
+      companyId: company.id,
+      firstName: identity.firstName,
+      lastName: identity.lastName,
+      email: identity.email,
+      phone: normalizeE164(identity.phone) ?? identity.phone,
+      isPrimaryContact: true,
+      activeProfileType,
+      onboardingStep: "company",
+      onboardingCompleted: false,
+    });
+
+    await this.ensureCompanyProfiles(company.id, companyType, chosenTypes);
+
+    return this.getCompanyInfoByUserId(identity.userId);
+  }
+
+  /** Create any of the requested operational profiles that don't exist yet. */
+  private async ensureCompanyProfiles(
+    companyId: string,
+    companyType: CompanyType,
+    roles: ProfileType[],
+  ): Promise<void> {
+    const allowedTypes = this.getProfileTypeForCompanyType(companyType);
+    for (const type of roles) {
+      if (!allowedTypes.includes(type)) continue;
+      const existing = await this.companyProfilesRepo.findByType(
+        companyId,
+        type,
+      );
+      if (existing) continue;
+      const reference = await this.companyProfilesRepo.generateReference(type);
+      await this.companyProfilesRepo.create({
+        companyId,
+        type,
+        reference,
+        status: ProfileStatus.Active,
+      });
+    }
+  }
+
+  /**
+   * A unique 10-char placeholder TIN for a draft company (the column is
+   * NOT NULL + unique). Overwritten with the real TIN on the company step.
+   */
+  private async generateDraftTin(): Promise<string> {
+    for (let i = 0; i < 10; i++) {
+      const candidate =
+        "D" + Math.floor(Math.random() * 1_000_000_000).toString().padStart(9, "0");
+      if (!(await this.companiesRepo.existsByTin(candidate))) return candidate;
+    }
+    // Extremely unlikely; fall back to a timestamp-derived value.
+    return ("D" + Date.now().toString()).slice(0, 10);
+  }
+
   async findAllCompanies(): Promise<Company[]> {
     return this.companiesRepo.findAll({ order: { name: "ASC" } });
   }
@@ -174,6 +311,18 @@ export class CompaniesService {
     const companyId = profile?.company?.id ?? profile?.companyId ?? null;
     if (!companyId) return this.emptyDashboardSummary();
 
+    // Scope KPIs to the active operational profile (importer/exporter mode) when
+    // one resolves; otherwise aggregate across the whole company.
+    const companyProfileId = profile?.activeProfileType
+      ? ((await this.companyProfilesRepo.findByType(
+          companyId,
+          profile.activeProfileType,
+        )) ?? null)
+      : null;
+    const scope = companyProfileId
+      ? { companyProfileId: companyProfileId.id }
+      : { companyId };
+
     const now = new Date();
     const yearStart = new Date(now.getFullYear(), 0, 1);
     const prevYearStart = new Date(now.getFullYear() - 1, 0, 1);
@@ -191,22 +340,22 @@ export class CompaniesService {
       tonnagePrev,
       monthlyRows,
     ] = await Promise.all([
-      this.dashboardRepo.countDelivered(companyId, yearStart, now),
-      this.dashboardRepo.countCommitted(companyId, yearStart, now),
-      this.dashboardRepo.sumPaidSpendByCurrency(companyId, yearStart, now),
+      this.dashboardRepo.countDelivered(scope, yearStart, now),
+      this.dashboardRepo.countCommitted(scope, yearStart, now),
+      this.dashboardRepo.sumPaidSpendByCurrency(scope, yearStart, now),
       this.dashboardRepo.sumPaidSpendByCurrency(
-        companyId,
+        scope,
         prevYearStart,
         prevYearToDate,
       ),
-      this.dashboardRepo.sumCommittedTonnage(companyId, yearStart, now),
+      this.dashboardRepo.sumCommittedTonnage(scope, yearStart, now),
       this.dashboardRepo.sumCommittedTonnage(
-        companyId,
+        scope,
         prevYearStart,
         prevYearToDate,
       ),
       this.dashboardRepo.monthlyCommittedTonnage(
-        companyId,
+        scope,
         this.monthsAgo(now, 5),
         now,
       ),
@@ -323,14 +472,27 @@ export class CompaniesService {
     const companyUpdates: Record<string, any> = {};
     const attrUpdates: Record<string, any> = { ...(company.attributes ?? {}) };
 
+    if (dto.nationality !== undefined)
+      companyUpdates.nationality = dto.nationality;
     if (dto.companyName !== undefined) companyUpdates.name = dto.companyName;
     if (dto.companyEmail !== undefined) companyUpdates.email = dto.companyEmail;
-    if (dto.companyPhone !== undefined) companyUpdates.phone = dto.companyPhone;
+    if (dto.companyPhone !== undefined)
+      companyUpdates.phone = normalizeE164(dto.companyPhone);
     if (dto.companyLocation !== undefined)
       companyUpdates.country = dto.companyLocation;
     if (dto.companyAddress !== undefined)
       companyUpdates.address = dto.companyAddress;
-    if (dto.tin !== undefined) companyUpdates.tin = dto.tin;
+    if (dto.tin !== undefined && dto.tin !== company.tin) {
+      // Reject a TIN already taken by a different company (the user's own draft
+      // placeholder is fine to overwrite).
+      const owner = await this.companiesRepo.findByTin(dto.tin);
+      if (owner && owner.id !== company.id) {
+        throw new ConflictException(
+          `This TIN (${dto.tin}) is already registered to another company. Please check the number and try again.`,
+        );
+      }
+      companyUpdates.tin = dto.tin;
+    }
     if (dto.vatNumber !== undefined) companyUpdates.vatNumber = dto.vatNumber;
     if (dto.fanNumber !== undefined) {
       companyUpdates.fanNumber = dto.fanNumber;
@@ -338,21 +500,51 @@ export class CompaniesService {
 
     if (dto.contactPersonName !== undefined)
       attrUpdates.contactPersonName = dto.contactPersonName;
+    if (dto.contactPersonPosition !== undefined)
+      attrUpdates.contactPersonPosition = dto.contactPersonPosition;
+    if (dto.contactPersonEmail !== undefined)
+      attrUpdates.contactPersonEmail = dto.contactPersonEmail;
     if (dto.contactPersonPhone !== undefined)
-      attrUpdates.contactPersonPhone = dto.contactPersonPhone;
+      attrUpdates.contactPersonPhone = normalizeE164(dto.contactPersonPhone);
     if (dto.generalManagerName !== undefined)
       attrUpdates.generalManagerName = dto.generalManagerName;
     if (dto.generalManagerEmail !== undefined)
       attrUpdates.generalManagerEmail = dto.generalManagerEmail;
     if (dto.generalManagerPhone !== undefined)
-      attrUpdates.generalManagerPhone = dto.generalManagerPhone;
+      attrUpdates.generalManagerPhone = normalizeE164(dto.generalManagerPhone);
     if (dto.poaName !== undefined) attrUpdates.poaName = dto.poaName;
-    if (dto.poaPhone !== undefined) attrUpdates.poaPhone = dto.poaPhone;
+    if (dto.poaPhone !== undefined)
+      attrUpdates.poaPhone = normalizeE164(dto.poaPhone);
     if (dto.poaEmail !== undefined) attrUpdates.poaEmail = dto.poaEmail;
     if (dto.poaLocation !== undefined)
       attrUpdates.poaLocation = dto.poaLocation;
     if (dto.poaAddress !== undefined) attrUpdates.poaAddress = dto.poaAddress;
 
+    if (dto.licenceNumber !== undefined)
+      companyUpdates.licenceNumber = dto.licenceNumber;
+    if (dto.statusDescription !== undefined)
+      companyUpdates.statusDescription = dto.statusDescription;
+    if (dto.dateRegistered !== undefined)
+      companyUpdates.dateRegistered = dto.dateRegistered;
+    if (dto.renewedFrom !== undefined)
+      companyUpdates.renewedFrom = dto.renewedFrom;
+    if (dto.renewalDate !== undefined)
+      companyUpdates.renewalDate = dto.renewalDate;
+    if (dto.renewedTo !== undefined)
+      companyUpdates.renewedTo = dto.renewedTo;
+    if (dto.region !== undefined)
+      companyUpdates.region = dto.region;
+    if (dto.zone !== undefined)
+      companyUpdates.zone = dto.zone;
+    if (dto.woreda !== undefined)
+      companyUpdates.woreda = dto.woreda;
+    if (dto.kebele !== undefined)
+      companyUpdates.kebele = dto.kebele;
+    if (dto.houseNo !== undefined)
+      companyUpdates.houseNo = dto.houseNo;
+    if (dto.etradePhone !== undefined)
+      companyUpdates.etradePhone = normalizeE164(dto.etradePhone);
+
     companyUpdates.attributes = attrUpdates;
 
     const updated = await this.companiesRepo.update(company.id, companyUpdates);
@@ -393,7 +585,13 @@ export class CompaniesService {
   private getProfileTypeForCompanyType(companyType: string): ProfileType[] {
     switch (companyType) {
       case "customer":
-        return [ProfileType.importer, ProfileType.exporter];
+        // A customer can operate as an importer and/or exporter, and may also
+        // add a freight-forwarder service profile under the same company.
+        return [
+          ProfileType.importer,
+          ProfileType.exporter,
+          ProfileType.freightForwarder,
+        ];
       case "freight_forwarder":
         return [ProfileType.freightForwarder];
       case "dj_freight_forwarder":
@@ -505,4 +703,243 @@ export class CompaniesService {
 
     return this.companyProfilesRepo.findByCompanyId(companyId);
   }
+
+  /**
+   * Create a single operational profile for the current user's company and
+   * make it the active mode in the same call. Powers the header "Switch to
+   * Exporter/Importer" flow when the target profile doesn't exist yet.
+   */
+  async createCompanyProfileForUser(
+    userId: string,
+    type: ProfileType,
+    businessLicense?: string,
+  ): Promise<CompanyProfile> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+
+    const companyId = profile.company?.id ?? profile.companyId;
+    const company = await this.findCompanyById(companyId);
+    const allowedTypes = this.getProfileTypeForCompanyType(company.type);
+    if (!allowedTypes.includes(type)) {
+      throw new BadRequestException(
+        `Profile type "${type}" is not allowed for company type "${company.type}"`,
+      );
+    }
+
+    let created = await this.companyProfilesRepo.findByType(companyId, type);
+    if (!created) {
+      const reference = await this.companyProfilesRepo.generateReference(type);
+      created = await this.companyProfilesRepo.create({
+        companyId,
+        type,
+        reference,
+        businessLicense: businessLicense ?? null,
+        status: ProfileStatus.Active,
+      });
+    }
+
+    await this.profilesRepo.update(profile.id, { activeProfileType: type });
+
+    return created;
+  }
+
+  /**
+   * Switch the user's active operational mode. The target profile must already
+   * exist — clients create it first via createCompanyProfileForUser.
+   */
+  async setActiveMode(
+    userId: string,
+    type: ProfileType,
+  ): Promise<{ profile: ExternalProfile; company: Company }> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+
+    const companyId = profile.company?.id ?? profile.companyId;
+    const company = await this.findCompanyById(companyId);
+
+    const allowedTypes = this.getProfileTypeForCompanyType(company.type);
+    if (!allowedTypes.includes(type)) {
+      throw new BadRequestException(
+        `Profile type "${type}" is not allowed for company type "${company.type}"`,
+      );
+    }
+
+    const existing = await this.companyProfilesRepo.findByType(companyId, type);
+    if (!existing) {
+      throw new ConflictException(
+        `No ${type} profile exists yet — create it before switching`,
+      );
+    }
+
+    await this.profilesRepo.update(profile.id, { activeProfileType: type });
+
+    return this.getCompanyInfoByUserId(userId);
+  }
+
+  async setOnboardingStep(userId: string, step: string): Promise<void> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+    await this.profilesRepo.update(profile.id, { onboardingStep: step });
+  }
+
+  async markOnboardingComplete(
+    userId: string,
+  ): Promise<{ profile: ExternalProfile; company: Company }> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+
+    const companyId = profile.company?.id ?? profile.companyId;
+    const company = await this.findCompanyById(companyId);
+
+    // Guard against finishing on a still-draft company (TIN never filled in).
+    if (!company.tin || company.tin.startsWith("D")) {
+      throw new BadRequestException(
+        "Company information is incomplete — please fill in your company details before finishing.",
+      );
+    }
+
+    // Every operational profile must have at least one business-license file
+    // (stored directly on the profile).
+    const profiles = await this.companyProfilesRepo.findByCompanyId(companyId);
+    for (const cp of profiles) {
+      if (!cp.businessLicenseFiles || cp.businessLicenseFiles.length === 0) {
+        throw new BadRequestException(
+          `Please upload a business license for your ${cp.type.replace(/_/g, " ")} profile before finishing.`,
+        );
+      }
+    }
+
+    await this.profilesRepo.update(profile.id, {
+      onboardingCompleted: true,
+      onboardingStep: "done",
+    });
+    await this.companiesRepo.update(companyId, {
+      status: CompanyStatus.Active,
+    });
+    return this.getCompanyInfoByUserId(userId);
+  }
+
+  /**
+   * Authorize and resolve a company_profile that must belong to the current
+   * user's company — used before accepting/returning its license files.
+   */
+  async resolveOwnedProfile(
+    userId: string,
+    profileId: string,
+  ): Promise<CompanyProfile> {
+    const { company } = await this.getCompanyInfoByUserId(userId);
+    const owned = (company.companyProfiles ?? []).find(
+      (p) => p.id === profileId,
+    );
+    if (!owned) {
+      throw new NotFoundException(`Profile ${profileId} not found`);
+    }
+    return owned;
+  }
+
+  /**
+   * Upload business-license document(s) and store them directly on the company
+   * profile (multi-file). Bytes go to object storage; only metadata/URLs are
+   * persisted on the profile — intentionally not via the FileRecord file model.
+   * New files are appended to any already present. Returns the full list.
+   */
+  async uploadProfileLicenseFiles(
+    userId: string,
+    profileId: string,
+    files: Express.Multer.File[],
+  ): Promise<BusinessLicenseFile[]> {
+    const profile = await this.resolveOwnedProfile(userId, profileId);
+
+    const uploaded: BusinessLicenseFile[] = [];
+    for (const file of files) {
+      const objectName = `company_profiles/${profileId}/${Date.now()}_${file.originalname}`;
+      const url = await this.minioService.uploadFile(
+        objectName,
+        file.buffer,
+        file.mimetype,
+      );
+      uploaded.push({
+        name: file.originalname,
+        url,
+        size: file.size,
+        mimeType: file.mimetype,
+      });
+    }
+
+    const next = [...(profile.businessLicenseFiles ?? []), ...uploaded];
+    await this.companyProfilesRepo.update(profileId, {
+      businessLicenseFiles: next,
+    });
+    return next;
+  }
+
+  /** The business-license files stored on a single company profile. */
+  async listProfileLicenseFiles(
+    userId: string,
+    profileId: string,
+  ): Promise<BusinessLicenseFile[]> {
+    const profile = await this.resolveOwnedProfile(userId, profileId);
+    return profile.businessLicenseFiles ?? [];
+  }
+
+  /**
+   * Resolve which company_profile a new booking belongs to, from the company
+   * and the booking's trade direction. IMPORT → importer profile, EXPORT →
+   * exporter profile; for DOMESTIC or a forwarder/single-profile company (or
+   * when the natural profile doesn't exist) it falls back to the user's active
+   * profile, then the company's first profile. Returns null when the company
+   * has no profiles at all.
+   */
+  async resolveCompanyProfileIdForBooking(
+    companyId: string,
+    tradeDirection: string,
+    fallbackType?: ProfileType | null,
+  ): Promise<string | null> {
+    const profiles = await this.companyProfilesRepo.findByCompanyId(companyId);
+    if (profiles.length === 0) return null;
+
+    const naturalType =
+      tradeDirection === 'IMPORT'
+        ? ProfileType.importer
+        : tradeDirection === 'EXPORT'
+          ? ProfileType.exporter
+          : null;
+
+    const byType = (type?: ProfileType | null) =>
+      type ? profiles.find((p) => p.type === type) : undefined;
+
+    const match = byType(naturalType) ?? byType(fallbackType) ?? profiles[0];
+    return match?.id ?? null;
+  }
+
+  /**
+   * Resolve the company_profile a customer's data should be scoped to, from
+   * their persisted active mode. Returns null when nothing can be resolved
+   * (not onboarded yet) so callers can fall back to company-level scoping.
+   */
+  async resolveActiveCompanyProfileId(userId: string): Promise<string | null> {
+    try {
+      const { profile, company } = await this.getCompanyInfoByUserId(userId);
+      const type = profile.activeProfileType;
+      if (!type) return null;
+      const match = company.companyProfiles?.find((p) => p.type === type);
+      return match?.id ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  async fetchETradeData(tin: string) {
+    const { businessInfo } = await this.etradeService.resolveCompanyData(tin);
+    if (!businessInfo) {
+      throw new BadRequestException(
+        "No business license found for this TIN. Please check the number and try again.",
+      );
+    }
+    return this.etradeService.extractRegistrationData(businessInfo);
+  }
 }

apps/edr-freight-api/src/modules/companies/company-dashboard.repository.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
+import { Repository, SelectQueryBuilder } from 'typeorm';
 
 import { Booking } from '../bookings/entities/booking.entity';
 
@@ -31,6 +31,27 @@ export interface CurrencyTotal {
   total: number;
 }
 
+/**
+ * What the dashboard is scoped to: a single operational profile (the active
+ * importer/exporter mode) when one resolves, otherwise the whole company
+ * (legacy / not-yet-onboarded fallback).
+ */
+export type DashboardScope =
+  | { companyProfileId: string }
+  | { companyId: string };
+
+/** Apply the scope as a WHERE clause on a bookings query builder. */
+function applyScope(
+  qb: SelectQueryBuilder<Booking>,
+  scope: DashboardScope,
+): SelectQueryBuilder<Booking> {
+  return 'companyProfileId' in scope
+    ? qb.where('b.company_profile_id = :companyProfileId', {
+        companyProfileId: scope.companyProfileId,
+      })
+    : qb.where('b.company_id = :companyId', { companyId: scope.companyId });
+}
+
 export interface MonthlyTonnage {
   year: number;
   month: number; // 1-12
@@ -50,35 +71,33 @@ export class CompanyDashboardRepository {
     private readonly bookings: Repository<Booking>,
   ) {}
 
-  /** Count of delivered/completed bookings for a company within [from, to). */
-  async countDelivered(companyId: string, from: Date, to: Date): Promise<number> {
-    return this.bookings
-      .createQueryBuilder('b')
-      .where('b.company_id = :companyId', { companyId })
+  /** Count of delivered/completed bookings within [from, to) for the scope. */
+  async countDelivered(scope: DashboardScope, from: Date, to: Date): Promise<number> {
+    return applyScope(this.bookings.createQueryBuilder('b'), scope)
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...DELIVERED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
       .getCount();
   }
 
-  /** Count of committed (non-draft, non-dead) bookings for a company within [from, to). */
-  async countCommitted(companyId: string, from: Date, to: Date): Promise<number> {
-    return this.bookings
-      .createQueryBuilder('b')
-      .where('b.company_id = :companyId', { companyId })
+  /** Count of committed (non-draft, non-dead) bookings within [from, to) for the scope. */
+  async countCommitted(scope: DashboardScope, from: Date, to: Date): Promise<number> {
+    return applyScope(this.bookings.createQueryBuilder('b'), scope)
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...COMMITTED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
       .getCount();
   }
 
-  /** Sum of paid booking totals, grouped by currency, within [from, to). */
-  async sumPaidSpendByCurrency(companyId: string, from: Date, to: Date): Promise<CurrencyTotal[]> {
-    const rows = await this.bookings
-      .createQueryBuilder('b')
-      .select('b.payment_currency', 'currency')
-      .addSelect('COALESCE(SUM(b.total_amount), 0)', 'total')
-      .where('b.company_id = :companyId', { companyId })
+  /** Sum of paid booking totals, grouped by currency, within [from, to) for the scope. */
+  async sumPaidSpendByCurrency(scope: DashboardScope, from: Date, to: Date): Promise<CurrencyTotal[]> {
+    const rows = await applyScope(
+      this.bookings
+        .createQueryBuilder('b')
+        .select('b.payment_currency', 'currency')
+        .addSelect('COALESCE(SUM(b.total_amount), 0)', 'total'),
+      scope,
+    )
       .andWhere('b.deleted_at IS NULL')
       .andWhere("b.payment_status = 'PAID'")
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
@@ -88,12 +107,14 @@ export class CompanyDashboardRepository {
     return rows.map((r) => ({ currency: r.currency ?? 'ETB', total: Number(r.total) }));
   }
 
-  /** Total committed tonnage (cargo VGM) for a company within [from, to). */
-  async sumCommittedTonnage(companyId: string, from: Date, to: Date): Promise<number> {
-    const row = await this.bookings
-      .createQueryBuilder('b')
-      .select('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total')
-      .where('b.company_id = :companyId', { companyId })
+  /** Total committed tonnage (cargo VGM) within [from, to) for the scope. */
+  async sumCommittedTonnage(scope: DashboardScope, from: Date, to: Date): Promise<number> {
+    const row = await applyScope(
+      this.bookings
+        .createQueryBuilder('b')
+        .select('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total'),
+      scope,
+    )
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...COMMITTED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
@@ -102,14 +123,16 @@ export class CompanyDashboardRepository {
     return Number(row?.total ?? 0);
   }
 
-  /** Committed tonnage grouped by calendar month within [from, to). */
-  async monthlyCommittedTonnage(companyId: string, from: Date, to: Date): Promise<MonthlyTonnage[]> {
-    const rows = await this.bookings
-      .createQueryBuilder('b')
-      .select('EXTRACT(YEAR FROM b.created_at)', 'year')
-      .addSelect('EXTRACT(MONTH FROM b.created_at)', 'month')
-      .addSelect('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total')
-      .where('b.company_id = :companyId', { companyId })
+  /** Committed tonnage grouped by calendar month within [from, to) for the scope. */
+  async monthlyCommittedTonnage(scope: DashboardScope, from: Date, to: Date): Promise<MonthlyTonnage[]> {
+    const rows = await applyScope(
+      this.bookings
+        .createQueryBuilder('b')
+        .select('EXTRACT(YEAR FROM b.created_at)', 'year')
+        .addSelect('EXTRACT(MONTH FROM b.created_at)', 'month')
+        .addSelect('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total'),
+      scope,
+    )
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...COMMITTED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })

apps/edr-freight-api/src/modules/companies/company-profile.repository.ts

@@ -15,7 +15,7 @@ const SEQUENCE_MAP: Record<ProfileType, string> = {
 const PREFIX_MAP: Record<ProfileType, string> = {
   [ProfileType.exporter]: "EX",
   [ProfileType.importer]: "IM",
-  [ProfileType.freightForwarder]: "FFE",
+  [ProfileType.freightForwarder]: "FF",
   [ProfileType.djFreightForwarder]: "FWJ",
   [ProfileType.transporter]: "TR",
 };

apps/edr-freight-api/src/modules/companies/dto/company-info-response.dto.ts

@@ -8,7 +8,7 @@ export class CompanyInfoResponseDto {
   company: ResponseCompanyDto;
 
   constructor(profile: ExternalProfile, company: Company) {
-    this.profile = new ResponseExternalProfileDto(profile);
+    this.profile = new ResponseExternalProfileDto(profile, company);
     this.company = new ResponseCompanyDto(company);
   }
 }

apps/edr-freight-api/src/modules/companies/dto/create-company-profile.dto.ts

@@ -0,0 +1,12 @@
+import { IsEnum, IsOptional, IsString, MaxLength } from 'class-validator';
+import { ProfileType } from '../entities/company-profile.entity';
+
+export class CreateCompanyProfileDto {
+  @IsEnum(ProfileType)
+  type!: ProfileType;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  businessLicense?: string;
+}

apps/edr-freight-api/src/modules/companies/dto/create-company-with-profile.dto.ts

@@ -2,6 +2,7 @@ import { IsString, IsNotEmpty, IsOptional, IsEmail, MaxLength, IsBoolean, IsEnum
 import { Type } from 'class-transformer';
 import { CompanyType } from '../entities/company.entity';
 import { ProfileType } from '../entities/company-profile.entity';
+import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
 
 export class CompanyProfileInputDto {
   @IsEnum(ProfileType)
@@ -30,6 +31,7 @@ export class CreateCompanyWithProfileDto {
   @IsOptional()
   @IsString()
   @MaxLength(20)
+  @IsValidPhone()
   companyPhone?: string;
 
   @IsOptional()

apps/edr-freight-api/src/modules/companies/dto/create-company.dto.ts

@@ -1,5 +1,6 @@
 import { IsString, IsNotEmpty, IsOptional, IsEnum, MaxLength, Length, Matches, IsEmail } from 'class-validator';
 import { CompanyType, CompanyStatus } from '../entities/company.entity';
+import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
 
 export class CreateCompanyDto {
   @IsString()
@@ -37,6 +38,7 @@ export class CreateCompanyDto {
   @IsOptional()
   @IsString()
   @MaxLength(20)
+  @IsValidPhone()
   phone?: string;
 
   @IsOptional()

apps/edr-freight-api/src/modules/companies/dto/create-external-profile.dto.ts

@@ -1,4 +1,5 @@
 import { IsString, IsNotEmpty, IsOptional, IsEmail, MaxLength, IsBoolean, IsUUID } from 'class-validator';
+import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
 
 export class CreateExternalProfileDto {
   @IsUUID()
@@ -26,6 +27,7 @@ export class CreateExternalProfileDto {
   @IsOptional()
   @IsString()
   @MaxLength(20)
+  @IsValidPhone()
   phone?: string;
 
   @IsOptional()

apps/edr-freight-api/src/modules/companies/dto/etrade-response.dto.ts

@@ -0,0 +1,39 @@
+import { CompanyRegistrationData } from "@edr/types";
+
+export class ETradeResponseDto implements CompanyRegistrationData {
+  licenceNumber!: string;
+  statusDescription!: string;
+  dateRegistered!: string;
+  renewedFrom!: string;
+  renewalDate!: string;
+  renewedTo!: string;
+  region!: string;
+  zone!: string;
+  woreda!: string;
+  kebele!: string;
+  houseNo!: string;
+  mobilePhone!: string;
+  regularPhone!: string;
+  managerName!: string;
+  managerEmail?: string;
+  managerPhone!: string;
+
+  constructor(data: CompanyRegistrationData) {
+    this.licenceNumber = data.licenceNumber;
+    this.statusDescription = data.statusDescription;
+    this.dateRegistered = data.dateRegistered;
+    this.renewedFrom = data.renewedFrom;
+    this.renewalDate = data.renewalDate;
+    this.renewedTo = data.renewedTo;
+    this.region = data.region;
+    this.zone = data.zone;
+    this.woreda = data.woreda;
+    this.kebele = data.kebele;
+    this.houseNo = data.houseNo;
+    this.mobilePhone = data.mobilePhone;
+    this.regularPhone = data.regularPhone;
+    this.managerName = data.managerName;
+    this.managerEmail = data.managerEmail;
+    this.managerPhone = data.managerPhone;
+  }
+}

apps/edr-freight-api/src/modules/companies/dto/fetch-etrade.dto.ts

@@ -0,0 +1,8 @@
+import { IsString, IsNotEmpty, Length } from "class-validator";
+
+export class FetchETradeDto {
+  @IsString()
+  @IsNotEmpty()
+  @Length(10, 10, { message: "TIN must be exactly 10 digits" })
+  tin!: string;
+}

apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts

@@ -6,6 +6,7 @@ export class ProfileResponseDto {
   companyId: string;
   companyName: string;
   companyType: string;
+  nationality: string | null;
   companyEmail: string | null;
   companyPhone: string | null;
   companyLocation: string;
@@ -16,7 +17,22 @@ export class ProfileResponseDto {
 
   companyProfiles: ResponseCompanyProfileDto[];
 
+  licenceNumber: string | null;
+  statusDescription: string | null;
+  dateRegistered: string | null;
+  renewedFrom: string | null;
+  renewalDate: string | null;
+  renewedTo: string | null;
+  region: string | null;
+  zone: string | null;
+  woreda: string | null;
+  kebele: string | null;
+  houseNo: string | null;
+  etradePhone: string | null;
+
   contactPersonName: string | null;
+  contactPersonPosition: string | null;
+  contactPersonEmail: string | null;
   contactPersonPhone: string | null;
   generalManagerName: string | null;
   generalManagerEmail: string | null;
@@ -34,6 +50,7 @@ export class ProfileResponseDto {
     this.companyId = company.id;
     this.companyName = company.name;
     this.companyType = company.type;
+    this.nationality = company.nationality ?? null;
     this.companyProfiles =
       company.companyProfiles?.map((p) => new ResponseCompanyProfileDto(p)) ??
       [];
@@ -46,8 +63,23 @@ export class ProfileResponseDto {
     this.fanNumber = company.fanNumber ?? null;
     this.profileId = profile.id;
 
+    this.licenceNumber = company.licenceNumber ?? null;
+    this.statusDescription = company.statusDescription ?? null;
+    this.dateRegistered = company.dateRegistered ?? null;
+    this.renewedFrom = company.renewedFrom ?? null;
+    this.renewalDate = company.renewalDate ?? null;
+    this.renewedTo = company.renewedTo ?? null;
+    this.region = company.region ?? null;
+    this.zone = company.zone ?? null;
+    this.woreda = company.woreda ?? null;
+    this.kebele = company.kebele ?? null;
+    this.houseNo = company.houseNo ?? null;
+    this.etradePhone = company.etradePhone ?? null;
+
     const attrs = company.attributes ?? {};
     this.contactPersonName = attrs.contactPersonName ?? null;
+    this.contactPersonPosition = attrs.contactPersonPosition ?? null;
+    this.contactPersonEmail = attrs.contactPersonEmail ?? null;
     this.contactPersonPhone = attrs.contactPersonPhone ?? null;
     this.generalManagerName = attrs.generalManagerName ?? null;
     this.generalManagerEmail = attrs.generalManagerEmail ?? null;

apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts

@@ -1,5 +1,13 @@
-import { Company, CompanyType, CompanyStatus } from '../entities/company.entity';
-import { CompanyProfile } from '../entities/company-profile.entity';
+import {
+  Company,
+  CompanyType,
+  CompanyStatus,
+  CompanyNationality,
+} from '../entities/company.entity';
+import {
+  BusinessLicenseFile,
+  CompanyProfile,
+} from '../entities/company-profile.entity';
 import { ResponseExternalProfileDto } from './response-external-profile.dto';
 
 export class ResponseCompanyProfileDto {
@@ -7,7 +15,10 @@ export class ResponseCompanyProfileDto {
   type: string;
   reference: string;
   status: string;
+  /** @deprecated Superseded by licenseFiles. Kept for back-compat. */
   businessLicense?: string | null;
+  /** Business-license documents stored on the profile (multi-file). */
+  licenseFiles: BusinessLicenseFile[];
   attributes?: Record<string, any> | null;
   createdAt: Date;
   updatedAt: Date;
@@ -18,6 +29,7 @@ export class ResponseCompanyProfileDto {
     this.reference = profile.reference;
     this.status = profile.status;
     this.businessLicense = profile.businessLicense;
+    this.licenseFiles = profile.businessLicenseFiles ?? [];
     this.attributes = profile.attributes;
     this.createdAt = profile.createdAt;
     this.updatedAt = profile.updatedAt;
@@ -29,6 +41,7 @@ export class ResponseCompanyDto {
   name: string;
   type: CompanyType;
   status: CompanyStatus;
+  nationality?: CompanyNationality | null;
   tin: string;
   vatNumber?: string | null;
   fanNumber?: string | null;
@@ -48,6 +61,7 @@ export class ResponseCompanyDto {
     this.name = company.name;
     this.type = company.type;
     this.status = company.status;
+    this.nationality = company.nationality ?? null;
     this.tin = company.tin;
     this.vatNumber = company.vatNumber;
     this.fanNumber = company.fanNumber;
@@ -58,7 +72,9 @@ export class ResponseCompanyDto {
     this.website = company.website;
     this.attributes = company.attributes;
     this.profiles = company.profiles?.map((p) => new ResponseExternalProfileDto(p));
-    this.companyProfiles = company.companyProfiles?.map((p) => new ResponseCompanyProfileDto(p));
+    this.companyProfiles = company.companyProfiles?.map(
+      (p) => new ResponseCompanyProfileDto(p),
+    );
     this.createdAt = company.createdAt;
     this.updatedAt = company.updatedAt;
   }

apps/edr-freight-api/src/modules/companies/dto/response-external-profile.dto.ts

@@ -1,4 +1,8 @@
-import { ExternalProfile } from '../entities/external-profile.entity';
+import { Company } from '../entities/company.entity';
+import {
+  ExternalProfile,
+} from '../entities/external-profile.entity';
+import { ProfileType } from '../entities/company-profile.entity';
 
 export class ResponseExternalProfileDto {
   id: string;
@@ -11,10 +15,20 @@ export class ResponseExternalProfileDto {
   nationalId?: string | null;
   jobTitle?: string | null;
   isPrimaryContact: boolean;
+  /** The active operational mode (importer/exporter/forwarder). */
+  activeProfileType?: ProfileType | null;
+  /**
+   * The id of the company_profile matching activeProfileType, resolved
+   * server-side so the client never re-derives it. Null until a company
+   * (with profiles) is loaded and a matching profile exists.
+   */
+  activeCompanyProfileId?: string | null;
+  onboardingStep?: string | null;
+  onboardingCompleted: boolean;
   createdAt: Date;
   updatedAt: Date;
 
-  constructor(profile: ExternalProfile) {
+  constructor(profile: ExternalProfile, company?: Company) {
     this.id = profile.id;
     this.userId = profile.userId;
     this.companyId = profile.companyId;
@@ -25,6 +39,13 @@ export class ResponseExternalProfileDto {
     this.nationalId = profile.nationalId;
     this.jobTitle = profile.jobTitle;
     this.isPrimaryContact = profile.isPrimaryContact;
+    this.activeProfileType = profile.activeProfileType ?? null;
+    this.onboardingStep = profile.onboardingStep ?? null;
+    this.onboardingCompleted = profile.onboardingCompleted ?? false;
+    this.activeCompanyProfileId =
+      company?.companyProfiles?.find(
+        (p) => p.type === profile.activeProfileType,
+      )?.id ?? null;
     this.createdAt = profile.createdAt;
     this.updatedAt = profile.updatedAt;
   }

apps/edr-freight-api/src/modules/companies/dto/set-active-mode.dto.ts

@@ -0,0 +1,7 @@
+import { IsEnum } from 'class-validator';
+import { ProfileType } from '../entities/company-profile.entity';
+
+export class SetActiveModeDto {
+  @IsEnum(ProfileType)
+  type!: ProfileType;
+}

apps/edr-freight-api/src/modules/companies/dto/set-onboarding-step.dto.ts

@@ -0,0 +1,7 @@
+import { IsString, MaxLength } from 'class-validator';
+
+export class SetOnboardingStepDto {
+  @IsString()
+  @MaxLength(40)
+  step!: string;
+}

apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts

@@ -0,0 +1,17 @@
+import { ArrayMinSize, IsArray, IsEnum, IsOptional } from "class-validator";
+import { CompanyNationality, CompanyType } from "../entities/company.entity";
+import { ProfileType } from "../entities/company-profile.entity";
+
+export class StartOnboardingDto {
+  @IsEnum(CompanyType)
+  companyType!: CompanyType;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @IsEnum(ProfileType, { each: true })
+  roles!: ProfileType[];
+
+  @IsOptional()
+  @IsEnum(CompanyNationality)
+  nationality?: CompanyNationality;
+}

apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts

@@ -1,6 +1,12 @@
-import { IsString, IsOptional, IsEmail, MaxLength, Length, Matches } from 'class-validator';
+import { IsString, IsOptional, IsEmail, MaxLength, Length, Matches, IsEnum } from 'class-validator';
+import { CompanyNationality } from '../entities/company.entity';
+import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
 
 export class UpdateProfileDto {
+  @IsOptional()
+  @IsEnum(CompanyNationality)
+  nationality?: CompanyNationality;
+
   @IsOptional()
   @IsString()
   @MaxLength(200)
@@ -14,6 +20,7 @@ export class UpdateProfileDto {
   @IsOptional()
   @IsString()
   @MaxLength(20)
+  @IsValidPhone()
   companyPhone?: string;
 
   @IsOptional()
@@ -47,6 +54,15 @@ export class UpdateProfileDto {
 
   @IsOptional()
   @IsString()
+  contactPersonPosition?: string;
+
+  @IsOptional()
+  @IsEmail()
+  contactPersonEmail?: string;
+
+  @IsOptional()
+  @IsString()
+  @IsValidPhone()
   contactPersonPhone?: string;
 
   @IsOptional()
@@ -59,6 +75,7 @@ export class UpdateProfileDto {
 
   @IsOptional()
   @IsString()
+  @IsValidPhone()
   generalManagerPhone?: string;
 
   @IsOptional()
@@ -67,6 +84,7 @@ export class UpdateProfileDto {
 
   @IsOptional()
   @IsString()
+  @IsValidPhone()
   poaPhone?: string;
 
   @IsOptional()
@@ -80,4 +98,64 @@ export class UpdateProfileDto {
   @IsOptional()
   @IsString()
   poaAddress?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  licenceNumber?: string;
+
+  @IsOptional()
+  @IsString()
+  statusDescription?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  dateRegistered?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  renewedFrom?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  renewalDate?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  renewedTo?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  region?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  zone?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  woreda?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  kebele?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  houseNo?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  @IsValidPhone()
+  etradePhone?: string;
 }

apps/edr-freight-api/src/modules/companies/entities/company-profile.entity.ts

@@ -17,6 +17,14 @@ export enum ProfileStatus {
   Blacklisted = "blacklisted",
 }
 
+/** A business-license document stored directly on the company profile. */
+export interface BusinessLicenseFile {
+  name: string;
+  url: string;
+  size: number;
+  mimeType?: string;
+}
+
 @Entity({ schema: "freight", name: "company_profiles" })
 @Index(["reference"], { unique: true })
 @Index(["type"])
@@ -57,6 +65,14 @@ export class CompanyProfile extends BaseEntity {
   })
   businessLicense?: string | null;
 
+  /**
+   * Business-license documents for this profile, stored directly on the profile
+   * (multi-file). The bytes live in object storage; only the metadata/URLs are
+   * persisted here — this is intentionally NOT modelled via the FileRecord table.
+   */
+  @Column({ name: "business_license_files", type: "jsonb", nullable: true })
+  businessLicenseFiles?: BusinessLicenseFile[] | null;
+
   @Column({ name: "attributes", type: "jsonb", nullable: true })
   attributes?: Record<string, any> | null;
 }

apps/edr-freight-api/src/modules/companies/entities/company.entity.ts

@@ -17,6 +17,11 @@ export enum CompanyStatus {
   Blacklisted = "blacklisted",
 }
 
+export enum CompanyNationality {
+  Ethiopian = "ethiopian",
+  Foreign = "foreign",
+}
+
 @Entity({ schema: "freight", name: "companies" })
 @Index(["tin"])
 @Index(["type"])
@@ -47,6 +52,16 @@ export class Company extends BaseEntity {
   @Column({ name: "country", type: "varchar", length: 32, default: "Ethiopia" })
   country!: string;
 
+  /** Whether the company is Ethiopian or Foreign — drives the required onboarding documents. */
+  @Column({
+    name: "nationality",
+    type: "varchar",
+    length: 32,
+    nullable: true,
+    enum: CompanyNationality,
+  })
+  nationality?: CompanyNationality | null;
+
   @Column({ name: "address", type: "text", nullable: true })
   address?: string | null;
 
@@ -102,6 +117,67 @@ export class Company extends BaseEntity {
   @Column({ name: "attributes", type: "jsonb", nullable: true })
   attributes?: Record<string, any> | null;
 
+  @Column({
+    name: "licence_number",
+    type: "varchar",
+    length: 100,
+    nullable: true,
+  })
+  licenceNumber?: string | null;
+
+  @Column({ name: "status_description", type: "text", nullable: true })
+  statusDescription?: string | null;
+
+  @Column({
+    name: "date_registered",
+    type: "varchar",
+    length: 50,
+    nullable: true,
+  })
+  dateRegistered?: string | null;
+
+  @Column({
+    name: "renewed_from",
+    type: "varchar",
+    length: 50,
+    nullable: true,
+  })
+  renewedFrom?: string | null;
+
+  @Column({
+    name: "renewal_date",
+    type: "varchar",
+    length: 50,
+    nullable: true,
+  })
+  renewalDate?: string | null;
+
+  @Column({
+    name: "renewed_to",
+    type: "varchar",
+    length: 50,
+    nullable: true,
+  })
+  renewedTo?: string | null;
+
+  @Column({ name: "region", type: "varchar", length: 100, nullable: true })
+  region?: string | null;
+
+  @Column({ name: "zone", type: "varchar", length: 100, nullable: true })
+  zone?: string | null;
+
+  @Column({ name: "woreda", type: "varchar", length: 100, nullable: true })
+  woreda?: string | null;
+
+  @Column({ name: "kebele", type: "varchar", length: 100, nullable: true })
+  kebele?: string | null;
+
+  @Column({ name: "house_no", type: "varchar", length: 100, nullable: true })
+  houseNo?: string | null;
+
+  @Column({ name: "etrade_phone", type: "varchar", length: 20, nullable: true })
+  etradePhone?: string | null;
+
   @OneToMany(() => ExternalProfile, (profile) => profile.company)
   profiles?: ExternalProfile[];
 

apps/edr-freight-api/src/modules/companies/entities/external-profile.entity.ts

@@ -1,6 +1,7 @@
 import { BaseEntity } from '@edr/api-common';
 import { Column, Entity, Index, ManyToOne, JoinColumn } from 'typeorm';
 import { Company } from './company.entity';
+import { ProfileType } from './company-profile.entity';
 
 @Entity({ schema: 'freight', name: 'external_profiles' })
 @Index(['userId'])
@@ -36,4 +37,31 @@ export class ExternalProfile extends BaseEntity {
 
   @Column({ name: 'is_primary_contact', type: 'boolean', default: false })
   isPrimaryContact!: boolean;
+
+  /**
+   * The operational profile the user is currently "in" (importer vs exporter,
+   * or the single forwarder profile). Drives header switching and scopes the
+   * customer's bookings / dashboard to that company_profile. Nullable for
+   * users who haven't picked a role yet.
+   */
+  @Column({
+    name: 'active_profile_type',
+    type: 'varchar',
+    length: 32,
+    nullable: true,
+    enum: ProfileType,
+  })
+  activeProfileType?: ProfileType | null;
+
+  /** Coarse resume point for the onboarding wizard (e.g. 'role', 'company', 'documents', 'done'). */
+  @Column({
+    name: 'onboarding_step',
+    type: 'varchar',
+    length: 40,
+    nullable: true,
+  })
+  onboardingStep?: string | null;
+
+  @Column({ name: 'onboarding_completed', type: 'boolean', default: false })
+  onboardingCompleted!: boolean;
 }

apps/edr-freight-api/src/modules/companies/services/etrade.service.ts

@@ -0,0 +1,113 @@
+import { Injectable, BadRequestException } from "@nestjs/common";
+import { HttpService } from "@nestjs/axios";
+import { Agent } from "https";
+import { firstValueFrom } from "rxjs";
+import {
+  ETradeCompanyInfo,
+  ETradeBusinessInfo,
+  CompanyRegistrationData,
+} from "@edr/types";
+
+@Injectable()
+export class ETradeService {
+  private readonly baseUrl = "https://etrade.gov.et/api";
+  private readonly referer = "https://etrade.gov.et/business-license-checker";
+
+  /**
+   * The eTrade server serves an incomplete TLS chain (it omits the intermediate
+   * CA cert), so Node rejects the handshake with UNABLE_TO_GET_ISSUER_CERT.
+   * Scope a relaxed agent to these outbound calls only — the rest of the app
+   * keeps full certificate verification.
+   */
+  private readonly httpsAgent = new Agent({ rejectUnauthorized: false });
+
+  constructor(private readonly httpService: HttpService) {}
+
+  async getCompanyInfoByTin(tin: string): Promise<ETradeCompanyInfo> {
+    const url = `${this.baseUrl}/Registration/GetRegistrationInfoByTin/${tin}/en`;
+    try {
+      const response = await firstValueFrom(
+        this.httpService.get<ETradeCompanyInfo>(url, {
+          headers: { Referer: this.referer },
+          httpsAgent: this.httpsAgent,
+        }),
+      );
+      return response.data;
+    } catch (error: any) {
+      throw new BadRequestException(
+        `Failed to fetch company info from eTrade: ${error.message}`,
+      );
+    }
+  }
+
+  async getBusinessByLicenseNo(
+    licenseNo: string,
+    tin: string,
+  ): Promise<ETradeBusinessInfo> {
+    const url = `${this.baseUrl}/BusinessMain/GetBusinessByLicenseNo`;
+    try {
+      const response = await firstValueFrom(
+        this.httpService.get<ETradeBusinessInfo>(url, {
+          params: {
+            LicenseNo: licenseNo,
+            Tin: tin,
+            Lang: "en",
+          },
+          headers: { Referer: this.referer },
+          httpsAgent: this.httpsAgent,
+        }),
+      );
+      return response.data;
+    } catch (error: any) {
+      throw new BadRequestException(
+        `Failed to fetch business info from eTrade: ${error.message}`,
+      );
+    }
+  }
+
+  async resolveCompanyData(tin: string): Promise<{
+    companyInfo: ETradeCompanyInfo;
+    businessInfo: ETradeBusinessInfo | null;
+  }> {
+    const companyInfo = await this.getCompanyInfoByTin(tin);
+
+    if (!companyInfo.Businesses || companyInfo.Businesses.length === 0) {
+      return { companyInfo, businessInfo: null };
+    }
+
+    const latestBusiness = companyInfo.Businesses[0];
+    try {
+      const businessInfo = await this.getBusinessByLicenseNo(
+        latestBusiness.LicenceNumber,
+        tin,
+      );
+      return { companyInfo, businessInfo };
+    } catch {
+      return { companyInfo, businessInfo: null };
+    }
+  }
+
+  extractRegistrationData(
+    businessInfo: ETradeBusinessInfo,
+  ): CompanyRegistrationData {
+    const primaryManager = businessInfo.AssociateShortInfos?.[0];
+
+    return {
+      licenceNumber: businessInfo.LicenceNumber,
+      statusDescription: businessInfo.StatusDescription,
+      dateRegistered: businessInfo.DateRegistered,
+      renewedFrom: businessInfo.RenewedFrom,
+      renewalDate: businessInfo.RenewalDate,
+      renewedTo: businessInfo.RenewedTo,
+      region: businessInfo.AddressInfo?.Region || "",
+      zone: businessInfo.AddressInfo?.Zone || "",
+      woreda: businessInfo.AddressInfo?.Woreda || "",
+      kebele: businessInfo.AddressInfo?.Kebele || "",
+      houseNo: businessInfo.AddressInfo?.HouseNo || "",
+      mobilePhone: businessInfo.AddressInfo?.MobilePhone || "",
+      regularPhone: businessInfo.AddressInfo?.RegularPhone || "",
+      managerName: primaryManager?.ManagerNameEng || "",
+      managerPhone: primaryManager?.RegularPhone || "",
+    };
+  }
+}

apps/edr-freight-api/src/modules/payment/payment.module.ts

@@ -18,6 +18,7 @@ import { PaymentEventsConsumer } from "./payment-events.consumer";
 import { InternalPaymentController } from "./internal-payment.controller";
 import { ServiceAuthGuard } from "../../common/guards/service-auth.guard";
 import { TrainSchedulingModule } from "../train-scheduling/train-scheduling.module";
+import { DropdownSettingsModule } from "../dropdown-settings/dropdown-settings.module";
 import { PaymentWebhookEventEntity } from "./entities/payment-webhook-event.entity";
 import { PaymentRefundEntity } from "./entities/payment-refund.entity";
 
@@ -27,6 +28,7 @@ const FREIGHT_QUEUE = PAYMENT_QUEUES[PaymentServiceEnum.FREIGHT];
     imports: [
         HttpModule.register({ timeout: 10_000 }),
         ConfigModule,
+        DropdownSettingsModule,
         forwardRef(() => TrainSchedulingModule),
         TypeOrmModule.forFeature([PaymentWebhookEventEntity, PaymentRefundEntity]),
         RabbitMQModule.forRootAsync({

apps/edr-freight-api/src/modules/payment/payment.service.ts

@@ -34,6 +34,11 @@ import {
     RefundDto,
 } from "./payments.dto";
 import { BookingBatchService } from "../train-scheduling/booking-batch.service";
+import { DropdownSettingsService } from "../dropdown-settings/dropdown-settings.service";
+
+/** Setting code holding the global ordering window (months) for general contracts. */
+const CONTRACT_PERIOD_SETTING_CODE = "general_contract_period";
+const DEFAULT_CONTRACT_PERIOD_MONTHS = 3;
 
 const STATUS_MAP: Record<string, ProviderPaymentStatus> = {
     "action-required": ProviderPaymentStatus.REQUIRES_ACTION,
@@ -54,8 +59,23 @@ export class PaymentService {
         private readonly paymentClient: PaymentClientService,
         @Inject(forwardRef(() => BookingBatchService))
         private readonly bookingBatchService: BookingBatchService,
+        private readonly dropdownSettings: DropdownSettingsService,
     ) { }
 
+    /** Configured general-contract ordering window in months (defaults to 3). */
+    private async contractPeriodMonths(): Promise<number> {
+        try {
+            const setting = await this.dropdownSettings.getByCode(
+                CONTRACT_PERIOD_SETTING_CODE,
+            );
+            const months = Number(setting.children?.[0]?.value);
+            if (Number.isFinite(months) && months > 0) return months;
+        } catch {
+            // Setting not seeded — fall back to the default.
+        }
+        return DEFAULT_CONTRACT_PERIOD_MONTHS;
+    }
+
     async getAll(filters: {
         search?: string;
         status?: string;
@@ -293,15 +313,44 @@ export class PaymentService {
 
         const paidAt = input.paidAt ?? new Date();
 
+        // A general contract is paid once, up front; it does NOT enter the train
+        // queue (nothing has been ordered yet). Instead it becomes ACTIVE and
+        // opens its ordering window. Orders placed later spawn their own paid
+        // child bookings that go through the normal pipeline.
+        const booking = await this.datasource
+            .getRepository(Booking)
+            .findOne({ where: { id: input.bookingId } });
+        const isGeneralContract = booking?.bookingType === "GENERAL_CONTRACT";
+
+        let contractExpiresAt: Date | null = null;
+        if (isGeneralContract) {
+            const months = await this.contractPeriodMonths();
+            contractExpiresAt = new Date(paidAt);
+            contractExpiresAt.setMonth(contractExpiresAt.getMonth() + months);
+        }
+
         await this.datasource.transaction(async (mg) => {
             await mg.update(
                 PaymentEntity,
                 { id: intent.id },
                 { status: "success", paidAt, transactionId: input.providerTxnId ?? intent.transactionId },
             );
-            await mg.update(Booking, { id: input.bookingId }, { paymentStatus: "PAID" ,status:"PAID"});
+            await mg.update(
+                Booking,
+                { id: input.bookingId },
+                isGeneralContract
+                    ? { paymentStatus: "PAID", status: "CONTRACT_ACTIVE", expiresAt: contractExpiresAt }
+                    : { paymentStatus: "PAID", status: "PAID" },
+            );
         });
 
+        if (isGeneralContract) {
+            this.logger.log(
+                `General contract ${booking?.reference ?? input.bookingId} ACTIVE — ordering open until ${contractExpiresAt?.toISOString()}`,
+            );
+            return { alreadyFinalized: false };
+        }
+
         try {
             await this.bookingBatchService.ensurePaidBookingAllocated(input.bookingId);
         } catch (err) {

apps/edr-freight-api/src/modules/rule-engine/dto/create-cargo-type.dto.ts

@@ -1,5 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsBoolean, IsInt, IsOptional, IsString, IsUUID, MaxLength, Min } from 'class-validator';
+import { CargoUnitOfMeasure } from '@edr/types';
+import { IsBoolean, IsEnum, IsInt, IsOptional, IsString, IsUUID, MaxLength, Min } from 'class-validator';
 
 export class CreateCargoTypeDto {
   @ApiProperty({ description: 'Cargo type display name', maxLength: 255 })
@@ -7,6 +8,14 @@ export class CreateCargoTypeDto {
   @MaxLength(255)
   cargoTypeName!: string;
 
+  @ApiPropertyOptional({
+    enum: CargoUnitOfMeasure,
+    description: 'How this cargo is measured (PER_TON for bulk, PER_ITEM for break-bulk)',
+  })
+  @IsOptional()
+  @IsEnum(CargoUnitOfMeasure)
+  unitOfMeasure?: CargoUnitOfMeasure;
+
   @ApiPropertyOptional({ description: 'Parent group ID for hierarchical cargo types' })
   @IsOptional()
   @IsUUID()

apps/edr-freight-api/src/modules/rule-engine/entities/cargo-type.entity.ts

@@ -1,4 +1,5 @@
 import { BaseEntity } from '@edr/api-common';
+import { CargoUnitOfMeasure } from '@edr/types';
 import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
 
 @Entity({ schema: 'freight', name: 'cargo_types' })
@@ -19,6 +20,14 @@ export class CargoType extends BaseEntity {
   @Column({ name: 'show_free_text_box', type: 'boolean', default: false })
   showFreeTextBox!: boolean;
 
+  /**
+   * How this cargo's quantity is measured: PER_TON (bulk) or PER_ITEM
+   * (break-bulk). Nullable for container/legacy cargo, which is counted by
+   * container. Drives the unit shown when ordering against a general contract.
+   */
+  @Column({ name: 'unit_of_measure', type: 'varchar', length: 16, nullable: true })
+  unitOfMeasure?: CargoUnitOfMeasure | null;
+
   @Column({ name: 'requires_director_approval', type: 'boolean', default: false })
   requiresDirectorApproval!: boolean;
 

apps/edr-freight-api/src/modules/rule-engine/services/cargo-types.service.ts

@@ -82,6 +82,7 @@ export class CargoTypesService {
       showFreeTextBox: dto.showFreeTextBox ?? false,
       requiresDirectorApproval: dto.requiresDirectorApproval ?? false,
       isActive: dto.isActive ?? true,
+      unitOfMeasure: dto.unitOfMeasure ?? null,
       displayOrder,
     });
   }

apps/edr-freight-api/src/modules/scheduling/compare-scheduling-priority.util.ts

@@ -1,7 +1,9 @@
 export interface SchedulingPriorityBooking {
   isGovernment?: boolean;
   priorityScore?: number | null;
-  scheduledDate: Date | string;
+  // One-time bookings always carry a date; general contracts (never scheduled)
+  // may be null — treated as epoch 0 so they sort last.
+  scheduledDate?: Date | string | null;
 }
 
 /** Government first, then priority score, then earliest scheduled date. */
@@ -15,5 +17,7 @@ export function compareSchedulingPriority(
   const priorityDiff = (b.priorityScore ?? 0) - (a.priorityScore ?? 0);
   if (priorityDiff !== 0) return priorityDiff;
 
-  return new Date(a.scheduledDate).getTime() - new Date(b.scheduledDate).getTime();
+  const aTime = a.scheduledDate ? new Date(a.scheduledDate).getTime() : 0;
+  const bTime = b.scheduledDate ? new Date(b.scheduledDate).getTime() : 0;
+  return aTime - bTime;
 }

apps/edr-freight-api/src/modules/train-scheduling/booking-batch.constants.ts

@@ -3,10 +3,11 @@
  * Times run in EAT so the 07:00/10:00/… boundaries match the local operating clock.
  */
 
-/** Batch boundaries — every 3h from 07:00 (the 07:00–10:00 intake settles at 10:00, etc.). */
+/** Batch boundaries — every 3h from 00:00 (00–03, 03–06, … 21–24), matching the board windows. */
 // export const BATCH_CRON = '0 7,10,13,16,19,22 * * *';
 // export const BATCH_CRON = '*/3 * * * *';
 export const BATCH_CRON = '*/5 * * * *';
+// export const BATCH_CRON = '0 */3 * * *';//
 
 export const BATCH_TIMEZONE = 'Africa/Addis_Ababa';
 

apps/edr-freight-api/src/modules/train-scheduling/fleet-plan.util.ts

@@ -30,7 +30,9 @@ export function sortBookingsForScheduling(bookings: Booking[]): Booking[] {
     const priorityDiff = (b.priorityScore ?? 0) - (a.priorityScore ?? 0);
     if (priorityDiff !== 0) return priorityDiff;
 
-    return new Date(a.scheduledDate).getTime() - new Date(b.scheduledDate).getTime();
+    const aTime = a.scheduledDate ? new Date(a.scheduledDate).getTime() : 0;
+    const bTime = b.scheduledDate ? new Date(b.scheduledDate).getTime() : 0;
+    return aTime - bTime;
   });
 }
 

apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts

@@ -1880,7 +1880,7 @@ export class TrainSchedulingService {
       origin: booking.originYard?.label ?? booking.originYard?.code ?? 'Unknown origin',
       destination:
         booking.destinationYard?.label ?? booking.destinationYard?.code ?? 'Unknown destination',
-      preferredDepartureDate: booking.scheduledDate.toISOString(),
+      preferredDepartureDate: booking.scheduledDate?.toISOString() ?? null,
       status: booking.status,
     };
   }