# ENG-2774 — Geração de tarefas de transferência para empilhadeiras

## Contexto

A automação deve manter o abastecimento das prateleiras baixas da Expedição alinhado às separações abertas. Quando o saldo baixo e as transferências já planejadas não cobrirem a necessidade, o sistema deve sugerir uma transferência de estoque disponível em endereço alto para um endereço baixo.

O backend já possui tarefas de separação (`picking_orders` e `picking_order_products`), tarefas de transferência (`transfer_tasks` e `transfer_task_products`) e ordenação de endereços por equipe (`address_order_groupers` e `address_orders`). Hoje, porém, não existe um atributo que classifique fisicamente um endereço como alto ou baixo; a vinculação do endereço à equipe será a classificação operacional usada pela automação.

## Escopo e limites

- Incluir somente separações e endereços do setor **Expedição** (`SectorEnum::EXPEDITION`).
- Não alterar nem impactar a separação, estoque ou automações do setor **Almoxarifado** (`SectorEnum::WAREHOUSE`).
- A tarefa de transferência será atribuída à equipe dona do endereço alto selecionado como origem. A equipe **Empilhadeira** existente é a equipe operacional esperada para essas origens.
- A configuração dos endereços será revisada com a Rex antes de habilitar a automação.
- A documentação operacional do DocX pertence também à sub-issue ENG-2781 e deve refletir o comportamento validado.

## Glossário operacional

- **Equipe de separação**: equipe da Expedição associada à tarefa de saída; seus endereços configurados representam prateleiras baixas.
- **Equipe Empilhadeira**: equipe da Expedição dona dos endereços configurados como prateleiras altas e responsável pelas tarefas de transferência originadas neles.
- **Necessidade aberta**: quantidade ainda não coletada em linhas de tarefas de separação ativas.
- **Cobertura de transferência**: quantidade de uma transferência aberta ainda esperada no endereço baixo; não inclui quantidades já entregues, pois estas já aparecem no saldo físico.
- **Tarefa automática**: transferência criada e gerenciada pela automação, distinguida de tarefas manuais por metadado explícito, nunca somente pelo usuário criador ou pela observação.

## Configuração operacional dos endereços (M02.1)

A classificação é **manual**, feita no cadastro/ordenação de endereços existente por equipe, não inferida pelo nome do endereço e sem novo campo alto/baixo no banco. A equipe Empilhadeira é identificada por `REX_EXPEDITION_FORKLIFT_TEAM_ID`, configurado por ambiente; o ID precisa apontar para uma equipe do setor Expedição. Não há fallback por nome, pois IDs podem variar entre bases locais, homologação e produção.

1. Levantar as associações atuais de endereços físicos às equipes da Expedição.
2. Revisar com a Rex quais endereços são prateleiras baixas e quais são prateleiras altas.
3. Ajustar as listas de endereços para que cada equipe de separação tenha somente endereços baixos e a equipe Empilhadeira somente endereços altos.
4. Verificar setor, categoria física, endereços sem equipe, associações duplicadas/conflitantes e confirmar que o ID configurado para Empilhadeira pertence a uma equipe da Expedição com endereços altos.
5. Obter aceite da Rex antes de habilitar a automação.

Se a classificação ou a equipe de origem não for inequívoca, a automação falha de forma segura: não cria transferência e registra a inconsistência para diagnóstico. A configuração validada é pré-requisito de ativação; não é executada por migration nem por heurística de nome de endereço.

## Regra de necessidade e cobertura (M02.2)

A necessidade é calculada por **equipe de separação + produto**, considerando linhas de tarefas de saída da Expedição cujas tarefas e linhas estejam em `PENDING`, `STARTED` ou `PAUSED`. Para cada linha, usa-se `max(amount - quantidade já coletada, 0)`. Linhas concluídas/canceladas, produtos cancelados, saídas de reclassificação (que têm fluxo de demanda próprio) e operações de outros setores ficam fora do cálculo. Coletas legadas sem vínculo à linha só são atribuídas quando existe uma única linha histórica para o produto da saída; se houver ambiguidade, a reposição automática daquele produto é suspensa e diagnosticada, sem inferir a tarefa responsável.

O saldo baixo é a soma do estoque físico (`items.amount`) do produto nos endereços baixos configurados para a equipe de separação correspondente. Estoque em endereço baixo de outra equipe não é considerado disponível para essa necessidade.

As transferências abertas para o mesmo produto e para endereços baixos daquela equipe também entram como cobertura, sejam manuais ou automáticas. Só se atribui cobertura a uma transferência com quantidade e destino que permitam identificar o produto e a equipe beneficiária. Tarefas manuais podem reduzir a necessidade, mas nunca são alteradas pela automação.

```text
falta = max(necessidade aberta - saldo físico baixo - cobertura de transferências abertas, 0)
```

Quantidades entregues ao endereço baixo são contabilizadas no saldo físico, não novamente como cobertura. Quantidades ainda em trânsito e a parcela não iniciada de uma transferência aberta permanecem como cobertura, de modo a evitar tarefas duplicadas.

## Geração e reconciliação (M02.3)

Quando houver falta positiva, a transferência sugerida não excede o saldo efetivamente disponível em endereços altos da equipe Empilhadeira. Se o saldo alto cobrir apenas parte da falta, gera-se uma transferência parcial; se não houver saldo alto elegível, não se cria uma tarefa inexequível e a insuficiência fica disponível para diagnóstico e reconciliações futuras.

Cada linha gerada recebe produto, quantidade sugerida, endereço alto de origem e endereço baixo de destino. Se houver mais de uma origem, a quantidade poderá ser dividida; cada tarefa ficará com a equipe dona de sua origem. A reconciliação mantém idempotência por equipe de separação e produto, contabiliza transferências já abertas e não duplica sugestões.

As tarefas automáticas terão um identificador explícito de origem/automação. Quando reposição manual ou outro fluxo tornar uma transferência automática pendente desnecessária, ela será retirada da fila por cancelamento (`CANCELED`), preservando rastreabilidade. Se uma tarefa automática agrupar produtos, somente a linha obsoleta será removida/ajustada; o cabeçalho será cancelado quando não restar trabalho. Tarefas automáticas já iniciadas não serão canceladas automaticamente. Tarefas manuais nunca serão canceladas, editadas ou removidas pela reconciliação.

## Arquitetura, consistência e falhas

Adotar reconciliação híbrida:

- solicitar um job de reconciliação após commit nos fluxos relevantes de separação, movimentação de estoque e transferência;
- executar comando agendado periódico como proteção para alterações vindas de outros fluxos;
- tornar a operação idempotente e serializar reconciliações concorrentes da mesma equipe/produto;
- usar o usuário de sistema como criador, além do metadado que identifica a origem automática;
- registrar mapeamentos inválidos, falta sem origem elegível, falhas e tentativas, sem bloquear a operação que gerou o evento.

A automação deve ser habilitada por configuração controlada, somente depois da revisão de endereços e aceite da Rex. Na primeira ativação, um modo de prévia/diagnóstico deve permitir conferir as equipes, endereços, faltas e sugestões antes de expor tarefas aos operadores.

## QA e critérios de aceite

Cobrir, com testes unitários e Pest de feature:

- cálculo agrupado por equipe/produto e exclusão de tarefas/linhas concluídas, canceladas e de outros setores;
- desconto de quantidades já coletadas, saldo baixo e transferências abertas manuais/automáticas;
- saldo suficiente, insuficiente e inexistente em endereços altos, incluindo geração parcial;
- endereço de origem alto, destino baixo e equipe de transferência igual à equipe dona da origem;
- idempotência, concorrência e ausência de tarefas duplicadas;
- cancelamento de transferência automática pendente que se tornou desnecessária;
- preservação de tarefas manuais e tarefas automáticas iniciadas;
- equipe/endereço ausente, setor incorreto, classificação conflitante e falha segura;
- não regressão explícita para Almoxarifado.

Antes do deploy operacional, a Rex deve validar as associações de endereço por equipe. O deploy deve permitir ativar/desativar a automação sem rollback de dados, monitorar a primeira execução e atualizar o DocX com o fluxo entregue.

## Prazo e risco

O prazo informado no issue é 25/10/2026. Na data deste documento (23/10/2026), restam dois dias corridos; desenvolver, executar QA, implantar e obter a validação operacional nesse intervalo é um risco de cronograma. A ativação não deve contornar a revisão dos endereços para atender à data.