74 lines
10 KiB
Markdown
74 lines
10 KiB
Markdown
# Preparação SGC → facturas SGF8085 — 10/11/2026
|
|
|
|
**Continuação posterior autorizada:** [ecrã e persistência auditada agora implementados](SGC_INVOICE_WORKSPACE_DELIVERY.md),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.
|
|
|
|
```powershell
|
|
& '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](proofs/sgc-8085-integration-preparation-20261110.json). 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.
|