SGF/docs/GENERAL_LEDGER_REPORTS_DELIVERY.md

# Balancete e razão por conta — consulta integrada de ensaio

03/11/2026. `COMMON-LEDGER-REPORTS-SIM-v1` implementado localmente sob a continuação de desenvolvimento e integração. Apenas leitura dos lançamentos existentes, reutilizando `general_ledger.view`; sem novos direitos, motores de dívida, efeitos contabilísticos ou instalações no destino. Preserva os recortes contabilísticos anteriormente autorizados.

## Resultado funcional

O núcleo comum fornece balancete de ensaio por conta e razão com saldo acumulado. Os adaptadores SGF e SGC autónomo expõem a mesma interface HTML e APIs:

- `/general-ledger/trial-balance` e `/api/general-ledger/trial-balance`;
- `/general-ledger/account-ledger` e `/api/general-ledger/account-ledger`.

Os filtros `from_on` e `to_on` são obrigatórios, datas válidas e inclusivas. O razão exige `account_id`; o balancete pode também restringir uma conta. `page` é limitado a 100.000 e `per_page` a **25 ou 100**. Parâmetros desconhecidos, datas invertidas/impossíveis e contas externas ao âmbito são recusados. Não se aceitam tenant/empresa/unidade do pedido como autoridade.

A abertura considera lançamentos anteriores ao início; débitos/créditos de movimento incluem todo o intervalo; o saldo final soma abertura e movimento. O balancete inclui contas com lançamentos até à data final, inclusive contas sem movimento no intervalo que ainda contribuem para a abertura. Contas apenas com movimentos futuros não entram. Totais são calculados sobre todo o filtro, independentemente da página. No razão, a janela SQL calcula o saldo acumulado antes da paginação, ordenando por data, lançamento, linha e ID; a segunda página não reinicia o saldo.

O balancete liga ao razão preservando datas e tamanho da página. Cada linha do razão conserva tipo de efeito, lançamento, proposta/revisão, autor, fundamento, data e versão da fonte. No SGF, origens de venda ligam ao percurso Comercial → Recebíveis → Contabilidade; as restantes fotografias continuam no diário. A consulta soma os lançamentos elegíveis das fontes compostas, sem refazer a posição financeira nem presumir nova emissão, dívida ou liquidação.

O marcador de consulta inclui âmbito, data final, número de lançamentos e último ID até essa data. Identifica o estado append-only observado e detecta também uma inserção posteriormente retrodatada. **Não é fotografia persistida, assinatura, aprovação de fecho ou relatório legal.** Os montantes usam inteiros exactos em cêntimos, agregação SQL `numeric` e recusa de valores fora da representação inteira suportada; não há aritmética monetária em float.

## Isolamento e disponibilidade

As três relações usadas nas agregações — linhas, lançamentos e contas — recebem o mesmo filtro de tenant/empresa/unidade. Não basta validar o ID da conta. Autorizações e contexto correntes são verificados antes da consulta. SGF exige Contabilidade; SGC mantém o contexto financeiro nativo e a pessoa/permissão explícitas. Direito revogado é recusado.

Cada leitura HTTP própria usa transacção **repeatable read/read only**, sem `FOR UPDATE`, para conservar coerência entre totais, página e marcador. Um livro disponível sem factos é identificado como vazio; tabela necessária ausente responde **503**, sem converter indisponibilidade em saldo zero. Esta prova identificou que o adaptador SGC não tinha essa verificação explícita para o novo relatório: foi acrescentada antes da leitura. A tentativa inicial falhou na prova, foi revertida e não é contada como aprovação; a prova corrigida passou.

Não há comandos nos formulários HTML nem exportação ilimitada. Só as linhas da página são materializadas no PHP; agregações e saldo acumulado correm na base. O balancete usa **três consultas de relatório** — totais, página e marcador — tanto com 25 como com 100 contas. Este número exclui consultas de sessão, autorização e disponibilidade do schema; não representa o total de consultas HTTP. O razão tem consultas adicionais de conta, contagem e janela; não se afirma que use apenas três.

## Provas novas e reutilizadas

[Manifesto de provas e hashes](proofs/common-ledger-reports-20261103.json). Foram criadas duas bases exclusivas para os testes dos relatórios, separadas de demonstrações e de provas anteriores. Em cada uma, um reconhecimento de fornecedor60 vem do workflow existente; outros **130 lançamentos de teste / 260 linhas contabilísticas** foram gerados explicitamente por SQL para exercitar contas, datas e paginação. Estes 130 lançamentos são dados artificiais do relatório, identificados como `report.fixture`; **não são 130 dívidas reconhecidas ou execução do writer**. Todas as constraints de equilíbrio/fotografia foram conferidas. Nenhuma obrigação, pagamento ou afectação financeira adicional foi criado por esse gerador.

| Prova | Resultado |
|---|---|
| Serviço SGF | 21 verificações: datas, abertura/movimento/fecho, paginação, saldo entre páginas, acesso revogado e preservação financeira |
| Serviço SGC | As mesmas 21 verificações sobre o adaptador nativo e núcleo único |
| HTTP SGF / SGC | 21 / 20 verificações: API e HTML, consulta autenticada, recusas, evidências, cache no-store, 25/100 e leitura coerente |
| Isolamento SGF / SGC | 8 / 8 verificações: livros estrangeiros de tenant/empresa/unidade excluídos, contas estrangeiras recusadas e fonte ausente503; tudo revertido |
| Vendas e reversão efectivas | 6 verificações só de leitura sobre a prova válida de quatro lançamentos/nove linhas; 2.400 MZN brutos por lado, contas reconciliadas |
| Cliente + fornecedor no mesmo livro | 7 verificações só de leitura, dois lançamentos/cinco linhas; 1.060 MZN por lado, IDs financeiros coincidentes sem mistura |
| Ciclo fornecedor SGC com reversão e correcção | 5 verificações só de leitura, cinco lançamentos/dez linhas; 220 MZN por lado e contas reconciliadas |
| Distribuição autónoma nova | 6 verificações, runtime e interface carregados do artefacto fixado por hash, um lançamento real do workflow e nenhuma exigência de Sales |
| Artefacto autónomo anterior | Capacidade de relatório ausente responde503; não foi substituído nem alterado |

Os três livros de integração anteriores foram observados sem repetir os percursos de escrita: os fingerprints de lançamentos, linhas, propostas, decisões, histórico e períodos disponíveis ficaram idênticos. As provas válidas anteriores são referenciadas e verificadas por hash. O único erro inicial de preparação SGF ocorreu antes de criar o reconhecimento, por carregamento tardio da variável da fixture; o helper foi corrigido e a mesma base ainda vazia foi preparada sem reset.

O artefacto QA novo contém **30 ficheiros**, manifesto `cbc4ddbea15f5e396c92bc2e664b973138551928980f334bcf3eb0cf097cacb1`. Inclui apenas runtime/README dos núcleos, sem credenciais ou fixtures. Foi ensaiado numa terceira base nativa própria. O artefacto congelado anterior de25 ficheiros, as demonstrações existentes e o pacote do destino ficam intactos. A publicação e substituição do pacote instalado não fazem parte desta entrega.

Sintaxe PHP/JavaScript, `git diff --check` dos dois repositórios e verificações dirigidas Pint/PHPStan dos dois ficheiros nativos alterados constam do manifesto. O SGF não tem Pint/PHPStan instalados. As primeiras invocações do analisador nativo falharam por configuração de autoload — símbolos comuns ausentes e depois duas cópias do Payables; a execução final usa um único caminho canónico, bootstrap explícito e cache privada, sem modificar dependências ou apagar caches.

## Utilização e limites

No SGF, abrir a demonstração existente **http://127.0.0.1:8053/qa/sales-demo**, escolher um perfil e seguir Diário e extracto → **Balancete e razão por conta — Outubro de 2026 (QA)**. No ciclo nativo canónico8051 existe a mesma ligação. O conteúdo reflecte apenas as decisões já registadas nessa demonstração; uma base ainda sem lançamentos aparece vazia e não é preenchida automaticamente. A demonstração8052 conserva o pacote congelado anterior e recusa este relatório por não ter essa capacidade composta.

As bases com os 130 lançamentos artificiais são exclusivamente de regressão e não foram transformadas em demonstrações da equipa. Não houve nova execução de suites financeiras/stock alheias, movimentos em dados reais, novos direitos, migrações no destino, limpeza da cache bloqueada, alteração dos seis registos, publicação, activação de Compras, checkpoint ou aceitação presumida.

Revisão visual, carga sustentada e capacidade de implantação continuam pendentes e separadas. Os ensaios de131 lançamentos por base verificam resultados/paginação; não substituem as medições anteriores de1.000/5.000/10.000 nem validam relatórios de grande volume. Sem índices novos, demonstrações financeiras fiscais, contas legais, saldos iniciais importados, consolidação de empresas, conversão de moedas ou contabilidade de stock/custos/salários.