# ENG-3270 — Validação do backend operacional

## Entrega

- Contexto operacional dedicado, extensões aditivas de descoberta/tarefas e capacidades compartilhadas com a validação dos comandos.
- Leitura cega autorizada após fechamento, incluindo contagem vigente própria; replay preservado como recibo da revisão original.
- Conflitos distintos de rodada concluída/desconsiderada, sem alterar schema, estoque/ERP, desbloqueio, ações gerenciais ou o app.
- Contrato para o consumidor nativo: [inventory-operational-api.md](../../inventory-operational-api.md).

## Ambiente seguro

Validação em 2026-11-13, na branch `feature/inventario`. Base anterior à implementação: `be2ac774` (somente o desenho aprovado foi acrescentado sobre `1aed692a`).

Foi criada uma cópia isolada de código e dependências, sem copiar `.env`/`.env.testing` da aplicação principal. Ambiente PHP 8.4.27, PostgreSQL 16.1 descartável e rede Docker interna exclusiva. O banco verificado foi `rex_test`, em `127.0.0.1:5432` no namespace compartilhado dos dois containers de teste. O PostgreSQL de desenvolvimento não foi usado.

`php artisan --env=testing test:database-safety` confirmou `environment=testing`, conexão `pgsql`, configuração e conexão efetiva no banco esperado antes das execuções. Os `.env` da cópia descartável não contêm credenciais da aplicação principal; a configuração de depósito de fixture é `REX_INVENTORY_EXPEDITION_DEPOT_CODE=004`. `LOG_CHANNEL=single` evita imprimir no console os erros sintéticos dos testes de rollback. Os testes novos usam `Http::preventStrayRequests()`.

As suítes foram executadas serialmente no banco exclusivo; somente os workers explícitos dos testes de concorrência usam processos/conexões separados. A cópia de execução recebeu os PHP modificados antes dos testes finais.

## Testes e resultados

### RED inicial

Antes da implementação, a primeira versão da suíte nova reproduziu 15 falhas: rota inexistente, contrato incompleto, leituras pós-fechamento recusadas e conflitos incorretos.

### Focais: **38 passaram, 899 assertions**

```bash
php artisan --env=testing test:database-safety
LOG_CHANNEL=single ./vendor/bin/pest \
  tests/Feature/Inventory/InventoryOperationalContextTest.php \
  tests/Feature/Inventory/InventoryRoundExecutionTest.php \
  tests/Feature/Inventory/InventoryCountCommandTest.php \
  tests/Feature/Inventory/InventoryReviewWorkflowTest.php \
  tests/Feature/Inventory/InventoryReviewConcurrencyTest.php \
  --compact --display-warnings
```

Execução final sem falhas ou warnings. Cobre:

- Contexto mínimo, ingresso individual, capacidades de tarefa aberta/própria e modalidade congelada ausente.
- Os cinco estados pós-início, rodadas pendentes/em andamento/concluídas/desconsideradas, fechamento real e descoberta de recontagem configurada.
- Replay após fechamento, recibo antigo versus contagem vigente e ausência de duplicação de revisões, leituras e eventos.
- GETs sem mutações de configuração, ingresso, propriedade, versões, eventos ou evidências.
- Autenticação, identidade de tarefa/rodada, contexto fora do escopo, participante removido, acesso revogado e ausência de bypass Admin/Master.
- Cegueira: sem saldo/resultado oficial/quantidade alheia; propriedade e autoria exigidas para expor contagem.
- Corridas reais PostgreSQL: gravação vencedora seguida de fechamento/replay/leitura; fechamento vencedor seguido de nova gravação recusada; leitura aguardando commit **ou rollback** do fechamento e projetando estado coerente.

### Regressão completa: **215 passaram, 1 falhou, 2297 assertions**

```bash
LOG_CHANNEL=single ./vendor/bin/pest \
  tests/Feature/Inventory tests/Unit/Inventory \
  --compact --display-warnings
```

A única falha foi `InventoryStartConcurrencyTest`: `allows a disjoint inventory to start without waiting on another product`, linha 134. O worker excede o timeout de 15 segundos enquanto o teste mantém a transação do primeiro início aberta. Esse teste não foi alterado nesta entrega.

**Confirmação de preexistência:** os serviços/rota/controller/worker modificados foram temporariamente substituídos, somente na cópia descartável, pelos arquivos de `be2ac774`. O mesmo caso isolado apresentou o mesmo `ProcessTimedOutException` de 15 segundos (1 falha, 2 assertions). Os arquivos da implementação foram restaurados na cópia antes das validações finais. Não foi atribuído sucesso a essa regressão nem alterado o fluxo de início para contorná-la.

Na primeira execução ampla também houve três falhas de workers de assunção sem a configuração de depósito no ambiente filho; após configurar a fixture no `.env.testing` descartável, todas passaram. Isso não exigiu alteração no código desses workers/testes.

### Regressão excluindo apenas a falha confirmada na base: **215 passaram, 2295 assertions**

```bash
LOG_CHANNEL=single ./vendor/bin/pest \
  tests/Feature/Inventory tests/Unit/Inventory \
  --filter='/^(?!.*allows a disjoint inventory to start without waiting on another product).*$/' \
  --compact --display-warnings
```

Execução sem falhas ou warnings. Nenhum teste foi editado, desabilitado ou marcado como skipped para obter esse resultado; o filtro está explícito acima.

### Formatação e diff

`./vendor/bin/pint` e `./vendor/bin/pint --test` aprovaram os nove PHP desta entrega:

- `Domain/Inventory/Services/InventoryOperationalPolicy.php`
- `Domain/Inventory/Services/InventoryRoundExecutionService.php`
- `Domain/Inventory/Services/InventoryCountCommandService.php`
- `Domain/Inventory/Services/InventoryRoundTaskProjection.php`
- `app/Http/Controllers/Inventory/InventoryRoundExecutionController.php`
- `routes/api.php`
- `tests/Feature/Inventory/InventoryOperationalContextTest.php`
- `tests/Feature/Inventory/InventoryReviewConcurrencyTest.php`
- `tests/Support/InventoryConcurrencyWorker.php`

`git diff --cached --check` foi executado em um índice temporário contendo apenas os arquivos/hunks desta entrega, incluindo os arquivos novos. No documento compartilhado de rodadas, esse índice inclui somente a seção operacional; o índice real e os trechos gerenciais locais não foram alterados. O working tree compartilhado contém alterações de terceiros; uma execução global também apontou whitespace em `webservices/combrSoelXProdutos/ListarProdutos.txt`, que não foi corrigido nem incluído nesta entrega.

## Preservação e limites

Foram preservadas as alterações locais anteriores em `InventoryRoundController.php`, `InventoryParticipantIndexRequest.php`, `InventoryRoundSearchTest.php` e nos trechos gerenciais de `inventory-rounds-api.md`, bem como o trabalho concorrente em importação de produtos. Não modificar/commitar esses trechos junto ao contrato operacional.

O commit `be2ac774` contém somente o desenho aprovado; a implementação fica em commit próprio, sem incluir o trabalho local anterior. O responsável autorizou o commit e o push após a validação. Nenhuma alteração no Rex-Estoque ou deploy. A integração nativa, retomada das telas e tratamento visual das capacidades continuam com Gabriel. A falha preexistente de início concorrente de inventários disjuntos continua uma limitação conhecida e deve ser tratada separadamente.

Logs locais da execução: `/tmp/rex-eng3270-focused-final.log`, `/tmp/rex-eng3270-inventory-final.log`, `/tmp/rex-eng3270-baseline-disjoint.log`, `/tmp/rex-eng3270-inventory-excluding-baseline.log` e `/tmp/rex-eng3270-preflight-final.log`.
