# ENG-2774 — Plano de implementação

## Objetivo

Entregar a geração/reconciliação automática de transferências para a Expedição, validar a associação de endereços com a Rex, executar QA sem regressões no Almoxarifado, implantar com ativação controlada e atualizar a documentação de usuário (ENG-2781).

- **Branch:** `feature/eng-2774`
- **Design aprovado:** `docs/plans/2026-10-23-eng-2774-transferencias-empilhadeiras-design.md`
- **Status:** backend, comando, gatilhos e testes de feature estão implementados; a execução dos testes foi bloqueada pelo `TestingDatabaseGuard` (identidade/porta do PostgreSQL não confirmada), sem migration destrutiva executada. Ativação continua desabilitada por padrão, e revisão/aceite dos endereços pela Rex permanece pendente.
**Prazo informado:** 25/10/2026. Na data deste plano (23/10/2026), restam dois dias corridos; confirmar disponibilidade da Rex para a revisão obrigatória antes de prometer ativação em produção.

## 1. Revisar e corrigir os endereços — M02.1

Esta etapa operacional precede qualquer ativação. A tela existente de ordenação de endereços por equipe (`rex-front/src/pages/Teams/components/OrderAddress`) já permite ajustar as associações; não se prevê criar uma classificação alto/baixo no cadastro do endereço.

- [ ] Extrair a lista de endereços físicos ativos do setor Expedição, incluindo ID, nome, setor, categoria, equipes/grupos associados e saldo atual.
- [ ] Fazer a revisão com a Rex para classificar cada endereço como prateleira baixa ou alta.
- [ ] Pela tela existente, deixar somente endereços baixos nas equipes de separação e somente endereços altos na equipe chamada **Empilhadeira**.
- [ ] Configurar `REX_EXPEDITION_FORKLIFT_TEAM_ID` para o ID da equipe Empilhadeira em cada ambiente; confirmar que a equipe pertence à Expedição e que seus endereços associados são de fato altos.
- [ ] Identificar endereços sem classificação, associações conflitantes/duplicadas e endereços que não sejam físicos; corrigir ou manter a automação desabilitada.
- [ ] Registrar o aceite da Rex e validar a configuração em produção/homologação antes de habilitar a automação.

**Gate:** não ativar se a equipe Empilhadeira ou as listas baixa/alta forem ambíguas. Almoxarifado não participa dessa revisão nem tem suas associações alteradas por esta entrega.

## 2. Preparar configuração e identificação de origem automática

- [x] Adicionar um campo explícito de origem/automação em `transfer_tasks`, com valor padrão manual e valor próprio para reposição da separação da Expedição. Não inferir automação pelo `created_by` nem pelo texto de `observation`.
- [x] Criar migration reversível e compatível com tarefas existentes; registros antigos permanecem manuais. Adicionar índices somente para filtros de origem/status/equipe demonstrados pelas consultas.
- [x] Adicionar configuração de ativação desabilitada por padrão e documentar a variável correspondente em `.env.example`, seguindo as regras de configuração do repositório.
- [x] Implementar validação da equipe Empilhadeira pelo ID configurado e setor Expedição, falhando de forma segura se o ID estiver ausente, inválido ou apontar para outro setor.
- [x] Usar `AppHelper::systemUser()` como criador para tarefas automáticas; preservar o metadado independente que identifica a automação.

## 3. Implementar consultas de necessidade e cobertura — M02.2

Criar consultas/serviços de domínio dedicados, sem alterar os cálculos globais de estoque reutilizados pelo Almoxarifado.

- [x] Calcular, por equipe de separação e produto, o restante de linhas de saída comuns da Expedição em tarefas `PENDING`, `STARTED` ou `PAUSED`, excluindo saídas de reclassificação que têm fluxo próprio.
- [x] Subtrair coletas já registradas por linha e cobrir compatibilidade necessária com registros legados de `picked_items` sem `picking_order_product_id`, apenas quando a associação histórica for inequívoca; ambiguidades suspendem a reposição daquele produto.
- [x] Calcular saldo físico do produto somente em endereços baixos configurados para aquela equipe, no setor Expedição.
- [x] Calcular cobertura de transferências abertas manuais e automáticas destinadas aos endereços baixos da equipe. Diferenciar quantidade entregue (já refletida no saldo), em trânsito e ainda não iniciada; só contar linhas com produto, quantidade e destino identificáveis.
- [x] Calcular disponibilidade nas origens altas da equipe Empilhadeira, respeitando reservas de transferências já em andamento.
- [x] Arredondar quantidades conforme precisão já utilizada pelo domínio e impedir valores negativos.
- [x] Expor diagnóstico para necessidade sem origem elegível, sem destino elegível, equipe ausente e associação de endereço inválida.

## 4. Implementar reconciliador idempotente — M02.3

- [x] Implementar reconciliação por equipe de separação + produto, dentro de transação e com serialização de concorrência para a mesma chave.
- [x] Criar tarefa automática somente para falta positiva e limitada ao saldo alto disponível; permitir transferência parcial e dividir entre origens quando necessário.
- [x] Definir origem alta e destino baixo elegíveis usando a ordenação já configurada por equipe e as permissões de armazenamento do endereço; persistir ambos nas sugestões da linha.
- [x] Atribuir cada tarefa à equipe dona do endereço alto de origem.
- [x] Manter as tarefas automáticas pendentes reconciliáveis e evitar duplicatas. Ao recalcular, ajustar uma sugestão ainda necessária e cancelar (`CANCELED`) a tarefa pendente/linha automática que se tornar desnecessária.
- [x] Agrupar linhas por equipe de origem conforme o design; em tarefa automática com múltiplos produtos, remover/ajustar só as linhas obsoletas e cancelar o cabeçalho quando não restar trabalho.
- [x] Nunca editar/cancelar tarefa manual. Tarefa automática já iniciada conta como cobertura, mas não é cancelada automaticamente.
- [x] Se não houver saldo alto, não criar tarefa inexequível; persistir log/diagnóstico e tentar novamente em reconciliação posterior.

## 5. Integrar disparos e proteção agendada

- [x] Disparar job após commit em mudanças relevantes de tarefas/linhas de separação, saldo de endereço, transferências e configuração de endereços.
- [x] Filtrar disparos para limitar o efeito à Expedição; não acoplar a lógica ao evento genérico `ServiceProcessed`.
- [x] Criar comando periódico de reconciliação como proteção para fluxos que não emitam disparos, com opção de prévia/`--dry-run` para QA.
- [x] Agendar o comando com proteção contra sobreposição e limitar o escopo por equipe/produto quando possível.
- [x] Garantir retry/log de falha sem bloquear a operação que alterou separação ou estoque.

## 6. Cobertura automatizada e QA

### Testes automatizados

- [ ] Testar a fórmula por equipe/produto: necessidade aberta, coletas parciais, estoque baixo suficiente/insuficiente e rounding.
- [ ] Testar exclusão de tarefas concluídas/canceladas e de separações fora da Expedição.
- [ ] Testar transferências manuais e automáticas pendentes/iniciadas, quantidade em trânsito e quantidade já entregue.
- [ ] Testar origem alta, destino baixo, equipe atribuída pela origem e quantidade limitada ao saldo alto disponível, incluindo várias origens e saldo parcial.
- [ ] Testar idempotência sob execuções repetidas e concorrentes.
- [ ] Testar cancelamento quando reposição manual/de outro fluxo elimina a falta, preservando tarefas manuais e tarefas automáticas iniciadas.
- [ ] Testar equipe ausente/duplicada, endereço não físico, conflito de equipe/setor e falta de origem/destino, garantindo falha segura.
- [ ] Adicionar teste de não regressão que reproduz dados equivalentes no setor Almoxarifado e confirma ausência de tarefa/alteração automática.
- [ ] Testar migration e rollback do campo de origem, com dados de tarefas manuais pré-existentes.

### QA operacional

- [ ] Executar prévia com dados representativos e comparar, com a Rex, demanda, saldo baixo, cobertura aberta, falta, origem, destino, equipe e quantidade sugerida.
- [ ] Validar os casos de reposição manual e por outro fluxo, incluindo a saída da tarefa automática desnecessária da fila pendente.
- [ ] Confirmar o comportamento para ausência de estoque alto e para insuficiência parcial de estoque alto.
- [ ] Repetir os cenários com setor Almoxarifado e comprovar não regressão.

## 7. Deploy, ativação e acompanhamento

- [ ] Executar Pest direcionado aos novos testes e aos módulos PickingOrder, TransferTask, Address e transferência de estoque; executar a suíte completa quando o ambiente permitir.
- [ ] Rodar Pint e `git diff --check` antes do commit de implementação.
- [ ] Implantar migration e código com automação desabilitada por padrão.
- [ ] Executar diagnóstico/prévia, corrigir configuração e obter aceite explícito da Rex sobre os endereços.
- [ ] Habilitar a automação após o gate operacional; monitorar primeira execução, tarefas criadas/canceladas e erros de mapeamento.
- [ ] Confirmar procedimento de rollback por desativação da configuração, sem desfazer histórico ou alterações de estoque.

## 8. Documentação DocX — ENG-2781

- [ ] Documentar no DocX a configuração manual de endereços baixos para separação e altos para Empilhadeira.
- [ ] Explicar a comparação entre separações abertas, saldo baixo e transferências já planejadas.
- [ ] Explicar origem alta, destino baixo, execução da transferência e cancelamento de tarefas automáticas pendentes que deixarem de ser necessárias.
- [ ] Revisar o conteúdo com a Rex após QA e alinhar a publicação à ativação da automação.

## Critérios finais de conclusão

- A automação opera exclusivamente na Expedição; o Almoxarifado permanece inalterado.
- Os endereços foram classificados manualmente na tela de equipes e validados pela Rex antes da ativação.
- A quantidade transferida considera necessidade restante, saldo baixo, transferências abertas e disponibilidade real em endereços altos.
- A geração é idempotente; tarefas manuais não são modificadas; tarefas automáticas pendentes desnecessárias saem da fila.
- QA, deploy controlado e atualização/revisão do DocX foram concluídos.