BI Agentes - CambioReal

Dashboard de Business Intelligence para agentes de cambio CambioReal. Monitoramento em tempo real de transacoes BRL-USD com dados do AWS RDS.

Visao Geral

Sistema web que permite aos agentes de cambio visualizar suas transacoes, KPIs de performance e graficos analiticos. Cada agente ve apenas suas proprias transacoes, filtradas pelo agente_id.

Principais recursos:

• Autenticacao segura (bcrypt + sessoes)
• KPIs em tempo real (volume, spread, IOF, ticket medio)
• Graficos interativos (Chart.js)
• Filtros por periodo, fluxo e cliente
• Exportacao de dados (em breve)

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                    BI Agentes (Express)                      │
│                                                              │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│   │   Login      │───▶│   Session    │───▶│  Dashboard   │  │
│   │   (HTML)     │    │   (Memory)   │    │   (HTML)     │  │
│   └──────────────┘    └──────────────┘    └──────────────┘  │
│                              │                    │          │
│                              ▼                    ▼          │
│   ┌──────────────────────────────────────────────────────┐  │
│   │                    Express Server                     │  │
│   │                     PORT 3080                         │  │
│   └────────────────┬─────────────────────┬───────────────┘  │
│                    │                     │                   │
└────────────────────┼─────────────────────┼───────────────────┘
                     │                     │
                     ▼                     ▼
            ┌──────────────┐      ┌──────────────┐
            │   SQLite     │      │   AWS RDS    │
            │  (agentes)   │      │  (cambio_db) │
            │    AUTH      │      │  READ-ONLY   │
            └──────────────┘      └──────────────┘

Bancos de Dados

Banco	Tipo	Proposito
SQLite (agentes.db)	Local	Autenticacao - email, senha hash, agente_id
MySQL (cambio_db)	AWS RDS	Transacoes - somente leitura

Fluxos de Transacao

Fluxo	Tabela RDS	Descricao
BRL → USD	br_transaction_to_usa	Envio de reais para dolares
USD → BRL	pagamento_br	Recebimento de dolares em reais

Estrutura do Projeto

bi-agentes/
├── server.js                 # Entry point Express
├── package.json              # Dependencias
├── .env.example              # Template de configuracao
├── .gitignore
│
├── src/
│   ├── auth.js               # Login, logout, bcrypt, middleware
│   ├── db-local.js           # SQLite - tabela agentes
│   ├── db-rds.js             # MySQL pool read-only
│   ├── queries.js            # SQL parametrizado + serializacao
│   └── dashboard.js          # Geracao HTML (KPIs, graficos, tabela)
│
├── public/
│   └── login.html            # Tela de login
│
├── scripts/
│   └── seed-agente.js        # CLI gerenciamento de agentes
│
├── data/
│   └── agentes.db            # SQLite (criado automaticamente)
│
└── docs/                     # Documentacao adicional
    ├── ARCHITECTURE.md       # Detalhes tecnicos
    ├── API.md                # Endpoints
    └── GUIA-USUARIO.md       # Manual do agente

Instalacao

Pre-requisitos

• Node.js 18+
• Acesso ao AWS RDS (credenciais read-only)

Setup

# Clonar e instalar
git clone <repo>
cd bi-agentes
npm install

# Configurar ambiente
cp .env.example .env
# Editar .env com credenciais

Configuracao (.env)

# Conexao AWS RDS
MYSQL_URL=cambio-db.xxx.us-east-1.rds.amazonaws.com
USER_MYSQL=bi_readonly
PW_MYSQL=senha_segura

# Aplicacao
SESSION_SECRET=chave_secreta_aleatoria_32_chars
PORT=3080

Uso

Iniciar o Servidor

# Desenvolvimento
node server.js

# Producao (PM2)
pm2 start server.js --name bi-agentes
pm2 save

Acesse: http://localhost:3080

Gerenciar Agentes

Cadastrar novo agente:

node scripts/seed-agente.js \
  --email agente@cambioreal.com \
  --senha senha123 \
  --agente 76 \
  --nome "ValorFx"

Listar agentes:

node scripts/seed-agente.js --list

Saida:

ID  | Agente | Nome     | Email                  | Ativo | Criado
1   | 76     | ValorFx  | agente@cambioreal.com  | Sim   | 2024-01-15

Funcionalidades

Dashboard

KPIs Exibidos

KPI	Descricao
Transacoes	Quantidade total no periodo
Volume BRL	Soma em reais
Volume USD	Soma em dolares
Taxa Media	Media ponderada da taxa cobrada
Spread Medio	% medio sobre PTAX
IOF Total	Soma do IOF cobrado
Ticket Medio	USD medio por transacao
Clientes Ativos	Quantidade de clientes unicos

Graficos (Chart.js)

• Volume por Periodo - Barras duplas BRL/USD com eixo dual
• Top 10 Clientes - Barras horizontais por volume
• Taxa vs PTAX - Linha comparando taxa cobrada com PTAX

Filtros Disponiveis

• Data inicio / Data fim
• Granulacao: Dia, Mes, Ano
• Fluxo: BRL→USD, USD→BRL, Ambos
• Cliente especifico

Tabela de Transacoes

Colunas: Data, Cliente, Valor BRL, Valor USD, IOF %, IOF R$, PTAX, Taxa Cobrada, Spread, Spread %, Status

Seguranca

• Senhas: Hash bcrypt com 10 salt rounds
• SQL: Queries parametrizadas (previne SQL injection)
• Sessoes: 8 horas de timeout, armazenamento em memoria
• RDS: Acesso somente leitura (sem permissao de escrita)
• Isolamento: Cada agente ve apenas seus dados (WHERE agente_id = ?)

Tech Stack

Camada	Tecnologia
Runtime	Node.js 18+
Framework	Express.js
Auth DB	better-sqlite3 (WAL mode)
Data DB	mysql2/promise (pool)
Seguranca	bcrypt, express-session
Frontend	HTML5, CSS3, Vanilla JS
Graficos	Chart.js 4.x (CDN)
Tipografia	Google Fonts Inter

Troubleshooting

Erro de conexao RDS

Error: connect ETIMEDOUT

• Verificar se IP esta liberado no Security Group
• Confirmar credenciais no .env

Agente nao consegue logar

Credenciais invalidas

• Verificar se agente esta ativo: node scripts/seed-agente.js --list
• Recriar senha se necessario

Graficos nao aparecem

• Verificar conexao com internet (Chart.js via CDN)
• Abrir DevTools e verificar erros no console

Roadmap

• Autenticacao local
• Dashboard com KPIs
• Graficos interativos
• Filtros de periodo
• Exportacao Excel/CSV
• Comparativo periodo anterior
• Dashboard administrativo
• Alertas de spread

Licenca

Uso interno CambioReal.