SGF/docs/DRAFT_INVOICE_PREVIEW_DELIVERY.md

Primeira pré-visualização documental — entrega técnica

Data: 26 de Outubro de 2026 (Africa/Johannesburg). Implementação e provas concluídas; concessão real de configuração especificamente confirmada e aplicada. Entrega pronta para validação do utilizador, sem a declarar aceite, nem à preparação documental anterior. Preservar identidade 26b80df, A ca13acb, B1 8fcd52c e as alterações posteriores ainda não incluídas num novo checkpoint.

Funcional

Em Rascunhos de facturação → abrir rascunho → Pré-visualizar rascunho, a aplicação apresenta dados reutilizados do emitente, cliente, linhas, preparação de datas/condições/moeda/unidades e instruções seleccionadas. Não se redigitam cadastros ou identificadores bancários. A apresentação configura-se separadamente em Apresentação do rascunho, no âmbito da empresa.

O aviso exacto RASCUNHO — SEM VALIDADE FISCAL fica fixo no topo da janela, em desktop e ecrã pequeno, e repete-se na folha visual. A configuração não dispõe de campos para alterar/ocultar aviso ou pendências; a API e o trigger SQL recusam campos fora do catálogo. As regras de estilo para a impressão normal do navegador mantêm aviso e pendências. Não existe função de impressão, exportação ou PDF no SGF neste incremento.

Os rótulos são Preço proposto, Valor aritmético provisório, Imposto por apurar e Total definitivo por apurar. O valor aritmético reutiliza a operação decimal exacta já existente. Falta de quantidade/preço mantém valor desconhecido, enquanto zero explicitamente guardado continua zero. Imposto e total definitivo mostram «Não apurado». Moeda ausente mostra «Moeda por definir»; não se presume MZN, não se somam moedas diferentes e não se decompõe preço com imposto incluído desconhecido. Nenhuma base aritmética é promovida a base tributável.

Campos em falta e pendências mantêm rótulos próprios, incluindo validação legal/fiscal, moeda, modo de preço, condições/vencimento e origem alterada. Dados preenchidos não passam a fiscalmente validados. O instante de consulta é rotulado como consulta, distinto de data/período do serviço e vencimento proposto. Não há data efectiva de emissão, número fiscal ou estado emitido.

Configuração delimitada e recursos

O modelo por empresa tem versão e histórico append-only. Permite apresentar/omitir os blocos opcionais de logótipo, contactos, observações e instruções seleccionadas. Omitir blocos não elimina as pendências de negócio/documentais. Contactos e observações são texto de apresentação configurado uma vez por empresa; não havia campos de contacto empresarial nesses cadastros, e não se usa automaticamente o email privado do utilizador.

As instruções aplicáveis são as selecções já guardadas na preparação de cada rascunho; não se criam novas escolhas de meio de recebimento, cobranças ou ligações bancárias. A configuração só controla a apresentação desse bloco. A leitura de valores completos exige os direitos existentes e não os envia para logs, URLs ou relatórios de prova.

Limitação identificada antes da implementação: não havia logótipo empresarial nos recursos existentes. A opção de apresentação funciona, mas sem recurso surge «Logótipo opcional não disponível». Não se extraiu uma marca das imagens nem se criou/importou uma identidade visual. O resolvedor aceita apenas PNG local autorizado, até 512 KiB, do disco privado local no caminho fixo document-logos/company-<ID>.png; valida assinatura/MIME e inclui os bytes na resposta, sem pedido externo. Não há upload, URL configurável ou escolha arbitrária de ficheiro. Qualquer colocação futura de imagem deve ter autorização própria; não copiar os exemplos como recurso por omissão.

Contactos, observações, descrições e instruções são renderizados como texto escapado por React, sem HTML executável, links automáticos ou recursos externos. O modelo não permite HTML/CSS livre, regras de cálculo ou campos personalizados. O conteúdo não sai para serviços de renderização de terceiros.

Consulta coerente e actualização explícita

Cada composição HTTP inicia uma transacção PostgreSQL REPEATABLE READ READ ONLY antes de ler dados e permissões. Configuração, cadastros, linhas, pendências e instruções vêm da mesma fotografia de leitura. A consulta não cria registos, resolve pendências, audita uma alteração de negócio, confirma ou emite documentos. A configuração é uma operação de escrita distinta, autorizada e auditada.

A resposta inclui uma revisão HMAC e metadados de versão; o instante da consulta fica fora dessa revisão. O endpoint de verificação devolve só a revisão. No navegador, verifica-se a cada dez segundos enquanto visível e ao regressar à janela. Uma mudança mostra Pré-visualização desactualizada, mantendo os valores já apresentados; só Actualizar pré-visualização substitui o conteúdo. Falha/recusa de nova consulta remove o conteúdo. A verificação é periódica, não uma notificação instantânea por push.

As consultas e revisões revalidam contexto, pertenças, empresa/unidade e permissões no servidor; respostas têm Cache-Control: no-store. A mudança de contexto desmonta a vista e elimina o estado anterior da interface. Não há cache partilhada nem reutilização de dados entre empresas/unidades. A revisão é autenticada com chave do servidor, sem permitir adivinhar identificadores bancários a partir de um hash simples.

Histórico B1 separado

Em registos confirmados, a acção é Abrir confirmação interna histórica. O endpoint de rascunho recusa esse registo com 409 e indica a vista histórica. A nova vista usa exclusivamente a fotografia B1 preservada para o conteúdo, incluindo linhas, valores e dados documentais/instruções que tenham sido capturados no esquema 2. Não lê a configuração actual para enriquecer a história.

Campos não capturados mostram Não capturado nesta confirmação. As fotografias existentes não contêm logótipo/contactos/observações do modelo nem a denominação do emitente: não se completa essa informação a partir da empresa actual. A denominação actual no cabeçalho geral da aplicação indica apenas o contexto autorizado; não é inserida no documento histórico. A vista distingue autor/instante de confirmação, instante desta consulta, esquema da fotografia e ausência de modelo histórico capturado.

Nenhuma fotografia foi alterada ou reconstruída. As vistas antigas/esquema 2 continuam distintas de uma factura emitida. O mesmo aviso de ausência de validade fiscal acompanha a consulta histórica.

Migração e preservação

Delta aditivo apresentado antes da aplicação: 2026_10_26_020000_create_document_preview_models, testado em sgf_tempo_test e aplicado em sgf_tempo_dev pelo wrapper/proprietário separado.

• Cria document_preview_models (empresa, configuração, versão) e document_preview_model_history (versão preservada, autor, instante).
• Acrescenta constraints/triggers para pertença imutável, versão, campos configuráveis fixos e histórico append-only.
• Permite document_preview.configure apenas no âmbito da empresa; a migração não concede o direito.
• Não cria emissão, numeração, datas fiscais, impostos, recebimentos ou lançamentos. Rollback automático recusado para preservar o histórico; eventual reversão exige procedimento revisto.

document-preservation.php foi alargado para comparar também doc_records/doc_history. A comparação antes/depois da migração confirmou conteúdo e contagens exactamente iguais em identidade, A, B1 e preparação documental. Não houve reset/fresh/limpeza destrutiva de desenvolvimento. Após a aplicação, as duas tabelas de modelo estavam vazias em desenvolvimento; não se criaram configurações de demonstração na Tempo Lda. A aplicação normal manteve a ligação a sgf_tempo_dev e o papel sgf_dev_app sem administração PostgreSQL.

Acessos confirmados e aplicados

Consulta de rascunho reutiliza os direitos explícitos existentes: consulta da empresa/unidade, facturação, clientes e dados documentais de emitente/cliente/unidade. Consulta de configuração usa issuer_documents.view. Histórico v1 conserva a fronteira de consulta B1; conteúdo v2 com dados documentais exige também esses direitos de consulta. Nenhuma acção de leitura concede configuração ou emissão.

Contas existentes conferidas: ID 1 — Osmane Nala; ID 2 — Samira Nal. Operação concreta apresentada para confirmação: conceder apenas document_preview.configure ao ID 1 na Tempo Lda, empresa ID 1, unidade nula. Samira mantém os direitos de consulta existentes, sem novo direito de configuração. Não há gestão desse novo direito pela interface ou poder financeiro derivado.

Estado efectivo: o utilizador respondeu «Confirmar exactamente esta concessão». A conta e a empresa foram novamente conferidas; preview-access.php 1 1 --apply aplicou apenas document_preview.configure à conta 1 na empresa 1, com auditoria document_preview.access.initial_grant. A verificação posterior confirmou exactamente essa concessão, com unidade nula. Samira não recebeu configuração, os restantes direitos foram preservados e nenhuma configuração de demonstração foi criada em desenvolvimento. Não repetir a aplicação sem confirmação específica de uma nova operação.

Verificação

• Suite completa: 89 testes / 893 asserções aprovados, incluindo regressões da fundação e entregas anteriores. Aceitações não foram reabertas.
• Compilação final Vite aprovada: 16 módulos, sem mudança de versões, manifests ou lockfiles.
• Execução final apenas dos 13 testes novos: 13 testes / 210 asserções aprovados. A prova de navegador foi parada antes dessa execução, que também limpa as fixtures de teste.
• Testes de reutilização, consulta sem escritas, desconhecido distinto de zero, aritmética exacta, direitos explícitos, recusa de configuração para consulta, versões antigas, aviso/pendências não configuráveis, recurso externo recusado, revisão alterada, campos históricos não reconstruídos, acesso cruzado/revogação, PNG local, imutabilidade SQL e rollback de configuração.
• Prova concorrente com processos PHP/PostgreSQL: isolamento repeatable read verificado; uma consulta em curso manteve ambas as versões antigas enquanto outra transacção alterava emitente/cliente; nova consulta viu ambas as versões novas, sem mistura. Resultado.
• HTTP com login real sintético, CSRF e sessões distintas: configuração autorizada, leitor 403, campos proibidos 422, versão/contexto antigos 409, revisão sem conteúdo sensível e história independente do modelo actual. Resultado.
• Navegador: configuração pelo gestor sintético, leitura de rascunho, mudança em segundo separador com aviso sem substituir o texto antigo, actualização explícita, consulta histórica, leitor sem botão Guardar e remoção da vista após mudar unidade. Ecrã real de 390 × 844, sem transbordo horizontal, aviso visível no topo durante a rolagem. Registo sem valores bancários.

Provas visuais: desktop, desactualização, ecrã pequeno, histórico, histórico em ecrã pequeno, configuração em consulta. As provas omitem valores completos das instruções; o bloco foi desactivado apenas na configuração sintética, mantendo as pendências. O comportamento de apresentação de instruções seleccionadas foi verificado por testes e HTTP.

As provas usaram exclusivamente a instância na porta 8001 e sgf_tempo_test, sem mudar a ligação normal ou introduzir demonstrações na Tempo Lda. A dimensão temporária do navegador foi reposta; os separadores de prova foram fechados. Sem publicação ou processos alheios terminados.

Ficheiros e navegação

Novos: app/Modules/Services/DocumentPreview.php, Http/DocumentPreviewController.php, resources/js/DocumentPreview.jsx, migração indicada, DocumentPreviewTest.php, fixture própria e scripts preview-access.php, preview-status.php, preview-http-proof.mjs, preview-coherence-proof.php, preview-coherence-worker.php. Integração em rotas, navegação, ServicesWorkspace e CSS; fixture de navegador e verificação de preservação adaptadas.

1. Actualizar o navegador e entrar; seleccionar Tempo Lda / SEGI.
2. Se ainda não houver rascunho, usar o percurso existente: Clientes → Serviços → Prestações em rascunho → abrir prestação → Preparar rascunho de facturação; completar os dados em Preparação documental, conforme necessário.
3. Rascunhos de facturação → seleccionar um rascunho não confirmado → Pré-visualizar rascunho.
4. Se houver aviso de alteração, usar Actualizar pré-visualização. A abertura/actualização não confirma nem emite.
5. Apresentação do rascunho permite consultar a configuração. Osmane pode guardar a apresentação; Samira permanece em consulta. Actualizar a sessão, saindo e entrando novamente se necessário, para carregar a concessão aplicada.
6. Para história: Rascunhos de facturação → seleccionar registo confirmado → Abrir confirmação interna histórica. Não completar campos históricos com dados actuais.

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 php scripts/preview-status.php
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 test --filter DocumentPreviewTest
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 npm run build

Limites

Apenas navegador. Sem PDF/exportação/impressão documental, emissão fiscal, data efectiva de emissão, número fiscal, novo cálculo de impostos, recibos, recebimentos, afectações, reconciliação ou lançamentos. Não se validaram novas fontes legais/fiscais ou regras de arredondamento. O modelo não é editor geral nem prova de conformidade. Não há recurso empresarial de logótipo instalado, carregamento externo ou upload. O restante âmbito e publicação continuam sem autorização. Esta entrega aguarda validação do utilizador.