cassel/bi-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
bi-agents/PROJETO.md
Cassel 647cbec54f docs: update all documentation and add AI tooling configs 
- Rewrite README.md with current architecture, features and stack
- Update docs/API.md with all current endpoints (corporate, BI, client 360)
- Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL
- Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente)
- Add docs/INDEX.md documentation index
- Add PROJETO.md comprehensive project reference
- Add BI-CCC-Implementation-Guide.md
- Include AI agent configs (.claude, .agents, .gemini, _bmad)
- Add netbird VPN configuration
- Add status report

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 13:29:03 -04:00

262 lines
12 KiB
Markdown
Raw Permalink Blame History

# BI-CCC (Central Command Center) — CambioReal
Sistema de Business Intelligence interno da CambioReal para monitoramento de operacoes cambiais, analise de clientes e gestao de agentes.
## O que faz
O BI-CCC consolida dados de tres produtos de cambio em dashboards visuais:
- **CambioPay** (BRL→USD): Clientes brasileiros enviam reais que sao convertidos em dolares para destinatarios nos EUA
- **CambioPay Reverso** (USD→BRL): Clientes nos EUA enviam dolares convertidos em reais para o Brasil
- **CambioCheckout** (BR→US via Cobranca): Merchants nos EUA recebem pagamentos de clientes brasileiros via links de cobranca
Os dados transacionais vivem em um banco MySQL (RDS na AWS), acessivel via VPN Netbird. O sistema calcula receita, spread, volume, e indicadores de saude por cliente/agente/periodo.
## Stack Tecnica
| Camada | Tecnologia |
|--------|-----------|
| Runtime | Node.js 20 (Alpine) |
| Framework | Express 4 |
| Banco transacional | MySQL 8 (AWS RDS) — read-only |
| Banco local | SQLite (better-sqlite3) — usuarios/auth |
| Graficos | Chart.js (inline, sem CDN) |
| Autenticacao | 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 graficos │
└───────────────────┬─────────────────────────────┘
│ 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.js │ 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 — transacoes │ agentes.db │
└───────────────────────────────┴─────────────────┘
```
### Padrao de paginas
Cada pagina e um modulo em `src/` que exporta uma funcao `buildXxxHTML(user)`. Essa funcao retorna uma string HTML completa com CSS e JS inline. Nao usa templates externos — tudo e construido server-side via template literals do JavaScript.
Fluxo:
1. Express recebe request → verifica auth/role
2. Chama `buildXxxHTML(user)` → retorna HTML string
3. Frontend faz `fetch()` para APIs de dados
4. JavaScript inline renderiza Chart.js e popula o DOM
## Estrutura de Arquivos
```
bi-agentes/
├── server.js # Rotas + APIs + middleware
├── src/
│ ├── queries.js # Todas as queries MySQL (1786 linhas)
│ ├── ui-template.js # Header, footer, CSS vars, tema, Chart.js
│ ├── auth.js # Login/logout, bcrypt, requireRole middleware
│ ├── cache.js # Cache em memoria com stale-while-revalidate
│ ├── db-rds.js # Pool MySQL (read-only, 10 conexoes)
│ ├── db-local.js # SQLite — tabela agentes (auth)
│ ├── admin-bi.js # Pagina: BI Executive (2133 linhas)
│ ├── admin-cliente.js # Pagina: Client 360 (1309 linhas)
│ ├── admin-dashboard.js # Pagina: Corporate Dashboard (746 linhas)
│ ├── admin-home.js # Pagina: Daily overview (510 linhas)
│ ├── admin-panel.js # Pagina: Gestao de usuarios (523 linhas)
│ └── dashboard.js # Pagina: Dashboard do agente (1585 linhas)
├── public/
│ ├── chart.umd.min.js # Chart.js (carregado inline)
│ ├── login.html # Tela de login
│ ├── logo.png # Logo CambioReal
│ └── logo-small.png
├── data/
│ └── agentes.db # SQLite (persistido via Docker volume)
├── scripts/
│ ├── seed-admin.js # Cria usuario admin
│ └── seed-agente.js # Cria usuario agente
├── Dockerfile
├── docker-compose.yml
├── docker-entrypoint.sh # Startup: Netbird VPN + node server.js
└── .env # Credenciais (nao versionado)
```
## Roles e Permissoes
| Role | Acesso | Rota principal |
|------|--------|---------------|
| `admin` | Tudo: Corporate, BI, Clientes, Usuarios, Emular agente | `/corporate` |
| `corporate` | Corporate Dashboard apenas | `/corporate` |
| `agente` | Seu proprio dashboard de transacoes | `/dashboard` |
Middleware `requireRole('admin')` protege rotas. Admins podem emular agentes via `/corporate/emular/:agente_id`.
## Paginas e Funcionalidades
### Corporate Dashboard (`/corporate`)
- KPIs do periodo: volume, transacoes, ticket medio
- Graficos de tendencia (30 dias default)
- Tres fluxos separados: BRL→USD, USD→BRL, USD→USD (balance)
- Filtros por periodo customizado
### BI Executive (`/admin/bi`)
- Dashboard consolidado com KPIs comparativos (periodo atual vs anterior)
- Revenue Analytics por produto com granularidade (dia/mes/ano)
- Receita por produto: CambioPay, CambioCheckout, Balance
- Ranking de agentes com spread revenue
- Top 10 clientes por volume
- Retencao, clientes em risco, netting
- BI Estrategico: cohort retention, revenue expansion/contraction, cross-sell, maturidade
### Client 360 (`/admin/cliente`)
- Busca de clientes (server-side, top 20 por volume)
- Profile card: nome, lifetime stats, health score
- **Merchant detection**: clientes que sao merchants CambioCheckout mostram badge roxo e secao dedicada
- 6 KPI cards: volume, transacoes, receita, ticket medio, ARPA, spread
- 6 KPI cards checkout (merchants): volume, payers, receita, ops, ticket, spread
- Health Score (0-100): volume + frequencia + recencia + crescimento
- Churn Risk: indicadores de risco com classificacao (baixo/medio/alto/critico)
- Netting: posicao liquida BRL→USD vs USD→BRL
- Revenue Intelligence: receita mensal + MoM growth
- Timeline: volume + quantidade diaria com granularidade D/W/M
- Analise de fluxo: donut BRL↔USD + tendencia de spread
- Checkout Analytics (merchants): chart mensal volume+payers + top 10 pagadores clicaveis
- Tabela de transacoes: ordenavel, paginada, exportavel CSV
- Insights comportamentais: dia da semana, ticket medio, providers
### Gestao de Usuarios (`/admin`)
- CRUD de usuarios (admin, corporate, agente)
- Ativar/desativar usuarios
- Reset de senha
### Dashboard Agente (`/dashboard`)
- Transacoes do agente (filtradas por `agente_id`)
- KPIs pessoais
## Banco de Dados
### MySQL RDS (`cambio_db`) — Transacoes
| Tabela | Descricao |
|--------|-----------|
| `br_transaction_to_usa` | Transacoes BRL→USD (amount_brl, amount_usd, exchange_rate, ptax, iof, status, cobranca_id) |
| `pagamento_br` | Pagamentos USD→BRL (valor, cotacao, ptax, valor_sol, tipo_envio, pgto, fee) |
| `conta` | Contas/clientes (id_conta, nome) |
| `ag_contas` | Mapeamento agente→conta (agente_id, conta_id) |
| `br_payment_methods` | Provedores de pagamento (id, provider: dlocal, bexs, braza, bs2, ouribank, msb) |
| `br_cb_empresas` | Merchants CambioCheckout (id, id_conta, nome_empresa, active) |
| `br_cb_cobranca` | Cobrancas/links de pagamento (id, empresa_id) |
**Relacao Merchant/Checkout**: `br_cb_empresas.id_conta` identifica o merchant. `br_cb_cobranca.empresa_id` liga ao merchant. `br_transaction_to_usa.cobranca_id` liga a transacao a cobranca. O `id_conta` na transacao e o **pagador** (cliente BR), nao o merchant.
### SQLite Local (`data/agentes.db`) — Auth
| Tabela | Descricao |
|--------|-----------|
| `agentes` | Usuarios do sistema (email, senha_hash, nome, role, agente_id, ativo) |
## Calculo de Receita
A receita e calculada de forma diferente por produto:
**BRL→USD (CambioPay/CambioCheckout)**:
```
receita = (amount_brl - fee_ajustado) / ptax - pfee - (amount_usd + bonus - taxa_cr)
```
Onde `fee_ajustado` depende do provider (ouribank/bs2 nao descontam fee).
**USD→BRL**:
```
receita = ((ptax - cotacao) * valor) / ptax + fee
```
Balance: apenas `fee`.
## Cache
O sistema usa cache em memoria (`src/cache.js`) com padrao stale-while-revalidate:
- **KPIs**: TTL 5 min, auto-refresh
- **Tendencia 30d**: TTL 10 min, auto-refresh
- **Top agentes**: TTL 10 min, auto-refresh (7d, 30d, 90d)
- **Top clientes**: TTL 15 min
Dados "stale" sao retornados imediatamente enquanto o refresh acontece em background.
## Design System
- **Tema**: Dark mode estilo Bloomberg terminal (verde #00FF88, monospace)
- **Light mode**: Cores institucionais CambioReal (roxo #7600be, verde #2E7D32)
- **Trading Console**: classe `body.trading-console` ativa estetica de terminal
- **Console Nav**: Navegacao lateral fixa (folder tabs) no lado direito
- **Hero Cards**: Cards de KPI com borda colorida superior via `::before`
- **Charts**: Chart.js com `getChartTheme()` para cores que se adaptam ao tema
- **Responsivo**: Breakpoints em 1200px, 900px, 768px, 480px
- **Font**: Inter (Google Fonts) + SF Mono/Fira Code (dark mode)
## 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 usuario admin
docker exec -it bi-ccc node scripts/seed-admin.js
```
O container:
1. Inicia Netbird VPN daemon (acesso ao RDS via rede privada)
2. Aguarda conexao VPN (~10s)
3. Roda `node server.js` na porta 3080
## Variaveis de Ambiente
| Variavel | Descricao |
|----------|-----------|
| `MYSQL_URL` | Host do MySQL RDS |
| `USER_MYSQL` | Usuario 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 cotacao USD/BRL em tempo real |
## APIs Internas
Todas as APIs retornam JSON e requerem autenticacao.
| Endpoint | Descricao |
|----------|-----------|
| `GET /corporate/api/kpis` | KPIs hoje vs media 30d |
| `GET /corporate/api/trend` | Tendencia 30 dias |
| `GET /corporate/api/top-agentes?dias=N` | Top 5 agentes |
| `GET /corporate/api/kpis-period?inicio=&fim=` | KPIs por periodo |
| `GET /corporate/api/trend-period?inicio=&fim=` | Tendencia por periodo |
| `GET /admin/api/bi?start=&end=` | BI completo (KPIs, trends, ranking, retencao) |
| `GET /admin/api/bi/revenue?start=&end=&granularity=` | Revenue analytics |
| `GET /admin/api/bi/strategic?start=&end=` | BI estrategico (cohort, expansion) |
| `GET /admin/api/clientes/top` | Top 20 clientes por volume |
| `GET /admin/api/clientes/search?q=` | Busca clientes por nome |
| `GET /admin/api/cliente/:id/profile` | Profile lifetime do cliente |
| `GET /admin/api/cliente/:id/data?start=&end=` | Dados do cliente por periodo |
| `GET /api/cotacao` | Cotacao USD/BRL em tempo real (proxy) |
Reference in New Issue View Git Blame Copy Permalink