# ENG-2309 — Complemento da proteção de RequisicaoAgrupada

## Evidências e limites do diagnóstico

O cliente informou que front e back estão na v1.10.6 e que, nos incidentes, chegam duas chamadas de `RequisicaoAgrupada` com milissegundos de diferença. Não foi possível comparar os payloads dessas chamadas; a causa exata dos incidentes permanece não confirmada.

A análise do Rex-Estoque identificou falhas reproduzíveis:

- `Request.post` não enviava `Idempotency-Key`; o backend gerava um UUID diferente para cada POST sem chave.
- O bloqueio do `CustomButtom` dependia de renderização. Duas execuções antes dessa renderização podiam chamar o handler duas vezes. Uma prop `disabled=false` também sobrepunha o bloqueio interno.
- A tela permitia incluir o mesmo produto mais de uma vez. O backend aceitava esse payload e exportava cada entrada individualmente.
- No frontend web, fechar a confirmação apagava a chave, inclusive após um resultado incerto.

Essas falhas permitem tanto duas criações independentes quanto dois itens repetidos em uma criação. A diferença de horários sozinha não distingue os cenários. Chamadas para produtos diferentes usando o mesmo número Senior continuam sendo legítimas.

## Alterações

### Mobile

- Trava síncrona no botão, combinada com a prop de desabilitação.
- Serviço de criação com chave persistida em AsyncStorage **antes** do envio, isolada por API e usuário.
- Reutilização da chave em retry e após remontagem/reinício do app.
- A operação incerta não pode ser substituída por dados diferentes.
- Erros de validação 422 com `errors` permitem corrigir o formulário; erros SOAP 422 sem `errors`, conflitos 409 e falhas de rede preservam a chave.
- Sucesso confirmado libera a chave para uma nova operação.
- Inclusão de produto repetido bloqueada, inclusive em atualizações concorrentes do estado.

### Frontend web

- Mesma política de retry, com persistência em sessionStorage (sobrevive a remontagem e reload na mesma aba).
- Trava síncrona de criação e impedimento de fechar a confirmação durante o envio.
- Fechar a confirmação após falha não descarta a operação incerta.

### Backend

- Validação `distinct` no endpoint e guard adicional no serviço, antes da autenticação/reserva/exportação.
- UUID HTTP nos logs da API, resposta `X-Request-Id` e contexto SOAP.
- Logs SOAP incluem Request/RequestItem locais, índice do item, produto, derivação, quantidade, fingerprint, hash da chave e `creates_request`.
- Chaves brutas e credenciais não são adicionadas aos novos logs.
- Nenhuma alteração no payload SOAP, nos números existentes ou no mecanismo de reserva/índice da correção anterior.

## Diagnóstico de eventual recorrência

Correlacionar `request.log` (`uuid`) com `integration.log` (`http_request_uuid`):

- Dois UUIDs HTTP e duas chamadas com `creates_request=true`: duas criações entraram na API. Comparar os hashes de chave/fingerprints.
- Um UUID HTTP, primeira chamada de criação e chamadas seguintes com `num_eme` preenchido: exportação de itens do mesmo POST. Conferir produto/derivação e índice.
- Mesma chave com operação `reserved`, `processing` ou `unknown`: deve retornar conflito sem novo SOAP.

Operações `unknown` ainda precisam de reconciliação com o Senior. Não apagar a chave local nem resetar o estado no banco para forçar uma nova geração sem confirmar o resultado externo. A aplicação não cancela nem corrige automaticamente registros já duplicados.

## Implantação

1. Aplicar o complemento no backend e confirmar o índice `integrations_operation_idempotency_unique` da migration anterior.
2. Publicar o frontend web atualizado.
3. Distribuir e exigir o uso do **mobile atualizado** no fluxo de criação. Atualizar apenas front/back não fecha a lacuna dos aplicativos antigos.
4. Monitorar os campos de correlação e os conflitos de operação.

O backend mantém compatibilidade com clientes sem header: eles ainda recebem uma chave nova por chamada. A obrigatoriedade de `Idempotency-Key` deve ser uma mudança contratual coordenada se houver necessidade de bloquear builds antigos/consumidores externos.

## Validação

- Backend: 22 testes direcionados (197 assertions), incluindo replay, mudanças de payload, estados bloqueados, timeout SOAP, produto repetido, serviço direto, múltiplos produtos e correlação dos logs. Fixtures de requisição isoladas em transações.
- Mobile: 80 testes, incluindo trava do botão, envio/reuso do header, persistência após reinício do controlador, dados alterados, falhas de storage, isolamento de usuários/API e produtos repetidos; TypeScript aprovado.
- Frontend web: 273 testes e build aprovados.
- SOAP mockado em testes; banco PostgreSQL temporário `rex_test` validado pelo guard. Nenhum acesso ao ERP ou alteração dos registros do cliente.
