SGF/docs/DOCUMENT_PREPARATION_DELIVERY.md

# Preparação documental — entrega local

Data: 26 de Outubro de 2026 (Africa/Johannesburg). Estado: implementado no âmbito autorizado e pronto para validação própria. B1 aceite em `8fcd52c`, A em `ca13acb` e identidade em `26b80df` permanecem preservados. Não houve reinstalação, mudança de versões, acesso ao InvesteMoz ou publicação.

## Resultado funcional

Novo menu **Preparação documental**, com cinco áreas: Dados do emitente, Dados dos clientes, Instruções de pagamento, Preparação de prestações e Preparação de facturação. Os nomes são reutilizados dos cadastros originais como denominação, sem segundo campo redundante. Se a denominação tiver de mudar, edita-se o nome no menu original, segundo os direitos existentes. Não se presume que esse nome já seja uma denominação legal validada.

Emitente e clientes podem preparar NUIT, morada, localidade e país. Clientes continuam a ser criados apenas com nome no percurso de A; os campos documentais podem ficar por completar. Os cadastros são da empresa e reutilizados entre unidades.

Nos rascunhos existentes da unidade autorizada podem preparar-se moeda, unidade de medida de cada linha, data/período do serviço, condições de pagamento, vencimento proposto e modo de preço: **Por definir / Imposto incluído / Imposto acrescido**. Datas são validadas como datas e fim de período anterior ao início é recusado. Não há data efectiva de emissão.

O modo de preço regista uma intenção para preparação futura: não altera os preços ou cálculos existentes, não calcula impostos nem reinterpreta valores históricos. Moeda vazia continua desconhecida. Se o utilizador alterar explicitamente a moeda, o workflow existente do rascunho cria nova versão e captura essa alteração, conservando a precisão e os valores. Essa operação continua a exigir o direito de edição do rascunho em A, além da edição documental; não é um direito implícito novo.

Condições e vencimento ficam sujeitos a conferência explícita. Sem data de emissão e convenção de contagem aprovadas, não há base para validar automaticamente um prazo contra a data proposta: aparece uma pendência de compatibilidade, sem declarar coerência nem corrigir datas silenciosamente. A indicação livre de «30 dias» não activa uma regra universal.

## Instruções do emitente para facilitar o pagamento

Podem configurar-se várias instruções identificadas por designação, com banco, titular, identificador de conta, NIB, IBAN, SWIFT, código bancário e moeda quando aplicáveis, mais texto. A designação é necessária para seleccionar a configuração; os restantes campos não são impostos a instruções que não sejam bancárias. Não existe uma pergunta ao cliente sobre como pagará.

Cada rascunho pode seleccionar instruções do emitente por identidade, sem redigitar identificadores. O ecrã de selecção mostra designação/versão e explicita que não houve verificação pelo banco. Não inicia operação bancária, não contacta fornecedores, não cria recebimento nem afecta valores.

Não se importaram contas dos exemplos nem foram definidos valores reais por omissão. O esquema/API não aceita campos de palavras-passe, tokens ou cartões; atribuições óbvias de segredos em texto são recusadas. O formulário informa que não se introduzem credenciais, PIN ou dados de cartões. Isso não constitui um serviço geral de detecção/verificação de dados bancários.

Alterações têm versão, histórico append-only e auditoria com identificadores/versão, sem valores das instruções. As respostas de erro de escrita e captura não transportam a consulta SQL com dados bancários nem a remetem para os logs da aplicação. Valores necessários ficam apenas nos registos/histórico autorizados e fotografias futuras correspondentes; não entram nos relatórios de prova ou repositório.

## Reutilização, completude e histórico

Ao criar um novo rascunho de facturação de uma prestação com preparação documental actual e consulta documental autorizada, reutilizam-se datas, condições, unidades, modo proposto e selecções de instruções. A origem/versão dessa preparação fica registada. Uma preparação de origem desactualizada não é copiada como actual; cadastros/preparações acrescentados depois não são injectados retrospectivamente nos rascunhos ou documentos anteriores.

O painel **Completude e validações** distingue «Por completar / confirmar aplicabilidade», «Preenchido — não validado», «Validação pendente» e «Origem alterada — rever». Mostra origem e próxima acção, incluindo consulta dos dados relacionados de emitente/cliente. Não há estado «apto para emissão fiscal». Não se construíram campos estatísticos, contratos ou motor geral de parâmetros.

Editar um rascunho após preparar os dados torna a preparação desactualizada. A confirmação interna exige revisão/actualização dessa preparação. Unidades de medida devem corresponder às linhas actuais; moeda é reutilizada do registo original, não mantida numa segunda fonte independente.

As fotografias B1 antigas não são actualizadas, reconstruídas ou promovidas a facturas. Para novas confirmações que utilizem preparação documental, o JSON da fotografia e o evento passam ao **esquema 2**, acrescentando `document_preparation`, versões dos registos, completude e cópias das instruções seleccionadas. Sem preparação aplicável mantém-se o formato anterior. O tipo de evento continua a significar confirmação interna, sem validade fiscal.

Alterações posteriores das instruções/cadastros não alteram fotografias v1 ou v2. A leitura de uma nova fotografia que contenha esses dados exige também consulta documental de emitente, cliente e unidade; apenas consultar facturação em A não passa a expor dados bancários. Rascunhos B1 confirmados continuam bloqueados por API e SQL, incluindo a preparação documental associada.

## Delta aplicado e preservação

O delta e destino foram apresentados antes da aplicação. Migração aditiva `2026_10_26_010000_create_document_preparation`, testada em `sgf_tempo_test` e aplicada em `sgf_tempo_dev` pelo wrapper/proprietário separado:

- `doc_records`: dados de emitente, cliente, instruções e preparação de rascunhos, com tipo, referência ao cadastro original, empresa/unidade e versão.
- `doc_history`: versões preservadas, autor e instante; protecção append-only.
- Constraints/triggers: fronteira de âmbito e referências, proibição de transferências por operações em massa, versões, selecção de instruções da mesma empresa e bloqueio da preparação de rascunhos confirmados.
- Catálogo SQL ampliado apenas para os direitos documentais definidos abaixo; sem concessão automática pela migração.

Não houve reset/fresh/limpeza destrutiva em desenvolvimento. `document-preservation.php` comparou contagens e resumos criptográficos dos registos existentes antes/depois da migração/concessões: identidade, registos e captura de A e fotografias B1 permaneceram exactamente iguais. Os resumos ficam no directório operacional local, sem valores dos registos no relatório.

Na verificação final havia duas contas, uma empresa, uma unidade, um cliente e um serviço previamente existentes, sem prestações/rascunhos/confirmações em desenvolvimento; `doc_records` e `doc_history` estavam vazias. Não se criaram dados de demonstração na Tempo Lda/SEGI. A aplicação continua a usar `sgf_dev_app`, sem administração PostgreSQL, e a ligação normal não mudou.

O rollback automático desta migração é recusado para preservar história; qualquer reversão requer procedimento revisto de preservação. Não foram criadas tabelas de emissão fiscal, recebimentos ou lançamentos.

## Concessões especificamente confirmadas e aplicadas

As contas existentes foram conferidas, apresentadas e confirmadas antes da aplicação; nenhuma foi criada ou associada por suposição.

| Conta | Empresa Tempo Lda, ID 1 | Unidade SEGI, ID 1 |
| --- | --- | --- |
| ID 1 — Osmane Nala | `issuer_documents.view/edit` (inclui instruções); `client_documents.view/edit` | `draft_documents.view/edit` |
| ID 2 — Samira Nal | `issuer_documents.view`; `client_documents.view` | `draft_documents.view` |

Aplicadas nove concessões, auditadas como `documents.access.initial_grant`; os direitos anteriores foram preservados. Não incluem gestão dos novos direitos, emissão, recebimento ou contabilização. Nomes/emails não determinam privilégios durante a execução. A API revalida contexto, pertenças, permissões e versão; revogação de consulta impede o pedido seguinte, inclusive a leitura de fotografias v2 com instruções.

`scripts/document-access.php` é procedimento local de pré-visualização/aplicação; não executar `--apply` como seed ou sem confirmação específica de nova operação. O procedimento usado recebeu os IDs explicitamente confirmados. `scripts/document-status.php` mostra contagens e direitos, sem valores das instruções.

## Verificações e provas

- **76 testes / 683 asserções aprovados** na suite completa, incluindo identidade, A e B1. As aceitações anteriores não foram reabertas.
- Compilação Vite aprovada: 15 módulos, sem alteração de dependências, versões ou lockfiles.
- Testes de cliente só com nome, denominação reutilizada, cadastros partilhados, instruções seleccionadas, herança da preparação, moeda desconhecida, precisão exacta, preenchido distinto de validado, períodos inválidos, pendência de condições/vencimento, versão/contexto antigos, origem alterada, acesso cruzado, leitura sem edição, ausência de direitos implícitos, revogação, SQL em massa, histórico append-only e rollback integral com falha injectada.
- Compatibilidade: fotografia antiga sem esquema 2 preservada byte a byte pela resposta; nova fotografia v2 conserva instrução/versão seleccionada após alteração da configuração; consulta sem direito ao emitente é recusada. Eventos novos com conteúdo documental declaram esquema 2.
- Falha de escrita com identificador sintético aleatório: nenhum valor incluído no erro, auditoria ou log técnico. Os relatórios de prova omitem os identificadores.
- Prova HTTP com login real sintético: reutilização, fotografias v1/v2, recusas 403/409, selecção sem recebimento e ausência de reinterpretação monetária. [Resultado](proofs/document-http-results.json).
- Prova no navegador, com CSRF e sessões/cache isolados: gestor actualizou emitente/cliente, consultou dados herdados, seleccionou instruções e guardou o modo proposto. Conta de consulta entrou pelo formulário, viu os dados e instruções seleccionadas, sem botão Guardar e com edição desactivada. A mudança entre separadores revelou uma falha de transição React, corrigida e novamente verificada.

Provas: [emitente e completude](proofs/document-01-issuer-profile.png), [instruções reutilizadas sem recebimento](proofs/document-02-reused-instructions.png), [consulta com contexto sintético](proofs/document-03-read-only.png), [métricas sem valores das instruções](proofs/document-capture.json).

A instância isolada usou apenas `sgf_tempo_test` na porta 8001. Foi parada antes da suite final que limpa os dados de teste. A aplicação normal permaneceu em `sgf_tempo_dev` na porta 8000; não se terminaram processos de outros projectos.

## Navegação exacta

1. Actualizar o navegador e entrar como utilizador autorizado; seleccionar Tempo Lda / SEGI. Se os novos direitos não aparecerem, sair e voltar a entrar.
2. Abrir **Preparação documental → Dados do emitente**, completar e guardar. O nome é alterado em **Empresa**, segundo o direito existente.
3. Abrir **Dados dos clientes**, seleccionar um cliente já criado em **Clientes**, completar os dados e guardar. Não duplicar o cadastro.
4. Abrir **Instruções de pagamento → Novas instruções**, preencher apenas os dados aplicáveis, dar uma designação e guardar. Sem segredos ou dados de cartões.
5. Criar uma prestação no menu **Prestações em rascunho**, se ainda não existir. Voltar a **Preparação documental → Preparação de prestações**, seleccioná-la, completar campos e seleccionar as instruções aplicáveis; guardar.
6. Abrir a prestação em **Prestações em rascunho → Preparar rascunho de facturação**. Em **Preparação documental → Preparação de facturação**, seleccionar o rascunho e conferir os dados reutilizados e pendências. Pode também preparar directamente um rascunho existente ainda não confirmado.
7. A confirmação interna B1 continua em **Rascunhos de facturação → abrir registo → Rever confirmação interna**; não é emissão. Nenhuma preparação pode editar um rascunho já confirmado.

## Ficheiros e comandos

Novos: `DocumentPreparation.php`, `Http/DocumentPreparationController.php`, `DocumentPreparationWorkspace.jsx`, migração indicada, `DocumentPreparationTest.php`, fixture documental e scripts `document-access.php`, `document-status.php`, `document-preservation.php`, `document-http-proof.mjs`, `document-proof-metrics.php`. Integração em rotas, navegação, CSS, criação de rascunho de facturação e captura/leitura de confirmações internas. A preparação de fixtures do navegador passou a conceder os novos direitos apenas a identidades sintéticas.

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 test
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 npm run build
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 php scripts/document-status.php
```

Testes destrutivos permanecem exclusivos de `sgf_tempo_test`. Scripts de métricas verificam esse destino. Parar a instância de navegador de testes antes da suite. Nenhum exemplo real deve ser usado como fixture, configuração ou referência bancária por omissão.

## Pendências e limites

Nenhuma fonte legal/fiscal nova foi validada neste incremento. Obrigatoriedade por regime/tipo, validade de NUIT/moradas, numeração, emissão, taxas, incidência e arredondamento fiscal permanecem pendentes. Contas, reconhecimento, moeda funcional e processamento contabilístico também. A preparação não se apresenta como validada pelo banco ou apta para emissão fiscal.

Não há emissão de factura, recibo ou factura-recibo, data efectiva de emissão, número fiscal, PDF de factura, recebimento, afectação ou lançamento. Descontos, contratos, estatísticas e dimensões analíticas não foram implementados. Não existe eliminação de configurações ou gestão das novas concessões pela interface. Restantes incrementos e publicação continuam sem autorização; esta entrega aguarda validação do utilizador.