compras/docs/integracao-factura-obrigacao.md

Factura → obrigação: navegação integrada e próxima ligação

29/10/2026. Continuação local durante a avaliação do proprietário.

Activação local posterior

Após a orientação para prosseguir, o percurso foi activado em compras_dev, no ambiente local. Conferida a única conta existente, #1, administrativa, empresa #1; concedidas explicitamente consulta/preparação/validação em pa_access, com pessoa estável local-user-1 e auditoria supplier_payables.local_activated. Nome, palavra-passe, perfil e dados anteriores da conta foram preservados. Não se criou nova conta nem se dispensa revisor distinto do preparador.

COMMON_PAYABLES_ENABLED=true e identidade persistente própria foram guardados apenas no .env local, depois de novo backup privado de 367 719 bytes, restaurado e comparado nas 72 tabelas. O servidor público e as configurações das demonstrações não foram alterados. A aplicação tem zero facturas, zero pagamentos e zero obrigações; não houve importação, reconhecimento ou operação financeira automática. Evidência sem segredos: obrigacoes-activacao-local.json.

Acrescentada ligação «Obrigações a fornecedores» no menu Finanças quando a consulta está autorizada pelo servidor. A navegação usa carregamento de página completo, porque a página comum não é uma resposta Inertia. A revogação de consulta retira o menu e mantém a recusa no servidor. Testes de integração/navegação e pagamentos: 39 aprovados, 152 asserções; build, TypeScript e PHPStan do middleware aprovados. O PHPUnit fixa a desactivação e identidade vazia por omissão, para não herdar a activação de .env nos restantes testes.

O arranque adicional do servidor em 8015 foi recusado pela revisão automática (blocked by policy, sem motivo específico devolvido); não se contornou essa recusa. A configuração activada foi verificada num processo novo. A demonstração em 8005 continua disponível, com a nova ligação de menu após actualizar a página.

Para desactivar esta configuração enquanto não houver obrigações, definir somente COMMON_PAYABLES_ENABLED=false; conservar a identidade da instalação e a auditoria. Não alterar identidade ou apagar direitos/histórico como mecanismo de reversão. Havendo obrigações, preparar a transição da responsabilidade pelo saldo antes de qualquer desactivação. A activação local não conclui a migração dos pagamentos históricos nem autoriza uso financeiro real.

Aplicação autorizada à instalação local

Após pedido expresso «aplique», 000021 foi aplicada em compras_dev, lote 22, em 29/10/2026. Backup privado de 346 030 bytes, SHA-256 481a4d2a7430e0a43c0a7ba4c190f22e5a2520a5423587f90579bcfb917d373a, restaurado e comparado numa base separada antes da aplicação; base de restauro removida. As 65 tabelas anteriores, os seus registos, restrições e .env ficaram preservados. Sete tabelas novas vazias e seis triggers append-only conferidos. Aplicação e verificação feitas em transacção, com limites de bloqueio/execução, sem seeds.

Evidência sanitizada: obrigacoes-migracao-000021.json. Backup e manifesto privados em storage/app/private/backups/supplier-payables-000021-20261029-185002-93c089/. A activação continua desligada e nenhum acesso/conta foi criado. As demonstrações persistentes e o servidor público não foram alterados. A aplicação do esquema não incorpora facturas nem constitui obrigações automaticamente.

Continuação: instalação do esquema e ativação explícita

Preparada a migração 2026_10_29_000021_create_supplier_payables.php, utilizando PayablesSchema do pacote comum. O instalador QA usa a mesma definição: não existe uma segunda cópia do esquema. PostgreSQL e SQLite têm protecção append-only para origens, propostas, obrigações, comandos, eventos e outbox. Instalação sobre tabelas existentes ou parciais recusa reconciliação implícita. O instalador QA pode reconhecer a instalação completa da migração e confere os seis triggers PostgreSQL.

COMMON_PAYABLES_ENABLED=false é o estado inicial. A activação explícita exige PAYABLE_SOURCE_INSTANCE persistente e esquema instalado; não concede qualquer direito. As entradas QA existentes mantêm o reconhecimento isolado anterior. O saldo passa a conferir também a identidade canónica da origem; mudar a identidade de instalação com obrigações existentes provoca conflito em vez de cair no saldo antigo.

Estado anterior à autorização de aplicação: migração apenas preparada. A aplicação posterior em compras_dev está registada acima; as demonstrações persistentes, .env, contas, concessões e facturas reais continuam inalterados. A interface mantém identificação de ensaio, sem activação financeira real.

Facturas com pagamentos anteriores mantêm o saldo do percurso existente. A incorporação automática continua recusada; a transição com transporte explícito de histórico fica para incremento próprio. Nesta passagem não se regista ou executa nenhum novo pagamento real, nem se desbloqueiam pagamentos posteriores sobre uma obrigação incorporada.

Novos testes SupplierPayableIntegrationTest.php: activação no esquema de aplicação, reconhecimento único, principal de 6 000 centavos e vencimento nulo, saldo preservado de 2 000 após pagamento confirmado de 4 000 sobre factura de 6 000, recusa de segunda dívida, controlo de acesso/empresa, mudança de identidade e imutabilidade. Com facturas/pagamentos: 60 testes aprovados, 215 asserções. Todas as operações destes testes são em SQLite em memória, não na demonstração.

Prova PostgreSQL payables-demo.ps1 proof aprovada nos dois hosts, com instalação da nova migração em Compras e instalação QA comum em SGF: obrigação única de 11 600 MZN, vencimento desconhecido, concorrência, falhas/recuperação, versões e isolamento; orçamento/stock/pagamentos conservados. Bases e roles descartáveis removidas. PHPStan do adaptador/controlador aprovado e formatação Pint dos ficheiros deste incremento aplicada. A primeira execução PHPStan com 128 MB tinha esgotado memória; repetição com limite de 512 MB aprovada, sem configuração global.

Regressão completa após este incremento: 503 aprovados, 2 ignorados, 4 167 asserções (505 testes). Mantêm-se dois testes anteriormente ignorados; não foram apresentados como executados. Sem novo build necessário neste incremento exclusivamente PHP/configuração/migração; o build do incremento anterior mantém-se aprovado.

Alteração entregue

Cada factura apresenta uma ligação para /obrigacoes-fornecedores?invoice={id} quando o utilizador tem consulta do núcleo comum na instalação sintética. A página mostra apenas o documento seleccionado, as propostas, a obrigação e os eventos da respectiva identidade canónica. O regresso leva a /facturas. O endpoint de consulta aceita o mesmo filtro; a consulta geral mantém-se.

O filtro usa empresa do utilizador e Payables::identity, não apenas o número visível ou o identificador local. Parâmetros inválidos recebem 422; facturas inexistentes ou fora da empresa não são adoptadas. Sem filtro, o comportamento anterior é preservado. Não há reconhecimento, pagamento, consumo de stock/orçamento ou alteração de histórico por navegação.

Conferência da integração existente

• Compras já fornece factura, fornecedor, ordem, moeda, valores/linhas e a referência da auditoria de conferência ao núcleo único. Não se redigitam esses dados no reconhecimento.
• O núcleo conserva uma identidade por instância/empresa/documento e uma revisão da origem. A conferência documental e a validação da obrigação são decisões separadas.
• O principal comum já é consultado pelo saldo de Compras quando a origem está incorporada e compatível. Origem alterada ou pagamentos associados provocam conflito; não se presume outro saldo.
• A incorporação continua limitada às bases QA reconhecidas. A consulta integrada não publica nem instala o esquema na base habitual de Compras.
• Vencimento desconhecido permanece pendência visível; não impede por si só reconhecer o principal, não é uma data inventada e não produz atraso igual a zero.

Próximo incremento funcional a delimitar

Integrar a incorporação no percurso normal exige transportar o esquema QA para migrações de aplicação, configurar a identidade persistente da instalação e os direitos por empresa, e definir a transição das facturas já existentes. A configuração será verificável antes de aplicação; não executar migrações reais por consequência deste relatório.

Facturas sem pagamentos podem seguir a origem conferida e o reconhecimento existente. Para facturas com pagamentos, o plano deve preservar separadamente principal original, pagamentos confirmados e pendentes, e atribuir uma só responsabilidade pelo saldo. Nunca importar o saldo líquido como principal e deduzir pagamentos novamente. O caminho de pagamentos existente é conservado até essa transição estar implementada e verificada.

Revisão documental de vencimento é outro incremento: evidência, autor, versão anterior e histórico, sobre a mesma obrigação. Não inferir data a partir de texto livre nem transformar revisão documental em nova dívida. Não incluir cancelamento de ordens, estornos, notas de crédito ou operações bancárias neste delta de navegação.

Verificação

• scripts/invoice-payable-link-check.mjs: consulta da factura presente na demonstração, filtro, regresso, identificadores inválidos/inexistentes e igualdade integral da consulta/histórico antes e depois. Resultado em proofs/invoice-payable-link.json. A demonstração tem uma factura: esta prova HTTP não declara teste de duas origens distintas ou de concorrência.
• Regressão dirigida: InvoiceTest.php e ExternalPaymentTest.php, 56 aprovados, 195 asserções, SQLite em memória. A primeira tentativa não executou os testes por falta do driver; repetição com -d extension=pdo_sqlite -d extension=sqlite3 aprovada, sem alteração global do PHP.
• Build frontend aprovado, sem novas dependências. Sintaxe PHP e git diff --check aprovados.
• PHPStan dos dois ficheiros PHP alterados aprovado, sem erros, com limite de memória de 512 MB por comando; a tentativa inicial com 128 MB esgotou memória, sem alterar configuração global.
• Sem declaração de revisão visual, aceitação, publicação ou checkpoint. Dados e acessos de avaliação conservados.