SGF/docs/SGF_PAYABLE_HISTORY_RECEIPT_DELIVERY.md

# Compras → Financeiro SGF: recibo histórico de ensaio

Continuação posterior: [consulta paginada e leitura conjunta SGF](SGF_PAYABLE_PAGED_READ_DELIVERY.md). A listagem integral referida como limite nesta entrega foi substituída no adaptador SGF; a leitura nativa anterior, a origem viva/cutover, revisão visual e capacidade de implantação mantêm os respectivos limites. Os dados e hashes desta prova inicial permanecem preservados.

02/11/2026 — `SGF-PAYABLE-HISTORY-RECEIPT-SIM-v1`. Adaptador SGF funcional sobre o núcleo comum existente. Entrega exclusivamente sintética, desactivada por defeito. Não é uma passagem operacional de responsabilidade financeira nem ligação histórica em tempo real.

## Lacuna e implementação

O núcleo `packages/payables` já incorporava pagamentos originais e o adaptador de Compras já fornecia esse histórico. O adaptador SGF não tinha fornecedor histórico nem rotas para preparar/validar essa incorporação. Agora `SupplierHistoryReceipts` lê recibos históricos explicitamente reconciliados com uma origem SGF, e `SupplierPayables` fornece-os ao mesmo `Payables`. Não se copiou o motor de saldo ou de dedução.

`POST /api/supplier-payables/prepare_history` e `.../validate_history` reutilizam o controlador, os fundamentos, a repetição, os direitos `prepare`/`validate` de `pa_access` e `supplier_payables.view`. A validação mantém identidade/pessoa distinta, bloqueios, revisão documental e hash histórico exactos. Nenhum novo direito ou acesso real foi concedido. A consulta e a página existentes apresentam a capacidade apenas quando ligada no ensaio. A interface identifica expressamente a fotografia de origem e a ausência de passagem operacional validada.

`config/supplier_payable_history.php` mantém `synthetic_enabled=false`, sem variável de activação operacional. A guarda SGF permanece limitada a `payable-testing` e bases `payable_sgf_<12 hex>`. O schema novo existe apenas na preparação explícita de uma base QA nova; não há migração, criação de tabela por acesso, publicação de recibos ou instalador operacional.

## Contrato do recibo

`pa_source_histories` guarda empresa/unidade SGF, origem local, versão positiva, payload, checksum e data, com unicidade por âmbito/origem/versão e protecção append-only. A leitura escolhe a versão mais recente **da origem e contexto exactos** e exige:

- Contrato `SGF-PAYABLE-HISTORY-RECEIPT-SIM-v1`, versão do payload igual à linha e checksum canónico íntegro.
- Identidade factual completa da origem (`instance/company/document`) e revisão documental iguais à factura local explicitamente mapeada. IDs iguais entre aplicações não são usados como correspondência automática.
- Histórico completo, sem pagamentos repetidos, com empresa/documento/moeda compatíveis, montantes exactos, estados e auditorias originais válidos.
- Hash da captura calculado pelo próprio `HistoricalPayments`, sem novo cálculo de saldo no adaptador.

Os hashes demonstram integridade/coerência, **não autenticam sozinhos um remetente externo**. Neste incremento, o produtor é a preparação QA controlada. Não existe endpoint público para inserir/alterar recibos, descoberta automática de dados antigos, sincronização nativa ou mecanismo de confiança/cutover para implantação. Uma futura publicação operacional terá de resolver essa autoridade e a actualidade dos factos, sem manter dois escritores da mesma dívida.

Recibo ausente, divergente ou antigo recusa o comando. Numa obrigação já reconhecida, divergência mantém o principal/histórico consultáveis e o saldo **indeterminado (`null`)**, sem converter falta de evidência em saldo zero ou bloquear toda a página. Uma captura diferente após preparação exige nova conferência. Confirmar pagamentos pendentes importados continua indisponível no SGF; não se instalou `pa_payment_decisions` nem se acrescentou essa rota.

## Cenário de origem efectiva e resultado

O ensaio criou duas bases novas com roles próprias no cluster de regressão 55439. Em Compras, reutilizou `PaymentFixture`, recepção, registo/conferência de factura e os workflows originais de pagamentos/banco sintético. Não simulou uma factura conferida apenas preenchendo um estado:

1. Factura de **60,00 MZN**, imposto documental zero conforme a fixture existente.
2. Pagamentos originais de **30,00 confirmados**, **10,00 pendentes** e **5,00 rejeitados**, com registo e decisões independentes pelos mecanismos existentes.
3. Preparação histórica pelo núcleo nativo, sem reconhecer uma obrigação comum na base de origem. Exportação apenas dos campos documentais e da captura histórica autorizada, sem conta bancária/referências cifradas.
4. Origem e recibo mapeados explicitamente na base SGF nova. Preparação e validação distintas reconhecem principal **60,00**, dedução histórica **30,00**, saldo **30,00**. Pendentes/rejeitados preservam estado e não abatem.

Vencimento e dias de atraso continuam nulos; atraso indeterminado. Não se recalcula imposto, executa transferência, confirma pendente ou cria lançamento/novo movimento de stock/orçamento por esta passagem.

As duas bases são composições de ensaio distintas. O facto de o SGF apresentar o saldo correcto **não comprova que instalações nativas e SGF operadas em simultâneo partilham uma autoridade financeira**. Não houve bloqueio/cutover operacional da origem; não se autoriza usar esta fotografia como fonte viva. Os originais da base nativa foram conferidos depois em transacção só de leitura: mesmos hashes e estados, zero obrigações comuns nativas reconhecidas.

## Provas e recuperação

[Relatório consolidado e hashes](proofs/sgf-payable-history-receipt-20261102.json): **10 cenários dirigidos / 56 asserções**, mais **17 verificações HTTP pelo kernel real**, sem navegador. Suites anteriores de Oficina, Stock, associações e financeira geral não foram repetidas. O núcleo financeiro não foi alterado; a apresentação comum recebeu apenas o aviso condicional específico do recibo SGF. A alteração é PHP/HTML e não exige novo build JavaScript.

Cobertura: configuração desligada e recusa no percurso antigo, principal integral/dedução única, independência, repetição da mesma chave e outra chave, integridade/identidade/versão do recibo, omissão/duplicação/empresa/moeda/auditoria, alteração histórica entre preparação e validação, revogação de competências, troca de pessoa/contexto, append-only, rollback integral e recuperação após falha de importação, consulta com saldo indeterminado e delegação pelo controlador existente.

Dois processos efectivamente concorreram pela mesma confirmação. O bloqueio da primeira transacção na empresa foi identificado por `pg_blocking_pids`; após o commit, a segunda operação terminou com o resultado original, sem duplicação. Resultado final: uma obrigação, uma incorporação, três pagamentos originais, um evento de reconhecimento e um de incorporação.

HTTP confirmou a mesma posição financeira/HTML, recusa de escrita pelo leitor, contexto obsoleto 409, CSRF ausente 419, injecção de contexto 422, repetição sem segunda dívida e configuração sem decisão de pendentes. O servidor temporário escutou apenas em loopback 8047; a prova encerrou somente o processo que criou. Credenciais, cookies e configurações ficaram na pasta privada, fora do relatório versionável.

Para nova prova: executar `scripts/payable-history-sgf-run.mjs` com o Node fixado; depois `scripts/payable-history-sgf-http.mjs <tag>`, postchecks `post,native-post` e `scripts/summarize-payable-history-sgf.mjs <tag>`. O runner cria novas bases/roles; não usar a regressão sobre a fixture cujo reconhecimento final foi preservado, nem fazer reset. Retomas nomeadas servem apenas para fases ainda não executadas e consultas posteriores. Evidências anteriores e diagnósticos ficam preservados, sem apagar bases.

## Limites e preservação

Pendentes: produtor/importador operacional autenticado, frescura/cutover/responsabilidade financeira, composição instalada, paginação/carga do leitor financeiro existente, revisão visual e capacidade de implantação. A listagem financeira herdada continua integral; este incremento não declara optimização de volume dessa área nem Financeiro completo. Pagamentos novos, decisões de pendentes importados, reconciliação bancária e contabilidade continuam fora deste recorte.

Os seis registos protegidos, cache bloqueada, demonstrações, bases/acessos reais, provas/checkpoints anteriores e trabalho alheio foram preservados. Sem publicação, activação de Compras, migração/concessão real ou checkpoint presumidos.