# ENG-2309 — Idempotência de requisições e solicitações de compra

## Contexto e diagnóstico

A investigação do caso identificou:

- `StockIO` `226891`, requisição Senior `84213`, foi importado com `reason = SYNCED_REQUEST`.
- O item importado é `StockIOProduct` `1198250`, produto Senior `91020717`, quantidade 1.
- A saída não possui `Request` local associado; portanto, a importação não criou uma requisição local duplicada.
- A integração da saída (`3230879`) já indicava a solicitação de compra `39766`.
- Posteriormente, a integração do item (`3230880`) passou a indicar a solicitação `39973`, em 04/09, para o mesmo item.
- O item já havia sido cancelado pelo ERP antes da segunda solicitação ser registrada localmente.

A evidência aponta que a segunda solicitação foi criada pelo fluxo de geração de solicitação de compra, que não verificava a solicitação legada existente, o estado cancelado do item nem repetição concorrente. O caller exato ainda depende de auditoria do Senior/API, pois o `rex-front` atual não chama esse endpoint.

## Objetivos

1. Impedir a criação de uma nova solicitação de compra quando já existir uma solicitação válida para o item ou para a saída.
2. Impedir repetição causada por duplo envio, concorrência, timeout ou perda de resposta.
3. Aplicar o mesmo controle ao fluxo de criação de requisição via `RequisicaoAgrupada`.
4. Preservar o contrato e o payload atual das integrações SOAP.
5. Manter rastreável o estado de uma operação cujo resultado externo seja desconhecido.

## Fora de escopo

- Cancelar ou excluir automaticamente as solicitações `39766` e `39973` no Senior.
- Alterar o contrato dos webservices Senior.
- Substituir a tabela `integrations` por uma nova tabela.
- Permitir automaticamente uma nova solicitação para substituir uma solicitação cancelada; isso deverá ser uma ação de negócio explícita, se necessário.

## Decisão arquitetural

A tabela existente `integrations` será usada para armazenar o estado da operação. Não será criada uma nova tabela.

Será adicionado um bloco reservado nos parâmetros JSON, por exemplo:

```json
{
  "rex_integration_operation": {
    "type": "request_creation",
    "idempotency_key": "...",
    "fingerprint": "sha256...",
    "status": "reserved|processing|succeeded|failed|unknown",
    "external_reference": {},
    "last_error": null,
    "updated_at": "..."
  }
}
```

A chave será criada por operação do usuário e permanecerá a mesma durante as tentativas da mesma operação. A impressão digital será calculada localmente a partir do payload normalizado e servirá para rejeitar a reutilização da chave com dados diferentes.

Para evitar concorrência:

- a `Integration` será bloqueada durante a reserva da operação;
- a reserva será feita antes da chamada ao Senior;
- será adicionada proteção de unicidade para a combinação do tipo da operação e da chave na própria tabela `integrations`, sem criar nova tabela;
- o serviço de integração reutilizará a `Integration` existente, pois `IntegrationStoreService` atualmente sempre cria uma nova linha.

O `IntegrationUpdateService` deverá preservar o bloco reservado ao atualizar os parâmetros ERP. Os campos atuais do ERP continuarão sendo atualizados pelo DTO existente.

## Fluxo de criação de requisição

O endpoint continuará usando `RequestStoreService`, `SeniorRequestExport`, `RequisicaoAgrupada` e `SeniorSyncRequestsJob`.

1. O `rex-front` envia uma chave de idempotência no `POST /api/v1/request`.
2. O backend calcula a impressão digital e verifica operação existente.
3. A `Request`, seus itens e a `Integration` com a operação reservada são persistidos antes da chamada externa.
4. A chamada `RequisicaoAgrupada` mantém o payload atual.
5. O primeiro item continua criando o `numEme`; itens seguintes continuam usando o mesmo `numEme`.
6. `SeniorSyncRequestsJob` continua importando e vinculando a saída.
7. O número Senior e o estado da operação são salvos na `Integration` existente.
8. Em sucesso, a resposta do endpoint permanece compatível com a atual.

Uma repetição com a mesma chave e o mesmo payload retorna o resultado já registrado. A mesma chave com payload diferente é rejeitada. Em timeout ou perda de resposta, a operação fica `unknown` e não é enviada novamente automaticamente.

## Fluxo de solicitação de compra

O endpoint continuará usando `StockOutputPurchaseSolicitationService`, `SeniorPurchaseSolicitationExport` e os webservices `GerarSolicitacaoCompra` e `VincularRequisicaoSolicitacao`.

Antes de chamar o Senior, o backend deverá:

- validar que os itens pertencem à saída;
- rejeitar IDs de item repetidos;
- rejeitar saída ou item cancelado;
- rejeitar quantidade maior que a quantidade pendente;
- verificar `purchase_solicitation_number` no item;
- verificar `solicitation_number` legado na saída;
- reservar a operação na `Integration` da saída.

Assim, a solicitação `39766` existente no caso analisado impediria a geração de `39973`.

Depois da reserva:

1. O payload atual será enviado ao `GerarSolicitacaoCompra` sem alteração.
2. O número retornado será salvo na operação antes do vínculo.
3. O `VincularRequisicaoSolicitacao` continuará recebendo o mesmo contrato.
4. Os campos atuais de solicitação de compra continuarão sendo salvos na `Integration` do item.
5. Em falha no vínculo, uma nova tentativa repetirá somente o vínculo.
6. Em perda da resposta da geração, a operação ficará `unknown` e não gerará outra solicitação automaticamente.

Como o `rex-front` atual não possui caller desse endpoint, o cliente que efetivamente o utiliza deverá ser identificado. Caso o fluxo seja incorporado ao frontend, ele também enviará a chave de idempotência. As proteções de negócio permanecerão no backend para clientes antigos ou externos.

## Estados e erros

- Solicitação existente: conflito, informando o número já encontrado.
- Saída ou item cancelado: operação rejeitada antes do SOAP.
- Mesma chave e mesmos dados concluídos: resultado anterior reutilizado.
- Mesma chave com dados diferentes: conflito de idempotência.
- Operação em andamento: nova geração não é iniciada.
- Falha funcional confirmada pelo Senior: operação `failed`, permitindo reprocessamento seguro.
- Timeout, erro de rede ou resposta perdida: operação `unknown`, sem retry automático.
- Solicitação gerada e vínculo pendente: retry somente do vínculo.

As solicitações existentes não serão alteradas automaticamente. A reconciliação de uma operação `unknown` deverá confirmar o resultado no Senior antes de atualizar a `Integration` local.

## Compatibilidade

- Não serão alterados WSDLs, nomes de operações SOAP ou payloads existentes.
- `SeniorRequestExport` continuará usando o fluxo atual de `RequisicaoAgrupada`.
- A sincronização por `SeniorSyncRequestsJob` continuará sendo executada.
- Os campos atuais de `Integration` serão preservados.
- O novo bloco de operação será aditivo e não será enviado ao Senior.
- O frontend oficial será atualizado para enviar e reutilizar a chave de idempotência.
- Clientes externos continuarão funcionando com as validações de negócio; a obrigatoriedade da chave será avaliada após identificar os callers.

## Testes

### Backend

- mesma chave com mesmo payload;
- mesma chave com payload diferente;
- chamadas concorrentes;
- falha funcional, timeout e resposta perdida;
- requisição com múltiplos itens e mesmo `numEme`;
- bloqueio por solicitação legada `39766`;
- bloqueio por solicitação já gravada no item;
- bloqueio de item ou saída cancelada;
- repetição do vínculo sem nova geração;
- preservação do bloco de operação durante a sincronização;
- manutenção dos payloads SOAP atuais.

### Frontend

- geração de uma chave por operação;
- reutilização da chave em retry;
- geração de nova chave para uma nova operação;
- mensagens amigáveis para conflito, processamento e resultado desconhecido.

## Implantação

1. Criar `feature/eng-2309` a partir de `release/v1.10.5` nos dois repositórios.
2. Implementar primeiro a compatibilidade e o controle no `rex-back`.
3. Atualizar o `rex-front` para enviar e reutilizar a chave no fluxo de requisição e em eventual caller de solicitação de compra.
4. Monitorar operações concluídas, bloqueadas e desconhecidas.
5. Tratar separadamente no Senior os registros já duplicados `39766` e `39973`.
