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

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

package/src/modules/sales/di.ts

@@ -2,6 +2,8 @@ import { asFunction, asValue } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { EventBus } from '@open-mercato/events'
 import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { OptimisticLockCurrentReader } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { registerOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { DefaultSalesCalculationService } from './services/salesCalculationService'
 import { DefaultTaxCalculationService } from './services/taxCalculationService'
 import { SalesDocumentNumberGenerator } from './services/salesDocumentNumberGenerator'
@@ -38,6 +40,34 @@ type AppCradle = AppContainer['cradle'] & {
   eventBus?: EventBus | null
 }
 
+const RESOURCE_KIND_ORDER = 'sales.order'
+
+const readSalesOrderUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const row = await em.findOne(
+    SalesOrder,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      deletedAt: null,
+    },
+    { fields: ['updatedAt'] as const },
+  )
+  return row?.updatedAt instanceof Date ? row.updatedAt.toISOString() : null
+}
+
+// Hand-wired sales.order reader registered at module-load time so the
+// `customer_entities`-style polymorphic-table override pattern stays
+// observable for downstream modules. Functionally identical to the
+// auto-registered generic reader; kept here as a reference example. The
+// guard's mode check short-circuits when `OM_OPTIMISTIC_LOCK=off`.
+registerOptimisticLockReaders({
+  [RESOURCE_KIND_ORDER]: readSalesOrderUpdatedAt,
+})
+
 export function register(container: AppContainer) {
   container.register({
     salesCalculationService: asFunction(({ eventBus }: AppCradle) => {
@@ -81,4 +111,9 @@ export function register(container: AppContainer) {
     SalesPaymentMethod: asValue(SalesPaymentMethod),
     SalesTaxRate: asValue(SalesTaxRate),
   })
+
+  // `crudMutationGuardService` is registered platform-wide in the shared
+  // DI bootstrap (`packages/shared/src/lib/di/container.ts`). The
+  // hand-wired sales.order reader above already lives in the global store,
+  // so this module no longer needs its own DI binding.
 }

package/src/modules/sales/i18n/de.json

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Dokumentadresse hinzufügen",
+  "sales.audit.document_addresses.delete": "Dokumentadresse entfernen",
+  "sales.audit.document_addresses.update": "Dokumentadresse aktualisieren",
   "sales.audit.invoices.create": "Rechnung erstellen",
   "sales.audit.invoices.delete": "Rechnung löschen",
   "sales.audit.invoices.update": "Rechnung aktualisieren",

package/src/modules/sales/i18n/en.json

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Add document address",
+  "sales.audit.document_addresses.delete": "Remove document address",
+  "sales.audit.document_addresses.update": "Update document address",
   "sales.audit.invoices.create": "Create invoice",
   "sales.audit.invoices.delete": "Delete invoice",
   "sales.audit.invoices.update": "Update invoice",

package/src/modules/sales/i18n/es.json

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Agregar dirección del documento",
+  "sales.audit.document_addresses.delete": "Eliminar dirección del documento",
+  "sales.audit.document_addresses.update": "Actualizar dirección del documento",
   "sales.audit.invoices.create": "Crear factura",
   "sales.audit.invoices.delete": "Eliminar factura",
   "sales.audit.invoices.update": "Actualizar factura",

package/src/modules/sales/i18n/pl.json

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Dodaj adres dokumentu",
+  "sales.audit.document_addresses.delete": "Usuń adres dokumentu",
+  "sales.audit.document_addresses.update": "Zaktualizuj adres dokumentu",
   "sales.audit.invoices.create": "Utwórz fakturę",
   "sales.audit.invoices.delete": "Usuń fakturę",
   "sales.audit.invoices.update": "Zaktualizuj fakturę",

package/src/modules/staff/api/job-histories.ts

@@ -4,6 +4,7 @@ import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import { StaffTeamMemberJobHistory } from '../data/entities'
 import {
+  optimisticUpdatedAtSchema,
   staffTeamMemberJobHistoryCreateSchema,
   staffTeamMemberJobHistoryUpdateSchema,
 } from '../data/validators'
@@ -12,6 +13,11 @@ import { E } from '#generated/entities.ids.generated'
 
 const rawBodySchema = z.object({}).passthrough()
 
+const optimisticDeleteSchema = z.object({
+  id: z.string().uuid(),
+  updatedAt: optimisticUpdatedAtSchema.optional(),
+})
+
 const listSchema = z
   .object({
     page: z.coerce.number().min(1).default(1),
@@ -94,7 +100,11 @@ const crud = makeCrudRoute({
       mapInput: async ({ parsed, ctx }) => {
         const { translate } = await resolveTranslations()
         const id = resolveCrudRecordId(parsed, ctx, translate)
-        return { id }
+        const parsedBody = (parsed as { body?: Record<string, unknown> })?.body
+        return {
+          id,
+          updatedAt: typeof parsedBody?.updatedAt === 'string' ? parsedBody.updatedAt : undefined,
+        }
       },
       response: () => ({ ok: true }),
     },
@@ -137,7 +147,7 @@ export const openApi = createStaffCrudOpenApi({
     description: 'Updates a team member job history entry.',
   },
   del: {
-    schema: z.object({ id: z.string().uuid() }),
+    schema: optimisticDeleteSchema,
     responseSchema: defaultOkResponseSchema,
     description: 'Deletes a team member job history entry.',
   },

package/src/modules/staff/api/timesheets/time-entries/route.ts

@@ -37,13 +37,25 @@ export const metadata = routeMetadata
 
 const rawBodySchema = z.object({}).passthrough()
 
+const isParseableDateFilter = (value: string): boolean => {
+  const trimmed = value.trim()
+  if (trimmed.length === 0) return true
+  if (!/^\d{4}-\d{2}-\d{2}([T ].*)?$/.test(trimmed)) return false
+  return !Number.isNaN(new Date(trimmed).getTime())
+}
+
+const dateFilterSchema = z
+  .string()
+  .refine(isParseableDateFilter, { message: 'Invalid date' })
+  .optional()
+
 const listSchema = z
   .object({
     page: z.coerce.number().min(1).default(1),
     pageSize: z.coerce.number().min(1).max(100).default(50),
     staffMemberId: z.string().uuid().optional(),
-    from: z.string().optional(),
-    to: z.string().optional(),
+    from: dateFilterSchema,
+    to: dateFilterSchema,
     projectId: z.string().uuid().optional(),
     ids: z.string().optional(),
     sortField: z.string().optional(),
@@ -102,10 +114,10 @@ const crud = makeCrudRoute({
       if (typeof query.staffMemberId === 'string' && query.staffMemberId.length > 0) {
         filters[F.staff_member_id] = query.staffMemberId
       }
-      if (typeof query.from === 'string' && query.from.length > 0) {
+      if (typeof query.from === 'string' && query.from.length > 0 && isParseableDateFilter(query.from)) {
         filters[F.date] = { ...((filters[F.date] as Record<string, unknown>) ?? {}), $gte: query.from }
       }
-      if (typeof query.to === 'string' && query.to.length > 0) {
+      if (typeof query.to === 'string' && query.to.length > 0 && isParseableDateFilter(query.to)) {
         filters[F.date] = { ...((filters[F.date] as Record<string, unknown>) ?? {}), $lte: query.to }
       }
       if (typeof query.projectId === 'string' && query.projectId.length > 0) {

package/src/modules/staff/backend/staff/leave-requests/[id]/page.tsx

@@ -8,7 +8,8 @@ import { Button } from '@open-mercato/ui/primitives/button'
 import { Textarea } from '@open-mercato/ui/primitives/textarea'
 import { LoadingMessage, ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
 import { SendObjectMessageDialog } from '@open-mercato/ui/backend/messages'
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -89,6 +90,7 @@ export default function StaffLeaveRequestDetailPage({ params }: { params?: { id?
     unavailabilityReasonEntryId: record?.unavailabilityReasonEntryId ?? null,
     unavailabilityReasonValue: record?.unavailabilityReasonValue ?? null,
     note: record?.note ?? null,
+    updatedAt: record?.updatedAt ?? null,
   }), [record, memberLabel])
 
 const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) => {
@@ -104,11 +106,14 @@ const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) =>
   const handleDecision = React.useCallback(async (action: 'accept' | 'reject') => {
     if (!record?.id) return
     const endpoint = action === 'accept' ? '/api/staff/leave-requests/accept' : '/api/staff/leave-requests/reject'
-    await apiCallOrThrow(endpoint, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ id: record.id, decisionComment: decisionComment || null }),
-    })
+    await withScopedApiRequestHeaders(
+      buildOptimisticLockHeader(record.updatedAt),
+      () => apiCallOrThrow(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: record.id, decisionComment: decisionComment || null }),
+      }),
+    )
     flash(
       action === 'accept'
         ? t('staff.leaveRequests.messages.accepted', 'Leave request approved.')
@@ -116,7 +121,7 @@ const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) =>
       'success',
     )
     router.refresh()
-  }, [decisionComment, record?.id, router, t])
+  }, [decisionComment, record?.id, record?.updatedAt, router, t])
 
   if (isLoading) {
     return (

package/src/modules/staff/backend/staff/my-leave-requests/[id]/page.tsx

@@ -74,6 +74,7 @@ export default function StaffMyLeaveRequestDetailPage({ params }: { params?: { i
 
   const status = record?.status ?? 'pending'
   const memberLabel = record?.member?.displayName ?? null
+  // optimistic-lock: LeaveRequestForm forwards optimisticLockUpdatedAt from initialValues.updatedAt (wrapper auto-derives the header on save).
   const initialValues = React.useMemo<LeaveRequestFormValues>(() => ({
     id: record?.id,
     memberId: record?.memberId ?? null,
@@ -84,6 +85,7 @@ export default function StaffMyLeaveRequestDetailPage({ params }: { params?: { i
     unavailabilityReasonEntryId: record?.unavailabilityReasonEntryId ?? null,
     unavailabilityReasonValue: record?.unavailabilityReasonValue ?? null,
     note: record?.note ?? null,
+    updatedAt: record?.updatedAt ?? null,
   }), [record, memberLabel])
   const dateSummary = formatDateRange(record?.startDate, record?.endDate)
 const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) => {

package/src/modules/staff/backend/staff/team-members/[id]/page.tsx

@@ -5,9 +5,10 @@ import Link from 'next/link'
 import { useRouter, useSearchParams } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-fields-client'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { createTranslatorWithFallback } from '@open-mercato/shared/lib/i18n/translate'
@@ -54,6 +55,8 @@ type TeamMemberRecord = {
   is_active?: boolean
   availabilityRuleSetId?: string | null
   availability_rule_set_id?: string | null
+  updatedAt?: string | null
+  updated_at?: string | null
   user?: { id?: string; email?: string | null } | null
   team?: { id?: string; name?: string | null } | null
   customFields?: Record<string, unknown> | null
@@ -226,6 +229,11 @@ export default function StaffTeamMemberDetailPage({ params }: { params?: { id?:
             roleIds: normalizedRoleIds,
             tags: normalizeStringList(record.tags),
             isActive: record.isActive ?? record.is_active ?? true,
+            updatedAt: typeof record.updatedAt === 'string'
+              ? record.updatedAt
+              : typeof record.updated_at === 'string'
+                ? record.updated_at
+                : null,
             ...customFields,
           })
           setMemberRecord(record)
@@ -289,12 +297,15 @@ export default function StaffTeamMemberDetailPage({ params }: { params?: { id?:
 
   const handleRulesetChange = React.useCallback(async (nextId: string | null) => {
     if (!memberId) return
-    await updateCrud('staff/team-members', { id: memberId, availabilityRuleSetId: nextId }, {
-      errorMessage: t('staff.teamMembers.availability.ruleset.updateError', 'Failed to update schedule.'),
-    })
+    const headers = buildOptimisticLockHeader(initialValues?.updatedAt)
+    await withScopedApiRequestHeaders(headers, () => (
+      updateCrud('staff/team-members', { id: memberId, availabilityRuleSetId: nextId }, {
+        errorMessage: t('staff.teamMembers.availability.ruleset.updateError', 'Failed to update schedule.'),
+      })
+    ))
     setAvailabilityRuleSetId(nextId)
     flash(t('staff.teamMembers.availability.ruleset.updateSuccess', 'Schedule updated.'), 'success')
-  }, [memberId, t])
+  }, [initialValues?.updatedAt, memberId, t])
 
   const panelTabs = React.useMemo(() => ([
     { id: 'details' as const, label: t('staff.teamMembers.detail.tabs.details', 'Details') },

package/src/modules/staff/backend/staff/team-members/page.tsx

@@ -9,8 +9,9 @@ import { DataTable, withDataTableNamespaces } from '@open-mercato/ui/backend/Dat
 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 { readApiResultOrThrow, apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
@@ -391,7 +392,10 @@ export default function StaffTeamMembersPage() {
     })
     if (!confirmed) return
     try {
-      await deleteCrud('staff/team-members', entry.id, { errorMessage: labels.errors.delete })
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      await withScopedApiRequestHeaders(headers, () => (
+        deleteCrud('staff/team-members', entry.id, { errorMessage: labels.errors.delete })
+      ))
       flash(labels.messages.deleted, 'success')
       handleRefresh()
     } catch (error) {

package/src/modules/staff/backend/staff/team-roles/[id]/edit/page.tsx

@@ -23,6 +23,8 @@ type TeamRoleRecord = {
   appearanceColor?: string | null
   appearance_icon?: string | null
   appearance_color?: string | null
+  updatedAt?: string | null
+  updated_at?: string | null
 } & Record<string, unknown>
 
 type TeamRoleResponse = {
@@ -38,6 +40,7 @@ export default function StaffTeamRoleEditPage({ params }: { params?: { id?: stri
   const t = useT()
   const router = useRouter()
   const scopeVersion = useOrganizationScopeVersion()
+  // optimistic-lock: TeamRoleForm forwards optimisticLockUpdatedAt from initialValues.updatedAt (wrapper auto-derives the header on save + delete).
   const [initialValues, setInitialValues] = React.useState<TeamRoleFormValues | null>(null)
   const [error, setError] = React.useState<string | null>(null)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -86,6 +89,11 @@ export default function StaffTeamRoleEditPage({ params }: { params?: { id?: stri
             name: record.name ?? '',
             description: record.description ?? '',
             appearance: { icon: appearanceIcon, color: appearanceColor },
+            updatedAt: typeof record.updatedAt === 'string'
+              ? record.updatedAt
+              : typeof record.updated_at === 'string'
+                ? record.updated_at
+                : null,
             ...customFields,
           })
         }

package/src/modules/staff/backend/staff/team-roles/page.tsx

@@ -9,8 +9,9 @@ import { DataTable, withDataTableNamespaces } from '@open-mercato/ui/backend/Dat
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { MarkdownPreview } from '@open-mercato/ui/backend/markdown/MarkdownContent'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { readApiResultOrThrow, apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { Pencil, Users } from 'lucide-react'
@@ -277,7 +278,10 @@ export default function StaffTeamRolesPage() {
     })
     if (!confirmed) return
     try {
-      await deleteCrud('staff/team-roles', entry.id, { errorMessage: labels.errors.delete })
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      await withScopedApiRequestHeaders(headers, () => (
+        deleteCrud('staff/team-roles', entry.id, { errorMessage: labels.errors.delete })
+      ))
       flash(labels.messages.deleted, 'success')
       handleRefresh()
     } catch (error) {