# ENG-3116 — Validação da busca operacional de tarefas

## Escopo e base

Correção somente no backend, em `feature/eng-3116`, após fast-forward da base `origin/feature/inventario` em `de13e72b`. O desenho aprovado foi registrado em `5795fa07`.

`GET /api/v1/inventory/rounds/{round}/tasks` agora valida `search` opcional/anulável (string, até 150 caracteres) e o encaminha ao filtro existente do projetor. Não houve alteração no algoritmo de busca, schema, regras de propriedade, comandos, capacidades, estoque ou ERP. Frontend web e app nativo não foram modificados.

Contratos: [rodadas](../../inventory-rounds-api.md) e [contexto operacional](../../inventory-operational-api.md).

## Ambiente seguro

Execução em 2026-11-13 com PHP 8.4 e PostgreSQL 16.1 descartável. Código e dependências foram copiados para runtime separado, sem copiar `.env` ou credenciais da aplicação. Os arquivos de ambiente descartáveis tinham apenas configuração de testes. PostgreSQL sem porta publicada, em namespace Docker sem acesso externo, com armazenamento temporário em memória.

`php artisan --env=testing test:database-safety` confirmou ambiente `testing`, banco `rex_test` e conexão efetiva/configurada em `127.0.0.1:5432` dentro desse namespace. Nenhuma suíte/migration usou o PostgreSQL compartilhado. Os testes novos usam `Http::preventStrayRequests()` e `Http::assertNothingSent()`.

## RED → GREEN

Arquivo novo: `tests/Feature/Inventory/InventoryOperationalTaskSearchTest.php`.

- Antes de alterar controller/serviço: **24 falhas, 10 passaram, 322 assertions**. O servidor ignorava a busca e retornava o total sem filtro; arrays, inteiros/booleanos JSON e texto acima de 150 caracteres não eram validados.
- Depois da alteração mínima: **34 passaram, 467 assertions**, sem falhas ou warnings.

```bash
./vendor/bin/pest tests/Feature/Inventory/InventoryOperationalTaskSearchTest.php --compact --display-warnings
```

Cobertura:

- Código/descrição do produto e nome/hierarquia do endereço fotografados, com caixa e espaços externos distintos.
- Escopos `mine`/`open`, paginação após o filtro, totais/última página, ordenação e exclusão de tarefas alheias/de outra rodada.
- Ausência, nulo, vazio, espaços, tipos inválidos e limite de 150 caracteres.
- Cadastro vivo alterado não muda os resultados da fotografia.
- Preservação do contexto, capacidades e projeção cega; nenhum saldo retornado.
- GETs sem modificar cabeçalhos, participantes, tarefas, contagens, auditoria, bloqueios ou quantidades dos itens.
- Master/Admin/Armazenador/Separador; autenticação, participação, revogação, setor e depósito revalidados.
- Leitura filtrada após conferência, aprovação pendente, aprovação e reprovação, sem conceder escrita.

## Regressão ampla e falha preexistente

```bash
./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory --compact --display-warnings
```

Resultado completo: **249 passaram, 1 falhou, 2764 assertions**. A única falha foi `InventoryStartConcurrencyTest`: `allows a disjoint inventory to start without waiting on another product`, linha 134. O worker de início excedeu o timeout existente de 15 segundos.

A preexistência foi confirmada nesta execução: somente na cópia descartável, controller e serviço foram restaurados para `de13e72b`. O mesmo teste isolado voltou a falhar com o mesmo timeout (**1 falha, 2 assertions**), sem a correção de busca. Os dois arquivos da implementação foram restaurados no runtime antes da validação final. Não foram alterados o teste, o timeout ou o início de inventários para contornar o problema.

Regressão final excluindo **somente esse caso confirmado na base**:

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

Resultado: **249 passaram, 2762 assertions**, sem falhas ou warnings. Inclui a suíte nova, execução/contexto, configuração, claims concorrentes PostgreSQL, contagens, revisão, consultas e schemas. Nenhum teste foi desabilitado ou marcado como skipped no código.

## Checks e limites de entrega

- Pint real em PHP 8.4: **3 arquivos aprovados** (controller, serviço e teste novo).
- Lint PHP 8.2 dos mesmos arquivos: aprovado.
- `git diff --check`: aprovado; diff de implementação limitado a dois PHP, com quatro linhas adicionadas e uma substituída.
- Nenhum E2E mobile/dispositivo foi executado; a adaptação permanece na ENG-3268, para Gabriel.
- Correção preparada em commit local de `feature/eng-3116`. Sem merge de volta para `feature/inventario`, push ou deploy nesta etapa.

Logs locais: `/tmp/rex-eng3116-search-red.log`, `/tmp/rex-eng3116-search-green.log`, `/tmp/rex-eng3116-search-regression.log`, `/tmp/rex-eng3116-search-baseline.log` e `/tmp/rex-eng3116-search-regression-filtered.log`.
