merge

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

@@ -392,6 +392,17 @@ export class BookingsService {
           tradeDirection,
           fallbackType,
         );
+
+      // A customer booking under their own account may only do so once the
+      // resolved operational profile has been approved by the backoffice. Staff-
+      // and government-initiated bookings (companyId supplied explicitly) bypass
+      // this gate.
+      const customerSelfBooking = !dto.companyId && !!userId;
+      if (customerSelfBooking && companyProfileId) {
+        await this.companiesService.assertCompanyProfileApprovedForBooking(
+          companyProfileId,
+        );
+      }
     }
 
     const needsConsolidation =

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

@@ -41,6 +41,7 @@ import { ProfileResponseDto } from "./dto/profile-response.dto";
 import { DashboardSummaryResponseDto } from "./dto/dashboard-summary-response.dto";
 import { ListCompaniesQueryDto } from "./dto/list-companies-query.dto";
 import { CompanyStatsResponseDto } from "./dto/company-stats-response.dto";
+import { OnboardingRequirementsResponseDto } from "./dto/onboarding-requirements-response.dto";
 import { UpdateCompanyProfileStatusDto } from "./dto/update-company-profile-status.dto";
 import { FetchETradeDto } from "./dto/fetch-etrade.dto";
 import { ETradeResponseDto } from "./dto/etrade-response.dto";
@@ -226,6 +227,17 @@ export class CompaniesController {
     await this.companiesService.setOnboardingStep(user.id, dto.step);
   }
 
+  @Get("onboarding/requirements")
+  @ApiOperation({
+    summary:
+      "What the current user's company still needs to finish onboarding (server-driven documents + outstanding items)",
+  })
+  async getOnboardingRequirements(
+    @CurrentUser() user: CurrentIamUser,
+  ): Promise<OnboardingRequirementsResponseDto> {
+    return this.companiesService.getOnboardingRequirements(user.id);
+  }
+
   @Post("onboarding/complete")
   @ApiOperation({ summary: "Mark the current user's onboarding as complete" })
   async completeOnboarding(

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

@@ -2,6 +2,7 @@ import { Module } from "@nestjs/common";
 import { TypeOrmModule } from "@nestjs/typeorm";
 import { HttpModule } from "@nestjs/axios";
 import { FilesModule } from "../files/files.module";
+import { FileUploadSettingsModule } from "../file-upload-settings/file-upload-settings.module";
 import { MinioModule } from "../minio/minio.module";
 import { CompaniesController } from "./companies.controller";
 import { CompaniesService } from "./companies.service";
@@ -20,6 +21,7 @@ import { ETradeService } from "./services/etrade.service";
     TypeOrmModule.forFeature([Company, ExternalProfile, CompanyProfile, Booking]),
     HttpModule,
     FilesModule,
+    FileUploadSettingsModule,
     MinioModule,
   ],
   controllers: [CompaniesController],

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

@@ -3,6 +3,7 @@ import {
   NotFoundException,
   ConflictException,
   BadRequestException,
+  ForbiddenException,
 } from "@nestjs/common";
 import { CompaniesRepository } from "./companies.repository";
 import { CompanyProfileRepository } from "./company-profile.repository";
@@ -12,7 +13,10 @@ import {
   DashboardScope,
 } from "./company-dashboard.repository";
 import { MinioService } from "../minio/minio.service";
+import { FilesService } from "../files/files.service";
+import { FileUploadSettingsService } from "../file-upload-settings/file-upload-settings.service";
 import { ETradeService } from "./services/etrade.service";
+import { OnboardingRequirementsResponseDto } from "./dto/onboarding-requirements-response.dto";
 import { normalizeE164 } from "../../common/validators/is-phone-number.validator";
 import { CreateCompanyDto } from "./dto/create-company.dto";
 import { UpdateCompanyDto } from "./dto/update-company.dto";
@@ -53,9 +57,67 @@ export class CompaniesService {
     private readonly profilesRepo: ExternalProfileRepository,
     private readonly dashboardRepo: CompanyDashboardRepository,
     private readonly minioService: MinioService,
+    private readonly filesService: FilesService,
+    private readonly fileUploadSettingsService: FileUploadSettingsService,
     private readonly etradeService: ETradeService,
   ) { }
 
+  /**
+   * Required company-information fields that must be filled before onboarding can
+   * be submitted. The backend owns this list so the portal never has to know
+   * which fields are mandatory — it just renders what's reported outstanding.
+   * `get` reads the value from the company (some live in the attributes blob).
+   */
+  private readonly REQUIRED_COMPANY_INFO: {
+    key: string;
+    label: string;
+    get: (company: Company) => unknown;
+  }[] = [
+    {
+      key: "tinNumber",
+      label: "Company TIN",
+      get: (c) => (c.tin && !c.tin.startsWith("D") ? c.tin : null),
+    },
+    { key: "companyEmail", label: "Company email", get: (c) => c.email },
+    { key: "companyPhone", label: "Company phone", get: (c) => c.phone },
+    { key: "companyAddress", label: "Company address", get: (c) => c.address },
+    { key: "fanNumber", label: "FAN number", get: (c) => c.fanNumber },
+    {
+      key: "contactPersonName",
+      label: "Contact person name",
+      get: (c) => c.attributes?.contactPersonName,
+    },
+    {
+      key: "contactPersonPhone",
+      label: "Contact person phone",
+      get: (c) => c.attributes?.contactPersonPhone,
+    },
+    {
+      key: "generalManagerName",
+      label: "General manager name",
+      get: (c) => c.attributes?.generalManagerName,
+    },
+    {
+      key: "generalManagerEmail",
+      label: "General manager email",
+      get: (c) => c.attributes?.generalManagerEmail,
+    },
+    {
+      key: "generalManagerPhone",
+      label: "General manager phone",
+      get: (c) => c.attributes?.generalManagerPhone,
+    },
+  ];
+
+  /** The nationality-based document setting code for a company. */
+  private documentSettingCodeFor(
+    nationality: CompanyNationality | null | undefined,
+  ): string {
+    return nationality === CompanyNationality.Foreign
+      ? "company_onboarding_documents_foreign"
+      : "company_onboarding_documents_ethiopian";
+  }
+
   async createCompany(dto: CreateCompanyDto): Promise<Company> {
     const exists = await this.companiesRepo.existsByTin(dto.tin);
     if (exists) {
@@ -77,10 +139,12 @@ export class CompaniesService {
       }
     }
 
-    const existingProfile = await this.profilesRepo.findByEmail(identity.email);
+    const existingProfile = await this.profilesRepo.findByUserId(
+      identity.userId,
+    );
     if (existingProfile) {
       throw new ConflictException(
-        `Profile with email ${identity.email} already exists`,
+        `Profile for user ${identity.userId} already exists`,
       );
     }
 
@@ -114,8 +178,6 @@ export class CompaniesService {
       companyId: company.id,
       firstName: identity.firstName,
       lastName: identity.lastName,
-      email: identity.email,
-      phone: normalizeE164(identity.phone) ?? identity.phone,
       jobTitle: dto.jobTitle ?? null,
       isPrimaryContact: dto.isPrimaryContact ?? true,
       activeProfileType,
@@ -134,15 +196,13 @@ export class CompaniesService {
           input.type,
         );
         if (existing) continue;
-        const reference = await this.companyProfilesRepo.generateReference(
-          input.type,
-        );
+        // No reference yet — these profiles await backoffice approval, which
+        // is when the reference is minted (see setCompanyProfileStatus).
         await this.companyProfilesRepo.create({
           companyId: company.id,
           type: input.type,
-          reference,
           businessLicense: input.businessLicense ?? null,
-          status: ProfileStatus.Active,
+          status: ProfileStatus.Pending,
         });
       }
       company.companyProfiles = await this.companyProfilesRepo.findByCompanyId(
@@ -191,15 +251,6 @@ export class CompaniesService {
       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 =
@@ -224,8 +275,6 @@ export class CompaniesService {
       companyId: company.id,
       firstName: identity.firstName,
       lastName: identity.lastName,
-      email: identity.email,
-      phone: normalizeE164(identity.phone) ?? identity.phone,
       isPrimaryContact: true,
       activeProfileType,
       onboardingStep: "company",
@@ -251,12 +300,11 @@ export class CompaniesService {
         type,
       );
       if (existing) continue;
-      const reference = await this.companyProfilesRepo.generateReference(type);
+      // No reference yet — minted on backoffice approval (setCompanyProfileStatus).
       await this.companyProfilesRepo.create({
         companyId,
         type,
-        reference,
-        status: ProfileStatus.Active,
+        status: ProfileStatus.Pending,
       });
     }
   }
@@ -527,6 +575,8 @@ export class CompaniesService {
       attrUpdates.contactPersonEmail = dto.contactPersonEmail;
     if (dto.contactPersonPhone !== undefined)
       attrUpdates.contactPersonPhone = normalizeE164(dto.contactPersonPhone);
+    if (dto.contactVerifiedPhone !== undefined)
+      attrUpdates.contactVerifiedPhone = normalizeE164(dto.contactVerifiedPhone);
     if (dto.generalManagerName !== undefined)
       attrUpdates.generalManagerName = dto.generalManagerName;
     if (dto.generalManagerEmail !== undefined)
@@ -576,10 +626,10 @@ export class CompaniesService {
   async createProfile(dto: CreateExternalProfileDto): Promise<ExternalProfile> {
     await this.findCompanyById(dto.companyId);
 
-    const existing = await this.profilesRepo.findByEmail(dto.email);
+    const existing = await this.profilesRepo.findByUserId(dto.userId);
     if (existing) {
       throw new ConflictException(
-        `Profile with email ${dto.email} already exists`,
+        `Profile for user ${dto.userId} already exists`,
       );
     }
 
@@ -622,12 +672,33 @@ export class CompaniesService {
     profileId: string,
     status: ProfileStatus,
   ): Promise<CompanyProfile> {
-    const updated = await this.companyProfilesRepo.updateStatus(
-      profileId,
-      status,
-    );
+    const existing = await this.companyProfilesRepo.findById(profileId);
+    if (!existing)
+      throw new NotFoundException(`Company profile ${profileId} not found`);
+
+    // A reference number is only minted the first time a profile is approved
+    // (status → Active). Pending/unapproved profiles carry no reference.
+    const patch: Partial<CompanyProfile> = { status };
+    if (status === ProfileStatus.Active && !existing.reference) {
+      patch.reference = await this.companyProfilesRepo.generateReference(
+        existing.type,
+      );
+    }
+
+    const updated = await this.companyProfilesRepo.update(profileId, patch);
     if (!updated)
       throw new NotFoundException(`Company profile ${profileId} not found`);
+
+    // Approving any profile promotes a pending company to active, so the
+    // customer can start working as soon as their first profile is cleared.
+    if (status === ProfileStatus.Active) {
+      const company = await this.companiesRepo.findById(updated.companyId);
+      if (company && company.status === CompanyStatus.Pending) {
+        await this.companiesRepo.update(updated.companyId, {
+          status: CompanyStatus.Active,
+        });
+      }
+    }
     return updated;
   }
 
@@ -649,7 +720,7 @@ export class CompaniesService {
     const existing = await this.companyProfilesRepo.findByType(companyId, type);
     if (existing) {
       throw new ConflictException(
-        `Company already has a ${type} profile (${existing.reference})`,
+        `Company already has a ${type} profile (${existing.reference ?? "pending approval"})`,
       );
     }
 
@@ -813,6 +884,100 @@ export class CompaniesService {
     await this.profilesRepo.update(profile.id, { onboardingStep: step });
   }
 
+  /**
+   * Server-driven onboarding requirements for the current user's company.
+   *
+   * The backend resolves the nationality-based document set, checks which
+   * company documents and per-profile licenses are already uploaded, and reports
+   * exactly what is still outstanding. The portal renders this list verbatim and
+   * relies on `isComplete` to decide when to auto-finish — it never decides for
+   * itself which documents apply or which fields are mandatory.
+   */
+  async getOnboardingRequirements(
+    userId: string,
+  ): Promise<OnboardingRequirementsResponseDto> {
+    const { profile, company } = await this.getCompanyInfoByUserId(userId);
+
+    // 1. Required company-information fields.
+    const missingInfo = this.REQUIRED_COMPANY_INFO.filter(
+      (f) => !f.get(company),
+    ).map((f) => ({ key: f.key, label: f.label }));
+
+    // 2. Nationality-based company documents + which are already uploaded.
+    const documentSettingCode = this.documentSettingCodeFor(company.nationality);
+    const [setting, uploadedFiles] = await Promise.all([
+      this.fileUploadSettingsService
+        .getByCode(documentSettingCode)
+        .catch(() => null),
+      this.filesService.findByResource(company.id, "companies"),
+    ]);
+    const uploadedCodes = new Set(uploadedFiles.map((f) => f.code));
+    const documents = (setting?.fields ?? [])
+      .slice()
+      .sort((a, b) => a.displayOrder - b.displayOrder)
+      .map((f) => ({
+        fileKey: f.fileKey,
+        fileLabel: f.fileLabel,
+        helpText: f.helpText ?? null,
+        isRequired: f.isRequired,
+        isMultiple: f.isMultiple,
+        maxFiles: f.maxFiles,
+        allowedExtensions: f.allowedExtensions,
+        maxSizeMb: f.maxSizeMb,
+        displayOrder: f.displayOrder,
+        uploaded: uploadedCodes.has(f.fileKey),
+      }));
+    const missingDocs = documents.filter((d) => d.isRequired && !d.uploaded);
+
+    // 3. Per-operational-profile business licenses.
+    const licenseProfiles = (company.companyProfiles ?? []).map((p) => ({
+      profileId: p.id,
+      type: p.type,
+      reference: p.reference ?? "",
+      uploaded: (p.businessLicenseFiles?.length ?? 0) > 0,
+    }));
+    const missingLicenses = licenseProfiles.filter((p) => !p.uploaded);
+
+    const outstanding = [
+      ...missingInfo.map((f) => `Add your ${f.label.toLowerCase()}`),
+      ...missingDocs.map((d) => `Upload your ${d.fileLabel}`),
+      ...missingLicenses.map(
+        (p) =>
+          `Upload a business license for your ${p.type.replace(/_/g, " ")} profile`,
+      ),
+    ];
+
+    // Progress spans every required item the user has to satisfy: company-info
+    // fields, required documents and one license per operational profile.
+    const requiredDocCount = documents.filter((d) => d.isRequired).length;
+    const total =
+      this.REQUIRED_COMPANY_INFO.length +
+      requiredDocCount +
+      licenseProfiles.length;
+    const completed =
+      total -
+      (missingInfo.length + missingDocs.length + missingLicenses.length);
+
+    return new OnboardingRequirementsResponseDto({
+      documentSettingCode,
+      nationality: company.nationality ?? CompanyNationality.Ethiopian,
+      companyInfo: { complete: missingInfo.length === 0, missingFields: missingInfo },
+      documents,
+      licenseProfiles,
+      progress: { completed, total },
+      isComplete: outstanding.length === 0,
+      onboardingCompleted: profile.onboardingCompleted,
+      outstanding,
+    });
+  }
+
+  /**
+   * Submit onboarding for review. Validation is delegated entirely to
+   * getOnboardingRequirements (the same source of truth the portal renders), so
+   * the gate can never drift from what the UI shows. On success the company and
+   * all its operational profiles move to PENDING — the backoffice approves each
+   * profile before it can be used (see setCompanyProfileStatus).
+   */
   async markOnboardingComplete(
     userId: string,
   ): Promise<{ profile: ExternalProfile; company: Company }> {
@@ -821,23 +986,21 @@ export class CompaniesService {
       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")) {
+    const requirements = await this.getOnboardingRequirements(userId);
+    if (!requirements.isComplete) {
       throw new BadRequestException(
-        "Company information is incomplete — please fill in your company details before finishing.",
+        requirements.outstanding[0] ??
+          "Your onboarding is incomplete. Please complete all required steps before submitting.",
       );
     }
 
-    // Every operational profile must have at least one business-license file
-    // (stored directly on the profile).
+    // Send every operational profile in for approval; the company itself becomes
+    // active once the backoffice approves at least one 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.`,
-        );
+      if (cp.status !== ProfileStatus.Pending) {
+        await this.companyProfilesRepo.updateStatus(cp.id, ProfileStatus.Pending);
       }
     }
 
@@ -852,6 +1015,25 @@ export class CompaniesService {
     return this.getCompanyInfoByUserId(userId);
   }
 
+  /**
+   * Block a customer from booking under a profile that isn't approved yet.
+   * Called from the booking-create path for self-service bookings; staff- and
+   * government-initiated bookings bypass this. No-op when the profile can't be
+   * found (defensive — resolution is best-effort upstream).
+   */
+  async assertCompanyProfileApprovedForBooking(
+    companyProfileId: string,
+  ): Promise<void> {
+    const profile = await this.companyProfilesRepo.findById(companyProfileId);
+    if (!profile) return;
+    if (profile.status !== ProfileStatus.Active) {
+      const role = profile.type.replace(/_/g, " ");
+      throw new ForbiddenException(
+        `Your ${role} profile is awaiting approval. You'll be able to create bookings once it has been approved.`,
+      );
+    }
+  }
+
   /**
    * Authorize and resolve a company_profile that must belong to the current
    * user's company — used before accepting/returning its license files.

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

@@ -30,7 +30,11 @@ export class CompanyProfileRepository extends BaseRepository<CompanyProfile> {
   }
 
   async generateReference(type: ProfileType): Promise<string> {
-    const seqName = SEQUENCE_MAP[type];
+    // The sequences live in the same schema as the entity (e.g. "freight"), but
+    // the connection's search_path is "public" — so the sequence MUST be
+    // schema-qualified or `nextval` fails with "relation does not exist".
+    const schema = this.repository.metadata.schema ?? "public";
+    const seqName = `"${schema}".${SEQUENCE_MAP[type]}`;
     const result = await this.repository.query(
       `SELECT nextval('${seqName}') AS next_id`,
     );

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

@@ -1,5 +1,4 @@
-import { IsString, IsNotEmpty, IsOptional, IsEmail, MaxLength, IsBoolean, IsUUID } from 'class-validator';
-import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
+import { IsString, IsNotEmpty, IsOptional, MaxLength, IsBoolean, IsUUID } from 'class-validator';
 
 export class CreateExternalProfileDto {
   @IsUUID()
@@ -20,16 +19,6 @@ export class CreateExternalProfileDto {
   @MaxLength(100)
   lastName!: string;
 
-  @IsEmail()
-  @IsNotEmpty()
-  email!: string;
-
-  @IsOptional()
-  @IsString()
-  @MaxLength(20)
-  @IsValidPhone()
-  phone?: string;
-
   @IsOptional()
   @IsString()
   @MaxLength(50)

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

@@ -0,0 +1,78 @@
+/**
+ * Server-driven description of what a company still needs to finish onboarding.
+ *
+ * The portal renders this verbatim instead of deciding for itself which
+ * documents apply or which fields are mandatory: the backend resolves the
+ * nationality-based document set, checks which files are already uploaded, and
+ * reports exactly what is outstanding. `isComplete` is the single source of
+ * truth the wizard uses to auto-finish.
+ */
+
+export interface OnboardingInfoField {
+  key: string;
+  label: string;
+}
+
+export interface OnboardingDocumentField {
+  fileKey: string;
+  fileLabel: string;
+  helpText: string | null;
+  isRequired: boolean;
+  isMultiple: boolean;
+  maxFiles: number;
+  allowedExtensions: string[];
+  maxSizeMb: number;
+  displayOrder: number;
+  /** True when a file with this code is already stored for the company. */
+  uploaded: boolean;
+}
+
+export interface OnboardingLicenseProfile {
+  profileId: string;
+  type: string;
+  reference: string;
+  /** True when at least one business-license file is stored on the profile. */
+  uploaded: boolean;
+}
+
+export class OnboardingRequirementsResponseDto {
+  /** Resolved document setting code (by nationality) the docs were drawn from. */
+  documentSettingCode: string;
+  nationality: string;
+
+  /** Required company-information fields and whether each is filled. */
+  companyInfo: {
+    complete: boolean;
+    missingFields: OnboardingInfoField[];
+  };
+
+  /** The document fields the portal should render, with upload state. */
+  documents: OnboardingDocumentField[];
+
+  /** Per-operational-profile business-license requirements. */
+  licenseProfiles: OnboardingLicenseProfile[];
+
+  /** Overall setup progress across fields + documents + licenses. */
+  progress: { completed: number; total: number };
+
+  /** True once every required field, document and license is satisfied. */
+  isComplete: boolean;
+
+  /** Whether the user has already submitted onboarding (awaiting approval). */
+  onboardingCompleted: boolean;
+
+  /** Human-readable list of everything still outstanding (empty when complete). */
+  outstanding: string[];
+
+  constructor(init: Omit<OnboardingRequirementsResponseDto, never>) {
+    this.documentSettingCode = init.documentSettingCode;
+    this.nationality = init.nationality;
+    this.companyInfo = init.companyInfo;
+    this.documents = init.documents;
+    this.licenseProfiles = init.licenseProfiles;
+    this.progress = init.progress;
+    this.isComplete = init.isComplete;
+    this.onboardingCompleted = init.onboardingCompleted;
+    this.outstanding = init.outstanding;
+  }
+}

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

@@ -34,6 +34,8 @@ export class ProfileResponseDto {
   contactPersonPosition: string | null;
   contactPersonEmail: string | null;
   contactPersonPhone: string | null;
+  /** Phone that passed SMS OTP verification (drives the verify-step resume). */
+  contactVerifiedPhone: string | null;
   generalManagerName: string | null;
   generalManagerEmail: string | null;
   generalManagerPhone: string | null;
@@ -81,6 +83,7 @@ export class ProfileResponseDto {
     this.contactPersonPosition = attrs.contactPersonPosition ?? null;
     this.contactPersonEmail = attrs.contactPersonEmail ?? null;
     this.contactPersonPhone = attrs.contactPersonPhone ?? null;
+    this.contactVerifiedPhone = attrs.contactVerifiedPhone ?? null;
     this.generalManagerName = attrs.generalManagerName ?? null;
     this.generalManagerEmail = attrs.generalManagerEmail ?? null;
     this.generalManagerPhone = attrs.generalManagerPhone ?? null;

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

@@ -28,7 +28,7 @@ export class ResponseCompanyProfileDto {
     this.id = profile.id;
     this.companyId = profile.companyId;
     this.type = profile.type;
-    this.reference = profile.reference;
+    this.reference = profile.reference ?? '';
     this.status = profile.status;
     this.businessLicense = profile.businessLicense;
     this.licenseFiles = profile.businessLicenseFiles ?? [];

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

@@ -10,8 +10,6 @@ export class ResponseExternalProfileDto {
   companyId: string;
   firstName: string;
   lastName: string;
-  email: string;
-  phone?: string | null;
   nationalId?: string | null;
   jobTitle?: string | null;
   isPrimaryContact: boolean;
@@ -34,8 +32,6 @@ export class ResponseExternalProfileDto {
     this.companyId = profile.companyId;
     this.firstName = profile.firstName;
     this.lastName = profile.lastName;
-    this.email = profile.email;
-    this.phone = profile.phone;
     this.nationalId = profile.nationalId;
     this.jobTitle = profile.jobTitle;
     this.isPrimaryContact = profile.isPrimaryContact;

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

@@ -67,6 +67,16 @@ export class UpdateProfileDto {
   @IsValidPhone()
   contactPersonPhone?: string;
 
+  /**
+   * The contact-person phone that completed SMS OTP verification. Persisted so
+   * the onboarding "verify" step can resume its "done" state after a refresh
+   * (compared against the current contactPersonPhone on the client).
+   */
+  @IsOptional()
+  @IsString()
+  @IsValidPhone()
+  contactVerifiedPhone?: string;
+
   @IsOptional()
   @IsString()
   generalManagerName?: string;

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

@@ -40,14 +40,19 @@ export class CompanyProfile extends BaseEntity {
   @Column({ name: "type", type: "varchar", length: 32, enum: ProfileType })
   type!: ProfileType;
 
+  /**
+   * Official profile reference (e.g. "EX-00001"). Minted only when the profile
+   * is approved (status → Active); pending/unapproved profiles carry NULL.
+   * The unique index tolerates this because Postgres treats NULLs as distinct.
+   * API responses surface it as "" when absent — see ResponseCompanyProfileDto.
+   */
   @Column({
     name: "reference",
     type: "varchar",
     length: 20,
-    nullable: false,
-    unique: true,
+    nullable: true,
   })
-  reference!: string;
+  reference!: string | null;
 
   @Column({
     name: "status",

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

@@ -23,12 +23,6 @@ export class ExternalProfile extends BaseEntity {
   @Column({ name: 'last_name', type: 'varchar', length: 100 })
   lastName!: string;
 
-  @Column({ name: 'email', type: 'varchar', length: 150, unique: true })
-  email!: string;
-
-  @Column({ name: 'phone', type: 'varchar', length: 20, nullable: true })
-  phone?: string | null;
-
   @Column({ name: 'national_id', type: 'varchar', length: 50, nullable: true })
   nationalId?: string | null;
 

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

@@ -23,8 +23,4 @@ export class ExternalProfileRepository extends BaseRepository<ExternalProfile> {
   async findByCompanyId(companyId: string): Promise<ExternalProfile[]> {
     return this.repository.find({ where: { companyId } as any });
   }
-
-  async findByEmail(email: string): Promise<ExternalProfile | null> {
-    return this.repository.findOne({ where: { email } as any });
-  }
 }

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

@@ -59,7 +59,7 @@ export class FirstMileController {
   @TrainSchedulingManage()
   @ApiOperation({ summary: 'Accept a paid booking and create a first-mile leg' })
   acceptBooking(@Param('reference') reference: string) {
-    return this.firstMileService.acceptBooking(reference);
+    return this.firstMileService.acceptBookingByReference(reference);
   }
 
   @Post()

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

@@ -2,13 +2,22 @@ import { Module, forwardRef } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { BookingsModule } from '../bookings/bookings.module';
+import { DriversModule } from '../drivers/drivers.module';
+import { NotificationsModule } from '../notifications/notifications.module';
+import { VehiclesModule } from '../vehicles/vehicles.module';
 import { FirstMile } from './entities/first-mile.entity';
 import { FirstMileController } from './first-mile.controller';
 import { FirstMileRepository } from './first-mile.repository';
 import { FirstMileService } from './first-mile.service';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([FirstMile]), forwardRef(() => BookingsModule)],
+  imports: [
+    TypeOrmModule.forFeature([FirstMile]),
+    forwardRef(() => BookingsModule),
+    VehiclesModule,
+    DriversModule,
+    NotificationsModule,
+  ],
   controllers: [FirstMileController],
   providers: [FirstMileRepository, FirstMileService],
   exports: [FirstMileRepository, FirstMileService],

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

@@ -1,7 +1,10 @@
-import { Injectable, NotFoundException } from '@nestjs/common';
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { FindOptionsWhere } from 'typeorm';
 
 import { BookingsRepository } from '../bookings/bookings.repository';
+import { DriversService } from '../drivers/drivers.service';
+import { NotificationsService } from '../notifications/notifications.service';
+import { VehiclesService } from '../vehicles/vehicles.service';
 import { CreateFirstMileDto } from './dto/create-first-mile.dto';
 import { UpdateFirstMileDto } from './dto/update-first-mile.dto';
 import { FirstMile, FirstMileStatus } from './entities/first-mile.entity';
@@ -26,9 +29,14 @@ const SORTABLE_FIELDS: (keyof FirstMile)[] = [
 
 @Injectable()
 export class FirstMileService {
+  private readonly logger = new Logger(FirstMileService.name);
+
   constructor(
     private readonly firstMileRepository: FirstMileRepository,
     private readonly bookingsRepository: BookingsRepository,
+    private readonly vehiclesService: VehiclesService,
+    private readonly driversService: DriversService,
+    private readonly notificationsService: NotificationsService,
   ) {}
 
   /**
@@ -36,8 +44,8 @@ export class FirstMileService {
    * paid before any first-mile work proceeds. Throws if the reference is
    * unknown or the booking has not reached PAID status.
    */
-  async acceptBooking(bookingReference: string): Promise<FirstMile | null> {
-    const booking = await this.bookingsRepository.findByReference(bookingReference);
+  async acceptBooking(bookingId: string): Promise<FirstMile | null> {
+    const booking = await this.bookingsRepository.findById(bookingId);
 
     if (!booking) {
       return null;
@@ -53,6 +61,22 @@ export class FirstMileService {
     });
   }
 
+  async acceptBookingByReference(bookingReference: string): Promise<FirstMile | null> {
+    const booking = await this.bookingsRepository.findByReference(bookingReference);
+
+    if (!booking) {
+      return null;
+    }
+
+    if (booking.paymentStatus !== 'PAID') {
+      return null;
+    }
+
+    return this.create({
+      bookingId: booking.id,
+      advancedPayment: 0,
+    });
+  }
   async findAll(filter: FirstMileListFilter = {}): Promise<{
     data: FirstMile[];
     meta: { total: number; page: number; pageSize: number; totalPages: number };
@@ -119,7 +143,7 @@ export class FirstMileService {
   }
 
   async update(id: string, dto: UpdateFirstMileDto): Promise<FirstMile> {
-    await this.findById(id);
+    const existing = await this.findById(id);
 
     const updated = await this.firstMileRepository.update(id, {
       ...(dto.bookingId !== undefined ? { bookingId: dto.bookingId } : {}),
@@ -135,9 +159,45 @@ export class FirstMileService {
       throw new NotFoundException(`First-mile record ${id} not found`);
     }
 
+    // Notify assigned driver on every explicit vehicle assignment or reassignment
+    if (dto.vehicleId) {
+      void this.notifyDriverAssignment(dto.vehicleId, existing);
+    }
+
     return updated;
   }
 
+  private async notifyDriverAssignment(vehicleId: string, record: FirstMile): Promise<void> {
+    try {
+      const vehicle = await this.vehiclesService.findById(vehicleId);
+      if (!vehicle.assignedDriverId) {
+        this.logger.warn(`Vehicle ${vehicleId} has no assigned driver — skipping SMS`);
+        return;
+      }
+
+      const driver = await this.driversService.findById(vehicle.assignedDriverId);
+      if (!driver.phoneNumber) {
+        this.logger.warn(`Driver ${vehicle.assignedDriverId} has no phone number — skipping SMS`);
+        return;
+      }
+
+      const booking = (record as FirstMile & { booking?: { reference?: string; firstMilePickupAddress?: string | null; originYard?: { label?: string } | null } }).booking;
+
+      await this.notificationsService.notifyDriverVehicleAssignment({
+        driverPhone: driver.phoneNumber,
+        driverName: `${driver.firstName ?? ''} ${driver.lastName ?? ''}`.trim(),
+        vehiclePlateNumber: vehicle.plateNumber ?? vehicleId,
+        bookingReference: booking?.reference ?? record.bookingId,
+        pickupAddress: booking?.firstMilePickupAddress,
+        destinationYard: booking?.originYard?.label,
+      });
+
+      this.logger.log(`SMS sent to driver ${driver.phoneNumber} for vehicle ${vehicleId} assignment`);
+    } catch (err) {
+      this.logger.error(`Failed to notify driver for vehicle ${vehicleId}: ${String(err)}`);
+    }
+  }
+
   async remove(id: string): Promise<void> {
     await this.findById(id);
     await this.firstMileRepository.softDelete(id);

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

@@ -59,7 +59,7 @@ export class LastMileController {
   @TrainSchedulingManage()
   @ApiOperation({ summary: 'Accept a paid booking and create a last-mile leg' })
   acceptBooking(@Param('reference') reference: string) {
-    return this.lastMileService.acceptBooking(reference);
+    return this.lastMileService.acceptBookingByReference(reference);
   }
 
   @Post()

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

@@ -2,13 +2,22 @@ import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { BookingsModule } from '../bookings/bookings.module';
+import { DriversModule } from '../drivers/drivers.module';
+import { NotificationsModule } from '../notifications/notifications.module';
+import { VehiclesModule } from '../vehicles/vehicles.module';
 import { LastMile } from './entities/last-mile.entity';
 import { LastMileController } from './last-mile.controller';
 import { LastMileRepository } from './last-mile.repository';
 import { LastMileService } from './last-mile.service';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([LastMile]), BookingsModule],
+  imports: [
+    TypeOrmModule.forFeature([LastMile]),
+    BookingsModule,
+    VehiclesModule,
+    DriversModule,
+    NotificationsModule,
+  ],
   controllers: [LastMileController],
   providers: [LastMileRepository, LastMileService],
   exports: [LastMileRepository, LastMileService],

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

@@ -1,7 +1,10 @@
-import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { FindOptionsWhere } from 'typeorm';
 
 import { BookingsRepository } from '../bookings/bookings.repository';
+import { DriversService } from '../drivers/drivers.service';
+import { NotificationsService } from '../notifications/notifications.service';
+import { VehiclesService } from '../vehicles/vehicles.service';
 import { CreateLastMileDto } from './dto/create-last-mile.dto';
 import { UpdateLastMileDto } from './dto/update-last-mile.dto';
 import { LastMile, LastMileStatus } from './entities/last-mile.entity';
@@ -26,9 +29,14 @@ const SORTABLE_FIELDS: (keyof LastMile)[] = [
 
 @Injectable()
 export class LastMileService {
+  private readonly logger = new Logger(LastMileService.name);
+
   constructor(
     private readonly lastMileRepository: LastMileRepository,
     private readonly bookingsRepository: BookingsRepository,
+    private readonly vehiclesService: VehiclesService,
+    private readonly driversService: DriversService,
+    private readonly notificationsService: NotificationsService,
   ) {}
 
   async acceptBooking(bookingReference: string): Promise<LastMile> {
@@ -46,7 +54,26 @@ export class LastMileService {
 
     return this.create({
       bookingId: booking.id,
-      advancedPayment: booking.totalAmount,
+      advancedPayment: 0,
+    });
+  }
+
+    async acceptBookingByReference(bookingReference: string): Promise<LastMile> {
+    const booking = await this.bookingsRepository.findByReference(bookingReference);
+
+    if (!booking) {
+      throw new NotFoundException(`Booking ${bookingReference} not found`);
+    }
+
+    if (booking.paymentStatus !== 'PAID') {
+      throw new BadRequestException(
+        `Booking ${bookingReference} is not paid (payment status: ${booking.paymentStatus})`,
+      );
+    }
+
+    return this.create({
+      bookingId: booking.id,
+      advancedPayment: 0,
     });
   }
 
@@ -116,7 +143,7 @@ export class LastMileService {
   }
 
   async update(id: string, dto: UpdateLastMileDto): Promise<LastMile> {
-    await this.findById(id);
+    const existing = await this.findById(id);
 
     const updated = await this.lastMileRepository.update(id, {
       ...(dto.bookingId !== undefined ? { bookingId: dto.bookingId } : {}),
@@ -132,9 +159,50 @@ export class LastMileService {
       throw new NotFoundException(`Last-mile record ${id} not found`);
     }
 
+    // Notify assigned driver on every explicit vehicle assignment or reassignment
+    if (dto.vehicleId) {
+      void this.notifyDriverAssignment(dto.vehicleId, existing);
+    }
+
     return updated;
   }
 
+  private async notifyDriverAssignment(vehicleId: string, record: LastMile): Promise<void> {
+    try {
+      const vehicle = await this.vehiclesService.findById(vehicleId);
+      if (!vehicle.assignedDriverId) {
+        this.logger.warn(`Vehicle ${vehicleId} has no assigned driver — skipping SMS`);
+        return;
+      }
+
+      const driver = await this.driversService.findById(vehicle.assignedDriverId);
+      if (!driver.phoneNumber) {
+        this.logger.warn(`Driver ${vehicle.assignedDriverId} has no phone number — skipping SMS`);
+        return;
+      }
+
+      type BookingWithYards = {
+        reference?: string;
+        lastMileDeliveryAddress?: string | null;
+        destinationYard?: { label?: string } | null;
+      };
+      const booking = (record as LastMile & { booking?: BookingWithYards }).booking;
+
+      await this.notificationsService.notifyDriverVehicleAssignment({
+        driverPhone: driver.phoneNumber,
+        driverName: `${driver.firstName ?? ''} ${driver.lastName ?? ''}`.trim(),
+        vehiclePlateNumber: vehicle.plateNumber ?? vehicleId,
+        bookingReference: booking?.reference ?? record.bookingId,
+        pickupAddress: booking?.destinationYard?.label,
+        destinationYard: booking?.lastMileDeliveryAddress,
+      });
+
+      this.logger.log(`SMS sent to driver ${driver.phoneNumber} for vehicle ${vehicleId} assignment`);
+    } catch (err) {
+      this.logger.error(`Failed to notify driver for vehicle ${vehicleId}: ${String(err)}`);
+    }
+  }
+
   async remove(id: string): Promise<void> {
     await this.findById(id);
     await this.lastMileRepository.softDelete(id);

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

@@ -1,14 +1,14 @@
 import { Module } from "@nestjs/common";
+import { ConfigModule } from "@nestjs/config";
 
 import { NotificationsService } from "./notifications.service";
 import { EmailNotificationStrategy } from "./strategies/notification.email.strategy";
 import { SmsNotificationStrategy } from "./strategies/notification.sms.strategy";
-import { HttpModule } from "@nestjs/axios";
 
 @Module({
-  imports: [HttpModule],
+  imports: [ConfigModule],
   controllers: [],
   providers: [EmailNotificationStrategy, SmsNotificationStrategy, NotificationsService],
   exports: [NotificationsService],
 })
-export class NotificationsModule { }
+export class NotificationsModule {}

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

@@ -27,9 +27,29 @@ export class NotificationsService {
     if (!strategy) {
       throw new NotFoundException();
     }
-    const sent = await strategy.send(recipient, message)
-    this.logger.log(`is sent - ${sent}`)
+    const sent = await strategy.send(recipient, message);
+    this.logger.log(`is sent - ${sent}`);
   }
 
+  async notifyDriverVehicleAssignment(params: {
+    driverPhone: string;
+    driverName: string;
+    vehiclePlateNumber: string;
+    bookingReference: string;
+    pickupAddress?: string | null;
+    destinationYard?: string | null;
+  }): Promise<void> {
+    const { driverPhone, driverName, vehiclePlateNumber, bookingReference, pickupAddress, destinationYard } = params;
+    const message =
+      `Dear ${driverName}, you have been assigned to a first-mile pickup. ` +
+      `Booking: ${bookingReference}. Vehicle: ${vehiclePlateNumber}. ` +
+      (pickupAddress ? `Pickup: ${pickupAddress}. ` : '') +
+      (destinationYard ? `Destination: ${destinationYard}.` : '');
 
+    try {
+      await this.directSend('sms', driverPhone, message);
+    } catch (err) {
+      this.logger.error(`Failed to notify driver ${driverName} (${driverPhone}): ${String(err)}`);
+    }
+  }
 }

apps/edr-freight-api/src/modules/notifications/strategies/notification.sms.strategy.ts

@@ -1,25 +1,36 @@
-import { Injectable} from "@nestjs/common";
-import { NotificationStrategy } from "./notification.strategy";
-import { HttpService } from '@nestjs/axios';
+import { Injectable } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
-import {  firstValueFrom } from 'rxjs';
+import axios from "axios";
+
+import { NotificationStrategy } from "./notification.strategy";
 
 @Injectable()
 export class SmsNotificationStrategy implements NotificationStrategy {
-    constructor(private readonly httpService: HttpService, private readonly configService: ConfigService) { }
-    async send(recipient: string, message: string) {
-        const url = this.configService.get("OZIKING_SMS_URL")
-        const body = {
-            to: recipient,
-            text: message
-        }
-        const response = await firstValueFrom(
-            this.httpService.post(
-                url,
-                body,
-            ),
-        );
+  constructor(private readonly configService: ConfigService) {}
 
-        return response.status === 201;
-    }
+  async send(recipient: string, message: string): Promise<boolean> {
+    const url =
+      this.configService.get<string>("OZIKING_SMS_URL") ??
+      "https://notification-dev.license.aafda.gov.et/api/sms-services/ozeking/sms";
+
+    await axios.post(
+      url,
+      {
+        to: recipient,
+        sourceId: this.configService.get<string>("OZIKING_SOURCE_ID") ?? "EDR",
+        sourceName: this.configService.get<string>("OZIKING_SOURCE_NAME") ?? "EDR Freight",
+        appKey: this.configService.get<string>("OZIKING_APP_KEY") ?? "",
+        text: message,
+        callbackUrl: "",
+      },
+      {
+        headers: {
+          accept: "*/*",
+          "Content-Type": "application/json",
+        },
+      },
+    );
+
+    return true;
+  }
 }

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

@@ -24,13 +24,9 @@ export class OtpController {
   @Post("send")
   async sendOtp(
     @Body("phone")
-    phone: string,
-     @Body("otp")
-    otp: string
+    phone: string
   ) {
-    return this.otpService.sendOtp(
-      phone,otp
-    );
+    return this.otpService.sendOtp(phone);
   }
 
   // ---------------------------------------------------------------------------

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

@@ -29,11 +29,12 @@ export class OtpService {
   // Send OTP
   // ---------------------------------------------------------------------------
 
-  async sendOtp(phone: string, otp: string) {
+  async sendOtp(phone: string) {
     try {
-      // generate otp
-      // const otp =
-      //   this.generateOtp();
+      // The verification code is generated server-side — never supplied by the
+      // caller — so the OTP stays a secret known only to the server and the
+      // recipient of the SMS.
+      const otp = this.generateOtp();
 
       // find existing phone
       const existingPhone =

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

@@ -64,4 +64,4 @@ const FREIGHT_QUEUE = PAYMENT_QUEUES[PaymentServiceEnum.FREIGHT];
     controllers: [PaymentController, InternalPaymentController],
     exports: [PaymentService],
 })
-export class PaymentModule { }
+export class PaymentModule { }

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

@@ -436,7 +436,7 @@ export class TrainSchedulingController {
     return this.trainSchedulingService.cancelTrainSchedule(id);
   }
 
-  @Post("bulk/schedules/:id/cancel")
+  @Post('bulk/schedules/:id/cancel')
   @TrainSchedulingManage()
   @ApiOperation({ summary: "Cancel bulk train schedule" })
   cancelBulkTrainSchedule(@Param("id", ParseUUIDPipe) id: string) {

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

@@ -1,4 +1,4 @@
-import {
+import {
   AllocationLoadType,
   SchedulingStatus,
   TrainCheckpointKind,
@@ -1005,12 +1005,29 @@ export class TrainSchedulingService {
         });
       }
 
-      const arrivingLocoIds = this.locomotivesOfTrainSet(schedule.trainSet).map((l) => l.id);
-      if (arrivingLocoIds.length) {
-        await manager.getRepository(Locomotive).update(
-          { id: In(arrivingLocoIds) },
-          { status: 'AVAILABLE', currentYardId: schedule.destinationStationId },
-        );
+      await manager.query(
+        `UPDATE freight.bookings b
+            SET status = $2,
+                scheduling_status = $3
+           FROM freight.train_schedule_bookings tsb
+          WHERE tsb.booking_id = b.id
+            AND tsb.train_schedule_id = $1
+            AND tsb.deleted_at IS NULL
+            AND b.deleted_at IS NULL
+            AND b.status NOT IN ('DRAFT', 'REJECTED', 'CANCELLED', 'COMPLETED')`,
+        [scheduleId, 'IN_TRANSIT', SchedulingStatus.Dispatched],
+      );
+
+      if (schedule.trainSet?.locomotiveId) {
+        const loco = await manager
+          .getRepository(Locomotive)
+          .findOne({ where: { id: schedule.trainSet.locomotiveId } });
+        if (loco) {
+          await manager.getRepository(Locomotive).update(loco.id, {
+            status: 'AVAILABLE',
+            currentYardId: schedule.destinationStationId,
+          });
+        }
       }
 
       for (const slot of schedule.trainSet?.wagons ?? []) {

apps/edr-freight-api/src/modules/vehicles/dto/create-vehicle.dto.ts

@@ -37,4 +37,16 @@ export class CreateVehicleDto {
   @IsOptional()
   @IsString()
   assignedDriverName?: string;
+
+  @IsOptional()
+  @IsString()
+  code?: string;
+
+  @IsOptional()
+  @IsString()
+  powerPlateNo?: string;
+
+  @IsOptional()
+  @IsString()
+  trailerPlateNo?: string;
 }

apps/edr-freight-api/src/modules/vehicles/entities/vehicle.entity.ts

@@ -62,4 +62,13 @@ export class Vehicle extends BaseEntity {
 
   @Column({ name: 'assigned_driver_name', nullable: true })
   assignedDriverName?: string;
+
+  @Column({ name: 'code', nullable: true })
+  code?: string;
+
+  @Column({ name: 'power_plate_no', nullable: true })
+  powerPlateNo?: string;
+
+  @Column({ name: 'trailer_plate_no', nullable: true })
+  trailerPlateNo?: string;
 }

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

@@ -67,13 +67,12 @@ export class VehiclesRepository extends BaseRepository<Vehicle> {
     };
   }
 
-  async createVehicle(vehicleData: any): Promise<Vehicle> {
+  async createVehicle(vehicleData: Partial<Vehicle>): Promise<Vehicle> {
     const vehicle = this.repository.create(vehicleData);
-    const vehicles = await this.repository.save(vehicle);
-    return vehicles?.[0] as Vehicle;
+    return this.repository.save(vehicle);
   }
 
   async updateVehicle(vehicle: Vehicle): Promise<Vehicle> {
-    return (await this.repository.save(vehicle)) as Vehicle;
+    return this.repository.save(vehicle);
   }
 }

apps/edr-freight-api/src/modules/wagons/entities/wagon.entity.ts

@@ -11,6 +11,8 @@ import { Yard } from '../../rule-engine/entities/yard.entity';
 export const WAGON_STATUSES = [
   WagonStatus.Available,
   WagonStatus.Assigned,
+  WagonStatus.ImportReady,
+  WagonStatus.ExportReady,
   WagonStatus.Maintenance,
   WagonStatus.Retired,
 ] as const;
@@ -65,7 +67,7 @@ export class Wagon extends BaseEntity {
   @JoinColumn({ name: 'current_train_schedule_id' })
   currentTrainSchedule?: TrainSchedule | null;
 
-  /** Fleet master consist grouping — separate from operational train_schedules. */
+  /** Fleet master consist grouping — separate from operational train_schedules. */
   @ManyToOne(() => Train, (train) => train.wagons, { onDelete: 'SET NULL' })
   @JoinColumn({ name: 'train_id' })
   train!: Train | null;

apps/edr-freight-api/src/modules/warehouses/dto/filter-inventory.dto.ts

@@ -12,6 +12,11 @@ export class FilterWarehouseInventoryDto {
   @IsUUID()
   warehouseId?: string;
 
+  @ApiPropertyOptional({ format: 'uuid' })
+  @IsOptional()
+  @IsUUID()
+  facilityId?: string;
+
   @ApiPropertyOptional({ format: 'uuid' })
   @IsOptional()
   @IsUUID()
@@ -51,4 +56,14 @@ export class FilterWarehouseInventoryDto {
   @IsOptional()
   @IsString()
   search?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  dateFrom?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  dateTo?: string;
 }

apps/edr-freight-api/src/modules/warehouses/dto/inquiry-inventory.dto.ts

@@ -10,6 +10,11 @@ export class InquiryWarehouseInventoryDto {
   @ApiPropertyOptional()
   @IsOptional()
   @IsString()
+  bookingReference?: string;
+
+  @ApiPropertyOptional({ description: 'Legacy alias for bookingReference' })
+  @IsOptional()
+  @IsString()
   bookingNumber?: string;
 
   @ApiPropertyOptional()

apps/edr-freight-api/src/modules/warehouses/warehouse-allocation.service.ts

@@ -78,17 +78,13 @@ export class WarehouseAllocationService {
   /** Resolve a concrete warehouse/yard/zone for the given criteria, or null if none configured. */
   async resolveLocation(criteria: AllocationCriteria): Promise<AllocationResult | null> {
     const rule = await this.findMatchingRule(criteria);
-    const yardCode = rule?.targetYardCode;
+    if (!rule) return null;
 
-    // Resolve yard (by rule code, else first available yard with a zone).
+    // Resolve yard by rule code.
     const [yard] = await this.dataSource.query(
-      yardCode
-        ? `SELECT y.id, y.warehouse_id AS "warehouseId", y.name FROM freight.warehouse_yards y
-             WHERE y.code = $1 AND y.deleted_at IS NULL LIMIT 1`
-        : `SELECT y.id, y.warehouse_id AS "warehouseId", y.name FROM freight.warehouse_yards y
-             JOIN freight.warehouse_zones z ON z.yard_id = y.id AND z.deleted_at IS NULL
-             WHERE y.deleted_at IS NULL ORDER BY y.created_at ASC LIMIT 1`,
-      yardCode ? [yardCode] : [],
+      `SELECT y.id, y.warehouse_id AS "warehouseId", y.name FROM freight.warehouse_yards y
+        WHERE y.code = $1 AND y.deleted_at IS NULL LIMIT 1`,
+      [rule.targetYardCode],
     );
     if (!yard) return null;
 

apps/edr-freight-api/src/modules/warehouses/warehouse-dashboard.service.ts

@@ -1,5 +1,5 @@
 import { Injectable } from '@nestjs/common';
-import { DataSource, IsNull } from 'typeorm';
+import { DataSource, FindManyOptions, IsNull, ObjectLiteral, Repository } from 'typeorm';
 
 import { Warehouse } from './entities/warehouse.entity';
 import { WarehouseInventory } from './entities/warehouse-inventory.entity';
@@ -26,6 +26,29 @@ export interface WarehouseDashboard {
 export class WarehouseDashboardService {
   constructor(private readonly dataSource: DataSource) {}
 
+  private async safeCount<T extends ObjectLiteral>(
+    repo: Repository<T>,
+    options?: FindManyOptions<T>,
+  ): Promise<number> {
+    try {
+      return await repo.count(options);
+    } catch {
+      return 0;
+    }
+  }
+
+  private async safeReceivedToday(startOfToday: Date): Promise<number> {
+    try {
+      return await this.dataSource
+        .getRepository(WarehouseInventory)
+        .createQueryBuilder('inv')
+        .where('inv.arrived_at >= :start', { start: startOfToday })
+        .getCount();
+    } catch {
+      return 0;
+    }
+  }
+
   async getDashboard(): Promise<WarehouseDashboard> {
     const warehouseRepo = this.dataSource.getRepository(Warehouse);
     const inventoryRepo = this.dataSource.getRepository(WarehouseInventory);
@@ -47,21 +70,18 @@ export class WarehouseDashboardService {
       delivered,
       receivedToday,
     ] = await Promise.all([
-      warehouseRepo.count(),
-      inventoryRepo.count(),
-      inventoryRepo.count({ where: { status: 'RECEIVED', inspectionStatus: IsNull() } }),
-      inventoryRepo.count({ where: { inspectionStatus: 'PASSED' } }),
-      inventoryRepo.count({ where: { status: 'STORED' } }),
-      inventoryRepo.count({ where: { status: 'RESERVED' } }),
-      inventoryRepo.count({ where: { status: 'READY_FOR_LOADING' } }),
-      inventoryRepo.count({ where: { status: 'LOADED' } }),
-      inventoryRepo.count({ where: { status: 'DISPATCHED' } }),
-      inventoryRepo.count({ where: { status: 'READY_FOR_PICKUP' } }),
-      inventoryRepo.count({ where: { status: 'DELIVERED' } }),
-      inventoryRepo
-        .createQueryBuilder('inv')
-        .where('inv.arrived_at >= :start', { start: startOfToday })
-        .getCount(),
+      this.safeCount(warehouseRepo),
+      this.safeCount(inventoryRepo),
+      this.safeCount(inventoryRepo, { where: { status: 'RECEIVED', inspectionStatus: IsNull() } }),
+      this.safeCount(inventoryRepo, { where: { inspectionStatus: 'PASSED' } }),
+      this.safeCount(inventoryRepo, { where: { status: 'STORED' } }),
+      this.safeCount(inventoryRepo, { where: { status: 'RESERVED' } }),
+      this.safeCount(inventoryRepo, { where: { status: 'READY_FOR_LOADING' } }),
+      this.safeCount(inventoryRepo, { where: { status: 'LOADED' } }),
+      this.safeCount(inventoryRepo, { where: { status: 'DISPATCHED' } }),
+      this.safeCount(inventoryRepo, { where: { status: 'READY_FOR_PICKUP' } }),
+      this.safeCount(inventoryRepo, { where: { status: 'DELIVERED' } }),
+      this.safeReceivedToday(startOfToday),
     ]);
 
     return {

apps/edr-freight-api/src/modules/warehouses/warehouse-fee.service.ts

@@ -13,6 +13,8 @@ interface ItemAttributes {
   tradeDirection: string | null;
   cargoTypeCode: string | null;
   containerTypeCode: string | null;
+  inventoryQuantity: number;
+  bookingContainerCount: number;
   facilityId: string | null;
   warehouseId: string | null;
   yardId: string | null;
@@ -31,6 +33,8 @@ export interface FeePreview {
   endIsOpen: boolean; // true when still accruing (no release/gate-clear yet)
   elapsedDays: number;
   chargeableDays: number;
+  containerCount: number;
+  billableUnits: number;
   amount: number;
 }
 
@@ -67,6 +71,7 @@ export class WarehouseFeeService {
       `SELECT inv.arrived_at        AS "arrivedAt",
               inv.gate_cleared_at   AS "gateClearedAt",
               inv.release_date      AS "releaseDate",
+              inv.quantity          AS "inventoryQuantity",
               inv.warehouse_id      AS "warehouseId",
               inv.yard_id           AS "yardId",
               inv.zone_id           AS "zoneId",
@@ -74,7 +79,8 @@ export class WarehouseFeeService {
               b.freight_type        AS "freightType",
               b.trade_direction     AS "tradeDirection",
               cgt.code              AS "cargoTypeCode",
-              ctt.code              AS "containerTypeCode"
+              ctt.code              AS "containerTypeCode",
+              COALESCE(container_lines.container_count, 0) AS "bookingContainerCount"
          FROM freight.warehouse_inventory inv
          LEFT JOIN freight.warehouses w ON w.id = inv.warehouse_id
          LEFT JOIN freight.bookings b ON b.id = inv.booking_id
@@ -82,6 +88,12 @@ export class WarehouseFeeService {
          LEFT JOIN freight.cargo_types cgt ON cgt.id = cg.cargo_type_id
          LEFT JOIN freight.containers ct ON ct.id = inv.container_id
          LEFT JOIN freight.container_types ctt ON ctt.id = ct.container_type_id
+         LEFT JOIN LATERAL (
+           SELECT COALESCE(SUM(bc.quantity), 0)::int AS container_count
+             FROM freight.booking_container bc
+            WHERE bc.booking_id = inv.booking_id
+              AND bc.deleted_at IS NULL
+         ) container_lines ON true
         WHERE inv.id = $1 AND inv.deleted_at IS NULL`,
       [inventoryId],
     );
@@ -131,12 +143,18 @@ export class WarehouseFeeService {
     const endIsOpen = !item.gateClearedAt && !item.releaseDate;
     const freeDays = rule?.freeDays ?? 0;
     const ratePerDay = Number(rule?.ratePerDay ?? 0);
+    const isContainer = (item.freightType ?? '').toUpperCase() === 'CONTAINER';
+    const inventoryQuantity = Math.max(1, Math.round(Number(item.inventoryQuantity) || 1));
+    const containerCount = isContainer
+      ? Math.max(1, Math.round(Number(item.bookingContainerCount) || inventoryQuantity))
+      : 1;
 
     const elapsedDays = start
       ? Math.max(0, Math.ceil((new Date(endDate).getTime() - start.getTime()) / MS_PER_DAY))
       : 0;
     const chargeableDays = Math.max(0, elapsedDays - freeDays);
-    const amount = Math.round(chargeableDays * ratePerDay * 100) / 100;
+    const billableUnits = chargeableDays * containerCount;
+    const amount = Math.round(billableUnits * ratePerDay * 100) / 100;
 
     return {
       ruleType,
@@ -150,6 +168,8 @@ export class WarehouseFeeService {
       endIsOpen,
       elapsedDays,
       chargeableDays,
+      containerCount,
+      billableUnits,
       amount,
     };
   }

apps/edr-freight-api/src/modules/warehouses/warehouse-inspection.service.ts

@@ -18,7 +18,7 @@ export class WarehouseInspectionService {
     private readonly filesService: FilesService,
   ) {}
 
-  /** Create an inspection report for an inventory item and sync its inspectionStatus. */
+  /** Create or update the inspection report for an inventory item and sync its inspectionStatus. */
   async create(inventoryId: string, dto: CreateInspectionReportDto): Promise<WarehouseInspectionReport> {
     const inventoryRepo = this.dataSource.getRepository(WarehouseInventory);
     const inventory = await inventoryRepo.findOne({ where: { id: inventoryId } });
@@ -29,8 +29,9 @@ export class WarehouseInspectionService {
     const expected = dto.expectedWeight ?? null;
     const actual = dto.actualWeight ?? null;
     const weightLoss = expected !== null && actual !== null ? Math.max(0, expected - actual) : null;
+    const inspectedAt = new Date();
 
-    const report = await this.inspectionRepository.create({
+    const payload = {
       inventoryId,
       bookingId: inventory.bookingId ?? null,
       reportType: dto.reportType,
@@ -46,13 +47,27 @@ export class WarehouseInspectionService {
       missingItemsDescription: dto.missingItemsDescription ?? null,
       remarks: dto.remarks ?? null,
       inspectedById: dto.inspectedById ?? null,
-      inspectedAt: new Date(),
+      inspectedAt,
+    };
+
+    const [existingReport] = await this.inspectionRepository.findAll({
+      where: { inventoryId },
+      order: { createdAt: 'DESC' },
+      take: 1,
     });
 
+    let report: WarehouseInspectionReport;
+    if (existingReport) {
+      await this.inspectionRepository.update(existingReport.id, payload);
+      report = await this.findById(existingReport.id);
+    } else {
+      report = await this.inspectionRepository.create(payload);
+    }
+
     // Mirror the latest outcome onto the inventory item so loading rules can read it.
     await inventoryRepo.update(inventoryId, {
       inspectionStatus: dto.inspectionStatus,
-      inspectedAt: new Date(),
+      inspectedAt,
     });
 
     return report;

apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts

@@ -1,5 +1,6 @@
-import { Body, Controller, Get, Param, ParseUUIDPipe, Patch, Post, Query } from '@nestjs/common';
+import { Body, Controller, Get, Param, ParseUUIDPipe, Patch, Post, Query, Res } from '@nestjs/common';
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import type { Response } from 'express';
 
 import { BulkReceiveDto } from './dto/bulk-receive.dto';
 import { BulkInspectDto } from './dto/bulk-inspect.dto';
@@ -226,6 +227,16 @@ export class WarehouseInventoryController {
     return this.inventoryService.release(id, dto);
   }
 
+  @Get(':id/release-document')
+  @ApiOperation({ summary: 'View warehouse release / exit paper PDF' })
+  async releaseDocument(@Param('id', ParseUUIDPipe) id: string, @Res() res: Response) {
+    const { filename, buffer } = await this.inventoryService.releaseDocument(id);
+    res.setHeader('Content-Type', 'application/pdf');
+    res.setHeader('Content-Disposition', `inline; filename="${filename}"`);
+    res.setHeader('Content-Length', buffer.length);
+    return res.send(buffer);
+  }
+
   @Post(':id/deliver')
   @ApiOperation({ summary: 'Deliver import goods to the customer + capture proof of delivery' })
   deliver(@Param('id', ParseUUIDPipe) id: string, @Body() dto: DeliverInventoryDto) {

apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts

@@ -75,9 +75,9 @@ export class WarehouseInvoiceService {
           feeType,
           description:
             p.ruleType === 'STORAGE_FEE'
-              ? `Storage fee — ${p.chargeableDays} chargeable day(s) after ${p.freeDays} free`
-              : `${isContainer ? 'Container' : 'Bulk'} demurrage — ${p.chargeableDays} chargeable day(s) after ${p.freeDays} free`,
-          quantity: p.chargeableDays,
+              ? `Storage fee - ${p.chargeableDays} chargeable day(s) x ${p.containerCount} container(s) after ${p.freeDays} free`
+              : `${isContainer ? 'Container' : 'Bulk'} demurrage - ${p.chargeableDays} chargeable day(s) x ${p.containerCount} container(s) after ${p.freeDays} free`,
+          quantity: p.billableUnits,
           unitRate: p.ratePerDay,
           amount: p.amount,
           currency: p.currency,

apps/edr-freight-api/src/modules/warehouses/warehouse-yards.controller.ts

@@ -15,6 +15,12 @@ export class WarehouseYardsController {
     private readonly zonesService: WarehouseZonesService,
   ) {}
 
+  @Get()
+  @ApiOperation({ summary: 'List all warehouse yards' })
+  findAll() {
+    return this.yardsService.findAll();
+  }
+
   @Get(':id')
   @ApiOperation({ summary: 'Get warehouse yard by ID' })
   findOne(@Param('id', ParseUUIDPipe) id: string) {

apps/edr-freight-api/src/modules/warehouses/warehouse-yards.service.ts

@@ -13,6 +13,13 @@ export class WarehouseYardsService {
     private readonly warehousesService: WarehousesService,
   ) {}
 
+  findAll(): Promise<WarehouseYard[]> {
+    return this.yardsRepository.findAll({
+      relations: { warehouse: true, zones: true },
+      order: { code: 'ASC' },
+    });
+  }
+
   findByWarehouse(warehouseId: string): Promise<WarehouseYard[]> {
     return this.yardsRepository.findAll({
       where: { warehouseId },

apps/edr-freight-api/src/modules/warehouses/warehouse-zones.controller.ts

@@ -10,6 +10,12 @@ import { WarehouseZonesService } from './warehouse-zones.service';
 export class WarehouseZonesController {
   constructor(private readonly zonesService: WarehouseZonesService) {}
 
+  @Get()
+  @ApiOperation({ summary: 'List all warehouse zones' })
+  findAll() {
+    return this.zonesService.findAll();
+  }
+
   @Get(':id')
   @ApiOperation({ summary: 'Get warehouse zone by ID' })
   findOne(@Param('id', ParseUUIDPipe) id: string) {

apps/edr-freight-api/src/modules/warehouses/warehouse-zones.service.ts

@@ -13,6 +13,13 @@ export class WarehouseZonesService {
     private readonly yardsService: WarehouseYardsService,
   ) {}
 
+  findAll(): Promise<WarehouseZone[]> {
+    return this.zonesRepository.findAll({
+      relations: { yard: { warehouse: true } },
+      order: { code: 'ASC' },
+    });
+  }
+
   findByYard(yardId: string): Promise<WarehouseZone[]> {
     return this.zonesRepository.findAll({
       where: { yardId },

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

@@ -1,6 +1,7 @@
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
+import { ContractPdfService } from '../../contracts/contract-pdf.service';
 import { FilesModule } from '../files/files.module';
 import { WarehouseActivityLog } from './entities/warehouse-activity-log.entity';
 import { WarehouseAllocationRule } from './entities/warehouse-allocation-rule.entity';
@@ -100,6 +101,7 @@ import { WarehousesService } from './warehouses.service';
     WarehouseInvoiceService,
     WarehouseSchedulingAdapterService,
     SchedulingReadFacade,
+    ContractPdfService,
   ],
   exports: [
     WarehousesService,