# ENG-3114 — Implementação e evidências

**Data:** 2026-11-06. **Situação:** implementação local disponível para revisão, sem publicação/deploy.
**Branches:** feature/eng-3114 em rex-back e rex-front. **Base de revisão:** feature/inventario.
**Pré-requisito incorporado:** ENG-3113 — backend da900b92; frontend 753c7497.

## Entrega

- Comando de início autorizado, versionado e idempotente pela versão de origem.
- Fotografia cadastral de produtos/endereços e bloqueios ativados na mesma transação.
- Proteção por produto/depósito em serviços e defesa adicional nos modelos quantitativos; sem bypass por endereço, OP, lote, perfil ou job.
- Preflight de lotes completos, incluindo entrada automática por StockIO, e auditoria fora do rollback externo.
- Trânsito real de transferência impede o início; tarefa apenas pendente não impede.
- Quantidades em embalagens e caixas/paletes legados também protegidas, com contexto físico persistido e coordenação de conteúdo/posicionamento.
- Interface com confirmação, reconsulta após resposta perdida, ausência da flag e detalhe iniciado somente com fotografia persistida. A reabertura não requisita catálogo nem scope-preview; também é testada com catálogo vivo indisponível.
- Contrato interno de liberação terminal preparado; telas/rotas de aprovação/reprovação pertencem à ENG-3118.
- Nenhuma quantidade foi ajustada ao iniciar; bloqueio/liberação não dependem de ERP.

Referências: [contrato](../inventory-start-api.md), [matriz de escritores](../validation/eng-3114/movement-paths.md), [desenho](../plans/2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-design.md) e [plano](../plans/2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-implementation-plan.md).

## Ambiente seguro

PHP 8.4.27, PostgreSQL 16.1 descartável rex_test e Node 20.20.2. Dependências do lockfile instaladas nas worktrees, sem symlink de vendor nem cópia do .env oficial.

O PHP de testes compartilhou o namespace de rede do PostgreSQL descartável, com loopback e porta interna iguais aos configurados, em rede Docker interna sem acesso ao ERP. O preflight confirmou APP_ENV=testing, conexão pgsql e current_database=rex_test antes das suítes. Não houve acesso ao banco oficial.

Não foram executadas duas suítes que recriam schema simultaneamente. Processos filhos dos testes de concorrência usam a mesma base preparada, mas não executam migrations. Testes de auditoria usam commits reais e limpam seus dados antes/depois, preservando a parametrização inicial de transferências.

## Gates executados

| Verificação | Resultado |
| --- | --- |
| Segurança do banco | Preflight aprovado antes das suítes. |
| Módulo Inventory, extraído do JUnit final | **117 testes, 698 assertions, zero falhas**. |
| Concorrência PostgreSQL | **13 cenários** com processos independentes; pg_blocking_pids comprova as esperas relevantes. |
| Frontend npm test | **457 testes, zero falhas**, em Node 20. |
| ESLint focal | Arquivos JS/JSX/MJS alterados, incluindo E2E, sem erros/avisos. |
| Build Vite | Aprovado; aviso preexistente de chunk maior que 500 kB. |
| Playwright UI/contrato isolado | **21 testes aprovados**, incluindo 9 do início. |
| Playwright com API/PostgreSQL reais | **2 testes aprovados**, incluindo início, fotografia, recusa de edição/movimento e SKU livre. |
| Pint | Aprovado nos **65 arquivos PHP alterados**, por lista explícita de caminhos. |
| Diff | diff --check aprovado nos dois repositórios. |

O --dirty do Pint dentro do contêiner não encontra o gitdir absoluto da worktree no host e inicialmente reportou zero arquivos. Isso não foi usado como certificação: o formatador foi efetivamente executado e verificado sobre a lista explícita de arquivos alterados.

### Concorrência comprovada

- Movimentação termina antes da fotografia ou espera e recebe conflito auditado após o início.
- Início relê uma coleta concorrente e recusa material em trânsito.
- Pull aguardando o início não cria reserva depois.
- Dois inícios sobrepostos, inclusive vários produtos enviados em ordem inversa, não deixam segundo inventário parcial.
- Produtos distintos não usam um lock global.
- Edição que aguardava o início não sobrescreve o registro.
- Novo endereço/item não contorna o bloqueio.
- Mudança Warehouse → Expedição e posicionamento de contêiner inicialmente vazio não deixam um write previamente validado escapar.
- Uma movimentação aguardando encerramento só é liberada se a transação terminal realmente confirmar; rollback mantém proteção.

### Auditoria e processos

Os testes comprovam registro após rollback externo, ausência de gravação após mero savepoint, deduplicação, quantidade solicitada, operador e máquina do OperationalActor. A falha do armazenamento gera observabilidade crítica sem permitir a movimentação.

InventoryInputJobTest executa dispatchSync real de ProcessInputProductsJob: duas linhas do mesmo StockIO, primeira livre e segunda bloqueada, são recusadas antes da primeira aplicação. O registro identifica o System e a origem job; não há PickedItem, transação ou consulta ERP produzida pelo bloqueio.

## Smoke real entre duas sessões

A criou o rascunho e iniciou. B, com token de Master, reabriu e viu a mesma fotografia, sem edição. Repetir o início com a versão original não duplicou bloqueios. Edição direta retornou 409. Transferência do produto bloqueado retornou product_in_active_inventory; a de um SKU fora da abrangência retornou 200.

Verificação posterior diretamente no banco descartável:

~~~json
{
  "status": "iniciado",
  "products": 1,
  "frozen_addresses": 2,
  "active_locks": 1,
  "refused_attempts": 1,
  "blocked_quantity": 10,
  "free_quantity_after_transfer": 7
}
~~~

A quantidade livre era 8 antes da transferência. A quantidade bloqueada permaneceu 10. Contas/tokens eram sintéticos e não foram versionados; nenhum endpoint de auditoria ou de teste foi acrescentado à aplicação.

## Regressões legadas e limite da validação

### Recorte amplo concluído: itens, endereços, transferências e embalagens

Mesmo comando comparado com a base imutável da ENG-3113 (da900b92), no mesmo runtime isolado:

- **Base:** 178 aprovados e 30 falhas.
- **ENG-3114:** 250 aprovados e as mesmas 30 falhas.
- A lista de testes/famílias de erro coincide; nenhuma falha nova nesse recorte concluído.
- Exemplos herdados: contratos/rotas antigos, argumentos ausentes em testes de Transferable, permissões esperadas como 404 que atualmente retornam 403 e fixtures antigas de embalagem.

Comando executado em cada checkout, sempre depois do preflight no banco descartável:

~~~bash
./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory \
  tests/Unit/Item tests/Unit/Address \
  tests/Feature/Transferable tests/Unit/Transferable \
  tests/Feature/ShippingPackaging tests/Unit/ShippingPackaging \
  tests/Feature/TransferTask --log-junit=/tmp/eng3114-focal.xml
~~~

### Recorte adicional concluído de PickingOrder/Request

Foram executados separadamente os seis arquivos de PickingOrder que reportaram falhas na tentativa ampla, mais BackfillOutputRequestSeparationServiceTest e os testes de schema/contexto Inventory:

- **Base:** 43 aprovados e 16 falhas.
- **ENG-3114:** 45 aprovados e as mesmas 16 falhas.
- JUnit comparado por identificação do teste e tipo de falha/erro, sem novas diferenças. Os dois testes aprovados adicionais são de schema operacional.

~~~bash
./vendor/bin/pest tests/Unit/Inventory \
  tests/Feature/PickingOrder/ExpeditionPickingOrderMultiFinishTest.php \
  tests/Feature/PickingOrder/ExpeditionPickingOrderStoreTest.php \
  tests/Feature/PickingOrder/PickingOrderPauseTest.php \
  tests/Feature/PickingOrder/PickingOrderStartTest.php \
  tests/Feature/PickingOrder/ReclassificationPickingOrderStoreTest.php \
  tests/Unit/PickingOrder/MarkConcludedPickingOrdersWithSeparatedItemsAsDeliveredPartialMigrationTest.php \
  tests/Unit/Request/BackfillOutputRequestSeparationServiceTest.php \
  --log-junit=/tmp/eng3114-bounded.xml
~~~

### Não certificado

A tentativa de executar de uma vez todos os testes de Feature/Unit PickingOrder, Feature StockIO e Feature Request excedeu **600 segundos** e foi interrompida no contêiner isolado. Não foi tratada como regressão completa aprovada. As falhas parciais observadas foram reexecutadas no recorte limitado acima e reproduzidas na base.

Não foi executada com sucesso uma suíte geral de toda a aplicação. Não foram corrigidas falhas legadas ou atualizado o script composer test-safe nesta issue; os comandos seguros foram preflight e Pest separados.

Não houve homologação do aplicativo nativo, do encerramento operacional da ENG-3118, de integração ERP nem implantação em ambiente oficial.

## Reprodução

Usar PHP compatível e ambiente descartável explicitamente configurado, seguindo docs/testing-database.md. Nunca usar o .env oficial para estas suítes.

~~~bash
# Na worktree backend, no runtime de testes:
php artisan --env=testing test:database-safety
./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory

# Na worktree frontend, em Node 20:
npm test
npm run build
# Subir Vite e configurar URLs/portas somente por ambiente antes:
npx playwright test --config=e2e/inventory/playwright.config.mjs
# A suíte real exige INVENTORY_E2E_SESSIONS_FILE de contas sintéticas autorizadas:
npx playwright test --config=e2e/inventory/integration.config.mjs
~~~

Os screenshots de 390/1280/1440 estão na documentação de validação da worktree frontend e comprovam UI, não substituem o smoke real. Publicação de branches, PR, integração na main e deploy continuam fora desta execução.
