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](proofs/preview-coherence.json).
- 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](proofs/preview-http-results.json).
- 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](proofs/preview-browser-results.json).

Provas visuais: [desktop](proofs/preview-01-desktop.png), [desactualização](proofs/preview-02-stale.png), [ecrã pequeno](proofs/preview-03-small-screen.png), [histórico](proofs/preview-04-historical.png), [histórico em ecrã pequeno](proofs/preview-05-history-small.png), [configuração em consulta](proofs/preview-06-reader-configuration.png). 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
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.