@open-mercato/core 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4559.1.839e136509

package/src/modules/sales/components/channels/SalesChannelOffersPanel.tsx

@@ -9,7 +9,8 @@ import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { BooleanIcon } from '@open-mercato/ui/backend/ValueIcons'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, 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 { useT } from '@open-mercato/shared/lib/i18n/context'
 import { mapOfferRow, renderOfferPriceSummary, type OfferRow } from './offerTableUtils'
@@ -123,9 +124,11 @@ export function SalesChannelOffersPanel({ channelId, channelName }: { channelId:
 
   const handleDelete = React.useCallback(async (row: OfferRow) => {
     try {
-      await deleteCrud('catalog/offers', row.id, {
-        errorMessage: t('sales.channels.offers.errors.delete', 'Failed to delete offer.'),
-      })
+      await withScopedApiRequestHeaders(buildOptimisticLockHeader(row.updatedAt), () =>
+        deleteCrud('catalog/offers', row.id, {
+          errorMessage: t('sales.channels.offers.errors.delete', 'Failed to delete offer.'),
+        }),
+      )
       flash(t('sales.channels.offers.messages.deleted', 'Offer deleted.'), 'success')
       setReloadToken((token) => token + 1)
     } catch (err) {

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

@@ -4,7 +4,8 @@
 
 import * as React from 'react'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { createCrud } from '@open-mercato/ui/backend/utils/crud'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { ErrorMessage, LoadingMessage, TabEmptyState } from '@open-mercato/ui/backend/detail'
@@ -691,14 +692,17 @@ export function SalesDocumentAddressesSection({
       }
       await runGuardedMutation(
         () =>
-          apiCallOrThrow(
-            '/api/sales/document-addresses',
-            {
-              method: 'PUT',
-              headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify(payload),
-            },
-            { errorMessage: t('sales.documents.detail.addresses.saveError', 'Failed to update addresses.') },
+          // TODO(#2373-C): thread document updatedAt
+          withScopedApiRequestHeaders(buildOptimisticLockHeader(undefined), () =>
+            apiCallOrThrow(
+              '/api/sales/document-addresses',
+              {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+              },
+              { errorMessage: t('sales.documents.detail.addresses.saveError', 'Failed to update addresses.') },
+            ),
           ),
         payload,
       )
@@ -750,14 +754,17 @@ export function SalesDocumentAddressesSection({
         const payload = { id, documentId, documentKind: kind }
         await runGuardedMutation(
           () =>
-            apiCallOrThrow(
-              '/api/sales/document-addresses',
-              {
-                method: 'DELETE',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(payload),
-              },
-              { errorMessage: t('sales.documents.detail.addresses.deleteError', 'Failed to remove address.') },
+            // TODO(#2373-C): thread document updatedAt
+            withScopedApiRequestHeaders(buildOptimisticLockHeader(undefined), () =>
+              apiCallOrThrow(
+                '/api/sales/document-addresses',
+                {
+                  method: 'DELETE',
+                  headers: { 'Content-Type': 'application/json' },
+                  body: JSON.stringify(payload),
+                },
+                { errorMessage: t('sales.documents.detail.addresses.deleteError', 'Failed to remove address.') },
+              ),
             ),
           payload,
         )
@@ -849,14 +856,17 @@ export function SalesDocumentAddressesSection({
       const endpoint = kind === 'order' ? '/api/sales/orders' : '/api/sales/quotes'
       const call = await runGuardedMutation(
         () =>
-          apiCallOrThrow<Record<string, unknown>>(
-            endpoint,
-            {
-              method: 'PUT',
-              headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify(payload),
-            },
-            { errorMessage: t('sales.documents.detail.updateError', 'Failed to update document.') },
+          // TODO(#2373-C): thread document updatedAt
+          withScopedApiRequestHeaders(buildOptimisticLockHeader(undefined), () =>
+            apiCallOrThrow<Record<string, unknown>>(
+              endpoint,
+              {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+              },
+              { errorMessage: t('sales.documents.detail.updateError', 'Failed to update document.') },
+            ),
           ),
         payload,
       )

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

@@ -8,9 +8,11 @@ import { Badge } from '@open-mercato/ui/primitives/badge'
 import { DataTable } from '@open-mercato/ui/backend/DataTable'
 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 { createCrud, deleteCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { handleSectionMutationError } from './optimisticLock'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { type DictionaryOption } from '@open-mercato/core/modules/dictionaries/components/DictionaryEntrySelect'
 import {
@@ -31,6 +33,7 @@ type SalesDocumentAdjustmentsSectionProps = {
   documentId: string
   kind: 'order' | 'quote'
   currencyCode: string | null | undefined
+  documentUpdatedAt?: string | null
   organizationId?: string | null
   tenantId?: string | null
   onActionChange?: (action: SectionAction | null) => void
@@ -64,6 +67,7 @@ export function SalesDocumentAdjustmentsSection({
   documentId,
   kind,
   currencyCode,
+  documentUpdatedAt,
   organizationId: orgFromProps,
   tenantId: tenantFromProps,
   onActionChange,
@@ -317,27 +321,43 @@ export function SalesDocumentAdjustmentsSection({
       }
 
       const action = values.id ? updateCrud : createCrud
-      const result = await action(
-        crudResourcePath,
-        values.id ? { id: values.id, ...payload } : payload,
-        {
-          successMessage: values.id
-            ? t('sales.documents.adjustments.updated', 'Adjustment updated.')
-            : t('sales.documents.adjustments.created', 'Adjustment added.'),
-          errorMessage: t('sales.documents.adjustments.errorSave', 'Failed to save adjustment.'),
+      try {
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(documentUpdatedAt),
+          () =>
+            action(
+              crudResourcePath,
+              values.id ? { id: values.id, ...payload } : payload,
+              {
+                successMessage: values.id
+                  ? t('sales.documents.adjustments.updated', 'Adjustment updated.')
+                  : t('sales.documents.adjustments.created', 'Adjustment added.'),
+                errorMessage: t('sales.documents.adjustments.errorSave', 'Failed to save adjustment.'),
+              }
+            )
+        )
+        if (result.ok) {
+          await loadAdjustments()
+          emitSalesDocumentTotalsRefresh({ documentId, kind })
+          setDialogOpen(false)
+          setActiveAdjustment(null)
         }
-      )
-      if (result.ok) {
-        await loadAdjustments()
-        emitSalesDocumentTotalsRefresh({ documentId, kind })
-        setDialogOpen(false)
-        setActiveAdjustment(null)
+      } catch (err) {
+        if (
+          handleSectionMutationError(err, t, () => void loadAdjustments())
+        ) {
+          setDialogOpen(false)
+          setActiveAdjustment(null)
+          return
+        }
+        throw err
       }
     },
     [
       currencyCode,
       documentId,
       documentKey,
+      documentUpdatedAt,
       kind,
       loadAdjustments,
       crudResourcePath,
@@ -350,25 +370,30 @@ export function SalesDocumentAdjustmentsSection({
   const handleDelete = React.useCallback(
     async (row: AdjustmentRow) => {
       try {
-        const result = await deleteCrud(crudResourcePath, {
-          body: {
-            id: row.id,
-            [documentKey]: documentId,
-            organizationId: resolvedOrganizationId ?? undefined,
-            tenantId: resolvedTenantId ?? undefined,
-          },
-          errorMessage: t('sales.documents.adjustments.errorDelete', 'Failed to delete adjustment.'),
-        })
+        const result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(documentUpdatedAt),
+          () =>
+            deleteCrud(crudResourcePath, {
+              body: {
+                id: row.id,
+                [documentKey]: documentId,
+                organizationId: resolvedOrganizationId ?? undefined,
+                tenantId: resolvedTenantId ?? undefined,
+              },
+              errorMessage: t('sales.documents.adjustments.errorDelete', 'Failed to delete adjustment.'),
+            })
+        )
         if (result.ok) {
           await loadAdjustments()
           emitSalesDocumentTotalsRefresh({ documentId, kind })
         }
       } catch (err) {
+        if (handleSectionMutationError(err, t, () => void loadAdjustments())) return
         console.error('sales.document.adjustments.delete', err)
         flash(t('sales.documents.adjustments.errorDelete', 'Failed to delete adjustment.'), 'error')
       }
     },
-    [crudResourcePath, documentId, documentKey, kind, loadAdjustments, resolvedOrganizationId, resolvedTenantId, t]
+    [crudResourcePath, documentId, documentKey, documentUpdatedAt, kind, loadAdjustments, resolvedOrganizationId, resolvedTenantId, t]
   )
 
   const columns = React.useMemo<ColumnDef<AdjustmentRow>[]>(

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) => {