# ENG-3090 — Transferências da Expedição por peso

Issue: https://linear.app/soelx/issue/ENG-3090/m01-transferencias-para-empilhadeiras-por-peso-configurado

## Manual operacional — conteúdo para atualização do DocX

Este texto substitui as orientações de endereços altos/baixos da ENG-2781 para **novas separações de pré-faturas da Expedição**. O manual existente no DocX precisa receber esta atualização antes da ativação; este arquivo não comprova publicação no DocX.

### Configurar

Na consulta de Saídas da Expedição, o administrador acessa **Configurar Empilhadeira**. O limite inicial é **500 kg**, editável sem nova publicação. Somente um operador com perfil ativo Master ou Administrador da Expedição pode salvar. Alterar o limite não altera separações existentes nem decisões confirmadas.

O controle **Habilitar automação por peso** inicia marcado (`enabled=true`) e habilita somente o reconciliador novo por peso. A chave operacional do servidor `REX_EXPEDITION_REPLENISHMENT_ENABLED` continua sendo o bloqueio geral e permanece desligada por padrão; enquanto ela estiver desligada, o controle marcado não cria transferências automáticas. `REX_EXPEDITION_FORKLIFT_TEAM_ID` identifica a equipe que recebe as transferências automáticas. Os endereços físicos ativos na rota dessa equipe são usados para sugerir origens com estoque; o destino é escolhido durante a execução. O usuário de sistema é apenas o autor técnico (`created_by`) e não precisa pertencer à equipe. Não há nova exigência de classificar endereços como altos ou baixos. Não altere cadastros usados pelo fluxo legado sem revisão operacional própria.

### Preparar e confirmar a separação

Selecionar uma ou várias pré-faturas apenas abre a preparação; não gera transferências. Com **Habilitar automação por peso** marcado, cada linha usa seu **peso bruto total original**, vindo do `PESBRU` da linha, sem multiplicar pelo saldo e sem somar produtos ou pré-faturas; peso igual ou superior ao limite pré-marca **Empilhadeira**, e o operador pode ajustar manualmente. Com a opção desmarcada, a coluna **Empilhadeira** não aparece e as novas linhas são salvas com `forklift=false`.

Com **Habilitar automação por peso** marcado, antes de **Gerar Tarefa**, confira os itens selecionados e ajuste a caixa Empilhadeira de cada linha. É permitido marcar abaixo do limite ou desmarcar acima. Com a opção desmarcada, a coluna fica oculta e as novas linhas recebem `forklift=false`. Somente itens selecionados entram na separação. Ao salvar com sucesso, o servidor preserva o peso original e a decisão por linha; coletas parciais ou alterações posteriores do limite não reclassificam essa decisão. Abandonar a tela ou uma falha com rollback não confirma marcações nem gera transferências.

### Processar e executar

Após a confirmação transacional, o worker recebe a reconciliação. O Scheduler recupera pendências a cada cinco minutos. Uma tarefa automática por demanda pendente é criada para a equipe Empilhadeira, sem transferir a responsabilidade pela coleta da pré-fatura: ela continua com a equipe de separação.

A origem é apenas uma sugestão baseada em estoque físico removível da Expedição, descontando reservas. Estoque parcial não elimina a demanda restante. Sem estoque, a tarefa continua existindo, com aviso e **sem origem sugerida**. O operador pode usar outra origem válida e escolhe o destino durante a execução, pelas validações normais de movimentação. Não é necessário obedecer a uma relação alto/baixo.

### Vincular uma reposição manual

No aplicativo, o item da tarefa automática exibe **Demanda da Expedição #N**. Ao criar a reposição manual do mesmo produto, informe esse número no campo **Demanda da Expedição (opcional)** de cada produto. Confira produto, quantidade e vínculo antes de confirmar. O número identifica a **linha da tarefa de separação**, não o produto, a pré-fatura ou a tarefa de transferência.

Apenas operadores da Expedição pertencentes à equipe Empilhadeira configurada podem criar esse vínculo. O servidor valida o mesmo produto e uma quantidade positiva. Uma reposição sem vínculo explícito não abate a nova demanda, mesmo que use os mesmos endereços. O vínculo confirmado não pode ser trocado; tarefas vinculadas já iniciadas não podem ser editadas por esse fluxo.

Reposições vinculadas reduzem a transferência automática ainda pendente ou a cancelam quando cobrem toda a demanda. Reposições manuais e transferências automáticas iniciadas são preservadas. Quantidades entregues por transferência e depois coletadas para a mesma demanda não são subtraídas duas vezes. Cancelamentos preservam o histórico; cancelar uma nova separação mantém suas linhas e decisões, cancelando apenas o trabalho automático ainda pendente na reconciliação.

## Contratos e compatibilidade

- Migration aditiva: limite e habilitação persistidos, peso original em `stock_io_products` e `picking_order_products`, decisão `forklift` anulável e vínculo `transfer_task_products.picking_order_product_id` anulável. Não há backfill nem reclassificação de registros antigos.
- GET/PUT `/api/v1/stock/expedition/transfer-settings`: `minimum_weight` numérico não negativo e `enabled` booleano opcional no PUT. Leitura autenticada na Expedição; escrita limitada ao perfil administrativo ativo.
- Os três contratos de criação de separação aceitam `stock_io_products[].forklift` booleano opcional. Para novas linhas de pré-fatura da Expedição, o servidor aplica o limite ao peso original apenas se `enabled=true`; com `enabled=false`, persiste `forklift=false`, mesmo se o cliente enviar `true` ou omitir o campo. Campos de peso enviados pelo cliente não são usados.
- A criação de transferência manual aceita `transfer_task_products[].picking_order_product_id`. O retorno de cada item de transferência e dos produtos da separação inclui o vínculo necessário para rastrear a demanda.
- `forklift = null` identifica linhas legadas: continuam no reconciliador anterior. `false` é uma decisão confirmada, não autorização para o fluxo legado. `true` participa do novo reconciliador, com origem `expedition_weight`.
- Automação desabilitada não apaga tarefas nem histórico. Mantenha os três componentes atualizados antes de habilitar: clientes antigos não conhecem o novo campo de marcação.

## QA e ativação — executar somente em ambiente isolado

1. Aplicar migrations compatíveis e publicar backend, web e aplicativo, mantendo `REX_EXPEDITION_REPLENISHMENT_ENABLED=false`. O controle por peso inicia marcado, mas a chave global mantém todo processamento automático bloqueado. Verificar equipe e rota de origem, usuário de sistema, fila assíncrona e worker. Não usar conexão de fila `sync` na operação.
2. Testar pesos 499, 500 e 501 kg, limite alterado, peso desconhecido, permissões e tentativas de escrita por outro perfil/setor. Testar linhas do mesmo produto e de pré-faturas distintas sem agregação de peso.
3. Testar com `enabled=true` as marcações contrárias ao padrão, seleção parcial e lote agrupado/não agrupado; com `enabled=false`, confirmar que a coluna fica oculta e novas linhas recebem `forklift=false`. Conferir peso original e decisão após coleta parcial. Confirmar que carregar candidatos, abandonar ou reverter uma transação não gera tarefas.
4. Confirmar recuperação pelo worker e pelo comando agendado, repetindo a reconciliação e concorrendo solicitações para verificar ausência de duplicidades. Exercitar estoque suficiente, parcial e inexistente; usar origem e destino válidos diferentes da sugestão.
5. Vincular reposições manuais parciais e totais, rejeitar produto diferente e vínculo inválido, conferir reposição sem vínculo e coleta após entrega. Preservar manuais e automáticas iniciadas. Cancelar uma nova separação e verificar histórico.
6. Conferir regressão de separações antigas, Almoxarifado e reclassificação. Atualizar o manual do DocX referente à ENG-2781 com o conteúdo operacional desta seção.
7. Obter aceite formal de **Edson Peixer e Davi Lemes** antes de ativar. Esta implementação e seus testes automatizados não substituem esse aceite nem o QA operacional.
8. Com as tarefas reais ainda bloqueadas, executar a prévia `php artisan transfer-task:reconcile-expedition-replenishment --dry-run`. Opcionalmente filtrar `--team-id=ID`. A prévia não persiste alterações e considera também o fluxo legado ainda ativo.
9. Após revisão da prévia, habilitar a chave operacional do servidor e a configuração administrativa por peso, conferir o Scheduler a cada cinco minutos e monitorar os diagnósticos e a ausência de duplicidades.

## Reversão operacional

Desmarcar **Habilitar automação por peso** para suspender somente as transferências por peso; para suspender todo o processamento automático, desabilitar também `REX_EXPEDITION_REPLENISHMENT_ENABLED` e atualizar a configuração dos workers/Scheduler pelo procedimento operacional existente. Não apagar registros, não desfazer decisões e não remover migrations com histórico vinculado. Revisar operacionalmente as tarefas já iniciadas e as pendentes antes de retomá-las.

Não há merge, deploy ou ativação automática nesta entrega. Publicação no DocX, QA operacional isolado, aceite e ativação continuam sendo etapas explícitas de liberação.
