Enhance clearance milestone management and introduce new contract actions

- Added new milestones for 'Transit Permit Uploaded' and 'Export Transport Document Issued' in the clearance milestone catalog.
- Implemented methods in ClearanceMilestoneService to skip milestones and complete them with metadata.
- Updated ContractBookingService to check boundary conditions before booking creation.
- Introduced new endpoints in ContractsController for uploading customs declarations, advising duty, and handling various document uploads.
- Enhanced the UI to support new clearance actions and display relevant components based on milestone statuses.

apps/edr-freight-api/src/modules/contracts/clearance-milestone.service.ts

@@ -187,6 +187,58 @@ export class ClearanceMilestoneService {
     return this.repo.save(milestone);
   }
 
+  /** Skip optional milestones (e.g. duty when not required). */
+  async skipForContract(contractId: string, code: string): Promise<ClearanceMilestone> {
+    const milestone = await this.repo.findOne({ where: { contractId, milestoneCode: code } });
+    if (!milestone) {
+      throw new NotFoundException(`Milestone ${code} not found for contract ${contractId}`);
+    }
+    if (milestone.status === 'COMPLETED') return milestone;
+    milestone.status = 'SKIPPED';
+    milestone.triggeredAt = new Date();
+    return this.repo.save(milestone);
+  }
+
+  /** Complete a contract milestone with structured metadata (duty advice, etc.). */
+  async completeWithMetadataForContract(
+    contractId: string,
+    code: string,
+    metadata: MilestoneMetadata,
+    userId?: string,
+    note?: string,
+  ): Promise<ClearanceMilestone> {
+    const milestone = await this.repo.findOne({ where: { contractId, milestoneCode: code } });
+    if (!milestone) {
+      throw new NotFoundException(`Milestone ${code} not found for contract ${contractId}`);
+    }
+    if (milestone.status === 'COMPLETED') {
+      throw new BadRequestException(`Milestone ${code} is already completed.`);
+    }
+    milestone.status = 'COMPLETED';
+    milestone.triggeredAt = new Date();
+    milestone.triggeredByUserId = userId ?? null;
+    milestone.metadata = { ...(milestone.metadata ?? {}), ...metadata };
+    if (note) milestone.note = note;
+    return this.repo.save(milestone);
+  }
+
+  async adviseDutyForContract(
+    contractId: string,
+    input: { amount: number; currency: string; declarationSerial?: string },
+    userId?: string,
+  ): Promise<ClearanceMilestone> {
+    return this.completeWithMetadataForContract(
+      contractId,
+      'DUTY_TAXES_ADVISED',
+      {
+        dutyAmount: input.amount,
+        dutyCurrency: input.currency,
+        declarationSerial: input.declarationSerial,
+      },
+      userId,
+    );
+  }
+
   /** Complete a doc-triggered milestone when its document is uploaded/approved. */
   async completeByDocTrigger(
     scope: { bookingId?: string; contractId?: string },