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>
This commit is contained in:
root
350
docs/API.md
Normal file
350
docs/API.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# API Reference - BI Agentes
|
||||
|
||||
Documentacao dos endpoints HTTP do sistema BI Agentes.
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
http://localhost:3080
|
||||
```
|
||||
|
||||
## Autenticacao
|
||||
|
||||
O sistema usa autenticacao baseada em sessao. Apos login bem-sucedido, um cookie de sessao e enviado automaticamente pelo browser.
|
||||
|
||||
**Cookie:** `connect.sid`
|
||||
**Duracao:** 8 horas
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### GET /login
|
||||
|
||||
Exibe a pagina de login.
|
||||
|
||||
**Autenticacao:** Nao requerida
|
||||
|
||||
**Comportamento:**
|
||||
- Se usuario ja autenticado: redireciona para `/dashboard`
|
||||
- Se nao autenticado: retorna `login.html`
|
||||
|
||||
**Response:**
|
||||
|
||||
| Status | Descricao |
|
||||
|--------|-----------|
|
||||
| 200 | Pagina HTML de login |
|
||||
| 302 | Redirect para /dashboard (se ja logado) |
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Param | Tipo | Descricao |
|
||||
|-------|------|-----------|
|
||||
| error | number | Se `1`, exibe mensagem de erro |
|
||||
|
||||
**Exemplo:**
|
||||
```http
|
||||
GET /login HTTP/1.1
|
||||
Host: localhost:3080
|
||||
```
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/html
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /login
|
||||
|
||||
Processa tentativa de login.
|
||||
|
||||
**Autenticacao:** Nao requerida
|
||||
|
||||
**Content-Type:** `application/x-www-form-urlencoded`
|
||||
|
||||
**Request Body:**
|
||||
|
||||
| Campo | Tipo | Obrigatorio | Descricao |
|
||||
|-------|------|-------------|-----------|
|
||||
| email | string | Sim | Email do agente |
|
||||
| senha | string | Sim | Senha em texto plano |
|
||||
|
||||
**Response:**
|
||||
|
||||
| Status | Descricao | Redirect |
|
||||
|--------|-----------|----------|
|
||||
| 302 | Login bem-sucedido | /dashboard |
|
||||
| 302 | Login falhou | /login?error=1 |
|
||||
|
||||
**Comportamento:**
|
||||
1. Busca agente por email no SQLite
|
||||
2. Compara senha com hash (bcrypt)
|
||||
3. Se valido, cria sessao com dados do agente
|
||||
4. Redireciona para dashboard
|
||||
|
||||
**Exemplo:**
|
||||
```http
|
||||
POST /login HTTP/1.1
|
||||
Host: localhost:3080
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
email=agente@cambioreal.com&senha=minhasenha123
|
||||
```
|
||||
|
||||
```http
|
||||
HTTP/1.1 302 Found
|
||||
Location: /dashboard
|
||||
Set-Cookie: connect.sid=s%3A...; Path=/; HttpOnly
|
||||
```
|
||||
|
||||
**Dados da Sessao (interno):**
|
||||
```javascript
|
||||
req.session.agente = {
|
||||
id: 1, // ID interno SQLite
|
||||
email: "agente@email.com",
|
||||
agente_id: 76, // ID do agente no RDS
|
||||
nome: "ValorFx"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /logout
|
||||
|
||||
Encerra a sessao do usuario.
|
||||
|
||||
**Autenticacao:** Nao requerida (mas so faz sentido se logado)
|
||||
|
||||
**Response:**
|
||||
|
||||
| Status | Descricao | Redirect |
|
||||
|--------|-----------|----------|
|
||||
| 302 | Sessao destruida | /login |
|
||||
|
||||
**Comportamento:**
|
||||
1. Destroi sessao server-side
|
||||
2. Invalida cookie
|
||||
3. Redireciona para login
|
||||
|
||||
**Exemplo:**
|
||||
```http
|
||||
GET /logout HTTP/1.1
|
||||
Host: localhost:3080
|
||||
Cookie: connect.sid=s%3A...
|
||||
```
|
||||
|
||||
```http
|
||||
HTTP/1.1 302 Found
|
||||
Location: /login
|
||||
Set-Cookie: connect.sid=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /dashboard
|
||||
|
||||
Exibe o dashboard de transacoes do agente.
|
||||
|
||||
**Autenticacao:** Requerida (cookie de sessao)
|
||||
|
||||
**Response:**
|
||||
|
||||
| Status | Descricao |
|
||||
|--------|-----------|
|
||||
| 200 | Pagina HTML do dashboard |
|
||||
| 302 | Redirect para /login (nao autenticado) |
|
||||
| 500 | Erro ao carregar dados |
|
||||
|
||||
**Comportamento:**
|
||||
1. Middleware `requireAuth` verifica sessao
|
||||
2. Busca `agente_id` da sessao
|
||||
3. Executa queries no RDS (BRL→USD e USD→BRL)
|
||||
4. Serializa e ordena dados
|
||||
5. Gera HTML com KPIs, graficos e tabela
|
||||
6. Retorna HTML completo
|
||||
|
||||
**Dados Retornados no HTML:**
|
||||
|
||||
O dashboard inclui dados embedded como JavaScript:
|
||||
|
||||
```javascript
|
||||
window.TRANSACOES = [
|
||||
{
|
||||
fluxo: "BRL → USD",
|
||||
cliente: "Cliente A",
|
||||
data_operacao: "2024-01-15 14:30",
|
||||
valor_reais: 10000.00,
|
||||
valor_dolar: 2000.00,
|
||||
iof_pct: 1.10,
|
||||
iof_valor_rs: 110.00,
|
||||
taxa_ptax: 4.95,
|
||||
taxa_cobrada: 5.00,
|
||||
spread_bruto: 0.05,
|
||||
spread_pct: 1.00,
|
||||
status: "completed"
|
||||
},
|
||||
// ... mais transacoes
|
||||
];
|
||||
```
|
||||
|
||||
**Exemplo:**
|
||||
```http
|
||||
GET /dashboard HTTP/1.1
|
||||
Host: localhost:3080
|
||||
Cookie: connect.sid=s%3A...
|
||||
```
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/html
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /
|
||||
|
||||
Redireciona para o dashboard.
|
||||
|
||||
**Autenticacao:** Nao requerida (redirect acontece primeiro)
|
||||
|
||||
**Response:**
|
||||
|
||||
| Status | Descricao | Redirect |
|
||||
|--------|-----------|----------|
|
||||
| 302 | Redirect | /dashboard |
|
||||
|
||||
**Exemplo:**
|
||||
```http
|
||||
GET / HTTP/1.1
|
||||
Host: localhost:3080
|
||||
```
|
||||
|
||||
```http
|
||||
HTTP/1.1 302 Found
|
||||
Location: /dashboard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Arquivos Estaticos
|
||||
|
||||
### GET /public/*
|
||||
|
||||
Serve arquivos estaticos da pasta `public/`.
|
||||
|
||||
**Autenticacao:** Nao requerida
|
||||
|
||||
**Arquivos Disponiveis:**
|
||||
|
||||
| Path | Arquivo |
|
||||
|------|---------|
|
||||
| /public/login.html | Pagina de login |
|
||||
|
||||
**Exemplo:**
|
||||
```http
|
||||
GET /public/login.html HTTP/1.1
|
||||
Host: localhost:3080
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Codigos de Erro
|
||||
|
||||
| Codigo | Significado | Causa Comum |
|
||||
|--------|-------------|-------------|
|
||||
| 302 | Redirect | Login/logout, acesso nao autorizado |
|
||||
| 500 | Erro interno | Falha conexao RDS, erro de query |
|
||||
|
||||
---
|
||||
|
||||
## Middleware
|
||||
|
||||
### requireAuth
|
||||
|
||||
Middleware que protege rotas que exigem autenticacao.
|
||||
|
||||
**Comportamento:**
|
||||
```javascript
|
||||
function requireAuth(req, res, next) {
|
||||
if (req.session && req.session.agente) {
|
||||
return next(); // Continua para rota
|
||||
}
|
||||
res.redirect('/login'); // Redireciona
|
||||
}
|
||||
```
|
||||
|
||||
**Rotas Protegidas:**
|
||||
- GET /dashboard
|
||||
|
||||
---
|
||||
|
||||
## Modelo de Dados (Sessao)
|
||||
|
||||
### Agente (sessao)
|
||||
|
||||
```typescript
|
||||
interface AgenteSession {
|
||||
id: number; // ID interno (SQLite)
|
||||
email: string; // Email do agente
|
||||
agente_id: number; // ID no sistema RDS
|
||||
nome: string; // Nome de exibicao
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Fluxo Completo de Login
|
||||
|
||||
```bash
|
||||
# 1. Tentar acessar dashboard (sera redirecionado)
|
||||
curl -v http://localhost:3080/dashboard
|
||||
# < HTTP/1.1 302 Found
|
||||
# < Location: /login
|
||||
|
||||
# 2. Fazer login
|
||||
curl -v -X POST http://localhost:3080/login \
|
||||
-d "email=agente@cambioreal.com" \
|
||||
-d "senha=minhasenha" \
|
||||
-c cookies.txt
|
||||
# < HTTP/1.1 302 Found
|
||||
# < Location: /dashboard
|
||||
# < Set-Cookie: connect.sid=...
|
||||
|
||||
# 3. Acessar dashboard com cookie
|
||||
curl -v http://localhost:3080/dashboard \
|
||||
-b cookies.txt
|
||||
# < HTTP/1.1 200 OK
|
||||
# < Content-Type: text/html
|
||||
|
||||
# 4. Fazer logout
|
||||
curl -v http://localhost:3080/logout \
|
||||
-b cookies.txt
|
||||
# < HTTP/1.1 302 Found
|
||||
# < Location: /login
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Futuras Extensoes
|
||||
|
||||
Endpoints planejados para proximas versoes:
|
||||
|
||||
| Endpoint | Metodo | Descricao |
|
||||
|----------|--------|-----------|
|
||||
| /api/export | GET | Exportar transacoes (CSV/Excel) |
|
||||
| /api/kpis | GET | KPIs em formato JSON |
|
||||
| /api/transacoes | GET | Transacoes paginadas (JSON) |
|
||||
## Futuras Extensoes
|
||||
|
||||
Endpoints planejados para proximas versoes:
|
||||
|
||||
| Endpoint | Metodo | Descricao |
|
||||
|----------|--------|-----------|
|
||||
| /api/export | GET | Exportar transacoes (CSV/Excel) |
|
||||
| /api/kpis | GET | KPIs em formato JSON |
|
||||
| /api/transacoes | GET | Transacoes paginadas (JSON) |
|
||||
349
docs/ARCHITECTURE.md
Normal file
349
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# Arquitetura - BI Agentes
|
||||
|
||||
Documentacao tecnica da arquitetura do sistema BI Agentes.
|
||||
|
||||
## Visao Geral
|
||||
|
||||
O BI Agentes e uma aplicacao web monolitica construida com Node.js/Express que serve dashboards de BI para agentes de cambio. A arquitetura prioriza simplicidade, seguranca e isolamento de dados.
|
||||
|
||||
## Diagrama de Arquitetura
|
||||
|
||||
```
|
||||
INTERNET
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────────────────────────────────────────┐
|
||||
│ SERVIDOR EXPRESS │
|
||||
│ (PORT 3080) │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
|
||||
│ │ Static │ │ Session │ │ Auth │ │ Dashboard │ │
|
||||
│ │ Files │ │ Middleware │ │ Middleware │ │ Generator │ │
|
||||
│ │ /public │ │ (in-memory) │ │ requireAuth │ │ (HTML) │ │
|
||||
│ └─────────────┘ └──────┬──────┘ └──────┬──────┘ └─────┬──────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ REQUEST ROUTER │ │
|
||||
│ │ │ │
|
||||
│ │ GET /login ──────▶ login.html │ │
|
||||
│ │ POST /login ─────▶ authenticate() ──▶ session.create() │ │
|
||||
│ │ GET /logout ─────▶ session.destroy() │ │
|
||||
│ │ GET /dashboard ──▶ requireAuth ──▶ fetchTransacoes() ──▶ HTML │ │
|
||||
│ │ GET / ───────────▶ redirect /dashboard │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
└────────────────────────────┼───────────────────────────┼──────────────────┘
|
||||
│ │
|
||||
┌──────────────┘ └──────────────┐
|
||||
▼ ▼
|
||||
┌───────────────────┐ ┌───────────────────┐
|
||||
│ SQLite │ │ AWS RDS │
|
||||
│ (agentes.db) │ │ (cambio_db) │
|
||||
│ │ │ │
|
||||
│ ┌─────────────┐ │ │ ┌─────────────┐ │
|
||||
│ │ agentes │ │ │ │br_transac...│ │
|
||||
│ │ - id │ │ │ │- id │ │
|
||||
│ │ - email │ │ │ │- id_conta │ │
|
||||
│ │ - senha_hash│ │ │ │- amount_brl │ │
|
||||
│ │ - agente_id │ │ │ │- amount_usd │ │
|
||||
│ │ - nome │ │ │ │- exchange...| │
|
||||
│ │ - ativo │ │ │ │- status │ │
|
||||
│ └─────────────┘ │ │ └─────────────┘ │
|
||||
│ │ │ │
|
||||
│ LOCAL (WAL) │ │ ┌─────────────┐ │
|
||||
│ WRITE + READ │ │ │pagamento_br │ │
|
||||
└───────────────────┘ │ │- id │ │
|
||||
│ │- id_conta │ │
|
||||
│ │- valor │ │
|
||||
│ │- valor_sol │ │
|
||||
│ │- cotacao │ │
|
||||
│ └─────────────┘ │
|
||||
│ │
|
||||
│ REMOTE (MySQL) │
|
||||
│ READ-ONLY │
|
||||
└───────────────────┘
|
||||
```
|
||||
|
||||
## Componentes
|
||||
|
||||
### 1. Camada de Apresentacao
|
||||
|
||||
**Tecnologias:** HTML5, CSS3, Vanilla JavaScript, Chart.js
|
||||
|
||||
| Arquivo | Responsabilidade |
|
||||
|---------|------------------|
|
||||
| `public/login.html` | Formulario de login estilizado |
|
||||
| `src/dashboard.js` | Geracao dinamica do HTML do dashboard |
|
||||
|
||||
**Caracteristicas:**
|
||||
- Server-Side Rendering (SSR) - HTML gerado no backend
|
||||
- Chart.js carregado via CDN (sem build step)
|
||||
- CSS inline no dashboard para simplicidade
|
||||
- Google Fonts Inter para tipografia
|
||||
|
||||
### 2. Camada de Aplicacao
|
||||
|
||||
**Tecnologias:** Node.js, Express.js
|
||||
|
||||
| Modulo | Responsabilidade |
|
||||
|--------|------------------|
|
||||
| `server.js` | Entry point, rotas, middleware |
|
||||
| `src/auth.js` | Autenticacao, bcrypt, sessoes |
|
||||
| `src/queries.js` | Queries SQL, serializacao de dados |
|
||||
|
||||
**Middleware Stack:**
|
||||
```
|
||||
Request
|
||||
│
|
||||
▼
|
||||
express.urlencoded() ← Parse form data
|
||||
│
|
||||
▼
|
||||
express.json() ← Parse JSON
|
||||
│
|
||||
▼
|
||||
express-session() ← Gerenciar sessao
|
||||
│
|
||||
▼
|
||||
requireAuth() ← Verificar autenticacao (rotas protegidas)
|
||||
│
|
||||
▼
|
||||
Route Handler
|
||||
```
|
||||
|
||||
### 3. Camada de Dados
|
||||
|
||||
#### SQLite (Local)
|
||||
|
||||
**Biblioteca:** better-sqlite3 (sincrono, WAL mode)
|
||||
|
||||
```sql
|
||||
CREATE TABLE agentes (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
email TEXT UNIQUE NOT NULL,
|
||||
senha_hash TEXT NOT NULL,
|
||||
agente_id INTEGER NOT NULL,
|
||||
nome TEXT NOT NULL,
|
||||
ativo INTEGER DEFAULT 1,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
**Caracteristicas:**
|
||||
- WAL mode para melhor concorrencia
|
||||
- Arquivo em `data/agentes.db`
|
||||
- Criado automaticamente no primeiro start
|
||||
|
||||
#### MySQL (RDS)
|
||||
|
||||
**Biblioteca:** mysql2/promise (pool de conexoes)
|
||||
|
||||
**Configuracao do Pool:**
|
||||
```javascript
|
||||
{
|
||||
host: process.env.MYSQL_URL,
|
||||
user: process.env.USER_MYSQL,
|
||||
password: process.env.PW_MYSQL,
|
||||
database: 'cambio_db',
|
||||
waitForConnections: true,
|
||||
connectionLimit: 10,
|
||||
queueLimit: 0
|
||||
}
|
||||
```
|
||||
|
||||
**Tabelas Consultadas:**
|
||||
|
||||
| Tabela | Fluxo | Campos Principais |
|
||||
|--------|-------|-------------------|
|
||||
| `br_transaction_to_usa` | BRL→USD | amount_brl, amount_usd, exchange_rate, iof, ptax |
|
||||
| `pagamento_br` | USD→BRL | valor, valor_sol, cotacao, ptax |
|
||||
| `ag_contas` | Join | agente_id, conta_id |
|
||||
| `conta` | Join | id_conta, nome |
|
||||
|
||||
## Fluxo de Dados
|
||||
|
||||
### Autenticacao
|
||||
|
||||
```
|
||||
┌──────────┐ POST /login ┌──────────┐
|
||||
│ Browser │ ─────────────────▶ │ Express │
|
||||
│ │ email, senha │ │
|
||||
└──────────┘ └────┬─────┘
|
||||
│
|
||||
┌────────────────┘
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ SQLite │
|
||||
│ SELECT WHERE │
|
||||
│ email = ? │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ bcrypt │
|
||||
│ compare │
|
||||
└──────┬───────┘
|
||||
│
|
||||
┌───────┴───────┐
|
||||
▼ ▼
|
||||
[MATCH] [NO MATCH]
|
||||
│ │
|
||||
▼ ▼
|
||||
session.agente redirect
|
||||
= {...} /login?error=1
|
||||
│
|
||||
▼
|
||||
redirect
|
||||
/dashboard
|
||||
```
|
||||
|
||||
### Carregamento do Dashboard
|
||||
|
||||
```
|
||||
┌──────────┐ GET /dashboard ┌──────────┐
|
||||
│ Browser │ ─────────────────▶ │ Express │
|
||||
│ (cookie) │ │ │
|
||||
└──────────┘ └────┬─────┘
|
||||
│
|
||||
requireAuth()────┘
|
||||
│
|
||||
┌─────────────┴─────────────┐
|
||||
▼ ▼
|
||||
[NO SESSION] [HAS SESSION]
|
||||
│ │
|
||||
▼ ▼
|
||||
redirect ┌─────────────────┐
|
||||
/login │ fetchTransacoes │
|
||||
│ (agente_id) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌─────────────────┘
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ AWS RDS │
|
||||
│ 2 queries: │
|
||||
│ BRL→USD │
|
||||
│ USD→BRL │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ serialize() │
|
||||
│ merge + │
|
||||
│ sort │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ buildHTML() │
|
||||
│ KPIs + │
|
||||
│ Charts + │
|
||||
│ Table │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
res.send(html)
|
||||
```
|
||||
|
||||
## Seguranca
|
||||
|
||||
### Autenticacao
|
||||
|
||||
| Aspecto | Implementacao |
|
||||
|---------|---------------|
|
||||
| Hash de senha | bcrypt, 10 salt rounds |
|
||||
| Sessao | express-session, in-memory |
|
||||
| Timeout | 8 horas (cookie maxAge) |
|
||||
| Middleware | requireAuth em rotas protegidas |
|
||||
|
||||
### Protecao de Dados
|
||||
|
||||
| Aspecto | Implementacao |
|
||||
|---------|---------------|
|
||||
| SQL Injection | Queries parametrizadas (?) |
|
||||
| Isolamento | WHERE agente_id = ? em todas queries |
|
||||
| RDS Access | Usuario read-only (sem INSERT/UPDATE/DELETE) |
|
||||
|
||||
### Recomendacoes para Producao
|
||||
|
||||
- [ ] Usar Redis para sessoes (em vez de in-memory)
|
||||
- [ ] HTTPS obrigatorio (TLS)
|
||||
- [ ] Helmet.js para headers de seguranca
|
||||
- [ ] Rate limiting no login
|
||||
- [ ] Logs de auditoria
|
||||
|
||||
## Performance
|
||||
|
||||
### Estrategias Atuais
|
||||
|
||||
- **Connection Pool**: 10 conexoes MySQL reutilizaveis
|
||||
- **WAL Mode**: SQLite com Write-Ahead Logging
|
||||
- **CDN**: Chart.js e fonts via CDN (cache do browser)
|
||||
- **SSR**: HTML pre-renderizado (sem SPA overhead)
|
||||
|
||||
### Gargalos Potenciais
|
||||
|
||||
| Componente | Risco | Mitigacao |
|
||||
|------------|-------|-----------|
|
||||
| Sessoes in-memory | Perda em restart | Migrar para Redis |
|
||||
| Queries RDS | Tabelas grandes | Adicionar indices, paginacao |
|
||||
| HTML generation | Muitas transacoes | Paginacao server-side |
|
||||
|
||||
## Estrutura de Modulos
|
||||
|
||||
```
|
||||
src/
|
||||
├── auth.js # Autenticacao
|
||||
│ ├── authenticate(email, senha)
|
||||
│ └── requireAuth(req, res, next)
|
||||
│
|
||||
├── db-local.js # SQLite setup
|
||||
│ └── initDB()
|
||||
│
|
||||
├── db-rds.js # MySQL pool
|
||||
│ └── pool (export)
|
||||
│
|
||||
├── queries.js # Data access
|
||||
│ ├── fetchTransacoes(agenteId)
|
||||
│ └── serialize(rowsBrlUsd, rowsUsdBrl)
|
||||
│
|
||||
└── dashboard.js # View generation
|
||||
└── buildHTML(data, agente)
|
||||
```
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Pacote | Versao | Proposito |
|
||||
|--------|--------|-----------|
|
||||
| express | ^4.x | Framework web |
|
||||
| express-session | ^1.x | Gerenciamento de sessao |
|
||||
| better-sqlite3 | ^9.x | SQLite driver (sync) |
|
||||
| mysql2 | ^3.x | MySQL driver (async) |
|
||||
| bcrypt | ^5.x | Hash de senhas |
|
||||
| dotenv | ^16.x | Variaveis de ambiente |
|
||||
|
||||
## Extensibilidade
|
||||
|
||||
### Adicionar Nova Feature
|
||||
|
||||
1. **Novo endpoint**: Adicionar rota em `server.js`
|
||||
2. **Nova query**: Adicionar funcao em `src/queries.js`
|
||||
3. **Nova UI**: Modificar `src/dashboard.js` ou criar novo modulo
|
||||
|
||||
### Adicionar Novo Fluxo de Transacao
|
||||
|
||||
1. Criar query em `src/queries.js`
|
||||
2. Atualizar `serialize()` para incluir novo fluxo
|
||||
3. Atualizar `buildHTML()` para exibir dados
|
||||
|
||||
## Decisoes de Arquitetura
|
||||
|
||||
| Decisao | Justificativa |
|
||||
|---------|---------------|
|
||||
| Monolito | Simplicidade para equipe pequena |
|
||||
| SSR | Sem necessidade de SPA, SEO nao relevante |
|
||||
| SQLite para auth | Independencia do RDS, portabilidade |
|
||||
| Vanilla JS | Sem build step, menor complexidade |
|
||||
| better-sqlite3 | Sync API mais simples para auth |
|
||||
| mysql2 | Pool de conexoes async para RDS |
|
||||
BIN
docs/CambioReal_original.png
Normal file
BIN
docs/CambioReal_original.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
272
docs/GUIA-USUARIO.md
Normal file
272
docs/GUIA-USUARIO.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Guia do Usuario - BI Agentes
|
||||
|
||||
Manual de uso do dashboard de transacoes para agentes CambioReal.
|
||||
|
||||
---
|
||||
|
||||
## Indice
|
||||
|
||||
1. [Acessando o Sistema](#acessando-o-sistema)
|
||||
2. [Visao Geral do Dashboard](#visao-geral-do-dashboard)
|
||||
3. [Usando os Filtros](#usando-os-filtros)
|
||||
4. [Entendendo os KPIs](#entendendo-os-kpis)
|
||||
5. [Interpretando os Graficos](#interpretando-os-graficos)
|
||||
6. [Tabela de Transacoes](#tabela-de-transacoes)
|
||||
7. [Perguntas Frequentes](#perguntas-frequentes)
|
||||
|
||||
---
|
||||
|
||||
## Acessando o Sistema
|
||||
|
||||
### Login
|
||||
|
||||
1. Abra o navegador e acesse o endereco fornecido pelo administrador
|
||||
2. Na tela de login, digite:
|
||||
- **E-mail**: Seu email cadastrado
|
||||
- **Senha**: Sua senha pessoal
|
||||
3. Clique em **Entrar**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ BI Agentes │
|
||||
│ CambioReal - Dashboard │
|
||||
│ │
|
||||
│ E-mail: [_________________] │
|
||||
│ │
|
||||
│ Senha: [_________________] │
|
||||
│ │
|
||||
│ [ Entrar ] │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Dica:** Se aparecer a mensagem "E-mail ou senha incorretos", verifique se digitou corretamente. Caso persista, contate o administrador.
|
||||
|
||||
### Logout
|
||||
|
||||
Para sair do sistema, clique no botao **Sair** no canto superior direito do dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Visao Geral do Dashboard
|
||||
|
||||
Apos o login, voce vera o dashboard com suas transacoes:
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ [Nome do Agente] - Agente [ID] [Ao vivo] [Sair] │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ De: [____] Ate: [____] Granulacao: [___] Fluxo: [___] [Aplicar] │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||||
│ │ KPI 1 │ │ KPI 2 │ │ KPI 3 │ │ KPI 4 │ <- Indicadores │
|
||||
│ └────────┘ └────────┘ └────────┘ └────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Grafico 1 │ │ Grafico 2 │ <- Graficos │
|
||||
│ └─────────────────┘ └─────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ Tabela de Transacoes │ <- Detalhes │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Importante:** Voce ve apenas suas proprias transacoes. Outros agentes nao tem acesso aos seus dados.
|
||||
|
||||
---
|
||||
|
||||
## Usando os Filtros
|
||||
|
||||
Os filtros ficam na barra abaixo do cabecalho. Use-os para refinar a visualizacao:
|
||||
|
||||
### Periodo (De / Ate)
|
||||
|
||||
Selecione a data inicial e final para ver transacoes em um periodo especifico.
|
||||
|
||||
**Exemplo:** Para ver transacoes de janeiro:
|
||||
- De: `2024-01-01`
|
||||
- Ate: `2024-01-31`
|
||||
|
||||
### Granulacao
|
||||
|
||||
Escolha como agrupar os dados nos graficos:
|
||||
|
||||
| Opcao | Uso |
|
||||
|-------|-----|
|
||||
| **Dia** | Ver detalhes diarios (periodos curtos) |
|
||||
| **Mes** | Visao mensal (padrao, recomendado) |
|
||||
| **Ano** | Comparar anos inteiros |
|
||||
|
||||
### Fluxo
|
||||
|
||||
Filtre por tipo de operacao:
|
||||
|
||||
| Opcao | Significado |
|
||||
|-------|-------------|
|
||||
| **Todos** | BRL→USD e USD→BRL juntos |
|
||||
| **BRL → USD** | Apenas envios (reais para dolares) |
|
||||
| **USD → BRL** | Apenas recebimentos (dolares para reais) |
|
||||
|
||||
### Cliente
|
||||
|
||||
Selecione um cliente especifico ou deixe em "Todos" para ver todas as transacoes.
|
||||
|
||||
### Aplicar
|
||||
|
||||
**Importante:** Apos alterar os filtros, clique em **Aplicar** para atualizar a tela.
|
||||
|
||||
---
|
||||
|
||||
## Entendendo os KPIs
|
||||
|
||||
Os KPIs (Indicadores-Chave) mostram um resumo do periodo selecionado:
|
||||
|
||||
### Transacoes
|
||||
Quantidade total de operacoes realizadas.
|
||||
|
||||
### Volume BRL
|
||||
Soma de todos os valores em reais movimentados.
|
||||
|
||||
**Exemplo:** Se teve 3 transacoes de R$ 10.000, R$ 20.000 e R$ 15.000, o volume e R$ 45.000.
|
||||
|
||||
### Volume USD
|
||||
Soma de todos os valores em dolares movimentados.
|
||||
|
||||
### Taxa Media
|
||||
Media ponderada da taxa de cambio cobrada (BRL/USD).
|
||||
|
||||
**Ponderada significa:** Transacoes maiores tem mais peso no calculo.
|
||||
|
||||
### Spread Medio
|
||||
Porcentagem media de lucro sobre a taxa PTAX.
|
||||
|
||||
**O que e PTAX?** Taxa de cambio oficial do Banco Central.
|
||||
|
||||
**Exemplo:** Se a PTAX e 5,00 e voce cobra 5,05, o spread e 1% (0,05 / 5,00).
|
||||
|
||||
### IOF Total
|
||||
Soma do IOF (Imposto sobre Operacoes Financeiras) recolhido.
|
||||
|
||||
### Ticket Medio
|
||||
Valor medio em USD por operacao.
|
||||
|
||||
**Calculo:** Volume USD / Numero de Transacoes
|
||||
|
||||
### Clientes Ativos
|
||||
Quantos clientes diferentes fizeram transacoes no periodo.
|
||||
|
||||
---
|
||||
|
||||
## Interpretando os Graficos
|
||||
|
||||
### Volume BRL / USD por Periodo
|
||||
|
||||
Grafico de barras mostrando a evolucao do volume ao longo do tempo.
|
||||
|
||||
- **Barras verdes** = Volume em BRL (eixo esquerdo)
|
||||
- **Barras azuis** = Volume em USD (eixo direito)
|
||||
|
||||
**Como ler:**
|
||||
- Barras mais altas = mais volume naquele periodo
|
||||
- Compare meses para identificar sazonalidade
|
||||
|
||||
### Volume por Cliente (Top 10)
|
||||
|
||||
Grafico horizontal mostrando os 10 maiores clientes por volume USD.
|
||||
|
||||
**Como usar:**
|
||||
- Identifique seus clientes mais importantes
|
||||
- Foque atencao nos maiores volumes
|
||||
|
||||
### Taxa Cobrada vs PTAX
|
||||
|
||||
Grafico de linha comparando sua taxa com a taxa oficial.
|
||||
|
||||
- **Linha roxa** = Sua taxa cobrada (media ponderada)
|
||||
- **Linha azul** = PTAX oficial
|
||||
|
||||
**O que observar:**
|
||||
- A distancia entre as linhas e seu spread
|
||||
- Quanto maior a distancia, maior sua margem
|
||||
|
||||
---
|
||||
|
||||
## Tabela de Transacoes
|
||||
|
||||
A tabela mostra todas as transacoes individuais do periodo.
|
||||
|
||||
### Colunas
|
||||
|
||||
| Coluna | Descricao |
|
||||
|--------|-----------|
|
||||
| **Data/Hora** | Quando a transacao foi realizada |
|
||||
| **Cliente** | Nome do cliente |
|
||||
| **Valor BRL** | Valor em reais |
|
||||
| **Valor USD** | Valor em dolares |
|
||||
| **IOF %** | Aliquota de IOF aplicada |
|
||||
| **IOF R$** | Valor do IOF em reais |
|
||||
| **PTAX** | Taxa oficial do BC no momento |
|
||||
| **Taxa Cobrada** | Sua taxa de cambio |
|
||||
| **Spread** | Diferenca entre taxa cobrada e PTAX |
|
||||
| **Spread %** | Spread em porcentagem |
|
||||
| **Status** | Situacao da operacao |
|
||||
|
||||
### Organizacao
|
||||
|
||||
As transacoes sao separadas por fluxo:
|
||||
- **BRL → USD** (fundo roxo claro) - Envios
|
||||
- **USD → BRL** (fundo azul claro) - Recebimentos
|
||||
|
||||
### Navegando
|
||||
|
||||
- Use a barra de rolagem horizontal para ver todas as colunas
|
||||
- A tabela ordena por data (mais antigas primeiro)
|
||||
|
||||
---
|
||||
|
||||
## Perguntas Frequentes
|
||||
|
||||
### Posso ver transacoes de outros agentes?
|
||||
|
||||
**Nao.** Cada agente ve apenas suas proprias transacoes. O sistema garante isolamento total dos dados.
|
||||
|
||||
### Os dados sao atualizados em tempo real?
|
||||
|
||||
**Sim.** A cada vez que voce carrega o dashboard ou aplica filtros, os dados sao buscados diretamente do sistema.
|
||||
|
||||
### O que fazer se os graficos nao aparecerem?
|
||||
|
||||
1. Verifique sua conexao com a internet (os graficos usam biblioteca externa)
|
||||
2. Tente recarregar a pagina (F5)
|
||||
3. Se persistir, contate o suporte tecnico
|
||||
|
||||
### Como exportar os dados?
|
||||
|
||||
*Em breve!* Estamos desenvolvendo funcionalidade de exportacao para Excel/CSV.
|
||||
|
||||
### A sessao expira?
|
||||
|
||||
**Sim.** Apos 8 horas de inatividade, voce precisara fazer login novamente.
|
||||
|
||||
### Posso acessar de celular?
|
||||
|
||||
**Sim.** O dashboard e responsivo e funciona em dispositivos moveis, porem a experiencia e melhor em telas maiores.
|
||||
|
||||
### O que significa PTAX?
|
||||
|
||||
PTAX e a taxa de cambio oficial divulgada pelo Banco Central do Brasil. E usada como referencia para calcular o spread das operacoes.
|
||||
|
||||
---
|
||||
|
||||
## Suporte
|
||||
|
||||
Em caso de problemas:
|
||||
1. Verifique usuario e senha
|
||||
2. Tente recarregar a pagina
|
||||
3. Contate o administrador do sistema
|
||||
|
||||
---
|
||||
|
||||
*CambioReal - BI Agentes v1.0*
|
||||
BIN
docs/logo-small.png
Normal file
BIN
docs/logo-small.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.8 KiB |
Reference in New Issue
Block a user