# ENG-3114 — Início, abrangência definitiva e bloqueio WMS

## Base e contexto

Extensão da [API de rascunhos da ENG-3113](inventory-manual-api.md). A implementação está nas branches feature/eng-3114 de backend e frontend, sobre as entregas da ENG-3113 (backend da900b92; frontend 753c7497). Destino de revisão: feature/inventario, não main.

O contexto continua sendo Expedição e o depósito definido em REX_INVENTORY_EXPEDITION_DEPOT_CODE. A instância aprovada usa 004. Não há descoberta de depósito no ERP, configuração de bloqueio pelo usuário ou ajuste de quantidades ao iniciar.

## Iniciar

**POST /api/v1/inventory/{id}/start**

Autenticação e sessão ativa na Expedição com nível Administrador ou Master. O middleware explícito permanece necessário apesar do bypass global de Master nas Policies.

Corpo:

~~~json
{"version": 1}
~~~

Somente version é aceito. Produtos, endereços, setor, depósito, situação, autores, blockMovements e block_movements não são campos de escrita.

O início valida a versão e o rascunho sob lock, protege todos os produtos/depósito com advisory locks exclusivos, rejeita sobreposição e coleta em trânsito, resolve a abrangência atual e grava fotografia, bloqueios, autoria, horário e nova versão numa única transação. Não inclui produtos que não estavam selecionados nem gera rodadas/tarefas.

### Resposta 200

Retorna o Resource de detalhe, preservando os campos da ENG-3113 e acrescentando:

- status: iniciado;
- version incrementada;
- started_at: horário ISO 8601;
- started_by: id e nome de quem efetivamente iniciou;
- frozen_products: produtos com identidade/metadados cadastrais locais e addresses, contendo id, parent_id, name e hierarchy;
- scope: totais e IDs derivados da fotografia, não do catálogo vivo.

As respostas de listagem também incluem iniciados e apresentam a situação real. Rascunhos mantêm scope vivo e frozen_products nulo. Para iniciados, edições da API de rascunho retornam 409; a consulta não recalcula a fotografia.

started_from_version é persistido internamente. Reenviar a mesma versão de origem em inventário já iniciado e não terminal devolve o estado atual, sem recriar dados nem mudar autoria. Não há reinício de inventário encerrado.

### Erros

| HTTP | Código/condição |
| --- | --- |
| 401 | Sem autenticação. |
| 403 | Nível ou setor ativo não autorizado. |
| 404 | Registro inexistente ou fora do contexto configurado. |
| 422 | Corpo inválido/campo não permitido ou produto que perdeu elegibilidade; exige revisão. |
| 409 inventory_start_conflict | Versão alterada ou situação incompatível. |
| 409 inventory_scope_conflict | Outro inventário já bloqueia algum produto/depósito. conflicts identifica produtos e inventários. |
| 409 inventory_transfer_pending | Existem coletas efetivamente em trânsito. conflicts identifica produto, coleta e tarefa. |

Tarefa apenas pendente não impede o início. Cancelar somente o cabeçalho da tarefa não resolve uma coleta TRANSFERRING. Não foi criada rotina nova de cancelamento: é necessário endereçar ou resolver efetivamente a coleta pelos fluxos existentes.

## Movimentações recusadas

As rotas WMS existentes passam a responder:

~~~json
{
  "message": "O produto X está em inventário ativo INV-0123 no depósito 004.",
  "code": "product_in_active_inventory",
  "blocked_items": [
    {
      "inventory_lock_id": 1,
      "inventory_id": 123,
      "inventory_code": "INV-0123",
      "product_id": 456,
      "depot_code": "004",
      "description": "X"
    }
  ]
}
~~~

A regra usa o produto e o depósito, sem restringir a consulta ao endereço fotografado, OP ou lote. Abrange criação/remoção de item, ajustes, transferências, entradas/saídas, separação, embalagens e aplicação local de quantidades por processos automáticos. Não há exceção para Admin, Master, System ou tarefa antiga.

As entradas de lote validam o conjunto completo antes de escrever. Um produto bloqueado recusa o lote, sem aplicar linhas livres parcialmente. Documentos de entrada distintos de um job continuam operações independentes; todas as linhas de cada StockIO são atômicas.

## Implementação e auditoria

InventoryMovementGuard é compartilhado entre os serviços de domínio. GuardsInventoryMovements é uma defesa adicional em modelos quantitativos e cadastros cujo deslocamento/exclusão poderia contornar a proteção. Não é substituto do preflight do lote e não protege SQL administrativo externo.

InventoryProductDepotLock deriva chaves determinísticas por produto/depósito: início e liberação usam lock exclusivo; movimentações usam compartilhado até terminar a transação externa. As identidades relevantes são relidas sob proteção; locks de item/tarefa já existentes continuam necessários.

Caixas/paletes Storage são resolvidos pelos vínculos locais de localização e conteúdo, inclusive aninhados, sem inferir setor pelo operador. InventoryStorageLock coordena conteúdo e posicionamento antes de resolver o depósito. Essa proteção não amplia o catálogo/seleção da ENG-3113.

A recusa é acumulada no contexto da operação e persistida em inventory_movement_attempts somente quando o transactionLevel da conexão principal volta a zero, nos eventos de rollback/commit. Um savepoint não dispara a persistência. Isso cobre serviços diretos, HTTP, jobs e comandos sem perder o registro com o rollback da movimentação.

Cada tentativa tem UUID e unicidade por bloqueio. Guarda operação, origem técnica, operador/máquina quando conhecidos, contextos de origem/destino e quantidades solicitadas com sua semântica. Não guarda tokens, credenciais ou payload integral. Quantidade de um contêiner não é convertida ficticiamente em unidades de produto.

Se a persistência da auditoria falhar, a operação continua recusada e é emitido inventory.movement_audit_failed em nível crítico. Não existe fila como única garantia, painel de auditoria ou endpoint de desbloqueio nesta entrega.

## Contrato interno para ENG-3118

InventoryReleaseLocksService::release recebe o inventário e o operador. **O chamador deve abrir a transação, bloquear o cabeçalho e registrar status aprovado ou reprovado antes da chamada; o commit é único.**

O serviço exige transação ativa e situação terminal, resolve os bloqueios pelo proprietário, adquire as mesmas chaves exclusivas e registra released_at, released_by e release_reason. Repetir não altera o histórico nem libera outro inventário. Rollback do encerramento restaura os bloqueios.

Contagem, recontagem, conferência, tempo decorrido e produtos abortados não liberam nada. A aprovação/reprovação operacional continua sendo responsabilidade da ENG-3118; não há tela/rota terminal antecipada.

## Publicação segura

- Configurar o mapeamento local antes de iniciar; não mudar o depósito enquanto houver bloqueios ativos.
- Aplicar a migration, publicar todos os escritores protegidos e drenar/reiniciar workers antigos antes do primeiro início.
- Não habilitar apenas a interface contra um backend/worker antigo.
- Não remover tabelas ou voltar a código que ignora bloqueios com inventário ativo.
- Não executar migrations/testes destrutivos no banco oficial; seguir docs/testing-database.md.
- Consultar a [matriz de caminhos](validation/eng-3114/movement-paths.md) e as [evidências](testing/eng-3114-inicio-bloqueio.md).
