# Conclusão de pré-faturas — ENG-2555

A conclusão é síncrona e não exige worker. Antes do SOAP, o WMS reserva uma operação durável em `pre_invoice_billing_operations`. A chave abrange URL da instância ERP, empresa, filial, análise, pré-fatura e `FormarEmbalagens`.

## Implantação

Aplicar as migrations antes de liberar os endpoints individual e em lote. A migration da proteção também registra somente saídas de expedição com motivo pré-fatura, já concluídas e com identidade ERP válida, para impedir reenvio caso outro processo posteriormente altere seu status. Ela não chama o ERP. Evitar conclusões durante a troca de código/migration; reiniciar processos persistentes para carregar a versão nova.

```sh
php artisan migrate
```

O cache dos detalhes fica em `integrations.parameters.pre_invoice_details_cache`, contendo `data` e `last_success_at`. A validade é de 60 segundos. Atualizações concorrentes usam lock de sessão do PostgreSQL, sem manter transação ou lock de linha durante o SOAP. Sincronizações preservam esse campo atomicamente. Não há histórico de detalhes.

A migration `index_pre_invoice_details_lookup` indexa a busca pelos quatro identificadores, incluindo os aliases legados. Durante uma atualização em andamento, chamadas concorrentes aguardam dados novos; somente após erro ou timeout exibem dados antigos. `SENIOR_PRE_INVOICE_DETAILS_WAIT_TIMEOUT` controla essa espera (60 segundos por padrão; ajustar acima dos timeouts SOAP da instância). `SENIOR_PRE_INVOICE_DETAILS_WSDL_CACHE=true` reutiliza o WSDL em disco, sem armazenar respostas do ERP nem estender a validade dos detalhes. Após alterar o contrato SOAP, limpar o cache WSDL do PHP ou desativar essa opção temporariamente. O header `Server-Timing: details;dur=...` mede o serviço de detalhes, incluindo banco, espera e ERP, mas exclui autenticação, inicialização do Laravel e rede.

## Diagnóstico e recuperação

Consultar `id`, `stock_io_id`, `status`, `attempts`, `erp_succeeded_at`, `completed_at` e `message` em `pre_invoice_billing_operations`. Os logs de integração registram início, resultado, conclusão e duplicatas bloqueadas; o payload é identificado por hash, sem observações ou credenciais nos logs.

- `succeeded`: conclusão finalizada; nenhum novo envio permitido.
- `erp_succeeded`: ERP confirmou, mas conclusão local ficou pendente.
- `processing`: execução ativa ou interrompida; nunca é liberada por expiração de tempo.
- `unknown`: houve falha de comunicação ou erro sem confirmação de sucesso; uma nova tentativa manual é permitida quando o envio anterior terminou.
- `failed`: falha anterior ao SOAP ou falha comprovada; nova tentativa pode reservar a mesma operação.

Para recuperar uma conclusão local após sucesso confirmado, usar o UUID da operação:

```sh
php artisan pre-invoices:complete-local UUID
```

Esse comando atualiza apenas registros locais e não chama o ERP. Uma pré-fatura cancelada exige análise antes da atualização local.

Erros sem confirmação de sucesso permitem nova tentativa individual ou em lote. Durante os 5 segundos após o término da última tentativa com erro (`last_attempt_finished_at`), novas solicitações retornam a mensagem registrada sem reenviar SOAP nem incrementar tentativas. Repetições não renovam essa janela. O controle vale entre usuários, navegadores e chamadas individuais ou em lote. O reenvio é bloqueado durante o processamento e após sucesso confirmado no ERP, inclusive quando a conclusão local está pendente. Uma operação interrompida que permaneceu em `processing` pode ser reconciliada. Para registrar uma conferência no ERP, usar UMA das conclusões, com usuário responsável e evidência:

```sh
php artisan pre-invoices:reconcile UUID --confirmed --operator=ID --reason="Referência da conferência que confirmou as embalagens no ERP"
php artisan pre-invoices:reconcile UUID --not-executed --operator=ID --reason="Evidência da ausência de qualquer efeito no ERP"
```

Os comandos nunca chamam o ERP. A reconciliação é recusada enquanto o executor ainda detém o lock da operação, e jamais reabre uma operação concluída com sucesso. `--confirmed` retoma apenas a conclusão local; `--not-executed` libera uma nova tentativa pelo fluxo normal. Se o sucesso foi registrado, mas a atualização local falhar, usar `complete-local`.

Não apagar registros nem alterar status/chaves manualmente: isso remove a proteção contra duplicação. A conferência manual não é substituída por retry automático.
