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

package/src/modules/customers/components/detail/schedule/useScheduleFormState.ts

@@ -19,6 +19,8 @@ export type LinkedEntity = {
 
 export type ScheduleActivityEditData = {
   id: string
+  /** Record version for the OSS optimistic-lock header on edit (#2055). */
+  updatedAt?: string | null
   interactionType?: string
   title?: string | null
   body?: string | null

package/src/modules/customers/components/detail/types.ts

@@ -113,6 +113,7 @@ export type TodoLinkSummary = {
   description?: string | null
   dueAt?: string | null
   todoOrganizationId?: string | null
+  updatedAt?: string | null
   customValues?: Record<string, unknown> | null
   externalHref?: string | null
 }

package/src/modules/customers/components/formConfig.tsx

@@ -1897,6 +1897,8 @@ export type PersonOverview = {
     nextInteractionIcon?: string | null
     nextInteractionColor?: string | null
     organizationId?: string | null
+    updatedAt?: string | null
+    updated_at?: string | null
   }
   profile: {
     id: string

package/src/modules/customers/data/guards.ts

@@ -0,0 +1,67 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { MutationGuard } from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { parseOptimisticLockEnv } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { getAllOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_CONFLICT_ERROR,
+  OPTIMISTIC_LOCK_ENV_VAR,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+function normalizeIsoToken(raw: string): string | null {
+  const ms = Date.parse(raw)
+  if (!Number.isFinite(ms)) return null
+  return new Date(ms).toISOString()
+}
+
+const optimisticLockGuard: MutationGuard = {
+  id: 'customers.optimistic-lock',
+  targetEntity: '*',
+  operations: ['update', 'delete'],
+  priority: 100,
+  async validate(input) {
+    const config = parseOptimisticLockEnv(process.env[OPTIMISTIC_LOCK_ENV_VAR])
+    if (config.mode === 'off') return { ok: true }
+    const enabled = config.mode === 'all' || config.entities.has(input.resourceKind.toLowerCase())
+    if (!enabled) return { ok: true }
+    const readers = getAllOptimisticLockReaders()
+    const reader = readers[input.resourceKind]
+    if (!reader) return { ok: true }
+    const expectedRaw = input.requestHeaders.get(OPTIMISTIC_LOCK_HEADER_NAME)
+    if (!expectedRaw || expectedRaw.trim().length === 0) return { ok: true }
+    const expectedIso = normalizeIsoToken(expectedRaw.trim())
+    if (!expectedIso) return { ok: true }
+    if (!input.resourceId) return { ok: true }
+    const container = await createRequestContainer()
+    let em: EntityManager
+    try {
+      em = container.resolve('em') as EntityManager
+    } catch {
+      return { ok: true }
+    }
+    const currentRaw = await reader(em, {
+      resourceKind: input.resourceKind,
+      resourceId: input.resourceId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId ?? null,
+    })
+    if (currentRaw == null) return { ok: true }
+    const currentIso = normalizeIsoToken(currentRaw)
+    if (currentIso == null) return { ok: true }
+    if (currentIso === expectedIso) return { ok: true }
+    return {
+      ok: false,
+      status: 409,
+      body: {
+        error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: currentIso,
+        expectedUpdatedAt: expectedIso,
+      },
+    }
+  },
+}
+
+export const guards: MutationGuard[] = [optimisticLockGuard]

package/src/modules/customers/di.ts

@@ -1,11 +1,77 @@
 import { asValue } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
 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 { CustomerEntity, CustomerAddress, CustomerInteraction } from './data/entities'
 
+const RESOURCE_KIND_COMPANY = 'customers.company'
+// The CRUD factory derives resourceKind via singularize-the-second-segment of
+// the commandId. For `customers.companies.update` it produces 'customers.company'.
+// For `customers.people.update` it does NOT singularize 'people' → 'person' (the
+// irregular plural is preserved), so the runtime resourceKind is
+// 'customers.people'. We register the reader under BOTH names so the
+// env opt-in entry can use either form (`customers.person` per spec or
+// `customers.people` matching the factory's derivation).
+const RESOURCE_KIND_PERSON = 'customers.person'
+const RESOURCE_KIND_PEOPLE = 'customers.people'
+
+const readCustomerCompanyUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const row = await em.findOne(
+    CustomerEntity,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      kind: 'company',
+      deletedAt: null,
+    },
+    { fields: ['updatedAt'] as const },
+  )
+  return row?.updatedAt instanceof Date ? row.updatedAt.toISOString() : null
+}
+
+const readCustomerPersonUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const row = await em.findOne(
+    CustomerEntity,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      kind: 'person',
+      deletedAt: null,
+    },
+    { fields: ['updatedAt'] as const },
+  )
+  return row?.updatedAt instanceof Date ? row.updatedAt.toISOString() : null
+}
+
+// Hand-wired readers must register at module-load time so they LAND BEFORE
+// the factory's `registerOptimisticLockReaderIfAbsent` calls in
+// `makeCrudRoute`. The discriminator (`kind: 'company' | 'person'`) cannot
+// be expressed by the generic auto-reader because both kinds share the
+// `customer_entities` polymorphic table. Registered unconditionally — the
+// guard's mode check short-circuits when `OM_OPTIMISTIC_LOCK=off`.
+registerOptimisticLockReaders({
+  [RESOURCE_KIND_COMPANY]: readCustomerCompanyUpdatedAt,
+  [RESOURCE_KIND_PERSON]: readCustomerPersonUpdatedAt,
+  [RESOURCE_KIND_PEOPLE]: readCustomerPersonUpdatedAt,
+})
+
 export function register(container: AppContainer) {
   container.register({
     CustomerEntity: asValue(CustomerEntity),
     CustomerAddress: asValue(CustomerAddress),
     CustomerInteraction: asValue(CustomerInteraction),
   })
+  // `crudMutationGuardService` is registered platform-wide in the shared
+  // DI bootstrap (`packages/shared/src/lib/di/container.ts`). It already
+  // resolves the hand-wired readers above from the global store, so this
+  // module no longer needs its own DI binding.
 }

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

@@ -317,6 +317,7 @@
   "customers.companies.detail.deals.loading": "Deals werden geladen…",
   "customers.companies.detail.deleteConfirmDescription": "Diese Aktion kann nicht rückgängig gemacht werden.",
   "customers.companies.detail.deleteConfirmTitle": "Unternehmen löschen?",
+  "customers.companies.detail.deleteError": "Unternehmen konnte nicht gelöscht werden.",
   "customers.companies.detail.employees": "Mitarbeiter",
   "customers.companies.detail.empty.addresses": "Keine Adressen erfasst.",
   "customers.companies.detail.empty.comments": "Noch keine Notizen.",
@@ -1673,6 +1674,7 @@
   "customers.people.detail.deals.valueInvalid": "Bitte gib einen gültigen Betrag ein",
   "customers.people.detail.deleteConfirmDescription": "Diese Aktion kann nicht rückgängig gemacht werden.",
   "customers.people.detail.deleteConfirmTitle": "Person löschen?",
+  "customers.people.detail.deleteError": "Person konnte nicht gelöscht werden.",
   "customers.people.detail.empty.activities": "Noch keine Aktivitäten",
   "customers.people.detail.empty.addresses": "Noch keine Adressen",
   "customers.people.detail.empty.comments": "Noch keine Notizen",

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

@@ -317,6 +317,7 @@
   "customers.companies.detail.deals.loading": "Loading deals…",
   "customers.companies.detail.deleteConfirmDescription": "This action cannot be undone.",
   "customers.companies.detail.deleteConfirmTitle": "Delete company?",
+  "customers.companies.detail.deleteError": "Failed to delete company.",
   "customers.companies.detail.employees": "employees",
   "customers.companies.detail.empty.addresses": "No addresses recorded.",
   "customers.companies.detail.empty.comments": "No notes yet.",
@@ -1673,6 +1674,7 @@
   "customers.people.detail.deals.valueInvalid": "Enter a valid amount",
   "customers.people.detail.deleteConfirmDescription": "This action cannot be undone.",
   "customers.people.detail.deleteConfirmTitle": "Delete person?",
+  "customers.people.detail.deleteError": "Failed to delete person.",
   "customers.people.detail.empty.activities": "No activity yet",
   "customers.people.detail.empty.addresses": "No addresses yet",
   "customers.people.detail.empty.comments": "No notes yet",

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

@@ -317,6 +317,7 @@
   "customers.companies.detail.deals.loading": "Cargando oportunidades…",
   "customers.companies.detail.deleteConfirmDescription": "Esta acción no se puede deshacer.",
   "customers.companies.detail.deleteConfirmTitle": "¿Eliminar empresa?",
+  "customers.companies.detail.deleteError": "Error al eliminar la empresa.",
   "customers.companies.detail.employees": "empleados",
   "customers.companies.detail.empty.addresses": "Sin direcciones registradas.",
   "customers.companies.detail.empty.comments": "Sin notas aún.",
@@ -1673,6 +1674,7 @@
   "customers.people.detail.deals.valueInvalid": "Introduce un importe válido",
   "customers.people.detail.deleteConfirmDescription": "Esta acción no se puede deshacer.",
   "customers.people.detail.deleteConfirmTitle": "¿Eliminar persona?",
+  "customers.people.detail.deleteError": "Error al eliminar la persona.",
   "customers.people.detail.empty.activities": "Sin actividad",
   "customers.people.detail.empty.addresses": "Sin direcciones",
   "customers.people.detail.empty.comments": "Sin notas",

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

@@ -317,6 +317,7 @@
   "customers.companies.detail.deals.loading": "Ładowanie szans sprzedaży…",
   "customers.companies.detail.deleteConfirmDescription": "Tej operacji nie można cofnąć.",
   "customers.companies.detail.deleteConfirmTitle": "Usunąć firmę?",
+  "customers.companies.detail.deleteError": "Nie udało się usunąć firmy.",
   "customers.companies.detail.employees": "osób",
   "customers.companies.detail.empty.addresses": "Brak zarejestrowanych adresów.",
   "customers.companies.detail.empty.comments": "Brak notatek.",
@@ -1673,6 +1674,7 @@
   "customers.people.detail.deals.valueInvalid": "Podaj poprawną kwotę",
   "customers.people.detail.deleteConfirmDescription": "Tej operacji nie można cofnąć.",
   "customers.people.detail.deleteConfirmTitle": "Usunąć osobę?",
+  "customers.people.detail.deleteError": "Nie udało się usunąć osoby.",
   "customers.people.detail.empty.activities": "Brak aktywności",
   "customers.people.detail.empty.addresses": "Brak adresów",
   "customers.people.detail.empty.comments": "Brak notatek",

package/src/modules/customers/lib/todoCompatibility.ts

@@ -26,6 +26,7 @@ export type CustomerTodoRow = {
   todoDueAt?: string | null
   todoCustomValues?: Record<string, unknown> | null
   todoOrganizationId: string | null
+  todoUpdatedAt?: string | null
   organizationId: string
   tenantId: string
   createdAt: string
@@ -46,6 +47,7 @@ export type LegacyTodoDetail = {
   description: string | null
   dueAt: string | null
   organizationId: string | null
+  updatedAt: string | null
   customValues: Record<string, unknown> | null
 }
 
@@ -336,6 +338,15 @@ export async function resolveLegacyTodoDetails(
           }
         }
 
+        const updatedAt = (() => {
+          const candidates = [record.updated_at, record.updatedAt]
+          for (const candidate of candidates) {
+            const parsed = parseDateValue(candidate)
+            if (parsed) return parsed
+          }
+          return null
+        })()
+
         details.set(`${source}:${rawId}`, {
           title: extractTodoTitle(record),
           isDone,
@@ -344,6 +355,7 @@ export async function resolveLegacyTodoDetails(
           description,
           dueAt,
           organizationId,
+          updatedAt,
           customValues: Object.keys(customValues).length > 0 ? customValues : null,
         })
       }
@@ -550,6 +562,7 @@ export function mapLegacyTodoLinkToRow(
     todoDueAt: detail?.dueAt ?? null,
     todoCustomValues: detail?.customValues ?? null,
     todoOrganizationId: detail?.organizationId ?? link.organizationId ?? null,
+    todoUpdatedAt: detail?.updatedAt ?? null,
     organizationId: link.organizationId,
     tenantId: link.tenantId,
     createdAt: link.createdAt.toISOString(),
@@ -595,6 +608,7 @@ export function mapInteractionRecordToTodoRow(
     todoDueAt: interaction.scheduledAt ?? null,
     todoCustomValues: Object.keys(customValues).length > 0 ? customValues : null,
     todoOrganizationId: interaction.organizationId ?? null,
+    todoUpdatedAt: interaction.updatedAt ?? null,
     organizationId: interaction.organizationId ?? '',
     tenantId: interaction.tenantId ?? '',
     createdAt: interaction.createdAt,

package/src/modules/dashboards/components/WidgetVisibilityEditor.tsx

@@ -242,6 +242,7 @@ export const WidgetVisibilityEditor = React.forwardRef<WidgetVisibilityEditorHan
           organizationId: organizationId ?? null,
           widgetIds: selected,
         }
+        // optimistic-lock-exempt: per-role widget visibility preference
         await apiCallOrThrow('/api/dashboards/roles/widgets', {
           method: 'PUT',
           headers: { 'content-type': 'application/json' },
@@ -258,6 +259,7 @@ export const WidgetVisibilityEditor = React.forwardRef<WidgetVisibilityEditorHan
           mode,
           widgetIds: selected,
         }
+        // optimistic-lock-exempt: per-user widget visibility preference
         await apiCallOrThrow('/api/dashboards/users/widgets', {
           method: 'PUT',
           headers: { 'content-type': 'application/json' },

package/src/modules/data_sync/api/options.ts

@@ -33,9 +33,12 @@ export async function GET(req: Request) {
         const adapter = getDataSyncAdapter(integration.providerKey as string)
         if (!adapter) return null
 
-        const [credentials, state] = await Promise.all([
-          credentialsService.resolve(integration.id, scope),
-          stateService.resolveState(integration.id, scope),
+        const [credentials, isEnabled] = await Promise.all([
+          credentialsService.resolve(integration.id, scope).catch(() => null),
+          stateService
+            .resolveState(integration.id, scope)
+            .then((state) => state.isEnabled)
+            .catch(() => false),
         ])
 
         return {
@@ -48,7 +51,7 @@ export async function GET(req: Request) {
           canStartRun: adapter.runMode !== 'provider',
           supportedEntities: adapter.supportedEntities,
           hasCredentials: Boolean(credentials),
-          isEnabled: state.isEnabled,
+          isEnabled,
           settingsPath: `/backend/integrations/${encodeURIComponent(integration.id)}`,
         }
       }),

package/src/modules/data_sync/api/schedules/route.ts

@@ -5,6 +5,8 @@ import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
 import { createSyncScheduleSchema, listSyncSchedulesQuerySchema } from '../../data/validators'
 import type { SyncScheduleService } from '../../lib/sync-schedule-service'
 import { serializeSchedule } from './serialize'
+import { readOptimisticLockExpected } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['data_sync.configure'] },
@@ -65,12 +67,18 @@ export async function POST(req: Request) {
   const scheduleService = container.resolve('dataSyncScheduleService') as SyncScheduleService
 
   try {
-    const schedule = await scheduleService.saveSchedule(parsed.data, {
+    const schedule = await scheduleService.saveSchedule({
+      ...parsed.data,
+      expectedUpdatedAt: readOptimisticLockExpected(req),
+    }, {
       organizationId: auth.orgId as string,
       tenantId: auth.tenantId,
     })
     return NextResponse.json(serializeSchedule(schedule), { status: 201 })
   } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
     const message = error instanceof Error ? error.message : 'Failed to save sync schedule'
     return NextResponse.json({ error: message }, { status: 422 })
   }

package/src/modules/data_sync/backend/data-sync/page.tsx

@@ -23,7 +23,8 @@ import {
 import { Separator } from '@open-mercato/ui/primitives/separator'
 import { Switch } from '@open-mercato/ui/primitives/switch'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
-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 { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -88,6 +89,7 @@ type SyncScheduleRecord = {
   fullSync: boolean
   isEnabled: boolean
   lastRunAt: string | null
+  updatedAt?: string | null
 }
 
 type SyncSchedulesResponse = {
@@ -102,6 +104,7 @@ type SyncScheduleEditorState = {
   fullSync: boolean
   isEnabled: boolean
   lastRunAt: string | null
+  updatedAt?: string | null
 }
 
 const STATUS_STYLES: Record<string, string> = {
@@ -171,6 +174,7 @@ function buildDefaultScheduleState(entityType: string): SyncScheduleEditorState
     fullSync: normalized !== 'products',
     isEnabled: true,
     lastRunAt: null,
+    updatedAt: null,
   }
 }
 
@@ -328,6 +332,7 @@ export default function SyncRunsDashboardPage() {
         fullSync: record.fullSync,
         isEnabled: record.isEnabled,
         lastRunAt: record.lastRunAt,
+        updatedAt: record.updatedAt ?? null,
       })
       setIsLoadingSchedule(false)
     }
@@ -341,6 +346,7 @@ export default function SyncRunsDashboardPage() {
   }, [])
 
   const handleCancel = React.useCallback(async (row: SyncRunRow) => {
+    // optimistic-lock-exempt: run lifecycle action endpoint (cancel), not a concurrent record edit
     const call = await apiCall(`/api/data_sync/runs/${encodeURIComponent(row.id)}/cancel`, {
       method: 'POST',
     }, { fallback: null })
@@ -353,6 +359,7 @@ export default function SyncRunsDashboardPage() {
   }, [t])
 
   const handleRetry = React.useCallback(async (row: SyncRunRow) => {
+    // optimistic-lock-exempt: run lifecycle action endpoint (retry), not a concurrent record edit
     const call = await apiCall(`/api/data_sync/runs/${encodeURIComponent(row.id)}/retry`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -391,6 +398,7 @@ export default function SyncRunsDashboardPage() {
 
     try {
       const call = await runMutation({
+        // optimistic-lock-exempt: starts a new sync run (create), not a concurrent record edit
         operation: () => apiCall<{ id: string }>('/api/data_sync/run', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
@@ -440,6 +448,7 @@ export default function SyncRunsDashboardPage() {
     setIsSavingSchedule(true)
     try {
       const call = await runMutation({
+        // optimistic-lock-exempt: keyed upsert (POST, no record id/version in body) — guard targets id-addressed PUT/PATCH/DELETE
         operation: () => apiCall<SyncScheduleRecord>('/api/data_sync/schedules', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
@@ -484,6 +493,7 @@ export default function SyncRunsDashboardPage() {
         fullSync: call.result.fullSync,
         isEnabled: call.result.isEnabled,
         lastRunAt: call.result.lastRunAt,
+        updatedAt: call.result.updatedAt ?? null,
       })
       flash(t('data_sync.dashboard.schedule.success', 'Recurring schedule saved'), 'success')
     } catch (error) {
@@ -500,9 +510,12 @@ export default function SyncRunsDashboardPage() {
     setIsDeletingSchedule(true)
     try {
       const call = await runMutation({
-        operation: () => apiCall(`/api/data_sync/schedules/${encodeURIComponent(scheduleEditor.id as string)}`, {
-          method: 'DELETE',
-        }, { fallback: null }),
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(scheduleEditor.updatedAt),
+          () => apiCall(`/api/data_sync/schedules/${encodeURIComponent(scheduleEditor.id as string)}`, {
+            method: 'DELETE',
+          }, { fallback: null }),
+        ),
         mutationPayload: {
           scheduleId: scheduleEditor.id,
         },
@@ -525,7 +538,7 @@ export default function SyncRunsDashboardPage() {
     } finally {
       setIsDeletingSchedule(false)
     }
-  }, [runMutation, scheduleEditor.id, selectedEntityType, t])
+  }, [runMutation, scheduleEditor.id, scheduleEditor.updatedAt, selectedEntityType, t])
 
   const filters: FilterDef[] = [
     {

package/src/modules/data_sync/components/IntegrationScheduleTab.tsx

@@ -1,7 +1,9 @@
 "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 { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { Badge } from '@open-mercato/ui/primitives/badge'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -54,6 +56,7 @@ type SyncScheduleRecord = {
   fullSync: boolean
   isEnabled: boolean
   lastRunAt: string | null
+  updatedAt?: string | null
 }
 
 type SyncSchedulesResponse = {
@@ -68,6 +71,7 @@ type SyncScheduleEditorState = {
   fullSync: boolean
   isEnabled: boolean
   lastRunAt: string | null
+  updatedAt?: string | null
 }
 
 type IntegrationScheduleTabProps = {
@@ -94,6 +98,7 @@ function buildDefaultScheduleState(entityType: string): SyncScheduleEditorState
     fullSync: normalized !== 'products',
     isEnabled: true,
     lastRunAt: null,
+    updatedAt: null,
   }
 }
 
@@ -127,6 +132,7 @@ function buildScheduleEditors(
             fullSync: record.fullSync,
             isEnabled: record.isEnabled,
             lastRunAt: record.lastRunAt,
+            updatedAt: record.updatedAt ?? null,
           }
           : buildDefaultScheduleState(entityType),
       ])
@@ -214,6 +220,7 @@ export function IntegrationScheduleTab(props: IntegrationScheduleTabProps) {
     setRunningKey(scheduleKey)
     try {
       const scheduleState = schedules[scheduleKey] ?? buildDefaultScheduleState(entityType)
+      // optimistic-lock-exempt: starts a new sync run (create), not a concurrent record edit
       const call = await apiCall<{ id: string }>('/api/data_sync/run', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
@@ -243,23 +250,39 @@ export function IntegrationScheduleTab(props: IntegrationScheduleTabProps) {
     const scheduleState = schedules[scheduleKey] ?? buildDefaultScheduleState(entityType)
     setSavingKey(scheduleKey)
     try {
-      const call = await apiCall<SyncScheduleRecord>('/api/data_sync/schedules', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          integrationId: props.integrationId,
-          entityType,
-          direction,
-          scheduleType: scheduleState.scheduleType,
-          scheduleValue: scheduleState.scheduleValue,
-          timezone: scheduleState.timezone,
-          fullSync: scheduleState.fullSync,
-          isEnabled: scheduleState.isEnabled,
-        }),
-      }, { fallback: null })
+      // Keyed upsert (POST). When the server resolves an existing row the save
+      // version-checks against this schedule's loaded `updatedAt`; for a brand
+      // new row the header is empty so the create path is unaffected.
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(scheduleState.updatedAt),
+        () => apiCall<SyncScheduleRecord>('/api/data_sync/schedules', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            integrationId: props.integrationId,
+            entityType,
+            direction,
+            scheduleType: scheduleState.scheduleType,
+            scheduleValue: scheduleState.scheduleValue,
+            timezone: scheduleState.timezone,
+            fullSync: scheduleState.fullSync,
+            isEnabled: scheduleState.isEnabled,
+          }),
+        }, { fallback: null }),
+      )
 
       if (!call.ok || !call.result) {
-        throw new Error((call.result as { error?: string } | null)?.error ?? 'Failed to save schedule')
+        const conflictError = Object.assign(
+          new Error((call.result as { error?: string } | null)?.error ?? 'Failed to save schedule'),
+          {
+            status: call.status,
+            ...(call.result && typeof call.result === 'object' ? call.result : {}),
+          },
+        )
+        if (surfaceRecordConflict(conflictError, t)) {
+          return
+        }
+        throw conflictError
       }
 
       updateScheduleEditor(scheduleKey, {
@@ -270,6 +293,7 @@ export function IntegrationScheduleTab(props: IntegrationScheduleTabProps) {
         fullSync: call.result.fullSync,
         isEnabled: call.result.isEnabled,
         lastRunAt: call.result.lastRunAt,
+        updatedAt: call.result.updatedAt ?? null,
       }, entityType)
       flash(t('data_sync.dashboard.schedule.success', 'Recurring schedule saved'), 'success')
     } catch (error) {
@@ -289,9 +313,12 @@ export function IntegrationScheduleTab(props: IntegrationScheduleTabProps) {
 
     setDeletingKey(scheduleKey)
     try {
-      const call = await apiCall(`/api/data_sync/schedules/${encodeURIComponent(scheduleState.id)}`, {
-        method: 'DELETE',
-      }, { fallback: null })
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(scheduleState.updatedAt),
+        () => apiCall(`/api/data_sync/schedules/${encodeURIComponent(scheduleState.id as string)}`, {
+          method: 'DELETE',
+        }, { fallback: null }),
+      )
 
       if (!call.ok) {
         throw new Error((call.result as { error?: string } | null)?.error ?? 'Failed to delete schedule')

package/src/modules/data_sync/lib/sync-schedule-service.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 import type { EntityManager, FilterQuery } from '@mikro-orm/postgresql'
 import { findAndCountWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { SyncSchedule } from '../data/entities'
 
 type SyncScope = {
@@ -129,11 +130,21 @@ export function createSyncScheduleService(em: EntityManager, schedulerService?:
       timezone: string
       fullSync: boolean
       isEnabled: boolean
+      expectedUpdatedAt?: string | null
     }, scope: SyncScope): Promise<SyncSchedule> {
       const existing = input.id
         ? await getById(input.id, scope)
         : await getByKey(input.integrationId, input.entityType, input.direction, scope)
 
+      if (existing) {
+        enforceCommandOptimisticLock({
+          resourceKind: 'data_sync.schedule',
+          resourceId: existing.id,
+          current: existing.updatedAt ?? null,
+          expected: input.expectedUpdatedAt ?? null,
+        })
+      }
+
       const row = existing ?? em.create(SyncSchedule, {
         id: randomUUID(),
         integrationId: input.integrationId,

package/src/modules/dictionaries/api/[dictionaryId]/entries/[entryId]/route.ts

@@ -4,6 +4,7 @@ import { Dictionary, DictionaryEntry } from '@open-mercato/core/modules/dictiona
 import { resolveDictionariesRouteContext } from '@open-mercato/core/modules/dictionaries/api/context'
 import { updateDictionaryEntrySchema } from '@open-mercato/core/modules/dictionaries/data/validators'
 import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import type { CommandBus } from '@open-mercato/shared/lib/commands'
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
 import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
@@ -70,7 +71,13 @@ export async function PATCH(req: Request, ctx: { params?: { dictionaryId?: strin
       entryId: ctx.params?.entryId,
     })
     const dictionary = await loadDictionary(context, dictionaryId)
-    await loadEntry(context, dictionary, entryId)
+    const entry = await loadEntry(context, dictionary, entryId)
+    enforceCommandOptimisticLock({
+      resourceKind: 'dictionaries.entry',
+      resourceId: entry.id,
+      current: entry.updatedAt ?? null,
+      request: req,
+    })
     const rawBody = await req.json().catch(() => ({}))
     const payload = updateDictionaryEntrySchema.parse(rawBody)
     // These nested routes don't use the CRUD factory, so invoke the command bus explicitly.