# ENG-2486: busca e confirmação de requisições

## Entrega e limites

Este incremento melhora a busca local de produtos requisitáveis. O backend pagina antes de calcular reservas e saldos. Os agregados de reserva, integração de itens e quantidades separadas recebem os produtos da página. O cálculo de estoque ainda inclui os produtos equivalentes que a regra existente determina.

A descrição normalizada persistida usa `lower(unaccent(description))`. Um trigger do PostgreSQL mantém esse campo em inserções e alterações, inclusive nas importações em lote que não executam eventos de modelo. A consulta usa essa mesma normalização com um índice GIN de trigramas. `unaccent` não foi declarado imutável.

Os testes preservam pesquisa por todos os termos, sem acentos, fora de ordem e por trechos. Também cobrem códigos curtos, derivação, produtos bloqueados, cursor, reservas parciais, entradas pendentes e equivalência de derivação. Requisições locais sem saída associada continuam sem reserva antecipada. A resposta mantém os campos existentes.

Não há uma restrição nova de três caracteres. A API aceita descrições curtas, e não há catálogo representativo aprovado para decidir quais delas bloquear. O scanner e a busca por códigos continuam sem esse mínimo.

O envio assíncrono foi implementado depois do primeiro incremento de busca. Clientes preparados enviam o cabeçalho `X-Request-Submission: async-v1`. Quando a configuração e o grupo piloto permitem, o backend registra a operação local e responde 202 sem chamadas ao Senior. A fila de banco executa o envio com a identidade original e preserva o avanço por item. Clientes antigos e novas intenções fora do piloto mantêm o contrato síncrono 201.

A configuração permanece desativada por padrão. Web e mobile têm acompanhamento global, alertas de rejeição/timeout e recuperação por chave sem POST automático. Operações com resultado externo incerto não repetem a criação. O contrato, as credenciais criptografadas com prazo, a recuperação, o exemplo de supervisão e os passos de piloto estão em [request-submissions.md](request-submissions.md). Implementação local não equivale a ativação ou aprovação de produção.

## Referência local

A referência do backend foi o commit `396a4aea`. O índice foi medido depois de `96d230f3`. A paginação e os agregados restritos foram medidos em `20aae39d`.

O comando usa a API HTTP da aplicação, com um operador requisitante sintético, sem rede entre cliente e servidor. Os dados são sintéticos e não vêm de uma cópia de produção.

- PostgreSQL 16.1 e PHP 8.4.22 em containers locais, arquitetura aarch64.
- Uma execução sequencial, 15 amostras por busca e dois aquecimentos.
- Catálogos com 5.000 e 20.000 produtos. Cada produto tem estoque em endereço, entrada identificada, entrada parcialmente identificada e linhas de saída pendente/parcial.
- Quatro linhas de estoque por produto, três registros de quantidade separada e quatro versões de integração de saída por produto. Há produtos não requisitáveis e itens de requisição local vinculados a saídas.
- A página comum tem 30 produtos. A pesquisa rara retorna um produto; pesquisa inexistente e pontuação retornam zero.
- OPcache CLI desligado e Xdebug em modo `develop`. O computador e outros processos locais podem introduzir variação.

Os valores abaixo são milissegundos. Eles não comprovam metas de produção, tempo percebido no mobile, saturação do servidor ou tempo de sincronização do ERP.

| Produtos | Pesquisa | Antes p50 / p95 | Só índice p95 | Índice e página p50 / p95 | SQL antes / depois p95 |
| --- | --- | --- | --- | --- | --- |
| 5.000 | Comum | 1.651,747 / 1.809,959 | 164,007 | 124,977 / 154,871 | 1.762,610 / 98,650 |
| 5.000 | Rara | 81,250 / 85,003 | 76,446 | 30,577 / 263,761 | 71,010 / 204,400 |
| 5.000 | Inexistente | 23,985 / 26,164 | 17,313 | 14,130 / 16,566 | 15,750 / 7,260 |
| 5.000 | Trechos fora de ordem sem acentos | 1.692,378 / 2.465,771 | 159,397 | 123,888 / 132,923 | 2.390,810 / 87,480 |
| 5.000 | Pontuação | 11,895 / 14,171 | 16,213 | 9,071 / 9,762 | 4,060 / 2,230 |
| 20.000 | Comum | 339,416 / 429,603 | 390,483 | 220,284 / 297,442 | 378,410 / 239,500 |
| 20.000 | Rara | 281,170 / 379,278 | 276,982 | 45,629 / 48,791 | 358,790 / 32,790 |
| 20.000 | Inexistente | 60,820 / 69,526 | 38,878 | 25,502 / 29,365 | 58,130 / 19,380 |
| 20.000 | Trechos fora de ordem sem acentos | 371,828 / 637,343 | 371,646 | 232,135 / 249,331 | 583,790 / 206,770 |
| 20.000 | Pontuação | 13,516 / 15,362 | 12,819 | 9,221 / 17,908 | 4,620 / 4,070 |

A pesquisa rara com 5.000 produtos teve um valor extremo após a mudança. O p50 caiu, mas o p95 aumentou. Não se deve afirmar que todos os cenários melhoraram pelo p95 desta amostra. Também não se deve atribuir à paginação a diferença obtida apenas pelo índice.

As buscas que retornam produtos executavam entre 13 e 15 consultas SQL. Depois executam entre 14 e 16, porque a reserva agora tem uma consulta separada após a página. Consultas vazias executam entre 3 e 5. A quantidade de consultas inclui autenticação e middleware. O ganho veio do trabalho por consulta, não da redução desse número. A busca não faz chamadas externas.

### Planos SQL

O comando opcional `--explain` grava `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` em arquivos temporários. Ele não imprime tokens nem parâmetros de autenticação.

Na referência de 5.000 produtos, a consulta principal executou um agregado de reserva 5.000 vezes, com até 2.500 linhas por execução. O plano registrado levou 2.491,494 ms. Em 20.000 produtos, o plano mudou e a consulta principal levou 340,609 ms. Essa diferença explica por que aumentar o catálogo não aumentou todos os tempos de forma proporcional.

Após a mudança, a consulta que encontra produtos não contém o agregado de reservas. No plano de 20.000 produtos, a consulta separada de reservas processou 90 linhas relevantes para 30 produtos e levou 2,884 ms. Os planos examinados não registraram leitura de blocos do disco; os dados estavam em cache. A busca comum ainda pode visitar muitos produtos elegíveis antes de ordenar a página. Há espaço para otimizações posteriores, sem mudar critérios de seleção.

## Repetir a medição com segurança

O script exige ambiente `testing`, banco `rex_test`, conexão PostgreSQL em `127.0.0.1:5433` e identidade do servidor em `127.0.0.1:5432`. Ele recusa URLs de conexão e configurações de réplica. Confirme também a proteção existente antes de executar:

```sh
php artisan --env=testing test:database-safety
php tests/Support/benchmark-requestable-products.php \
  --confirm-disposable=rex_test --sizes=5000,20000 --iterations=15 --explain
```

Use somente um banco descartável dedicado. A fixture usa `TRUNCATE ... CASCADE`, insere dados e executa `ANALYZE` dentro de uma transação que o script desfaz ao final. Ela bloqueia outros benchmarks por advisory lock, mas não coordena outros testes ou aplicações. Não rode testes em paralelo nesse banco. Valores de sequências e estatísticas do PostgreSQL podem mudar apesar do rollback. O script nunca é um comando para executar no banco operacional.

Nesta sessão, `5433` no host pertencia a outro projeto. O teste utilizou os containers descartáveis `eng2486-test-db` e `eng2486-test-runner`, sem publicação de portas e com `--network none`. Um encaminhamento de loopback no runner permite manter a configuração exigida pela proteção, sem alterar `phpunit.xml` ou o banco de outro projeto:

```sh
docker exec eng2486-test-runner php artisan --env=testing test:database-safety
docker exec eng2486-test-runner php tests/Support/benchmark-requestable-products.php \
  --confirm-disposable=rex_test --sizes=5000,20000 --iterations=15 --explain
```

A saída JSON registra versões, tamanho do catálogo, concorrência, tempos SQL, contagens e hashes dos arquivos relevantes. Os arquivos temporários desta sessão ficam fora do Git.

## Validação da implementação

A suíte nova `RequestableProductSearchTest.php` passou com 11 testes e 55 assertions na continuação. Os 12 testes direcionados de busca, reservas e disponibilidade do arquivo existente também passaram. A suíte de saldo `StockIOProductMissingAmountServiceTest.php` passou com 14 testes. Os oito casos funcionais de posição de estoque passaram; o caso de autorização continua esperando 404 onde a API responde 403, falha já observada antes da mudança.

A execução completa do primeiro incremento terminou com 881 testes passando, 165 falhando e 3.308 assertions. A primeira tentativa parou no limite de 128 MB; a segunda concluiu com 1 GB. Os testes novos de busca passaram na execução completa. A comparação posterior com a referência `396a4aea` encontrou 164 identidades de falha compartilhadas. A referência completou 1.035 testes, com 871 aprovados, 164 falhas e 3.261 asserções. Um atraso controlado de 1,1 segundo reproduziu a falha adicional de `BackfillOutputSeniorSyncRequestsJobTest` nos dois snapshots; sem o atraso, os dois passaram. O problema é o teste de timestamp tratar a atualização do próprio job como concorrente ao atravessar um segundo. Não houve correção dessa lógica nesta issue. Os relatórios estão em `/tmp/eng-2486-baseline/comparison` e `/tmp/eng-2486-baseline/current-only-diagnosis`. Essa comparação histórica não aprova a suíte completa da entrega assíncrona final.

Depois da revisão, os seis testes novos de proteção de alteração/cancelamento passaram com 23 assertions. O teste existente de concorrência entre cancelamento de item e separação também passou. A revisão estática dessas correções não encontrou outro defeito concreto. Esses testes direcionados não substituem a aprovação da suíte completa.

Pint passou nos arquivos novos e nos serviços alterados. PHPStan passou na busca, disponibilidade e serviços de alteração/cancelamento. O serviço compartilhado `StockIOProductMissingAmountService.php` mantém 11 erros de tipagem que a mesma execução sobre o arquivo da referência também apresentou; os dois filtros acrescentados não adicionaram outro erro.

Na verificação final dos incrementos, o conjunto de busca, proteção de alteração/cancelamento, concorrência e saldo passou com 32 testes e 108 assertions. A revisão em dois eixos identificou corridas entre abas, troca de credencial durante confirmação, resposta atrasada e IDs malformados. Os clientes agora tratam esses casos sem apagar ou substituir outra intenção de envio.

Na primeira entrega parcial, o web passou com 268 testes Node, build Vite e 31 testes Playwright. Depois da implementação assíncrona e das correções finais, a suíte completa isolada passou com 57 testes Playwright. Os 268 testes Node e o build Vite também passaram. O lint focado não encontrou erros; `Requests.jsx` mantém dois avisos existentes de dependências de hooks. Os testes usam somente API controlada, sem ERP ou backend de produção.

A revisão final verificou que o web só marca e reconhece uma falha após apresentar o diálogo em uma aba visível. O acompanhamento pausa após cinco minutos ou 60 consultas e permite atualização manual. Recibos e GETs atrasados não substituem o resultado terminal da mesma operação, inclusive entre abas e na lista/detalhe. Os três defeitos anteriores têm regressões na interface pública; a revisão focada não encontrou novos defeitos P1/P2 nesse trecho.

O backend passou com 23 casos e 230 asserções da API assíncrona. Um conjunto com quatro testes legados de integração seguido dos 23 casos passou com 27 testes e 243 asserções após isolar o processo de cada caso. A correção evita classes que Mockery mantém de outros testes e restaura os handlers do PHPUnit após o Laravel destruir a aplicação. Não desativa a captura de avisos nem muda o guard do banco.

A execução completa final, sobre o código de `50f8b6e8` em PHP 8.4/PostgreSQL 16 descartáveis, terminou com 1.075 testes, 911 aprovados, 164 falhas e 3.568 asserções. As 164 identidades de falha também aparecem na referência `396a4aea`; nenhuma identidade adicional falhou. Isso não torna a suíte verde nem comprova a causa de cada falha compartilhada. A tentativa anterior com 128 MB abortou e não conta como execução completa; a conclusão usou 1 GB. O JUnit e a comparação por identidade estão em `/tmp/eng-2486-runner/FINAL-50f8b6e8-junit.xml` e `FINAL-50f8b6e8-comparison.json`. O log de console da segunda tentativa não registra o trecho final após o encerramento do agente responsável; os totais vêm do JUnit completo, recuperado do container após o processo terminar.

O ambiente do mobile foi desbloqueado na continuação. As dependências de teste foram instaladas, os tipos do renderizador foram alinhados ao React 19 e o TypeScript passou sem novos arquivos de declaração para esconder erros. O Jest completo passou com 13 suítes e 69 testes. O APK de desenvolvimento, Java 21 e Maestro 2.11 permitiram testes reais no emulador Android com a API e a licença direcionadas à fixture local.

Cinco conjuntos nativos passaram. O primeiro cobre aceite, navegação, processamento, confirmação e número externo. O segundo cobre rejeição mantida na lista e no detalhe depois de fechar e reiniciar, sem repetir o alerta. Os três seguintes, no bundle de `51fe2fe`, cobrem timeout, falha de importação após criação externa e perda da resposta inicial com recuperação por GET sem outro POST. Os resultados estão em `/tmp/eng2486-native` e no documento `Rex-Estoque/maestro/request-submission.md`. Uma execução agregada de falha de conexão não terminou e não conta como conjunto aprovado. Falha de armazenamento, troca de escopo e regressão nativa completa de busca/scanner ainda não têm prova integral.

## Implantação da busca

Execute a migration antes de disponibilizar o código que consulta `request_search_description`. Ela declara as dependências `unaccent` e `pg_trgm` antes de criar o trigger e preencher registros existentes. A instalação exige permissões para essas extensões e cria o índice na transação da migration. O preenchimento e a criação do índice podem bloquear alterações de produtos. Antes de aplicar em um banco grande, meça essa instalação em uma cópia autorizada e escolha uma janela de manutenção. Não há execução de migration em produção autorizada por esta entrega.

A função usa `CREATE OR REPLACE` porque a reconstrução de tabelas feita pelos testes não remove funções PostgreSQL. O rollback da migration remove seu trigger, função e coluna. Ele não remove as extensões `unaccent` e `pg_trgm`, que outras consultas e índices podem usar.

### Correção da dependência de normalização

O teste de regressão removeu `unaccent` dentro de uma transação no PostgreSQL descartável, manteve a migration anterior registrada e executou o comando Artisan `migrate` para a migration de busca. Antes da correção, o backfill falhou na linha 34 com `SQLSTATE[42883]: function unaccent(character varying) does not exist`. A migration de busca agora instala a própria dependência com `CREATE EXTENSION IF NOT EXISTS unaccent`; não depende apenas do histórico da migration de julho.

`RequestableProductSearchMigrationTest.php` tem três casos. Eles verificam a dependência ausente, a extensão já instalada com rollback e reaplicação, e uma falha no backfill seguida de nova execução. As mudanças de schema e extensão ocorrem em transações desfeitas ao final dos testes. Os casos também verificam normalização de registros existentes, inserções e alterações futuras, busca pela API e ausência de índice duplicado. O conjunto com os 11 testes existentes de busca passou com 14 testes e 79 asserções em PHP 8.4.22/PostgreSQL 16.1, nos containers isolados `eng2486-test-runner` e `eng2486-test-db`. Pint passou nos dois arquivos PHP alterados.

Uma extensão instalada em schema fora do `search_path` continua invisível para chamadas não qualificadas. A migration anterior não especifica schema, e o banco descartável tinha ambas as extensões em `public`. Esta correção não move extensões compartilhadas nem muda o `search_path`; não comprova qual era a configuração do banco de QA. A suíte completa não foi repetida nesta correção urgente. As falhas de referência da execução anterior continuam registradas acima.

## Dependências identificadas e tratamento seguro

A análise estática encontrou os seguintes pontos no backend atual:

1. `Domain/Request/Services/RequestStoreService.php` autentica no Senior antes da transação e pode importar o solicitante dentro dela. Depois processa cada exportação e importação antes de responder.
2. Esse serviço inclui `identificadorExterno` ao construir o DTO, mas `Domain/Request/DTOs/ExportRequestSeniorDTO.php` não transmite o campo. `SeniorRequestImport.php` consulta por um `numEme` conhecido. Não há evidência de consulta confiável por uma chave local depois da perda da primeira resposta.
3. `SeniorRequestExport.php` usa `Auth::user()`. `SeniorCredentialResolver.php` pode obter senha do token HTTP ou das integrações do usuário. Um worker não herda esse contexto. É necessário definir uma identidade explícita e uma política segura de retenção/decriptação de credenciais, sem trocar o autor por usuário de sistema.
4. `config/queue.php` tem padrão síncrono. Os arquivos Docker e de implantação examinados não demonstram supervisão de um worker de criação, limite de concorrência, prazo de reentrega ou recuperação entre commit e publicação. Isso não prova que não exista configuração externa, mas ela não foi verificada.

Esses pontos descrevem a referência síncrona examinada antes da continuação. A implementação agora captura as credenciais do operador localmente, as armazena criptografadas com prazo em tabela separada, remove-as ao terminar e usa identidade explícita no worker. A conexão de fila dedicada é assíncrona, mesmo quando a fila geral permanece `sync`. A recuperação trata operações sem publicação e execuções interrompidas. Locks de sessão impedem concorrência da mesma operação e limitam o trabalho simultâneo no ERP.

O contrato oficial de consulta/deduplicação por referência externa do Senior continua sem comprovação. A implementação não depende dele para repetir uma criação: uma interrupção durante exportação ou resposta perdida termina com erro de timeout e bloqueia reexportação. O suporte precisa de evidência externa para reconciliar esse caso. O exemplo de supervisão ainda exige instalação e validação no ambiente piloto, com autorização.

Um identificador no payload não é garantia de deduplicação. Timeout ou interrupção após o sucesso externo não autorizam outra criação. Operações incertas precisam de reconciliação com evidência externa. Nada neste incremento adiciona retry automático, altera reserva ou libera separação/entrega.

A revisão identificou que o fluxo síncrono também permitia alterar ou cancelar uma requisição local durante seu envio. Os serviços agora bloqueiam a operação de integração na transação da alteração e respondem 409 para operações `reserved` ou `processing`. A proteção cobre requisição e item, preserva o cancelamento após conclusão e não cria um novo fluxo assíncrono de cancelamento.

A continuação entregou aceitação 202, operação e publicação duráveis, executor sem sessão HTTP, acompanhamento global, alertas de rejeição/timeout e consulta autorizada por chave. Também mediu criações sintéticas com 1, 5 e 20 itens, SQL da aceitação, chamadas externas e tempo local até processamento, conforme [request-submissions.md](request-submissions.md). Esses números não vêm dos tempos de busca e não comprovam metas de produção.

Ainda faltam a validação operacional da supervisão no piloto, o ensaio autorizado das migrations no volume real, medições representativas de rede/dispositivo e carga simultânea. Não houve push, publicação de versão, migration de produção nem chamada real ao Senior nesta entrega.
