@open-mercato/core 0.10.1-develop.7709.1.046124599c → 0.10.1-develop.7714.1.9dbb8200d8

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

@@ -1,10 +1,40 @@
-import type { InventoryLotStatus, InventoryStrategy } from '../data/entities'
+import type {
+  InventoryLotStatus,
+  InventoryStrategy,
+  WarehouseLocationType,
+} from '../data/entities'
 
 type LotEligibilityInput = {
   status?: InventoryLotStatus | null
   expiresAt?: Date | null
 } | null | undefined
 
+/** Staging/dock hold inbound stock; Phase 2 must not treat them as pick/reserve candidates. */
+export const NON_RESERVABLE_LOCATION_TYPES: ReadonlySet<WarehouseLocationType> = new Set([
+  'staging',
+  'dock',
+])
+
+export function isReservableLocationType(type: string | null | undefined): boolean {
+  if (typeof type !== 'string' || type.length === 0) return true
+  return !NON_RESERVABLE_LOCATION_TYPES.has(type as WarehouseLocationType)
+}
+
+/**
+ * Returns false when the balance sits on staging/dock. Unpopulated location FKs
+ * (string id only) stay eligible so callers that omit `populate: ['location']`
+ * do not accidentally empty the candidate set.
+ */
+export function isBalanceLocationReservable(balance: { location?: unknown }): boolean {
+  const location = balance.location
+  if (!location || typeof location === 'string') return true
+  const type =
+    typeof (location as { type?: unknown }).type === 'string'
+      ? (location as { type: string }).type
+      : null
+  return isReservableLocationType(type)
+}
+
 export function isLotEligible(lot: LotEligibilityInput, now: Date = new Date()): boolean {
   if (!lot) return true
   if (lot.status !== 'available') return false

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

@@ -1,6 +1,7 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import {
+  Asn,
   InventoryBalance,
   InventoryLot,
   InventoryMovement,
@@ -16,6 +17,8 @@ const TREND_DAYS = 7
 const MONTHLY_TREND_MONTHS = 6
 const ACTIVITY_LIMIT = 10
 const EXPIRY_CARD_LIMIT = 5
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
 export type OperationalDashboardScope = {
   organizationId: string
@@ -52,8 +55,12 @@ export type OperationalDashboardActivityRow = {
   variantId: string
   referenceType: string | null
   referenceId: string | null
+  /** Human-readable reference (e.g. ASN reference number) — never the idempotency UUID. */
+  referenceLabel: string | null
   reason: string | null
   reasonCode: string | null
+  /** Movement metadata `source` (e.g. `asn_receive`) for activity label recovery. */
+  source: string | null
   locationLabel: string
   performedAt: string
 }
@@ -340,6 +347,66 @@ async function loadVariantSkus(
   return map
 }
 
+function readMovementMetadataRecord(
+  metadata: InventoryMovement['metadata'],
+): Record<string, unknown> | null {
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return null
+  return metadata as Record<string, unknown>
+}
+
+export function extractActivityMovementSource(
+  metadata: InventoryMovement['metadata'],
+): string | null {
+  const record = readMovementMetadataRecord(metadata)
+  const source = record?.source
+  return typeof source === 'string' && source.trim() ? source.trim() : null
+}
+
+export function extractActivityAsnId(metadata: InventoryMovement['metadata']): string | null {
+  const record = readMovementMetadataRecord(metadata)
+  const asnId = record?.asnId
+  if (typeof asnId !== 'string') return null
+  const trimmed = asnId.trim()
+  return UUID_PATTERN.test(trimmed) ? trimmed : null
+}
+
+export function extractActivityAsnReferenceNumber(
+  metadata: InventoryMovement['metadata'],
+): string | null {
+  const record = readMovementMetadataRecord(metadata)
+  const value = record?.asnReferenceNumber
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+async function loadAsnReferenceNumbers(
+  em: EntityManager,
+  scope: OperationalDashboardScope,
+  asnIds: string[],
+): Promise<Map<string, string>> {
+  if (asnIds.length === 0) return new Map()
+  const decryptionScope = resolveDecryptionScope(scope)
+  const asns = await findWithDecryption(
+    em,
+    Asn,
+    {
+      id: { $in: asnIds },
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    },
+    undefined,
+    decryptionScope,
+  )
+  const map = new Map<string, string>()
+  for (const asn of asns) {
+    const label = asn.referenceNumber?.trim()
+    if (label) map.set(asn.id, label)
+  }
+  return map
+}
+
 async function loadVariantIdsForProductLevelProfiles(
   em: EntityManager,
   scope: OperationalDashboardScope,
@@ -785,8 +852,27 @@ export async function loadOperationalDashboard(
   const variantIds = Array.from(new Set(activityMovements.map((movement) => movement.catalogVariantId)))
   const variantSkus = await loadVariantSkus(em, scope, variantIds)
 
+  const asnIdsNeedingLookup = Array.from(
+    new Set(
+      activityMovements
+        .map((movement) => {
+          if (extractActivityAsnReferenceNumber(movement.metadata)) return null
+          return extractActivityAsnId(movement.metadata)
+        })
+        .filter((id): id is string => Boolean(id)),
+    ),
+  )
+  const asnReferenceNumbers = await loadAsnReferenceNumbers(em, scope, asnIdsNeedingLookup)
+
   const recentActivity: OperationalDashboardActivityRow[] = activityMovements.map((movement) => {
     const warehouseLabel = resolveWarehouseLabel(movement.warehouse, movement.warehouse.id)
+    const source = extractActivityMovementSource(movement.metadata)
+    const metadataAsnReference = extractActivityAsnReferenceNumber(movement.metadata)
+    const asnId = extractActivityAsnId(movement.metadata)
+    const referenceLabel =
+      metadataAsnReference ?? (asnId ? asnReferenceNumbers.get(asnId) ?? null : null)
+    const reasonCode =
+      movement.reasonCode?.trim() || (source === 'asn_receive' ? 'asn_receive' : null)
     return {
       id: movement.id,
       movementType: movement.type,
@@ -795,8 +881,10 @@ export async function loadOperationalDashboard(
       variantId: movement.catalogVariantId,
       referenceType: movement.referenceType ?? null,
       referenceId: movement.referenceId ?? null,
+      referenceLabel,
       reason: movement.reason ?? null,
-      reasonCode: movement.reasonCode ?? null,
+      reasonCode,
+      source,
       locationLabel: resolveLocationLabel(
         warehouseLabel,
         movement.locationFrom?.code,

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

@@ -0,0 +1,210 @@
+import { createHash } from 'crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  InventoryMovement,
+  type PutawayTaskStatus,
+  type WarehouseLocationType,
+} from '../data/entities'
+
+const TERMINAL: ReadonlySet<PutawayTaskStatus> = new Set(['done', 'cancelled'])
+const FORBIDDEN_PUTAWAY_TARGET_TYPES: ReadonlySet<WarehouseLocationType> = new Set(['staging', 'dock'])
+const PUTAWAY_TASK_STATUSES: ReadonlySet<PutawayTaskStatus> = new Set([
+  'open',
+  'in_progress',
+  'done',
+  'cancelled',
+])
+
+/**
+ * Parse list `status` query: single value or comma-separated (e.g. `open,in_progress`).
+ * Returns `$eq` / `$in` filter fragment, or undefined when empty/invalid.
+ */
+export function buildPutawayTaskStatusFilter(
+  statusQuery: string | undefined,
+): { $eq: PutawayTaskStatus } | { $in: PutawayTaskStatus[] } | undefined {
+  if (typeof statusQuery !== 'string' || statusQuery.trim().length === 0) return undefined
+  const statuses = [
+    ...new Set(
+      statusQuery
+        .split(',')
+        .map((value) => value.trim())
+        .filter((value): value is PutawayTaskStatus =>
+          PUTAWAY_TASK_STATUSES.has(value as PutawayTaskStatus),
+        ),
+    ),
+  ]
+  if (statuses.length === 0) return undefined
+  if (statuses.length === 1) return { $eq: statuses[0]! }
+  return { $in: statuses }
+}
+
+export function assertPutawayAssignable(status: PutawayTaskStatus): void {
+  if (TERMINAL.has(status)) {
+    throw new CrudHttpError(409, { error: 'invalid_putaway_state' })
+  }
+}
+
+export function assertPutawayStartable(status: PutawayTaskStatus): void {
+  if (status !== 'open' && status !== 'in_progress') {
+    throw new CrudHttpError(409, { error: 'invalid_putaway_state' })
+  }
+}
+
+export function assertPutawayCompletable(status: PutawayTaskStatus): void {
+  if (status !== 'open' && status !== 'in_progress') {
+    throw new CrudHttpError(409, { error: 'invalid_putaway_state' })
+  }
+}
+
+export function assertPutawayCancellable(status: PutawayTaskStatus): void {
+  if (TERMINAL.has(status)) {
+    throw new CrudHttpError(409, { error: 'invalid_putaway_state' })
+  }
+}
+
+/**
+ * Soft-delete is archival cleanup for cancelled tasks only.
+ * Done is permanent history: soft-deleting it would drop the row from the
+ * partial unique index (`deleted_at IS NULL`) while leaving `putaway_key`,
+ * letting idempotent ASN receive recreate an open putaway for already-moved stock.
+ * Cancel first (clears the key); refuse open/in_progress/done delete.
+ */
+export function assertPutawayDeletable(status: PutawayTaskStatus): void {
+  if (status === 'cancelled') return
+  if (status === 'done') {
+    throw new CrudHttpError(409, { error: 'putaway_delete_done_forbidden' })
+  }
+  throw new CrudHttpError(409, { error: 'putaway_delete_requires_terminal_status' })
+}
+
+/** Reject lifecycle fields on putaway-task CRUD before zod strips them. */
+export function assertPutawayLifecycleFieldsForbidden(rawInput: unknown): void {
+  if (!rawInput || typeof rawInput !== 'object') return
+  const payload = rawInput as Record<string, unknown>
+  // Status and assignee changes go through dedicated lifecycle endpoints.
+  if ('status' in payload || 'assignedTo' in payload || 'assigned_to' in payload) {
+    throw new CrudHttpError(422, { error: 'lifecycle_field_forbidden' })
+  }
+}
+
+/**
+ * Complete authorization: managers may complete any task; operators with
+ * `wms.adjust_inventory` may complete only when the task is assigned to them.
+ */
+export function assertPutawayCompleteAuthorized(input: {
+  canManagePutaway: boolean
+  canAdjustInventory: boolean
+  actorUserId: string | null | undefined
+  assignedTo: string | null | undefined
+}): void {
+  if (input.canManagePutaway) return
+  if (
+    input.canAdjustInventory
+    && typeof input.actorUserId === 'string'
+    && input.actorUserId.length > 0
+    && input.assignedTo === input.actorUserId
+  ) {
+    return
+  }
+  throw new CrudHttpError(403, { error: 'Forbidden' })
+}
+
+/** Reject completing with more than the open task quantity. */
+export function assertPutawayConfirmedQuantity(
+  taskQuantity: number,
+  confirmedQuantity: number,
+): void {
+  if (!(confirmedQuantity > 0) || !Number.isFinite(confirmedQuantity)) {
+    throw new CrudHttpError(422, { error: 'invalid_putaway_quantity' })
+  }
+  if (confirmedQuantity > taskQuantity + 0.000001) {
+    throw new CrudHttpError(422, { error: 'putaway_quantity_exceeds_task' })
+  }
+}
+
+export function putawayResidualQuantity(taskQuantity: number, confirmedQuantity: number): number {
+  const residual = taskQuantity - confirmedQuantity
+  return residual > 0.000001 ? residual : 0
+}
+
+/**
+ * Staging floor for new putaway: on-hand minus reserved/allocated minus open
+ * and in-progress putaway commitments (optionally excluding one task being updated).
+ */
+export function computeUncommittedPutawaySourceQuantity(input: {
+  quantityOnHand: number
+  quantityReserved: number
+  quantityAllocated: number
+  openPutawayQuantities: number[]
+}): number {
+  const available =
+    input.quantityOnHand - input.quantityReserved - input.quantityAllocated
+  const committed = input.openPutawayQuantities.reduce((sum, qty) => sum + qty, 0)
+  return available - committed
+}
+
+/** True when requested qty fits the uncommitted staging floor (epsilon-tolerant). */
+export function hasUncommittedPutawaySourceQuantity(
+  remainingAvailable: number,
+  requestedQuantity: number,
+): boolean {
+  return requestedQuantity <= remainingAvailable + 0.000001
+}
+
+/**
+ * Prefer an open/in_progress peer whose quantity covers the receipt when
+ * recreate would oversubscribe staging stock already queued elsewhere.
+ */
+export function selectCoveringOpenPutawayTask<T extends { quantity: number }>(
+  tasks: T[],
+  requestedQuantity: number,
+): T | null {
+  if (!(requestedQuantity > 0.000001) || tasks.length === 0) return null
+  let best: T | null = null
+  for (const task of tasks) {
+    if (task.quantity + 0.000001 < requestedQuantity) continue
+    if (!best || task.quantity < best.quantity) best = task
+  }
+  return best
+}
+
+/**
+ * Stable movement reference for putaway complete — task id only (not confirmed qty).
+ * Retries with the same or different confirmedQuantity must not open a second
+ * stock move under a different idempotency signature; quantity conflicts are
+ * detected by looking up this reference before moving.
+ */
+export function buildPutawayCompleteReferenceId(taskId: string): string {
+  const hex = createHash('sha256').update(`wms:putaway-complete:${taskId}`).digest('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+export function assertPutawayTargetLocationType(type: WarehouseLocationType): void {
+  if (FORBIDDEN_PUTAWAY_TARGET_TYPES.has(type)) {
+    throw new CrudHttpError(422, { error: 'invalid_putaway_target_location' })
+  }
+}
+
+export async function resolveLotIdFromMovement(
+  em: EntityManager,
+  ctx: CommandRuntimeContext,
+  movementId: string,
+): Promise<string | null> {
+  const tenantId = ctx.auth?.tenantId ?? null
+  const organizationId = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
+  if (!tenantId || !organizationId) return null
+  const movement = await findOneWithDecryption(
+    em,
+    InventoryMovement,
+    { id: movementId, deletedAt: null },
+    undefined,
+    { tenantId, organizationId },
+  )
+  if (!movement) return null
+  const lotRaw = movement.lot ?? null
+  if (!lotRaw) return null
+  return typeof lotRaw === 'string' ? lotRaw : lotRaw.id
+}

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

@@ -20,6 +20,8 @@ export const WMS_MANAGE_FEATURES = [
   'wms.manage_locations',
   'wms.manage_inventory',
   'wms.manage_reservations',
+  'wms.manage_asn',
+  'wms.manage_putaway',
 ] as const
 
 export const WMS_SUPERVISOR_FEATURES = [

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

@@ -3,11 +3,13 @@ import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import type { FeatureTogglesService } from '@open-mercato/core/modules/feature_toggles/lib/feature-flag-check'
+import { createLogger } from '@open-mercato/shared/lib/logger'
 import type { QueryEngine } from '@open-mercato/shared/lib/query/types'
 import { E } from '#generated/entities.ids.generated'
 import { InventoryBalance, InventoryReservation } from '../data/entities'
 import { emitWmsEvent } from '../events'
 import { loadExplicitWarehouseIdForOrder } from './salesOrderWarehouseAssignment'
+import { isBalanceLocationReservable } from './inventoryPolicy'
 import {
   resolvePrimaryWarehouseId,
   sortWarehouseAvailabilityForReservation,
@@ -15,6 +17,8 @@ import {
 } from './primaryWarehousePolicy'
 import { resolveWmsIntegrationToggleEnabled } from './wmsIntegrationToggles'
 
+const logger = createLogger('wms')
+
 type EventContext = {
   resolve: <T = unknown>(name: string) => T
 }
@@ -49,10 +53,29 @@ type SalesOrderRow = {
   id?: string
   order_number?: string | null
   status?: string | null
+  fulfillment_status?: string | null
   tenant_id?: string | null
   organization_id?: string | null
 }
 
+/** Only confirmed (non-fulfilled / non-cancelled) orders may receive re-reservations. */
+export function isReservableOrderStatus(
+  status?: string | null,
+  fulfillmentStatus?: string | null,
+): boolean {
+  const normalized = (status ?? '').trim().toLowerCase()
+  if (normalized !== 'confirmed') return false
+  const fulfillment = (fulfillmentStatus ?? '').trim().toLowerCase()
+  if (
+    fulfillment === 'fulfilled' ||
+    fulfillment === 'cancelled' ||
+    fulfillment === 'canceled'
+  ) {
+    return false
+  }
+  return true
+}
+
 type SalesOrderLineRow = {
   id?: string
   kind?: string | null
@@ -197,7 +220,7 @@ async function loadBalances(
       organizationId: scope.organizationId,
       deletedAt: null,
     },
-    undefined,
+    { populate: ['location'] },
     scope,
   )
 }
@@ -232,6 +255,10 @@ function buildWarehouseAvailability(
 ): Map<string, WarehouseAvailability[]> {
   const byVariant = new Map<string, Map<string, number>>()
   for (const balance of balances) {
+    // Staging/dock are inbound holding locations — availability for sales
+    // reservation must ignore them so ASN receive re-eval does not claim
+    // stock that putaway still needs to move into storage.
+    if (!isBalanceLocationReservable(balance)) continue
     const warehouseId = getWarehouseId(balance)
     if (!warehouseId) continue
     const available =
@@ -364,6 +391,128 @@ export async function reserveInventoryForConfirmedOrder(
   }
 }
 
+type StockIncreasePayload = {
+  catalogVariantId?: string | null
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+/**
+ * Re-runs reservation automation for sales orders that include the received
+ * catalog variant. Idempotent: reserveInventoryForConfirmedOrder only fills
+ * remaining shortfall. No-ops when the sales integration toggle is off or
+ * sales query peers are unavailable.
+ *
+ * Candidate discovery starts from currently reservable (confirmed,
+ * non-terminal fulfillment) sales orders — not lifetime `sales_order_line`
+ * history for the variant — then keeps only orders that still reference the
+ * received catalog variant. That bounds work to the open order set.
+ */
+const REEVAL_ORDER_PAGE_SIZE = 500
+
+export async function reevaluateReservationsAfterStockIncrease(
+  payload: StockIncreasePayload,
+  ctx: EventContext,
+): Promise<void> {
+  if (!payload.catalogVariantId || !payload.tenantId || !payload.organizationId) return
+  if (!(await isInventoryAutomationEnabled(ctx, payload.tenantId))) return
+
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+
+  let queryEngine: QueryEngine
+  try {
+    queryEngine = ctx.resolve<QueryEngine>('queryEngine')
+  } catch {
+    // Sales module / query engine absent or unavailable — degrade gracefully.
+    return
+  }
+
+  // Page reservable orders, then intersect with lines for this variant.
+  // Process each page immediately (bounded memory); reserveInventoryForConfirmedOrder is idempotent.
+  let page = 1
+
+  for (;;) {
+    let orderItems: SalesOrderRow[]
+    try {
+      const result = await queryEngine.query<SalesOrderRow>(E.sales.sales_order, {
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        filters: { status: { $eq: 'confirmed' } },
+        fields: ['id', 'status', 'fulfillment_status'],
+        page: { page, pageSize: REEVAL_ORDER_PAGE_SIZE },
+      })
+      orderItems = result.items
+    } catch {
+      return
+    }
+
+    if (orderItems.length === 0) break
+
+    const reservableOrderIds = orderItems
+      .filter((order) => isReservableOrderStatus(order.status, order.fulfillment_status))
+      .map((order) => order.id)
+      .filter((value): value is string => typeof value === 'string' && value.length > 0)
+
+    if (reservableOrderIds.length > 0) {
+      const matchingOrderIds = new Set<string>()
+      let linePage = 1
+      try {
+        for (;;) {
+          const lines = await queryEngine.query<SalesOrderLineRow & { order_id?: string | null }>(
+            E.sales.sales_order_line,
+            {
+              tenantId: scope.tenantId,
+              organizationId: scope.organizationId,
+              filters: {
+                product_variant_id: { $eq: payload.catalogVariantId },
+                order_id: { $in: reservableOrderIds },
+              },
+              fields: ['id', 'order_id', 'product_variant_id'],
+              page: { page: linePage, pageSize: REEVAL_ORDER_PAGE_SIZE },
+            },
+          )
+          for (const line of lines.items) {
+            if (typeof line.order_id === 'string' && line.order_id.length > 0) {
+              matchingOrderIds.add(line.order_id)
+            }
+          }
+          if (lines.items.length < REEVAL_ORDER_PAGE_SIZE) break
+          linePage += 1
+        }
+      } catch (error) {
+        // Transient peer failure on one page must not abort later order pages.
+        logger.warn('Reservation re-eval line lookup failed; continuing next page', {
+          catalogVariantId: payload.catalogVariantId,
+          page,
+          orderCount: reservableOrderIds.length,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+
+      for (const orderId of matchingOrderIds) {
+        try {
+          await reserveInventoryForConfirmedOrder(
+            {
+              orderId,
+              tenantId: scope.tenantId,
+              organizationId: scope.organizationId,
+            },
+            ctx,
+          )
+        } catch {
+          // Keep processing remaining orders; a single peer failure must not abort the batch.
+        }
+      }
+    }
+
+    if (orderItems.length < REEVAL_ORDER_PAGE_SIZE) break
+    page += 1
+  }
+}
+
 export async function releaseInventoryForCancelledOrder(
   payload: SalesOrderLifecyclePayload,
   ctx: EventContext,