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) |
|
||||
Reference in New Issue
Block a user