SGF/docs/DRAFT_INVOICE_PREVIEW_PLAN.md

Pré-visualização de factura de serviço — plano para aprovação

Data: 26 de Outubro de 2026 (Africa/Johannesburg). Apenas plano, critérios e decisões; não autoriza implementação ou publicação.

Actualização posterior: o utilizador fechou as decisões de configuração limitada, rótulos, actualização explícita e história B1 separada e autorizou a primeira implementação por prompt próprio. A execução está em DRAFT_INVOICE_PREVIEW_DELIVERY.md. A concessão efectiva de configuração é uma confirmação específica separada; o restante âmbito fiscal/contabilístico continua sem autorização.

Preservar a preparação documental entregue e o trabalho posterior ainda não incluído num novo checkpoint. Preservar identidade 26b80df, A ca13acb e B1 8fcd52c, com as respectivas aceitações. A preparação documental tem relatório próprio e não é declarada aceite por este plano. Não alterar código, bases, permissões, fotografias ou versões nesta etapa. Não foram repetidos testes.

Referências: SGF_TEMPO_Roteiro_v0_9.docx, BILLING_DOCUMENTS_FIELD_SPEC.md, DOCUMENT_PREPARATION_DELIVERY.md e SERVICES_B1_DELIVERY.md. Os três exemplos informam a organização do conteúdo, sem limitar o modelo ou validar obrigações legais.

Próximo incremento proposto

Acrescentar uma pré-visualização de leitura do rascunho de facturação de serviço, dentro da aplicação. Reutilizar dados existentes, sem duplicar cadastros, recolher novamente instruções de pagamento ou criar um novo documento emitido. Proposta inicial: um modelo comum, configurável de forma limitada e com versão identificada, apresentado no navegador. Sem PDF, exportação ou função de impressão neste incremento.

Mostrar permanentemente RASCUNHO — SEM VALIDADE FISCAL no cabeçalho e num aviso visível durante a navegação/rolagem. Repetir a indicação nas páginas visuais do documento. O aviso não pode ser removido por configuração. Uma eventual impressão pelo próprio navegador não é uma capacidade fiscal do SGF; a folha de impressão deve conservar o aviso. Não há número fiscal, data efectiva de emissão, assinatura fiscal ou estado de factura emitida.

Percurso proposto: Rascunhos de facturação → abrir registo → Pré-visualizar rascunho. A pré-visualização permite voltar aos menus de preparação autorizados; não edita silenciosamente os dados nem oferece botões de emissão, recebimento ou contabilização.

Conteúdo e origem

Bloco	Origem	Apresentação proposta / informação em falta
Identificação	Rascunho e contexto autorizado	Referência interna claramente rotulada, empresa/unidade, versão do rascunho e da preparação. Sem converter INT-B1 ou ID técnico em número de factura
Emitente	Nome da empresa e preparação documental	Denominação reutilizada, NUIT, morada, localidade e país quando preenchidos. Campo relevante vazio: «Por completar», sem inventar identificação
Cliente	Cliente seleccionado e preparação documental da empresa	Mesmo cadastro e versões, sem cópia por unidade. Nome basta para começar; restantes dados em falta permanecem visíveis
Serviço e origem	Prestação/rascunho existentes	Descrição, origem e versões. Não afirmar execução confirmada do serviço
Linhas	Linhas guardadas e unidades de medida preparadas	Serviço, descrição, quantidade, unidade e preço proposto. Desconhecido é «Por completar»; zero explicitamente guardado continua zero
Datas	Preparação documental	Data/período do serviço e vencimento proposto, separados. Condições e vencimento com pendência de compatibilidade; não inferir emissão ou competência contabilística
Moeda	Moeda guardada no rascunho	Código indicado, com validação pendente, ou «Moeda por definir». Nenhuma moeda por omissão
Modo de preço	Preparação guardada	«Por definir», «Imposto incluído — indicação proposta» ou «Imposto acrescido — indicação proposta». Não altera os preços existentes
Valores	Valores exactos já existentes	Preços propostos e, se disponível, valor aritmético já calculado pelo percurso existente, com rótulo provisório. Não chamar base tributável à base aritmética de A/B1
Impostos e total	Pendências existentes; sem motor fiscal	«Impostos não apurados» e «Total fiscal / montante definitivo: não apurado». Não mostrar imposto zero ou fabricar um total pela ausência de regra
Instruções para pagamento	Configurações do emitente explicitamente seleccionadas	Dados aplicáveis reutilizados, sem redigitação; designação/versão e indicação de introdução pelo utilizador, sem verificação bancária. Sem selecção: «Instruções não seleccionadas», nunca «pagamento pendente/recebido»
Completude	Verificações documentais existentes	Separar «Por completar», «Preenchido — não validado», «Validação pendente» e «Origem alterada». Mostrar origem e próxima acção

Sem moeda definida, qualquer expressão aritmética existente deve ser identificada como valor sem unidade monetária validada, sem símbolo monetário ou total definitivo. Não agregar moedas distintas. A escolha de imposto incluído/acrescido não autoriza decompor o preço, aplicar taxa, arredondar ou relançar valores anteriores. Não introduzir novos cálculos de impostos, descontos, câmbio ou totais fiscais.

Dados adicionais de gestão/estatísticas, extractos de conta, publicidade, contratos, descontos e logística ficam fora deste incremento. Dados bancários seleccionados são instruções do emitente para facilitar pagamento, não uma pergunta sobre como o cliente pagará.

Modelo configurável proposto

Usar um núcleo de conteúdo comum e configuração limitada de apresentação, sem motor geral de campos personalizados. Não reproduzir obrigatoriamente as colunas, marcas, bancos ou rodapés das imagens fornecidas.

Proposta mínima de configuração: ordem dos blocos opcionais, visibilidade de dados opcionais já autorizados e rótulos de apresentação não fiscais. Modelo base por empresa, com versão; eventual logótipo só se houver activo autorizado disponível. Não criar agora um editor livre de HTML, uploads ou integrações. A leitura/configuração do modelo não altera regras de negócio ou permissões sobre o conteúdo.

Não configuráveis: aviso de rascunho, ausência de emissão, distinção entre provisório e definitivo, indicação de impostos não apurados, identificação das origens/versões e pendências relevantes. Ocultar um campo opcional do desenho não resolve nem elimina uma pendência no painel de completude. Dados em falta não devem ser ocultados para produzir aparência de documento completo.

Propor um desenho sóbrio com identificação das partes, linhas, datas e condições, secção de valores provisórios, instruções e pendências. O painel de trabalho pode apresentar metadados de contexto e versões separado da folha visual. A configuração não é um mecanismo de autorização nem prova de conformidade fiscal.

Actualidade e preservação histórica

• Rascunho editável: proposta de leitura conjunta coerente das versões actuais autorizadas, com indicação das versões de empresa/cliente/preparação/linhas/instruções e instante de consulta rotulado como tal, nunca emissão. A confirmação de geração não deve gravar nova fotografia B1 nem alterar estados.
• Se os dados mudarem enquanto a pré-visualização estiver aberta, indicar «Pré-visualização desactualizada — actualizar». A actualização é explícita; não substituir silenciosamente valores ou instruções já visíveis. A estratégia de detecção (ao regressar/recarregar, sem actualização automática contínua) deve ser aprovada antes de implementar.
• Registo já confirmado B1: não montar um documento aparentemente histórico com cadastros actuais. Proposta: manter a consulta histórica B1 separada e usar exclusivamente a fotografia guardada. Formato antigo sem determinado campo mostra «Não capturado nesta confirmação», sem o ir buscar ao cadastro actual. Esquema 2 mostra apenas os dados capturados na sua versão.
• Não chamar à consulta B1 uma factura ou emissão. Manter «Confirmado internamente — sem validade fiscal» e, se adoptar a mesma representação visual, conservar também o aviso de rascunho. Não alterar fotografias antigas para acomodar o modelo.
• O modelo de apresentação pode evoluir sem modificar os dados de origem. Uma representação histórica não é prova de que essa versão do modelo já existia na confirmação: mostrar separadamente versão da fotografia e versão do modelo usado na consulta.

Acessos e protecção

Proposta: reutilizar apenas consulta já explicitamente concedida, sem criar poder de emissão: consulta de facturação no âmbito da unidade, draft_documents.view nessa unidade, issuer_documents.view e client_documents.view na empresa. Confirmar a matriz exacta antes da implementação; editar preparação ou configurar um modelo não resulta desta acção de consulta.

O servidor revalida utilizador, pertenças, contexto, unidade e referências em cada pedido. Identificadores enviados pelo navegador não autorizam dados. Revogação impede a consulta no pedido seguinte; não misturar dados de empresas do mesmo tenant ou de outra unidade.

Valores completos das instruções de pagamento só aparecem na apresentação autorizada quando seleccionados; não entram em URLs, logs, erros, telemetria, relatórios de testes ou repositório. Evitar cache partilhada e dados de um contexto anterior ao mudar empresa/unidade ou sair. Escapar texto e impedir HTML/script introduzido em instruções ou descrições. Provas futuras com dados sintéticos em instância isolada, mantendo valores de instruções fora das capturas de prova a versionar.

Plano de implementação futuro, sujeito a aprovação

1. Fechar decisões abaixo e aprovar um exemplo de organização visual com campos fictícios/sem identificadores bancários reais, sem avançar para emissão.
2. Compor uma resposta de leitura com conteúdo e proveniência/versões, reutilizando workflows existentes. Definir a política de actualidade e acesso; não persistir um novo documento fiscal.
3. Renderizar o modelo base e painel de pendências, com configuração limitada e aviso obrigatório; separar consulta de rascunho actual e fotografia B1.
4. Testar a composição, a confidencialidade e a apresentação; demonstrar no navegador isolado o percurso com dados sintéticos. Executar apenas regressões justificadas pelas alterações, quando a implementação for autorizada.
5. Entregar ficheiros, provas, limitações e instruções de navegação. Não aplicar novas concessões, migrações ou criação de configuração sem apresentar o delta/âmbito correspondente. Não publicar.

Critérios de aceitação propostos

1. Um rascunho de serviço existente é apresentado sem redigitar emitente, cliente, linhas, datas, moeda ou instruções seleccionadas e sem criar outro cliente/documento/recebimento.
2. O aviso exacto RASCUNHO — SEM VALIDADE FISCAL mantém-se visível durante a leitura, em páginas visuais e no estilo de impressão; nenhuma configuração o remove.
3. Campos em falta, dados preenchidos sem validação e regras pendentes têm estados/rótulos distintos; zero explícito não é confundido com desconhecido. Nenhum estado afirma aptidão fiscal.
4. Datas de serviço/período, vencimento proposto e instante de consulta aparecem distintos; não existe data efectiva de emissão, número fiscal ou estado emitido.
5. Valores mantêm as cadeias decimais exactas de origem. Moeda/mode desconhecidos não são presumidos; modos incluído/acrescido não geram taxa, imposto, base tributável ou total fictícios. Impostos/total definitivo ficam não apurados.
6. Só as instruções seleccionadas da empresa autorizada aparecem. Reabrir/actualizar não cria pagamento nem apresenta verificação bancária. Valores completos não surgem em artefactos de prova ou logs.
7. Mudança de cadastros/rascunho/instruções detectável segundo a política aprovada gera sinalização de desactualização e actualização explícita; não há mistura silenciosa de versões/contextos.
8. B1 v1/v2 mantém dados e metadados imutáveis. Campo não capturado na versão antiga não é completado a partir do presente. Consulta histórica permanece distinta da factura emitida.
9. Acesso directo, identificadores manipulados, outra empresa do mesmo tenant, outra unidade e revogação de direitos são tratados no servidor; utilizador de consulta não edita dados ou modelo.
10. Textos longos, linhas múltiplas e campos ausentes têm apresentação legível sem esconder aviso ou pendências. A configuração permitida varia o desenho sem limitar o conteúdo aos três exemplos ou alterar regras.
11. Não há gravação de emissão, imposto, recebimento, afectação ou lançamento, nem promoção de confirmações B1. Código/bases aceites preservados e nenhuma publicação.

Decisões para fechar antes de implementar

Decisão	Proposta para revisão
Saída inicial	Pré-visualização dentro da aplicação; sem PDF, exportação ou botão de impressão
Acesso ao rascunho	Reutilizar a conjunção dos direitos de consulta acima; sem concessões novas por inferência
Acesso/configuração do modelo	Definir quem configura e quais opções. Se exigir direito novo, matriz e concessão confirmadas separadamente; não derivar gestão de modelo de consulta/edição de dados
Configuração inicial	Um modelo base comum, configuração limitada por empresa; decidir quais blocos opcionais/rótulos podem variar e se essa edição entra já no incremento
Valores mostrados	Proposta: preços exactos propostos e valor aritmético já existente com rótulo inequívoco; imposto e total definitivo não apurados. Aprovar a nomenclatura antes de desenhar
Actualidade	Proposta: composição coerente ao abrir e verificação ao regressar/actualizar; aviso de mudança, sem substituir dados automaticamente. Definir tratamento de mudança durante a consulta
B1	Proposta: ligação separada para a fotografia histórica, sem reconstrução; decidir se reutiliza o desenho com rótulo histórico explícito ou mantém o detalhe actual
Instruções de pagamento	Mostrar apenas as seleccionadas e aplicáveis, sem as mascarar no documento autorizado; não fotografar valores completos para relatórios/repositório

Estas decisões são de produto/segurança/apresentação. Podem ser fechadas sem aprovar taxas, plano de contas ou emissão. Não se pede uma nova aceitação de identidade, A ou B1.

Fontes e decisões ainda necessárias para cálculo e emissão reais

Estado das fontes: a documentação local regista que nenhuma fonte legal/fiscal foi validada nesta tarefa. A v0.9 e as entregas aceites são referências de produto; os exemplos são referências de conteúdo. Esta revisão não realizou pesquisa legislativa nem atribui vigência/conformidade a diplomas não consultados.

Tema	Fonte/evidência a obter e validar	Decisão dependente
Âmbito fiscal	Enquadramento efectivo da empresa, operações e período; documentação oficial aplicável e responsável competente identificado	Quais tipos/casos de emissão devem ser suportados e em que regime
Identificação e conteúdo	Textos oficiais sobre elementos documentais aplicáveis, com artigo, vigência, alterações e casos especiais	Obrigatoriedade de NUIT/moradas/identificação do cliente, descrições, datas e textos por tipo de documento
Impostos	Normas/tabelas oficiais aplicáveis à operação/data, fundamentos de isenção/não sujeição e validação do enquadramento	Tratamento, taxas, incidência, descontos/encargos, adiantamentos e eventuais retenções; desconhecido continua pendente
Preço e cálculo	Política aprovada compatível com as fontes aplicáveis e exemplos de cálculo conferidos	Incluído/acrescido, precisão, sequência e ponto/método de arredondamento por linha/documento e explicação de diferenças
Moeda e câmbio	Regras oficiais aplicáveis e política da empresa validada; fontes de câmbio só se necessárias e autorizadas	Moeda documental/funcional, fonte/data/taxa de conversão, exposição de impostos e tratamento de diferenças
Emissão e identidade	Regras oficiais aplicáveis a numeração/séries, datas, emissão, rectificação e reprodução; requisitos do software/autoridade se exigíveis	Atribuição de número, unicidade, concorrência, lacunas, momento de emissão, exemplares e controlo de alterações
Arquivo e representação	Requisitos aplicáveis de arquivo, conservação, autenticidade, comunicação e acesso	Formato definitivo, conteúdo legal, evidências, retenção e eventuais integrações; nenhuma presumida neste desenho
Factura-recibo e recibo	Regras aplicáveis e casos operacionais aprovados, critérios de evidência do recebimento	Quando se usam, identidades, afectações, parciais, excedentes, duplicados e prevenção de dupla documentação
Responsabilidade e permissões	Matriz aprovada pelo utilizador e responsabilidades fiscal/contabilística identificadas	Quem verifica, emite, documenta recebimentos, corrige ou autoriza; sem herdar esses poderes da pré-visualização
Contabilidade	Política/plano de contas, reconhecimento, períodos e classificação validados por responsável competente	Quais acontecimentos geram efeitos, quando e com que regras. Desenho ou emissão não aprovam lançamentos

Para cada fonte futura registar identificação oficial/URL, versão, artigo, datas de vigência, âmbito de aplicação, responsável e estado da validação. Um parecer deve ser distinguido da norma que interpreta; um exemplo impresso não substitui nenhuma dessas fontes. Este levantamento documental é uma frente de requisitos, não implementação em paralelo de fiscalidade/contabilidade.

O próximo prompt de execução deverá seleccionar apenas a pré-visualização aprovada. Cálculo fiscal, emissão e demais operações continuarão bloqueados até âmbito, regras, fontes e acessos próprios estarem definidos e autorizados.