# ENG-3114 — Início do inventário e bloqueio de movimentações WMS

**Status:** desenho aprovado por seções em 2026-11-05; implementação autorizada e realizada em 2026-11-06, disponível para revisão. [Evidências e limites](../testing/eng-3114-inicio-bloqueio.md).
**Issue:** https://linear.app/soelx/issue/ENG-3114/iniciar-inventario-e-bloquear-movimentacoes-no-wms
**Pré-requisito:** [desenho da ENG-3113](2026-11-05-eng-3113-inventario-manual-design.md) e seu [plano de implementação](2026-11-05-eng-3113-inventario-manual-implementation-plan.md).

## Objetivo e limites

Iniciar um inventário persistido, congelar sua abrangência operacional e impedir alterações de quantidades dos produtos no depósito correspondente. O bloqueio é obrigatório no backend e abrange todos os endereços, não apenas os endereços usados para selecionar produtos.

As decisões de cadastro da ENG-3113 são pré-requisitos, não serão reabertas nesta atividade. O recorte inicial permanece **Expedição ↔ depósito 004**, obtido da configuração local introduzida pela ENG-3113. Não hardcodar o depósito nem consultar o ERP para descobrir a associação.

Esta issue não implementa participantes, rodadas, distribuição, contagens, resultados, aprovação/reprovação ou integração com ERP. Prepara o contrato interno de liberação a ser chamado pelo encerramento da ENG-3118.

## Contexto e isolamento do trabalho

A inspeção encontrou vários caminhos de escrita: transferências genéricas, ajustes, geração/sincronização de itens, separação, coleta para transferência, embalagens e rotinas de devolução/estorno. Proteger apenas controllers, a tela de inventário ou os métodos de incremento/decremento de `Item` não atende ao aceite.

No momento do planejamento, a ENG-3113 possui documentos, mas ainda não possui a implementação de inventário. Nomes novos de classes/tabelas abaixo são contratos propostos; devem ser reconciliados com sua entrega efetiva, sem duplicar seu contexto ou seu resolvedor de abrangência.

A documentação desta issue fica em `rex-back/docs/plans/`. Para não interferir na sessão da ENG-3113, foi criada a worktree `rex-back-eng-3114`, branch `feature/eng-3114`, a partir de `bbb18508` — somente documentação da dependência sobre a base backend `a6b49a5f`. Não houve troca de branch em `rex-back` ou `rex-front`. Antes da implementação, incorporar a entrega aprovada da ENG-3113 e criar/atualizar a branch correspondente do frontend a partir dela, não de uma base sem o cadastro persistido.

## Decisões aprovadas

1. Não iniciar parcialmente: qualquer conflito ou inconsistência recusa o início inteiro.
2. Impedir inventários ativos sobrepostos para o mesmo produto e depósito. Inventários com produtos distintos podem ocorrer em paralelo.
3. Tarefas pendentes não impedem o início nem são canceladas automaticamente.
4. Material coletado ainda em transferência precisa ser endereçado ou ter sua coleta efetivamente cancelada antes do início. Após o início, tarefas novas ou antigas não podem movimentar os produtos bloqueados.
5. A abrangência definitiva usa os produtos selecionados no rascunho e todos os seus endereços atuais na Expedição, inclusive sem saldo. Não inclui novos produtos automaticamente.
6. A flag **“Bloquear movimentações WMS” deve ser removida**. Não existe modo de iniciar sem bloqueio, nem parâmetro de API que o desative.
7. A proteção vale também para transferências internas, ajustes, estornos/devoluções, quantidades em embalagens e processos automáticos que alterem quantidades no contexto abrangido.
8. Lotes são atômicos: a presença de um produto bloqueado recusa todo o lote. Produtos não abrangidos continuam movimentáveis em operações independentes.
9. O bloqueio permanece até o encerramento local aprovado ou reprovado; não expira e não é liberado por rodada, recontagem, aborto de produto ou mudança de responsável.
10. Não consultar saldos, enviar ajustes ou aguardar confirmação do ERP para iniciar, bloquear ou liberar.

## Abordagens consideradas

| Abordagem | Benefício | Custo ou risco |
| --- | --- | --- |
| **Validação compartilhada nos serviços de domínio + travas transacionais — escolhida** | Preserva os fluxos existentes e protege HTTP, jobs e comandos com a mesma regra. | Exige inventário completo dos escritores, fronteiras transacionais corretas e cobertura de cada caminho. |
| Novo serviço central para todas as movimentações | Uniformiza a proteção em uma única escrita. | Refatoração ampla de entradas, saídas, transferências, ajustes e embalagens, além desta entrega. |
| Triggers de banco | Protege inclusive alterações SQL que passem pelas tabelas protegidas. | Aumenta a complexidade de contexto, mensagens, manutenção e auditoria após rollback. |

A solução escolhida não promete proteger SQL administrativo executado fora do WMS. Nenhum escritor da aplicação pode contornar a regra; novos caminhos precisam aderir ao contrato e à matriz de testes.

## 1. Início e abrangência definitiva

### Acesso e comando

Disponibilizar `POST /api/v1/inventory/{inventory}/start`, autenticado e sujeito às mesmas verificações explícitas de contexto da ENG-3113: Administrador ou Master com sessão ativa na Expedição. Não depender exclusivamente de Policy com bypass global de Master.

O cliente informa a versão lida do rascunho. Depósito, setor, produtos, endereços, autoria, situação e bloqueio não são campos de escrita desse comando. Não aceitar `blockMovements: false` ou equivalente como forma de contornar a regra.

### Fluxo atômico

1. Autorizar e ler o cabeçalho contextualizado sob lock curto; validar situação e versão.
2. Obter os produtos persistidos, sem confiar em endereços ou filtros enviados pelo navegador.
3. Adquirir as travas por produto/depósito e revalidar os dados operacionais sob essas travas.
4. Verificar conflitos com bloqueios ativos e coletas de transferência ainda pendentes no contexto afetado.
5. Resolver todos os endereços atuais da seleção pelo serviço da ENG-3113. Produto sem vínculo elegível exige revisão; nunca removê-lo silenciosamente.
6. Persistir a fotografia da abrangência e os bloqueios; registrar situação iniciada, autor, horário e nova versão.
7. Confirmar tudo na mesma transação. Uma falha não deixa fotografia parcial, bloqueio órfão ou inventário iniciado sem proteção.

A fotografia preserva identidades e os metadados cadastrais mínimos necessários à apresentação e às tarefas futuras. Não é uma fotografia de saldo ERP e não introduz saldos de referência nesta issue. OPs/itens repetidos não duplicam o par produto/endereço.

A repetição do comando que já iniciou o mesmo rascunho não recria abrangência ou bloqueios. Vincular a confirmação à versão de origem do início permite recuperar uma resposta perdida sem iniciar novamente ou ignorar uma edição concorrente.

### Persistência proposta

- Estender `inventories` com autor/horário do início e versão de origem do comando confirmado.
- Preservar `inventory_products` como seleção imutável depois do início.
- Acrescentar fotografia relacional dos endereços por produto do inventário, com unicidade e referências que não desapareçam por exclusão em cascata de cadastros.
- Acrescentar bloqueios persistentes vinculados ao inventário/produto/depósito, com criação e liberação rastreáveis. Usar unicidade **apenas dos bloqueios ativos** para impedir sobreposição e permitir novos inventários após o encerramento.
- Guardar tentativas recusadas em estrutura própria de auditoria, não em transações de estoque efetivadas.

Não usar o estado completo do protótipo como JSON, uma flag no cadastro global do produto ou um bloqueio por endereço. Manter o código do depósito como string, preservando `004`, e reutilizar a identidade de contexto da dependência.

## 2. Proteção dos caminhos WMS

### Regra compartilhada

Um guard de domínio recebe os produtos e os contextos locais efetivamente afetados pela operação. O contexto vem dos objetos persistidos de origem/destino — endereço, entrada/saída ou vínculo da embalagem —, não do setor declarado pelo cliente nem somente da sessão do operador.

Consultar bloqueios ativos por produto/depósito, sem restringir a consulta aos endereços da fotografia. Isso também impede criar saldo num endereço novo. OP, lote, outro endereço, outro operador ou nível administrativo não são exceções.

Verificar origem e destino nas transferências e o conjunto completo de produtos nos lotes. Produto fora da abrangência e o mesmo produto em outro depósito seguem suas regras normais. Objetos de contextos fora do recorte não podem ser convertidos automaticamente em depósito 004.

Incluir criação, alteração e remoção de quantidades, transferências entre embalagens, aplicação local de sincronizações e escritas diretas de itens que não passam pelo serviço genérico de transferência. Trocas de produto/detentor/setor que representem deslocamento de saldo também não podem ser um atalho para escapar do bloqueio. Não refatorar cadastros sem relação com esse risco.

A coleta para transferência exige a mesma proteção, embora possa apenas reservar material antes do endereçamento. Permitir coletar durante um inventário criaria trânsito físico sem alterar imediatamente `items.amount`.

### Concorrência

Usar um protocolo único de travas transacionais PostgreSQL por identidade de produto/depósito. A proposta técnica é trava advisory **exclusiva** para início/liberação e **compartilhada** para movimentações/coletas, mantida até o commit ou rollback externo. Movimentações continuam usando os locks de saldo já necessários; o advisory não substitui sua validação de disponibilidade.

Adquirir todas as chaves em ordem determinística antes das leituras decisivas e dos locks operacionais dos fluxos tocados. Reconciliar a ordem existente de locks de tarefa, item e embalagem; inserir uma consulta tardia no meio de uma escrita não resolve a corrida.

Assim, uma operação termina antes da fotografia ou espera e é recusada depois do início. O início que aguarda uma coleta concorrente deve reler o trânsito e falhar se ela deixou material pendente. Uma consulta `exists` sem esse protocolo não protege a ausência inicial de uma linha de bloqueio.

Tarefas pendentes permanecem disponíveis para consulta e ações sem efeitos quantitativos. Processos automáticos não têm bypass; eventos e efeitos externos de operações recusadas não podem sobreviver ao rollback.

### Atenção ao cancelamento existente

Na base inspecionada, `TransferTaskCancelService` altera a situação da tarefa, mas não resolve por si só os registros de coleta em trânsito. Portanto, **tarefa cancelada não prova coleta cancelada**. A validação deve usar as quantidades/estados reais das coletas. O endereçamento está identificado no fluxo `pull`/`push`; eventual ausência de um cancelamento efetivo de coleta deve ser registrada como lacuna separada, não contornada ignorando trânsito ou inventando uma nova rotina nesta issue.

## 3. Respostas e auditoria

Uma tentativa bloqueada retorna `409` com código estável, por exemplo `product_in_active_inventory`, mensagem legível e produtos que impedem a operação. Exemplo: **“O produto X está em inventário ativo INV-123 no depósito 004.”** Preservar o envelope de erros legíveis e a sanitização existentes.

Registrar uma identificação da tentativa e os vínculos bloqueadores, operação, quantidade solicitada com sua semântica, origem/destino, horário, operador e máquina quando disponíveis. Jobs/comandos registram sua origem técnica; não inventar usuário ou máquina. Não armazenar credenciais, tokens ou o payload completo.

A auditoria fica **fora da transação operacional revertida**. O guard sinaliza a recusa; a fronteira externa da operação termina o rollback e persiste a auditoria antes de devolver o conflito ou concluir o tratamento do job. Um commit de transação aninhada/savepoint não basta. Não depender apenas do Exception Handler HTTP, pois existem chamadas de domínio, jobs e comandos.

Reutilizar a mesma identificação nos serviços internos e impedir duplicação por tentativa/vínculo bloqueador. Um lote com vários produtos bloqueados pode possuir vários detalhes associados à mesma tentativa, não várias tentativas fictícias.

Se a gravação falhar, a movimentação continua recusada e a falha é registrada de forma operacionalmente observável. Não usar fila assíncrona como única garantia da auditoria. Não criar painel ou consulta avançada de auditoria nesta entrega.

## 4. Duração e contrato com a ENG-3118

O registro ativo do bloqueio é a fonte de proteção, sem uma lista permissiva de situações que possa esquecer fases futuras. Contagens, recontagens, conferência, espera por aprovação e produtos abortados não o liberam.

Preparar serviço interno de liberação restrito aos bloqueios pertencentes ao inventário e aos motivos terminais aprovado/reprovado. Deve ser idempotente, preservar o histórico e usar o mesmo protocolo de locks. Não disponibilizar endpoint de desbloqueio nem permitir exclusão/reinício como alternativa.

A ENG-3118 chama esse contrato **na mesma transação do encerramento local aprovado ou reprovado**. Qualquer falha preserva situação anterior e bloqueios. Até sua entrega não há ação operacional de encerramento nesta issue. Testes do contrato interno não serão apresentados como homologação do fluxo completo de aprovação.

Nenhuma liberação depende do ERP, de ajuste de saldo ou de relógio/timeout.

## 5. Interface e fluxo de dados

No detalhe persistido pela ENG-3113, exibir **Iniciar inventário** para quem possui permissão e situação adequada. A confirmação apresenta depósito e abrangência, aguarda a API e impede envio duplicado. Não exigir participantes ou distribuição.

Exibir conflitos de versão, sobreposição e transferências pendentes sem modificar o rascunho nem recorrer a estado local simulado. Depois da confirmação do servidor, apresentar a situação iniciada e a abrangência definitiva em modo somente leitura; mantê-lo acessível pelo mesmo identificador após refresh e em outra sessão autorizada.

Remover a flag **Bloquear movimentações WMS** do cadastro/fluxo real, sem substituí-la por outra configuração. A ENG-3113 já prevê retirar essa opção; a ENG-3114 deve verificar que ela não reaparece no detalhe, na confirmação, nos helpers ou no contrato da API.

Não usar `transition(START)`, `createStarted`, fixture ou storage do protótipo. Não construir app de contagem, distribuição, aprovação, resultados ou filtros gerenciais. Não há alteração planejada em `Rex-Estoque`; confirmar que seus consumidores apresentam a mensagem legível do backend, registrando separadamente eventual incompatibilidade real.

## 6. Validação planejada

### Backend

- Início autorizado, situação/versão, repetição, resolução de todos os endereços e ausência de inclusão automática de produtos.
- Abrangência sem filtro de saldo, deduplicação por OP e revisão de produtos sem vínculo.
- Atomicidade de cabeçalho/fotografia/bloqueios e unicidade ativa, com teste de migrations/constraints.
- Inventários simultâneos sobrepostos e distintos, além da edição concorrente do rascunho.
- Matriz comportamental de todos os escritores: criação/remoção de item, transferência, ajuste, entrada/saída, estorno/devolução, embalagem e aplicação local por job/comando.
- Outro endereço, endereço novo, item inexistente, outra OP/lote, usuário Master e tentativa direta de API não contornam a regra.
- Produtos não selecionados e contextos não bloqueados continuam movimentáveis; lote misto não é aplicado parcialmente.
- Coletas pendentes reais impedem o início; tarefa apenas pendente não impede; situação cancelada do cabeçalho não esconde coleta aberta.
- Concorrência real com processos PostgreSQL independentes entre início/movimentação, início/coleta e dois inícios. Não certificar concorrência apenas com chamadas sequenciais ou mocks.
- Auditoria após rollback externo, identificação de operador/máquina/processo, deduplicação e falha de gravação sem liberar movimentação.
- Persistência do bloqueio durante estados não terminais, contrato de liberação terminal idempotente e rollback de encerramento simulado.
- Ausência de dependência/chamadas ERP no início, guard e liberação; não disparar ajustes ou efeitos externos para contornar recusas.

### Frontend e integração

- Confirmação, duplo envio, erros, resposta perdida/reconsulta, sucesso e abrangência imutável.
- Ausência da flag e de transições/storage/fixture do protótipo no runtime.
- Reabertura por outra sessão autorizada; permissões e mensagens de conflito preservadas.
- Teclado, foco, estados assíncronos e responsividade, reaproveitando os componentes existentes sem refatoração global.
- Distinguir testes de UI interceptados de testes reais com backend e banco.

Antes de qualquer suíte que altere schema, seguir `docs/testing-database.md` e executar o preflight da instância descartável. Não usar o banco oficial nem executar testes concorrentes que recriem o mesmo schema em sessões diferentes. Não executar migrations, ERP ou testes de funcionalidade como parte deste planejamento.

## Limites entre entregas

| Issue | Responsabilidade |
| --- | --- |
| ENG-3113 | Cadastro, seleção persistida e resolução cadastral da abrangência em rascunho. |
| **ENG-3114** | Início, fotografia definitiva, bloqueios, recusa auditada e contrato interno de liberação. |
| ENG-3115 | Consulta/filtros gerenciais e acompanhamento avançado. |
| ENG-3116 | Distribuição e assunção das tarefas. |
| ENG-3117 | Modalidades e registro de contagens no aplicativo. |
| ENG-3118 | Conferência, resultados e encerramento local aprovado/reprovado com liberação efetiva. |

O [plano detalhado de implementação](2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-implementation-plan.md) descreve tarefas, arquivos e validações. A implementação foi autorizada após a entrega da ENG-3113 e realizada nas branches da issue. Não houve publicação/deploy; os resultados e limites da validação estão registrados nas evidências.
