SGF/README.md

# SGF TEMPO

Primeiro percurso funcional local, sobre a fundação existente e o roteiro v0.9 de 25 de Outubro de 2026. Laravel modular com React, independente do InvesteMoz. Versões e lockfiles preservados; sem módulos financeiros, integrações externas ou publicação.

**Base aceite:** incremento local de entrada, contexto e permissões aceite e concluído pelo utilizador em 25 de Outubro de 2026, com os limites de [IDENTITY_DELIVERY.md](docs/IDENTITY_DELIVERY.md). Preservar esta base. A autorização posterior de serviços está delimitada abaixo.

**Entrega A aceite em 25 de Outubro de 2026:** serviços em rascunho, no âmbito demonstrado e com os limites de [SERVICES_A_DELIVERY.md](docs/SERVICES_A_DELIVERY.md). B/C, operações financeiras confirmadas e publicação continuam sem autorização. O checkpoint aceite `26b80df` permanece preservado.

## Preparação documental (incremento posterior)

**Pré-visualização no navegador:** em **Rascunhos de facturação**, abrir um rascunho não confirmado e escolher **Pré-visualizar rascunho**. O aviso de ausência de validade fiscal e as pendências são obrigatórios. Mudanças geram aviso; **Actualizar pré-visualização** carrega explicitamente a nova versão. Para registos confirmados, usar **Abrir confirmação interna histórica**, que não reconstrói dados ausentes. A apresentação consulta-se em **Apresentação do rascunho**; Osmane tem configuração especificamente confirmada e aplicada na Tempo Lda; Samira apenas consulta. Sair e voltar a entrar, se necessário, para carregar o novo direito. [Relatório da pré-visualização](docs/DRAFT_INVOICE_PREVIEW_DELIVERY.md). Sem PDF, impressão documental ou emissão fiscal.

Depois de entrar e seleccionar a empresa/unidade autorizadas, abrir **Preparação documental** no menu lateral:

1. **Dados do emitente**: completar NUIT, morada, localidade e país. A denominação é o nome já existente; altera-se no menu Empresa, conforme direitos próprios.
2. **Dados dos clientes**: seleccionar um cliente existente e completar os mesmos campos uma vez. Continua a ser possível criar clientes apenas com nome no menu Clientes.
3. **Instruções de pagamento**: escolher **Novas instruções** ou uma configuração existente. Preparar banco/titular/identificadores/moeda quando aplicáveis e texto. São instruções do emitente para facilitar o pagamento, sem registo de recebimento ou ligação a bancos. Não introduzir credenciais, tokens, PIN ou dados de cartões.
4. **Preparação de prestações** ou **Preparação de facturação**: seleccionar um rascunho já criado nos menus existentes. Preparar moeda, unidades das linhas, data/período, condições, vencimento proposto e modo de preço. Seleccionar instruções configuradas por designação; guardar.
5. Consultar **Completude e validações** e os dados relacionados do emitente/cliente. «Preenchido» não é «validado». Condições/vencimento continuam sujeitos a conferência, sem correcção automática.

Ao criar um novo rascunho de facturação a partir de uma prestação com preparação actual, os dados documentais e selecções são reutilizados. Preparar uma moeda diferente actualiza explicitamente a moeda do rascunho pela operação existente, mantendo valores exactos; escolher «imposto incluído/acrescido» não recalcula impostos nem reinterpreta preços. Se um rascunho for editado depois, rever e guardar novamente a sua preparação. Documentos B1 confirmados permanecem bloqueados.

Osmane tem os direitos documentais especificamente confirmados na Tempo Lda/SEGI; Samira apenas consulta. Para carregar as novas concessões, actualizar o navegador e, se necessário, sair e voltar a entrar. Sem rascunhos, as listas de preparação estarão vazias: este ecrã reutiliza os registos existentes, não cria uma factura.

[Relatório e limites da preparação documental](docs/DOCUMENT_PREPARATION_DELIVERY.md). Não há emissão, numeração fiscal, PDF de factura, recebimentos ou lançamentos. Dados bancários apenas introduzidos pelo utilizador não são apresentados como verificados pelo banco.

## Usar a entrega A e B1

**Incremento posterior B1:** disponível a confirmação interna do rascunho de facturação para quem possua `billing_drafts.confirm_internal`. Abrir o rascunho, escolher **Rever confirmação interna**, conferir versão/contexto e confirmar. Quantidades/preços e referências devem estar completos e actuais; moeda ou regras desconhecidas permanecem pendentes. A fotografia é imutável e o rascunho confirmado deixa de poder ser editado ou eliminado. A referência `INT-B1-…` não é numeração fiscal. Não há emissão, impressão de factura, reconhecimento ou lançamento contabilístico. [Relatório B1](docs/SERVICES_B1_DELIVERY.md). A mantém-se aceite no checkpoint `ca13acb`; B1 foi aceite em 25 de Outubro de 2026 no âmbito demonstrado, sem validade fiscal nem lançamentos contabilísticos. Não avançar para os restantes incrementos nem publicar.

Actualizar o navegador e entrar normalmente. Seleccionar a empresa e a unidade autorizadas. Os novos menus são **Clientes**, **Serviços**, **Prestações em rascunho** e **Rascunhos de facturação**.

1. Criar o cliente (apenas nome obrigatório) e o serviço. São cadastros da empresa, reutilizados entre unidades.
2. Criar uma prestação em rascunho na unidade seleccionada, escolhendo o cliente e as linhas de serviço existentes.
3. Preencher quantidades/preços como texto decimal com ponto, até 16 algarismos inteiros e 8 decimais. Valores vazios ficam pendentes. Não há moeda por omissão.
4. Guardar e usar **Preparar rascunho de facturação**. O servidor reutiliza cliente, linhas, moeda indicada e versão da prestação, sem emitir factura.
5. Consultar pendências e **Histórico e captura durável**. A base aritmética não é um total fiscal ou valor definitivo a pagar.

Uma prestação alterada não reescreve silenciosamente o rascunho de facturação: aparece uma pendência. **Actualizar explicitamente da prestação** cria outra versão com os dados de origem revistos.

**Gerir acessos desta área** permite conceder/revogar apenas acções que o gestor possui no mesmo âmbito. Clientes/serviços têm âmbito de empresa; os dois tipos de rascunho têm âmbito de unidade. Os acessos de identidade continuam no menu anterior **Acessos**.

As novas concessões foram confirmadas especificamente para os registos existentes de Osmane (16 concessões) e Samira (4 de consulta), na Tempo Lda/SEGI. Nenhuma conta foi criada nesta entrega e nenhum dado de demonstração foi colocado em desenvolvimento.

Consultar estado local, sem mostrar segredos: `sgf.ps1 php scripts/a-status.php`. Não repetir `a-access-plan.php --apply` sem nova confirmação específica caso os direitos tenham sido entretanto alterados.

## Abrir e parar

Em `C:\laragon\www\sgf-tempo`:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 start
```

Abrir http://127.0.0.1:8000. Se a porta estiver ocupada, o arranque recusa sem terminar processos. `status` mostra o estado; `stop` pára apenas os processos próprios registados e o cluster exclusivo. Não existe serviço Windows novo nem alteração global da política de execução.

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 status
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 stop
```

## Primeira conta

**Estado actual:** a conta inicial de Osmane Nala já foi criada e verificada na Tempo Lda. Não repetir o comando de criação abaixo; conserva-se como registo do procedimento. Entrar com o email indicado e a palavra-passe definida localmente.


Sem utilizadores, o ecrã mostra «Falta concluir a primeira conta» e o procedimento local. A existência da aplicação não significa que haja uma conta criada. Não há palavras-passe por omissão nem administrador universal.

A operação inicial de Osmane Nala / Tempo Lda foi pré-visualizada e confirmada na sessão. Para a concluir, o utilizador deve executar no seu terminal local:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\laragon\data\sgf-tempo\run\complete-first-admin.ps1
```

O procedimento apresenta o âmbito já confirmado nesta sessão e solicita uma nova palavra-passe duas vezes com Read-Host -AsSecureString do PowerShell, mostrando apenas asteriscos. Não é necessário responder yes novamente. Não introduzir palavras-passe no chat, em argumentos ou no motivo. Só depois da confirmação e das duas entradas válidas são criados, atomicamente, o tenant, empresa, utilizador e concessões. Se for interrompido ou falhar, a criação não fica parcialmente aplicada. Não repetir depois de a conta existir.

Concluído o procedimento, actualizar o estado no navegador e entrar com a credencial definida localmente. A conta inicial tem apenas consulta/edição do nome da empresa, criação de unidades e gestão delimitada de acessos na empresa aprovada. Não se criam unidades iniciais: o utilizador pode criá-las com a permissão específica. Ao criá-las, recebe concessões explícitas de consulta e edição apenas para cada nova unidade, conforme decisão aprovada.

## Percurso disponível

1. Entrar por email/palavra-passe; tentativas repetidas são limitadas.
2. Seleccionar uma empresa autorizada e uma unidade com consulta explicitamente concedida.
3. Consultar a área inicial com empresa e unidade visíveis.
4. Consultar/editar nomes segundo as concessões; criar unidades apenas com `unit.create`.
5. Gerir acessos de utilizadores existentes apenas na empresa activa e sem delegar direitos superiores aos próprios.
6. Sair: a sessão anterior é invalidada.

Não existe criação de tenants ou empresas pela interface, auto-registo, opção «todas as unidades», recuperação por email ou fornecedor externo. Consultar [utilização e recuperação](docs/IDENTITY_WORKFLOW.md) para os procedimentos locais de utilizadores e recuperação.

## Testes e ferramentas

```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/verify-foundation.php
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 php scripts/identity-status.php
```

Os testes destrutivos usam exclusivamente `sgf_tempo_test`, verificada antes da execução. Não usar fresh, reset ou wipe em desenvolvimento. Migrações futuras aprovadas: `sgf.ps1 migrate`, com proprietário de migrações separado; a aplicação continua a usar `sgf_dev_app` sem administração ou criação de tabelas.

Para Vite, `sgf.ps1 frontend` (porta 5173, estrita). A aplicação continua a ser aberta na porta 8000. As ferramentas usam caminhos explícitos em `C:\laragon\tools\sgf-tempo`; o cluster fica em `C:\laragon\data\sgf-tempo\postgres-17`, porta 55432. Não alterar as versões ou o ambiente do InvesteMoz.

[Relatório do incremento e provas](docs/IDENTITY_DELIVERY.md) · [Registo histórico da preparação inicial](docs/LOCAL_ENVIRONMENT.md)

O primeiro núcleo de cálculo de serviço e a política operacional de truncagem estão documentados em [cálculo de serviço: utilização, provas e limites](docs/SERVICE_CALCULATION_DELIVERY.md). A aplicação normal conserva pendências de aplicabilidade; cálculos de ensaio são exclusivos da instância isolada de testes. Não há activação de perfil fiscal real, emissão, recebimento ou contabilização.

O menu **Classificação contabilística**, disponível após actualizar a sessão com os acessos especificamente concedidos, permite preparar e submeter versões PGC-NIRF, validar/recusar sem editar e consultar classificação por data. Categoria e excepções são empresariais; operações e respectivos históricos continuam limitados às unidades autorizadas. As tabelas reais começam vazias, sem contas de movimento ou regras aprovadas por omissão. Consultar [utilização, provas e limites da classificação](docs/CATALOGUE_ACCOUNTING_DELIVERY.md).