Picking: ondas, tarefas e PICK-STAGE

Libere ondas (manual ou agendada), gere tarefas por pedido e execute passo a passo no celular, com picks parciais, pulos e shorts.

Liberação de ondas#

Uma onda agrupa remessas de saída por merchant × filtro, divide por quantidade de pedidos e as libera como onda; cada remessa recebe depois sua tarefa de picking. Duas entradas: liberação manual (wave/manual) e agendada (scheduler + cron externo). Só remessas com status commit/draft/ready; as bloqueadas por uma onda inacabada são excluídas.

• Wave Filter: conditions [{field, operator, values[]}], operadores in/not_in/eq/ne/gt/lt/gte/lte (wave/filter).
• Dispatch Setting: customer_filters [{merchant_id, filter_id}], max/min por plano, default_pick_method (order/batch/wave/wave_by_item, padrão order), is_active (wave/settings).
• Scheduler: work_days (1=segunda…7=domingo, padrão 1–5), time_from/time_to, step_minutes, is_active (wave/scheduler).
• Horários de corte: por merchant/transportadora, HH:MM (wave/cutoff-time).

1. Escolha Cliente (merchant, obrigatório) + 1 ou mais Dispatch Settings → Prévia: retorna a contagem por setting e o detalhe por grupo sem criar a onda.
2. Opcionalmente ajuste min/max_qty_per_batch (valida Min ≤ Max).
3. Liberar: cria a onda — wave_no = WV-YYYYMMDD-NNNN, status=released (a onda nasce liberada; sem estado draft intermediário), shipment_ids guarda as remessas.
4. Após liberar, a página lista as remessas da onda: Create Pick Task por remessa (ver abaixo).
5. Liberação agendada: um cron externo faz POST em /api/wms/wave/scheduler/run a cada N minutos (com x-cron-secret). Só executa schedulers cujo dia esteja em work_days, hora atual em time_from~time_to e última execução ≥ step_minutes atrás.

Gerar tarefas de picking#

• Três entradas: a página da onda liberada, seleção em massa na lista de pedidos → Create Pick Task, ou Create Pick Task no detalhe do pedido.
• pick_method=order: uma tarefa por pedido. Linhas = linhas do pedido × endereços alocados pelo sistema (zona pick primeiro; faltas criam linhas com a quantidade alocável e o restante em warnings).
• Planejamento de rota: cada linha recebe um seq pela ordem de percurso; o celular guia endereço por endereço.
• Proteção contra duplicatas: um pedido com tarefa inacabada que ainda tenha linhas pending não pode gerar de novo; o restante como short pode ser regenerado depois.
• Após gerar, o campo de tarefa é gravado no pedido com link para o detalhe.

Execução no celular#

Uma etapa = um produto × um endereço. Cada etapa envia quatro campos: endereço de origem, LPN do palete (só endereços storage), LPN de destino (o tote alvo), quantidade.

1. Leia/digite o endereço de origem → Enter: inválido → erro no topo + entrada selecionada; válido → um endereço picking pula para o to-LPN, um storage mostra primeiro o LPN do palete.
2. Leia/digite o to LPN → validado (deve ser um tote da tarefa) → ir para quantidade.
3. Informe a quantidade (só dígitos) → toque Pick para enviar → próxima etapa; se falhar, permanece na etapa com o erro.
4. Pick parcial: pediu 10, coletou 5 → registra 5 e adiciona automaticamente uma etapa de 5 ao fim da fila.
5. Next: pula a etapa atual; a fila voltará a ela depois.
6. Force close (canto superior direito): fecha um pick parcial diretamente; o sistema liquida com o realmente coletado.
7. Short: o endereço não tem estoque ou a mercadoria está avariada → marcar short; a tarefa pode terminar e o restante ser regenerado depois.

Totes de destino e PICK-STAGE#

Os totes de destino do picking pertencem ao endereço PICK-STAGE (um por armazém, location_type=staging; o sistema cria se faltar e fica oculto na UI). Gere-os em WMS → Pallets com “Batch generate LPN”: escolha o armazém (padrão: atual) + quantidade N (1–200, padrão 10). O backend gera LPN-{seq} (prefixo unificado; os PLT- existentes não mudam) com status=building e source_type=pick. Depois escolha “Generate only” ou “Generate and print”. Nota: o picking cart (location_type=cart) é um endereço móvel; um tote é um LPN (license_plate único por tenant) e o picking de totes lança no location_id do carrinho ao qual o tote pertence. PICK-STAGE (staging) é o buffer por armazém; os paletes de destino devem pertencer a ele.

Status da tarefa e revisão#

pending → in_progress (toque Iniciar, ou automático no primeiro pick; a remessa vai para picking) → completed (todas as linhas picked ou short; a remessa vai para picked). Ao concluir, picked_qty é gravado nas linhas e uma verificação de reposição é disparada. Revisão: o detalhe da tarefa no desktop mostra tudo o que o celular enviou (endereço de origem / LPN do palete / to LPN / quantidade / cada registro): aqui se verifica o picking; a verificação de embalagem continua na estação de envio (pack-verify).