# ENG-3114 — Plano de implementação do início e bloqueio WMS

**Status:** implementação autorizada e realizada em 2026-11-06, nas branches feature/eng-3114, disponível para revisão. [Resultados, regressões legadas e limites](../testing/eng-3114-inicio-bloqueio.md). O roteiro abaixo preserva o plano aprovado.
**Desenho aprovado:** [Início do inventário e bloqueio de movimentações WMS](2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-design.md), commit `c5199dc2`.
**Pré-requisito:** implementação da ENG-3113, conforme seu [desenho](2026-11-05-eng-3113-inventario-manual-design.md) e [plano](2026-11-05-eng-3113-inventario-manual-implementation-plan.md).

## Resultado esperado

Iniciar um rascunho compartilhado, congelar os produtos/endereços abrangidos e bloquear no backend todas as movimentações desses produtos no depósito configurado. Para esta instância, Expedição corresponde a **004**. Produtos fora da abrangência continuam movimentáveis.

A flag **Bloquear movimentações WMS** desaparece do fluxo real e não integra a escrita da API: todo início ativa o bloqueio. Não criar outra configuração equivalente.

Não implementar cadastro novamente, distribuição, rodadas, contagens, resultados ou encerramento operacional. A ENG-3118 utilizará o contrato interno de liberação terminal preparado aqui. Nenhum início, bloqueio ou liberação consulta saldos ou envia ajustes ao ERP.

## Estado e cuidados antes da execução

- [x] Desenho aprovado por seções e versionado.
- [x] Worktree de documentação `rex-back-eng-3114`, branch `feature/eng-3114`, criada de `bbb18508` sem trocar branches da sessão da ENG-3113.
- [x] Receber autorização posterior para implementar.
- [x] Incorporar a implementação aprovada da ENG-3113: backend da900b92 e frontend 753c7497.
- [x] Preparar as duas branches `feature/eng-3114` sobre a entrega correspondente da ENG-3113.

Revalidar working trees e commits antes de começar. Não resetar alterações de outra sessão nem presumir que a `main` do frontend contém o cadastro aprovado. Nomes novos deste plano podem ser ajustados à implementação da dependência sem alterar o contrato ou duplicar serviços.

Seguir `rex-back/AGENTS.md` e `docs/testing-database.md`. O projeto exige PHP `^8.4`; o CLI padrão inspecionado é PHP 8.2. Usar o runtime compatível já previsto pelo projeto/ambiente antes de rodar Artisan ou a aplicação, sem atualizar dependências nesta issue.

```bash
cd rex-back
# Somente se a instância descartável ainda precisar ser iniciada:
docker compose --profile test up -d postgres-test
php artisan --env=testing test:database-safety
```

Não executar migrations ou `migrate:fresh` no banco oficial. Não executar suítes que recriem o mesmo schema simultaneamente em duas sessões. Os comandos deste plano são para execução futura, no runtime e na instância de testes corretos.

## Contrato proposto da API

### Início

`POST /api/v1/inventory/{inventory}/start`, corpo contendo somente `version`, inteiro válido da versão lida.

- Autenticação e autorização explícita de Admin/Master com sessão ativa na Expedição, inclusive quando existir bypass global de Master nas Policies.
- Servidor resolve seleção, setor, depósito, abrangência e autoria. Proibir campos de substituição como `product_ids`, `addresses`, `sector`, `depot_code`, `status`, `blockMovements` e `block_movements`.
- Sucesso: `200` com o detalhe persistido atualizado, situação iniciada, versão, autoria/horário do início e abrangência congelada. Não retornar rodadas ou tarefas fictícias.
- `401/403/404`: convenções de sessão/acesso/contexto da ENG-3113.
- `422`: corpo inválido ou seleção que perdeu elegibilidade, identificando necessidade de revisão sem descartar produtos silenciosamente.
- `409`: versão/situação incompatível, sobreposição com inventário ativo ou coleta de transferência pendente; usar códigos distinguíveis e informações locais suficientes para resolver o conflito.

Proposta de repetição sem chave adicional: persistir `started_from_version`. Sob lock do cabeçalho, uma repetição dessa mesma versão de origem em inventário já iniciado e ainda não terminal retorna seu estado atual, sem reaplicar início. Outra versão não contorna conflitos; encerrado não pode ser reiniciado. Registrar autor original do início, não quem repetiu o comando.

### Recusa de movimentação

Manter as rotas WMS existentes. Acrescentar `409` legível com `code: product_in_active_inventory`, mensagem e lista dos vínculos bloqueadores, respeitando o envelope e a sanitização existentes. Conferir a compatibilidade dos consumidores atuais; não supor que tratam somente `422`.

`GET /inventory/{inventory}` passa a apresentar a fotografia quando iniciado, não a resolver novamente a abrangência pelo cadastro vivo. A listagem básica precisa preservar acesso aos registros iniciados, sem implementar filtros gerenciais da ENG-3115.

## Protocolo técnico a preservar

1. Bloqueio persistido por produto + identidade local do depósito, obtida do contexto da ENG-3113; nenhuma dimensão enviada pelo cliente substitui essa identidade.
2. Advisory lock PostgreSQL transacional exclusivo no início/liberação; compartilhado na movimentação/coleta. Usar a mesma função de derivação de chave, com namespace próprio, e ordenar/deduplicar as chaves efetivas.
3. Movimentações em lote resolvem e protegem previamente todos os produtos/contextos afetados. Nas transferências, incluir origem e destino; na substituição de produto/detentor, incluir as identidades anterior e posterior.
4. Adquirir esses locks antes das leituras decisivas de saldo/trânsito e dos locks operacionais dos caminhos tocados. Reler objetos carregados antes da trava, sem confiar em instâncias Eloquent desatualizadas.
5. Preservar os locks de saldo/tarefa existentes: advisory de inventário não substitui consistência de disponibilidade nem autorização geral.
6. O guard não pode funcionar como simples `exists` fora de uma transação. Exceções de bloqueio abortam a operação inteira, sem captura por linha que permita continuação parcial.
7. Auditoria é persistida depois do rollback externo, não depois de um savepoint. A mesma identificação percorre chamadas internas; HTTP, domínio, jobs e comandos devem ter fronteira externa identificada.
8. Nenhum caminho pode emitir integração/ajuste para contornar o bloqueio. Efeitos de sucesso dos fluxos alterados só podem sobreviver após commit externo.

## Roteiro por tarefa

Em cada tarefa futura: escrever o teste focal → comprovar a falha esperada → implementar o mínimo → comprovar sucesso → revisar diff → commit pequeno com prefixo `ENG-3114`. Rodar Pint antes dos commits backend. Não executar essas tarefas durante o planejamento.

### 1. Reconciliar a dependência e fechar a matriz de escritores

**Depende de:** autorização e entrega efetiva da ENG-3113.

**Ler/reconciliar:** contexto, middleware/Policy, Models, `InventoryScopeService`, Resources, Requests, migrations, testes e serviço frontend da ENG-3113.

**Novo artefato de execução:** `docs/validation/eng-3114/movement-paths.md`.

1. Confirmar `004` como configuração da instância, string sem fallback hardcoded, e a identidade usada pelo contexto. Não consultar o ERP.
2. Para cada linha da matriz abaixo, registrar rota/job/comando → serviço de entrada → escrita efetiva → dono da transação externa → ordem de locks → fronteira de auditoria → teste comportamental.
3. Rastrear criação, atualização e remoção direta de `Item`, reatribuição de produto/detentor e alterações de contexto que deslocam saldo, além de incrementos/decrementos. Examinar chamadas herdadas de `TransferableTransferPickedItemService`.
4. Distinguir quantidade física/operacional de simples quantidade planejada de demanda/tarefa. Não bloquear indiscriminadamente todo campo chamado `amount`; justificar caminhos sem efeito de movimentação e provar que sua coleta continua protegida.
5. Confirmar que todo processo automático que aplica quantidades locais passa por um caminho protegido. Ler os escritores concretos e seus chamadores; uma busca textual é apoio, não prova de cobertura.
6. Inspecionar coletores e cancelamentos reais. Na base atual, `TransferTaskCancelService` só muda o cabeçalho. Não tratar isso como cancelamento da coleta nem ignorar `TRANSFERRING` por causa da situação da tarefa.

**Saída:** matriz completa, sem escritor não classificado. Não encerrar a implementação com linhas importantes marcadas apenas como “a verificar”.

### Matriz inicial de caminhos a rastrear

Todos os caminhos abaixo são relativos a `rex-back`; reconciliar com a entrega efetiva antes de editar.

| Grupo | Arquivos/pontos identificados | Comprovação necessária |
| --- | --- | --- |
| Transferência e ajuste genérico | `Domain/Transferable/Services/TransferableTransferItemService.php`, subclasse `TransferableTransferPickedItemService.php`; métodos `transferMany`, `transferOne`, `transactionOne`, `transferItemToRecipient` | Verificar cada entrada pública, inclusive métodos chamados diretamente; origem/destino e lotes atômicos. |
| Escrita direta de itens | `Domain/Item/Services/ItemStoreService.php`, `ItemUpdateService.php`, `ItemDeleteService.php`, `GenerateItemService.php`, `ItemTransferService.php` | Criação, alteração, remoção e substituição de identidade/detentor, mesmo sem passar pelo serviço genérico. |
| Ajustes | `Domain/Item/Services/ItemAdjustmentService.php`; `Domain/StockAdjustment/Services/StockAdjustmentService.php` | Aumento/redução/exclusão, criação de item inexistente, lote misto e preservação das regras de OP 0. |
| Sincronização/aplicação local | `Domain/Item/Services/SyncItemsService.php`, `ProductsItemsHandler.php`, `StorageItemsHandler.php`; serviços de integração de `Domain/StockIO/Services/` | Aplicação de quantidades locais não escapa pelo importador; distinguir produtos de materiais fora do recorte e não ampliar a integração. |
| Separação | `Domain/PickingOrder/Services/PickItemFromAddressService.php`, serviços de `PickedItem`; `Domain/Request/Services/RequestSeparationService.php` | Tarefa antiga ou nova não coleta produto protegido; nenhum progresso/embalagem/log de sucesso sobrevive à recusa. |
| Trânsito de transferência | `Domain/TransferTask/Services/TransferTaskPullProductService.php`, `TransferTaskPushProductService.php`, `TransferTaskPickProductService.php`, `PickedTransferTaskProductStoreService.php`, `TransferTaskCancelService.php` | Coleta/reserva, endereçamento e transferência direta aderem à mesma trava; cabeçalho cancelado não esconde coleta aberta. |
| Embalagem | `Domain/ShippingPackaging/Services/ShippingPackagingQuantityService.php`, `ShippingPackagingRemoveProductService.php` e chamadores de transferências parcial/total | Proteger soma, remoção e transferências de quantidade mesmo quando `items.amount` não muda. Resolver produto por vínculos locais, inclusive fallback por `StockIOProduct`. |
| Saída, entrega, devolução e estorno | `Domain/Request/Services/RequestDeliveryService.php`, `RequestDevolutionService.php`; cancelamentos de separação e finalizações em `Domain/PickingOrder/Services/` e `Domain/StockIO/Services/` | Classificar efeito real e setor. Proteger mutações quantitativas; fluxos exclusivamente do Almoxarifado permanecem funcionais. |
| Cadastros com efeito sobre saldo/contexto | `Domain/Address/Services/AddressUpdateService.php`, `AddressDeleteService.php`, serviços de produto e escritas diretas de item | Impedir que mudança de setor, detentor ou remoção de saldo contorne a proteção. Não refatorar renomeações/cadastros sem efeito nesse risco. |
| Adaptadores | `app/Http/Controllers/Item/ItemController.php`, `Stock/StockController.php`, controllers de transferência/embalagem; jobs e comandos chamadores | Confirmar fronteiras reais e compatibilidade de erros. Middleware HTTP sozinho não certifica o domínio. |

### 2. Persistência do início, fotografia e bloqueios

**Depende de:** 1 e schema efetivo da ENG-3113.

**Novos propostos:**
- `database/migrations/<timestamp>_add_inventory_start_scope_and_locks.php`
- `app/Models/Inventory/InventoryProductAddress.php`
- `app/Models/Inventory/InventoryLock.php`
- `Domain/Inventory/Enums/InventoryStatusEnum.php`, somente se a dependência ainda não o possuir
- `tests/Unit/Inventory/InventoryOperationalSchemaTest.php`

**Editar:** `Inventory.php`, `InventoryProduct.php`, factories e opt-in das suítes Inventory em `tests/Pest.php`, se necessário.

1. Testar autor/horário do início, versão de origem e evolução da situação, preservando o contrato de rascunho.
2. Acrescentar fotografia de endereços por `inventory_product`, com unicidade produto-do-inventário/endereço, metadados cadastrais mínimos e referências que não desapareçam silenciosamente. Não armazenar OPs repetidas como novas tarefas nem saldo ERP.
3. Acrescentar bloqueios com proprietário, produto/contexto, timestamps e metadados de liberação. Proteger a correspondência do bloqueio com a seleção persistida por constraints/FKs apropriadas.
4. Criar índice único parcial de produto/depósito enquanto `released_at IS NULL`; testar conflito ativo, coexistência de produtos distintos e reuso após liberação. Não usar apenas validação PHP.
5. Não criar cascatas que apaguem bloqueios ativos/histórico ao excluir um produto/endereço/inventário. Não criar endpoint de exclusão de inventário.
6. Testar migration/down exclusivamente em banco descartável e sem apagar as tabelas da ENG-3113.

**Validar:** `./vendor/bin/pest tests/Unit/Inventory/InventoryOperationalSchemaTest.php`, após preflight.

### 3. Contexto da movimentação e protocolo de locks

**Depende de:** 1–2.

**Novos propostos em `Domain/Inventory/`:**
- `DTOs/InventoryMovementTargetDTO.php`
- `Services/InventoryMovementContextResolver.php`
- `Services/InventoryProductDepotLock.php`
- `Services/InventoryMovementGuard.php`
- `Exceptions/ProductInActiveInventoryException.php`
- `tests/Unit/Inventory/InventoryMovementContextTest.php`
- `tests/Unit/Inventory/InventoryProductDepotLockTest.php`
- `tests/Feature/Inventory/InventoryMovementGuardTest.php`

1. Testar resolução de contextos a partir de endereço, entrada/saída, item e embalagem, sem depender do setor do cliente/operador. Reutilizar o contexto da ENG-3113, sem inventar empresa, depósito ou associação por nome.
2. Testar origem e destino, produto/identidade anterior e posterior, IDs repetidos e depósito com zeros à esquerda. Contexto fora do recorte não vira `004`; inconsistência de um objeto relevante não vira autorização silenciosa.
3. Derivar chaves advisory com namespace, hash determinístico e inteiro suportado pelo PHP/PostgreSQL. Ordenar/deduplicar pela chave de lock efetiva, inclusive em caso de colisão. Hash não substitui a identidade exata da consulta aos bloqueios.
4. Cobrir modos compartilhado/exclusivo e duração até commit/rollback externo, incluindo chamada aninhada. O guard deve exigir contexto transacional correto, não liberar a trava antes da escrita.
5. Resolver todos os bloqueadores em lote, sem N+1 por item. A recusa não depende de endereço, OP, lote, saldo positivo ou nível administrativo.
6. Provar casos fora da abrangência e em outro contexto, além de item ainda inexistente e endereço novo. Não alterar locks de disponibilidade existentes.

**Validar:** testes novos de contexto/lock/guard, primeiro focais e depois suíte Inventory.

### 4. Início transacional e leitura da fotografia

**Depende de:** 2–3; validar sua corrida com coletas na tarefa 8.

**Novos propostos:** `Domain/Inventory/DTOs/InventoryStartDTO.php`, `Services/InventoryStartService.php`, `Services/InventoryTransferInTransitGuard.php`, `Exceptions/InventoryStartConflictException.php`, `app/Http/Requests/InventoryStartRequest.php`, `tests/Feature/Inventory/InventoryStartTest.php`, `InventoryStartedReadTest.php` e `InventoryStartSideEffectsTest.php` nessa pasta.

**Editar:** `app/Http/Controllers/Inventory/InventoryController.php`, `Domain/Inventory/Resources/InventoryResource.php`, `InventorySummaryResource.php`, `app/Policies/InventoryPolicy.php`, middleware de acesso e `routes/api.php`.

1. Cobrir comando válido, nível/setor indevido, ID fora do contexto, corpo proibido, versão desatualizada e situação incompatível. Estender os testes de acesso existentes para a nova rota.
2. Implementar a sequência do desenho: lock contextualizado do cabeçalho → versão/situação → chaves exclusivas dos produtos persistidos → conflitos/trânsito → resolução atual de todos os endereços → fotografia/bloqueios/início/versionamento → commit.
3. Usar o resolvedor da ENG-3113, sem acrescentar produtos num geral já revisado nem reaplicar o filtro de grupo à expansão de endereços. Cobrir endereço sem saldo e produto que perdeu elegibilidade.
4. Verificar trânsito por coletas efetivamente pendentes e quantidades, considerando origem e destino conhecidos no contexto. Tarefa só pendente não bloqueia; mudar apenas o cabeçalho para cancelado não resolve coleta aberta.
5. Injetar falhas após cada gravação relevante e provar que não sobram estado iniciado, fotografia ou bloqueio parcial. Tratar a constraint de unicidade como conflito legível, preservando rollback.
6. Persistir e testar `started_from_version`: dois envios iguais não duplicam nem trocam autoria; outra versão não oculta edição concorrente; inventário terminal não reinicia.
7. Na leitura de iniciados, usar a fotografia, inclusive após mudança cadastral permitida. Recusar edição de rascunho já iniciado na API, não apenas esconder o botão.
8. Manter iniciados acessíveis no detalhe e na listagem básica necessária à reabertura, sem filtros/monitoramento avançado.
9. Espionar/bloquear dependências ERP no início; verificar quantidades, transações, integrações e filas antes/depois. Não criar tarefas, rodadas ou participantes.

**Validar:** `./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory` após preflight.

### 5. Recusa auditada fora da transação operacional

**Depende de:** 1–3; integrar em todas as fronteiras identificadas nas tarefas 6–8.

**Novos propostos:**
- `database/migrations/<timestamp>_create_inventory_movement_attempts.php`
- `app/Models/Inventory/InventoryMovementAttempt.php`
- `Domain/Inventory/DTOs/InventoryMovementAttemptDTO.php`
- `Domain/Inventory/Services/InventoryMovementAttemptContext.php`
- `Domain/Inventory/Services/InventoryMovementExecutor.php`
- `Domain/Inventory/Services/InventoryMovementAttemptStoreService.php`
- `tests/Feature/Inventory/InventoryBlockedMovementAuditTest.php`

**Editar:** `app/Providers/AppServiceProvider.php` se necessário para contexto de tentativa escopado; exceção de bloqueio e adaptadores da matriz. Alterar `app/Exceptions/Handler.php` somente se indispensável à apresentação específica, sem refatoração genérica.

1. Testar mensagem/código `409`, vários produtos bloqueados, usuário/máquina, origem automática e ausência de dados sensíveis. Usar `OperationalActor` quando existente.
2. Criar identificação da tentativa na fronteira externa e propagá-la às chamadas internas. Modelar um detalhe por vínculo bloqueador, com unicidade tentativa/bloqueio; separar quantidade desejada de delta para não falsificar a auditoria de ajustes.
3. Colocar o executor no dono real da transação de cada operação. Em caso de recusa, terminar rollback externo e só então persistir a auditoria e propagar o erro. Não auditar no meio de uma transação aninhada nem exclusivamente no render HTTP.
4. Quando um caminho já chega em transação aberta, elevar essa fronteira ao dono externo; não fingir durabilidade após um savepoint. Manter chamadas diretas ao domínio e jobs cobertas.
5. Não criar FKs para registros novos que serão apagados pelo rollback, como um item recém-criado no lote recusado. Referenciar o bloqueio persistente e guardar apenas o contexto mínimo do alvo solicitado.
6. Provar rollback de alteração anterior no mesmo lote e permanência da auditoria, inclusive por execução real sem transação de teste mascarando o commit externo. Testes de processos/concorrência precisam seguir as estratégias existentes da instância descartável.
7. Testar falha de armazenamento: nenhum saldo/progresso é aplicado, a movimentação não é liberada e a falha operacional fica observável. Não substituir o registro persistente por fila ou apenas logs de aplicação no caso normal.
8. Demonstrar que uma tentativa que atravessa serviços aninhados não é auditada várias vezes. Distinguir nova tentativa HTTP/job de repetição interna do mesmo processamento.

**Validar:** teste focal de auditoria, guard e testes de erros dos consumidores tocados.

### 6. Proteger transferências, ajustes e escrita direta de itens

**Depende de:** 3–5.

**Editar:** caminhos dos grupos transferência genérica, itens, ajustes e aplicação local da matriz. Acrescentar testes em `tests/Feature/Inventory/InventoryQuantityPathsTest.php` e regressões nos diretórios de testes existentes.

1. Proteger os serviços de entrada antes de efeitos e locks operacionais, usando conjunto completo de chaves em lotes. Manter proteção comum nos pontos de escrita compartilhados para os chamadores diretos, sem criar nova tentativa por chamada interna.
2. Cobrir `transferMany`, `transferOne`, `transactionOne` e chamadas diretas a `transferItemToRecipient`, criação/atualização/remoção de item e escrita direta nos ajustes. Não assumir que todos os chamadores chegam pelo mesmo controller.
3. Na sincronização, impedir a aplicação local de quantidades bloqueadas e sua exclusão por ausência no retorno. Não acrescentar consultas ERP ao bloqueio, alterar a política de importação alheia ou enviar ajustes compensatórios.
4. Testar produto selecionado em outro endereço, nova posição/item, OP diferente e OP 0. Preservar a autorização especial de OP 0 e as validações de saldo atual/reservas quando não há inventário.
5. Testar aumento, redução, exclusão, entrada/saída e transferência com origem ou destino bloqueado. Lote misto recusa tudo; operação independente de produto liberado continua funcionando.
6. Proteger reatribuições de produto/detentor/setor que deslocam saldo e tratar criação/remoção de vínculos relevantes ao congelamento sem corrida com o início. Não fazer uma refatoração geral de produto/endereço.
7. Revisar eventos `ServiceProcessed`, gatilhos de reposição e demais efeitos dos caminhos tocados. Um commit interno não pode publicar sucesso ou movimentação externa de um lote revertido.
8. Atualizar a matriz com o teste de cada escrita e fronteira de auditoria. Não considerar somente testes do guard como prova dos caminhos.

**Validar:** teste parametrizado dos caminhos + suítes focais existentes de Item, StockAdjustment e Transferable, conforme diretórios reais.

### 7. Proteger separação, embalagens, estornos e processos automáticos

**Depende de:** 3, 5–6 e classificação concluída na tarefa 1.

**Editar:** grupos separação, embalagem, devolução/estorno, saída e respectivos jobs/comandos da matriz; ampliar `InventoryQuantityPathsTest.php` ou separar casos por grupo.

1. Cobrir coleta/separação de tarefas antigas e novas. Respeitar a hierarquia de locks do inventário antes dos locks já existentes de tarefa, item e embalagem.
2. Cobrir `ShippingPackagingQuantityService`: soma, remoção, transferência parcial e total. Resolver contexto/produto pelos vínculos locais mesmo se o item original tiver desaparecido e houver referência pelo `StockIOProduct`.
3. Aplicar a proteção nos estornos/devoluções e conclusões que realmente alterem quantidades WMS; não bloquear metadados ou consultas sem esse efeito.
4. Testar jobs/comandos por sua entrada real, mostrando recusa, rollback, origem técnica auditada e ausência de bypass administrativo/automático. Não transformar conflito de inventário em sucesso silencioso.
5. Conferir o comportamento de retry existente sem criar nova política ampla de integração: erro de inventário deve ser reconhecível, sem repetição ocupada ou descarte invisível de movimento. Registrar adequações mínimas por consumidor.
6. Provar que alterações quantitativas de embalagens não escapam por manter inalterado o total de `items.amount`.
7. Provar ausência de progresso, transação de sucesso, embalagem parcial, gatilho externo ou ajuste ERP após a recusa. Preservar chamadas de leitura já próprias de integrações existentes sem atribuí-las ao guard.
8. Rodar regressão dos caminhos exclusivamente de Almoxarifado e demais contextos não bloqueados, sem ampliar o recorte inicial do inventário.

**Validar:** Inventory + suítes focais de PickingOrder, ShippingPackaging, StockIO e Request afetadas.

### 8. Coordenar o início com coleta e endereçamento de transferências

**Depende de:** 3–6; revisar com a tarefa 4.

**Editar:** `TransferTaskPullProductService.php`, `TransferTaskPushProductService.php`, `TransferTaskPickProductService.php` e chamadores diretos de `PickedTransferTaskProductStoreService.php`; `InventoryTransferInTransitGuard.php`.

**Novo:** `tests/Feature/Inventory/InventoryTransferInTransitTest.php`.

1. Aderir ao advisory compartilhado antes de coletar/reservar material, não somente no `push` que muda os saldos. Recarregar a tarefa/item necessários sob a ordem de locks definida.
2. Validar pendência real por quantidade/estado das coletas, sem se limitar à situação da tarefa. Cobrir coleta parcial e várias OPs do mesmo produto.
3. Provar que tarefa pendente sem coleta não impede o início; a mesma tarefa não pode coletar depois do bloqueio.
4. Provar que material coletado impede o início até o endereçamento ou cancelamento efetivo da coleta. Não criar endpoint de cancelamento de coleta como escopo implícito. Se não existir rotina efetiva reutilizável, registrar a lacuna; o caminho confirmado de resolução é endereçar.
5. Cobrir origem/destino conhecidos no contexto abrangido, tarefa cancelada com coleta aberta e transferências de outros produtos/contextos.
6. Garantir recusa auditada para coleta/endereçamento durante inventário ativo, sem deixar reserva ou progresso parcial.

**Validar:** teste focal e regressões de TransferTask, seguidos dos testes concorrentes da tarefa 11.

### 9. Preparar o contrato interno de liberação terminal

**Depende de:** 2–3; o fluxo operacional chamador pertence à ENG-3118.

**Novos propostos:** `Domain/Inventory/Services/InventoryReleaseLocksService.php`, enum de motivo terminal se necessário e `tests/Feature/Inventory/InventoryReleaseLocksContractTest.php`.

1. Resolver todos os bloqueios pelo inventário proprietário, sem aceitar uma lista arbitrária de produtos para liberar.
2. Exigir contexto de encerramento local aprovado/reprovado e sua fronteira transacional; não liberar em `rascunho`, `iniciado`, contagem, conferência ou por parâmetro terminal sem estado correspondente.
3. Usar as chaves exclusivas e a ordem de locks do início. Persistir motivo/autor/horário da liberação; não apagar o histórico.
4. Testar repetição idempotente, preservação de bloqueios de outros inventários/produtos e ausência de chamadas ERP.
5. Em teste de contrato, simular um chamador que registra o encerramento e libera na mesma transação. Injetar falha e comprovar rollback de ambos. Não adicionar rota/tela de aprovação/reprovação para realizar esse teste.
6. Documentar para a ENG-3118: lock do cabeçalho e transação externa → encerramento válido → liberação → commit único. Produtos abortados não liberam antecipadamente.
7. Testar que tempo decorrido, término de rodada e mudança de responsável não alteram bloqueios ativos. Não criar scheduler de expiração nem desbloqueio administrativo.

**Validar:** contrato focal. Registrar que a homologação do encerramento real só ocorre na ENG-3118.

### 10. Conectar o início à interface persistida

**Depende de:** contrato estável da tarefa 4 e cadastro real da ENG-3113. Não disponibilizar operacionalmente antes da proteção integral do backend.

**Editar — frontend:**
- `src/domain/Inventory/services/InventoryService.jsx`
- `src/pages/Inventory/Inventory.jsx`, `InventoryList.jsx` e detalhe persistido criado pela dependência
- `src/pages/Inventory/DraftPanel.jsx`, `draft.mjs` e testes, se ainda existir qualquer configuração de bloqueio
- `src/pages/Inventory/permissions.mjs` e testes

**Novos candidatos:** `src/pages/Inventory/StartInventoryPanel.jsx`, `start.mjs` e `start.test.mjs`, apenas se a composição existente não contemplar a confirmação.

1. Acrescentar o comando ao cliente HTTP já autenticado, enviando somente a versão. Não usar store/fixture/transição local nem abrir permissões para outro setor.
2. Mostrar ação Iniciar somente em rascunho autorizado, com confirmação de depósito/abrangência, estado ocupado e proteção contra duplo clique. Não pedir participantes/distribuição.
3. Eliminar a flag **Bloquear movimentações WMS** da interface, helpers e payload do fluxo real. A dependência já prevê retirá-la: confirmar sua ausência, sem refatorar o motor legado isolado ou migrar storage.
4. Em conflito, preservar o rascunho, apresentar produtos/inventários ou transferências impedidoras e oferecer reconsulta explícita. Não remover produtos nem tentar início parcial automaticamente.
5. Após sucesso, atualizar pela resposta do servidor, mostrar situação iniciada e fotografia somente leitura. Desabilitar edição também com reconsulta após refresh; não simular a ENG-3116.
6. Diante de resposta perdida, consultar o detalhe antes de presumir falha; um reenvio da mesma versão de origem deve respeitar o contrato idempotente.
7. Preservar acesso ao iniciado pela listagem básica/detalhe e por outra sessão autorizada. Não criar filtros gerenciais ou dashboard.
8. Reaproveitar `Button`, `SidePanel` e estilos existentes preservando foco, teclado, fechamento e mensagens legíveis. Conferir apresentação do `409` nos consumidores atuais da web/app; eventual alteração de app não está assumida neste plano e exige necessidade demonstrada.

**Validar:** testes Node dos helpers e permissões, lint focal e build. Manter o guard de isolamento da ENG-3113 contra fixture, storage e ERP no runtime.

### 11. Comprovar concorrência real e ausência de janelas

**Depende de:** 4–9; executar somente no PostgreSQL descartável, sem suítes paralelas que recriem seu schema.

**Novos:** `tests/Feature/Inventory/InventoryStartConcurrencyTest.php`, `tests/Support/InventoryConcurrencyWorker.php` e documentação dos cenários.

Usar processos/conexões PostgreSQL independentes e comprovação de disputa por locks, conforme as estratégias de concorrência de `tests/Feature/PickingOrder/` e `tests/Support/ReclassificationPickingConcurrencyWorker.php`. Não substituir a disputa por chamadas sequenciais ou `sleep` sem prova de bloqueio. Limitar espera, limpar processos e bloquear dependências externas.

1. **Movimentação primeiro:** início aguarda; após o commit, resolve a abrangência atual e inicia de forma consistente. Não pode existir escrita atravessando a fotografia.
2. **Início primeiro:** movimentação aguarda e depois recebe conflito auditado, sem alteração quantitativa/progresso.
3. **Coleta primeiro:** início aguarda e recusa ao reler material em trânsito, sem fotografia/bloqueios parciais.
4. **Início antes da coleta:** coleta aguarda e recusa sem reserva criada, com auditoria persistida uma vez.
5. **Dois inícios sobrepostos:** somente um inventário obtém o produto; o outro permanece rascunho integral, sem bloqueios/fotografia órfãos. Repetir com conjuntos sobrepostos em ordens de envio inversas.
6. **Produtos distintos:** não há serialização global desnecessária; ambos iniciam e produtos não abrangidos continuam movimentáveis.
7. **Edição concorrente:** o início não usa uma seleção silenciosamente substituída por edição da mesma versão; só uma evolução de versão é aceita.
8. **Endereço/item concorrente:** uma criação/reatribuição de localização no momento do início ou acontece antes da resolução ou é recusada depois. Não permitir inclusão de quantidade fora da fotografia por falta de linha de item preexistente.
9. **Liberação interna concorrente:** o contrato terminal não libera outro proprietário nem permite que uma movimentação veja encerramento confirmado com proteção parcialmente aplicada. O fluxo real continua dependente da ENG-3118.

**Validar:** teste focal repetido e suíte Inventory. Registrar explicitamente os cenários executados, sem tratar cobertura de mocks como prova de concorrência.

### 12. E2E, regressão, evidências e publicação segura

**Depende de:** 6–11 completos.

**Novos — frontend:** `e2e/inventory/persisted/start.spec.mjs`, `start-errors.spec.mjs` e casos de mensagens de movimentação nos testes existentes apropriados.

**Editar:** fixtures/setup persistidos da ENG-3113, configuração Playwright apenas quando necessário, e documentação de validação `docs/validation/eng-3114/README.md` em cada repositório com evidência própria.

1. Testar confirmação, duplo envio, `401/403/409/422`, resposta perdida/reconsulta, sucesso, refresh, abrangência imutável e ausência da flag. Não reativar os setups históricos que usam inventários em localStorage.
2. Validar em duas sessões autorizadas: A inicia; B reabre e vê estado/fotografia; edição direta é recusada; movimentação do produto abrangido recebe mensagem e outra movimentação de produto não abrangido permanece válida.
3. Para comportamento visual, respostas sintéticas são permitidas somente em testes. Para provar persistência/bloqueio real, usar backend real e banco descartável, sem criar contas/movimentos no ambiente oficial.
4. Conferir teclado, foco, layout e estados assíncronos em larguras 390, 1280 e 1440, sem dependência de tooltip para abrangência e sem overflow. Preservar estilos do cadastro da dependência.
5. Executar testes focais e regressão conforme o mapa final; documentar falhas preexistentes separadamente. Não corrigir outras issues por conveniência.
6. Publicar a proteção de todos os escritores e reiniciar/drenar processos HTTP/queue antigos antes de aceitar o primeiro início. Não disponibilizar endpoint/botão quando algum worker ainda executa código sem guard.
7. Não reverter para código que ignora bloqueios nem remover as tabelas enquanto existirem inventários ativos. Rollback de migrations descrito nos testes não é um procedimento de desbloqueio de produção.
8. Confirmar que a implantação/configuração não consulta o ERP para compor contexto e não dispara ajustes. Nenhuma etapa deste roteiro exige homologar integração ERP.
9. Revisar `git diff --check`, escopo de arquivos, migrations, índices/constraints, hierarquia de locks, fronteiras de auditoria e todos os critérios abaixo.

**Comandos futuros — backend, sempre após preflight:**

```bash
cd rex-back
php artisan --env=testing test:database-safety
./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory
# Executar também as suítes focais existentes indicadas pela matriz final.
./vendor/bin/pint --dirty
composer test-safe
```

**Comandos futuros — frontend:**

```bash
cd rex-front
node --test src/pages/Inventory/*.test.mjs
npm test
npm run lint
npm run build
# Subir Vite com parâmetros do ambiente de testes antes:
npx playwright test --config=e2e/inventory/playwright.config.mjs
```

Adequar os comandos aos arquivos/suítes efetivamente criados pela ENG-3113. Não presumir que testes históricos do protótipo certificam o fluxo persistido. Registrar qualquer smoke não executado por falta de ambiente/contas, em vez de apresentá-lo como concluído.

## Matriz de aceite para a execução

| Critério | Tarefas e evidências obrigatórias |
| --- | --- |
| Início persiste abrangência e ativa proteção consistentemente | 2–4 e 11: constraints, transação, falhas injetadas, snapshot autoritativo e concorrência. |
| Todos os caminhos rejeitam alterações do produto/depósito, qualquer endereço | 1, 3 e 6–8: matriz final sem lacunas, testes comportamentais por escritor, item novo/outro endereço/OP e API direta/jobs. |
| Produtos fora da abrangência permanecem movimentáveis | 3, 6–8 e 11–12: produto não selecionado, contexto distinto e inventários disjuntos. |
| Recusa legível e tentativa auditada | 5–8 e 12: contrato `409`, rollback externo, origem e deduplicação; teste de falha sem liberação. |
| Bloqueio até encerramento aprovado/reprovado | 9 e 11: permanência e contrato interno atômico/idempotente. Homologação do encerramento operacional pertence à ENG-3118. |
| Bloqueio sem consultas ou ajustes ERP | 3–5, 9 e 12: dependências externas bloqueadas nos testes do início/guard/liberação, sem payloads/filas de ajuste. |
| Ausência da flag do protótipo | 4, 10 e 12: corpo proibido no backend e ausência na criação/confirmação/payload do fluxo real. |

## Pontos de atenção já identificados

- A base original deste planejamento ainda não continha a ENG-3113. Na execução autorizada, seu contrato real foi incorporado antes de implementar, sem reabrir decisões de cadastro/abrangência.
- Cancelamento de tarefa não cancela coleta no código inspecionado. Se não houver rotina efetiva reutilizável, a resolução confirmada é o endereçamento; qualquer nova rotina de cancelamento deve ser discutida separadamente.
- Auditoria depois de savepoint, proteção apenas na interface/controller e dependência dos métodos `incrementAmount`/`decrementAmount` são insuficientes.
- A abordagem escolhida exige atualizar todos os processos escritores da aplicação. Não atribuir a ela proteção contra SQL administrativo fora do WMS.
- A etapa inicial de planejamento não executou migrations, testes ou consultas ao banco/ERP. A skill `writing-plans` não estava instalada; o roteiro foi estruturado manualmente. A execução posterior usou somente PostgreSQL descartável após preflight; seus gates, falhas herdadas e timeout da suíte ampliada estão nas evidências.
