compras/docs/passagem-historico-pagamentos.md

Passagem de histórico de pagamentos para obrigações

29/10/2026. Continuação autorizada pelo proprietário após a conferência do novo menu. Identificador técnico: PAYABLE-HISTORY-IMPORT-v1.

Resultado e limites

Implementada uma passagem explícita em duas etapas: preparar a fotografia dos pagamentos existentes e validá-la por pessoa distinta. A factura conferida mantém o principal integral. A obrigação comum passa a fornecer o saldo, deduzindo uma única vez apenas os pagamentos anteriormente confirmados. Pendentes e rejeitados conservam montantes/estados e não são deduzidos.

Não é um novo pagamento, afectação arbitrária ou reconciliação bancária. Não executa transferências, confirma pendentes, cria stock, consome novamente orçamento ou produz lançamentos contabilísticos. O circuito normal continua a recusar incorporar pagamentos implicitamente; o percurso novo tem acções e activação próprias.

Exemplo de referência: principal 1 160,00 MZN, confirmado 300,00 e pendente 100,00 → saldo 860,00. Prova PostgreSQL integrada: principal 11 600,00, confirmado 3 000,00, pendente 1 000,00 e rejeitado 500,00 → saldo 8 600,00; pendente/rejeitado não reduzem o saldo. Vencimento e dias de atraso mantêm-se nulos.

Responsabilidade e preservação

• Fonte única em sgf-tempo/packages/payables: HistoricalPayments, HistorySchema e extensão opcional de Payables; sem segundo motor de saldo no adaptador Compras.
• principal() conserva o principal documental; balance() consulta a posição do núcleo. ExternalPaymentWorkflow::outstanding() recebe o saldo comum já líquido, sem voltar a subtrair os mesmos pagamentos.
• A fotografia guarda IDs, empresa/documento/moeda, valor, estado, autor/data e referências das auditorias de registo/decisão. Não copia referências externas cifradas, comprovativos, contas bancárias ou instruções de pagamento.
• O adaptador confere que a auditoria corresponde ao pagamento, factura, valor, estado e interveniente. Confirmações/rejeições exigem decisão independente; a importação não reescreve decisões históricas em função dos perfis actuais desses antigos intervenientes.
• Identidade canónica por instância/empresa/documento, chave única por pagamento original e uma importação por obrigação/origem. Mudança de identidade não pode criar uma segunda obrigação para a mesma factura local.
• Mudança de pagamentos entre preparação e validação produz conflito e exige nova fotografia. Leitura posterior detecta origem/histórico divergente e deixa o saldo indisponível, conservando principal/originais. Desactivar a integração com obrigação incorporada não autoriza cair silenciosamente no saldo antigo.
• A gravação do principal, passagem, ligações, eventos e idempotência é transaccional. Falha intermédia não deixa incorporação parcial. A importação não altera as tabelas originais de factura, pagamentos, orçamento ou stock.

Esquema, acesso e interface

Migração aditiva 2026_10_29_000022_create_payable_history_imports.php, com duas tabelas append-only: pa_history_imports e pa_imported_payments. Reutiliza os direitos explícitos de preparação/validação existentes; a validação própria permanece recusada. Não cria contas nem concessões.

Activação separada COMMON_PAYABLES_HISTORY_ENABLED=false por omissão. Exige integração anterior activa, esquema completo e adaptador com fornecedor de histórico. O SGF mantém o percurso anterior sem pagamentos; esta entrega não configura automaticamente um fornecedor de pagamentos históricos no adaptador SGF.

Na página comum, quando activado e existindo pagamentos na factura, surge «Incorporar factura com pagamentos anteriores». A proposta apresenta confirmados/pendentes/rejeitados. A obrigação apresenta principal e saldo por liquidar separadamente. As fotografias antigas continuam consultáveis. Depois da passagem, novos pagamentos e confirmação de pendentes ficam para o incremento do circuito comum; não continuar a escrever pelo percurso antigo após transferir a responsabilidade.

Estado de aplicação

Após orientação posterior «continue», 000022 aplicada em compras_dev, lote 23, e COMMON_PAYABLES_HISTORY_ENABLED=true guardado no .env local. Novo backup privado de 367 910 bytes, SHA-256 1f29bdaf0ea0379475c26e78f07cffe2ca31401ab216031b499c2562bafad7dc, restaurado e comparado nas 72 tabelas antes da aplicação; base de restauro removida. Registos/restrições anteriores preservados na aplicação transaccional; duas tabelas novas vazias e dois triggers append-only conferidos.

Activação registada em supplier_payables.history_local_activated, sem criar conta ou alterar concessões. Projecções dos registos das 72 tabelas anteriores conferidas novamente, descontando apenas o registo da nova migração e a nova entrada de auditoria. Identidade da instalação e permissões anteriores preservadas. A configuração foi confirmada num processo novo: activação histórica verdadeira, uma conta, três direitos anteriores e zero facturas/pagamentos/obrigações. Nenhuma incorporação automática.

Evidências sanitizadas: historico-migracao-000022.json e historico-activacao-local.json. Backup/manifesto privados em storage/app/private/backups/payable-history-000022-20261029-193307-f5d793/.

As demonstrações persistentes e o servidor público não foram migrados/configurados nesta aplicação. Conferência só de leitura em 8005 confirmou activação histórica falsa e ausência das tabelas novas nesse ambiente. A demonstração não passa a ter histórico sintético por consequência da activação de compras_dev. Migração/activação anteriores 000021, menus e acessos do proprietário preservados. A interface nova foi conferida por resposta HTML nas provas PostgreSQL, sem uma nova prova visual no navegador.

Provas

PayableHistoryImportTest.php: principal bruto/saldo, decisão independente, repetição da mesma chave e de chaves distintas, pagamentos pendentes/rejeitados, total liquidado, alteração entre proposta/validação, ausência de auditoria, falha/recuperação, imutabilidade, configuração desactivada, duplicações/omissões/incompatibilidades, mudança de identidade e exemplo 1 160−300=860.

scripts/payable-history-proof.mjs: cria bases/roles QA exclusivas, regista/conferencia os pagamentos sintéticos pelo circuito existente, injecta uma falha e valida simultaneamente em dois processos. Confere uma obrigação, uma importação, três ligações, saldo correcto, original de negócio intacto, protecções SQL e recusa de alteração histórica; elimina as bases/roles no final. Relatório sanitizado: proofs/payable-history-pg.json.

Regressão geral: 517 aprovados, 2 ignorados, 4 337 asserções (519 testes). Após o reforço final da consulta de identidade, repetida a bateria específica: 11 aprovados, 64 asserções. PHPStan dos adaptadores/controlador e Pint do âmbito aprovados. A prova antiga de obrigações sem pagamentos também passou em Compras e SGF, com concorrência/recuperação e efeitos de orçamento/stock/pagamentos preservados. As bases e roles de ambas as provas PostgreSQL foram removidas.

Leitura anterior à aplicação: 000022 não aplicada e importação histórica desactivada. A aplicação/activação posteriores estão registadas acima. Não há build novo neste incremento PHP/esquema; o frontend e os menus anteriores não foram alterados. As verificações técnicas e a activação local não constituem aceitação visual ou publicação, nem executam pagamentos.