chore: adiciona Docker, scripts e documentacao

- Adiciona Dockerfile e docker-compose para containerizacao - Adiciona docker-entrypoint.sh com inicializacao - Adiciona scripts/seed-admin.js para criar admin inicial - Adiciona docs/ com logos originais CambioReal - Atualiza README.md com instrucoes de uso - Atualiza queries.js com metricas de portfólio Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-08 13:20:15 -05:00
parent 1321b949e4
commit 96222aa6a2
12 changed files with 1470 additions and 68 deletions
--- a/README.md
+++ b/README.md
@@ -1,109 +1,243 @@
-# BI Agentes — CambioReal
+# BI Agentes - CambioReal

-Dashboard de transações para agentes CambioReal com autenticação local e dados ao vivo do RDS.
+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)      │
-│                                 │
-│  SQLite (auth)    Express/HTTP  │
-│  agentes.db       :3080         │
-│  email/senha      /login        │
-│  agente_id        /dashboard    │
-└───────────────────────┬─────────┘
-                        │ READ-ONLY
-                 ┌──────▼──────┐
-                 │  cambio_db  │
-                 │  (AWS RDS)  │
-                 └─────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                    BI Agentes (Express)                      │
+│                                                              │
+│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│   │   Login      │───▶│   Session    │───▶│  Dashboard   │  │
+│   │   (HTML)     │    │   (Memory)   │    │   (HTML)     │  │
+│   └──────────────┘    └──────────────┘    └──────────────┘  │
+│                              │                    │          │
+│                              ▼                    ▼          │
+│   ┌──────────────────────────────────────────────────────┐  │
+│   │                    Express Server                     │  │
+│   │                     PORT 3080                         │  │
+│   └────────────────┬─────────────────────┬───────────────┘  │
+│                    │                     │                   │
+└────────────────────┼─────────────────────┼───────────────────┘
+                     │                     │
+                     ▼                     ▼
+            ┌──────────────┐      ┌──────────────┐
+            │   SQLite     │      │   AWS RDS    │
+            │  (agentes)   │      │  (cambio_db) │
+            │    AUTH      │      │  READ-ONLY   │
+            └──────────────┘      └──────────────┘
 ```

- **SQLite local** — controle de agentes (email, senha bcrypt, agente_id). Sem dependência do RDS para autenticação.
- **MySQL RDS** — somente leitura. Consulta `br_transaction_to_usa` (BRL→USD) e `pagamento_br` (USD→BRL) filtradas pelo `agente_id` da sessão.
+### Bancos de Dados

-## Estrutura
+| 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 + sessions)
+├── server.js                 # Entry point Express
+├── package.json              # Dependencias
+├── .env.example              # Template de configuracao
+├── .gitignore
+│
 ├── src/
-│   ├── auth.js             ← Login/logout, bcrypt, middleware requireAuth
-│   ├── db-local.js         ← SQLite (better-sqlite3) — tabela agentes
-│   ├── db-rds.js           ← MySQL pool read-only (mysql2)
-│   ├── queries.js          ← SQL parametrizado por agente_id
-│   └── dashboard.js        ← Gerador HTML (KPIs, Chart.js, tabela)
+│   ├── 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
+│   └── login.html            # Tela de login
+│
 ├── scripts/
-│   └── seed-agente.js      ← CLI para cadastrar/listar agentes
+│   └── seed-agente.js        # CLI gerenciamento de agentes
+│
 ├── data/
-│   └── agentes.db          ← SQLite database (gerado automaticamente)
-├── .env                    ← Credenciais RDS + SESSION_SECRET
-└── .gitignore
+│   └── agentes.db            # SQLite (criado automaticamente)
+│
+└── docs/                     # Documentacao adicional
+    ├── ARCHITECTURE.md       # Detalhes tecnicos
+    ├── API.md                # Endpoints
+    └── GUIA-USUARIO.md       # Manual do agente
 ```

-## Setup
+## 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
-cp .env.example .env   # editar com credenciais do RDS
+
+# Configurar ambiente
+cp .env.example .env
+# Editar .env com credenciais
 ```

-## Configuração (.env)
+### Configuracao (.env)

-```
-MYSQL_URL=<host-rds>
-USER_MYSQL=<usuario-readonly>
-PW_MYSQL=<senha>
-SESSION_SECRET=<chave-secreta-sessao>
+```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
 ```

-## Gerenciar Agentes
+## Uso

-Cadastrar:
+### Iniciar o Servidor

 ```bash
-node scripts/seed-agente.js --email agente@email.com --senha 123456 --agente 76 --nome "ValorFx"
+# Desenvolvimento
+node server.js
+
+# Producao (PM2)
+pm2 start server.js --name bi-agentes
+pm2 save
 ```

-Listar:
+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
 ```

-## Rodar
-
-```bash
-node server.js
-# BI Agentes rodando: http://localhost:3080
+**Saida:**
+```
+ID  | Agente | Nome     | Email                  | Ativo | Criado
+1   | 76     | ValorFx  | agente@cambioreal.com  | Sim   | 2024-01-15
 ```

-Para produção (intranet):
+## Funcionalidades

-```bash
-pm2 start server.js --name bi-agentes
+### 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

-## Funcionalidades do Dashboard
+### Agente nao consegue logar
+```
+Credenciais invalidas
+```
+- Verificar se agente esta ativo: `node scripts/seed-agente.js --list`
+- Recriar senha se necessario

- **Autenticação** — cada agente loga com email/senha e vê apenas suas transações
- **KPIs** — transações, volume BRL/USD, taxa média, spread, IOF, ticket médio, clientes ativos
- **Gráficos** — volume por período (BRL+USD dual axis), volume por cliente (top 10), taxa cobrada vs PTAX
- **Tabela** — todas as transações com data/hora, cliente, valores, IOF, taxas, spread, status
- **Filtros** — período (de/até), granulação (dia/mês/ano), fluxo (BRL→USD / USD→BRL), cliente
- **Dados ao vivo** — cada refresh consulta o RDS em tempo real
- **Dois fluxos** — BRL→USD (`br_transaction_to_usa`) e USD→BRL (`pagamento_br`)
+### Graficos nao aparecem
+- Verificar conexao com internet (Chart.js via CDN)
+- Abrir DevTools e verificar erros no console

-## Stack
+## Roadmap

- Node.js + Express
- express-session (sessões em memória)
- better-sqlite3 (auth local)
- mysql2 (RDS read-only)
- bcrypt (hash de senhas)
- Chart.js 4.x (gráficos client-side via CDN)
- Google Fonts Inter (tipografia via CDN)
+- [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.