@open-mercato/core 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/src/modules/sales/commands/payments.ts

@@ -32,6 +32,7 @@ import {
   toNumericString,
 } from './shared'
 import { resolveDictionaryEntryValue } from '../lib/dictionaries'
+import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
 import { invalidateCrudCache } from '@open-mercato/shared/lib/crud/cache'
 import { emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
 import type { CrudEventsConfig } from '@open-mercato/shared/lib/crud/types'
@@ -252,7 +253,12 @@ async function recomputeOrderPaymentTotals(
   const scope = { organizationId: order.organizationId, tenantId: order.tenantId }
 
   if (options?.lock) {
-    await em.findOne(SalesOrder, { id: orderId }, { lockMode: LockMode.PESSIMISTIC_WRITE })
+    // Raw findOne is intentional: this acquires a row lock only — no encrypted
+    // SalesOrder field is read, so decryption (findOneWithDecryption) is unnecessary.
+    // Scope filter is defence-in-depth (#2111): the caller is expected to pass a
+    // correctly scoped order, but filtering here ensures we never lock a foreign
+    // tenant's row even if a caller messed up.
+    await em.findOne(SalesOrder, { id: orderId, ...scope }, { lockMode: LockMode.PESSIMISTIC_WRITE })
   }
 
   const allocations = await findWithDecryption(
@@ -369,7 +375,7 @@ const createPaymentCommand: CommandHandler<
         tx.persist(order)
       }
       if (input.documentStatusEntryId !== undefined) {
-        const orderStatus = await resolveDictionaryEntryValue(tx, input.documentStatusEntryId ?? null)
+        const orderStatus = await resolveDictionaryEntryValue(tx, input.documentStatusEntryId ?? null, { tenantId: input.tenantId })
         if (input.documentStatusEntryId && !orderStatus) {
           throw new CrudHttpError(400, {
             error: translate('sales.documents.detail.statusInvalid', 'Selected status could not be found.'),
@@ -381,7 +387,7 @@ const createPaymentCommand: CommandHandler<
         tx.persist(order)
       }
       if (input.lineStatusEntryId !== undefined) {
-        const lineStatus = await resolveDictionaryEntryValue(tx, input.lineStatusEntryId ?? null)
+        const lineStatus = await resolveDictionaryEntryValue(tx, input.lineStatusEntryId ?? null, { tenantId: input.tenantId })
         if (input.lineStatusEntryId && !lineStatus) {
           throw new CrudHttpError(400, {
             error: translate('sales.documents.detail.statusInvalid', 'Selected status could not be found.'),
@@ -395,7 +401,7 @@ const createPaymentCommand: CommandHandler<
         })
         orderLines.forEach((line) => tx.persist(line))
       }
-      const status = await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null)
+      const status = await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null, { tenantId: input.tenantId })
       const payment = tx.create(SalesPayment, {
         organizationId: input.organizationId,
         tenantId: input.tenantId,
@@ -611,6 +617,83 @@ const createPaymentCommand: CommandHandler<
       }
     }
   },
+  redo: async ({ ctx, logEntry }) => {
+    const after = resolveRedoSnapshot<PaymentSnapshot>(logEntry)
+    const paymentId = after?.id ?? logEntry.resourceId ?? null
+    if (!after || !paymentId) {
+      throw new CrudHttpError(400, { error: '[internal] redo snapshot unavailable for sales.payments.create' })
+    }
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    await restorePaymentSnapshot(em, after)
+    await em.flush()
+
+    const orderIds = Array.from(
+      new Set(
+        [
+          after.orderId,
+          ...after.allocations.map((allocation) => allocation.orderId),
+        ].filter((value): value is string => typeof value === 'string' && value.length > 0)
+      )
+    )
+    let totals: { paidTotalAmount: number; refundedTotalAmount: number; outstandingAmount: number } | undefined
+    for (const orderId of orderIds) {
+      const recomputed = await em.transactional(async (tx) => {
+        const order = await findOneWithDecryption(
+          tx,
+          SalesOrder,
+          { id: orderId },
+          { lockMode: LockMode.PESSIMISTIC_WRITE },
+          { tenantId: after.tenantId, organizationId: after.organizationId },
+        )
+        if (!order) return undefined
+        if (orderId === after.orderId && after.paymentMethodId && !order.paymentMethodId) {
+          const method = await findOneWithDecryption(
+            tx,
+            SalesPaymentMethod,
+            { id: after.paymentMethodId },
+            {},
+            { tenantId: after.tenantId, organizationId: after.organizationId },
+          )
+          order.paymentMethodId = method?.id ?? after.paymentMethodId
+          order.paymentMethodCode = method?.code ?? null
+          order.updatedAt = new Date()
+          await tx.flush()
+        }
+        const result = await recomputeOrderPaymentTotals(tx, order)
+        await tx.flush()
+        return result
+      })
+      if (recomputed && (!totals || orderId === after.orderId)) {
+        totals = recomputed
+      }
+      // Raw findOne is intentional: the order is fetched only to read its id/scope
+      // for cache invalidation — no encrypted field is read, so decryption is unnecessary.
+      // Scope filter (#2111): never cache-invalidate a foreign tenant's order even
+      // if a snapshot's orderId was somehow tampered with.
+      const target = await em.findOne(SalesOrder, { id: orderId, organizationId: after.organizationId, tenantId: after.tenantId })
+      if (target) {
+        ensureSameScope(target, after.organizationId, after.tenantId)
+        await invalidateOrderCache(ctx.container, target, ctx.auth?.tenantId ?? null)
+      }
+    }
+
+    const payment = await findOneWithDecryption(em, SalesPayment, { id: after.id }, {}, { tenantId: after.tenantId, organizationId: after.organizationId })
+    const dataEngine = ctx.container.resolve('dataEngine') as DataEngine
+    await emitCrudSideEffects({
+      dataEngine,
+      action: 'created',
+      entity: payment,
+      identifiers: {
+        id: after.id,
+        organizationId: after.organizationId,
+        tenantId: after.tenantId,
+      },
+      indexer: { entityType: E.sales.sales_payment },
+      events: paymentCrudEvents,
+    })
+
+    return { paymentId: after.id, orderTotals: totals }
+  },
 }
 
 const updatePaymentCommand: CommandHandler<
@@ -696,7 +779,7 @@ const updatePaymentCommand: CommandHandler<
         throw new CrudHttpError(400, { error: translate('sales.payments.order_required', 'Order is required for payments.') })
       }
       if (currentOrder && input.documentStatusEntryId !== undefined) {
-        const orderStatus = await resolveDictionaryEntryValue(tx, input.documentStatusEntryId ?? null)
+        const orderStatus = await resolveDictionaryEntryValue(tx, input.documentStatusEntryId ?? null, { tenantId: resolvedTenantId })
         if (input.documentStatusEntryId && !orderStatus) {
           throw new CrudHttpError(400, {
             error: translate('sales.documents.detail.statusInvalid', 'Selected status could not be found.'),
@@ -708,7 +791,7 @@ const updatePaymentCommand: CommandHandler<
         tx.persist(currentOrder)
       }
       if (currentOrder && input.lineStatusEntryId !== undefined) {
-        const lineStatus = await resolveDictionaryEntryValue(tx, input.lineStatusEntryId ?? null)
+        const lineStatus = await resolveDictionaryEntryValue(tx, input.lineStatusEntryId ?? null, { tenantId: resolvedTenantId })
         if (input.lineStatusEntryId && !lineStatus) {
           throw new CrudHttpError(400, {
             error: translate('sales.documents.detail.statusInvalid', 'Selected status could not be found.'),
@@ -725,7 +808,7 @@ const updatePaymentCommand: CommandHandler<
       if (input.paymentReference !== undefined) payment.paymentReference = input.paymentReference ?? null
       if (input.statusEntryId !== undefined) {
         payment.statusEntryId = input.statusEntryId ?? null
-        payment.status = await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null)
+        payment.status = await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null, { tenantId: resolvedTenantId })
       }
       if (input.amount !== undefined) payment.amount = toNumericString(input.amount) ?? '0'
       if (input.currencyCode !== undefined) payment.currencyCode = input.currencyCode
@@ -757,6 +840,12 @@ const updatePaymentCommand: CommandHandler<
       }
       payment.updatedAt = new Date()
 
+      // Persist the payment scalar changes before any allocation query below.
+      // MikroORM discards pending scalar mutations when a find() runs on the
+      // same EntityManager before they are flushed, which would otherwise drop
+      // the updated amount/reference when allocations are (re)synced.
+      await tx.flush()
+
       if (input.allocations !== undefined) {
         const existingAllocations = await findWithDecryption(tx, SalesPaymentAllocation, { payment }, {}, { tenantId: payment.tenantId, organizationId: payment.organizationId })
         existingAllocations.forEach((allocation) => tx.remove(allocation))
@@ -816,6 +905,29 @@ const updatePaymentCommand: CommandHandler<
           })
           tx.persist(entity)
         }
+      } else if (input.amount !== undefined || input.currencyCode !== undefined) {
+        // The caller changed the payment amount/currency without managing
+        // allocations explicitly. A simple payment carries a single
+        // auto-created allocation covering the full amount (see create); keep
+        // it in sync so recomputeOrderPaymentTotals — which sums allocations in
+        // preference to the payment amount — does not report a stale paid total
+        // after a payment edit (#2455).
+        const existingAllocations = await findWithDecryption(tx, SalesPaymentAllocation, { payment }, {}, { tenantId: payment.tenantId, organizationId: payment.organizationId })
+        const paymentOrderId =
+          (typeof payment.order === 'string' ? payment.order : payment.order?.id) ?? null
+        const isDefaultAllocation = (allocation: SalesPaymentAllocation): boolean => {
+          const allocationOrderId =
+            typeof allocation.order === 'string' ? allocation.order : allocation.order?.id ?? null
+          const allocationInvoiceId =
+            typeof allocation.invoice === 'string' ? allocation.invoice : allocation.invoice?.id ?? null
+          return allocationInvoiceId === null && allocationOrderId === paymentOrderId
+        }
+        if (existingAllocations.length === 1 && isDefaultAllocation(existingAllocations[0])) {
+          const [allocation] = existingAllocations
+          allocation.amount = toNumericString(toNumber(payment.amount)) ?? '0'
+          allocation.currencyCode = payment.currencyCode
+          tx.persist(allocation)
+        }
       }
     })
 
@@ -825,21 +937,42 @@ const updatePaymentCommand: CommandHandler<
     let totals: { paidTotalAmount: number; refundedTotalAmount: number; outstandingAmount: number } | undefined
     if (nextOrderId) {
       totals = await em.transactional(async (tx) => {
-        const lockedOrder = await tx.findOne(SalesOrder, { id: nextOrderId }, { lockMode: LockMode.PESSIMISTIC_WRITE })
+        // Scope filter (#2111): never lock or recompute totals on a foreign
+        // tenant's order, even if payment.order somehow points there.
+        const lockedOrder = await tx.findOne(
+          SalesOrder,
+          { id: nextOrderId, organizationId: payment.organizationId, tenantId: payment.tenantId },
+          { lockMode: LockMode.PESSIMISTIC_WRITE },
+        )
         if (!lockedOrder) return undefined
+        ensureSameScope(lockedOrder, payment.organizationId, payment.tenantId)
         const result = await recomputeOrderPaymentTotals(tx, lockedOrder)
         await tx.flush()
         return result
       })
       if (totals) {
-        const nextOrder = await em.findOne(SalesOrder, { id: nextOrderId })
-        if (nextOrder) await invalidateOrderCache(ctx.container, nextOrder, ctx.auth?.tenantId ?? null)
+        // Raw findOne is intentional: the order is fetched only to read its id/scope
+        // for cache invalidation — no encrypted field is read, so decryption is unnecessary.
+        // Scope filter (#2111): same rationale as the lock above.
+        const nextOrder = await em.findOne(SalesOrder, { id: nextOrderId, organizationId: payment.organizationId, tenantId: payment.tenantId })
+        if (nextOrder) {
+          ensureSameScope(nextOrder, payment.organizationId, payment.tenantId)
+          await invalidateOrderCache(ctx.container, nextOrder, ctx.auth?.tenantId ?? null)
+        }
       }
     }
     if (previousOrder && (!nextOrderId || previousOrder.id !== nextOrderId)) {
       await em.transactional(async (tx) => {
-        const lockedOrder = await tx.findOne(SalesOrder, { id: previousOrder.id }, { lockMode: LockMode.PESSIMISTIC_WRITE })
+        // Scope filter (#2111): previousOrder was already loaded via the
+        // payment's scope, so its tenant/org match the payment's. Filter
+        // the lock query the same way as defence-in-depth.
+        const lockedOrder = await tx.findOne(
+          SalesOrder,
+          { id: previousOrder.id, organizationId: payment.organizationId, tenantId: payment.tenantId },
+          { lockMode: LockMode.PESSIMISTIC_WRITE },
+        )
         if (!lockedOrder) return
+        ensureSameScope(lockedOrder, payment.organizationId, payment.tenantId)
         await recomputeOrderPaymentTotals(tx, lockedOrder)
         await tx.flush()
       })
@@ -963,8 +1096,15 @@ const deletePaymentCommand: CommandHandler<
     const primaryOrderId = order && typeof order === 'object' ? order.id : null
     for (const orderId of orderIds) {
       const recomputed = await em.transactional(async (tx) => {
-        const lockedOrder = await tx.findOne(SalesOrder, { id: orderId }, { lockMode: LockMode.PESSIMISTIC_WRITE })
+        // Scope filter (#2111): never lock or recompute totals on a foreign
+        // tenant's order, even if a payment allocation somehow points there.
+        const lockedOrder = await tx.findOne(
+          SalesOrder,
+          { id: orderId, organizationId: payment.organizationId, tenantId: payment.tenantId },
+          { lockMode: LockMode.PESSIMISTIC_WRITE },
+        )
         if (!lockedOrder) return undefined
+        ensureSameScope(lockedOrder, payment.organizationId, payment.tenantId)
         const result = await recomputeOrderPaymentTotals(tx, lockedOrder)
         await tx.flush()
         return result
@@ -972,8 +1112,14 @@ const deletePaymentCommand: CommandHandler<
       if (recomputed && (!totals || (primaryOrderId && orderId === primaryOrderId))) {
         totals = recomputed
       }
-      const target = await em.findOne(SalesOrder, { id: orderId })
-      if (target) await invalidateOrderCache(ctx.container, target, ctx.auth?.tenantId ?? null)
+      // Raw findOne is intentional: the order is fetched only to read its id/scope
+      // for cache invalidation — no encrypted field is read, so decryption is unnecessary.
+      // Scope filter (#2111): same rationale as the lock above.
+      const target = await em.findOne(SalesOrder, { id: orderId, organizationId: payment.organizationId, tenantId: payment.tenantId })
+      if (target) {
+        ensureSameScope(target, payment.organizationId, payment.tenantId)
+        await invalidateOrderCache(ctx.container, target, ctx.auth?.tenantId ?? null)
+      }
     }
     const dataEngine = ctx.container.resolve('dataEngine') as DataEngine
     await emitCrudSideEffects({

package/src/modules/sales/commands/returns.ts

@@ -12,7 +12,8 @@ import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/
 import { SalesDocumentNumberGenerator } from '../services/salesDocumentNumberGenerator'
 import type { SalesCalculationService } from '../services/salesCalculationService'
 import type { SalesAdjustmentDraft, SalesLineSnapshot, SalesDocumentCalculationResult } from '../lib/types'
-import { cloneJson, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString } from './shared'
+import { cloneJson, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString, enforceSalesDocumentOptimisticLock, SALES_RESOURCE_KIND_ORDER } from './shared'
+import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
 import { SalesOrder, SalesOrderAdjustment, SalesOrderLine, SalesReturn, SalesReturnLine } from '../data/entities'
 import { returnCreateSchema, type ReturnCreateInput } from '../data/validators'
 import { E } from '#generated/entities.ids.generated'
@@ -286,6 +287,7 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
         throw new CrudHttpError(404, { error: translate('sales.returns.orderMissing', 'Order not found.') })
       }
       ensureSameScope(order, input.organizationId, input.tenantId)
+      enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
 
       const orderLines = await findWithDecryption(
         tx,
@@ -476,11 +478,12 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
     // Line reversals, adjustment/return removals, and the order-total recompute
     // interleave queries on the same EntityManager with scalar mutations, so they
     // must run inside an atomic flush to avoid lost updates and partial commits.
+    let lines: SalesOrderLine[] = []
     await withAtomicFlush(
       em,
       [
         async () => {
-          const lines = await findWithDecryption(
+          lines = await findWithDecryption(
             em,
             SalesOrderLine,
             { order: order.id, deletedAt: null },
@@ -496,7 +499,14 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
             line.updatedAt = new Date()
             em.persist(line)
           })
-
+        },
+        // The line returnedQuantity reversals above are persisted by
+        // withAtomicFlush's per-phase flush boundary before the adjustment /
+        // header / return-line lookups below run any query on this
+        // EntityManager. MikroORM v7 would otherwise silently discard the pending
+        // scalar changes on the managed `lines` when the next read resets the
+        // changeset (see SPEC-018).
+        async () => {
           if (after.adjustmentIds.length) {
             const adjustments = await findWithDecryption(
               em,
@@ -548,6 +558,187 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
       { transaction: true },
     )
   },
+  redo: async ({ ctx, logEntry }) => {
+    const after = resolveRedoSnapshot<ReturnSnapshot>(logEntry)
+    const returnId = after?.id ?? logEntry.resourceId ?? null
+    if (!after || !returnId) {
+      throw new CrudHttpError(400, { error: '[internal] redo snapshot unavailable for sales.returns.create' })
+    }
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const salesCalculationService = ctx.container.resolve<SalesCalculationService>('salesCalculationService')
+
+    const createdLines: SalesReturnLine[] = []
+
+    await withAtomicFlush(
+      em,
+      [
+        async () => {
+          const order = await findOneWithDecryption(
+            em,
+            SalesOrder,
+            { id: after.orderId, deletedAt: null },
+            {},
+            { tenantId: after.tenantId, organizationId: after.organizationId },
+          )
+          if (!order) {
+            throw new CrudHttpError(404, { error: 'sales.returns.orderMissing' })
+          }
+          ensureSameScope(order, after.organizationId, after.tenantId)
+
+          const orderLines = await findWithDecryption(
+            em,
+            SalesOrderLine,
+            { order: order.id, deletedAt: null },
+            { lockMode: LockMode.PESSIMISTIC_WRITE },
+            { tenantId: after.tenantId, organizationId: after.organizationId },
+          )
+          const lineMap = new Map(orderLines.map((line) => [line.id, line]))
+
+          const existingAdjustments = await findWithDecryption(
+            em,
+            SalesOrderAdjustment,
+            { order: order.id, deletedAt: null },
+            { orderBy: { position: 'asc' } },
+            { tenantId: after.tenantId, organizationId: after.organizationId },
+          )
+          const positionStart = existingAdjustments.reduce((acc, adj) => Math.max(acc, adj.position ?? 0), 0) + 1
+
+          const restoredHeader =
+            (await findOneWithDecryption(
+              em,
+              SalesReturn,
+              { id: after.id },
+              {},
+              { tenantId: after.tenantId, organizationId: after.organizationId },
+            )) ??
+            em.create(SalesReturn, {
+              id: after.id,
+              order,
+              organizationId: after.organizationId,
+              tenantId: after.tenantId,
+              returnNumber: after.returnNumber,
+              reason: after.reason ?? null,
+              notes: after.notes ?? null,
+              returnedAt: after.returnedAt ? new Date(after.returnedAt) : new Date(),
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            })
+          restoredHeader.order = order
+          restoredHeader.deletedAt = null
+          restoredHeader.organizationId = after.organizationId
+          restoredHeader.tenantId = after.tenantId
+          restoredHeader.returnNumber = after.returnNumber
+          restoredHeader.reason = after.reason ?? null
+          restoredHeader.notes = after.notes ?? null
+          restoredHeader.returnedAt = after.returnedAt ? new Date(after.returnedAt) : new Date()
+          restoredHeader.updatedAt = new Date()
+          em.persist(restoredHeader)
+
+          const createdAdjustments: SalesOrderAdjustment[] = []
+          after.lines.forEach((lineSnapshot, index) => {
+            const line = lineMap.get(lineSnapshot.orderLineId)
+            if (!line) return
+            const totalNet = lineSnapshot.totalNetAmount
+            const totalGross = lineSnapshot.totalGrossAmount
+            const adjustmentId = after.adjustmentIds[index] ?? randomUUID()
+
+            const returnLine = em.create(SalesReturnLine, {
+              id: lineSnapshot.id,
+              salesReturn: restoredHeader,
+              orderLine: em.getReference(SalesOrderLine, line.id),
+              organizationId: after.organizationId,
+              tenantId: after.tenantId,
+              quantityReturned: lineSnapshot.quantityReturned.toString(),
+              unitPriceNet: lineSnapshot.unitPriceNet.toString(),
+              unitPriceGross: lineSnapshot.unitPriceGross.toString(),
+              totalNetAmount: totalNet.toString(),
+              totalGrossAmount: totalGross.toString(),
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            })
+            createdLines.push(returnLine)
+            em.persist(returnLine)
+
+            const adjustment = em.create(SalesOrderAdjustment, {
+              id: adjustmentId,
+              order,
+              orderLine: em.getReference(SalesOrderLine, line.id),
+              organizationId: after.organizationId,
+              tenantId: after.tenantId,
+              scope: 'line',
+              kind: 'return',
+              rate: '0',
+              amountNet: totalNet.toString(),
+              amountGross: totalGross.toString(),
+              currencyCode: order.currencyCode,
+              metadata: { returnId, returnLineId: lineSnapshot.id },
+              position: positionStart + index,
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            })
+            createdAdjustments.push(adjustment)
+            em.persist(adjustment)
+
+            line.returnedQuantity = (toNumeric(line.returnedQuantity) + lineSnapshot.quantityReturned).toString()
+            line.updatedAt = new Date()
+            em.persist(line)
+          })
+
+          const lineSnapshots: SalesLineSnapshot[] = orderLines.map(mapOrderLineEntityToSnapshot)
+          const adjustmentDrafts: SalesAdjustmentDraft[] = [...existingAdjustments, ...createdAdjustments].map(
+            mapOrderAdjustmentToDraft,
+          )
+          const calculation = await salesCalculationService.calculateDocumentTotals({
+            documentKind: 'order',
+            lines: lineSnapshots,
+            adjustments: adjustmentDrafts,
+            context: buildCalculationContext(order),
+          })
+          applyOrderTotals(order, calculation.totals, calculation.lines.length)
+          order.updatedAt = new Date()
+          em.persist(order)
+        },
+      ],
+      { transaction: true },
+    )
+
+    const header = await findOneWithDecryption(
+      em,
+      SalesReturn,
+      { id: after.id, deletedAt: null },
+      {},
+      { tenantId: after.tenantId, organizationId: after.organizationId },
+    )
+    if (!header) {
+      throw new CrudHttpError(404, { error: 'sales.returns.orderMissing' })
+    }
+
+    const dataEngine = ctx.container.resolve('dataEngine') as DataEngine
+    await emitCrudSideEffects({
+      dataEngine,
+      action: 'created',
+      entity: header,
+      identifiers: { id: header.id, organizationId: header.organizationId, tenantId: header.tenantId },
+      indexer: { entityType: E.sales.sales_return },
+      events: returnCrudEvents,
+    })
+
+    if (createdLines.length) {
+      await Promise.all(
+        createdLines.map((line) =>
+          emitCrudSideEffects({
+            dataEngine,
+            action: 'created',
+            entity: line,
+            identifiers: { id: line.id, organizationId: line.organizationId, tenantId: line.tenantId },
+            indexer: { entityType: E.sales.sales_return_line },
+          }),
+        ),
+      )
+    }
+
+    return { returnId: header.id }
+  },
 }
 
 registerCommand(createReturnCommand)

package/src/modules/sales/commands/shared.ts

@@ -2,10 +2,46 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 export { assertFound } from '@open-mercato/shared/lib/crud/errors'
 export { ensureOrganizationScope, ensureSameScope, ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
 export { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
 
+/** Resource kinds used by the document-aggregate optimistic-lock check. */
+export const SALES_RESOURCE_KIND_ORDER = 'sales.order'
+export const SALES_RESOURCE_KIND_QUOTE = 'sales.quote'
+
+/**
+ * Enforce the document-aggregate OSS optimistic lock for a sales sub-resource
+ * command (lines, adjustments, shipments, payments, returns, quote
+ * conversion). The client sends the parent order/quote's expected `updated_at`
+ * via the optimistic-lock extension header; this compares it against the
+ * already-loaded document and throws the structured 409 on mismatch.
+ *
+ * The parent document is the consistency boundary: sub-resource mutations
+ * recalculate document totals (or transition the document), which dirties the
+ * parent so its `updated_at` advances on flush — meaning concurrent sub-edits
+ * observe each other and conflict. Call this AFTER loading + scope-checking the
+ * document and BEFORE mutating, so `document.updatedAt` is the pre-mutation
+ * version.
+ *
+ * Strictly additive: when the client sends no header the check is a no-op, so
+ * existing API consumers are unaffected. Respects `OM_OPTIMISTIC_LOCK`.
+ */
+export function enforceSalesDocumentOptimisticLock(
+  ctx: CommandRuntimeContext,
+  document: { id: string; updatedAt?: Date | string | null } | null | undefined,
+  resourceKind: string,
+): void {
+  if (!document) return
+  enforceCommandOptimisticLock({
+    resourceKind,
+    resourceId: document.id,
+    current: document.updatedAt ?? null,
+    request: ctx.request ?? null,
+  })
+}
+
 export function cloneJson<T>(value: T): T {
   if (value === null || value === undefined) return value
   return JSON.parse(JSON.stringify(value)) as T