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

package/dist/modules/wms/commands/putaway.js

@@ -0,0 +1,945 @@
+import { registerCommand } from "@open-mercato/shared/lib/commands";
+import { emitCrudSideEffects } from "@open-mercato/shared/lib/commands/helpers";
+import { extractUndoPayload } from "@open-mercato/shared/lib/commands/undo";
+import { LockMode } from "@mikro-orm/core";
+import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import { resolveTranslations } from "@open-mercato/shared/lib/i18n/server";
+import { findOneWithDecryption, findWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { enforceCommandOptimisticLockWithGuards } from "@open-mercato/shared/lib/crud/optimistic-lock-command";
+import {
+  InventoryBalance,
+  PutawayTask,
+  Warehouse,
+  WarehouseLocation
+} from "../data/entities.js";
+import {
+  putawayTaskAssignSchema,
+  putawayTaskCancelSchema,
+  putawayTaskCompleteSchema,
+  putawayTaskCreateFromBalanceSchema,
+  putawayTaskCreateSchema,
+  putawayTaskStartSchema,
+  putawayTaskUpdateSchema
+} from "../data/validators.js";
+import { emitWmsEvent } from "../events.js";
+import {
+  assertPutawayAssignable,
+  assertPutawayCancellable,
+  computeUncommittedPutawaySourceQuantity,
+  hasUncommittedPutawaySourceQuantity,
+  assertPutawayCompleteAuthorized,
+  assertPutawayCompletable,
+  assertPutawayConfirmedQuantity,
+  assertPutawayDeletable,
+  assertPutawayLifecycleFieldsForbidden,
+  assertPutawayStartable,
+  assertPutawayTargetLocationType,
+  buildPutawayCompleteReferenceId,
+  putawayResidualQuantity
+} from "../lib/putaway.js";
+import {
+  applyInventoryMoveInTransaction,
+  emitInventoryMoveSideEffects,
+  findPutawayCompleteMovementByReference
+} from "./inventory-actions.js";
+import {
+  ensureOrganizationScope,
+  ensureTenantScope,
+  putawayTaskCrudEvents,
+  putawayTaskCrudIndexer,
+  requireId,
+  toNumericString,
+  WMS_INVENTORY_BALANCE_RESOURCE,
+  WMS_PUTAWAY_TASK_RESOURCE
+} from "./shared.js";
+function resolveScope(ctx, fallback) {
+  const tenantId = fallback?.tenantId ?? ctx.auth?.tenantId ?? null;
+  const organizationId = fallback?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null;
+  if (!tenantId || !organizationId) {
+    throw new CrudHttpError(400, { error: "Tenant and organization scope are required." });
+  }
+  return { tenantId, organizationId };
+}
+function resolveEm(ctx) {
+  return ctx.container.resolve("em").fork();
+}
+async function resolvePutawayCompleteAuthorization(ctx, scope, assignedTo) {
+  const actorUserId = typeof ctx.auth?.sub === "string" ? ctx.auth.sub : null;
+  let canManagePutaway = false;
+  let canAdjustInventory = false;
+  if (actorUserId) {
+    try {
+      const rbacService = ctx.container.resolve("rbacService");
+      if (typeof rbacService.userHasAllFeatures === "function") {
+        ;
+        [canManagePutaway, canAdjustInventory] = await Promise.all([
+          rbacService.userHasAllFeatures(actorUserId, ["wms.manage_putaway"], scope),
+          rbacService.userHasAllFeatures(actorUserId, ["wms.adjust_inventory"], scope)
+        ]);
+      }
+    } catch {
+    }
+  }
+  assertPutawayCompleteAuthorized({
+    canManagePutaway,
+    canAdjustInventory,
+    actorUserId,
+    assignedTo
+  });
+}
+function toJsonValue(value) {
+  if (value === void 0) return void 0;
+  return value ?? null;
+}
+function iso(value) {
+  if (value instanceof Date) return value.toISOString();
+  return new Date(value).toISOString();
+}
+function snapshotPutawayTask(record) {
+  const warehouseId = typeof record.warehouse === "string" ? record.warehouse : record.warehouse.id;
+  return {
+    id: record.id,
+    organizationId: record.organizationId,
+    tenantId: record.tenantId,
+    warehouseId,
+    sourceLocationId: record.sourceLocationId,
+    targetLocationId: record.targetLocationId ?? null,
+    catalogVariantId: record.catalogVariantId,
+    lotId: record.lotId ?? null,
+    quantity: record.quantity,
+    status: record.status,
+    assignedTo: record.assignedTo ?? null,
+    priority: Number(record.priority),
+    metadata: record.metadata ?? null,
+    createdAt: iso(record.createdAt),
+    updatedAt: iso(record.updatedAt)
+  };
+}
+async function loadPutawayTask(em, ctx, id) {
+  const task = await findOneWithDecryption(
+    em,
+    PutawayTask,
+    { id, deletedAt: null },
+    void 0,
+    resolveScope(ctx)
+  );
+  if (!task) throw new CrudHttpError(404, { error: "Putaway task not found." });
+  ensureTenantScope(ctx, task.tenantId);
+  ensureOrganizationScope(ctx, task.organizationId);
+  return task;
+}
+async function withLockedPutawayTask(em, ctx, id, scope, fn) {
+  return em.transactional(async (trx) => {
+    const task = await findOneWithDecryption(
+      trx,
+      PutawayTask,
+      { id, deletedAt: null },
+      { lockMode: LockMode.PESSIMISTIC_WRITE },
+      scope
+    );
+    if (!task) throw new CrudHttpError(404, { error: "Putaway task not found." });
+    ensureTenantScope(ctx, task.tenantId);
+    ensureOrganizationScope(ctx, task.organizationId);
+    await enforceCommandOptimisticLockWithGuards(ctx.container, {
+      resourceKind: WMS_PUTAWAY_TASK_RESOURCE,
+      resourceId: task.id,
+      current: task.updatedAt,
+      request: ctx.request ?? null
+    });
+    return fn(task, trx);
+  });
+}
+async function requireWarehouse(em, ctx, warehouseId, scope) {
+  const warehouse = await findOneWithDecryption(
+    em,
+    Warehouse,
+    { id: warehouseId, deletedAt: null },
+    void 0,
+    scope
+  );
+  if (!warehouse) throw new CrudHttpError(404, { error: "Warehouse not found." });
+  ensureTenantScope(ctx, warehouse.tenantId);
+  ensureOrganizationScope(ctx, warehouse.organizationId);
+  return warehouse;
+}
+async function requireActiveLocation(em, ctx, locationId, warehouseId, scope) {
+  const location = await findOneWithDecryption(
+    em,
+    WarehouseLocation,
+    { id: locationId, deletedAt: null },
+    void 0,
+    scope
+  );
+  if (!location) throw new CrudHttpError(404, { error: "Warehouse location not found." });
+  ensureTenantScope(ctx, location.tenantId);
+  ensureOrganizationScope(ctx, location.organizationId);
+  const locationWarehouseId = typeof location.warehouse === "string" ? location.warehouse : location.warehouse.id;
+  if (locationWarehouseId !== warehouseId) {
+    throw new CrudHttpError(422, { error: "invalid_location" });
+  }
+  if (!location.isActive) {
+    throw new CrudHttpError(422, { error: "inactive_location" });
+  }
+  return location;
+}
+function toNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return 0;
+}
+async function requireAvailableBalanceQuantity(em, ctx, input, scope, options) {
+  const serialNumber = input.serialNumber?.trim() ? input.serialNumber.trim() : null;
+  const balance = await findOneWithDecryption(
+    em,
+    InventoryBalance,
+    {
+      warehouse: input.warehouseId,
+      location: input.sourceLocationId,
+      catalogVariantId: input.catalogVariantId,
+      lot: input.lotId ?? null,
+      serialNumber,
+      deletedAt: null
+    },
+    options?.lock ? { lockMode: LockMode.PESSIMISTIC_WRITE } : void 0,
+    scope
+  );
+  if (!balance) {
+    throw new CrudHttpError(409, { error: "insufficient_stock" });
+  }
+  ensureTenantScope(ctx, balance.tenantId);
+  ensureOrganizationScope(ctx, balance.organizationId);
+  const openTasks = await findWithDecryption(
+    em,
+    PutawayTask,
+    {
+      warehouse: input.warehouseId,
+      sourceLocationId: input.sourceLocationId,
+      catalogVariantId: input.catalogVariantId,
+      lotId: input.lotId ?? null,
+      serialNumber,
+      status: { $in: ["open", "in_progress"] },
+      deletedAt: null
+    },
+    void 0,
+    scope
+  );
+  const remaining = computeUncommittedPutawaySourceQuantity({
+    quantityOnHand: toNumber(balance.quantityOnHand),
+    quantityReserved: toNumber(balance.quantityReserved),
+    quantityAllocated: toNumber(balance.quantityAllocated),
+    openPutawayQuantities: openTasks.filter((task) => !(options?.excludeTaskId && task.id === options.excludeTaskId)).map((task) => toNumber(task.quantity))
+  });
+  if (!hasUncommittedPutawaySourceQuantity(remaining, input.quantity)) {
+    throw new CrudHttpError(409, { error: "insufficient_stock" });
+  }
+  return balance;
+}
+async function emitPutawaySideEffects(ctx, tasks) {
+  const dataEngine = ctx.container.resolve("dataEngine");
+  for (const entry of tasks) {
+    await emitCrudSideEffects({
+      dataEngine,
+      action: entry.action,
+      entity: entry.entity,
+      identifiers: {
+        id: entry.entity.id,
+        organizationId: entry.entity.organizationId,
+        tenantId: entry.entity.tenantId
+      },
+      events: putawayTaskCrudEvents,
+      indexer: putawayTaskCrudIndexer
+    });
+  }
+}
+async function buildCrudLog(ctx, input, resultId, actionKey, fallbackLabel) {
+  const { translate } = await resolveTranslations();
+  return {
+    actionLabel: translate(actionKey, fallbackLabel),
+    resourceKind: WMS_PUTAWAY_TASK_RESOURCE,
+    resourceId: resultId ?? input?.id ?? null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
+  };
+}
+function readPutawaySourceBucket(task) {
+  const warehouseId = typeof task.warehouse === "string" ? task.warehouse : task.warehouse.id;
+  const serialNumber = task.serialNumber?.trim() ?? "";
+  return {
+    warehouseId,
+    sourceLocationId: task.sourceLocationId,
+    catalogVariantId: task.catalogVariantId,
+    lotId: task.lotId ?? null,
+    serialNumber: serialNumber.length > 0 ? serialNumber : null
+  };
+}
+function samePutawaySourceBucket(left, right) {
+  return left.warehouseId === right.warehouseId && left.sourceLocationId === right.sourceLocationId && left.catalogVariantId === right.catalogVariantId && (left.lotId ?? null) === (right.lotId ?? null) && (left.serialNumber ?? null) === (right.serialNumber ?? null);
+}
+async function assertResultingPutawayCapacity(em, ctx, scope, input) {
+  const bucketChanged = !samePutawaySourceBucket(input.previous, input.next);
+  const quantityIncreased = input.nextQuantity > input.previousQuantity + 1e-6;
+  if (!bucketChanged && !quantityIncreased) return;
+  await requireAvailableBalanceQuantity(
+    em,
+    ctx,
+    {
+      warehouseId: input.next.warehouseId,
+      sourceLocationId: input.next.sourceLocationId,
+      catalogVariantId: input.next.catalogVariantId,
+      lotId: input.next.lotId,
+      serialNumber: input.next.serialNumber,
+      quantity: input.nextQuantity
+    },
+    scope,
+    { lock: true, excludeTaskId: input.excludeTaskId }
+  );
+}
+async function createOpenPutawayTask(em, ctx, input) {
+  const scope = resolveScope(ctx, input);
+  await requireWarehouse(em, ctx, input.warehouseId, scope);
+  await requireActiveLocation(em, ctx, input.sourceLocationId, input.warehouseId, scope);
+  if (input.targetLocationId) {
+    await requireActiveLocation(em, ctx, input.targetLocationId, input.warehouseId, scope);
+  }
+  const task = em.create(PutawayTask, {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    warehouse: em.getReference(Warehouse, input.warehouseId),
+    sourceLocationId: input.sourceLocationId,
+    targetLocationId: input.targetLocationId ?? null,
+    catalogVariantId: input.catalogVariantId,
+    lotId: input.lotId ?? null,
+    serialNumber: input.serialNumber?.trim() ? input.serialNumber.trim() : null,
+    quantity: toNumericString(input.quantity),
+    status: "open",
+    assignedTo: input.assignedTo ?? null,
+    priority: input.priority ?? 5,
+    putawayKey: input.putawayKey ?? null,
+    metadata: toJsonValue(input.metadata) ?? null
+  });
+  await em.persist(task).flush();
+  return task;
+}
+async function ensureResidualPutawayTask(em, ctx, input) {
+  const residualKey = `wms:putaway-residual:${input.parent.id}`;
+  const existing = await findOneWithDecryption(
+    em,
+    PutawayTask,
+    {
+      organizationId: input.scope.organizationId,
+      tenantId: input.scope.tenantId,
+      putawayKey: residualKey,
+      deletedAt: null,
+      status: { $in: ["open", "in_progress", "done"] }
+    },
+    void 0,
+    input.scope
+  );
+  if (existing) return;
+  try {
+    await createOpenPutawayTask(em, ctx, {
+      organizationId: input.scope.organizationId,
+      tenantId: input.scope.tenantId,
+      warehouseId: input.warehouseId,
+      sourceLocationId: input.parent.sourceLocationId,
+      targetLocationId: null,
+      catalogVariantId: input.parent.catalogVariantId,
+      lotId: input.parent.lotId,
+      serialNumber: input.parent.serialNumber ?? null,
+      quantity: input.residual,
+      assignedTo: input.parent.assignedTo,
+      priority: input.parent.priority,
+      putawayKey: residualKey,
+      metadata: {
+        source: "putaway_residual",
+        parentPutawayTaskId: input.parent.id
+      }
+    });
+  } catch (error) {
+    const code = error && typeof error === "object" ? error.code : void 0;
+    const name = error && typeof error === "object" ? error.name : void 0;
+    if (code !== "23505" && name !== "UniqueConstraintViolationException") throw error;
+  }
+}
+const createPutawayTaskCommand = {
+  id: "wms.putaway-tasks.create",
+  async execute(rawInput, ctx) {
+    const input = putawayTaskCreateSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const scope = resolveScope(ctx, input);
+    const task = await em.transactional(async (trx) => {
+      await requireAvailableBalanceQuantity(
+        trx,
+        ctx,
+        {
+          warehouseId: input.warehouseId,
+          sourceLocationId: input.sourceLocationId,
+          catalogVariantId: input.catalogVariantId,
+          lotId: input.lotId,
+          quantity: input.quantity
+        },
+        scope,
+        { lock: true }
+      );
+      return createOpenPutawayTask(trx, ctx, input);
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "created" }]);
+    void emitWmsEvent("wms.putaway.created", {
+      id: task.id,
+      warehouseId: input.warehouseId,
+      sourceLocationId: task.sourceLocationId,
+      targetLocationId: task.targetLocationId ?? null,
+      catalogVariantId: task.catalogVariantId,
+      quantity: task.quantity,
+      tenantId: task.tenantId,
+      organizationId: task.organizationId
+    }).catch(() => void 0);
+    return { taskId: task.id };
+  },
+  captureAfter: async (_input, result, ctx) => {
+    if (!result?.taskId) return null;
+    const task = await loadPutawayTask(resolveEm(ctx), ctx, result.taskId);
+    return snapshotPutawayTask(task);
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload(logEntry);
+    const after = payload?.after;
+    if (!after?.id) return;
+    const em = resolveEm(ctx);
+    const scope = { tenantId: after.tenantId, organizationId: after.organizationId };
+    const task = await withLockedPutawayTask(em, ctx, after.id, scope, async (locked, trx) => {
+      if (locked.status !== "open") {
+        throw new CrudHttpError(409, { error: "invalid_putaway_state" });
+      }
+      locked.deletedAt = /* @__PURE__ */ new Date();
+      await trx.flush();
+      return locked;
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "deleted" }]);
+  },
+  buildLog: async ({ snapshots, input, result, ctx }) => {
+    const after = snapshots?.after;
+    return {
+      ...await buildCrudLog(ctx, input, result?.taskId ?? null, "wms.audit.putaway.create", "Create putaway task"),
+      snapshotAfter: after,
+      payload: { undo: { after } }
+    };
+  }
+};
+const updatePutawayTaskCommand = {
+  id: "wms.putaway-tasks.update",
+  async prepare(rawInput, ctx) {
+    const id = requireId(rawInput?.id, "Putaway task");
+    const task = await loadPutawayTask(resolveEm(ctx), ctx, id);
+    return { before: snapshotPutawayTask(task) };
+  },
+  async execute(rawInput, ctx) {
+    assertPutawayLifecycleFieldsForbidden(rawInput);
+    const input = putawayTaskUpdateSchema.parse(rawInput ?? {});
+    const em = resolveEm(ctx);
+    const scope = resolveScope(ctx);
+    const task = await withLockedPutawayTask(em, ctx, input.id, scope, async (locked, trx) => {
+      if (locked.status === "done" || locked.status === "cancelled") {
+        throw new CrudHttpError(409, { error: "invalid_putaway_state" });
+      }
+      const previousBucket = readPutawaySourceBucket(locked);
+      const nextBucket = {
+        warehouseId: input.warehouseId ?? previousBucket.warehouseId,
+        sourceLocationId: input.sourceLocationId ?? previousBucket.sourceLocationId,
+        catalogVariantId: input.catalogVariantId ?? previousBucket.catalogVariantId,
+        lotId: input.lotId !== void 0 ? input.lotId : previousBucket.lotId,
+        serialNumber: previousBucket.serialNumber
+      };
+      const previousQty = toNumber(locked.quantity);
+      const nextQty = input.quantity !== void 0 ? Number(input.quantity) : previousQty;
+      const taskScope = resolveScope(ctx, {
+        tenantId: locked.tenantId,
+        organizationId: locked.organizationId
+      });
+      if (input.warehouseId) {
+        await requireWarehouse(trx, ctx, input.warehouseId, taskScope);
+      }
+      if (input.sourceLocationId) {
+        await requireActiveLocation(trx, ctx, input.sourceLocationId, nextBucket.warehouseId, taskScope);
+      }
+      if (input.targetLocationId) {
+        await requireActiveLocation(trx, ctx, input.targetLocationId, nextBucket.warehouseId, taskScope);
+      }
+      await assertResultingPutawayCapacity(trx, ctx, taskScope, {
+        previous: previousBucket,
+        next: nextBucket,
+        previousQuantity: previousQty,
+        nextQuantity: nextQty,
+        excludeTaskId: locked.id
+      });
+      if (input.warehouseId) {
+        locked.warehouse = trx.getReference(Warehouse, input.warehouseId);
+      }
+      if (input.sourceLocationId) locked.sourceLocationId = input.sourceLocationId;
+      if (input.targetLocationId !== void 0) locked.targetLocationId = input.targetLocationId;
+      if (input.catalogVariantId !== void 0) locked.catalogVariantId = input.catalogVariantId;
+      if (input.lotId !== void 0) locked.lotId = input.lotId;
+      if (input.quantity !== void 0) locked.quantity = toNumericString(input.quantity);
+      if (input.priority !== void 0) locked.priority = input.priority;
+      if (input.metadata !== void 0) locked.metadata = toJsonValue(input.metadata) ?? null;
+      await trx.flush();
+      return locked;
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "updated" }]);
+    return { taskId: task.id };
+  },
+  captureAfter: async (_input, result, ctx) => {
+    if (!result?.taskId) return null;
+    const task = await loadPutawayTask(resolveEm(ctx), ctx, result.taskId);
+    return snapshotPutawayTask(task);
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload(logEntry);
+    const before = payload?.before;
+    if (!before?.id) return;
+    const em = resolveEm(ctx);
+    const scope = { tenantId: before.tenantId, organizationId: before.organizationId };
+    const task = await withLockedPutawayTask(em, ctx, before.id, scope, async (locked, trx) => {
+      if (locked.status === "done" || locked.status === "cancelled") {
+        throw new CrudHttpError(409, { error: "invalid_putaway_state" });
+      }
+      if (before.status === "done" || before.status === "cancelled") {
+        throw new CrudHttpError(409, { error: "invalid_putaway_state" });
+      }
+      const previousBucket = readPutawaySourceBucket(locked);
+      const restoredBucket = {
+        warehouseId: before.warehouseId,
+        sourceLocationId: before.sourceLocationId,
+        catalogVariantId: before.catalogVariantId,
+        lotId: before.lotId ?? null,
+        serialNumber: previousBucket.serialNumber
+      };
+      await assertResultingPutawayCapacity(trx, ctx, scope, {
+        previous: previousBucket,
+        next: restoredBucket,
+        previousQuantity: toNumber(locked.quantity),
+        nextQuantity: toNumber(before.quantity),
+        excludeTaskId: locked.id
+      });
+      locked.warehouse = trx.getReference(Warehouse, before.warehouseId);
+      locked.sourceLocationId = before.sourceLocationId;
+      locked.targetLocationId = before.targetLocationId;
+      locked.catalogVariantId = before.catalogVariantId;
+      locked.lotId = before.lotId;
+      locked.quantity = before.quantity;
+      locked.status = before.status;
+      locked.assignedTo = before.assignedTo;
+      locked.priority = before.priority;
+      locked.metadata = before.metadata;
+      locked.deletedAt = null;
+      await trx.flush();
+      return locked;
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "updated" }]);
+  },
+  buildLog: async ({ snapshots, input, result, ctx }) => {
+    const before = snapshots?.before;
+    const after = snapshots?.after;
+    return {
+      ...await buildCrudLog(ctx, input, result?.taskId ?? null, "wms.audit.putaway.update", "Update putaway task"),
+      snapshotBefore: before,
+      snapshotAfter: after,
+      payload: { undo: { before, after } }
+    };
+  }
+};
+const deletePutawayTaskCommand = {
+  id: "wms.putaway-tasks.delete",
+  async prepare(rawInput, ctx) {
+    const id = requireId(rawInput?.id, "Putaway task");
+    const task = await loadPutawayTask(resolveEm(ctx), ctx, id);
+    return { before: snapshotPutawayTask(task) };
+  },
+  async execute(rawInput, ctx) {
+    const id = requireId(rawInput?.id, "Putaway task");
+    const em = resolveEm(ctx);
+    const scope = resolveScope(ctx);
+    const task = await withLockedPutawayTask(em, ctx, id, scope, async (locked, trx) => {
+      assertPutawayDeletable(locked.status);
+      locked.deletedAt = /* @__PURE__ */ new Date();
+      await trx.flush();
+      return locked;
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "deleted" }]);
+    return { taskId: task.id };
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload(logEntry);
+    const before = payload?.before;
+    if (!before?.id) return;
+    const em = resolveEm(ctx);
+    const scope = { tenantId: before.tenantId, organizationId: before.organizationId };
+    const task = await em.transactional(async (trx) => {
+      const locked = await findOneWithDecryption(
+        trx,
+        PutawayTask,
+        { id: before.id },
+        { lockMode: LockMode.PESSIMISTIC_WRITE },
+        scope
+      );
+      if (!locked) return null;
+      ensureTenantScope(ctx, locked.tenantId);
+      ensureOrganizationScope(ctx, locked.organizationId);
+      if (locked.status !== "cancelled") {
+        throw new CrudHttpError(409, { error: "invalid_putaway_state" });
+      }
+      if (!locked.deletedAt) return locked;
+      locked.deletedAt = null;
+      await trx.flush();
+      return locked;
+    });
+    if (!task) return;
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "updated" }]);
+  },
+  buildLog: async ({ snapshots, input, result, ctx }) => {
+    const before = snapshots?.before;
+    return {
+      ...await buildCrudLog(ctx, input, result?.taskId ?? null, "wms.audit.putaway.delete", "Delete putaway task"),
+      snapshotBefore: before,
+      payload: { undo: { before } }
+    };
+  }
+};
+const createPutawayTaskFromBalanceCommand = {
+  id: "wms.putaway-tasks.create-from-balance",
+  async execute(rawInput, ctx) {
+    const input = putawayTaskCreateFromBalanceSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const scope = resolveScope(ctx, input);
+    const task = await em.transactional(async (trx) => {
+      await requireAvailableBalanceQuantity(
+        trx,
+        ctx,
+        {
+          warehouseId: input.warehouseId,
+          sourceLocationId: input.sourceLocationId,
+          catalogVariantId: input.catalogVariantId,
+          lotId: input.lotId,
+          quantity: input.quantity
+        },
+        scope,
+        { lock: true }
+      );
+      return createOpenPutawayTask(trx, ctx, {
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+        warehouseId: input.warehouseId,
+        sourceLocationId: input.sourceLocationId,
+        targetLocationId: input.targetLocationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId,
+        quantity: input.quantity,
+        priority: input.priority,
+        assignedTo: input.assignedTo,
+        metadata: {
+          ...input.metadata ?? {},
+          source: "create_from_balance"
+        }
+      });
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "created" }]);
+    void emitWmsEvent("wms.putaway.created", {
+      id: task.id,
+      warehouseId: input.warehouseId,
+      sourceLocationId: task.sourceLocationId,
+      targetLocationId: task.targetLocationId ?? null,
+      catalogVariantId: task.catalogVariantId,
+      quantity: task.quantity,
+      tenantId: task.tenantId,
+      organizationId: task.organizationId
+    }).catch(() => void 0);
+    return { taskId: task.id };
+  },
+  buildLog: async ({ input, result, ctx }) => buildCrudLog(
+    ctx,
+    input,
+    result?.taskId ?? null,
+    "wms.audit.putaway.createFromBalance",
+    "Create putaway task from balance"
+  )
+};
+const assignPutawayTaskCommand = {
+  id: "wms.putaway-tasks.assign",
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = putawayTaskAssignSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const scope = resolveScope(ctx, input);
+    const task = await withLockedPutawayTask(em, ctx, input.id, scope, async (locked, trx) => {
+      assertPutawayAssignable(locked.status);
+      locked.assignedTo = input.assignedTo;
+      await trx.flush();
+      return locked;
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "updated" }]);
+    void emitWmsEvent("wms.putaway.assigned", {
+      id: task.id,
+      assignedTo: task.assignedTo,
+      tenantId: task.tenantId,
+      organizationId: task.organizationId
+    }).catch(() => void 0);
+    return { taskId: task.id };
+  },
+  buildLog: async ({ input, result, ctx }) => buildCrudLog(ctx, input, result?.taskId ?? null, "wms.audit.putaway.assign", "Assign putaway task")
+};
+const startPutawayTaskCommand = {
+  id: "wms.putaway-tasks.start",
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = putawayTaskStartSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const scope = resolveScope(ctx, input);
+    const task = await withLockedPutawayTask(em, ctx, input.id, scope, async (locked, trx) => {
+      assertPutawayStartable(locked.status);
+      locked.status = "in_progress";
+      await trx.flush();
+      return locked;
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "updated" }]);
+    void emitWmsEvent("wms.putaway.started", {
+      id: task.id,
+      tenantId: task.tenantId,
+      organizationId: task.organizationId
+    }).catch(() => void 0);
+    return { taskId: task.id };
+  },
+  buildLog: async ({ input, result, ctx }) => buildCrudLog(ctx, input, result?.taskId ?? null, "wms.audit.putaway.start", "Start putaway task")
+};
+const completePutawayTaskCommand = {
+  id: "wms.putaway-tasks.complete",
+  // Stock-affecting — align with Phase 1 inventory undo policy.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = putawayTaskCompleteSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const rootEm = resolveEm(ctx);
+    const scope = resolveScope(ctx, input);
+    const referenceId = buildPutawayCompleteReferenceId(input.id);
+    const outcome = await rootEm.transactional(async (trx) => {
+      const task = await findOneWithDecryption(
+        trx,
+        PutawayTask,
+        { id: input.id, deletedAt: null },
+        { lockMode: LockMode.PESSIMISTIC_WRITE },
+        scope
+      );
+      if (!task) throw new CrudHttpError(404, { error: "Putaway task not found." });
+      ensureTenantScope(ctx, task.tenantId);
+      ensureOrganizationScope(ctx, task.organizationId);
+      await resolvePutawayCompleteAuthorization(ctx, scope, task.assignedTo);
+      await enforceCommandOptimisticLockWithGuards(ctx.container, {
+        resourceKind: WMS_PUTAWAY_TASK_RESOURCE,
+        resourceId: task.id,
+        current: task.updatedAt,
+        request: ctx.request ?? null
+      });
+      const warehouseId = typeof task.warehouse === "string" ? task.warehouse : task.warehouse.id;
+      const taskQuantity = toNumber(task.quantity);
+      const existingByRef = await findPutawayCompleteMovementByReference(trx, scope, referenceId);
+      if (task.status === "done") {
+        if (!existingByRef) {
+          throw new CrudHttpError(409, { error: "invalid_putaway_state" });
+        }
+        const existingQty = toNumber(existingByRef.quantity);
+        if (Math.abs(existingQty - input.confirmedQuantity) > 1e-6) {
+          throw new CrudHttpError(409, { error: "putaway_complete_quantity_conflict" });
+        }
+        return {
+          task,
+          warehouseId,
+          taskQuantity,
+          moveResult: {
+            movementId: existingByRef.id,
+            warehouseId,
+            catalogVariantId: task.catalogVariantId,
+            quantity: existingQty,
+            tenantId: scope.tenantId,
+            organizationId: scope.organizationId,
+            movementEntity: existingByRef,
+            balances: [],
+            idempotentReplay: true
+          },
+          residual: 0,
+          alreadyDone: true,
+          emitCompletedEvent: false
+        };
+      }
+      assertPutawayCompletable(task.status);
+      assertPutawayConfirmedQuantity(taskQuantity, input.confirmedQuantity);
+      if (existingByRef) {
+        const existingQty = toNumber(existingByRef.quantity);
+        if (Math.abs(existingQty - input.confirmedQuantity) > 1e-6) {
+          throw new CrudHttpError(409, { error: "putaway_complete_quantity_conflict" });
+        }
+        task.targetLocationId = input.targetLocationId;
+        task.status = "done";
+        task.quantity = toNumericString(input.confirmedQuantity);
+        if (input.lotId) task.lotId = input.lotId;
+        await trx.flush();
+        const residual2 = putawayResidualQuantity(taskQuantity, input.confirmedQuantity);
+        if (residual2 > 0) {
+          await ensureResidualPutawayTask(trx, ctx, {
+            scope,
+            warehouseId,
+            parent: task,
+            residual: residual2
+          });
+        }
+        return {
+          task,
+          warehouseId,
+          taskQuantity,
+          moveResult: {
+            movementId: existingByRef.id,
+            warehouseId,
+            catalogVariantId: task.catalogVariantId,
+            quantity: existingQty,
+            tenantId: scope.tenantId,
+            organizationId: scope.organizationId,
+            movementEntity: existingByRef,
+            balances: [],
+            idempotentReplay: true
+          },
+          residual: residual2,
+          alreadyDone: false,
+          emitCompletedEvent: false
+        };
+      }
+      await requireActiveLocation(trx, ctx, task.sourceLocationId, warehouseId, scope);
+      const targetLocation = await requireActiveLocation(
+        trx,
+        ctx,
+        input.targetLocationId,
+        warehouseId,
+        scope
+      );
+      assertPutawayTargetLocationType(targetLocation.type);
+      const moveInput = {
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        warehouseId,
+        fromLocationId: task.sourceLocationId,
+        toLocationId: input.targetLocationId,
+        catalogVariantId: task.catalogVariantId,
+        lotId: input.lotId ?? task.lotId ?? void 0,
+        serialNumber: task.serialNumber?.trim() || void 0,
+        quantity: input.confirmedQuantity,
+        type: "putaway",
+        reason: input.reason ?? "Putaway task completion",
+        referenceType: "manual",
+        referenceId,
+        performedBy: input.performedBy,
+        performedAt: input.performedAt,
+        metadata: {
+          ...input.metadata ?? {},
+          putawayTaskId: task.id,
+          source: "putaway_task_complete"
+        }
+      };
+      const moveResult = await applyInventoryMoveInTransaction(trx, ctx, moveInput);
+      task.targetLocationId = input.targetLocationId;
+      task.status = "done";
+      task.quantity = toNumericString(input.confirmedQuantity);
+      if (input.lotId) task.lotId = input.lotId;
+      await trx.flush();
+      const residual = putawayResidualQuantity(taskQuantity, input.confirmedQuantity);
+      if (residual > 0) {
+        await ensureResidualPutawayTask(trx, ctx, {
+          scope,
+          warehouseId,
+          parent: task,
+          residual
+        });
+      }
+      return {
+        task,
+        warehouseId,
+        taskQuantity,
+        moveResult,
+        residual,
+        alreadyDone: false,
+        emitCompletedEvent: true
+      };
+    });
+    if (!outcome.alreadyDone) {
+      await emitPutawaySideEffects(ctx, [{ entity: outcome.task, action: "updated" }]);
+    }
+    await emitInventoryMoveSideEffects(ctx, outcome.moveResult);
+    if (outcome.emitCompletedEvent) {
+      void emitWmsEvent("wms.putaway.completed", {
+        id: outcome.task.id,
+        movementId: outcome.moveResult.movementId,
+        warehouseId: outcome.warehouseId,
+        sourceLocationId: outcome.task.sourceLocationId,
+        targetLocationId: outcome.task.targetLocationId,
+        catalogVariantId: outcome.task.catalogVariantId,
+        quantity: toNumericString(input.confirmedQuantity),
+        tenantId: outcome.task.tenantId,
+        organizationId: outcome.task.organizationId
+      }).catch(() => void 0);
+    }
+    return { taskId: outcome.task.id, movementId: outcome.moveResult.movementId };
+  },
+  buildLog: async ({ input, result, ctx }) => ({
+    ...await buildCrudLog(
+      ctx,
+      input,
+      result?.taskId ?? null,
+      "wms.audit.putaway.complete",
+      "Complete putaway task"
+    ),
+    context: { cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE, WMS_PUTAWAY_TASK_RESOURCE] }
+  })
+};
+const cancelPutawayTaskCommand = {
+  id: "wms.putaway-tasks.cancel",
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = putawayTaskCancelSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const scope = resolveScope(ctx, input);
+    const task = await withLockedPutawayTask(em, ctx, input.id, scope, async (locked, trx) => {
+      assertPutawayCancellable(locked.status);
+      locked.status = "cancelled";
+      locked.putawayKey = null;
+      await trx.flush();
+      return locked;
+    });
+    await emitPutawaySideEffects(ctx, [{ entity: task, action: "updated" }]);
+    void emitWmsEvent("wms.putaway.cancelled", {
+      id: task.id,
+      tenantId: task.tenantId,
+      organizationId: task.organizationId
+    }).catch(() => void 0);
+    return { taskId: task.id };
+  },
+  buildLog: async ({ input, result, ctx }) => buildCrudLog(ctx, input, result?.taskId ?? null, "wms.audit.putaway.cancel", "Cancel putaway task")
+};
+registerCommand(createPutawayTaskCommand);
+registerCommand(updatePutawayTaskCommand);
+registerCommand(deletePutawayTaskCommand);
+registerCommand(createPutawayTaskFromBalanceCommand);
+registerCommand(assignPutawayTaskCommand);
+registerCommand(startPutawayTaskCommand);
+registerCommand(completePutawayTaskCommand);
+registerCommand(cancelPutawayTaskCommand);
+//# sourceMappingURL=putaway.js.map