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

package/src/modules/wms/data/entities.ts

@@ -25,6 +25,9 @@ export type InventoryMovementType =
   | 'cycle_count'
   | 'return_receive'
 export type InventoryMovementReferenceType = 'po' | 'so' | 'transfer' | 'manual' | 'qc' | 'rma'
+export type AsnStatus = 'draft' | 'in_transit' | 'received' | 'closed'
+export type ReceivingLineQcStatus = 'pending' | 'passed' | 'failed'
+export type PutawayTaskStatus = 'open' | 'in_progress' | 'done' | 'cancelled'
 type WmsOptionalProps = 'createdAt' | 'updatedAt' | 'deletedAt' | 'metadata'
 
 abstract class WmsScopedEntity {
@@ -434,3 +437,155 @@ export class InventoryMovement extends WmsScopedEntity {
   @Property({ name: 'idempotency_key', type: 'text', nullable: true })
   idempotencyKey?: string | null
 }
+
+@Entity({ tableName: 'wms_asns' })
+@Index({ name: 'wms_asns_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Index({
+  name: 'wms_asns_org_warehouse_status_expected_idx',
+  properties: ['organizationId', 'warehouse', 'status', 'expectedAt'],
+})
+@Index({
+  name: 'wms_asns_org_vendor_expected_idx',
+  expression:
+    'create index "wms_asns_org_vendor_expected_idx" on "wms_asns" ("organization_id", "vendor_id", "expected_at" desc) where deleted_at is null',
+})
+@Index({
+  name: 'wms_asns_org_source_key_unique_idx',
+  expression:
+    'create unique index "wms_asns_org_source_key_unique_idx" on "wms_asns" ("organization_id", "source_key") where source_key is not null and deleted_at is null',
+})
+export class Asn extends WmsScopedEntity {
+  [OptionalProps]?: WmsOptionalProps | 'vendorId' | 'referenceNumber' | 'notes' | 'status' | 'sourceKey'
+
+  @ManyToOne(() => Warehouse, { fieldName: 'warehouse_id' })
+  warehouse!: Warehouse
+
+  @Property({ name: 'vendor_id', type: 'uuid', nullable: true })
+  vendorId?: string | null
+
+  @Property({ type: 'text', default: 'draft' })
+  status: AsnStatus = 'draft'
+
+  @Property({ name: 'expected_at', type: Date })
+  expectedAt!: Date
+
+  @Property({ name: 'reference_number', type: 'text', nullable: true })
+  referenceNumber?: string | null
+
+  /** Stable external linkage key (e.g. procurement goods receipt) for find-or-create. */
+  @Property({ name: 'source_key', type: 'text', nullable: true })
+  sourceKey?: string | null
+
+  @Property({ type: 'text', nullable: true })
+  notes?: string | null
+
+  @OneToMany(() => ReceivingLine, (line) => line.asn)
+  lines = new Collection<ReceivingLine>(this)
+}
+
+@Entity({ tableName: 'wms_receiving_lines' })
+@Index({ name: 'wms_receiving_lines_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Index({ name: 'wms_receiving_lines_org_asn_idx', properties: ['organizationId', 'asn'] })
+@Index({
+  name: 'wms_receiving_lines_org_variant_qc_idx',
+  properties: ['organizationId', 'catalogVariantId', 'qcStatus'],
+})
+export class ReceivingLine extends WmsScopedEntity {
+  [OptionalProps]?:
+    | WmsOptionalProps
+    | 'lotNumber'
+    | 'serialNumbers'
+    | 'targetStagingLocationId'
+    | 'rejectionReason'
+    | 'receivedQty'
+    | 'qcStatus'
+
+  @ManyToOne(() => Asn, { fieldName: 'asn_id' })
+  asn!: Asn
+
+  @Property({ name: 'catalog_variant_id', type: 'uuid' })
+  catalogVariantId!: string
+
+  @Property({ name: 'expected_qty', type: 'numeric', precision: 16, scale: 4 })
+  expectedQty!: string
+
+  @Property({ name: 'received_qty', type: 'numeric', precision: 16, scale: 4, default: '0' })
+  receivedQty: string = '0'
+
+  @Property({ name: 'lot_number', type: 'text', nullable: true })
+  lotNumber?: string | null
+
+  @Property({ name: 'serial_numbers', type: 'jsonb', nullable: true })
+  serialNumbers?: string[] | null
+
+  @Property({ name: 'qc_status', type: 'text', default: 'pending' })
+  qcStatus: ReceivingLineQcStatus = 'pending'
+
+  @Property({ name: 'target_staging_location_id', type: 'uuid', nullable: true })
+  targetStagingLocationId?: string | null
+
+  @Property({ name: 'rejection_reason', type: 'text', nullable: true })
+  rejectionReason?: string | null
+}
+
+@Entity({ tableName: 'wms_putaway_tasks' })
+@Index({ name: 'wms_putaway_tasks_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Index({
+  name: 'wms_putaway_tasks_org_warehouse_status_priority_idx',
+  properties: ['organizationId', 'warehouse', 'status', 'priority'],
+})
+@Index({
+  name: 'wms_putaway_tasks_org_assigned_status_idx',
+  properties: ['organizationId', 'assignedTo', 'status'],
+})
+@Index({
+  name: 'wms_putaway_tasks_org_putaway_key_unique_idx',
+  expression:
+    'create unique index "wms_putaway_tasks_org_putaway_key_unique_idx" on "wms_putaway_tasks" ("organization_id", "putaway_key") where putaway_key is not null and deleted_at is null and status <> \'cancelled\'',
+})
+export class PutawayTask extends WmsScopedEntity {
+  [OptionalProps]?:
+    | WmsOptionalProps
+    | 'targetLocationId'
+    | 'lotId'
+    | 'serialNumber'
+    | 'assignedTo'
+    | 'priority'
+    | 'status'
+    | 'putawayKey'
+
+  @ManyToOne(() => Warehouse, { fieldName: 'warehouse_id' })
+  warehouse!: Warehouse
+
+  @Property({ name: 'source_location_id', type: 'uuid' })
+  sourceLocationId!: string
+
+  @Property({ name: 'target_location_id', type: 'uuid', nullable: true })
+  targetLocationId?: string | null
+
+  @Property({ name: 'catalog_variant_id', type: 'uuid' })
+  catalogVariantId!: string
+
+  @Property({ name: 'lot_id', type: 'uuid', nullable: true })
+  lotId?: string | null
+
+  /** Set on quantity-one tasks created for a serial-tracked receipt. Null for aggregate tasks. */
+  @Property({ name: 'serial_number', type: 'text', nullable: true })
+  serialNumber?: string | null
+
+  @Property({ type: 'numeric', precision: 16, scale: 4 })
+  quantity!: string
+
+  @Property({ type: 'text', default: 'open' })
+  status: PutawayTaskStatus = 'open'
+
+  @Property({ name: 'assigned_to', type: 'uuid', nullable: true })
+  assignedTo?: string | null
+
+  @Property({ type: 'integer', default: 5 })
+  priority: number = 5
+
+  /** Stable ASN-receive attempt key for find-or-create without scanning newest-N metadata. */
+  @Property({ name: 'putaway_key', type: 'text', nullable: true })
+  putawayKey?: string | null
+}

package/src/modules/wms/data/validators.ts

@@ -228,6 +228,7 @@ export const inventoryReceiveSchema = scopedSchema.extend({
   receivedAt: z.coerce.date().optional(),
   performedAt: z.coerce.date().optional(),
   reason: z.string().trim().max(500).optional(),
+  reasonCode: z.string().trim().max(80).optional(),
   metadata: metadataSchema,
 })
 
@@ -325,6 +326,186 @@ export const inventoryMovementCreateSchema = scopedSchema.extend({
   metadata: metadataSchema,
 })
 
+/** Statuses clients may set on create/update — terminal received/closed come from receive/complete. */
+const asnWritableStatusSchema = z.enum(['draft', 'in_transit'])
+
+export const receivingLineCreateFieldsSchema = z.object({
+  catalogVariantId: uuid(),
+  expectedQty: positiveQuantity,
+  lotNumber: z.string().trim().max(120).optional().nullable(),
+  serialNumbers: z.array(z.string().trim().min(1).max(120)).optional().nullable(),
+  targetStagingLocationId: uuid().optional().nullable(),
+  metadata: metadataSchema,
+})
+
+export const asnCreateSchema = scopedSchema.extend({
+  warehouseId: uuid(),
+  vendorId: uuid().optional().nullable(),
+  status: asnWritableStatusSchema.optional(),
+  expectedAt: z.coerce.date(),
+  referenceNumber: z.string().trim().max(120).optional().nullable(),
+  /**
+   * Stable external linkage key; unique per org when set (procurement goods receipt, etc.).
+   * Server/system creates only — public HTTP create strips this; authenticated clients cannot set it.
+   */
+  sourceKey: z.string().trim().min(1).max(200).optional().nullable(),
+  notes: z.string().trim().max(2000).optional().nullable(),
+  lines: z.array(receivingLineCreateFieldsSchema).optional(),
+  metadata: metadataSchema,
+})
+
+/** Public ASN create body — omits `sourceKey` so clients cannot spoof procurement linkage. */
+export const asnCreatePublicSchema = asnCreateSchema.omit({ sourceKey: true })
+
+export const asnUpdateSchema = z
+  .object({ id: uuid() })
+  .merge(
+    scopedSchema
+      .extend({
+        warehouseId: uuid(),
+        vendorId: uuid().nullable(),
+        status: asnWritableStatusSchema,
+        expectedAt: z.coerce.date(),
+        referenceNumber: z.string().trim().max(120).nullable(),
+        notes: z.string().trim().max(2000).nullable(),
+        metadata: metadataSchema,
+      })
+      .partial(),
+  )
+
+export const receivingLineCreateSchema = scopedSchema.extend({
+  asnId: uuid(),
+  catalogVariantId: uuid(),
+  expectedQty: positiveQuantity,
+  lotNumber: z.string().trim().max(120).optional().nullable(),
+  serialNumbers: z.array(z.string().trim().min(1).max(120)).optional().nullable(),
+  targetStagingLocationId: uuid().optional().nullable(),
+  metadata: metadataSchema,
+})
+
+// Lifecycle fields (receivedQty / qcStatus / rejectionReason) are intentionally
+// omitted — only `wms.asns.receive-line` may mutate them.
+export const receivingLineUpdateSchema = z
+  .object({ id: uuid() })
+  .merge(
+    scopedSchema
+      .extend({
+        catalogVariantId: uuid(),
+        expectedQty: positiveQuantity,
+        lotNumber: z.string().trim().max(120).nullable(),
+        serialNumbers: z.array(z.string().trim().min(1).max(120)).nullable(),
+        targetStagingLocationId: uuid().nullable(),
+        metadata: metadataSchema,
+      })
+      .partial(),
+  )
+
+export const asnReceiveLineSchema = scopedSchema
+  .extend({
+    asnId: uuid(),
+    lineId: uuid(),
+    receivedQty: positiveQuantity,
+    /**
+     * Absolute received quantity the client intends after this attempt.
+     * Required for QC-pass and QC-fail so retries after success remain
+     * idempotent (applyQty=0) even if prior qty advanced. Do not derive from
+     * delta alone — QC-fail still advances audit receivedQty.
+     */
+    targetReceivedQty: positiveQuantity.optional(),
+    /** Optional client-stable attempt id; extra stabilizer alongside absolute target. */
+    idempotencyKey: uuid().optional(),
+    targetStagingLocationId: uuid().optional(),
+    lotId: uuid().optional(),
+    lotNumber: z.string().trim().max(120).optional(),
+    serialNumbers: z.array(z.string().trim().min(1).max(120)).optional(),
+    qcStatus: z.enum(['passed', 'failed']),
+    rejectionReason: z.string().trim().max(500).optional(),
+    performedBy: uuid(),
+    receivedAt: z.coerce.date().optional(),
+    metadata: metadataSchema,
+  })
+  .superRefine((value, ctx) => {
+    if (value.targetReceivedQty == null) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['targetReceivedQty'],
+        message: 'target_received_qty_required',
+      })
+    }
+  })
+
+export const asnCloseSchema = scopedSchema.extend({
+  id: uuid(),
+  closeWhenShort: z.boolean().optional(),
+})
+
+export const putawayTaskCreateSchema = scopedSchema.extend({
+  warehouseId: uuid(),
+  sourceLocationId: uuid(),
+  targetLocationId: uuid().optional().nullable(),
+  catalogVariantId: uuid(),
+  lotId: uuid().optional().nullable(),
+  quantity: positiveQuantity,
+  priority: z.coerce.number().int().min(0).max(100).optional(),
+  assignedTo: uuid().optional().nullable(),
+  metadata: metadataSchema,
+})
+
+// Status and assignee transitions are intentionally omitted — only lifecycle
+// commands (assign/start/complete/cancel) may change those fields.
+export const putawayTaskUpdateSchema = z
+  .object({ id: uuid() })
+  .merge(
+    scopedSchema
+      .extend({
+        warehouseId: uuid(),
+        sourceLocationId: uuid(),
+        targetLocationId: uuid().nullable(),
+        catalogVariantId: uuid(),
+        lotId: uuid().nullable(),
+        quantity: positiveQuantity,
+        priority: z.coerce.number().int().min(0).max(100),
+        metadata: metadataSchema,
+      })
+      .partial(),
+  )
+
+export const putawayTaskCreateFromBalanceSchema = scopedSchema.extend({
+  warehouseId: uuid(),
+  sourceLocationId: uuid(),
+  targetLocationId: uuid(),
+  catalogVariantId: uuid(),
+  lotId: uuid().optional(),
+  quantity: positiveQuantity,
+  priority: z.coerce.number().int().min(0).max(100).optional(),
+  assignedTo: uuid().optional().nullable(),
+  metadata: metadataSchema,
+})
+
+export const putawayTaskAssignSchema = scopedSchema.extend({
+  id: uuid(),
+  assignedTo: uuid(),
+})
+
+export const putawayTaskStartSchema = scopedSchema.extend({
+  id: uuid(),
+})
+
+export const putawayTaskCompleteSchema = scopedSchema.extend({
+  id: uuid(),
+  confirmedQuantity: positiveQuantity,
+  targetLocationId: uuid(),
+  lotId: uuid().optional(),
+  performedBy: uuid(),
+  performedAt: z.coerce.date().optional(),
+  reason: z.string().trim().min(1).max(500).optional(),
+  metadata: metadataSchema,
+})
+
+export const putawayTaskCancelSchema = scopedSchema.extend({
+  id: uuid(),
+})
+
 export type WarehouseCreateInput = z.infer<typeof warehouseCreateSchema>
 export type WarehouseUpdateInput = z.infer<typeof warehouseUpdateSchema>
 export type WarehouseZoneCreateInput = z.infer<typeof warehouseZoneCreateSchema>
@@ -342,6 +523,78 @@ export type InventoryReservationAllocateInput = z.infer<typeof inventoryReservat
 export type InventoryAdjustInput = z.infer<typeof inventoryAdjustSchema>
 export type InventoryMoveInput = z.infer<typeof inventoryMoveSchema>
 export type InventoryCycleCountInput = z.infer<typeof inventoryCycleCountSchema>
+export type AsnCreateInput = z.infer<typeof asnCreateSchema>
+export type AsnCreatePublicInput = z.infer<typeof asnCreatePublicSchema>
+export type AsnUpdateInput = z.infer<typeof asnUpdateSchema>
+export type ReceivingLineCreateInput = z.infer<typeof receivingLineCreateSchema>
+export type ReceivingLineUpdateInput = z.infer<typeof receivingLineUpdateSchema>
+export type AsnReceiveLineInput = z.infer<typeof asnReceiveLineSchema>
+export type AsnCloseInput = z.infer<typeof asnCloseSchema>
+export type PutawayTaskCreateInput = z.infer<typeof putawayTaskCreateSchema>
+export type PutawayTaskUpdateInput = z.infer<typeof putawayTaskUpdateSchema>
+export type PutawayTaskCreateFromBalanceInput = z.infer<typeof putawayTaskCreateFromBalanceSchema>
+export type PutawayTaskAssignInput = z.infer<typeof putawayTaskAssignSchema>
+export type PutawayTaskStartInput = z.infer<typeof putawayTaskStartSchema>
+export type PutawayTaskCompleteInput = z.infer<typeof putawayTaskCompleteSchema>
+export type PutawayTaskCancelInput = z.infer<typeof putawayTaskCancelSchema>
+
+export const scanResolveLocationSchema = scopedSchema.extend({
+  warehouseId: uuid(),
+  code: z.string().trim().min(1).max(120),
+})
+
+export const scanResolveLotSchema = scopedSchema.extend({
+  catalogVariantId: uuid(),
+  lotNumber: z.string().trim().min(1).max(120),
+})
+
+export const scanReceiveSchema = scopedSchema
+  .extend({
+    asnId: uuid(),
+    lineId: uuid(),
+    locationCode: z.string().trim().min(1).max(120),
+    lotNumber: z.string().trim().max(120).optional(),
+    serialNumbers: z.array(z.string().trim().min(1).max(120)).optional(),
+    receivedQty: positiveQuantity,
+    /**
+     * Absolute received quantity after this attempt. Required for QC-pass and
+     * QC-fail so identical retries no-op (applyQty=0). Do not derive as
+     * prior+delta in scan resolve — that doubles stock/audit qty on retry.
+     */
+    targetReceivedQty: positiveQuantity.optional(),
+    /** Optional client-stable attempt id; extra stabilizer alongside absolute target. */
+    idempotencyKey: uuid().optional(),
+    qcStatus: z.enum(['passed', 'failed']),
+    rejectionReason: z.string().trim().max(500).optional(),
+    performedBy: uuid(),
+    receivedAt: z.coerce.date().optional(),
+    metadata: metadataSchema,
+  })
+  .superRefine((value, ctx) => {
+    if (value.targetReceivedQty == null) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['targetReceivedQty'],
+        message: 'target_received_qty_required',
+      })
+    }
+  })
+
+export const scanPutawaySchema = scopedSchema.extend({
+  taskId: uuid(),
+  targetLocationCode: z.string().trim().min(1).max(120),
+  confirmedQuantity: positiveQuantity,
+  lotId: uuid().optional(),
+  performedBy: uuid(),
+  performedAt: z.coerce.date().optional(),
+  reason: z.string().trim().min(1).max(500).optional(),
+  metadata: metadataSchema,
+})
+
+export type ScanResolveLocationInput = z.infer<typeof scanResolveLocationSchema>
+export type ScanResolveLotInput = z.infer<typeof scanResolveLotSchema>
+export type ScanReceiveInput = z.infer<typeof scanReceiveSchema>
+export type ScanPutawayInput = z.infer<typeof scanPutawaySchema>
 
 export const salesOrderWarehouseAssignBodySchema = scopedSchema.extend({
   warehouseId: uuid(),
@@ -452,7 +705,10 @@ export const operationalDashboardResponseSchema = z.object({
       variantId: z.string().uuid(),
       referenceType: z.string().nullable(),
       referenceId: z.string().nullable(),
+      referenceLabel: z.string().nullable().optional(),
       reason: z.string().nullable(),
+      reasonCode: z.string().nullable().optional(),
+      source: z.string().nullable().optional(),
       locationLabel: z.string(),
       performedAt: z.string(),
     }),

package/src/modules/wms/events.ts

@@ -29,6 +29,17 @@ const events = [
   { id: 'wms.inventory.low_stock', label: 'Inventory Low Stock', entity: 'inventory', category: 'lifecycle' },
   { id: 'wms.inventory.balance_drift', label: 'Inventory Balance Drift', entity: 'inventory', category: 'lifecycle' },
   { id: 'wms.inventory.reservation_shortfall', label: 'Inventory Reservation Shortfall', entity: 'inventory', category: 'lifecycle' },
+  { id: 'wms.inventory.receipt_qc_failed', label: 'Inventory Receipt QC Failed', entity: 'inventory', category: 'custom' },
+  { id: 'wms.asn.created', label: 'ASN Created', entity: 'asn', category: 'crud' },
+  { id: 'wms.asn.updated', label: 'ASN Updated', entity: 'asn', category: 'crud' },
+  { id: 'wms.asn.receiving_started', label: 'ASN Receiving Started', entity: 'asn', category: 'lifecycle' },
+  { id: 'wms.asn.line_received', label: 'ASN Line Received', entity: 'asn', category: 'custom' },
+  { id: 'wms.asn.received', label: 'ASN Received', entity: 'asn', category: 'lifecycle' },
+  { id: 'wms.putaway.created', label: 'Putaway Task Created', entity: 'putaway', category: 'crud' },
+  { id: 'wms.putaway.assigned', label: 'Putaway Task Assigned', entity: 'putaway', category: 'lifecycle' },
+  { id: 'wms.putaway.started', label: 'Putaway Task Started', entity: 'putaway', category: 'lifecycle' },
+  { id: 'wms.putaway.completed', label: 'Putaway Task Completed', entity: 'putaway', category: 'lifecycle' },
+  { id: 'wms.putaway.cancelled', label: 'Putaway Task Cancelled', entity: 'putaway', category: 'lifecycle' },
 ] as const
 
 export const eventsConfig = createModuleEvents({

package/src/modules/wms/extension-points.ts

@@ -17,6 +17,8 @@ export const extensionPoints = defineModuleExtensionPoints({
     lotsTable: dataTableExtensionHost({ tableId: 'wms.lots.list', source: 'components/backend/WmsLotsListPage.tsx' }),
     skuDistributionTable: dataTableExtensionHost({ tableId: 'wms.sku.distribution', source: 'components/backend/WmsSkuDetailPage.tsx' }),
     skuActivityTable: dataTableExtensionHost({ tableId: 'wms.sku.activity', source: 'components/backend/WmsSkuDetailPage.tsx' }),
+    asnsTable: dataTableExtensionHost({ tableId: 'wms.asns.list', source: 'components/backend/WmsAsnsListPage.tsx' }),
+    putawayTasksTable: dataTableExtensionHost({ tableId: 'wms.putaway.tasks', source: 'components/backend/WmsPutawayQueuePage.tsx' }),
   },
 })