GPlanSiS|Controller

Controladoria e FP&A do plano de contas ao resultado: saúde da empresa, DRE (também em Sankey), fluxo de caixa, EBITDA e valuation, Lucro Real × Presumido, resultado gerencial, lançamentos manuais, câmbio e integrações com ERP — sobre uma base PostgreSQL que garante as regras.
A IA propõe; o humano decide.

➜ Abrir o GPlanSiS|Controller em controller.gplansis.com

---

O que é

O GPlanSiS|Controller é um sistema de controladoria e FP&A para quem fecha o mês. DRE, fluxo de caixa, EBITDA, valuation, Lucro Real e resultado gerencial saem do mesmo razão e são calculados duas vezes: pelo motor CTRL-ENGINE no navegador e pelas funções do PostgreSQL — e os testes exigem que os dois batam ao centavo. O cabeçalho mostra PostgreSQL · conferido quando isso acontece.

As regras críticas (partidas dobradas, período fechado, imutabilidade com correção por estorno, auditoria SHA-256, "IA não aprova fechamento"…) vivem no banco como CHECK, EXCLUDE e gatilhos (INV-01 a INV-14); a API só antecipa o erro. O sistema funciona sem integração (modo nativo) e recebe dados de ERP por um staging somente leitura.

Toda a base de exemplo é a Empresa Simulada Ltda. — uma simulação de R$ 1.000.000 de receita gerada pelo próprio motor. Nenhum dado real de empresa acompanha o repositório.

Funcionalidades

Módulos

• Saúde da empresa — índice 0–100, radar de 7 dimensões, 16 indicadores com meta e faixa crítica, "onde agir primeiro", ponte do caixa, projeção e DuPont.
• Fluxo do processo — do lançamento ao fechamento, com aprovação humana.
• DRE · Sankey — cada real da receita bruta seguido até tributo, custo, despesa ou lucro, em fluxo animado.
• Premissas — receita, custos, prazos (DSO/DIO/DPO), CAPEX, juros, Selic, beta e prêmio de risco que alimentam o motor.
• Lançamentos manuais — modal com modelos, validação ao vivo, idempotência, estorno, bloqueio após fechamento e trilha SHA-256.
• Plano de contas e razão, DRE, Fluxo de caixa (DFC indireta, CPC 03), EBITDA e valuation (CVM 156/2022, FCFF, WACC, EVA/ROIC), Resultado fiscal (LALUR/LACS, IRPJ/CSLL, tributos indiretos com créditos, Lucro Real × Presumido, taxa efetiva CPC 32) e Resultado gerencial.
• Validação e câmbio — 17 gates por fechamento, R$, US$ ou R$ + US$ com cotação ao vivo.
• Configuração e integrações — 12 conectores: SAP Business One (HANA e SQL Server), SAP S/4HANA, TOTVS Protheus, RM e Datasul, Senior, Oracle EBS, Sankhya, Omie, Odoo e arquivo CSV/Excel (os marcados como hipótese pedem confirmação na instância real).
• Usuários e acesso — cadastro, papéis, ativação, senha temporária e trilha de acesso.

Plataforma

• Banco que garante as regras: 14 invariantes, funções de apuração (fpa.dre, fpa.dfc_indireta, fpa.apurar_lucro_real, fpa.validar), auditoria encadeada e 28 testes SQL de aceitação.
• API FastAPI /api/v1: DRE, balancete, DFC, balanço, Lucro Real, gates, auditoria, contas e lançamentos com estorno e chave de idempotência; documentação em /docs.
• Login próprio: e-mail + senha com scrypt, sessão guardada só como sha256, cookie HttpOnly/Secure/SameSite, CSRF por origem, bloqueio após 5 senhas erradas por e-mail e IP (e por IP), troca obrigatória da senha temporária, CSP com hash dos scripts do build; só o master altera outro administrador.
• Papéis: CFO, CONTROLLER, ANALISTA, AUDITOR (só consulta) e administrador; o master (CTL_MASTER_EMAIL) é administrador permanente. Agente de IA não recebe credencial.
• Três modos do frontend: arquivo único offline (dist/controller.html), PWA instalável e modo banco (servido pela API).

Telas

Saúde da empresa	DRE · Sankey
Resultado fiscal	EBITDA e valuation

Capturas feitas numa instância local (API + PostgreSQL) com a Empresa Simulada Ltda. e um usuário fictício.

Arquitetura

flowchart LR
  subgraph Navegador["Navegador / PWA (frontend/)"]
    M["Motor CTRL-ENGINE<br/>cálculo determinístico<br/>centavos · meio-par"]
    UI["Módulos<br/>Saúde · DRE · Sankey · DFC<br/>Valuation · Fiscal · Gerencial"]
    L["Lançamentos manuais"]
    UI --- M
    L --> M
  end
  CADDY["Caddy<br/>TLS + proxy reverso"]
  subgraph API["API FastAPI (backend/)"]
    R["/api/v1<br/>Pydantic v2 · SQLAlchemy async"]
    AU["login · sessões · usuários"]
  end
  subgraph PG["PostgreSQL 16 (database/)"]
    F["fpa: razão, INV-01..14,<br/>DRE · DFC · Lucro Real · gates"]
    I["itg: staging ERP, de-para,<br/>quarentena, idempotência"]
    S["seg: credenciais, sessões,<br/>trilha de acesso"]
    A["auditoria SHA-256 encadeada"]
  end
  ERP["ERPs (somente leitura)"] --> I
  I -->|carregar_staging| F
  Navegador -->|"cookie de sessão"| CADDY --> R
  R --> F
  R --> AU --> S
  F --> A
  R -->|"GET /dre /lucro-real"| M

Loading

• Fonte única: o motor gera database/02_carga_simulacao.sql e fixtures/motor.json; o schema é também a migration 0001 do Alembic.
• Em produção roda em venv + systemd atrás do Caddy, com o PostgreSQL do host por socket e peer auth (deploy/README.md).
• Detalhes em docs/ARQUITETURA.md e database/LEIAME.md.

Stack

Camada	Tecnologia
Frontend	JavaScript sem framework e sem dependências em tempo de execução, SVG, PWA; build com Node
Backend	Python 3.12, FastAPI, Pydantic v2, SQLAlchemy async (asyncpg), Alembic
Banco	PostgreSQL 16 (schemas fpa, itg, seg)
Testes	node:test + jsdom, SQL de aceitação, pytest + httpx, Playwright
Implantação	systemd + Caddy, ou Docker Compose

Como rodar localmente

Com Docker (mais simples)

git clone https://github.com/SSBianchiplan/controller.git
cd controller
cp .env.example .env                    # troque a senha do banco e defina CTL_MASTER_SENHA
docker compose up --build               # PostgreSQL 16 + API + PWA

Abra http://localhost:8000 e entre com CTL_MASTER_EMAIL / CTL_MASTER_SENHA (troca obrigatória da senha no primeiro acesso). API documentada em http://localhost:8000/docs.

Sem Docker

# 1. frontend
cd frontend && npm install && npm run build && cd ..

# 2. banco (PostgreSQL 16)
createdb controller
psql -v ON_ERROR_STOP=1 -d controller -f database/01_schema.sql
psql -v ON_ERROR_STOP=1 -d controller -f database/02_carga_simulacao.sql
psql -v ON_ERROR_STOP=1 -d controller -f database/05_autenticacao.sql
# em produção a API não entra como dona do banco: ver database/06_papel_restrito.sql

# 3. API
python3 -m venv .venv && .venv/bin/pip install -r backend/requirements.txt
cd backend
DATABASE_URL=postgresql+asyncpg://controller:SUA_SENHA@localhost:5432/controller \
CTL_MASTER_EMAIL=admin@exemplo.com CTL_MASTER_SENHA='Senha-Local-2026' CTL_COOKIE_SEGURO=0 \
../.venv/bin/uvicorn app.main:app --port 8000

Só quer ver o motor? frontend/dist/controller.html abre direto no navegador, sem servidor (lançamentos ficam no localStorage).

Testes e verificação

Camada	Comando	O que prova
Motor + interface	cd frontend && npm test	valores de referência, invariantes, Monte Carlo de 1.000 cenários, modal de lançamento
Banco	psql -f database/03_testes.sql	28 invariantes recusados pelo próprio PostgreSQL
API	cd backend && TEST_ADMIN_DSN=… pytest	DRE, Lucro Real e DFC do banco iguais ao motor ao centavo; idempotência; estorno; período fechado
Ponta a ponta	pytest tests/test_e2e_fullstack.py	a PWA grava no banco pelo modal e a conferência motor × banco passa
Tudo	bash scripts/verificar.sh	gera docs/VERIFICACAO.md

Regra de ouro: mudou o motor → npm run gerar → bash scripts/verificar.sh.

Estrutura de pastas

controller/
├── frontend/            PWA — motor de cálculo + módulos (sem dependências em tempo de execução)
│   ├── src/engine/      CTRL-ENGINE (fonte única do cálculo) e catálogo de conectores
│   ├── src/app/         módulos da interface (01-núcleo … 06-eventos)
│   ├── public/          manifesto, service worker, ícones, imagens da landing
│   ├── scripts/         build.mjs · gerar-dados.mjs · motor.mjs
│   └── tests/           motor (node:test) e interface (jsdom)
├── backend/             API FastAPI + Pydantic v2 + SQLAlchemy async · Alembic · pytest
├── database/            schema, carga da simulação (gerada), 28 testes SQL, extração por ERP, autenticação
├── fixtures/motor.json  valores de referência gerados pelo motor (front e back)
├── tests/               ponta a ponta: PWA + API + PostgreSQL (Playwright)
├── deploy/              VPS: instalar.sh, enviar.sh, usuarios.sh, systemd e Caddy
├── brand/               logotipo e marca
├── docs/                arquitetura e relatório de verificação
└── scripts/             verificar.sh · verificar.ps1

Variáveis de ambiente

Variável	Uso
DATABASE_URL	Conexão da API (postgresql+asyncpg://…)
POSTGRES_PASSWORD	Senha do banco no docker-compose.yml
CTL_EMPRESA_ID · CTL_EXERCICIO	Empresa e exercício abertos (padrão 1 e 2026)
CTL_EXIGIR_LOGIN	0 desliga o login (só desenvolvimento)
CTL_USUARIO_ID	Autor dos lançamentos quando o login está desligado
CTL_MASTER_EMAIL · CTL_MASTER_NOME	Usuário master, administrador permanente (padrão contato@gplansis.com)
CTL_MASTER_SENHA	Semeia a primeira senha do master (desenvolvimento)
CTL_COOKIE_SEGURO	1 atrás de HTTPS; 0 em http://localhost
CTL_SESSAO_HORAS	Duração da sessão
CTL_STATIC_DIR	Pasta do frontend construído (padrão frontend/dist)
CTL_CORS_ORIGINS	Origens extras aceitas (lista)
TEST_ADMIN_DSN	Conexão administrativa para os testes (cria bancos descartáveis)

Modelo em .env.example. Nunca versione o .env.

Contribua

O Controller quer ser a controladoria que um CFO confia porque o banco confere o número. Há muito espaço para quem entende de contabilidade, tributos, dados ou front-end. Toda ajuda conta.

Por onde começar (boas primeiras issues):

• 🔌 Conectores ERP: confirmar as consultas marcadas como hipótese em database/04_extracao_erp.sql (RM, Datasul, Senior, Sankhya, Omie) numa instância de teste.
• 🧾 Tributos: reapuração automática do IRPJ/CSLL no banco após lançamentos manuais (o gate G07 já sinaliza).
• ✅ Fechamento pela API: levar a aprovação do fluxo do processo para o backend (o interlock já existe no banco).
• 🔐 SSO (OIDC) como segundo provedor de login, sem mudar os papéis.
• ⚛️ Migração do frontend para Vite + React + TypeScript com cliente gerado do OpenAPI — o motor é portável.
• 🌐 Internacionalização da interface (hoje em pt-BR).
• 📚 Documentação: guias de plano de contas, premissas e leitura dos indicadores.
• 🛠️ CI: workflow do GitHub Actions com npm test, testes SQL e pytest contra um PostgreSQL de serviço.

Leia o guia de contribuição, abra uma issue para combinar a ideia e mande seu pull request. Siga o código de conduta. Encontrou uma falha de segurança? Veja a política de segurança — não abra issue pública.

Licença

Código próprio sob a licença MIT — Copyright (c) 2026 GPlanSiS.

Nenhum código de terceiros é copiado no repositório. Dependências instaladas por pip/npm: FastAPI (MIT), uvicorn (BSD-3-Clause), SQLAlchemy (MIT), asyncpg (Apache-2.0), psycopg (LGPL-3.0, usada como biblioteca), Pydantic (MIT), Alembic (MIT); em desenvolvimento, pytest (MIT), httpx (BSD-3-Clause), ruff (MIT) e jsdom (MIT). A landing carrega as fontes Archivo e IBM Plex Mono do Google Fonts (SIL OFL 1.1); a cotação do dólar vem da API pública AwesomeAPI.

Créditos

Desenvolvido pela GPlanSiS|Group · contato: contato@gplansis.com · histórico em CHANGELOG.md

controller.gplansis.com