bi-agents/README.md

BI-CCC (Central Command Center) — CambioReal

Sistema de Business Intelligence interno da CambioReal para monitoramento de operações cambiais, análise de clientes e gestão de agentes.

O que faz

O BI-CCC consolida dados de três produtos de câmbio em dashboards visuais:

• CambioPay (BRL→USD): Clientes brasileiros enviam reais convertidos em dólares para destinatários nos EUA
• CambioPay Reverso (USD→BRL): Clientes nos EUA enviam dólares convertidos em reais para o Brasil
• CambioCheckout (BR→US via Cobrança): Merchants nos EUA recebem pagamentos de clientes brasileiros via links de cobrança

Os dados transacionais vivem em um banco MySQL (RDS na AWS), acessível via VPN Netbird.

Stack Técnica

Camada	Tecnologia
Runtime	Node.js 20 (Alpine)
Framework	Express 4
Banco transacional	MySQL 8 (AWS RDS) — read-only
Banco local	SQLite (better-sqlite3) — usuários/auth
Gráficos	Chart.js (inline, sem CDN)
Autenticação	bcrypt + express-session
VPN	Netbird (acesso ao RDS)
Deploy	Docker Compose
Tema	Dark/Light toggle, estilo Bloomberg terminal

Arquitetura

┌─────────────────────────────────────────────────┐
│  Browser                                         │
│  HTML + CSS + JS (tudo server-side rendered)     │
│  Chart.js para gráficos                          │
└───────────────────┬─────────────────────────────┘
                    │ HTTP
┌───────────────────▼─────────────────────────────┐
│  server.js (Express)                             │
│  - Rotas HTML (GET /corporate, /admin/bi, etc)   │
│  - API REST (GET /admin/api/bi, etc)             │
│  - Auth middleware (session + roles)             │
│  - Cache layer (stale-while-revalidate)          │
├──────────────────┬──────────────┬───────────────┤
│  src/queries/    │  src/auth.js │  src/*.js     │
│  (MySQL queries) │  (bcrypt)    │  (HTML builders)│
├──────────┬───────┴──────────────┴───────────────┤
│ db-rds.js│  db-local.js                          │
│ (mysql2) │  (better-sqlite3)                     │
├──────────┴──────────────────────────────────────┤
│  MySQL RDS (via Netbird VPN)  │  SQLite local   │
│  cambio_db — transações       │  agentes.db     │
└───────────────────────────────┴─────────────────┘

Estrutura de Arquivos

bi-agentes/
├── server.js                 # Rotas + APIs + middleware
├── src/
│   ├── ui-template.js        # Header, footer, CSS vars, tema, Chart.js
│   ├── auth.js               # Login/logout, bcrypt, requireRole middleware
│   ├── cache.js              # Cache em memória com stale-while-revalidate
│   ├── db-rds.js             # Pool MySQL (read-only, 10 conexões)
│   ├── db-local.js           # SQLite — tabela agentes (auth)
│   ├── panels.js             # Configuração de painéis
│   ├── admin-bi.js           # Página: BI Executive
│   ├── admin-cliente.js      # Página: Client 360
│   ├── admin-dashboard.js    # Página: Corporate Dashboard
│   ├── admin-home.js         # Página: Daily Overview
│   ├── admin-panel.js        # Página: Gestão de Usuários
│   ├── admin-providers.js    # Página: Payment Providers
│   ├── dashboard.js          # Página: Dashboard do Agente
│   ├── queries/              # Queries MySQL modulares
│   │   ├── bi.queries.js
│   │   ├── client.queries.js
│   │   ├── compliance.queries.js
│   │   ├── corporate.queries.js
│   │   ├── payin.queries.js
│   │   ├── payout.queries.js
│   │   ├── provider.queries.js
│   │   └── helpers.js
│   ├── services/             # Lógica de negócio
│   │   ├── churn-predictor.js
│   │   └── forecast.js
│   ├── alerts/               # Sistema de alertas
│   │   ├── alert-engine.js
│   │   └── channels.js
│   ├── etl/                  # Pipeline de dados
│   │   ├── daily-sync.js
│   │   └── data-quality.js
│   └── export/
│       └── excel-export.js
├── public/
│   ├── chart.umd.min.js      # Chart.js (carregado inline)
│   ├── login.html
│   └── logo.png
├── scripts/
│   ├── seed-admin.js
│   └── seed-agente.js
├── data/
│   └── agentes.db            # SQLite (persistido via Docker volume)
├── docs/                     # Documentação detalhada
│   ├── INDEX.md
│   ├── API.md
│   ├── ARCHITECTURE.md
│   └── GUIA-USUARIO.md
├── Dockerfile
├── docker-compose.yml
├── docker-entrypoint.sh
└── .env                      # Credenciais (não versionado)

Roles e Permissões

Role	Acesso	Rota principal
admin	Tudo: Corporate, BI, Clientes, Usuários, Providers	/corporate
corporate	Corporate Dashboard apenas	/corporate
agente	Seu próprio dashboard de transações	/dashboard

Principais Funcionalidades

• Corporate Dashboard — KPIs do período, tendências 30d, três fluxos separados
• BI Executive — Revenue analytics, ranking de agentes, retenção, cohort analysis, BI estratégico
• Client 360 — Profile lifetime, health score, churn risk, merchant detection, netting, revenue intelligence
• Payment Providers — Análise de provedores de pagamento
• Gestão de Usuários — CRUD de usuários, ativar/desativar, reset de senha
• Dashboard Agente — Transações pessoais, KPIs, gráficos
• Cache inteligente — Stale-while-revalidate com auto-refresh
• Export — Exportação Excel
• Alertas — Sistema de alertas com notificação por email
• Tema — Dark mode Bloomberg terminal / Light mode institucional

Deploy

# Build + restart container
docker compose build bi-ccc && docker compose down bi-ccc && docker compose up -d bi-ccc

# Ver logs
docker logs bi-ccc -f

# Criar usuário admin
docker exec -it bi-ccc node scripts/seed-admin.js

O container automaticamente:

1. Inicia Netbird VPN daemon (acesso ao RDS via rede privada)
2. Aguarda conexão VPN (~10s)
3. Roda node server.js na porta 3080

Variáveis de Ambiente

Copie .env.example para .env e configure:

Variável	Descrição
MYSQL_URL	Host do MySQL RDS
USER_MYSQL	Usuário MySQL (read-only)
PW_MYSQL	Senha MySQL
SESSION_SECRET	Secret para express-session
PORT	Porta do servidor (default: 3080)
NETBIRD_SETUP_KEY	Chave de setup da VPN Netbird
NETBIRD_MANAGEMENT_URL	URL do Netbird management
AWESOME_API_TOKEN	Token para API de cotação USD/BRL

Documentação

• Índice da Documentação
• API Reference
• Arquitetura Técnica
• Guia do Usuário
• Guia de Implementação BI-CCC

Licença

Uso interno CambioReal.