# ENG-3116 — Plano de implementação da busca operacional

Desenho aprovado: [operational-task-search-design](2026-11-13-eng-3116-operational-task-search-design.md).

A skill `writing-plans` não está instalada nesta sessão; este plano manual mantém a execução por etapas verificáveis.

## 1. Atualizar a branch da issue

- [x] Confirmar worktree `rex-back-eng-3116` limpa.
- [x] Buscar `origin/feature/inventario` e avançar `feature/eng-3116` até `de13e72b` sem rebase/force.
- [x] Documentar e commitar o desenho aprovado, sem alterar as outras worktrees.

## 2. Reproduzir a lacuna com testes

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

- [x] Criar fixture com fotografia real, produtos/endereço de busca controlados, duas rodadas e tarefas próprias, abertas e alheias.
- [x] Exigir filtro por código, descrição, nome e hierarquia em ambos os escopos, ignorando caixa e espaços externos.
- [x] Validar paginação/totais filtrados, página fora do intervalo e ausência real de correspondências.
- [x] Garantir compatibilidade de busca ausente/nula/vazia/espaços, tipos inválidos e limite de 150 caracteres.
- [x] Cobrir participação/autenticação, quatro perfis, contexto, cegueira, fotografia versus cadastro vivo e leitura passiva.
- [x] Executar no PostgreSQL descartável após `test:database-safety`; registrar falhas pelo filtro ignorado/validação ausente antes de implementar.

## 3. Implementar o encaminhamento mínimo

Arquivos:

- `app/Http/Controllers/Inventory/InventoryRoundExecutionController.php`: validar `search` com `sometimes`, `nullable`, `string`, `max:150` e passá-lo ao serviço.
- `Domain/Inventory/Services/InventoryRoundExecutionService.php`: acrescentar parâmetro opcional nulo e encaminhá-lo ao projetor junto ao mapper operacional existente.

Não alterar algoritmo do projetor, ordenação, autorização, capacidades, locks, schema ou comandos operacionais.

- [x] Fazer a suíte nova passar: 34 testes, 467 assertions.
- [x] Executar regressões de preparação/configuração/integridade/execução/claims/contexto/contagens/revisão e unidades de inventário. Suíte completa: 249 passaram e 1 timeout reproduzido na base; excluindo somente esse caso, 249 passaram/2762 assertions. Ver evidências.
- [x] Executar Pint focal, lint PHP e `git diff --check`.

## 4. Documentar e sinalizar

- [x] Atualizar `docs/inventory-rounds-api.md` e `docs/inventory-operational-api.md` com parâmetro, limites, filtros e paginação.
- [x] Registrar ambiente, comandos, resultados e limites em `docs/validation/eng-3116/operational-task-search.md`.
- [x] Preparar commit local da correção em `feature/eng-3116`.
- [x] Preparar o handoff para Gabriel na ENG-3268: contrato pronto na branch da issue, exemplo `scope=mine&search=parafuso&page=1&per_page=50`, substituição da varredura local por paginação do servidor, necessidade de integração/publicação antes de usar no ambiente. Publicar o comentário após criar o commit para incluir seu hash.
- [x] Não fazer merge de volta, push, deploy nem alteração mobile nesta etapa.
