bi-agents/docs/API.md

# 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) |