bi-agents/README.md

# 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

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

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

### Configuracao (.env)

```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

```bash
# Desenvolvimento
node server.js

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

Acesse: `http://localhost:3080`

### Gerenciar Agentes

**Cadastrar novo agente:**
```bash
node scripts/seed-agente.js \
  --email agente@cambioreal.com \
  --senha senha123 \
  --agente 76 \
  --nome "ValorFx"
```

**Listar agentes:**
```bash
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

- [x] Autenticacao local
- [x] Dashboard com KPIs
- [x] Graficos interativos
- [x] Filtros de periodo
- [ ] Exportacao Excel/CSV
- [ ] Comparativo periodo anterior
- [ ] Dashboard administrativo
- [ ] Alertas de spread

## Licenca

Uso interno CambioReal.