Merge pull request #641 from Tria-plc/freight_feature/usermanagement

enhance booking and contract management features

apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx

@@ -1,137 +1,147 @@
-import { useEffect, useMemo, useState } from "react";
-import { useNavigate } from "react-router-dom";
 import {
-  Badge,
+  ActionIcon,
+  Box,
+  Card,
   Group,
-  Paper,
-  SegmentedControl,
+  Select,
+  Stack,
   Tabs,
+  Text,
   TextInput,
+  ThemeIcon,
 } from "@mantine/core";
 import { useDebouncedValue } from "@mantine/hooks";
 import { keepPreviousData, useQuery } from "@tanstack/react-query";
-import { Search } from "lucide-react";
 import {
+  ArrowRight,
+  FileText,
+  Inbox,
+  RefreshCw,
+  Repeat,
+  Search,
+  User,
+  X,
+} from "lucide-react";
+import { useCallback, useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
+import { bookingTable } from "@/components/bookings/booking-ui.styles";
+import { ContractStatusBadge } from "@/components/contracts/ContractStatusBadge";
+import { PageContainer, PageHeader } from "@/components/page";
+import {
+  toContractListRow,
+  type ContractListRow,
+} from "@/features/contracts/mapContractListRow";
+import { bookingsService } from "@/services/bookings.service";
+import { contractsService } from "@/services/contracts.service";
+import type { BookingDetail } from "@/types/booking";
+import {
+  Badge,
   DataTable,
   DataTableFooter,
   usePagination,
   type ColumnDef,
 } from "@edr/ui-common";
-import type { Freight } from "@edr/types";
-
-import { PageContainer } from "@/components/page/PageContainer";
-import { PageHeader } from "@/components/page/PageHeader";
-import { contractsService } from "@/services/contracts.service";
-import { bookingsService } from "@/services/bookings.service";
-import type { BookingDetail } from "@/types/booking";
 
 /**
- * Operations "Clearance Documents" hub — the worklist for clearance-document
- * review on contracts WITHOUT customs clearing (self-clearance / Path A):
- *
- * - Contracts tab: contracts whose clearance runs at contract level; rows open
- *   the contract clearance detail where Operations approves + finalizes.
- * - General tab: booking instances under GENERAL non-customs contracts (those
- *   clear per booking); rows open the booking clearance review page.
- *
- * The hub only lists — all review/approve/finalize actions live on the
- * existing detail pages it links to.
+ * Operations "Clearance Documents" hub — worklist for clearance-document
+ * review on contracts WITHOUT customs clearing (self-clearance):
+ * Contracts tab = contract-level review (one-time flow), General tab =
+ * per-booking review under GENERAL non-customs contracts. Rows deep-link to
+ * the existing review detail pages; search / status filter / pagination are
+ * all server-side.
  */
 
 type HubTab = "contracts" | "general";
-type QueueTab = "queue" | "history";
 
 const PAGE_SIZE = 10;
 
-/** Booking statuses that mean "docs awaiting review" / "review finished". */
-const BOOKING_QUEUE_STATUS = "DOCUMENTS_UNDER_REVIEW";
-const BOOKING_HISTORY_STATUS = "CLEARANCE_READY";
+/** Status filter options for the Contracts tab (values = `statuses` param). */
+const CONTRACT_STATUS_OPTIONS = [
+  {
+    value: [
+      "AWAITING_CLEARANCE_DOCUMENTS",
+      "CLEARANCE_UNDER_REVIEW",
+      "CLEARANCE_READY_FOR_BOOKING",
+      "FULLY_EXECUTED",
+      "CONTRACT_ACTIVE",
+      "ACTIVE_SHIPMENT_IN_PROGRESS",
+      "CONTRACT_CLOSED",
+      "CANCELLED",
+    ].join(","),
+    label: "All statuses",
+  },
+  { value: "AWAITING_CLEARANCE_DOCUMENTS", label: "Awaiting documents" },
+  { value: "CLEARANCE_UNDER_REVIEW", label: "Under review" },
+  { value: "CLEARANCE_READY_FOR_BOOKING", label: "Ready for booking" },
+  { value: "FULLY_EXECUTED,CONTRACT_ACTIVE", label: "Finalized" },
+  {
+    value: "ACTIVE_SHIPMENT_IN_PROGRESS,CONTRACT_CLOSED",
+    label: "In progress / closed",
+  },
+  { value: "CANCELLED", label: "Cancelled" },
+];
 
-function formatDate(iso?: string | null): string {
-  if (!iso) return "—";
-  const d = new Date(iso);
-  if (Number.isNaN(d.getTime())) return "—";
-  return d.toLocaleDateString(undefined, {
-    day: "2-digit",
-    month: "short",
-    year: "numeric",
-  });
-}
-
-function statusLabel(status?: string | null): string {
-  return (status ?? "—").replaceAll("_", " ");
-}
-
-function StatusBadge({ status }: { status?: string | null }) {
-  const done =
-    status === "CLEARANCE_READY" ||
-    status === "CLEARANCE_READY_FOR_BOOKING" ||
-    status === "ACTIVE" ||
-    status === "CONTRACT_ACTIVE" ||
-    status === "FULLY_EXECUTED";
-  return (
-    <Badge variant="light" color={done ? "edr-green" : "yellow"} radius="sm">
-      {statusLabel(status)}
-    </Badge>
-  );
-}
+/** Status filter options for the General (per-booking) tab. */
+const BOOKING_STATUS_OPTIONS = [
+  {
+    value: "AWAITING_DOCUMENTS,DOCUMENTS_UNDER_REVIEW,CLEARANCE_READY",
+    label: "All statuses",
+  },
+  { value: "AWAITING_DOCUMENTS", label: "Awaiting documents" },
+  { value: "DOCUMENTS_UNDER_REVIEW", label: "Under review" },
+  { value: "CLEARANCE_READY", label: "Clearance ready" },
+];
 
 export default function ClearanceDocumentsPage() {
   const navigate = useNavigate();
   const [hubTab, setHubTab] = useState<HubTab>("contracts");
-  const [queueTab, setQueueTab] = useState<QueueTab>("queue");
   const [query, setQuery] = useState("");
   const [debouncedQuery] = useDebouncedValue(query, 300);
+  const [contractStatuses, setContractStatuses] = useState(
+    CONTRACT_STATUS_OPTIONS[0].value,
+  );
+  const [bookingStatuses, setBookingStatuses] = useState(
+    BOOKING_STATUS_OPTIONS[0].value,
+  );
+  const { pagination, setPagination } = usePagination({ pageSize: PAGE_SIZE });
+
   const search = debouncedQuery.trim() || undefined;
 
-  const contractsPager = usePagination({ pageSize: PAGE_SIZE });
-  const generalPager = usePagination({ pageSize: PAGE_SIZE });
+  const resetPage = useCallback(() => {
+    setPagination({ pageIndex: 0, pageSize: PAGE_SIZE });
+  }, [setPagination]);
 
-  // Any search / queue-history / tab switch restarts both lists from page 1.
-  useEffect(() => {
-    contractsPager.setPagination((p) => ({ ...p, pageIndex: 0 }));
-    generalPager.setPagination((p) => ({ ...p, pageIndex: 0 }));
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [debouncedQuery, queueTab, hubTab]);
-
-  const isHistory = queueTab === "history";
+  const page = pagination.pageIndex + 1;
 
   const contractsQuery = useQuery({
     queryKey: [
       "clearance-documents",
       "contracts",
-      queueTab,
-      contractsPager.pagination.pageIndex,
+      contractStatuses,
+      page,
       search,
     ],
-    queryFn: () => {
-      const filter = {
-        page: contractsPager.pagination.pageIndex + 1,
+    queryFn: () =>
+      contractsService.getOpsClearanceQueue({
+        page,
         pageSize: PAGE_SIZE,
+        statuses: contractStatuses,
         search,
-      };
-      return isHistory
-        ? contractsService.getOpsClearanceHistory(filter)
-        : contractsService.getOpsClearanceQueue(filter);
-    },
+      }),
     enabled: hubTab === "contracts",
     placeholderData: keepPreviousData,
   });
 
   const generalQuery = useQuery({
-    queryKey: [
-      "clearance-documents",
-      "general",
-      queueTab,
-      generalPager.pagination.pageIndex,
-      search,
-    ],
+    queryKey: ["clearance-documents", "general", bookingStatuses, page, search],
     queryFn: () =>
       bookingsService.list({
-        status: isHistory ? BOOKING_HISTORY_STATUS : BOOKING_QUEUE_STATUS,
+        statuses: bookingStatuses,
         bookingType: "GENERAL_CONTRACT",
         customsClearingEnabled: "false",
-        page: generalPager.pagination.pageIndex + 1,
+        page,
         pageSize: PAGE_SIZE,
         search,
       }),
@@ -139,171 +149,355 @@ export default function ClearanceDocumentsPage() {
     placeholderData: keepPreviousData,
   });
 
-  const contractColumns = useMemo(
-    (): ColumnDef<Freight.IContract, unknown>[] => [
+  const contractRows = useMemo(
+    () => (contractsQuery.data?.items ?? []).map(toContractListRow),
+    [contractsQuery.data?.items],
+  );
+  const bookingRows = generalQuery.data?.items ?? [];
+
+  const contractColumns: ColumnDef<ContractListRow>[] = useMemo(
+    () => [
       {
-        header: "Reference",
-        accessorKey: "reference",
+        id: "contract",
+        header: () => <span className={bookingTable.headerCell}>Customer</span>,
+        cell: ({ row }) => {
+          const c = row.original;
+          return (
+            <div className="flex items-center gap-3 py-1.5">
+              <div className={bookingTable.rowIcon}>
+                <User className="size-4" strokeWidth={1.75} />
+              </div>
+              <div className="min-w-0">
+                <p className="truncate font-medium text-foreground">
+                  {c.customerLabel}
+                </p>
+                <p className="mt-0.5 flex items-center gap-1 truncate text-xs text-muted-foreground">
+                  <FileText className="size-3 shrink-0 opacity-70" />
+                  {c.reference}
+                </p>
+              </div>
+            </div>
+          );
+        },
       },
       {
-        header: "Customer",
-        cell: ({ row }) => row.original.company?.name ?? "—",
+        id: "route",
+        header: () => <span className={bookingTable.headerCell}>Route</span>,
+        cell: ({ row }) => {
+          const c = row.original;
+          return (
+            <div className="space-y-1 py-1">
+              <div className="flex items-center gap-1.5 text-sm font-medium text-foreground">
+                <span className="max-w-[8rem] truncate">{c.originLabel}</span>
+                <ArrowRight className="size-3.5 shrink-0 text-muted-foreground" />
+                <span className="max-w-[8rem] truncate">
+                  {c.destinationLabel}
+                </span>
+              </div>
+              <div className="flex gap-1.5">
+                <Badge
+                  variant="outline"
+                  className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium uppercase backdrop-blur-sm"
+                >
+                  {c.tradeDirection}
+                </Badge>
+                <Badge
+                  variant="secondary"
+                  className="h-5 bg-muted/40 px-1.5 text-[10px] font-medium"
+                >
+                  {c.freightType}
+                </Badge>
+              </div>
+            </div>
+          );
+        },
       },
       {
-        header: "Kind",
-        cell: ({ row }) => statusLabel(row.original.contractKind),
+        id: "kind",
+        header: () => <span className={bookingTable.headerCell}>Kind</span>,
+        cell: ({ row }) => (
+          <Badge
+            variant="outline"
+            className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium uppercase"
+          >
+            {row.original.contractKind === "GENERAL" ? (
+              <span className="inline-flex items-center gap-1">
+                <Repeat className="size-3" /> General
+              </span>
+            ) : (
+              "One-time"
+            )}
+          </Badge>
+        ),
       },
       {
-        header: "Direction",
-        cell: ({ row }) => statusLabel(row.original.tradeDirection),
-      },
-      {
-        header: "Freight",
-        cell: ({ row }) => statusLabel(row.original.freightType),
-      },
-      {
-        header: "Status",
-        cell: ({ row }) => <StatusBadge status={row.original.status} />,
-      },
-      {
-        header: "Created",
-        cell: ({ row }) => formatDate(row.original.createdAt),
+        id: "status",
+        size: 200,
+        minSize: 180,
+        header: () => <span className={bookingTable.headerCell}>Status</span>,
+        cell: ({ row }) => (
+          <div className="py-1">
+            <ContractStatusBadge
+              status={row.original.status}
+              isRenewal={row.original.isRenewal}
+            />
+          </div>
+        ),
+        meta: {
+          headerClassName: "min-w-[11rem]",
+          cellClassName: "min-w-[11rem]",
+        },
       },
     ],
     [],
   );
 
-  const bookingColumns = useMemo(
-    (): ColumnDef<BookingDetail, unknown>[] => [
+  const bookingColumns: ColumnDef<BookingDetail>[] = useMemo(
+    () => [
       {
-        header: "Reference",
-        accessorKey: "reference",
+        id: "booking",
+        header: () => <span className={bookingTable.headerCell}>Customer</span>,
+        cell: ({ row }) => {
+          const b = row.original;
+          const customer = b.isGovernment
+            ? (b.governmentInstitution ?? "Government")
+            : (b.company?.name ?? "—");
+          return (
+            <div className="flex items-center gap-3 py-1.5">
+              <div className={bookingTable.rowIcon}>
+                <User className="size-4" strokeWidth={1.75} />
+              </div>
+              <div className="min-w-0">
+                <p className="truncate font-medium text-foreground">
+                  {customer}
+                </p>
+                <p className="mt-0.5 flex items-center gap-1 truncate text-xs text-muted-foreground">
+                  <FileText className="size-3 shrink-0 opacity-70" />
+                  {b.reference}
+                </p>
+              </div>
+            </div>
+          );
+        },
       },
       {
-        header: "Customer",
-        cell: ({ row }) =>
-          row.original.isGovernment
-            ? (row.original.governmentInstitution ?? "Government")
-            : (row.original.company?.name ?? "—"),
+        id: "contractRef",
+        header: () => <span className={bookingTable.headerCell}>Contract</span>,
+        cell: ({ row }) => (
+          <Text size="sm">{row.original.contractReference ?? "—"}</Text>
+        ),
       },
       {
-        header: "Contract",
-        cell: ({ row }) => row.original.contractReference ?? "—",
+        id: "shipment",
+        header: () => <span className={bookingTable.headerCell}>Shipment</span>,
+        cell: ({ row }) => {
+          const b = row.original;
+          return (
+            <div className="flex gap-1.5 py-1">
+              <Badge
+                variant="outline"
+                className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium uppercase backdrop-blur-sm"
+              >
+                {b.tradeDirection ?? "—"}
+              </Badge>
+              <Badge
+                variant="secondary"
+                className="h-5 bg-muted/40 px-1.5 text-[10px] font-medium"
+              >
+                {b.freightType ?? "—"}
+              </Badge>
+            </div>
+          );
+        },
       },
       {
-        header: "Direction",
-        cell: ({ row }) => statusLabel(row.original.tradeDirection),
-      },
-      {
-        header: "Freight",
-        cell: ({ row }) => statusLabel(row.original.freightType),
-      },
-      {
-        header: "Status",
-        cell: ({ row }) => <StatusBadge status={row.original.status} />,
+        id: "status",
+        size: 200,
+        minSize: 180,
+        header: () => <span className={bookingTable.headerCell}>Status</span>,
+        cell: ({ row }) => (
+          <div className="py-1">
+            <BookingStatusBadge status={row.original.status} />
+          </div>
+        ),
+        meta: {
+          headerClassName: "min-w-[11rem]",
+          cellClassName: "min-w-[11rem]",
+        },
       },
     ],
     [],
   );
 
-  const activeQuery = hubTab === "contracts" ? contractsQuery : generalQuery;
+  const isContracts = hubTab === "contracts";
+  const activeQuery = isContracts ? contractsQuery : generalQuery;
   const total = activeQuery.data?.total ?? 0;
   const pageCount = Math.max(1, Math.ceil(total / PAGE_SIZE));
-
+  const showEmpty =
+    !activeQuery.isLoading &&
+    !activeQuery.isError &&
+    (isContracts ? contractRows.length : bookingRows.length) === 0;
   const tableStatus = activeQuery.isLoading
     ? "loading"
     : activeQuery.isError
       ? "error"
       : "success";
 
+  const statusOptions = isContracts
+    ? CONTRACT_STATUS_OPTIONS
+    : BOOKING_STATUS_OPTIONS;
+  const statusValue = isContracts ? contractStatuses : bookingStatuses;
+  const setStatusValue = isContracts ? setContractStatuses : setBookingStatuses;
+
   return (
     <PageContainer>
-      <PageHeader
-        title="Clearance Documents"
-        subtitle="Operations review of customer clearance documents for contracts without customs clearing — contract-level (one-time) and per-booking (general)."
-      />
+      <Stack gap="lg">
+        <PageHeader
+          title="Clearance Documents"
+          subtitle="Operations review of customer clearance documents for contracts without customs clearing."
+          action={
+            <ActionIcon
+              variant="default"
+              size="lg"
+              radius="md"
+              loading={activeQuery.isFetching}
+              onClick={() => void activeQuery.refetch()}
+              aria-label="Refresh"
+            >
+              <RefreshCw size={16} />
+            </ActionIcon>
+          }
+        />
 
-      <Paper withBorder radius="md" p="md">
-        <Group justify="space-between" mb="md" wrap="wrap" gap="sm">
-          <Tabs
-            value={hubTab}
-            onChange={(v) => setHubTab((v as HubTab) ?? "contracts")}
-          >
-            <Tabs.List>
-              <Tabs.Tab value="contracts">Contracts</Tabs.Tab>
-              <Tabs.Tab value="general">General</Tabs.Tab>
-            </Tabs.List>
-          </Tabs>
-          <Group gap="sm">
-            <SegmentedControl
-              value={queueTab}
-              onChange={(v) => setQueueTab(v as QueueTab)}
-              data={[
-                { value: "queue", label: "Queue" },
-                { value: "history", label: "History" },
-              ]}
-              size="xs"
-            />
-            <TextInput
-              value={query}
-              onChange={(e) => setQuery(e.currentTarget.value)}
-              placeholder={
-                hubTab === "contracts"
-                  ? "Search reference or customer…"
-                  : "Search booking, customer or contract…"
-              }
-              leftSection={<Search size={14} />}
-              w={260}
-            />
-          </Group>
-        </Group>
+        <Tabs
+          value={hubTab}
+          onChange={(v) => {
+            setHubTab((v as HubTab) ?? "contracts");
+            resetPage();
+          }}
+        >
+          <Tabs.List>
+            <Tabs.Tab value="contracts">Contracts</Tabs.Tab>
+            <Tabs.Tab value="general">General</Tabs.Tab>
+          </Tabs.List>
+        </Tabs>
 
-        {hubTab === "contracts" ? (
-          <DataTable<Freight.IContract, unknown>
-            columns={contractColumns}
-            data={contractsQuery.data?.items ?? []}
-            status={tableStatus}
-            onRowClick={(row) =>
-              navigate(`/dashboard/contracts/clearance/${row.id}`)
-            }
-            pagination={{
-              pageIndex: contractsPager.pagination.pageIndex,
-              pageSize: PAGE_SIZE,
-              pageCount,
-              totalCount: total,
-            }}
-            tableOptions={{
-              state: { pagination: contractsPager.pagination },
-              onPaginationChange: contractsPager.setPagination,
-              manualPagination: true,
-              pageCount,
-            }}
-            containerClassName="border-0 shadow-none bg-transparent"
-            footer={DataTableFooter}
-          />
-        ) : (
-          <DataTable<BookingDetail, unknown>
-            columns={bookingColumns}
-            data={generalQuery.data?.items ?? []}
-            status={tableStatus}
-            onRowClick={(row) => navigate(`/dashboard/clearance/${row.id}`)}
-            pagination={{
-              pageIndex: generalPager.pagination.pageIndex,
-              pageSize: PAGE_SIZE,
-              pageCount,
-              totalCount: total,
-            }}
-            tableOptions={{
-              state: { pagination: generalPager.pagination },
-              onPaginationChange: generalPager.setPagination,
-              manualPagination: true,
-              pageCount,
-            }}
-            containerClassName="border-0 shadow-none bg-transparent"
-            footer={DataTableFooter}
-          />
-        )}
-      </Paper>
+        <Card p={0}>
+          <Stack gap={0}>
+            <Box px="md" pt="md" pb="sm" w="100%">
+              <Group justify="space-between" gap="md" wrap="wrap">
+                <TextInput
+                  placeholder={
+                    isContracts
+                      ? "Search reference or customer…"
+                      : "Search booking, contract or customer…"
+                  }
+                  leftSection={<Search size={18} />}
+                  value={query}
+                  onChange={(e) => {
+                    setQuery(e.target.value);
+                    resetPage();
+                  }}
+                  rightSection={
+                    query && (
+                      <ActionIcon
+                        size="sm"
+                        color="gray"
+                        radius="md"
+                        variant="transparent"
+                        onClick={() => {
+                          setQuery("");
+                          resetPage();
+                        }}
+                      >
+                        <X size={16} />
+                      </ActionIcon>
+                    )
+                  }
+                  style={{ flex: 1, minWidth: "200px" }}
+                  radius="lg"
+                />
+                <Select
+                  data={statusOptions}
+                  value={statusValue}
+                  onChange={(v) => {
+                    setStatusValue(v ?? statusOptions[0].value);
+                    resetPage();
+                  }}
+                  allowDeselect={false}
+                  radius="lg"
+                  w={220}
+                  aria-label="Filter by status"
+                />
+                <Text size="sm" c="dimmed">
+                  {total} record{total !== 1 ? "s" : ""}
+                </Text>
+              </Group>
+            </Box>
+
+            {showEmpty ? (
+              <Stack align="center" gap={8} py={48}>
+                <ThemeIcon variant="light" color="gray" radius="xl" size={48}>
+                  <Inbox size={22} />
+                </ThemeIcon>
+                <Text c="dimmed">
+                  No {isContracts ? "contracts" : "bookings"} match this view.
+                </Text>
+              </Stack>
+            ) : (
+              <Box style={{ overflowX: "auto" }} w="100%">
+                {isContracts ? (
+                  <DataTable
+                    columns={contractColumns}
+                    data={contractRows}
+                    status={tableStatus}
+                    onRowClick={(row) =>
+                      navigate(`/dashboard/contracts/clearance/${row.id}`)
+                    }
+                    pagination={{
+                      pageIndex: pagination.pageIndex,
+                      pageSize: pagination.pageSize,
+                      pageCount,
+                      totalCount: total,
+                    }}
+                    tableOptions={{
+                      state: { pagination },
+                      onPaginationChange: setPagination,
+                      manualPagination: true,
+                      pageCount,
+                    }}
+                    containerClassName="border-0 shadow-none bg-transparent"
+                    footer={DataTableFooter}
+                  />
+                ) : (
+                  <DataTable
+                    columns={bookingColumns}
+                    data={bookingRows}
+                    status={tableStatus}
+                    onRowClick={(row) =>
+                      navigate(`/dashboard/clearance/${row.id}`)
+                    }
+                    pagination={{
+                      pageIndex: pagination.pageIndex,
+                      pageSize: pagination.pageSize,
+                      pageCount,
+                      totalCount: total,
+                    }}
+                    tableOptions={{
+                      state: { pagination },
+                      onPaginationChange: setPagination,
+                      manualPagination: true,
+                      pageCount,
+                    }}
+                    containerClassName="border-0 shadow-none bg-transparent"
+                    footer={DataTableFooter}
+                  />
+                )}
+              </Box>
+            )}
+          </Stack>
+        </Card>
+      </Stack>
     </PageContainer>
   );
 }

apps/edr-freight-web/backoffice/src/services/contracts.service.ts

@@ -461,6 +461,8 @@ export const contractsService = {
     page?: number;
     pageSize?: number;
     search?: string;
+    /** Comma-separated ops-clearance lifecycle statuses; omitted → under-review queue. */
+    statuses?: string;
   }): Promise<PaginatedContracts> => {
     const response = await client.get<PaginatedContracts>(
       C.OPS_CLEARANCE_QUEUE,