feat: centralized the user onboaridn requriements

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

@@ -40,6 +40,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";
@@ -221,6 +222,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,13 +3,17 @@ import {
   NotFoundException,
   ConflictException,
   BadRequestException,
+  ForbiddenException,
 } from "@nestjs/common";
 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 { 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";
@@ -50,9 +54,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) {
@@ -624,6 +686,17 @@ export class CompaniesService {
     );
     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;
   }
 
@@ -809,6 +882,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 }> {
@@ -817,23 +984,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);
       }
     }
 
@@ -842,11 +1007,30 @@ export class CompaniesService {
       onboardingStep: "done",
     });
     await this.companiesRepo.update(companyId, {
-      status: CompanyStatus.Active,
+      status: CompanyStatus.Pending,
     });
     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/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;
+  }
+}