Picking: waves, pick tasks, and PICK-STAGE

Release waves (manual or scheduled), generate pick tasks per order, and execute step-by-step on the phone — including partial picks, skips and shorts.

Wave release#

A wave groups outbound shipments (wms_shipments) by merchant × filter, chunks them by order count, and releases them as a wave; each shipment in the wave then gets its own pick task. Two entry points: manual release (desktop wave/manual) and scheduled release (scheduler + external cron). Only shipments with status commit/draft/ready are eligible; shipments already locked by an unfinished wave (draft/released/picking) are excluded from new matches.

• Wave Filter: conditions [{field, operator, values[]}], operators in/not_in/eq/ne/gt/lt/gte/lte (wave/filter).
• Dispatch Setting: customer_filters [{merchant_id, filter_id}], max/min order qty per plan, default_pick_method (order / batch / wave / wave_by_item, default order), is_active (wave/settings).
• Scheduler: work_days (1=Monday … 7=Sunday, default 1–5), time_from/time_to, step_minutes, is_active (wave/scheduler).
• Cutoff times: per merchant/carrier, HH:MM (wave/cutoff-time).

1. Pick a Customer (merchant, required) + 1 or more Dispatch Settings → Preview: returns each setting’s matched order count + per-group detail without creating a wave.
2. Optionally override min/max_qty_per_batch (Min ≤ Max is validated).
3. Release: builds the wave — wave_no = WV-YYYYMMDD-NNNN, status=released (a wave is born released; there is no draft intermediate state), shipment_ids holds the outbound shipment ids.
4. After release, the page lists the wave’s shipments — Create Pick Task per shipment (see below).
5. Scheduled release: an external cron POSTs /api/wms/wave/scheduler/run every N minutes (with x-cron-secret). It only runs schedulers whose weekday is in work_days, whose current time is within time_from~time_to, and whose last run was ≥ step_minutes ago.

Generating pick tasks#

• Three entry points: the released wave page, bulk-selecting shipments in the order list → Create Pick Task, or Create Pick Task on the order detail.
• pick_method=order: one task per order. Task lines = order lines × system-allocated locations (pick zone first; shortages create lines at the actually allocatable qty with the remainder in warnings).
• Path planning: each line gets a seq by location travel order, and the phone guides the worker location-by-location, qty-by-qty.
• Duplicate protection: an order with an unfinished pick task that still has pending lines cannot generate again; quantities left over as short may be re-generated later.
• After generation, the order’s pick task field is written back with a link to the task detail.

Executing on the phone#

One step = one product × one location. Each step submits four fields: pick-from location, pallet LPN (storage locations only), pick-to LPN (the target tote), picked QTY.

1. Scan/type the from location → Enter: invalid → top error + input fully selected; valid → a picking location jumps to to-LPN, a storage location first shows the pallet LPN box.
2. Scan/type the to LPN → validated (must be a tote assigned to the task) → move to Qty.
3. Enter Qty (digits only) → tap Pick to submit → next step. Failures keep you on the step with the error shown.
4. Partial pick: asked 10, picked 5 → records 5 picked and auto-adds a qty=5 step to the tail of the queue; you’ll come back to it.
5. Next: skip the current step; the queue comes back to it later.
6. Force close (top-right): close a partial pick directly; the system settles on the actually picked quantities.
7. Short: the location has no stock or the goods are damaged → mark short; the task can still complete and the remainder can be re-generated later.

Target totes and PICK-STAGE#

Order-pick target totes belong to the PICK-STAGE location (one per warehouse, location_type=staging; auto-created by the system if missing and hidden from the UI). Generate them in WMS → Pallets with the “Batch generate LPN” button: pick the warehouse (defaults to current) + count N (1–200, default 10). The backend generates LPN-{seq} (unified prefix; existing PLT- prefixes are untouched) with status=building and source_type=pick. Afterwards choose “Generate only” (close and refresh the list) or “Generate and print” (calls the label API per pallet through the print pipeline). Note: the picking cart (location_type=cart) is a movable location — a tote is an LPN (license_plate, tenant-globally unique) and tote picking books to the cart location_id the tote belongs to (the cart itself is the location). PICK-STAGE (staging) is the per-warehouse pick buffer; order-pick target pallets must belong to it — don’t mix the two.

Task states and review#

pending → in_progress (tap Start, or automatically on the first pick; the outbound shipment syncs to picking) → completed (all lines picked or short; the shipment moves to picked). On completion the picked_qty is written back to the shipment lines and a replenishment check is triggered. Review: the desktop task detail page shows everything the phone submitted (from location / pallet LPN / to LPN / picked qty / every step record) — this is where you verify a pick; pack-level verification continues at the shipping station (pack-verify).