@open-mercato/core 0.6.5-develop.4516.1.88e6ab71a9 → 0.6.5-develop.4544.1.71c003c861

package/src/modules/sales/components/documents/ItemsSection.tsx

@@ -1,7 +1,8 @@
 "use client";
 
 import * as React from "react";
-import { apiCall } from "@open-mercato/ui/backend/utils/apiCall";
+import { apiCall, withScopedApiRequestHeaders } from "@open-mercato/ui/backend/utils/apiCall";
+import { buildOptimisticLockHeader } from "@open-mercato/ui/backend/utils/optimisticLock";
 import { deleteCrud } from "@open-mercato/ui/backend/utils/crud";
 import { normalizeCrudServerError } from "@open-mercato/ui/backend/utils/serverErrors";
 import { LoadingMessage, TabEmptyState } from "@open-mercato/ui/backend/detail";
@@ -19,6 +20,7 @@ import { useOrganizationScopeDetail } from "@open-mercato/shared/lib/frontend/us
 import { useConfirmDialog } from "@open-mercato/ui/backend/confirm-dialog";
 import { emitSalesDocumentTotalsRefresh } from "@open-mercato/core/modules/sales/lib/frontend/documentTotalsEvents";
 import { LineItemDialog } from "./LineItemDialog";
+import { handleSectionMutationError } from "./optimisticLock";
 import type { SalesLineRecord } from "./lineItemTypes";
 import { formatMoney, normalizeNumber } from "./lineItemUtils";
 import type { SectionAction } from "@open-mercato/ui/backend/detail";
@@ -109,6 +111,7 @@ type SalesDocumentItemsSectionProps = {
   documentId: string;
   kind: "order" | "quote";
   currencyCode: string | null | undefined;
+  documentUpdatedAt?: string | null;
   organizationId?: string | null;
   tenantId?: string | null;
   onActionChange?: (action: SectionAction | null) => void;
@@ -119,6 +122,7 @@ export function SalesDocumentItemsSection({
   documentId,
   kind,
   currencyCode,
+  documentUpdatedAt,
   organizationId: orgFromProps,
   tenantId: tenantFromProps,
   onActionChange,
@@ -449,24 +453,29 @@ export function SalesDocumentItemsSection({
       });
       if (!confirmed) return;
       try {
-        const result = await deleteCrud(resourcePath, {
-          body: {
-            id: line.id,
-            [documentKey]: documentId,
-            organizationId: resolvedOrganizationId ?? undefined,
-            tenantId: resolvedTenantId ?? undefined,
-          },
-          errorMessage: t(
-            "sales.documents.items.errorDelete",
-            "Failed to delete line.",
-          ),
-        });
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(documentUpdatedAt),
+          () =>
+            deleteCrud(resourcePath, {
+              body: {
+                id: line.id,
+                [documentKey]: documentId,
+                organizationId: resolvedOrganizationId ?? undefined,
+                tenantId: resolvedTenantId ?? undefined,
+              },
+              errorMessage: t(
+                "sales.documents.items.errorDelete",
+                "Failed to delete line.",
+              ),
+            }),
+        );
         if (result.ok) {
           flash(t("sales.documents.items.deleted", "Line removed."), "success");
           await loadItems();
           emitSalesDocumentTotalsRefresh({ documentId, kind });
         }
       } catch (err) {
+        if (handleSectionMutationError(err, t, () => void loadItems())) return;
         console.error("sales.document.items.delete", err);
         const normalized = normalizeCrudServerError(err);
         const fallback = t(
@@ -480,6 +489,7 @@ export function SalesDocumentItemsSection({
       confirm,
       documentId,
       documentKey,
+      documentUpdatedAt,
       kind,
       loadItems,
       resolvedOrganizationId,
@@ -800,6 +810,7 @@ export function SalesDocumentItemsSection({
         kind={kind}
         documentId={documentId}
         currencyCode={currencyCode}
+        documentUpdatedAt={documentUpdatedAt}
         organizationId={resolvedOrganizationId}
         tenantId={resolvedTenantId}
         initialLine={lineForEdit}

package/src/modules/sales/components/documents/LineItemDialog.tsx

@@ -12,9 +12,11 @@ import {
   type CrudCustomFieldRenderProps,
 } from "@open-mercato/ui/backend/CrudForm";
 import { collectCustomFieldValues } from "@open-mercato/ui/backend/utils/customFieldValues";
-import { apiCall } from "@open-mercato/ui/backend/utils/apiCall";
+import { apiCall, withScopedApiRequestHeaders } from "@open-mercato/ui/backend/utils/apiCall";
+import { buildOptimisticLockHeader } from "@open-mercato/ui/backend/utils/optimisticLock";
 import { createCrud, updateCrud } from "@open-mercato/ui/backend/utils/crud";
 import { createCrudFormError } from "@open-mercato/ui/backend/utils/serverErrors";
+import { handleSectionMutationError } from "./optimisticLock";
 import {
   Dialog,
   DialogContent,
@@ -233,6 +235,7 @@ type SalesLineDialogProps = {
   kind: "order" | "quote";
   documentId: string;
   currencyCode: string | null | undefined;
+  documentUpdatedAt?: string | null;
   organizationId: string | null;
   tenantId: string | null;
   initialLine?: SalesLineRecord | null;
@@ -426,6 +429,7 @@ export function LineItemDialog({
   kind,
   documentId,
   currencyCode,
+  documentUpdatedAt,
   organizationId,
   tenantId,
   initialLine,
@@ -1445,21 +1449,33 @@ export function LineItemDialog({
 
       try {
         const action = editingId ? updateCrud : createCrud;
-        const result = await action(
-          resourcePath,
-          editingId ? { id: editingId, ...payload } : payload,
-          {
-            errorMessage: t(
-              "sales.documents.items.errorSave",
-              "Failed to save line.",
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(documentUpdatedAt),
+          () =>
+            action(
+              resourcePath,
+              editingId ? { id: editingId, ...payload } : payload,
+              {
+                errorMessage: t(
+                  "sales.documents.items.errorSave",
+                  "Failed to save line.",
+                ),
+              },
             ),
-          },
         );
         if (result.ok) {
           if (onSaved) await onSaved();
           closeDialog();
         }
       } catch (err) {
+        if (
+          handleSectionMutationError(err, t, () => {
+            if (onSaved) void onSaved();
+          })
+        ) {
+          closeDialog();
+          return;
+        }
         throw err;
       }
     },
@@ -1467,6 +1483,7 @@ export function LineItemDialog({
       currencyCode,
       documentId,
       documentKey,
+      documentUpdatedAt,
       editingId,
       priceOptions,
       productOption,

package/src/modules/sales/components/documents/PaymentDialog.tsx

@@ -4,10 +4,12 @@ import * as React from 'react'
 import { CreditCard } from 'lucide-react'
 import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
 import { LookupSelect, type LookupSelectItem } from '@open-mercato/ui/backend/inputs'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { createCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { handleSectionMutationError, rowOptimisticVersion } from './optimisticLock'
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
 import { useDialogKeyHandler } from '@open-mercato/ui/hooks/useDialogKeyHandler'
 import { Input } from '@open-mercato/ui/primitives/input'
@@ -24,6 +26,7 @@ export type PaymentTotals = {
 
 export type PaymentFormData = {
   id?: string | null
+  updatedAt?: string | null
   amount?: number | string | null
   paymentMethodId?: string | null
   paymentReference?: string | null
@@ -534,23 +537,39 @@ export function PaymentDialog({
       if (Object.keys(customFields).length) payload.customFields = customFields
 
       const action = payment?.id ? updateCrud : createCrud
-      const result = await action(
-        'sales/payments',
-        payment?.id ? { id: payment.id, ...payload } : payload,
-        {
-          errorMessage: t('sales.documents.payments.errorSave', 'Failed to save payment.'),
+      try {
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(payment?.id ? rowOptimisticVersion(payment) : undefined),
+          () =>
+            action(
+              'sales/payments',
+              payment?.id ? { id: payment.id, ...payload } : payload,
+              {
+                errorMessage: t('sales.documents.payments.errorSave', 'Failed to save payment.'),
+              }
+            )
+        )
+        if (result.ok) {
+          const totals = (result.result as any)?.orderTotals as PaymentTotals | undefined
+          if (onSaved) {
+            await onSaved(totals ?? null)
+          }
+          setFormResetKey((prev) => prev + 1)
+          onOpenChange(false)
         }
-      )
-      if (result.ok) {
-        const totals = (result.result as any)?.orderTotals as PaymentTotals | undefined
-        if (onSaved) {
-          await onSaved(totals ?? null)
+      } catch (err) {
+        if (
+          handleSectionMutationError(err, t, () => {
+            if (onSaved) void onSaved()
+          })
+        ) {
+          onOpenChange(false)
+          return
         }
-        setFormResetKey((prev) => prev + 1)
-        onOpenChange(false)
+        throw err
       }
     },
-    [currencyCode, mode, onOpenChange, onSaved, orderId, organizationId, payment?.id, t, tenantId]
+    [currencyCode, mode, onOpenChange, onSaved, orderId, organizationId, payment?.id, payment?.updatedAt, t, tenantId]
   )
 
   const handleSubmitForm = React.useCallback(

package/src/modules/sales/components/documents/PaymentsSection.tsx

@@ -4,8 +4,10 @@ import * as React from 'react'
 import type { ColumnDef } from '@tanstack/react-table'
 import { DataTable } from '@open-mercato/ui/backend/DataTable'
 import { LoadingMessage, ErrorMessage, TabEmptyState } from '@open-mercato/ui/backend/detail'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { handleSectionMutationError, readRowUpdatedAt, rowOptimisticVersion } from './optimisticLock'
 import type { SectionAction } from '@open-mercato/ui/backend/detail'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -19,6 +21,7 @@ import { Plus } from 'lucide-react'
 
 type PaymentRow = {
   id: string
+  updatedAt: string | null
   paymentReference: string | null
   paymentMethodId: string | null
   paymentMethodName: string | null
@@ -108,6 +111,7 @@ export function SalesDocumentPaymentsSection({
               : {}
           const record: PaymentRow = {
             id: item.id,
+            updatedAt: readRowUpdatedAt(item),
             paymentReference: typeof item.payment_reference === 'string' ? item.payment_reference : null,
             paymentMethodId: typeof item.payment_method_id === 'string' ? item.payment_method_id : null,
             paymentMethodName:
@@ -183,6 +187,7 @@ export function SalesDocumentPaymentsSection({
     (record: PaymentRow) => {
       setEditingPayment({
         id: record.id,
+        updatedAt: record.updatedAt ?? null,
         amount: record.amount ?? '',
         paymentMethodId: record.paymentMethodId ?? '',
         paymentReference: record.paymentReference ?? '',
@@ -210,15 +215,19 @@ export function SalesDocumentPaymentsSection({
   const handleDelete = React.useCallback(
     async (row: PaymentRow) => {
       try {
-        const result = await deleteCrud<{ orderTotals?: PaymentTotals | null }>('sales/payments', {
-          body: {
-            id: row.id,
-            orderId,
-            organizationId: resolvedOrganizationId ?? undefined,
-            tenantId: resolvedTenantId ?? undefined,
-          },
-          errorMessage: t('sales.documents.payments.errorDelete', 'Failed to delete payment.'),
-        })
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(rowOptimisticVersion(row)),
+          () =>
+            deleteCrud<{ orderTotals?: PaymentTotals | null }>('sales/payments', {
+              body: {
+                id: row.id,
+                orderId,
+                organizationId: resolvedOrganizationId ?? undefined,
+                tenantId: resolvedTenantId ?? undefined,
+              },
+              errorMessage: t('sales.documents.payments.errorDelete', 'Failed to delete payment.'),
+            })
+        )
         if (result.ok) {
           onTotalsChange?.()
           flash(t('sales.documents.payments.deleted', 'Payment deleted.'), 'success')
@@ -226,6 +235,9 @@ export function SalesDocumentPaymentsSection({
           emitSalesDocumentTotalsRefresh({ documentId: orderId, kind: 'order' })
         }
       } catch (err) {
+        if (handleSectionMutationError(err, t, () => void loadPayments())) {
+          return
+        }
         console.error('sales.payments.delete', err)
         flash(t('sales.documents.payments.errorDelete', 'Failed to delete payment.'), 'error')
       }

package/src/modules/sales/components/documents/ReturnDialog.tsx

@@ -8,10 +8,12 @@ import { Textarea } from '@open-mercato/ui/primitives/textarea'
 import { Label } from '@open-mercato/ui/primitives/label'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
-import { apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { computeAvailableReturnQuantity } from '@open-mercato/core/modules/sales/lib/returnQuantity'
+import { handleSectionMutationError } from './optimisticLock'
 
 export type ReturnOrderLine = {
   id: string
@@ -26,6 +28,7 @@ type ReturnDialogProps = {
   open: boolean
   orderId: string
   lines: ReturnOrderLine[]
+  documentUpdatedAt?: string | null
   onClose: () => void
   onSaved: () => Promise<void>
 }
@@ -39,7 +42,7 @@ const normalizeNumber = (value: unknown): number => {
   return 0
 }
 
-export function ReturnDialog({ open, orderId, lines, onClose, onSaved }: ReturnDialogProps) {
+export function ReturnDialog({ open, orderId, lines, documentUpdatedAt, onClose, onSaved }: ReturnDialogProps) {
   const t = useT()
   const { runMutation } = useGuardedMutation({ contextId: `sales-returns-${orderId}` })
   const [reason, setReason] = React.useState('')
@@ -104,19 +107,23 @@ export function ReturnDialog({ open, orderId, lines, onClose, onSaved }: ReturnD
         context: { kind: 'order', record: { id: orderId } },
         mutationPayload: { orderId, lines: linesForRequest, reason, notes },
         operation: async () => {
-          const response = await apiCallOrThrow<{ id: string | null }>(
-            '/api/sales/returns',
-            {
-              method: 'POST',
-              headers: { 'content-type': 'application/json' },
-              body: JSON.stringify({
-                orderId,
-                lines: linesForRequest,
-                ...(reason.trim().length ? { reason: reason.trim() } : {}),
-                ...(notes.trim().length ? { notes: notes.trim() } : {}),
-              }),
-            },
-            { errorMessage: t('sales.returns.errors.create', 'Failed to create return.') },
+          const response = await withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(documentUpdatedAt),
+            () =>
+              apiCallOrThrow<{ id: string | null }>(
+                '/api/sales/returns',
+                {
+                  method: 'POST',
+                  headers: { 'content-type': 'application/json' },
+                  body: JSON.stringify({
+                    orderId,
+                    lines: linesForRequest,
+                    ...(reason.trim().length ? { reason: reason.trim() } : {}),
+                    ...(notes.trim().length ? { notes: notes.trim() } : {}),
+                  }),
+                },
+                { errorMessage: t('sales.returns.errors.create', 'Failed to create return.') },
+              ),
           )
           return response.result?.id ?? null
         },
@@ -124,12 +131,16 @@ export function ReturnDialog({ open, orderId, lines, onClose, onSaved }: ReturnD
       flash(t('sales.returns.created', 'Return created.'), 'success')
       onClose()
       await onSaved()
-    } catch {
+    } catch (err) {
+      if (handleSectionMutationError(err, t, () => void onSaved())) {
+        onClose()
+        return
+      }
       flash(t('sales.returns.errors.create', 'Failed to create return.'), 'error')
     } finally {
       setSaving(false)
     }
-  }, [availableLines, notes, onClose, onSaved, orderId, quantities, reason, runMutation, saving, t])
+  }, [availableLines, documentUpdatedAt, notes, onClose, onSaved, orderId, quantities, reason, runMutation, saving, t])
 
   const onKeyDown = React.useCallback(
     (e: React.KeyboardEvent) => {

package/src/modules/sales/components/documents/ReturnsSection.tsx

@@ -26,6 +26,7 @@ type ReturnRow = {
 type SalesReturnsSectionProps = {
   orderId: string
   currencyCode?: string | null
+  documentUpdatedAt?: string | null
 }
 
 function formatDisplayDate(value: string | null | undefined): string | null {
@@ -35,7 +36,7 @@ function formatDisplayDate(value: string | null | undefined): string | null {
   return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium' }).format(date)
 }
 
-export function SalesReturnsSection({ orderId, currencyCode }: SalesReturnsSectionProps) {
+export function SalesReturnsSection({ orderId, currencyCode, documentUpdatedAt }: SalesReturnsSectionProps) {
   const t = useT()
   const [returns, setReturns] = React.useState<ReturnRow[]>([])
   const [lines, setLines] = React.useState<ReturnOrderLine[]>([])
@@ -208,6 +209,7 @@ export function SalesReturnsSection({ orderId, currencyCode }: SalesReturnsSecti
           open={dialogOpen}
           orderId={orderId}
           lines={lines}
+          documentUpdatedAt={documentUpdatedAt}
           onClose={() => setDialogOpen(false)}
           onSaved={async () => {
             emitSalesDocumentTotalsRefresh({ documentId: orderId, kind: 'order' })
@@ -258,6 +260,7 @@ export function SalesReturnsSection({ orderId, currencyCode }: SalesReturnsSecti
         open={dialogOpen}
         orderId={orderId}
         lines={lines}
+        documentUpdatedAt={documentUpdatedAt}
         onClose={() => setDialogOpen(false)}
         onSaved={async () => {
           emitSalesDocumentTotalsRefresh({ documentId: orderId, kind: 'order' })

package/src/modules/sales/components/documents/SalesDocumentsTable.tsx

@@ -9,7 +9,8 @@ import { DataTable, type DataTableExportFormat, withDataTableNamespaces } from '
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { buildCrudExportUrl, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -76,6 +77,7 @@ type SalesDocumentRow = {
   totalGross?: number | null
   currency?: string | null
   date?: string | null
+  updatedAt?: string | null
 }
 
 const PAGE_SIZE = 20
@@ -464,6 +466,7 @@ export function SalesDocumentsTable({ kind }: { kind: SalesDocumentKind }) {
         totalGross,
         currency: doc.currencyCode ?? null,
         date,
+        updatedAt: doc.updatedAt ?? null,
       }, item)
     },
     [kind]
@@ -540,9 +543,13 @@ export function SalesDocumentsTable({ kind }: { kind: SalesDocumentKind }) {
       })
       if (!confirmed) return
       try {
-        const result = await deleteCrud(`sales/${resource}`, row.id, {
-          errorMessage: t('sales.documents.list.table.deleteError', 'Failed to delete document.'),
-        })
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(row.updatedAt),
+          () =>
+            deleteCrud(`sales/${resource}`, row.id, {
+              errorMessage: t('sales.documents.list.table.deleteError', 'Failed to delete document.'),
+            }),
+        )
         if (result.ok) {
           flash(
             kind === 'order'

package/src/modules/sales/components/documents/ShipmentDialog.tsx

@@ -10,10 +10,12 @@ import { Label } from '@open-mercato/ui/primitives/label'
 import { Switch } from '@open-mercato/ui/primitives/switch'
 import { CrudForm, type CrudCustomFieldRenderProps, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
 import { LookupSelect, type LookupSelectItem } from '@open-mercato/ui/backend/inputs'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { createCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { handleSectionMutationError, rowOptimisticVersion } from './optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { cn } from '@open-mercato/shared/lib/utils'
 import { E } from '#generated/entities.ids.generated'
@@ -973,13 +975,25 @@ export function ShipmentDialog({
       }
 
       const action = shipment?.id ? updateCrud : createCrud
-      const result = await action(
-        'sales/shipments',
-        shipment?.id ? { id: shipment.id, ...payload } : payload,
-        {
-          errorMessage: t('sales.documents.shipments.errorSave', 'Failed to save shipment.'),
-        },
-      )
+      let result
+      try {
+        result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(shipment?.id ? rowOptimisticVersion(shipment) : undefined),
+          () =>
+            action(
+              'sales/shipments',
+              shipment?.id ? { id: shipment.id, ...payload } : payload,
+              {
+                errorMessage: t('sales.documents.shipments.errorSave', 'Failed to save shipment.'),
+              },
+            ),
+        )
+      } catch (err) {
+        if (handleSectionMutationError(err, t, () => void onSaved())) {
+          return
+        }
+        throw err
+      }
       if (result.ok) {
         const shipmentId = ((result.result as any)?.id as string | undefined) ?? shipment?.id ?? null
         const shouldAddShippingAdjustment =
@@ -1101,6 +1115,7 @@ export function ShipmentDialog({
       orderId,
       organizationId,
       shipment?.id,
+      shipment?.updatedAt,
       addressOptions,
       addressOptionsMap,
       shippingMethods,

package/src/modules/sales/components/documents/ShipmentsSection.tsx

@@ -6,7 +6,8 @@ import { Button } from '@open-mercato/ui/primitives/button'
 import { Badge } from '@open-mercato/ui/primitives/badge'
 import { ErrorMessage, LoadingMessage, TabEmptyState } from '@open-mercato/ui/backend/detail'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { useOrganizationScopeDetail } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -19,6 +20,7 @@ import type { SectionAction } from '@open-mercato/core/modules/customers/compone
 import { generateTempId } from '@open-mercato/core/modules/customers/lib/detailHelpers'
 import { formatAddressString, type AddressValue } from '@open-mercato/core/modules/customers/utils/addressFormat'
 import { ShipmentDialog } from './ShipmentDialog'
+import { handleSectionMutationError, readRowUpdatedAt, rowOptimisticVersion } from './optimisticLock'
 import { extractCustomFieldValues } from './customFieldHelpers'
 import type { OrderLine, ShipmentRow, ShipmentItem } from './shipmentTypes'
 
@@ -267,6 +269,7 @@ export function SalesShipmentsSection({
           const customValues = extractCustomFieldValues(item as Record<string, unknown>)
           return {
             id,
+            updatedAt: readRowUpdatedAt(item),
             shipmentNumber:
               typeof (item as any).shipment_number === 'string'
                 ? (item as any).shipment_number
@@ -397,20 +400,27 @@ export function SalesShipmentsSection({
       })
       if (!confirmed) return
       try {
-        const result = await deleteCrud('sales/shipments', {
-          body: {
-            id: shipment.id,
-            orderId,
-            organizationId: resolvedOrganizationId,
-            tenantId: resolvedTenantId,
-          },
-          errorMessage: t('sales.documents.shipments.errorDelete', 'Failed to delete shipment.'),
-        })
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(rowOptimisticVersion(shipment)),
+          () =>
+            deleteCrud('sales/shipments', {
+              body: {
+                id: shipment.id,
+                orderId,
+                organizationId: resolvedOrganizationId,
+                tenantId: resolvedTenantId,
+              },
+              errorMessage: t('sales.documents.shipments.errorDelete', 'Failed to delete shipment.'),
+            })
+        )
         if (result.ok) {
           await loadShipments()
           emitSalesDocumentTotalsRefresh({ documentId: orderId, kind: 'order' })
         }
       } catch (err) {
+        if (handleSectionMutationError(err, t, () => void loadShipments())) {
+          return
+        }
         console.error('sales.shipments.delete', err)
         flash(t('sales.documents.shipments.errorDelete', 'Failed to delete shipment.'), 'error')
       }

package/src/modules/sales/components/documents/optimisticLock.ts

@@ -0,0 +1,34 @@
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+
+type Translate = (key: string, fallback?: string) => string
+
+export function rowOptimisticVersion(row: { updatedAt?: string | null } | null | undefined): string | undefined {
+  const value = row?.updatedAt
+  return typeof value === 'string' && value.length ? value : undefined
+}
+
+/**
+ * Read a row's `updated_at` / `updatedAt` version from an untyped API record
+ * without `any`. Returns `null` when neither key holds a non-empty string.
+ */
+export function readRowUpdatedAt(source: unknown): string | null {
+  if (!source || typeof source !== 'object') return null
+  const record = source as Record<string, unknown>
+  const snake = record.updated_at
+  if (typeof snake === 'string' && snake.length) return snake
+  const camel = record.updatedAt
+  if (typeof camel === 'string' && camel.length) return camel
+  return null
+}
+
+export function handleSectionMutationError(
+  err: unknown,
+  t: Translate,
+  refresh: () => void,
+): boolean {
+  if (surfaceRecordConflict(err, t, { onRefresh: refresh })) {
+    refresh()
+    return true
+  }
+  return false
+}

package/src/modules/sales/components/documents/shipmentTypes.ts

@@ -9,6 +9,7 @@ export type ShipmentItem = {
 
 export type ShipmentRow = {
   id: string
+  updatedAt: string | null
   shipmentNumber: string | null
   shippingMethodId: string | null
   shippingMethodCode: string | null