ENG-2486 · Análise de código e proposta

Menos espera na busca e na criação de requisições

Plano para o aplicativo de almoxarifado. A prioridade é reduzir o trabalho necessário para mostrar produtos e tirar a comunicação com o ERP da espera do usuário, sem perder rastreabilidade nem duplicar requisições.

Backend · release/v1.10.6 · 59210bf6Web · release/v1.10.6 · c2953103Mobile · main · 977fffe

O que a análise permite concluir

A confirmação depende do ERP por construção. O backend salva a requisição local, mas só responde após exportar os itens e importar os dados do Senior. A busca consulta o banco local, porém inclui cálculos de reserva e saldo além do filtro de descrição.

Esta é uma análise estática. Não houve consulta ao banco de produção, envio ao ERP nem teste de carga. Não há tempos medidos ou prova de saturação do servidor. Os pontos abaixo distinguem comportamento confirmado de custo que ainda precisa de medição.

Primeira frente

Buscar só o necessário

Manter a busca por termos sem acento, indexar a expressão correta e calcular disponibilidade apenas para a página encontrada. No mobile, impedir buscas curtas e respostas antigas sobrepondo a pesquisa atual.

Segunda frente

Confirmar localmente e sincronizar depois

Responder após persistir a requisição e o trabalho de sincronização. Mostrar o estado real do envio ao ERP. Repetir apenas operações seguras e reconciliar respostas incertas antes de reenviar.

Evidências no código atual

Confirmado

1. O mobile já filtra por descrição no servidor

A criação usa GET /api/v1/product/requestable com description. O backend separa palavras e exige que todas ocorram na descrição, em qualquer ordem, sem acentos.

unaccent(products.description) ILIKE unaccent('%termo%')
AND ... para cada termo da pesquisa

Não é preciso adicionar o filtro. É preciso melhorar sua execução sem mudar o resultado esperado. As migrations examinadas habilitam unaccent, mas não criam índice de trigramas para essa expressão.

Rex-Estoque/src/pages/Requisicoes/CriarRequisicao/CriarRequisicao.tsx:200–211
rex-back/Domain/Product/QueryBuilders/ProductQueryBuilder.php:27–60
rex-back/database/migrations/2026_07_29_180000_enable_unaccent_extension.php

Custo a medir

2. A pesquisa carrega cálculos operacionais

Antes de paginar, o controller acrescenta um agregado de reservas. Ele combina três consultas com UNION ALL, agrupa por produto e consulta integrações e quantidades separadas.

Essa consulta não recebe os IDs da página. O saldo físico e de entradas é calculado depois da paginação e já recebe os IDs dos produtos encontrados. Ainda há agregados internos de picked_items sem esse recorte.

A extensão da leitura depende do plano do PostgreSQL. O código aponta onde medir; não prova uma varredura completa em produção.

rex-back/app/Http/Controllers/Product/ProductController.php:256–275
rex-back/Domain/Product/Services/ProductAvailabilityService.php:124–278
rex-back/Domain/StockIO/Services/StockIOProductMissingAmountService.php:79–146, 313–385

Confirmado

3. O mobile espera 600 ms antes de pesquisar

O dropdown já tem debounce de 600 ms. A tela não exige tamanho mínimo para descrição e não cancela a chamada anterior nem descarta resultados de uma pesquisa antiga.

A tela consome só data da primeira página; não carrega links.next. O backend usa paginação por cursor de 30 produtos. Pesquisas amplas podem esconder o produto desejado e levar o usuário a repetir a busca.

No web, o componente equivalente espera 1.000 ms e oferece mais páginas, mas também não protege essa busca contra respostas fora de ordem.

Rex-Estoque/src/components/DropdownWithSearch/DropdownWithSearch.tsx:159–172
Rex-Estoque/src/pages/Requisicoes/CriarRequisicao/CriarRequisicao.tsx:200–225
rex-back/app/Models/AbstractModelDefault.php:26
rex-front/src/pages/StockOutputs/components/NewRequest/components/ProductRequestableSearch/ProductRequestableSearch.jsx:42–81

Confirmado

4. Há envio e importação a cada item

O backend autentica o usuário no Senior, grava a requisição e os itens, e executa um laço. Cada item faz um envio SOAP e chama dispatch_sync(new SeniorSyncRequestsJob(...)).

O job importa a requisição com Exportar_6 e processa os registros retornados. Para N itens novos processados com sucesso, esse trecho faz N envios e N importações, além da autenticação e de possíveis consultas de usuário. O app aguarda o conjunto.

rex-back/Domain/Request/Services/RequestStoreService.php:64–165, 298–345
rex-back/app/Jobs/Senior/SeniorSyncRequestsJob.php:79–148
rex-back/Domain/Shared/Integrations/Senior/SeniorRequestImport.php:20–39
Rex-Estoque/src/pages/Requisicoes/CriarRequisicao/CriarRequisicao.tsx:358–397

Confirmado

5. Já existe persistência de falhas e idempotência

A operação fica em integrations.parameters, com chave, fingerprint, estado, número externo, próximo item e último erro. Erros funcionais de exportação ficam como failed; resultados incertos e falhas de sincronização ficam como unknown.

O mobile não envia Idempotency-Key. Sem a chave, o backend gera uma nova a cada tentativa. O web já envia uma chave durante a confirmação. Logo, a proteção existente não cobre novas tentativas do mobile como deveria.

rex-back/Domain/Request/Services/RequestStoreService.php:47–61, 174–211, 365–381
rex-back/Domain/Integration/Services/IntegrationOperationService.php:18–60
Rex-Estoque/src/domain/erp/services/Request.ts:83–103
rex-front/src/pages/StockOutputs/components/NewRequest/NewRequest.jsx:171–194, 239–246

Confirmado

6. Há dependências que impedem uma troca simples por job

A exportação resolve credenciais com Auth::user(). Um worker não herda a sessão HTTP. A configuração de fila tem sync como padrão, então apenas trocar o dispatch não garante execução em segundo plano.

O recurso da API não expõe um estado específico de sincronização. O fluxo de falha registra dados e logs, mas não envia uma notificação de falha ao solicitante nesse caminho. Cada chamada SOAP cria um client com cache de WSDL desabilitado, outro custo a medir.

rex-back/Domain/Shared/Integrations/Senior/SeniorRequestExport.php:31, 86–89
rex-back/Domain/Shared/Integrations/Senior/SeniorImportBase.php:13–23
rex-back/config/queue.php:16
rex-back/Domain/Request/Resources/RequestResource.php:28–44

Proposta para a busca de produtos

Reduzir latência de rede, trabalho no banco e espera artificial. A busca não acessa o Senior diretamente; colocar a criação em fila não corrige, por si só, o custo desse endpoint.

MudançaComo executarCuidados
Busca indexável sem acentoEscolher uma descrição normalizada persistida e índice GIN com pg_trgm, ou uma expressão indexável cuja semântica corresponda à busca. Preencher registros existentes e manter a normalização nas importações e alterações.Não criar um índice só em description e esperar que ele atenda unaccent(description). O unaccent padrão não é imutável; um índice de expressão exige tratar essa restrição corretamente. Preservar busca por trechos, ordem livre e acentos.
Paginar antes de calcular reservasLocalizar os produtos requisitáveis, obter a página por cursor e resolver reservas e saldos em lote para seus IDs. Restringir agregados internos de separação aos registros relevantes quando o plano mostrar ganho.Hoje a consulta não filtra nem ordena por disponibilidade, o que permite essa separação. Preservar reservas parciais, entradas pendentes, setor e equivalência entre produtos/derivações.
Reduzir solicitações desnecessáriasPropor mínimo de 3 caracteres para descrição e debounce entre 250 e 350 ms. Buscar código e leitura de scanner por igualdade, sem aplicar o mínimo de descrição. Cancelar chamadas anteriores e aceitar só a resposta da pesquisa atual.Validar a necessidade de termos de 1 ou 2 caracteres com a operação. Explicar o mínimo na interface. Cancelar no cliente não garante que o banco interrompa a consulta.
Permitir continuação no mobileConsumir links.next com uma única página em andamento, sem duplicar itens. Limpar cursor e resultados ao trocar o filtro. Mostrar carregamento e erro dentro da lista.Não baixar o catálogo completo nem trocar a paginação por chamadas repetidas até esgotar os resultados.
Diminuir a respostaDefinir os campos usados pela tela e remover relações sem uso somente após verificar todos os consumidores. Considerar um recurso específico de autocomplete compartilhado entre mobile e web.A tela usa código, descrição, unidade e disponibilidade. Não remover campos de um contrato existente sem compatibilidade.
Cache apenas onde for seguroConsiderar cache de metadados do catálogo por consulta, setor e permissões após as correções SQL. Resolver o saldo atual separadamente ou indicar sua idade.Não tratar saldo em cache como autorização para entregar estoque. Validar a regra de disponibilidade na ação que efetivamente reserva ou movimenta quantidades.

Os testes existentes de produtos requisitáveis cobrem busca sem acento, termos em ordem diferente e regras de disponibilidade. Eles devem continuar passando. Referência: rex-back/tests/Feature/Product/BackfillAdminProductReadAndPriorityTest.php.

Proposta para sincronizar com o ERP em segundo plano

A requisição local já existe antes do envio. A mudança principal é tornar essa persistência uma confirmação útil ao usuário e transformar a sincronização em trabalho durável, recuperável e visível.

O usuário confirma no app com uma chave estável.
A API valida e grava requisição, itens e operação de envio na mesma transação.
A API responde 202 com o ID local e o estado de sincronização.
Um worker assume a operação e envia ao Senior com a identidade autorizada.
O worker registra o número do ERP e importa o resultado.
O app mostra um aviso pequeno de envio, sem impedir a navegação.
Se o ERP rejeitar ou não responder no prazo, o app abre um alerta de erro na tela.
Aguardando envio

Requisição registrada localmente. Ainda não confirmada no ERP.

Enviando ao ERP

Aviso pequeno com loading, visível durante a navegação. Não oferecer outro envio simultâneo.

Confirmada no ERP

Aviso pequeno de sucesso após confirmação. A aprovação e os estados operacionais continuam separados.

Erro de envio

Rejeição e timeout abrem um alerta de erro. Não usar toast para erros nem apresentar timeout como envio em andamento.

Mensagens e comportamento aprovados

ResultadoApresentaçãoMensagem
Envio em andamentoAviso pequeno com loading, sem bloquear o uso do app.Requisição #123 registrada. Enviando ao ERP...
ERP confirmouAviso pequeno de sucesso, que desaparece após alguns segundos.Requisição #123 enviada ao ERP.
ERP rejeitouAlerta de erro na tela, com motivo e botões "Ver requisição" e "Fechar".Não foi possível enviar a requisição #123. Motivo: [motivo informado pelo ERP].
Timeout do ERPAlerta de erro na tela, com botões "Ver requisição" e "Fechar". Encerrar o loading.Erro ao enviar a requisição #123. Não recebemos resposta do ERP dentro do prazo (timeout).

Não usar push neste fluxo. Erros continuam visíveis na lista e no detalhe após fechar o alerta. Se o app estiver fechado ou em segundo plano, apresentar o erro ainda não exibido ao voltar ao app, sem abrir alertas duplicados para a mesma falha.

Timeout é um erro de comunicação e deve aparecer como erro para o usuário, sem a mensagem "estamos verificando". Internamente, a ausência de resposta não comprova que o ERP deixou de criar a requisição. Preservar essa distinção apenas para impedir reenvio e duplicação; ela não substitui o alerta de timeout.

Requisitos antes de ativar o fluxo

  1. Chave idempotente no mobile. Gerar uma chave por intenção de criação e mantê-la em novas tentativas do mesmo conteúdo. Persistir ID e chave quando necessário para sobreviver a reinício. Conteúdo diferente exige uma nova intenção, sem duplicar silenciosamente a anterior.
  2. Envio durável. Gravar a operação ou um registro de saída na mesma transação da requisição. Publicar após commit e ter recuperação de operações que ficaram sem job. Um dispatch isolado após o commit deixa uma janela de perda se o processo morrer antes de publicar.
  3. Identidade do usuário. Refatorar o exportador para receber uma identidade explícita. Definir como o worker recupera credenciais autorizadas com segurança, inclusive quando a senha só existe no contexto do token. Não copiar senha ou token em texto aberto para o payload da fila. Preservar autoria e permissões do Senior.
  4. Fila real e concorrência. Usar conexão assíncrona e worker supervisionado. Definir exclusão por operação, tempo máximo, backoff e limites de concorrência que o ERP suporta. Fazer retry_after superar o tempo de execução esperado para evitar reentrega com execução ainda ativa.
  5. Proteção interna contra duplicação. Aproveitar failed e unknown no backend. A interface apresenta timeout como erro de comunicação. Antes de repetir criação ou item após ausência de resposta, consultar o ERP por referência verificável. Não esconder o erro com loading ou prometer uma verificação ao usuário. O campo identificadorExterno existe no payload, mas o código não comprova garantia de deduplicação no Senior.
  6. Alerta de erro e consulta de status. Expor estado, ID local, número externo, horário e erro sanitizado. Manter o aviso pequeno apenas durante o envio e no sucesso. Rejeição e timeout exigem alerta de erro na tela, nunca toast ou push. Persistir falhas na lista e no detalhe, controlar quais alertas o usuário já viu e evitar polling sem limite.
  7. Regras operacionais. Definir se itens pendentes de envio reservam saldo, podem ser editados ou cancelados, e quando entram na separação. Não permitir execução física de uma requisição rejeitada ou ainda não autorizada pelo ERP.
A reserva precisa de uma decisão explícita. A consulta atual de reservas de request_items faz join com requests.stock_io_id e stock_ios. Uma requisição local sem saída associada não participa dessa parte do cálculo. Se o novo fluxo precisar reservar antes da confirmação do ERP, será necessário mudar essa regra e impedir dupla contagem após sincronizar. Referência: ProductAvailabilityService.php:188–196.

Reduzir também o tempo total de sincronização

Responder rápido não reduz automaticamente o trabalho total. A fila remove essa espera do usuário; as mudanças acima reduzem chamadas e custo. Limitar concorrência evita apenas transferir a saturação do HTTP para o ERP.

Plano de execução por incremento

01 · Medição e proteção contra duplicação

Criar uma referência antes das mudanças

Medir busca por descrição e criação com 1, 5 e 20 itens em ambiente autorizado, com ERP simulado para falhas. Aproveitar os logs SOAP de tempo já presentes. Adicionar chave estável no mobile e testes de repetição sem duplicação.

Saída verificável. Relatório de p50/p95, quantidade de consultas e chamadas externas por operação. Testes de chave repetida, conteúdo diferente e resposta perdida.

02 · Busca com custo limitado

Corrigir a consulta e a experiência de pesquisa

Paginar antes de resolver reservas, adicionar índice compatível com a busca sem acento e limitar agregados internos quando necessário. Ajustar mínimo de caracteres, debounce, cancelamento e páginas no mobile e no web.

Saída verificável. Mesmos produtos e saldos dos testes atuais, menos leitura no plano SQL e nenhuma resposta antiga substituindo a nova.

03 · Operação assíncrona segura

Registrar localmente sem esperar o Senior

Implementar operação durável, worker com identidade explícita, estado público, recuperação de falhas e reconciliação. Ajustar regras de reserva e bloquear ações incompatíveis. Entregar clientes que compreendem resposta 202 antes de habilitar o backend para eles.

Saída verificável. A API responde sem chamar o ERP no caminho HTTP. Requisições sobrevivem a reinícios, reentregas de job e indisponibilidade do Senior sem duplicar.

04 · Avisos e operação assistida

Mostrar pendências e permitir recuperação

Exibir estado na lista e detalhe, manter aviso pequeno com loading durante o envio e abrir alerta de erro para rejeição ou timeout. Não usar push. Oferecer nova tentativa apenas em estados seguros e criar consulta operacional de itens parados ou incertos. Registrar trilha por ID local, chave e número ERP.

Saída verificável. O usuário sabe se o pedido está registrado, enviado ou rejeitado. Suporte identifica e reconcilia a mesma operação sem recriá-la.

05 · Menos chamadas e implantação gradual

Reduzir o custo do worker depois de garantir consistência

Testar importação final, lote e cache de WSDL. Ativar por configuração e grupo piloto. Acompanhar atraso da fila, falhas e duplicações. Se houver regressão, suspender novas admissões ao fluxo afetado e preservar operações pendentes para recuperação.

Saída verificável. Menos chamadas por requisição e tempo de sincronização menor, sem alterar aprovação, estoque, autoria ou números externos. Não reenviar pendências no modo antigo durante uma desativação.

Como comprovar a melhora

As metas abaixo são propostas de aceitação, não resultados medidos. Ajustá-las após obter a referência de rede, volume e concorrência real. Registrar dispositivo, número de produtos e requisições, versão e cenário em cada comparação.

IndicadorMeta propostaVerificação
Busca no backendp95 até 300 ms para uma página em volume representativo.Tempo HTTP e SQL. EXPLAIN (ANALYZE, BUFFERS) em cópia autorizada, com termos comuns, raros, sem resultado e com acentos.
Busca percebida no mobilep95 até 800 ms após a última tecla, incluindo debounce e rede representativa.Medir última tecla, envio, resposta e renderização em dispositivo real. Separar rede do processamento.
Confirmação localp95 até 500 ms no backend, sem espera por ERP.Simular Senior lento ou indisponível e verificar persistência, resposta 202 e operação pendente.
Conclusão no ERPDefinir SLA separado após a referência. Nunca confundir resposta rápida com envio concluído.Idade da operação, tempo na fila, duração SOAP e tempo até confirmação externa. Alertar para pendências fora do SLA.
Repetição e recuperaçãoUma criação externa por intenção, sem perda de operação nos testes de falha.Duplo clique, reentrega concorrente, reinício do worker, queda após sucesso externo e antes de gravação local, timeout e envio parcial.
Estoque e autorizaçãoMesmas regras aprovadas e nenhuma dupla reserva.Entradas pendentes, reservas parciais, equivalência de derivação, dois usuários concorrentes e transferência da reserva local para a saída sincronizada.
Matriz mínima de testes antes de ativar o assíncrono
  • Chave igual e conteúdo igual retornam a mesma requisição; chave igual e conteúdo diferente geram conflito.
  • ERP aceita, mas a resposta se perde. O app encerra o loading e abre um alerta de erro de timeout. O backend preserva o resultado externo incerto e impede uma segunda criação antes de reconciliar.
  • Falha no item intermediário preserva número externo e avanço dos itens já enviados.
  • Processo morre entre commit local e publicação. O recuperador encontra e agenda a operação.
  • Credencial expirada ou ausente produz estado acionável sem expor senha e sem trocar a autoria para usuário de sistema.
  • Rejeição funcional registra motivo sanitizado, encerra o loading e abre um alerta de erro com o motivo. Timeout também abre alerta de erro, nunca toast ou mensagem de verificação.
  • ERP confirma, mas não aprova quantidade. O app não trata sincronização como autorização de separação.
  • App fecha e reabre durante o envio. A lista recupera o estado da mesma requisição e o app apresenta um alerta de erro se houve falha ainda não exibida.
  • Resposta de pesquisa antiga chega por último. A lista mantém apenas o resultado do filtro atual.
Métricas e implantação sem sobrecarregar produção

Usar ID de correlação entre mobile, API, operação e logs SOAP. Coletar duração, quantidade de itens, filas e estados, sem payloads de credenciais. Medir CPU, memória, conexões e espera de banco antes de atribuir lentidão à capacidade do servidor. Rodar carga somente em ambiente e janela autorizados. Uma melhora de p95 não autoriza aumentar concorrência de workers sem medir o impacto no Senior.

Decisões que o código não resolve

Produto e operação

  • A requisição pendente de envio reserva estoque?
  • Pode ser editada ou cancelada antes de chegar ao ERP?
  • Além do alerta no app de quem confirmou, o solicitante deve ver a falha na lista quando for outra pessoa?
  • Qual prazo de sincronização é aceitável e quem trata resultados incertos?
  • Termos de descrição com menos de 3 caracteres são necessários?

Integração e infraestrutura

  • Qual é a garantia do Senior para identificadorExterno e consulta após timeout?
  • O envio em lote preserva regras por origem e devolve erros por item?
  • Como o worker preserva a identidade autorizada fora da sessão HTTP?
  • Qual fila, capacidade de workers e monitoramento existem no ambiente?
  • Qual é o plano SQL e quais índices estão realmente instalados no banco?

Ordem recomendada. Medir e proteger novas tentativas, reduzir custo da busca, implementar envio durável com status explícito e então reduzir chamadas ao Senior. Não basta trocar dispatch_sync por dispatch, aumentar timeouts ou exibir sucesso antes de persistir o trabalho.