SGF/docs/SGC_8085_INTEGRATION_PREPARATION.md

Preparação SGC → facturas SGF8085 — 10/11/2026

Continuação posterior autorizada: ecrã e persistência auditada agora implementados,20 casos únicos/142 asserções e14 verificações PostgreSQL entre aplicações. Novo pacote inactivo 3bb99e866f52965dbb7d; o anterior mantém-se preservado. As menções abaixo a ecrã/persistência por implementar descrevem a preparação anterior. Instalação/configuração/activação continuam pendentes, sem alterar8085.

Preparação técnica entregue; ligação ainda não instalada/activada em8085. Não foi criada outra demonstração, base, role, porta, conta ou concessão. O percurso de Compras já concluído em8085 mantém código, dados e configuração anteriores.

O que existe e o que falta

Peça	Estado desta entrega	Antes de utilizar
Endpoint SGF	Implementado e78 provas válidas reutilizadas; permanece desligado	Instalar o pacote preparado na mesma8085, sem trocar motor/livro; conferir código ainda desligado
Cliente de transporte SGC	Implementado, com prévia, aprovação exacta e recuperação da mesma intenção	Compor o ficheiro verificado pelo hash no SGC e configurar uma ligação aprovada
Gateway nativo SGC	SgfInvoiceGateway, sem listeners/rotas/jobs; configuração desligada	Ligar a uma acção autenticada do percurso de envio, com autoridade financeira actual
Origem documental	Contrato apenas para rascunho ainda não registado no SGC, autoridade única SGF	Implementar o ecrã/armazenamento durável desse rascunho/intenção/decisão/recibo; ainda não entregue como fluxo utilizável do SGC
Mapeamentos	Modelo preparado, nenhuma selecção ou associação criada	Escolher/versionar/conferir tenant de origem e empresa/unidade de destino, ordem e cada linha; sem inferência por nomes/NUIT/IDs coincidentes
Principal e segredo	Nenhum criado; modelos com camposNULL e enabled=false	Aprovar identidade QA, direitos existentes, versões de autenticação/contexto e provisionar bearer privado por via protegida
Ensaio SGC→8085	Contrato provado por fakes e kernel real no livro de regressão existente	Após autorização, ensaio de rede nas duas aplicações e nessa mesma8085, com novo documento sintético e confirmação individual

Instalar código desligado, configurar identidades/segredos e activar tráfego são passos distintos. Nenhum foi executado por consequência deste pedido de preparação sem activar. Não basta mudar uma flag para declarar o percurso de envio do SGC concluído.

Fronteira de autoridade

O SGC está no projecto C:/laragon/www/compras, produto autónomo sobre o mesmo núcleo. Os livros do SGC e de8085 não são automaticamente o mesmo livro. Uma factura já registada/validada/paga no SGC não deve ser reenviada como se fosse nova em8085: isso pode duplicar documentos, consumo e responsabilidade. Este cliente recusa estados de origem diferentes de unregistered_draft; não intercepta InvoiceWorkflow nem exporta Invoice existentes.

O próximo ecrã de envio terá de capturar/conservar o documento recebido antes de o registar financeiramente no SGC. O cliente não cria essa fonte nem comprova que uma declaração de rascunho corresponde a um estado real: o adaptador do futuro ecrã deverá reler a fonte autorizada e impedir o fluxo local concorrente. Se a decisão for partilhar o mesmo livro/instância em vez de transportar rascunhos, deve usar referência à factura existente, não uma segunda chamada de criação. Essa mudança de topologia e a migração de documentos históricos não estão presumidas.

O endpoint confirma só uma factura pendente em8085. Revisão distinta, consumo, obrigação, pagamento e contabilidade continuam nos mecanismos existentes. received_pending no cliente significa recepção documental pelo SGF, não validação financeira ou conclusão da compra.

Cliente preparado

Ficheiro portátil: packages/sgc-invoice-client/src/InvoiceClient.php, sem dependência de Laravel, base, ficheiros ou relógio. O transporte é injectado. Destino permitido neste recorte: exclusivamente http://127.0.0.1:8085, sem redirects nem URLs fornecidos pelo payload. Uma utilização remota/TLS requer recorte próprio.

intent(mapping, draft, key, reason) exige mapeamento explícito/versionado e UUID escolhido uma única vez; não faz rede nem escolhe entidades. Converte só as referências de linha aprovadas para IDs de destino, recusa âmbito diferente, duplicação/mapeamento em falta, floats e campos inesperados. A intenção inclui hashes do rascunho, mapeamento e ligação, sem bearer.

preview(intent, currentSourceVersion, currentMappingHash) confere a mesma origem/mapeamento/ligação, lê a ordem exacta e pede a prévia. Não confirma. Pode recuperar um recibo já confirmado pelo mesmo UUID.

confirm(state, approvedHash, currentSourceVersion, currentMappingHash) só aceita a decisão sobre esse impacto exacto e versão actual. Conserva UUID, cut e conteúdo quando a resposta é incerta. Timeout,503, redirects ou resposta de sucesso incoerente não são tratados como sucesso confirmado. Não há retry automático nem nova chave automática;401/403 bloqueiam,409 exige conferência. Uma recuperação explícita devolve o mesmo recibo pendente. As mensagens de transporte não são expostas e bearer não entra em estados serializáveis/debug.

O SGC ganhou app/Services/SgfInvoiceGateway.php e config/sgf_invoice.php. O gateway só cria o cliente com configuração aprovada/activa e pacote com hash verificado; relê a pessoa/empresa nativa, função financeira e exclusão de manutenção, tanto ao criar o cliente como imediatamente antes de cada operação de rede. Alteração da configuração impede usar o objecto antigo. A configuração entregue é enabled=false, pacoteNULL, hashNULL, ligações vazias; nenhum processo existente o invoca.

Persistência e interface ainda necessárias

A intenção é um envelope de transporte, não uma outbox persistida: não foi criada migração/tabela nem usado ficheiro/cache como armazenamento informal. O chamador do SGC ainda precisa de persistência auditada e ecrã de conferência. Contrato preparado para essa implementação:

1. Guardar fonte autorizada, versão, mapeamento/hash, UUID e intenção antes do primeiro envio. Uma fonte com envio pendente/incerto não pode gerar outra intenção/chave sem resolução explícita.
2. Conservar prévia, impacto e approval_hash; apresentar ao utilizador e registar a decisão individual, pessoa, data e fundamento.
3. Guardar o estado de confirmação em curso antes da rede. Se houver interrupção depois do commit remoto, recuperar pelo mesmo conteúdo/UUID/cut.
4. Guardar recibo invoice_id/order_id/pending, referência de origem e transições anteriores/posteriores. Não confiar apenas no retorno do browser nem iniciar validação financeira no SGC.
5. Antes de nova prévia/confirmação, reler pessoa/permissões, fonte, versão e mapeamento. Uma alteração invalida a conferência. Rotação de contexto também exige nova conferência; uma operação com resultado incerto não pode ser abandonada e refeita com outra chave.

Nenhuma nova tabela/direito foi concedida ou instalada. A futura persistência exige um desenho de migração/retencão e prova própria; a instalação em base operacional deverá ter autorização específica. Este relatório não declara essas capacidades implementadas.

Pacote de8085 preparado e verificável

Identificador: d09aac9d09da98e61df5. Local privado: C:/laragon/data/sgf-tempo/run/modular-regression-2576427d1939/private/receipt-composition-cc50a276c10c/prepared-sgc-invoice/d09aac9d09da98e61df5.

Contém oito ficheiros do endpoint para8085, três ficheiros do cliente/gateway/configuração, modelos não preenchidos e manifesto de hashes. Guarda as duas versões anteriores de bootstrap/navegação; não contém .env, binding, estado da instalação, contas ou credenciais. Bootstrap/navegação diferem somente pelas rotas SGC; o writer/controlador/runtime existentes não são substituídos.

& 'C:/laragon/tools/sgf-tempo/node-v24.22.1-win-arm64/node.exe' scripts/prepare-sgc-8085.mjs check

O comando verifica o código actual de8085, os78 resultados aceites e os hashes da preparação, sem instalar/activar/iniciar serviços/migrar/limpar cache. prepare cria apenas essa área de revisão fora da aplicação. Não existe opção de aplicar neste comando. Qualquer alteração posterior do destino ou do código exige nova conferência; não copiar o pacote às cegas sobre trabalho alheio. O script de actualização geral anterior não inclui estes oito ficheiros.

Depois de autorizado instalar código desligado: conferir hashes/pré-condições, backup privado dos ficheiros a substituir, aplicar apenas a allowlist e verificar /compras e a recusa404 do endpoint desligado. Reversão de código não desfaz dados; depois de um futuro envio confirmado, conservar o recibo e usar recuperação, nunca reset como rollback.

Evidência e limitações

16 testes Unit/46 asserções novos, sem base/rede: mapeamento, âmbito, documento já registado, fonte/mapeamento/contexto alterados, decisão individual, cabeçalhos, recuperação, estados de falha e gateway desligado. Seis verificações adicionais ligam o cliente ao kernel real no livro de regressão da77bb730751: consulta exacta/prévia real e recuperação de recibo existente, sem nova factura/evento persistido. As sequências de tentativa da prévia podem avançar nesse livro de regressão; não são revertidas artificialmente.

Os78 ensaios anteriores do endpoint e63 do percurso de8085 foram reutilizados por hash, não repetidos nem somados como cobertura nova do transporte.16 Unit+seis verificações de contrato não equivalem a22 testes de rede. Não foi executado tráfego para8085 nem comando/migração no piloto SGC. Os seis registos e a cache bloqueada não foram alterados;8085 manteve código e estado. Sem activação de candidatas, publicação, aceitação ou checkpoint. Visual, carga sustentada, TLS operacional, envio completo pela interface do SGC e implantação permanecem com provas próprias.

Prova da preparação. O pacote identifica ficheiros e hashes concretos para revisão; não representa autorização de aplicar/activar nem prova de um fluxo de utilizador ainda não implementado.