# ENG-3113 — Evidências da implementação

**Data:** 2026-11-06. **Branch:** feature/eng-3113, em worktrees próprias de backend e frontend.
**Destino de revisão:** feature/inventario. Nenhuma publicação, integração na main ou implantação foi realizada.

## Entrega

- Rascunhos gerais/cíclicos manuais persistidos, compartilhados entre gestores autorizados.
- Cabeçalho/seleção relacionais, autoria preservada, versão e atualização atômica.
- Catálogo de produtos vinculados à Expedição, sem filtro de saldo ou limite funcional de 100 produtos.
- Grupos descobrem produtos; todos os endereços desses produtos na Expedição são conservados.
- Seleção salva e endereços reconsultados; perda de elegibilidade exige revisão.
- API administrativa protegida pelo setor/nível ativo do token, inclusive para Master.
- Web em Dados → Abrangência → Revisão, com listagem/detalhe reais, sem início ou distribuição.
- Sem consultas ao ERP, mudanças de estoque, fixture/storage de inventário no runtime ou importação de progresso do protótipo.

Contrato efetivo: [API do inventário manual](../inventory-manual-api.md).
Requisitos e recorte: [desenho aprovado](../plans/2026-11-05-eng-3113-inventario-manual-design.md).

## Ambiente isolado

Backend executado com PHP **8.4.27**, dependências do lockfile instaladas na worktree, sem symlink de vendor ou cópia do .env oficial. PostgreSQL **16.1**, banco descartável rex_test, rede Docker interna sem acesso ao ERP. O preflight confirmou APP_ENV=testing, conexão pgsql, host de loopback e identidade real do banco antes de qualquer suíte que altera schema.

O guard existente compara porta configurada e porta interna do PostgreSQL. No runtime descartável ambas foram configuradas igualmente; o compose e a configuração de banco da aplicação principal não foram alterados.

Frontend executado com Node **20.20.2** e Chromium. URLs/portas foram fornecidas pelo ambiente, não gravadas como valores de instância no código.

Para o servidor HTTP de testes, display_errors ficou desabilitado: dependências legadas geram depreciações no PHP 8.4 e não podem prefixar respostas JSON com HTML. Não houve atualização de pacotes nem edição de vendor.

## Validações aprovadas

| Gate | Resultado |
| --- | --- |
| Preflight test:database-safety | Banco descartável confirmado |
| Pest: Inventory + regressão de produtos/endereços | **78 testes, 321 assertions, zero falhas** |
| Node: npm test do frontend | **454 testes, zero falhas** |
| ESLint de todos os JS/JSX/MJS alterados | Sem erros ou avisos |
| Build Vite em Node 20 | Aprovado; aviso preexistente de chunk >500 kB |
| Playwright: UI/contrato isolado | **12 testes aprovados** |
| Playwright: API/PostgreSQL reais, dois usuários | **1 teste aprovado** |
| Pint e diff --check | Aprovados antes dos commits |

Comandos focais, no runtime PHP 8.4 e ambiente de testes já configurados:

~~~bash
php artisan --env=testing test:database-safety
./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory tests/Feature/Product/RequestableProductSearchTest.php tests/Unit/Address
~~~

As suítes cobrem autorização em todas as rotas, contexto de Master, catálogo sem saldo, mais de 100 produtos, paginação, busca/filtros cadastrais, grupos sobrepostos/aninhados, todos os endereços, perda de elegibilidade, atomicidade e concorrência.

A busca por unidade foi conferida contra o comportamento do seletor do protótipo. A digitação rápida recebeu debounce de 250 ms: um teste que inicialmente observava seis consultas de catálogo passou a observar somente uma, sem perder a seleção.

O teste de alteração de endereços durante uma consulta foi escrito antes da proteção: inicialmente retornava 500. A implementação agora retorna 503 com orientação de nova tentativa, sem devolver uma abrangência parcial; a tentativa seguinte inclui os endereços atualizados.

## Integração real entre usuários

Duas sessões de navegador independentes usaram tokens reais de Administrador e Master, somente no banco descartável:

1. A criou um rascunho com produto ligado a dois endereços.
2. B reabriu o registro criado por A.
3. Ambos editaram a mesma versão; B salvou primeiro.
4. A recebeu 409 e permaneceu no formulário, sem sobrescrever B.
5. A descartou explicitamente a edição, recarregou e confirmou a mudança de B após refresh.
6. Verificação no banco confirmou situação rascunho, versão 2, criador A, última alteração B e quantidades WMS inalteradas nos dois endereços.

Nenhuma API de negócio foi interceptada nesse teste. Arquivos de sessão ficaram fora do Git. Isso não equivale a homologação com dados oficiais, usuários da operação ou dispositivo nativo.

## Pendências preexistentes dos gates globais

- **composer test-safe:** o primeiro preflight passou; o encadeamento do segundo @php foi interpretado pelo shell como comando inexistente (exit 127). O script não foi alterado. Os comandos foram executados separadamente para a regressão.
- **Suíte backend completa:** não concluída. Apresentou três falhas em MarkConcludedPickingOrdersWithSeparatedItemsAsDeliveredPartialMigrationTest e depois ficou aguardando lock no helper legado TruncateDatabase; a execução isolada foi interrompida.
- As **três falhas de migração foram reproduzidas na base main a6b49a5f**, sem a implementação da issue: a factory omite responsible_id obrigatório em picking_orders. Não foram corrigidas neste recorte. A espera por lock é registrada como limitação da execução geral, não como gate aprovado.
- **Lint global frontend:** 4 erros e 99 avisos em módulos não alterados. Erros em StockOutputAditionalInfos/AditionalInfos, Customer/ActiveCustomers, Customer/InactiveCustomers e Users/UsersTrashed. O lint focal da entrega está limpo.
- WebKit/Safari, Firefox, operação real da Rex e aplicativo nativo não foram homologados nesta etapa.

Não há declaração de sucesso da suíte completa ou do lint global.

## Evidência visual e reprodução

No frontend: docs/validation/inventario/eng-3113.md e e2e/inventory/persisted/README.md.
Capturas versionadas de UI usam dados sintéticos exclusivos dos testes e larguras 390, 1280 e 1440 px. O bundle e o grafo da entrada persistida foram inspecionados sem dependências de fixture/store/transições simuladas.

A configuração da instância deve fornecer REX_INVENTORY_EXPEDITION_DEPOT_CODE como string; para a Rex, o mapeamento aprovado é 004. Não foi alterado .env de nenhuma árvore principal.
