@open-mercato/core 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4544.1.71c003c861

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

@@ -7,7 +7,9 @@ import { CrudForm, type CrudField, type CrudFormGroup, type CrudFormGroupCompone
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError, type CrudServerFieldErrors } from '@open-mercato/ui/backend/utils/serverErrors'
-import { readApiResultOrThrow, apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Input } from '@open-mercato/ui/primitives/input'
@@ -41,6 +43,8 @@ type PriceOverrideDraft = {
   currencyCode?: string | null
   displayMode?: 'including-tax' | 'excluding-tax' | null
   amount?: string
+  /** The price row's version, for the per-price optimistic-lock header (#2332). */
+  updatedAt?: string | null
 }
 
 export type OfferFormValues = {
@@ -51,6 +55,7 @@ export type OfferFormValues = {
   defaultMediaId?: string | null
   isActive: boolean
   priceOverrides: PriceOverrideDraft[]
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 type ChannelOfferFormProps = {
@@ -141,13 +146,15 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
   const variantMediaCache = React.useRef<Map<string, VariantThumbnailInfo>>(new Map())
   const [selectedChannelId, setSelectedChannelId] = React.useState<string | null>(lockedChannelId ?? null)
   const manualMediaSelections = React.useRef<Set<string>>(new Set())
-  const initialPriceIdsRef = React.useRef<Set<string>>(new Set())
+  // Map of the loaded price-override id → its `updatedAt`, so deletes during the
+  // offer save can send the price's own optimistic-lock version (#2332).
+  const initialPriceVersionsRef = React.useRef<Map<string, string | null>>(new Map())
   const [currentProductId, setCurrentProductId] = React.useState<string | null>(null)
   React.useEffect(() => {
     if (initialValues) {
-      initialPriceIdsRef.current = collectPriceIds(initialValues.priceOverrides)
+      initialPriceVersionsRef.current = collectPriceVersions(initialValues.priceOverrides)
     } else {
-      initialPriceIdsRef.current = new Set()
+      initialPriceVersionsRef.current = new Map()
     }
   }, [initialValues])
   const channelOffersHref = React.useMemo(
@@ -438,12 +445,16 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
     if (!priceId) return true
     if (mode !== 'edit') return true
     try {
-      await deleteCrud('catalog/prices', priceId, {
-        errorMessage: t('sales.channels.offers.errors.removePrice', 'Failed to remove price override.'),
-      })
-      initialPriceIdsRef.current.delete(priceId)
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(draft.updatedAt),
+        () => deleteCrud('catalog/prices', priceId, {
+          errorMessage: t('sales.channels.offers.errors.removePrice', 'Failed to remove price override.'),
+        }),
+      )
+      initialPriceVersionsRef.current.delete(priceId)
       return true
     } catch (err) {
+      if (surfaceRecordConflict(err, t)) return false
       console.error('sales.channels.pricing.remove', err)
       flash(t('sales.channels.offers.errors.removePrice', 'Failed to remove price override.'), 'error')
       return false
@@ -594,10 +605,11 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
     }
     const submittedPriceIds = collectPriceIds(overrides)
     const deletedIdSet = new Set<string>()
-    initialPriceIdsRef.current.forEach((id) => {
+    initialPriceVersionsRef.current.forEach((_version, id) => {
       if (!submittedPriceIds.has(id)) deletedIdSet.add(id)
     })
     const deletedIds = Array.from(deletedIdSet)
+    const deletedVersions = new Map(deletedIds.map((id) => [id, initialPriceVersionsRef.current.get(id) ?? null]))
     let savedId = offerId ?? null
     try {
       if (mode === 'create') {
@@ -612,6 +624,13 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
         savedId = offerId
       }
     } catch (err) {
+      // Let an optimistic-lock 409 propagate untouched so CrudForm's
+      // extractOptimisticLockConflict still sees the top-level `code` /
+      // `currentUpdatedAt` / `expectedUpdatedAt` and surfaces the unified
+      // conflict bar. Re-wrapping via createCrudFormError below would drop them.
+      if (extractOptimisticLockConflict(err)) {
+        throw err
+      }
       const details = (err as { details?: unknown })?.details
       const rawFieldErrors = (err as { fieldErrors?: unknown })?.fieldErrors
       const fieldErrors = rawFieldErrors && typeof rawFieldErrors === 'object'
@@ -634,15 +653,16 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
       await syncPriceOverrides({
         overrides,
         deletedIds,
+        deletedVersions,
         offerId: savedId,
         channelId,
         productId,
       })
-      initialPriceIdsRef.current = submittedPriceIds
+      initialPriceVersionsRef.current = collectPriceVersions(overrides)
     }
     flash(t('sales.channels.offers.messages.saved', 'Offer saved.'), 'success')
     router.push(buildChannelOffersHref(channelId))
-  }, [attachmentCache, initialPriceIdsRef, lockedChannelId, mode, offerId, router, selectedChannelId, t])
+  }, [attachmentCache, lockedChannelId, mode, offerId, router, selectedChannelId, t])
 
   const handleDelete = React.useCallback(async () => {
     if (!offerId) return
@@ -669,6 +689,7 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
         fields={fields}
         groups={groups}
         initialValues={initialValues ?? undefined}
+        optimisticLockUpdatedAt={initialValues?.updatedAt}
         isLoading={loading}
         loadingMessage={t('sales.channels.offers.form.loading', 'Loading offer…')}
         submitLabel={mode === 'create'
@@ -706,6 +727,11 @@ function mapOfferToFormValues(item: Record<string, unknown>, lockedChannelId?: s
         : null,
     isActive: item.isActive === true || item.is_active === true,
     priceOverrides: [],
+    updatedAt: typeof item.updatedAt === 'string'
+      ? item.updatedAt
+      : typeof item.updated_at === 'string'
+        ? item.updated_at
+        : null,
   }
   mergeCustomFieldValues(values, item)
   return values
@@ -742,6 +768,11 @@ function mapPriceRow(row: Record<string, unknown>): PriceOverrideDraft {
           : typeof row.unit_price_gross === 'string'
             ? row.unit_price_gross
             : '',
+    updatedAt: typeof row.updatedAt === 'string'
+      ? row.updatedAt
+      : typeof row.updated_at === 'string'
+        ? row.updated_at
+        : null,
   }
 }
 
@@ -753,6 +784,17 @@ function collectPriceIds(source: PriceOverrideDraft[] | null | undefined): Set<s
   return new Set(ids)
 }
 
+function collectPriceVersions(source: PriceOverrideDraft[] | null | undefined): Map<string, string | null> {
+  const versions = new Map<string, string | null>()
+  if (!Array.isArray(source)) return versions
+  for (const entry of source) {
+    if (typeof entry?.priceId === 'string' && entry.priceId) {
+      versions.set(entry.priceId, typeof entry.updatedAt === 'string' ? entry.updatedAt : null)
+    }
+  }
+  return versions
+}
+
 function mergeCustomFieldValues(target: Record<string, unknown>, source: Record<string, unknown> | null | undefined) {
   Object.assign(target, extractCustomFieldEntries(source ?? {}))
 }
@@ -766,11 +808,12 @@ function buildChannelOffersHref(channelId?: string | null): string {
 async function syncPriceOverrides(params: {
   overrides: PriceOverrideDraft[]
   deletedIds: string[]
+  deletedVersions: Map<string, string | null>
   offerId: string
   channelId: string
   productId: string
 }) {
-  const { overrides, deletedIds, offerId, channelId, productId } = params
+  const { overrides, deletedIds, deletedVersions, offerId, channelId, productId } = params
   for (const draft of overrides) {
     if (!draft.priceKindId || !draft.amount) continue
     const amount = Number(draft.amount)
@@ -788,7 +831,14 @@ async function syncPriceOverrides(params: {
       payload.unitPriceNet = amount
     }
     if (draft.priceId) {
-      await updateCrud('catalog/prices', { id: draft.priceId, ...payload })
+      // Send the PRICE's own version, overriding the offer header the parent
+      // CrudForm submit scope put on the stack (otherwise the price guard would
+      // compare the offer's `updated_at` and 409 falsely). #2332.
+      const priceId = draft.priceId
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(draft.updatedAt),
+        () => updateCrud('catalog/prices', { id: priceId, ...payload }),
+      )
     } else {
       await createCrud('catalog/prices', payload)
     }
@@ -799,7 +849,10 @@ async function syncPriceOverrides(params: {
   for (const id of uniqueDeletedIds) {
     if (!id) continue
     try {
-      await deleteCrud('catalog/prices', id)
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(deletedVersions.get(id) ?? null),
+        () => deleteCrud('catalog/prices', id),
+      )
     } catch (err) {
       console.error('catalog.prices.delete', err)
     }

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,