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

package/src/modules/wms/api/asns/[id]/complete/route.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { asnCloseSchema } from '../../../../data/validators'
+import { executeWmsCustomPostRoute } from '../../../inventory/helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.manage_asn'] },
+}
+
+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/asns/${parsedParams.id}/complete`,
+    inputSchema: asnCloseSchema,
+    commandId: 'wms.asns.close',
+    describeResource: (input) => ({
+      resourceKind: 'wms.asn',
+      resourceId: input.id,
+    }),
+    mapSuccess: (result: { status: string }) => ({
+      ok: true,
+      status: result.status,
+    }),
+  })
+}
+
+const successSchema = z.object({
+  ok: z.literal(true),
+  status: z.enum(['draft', 'in_transit', 'received', 'closed']),
+})
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Complete ASN',
+  methods: {
+    POST: {
+      summary: 'Complete ASN',
+      description:
+        'Marks an ASN as received when it has receipt activity (at least one line with receivedQty > 0) and lines are complete (QC-passed accepted qty meets expected), or when closeWhenShort is true for short/QC-fail receipts after some receipt activity. Header-only ASNs and zero-receipt lines are rejected even with closeWhenShort.',
+      requestBody: { contentType: 'application/json', schema: asnCloseSchema },
+      responses: [{ status: 200, description: 'ASN completed', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 409, description: 'Invalid receipt state', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/asns/[id]/receive/route.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { asnReceiveLineSchema } from '../../../../data/validators'
+import { executeWmsCustomPostRoute } from '../../../inventory/helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.receive_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, asnId: parsedParams.id }),
+  })
+  return executeWmsCustomPostRoute({
+    request: scopedRequest,
+    routePath: `wms/asns/${parsedParams.id}/receive`,
+    inputSchema: asnReceiveLineSchema,
+    commandId: 'wms.asns.receive-line',
+    describeResource: (input) => ({
+      resourceKind: 'wms.asn',
+      resourceId: input.asnId,
+    }),
+    mapSuccess: (result: {
+      movementIds: string[]
+      putawayTaskIds: string[]
+      receivedQty?: number
+      asnUpdatedAt?: string
+    }) => ({
+      ok: true,
+      movementIds: result.movementIds,
+      putawayTaskIds: result.putawayTaskIds,
+      receivedQty: result.receivedQty,
+      asnUpdatedAt: result.asnUpdatedAt,
+    }),
+  })
+}
+
+const successSchema = z.object({
+  ok: z.literal(true),
+  movementIds: z.array(z.string().uuid()),
+  putawayTaskIds: z.array(z.string().uuid()),
+  receivedQty: z.number().optional(),
+  asnUpdatedAt: z.string().datetime().optional(),
+})
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Receive ASN line',
+  methods: {
+    POST: {
+      summary: 'Receive ASN line',
+      description:
+        'Receives a line against an ASN with QC outcome. QC pass writes receipt stock at staging/dock; QC fail records audit without balance increase. Both require absolute targetReceivedQty for retry-safe attempts (optional idempotencyKey is an extra stabilizer).',
+      requestBody: { contentType: 'application/json', schema: asnReceiveLineSchema },
+      responses: [{ status: 200, description: 'ASN line received', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 409, description: 'Invalid receipt state', schema: errorSchema },
+        { status: 422, description: 'Tracking or QC transition invalid', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/asns/route.ts

@@ -0,0 +1,200 @@
+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 { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { E } from '#generated/entities.ids.generated'
+import { Asn } from '../../data/entities'
+import { asnCreatePublicSchema, asnUpdateSchema } from '../../data/validators'
+import { buildAsnStatusFilter } from '../../lib/asnReceiving'
+import { attachVendorLabelsToListItems, attachWarehouseLabelsToListItems } from '../listEnrichers'
+import { createPagedListResponseSchema, createWmsCrudOpenApi, defaultOkResponseSchema } from '../openapi'
+
+const F = {
+  id: 'id',
+  organization_id: 'organization_id',
+  tenant_id: 'tenant_id',
+  warehouse_id: 'warehouse_id',
+  vendor_id: 'vendor_id',
+  status: 'status',
+  expected_at: 'expected_at',
+  reference_number: 'reference_number',
+  notes: 'notes',
+  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),
+  search: z.string().optional(),
+  ids: z.string().optional(),
+  warehouseId: z.string().uuid().optional(),
+  vendorId: z.string().uuid().optional(),
+  // Single status or comma-separated (e.g. draft,in_transit for open receiving queue).
+  status: z.string().optional(),
+  sortField: z.string().optional(),
+  sortDir: z.enum(['asc', 'desc']).optional(),
+}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: Asn,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.wms.asn },
+  list: {
+    schema: listSchema,
+    disableListCache: true,
+    entityId: E.wms.asn,
+    fields: [
+      F.id,
+      F.organization_id,
+      F.tenant_id,
+      F.warehouse_id,
+      F.vendor_id,
+      F.status,
+      F.expected_at,
+      F.reference_number,
+      F.notes,
+      F.created_at,
+      F.updated_at,
+    ],
+    sortFieldMap: {
+      status: F.status,
+      expectedAt: F.expected_at,
+      createdAt: F.created_at,
+      updatedAt: F.updated_at,
+      referenceNumber: F.reference_number,
+    },
+    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.vendorId === 'string' && query.vendorId.length > 0) {
+        filters[F.vendor_id] = { $eq: query.vendorId }
+      }
+      if (typeof query.status === 'string' && query.status.length > 0) {
+        const statusFilter = buildAsnStatusFilter(query.status)
+        if (statusFilter) filters[F.status] = statusFilter
+      }
+      const term = query.search?.trim()
+      if (term) {
+        const like = `%${escapeLikePattern(term)}%`
+        filters.$or = [
+          { [F.reference_number]: { $ilike: like } },
+          { [F.notes]: { $ilike: like } },
+        ]
+      }
+      return filters
+    },
+  },
+  hooks: {
+    afterList: async (payload, ctx) => {
+      await Promise.all([
+        attachWarehouseLabelsToListItems(payload, ctx),
+        attachVendorLabelsToListItems(payload, ctx),
+      ])
+    },
+  },
+  actions: {
+    create: {
+      commandId: 'wms.asns.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        // Public create strips sourceKey — procurement/system sets it via command with auth: null.
+        return parseScopedCommandInput(asnCreatePublicSchema, raw ?? {}, ctx, translate)
+      },
+      response: ({ result }) => ({
+        id: result?.asnId ?? null,
+        lineIds: result?.lineIds ?? [],
+      }),
+      status: 201,
+    },
+    update: {
+      commandId: 'wms.asns.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return parseScopedCommandInput(asnUpdateSchema, raw ?? {}, ctx, translate)
+      },
+      response: () => ({ ok: true }),
+    },
+    delete: {
+      commandId: 'wms.asns.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 asnListItemSchema = 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(),
+  warehouse_name: z.string().nullable().optional(),
+  warehouse_code: z.string().nullable().optional(),
+  vendor_id: z.string().uuid().nullable().optional(),
+  vendor_name: z.string().nullable().optional(),
+  status: z.string().nullable().optional(),
+  expected_at: z.string().nullable().optional(),
+  reference_number: z.string().nullable().optional(),
+  notes: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})
+
+export const openApi = createWmsCrudOpenApi({
+  resourceName: 'ASN',
+  pluralName: 'ASNs',
+  querySchema: listSchema,
+  listResponseSchema: createPagedListResponseSchema(asnListItemSchema),
+  create: {
+    schema: asnCreatePublicSchema,
+    description:
+      'Creates an ASN with optional expected receiving lines. `sourceKey` is server-only (procurement/system path) and is not accepted on this public API.',
+  },
+  update: {
+    schema: asnUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description:
+      'Updates an ASN by id while status is draft or in_transit and no receiving line has receipt/QC activity. Received/closed ASNs, or ASNs with line receipt/QC activity, return 409 invalid_receipt_state (status demotion and warehouse/header changes are not allowed). Status may only be set to draft or in_transit; received/closed are set via receive/complete flows.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Soft-deletes an ASN by id.',
+  },
+})

package/src/modules/wms/api/inventory/helpers.ts

@@ -5,13 +5,11 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveSingleOrganizationIdOrDeny } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { ensureOrganizationScope } from '@open-mercato/shared/lib/commands/scope'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
-import {
-  runCrudMutationGuardAfterSuccess,
-  validateCrudMutationGuard,
-} from '@open-mercato/shared/lib/crud/mutation-guard'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
 import { runCustomRouteAfterInterceptors } from '@open-mercato/shared/lib/crud/custom-route-interceptor'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
@@ -31,6 +29,27 @@ type ExecuteWmsCustomPostRouteOptions<TInput, TResult> = {
   mapSuccess: (result: TResult) => Record<string, unknown>
 }
 
+function resolveBodyOrganizationId(body: Record<string, unknown>): string | null {
+  const raw = body.organizationId
+  if (typeof raw !== 'string') return null
+  const trimmed = raw.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+/**
+ * Shared POST helper for WMS custom write routes.
+ *
+ * Organization scoping:
+ * - When the body includes `organizationId`, pass it through and validate with
+ *   `ensureOrganizationScope` (allowed org ids / Pattern C). Do not silently
+ *   overwrite with the session-selected org — that mis-routes multi-org writes.
+ * - When the body omits `organizationId`, default to the session selected/auth org.
+ * - `tenantId` is always taken from auth (never from the body).
+ *
+ * Intentional session-only exception: barcode scan resolve/receive/putaway routes
+ * force session org onto the request body *before* calling this helper so resolve
+ * lookups cannot probe another org. That pre-scope policy stays on those routes.
+ */
 export async function executeWmsCustomPostRoute<TInput, TResult>(
   options: ExecuteWmsCustomPostRouteOptions<TInput, TResult>,
 ) {
@@ -54,41 +73,45 @@ export async function executeWmsCustomPostRoute<TInput, TResult>(
       organizationIds: organizationScope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
       request: options.request,
     }
-    const body = await readJsonSafe<Record<string, unknown>>(options.request, {})
-    const parsed = options.inputSchema.parse(body)
-    const resource = options.describeResource(parsed)
-    const guardResult = await validateCrudMutationGuard(container, {
+    const body = (await readJsonSafe<Record<string, unknown>>(options.request, {})) ?? {}
+    const sessionOrganizationId = ctx.selectedOrganizationId ?? auth.orgId ?? null
+    const organizationId = resolveBodyOrganizationId(body) ?? sessionOrganizationId
+    if (!organizationId) {
+      throw new CrudHttpError(400, { error: 'organization_scope_required' })
+    }
+    ensureOrganizationScope(ctx, organizationId)
+    const scopedBody = {
+      ...body,
       tenantId: auth.tenantId,
-      organizationId: ctx.selectedOrganizationId,
-      userId: auth.sub,
-      resourceKind: resource.resourceKind,
-      resourceId: resource.resourceId,
-      operation: 'custom',
-      requestMethod: options.request.method,
-      requestHeaders: options.request.headers,
-      mutationPayload: parsed as Record<string, unknown>,
-    })
-    if (guardResult && !guardResult.ok) {
-      return NextResponse.json(guardResult.body, { status: guardResult.status })
+      organizationId,
     }
-    const commandBus = container.resolve('commandBus') as CommandBus
-    const execution = await commandBus.execute<TInput, TResult>(options.commandId, {
-      input: parsed,
-      ctx,
-    })
-    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
-      await runCrudMutationGuardAfterSuccess(container, {
-        tenantId: auth.tenantId,
-        organizationId: ctx.selectedOrganizationId,
+    const parsed = options.inputSchema.parse(scopedBody)
+    const resource = options.describeResource(parsed)
+    const guardResult = await runRouteMutationGuards({
+      container,
+      req: options.request,
+      auth: {
         userId: auth.sub,
+        tenantId: auth.tenantId,
+        organizationId,
+      },
+      input: {
         resourceKind: resource.resourceKind,
         resourceId: resource.resourceId,
         operation: 'custom',
-        requestMethod: options.request.method,
-        requestHeaders: options.request.headers,
-        metadata: guardResult.metadata ?? null,
-      })
+        mutationPayload: parsed as Record<string, unknown>,
+      },
+    })
+    if (!guardResult.ok) {
+      return NextResponse.json(guardResult.errorBody, { status: guardResult.errorStatus })
     }
+    const commandInput = (guardResult.modifiedPayload as TInput | undefined) ?? parsed
+    const commandBus = container.resolve('commandBus') as CommandBus
+    const execution = await commandBus.execute<TInput, TResult>(options.commandId, {
+      input: commandInput,
+      ctx,
+    })
+    await guardResult.runAfterSuccess()
     const responseBody = options.mapSuccess(execution.result)
     const intercepted = await runCustomRouteAfterInterceptors({
       routePath: options.routePath,
@@ -96,7 +119,7 @@ export async function executeWmsCustomPostRoute<TInput, TResult>(
       request: {
         method: 'POST',
         url: options.request.url,
-        body: parsed as Record<string, unknown>,
+        body: commandInput as Record<string, unknown>,
         headers: Object.fromEntries(options.request.headers.entries()),
       },
       response: {
@@ -108,7 +131,7 @@ export async function executeWmsCustomPostRoute<TInput, TResult>(
         em: container.resolve('em'),
         container,
         userId: auth.sub,
-        organizationId: ctx.selectedOrganizationId,
+        organizationId,
         tenantId: auth.tenantId,
       },
     })

package/src/modules/wms/api/inventory/receive/route.ts

@@ -36,7 +36,8 @@ export const openApi: OpenApiRouteDoc = {
   methods: {
     POST: {
       summary: 'Receive inventory',
-      description: 'Records inbound inventory receipt and appends a receipt movement ledger row.',
+      description:
+        'Records inbound inventory receipt and appends a receipt movement ledger row. When `organizationId` is present it must be in the caller organization scope; otherwise the session-selected organization is used.',
       requestBody: { contentType: 'application/json', schema: inventoryReceiveSchema },
       responses: [{ status: 200, description: 'Inventory received', schema: successSchema }],
       errors: [

package/src/modules/wms/api/listEnrichers.ts

@@ -266,6 +266,44 @@ export async function attachInventoryProfileCatalogLabelsToListItems(
   ])
 }
 
+// ---------------------------------------------------------------------------
+// Customers (ASN vendors)
+// ---------------------------------------------------------------------------
+
+type CustomerLookupRow = LookupRow & { display_name?: string | null }
+
+const CUSTOMER_FIELDS = ['id', 'display_name']
+
+/**
+ * Decorate list items with `vendor_name` when they carry a `vendor_id` column
+ * referencing `customers.customer_entity` by UUID only (no ORM cross-module
+ * relations). Mutates `payload.items` in place.
+ */
+export async function attachVendorLabelsToListItems(
+  payload: AnyListPayload,
+  ctx: CrudCtx,
+): Promise<void> {
+  const items = Array.isArray(payload?.items) ? payload.items : []
+  if (items.length === 0) return
+  const ids = uniqueIdsFromKeys(items, ['vendor_id'])
+  if (ids.length === 0) return
+  const map = (await batchLoadById(
+    ctx,
+    E.customers.customer_entity,
+    ids,
+    CUSTOMER_FIELDS,
+    'vendor',
+  )) as Map<string, CustomerLookupRow>
+  if (map.size === 0) return
+  for (const item of items) {
+    const id = item?.vendor_id
+    if (typeof id !== 'string' || !id) continue
+    const row = map.get(id)
+    if (!row) continue
+    decorateOnce(item, 'vendor_name', row.display_name ?? null)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Reservation sources
 // ---------------------------------------------------------------------------

package/src/modules/wms/api/putaway-tasks/[id]/assign/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 { putawayTaskAssignSchema } 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}/assign`,
+    inputSchema: putawayTaskAssignSchema,
+    commandId: 'wms.putaway-tasks.assign',
+    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: 'Assign putaway task',
+  methods: {
+    POST: {
+      summary: 'Assign putaway task',
+      description: 'Assigns a putaway task to a user.',
+      requestBody: { contentType: 'application/json', schema: putawayTaskAssignSchema },
+      responses: [{ status: 200, description: 'Putaway task assigned', 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/[id]/cancel/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 { putawayTaskCancelSchema } 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}/cancel`,
+    inputSchema: putawayTaskCancelSchema,
+    commandId: 'wms.putaway-tasks.cancel',
+    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: 'Cancel putaway task',
+  methods: {
+    POST: {
+      summary: 'Cancel putaway task',
+      description: 'Cancels an open or in-progress putaway task without moving stock.',
+      requestBody: { contentType: 'application/json', schema: putawayTaskCancelSchema },
+      responses: [{ status: 200, description: 'Putaway task cancelled', 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 },
+      ],
+    },
+  },
+}