mirror of
https://github.com/Tria-plc/edr-platform.git
synced 2026-08-30 06:28:12 +00:00
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.
This commit is contained in:
marshal
@@ -0,0 +1,333 @@
|
||||
import { BadRequestException, Injectable } from '@nestjs/common';
|
||||
import { ContractDocPhase } from '@edr/types';
|
||||
|
||||
import { ContractsRepository } from './contracts.repository';
|
||||
import { ClearanceMilestoneService } from './clearance-milestone.service';
|
||||
import { MilestoneMetadata } from './entities/clearance-milestone.entity';
|
||||
import { splitMilestones } from './clearance-milestone.catalog';
|
||||
import { Contract } from './entities/contract.entity';
|
||||
import { ContractClearanceCycle } from './entities/contract-clearance-cycle.entity';
|
||||
import { ClearanceMilestone } from './entities/clearance-milestone.entity';
|
||||
|
||||
export type ClearanceActorRole = 'CUSTOMER' | 'GL_ET' | 'GL_DJ' | 'OPERATIONS';
|
||||
|
||||
export interface ClearanceNextAction {
|
||||
actor: ClearanceActorRole;
|
||||
action: string;
|
||||
milestoneCode?: string | null;
|
||||
blockedReason?: string | null;
|
||||
}
|
||||
|
||||
const IMPORT_BOUNDARY = 'DO_COLLECTED';
|
||||
const EXPORT_BOUNDARY = 'EXPORT_RELEASED';
|
||||
|
||||
const IMPORT_DOC_UPLOADED = 'IMPORT_DOCS_UPLOADED';
|
||||
const EXPORT_DOC_UPLOADED = 'EXPORT_DOCS_UPLOADED';
|
||||
|
||||
@Injectable()
|
||||
export class ClearanceWorkflowService {
|
||||
constructor(
|
||||
private readonly contractsRepository: ContractsRepository,
|
||||
private readonly milestoneService: ClearanceMilestoneService,
|
||||
) {}
|
||||
|
||||
boundaryMilestone(tradeDirection: string): string {
|
||||
return tradeDirection === 'IMPORT' ? IMPORT_BOUNDARY : EXPORT_BOUNDARY;
|
||||
}
|
||||
|
||||
async listMilestones(contractId: string): Promise<ClearanceMilestone[]> {
|
||||
return this.milestoneService.listForContract(contractId);
|
||||
}
|
||||
|
||||
async isBoundaryComplete(contractId: string, tradeDirection: string): Promise<boolean> {
|
||||
const code = this.boundaryMilestone(tradeDirection);
|
||||
const milestones = await this.listMilestones(contractId);
|
||||
const m = milestones.find((x) => x.milestoneCode === code);
|
||||
return m?.status === 'COMPLETED';
|
||||
}
|
||||
|
||||
async assertBoundaryComplete(contract: Contract): Promise<void> {
|
||||
const ok = await this.isBoundaryComplete(contract.id, contract.tradeDirection);
|
||||
if (!ok) {
|
||||
throw new BadRequestException(
|
||||
`Pre-booking clearance is not complete — ${this.boundaryMilestone(contract.tradeDirection)} must be finished before booking.`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
async assertPriorComplete(
|
||||
contractId: string,
|
||||
tradeDirection: string,
|
||||
targetCode: string,
|
||||
): Promise<void> {
|
||||
const { preBooking } = splitMilestones(tradeDirection);
|
||||
const milestones = await this.listMilestones(contractId);
|
||||
const byCode = new Map(milestones.map((m) => [m.milestoneCode, m]));
|
||||
const targetIdx = preBooking.findIndex((d) => d.code === targetCode);
|
||||
if (targetIdx < 0) return;
|
||||
|
||||
for (let i = 0; i < targetIdx; i++) {
|
||||
const code = preBooking[i]!.code;
|
||||
const m = byCode.get(code);
|
||||
if (!m) continue;
|
||||
if (m.status === 'SKIPPED') continue;
|
||||
if (m.status !== 'COMPLETED') {
|
||||
throw new BadRequestException(
|
||||
`Complete "${preBooking[i]!.label}" before proceeding.`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async skipMilestones(contractId: string, codes: string[]): Promise<void> {
|
||||
for (const code of codes) {
|
||||
await this.milestoneService.skipForContract(contractId, code);
|
||||
}
|
||||
}
|
||||
|
||||
async completeMilestone(
|
||||
contractId: string,
|
||||
code: string,
|
||||
userId?: string,
|
||||
metadata?: MilestoneMetadata,
|
||||
): Promise<ClearanceMilestone> {
|
||||
if (metadata && Object.keys(metadata).length > 0) {
|
||||
return this.milestoneService.completeWithMetadataForContract(
|
||||
contractId,
|
||||
code,
|
||||
metadata,
|
||||
userId,
|
||||
);
|
||||
}
|
||||
return this.milestoneService.completeForContract(contractId, code, userId);
|
||||
}
|
||||
|
||||
async onCustomerDocsUploaded(contractId: string, tradeDirection: string): Promise<void> {
|
||||
const uploaded =
|
||||
tradeDirection === 'IMPORT' ? IMPORT_DOC_UPLOADED : EXPORT_DOC_UPLOADED;
|
||||
await this.completeMilestone(contractId, uploaded);
|
||||
await this.completeMilestone(contractId, 'PENDING_DOCUMENT_REVIEW');
|
||||
}
|
||||
|
||||
async onAllDocsApproved(contractId: string): Promise<void> {
|
||||
await this.completeMilestone(contractId, 'DOCUMENTS_APPROVED');
|
||||
}
|
||||
|
||||
async onDeclarationUploaded(contractId: string, userId?: string): Promise<void> {
|
||||
await this.completeMilestone(contractId, 'UNDER_CUSTOMS_CLEARANCE');
|
||||
await this.completeMilestone(contractId, 'DECLARED', userId);
|
||||
}
|
||||
|
||||
async onDutySkipped(contractId: string): Promise<void> {
|
||||
await this.skipMilestones(contractId, ['DUTY_TAXES_ADVISED', 'DUTY_TAX_PAID']);
|
||||
}
|
||||
|
||||
async onExportReleased(contractId: string, userId?: string): Promise<void> {
|
||||
await this.completeMilestone(contractId, 'EXPORT_RELEASED', userId);
|
||||
await this.markReadyForBooking(contractId);
|
||||
}
|
||||
|
||||
async markReadyForBooking(contractId: string): Promise<void> {
|
||||
const cycle = await this.contractsRepository.currentCycle(contractId);
|
||||
await this.contractsRepository.update(contractId, {
|
||||
status: 'CLEARANCE_READY_FOR_BOOKING',
|
||||
clearanceStatus: 'CLEARANCE_READY_FOR_BOOKING',
|
||||
} as never);
|
||||
if (cycle) {
|
||||
await this.contractsRepository.setCycleStatus(cycle.id, 'CLEARANCE_READY_FOR_BOOKING', {
|
||||
clearanceReadyAt: new Date(),
|
||||
currentPhase: ContractDocPhase.GlEtPostClearance,
|
||||
});
|
||||
await this.contractsRepository.updateCycle(cycle.id, {
|
||||
currentPhase: ContractDocPhase.GlEtPostClearance,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
resolvePhase(
|
||||
contract: Contract,
|
||||
cycle: ContractClearanceCycle | null,
|
||||
milestones: ClearanceMilestone[],
|
||||
): ContractDocPhase {
|
||||
if (cycle?.currentPhase) {
|
||||
return cycle.currentPhase as ContractDocPhase;
|
||||
}
|
||||
return this.inferPhase(contract, cycle, milestones);
|
||||
}
|
||||
|
||||
inferPhase(
|
||||
contract: Contract,
|
||||
cycle: ContractClearanceCycle | null,
|
||||
milestones: ClearanceMilestone[],
|
||||
): ContractDocPhase {
|
||||
const byCode = new Map(milestones.map((m) => [m.milestoneCode, m]));
|
||||
const isDone = (code: string) =>
|
||||
byCode.get(code)?.status === 'COMPLETED' || byCode.get(code)?.status === 'SKIPPED';
|
||||
|
||||
const docUploaded =
|
||||
contract.tradeDirection === 'IMPORT'
|
||||
? isDone(IMPORT_DOC_UPLOADED)
|
||||
: isDone(EXPORT_DOC_UPLOADED);
|
||||
|
||||
if (!docUploaded) return ContractDocPhase.CustomerIntake;
|
||||
if (!isDone('DOCUMENTS_APPROVED')) return ContractDocPhase.GlEtReview;
|
||||
|
||||
if (contract.tradeDirection === 'EXPORT') {
|
||||
if (!isDone('RELEASE_ORDER_SECURED')) {
|
||||
if (cycle?.roHoldReason) return ContractDocPhase.GlDjCollection;
|
||||
return ContractDocPhase.GlDjCollection;
|
||||
}
|
||||
if (!isDone('DECLARED')) return ContractDocPhase.GlEtOutput;
|
||||
if (!isDone(EXPORT_BOUNDARY)) return ContractDocPhase.GlEtPostClearance;
|
||||
return ContractDocPhase.GlEtPostClearance;
|
||||
}
|
||||
|
||||
// Import
|
||||
if (!isDone('DECLARED')) return ContractDocPhase.GlEtOutput;
|
||||
if (cycle?.dutyRequired === true && !isDone('DUTY_TAX_PAID')) {
|
||||
return ContractDocPhase.CustomerDuty;
|
||||
}
|
||||
if (!isDone('TRANSIT_PERMIT_UPLOADED')) return ContractDocPhase.GlEtPostClearance;
|
||||
if (!isDone(IMPORT_BOUNDARY)) return ContractDocPhase.GlDjCollection;
|
||||
return ContractDocPhase.GlEtPostClearance;
|
||||
}
|
||||
|
||||
computeNextAction(
|
||||
contract: Contract,
|
||||
cycle: ContractClearanceCycle | null,
|
||||
milestones: ClearanceMilestone[],
|
||||
): ClearanceNextAction | null {
|
||||
if (cycle?.roHoldReason) {
|
||||
return {
|
||||
actor: 'GL_DJ',
|
||||
action: 'Re-upload Release Order or request port amendment',
|
||||
milestoneCode: 'RELEASE_ORDER_SECURED',
|
||||
blockedReason: cycle.roHoldReason,
|
||||
};
|
||||
}
|
||||
|
||||
const byCode = new Map(milestones.map((m) => [m.milestoneCode, m]));
|
||||
const pending = (code: string) => {
|
||||
const m = byCode.get(code);
|
||||
return m && m.status === 'PENDING';
|
||||
};
|
||||
const isDone = (code: string) => {
|
||||
const m = byCode.get(code);
|
||||
return m?.status === 'COMPLETED' || m?.status === 'SKIPPED';
|
||||
};
|
||||
|
||||
const docCode =
|
||||
contract.tradeDirection === 'IMPORT' ? IMPORT_DOC_UPLOADED : EXPORT_DOC_UPLOADED;
|
||||
|
||||
if (pending(docCode) || !isDone(docCode)) {
|
||||
return {
|
||||
actor: 'CUSTOMER',
|
||||
action: 'Upload clearance documents',
|
||||
milestoneCode: docCode,
|
||||
};
|
||||
}
|
||||
|
||||
if (!isDone('DOCUMENTS_APPROVED')) {
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Review and approve customer documents',
|
||||
milestoneCode: 'DOCUMENTS_APPROVED',
|
||||
};
|
||||
}
|
||||
|
||||
if (contract.tradeDirection === 'EXPORT') {
|
||||
if (!isDone('RELEASE_ORDER_SECURED')) {
|
||||
return {
|
||||
actor: 'GL_DJ',
|
||||
action: 'Upload Release Order and vessel departure date',
|
||||
milestoneCode: 'RELEASE_ORDER_SECURED',
|
||||
};
|
||||
}
|
||||
if (!isDone('DECLARED')) {
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Upload customs declaration (EX3/EX8)',
|
||||
milestoneCode: 'DECLARED',
|
||||
};
|
||||
}
|
||||
if (!isDone(EXPORT_BOUNDARY)) {
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Confirm export release',
|
||||
milestoneCode: EXPORT_BOUNDARY,
|
||||
};
|
||||
}
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Create shipment booking',
|
||||
milestoneCode: EXPORT_BOUNDARY,
|
||||
};
|
||||
}
|
||||
|
||||
// Import
|
||||
if (!isDone('DECLARED')) {
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Upload customs declaration (IM4/IM5)',
|
||||
milestoneCode: 'DECLARED',
|
||||
};
|
||||
}
|
||||
|
||||
if (cycle?.dutyRequired === null || cycle?.dutyRequired === undefined) {
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Set whether duty/tax applies',
|
||||
milestoneCode: 'DUTY_TAXES_ADVISED',
|
||||
};
|
||||
}
|
||||
|
||||
if (cycle.dutyRequired && !isDone('DUTY_TAX_PAID')) {
|
||||
if (!isDone('DUTY_TAXES_ADVISED')) {
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Advise duty and tax amount',
|
||||
milestoneCode: 'DUTY_TAXES_ADVISED',
|
||||
};
|
||||
}
|
||||
return {
|
||||
actor: 'CUSTOMER',
|
||||
action: 'Upload duty/tax payment slip',
|
||||
milestoneCode: 'DUTY_TAX_PAID',
|
||||
};
|
||||
}
|
||||
|
||||
if (!isDone('TRANSIT_PERMIT_UPLOADED')) {
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Upload transit permit screenshot',
|
||||
milestoneCode: 'TRANSIT_PERMIT_UPLOADED',
|
||||
};
|
||||
}
|
||||
|
||||
if (!isDone(IMPORT_BOUNDARY)) {
|
||||
return {
|
||||
actor: 'GL_DJ',
|
||||
action: 'Upload Delivery Order',
|
||||
milestoneCode: IMPORT_BOUNDARY,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
actor: 'GL_ET',
|
||||
action: 'Create shipment booking',
|
||||
milestoneCode: IMPORT_BOUNDARY,
|
||||
};
|
||||
}
|
||||
|
||||
/** Contracts where the next pending milestone is owned by ET. */
|
||||
etPendingMilestoneCodes(milestones: ClearanceMilestone[]): string | null {
|
||||
const pending = milestones.find((m) => m.status === 'PENDING' && m.ownerRegion === 'ET');
|
||||
return pending?.milestoneCode ?? null;
|
||||
}
|
||||
|
||||
/** Contracts where the next pending milestone is owned by DJ. */
|
||||
djPendingMilestoneCodes(milestones: ClearanceMilestone[]): string | null {
|
||||
const pending = milestones.find((m) => m.status === 'PENDING' && m.ownerRegion === 'DJ');
|
||||
return pending?.milestoneCode ?? null;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user