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

```bash
# 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](docs/INDEX.md)
- [API Reference](docs/API.md)
- [Arquitetura Técnica](docs/ARCHITECTURE.md)
- [Guia do Usuário](docs/GUIA-USUARIO.md)
- [Guia de Implementação BI-CCC](docs/BI-CCC-Implementation-Guide.md)

## Licença

Uso interno CambioReal.