# Envio assíncrono de requisições

## Contrato público

Clientes preparados enviam `X-Request-Submission: async-v1` e `Idempotency-Key` no POST `/api/v1/request`. A ativação exige `REX_REQUEST_SUBMISSION_ENABLED=true` e inclusão do operador no piloto, quando a lista de operadores não está vazia. O padrão é desativado. Clientes antigos e novas intenções fora do piloto mantêm HTTP 201 síncrono.

A aceitação assíncrona retorna HTTP 202. A transação salva requisição, itens, integração e operação antes de publicar trabalho. Ela não autentica nem consulta o Senior. Um recibo tem esta forma:

```json
{
  "data": {
    "id": 123,
    "status": 1,
    "submission": {
      "id": "2729377a-48ea-4f55-b00c-53f4f7b548b6",
      "request_id": 123,
      "status": "queued",
      "request_number": null,
      "attempts": 0,
      "updated_at": "2026-10-01T15:00:00+00:00",
      "error": null,
      "failure_acknowledged": false
    }
  }
}
```

O ID da operação é um UUID. O ID da requisição local continua numérico. O status operacional não representa envio nem aprovação.

- `GET /api/v1/request/submission?key=<chave>` recupera o recibo do próprio operador após perda da resposta. Consultar não envia trabalho.
- `GET /api/v1/request/submissions` retorna operações ativas, falhas ainda não reconhecidas e confirmações recentes. `ids[]=<UUID>` inclui operações conhecidas mesmo fora dessa janela. O limite é 200 IDs por consulta, e a autorização por operador permanece obrigatória.
- `POST /api/v1/request/submissions/<UUID>/acknowledge`, com `event_id` UUID, reconhece apenas a falha correspondente. Uma confirmação atrasada não reconhece outra falha.
- Lista e detalhe de requisição incluem `submission`, ou `null` para o fluxo antigo. Eles preservam a falha depois de fechar o alerta.

A mesma chave e o mesmo conteúdo retornam a mesma requisição e seu estado, sem novo envio. Conteúdo diferente retorna 409. Uma operação assíncrona existente continua no contrato assíncrono depois de desativar o piloto ou remover o cabeçalho. Ela nunca passa pelo caminho antigo para criar novamente.

## Execução e recuperação

A conexão `request-submissions` usa a fila de banco de dados, independentemente de `QUEUE_CONNECTION=sync`. A publicação grava a linha da fila e seu marcador na mesma transação de banco. O registro durável permite recuperar a interrupção entre aceitação e publicação.

O job contém apenas o UUID. O backend salva credenciais do operador em uma coluna criptografada, separada dos parâmetros da integração. A fila, o recibo e os logs públicos não recebem senha nem token. O worker não depende da sessão HTTP e verifica novamente a permissão do operador. Ele preserva o requisitante selecionado e usa o operador original como autor das alterações locais. Credenciais ausentes ou expiradas produzem erro; o worker não substitui o operador por usuário de sistema.

O prazo padrão das credenciais é uma hora, configurável entre um minuto e um dia. Resultado terminal remove as credenciais. A recuperação também trata credenciais expiradas sem depender de um worker ativo. Backups devem respeitar a política de retenção de credenciais criptografadas. Trocar `APP_KEY` sem preservar a chave anterior impede recuperar operações pendentes.

Locks de sessão do PostgreSQL impedem dois executores da mesma operação e limitam a concorrência global. Um lease vencido não libera a criação enquanto o executor ainda mantém seu lock de sessão. O prazo de reentrega supera o prazo do job. As liberações por concorrência aguardam 15 segundos.

Antes de exportar um item, o backend grava a fase `exporting`. Depois da confirmação, grava número externo e próximo item antes de continuar. A importação ocorre após as exportações e não representa aprovação. Uma resposta sem quantidade aprovada não cria saída nem libera separação ou entrega. A requisição local sem saída continua sem reserva antecipada.

A recuperação segue estas regras:

| Situação | Ação segura |
| --- | --- |
| Registro local sem publicação | Publicar o trabalho da mesma operação. |
| Interrupção antes de exportar | Retomar a mesma operação depois de obter o lock. |
| Itens anteriores confirmados e fase segura | Continuar apenas os itens ainda não confirmados. |
| Todas as exportações confirmadas, importação interrompida | Repetir somente a importação pelo número conhecido. |
| Interrupção durante exportação ou resposta perdida | Registrar timeout e bloquear outra criação. |
| Exportação confirmada e falha de importação | Exibir `import_failed`, preservar o número e não criar novamente. |

Timeout encerra o loading e informa literalmente que o ERP não respondeu no prazo. A ausência de resposta não comprova ausência de criação. Todas as operações assíncronas não confirmadas permanecem sem edição ou cancelamento comum, pois uma falha pode ter ocorrido após o ERP aceitar parte dos itens.

## Preparar um piloto

Não execute estes passos em produção por causa deste documento. A implantação exige autorização do responsável pelo ambiente.

1. Ensaiar as duas migrations em uma cópia autorizada. A migration da busca faz backfill e cria índice na transação; ela pode bloquear alterações de produtos. Aplicar migrations antes do código que consulta as novas colunas e a tabela de operações.
2. Publicar clientes preparados para 202 antes de habilitar a aceitação. Manter o piloto desativado durante essa preparação.
3. Definir as variáveis `REX_REQUEST_SUBMISSION_*` de `.env.example`. Começar com concorrência global e um worker iguais a 1. O `retry_after` efetivo é, no mínimo, o timeout configurado mais 60 segundos.
4. Instalar, mediante autorização, `infra/docker/php/request-submissions-worker.conf.example` no Supervisor do ambiente. Exportar as variáveis de caminhos, usuário, fila e prazos para o processo Supervisor. O daemon não lê automaticamente o dotenv do Laravel. O exemplo não é carregado pelo Dockerfile nem ativa um worker nesta entrega.
5. Executar o scheduler Laravel a cada minuto. `request-submissions:recover` recupera operações e trata execuções interrompidas. `--submission=<UUID>` limita a recuperação a uma operação. A recuperação não repete uma criação incerta.
6. Verificar a supervisão com interrupção do worker e retomada da mesma operação no ambiente simulado. Conferir usuário, número externo, itens já enviados e ausência de duplicação antes de permitir chamadas reais.
7. Definir os IDs do grupo piloto e habilitar a configuração. Monitorar idade das operações, erros, fila e carga do Senior. Não aumentar a concorrência sem medir o efeito.

A configuração do exemplo exige `REX_APP_ROOT`, `REX_PHP_BINARY`, `REX_REQUEST_SUBMISSION_WORKER_USER` e `REX_REQUEST_SUBMISSION_LOG_PATH` válidos para a instância. `REX_REQUEST_SUBMISSION_WORKER_STOPWAIT_SECONDS` deve superar o timeout do job. Não copie credenciais para o arquivo Supervisor.

Para observar o estado sem revelar payloads, consulte as contagens por `status`, a idade do registro ativo mais antigo em `request_submissions` e as linhas de `jobs` da fila configurada. A API autorizada também apresenta tentativas, horário, número externo e último erro. Não imprima `credentials` nem parâmetros SOAP durante diagnóstico.

## Desativação e suporte

Desativar a aceitação impede novas operações assíncronas. Não desligue o worker nem o scheduler enquanto existem operações pendentes. A recuperação e as consultas continuam disponíveis; repetir uma chave antiga não cria pela integração síncrona.

Se uma operação está em timeout com resultado incerto, o suporte deve verificar o resultado no Senior por evidência externa. Não apagar a operação, trocar a chave, zerar o cursor, alterar a fase para `queued` ou executar novamente o POST como tentativa de reparo. Esses atos podem duplicar a requisição ou um item. O código não presume que `identificadorExterno` garanta deduplicação.

A entrega não inclui um comando que force a reconciliação sem essa evidência. Uma futura ação de suporte deve registrar a comprovação e validar correspondência de requisição, operador e itens. Até lá, o erro e os dados de acompanhamento permanecem disponíveis.

## Medição local de criação

`tests/Support/benchmark-request-submissions.php` compara o fluxo síncrono preservado com a aceitação assíncrona no mesmo código e conjunto sintético. A referência é o caminho síncrono atual, não uma reprodução do commit anterior à issue. O cliente SOAP simulado acrescenta 50 ms por chamada. Dez amostras e um aquecimento por cenário usam 20 produtos, uma execução por vez e uma resposta de importação sem quantidade aprovada.

| Itens | Resposta síncrona p50 / p95, ms | Aceitação assíncrona p50 / p95, ms | Worker p50 / p95, ms | SOAP no HTTP antes / depois | SOAP total antes / depois |
| --- | --- | --- | --- | --- | --- |
| 1 | 370,504 / 1.310,876 | 46,270 / 65,325 | 204,830 / 252,492 | 3 / 0 | 3 / 3 |
| 5 | 1.433,649 / 1.632,494 | 70,741 / 93,123 | 482,111 / 542,757 | 11 / 0 | 11 / 7 |
| 20 | 5.406,103 / 5.683,719 | 109,546 / 139,287 | 1.489,737 / 1.520,805 | 41 / 0 | 41 / 22 |

A redução de chamadas vem de uma importação ao final, em vez de uma após cada item. As exportações permanecem sequenciais. Com latência simulada zero, os p95 de aceitação assíncrona foram 55,040, 147,964 e 247,758 ms para 1, 5 e 20 itens. A variabilidade local não permite atribuir as diferenças entre esses p95 à latência externa. Todas as amostras assíncronas fizeram zero chamadas SOAP no HTTP.

O artefato JSON também registra tempo e contagem de SQL da aceitação. No cenário de 50 ms, os p95 de SQL foram 34,320, 44,580 e 62,730 ms. As contagens ficaram entre 20 e 22, entre 28 e 30, e em 60 consultas, respectivamente. A idade até iniciar o worker teve p95 de 97,694, 122,514 e 149,763 ms; esse número não mede espera em uma fila concorrida. O worker inicia logo após a aceitação e a publicação local.

O script usa uma transação externa apenas para desfazer as fixtures. Ela adia o callback `afterCommit`, portanto a medição de aceitação não inclui a publicação feita pelo callback em uma implantação real. O comando de recuperação publica a operação antes de executar o worker real. Essa limitação impede usar os tempos como comprovação da meta de 500 ms. A fixture também não mede criação de saída aprovada, rede, renderização nativa, carga simultânea ou latência real do Senior. Ela não modifica sequências de volta após rollback. Não execute o script em um banco operacional nem junto de outros testes.

```sh
docker exec -e APP_ENV=testing eng2486-test-runner \
  php tests/Support/benchmark-request-submissions.php \
  --confirm-disposable=rex_test --iterations=10 --latency-ms=50
```

O script exige o guard de testes e um servidor PostgreSQL local confirmado. Ele usa uma chave criptográfica fictícia apenas para seus dados descartáveis e nunca imprime senha, token ou bindings SQL. Os resultados desta sessão estão em `/tmp/eng-2486-runner/creation-50ms.jsonl` e `creation-0ms-async.jsonl`.

## Validação local

Os testes usam API, fila e recuperação reais da aplicação com o cliente SOAP simulado na fronteira externa. O runner descartável tem PHP 8.4 e PostgreSQL 16, sem rede externa. Os testes verificam aceitação sem Senior, envio sem sessão HTTP, autoria, rejeição, timeout, importação, avanço por item, reentrega, recuperação e privacidade.

```sh
docker exec eng2486-test-runner ./vendor/bin/pest \
  tests/Feature/Request/RequestSubmissionTest.php
```

Esse comando só vale para o runner descartável desta sessão. Ele não autoriza testes contra banco operacional. Os resultados completos e as limitações da release ficam em `docs/testing/eng-2486-performance.md`.

## Prazo efetivo da comunicação e confirmação manual

O envio `RequisicaoAgrupada` e a consulta `Exportar_6` são executados em um processo PHP CLI isolado. `SENIOR_SOAP_TIMEOUT` (padrão 45 segundos) limita o tempo total de cada chamada, incluindo a leitura do WSDL. Ao excedê-lo, Symfony Process encerra o filho e fecha a conexão, mesmo que o servidor continue enviando bytes sem terminar a resposta. Esse encerramento local não cancela uma gravação que o ERP já tenha recebido: o resultado do envio fica `unknown` (ou `timeout` no acompanhamento assíncrono) e não é reenviado automaticamente.

O ambiente precisa de `proc_open` habilitado e PHP CLI com a extensão SOAP. `REX_REQUEST_PHP_BINARY` permite indicar o executável; o padrão é `PHP_BINDIR/php`. Dados e credenciais entram apenas por stdin e não são gravados em argumentos, arquivos, logs ou mensagens do processo. O worker não inicializa Laravel nem abre conexão com o banco. Testes com cliente simulado usam o transporte em memória; `SeniorRequestSoapExecutorTest` testa o processo real com servidor local que responde, fica silencioso ou envia uma resposta infinita.

`REX_REQUEST_PROCESSING_TIMEOUT` (padrão 300 segundos, mínimo 60) continua sendo a recuperação de estado para uma execução síncrona interrompida por reinício ou morte do processo. Ele não reenfileira o envio. Deve ser maior que o prazo SOAP para não conciliar uma execução ainda ativa.

Para resultados desconhecidos, `POST /api/v1/request/{id}/confirm-erp` recebe `request_number` (inteiro positivo representado como string, até 9 dígitos) e `confirmed_in_erp: true`. Esta é uma declaração do usuário após conferir o ERP, sem depender de uma nova chamada externa. Exige permissão de alteração e autoria/requisitante, operador do envio ou administrador; rejeita execução ativa, troca de número já conhecido e número vinculado a outra requisição da mesma empresa/filial. Usa transação, bloqueio da integração e bloqueio por número para concorrência. Uma repetição com o mesmo número retorna o resultado já registrado, sem novo histórico.

A confirmação preserva chave e payload originais, encerra a pendência como `succeeded`, limpa credenciais e erro do acompanhamento assíncrono e grava autor, data e número em `manual_confirmation` e no histórico (operação 13). Web e mobile exibem **Confirmada pelo usuário**, distinguindo a declaração de uma resposta automática do ERP. Essa ação não cria, cancela nem sincroniza estoque; a sincronização posterior segue seu fluxo existente.

## Reenviar ou cancelar uma criação que falhou

Lista e detalhes retornam `creation_actions.retry` e `creation_actions.cancel`, considerando o estado persistido e as permissões do operador. São liberados somente para requisição local pendente, operação de criação `failed`, sem número externo, sem itens reconhecidos (`next_item_index=0`) e sem saída vinculada. `timeout` no acompanhamento não significa necessariamente envio incerto: uma falha na autenticação, antes da fase `exporting`, termina a operação como `failed` e permite essas ações. Timeout depois de iniciar o envio termina como `unknown` e exige conciliação, sem reenvio.

`POST /api/v1/request/{id}/retry-creation` exige `idempotency_key` igual à chave persistida e reutiliza a requisição, itens, integração e chave existentes. Somente o operador original pode solicitá-lo. No modo assíncrono, captura credenciais atualizadas do operador autenticado e recoloca o mesmo envio na fila, retornando 202; independe da flag de aceitação de novas operações assíncronas. O contador de tentativas avança quando o worker inicia, e `retry_generation` distingue o novo ciclo de recibos atrasados da tentativa anterior. No modo síncrono, retorna 201 ao concluir. Não recebe um novo formulário nem cria outra requisição local.

O cancelamento pelo endpoint existente encerra localmente a requisição e seus itens quando a criação falhou sem confirmação parcial, sem chamar o ERP. Limpa credenciais, reconhece o evento terminal e registra o cancelamento no histórico. Verificações sob bloqueio impedem reenvio após cancelamento e disputa entre reenvio/cancelamento. Envios ativos, desconhecidos ou parcialmente confirmados não passam por esse cancelamento local. Os clientes liberam somente a intenção salva com a mesma chave após aceitação do reenvio ou cancelamento.
