add permanent purge functionality for wagons and routes

- Implemented a method in to permanently delete wagons without history. - Added corresponding permissions for hard delete actions in . - Updated the UI components to include purge actions, ensuring they are only available to users with the appropriate permissions. - Created modals for confirming permanent deletions in and . - Enhanced API services to handle purge requests for locomotives, wagons, and routes. - Added tests for the purge functionality in both and services to ensure proper behavior and error handling.
2026-08-26 18:42:49 +00:00 · 2026-08-04 14:07:16 +00:00
parent 8cf49aa1cc
commit 5d68a3f7b7
22 changed files with 806 additions and 20 deletions
--- a/apps/edr-freight-web/backoffice/src/components/fleet/FleetCardGrid.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/fleet/FleetCardGrid.tsx
@@ -22,6 +22,8 @@ export interface FleetCardGridProps {
  /** Omit to hide the action (caller lacks the update/delete permission). */
  onEdit?: (record: FleetRecord) => void;
  onRemove?: (record: FleetRecord) => void;
+  /** Irreversible purge — omitted unless the caller holds the hard-delete grant. */
+  onPurge?: (record: FleetRecord) => void;
 }

 const FleetCardGrid = ({
@@ -35,6 +37,7 @@ const FleetCardGrid = ({
  onPaginationChange,
  onEdit,
  onRemove,
+  onPurge,
 }: FleetCardGridProps) => {
  const presentation = resolveFleetCardPresentation(config);

@@ -183,6 +186,7 @@ const FleetCardGrid = ({
                  layout="compact"
                  onEdit={onEdit}
                  onRemove={onRemove}
+                  onPurge={onPurge}
                />
              </Stack>
            </Card>
--- a/apps/edr-freight-web/backoffice/src/components/fleet/FleetRecordActions.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/fleet/FleetRecordActions.tsx
@@ -1,4 +1,12 @@
-import { Edit2, Trash2, Eye, Users, MoreVertical, History } from "lucide-react";
+import {
+  Edit2,
+  Trash2,
+  Eye,
+  Users,
+  MoreVertical,
+  History,
+  ShieldAlert,
+} from "lucide-react";
 import { ActionIcon, Menu, MenuItem, Tooltip } from "@mantine/core";
 import { useNavigate } from "react-router-dom";

@@ -11,6 +19,8 @@ export interface FleetRecordActionsProps {
  /** Omit to hide the action (caller lacks the update/delete permission). */
  onEdit?: (record: FleetRecord) => void;
  onRemove?: (record: FleetRecord) => void;
+  /** Irreversible purge — omitted unless the caller holds the hard-delete grant. */
+  onPurge?: (record: FleetRecord) => void;
  onAssignDriver?: (record: FleetRecord) => void;
  onHistory?: (record: FleetRecord) => void;
  onViewDetail?: (record: FleetRecord) => void;
@@ -22,6 +32,7 @@ const FleetRecordActions = ({
  config,
  onEdit,
  onRemove,
+  onPurge,
  onAssignDriver,
  onHistory,
  onViewDetail,
@@ -46,6 +57,7 @@ const FleetRecordActions = ({
  if (
    !onEdit &&
    !onRemove &&
+    !onPurge &&
    !showDetail &&
    !showViewDetail &&
    !showHistory &&
@@ -170,6 +182,15 @@ const FleetRecordActions = ({
            {removeLabel}
          </MenuItem>
        ) : null}
+        {onPurge ? (
+          <MenuItem
+            color="red"
+            onClick={() => onPurge(record)}
+            leftSection={<ShieldAlert size={14} strokeWidth={2} />}
+          >
+            Delete permanently
+          </MenuItem>
+        ) : null}
      </Menu.Dropdown>
    </Menu>
  );
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -122,12 +122,16 @@ export const FREIGHT_PERMS = {
    create: "edr_freight_app:locomotives:create",
    update: "edr_freight_app:locomotives:update",
    delete: "edr_freight_app:locomotives:delete",
+    /** Permanent purge — irreversible, granted separately from `delete`. */
+    hardDelete: "edr_freight_app:locomotives:hard_delete",
  },
  wagons: {
    view: "edr_freight_app:wagons:view",
    create: "edr_freight_app:wagons:create",
    update: "edr_freight_app:wagons:update",
    delete: "edr_freight_app:wagons:delete",
+    /** Permanent purge — irreversible, granted separately from `delete`. */
+    hardDelete: "edr_freight_app:wagons:hard_delete",
    transferRequest: "edr_freight_app:wagons:transfer_request",
    transferFulfill: "edr_freight_app:wagons:transfer_fulfill",
    transferHistoryAll: "edr_freight_app:wagons:transfer_history_all",
@@ -148,6 +152,8 @@ export const FREIGHT_PERMS = {
    create: "edr_freight_app:routes:create",
    update: "edr_freight_app:routes:update",
    delete: "edr_freight_app:routes:delete",
+    /** Permanent purge — irreversible, granted separately from `delete`. */
+    hardDelete: "edr_freight_app:routes:hard_delete",
  },
  containers: {
    view: "edr_freight_app:containers:view",
@@ -598,6 +604,19 @@ export function canFleetAction(
  );
 }

+/**
+ * Permanent-purge check for locomotives and wagons. Unlike
+ * {@link canFleetAction} this does NOT fall back to the coarse fleet:manage
+ * key — an irreversible delete needs its own grant, and the API guards these
+ * endpoints the same way.
+ */
+export function canFleetHardDelete(
+  user: AuthUser | null | undefined,
+  resource: "locomotives" | "wagons" | "routes",
+): boolean {
+  return hasPermission(user, FREIGHT_PERMS[resource].hardDelete);
+}
+
 export function isFreightAdmin(user: AuthUser | null | undefined): boolean {
  return hasPermission(user, FREIGHT_PERMS.admin);
 }
--- a/apps/edr-freight-web/backoffice/src/pages/contract_templates/ContractTemplateEditorPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contract_templates/ContractTemplateEditorPage.tsx
@@ -64,7 +64,7 @@ import type { ContractTemplateArticle } from "@/services/contract-templates.serv
 import { bodyToHtml, htmlToBody } from "./article-html";

 const BODY_HINT =
-  "Each paragraph becomes a numbered clause (1., 2., …) — use Indent to nest it as a sub-clause (1.1, 1.1.1). The bullet list makes • points under the clause above. Numbering is assigned when the document is generated, so it always comes out sequential. Placeholders are filled from the contract.";
+  "Enter starts a new line. Use the numbered list for clauses and Tab (or Indent) to nest — levels number 1. → a. → i. like a word processor. Numbering is assigned when the document is generated, so it always comes out sequential. Placeholders are filled from the contract.";

 interface ArticleDraft {
  id?: string;
@@ -350,6 +350,49 @@ function matchDepth(match: RegExpExecArray | null): number | null {
 /** Deepest supported sub-clause level. */
 const MAX_CLAUSE_DEPTH = 6;

+/** 1 → "a", 2 → "b", … 27 → "aa". Mirrors the API's `toAlpha`. */
+function toAlpha(n: number): string {
+  let out = "";
+  let value = n;
+  while (value > 0) {
+    const rem = (value - 1) % 26;
+    out = String.fromCharCode(97 + rem) + out;
+    value = Math.floor((value - 1) / 26);
+  }
+  return out || "a";
+}
+
+const ROMAN: Array<[number, string]> = [
+  [1000, "m"], [900, "cm"], [500, "d"], [400, "cd"],
+  [100, "c"], [90, "xc"], [50, "l"], [40, "xl"],
+  [10, "x"], [9, "ix"], [5, "v"], [4, "iv"], [1, "i"],
+];
+
+/** 1 → "i", 4 → "iv". Mirrors the API's `toRoman`. */
+function toRoman(n: number): string {
+  let value = n;
+  let out = "";
+  for (const [amount, numeral] of ROMAN) {
+    while (value >= amount) {
+      out += numeral;
+      value -= amount;
+    }
+  }
+  return out || "i";
+}
+
+/**
+ * Outline marker for a clause at its own level, cycling 1. → a. → i. by depth.
+ * Mirrors `clauseMarker` in the API's contract-article.util.ts — the preview
+ * must match the generated document exactly.
+ */
+function clauseMarker(counter: number, depth: number): string {
+  const style = (depth - 1) % 3;
+  if (style === 1) return toAlpha(counter);
+  if (style === 2) return toRoman(counter);
+  return String(counter);
+}
+
 /**
 * Mirror of the API renderer's rules (contract-article.util.ts): one clause per
 * line; a leading outline number ("2. ", "2.1 ") nests the line as a sub-clause
@@ -379,7 +422,7 @@ function parseArticleBody(body: string): ParsedBody {
    counters[depth - 1] += 1;
    clauses.push({
      text: match ? cleaned.slice(match[0].length).trim() : cleaned,
-      number: counters.slice(0, depth).join("."),
+      number: clauseMarker(counters[depth - 1], depth),
      depth,
      bullets: [],
    });
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
@@ -1,11 +1,16 @@
 import type { ColumnDef } from "@edr/ui-common";
-import { Box, Button, Card, Container, Group, Modal, Select, Stack, Text, Title } from "@mantine/core";
+import { Box, Button, Card, Container, Group, Modal, Select, Stack, Text, TextInput, Title } from "@mantine/core";
 import { DatePickerInput } from "@mantine/dates";
 import { keepPreviousData, useMutation, useQuery } from "@tanstack/react-query";

 import { api } from "@/services/api";
 import { useAuth } from "@/auth/useAuth";
-import { canFleetAction, hasPermission, FREIGHT_PERMS } from "@/lib/permissions";
+import {
+  canFleetAction,
+  canFleetHardDelete,
+  hasPermission,
+  FREIGHT_PERMS,
+} from "@/lib/permissions";
 import Breadcrumbs from "@/components/ui/Breadcrumbs";
 import { Inbox, Plus, Warehouse } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
@@ -31,6 +36,7 @@ import {
    type FleetResourceSlug,
 } from "@/pages/fleet/config/resources";
 import {
+  isFleetPurgeable,
  isFleetServerPaginated,
  type FleetListFilters,
  type FleetRecord,
@@ -49,6 +55,12 @@ const FleetResourcePage = () => {
  const canCreate = canFleetAction(user, slug, "create");
  const canUpdate = canFleetAction(user, slug, "update");
  const canDelete = canFleetAction(user, slug, "delete");
+  // Irreversible purge: only locomotives/wagons expose it, and it needs its own
+  // grant — the coarse fleet:manage key deliberately does not unlock it.
+  const canPurge =
+    isFleetPurgeable(slug) &&
+    (slug === "locomotives" || slug === "wagons") &&
+    canFleetHardDelete(user, slug);
  // Wagon transfer workspace: shown only to holders of a transfer capability
  // (raise a request, fulfill one, or see the cross-yard history).
  const canTransfer =
@@ -71,6 +83,10 @@ const FleetResourcePage = () => {
  const [formOpen, setFormOpen] = useState(false);
  const [editing, setEditing] = useState<FleetRecord | null>(null);
  const [removeTarget, setRemoveTarget] = useState<FleetRecord | null>(null);
+  const [purgeTarget, setPurgeTarget] = useState<FleetRecord | null>(null);
+  // Typing the record's own code is the confirmation — a purge cannot be undone,
+  // so a single misplaced click must not be enough to trigger it.
+  const [purgeConfirmText, setPurgeConfirmText] = useState("");
  const [assigningDriver, setAssigningDriver] = useState<FleetRecord | null>(null);
  const [historyTarget, setHistoryTarget] = useState<FleetRecord | null>(null);
  const [selectedDriver, setSelectedDriver] = useState<string>("");
@@ -142,6 +158,7 @@ const FleetResourcePage = () => {
  const create = useMutation(api.fleet.create.mutationOptions());
  const update = useMutation(api.fleet.update.mutationOptions());
  const remove = useMutation(api.fleet.remove.mutationOptions());
+  const purge = useMutation(api.fleet.purge.mutationOptions());

  const { data: wagonTypes = [], isLoading: wagonTypesLoading } = useQuery(
    api.wagonTypes.list.queryOptions(),
@@ -385,6 +402,7 @@ const FleetResourcePage = () => {
                : undefined
            }
            onRemove={canDelete ? setRemoveTarget : undefined}
+            onPurge={canPurge ? setPurgeTarget : undefined}
            onAssignDriver={canUpdate ? setAssigningDriver : undefined}
            onHistory={setHistoryTarget}
          />
@@ -446,6 +464,37 @@ const FleetResourcePage = () => {
    }
  };

+  /** The code the operator must retype to confirm a purge. */
+  const purgeFields = purgeTarget
+    ? (purgeTarget as unknown as Record<string, unknown>)
+    : null;
+  const purgeLabel = purgeFields
+    ? String(purgeFields.wagonNumber ?? purgeFields.code ?? "")
+    : "";
+
+  const closePurge = () => {
+    setPurgeTarget(null);
+    setPurgeConfirmText("");
+  };
+
+  const handlePurge = async () => {
+    if (!purgeTarget || !("id" in purgeTarget)) return;
+    try {
+      await purge.mutateAsync({ slug, id: String(purgeTarget.id) });
+      toast({ title: `${config.entityLabel} permanently deleted` });
+      closePurge();
+    } catch (err: unknown) {
+      const message =
+        (err as { response?: { data?: { message?: string } } })?.response?.data?.message ??
+        "Permanent delete failed";
+      toast({
+        title: "Permanent delete failed",
+        description: String(message),
+        variant: "destructive",
+      });
+    }
+  };
+
  const handleAssignDriver = async () => {
    if (!assigningDriver || !("id" in assigningDriver) || !selectedDriver) return;
    try {
@@ -673,6 +722,7 @@ const FleetResourcePage = () => {
                  : undefined
              }
              onRemove={canDelete ? setRemoveTarget : undefined}
+              onPurge={canPurge ? setPurgeTarget : undefined}
            />
          )}
        </Stack>
@@ -718,6 +768,48 @@ const FleetResourcePage = () => {
        </Stack>
      </Modal>

+      <Modal
+        opened={Boolean(purgeTarget)}
+        onClose={closePurge}
+        title={<Text fw={600}>Delete permanently</Text>}
+        radius="lg"
+        centered
+      >
+        <Stack gap="md">
+          <Text size="sm">
+            This permanently removes{" "}
+            <Text span fw={700}>
+              {purgeLabel || `this ${config.entityLabel.toLowerCase()}`}
+            </Text>{" "}
+            from the database. It cannot be undone.
+          </Text>
+          <Text size="sm" c="dimmed">
+            Only unused records can be purged — if it has any history or is still
+            referenced, the request is refused and you should use{" "}
+            {(config.removeActionLabel ?? "Delete").toLowerCase()} instead.
+          </Text>
+          <TextInput
+            label={`Type ${purgeLabel} to confirm`}
+            placeholder={purgeLabel}
+            value={purgeConfirmText}
+            onChange={(e) => setPurgeConfirmText(e.currentTarget.value)}
+          />
+          <Group justify="flex-end">
+            <Button variant="default" onClick={closePurge}>
+              Cancel
+            </Button>
+            <Button
+              color="red"
+              loading={purge.isPending}
+              disabled={purgeConfirmText.trim() !== purgeLabel || !purgeLabel}
+              onClick={handlePurge}
+            >
+              Delete permanently
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+
      <Modal
        opened={Boolean(assigningDriver)}
        onClose={() => {
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/RoutesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/RoutesPage.tsx
@@ -8,6 +8,7 @@ import {
  Plus,
  Route as RouteIcon,
  Trash2,
+  ShieldAlert,
 } from "lucide-react";
 import type { ColumnDef } from "@edr/ui-common";
 import {
@@ -23,6 +24,7 @@ import {
  SimpleGrid,
  Stack,
  Text,
+  TextInput,
  ThemeIcon,
  Tooltip,
 } from "@mantine/core";
@@ -38,7 +40,7 @@ import { ruleEngineTable } from "@/components/ruleEngine/ruleEngineStyles";
 import { api } from "@/services/api";
 import { ruleEngineService } from "@/services/ruleEngine/ruleEngine.service";
 import { useAuth } from "@/auth/useAuth";
-import { canFleetAction } from "@/lib/permissions";
+import { canFleetAction, canFleetHardDelete } from "@/lib/permissions";
 import { useToast } from "@/hooks/use-toast";
 import {
  formatRouteLabel,
@@ -168,6 +170,14 @@ export default function RoutesPage() {
  const canCreate = canFleetAction(user, "routes", "create");
  const canUpdate = canFleetAction(user, "routes", "update");
  const canDelete = canFleetAction(user, "routes", "delete");
+  // Irreversible purge needs its own grant — the coarse fleet:manage key that
+  // canFleetAction accepts deliberately does not unlock it.
+  const canPurge = canFleetHardDelete(user, "routes");
+  // Both destructive actions confirm first: deactivate is recoverable but still
+  // changes what operations can book, and a purge cannot be undone at all.
+  const [deactivateTarget, setDeactivateTarget] = useState<RouteRecord | null>(null);
+  const [purgeTarget, setPurgeTarget] = useState<RouteRecord | null>(null);
+  const [purgeConfirmText, setPurgeConfirmText] = useState("");

  const routesQuery = useQuery({
    ...api.routes.listPaged.queryOptions({
@@ -202,6 +212,7 @@ export default function RoutesPage() {
  const createMutation = useMutation(api.routes.create.mutationOptions());
  const updateMutation = useMutation(api.routes.update.mutationOptions());
  const deactivateMutation = useMutation(api.routes.deactivate.mutationOptions());
+  const purgeMutation = useMutation(api.routes.purge.mutationOptions());

  // Narrowing the result set can strand the user on a page that no longer
  // exists (search down to 3 rows while on page 5 → empty table).
@@ -353,15 +364,40 @@ export default function RoutesPage() {
    }
  };

-  const handleDeactivate = async (route: RouteRecord) => {
+  const handleDeactivate = async () => {
+    if (!deactivateTarget) return;
    try {
-      await deactivateMutation.mutateAsync(route.id);
+      await deactivateMutation.mutateAsync(deactivateTarget.id);
      toast({ title: "Route marked stop working" });
+      setDeactivateTarget(null);
    } catch {
      toast({ title: "Update failed", description: "Could not update route status", variant: "destructive" });
    }
  };

+  const closePurge = () => {
+    setPurgeTarget(null);
+    setPurgeConfirmText("");
+  };
+
+  /** The label the operator must retype to confirm an irreversible purge. */
+  const purgeLabel = purgeTarget ? formatRouteLabel(purgeTarget) : "";
+
+  const handlePurge = async () => {
+    if (!purgeTarget) return;
+    try {
+      await purgeMutation.mutateAsync(purgeTarget.id);
+      toast({ title: "Route permanently deleted" });
+      closePurge();
+    } catch (error) {
+      toast({
+        title: "Permanent delete failed",
+        description: normalizeRouteError(error),
+        variant: "destructive",
+      });
+    }
+  };
+
  const handleStatusChange = async (route: RouteRecord, status: RouteStatus) => {
    try {
      await updateMutation.mutateAsync({ id: route.id, data: { status } });
@@ -465,17 +501,29 @@ export default function RoutesPage() {
                  variant="subtle"
                  color="red"
                  disabled={row.original.status === "STOP_WORKING" || deactivateMutation.isPending}
-                  onClick={() => handleDeactivate(row.original)}
+                  onClick={() => setDeactivateTarget(row.original)}
                >
                  <Trash2 size={16} />
                </ActionIcon>
              </Tooltip>
            ) : null}
+            {canPurge ? (
+              <Tooltip label="Delete permanently">
+                <ActionIcon
+                  variant="subtle"
+                  color="red"
+                  disabled={purgeMutation.isPending}
+                  onClick={() => setPurgeTarget(row.original)}
+                >
+                  <ShieldAlert size={16} />
+                </ActionIcon>
+              </Tooltip>
+            ) : null}
          </Group>
        ),
      },
    ];
-  }, [deactivateMutation.isPending, canUpdate, canDelete]);
+  }, [deactivateMutation.isPending, purgeMutation.isPending, canUpdate, canDelete, canPurge]);

  return (
    <PageContainer>
@@ -696,6 +744,78 @@ export default function RoutesPage() {
        </form>
      </Modal>

+      <Modal
+        opened={Boolean(deactivateTarget)}
+        onClose={() => setDeactivateTarget(null)}
+        title={<Text fw={600}>Mark stop working</Text>}
+        radius="lg"
+        centered
+      >
+        <Stack gap="md">
+          <Text size="sm">
+            Stop new operations on{" "}
+            <Text span fw={700}>
+              {deactivateTarget ? formatRouteLabel(deactivateTarget) : ""}
+            </Text>
+            ? The route keeps its history and can no longer be booked.
+          </Text>
+          <Group justify="flex-end">
+            <Button variant="default" onClick={() => setDeactivateTarget(null)}>
+              Cancel
+            </Button>
+            <Button
+              color="red"
+              loading={deactivateMutation.isPending}
+              onClick={handleDeactivate}
+            >
+              Mark stop working
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+
+      <Modal
+        opened={Boolean(purgeTarget)}
+        onClose={closePurge}
+        title={<Text fw={600}>Delete permanently</Text>}
+        radius="lg"
+        centered
+      >
+        <Stack gap="md">
+          <Text size="sm">
+            This permanently removes{" "}
+            <Text span fw={700}>
+              {purgeLabel}
+            </Text>{" "}
+            and its stops from the database. It cannot be undone.
+          </Text>
+          <Text size="sm" c="dimmed">
+            Only unused routes can be purged — if any train schedule still
+            references it, the request is refused and you should mark it stop
+            working instead.
+          </Text>
+          <TextInput
+            label="Type the route to confirm"
+            placeholder={purgeLabel}
+            value={purgeConfirmText}
+            onChange={(e) => setPurgeConfirmText(e.currentTarget.value)}
+          />
+          <Group justify="flex-end">
+            <Button variant="default" onClick={closePurge}>
+              Cancel
+            </Button>
+            <Button
+              color="red"
+              loading={purgeMutation.isPending}
+              disabled={purgeConfirmText.trim() !== purgeLabel || !purgeLabel}
+              onClick={handlePurge}
+            >
+              Delete permanently
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+
      <Modal
        opened={Boolean(viewing)}
        onClose={() => setViewing(null)}
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -1605,6 +1605,15 @@ export const api = {
      undefined,
      () => [["routes"]],
    ),
+
+    /** Irreversible purge — refused while any train schedule uses the route. */
+    purge: endpoint<string, void>(
+      "routes",
+      "purge",
+      (id) => routesService.purge(id).then(() => undefined),
+      undefined,
+      () => [["routes"]],
+    ),
  },

  stations: {
@@ -2194,6 +2203,15 @@ export const api = {
      undefined,
      ({ slug }) => [QUERY_KEYS.FLEET.list(slug)],
    ),
+
+    /** Irreversible purge — locomotives and wagons only. */
+    purge: endpoint<{ slug: FleetResourceSlug; id: string }, unknown>(
+      "fleet",
+      "purge",
+      ({ slug, id }) => fleetService.purge(slug, id),
+      undefined,
+      ({ slug }) => [QUERY_KEYS.FLEET.list(slug)],
+    ),
  },

  truckTypes: {
--- a/apps/edr-freight-web/backoffice/src/services/fleet/fleet.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/fleet/fleet.service.ts
@@ -77,6 +77,21 @@ const removeHandlers: Record<FleetResourceSlug, (id: string) => Promise<unknown>
  drivers: (id) => driversService.delete(id),
 };

+/**
+ * Permanent purge, only for the two slugs that expose it. Everything else stays
+ * soft-delete/decommission only, so there is deliberately no entry here.
+ */
+const purgeHandlers: Partial<
+  Record<FleetResourceSlug, (id: string) => Promise<unknown>>
+> = {
+  locomotives: (id) => locomotivesService.purge(id),
+  wagons: (id) => wagonService.purge(id),
+};
+
+/** True when the slug supports an irreversible purge. */
+export const isFleetPurgeable = (slug: FleetResourceSlug) =>
+  slug in purgeHandlers;
+
 export const fleetService = {
  list: (slug: FleetResourceSlug, filters?: FleetListFilters) => listHandlers[slug](filters),
  /** Only for slugs in `pagedHandlers` — guard with `isFleetServerPaginated`. */
@@ -89,4 +104,11 @@ export const fleetService = {
  update: (slug: FleetResourceSlug, id: string, data: Record<string, unknown>) =>
    updateHandlers[slug](id, data),
  remove: (slug: FleetResourceSlug, id: string) => removeHandlers[slug](id),
+  purge: (slug: FleetResourceSlug, id: string) => {
+    const handler = purgeHandlers[slug];
+    if (!handler) {
+      throw new Error(`Fleet resource "${slug}" cannot be permanently deleted`);
+    }
+    return handler(id);
+  },
 };
--- a/apps/edr-freight-web/backoffice/src/services/locomotives.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/locomotives.service.ts
@@ -85,4 +85,7 @@ export const locomotivesService = {
  update: (id: string, data: Partial<SaveLocomotivePayload>) =>
    apiClient.patch(URL_CONSTANTS.LOCOMOTIVES.BY_ID(id), data),
  decommission: (id: string) => apiClient.post(URL_CONSTANTS.LOCOMOTIVES.DECOMMISSION(id), {}),
+  /** Irreversible purge — the API refuses it while any train references the loco. */
+  purge: (id: string) =>
+    apiClient.delete(`${URL_CONSTANTS.LOCOMOTIVES.BY_ID(id)}/permanent`),
 };
--- a/apps/edr-freight-web/backoffice/src/services/routes.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/routes.service.ts
@@ -101,6 +101,9 @@ export const routesService = {
  update: (id: string, data: Partial<SaveRoutePayload>) =>
    apiClient.patch(URL_CONSTANTS.ROUTES.BY_ID(id), data),
  deactivate: (id: string) => apiClient.delete(URL_CONSTANTS.ROUTES.BY_ID(id)),
+  /** Irreversible purge — the API refuses it while any train schedule uses the route. */
+  purge: (id: string) =>
+    apiClient.delete(`${URL_CONSTANTS.ROUTES.BY_ID(id)}/permanent`),
  /** All active yards (page-walked — the yards list API caps pageSize at 100). */
  getYards: async (): Promise<YardRef[]> => {
    const rows = await ruleEngineService.listAll("yards", { isActive: true });
--- a/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
@@ -123,6 +123,8 @@ export const wagonService = {
  create: (data: Partial<Wagon>) => apiClient.post('/wagons', data),
  update: (id: string, data: Partial<Wagon>) => apiClient.patch(`/wagons/${id}`, data),
  delete: (id: string) => apiClient.delete(`/wagons/${id}`),
+  /** Irreversible purge — the API refuses it when the wagon has any history. */
+  purge: (id: string) => apiClient.delete(`/wagons/${id}/permanent`),
  /** Relocate many wagons to one yard in a single call (writes movement ledger). */
  bulkTransfer: (wagonIds: string[], toYardId: string) =>
    apiClient.post<{ moved: number }>('/wagons/bulk-transfer', { wagonIds, toYardId }),