@open-mercato/core 0.6.7-develop.6661.1.0043ed1d03 → 0.6.7-develop.6670.1.4efa7961c6

package/src/modules/wms/index.ts

@@ -0,0 +1,15 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+import './commands'
+
+export const metadata: ModuleInfo = {
+  name: 'wms',
+  title: 'Warehouse Management System',
+  version: '0.1.0',
+  description: 'Warehouse topology, inventory balances, reservations, and movement ledger.',
+  author: 'Open Mercato Team',
+  license: 'MIT',
+  ejectable: true,
+  requires: ['catalog', 'sales', 'feature_toggles'],
+}
+
+export { features } from './acl'

package/src/modules/wms/lib/catalogInventoryProfileIntent.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod'
+
+const inventoryStrategySchema = z.enum(['fifo', 'lifo', 'fefo'])
+
+export const catalogInventoryProfileIntentSchema = z.object({
+  manageInventory: z.boolean(),
+  defaultUom: z.string().trim().max(32).nullable().optional(),
+  defaultStrategy: inventoryStrategySchema.optional(),
+  trackLot: z.boolean().optional(),
+  trackSerial: z.boolean().optional(),
+  trackExpiration: z.boolean().optional(),
+  reorderPoint: z.coerce.number().finite().min(0).nullable().optional(),
+  safetyStock: z.coerce.number().finite().min(0).nullable().optional(),
+}).superRefine((payload, ctx) => {
+  if (!payload.manageInventory) return
+
+  if (!payload.defaultUom || payload.defaultUom.trim().length === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['defaultUom'],
+      message: 'wms.widgets.catalog.inventoryProfile.errors.defaultUomRequired',
+    })
+  }
+
+  if (!payload.defaultStrategy) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['defaultStrategy'],
+      message: 'wms.widgets.catalog.inventoryProfile.errors.strategyRequired',
+    })
+  }
+
+  if (payload.trackExpiration && payload.defaultStrategy !== 'fefo') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['defaultStrategy'],
+      message: 'wms.widgets.catalog.inventoryProfile.errors.fefoRequired',
+    })
+  }
+})
+
+export type CatalogInventoryProfileIntent = z.infer<
+  typeof catalogInventoryProfileIntentSchema
+>
+
+export const WMS_CATALOG_PROFILE_HEADER =
+  'x-open-mercato-wms-catalog-profile'
+
+export function encodeCatalogInventoryProfileIntent(
+  intent: CatalogInventoryProfileIntent,
+): string {
+  return encodeURIComponent(JSON.stringify(intent))
+}
+
+export function decodeCatalogInventoryProfileIntent(
+  rawHeader: string | null | undefined,
+): CatalogInventoryProfileIntent | null {
+  if (typeof rawHeader !== 'string' || rawHeader.trim().length === 0) {
+    return null
+  }
+
+  const decoded = decodeURIComponent(rawHeader)
+  const parsed = JSON.parse(decoded) as unknown
+  return catalogInventoryProfileIntentSchema.parse(parsed)
+}

package/src/modules/wms/lib/catalogInventoryProfileSync.ts

@@ -0,0 +1,199 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import type { QueryEngine } from '@open-mercato/shared/lib/query/types'
+import { E } from '#generated/entities.ids.generated'
+import { ProductInventoryProfile } from '../data/entities'
+import {
+  catalogInventoryProfileIntentSchema,
+  type CatalogInventoryProfileIntent,
+} from './catalogInventoryProfileIntent'
+
+type SyncTarget = 'product' | 'variant'
+
+type SyncCatalogInventoryProfileInput = {
+  intent: CatalogInventoryProfileIntent
+  target: SyncTarget
+  recordId: string
+  organizationId: string
+  tenantId: string
+  userId: string
+  container: AwilixContainer
+}
+
+function normalizeOptionalString(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+function buildCommandContext(params: {
+  container: AwilixContainer
+  organizationId: string
+  tenantId: string
+  userId: string
+}): CommandRuntimeContext {
+  const auth: AuthContext = {
+    sub: params.userId,
+    userId: params.userId,
+    tenantId: params.tenantId,
+    orgId: params.organizationId,
+  }
+
+  return {
+    container: params.container,
+    auth,
+    organizationScope: null,
+    selectedOrganizationId: params.organizationId,
+    organizationIds: [params.organizationId],
+  }
+}
+
+async function loadExistingProfile(params: {
+  organizationId: string
+  tenantId: string
+  target: SyncTarget
+  recordId: string
+  catalogProductId: string
+  container: AwilixContainer
+}) {
+  const em = params.container.resolve('em') as EntityManager
+  const scope = {
+    organizationId: params.organizationId,
+    tenantId: params.tenantId,
+  }
+
+  if (params.target === 'variant') {
+    return findOneWithDecryption(
+      em,
+      ProductInventoryProfile,
+      {
+        organizationId: params.organizationId,
+        tenantId: params.tenantId,
+        deletedAt: null,
+        catalogVariantId: params.recordId,
+      } as never,
+      undefined,
+      scope,
+    )
+  }
+
+  return findOneWithDecryption(
+    em,
+    ProductInventoryProfile,
+    {
+      organizationId: params.organizationId,
+      tenantId: params.tenantId,
+      deletedAt: null,
+      catalogProductId: params.catalogProductId,
+      catalogVariantId: null,
+    } as never,
+    undefined,
+    scope,
+  )
+}
+
+async function resolveCatalogProductId(params: {
+  target: SyncTarget
+  recordId: string
+  organizationId: string
+  tenantId: string
+  container: AwilixContainer
+}): Promise<string> {
+  if (params.target === 'product') return params.recordId
+
+  // Read the variant -> product_id mapping via QueryEngine so this module does
+  // not import the catalog ORM entity directly. queryEngine resolves the
+  // base table via Mikro-ORM metadata, so the only cross-module surface we
+  // depend on is the public catalog entity id from the `E` registry.
+  const queryEngine = params.container.resolve('queryEngine') as QueryEngine
+  const result = await queryEngine.query<{ id?: string; product_id?: string }>(
+    E.catalog.catalog_product_variant,
+    {
+      tenantId: params.tenantId,
+      organizationId: params.organizationId,
+      filters: { id: { $eq: params.recordId } },
+      fields: ['id', 'product_id'],
+      page: { page: 1, pageSize: 1 },
+    },
+  )
+
+  const variantRow = result.items[0]
+  if (!variantRow) {
+    throw new Error(`Variant ${params.recordId} not found for WMS profile sync`)
+  }
+
+  const productId = typeof variantRow.product_id === 'string' ? variantRow.product_id : null
+  if (!productId) {
+    throw new Error(
+      `Variant ${params.recordId} is missing product context for WMS profile sync`,
+    )
+  }
+
+  return productId
+}
+
+export async function syncCatalogInventoryProfile(
+  input: SyncCatalogInventoryProfileInput,
+): Promise<void> {
+  const intent = catalogInventoryProfileIntentSchema.parse(input.intent)
+  const commandBus = input.container.resolve('commandBus') as CommandBus
+  const ctx = buildCommandContext(input)
+  const catalogProductId = await resolveCatalogProductId({
+    target: input.target,
+    recordId: input.recordId,
+    organizationId: input.organizationId,
+    tenantId: input.tenantId,
+    container: input.container,
+  })
+
+  const existingProfile = await loadExistingProfile({
+    organizationId: input.organizationId,
+    tenantId: input.tenantId,
+    target: input.target,
+    recordId: input.recordId,
+    catalogProductId,
+    container: input.container,
+  })
+
+  if (!intent.manageInventory) {
+    if (!existingProfile) return
+    await commandBus.execute('wms.inventoryProfiles.delete', {
+      input: { id: existingProfile.id },
+      ctx,
+    })
+    return
+  }
+
+  const profileInput = {
+    organizationId: input.organizationId,
+    tenantId: input.tenantId,
+    catalogProductId,
+    catalogVariantId: input.target === 'variant' ? input.recordId : null,
+    defaultUom: normalizeOptionalString(intent.defaultUom),
+    defaultStrategy: intent.defaultStrategy,
+    trackLot: intent.trackLot ?? false,
+    trackSerial: intent.trackSerial ?? false,
+    trackExpiration: intent.trackExpiration ?? false,
+    reorderPoint: intent.reorderPoint ?? 0,
+    safetyStock: intent.safetyStock ?? 0,
+  }
+
+  if (existingProfile) {
+    await commandBus.execute('wms.inventoryProfiles.update', {
+      input: {
+        id: existingProfile.id,
+        ...profileInput,
+      },
+      ctx,
+    })
+    return
+  }
+
+  await commandBus.execute('wms.inventoryProfiles.create', {
+    input: profileInput,
+    ctx,
+  })
+}

package/src/modules/wms/lib/expiry.ts

@@ -0,0 +1,30 @@
+export const EXPIRING_SOON_DAYS = 30
+
+export type ExpiryWindow = 'expiringSoon' | 'pastDue'
+
+export function startOfUtcDay(date: Date): Date {
+  return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()))
+}
+
+export function addUtcDays(date: Date, days: number): Date {
+  const next = new Date(date)
+  next.setUTCDate(next.getUTCDate() + days)
+  return next
+}
+
+export function buildExpiryWindowDateFilter(
+  expiryWindow: ExpiryWindow,
+  now: Date = new Date(),
+): Record<string, unknown> {
+  const today = startOfUtcDay(now)
+  if (expiryWindow === 'pastDue') {
+    return { expires_at: { $ne: null, $lt: today } }
+  }
+  return {
+    expires_at: {
+      $ne: null,
+      $gte: today,
+      $lte: addUtcDays(today, EXPIRING_SOON_DAYS),
+    },
+  }
+}

package/src/modules/wms/lib/flashMutationError.ts

@@ -0,0 +1,74 @@
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+
+/**
+ * Maps a `requireFeatures` ACL feature id to the i18n key that names the
+ * specific permission a 403 response is missing (#4102 follow-up — the
+ * generic "Forbidden" toast didn't say what was denied).
+ */
+const FORBIDDEN_FEATURE_MESSAGE_KEYS: Record<string, string> = {
+  'wms.manage_warehouses': 'wms.errors.forbidden.manageWarehouses',
+  'wms.manage_zones': 'wms.errors.forbidden.manageZones',
+  'wms.manage_locations': 'wms.errors.forbidden.manageLocations',
+  'wms.manage_inventory': 'wms.errors.forbidden.manageInventory',
+  'wms.manage_reservations': 'wms.errors.forbidden.manageReservations',
+  'wms.adjust_inventory': 'wms.errors.forbidden.adjustInventory',
+  'wms.receive_inventory': 'wms.errors.forbidden.receiveInventory',
+  'wms.cycle_count': 'wms.errors.forbidden.cycleCount',
+  'wms.import': 'wms.errors.forbidden.import',
+}
+
+const FORBIDDEN_FEATURE_MESSAGE_FALLBACKS: Record<string, string> = {
+  'wms.manage_warehouses': "You don't have permission to manage warehouses.",
+  'wms.manage_zones': "You don't have permission to manage warehouse zones.",
+  'wms.manage_locations': "You don't have permission to manage warehouse locations.",
+  'wms.manage_inventory': "You don't have permission to manage inventory profiles.",
+  'wms.manage_reservations': "You don't have permission to manage inventory reservations.",
+  'wms.adjust_inventory': "You don't have permission to adjust or move inventory.",
+  'wms.receive_inventory': "You don't have permission to receive inbound inventory.",
+  'wms.cycle_count': "You don't have permission to run cycle counts.",
+  'wms.import': "You don't have permission to import inventory.",
+}
+
+/**
+ * Reads the 403 response's `requiredFeatures` (attached to the thrown error
+ * by `raiseCrudError`) and, when the missing feature is a known WMS
+ * permission, resolves a translated message naming it. Returns `null` when
+ * the error isn't a recognized 403-with-features shape so callers can fall
+ * back to the generic message.
+ */
+function resolveForbiddenFeatureMessage(error: unknown, t?: TranslateFn): string | null {
+  if (!error || typeof error !== 'object') return null
+  const status = (error as Record<string, unknown>).status
+  if (status !== 403) return null
+  const requiredFeatures = (error as Record<string, unknown>).requiredFeatures
+  if (!Array.isArray(requiredFeatures)) return null
+  const knownFeature = requiredFeatures.find(
+    (feature): feature is string => typeof feature === 'string' && feature in FORBIDDEN_FEATURE_MESSAGE_KEYS,
+  )
+  if (!knownFeature) return null
+  const key = FORBIDDEN_FEATURE_MESSAGE_KEYS[knownFeature]
+  const fallback = FORBIDDEN_FEATURE_MESSAGE_FALLBACKS[knownFeature]
+  return t ? t(key, fallback) : fallback
+}
+
+/**
+ * Surfaces a mutation failure as an error flash toast. Prefers a
+ * feature-specific 403 message derived from the server's `requiredFeatures`
+ * hint (#4102 follow-up), then the thrown error's own message (already
+ * server-derived and translated by `raiseCrudError`/`useGuardedMutation`),
+ * and falls back to a translated, dialog-specific message otherwise (#4103).
+ */
+export function flashMutationError(error: unknown, fallbackMessage: string, t?: TranslateFn): void {
+  const forbiddenMessage = resolveForbiddenFeatureMessage(error, t)
+  if (forbiddenMessage) {
+    flash(forbiddenMessage, 'error')
+    return
+  }
+  // apiFetch throws ForbiddenError with a bare "Forbidden" message when the
+  // ACL body has no mappable feature — prefer the dialog-specific fallback
+  // over flashing the untranslated server token.
+  const rawMessage = error instanceof Error ? error.message.trim() : ''
+  const isGenericForbidden = rawMessage.length === 0 || /^forbidden$/i.test(rawMessage)
+  flash(isGenericForbidden ? fallbackMessage : rawMessage, 'error')
+}

package/src/modules/wms/lib/inventoryDisplayUi.ts

@@ -0,0 +1,249 @@
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { parseInventoryQuantity } from './inventoryMutationUi'
+
+export type InventoryDisplayTranslator = TranslateFn
+
+const MOVEMENT_TYPE_FALLBACKS: Record<string, string> = {
+  receipt: 'Receive',
+  return_receive: 'Receive',
+  adjust: 'Adjust',
+  transfer: 'Move',
+  pick: 'Allocate',
+  pack: 'Allocate',
+  cycle_count: 'Reconcile',
+  putaway: 'Putaway',
+  ship: 'Ship',
+}
+
+const RESERVATION_SOURCE_TYPE_FALLBACKS: Record<string, string> = {
+  order: 'Sales order',
+  transfer: 'Transfer',
+  manual: 'Manual',
+}
+
+const REFERENCE_TYPE_FALLBACKS: Record<string, string> = {
+  po: 'Purchase order',
+  so: 'Sales order',
+  transfer: 'Transfer',
+  manual: 'Manual',
+  qc: 'Quality control',
+  rma: 'RMA',
+}
+
+const RESERVATION_STATUS_FALLBACKS: Record<string, string> = {
+  active: 'Active',
+  released: 'Released',
+  fulfilled: 'Fulfilled',
+}
+
+const ROTATION_STRATEGY_FALLBACKS: Record<string, string> = {
+  fifo: 'FIFO',
+  lifo: 'LIFO',
+  fefo: 'FEFO',
+}
+
+const ADJUST_REASON_FALLBACKS: Record<string, string> = {
+  damaged: 'Damaged',
+  shrinkage: 'Shrinkage',
+  found: 'Found stock',
+  correction: 'Correction',
+  other: 'Other',
+}
+
+const MOVE_REASON_FALLBACKS: Record<string, string> = {
+  transfer: 'Transfer',
+  replenishment: 'Replenishment',
+  consolidation: 'Consolidation',
+  correction: 'Correction',
+  other: 'Other',
+}
+
+const RELEASE_REASON_FALLBACKS: Record<string, string> = {
+  order_cancelled: 'Order cancelled',
+  manual_release: 'Manual release',
+  correction: 'Correction',
+  other: 'Other',
+}
+
+const STABLE_REASON_CODE_PATTERN = /^[a-z][a-z0-9_]*$/
+
+export function createInventoryQuantityFormatter(locale: string): Intl.NumberFormat {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 })
+}
+
+export function formatInventoryQuantity(
+  value: string | number | null | undefined,
+  formatter: Intl.NumberFormat,
+): string {
+  return formatter.format(parseInventoryQuantity(value))
+}
+
+export function createInventoryDateTimeFormatter(
+  locale: string,
+  options: Intl.DateTimeFormatOptions = {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  },
+): Intl.DateTimeFormat {
+  return new Intl.DateTimeFormat(locale, options)
+}
+
+export function formatInventoryDateTime(
+  value: string | null | undefined,
+  formatter: Intl.DateTimeFormat,
+): string {
+  if (!value?.trim()) return '—'
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return '—'
+  return formatter.format(date)
+}
+
+export function inventoryMovementTypeLabel(type: string, t: InventoryDisplayTranslator): string {
+  const normalized = type.trim()
+  if (!normalized) return '—'
+  return t(
+    `wms.backend.dashboard.activity.types.${normalized}`,
+    MOVEMENT_TYPE_FALLBACKS[normalized] ?? normalized,
+  )
+}
+
+export function inventoryReservationSourceTypeLabel(
+  sourceType: string,
+  t: InventoryDisplayTranslator,
+): string {
+  const normalized = sourceType.trim()
+  if (!normalized) return '—'
+  return t(
+    `wms.backend.inventory.sourceTypes.${normalized}`,
+    RESERVATION_SOURCE_TYPE_FALLBACKS[normalized] ?? normalized,
+  )
+}
+
+export function inventoryReferenceTypeLabel(
+  referenceType: string,
+  t: InventoryDisplayTranslator,
+): string {
+  const normalized = referenceType.trim()
+  if (!normalized) return '—'
+  return t(
+    `wms.backend.inventory.referenceTypes.${normalized}`,
+    REFERENCE_TYPE_FALLBACKS[normalized] ?? normalized,
+  )
+}
+
+export function inventoryReservationStatusLabel(status: string, t: InventoryDisplayTranslator): string {
+  const normalized = status.trim()
+  if (!normalized) return '—'
+  return t(
+    `wms.backend.inventory.reservationStatuses.${normalized}`,
+    RESERVATION_STATUS_FALLBACKS[normalized] ?? normalized,
+  )
+}
+
+export function inventoryRotationStrategyLabel(strategy: string, t: InventoryDisplayTranslator): string {
+  const normalized = strategy.trim()
+  if (!normalized) return '—'
+  return t(
+    `wms.widgets.catalog.inventoryProfile.strategy.${normalized}`,
+    ROTATION_STRATEGY_FALLBACKS[normalized] ?? normalized,
+  )
+}
+
+function translateStableReasonCode(
+  code: string,
+  movementType: string | null | undefined,
+  t: InventoryDisplayTranslator,
+): string | null {
+  if (code === 'cycle_count') {
+    return t('wms.backend.dashboard.activity.reasons.cycleCount', 'Cycle count')
+  }
+
+  const type = (movementType ?? '').trim()
+  if (type === 'transfer' && code in MOVE_REASON_FALLBACKS) {
+    return t(`wms.backend.inventory.move.reasons.${code}`, MOVE_REASON_FALLBACKS[code])
+  }
+  if ((type === 'adjust' || type === 'cycle_count') && code in ADJUST_REASON_FALLBACKS) {
+    return t(`wms.backend.inventory.adjust.reasons.${code}`, ADJUST_REASON_FALLBACKS[code])
+  }
+  if (code in ADJUST_REASON_FALLBACKS) {
+    return t(`wms.backend.inventory.adjust.reasons.${code}`, ADJUST_REASON_FALLBACKS[code])
+  }
+  if (code in MOVE_REASON_FALLBACKS) {
+    return t(`wms.backend.inventory.move.reasons.${code}`, MOVE_REASON_FALLBACKS[code])
+  }
+  if (code in RELEASE_REASON_FALLBACKS) {
+    return t(`wms.backend.inventory.release.reasons.${code}`, RELEASE_REASON_FALLBACKS[code])
+  }
+  return null
+}
+
+/**
+ * Resolve a movement/activity reason for display. Prefers the stable
+ * `reasonCode` (re-translated for the current locale) over a free-text
+ * `reason` that may have been baked in a different language at write time.
+ */
+export function inventoryMovementReasonLabel(
+  input: {
+    reasonCode?: string | null
+    reason?: string | null
+    movementType?: string | null
+  },
+  t: InventoryDisplayTranslator,
+): string | null {
+  const reasonCode = input.reasonCode?.trim() || null
+  const reason = input.reason?.trim() || null
+  const candidateCode =
+    reasonCode ||
+    (reason && STABLE_REASON_CODE_PATTERN.test(reason) ? reason : null)
+
+  if (candidateCode) {
+    const translated = translateStableReasonCode(candidateCode, input.movementType, t)
+    if (translated) return translated
+  }
+
+  return reason
+}
+
+export function formatCatalogProductLabel(row: {
+  product_title?: string | null
+  product_sku?: string | null
+  catalog_product_id?: string | null
+}): string {
+  const title = (row.product_title ?? '').trim()
+  const sku = (row.product_sku ?? '').trim()
+  if (title && sku) return `${title} (${sku})`
+  if (title) return title
+  if (sku) return sku
+  return row.catalog_product_id?.trim() || '—'
+}
+
+export function formatCatalogVariantLabel(row: {
+  variant_name?: string | null
+  variant_sku?: string | null
+  catalog_variant_id?: string | null
+}): string {
+  const name = (row.variant_name ?? '').trim()
+  const sku = (row.variant_sku ?? '').trim()
+  if (name && sku) return `${name} (${sku})`
+  if (name) return name
+  if (sku) return sku
+  return row.catalog_variant_id?.trim() || '—'
+}
+
+export function formatReservationSourceLabel(
+  row: {
+    source_type?: string | null
+    source_id?: string | null
+    source_label?: string | null
+  },
+  t: InventoryDisplayTranslator,
+): string {
+  const sourceType = row.source_type?.trim()
+  if (!sourceType) return '—'
+  const typeLabel = inventoryReservationSourceTypeLabel(sourceType, t)
+  const sourceLabel = row.source_label?.trim()
+  if (sourceLabel) return `${typeLabel} · ${sourceLabel}`
+  return typeLabel
+}

package/src/modules/wms/lib/inventoryIdempotency.ts

@@ -0,0 +1,54 @@
+import type { InventoryMovementType, InventoryReservationSourceType } from '../data/entities'
+
+function normalizeSegment(value: string | null | undefined): string {
+  if (typeof value !== 'string' || value.trim().length === 0) return ''
+  return value.trim()
+}
+
+function normalizeQuantity(value: number): string {
+  return String(value)
+}
+
+export function buildMovementIdempotencyKey(input: {
+  referenceType: string
+  referenceId: string
+  type: InventoryMovementType
+  warehouseId: string
+  locationFromId?: string | null
+  locationToId?: string | null
+  catalogVariantId: string
+  lotId?: string | null
+  serialNumber?: string | null
+  quantity: number
+}): string {
+  return [
+    'movement',
+    normalizeSegment(input.referenceType),
+    normalizeSegment(input.referenceId),
+    normalizeSegment(input.type),
+    normalizeSegment(input.warehouseId),
+    normalizeSegment(input.locationFromId),
+    normalizeSegment(input.locationToId),
+    normalizeSegment(input.catalogVariantId),
+    normalizeSegment(input.lotId),
+    normalizeSegment(input.serialNumber),
+    normalizeQuantity(input.quantity),
+  ].join('|')
+}
+
+export function buildReservationIdempotencyKey(input: {
+  sourceType: InventoryReservationSourceType
+  sourceId: string
+  catalogVariantId: string
+  warehouseId: string
+  quantity: number
+}): string {
+  return [
+    'reservation',
+    normalizeSegment(input.sourceType),
+    normalizeSegment(input.sourceId),
+    normalizeSegment(input.catalogVariantId),
+    normalizeSegment(input.warehouseId),
+    normalizeQuantity(input.quantity),
+  ].join('|')
+}