cassel/bi-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation and add AI tooling configs

Browse Source 
- 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>
This commit is contained in:
Cassel
2026-03-19 13:29:03 -04:00
parent c5b377e788
commit 647cbec54f
3246 changed files with 479789 additions and 983 deletions
Download Patch File Download Diff File Expand all files Collapse all files

352
README.md
View File

@@ -1,243 +1,179 @@
# BI Agentes - CambioReal
# BI-CCC (Central Command Center) — CambioReal
Dashboard de Business Intelligence para agentes de cambio CambioReal. Monitoramento em tempo real de transacoes BRL-USD com dados do AWS RDS.
Sistema de Business Intelligence interno da CambioReal para monitoramento de operações cambiais, análise de clientes e gestão de agentes.
## Visao Geral
## O que faz
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`.
O BI-CCC consolida dados de três produtos de câmbio em dashboards visuais:
**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)
- **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
```
┌─────────────────────────────────────────────────────────────┐
│ BI Agentes (Express) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Login │───▶│ Session │───▶│ Dashboard │ │
│ │ (HTML) │ │ (Memory) │ │ (HTML) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Express Server │ │
│ │ PORT 3080 │ │
│ └────────────────┬─────────────────────┬───────────────┘ │
│ │ │ │
└────────────────────┼─────────────────────┼───────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ SQLite │ │ AWS RDS │
│ (agentes) │ │ (cambio_db) │
│ AUTH │ │ READ-ONLY │
└──────────────┘ └──────────────┘
┌─────────────────────────────────────────────────┐
│ 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 │
└───────────────────────────────┴─────────────────┘
```
### 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
## Estrutura de Arquivos
```
bi-agentes/
├── server.js # Entry point Express
├── package.json # Dependencias
├── .env.example # Template de configuracao
├── .gitignore
│
├── server.js # Rotas + APIs + middleware
├── 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)
│
│ ├── 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/
│ └── login.html # Tela de login
│
│ ├── chart.umd.min.js # Chart.js (carregado inline)
│ ├── login.html
│ └── logo.png
├── scripts/
│ └── seed-agente.js # CLI gerenciamento de agentes
│
│ ├── seed-admin.js
│ └── seed-agente.js
├── data/
│ └── agentes.db # SQLite (criado automaticamente)
│
└── docs/ # Documentacao adicional
├── ARCHITECTURE.md # Detalhes tecnicos
├── API.md # Endpoints
└── GUIA-USUARIO.md # Manual do agente
│ └── 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)
```
## Instalacao
## Roles e Permissões
### Pre-requisitos
| 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` |
- Node.js 18+
- Acesso ao AWS RDS (credenciais read-only)
## Principais Funcionalidades
### Setup
- **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
# Clonar e instalar
git clone <repo>
cd bi-agentes
npm install
# Build + restart container
docker compose build bi-ccc && docker compose down bi-ccc && docker compose up -d bi-ccc
# Configurar ambiente
cp .env.example .env
# Editar .env com credenciais
# Ver logs
docker logs bi-ccc -f
# Criar usuário admin
docker exec -it bi-ccc node scripts/seed-admin.js
```
### Configuracao (.env)
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
```env
# Conexao AWS RDS
MYSQL_URL=cambio-db.xxx.us-east-1.rds.amazonaws.com
USER_MYSQL=bi_readonly
PW_MYSQL=senha_segura
## Variáveis de Ambiente
# Aplicacao
SESSION_SECRET=chave_secreta_aleatoria_32_chars
PORT=3080
```
Copie `.env.example` para `.env` e configure:
## Uso
| 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 |
### Iniciar o Servidor
## Documentação
```bash
# Desenvolvimento
node server.js
- [Í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)
# 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
## Licença
Uso interno CambioReal.