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

package/src/modules/wms/api/putaway-tasks/[id]/complete/route.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { putawayTaskCompleteSchema } from '../../../../data/validators'
+import { executeWmsCustomPostRoute } from '../../../inventory/helpers'
+
+export const metadata = {
+  // Floor ACL: stock-moving operators (`wms.adjust_inventory`) and managers both hold this.
+  // Command also allows `wms.manage_putaway` for any task, or adjust + assignee match.
+  POST: { requireAuth: true, requireFeatures: ['wms.adjust_inventory'] },
+}
+
+const paramsSchema = z.object({
+  id: z.string().uuid(),
+})
+
+export async function POST(request: Request, routeContext: { params: { id: string } }) {
+  const parsedParams = paramsSchema.parse(routeContext.params)
+  const body = await readJsonSafe<Record<string, unknown>>(request, {})
+  const scopedRequest = new Request(request.url, {
+    method: 'POST',
+    headers: request.headers,
+    body: JSON.stringify({ ...body, id: parsedParams.id }),
+  })
+  return executeWmsCustomPostRoute({
+    request: scopedRequest,
+    routePath: `wms/putaway-tasks/${parsedParams.id}/complete`,
+    inputSchema: putawayTaskCompleteSchema,
+    commandId: 'wms.putaway-tasks.complete',
+    describeResource: (input) => ({
+      resourceKind: 'wms.putawayTask',
+      resourceId: input.id,
+    }),
+    mapSuccess: (result: { movementId: string }) => ({
+      ok: true,
+      movementId: result.movementId,
+    }),
+  })
+}
+
+const successSchema = z.object({
+  ok: z.literal(true),
+  movementId: z.string().uuid(),
+})
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Complete putaway task',
+  methods: {
+    POST: {
+      summary: 'Complete putaway task',
+      description:
+        'Confirms putaway quantity and target location, then moves stock staging→storage via an InventoryMovement of type putaway. Requires `wms.adjust_inventory`. Callers with `wms.manage_putaway` may complete any task; operators may complete only when the task is assigned to them.',
+      requestBody: { contentType: 'application/json', schema: putawayTaskCompleteSchema },
+      responses: [{ status: 200, description: 'Putaway completed', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 403, description: 'Forbidden', schema: errorSchema },
+        { status: 409, description: 'Invalid putaway state or insufficient stock', schema: errorSchema },
+        { status: 422, description: 'Invalid or inactive location', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/putaway-tasks/[id]/start/route.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { putawayTaskStartSchema } from '../../../../data/validators'
+import { executeWmsCustomPostRoute } from '../../../inventory/helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.manage_putaway'] },
+}
+
+const paramsSchema = z.object({
+  id: z.string().uuid(),
+})
+
+export async function POST(request: Request, routeContext: { params: { id: string } }) {
+  const parsedParams = paramsSchema.parse(routeContext.params)
+  const body = await readJsonSafe<Record<string, unknown>>(request, {})
+  const scopedRequest = new Request(request.url, {
+    method: 'POST',
+    headers: request.headers,
+    body: JSON.stringify({ ...body, id: parsedParams.id }),
+  })
+  return executeWmsCustomPostRoute({
+    request: scopedRequest,
+    routePath: `wms/putaway-tasks/${parsedParams.id}/start`,
+    inputSchema: putawayTaskStartSchema,
+    commandId: 'wms.putaway-tasks.start',
+    describeResource: (input) => ({
+      resourceKind: 'wms.putawayTask',
+      resourceId: input.id,
+    }),
+    mapSuccess: () => ({ ok: true }),
+  })
+}
+
+const successSchema = z.object({ ok: z.literal(true) })
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Start putaway task',
+  methods: {
+    POST: {
+      summary: 'Start putaway task',
+      description: 'Marks a putaway task as in progress.',
+      requestBody: { contentType: 'application/json', schema: putawayTaskStartSchema },
+      responses: [{ status: 200, description: 'Putaway task started', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 403, description: 'Forbidden', schema: errorSchema },
+        { status: 409, description: 'Invalid putaway state', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/putaway-tasks/create-from-balance/route.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { putawayTaskCreateFromBalanceSchema } from '../../../data/validators'
+import { executeWmsCustomPostRoute } from '../../inventory/helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.manage_putaway'] },
+}
+
+export async function POST(request: Request) {
+  return executeWmsCustomPostRoute({
+    request,
+    routePath: 'wms/putaway-tasks/create-from-balance',
+    inputSchema: putawayTaskCreateFromBalanceSchema,
+    commandId: 'wms.putaway-tasks.create-from-balance',
+    describeResource: (input) => ({
+      resourceKind: 'wms.putawayTask',
+      resourceId: `${input.warehouseId}:${input.sourceLocationId}:${input.catalogVariantId}`,
+    }),
+    mapSuccess: (result: { taskId: string }) => ({
+      ok: true,
+      taskId: result.taskId,
+    }),
+  })
+}
+
+const successSchema = z.object({
+  ok: z.literal(true),
+  taskId: z.string().uuid(),
+})
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Create putaway task from balance',
+  methods: {
+    POST: {
+      summary: 'Create putaway task from balance',
+      description: 'Manually creates an open putaway task against existing staged stock.',
+      requestBody: { contentType: 'application/json', schema: putawayTaskCreateFromBalanceSchema },
+      responses: [{ status: 200, description: 'Putaway task created', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 403, description: 'Forbidden', schema: errorSchema },
+        { status: 422, description: 'Invalid location', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/putaway-tasks/route.ts

@@ -0,0 +1,199 @@
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { parseScopedCommandInput, resolveCrudRecordId } from '@open-mercato/shared/lib/api/scoped'
+import { E } from '#generated/entities.ids.generated'
+import { PutawayTask } from '../../data/entities'
+import { putawayTaskCreateSchema, putawayTaskUpdateSchema } from '../../data/validators'
+import {
+  assertPutawayLifecycleFieldsForbidden,
+  buildPutawayTaskStatusFilter,
+} from '../../lib/putaway'
+import { createPagedListResponseSchema, createWmsCrudOpenApi, defaultOkResponseSchema } from '../openapi'
+
+const F = {
+  id: 'id',
+  organization_id: 'organization_id',
+  tenant_id: 'tenant_id',
+  warehouse_id: 'warehouse_id',
+  source_location_id: 'source_location_id',
+  target_location_id: 'target_location_id',
+  catalog_variant_id: 'catalog_variant_id',
+  lot_id: 'lot_id',
+  serial_number: 'serial_number',
+  quantity: 'quantity',
+  status: 'status',
+  assigned_to: 'assigned_to',
+  priority: 'priority',
+  created_at: 'created_at',
+  updated_at: 'updated_at',
+} as const
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['wms.view'] },
+  POST: { requireAuth: true, requireFeatures: ['wms.manage_putaway'] },
+  PUT: { requireAuth: true, requireFeatures: ['wms.manage_putaway'] },
+  DELETE: { requireAuth: true, requireFeatures: ['wms.manage_putaway'] },
+}
+
+export const metadata = routeMetadata
+
+const rawBodySchema = z.object({}).passthrough()
+
+const listSchema = z
+  .object({
+    page: z.coerce.number().min(1).default(1),
+    pageSize: z.coerce.number().min(1).max(100).default(25),
+    ids: z.string().optional(),
+    warehouseId: z.string().uuid().optional(),
+    // Single status or comma-separated (e.g. open,in_progress for the active queue).
+    status: z.string().optional(),
+    assignedTo: z.string().uuid().optional(),
+    catalogVariantId: z.string().uuid().optional(),
+    sortField: z.string().optional(),
+    sortDir: z.enum(['asc', 'desc']).optional(),
+  })
+  .passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: PutawayTask,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.wms.putaway_task },
+  list: {
+    schema: listSchema,
+    disableListCache: true,
+    entityId: E.wms.putaway_task,
+    fields: [
+      F.id,
+      F.organization_id,
+      F.tenant_id,
+      F.warehouse_id,
+      F.source_location_id,
+      F.target_location_id,
+      F.catalog_variant_id,
+      F.lot_id,
+      F.serial_number,
+      F.quantity,
+      F.status,
+      F.assigned_to,
+      F.priority,
+      F.created_at,
+      F.updated_at,
+    ],
+    sortFieldMap: {
+      status: F.status,
+      priority: F.priority,
+      createdAt: F.created_at,
+      updatedAt: F.updated_at,
+      quantity: F.quantity,
+    },
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      if (typeof query.ids === 'string' && query.ids.trim().length > 0) {
+        filters[F.id] = {
+          $in: query.ids
+            .split(',')
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0),
+        }
+      }
+      if (typeof query.warehouseId === 'string' && query.warehouseId.length > 0) {
+        filters[F.warehouse_id] = { $eq: query.warehouseId }
+      }
+      if (typeof query.status === 'string' && query.status.length > 0) {
+        const statusFilter = buildPutawayTaskStatusFilter(query.status)
+        if (statusFilter) filters[F.status] = statusFilter
+      }
+      if (typeof query.assignedTo === 'string' && query.assignedTo.length > 0) {
+        filters[F.assigned_to] = { $eq: query.assignedTo }
+      }
+      if (typeof query.catalogVariantId === 'string' && query.catalogVariantId.length > 0) {
+        filters[F.catalog_variant_id] = { $eq: query.catalogVariantId }
+      }
+      return filters
+    },
+  },
+  actions: {
+    create: {
+      commandId: 'wms.putaway-tasks.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return parseScopedCommandInput(putawayTaskCreateSchema, raw ?? {}, ctx, translate)
+      },
+      response: ({ result }) => ({ id: result?.taskId ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: 'wms.putaway-tasks.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        assertPutawayLifecycleFieldsForbidden(raw)
+        return parseScopedCommandInput(putawayTaskUpdateSchema, raw ?? {}, ctx, translate)
+      },
+      response: () => ({ ok: true }),
+    },
+    delete: {
+      commandId: 'wms.putaway-tasks.delete',
+      schema: rawBodySchema,
+      mapInput: async ({ parsed, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return { id: resolveCrudRecordId(parsed, ctx, translate) }
+      },
+      response: () => ({ ok: true }),
+    },
+  },
+})
+
+export const GET = crud.GET
+export const POST = crud.POST
+export const PUT = crud.PUT
+export const DELETE = crud.DELETE
+
+const putawayTaskListItemSchema = z.object({
+  id: z.string().uuid().nullable().optional(),
+  organization_id: z.string().uuid().nullable().optional(),
+  tenant_id: z.string().uuid().nullable().optional(),
+  warehouse_id: z.string().uuid().nullable().optional(),
+  source_location_id: z.string().uuid().nullable().optional(),
+  target_location_id: z.string().uuid().nullable().optional(),
+  catalog_variant_id: z.string().uuid().nullable().optional(),
+  lot_id: z.string().uuid().nullable().optional(),
+  serial_number: z.string().nullable().optional(),
+  quantity: z.union([z.string(), z.number()]).nullable().optional(),
+  status: z.string().nullable().optional(),
+  assigned_to: z.string().uuid().nullable().optional(),
+  priority: z.union([z.string(), z.number()]).nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})
+
+export const openApi = createWmsCrudOpenApi({
+  resourceName: 'PutawayTask',
+  pluralName: 'Putaway tasks',
+  querySchema: listSchema,
+  listResponseSchema: createPagedListResponseSchema(putawayTaskListItemSchema),
+  create: {
+    schema: putawayTaskCreateSchema,
+    description:
+      'Creates an open putaway task after verifying available staging balance (on-hand minus reserved/allocated minus open/in-progress putaway commitments). Target location may be null until completion. Assignee changes use POST .../assign.',
+  },
+  update: {
+    schema: putawayTaskUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description:
+      'Updates putaway task fields (locations, quantity, priority, metadata). Status and assignedTo are lifecycle-only — use POST .../{assign,start,complete,cancel}.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Soft-deletes a putaway task by id.',
+  },
+})

package/src/modules/wms/api/receiving-lines/route.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { parseScopedCommandInput, resolveCrudRecordId } from '@open-mercato/shared/lib/api/scoped'
+import { E } from '#generated/entities.ids.generated'
+import { ReceivingLine } from '../../data/entities'
+import { receivingLineCreateSchema, receivingLineUpdateSchema } from '../../data/validators'
+import { assertReceivingLineLifecycleFieldsForbidden } from '../../lib/asnReceiving'
+import { createPagedListResponseSchema, createWmsCrudOpenApi, defaultOkResponseSchema } from '../openapi'
+
+const F = {
+  id: 'id',
+  organization_id: 'organization_id',
+  tenant_id: 'tenant_id',
+  asn_id: 'asn_id',
+  catalog_variant_id: 'catalog_variant_id',
+  expected_qty: 'expected_qty',
+  received_qty: 'received_qty',
+  lot_number: 'lot_number',
+  serial_numbers: 'serial_numbers',
+  qc_status: 'qc_status',
+  target_staging_location_id: 'target_staging_location_id',
+  rejection_reason: 'rejection_reason',
+  created_at: 'created_at',
+  updated_at: 'updated_at',
+} as const
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['wms.view'] },
+  POST: { requireAuth: true, requireFeatures: ['wms.manage_asn'] },
+  PUT: { requireAuth: true, requireFeatures: ['wms.manage_asn'] },
+  DELETE: { requireAuth: true, requireFeatures: ['wms.manage_asn'] },
+}
+
+export const metadata = routeMetadata
+
+const rawBodySchema = z.object({}).passthrough()
+
+const listSchema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  pageSize: z.coerce.number().min(1).max(100).default(25),
+  ids: z.string().optional(),
+  asnId: z.string().uuid().optional(),
+  catalogVariantId: z.string().uuid().optional(),
+  qcStatus: z.enum(['pending', 'passed', 'failed']).optional(),
+  sortField: z.string().optional(),
+  sortDir: z.enum(['asc', 'desc']).optional(),
+}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: ReceivingLine,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.wms.receiving_line },
+  list: {
+    schema: listSchema,
+    disableListCache: true,
+    entityId: E.wms.receiving_line,
+    fields: [
+      F.id,
+      F.organization_id,
+      F.tenant_id,
+      F.asn_id,
+      F.catalog_variant_id,
+      F.expected_qty,
+      F.received_qty,
+      F.lot_number,
+      F.serial_numbers,
+      F.qc_status,
+      F.target_staging_location_id,
+      F.rejection_reason,
+      F.created_at,
+      F.updated_at,
+    ],
+    sortFieldMap: {
+      expectedQty: F.expected_qty,
+      receivedQty: F.received_qty,
+      qcStatus: F.qc_status,
+      createdAt: F.created_at,
+      updatedAt: F.updated_at,
+    },
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      if (typeof query.ids === 'string' && query.ids.trim().length > 0) {
+        filters[F.id] = {
+          $in: query.ids.split(',').map((value) => value.trim()).filter((value) => value.length > 0),
+        }
+      }
+      if (typeof query.asnId === 'string' && query.asnId.length > 0) {
+        filters[F.asn_id] = { $eq: query.asnId }
+      }
+      if (typeof query.catalogVariantId === 'string' && query.catalogVariantId.length > 0) {
+        filters[F.catalog_variant_id] = { $eq: query.catalogVariantId }
+      }
+      if (typeof query.qcStatus === 'string' && query.qcStatus.length > 0) {
+        filters[F.qc_status] = { $eq: query.qcStatus }
+      }
+      return filters
+    },
+  },
+  actions: {
+    create: {
+      commandId: 'wms.receiving-lines.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return parseScopedCommandInput(receivingLineCreateSchema, raw ?? {}, ctx, translate)
+      },
+      response: ({ result }) => ({ id: result?.lineId ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: 'wms.receiving-lines.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        assertReceivingLineLifecycleFieldsForbidden(raw)
+        return parseScopedCommandInput(receivingLineUpdateSchema, raw ?? {}, ctx, translate)
+      },
+      response: () => ({ ok: true }),
+    },
+    delete: {
+      commandId: 'wms.receiving-lines.delete',
+      schema: rawBodySchema,
+      mapInput: async ({ parsed, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return { id: resolveCrudRecordId(parsed, ctx, translate) }
+      },
+      response: () => ({ ok: true }),
+    },
+  },
+})
+
+export const GET = crud.GET
+export const POST = crud.POST
+export const PUT = crud.PUT
+export const DELETE = crud.DELETE
+
+const receivingLineListItemSchema = z.object({
+  id: z.string().uuid().nullable().optional(),
+  organization_id: z.string().uuid().nullable().optional(),
+  tenant_id: z.string().uuid().nullable().optional(),
+  asn_id: z.string().uuid().nullable().optional(),
+  catalog_variant_id: z.string().uuid().nullable().optional(),
+  expected_qty: z.union([z.string(), z.number()]).nullable().optional(),
+  received_qty: z.union([z.string(), z.number()]).nullable().optional(),
+  lot_number: z.string().nullable().optional(),
+  serial_numbers: z.array(z.string()).nullable().optional(),
+  qc_status: z.string().nullable().optional(),
+  target_staging_location_id: z.string().uuid().nullable().optional(),
+  rejection_reason: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})
+
+export const openApi = createWmsCrudOpenApi({
+  resourceName: 'ReceivingLine',
+  pluralName: 'Receiving lines',
+  querySchema: listSchema,
+  listResponseSchema: createPagedListResponseSchema(receivingLineListItemSchema),
+  create: {
+    schema: receivingLineCreateSchema,
+    description: 'Creates a receiving line against an ASN.',
+  },
+  update: {
+    schema: receivingLineUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Updates a receiving line by id.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Soft-deletes a receiving line by id.',
+  },
+})

package/src/modules/wms/api/scan/putaway/route.ts

@@ -0,0 +1,108 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { putawayTaskCompleteSchema, scanPutawaySchema } from '../../../data/validators'
+import { resolveScanPutawayCommandInput } from '../../../lib/scanResolve'
+import { executeWmsCustomPostRoute } from '../../inventory/helpers'
+
+const logger = createLogger('wms')
+
+export const metadata = {
+  // Same floor ACL as putaway-tasks/:id/complete (command enforces manage vs assignee).
+  POST: { requireAuth: true, requireFeatures: ['wms.adjust_inventory'] },
+}
+
+const successSchema = z.object({
+  ok: z.literal(true),
+  movementId: z.string().uuid(),
+})
+const errorSchema = z.object({ error: z.string() })
+
+export async function POST(request: Request) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(request)
+    if (!auth?.tenantId) {
+      throw new CrudHttpError(401, { error: 'Unauthorized' })
+    }
+    const organizationScope = await resolveOrganizationScopeForRequest({
+      container,
+      auth,
+      request,
+    })
+    const organizationId = organizationScope?.selectedId ?? auth.orgId ?? null
+    if (!organizationId) {
+      throw new CrudHttpError(400, { error: 'organization_scope_required' })
+    }
+    const body = await readJsonSafe<Record<string, unknown>>(request, {})
+    const parsed = scanPutawaySchema.parse(body)
+    if (parsed.tenantId !== auth.tenantId && !auth.isSuperAdmin) {
+      throw new CrudHttpError(403, { error: 'Forbidden' })
+    }
+    // Scope organization from auth/session — never trust body organizationId for
+    // task/location resolve (same contract as scan/receive and resolve-location/lot).
+    const scoped = {
+      ...parsed,
+      tenantId: auth.tenantId,
+      organizationId,
+    }
+    const em = (container.resolve('em') as EntityManager).fork()
+    const commandInput = await resolveScanPutawayCommandInput(em, scoped)
+    const scopedRequest = new Request(request.url, {
+      method: 'POST',
+      headers: request.headers,
+      body: JSON.stringify(commandInput),
+    })
+    return executeWmsCustomPostRoute({
+      request: scopedRequest,
+      routePath: 'wms/scan/putaway',
+      inputSchema: putawayTaskCompleteSchema,
+      commandId: 'wms.putaway-tasks.complete',
+      describeResource: (input) => ({
+        resourceKind: 'wms.putawayTask',
+        resourceId: input.id,
+      }),
+      mapSuccess: (result: { movementId: string }) => ({
+        ok: true,
+        movementId: result.movementId,
+      }),
+    })
+  } catch (error) {
+    if (error instanceof CrudHttpError) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Validation failed', details: error.issues }, { status: 400 })
+    }
+    logger.error('scan putaway failed', { err: error })
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Scan-assisted putaway complete',
+  methods: {
+    POST: {
+      summary: 'Complete putaway from scanned target location code',
+      description:
+        'Resolves the scanned target location code, then executes the same command path as POST /api/wms/putaway-tasks/:id/complete. Organization is taken from the authenticated session scope, not the request body. Requires `wms.adjust_inventory`; managers with `wms.manage_putaway` may complete any task, operators only when assigned.',
+      requestBody: { contentType: 'application/json', schema: scanPutawaySchema },
+      responses: [{ status: 200, description: 'Putaway completed', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 404, description: 'Task or location not found', schema: errorSchema },
+        { status: 409, description: 'Invalid putaway state or insufficient stock', schema: errorSchema },
+        { status: 422, description: 'Invalid or inactive location', schema: errorSchema },
+      ],
+    },
+  },
+}