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 |

483
docs/ARCHITECTURE.md
View File

@@ -1,10 +1,10 @@
# Arquitetura - BI Agentes
# Arquitetura — BI-CCC
Documentacao tecnica da arquitetura do sistema BI Agentes.
Documentação técnica da arquitetura do sistema BI-CCC (Central Command Center).
## Visao Geral
## Visão 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.
O BI-CCC é uma aplicação web monolítica construída com Node.js/Express que serve dashboards de BI para a operação de câmbio da CambioReal. A arquitetura prioriza simplicidade, segurança, isolamento de dados e performance via cache inteligente.
## Diagrama de Arquitetura
@@ -12,338 +12,233 @@ O BI Agentes e uma aplicacao web monolitica construida com Node.js/Express que s
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 │
└───────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ Docker Container (bi-ccc) │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Express Server (PORT 3080) │ │
│ │ │ │
│ │ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │ │
│ │ │ Session │ │requireAuth│ │requireRole│ │ Static │ │ │
│ │ │Middleware│─▶│ │─▶│ │─▶│ /public │ │ │
│ │ └──────────┘ └───────────┘ └───────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ Route Handlers │ │ │
│ │ │ │ │ │
│ │ │ /corporate ──▶ admin-dashboard.js ──▶ buildCorporateHTML│ │ │
│ │ │ /admin/bi ──▶ admin-bi.js ──▶ buildBiHTML │ │ │
│ │ │ /admin/cliente ▶ admin-cliente.js ──▶ buildClienteHTML │ │ │
│ │ │ /admin ──▶ admin-panel.js ──▶ buildPanelHTML │ │ │
│ │ │ /admin/home ─▶ admin-home.js ──▶ buildHomeHTML │ │ │
│ │ │ /admin/providers ▶ admin-providers ▶ buildProvidersHTML │ │ │
│ │ │ /dashboard ──▶ dashboard.js ──▶ buildDashHTML │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌─────────────┼─────────────┐ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌──────────────┐ ┌──────────┐ ┌──────────────┐ │ │
│ │ │ cache.js │ │ services │ │ export/ │ │ │
│ │ │ (SWR cache) │ │ churn │ │ excel-export│ │ │
│ │ │ │ │ forecast │ │ │ │ │
│ │ └──────┬───────┘ └──────────┘ └──────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ src/queries/ │ │ │
│ │ │ bi.queries │ client.queries │ corporate.q │ │ │
│ │ │ payin.q │ payout.q │ provider.q │ │ │
│ │ │ compliance.q│ helpers.js │ │ │
│ │ └──────────────────────┬───────────────────────┘ │ │
│ │ │ │ │
│ └─────────────────────────┼────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────┼───────────────────────────────────────┐ │
│ │ Netbird VPN daemon │ │ │
│ └─────────────────────────┼───────────────────────────────────────┘ │
└────────────────────────────┼──────────────────────────────────────────┘
┌─────────────┴─────────────┐
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ SQLite │ │ AWS RDS │
│ (agentes.db) │ │ (cambio_db) │
│ LOCAL / R+W │ │ REMOTE / R.O. │
│ │ │ via Netbird VPN │
│ agentes (auth) │ │ │
└───────────────────┘ │ br_transaction │
│ pagamento_br │
│ conta │
│ ag_contas │
│ br_payment_methods│
│ br_cb_empresas │
│ br_cb_cobranca │
└───────────────────┘
```
## Componentes
### 1. Camada de Apresentacao
### 1. Camada de Apresentação
**Tecnologias:** HTML5, CSS3, Vanilla JavaScript, Chart.js
**Padrão:** Server-Side Rendering — cada página é um módulo em `src/` que exporta `buildXxxHTML(user)` retornando uma string HTML completa com CSS e JS inline.
| Arquivo | Responsabilidade |
|---------|------------------|
| `public/login.html` | Formulario de login estilizado |
| `src/dashboard.js` | Geracao dinamica do HTML do dashboard |
| Módulo | Página | Linhas |
|--------|--------|--------|
| `admin-bi.js` | BI Executive | ~2250 |
| `admin-cliente.js` | Client 360 | ~1400 |
| `admin-dashboard.js` | Corporate Dashboard | ~750 |
| `admin-home.js` | Daily Overview | ~510 |
| `admin-panel.js` | Gestão de Usuários | ~620 |
| `admin-providers.js` | Payment Providers | ~1070 |
| `dashboard.js` | Dashboard do Agente | ~1585 |
| `ui-template.js` | Header, footer, CSS, tema | ~600 |
**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
**Fluxo:**
1. Express recebe request → verifica auth/role
2. Chama `buildXxxHTML(user)` → retorna HTML string
3. Frontend faz `fetch()` para APIs de dados
4. JavaScript inline renderiza Chart.js e popula o DOM
### 2. Camada de Aplicacao
### 2. Sistema de Temas
**Tecnologias:** Node.js, Express.js
- **Dark Mode:** Estilo Bloomberg terminal — verde #00FF88, fontes monospace (SF Mono/Fira Code)
- **Light Mode:** Cores institucionais CambioReal — roxo #7600be, verde #2E7D32
- **Toggle:** Atributo `data-theme` no HTML, persistido no localStorage
- **Charts:** `getChartTheme()` retorna cores adaptadas ao tema ativo
- **CSS:** Variáveis CSS com breakpoints em 1200px, 900px, 768px, 480px
| Modulo | Responsabilidade |
### 3. Cache Layer
**Módulo:** `src/cache.js` — Cache em memória com padrão stale-while-revalidate.
| Dado | TTL | Auto-refresh |
|------|-----|-------------|
| KPIs | 5 min | Sim |
| Tendência 30d | 10 min | Sim |
| Top agentes | 10 min | Sim |
| Top clientes | 15 min | Não |
Dados "stale" são retornados imediatamente enquanto o refresh acontece em background.
### 4. Queries Modulares
**Diretório:** `src/queries/` — Queries SQL separadas por domínio.
| Módulo | Responsabilidade |
|--------|------------------|
| `server.js` | Entry point, rotas, middleware |
| `src/auth.js` | Autenticacao, bcrypt, sessoes |
| `src/queries.js` | Queries SQL, serializacao de dados |
| `bi.queries.js` | KPIs executivos, revenue analytics, cohort, strategic |
| `client.queries.js` | Profile, health score, churn risk, timeline |
| `corporate.queries.js` | KPIs corporate, tendências, top agentes |
| `payin.queries.js` | Transações BRL→USD |
| `payout.queries.js` | Pagamentos USD→BRL |
| `provider.queries.js` | Análise de provedores de pagamento |
| `compliance.queries.js` | Queries de compliance |
| `helpers.js` | Utilitários de query (formatação, cálculos) |
**Middleware Stack:**
```
Request
│
▼
express.urlencoded() ← Parse form data
│
▼
express.json() ← Parse JSON
│
▼
express-session() ← Gerenciar sessao
│
▼
requireAuth() ← Verificar autenticacao (rotas protegidas)
│
▼
Route Handler
```
### 5. Serviços
### 3. Camada de Dados
| Módulo | Responsabilidade |
|--------|------------------|
| `services/churn-predictor.js` | Predição de churn baseada em recência, frequência, volume |
| `services/forecast.js` | Previsão de receita com tendência histórica |
#### SQLite (Local)
### 6. ETL & Data Quality
**Biblioteca:** better-sqlite3 (sincrono, WAL mode)
| Módulo | Responsabilidade |
|--------|------------------|
| `etl/daily-sync.js` | Sincronização diária de dados agregados |
| `etl/data-quality.js` | Validação e checagem de qualidade dos dados |
### 7. Alertas
| Módulo | Responsabilidade |
|--------|------------------|
| `alerts/alert-engine.js` | Motor de regras para disparar alertas |
| `alerts/channels.js` | Canais de notificação (email via nodemailer) |
### 8. Export
| Módulo | Responsabilidade |
|--------|------------------|
| `export/excel-export.js` | Exportação de dados para Excel (ExcelJS) |
## Banco de Dados
### MySQL RDS (`cambio_db`) — Transações
| Tabela | Descrição |
|--------|-----------|
| `br_transaction_to_usa` | Transações BRL→USD (amount_brl, amount_usd, exchange_rate, ptax, iof, status, cobranca_id) |
| `pagamento_br` | Pagamentos USD→BRL (valor, cotacao, ptax, valor_sol, tipo_envio, pgto, fee) |
| `conta` | Contas/clientes (id_conta, nome) |
| `ag_contas` | Mapeamento agente→conta (agente_id, conta_id) |
| `br_payment_methods` | Provedores de pagamento (id, provider) |
| `br_cb_empresas` | Merchants CambioCheckout (id, id_conta, nome_empresa, active) |
| `br_cb_cobranca` | Cobranças/links de pagamento (id, empresa_id) |
**Relação Merchant/Checkout:** `br_cb_empresas.id_conta` identifica o merchant. `br_cb_cobranca.empresa_id` liga ao merchant. `br_transaction_to_usa.cobranca_id` liga a transação à cobrança. O `id_conta` na transação é o **pagador** (cliente BR), não o merchant.
### SQLite Local (`data/agentes.db`) — Auth
```sql
CREATE TABLE agentes (
id INTEGER PRIMARY KEY AUTOINCREMENT,
email TEXT UNIQUE NOT NULL,
senha_hash TEXT NOT NULL,
agente_id INTEGER NOT NULL,
agente_id INTEGER,
nome TEXT NOT NULL,
role TEXT DEFAULT 'agente',
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
## Cálculo de Receita
#### MySQL (RDS)
**BRL→USD (CambioPay/CambioCheckout):**
```
receita = (amount_brl - fee_ajustado) / ptax - pfee - (amount_usd + bonus - taxa_cr)
```
Onde `fee_ajustado` depende do provider (ouribank/bs2 não descontam fee).
**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
}
**USD→BRL:**
```
receita = ((ptax - cotacao) * valor) / ptax + fee
```
**Tabelas Consultadas:**
**Balance:** apenas `fee`.
| 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 |
## Segurança
## 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 |
| Aspecto | Implementação |
|---------|---------------|
| 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 |
|---------|---------------|
| Sessão | express-session, in-memory, 8h timeout |
| SQL Injection | Queries parametrizadas (?) |
| Isolamento | WHERE agente_id = ? em todas queries |
| RDS Access | Usuario read-only (sem INSERT/UPDATE/DELETE) |
| Isolamento | WHERE agente_id = ? em todas queries de agente |
| RDS Access | Usuário read-only (sem INSERT/UPDATE/DELETE) |
| VPN | Netbird — acesso ao RDS somente via rede privada |
### Recomendacoes para Producao
## Deploy
- [ ] 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
**Docker Compose** com Netbird VPN integrado:
## Performance
1. `docker-entrypoint.sh` inicia Netbird VPN daemon
2. Aguarda conexão VPN (~10s)
3. Inicia `node server.js` na porta 3080
### 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)
```bash
docker compose build bi-ccc && docker compose down bi-ccc && docker compose up -d bi-ccc
```
## Dependencias
## Decisões de Arquitetura
| 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 |
| Decisão | 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 |
| SSR com HTML inline | Sem build step, deploy simples |
| SQLite para auth | Independência do RDS, portabilidade |
| MySQL pool async | 10 conexões reutilizáveis para RDS |
| Cache SWR | Resposta rápida sem stale data prolongado |
| Queries modulares | Separação por domínio, manutenibilidade |
| Chart.js inline | Sem CDN, funciona offline via VPN |
| Netbird VPN | Acesso seguro ao RDS sem expor porta pública |

1604
docs/BI-CCC-Implementation-Guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

343
docs/GUIA-USUARIO.md
View File

@@ -1,18 +1,19 @@
# Guia do Usuario - BI Agentes
# Guia do Usuário — BI-CCC
Manual de uso do dashboard de transacoes para agentes CambioReal.
Manual de uso do sistema BI-CCC (Central Command Center) da CambioReal.
---
## Indice
## Índice
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)
2. [Dashboard do Agente](#dashboard-do-agente)
3. [Corporate Dashboard](#corporate-dashboard)
4. [BI Executive](#bi-executive)
5. [Client 360](#client-360)
6. [Gestão de Usuários](#gestao-de-usuarios)
7. [Tema Dark/Light](#tema-darklight)
8. [Perguntas Frequentes](#perguntas-frequentes)
---
@@ -20,253 +21,215 @@ Manual de uso do dashboard de transacoes para agentes CambioReal.
### 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
1. Abra o navegador e acesse o endereço fornecido pelo administrador
2. Digite seu **e-mail** e **senha**
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.
Após o login, você será direcionado automaticamente:
- **Admin** → Corporate Dashboard
- **Corporate** → Corporate Dashboard
- **Agente** → Dashboard pessoal
### Logout
Para sair do sistema, clique no botao **Sair** no canto superior direito do dashboard.
Clique no botão **Sair** no canto superior direito. A sessão expira automaticamente após 8 horas.
---
### Navegação
## Visao Geral do Dashboard
Apos o login, voce vera o dashboard com suas transacoes:
Admins acessam todas as páginas via navegação lateral (console nav) no lado direito da tela:
```
┌────────────────────────────────────────────────────────────────────┐
│ [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 │
│ └─────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────┬───┐
│ │ H │ H = Home
│ Conteúdo da página │ C │ C = Corporate
│ │ B │ B = BI Executive
│ │ 3 │ 3 = Client 360
│ │ P │ P = Providers
│ │ U │ U = Usuários
└──────────────────────────────────────────┴───┘
```
**Importante:** Voce ve apenas suas proprias transacoes. Outros agentes nao tem acesso aos seus dados.
---
## Dashboard do Agente
**Rota:** `/dashboard`
**Role:** `agente`
Dashboard pessoal do agente mostrando apenas suas próprias transações.
### KPIs Exibidos
| KPI | Descrição |
|-----|-----------|
| Transações | Quantidade total no período |
| Volume BRL | Soma em reais |
| Volume USD | Soma em dólares |
| Taxa Média | Média ponderada da taxa cobrada |
| Spread Médio | % médio sobre PTAX |
| IOF Total | Soma do IOF cobrado |
| Ticket Médio | USD médio por transação |
| Clientes Ativos | Clientes únicos no período |
### Gráficos
- **Volume por Período** — Barras duplas BRL/USD
- **Top 10 Clientes** — Barras horizontais por volume
- **Taxa vs PTAX** — Linha comparando taxa cobrada com PTAX oficial
### Filtros
| Filtro | Opções |
|--------|--------|
| Período | Data início / Data fim |
| Granulação | Dia, Mês, Ano |
| Fluxo | BRL→USD, USD→BRL, Todos |
| Cliente | Todos ou cliente específico |
---
## Usando os Filtros
## Corporate Dashboard
Os filtros ficam na barra abaixo do cabecalho. Use-os para refinar a visualizacao:
**Rota:** `/corporate`
**Role:** `admin`, `corporate`
### Periodo (De / Ate)
Visão executiva com KPIs consolidados dos três fluxos de câmbio.
Selecione a data inicial e final para ver transacoes em um periodo especifico.
### Funcionalidades
**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.
- KPIs do período selecionado: volume, transações, ticket médio
- Comparativo com média 30 dias
- Gráficos de tendência
- Três fluxos separados: BRL→USD, USD→BRL, Balance
- Preset "Hoje" para visão rápida do dia
- Top 5 agentes por volume (7d, 30d, 90d)
---
## Entendendo os KPIs
## BI Executive
Os KPIs (Indicadores-Chave) mostram um resumo do periodo selecionado:
**Rota:** `/admin/bi`
**Role:** `admin`
### Transacoes
Quantidade total de operacoes realizadas.
Dashboard analítico completo para decisões estratégicas.
### Volume BRL
Soma de todos os valores em reais movimentados.
### Seções
**Exemplo:** Se teve 3 transacoes de R$ 10.000, R$ 20.000 e R$ 15.000, o volume e R$ 45.000.
| Seção | Descrição |
|-------|-----------|
| KPIs comparativos | Período atual vs anterior com variação % |
| Revenue Analytics | Receita por produto (CambioPay, CambioCheckout, Balance) com granularidade |
| Ranking de Agentes | Top agentes por volume e spread revenue |
| Top 10 Clientes | Maiores clientes por volume USD |
| Retenção | Clientes ativos, novos, inativos, em risco |
| BI Estratégico | Cohort retention, revenue expansion/contraction, cross-sell, maturidade |
### Volume USD
Soma de todos os valores em dolares movimentados.
### Filtros
### 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.
- Período customizado (data início / data fim)
- Granularidade: dia, mês, ano
---
## Interpretando os Graficos
## Client 360
### Volume BRL / USD por Periodo
**Rota:** `/admin/cliente`
**Role:** `admin`
Grafico de barras mostrando a evolucao do volume ao longo do tempo.
Visão completa e detalhada de cada cliente individual.
- **Barras verdes** = Volume em BRL (eixo esquerdo)
- **Barras azuis** = Volume em USD (eixo direito)
### Busca de Clientes
**Como ler:**
- Barras mais altas = mais volume naquele periodo
- Compare meses para identificar sazonalidade
- Busca por nome (server-side)
- Lista os top 20 clientes por volume ao abrir a página
- Clique no card do cliente para ver detalhes
### Volume por Cliente (Top 10)
### Profile do Cliente
Grafico horizontal mostrando os 10 maiores clientes por volume USD.
| Seção | Descrição |
|-------|-----------|
| Profile Card | Nome, lifetime stats, badge merchant (se aplicável) |
| 6 KPI Cards | Volume, transações, receita, ticket médio, ARPA, spread |
| Health Score | Score 0-100 baseado em volume + frequência + recência + crescimento |
| Churn Risk | Classificação: baixo / médio / alto / crítico com indicadores |
| Netting | Posição líquida BRL→USD vs USD→BRL |
| Revenue Intelligence | Receita mensal + MoM growth |
| Timeline | Volume + quantidade diária com granularidade D/W/M |
| Análise de Fluxo | Donut BRL↔USD + tendência de spread |
| Tabela de Transações | Ordenável, paginada, exportável CSV |
| Insights | Dia da semana preferido, ticket médio, providers usados |
**Como usar:**
- Identifique seus clientes mais importantes
- Foque atencao nos maiores volumes
### Merchant Detection
### 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
Clientes que são merchants CambioCheckout exibem badge roxo e seção dedicada:
- Volume checkout, payers, receita, operações
- Chart mensal volume + payers
- Top 10 pagadores clicáveis
---
## Tabela de Transacoes
## Gestão de Usuários
A tabela mostra todas as transacoes individuais do periodo.
**Rota:** `/admin`
**Role:** `admin`
### Colunas
Administração de usuários do sistema.
| 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 |
### Funcionalidades
### Organizacao
- Criar novo usuário (admin, corporate, agente)
- Editar dados do usuário
- Ativar/desativar usuários
- Reset de senha
- Vincular `agente_id` (para role agente)
As transacoes sao separadas por fluxo:
- **BRL → USD** (fundo roxo claro) - Envios
- **USD → BRL** (fundo azul claro) - Recebimentos
---
### Navegando
## Tema Dark/Light
- Use a barra de rolagem horizontal para ver todas as colunas
- A tabela ordena por data (mais antigas primeiro)
O sistema possui dois temas visuais:
| Tema | Estilo | Cores |
|------|--------|-------|
| **Dark** | Bloomberg terminal, monospace | Verde #00FF88, fundo escuro |
| **Light** | Institucional CambioReal | Roxo #7600be, verde #2E7D32 |
**Para alternar:** Clique no ícone de tema no header. A preferência é salva no navegador.
---
## Perguntas Frequentes
### Posso ver transacoes de outros agentes?
### Posso ver dados de outros agentes?
**Agentes** veem apenas seus próprios dados. **Admins** veem dados consolidados de todos.
**Nao.** Cada agente ve apenas suas proprias transacoes. O sistema garante isolamento total dos dados.
### Os dados são em tempo real?
Os dados são buscados do banco a cada requisição, com cache de 5-15 minutos para performance.
### Os dados sao atualizados em tempo real?
### Como exportar dados?
Na tabela de transações (Client 360 e Dashboard do Agente), use o botão de exportação para baixar em CSV ou Excel.
**Sim.** A cada vez que voce carrega o dashboard ou aplica filtros, os dados sao buscados diretamente do sistema.
### A sessão expira?
Sim, após 8 horas de inatividade.
### O que fazer se os graficos nao aparecerem?
### Funciona no celular?
Sim, o layout é responsivo, mas a experiência é melhor em telas maiores.
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
### O que é PTAX?
Taxa de câmbio oficial divulgada pelo Banco Central do Brasil, usada como referência para calcular o spread.
### 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.
### O que é Health Score?
Score de 0 a 100 que avalia a "saúde" do cliente baseado em volume de transações, frequência, recência da última operação e crescimento.
---
## Suporte
Em caso de problemas:
1. Verifique usuario e senha
2. Tente recarregar a pagina
1. Verifique usuário e senha
2. Recarregue a página (F5)
3. Contate o administrador do sistema
---
*CambioReal - BI Agentes v1.0*
*CambioReal — BI-CCC*

19
docs/INDEX.md Normal file
View File

@@ -0,0 +1,19 @@
# Documentação — BI-CCC
Índice de toda a documentação do projeto BI-CCC (Central Command Center).
## Documentos
| Documento | Descrição |
|-----------|-----------|
| [API Reference](API.md) | Endpoints HTTP, autenticação, exemplos de uso |
| [Arquitetura Técnica](ARCHITECTURE.md) | Componentes, fluxo de dados, decisões de arquitetura |
| [Guia do Usuário](GUIA-USUARIO.md) | Manual de uso para admin, corporate e agente |
| [Guia de Implementação](BI-CCC-Implementation-Guide.md) | Guia completo de implementação e evolução do BI-CCC |
## Documentos na Raiz
| Documento | Descrição |
|-----------|-----------|
| [README.md](../README.md) | Visão geral do projeto, setup, deploy |
| [PROJETO.md](../PROJETO.md) | Documentação técnica detalhada (referência completa) |