@open-mercato/core 0.6.6-develop.6399.1.93ba8ca030 → 0.6.6-develop.6402.1.080aab8ec9

package/src/modules/entities/api/definitions.ts

@@ -33,6 +33,7 @@ import {
   resolveDefinitionMutationScope,
   selectVisibleDefinitionWinner,
 } from '../lib/definition-scope'
+import { resolveEntityDefinitionsVersion } from '../lib/definitions-version'
 
 /**
  * Validate defaultValue against the field kind. Returns an error message string
@@ -620,7 +621,14 @@ export async function DELETE(req: Request) {
     entityIds: [entityId],
   })
   // Changing field definitions may impact forms but not sidebar items; no nav cache touch
-  return NextResponse.json({ ok: true })
+  // Return the post-delete aggregate version so the edit form keeps its optimistic-lock
+  // token in sync after removing a field out-of-band (issue #3152).
+  const version = await resolveEntityDefinitionsVersion(em, {
+    entityId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  })
+  return NextResponse.json({ ok: true, version })
 }
 
 const definitionsQuerySchema = z
@@ -716,6 +724,7 @@ const deleteDefinitionRequestSchema = z.object({
 
 const deleteDefinitionResponseSchema = z.object({
   ok: z.literal(true),
+  version: z.string().nullable().optional(),
 })
 
 export const openApi: OpenApiRouteDoc = {

package/src/modules/entities/backend/entities/user/[entityId]/page.tsx

@@ -4,7 +4,9 @@ import { useRouter, useSearchParams } from 'next/navigation'
 import { useQueryClient } from '@tanstack/react-query'
 import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, 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 { invalidateCustomFieldDefs } from '@open-mercato/ui/backend/utils/customFieldDefs'
 import { upsertCustomEntitySchema, upsertCustomFieldDefSchema } from '@open-mercato/core/modules/entities/data/validators'
 import { z } from 'zod'
@@ -31,7 +33,12 @@ export type EntitySource = 'code' | 'custom'
 type EntitiesListResponse = { items?: Array<Record<string, unknown>> }
 type FieldsetGroup = { code: string; title?: string; hint?: string }
 type FieldsetDefinition = { code: string; label: string; icon?: string; description?: string; groups?: FieldsetGroup[] }
-type DefinitionsManageResponse = { items?: any[]; deletedKeys?: string[]; fieldsets?: FieldsetDefinition[]; settings?: { singleFieldsetPerRecord?: boolean } }
+type DefinitionsManageResponse = { items?: any[]; deletedKeys?: string[]; fieldsets?: FieldsetDefinition[]; settings?: { singleFieldsetPerRecord?: boolean }; version?: string | null }
+type DefinitionsBatchResponse = { ok?: boolean; version?: string | null }
+
+function readVersionToken(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
 
 type DefErrors = FieldDefinitionError
 
@@ -48,6 +55,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
   const [entityFormLoading, setEntityFormLoading] = useState(true)
   const [entityInitial, setEntityInitial] = useState<{ label?: string; description?: string; labelField?: string; defaultEditor?: string; showInSidebar?: boolean; updatedAt?: string }>({})
   const [defs, setDefs] = useState<Def[]>([])
+  const [defsVersion, setDefsVersion] = useState<string | null>(null)
   const [orderDirty, setOrderDirty] = useState(false)
   const [orderSaving, setOrderSaving] = useState(false)
   const listRef = React.useRef<HTMLDivElement | null>(null)
@@ -197,6 +205,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
             (a, b) => Number(a.configJson?.priority ?? 0) - Number(b.configJson?.priority ?? 0)
           )
           setDefs(loaded)
+          setDefsVersion(readVersionToken(json.version))
           setDefErrors({})
           setDeletedKeys(Array.isArray(json.deletedKeys) ? json.deletedKeys : [])
           const loadedFieldsets = Array.isArray(json.fieldsets) ? json.fieldsets : []
@@ -253,6 +262,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
         (a, b) => Number(a.configJson?.priority ?? 0) - Number(b.configJson?.priority ?? 0)
       )
       setDefs(loaded)
+      setDefsVersion(readVersionToken(j2.version))
       setDeletedKeys(Array.isArray(j2.deletedKeys) ? j2.deletedKeys : [])
       flash(`Restored ${key}`, 'success')
       await invalidateCustomFieldDefs(queryClient, entityId)
@@ -278,14 +288,19 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
           isActive: d.isActive !== false,
         })),
       }
-      const call = await apiCall('/api/entities/definitions.batch', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(payload),
-      })
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(defsVersion),
+        () => apiCall<DefinitionsBatchResponse>('/api/entities/definitions.batch', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(payload),
+        }),
+      )
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, 'Failed to save definitions')
       }
+      setDefsVersion(readVersionToken(call.result?.version))
       await invalidateCustomFieldDefs(queryClient, entityId)
       router.push(`/backend/entities/user?flash=Definitions%20saved&type=success`)
     } catch (e: any) {
@@ -300,7 +315,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
     if (!def) return
     if (def.key) {
       try {
-        const call = await apiCall('/api/entities/definitions', {
+        const call = await apiCall<DefinitionsBatchResponse>('/api/entities/definitions', {
           method: 'DELETE',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ entityId, key: def.key }),
@@ -308,6 +323,9 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
         if (!call.ok) {
           await raiseCrudError(call.response, 'Failed to delete field')
         }
+        // Keep the optimistic-lock token in sync after an out-of-band delete so a
+        // later Save does not falsely 409 against our own change (issue #3152).
+        setDefsVersion(readVersionToken(call.result?.version))
       } catch (error) {
         const message = error instanceof Error ? error.message : 'Failed to delete field'
         flash(message, 'error')
@@ -364,12 +382,23 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
           isActive: d.isActive !== false,
         })),
       }
-      const call = await apiCall('/api/entities/definitions.batch', {
-        method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload)
-      })
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(defsVersion),
+        () => apiCall<DefinitionsBatchResponse>('/api/entities/definitions.batch', {
+          method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload),
+        }),
+      )
       if (!call.ok) {
+        // A stale reorder auto-save (another tab changed the schema first) returns a
+        // 409; surface the shared conflict bar and stop the retry loop instead of a
+        // generic flash (issue #3152).
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) {
+          setOrderDirty(false)
+          return
+        }
         await raiseCrudError(call.response, 'Failed to save order')
       }
+      setDefsVersion(readVersionToken(call.result?.version))
       setOrderDirty(false)
       flash('Order saved', 'success')
       await invalidateCustomFieldDefs(queryClient, entityId)
@@ -502,18 +531,25 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
       fieldsets: buildFieldsetPayload(),
       singleFieldsetPerRecord,
     })
-    const callDefs = await apiCall('/api/entities/definitions.batch', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(defsPayload),
-    })
+    // Send the aggregate schema version so a concurrent edit is rejected with a 409
+    // instead of silently overwriting the other tab (issue #3152). CrudForm's submit
+    // catch detects the optimistic-lock conflict and shows the shared conflict bar.
+    const callDefs = await withScopedApiRequestHeaders(
+      buildOptimisticLockHeader(defsVersion),
+      () => apiCall<DefinitionsBatchResponse>('/api/entities/definitions.batch', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(defsPayload),
+      }),
+    )
     if (!callDefs.ok) {
       await raiseCrudError(callDefs.response, 'Failed to save definitions')
     }
+    setDefsVersion(readVersionToken(callDefs.result?.version))
     try { window.dispatchEvent(new Event('om:refresh-sidebar')) } catch {}
     await invalidateCustomFieldDefs(queryClient, entityId)
     flash('Definitions saved', 'success')
-  }, [buildFieldsetPayload, defs, entityId, entitySource, queryClient, singleFieldsetPerRecord, validateAll])
+  }, [buildFieldsetPayload, defs, defsVersion, entityId, entitySource, queryClient, singleFieldsetPerRecord, validateAll])
 
   if (!entityId) {
     return (

package/src/modules/entities/lib/definitions-version.ts

@@ -0,0 +1,102 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  CustomFieldDef,
+  CustomFieldEntityConfig,
+} from '@open-mercato/core/modules/entities/data/entities'
+
+/**
+ * Aggregate optimistic-lock version for an entity's *definition schema*
+ * (issue #3152).
+ *
+ * The entity definition edit form (`/backend/entities/user|system/<entityId>`)
+ * saves a whole set of `CustomFieldDef` rows (plus fieldset config) via
+ * `POST /api/entities/definitions.batch`. There is no single row to lock, so the
+ * classic per-record `updated_at` guard cannot apply. Instead we derive one
+ * aggregate version token = the newest `updated_at` across the rows that make up
+ * the editable schema for the entity in the caller's scope:
+ *
+ *   - `CustomFieldDef` (active + tombstoned) — a field add/edit/delete bumps it,
+ *   - `CustomFieldEntityConfig` — a fieldset/settings change bumps it.
+ *
+ * The `CustomEntity` metadata row is deliberately NOT part of this token: the
+ * form's Save first PUTs entity metadata (`POST /api/entities/entities`, which
+ * bumps `CustomEntity.updatedAt` and enforces its own optimistic lock) and only
+ * then PUTs the definitions batch — folding the metadata row in here would make
+ * the batch 409 against the form's OWN just-completed metadata save. Custom
+ * entities therefore keep their concurrent-edit protection from the metadata
+ * lock (primary) with the definitions token as defense-in-depth; system/code
+ * entities (no metadata row, no metadata PUT) rely on the definitions token.
+ * A schema with zero definitions and no config yields `null`, so locking
+ * degrades to a no-op for that first-ever concurrent add edge case.
+ *
+ * Both the read path (`definitions.manage` GET) and the mutating endpoints must
+ * compute this with identical scope inputs so the token round-trips without
+ * false conflicts.
+ */
+export type EntityDefinitionsVersionScope = {
+  entityId: string
+  tenantId: string | null
+  organizationId: string | null
+}
+
+function buildVisibleScopeWhere(scope: EntityDefinitionsVersionScope): Record<string, unknown> {
+  const organizationCandidates: Array<{ organizationId: string | null }> = [{ organizationId: null }]
+  if (scope.organizationId) organizationCandidates.unshift({ organizationId: scope.organizationId })
+
+  const tenantCandidates: Array<{ tenantId: string | null }> = [{ tenantId: null }]
+  if (scope.tenantId) tenantCandidates.unshift({ tenantId: scope.tenantId })
+
+  return {
+    entityId: scope.entityId,
+    $and: [
+      { $or: organizationCandidates },
+      { $or: tenantCandidates },
+    ],
+  }
+}
+
+function toMillis(value: unknown): number {
+  if (value instanceof Date) {
+    const ms = value.getTime()
+    return Number.isFinite(ms) ? ms : 0
+  }
+  if (typeof value === 'string' && value.length > 0) {
+    const ms = Date.parse(value)
+    return Number.isFinite(ms) ? ms : 0
+  }
+  return 0
+}
+
+async function latestUpdatedAtMillis(
+  em: EntityManager,
+  entity: unknown,
+  where: Record<string, unknown>,
+): Promise<number> {
+  if (!entity) return 0
+  try {
+    const row = await em.findOne(entity as never, where as never, {
+      orderBy: { updatedAt: 'desc' } as never,
+      fields: ['updatedAt'] as never,
+    })
+    if (!row || typeof row !== 'object') return 0
+    return toMillis((row as Record<string, unknown>).updatedAt)
+  } catch {
+    // Fail-open: a projection/schema hiccup must never 500 a save — it degrades
+    // to "no version available", which the guard treats as a no-op.
+    return 0
+  }
+}
+
+export async function resolveEntityDefinitionsVersion(
+  em: EntityManager,
+  scope: EntityDefinitionsVersionScope,
+): Promise<string | null> {
+  const where = buildVisibleScopeWhere(scope)
+  const [defMillis, configMillis] = await Promise.all([
+    latestUpdatedAtMillis(em, CustomFieldDef, where),
+    latestUpdatedAtMillis(em, CustomFieldEntityConfig, where),
+  ])
+  const newest = Math.max(defMillis, configMillis)
+  if (!newest) return null
+  return new Date(newest).toISOString()
+}

package/src/modules/sales/cli.ts

@@ -1,7 +1,7 @@
 import type { ModuleCli } from '@open-mercato/shared/modules/registry'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { seedSalesAdjustmentKinds, seedSalesStatusDictionaries } from './lib/dictionaries'
+import { backfillDealLossReasonDictionary, seedSalesAdjustmentKinds, seedSalesStatusDictionaries } from './lib/dictionaries'
 import { seedSalesTaxRates } from './lib/seeds'
 import { ensureExamplePaymentMethods, ensureExampleShippingMethods } from './seed/examples-data'
 import { seedSalesExamples } from './seed/examples'
@@ -103,6 +103,43 @@ const seedAdjustmentKindsCommand: ModuleCli = {
   },
 }
 
+const backfillDealLossReasonsCommand: ModuleCli = {
+  command: 'backfill-deal-loss-reasons',
+  async run(rest) {
+    const args = parseArgs(rest)
+    const tenantId = String(args.tenantId ?? args.tenant ?? '')
+    const organizationId = String(args.organizationId ?? args.org ?? args.orgId ?? '')
+    if (!tenantId || !organizationId) {
+      console.error('Usage: mercato sales backfill-deal-loss-reasons --tenant <tenantId> --org <organizationId>')
+      return
+    }
+    const container = await createRequestContainer()
+    try {
+      const em = container.resolve<EntityManager>('em')
+      const result = await em.transactional(async (tem) => {
+        const backfillResult = await backfillDealLossReasonDictionary(tem, { tenantId, organizationId })
+        await tem.flush()
+        return backfillResult
+      })
+      console.log(
+        [
+          `Deal loss reasons dictionary ready for organization ${organizationId}.`,
+          `dictionaryId=${result.dictionaryId}`,
+          `createdDictionary=${String(result.createdDictionary)}`,
+          `copiedLegacyEntries=${String(result.copiedLegacyEntries)}`,
+          `seededDefaultEntries=${String(result.seededDefaultEntries)}`,
+          `existingEntries=${String(result.existingEntries)}`,
+        ].join(' '),
+      )
+    } finally {
+      const disposable = container as unknown as { dispose?: () => Promise<void> }
+      if (typeof disposable.dispose === 'function') {
+        await disposable.dispose()
+      }
+    }
+  },
+}
+
 const seedShippingMethodsCommand: ModuleCli = {
   command: 'seed-shipping-methods',
   async run(rest) {
@@ -189,6 +226,7 @@ export default [
   seedTaxRatesCommand,
   seedStatusesCommand,
   seedAdjustmentKindsCommand,
+  backfillDealLossReasonsCommand,
   seedShippingMethodsCommand,
   seedPaymentMethodsCommand,
   seedExamplesCommand,

package/src/modules/sales/lib/dictionaries.ts

@@ -133,6 +133,14 @@ type SalesDictionarySeed = {
 
 type SeedScope = { tenantId: string; organizationId: string }
 
+export type BackfillDealLossReasonDictionaryResult = {
+  dictionaryId: string
+  createdDictionary: boolean
+  copiedLegacyEntries: number
+  seededDefaultEntries: number
+  existingEntries: number
+}
+
 const ORDER_STATUS_DEFAULTS: SalesDictionarySeed[] = [
   { value: 'draft', label: 'Draft', color: '#94a3b8', icon: 'lucide:file-pen-line' },
   { value: 'pending_approval', label: 'Pending Approval', color: '#f59e0b', icon: 'lucide:hourglass' },
@@ -262,6 +270,88 @@ const DEAL_LOSS_REASON_DEFAULTS: SalesDictionarySeed[] = [
   { value: 'other', label: 'Other', color: '#71717a', icon: 'lucide:minus-circle' },
 ]
 
+export async function backfillDealLossReasonDictionary(
+  em: EntityManager,
+  scope: SeedScope
+): Promise<BackfillDealLossReasonDictionaryResult> {
+  const definition = getSalesDictionaryDefinition('deal-loss-reasons')
+  const existingDictionary = await em.findOne(Dictionary, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    key: definition.key,
+    deletedAt: null,
+  })
+  const dictionary = existingDictionary ?? await ensureSalesDictionary({
+    em,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    kind: 'deal-loss-reasons',
+  })
+  const targetEntries = await em.find(DictionaryEntry, {
+    dictionary,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  })
+
+  if (targetEntries.length > 0) {
+    return {
+      dictionaryId: dictionary.id,
+      createdDictionary: !existingDictionary,
+      copiedLegacyEntries: 0,
+      seededDefaultEntries: 0,
+      existingEntries: targetEntries.length,
+    }
+  }
+
+  const legacyDictionary = await em.findOne(Dictionary, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    key: 'customer_lost_reason',
+    deletedAt: null,
+  })
+  const legacyEntries = legacyDictionary
+    ? await em.find(
+      DictionaryEntry,
+      {
+        dictionary: legacyDictionary,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+      },
+      { orderBy: { position: 'asc', label: 'asc' } },
+    )
+    : []
+
+  let copiedLegacyEntries = 0
+  let seededDefaultEntries = 0
+  const processedValues = new Set<string>()
+  const seeds = legacyEntries.length
+    ? legacyEntries.map((entry) => ({
+      value: entry.value,
+      label: entry.label,
+      color: entry.color,
+      icon: entry.icon,
+    }))
+    : DEAL_LOSS_REASON_DEFAULTS
+
+  for (const seed of seeds) {
+    const normalizedValue = normalizeDictionaryValue(seed.value ?? '')
+    if (!normalizedValue || processedValues.has(normalizedValue)) continue
+    const entry = await ensureSalesDictionaryEntry(em, scope, 'deal-loss-reasons', seed)
+    if (!entry) continue
+    processedValues.add(normalizedValue)
+    if (legacyEntries.length) copiedLegacyEntries += 1
+    else seededDefaultEntries += 1
+  }
+
+  return {
+    dictionaryId: dictionary.id,
+    createdDictionary: !existingDictionary,
+    copiedLegacyEntries,
+    seededDefaultEntries,
+    existingEntries: 0,
+  }
+}
+
 export async function seedSalesStatusDictionaries(
   em: EntityManager,
   scope: SeedScope