# ENG-1439 — Plano de implementação

## Objetivo

Impedir que novas tarefas iniciadas ou pausadas permaneçam sem `shipping_packaging_id`, preservando registros legados e mantendo um caminho de recuperação para tarefas pausadas.

## Sequência de execução

### 1. Mapear os pontos de mutação

- Revisar `PickingOrderStartService` legado e V2.
- Revisar `PickingOrderPauseService`, `PickingOrderReturnPendingService` e `PickingOrderChangeShippingPackagingService`.
- Revisar `ShippingPackagingDeleteService` e `ShippingPackagingTotalTransferService`.
- Revisar jobs, integrações e comandos que atualizem `picking_orders` diretamente.
- Confirmar que a troca de embalagem salva a associação antes de reiniciar a tarefa.

### 2. Criar a regra compartilhada

- Centralizar a verificação de que `STARTED` e `PAUSED` exigem embalagem.
- Reutilizar a regra nos services e nos testes.
- Manter a regra específica da V2: tarefas fora da expedição podem iniciar sem embalagem.

### 3. Proteger sem alterar os dados existentes

- Criar consulta de diagnóstico para tarefas `STARTED`/`PAUSED` sem embalagem.
- Adicionar a constraint como `NOT VALID`, sem backfill e sem mudança de status durante a migration.
- Garantir que a constraint seja aplicada a novos inserts e updates.
- Planejar `VALIDATE CONSTRAINT` somente após a correção operacional dos registros legados.

### 4. Adicionar constraint PostgreSQL

- Criar migration com constraint em `picking_orders`:
  - `status = STARTED` exige embalagem;
  - `status = PAUSED` exige embalagem;
  - demais estados continuam aceitando `NULL`.
- Garantir rollback da constraint.
- Validar que updates diretos inválidos falham sem deixar alterações parciais.

### 5. Ajustar recuperação e fluxos relacionados

- Garantir que a troca de embalagem em tarefa pausada persista `shipping_packaging_id`.
- Impedir exclusão/transferência que deixe tarefa iniciada ou pausada sem embalagem.
- Preservar transações e mensagens funcionais existentes.

### 6. Cobertura de testes Pest

- Constraint para `STARTED`, `PAUSED` e `PENDING`.
- Correção operacional de registros inválidos.
- Troca de embalagem em tarefa pausada.
- Reinício depois da troca.
- Transferência e exclusão de embalagem.
- Rotas legada e V2, incluindo vínculos direto e indireto com expedição.
- Ausência de efeitos colaterais em falhas.

### 7. Validação final

- Executar testes direcionados do módulo PickingOrder e ShippingPackaging.
- Executar análise estática aplicável.
- Executar a suíte completa Pest do backend, se o ambiente permitir.
- Verificar `git diff --check`, migration reversível e payloads dos resources.

## Critérios de conclusão

- Nenhuma nova tarefa `STARTED` ou `PAUSED` pode ser persistida sem embalagem.
- A constraint protege alterações fora dos services.
- Uma tarefa pausada sem embalagem pode ser recuperada por troca de embalagem.
- As rotas existentes mantêm seus comportamentos funcionais e testes aprovados.