# ENG-3116 — Busca operacional de tarefas no servidor

## Escopo aprovado

Ajustar somente o backend na branch `feature/eng-3116`, atualizada por fast-forward com `origin/feature/inventario` (`de13e72b`). Não alterar o frontend web nem o Rex-Estoque. A adaptação do consumidor nativo será sinalizada a Gabriel no card ENG-3268 depois da validação do backend. O retorno para `feature/inventario` e o push ficam para uma próxima etapa.

## Problema

`GET /api/v1/inventory/rounds/{round}/tasks` aceita `scope`, `page` e `per_page`, mas não encaminha `search`. O projetor `InventoryRoundTaskProjection::page` já filtra produto/endereço antes da paginação. O app contorna a lacuna percorrendo todas as páginas autorizadas e filtrando em memória.

## Abordagens consideradas

1. Manter a busca no app: não altera a API, mas preserva o custo de carregar todas as páginas.
2. Encaminhar a busca ao projetor existente: alteração aditiva e pequena, mantém o contrato operacional e a paginação. **Escolhida.**
3. Criar outro endpoint/índice de busca: introduz manutenção e semântica novas sem necessidade comprovada neste recorte.

## Contrato e fluxo

- Acrescentar `search` opcional, anulável, string de até 150 caracteres ao endpoint operacional existente.
- Ausente, nulo, vazio ou somente espaços significa sem filtro. Texto preenchido mantém a busca parcial sem distinguir maiúsculas/minúsculas já implementada no projetor; espaços externos são ignorados.
- Pesquisar código/descrição do produto e nome/hierarquia do endereço na fotografia do inventário, não no cadastro vivo, saldos ou ERP.
- Encaminhar o valor validado por `InventoryRoundExecutionService::tasks` até o argumento `search` do projetor. Manter um valor padrão nulo para compatibilidade dos chamadores atuais do serviço.
- Filtrar somente dentro de `mine` ou `open`, da rodada e do contexto autorizados. Aplicar a busca antes de `count`, `offset` e `limit`.
- Preservar `data.context`, `data.scope`, `data.data` e `data.meta`; totais e última página refletem a consulta filtrada. Uma página sem itens não implica `total: 0`.
- Tipo inválido e texto acima do limite retornam 422. Permanecem 401/403/404, capacidades e leitura pós-fechamento existentes.
- GET continua passivo: não registra ingresso, início, atribuição, contagem ou auditoria. Nenhuma migration ou mudança quantitativa.

## Testes

Regressões HTTP/PostgreSQL para código, descrição, nome/hierarquia, busca vazia/nula, paginação filtrada, página vazia versus ausência de resultados, isolamento `mine/open`/rodada/contexto, identidade/autorização dos quatro perfis, fotografia versus cadastro atual, cegueira e ausência de mutações. Validar arrays e limite de 150 caracteres. Executar também regressões de execução/contexto/assunção concorrente e Pint focal.

O runtime de testes será isolado, sem copiar configuração privada e sem publicar portas do PostgreSQL. Executar `test:database-safety` e confirmar `rex_test` antes das suítes.

## Entrega e limites

Atualizar os contratos em `docs/inventory-rounds-api.md` e `docs/inventory-operational-api.md`, registrar resultados e avisar a ENG-3268 com exemplo de query, formato de resposta e orientação para substituir a varredura local por paginação filtrada. Indicar explicitamente que a correção ainda não estará em `feature/inventario` nem implantada.
