Tria/edr-platform
1
0
Fork 0
mirror of https://github.com/Tria-plc/edr-platform.git synced 2026-08-26 18:42:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(portal): show declaration, T1 and Djibouti clearance documents to the customer

Browse Source
This commit is contained in:
Marshal
2026-08-20 08:36:02 +00:00
parent ca774c536f
commit d7752f4386
12 changed files with 341 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
View File

@@ -47,6 +47,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
"POST /api/bookings/:id/clearance/proceed": ["Customer requests operation with a schedule day", "POST", "Booking"],
"POST /api/bookings/:id/clearance/release-order": ["Upload Booking Release Order", "POST", "Booking"],
"POST /api/bookings/:id/clearance/review": ["GL reviews a clearance document (Approve | Query)", "POST", "Booking"],
"POST /api/bookings/:id/clearance/doc-requests": ["GL asks the customer for additional clearance documents", "POST", "Booking"],
"POST /api/bookings/:id/clearance/charges/port-document": ["GL Djibouti uploads the port-charges document", "POST", "Booking"],
"PATCH /api/bookings/:id/clearance/charges/:chargeId/bill": ["GL Ethiopia sets or revises a clearance charge's amount + currency", "PATCH", "Booking"],
"POST /api/bookings/:id/clearance/charges/:chargeId/send": ["GL Ethiopia issues the clearance charge invoice to the customer", "POST", "Booking"],

11
apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
View File

@@ -202,6 +202,17 @@ export class BookingLifecycleNotifierService {
}
/** A clearance document was queried and needs the customer to re-upload. */
/** GL asked the customer for additional clearance document(s). */
additionalDocsRequested(b: Booking, note: string): void {
const msg =
`Additional document(s) requested on booking ${b.reference}: ` +
`${note} Please upload them from the portal.`;
void this.notifyContact(b, msg, 'ADDITIONAL DOCUMENTS REQUESTED');
this.inApp(b, 'Additional documents requested', msg, {
type: NotificationType.DOCUMENT_ACTION,
});
}
documentQueried(b: Booking, fileKey: string, note: string): void {
const msg =
`A clearance document on booking ${b.reference} needs attention: "${fileKey}". ` +

53
apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
View File

@@ -643,6 +643,12 @@ export class BookingTransitionService {
}>;
allApproved: boolean;
documentsOpen: boolean;
docRequests: Array<{
id: string;
note: string;
byName: string | null;
at: string;
}>;
phase?: string | null;
milestones?: unknown[];
nextAction?: unknown;
@@ -674,9 +680,14 @@ export class BookingTransitionService {
bookingId,
"CHANGES_REQUESTED",
);
const docRequestNotes = await this.bookingsRepository.findReviewNotes(
bookingId,
"ADDITIONAL_DOC_REQUEST",
);
const reviewerNames = await this.bookingsRepository.resolveStaffNames([
...reviews.map((r) => r.reviewedByStaffId),
...queryNotes.map((n) => n.authorId),
...docRequestNotes.map((n) => n.authorId),
]);
const documents: Awaited<
@@ -763,9 +774,51 @@ export class BookingTransitionService {
documents,
allApproved,
documentsOpen: clearanceDocumentsOpen(booking),
docRequests: docRequestNotes.map((n) => ({
id: n.id,
note: n.note,
byName: n.authorId ? (reviewerNames.get(n.authorId) ?? null) : null,
at: n.createdAt.toISOString(),
})),
};
}
/**
* GL asks the customer for additional clearance document(s). Stored as a
* review-note thread shown on both the GL clearance page and the customer's
* portal; the customer answers with an ad-hoc upload. Allowed for as long as
* documents are open (until the shipment is paid).
*/
async requestAdditionalDocuments(
bookingId: string,
note: string,
staffId: string,
): Promise<void> {
const booking = await this.bookingsService.findById(bookingId);
if (!clearanceDocumentsOpen(booking)) {
throw new ConflictException(
`Clearance documents are closed for this booking (status "${booking.status}").`,
);
}
if (!note?.trim()) {
throw new BadRequestException("Describe the document(s) you need.");
}
await this.bookingsRepository.createReviewNote(
bookingId,
note.trim(),
"ADDITIONAL_DOC_REQUEST",
staffId,
);
await this.clearanceEvents.record({
bookingId,
action: "ADDITIONAL_DOCS_REQUESTED",
label: "Requested additional document(s) from the customer",
actorId: staffId,
metadata: { note: note.trim() },
});
this.notifier.additionalDocsRequested(booking, note.trim());
}
/**
* True when every REQUIRED field of the booking's customer-input clearance set
* has an APPROVED review row. The 100% gate before clearance can be finalized.

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

@@ -1083,6 +1083,25 @@ export class BookingsController {
return this.transitionService.enrichBookingResponse(booking);
}
@Post(":id/clearance/doc-requests")
@BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
@ApiOperation({
summary:
"GL asks the customer for additional clearance document(s) — shown on the portal with author and time",
})
async requestAdditionalDocuments(
@Param("id", ParseUUIDPipe) id: string,
@Body("note") note: string,
@CurrentUser() user: AuthUserPayload,
) {
await this.transitionService.requestAdditionalDocuments(
id,
note,
resolveAuthUserId(user),
);
return { success: true };
}
@Get(":id/clearance/history")
@BookingStaff([
FREIGHT_PERMS.contracts.clearanceEtActions,

6
apps/edr-freight-api/src/modules/bookings/entities/booking-review-note.entity.ts
View File

@@ -11,6 +11,12 @@ export const REVIEW_NOTE_TYPES = [
* (price/files). One row per round — the draft/change-request loop can repeat.
*/
'DRAFT_DECL_CHANGE_REQUEST',
/**
* GL asked the customer for additional clearance document(s). Shown as a
* thread on both the GL clearance page and the customer's portal — the
* customer answers by uploading an ad-hoc document.
*/
'ADDITIONAL_DOC_REQUEST',
] as const;
export type ReviewNoteType = (typeof REVIEW_NOTE_TYPES)[number];

17
apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
View File

@@ -66,6 +66,12 @@ export interface BookingClearanceView {
}>;
allApproved: boolean;
documentsOpen: boolean;
docRequests: Array<{
id: string;
note: string;
byName: string | null;
at: string;
}>;
phase?: string | null;
milestones?: Array<{
id: string;
@@ -206,9 +212,14 @@ export class BookingClearanceService {
bookingId,
'CHANGES_REQUESTED',
);
const docRequestNotes = await this.bookingsRepository.findReviewNotes(
bookingId,
'ADDITIONAL_DOC_REQUEST',
);
const reviewerNames = await this.bookingsRepository.resolveStaffNames([
...reviews.map((r) => r.reviewedByStaffId),
...queryNotes.map((n) => n.authorId),
...docRequestNotes.map((n) => n.authorId),
]);
const documents: BookingClearanceView['documents'] = [];
@@ -357,6 +368,12 @@ export class BookingClearanceService {
documents,
allApproved,
documentsOpen: clearanceDocumentsOpen(booking),
docRequests: docRequestNotes.map((n) => ({
id: n.id,
note: n.note,
byName: n.authorId ? (reviewerNames.get(n.authorId) ?? null) : null,
at: n.createdAt.toISOString(),
})),
phase,
milestones: milestones.map((m) => ({
id: m.id,

113
apps/edr-freight-web/backoffice/src/components/bookings/detail/AdditionalDocsRequestCard.tsx Normal file
View File

@@ -0,0 +1,113 @@
import { useState } from "react";
import { useMutation } from "@tanstack/react-query";
import {
Box,
Button,
Group,
Paper,
Stack,
Text,
Textarea,
} from "@mantine/core";
import { MessageSquarePlus, Send } from "lucide-react";
import toast from "react-hot-toast";
import type { Freight } from "@edr/types";
import { SectionCard } from "./SectionCard";
import { bookingsService } from "@/services/bookings.service";
import { formatDateTime } from "@/lib/format";
import { extractErrorMessage } from "@/utils/errorExtractor";
export interface AdditionalDocsRequestCardProps {
bookingId: string;
/** Past requests, newest first. */
requests: Freight.ClearanceDocRequest[];
/** False once the shipment is paid — documents (and requests) are closed. */
canRequest: boolean;
onSent?: () => void;
}
/**
* GL asks the customer for additional clearance document(s) in plain words.
* The message, its author and its time show on the customer's portal beside
* the upload box, so the customer knows exactly what to send and who asked.
*/
export function AdditionalDocsRequestCard({
bookingId,
requests,
canRequest,
onSent,
}: AdditionalDocsRequestCardProps) {
const [note, setNote] = useState("");
const send = useMutation({
mutationFn: () => bookingsService.requestAdditionalDocuments(bookingId, note),
onSuccess: () => {
toast.success("Request sent to the customer");
setNote("");
onSent?.();
},
onError: (e) =>
toast.error(extractErrorMessage(e, "Could not send the request")),
});
return (
<SectionCard
icon={MessageSquarePlus}
title="Ask for a document"
subtitle="The customer sees your message, who wrote it, and uploads the file from their portal."
accent="edr-green"
>
<Stack gap="sm">
{canRequest ? (
<Box>
<Textarea
placeholder="e.g. Please send the amended commercial invoice showing the revised unit price."
value={note}
onChange={(e) => setNote(e.currentTarget.value)}
autosize
minRows={3}
radius="md"
size="sm"
/>
<Group justify="flex-end" mt={8}>
<Button
size="compact-sm"
color="edr-green"
radius="md"
leftSection={<Send size={14} />}
loading={send.isPending}
disabled={!note.trim()}
onClick={() => send.mutate()}
>
Send request
</Button>
</Group>
</Box>
) : (
<Text fz="12.5px" c="dimmed">
This shipment is settled — document requests are closed.
</Text>
)}
{requests.length > 0 && (
<Stack gap={8}>
<Text fz="11px" fw={700} tt="uppercase" c="dimmed" lts="0.05em">
Sent requests
</Text>
{requests.map((r) => (
<Paper key={r.id} withBorder radius="md" p="xs">
<Text fz="12.5px" c="edr-text">
{r.note}
</Text>
<Text fz="11px" c="dimmed" mt={4}>
{r.byName ?? "Staff"} · {formatDateTime(r.at)}
</Text>
</Paper>
))}
</Stack>
)}
</Stack>
</SectionCard>
);
}

9
apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
View File

@@ -36,6 +36,7 @@ import {
BookingContractCard,
} from "@/components/bookings/detail";
import { ClearanceReviewSection } from "@/components/bookings/detail/ClearanceReviewSection";
import { AdditionalDocsRequestCard } from "@/components/bookings/detail/AdditionalDocsRequestCard";
import { ClearancePhaseStepper } from "@/components/contracts/ClearancePhaseStepper";
import { PhasedClearanceActionPanel } from "@/components/contracts/PhasedClearanceActionPanel";
import { ClearanceMilestoneTimeline } from "@/components/contracts/ClearanceMilestoneTimeline";
@@ -363,6 +364,14 @@ export default function DocumentClearanceDetailPage() {
<Grid.Col span={{ base: 12, lg: isPhasedGeneral ? 5 : 4 }}>
<Box style={{ position: "sticky", top: 24 }}>
<Stack gap="lg">
{/* Documents stay open until payment, so GL can ask for a
missing file at any point in that window. */}
<AdditionalDocsRequestCard
bookingId={id!}
requests={clearance.docRequests ?? []}
canRequest={!documentsClosed}
onSent={() => void refetch()}
/>
{booking ? <BookingCompanyCard booking={booking} /> : null}
{booking ? <BookingContractCard booking={booking} /> : null}
{isPhasedGeneral ? (

5
apps/edr-freight-web/backoffice/src/services/bookings.service.ts
View File

@@ -432,6 +432,11 @@ export const bookingsService = {
return unwrap(response.data) as Freight.ClearanceView;
},
/** GL asks the customer for additional clearance document(s). */
requestAdditionalDocuments: async (id: string, note: string): Promise<void> => {
await client.post(`/bookings/${id}/clearance/doc-requests`, { note });
},
/** Clearance action history — reviews, workflow steps, charges (newest first). */
getClearanceHistory: async (
id: string,

83
apps/edr-freight-web/portal/src/pages/bookings/clearance/ClearanceFlow.tsx
View File

@@ -12,6 +12,7 @@ import {
Download,
Eye,
FileText,
MessageSquare,
} from "lucide-react";
import type { Freight } from "@edr/types";
@@ -55,6 +56,7 @@ export function ClearanceFlow({ booking, flow, footer }: ClearanceFlowProps) {
clearance,
customerDocs,
glDocs,
workflowFiles,
isReady,
needsCompletion,
awaitingGlCompletion,
@@ -152,6 +154,56 @@ export function ClearanceFlow({ booking, flow, footer }: ClearanceFlowProps) {
))}
</Stack>
{/* Customs paperwork GL produced for this shipment — declaration, T1
transit permit, Djibouti documents. These live in `workflowFiles`
rather than the seeded output set, so they need their own section:
without it the customer never sees their own declaration or T1. */}
{workflowFiles.length > 0 && (
<>
<Text fz="12.5px" fw={700} c="#10202F" mt="lg" mb={8}>
Clearance documents from Global Logistics
</Text>
<Stack gap={8}>
{workflowFiles.map((doc) => (
<Group
key={doc.code}
justify="space-between"
wrap="nowrap"
className="rounded-xl"
style={{ border: `1px solid ${BORDER}`, padding: 10 }}
>
<Group gap={10} wrap="nowrap" style={{ minWidth: 0 }}>
<Box c="#2E5B96">
<FileText size={18} />
</Box>
<Text fz="13px" c="#10202F" truncate>
{doc.label}
</Text>
</Group>
<Group gap={8} wrap="nowrap">
{isViewable({ name: doc.file.name, url: "" }) && (
<IconSquare
icon={<Eye size={15} />}
onClick={() =>
void fetchViewableFile(doc.file.id, doc.file.name).then(
view,
)
}
/>
)}
<IconSquare
icon={<Download size={15} />}
onClick={() =>
void downloadStoredFile(doc.file.id, doc.file.name)
}
/>
</Group>
</Group>
))}
</Stack>
</>
)}
{/* GL output documents (read-only to the customer). */}
{glDocs.length > 0 && (
<>
@@ -209,6 +261,37 @@ export function ClearanceFlow({ booking, flow, footer }: ClearanceFlowProps) {
</>
)}
{/* What Global Logistics asked for, in their own words — placed directly
above the upload box so the customer reads the ask and answers it in
one place. Newest first. */}
{(clearance.docRequests?.length ?? 0) > 0 && (
<Box mt="lg">
<Text fz="12.5px" fw={700} c="#10202F" mb={8}>
Requested by Global Logistics
</Text>
<Stack gap={8}>
{clearance.docRequests!.map((r) => (
<Alert
key={r.id}
color="blue"
variant="light"
radius="md"
icon={<MessageSquare size={16} />}
p="xs"
>
<Text fz="12.5px" c="#10202F">
{r.note}
</Text>
<Text fz="11px" c="dimmed" mt={4}>
{r.byName ?? "Global Logistics"} ·{" "}
{new Date(r.at).toLocaleString()}
</Text>
</Alert>
))}
</Stack>
</Box>
)}
{canUpload ? (
<ClearanceAdHocUploadSection
rows={adHoc}

13
apps/edr-freight-web/portal/src/pages/bookings/clearance/useClearanceFlow.ts
View File

@@ -97,6 +97,18 @@ export function useClearanceFlow(booking: Freight.IBooking) {
() => (clearance?.documents ?? []).filter((d) => d.uploadedBy === "gl"),
[clearance],
);
// Phased customs paperwork (declaration, T1 transit permit, Djibouti docs).
// Separate from `glDocs`, which only covers the seeded output-document set —
// these carry the shipment's own declaration and permit.
const workflowFiles = useMemo(
() =>
(clearance?.workflowFiles ?? []).filter(
(f): f is Freight.ClearanceWorkflowFile & {
file: NonNullable<Freight.ClearanceWorkflowFile["file"]>;
} => Boolean(f.file),
),
[clearance],
);
// OPERATION_CHANGES_REQUESTED re-opens the same pick-a-day flow: the
// customer resubmits via the same clearance/proceed endpoint.
@@ -205,6 +217,7 @@ export function useClearanceFlow(booking: Freight.IBooking) {
isLoading: clearanceQuery.isLoading,
customerDocs,
glDocs,
workflowFiles,
isReady,
needsCompletion,
completeTo,

11
packages/types/src/freight/index.ts
View File

@@ -856,6 +856,15 @@ export interface ClearanceCharge {
paidAt: string | null;
}
/** A GL→customer request for additional clearance document(s). */
export interface ClearanceDocRequest {
id: string;
note: string;
/** Staff display name; null when unresolvable. */
byName: string | null;
at: string;
}
/** One entry of a clearance document's audit trail, oldest first. */
export interface ClearanceDocumentEvent {
type: "UPLOADED" | "RESUBMITTED" | "QUERIED" | "APPROVED";
@@ -930,6 +939,8 @@ export interface ClearanceView {
* clearance is finalized.
*/
documentsOpen?: boolean;
/** GL→customer requests for additional documents, newest first. */
docRequests?: ClearanceDocRequest[];
/** Phased clearance (GENERAL + customs per-booking). */
phase?: ContractDocPhase | null;
milestones?: IClearanceMilestone[];