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

457
docs/API.md
View File

@@ -1,6 +1,6 @@
# API Reference - BI Agentes
# API Reference — BI-CCC
Documentacao dos endpoints HTTP do sistema BI Agentes.
Documentação dos endpoints HTTP do sistema BI-CCC.
## Base URL
@@ -8,343 +8,218 @@ Documentacao dos endpoints HTTP do sistema BI Agentes.
http://localhost:3080
```
## Autenticacao
## Autenticação
O sistema usa autenticacao baseada em sessao. Apos login bem-sucedido, um cookie de sessao e enviado automaticamente pelo browser.
O sistema usa autenticação baseada em sessão. Após login bem-sucedido, um cookie de sessão é enviado automaticamente pelo browser.
**Cookie:** `connect.sid`
**Duracao:** 8 horas
**Duração:** 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
## Endpoints de Autenticação
### POST /login
Processa tentativa de login.
**Content-Type:** `application/x-www-form-urlencoded`
**Content-Type:** `application/x-www-form-urlencoded`
| Campo | Tipo | Obrigatorio | Descricao |
|-------|------|-------------|-----------|
| email | string | Sim | Email do agente |
| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| email | string | Sim | Email do usuário |
| senha | string | Sim | Senha em texto plano |
| Status | Descricao | Redirect |
**Response:** `302` redirect para `/dashboard` (agente), `/corporate` (admin/corporate), ou `/login?error=1` (falha).
| 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 = {
**Dados da Sessão:**
```javascript
req.session.agente = {
id: 1, // ID interno SQLite
nome: "ValorFx"
}
```
email: "user@email.com",
agente_id: 76, // ID do agente no RDS (null para admin/corporate)
nome: "Nome",
role: "admin" // admin | corporate | agente
}
```
### GET /logout
### GET /logout
**Autenticacao:** Nao requerida (mas so faz sentido se logado)
Destrói sessão e redireciona para `/login`.
**Response:**
---
## Páginas HTML (Server-Side Rendered)
Todas requerem autenticação via cookie de sessão.
| Rota | Role | Descrição |
|------|------|-----------|
| `GET /corporate` | admin, corporate | Corporate Dashboard |
| `GET /admin/bi` | admin | BI Executive Dashboard |
| `GET /admin/cliente` | admin | Client 360 |
| `GET /admin` | admin | Gestão de Usuários |
| `GET /admin/home` | admin | Daily Overview |
| `GET /admin/providers` | admin | Payment Providers |
| `GET /dashboard` | agente | Dashboard pessoal do agente |
---
## APIs REST — Corporate
Todas retornam JSON e requerem role `admin` ou `corporate`.
### GET /corporate/api/kpis
KPIs de hoje vs média 30 dias.
**Response:**
|--------|-----------|----------|
| 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...
```
```json
{
"hoje": { "total_ops": 42, "volume_brl": 500000, "volume_usd": 100000, "ticket_medio": 2380 },
"media30d": { "total_ops": 35, "volume_brl": 420000, ... }
}
```
Location: /login
Set-Cookie: connect.sid=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT
```
---
### GET /corporate/api/trend
Tendência dos últimos 30 dias (volume diário).
### GET /corporate/api/top-agentes
Top 5 agentes por volume.
| Param | Tipo | Default | Descrição |
|-------|------|---------|-----------|
| dias | number | 30 | Período em dias (7, 30, 90) |
### GET /corporate/api/kpis-period
KPIs por período customizado.
| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| inicio | date | Sim | Data início (YYYY-MM-DD) |
| fim | date | Sim | Data fim (YYYY-MM-DD) |
### GET /corporate/api/trend-period
Tendência por período customizado.
| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| inicio | date | Sim | Data início |
| fim | date | Sim | Data fim |
---
Exibe o dashboard de transacoes do agente.
## APIs REST — BI Executive
**Autenticacao:** Requerida (cookie de sessao)
Requerem role `admin`.
**Response:**
### GET /admin/api/bi
Dashboard BI completo: KPIs, tendências, ranking de agentes, retenção.
| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| start | date | Sim | Data início (YYYY-MM-DD) |
| end | date | Sim | Data fim (YYYY-MM-DD) |
**Response:** Objeto com `kpis`, `kpisPrev`, `trend`, `topAgentes`, `topClientes`, `retention`.
### GET /admin/api/bi/revenue
Revenue analytics por produto com granularidade.
| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| start | date | Sim | Data início |
| end | date | Sim | Data fim |
| granularity | string | Não | `day`, `month`, `year` (default: `month`) |
### GET /admin/api/bi/strategic
BI estratégico: cohort retention, revenue expansion/contraction, cross-sell, maturidade.
| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| start | date | Sim | Data início |
| end | date | Sim | Data fim |
---
## APIs REST — Client 360
Requerem role `admin`.
### GET /admin/api/clientes/top
Top 20 clientes por volume total (lifetime).
### GET /admin/api/clientes/search
Busca clientes por nome.
| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| q | string | Sim | Termo de busca (mín. 2 caracteres) |
### GET /admin/api/cliente/:id/profile
Profile lifetime do cliente: stats gerais, health score, merchant detection.
| Param | Tipo | Descrição |
|-------|------|-----------|
| id | number | `id_conta` do cliente |
### GET /admin/api/cliente/:id/data
Dados detalhados do cliente por período: KPIs, transações, timeline, insights.
| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| id | number | Sim | `id_conta` do cliente |
| start | date | Sim | Data início |
| end | date | Sim | Data fim |
---
## APIs REST — Outras
### GET /api/cotacao
Cotação USD/BRL em tempo real (proxy para API externa AwesomeAPI).
**Autenticação:** Requerida (qualquer role)
**Response:**
|--------|-----------|
| 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
];
```
```json
{
"bid": "5.0123",
"ask": "5.0234",
"timestamp": "1706889600"
}
```
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:**
---
## Middleware
### requireAuth
}
Verifica se há sessão ativa. Redireciona para `/login` se não autenticado.
**Rotas Protegidas:**
- GET /dashboard
---
## Modelo de Dados (Sessao)
### Agente (sessao)
### requireRole(role)
```typescript
interface AgenteSession {
Verifica se o usuário tem a role necessária. Retorna `403` se não autorizado. Admin tem acesso a todas as rotas.
---
nome: string; // Nome de exibicao
## Códigos de Erro
```
---
## 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) |
| Código | Significado | Causa Comum |
|--------|-------------|-------------|
| 302 | Redirect | Login/logout, acesso não autorizado |
| 403 | Forbidden | Role insuficiente |
| 500 | Erro interno | Falha conexão RDS, erro de query |