841 lines
49 KiB
Markdown
841 lines
49 KiB
Markdown
# Arcádia BI — Mapa de Business Intelligence
|
||
|
||
> Mapa completo da arquitetura de BI, incluindo Motor Python, Metabase,
|
||
> Cientista (IA), ETL/Staging, APIs e Frontend.
|
||
> Atualizado em: Março 2026
|
||
|
||
---
|
||
|
||
## 1. Visão Geral
|
||
|
||
O BI da Arcádia Suite opera em **4 camadas complementares** que se combinam para oferecer analytics completo: desde queries SQL diretas até dashboards visuais no Metabase, passando por análise com IA e ingestão de dados externos.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ USUÁRIO / FRONTEND │
|
||
│ │
|
||
│ BiWorkspace.tsx (2.970 linhas) Metabase (Embeddado) │
|
||
│ React + Recharts + Tailwind Proxy → :8088 │
|
||
│ 8 abas funcionais Dashboards avançados │
|
||
│ │
|
||
│ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │
|
||
│ │ Overview │DataSrc │ Upload │ Datasets │ Charts │ │
|
||
│ ├──────────┼──────────┼──────────┼──────────┼──────────┤ │
|
||
│ │ Backups │ Staging │ Advanced │ │ │ │
|
||
│ └──────────┴──────────┴──────────┴──────────┴──────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ 🤖 Assistente BI (IA) │ │
|
||
│ │ Chat com GPT-4o sobre dados │ │
|
||
│ │ Prompts rápidos + análise livre │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
└─────────────────────────┬────────────────────────────────────────────┘
|
||
│
|
||
┌───────────────┼───────────────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
|
||
│ API BI (Node) │ │BI Engine (Python)│ │ Metabase (Java) │
|
||
│ /api/bi/* │ │ /api/bi-engine/* │ │ /metabase/* │
|
||
│ │ │ │ │ │
|
||
│ CRUD: │ │ SQL Execution │ │ Dashboards │
|
||
│ - DataSources │ │ Chart Data Gen │ │ Perguntas/Queries │
|
||
│ - Datasets │ │ Micro-BI │ │ Alertas │
|
||
│ - Charts │ │ Análise Pandas │ │ Visualizações │
|
||
│ - Dashboards │ │ Cache (TTL 5min) │ │ Coleções │
|
||
│ - Backups │ │ Agregações │ │ Embedding │
|
||
│ - Upload/ETL │ │ Insights Auto │ │ │
|
||
│ - Staging │ │ │ │ │
|
||
│ - AI Analysis │ │ │ │ │
|
||
└────────┬────────┘ └────────┬─────────┘ └──────────┬──────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ PostgreSQL (Porta 5432) │
|
||
│ │
|
||
│ Tabelas de gestão BI: data_sources, bi_datasets, bi_charts, │
|
||
│ bi_dashboards, bi_dashboard_charts, backup_jobs, backup_artifacts, │
|
||
│ staged_tables, staging_mappings, migration_jobs │
|
||
│ │
|
||
│ Tabelas de negócio: persons, products, sales_orders, fin_*, │
|
||
│ crm_*, whatsapp_messages, valuation_*, etc. │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Os 4 Pilares do BI
|
||
|
||
### Pilar 1 — Motor BI Python (FastAPI :8004)
|
||
|
||
O coração analítico. Processa SQL, gera dados para gráficos e fornece Micro-BI.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ BI ENGINE (Python 3.11) │
|
||
│ FastAPI + Pandas + NumPy │
|
||
│ Porta: 8004 │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ SEGURANÇA SQL │ │
|
||
│ │ │ │
|
||
│ │ ✓ Somente SELECT/WITH permitidos │ │
|
||
│ │ ✓ 17 keywords bloqueadas (DROP, DELETE, INSERT...) │ │
|
||
│ │ ✓ 7 padrões perigosos filtrados (pg_sleep, --, /*) │ │
|
||
│ │ ✓ Multi-statement bloqueado (múltiplos ;) │ │
|
||
│ │ ✓ Conexão read-only (autocommit) │ │
|
||
│ │ ✓ Timeout: 30 segundos por query │ │
|
||
│ │ ✓ Limite: 10.000 linhas por resultado │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ CACHE (QueryCache) │ │
|
||
│ │ │ │
|
||
│ │ • Tipo: In-memory (OrderedDict) │ │
|
||
│ │ • Max entries: 200 │ │
|
||
│ │ • TTL: 300 segundos (5 minutos) │ │
|
||
│ │ • Key: SHA-256 de (SQL + params) │ │
|
||
│ │ • Métricas: hits, misses, hit_rate (%) │ │
|
||
│ │ • Invalidação: por padrão ou total │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ CAPABILITIES │ │
|
||
│ │ │ │
|
||
│ │ • sql_query → Execução de SELECT arbitrário │ │
|
||
│ │ • chart_data → Geração de dados para gráficos │ │
|
||
│ │ • micro_bi → Métricas rápidas com comparação │ │
|
||
│ │ • analysis → Análise estatística com Pandas │ │
|
||
│ │ • aggregation → Agregações customizadas │ │
|
||
│ │ • cache → Cache inteligente de queries │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Pilar 2 — Metabase (Java :8088)
|
||
|
||
Plataforma visual de BI, acessível via proxy reverso.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ METABASE │
|
||
│ Porta: 8088 (via proxy /metabase) │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ PROXY (http-proxy-middleware) │ │
|
||
│ │ │ │
|
||
│ │ Gateway (:5000) → /metabase/* → Metabase (:8088) │ │
|
||
│ │ │ │
|
||
│ │ • pathRewrite: /metabase → / │ │
|
||
│ │ • changeOrigin: true │ │
|
||
│ │ • timeout: 60 segundos │ │
|
||
│ │ • Reescrita de Location headers │ │
|
||
│ │ • Fallback: 502 "Metabase indisponível" │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ FUNCIONALIDADES │ │
|
||
│ │ │ │
|
||
│ │ • Dashboards visuais (drag & drop) │ │
|
||
│ │ • Perguntas SQL / visual query builder │ │
|
||
│ │ • Alertas automáticos │ │
|
||
│ │ • Coleções organizadas │ │
|
||
│ │ • Embedding de dashboards │ │
|
||
│ │ • Filtros interativos │ │
|
||
│ │ • Exportação (CSV, Excel, PDF) │ │
|
||
│ │ • Agendamento de relatórios │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ CONEXÃO │ │
|
||
│ │ │ │
|
||
│ │ Banco: PostgreSQL (mesmo DATABASE_URL do Gateway) │ │
|
||
│ │ Acesso: Todas as tabelas public (read-only) │ │
|
||
│ │ Config: METABASE_HOST, METABASE_PORT │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Pilar 3 — API BI Node.js (Gateway :5000)
|
||
|
||
Camada de gestão e CRUD para objetos de BI.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ API BI (Node.js/Express) │
|
||
│ Registrada no Gateway (:5000) │
|
||
│ │
|
||
│ ┌── Gestão de Objetos BI ──────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ Data Sources → Conexões com bancos externos │ │
|
||
│ │ Datasets → Conjuntos de dados (table/SQL/API) │ │
|
||
│ │ Charts → Gráficos salvos (config + dados) │ │
|
||
│ │ Dashboards → Painéis com layout de charts │ │
|
||
│ │ Backup Jobs → Jobs de backup programados │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── ETL & Ingestão ────────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ Upload → Importação de arquivos │ │
|
||
│ │ Staging → Área de preparação para migração │ │
|
||
│ │ Migration → Jobs de migração de dados │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tabelas Internas ──────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ Exploração de schema do PostgreSQL │ │
|
||
│ │ Criação de datasets a partir de tabelas internas │ │
|
||
│ │ Categorização automática (Sistema, CRM, BI, etc.) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Análise com IA ────────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ OpenAI GPT-4o → Responde perguntas sobre dados │ │
|
||
│ │ Prompts pré-definidos (Resumo, Anomalias, etc.) │ │
|
||
│ │ Formato JSON estruturado (answer + insights) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Pilar 4 — Cientista (Python: Auto-Programação)
|
||
|
||
Módulo de IA para análise avançada e geração de código.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ CIENTISTA (Python) │
|
||
│ python-service/services/cientista.py │
|
||
│ │
|
||
│ ┌── Análise Estatística ───────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ analyze_data() │ │
|
||
│ │ → Shape (rows × columns) │ │
|
||
│ │ → Tipos de dados por coluna │ │
|
||
│ │ → Valores ausentes │ │
|
||
│ │ → Estatísticas (describe): mean, std, min, max │ │
|
||
│ │ → Amostra dos dados (5 primeiros registros) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Detecção de Padrões ──────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ detect_patterns() │ │
|
||
│ │ → Correlações fortes (> 0.7) entre colunas │ │
|
||
│ │ → Tendências (crescente/decrescente) via polyfit │ │
|
||
│ │ → Saída: [{ type, columns, value, description }] │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Insights Automáticos ─────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ generate_insights() │ │
|
||
│ │ → Valores ausentes por coluna (% de missing) │ │
|
||
│ │ → Detecção de outliers (IQR × 1.5) │ │
|
||
│ │ → Valores dominantes (> 50% em categóricas) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Auto-Programação (ScientistModule) ────────────────┐ │
|
||
│ │ │ │
|
||
│ │ generate_analysis_code(description, goal) │ │
|
||
│ │ → Templates: aggregate, filter, predict, correlate │ │
|
||
│ │ → Gera código Python executável │ │
|
||
│ │ → Salva padrões aprendidos │ │
|
||
│ │ → Histórico de execuções │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. API REST Completa
|
||
|
||
### 3.1 — BI Engine Proxy (/api/bi-engine/*)
|
||
|
||
Proxy do Gateway para o Motor Python FastAPI (:8004):
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/bi-engine/health` | Status do motor (online/offline, banco, cache) |
|
||
| GET | `/api/bi-engine/version` | Versão e capabilities |
|
||
| GET | `/api/bi-engine/metrics` | Métricas (cache stats, limites) |
|
||
| GET | `/api/bi-engine/tables` | Lista todas as tabelas do PostgreSQL |
|
||
| GET | `/api/bi-engine/tables/:name/columns` | Schema de colunas de uma tabela |
|
||
| GET | `/api/bi-engine/tables/:name/preview` | Preview dos dados (limit padrão: 50) |
|
||
| GET | `/api/bi-engine/tables/:name/stats` | Estatísticas (row_count, column_count) |
|
||
| POST | `/api/bi-engine/query` | Executa SQL (somente SELECT/WITH) |
|
||
| POST | `/api/bi-engine/chart-data` | Gera dados formatados para gráficos |
|
||
| POST | `/api/bi-engine/micro-bi` | Micro-BI: métricas rápidas com comparação temporal |
|
||
| POST | `/api/bi-engine/analyze` | Análise de dados com Pandas |
|
||
| POST | `/api/bi-engine/aggregate` | Agregações customizadas |
|
||
| GET | `/api/bi-engine/cache/stats` | Estatísticas do cache |
|
||
| POST | `/api/bi-engine/cache/invalidate` | Invalida cache (por padrão ou total) |
|
||
|
||
### 3.2 — BI Management (/api/bi/*)
|
||
|
||
CRUD de objetos BI no Gateway Node.js:
|
||
|
||
#### Data Sources
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/bi/data-sources` | Lista fontes de dados do usuário |
|
||
| POST | `/api/bi/data-sources` | Cria fonte (PostgreSQL, MySQL, MongoDB, SQLite, Internal) |
|
||
| POST | `/api/bi/data-sources/:id/test` | Testa conexão |
|
||
| DELETE | `/api/bi/data-sources/:id` | Remove fonte |
|
||
|
||
#### Datasets
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/bi/datasets` | Lista datasets do usuário |
|
||
| POST | `/api/bi/datasets` | Cria dataset (table, SQL ou API) |
|
||
| POST | `/api/bi/datasets/:id/execute` | Executa dataset e retorna dados |
|
||
| DELETE | `/api/bi/datasets/:id` | Remove dataset |
|
||
|
||
#### Charts
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/bi/charts` | Lista gráficos do usuário |
|
||
| POST | `/api/bi/charts` | Cria gráfico (bar, line, pie, area, scatter, table, metric, donut) |
|
||
| DELETE | `/api/bi/charts/:id` | Remove gráfico |
|
||
|
||
#### Dashboards
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/bi/dashboards` | Lista dashboards do usuário |
|
||
| GET | `/api/bi/dashboards/:id` | Detalhe do dashboard + charts posicionados |
|
||
| POST | `/api/bi/dashboards` | Cria dashboard |
|
||
| POST | `/api/bi/dashboards/:id/charts` | Adiciona chart ao dashboard (com posição X/Y/W/H) |
|
||
| DELETE | `/api/bi/dashboards/:id` | Remove dashboard |
|
||
|
||
#### Tabelas Internas
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/bi/internal-tables` | Lista tabelas do sistema (com tamanho e categoria) |
|
||
| GET | `/api/bi/internal-tables/:name/schema` | Schema + preview + row count |
|
||
| POST | `/api/bi/internal-tables/:name/create-dataset` | Cria dataset a partir de tabela interna |
|
||
| POST | `/api/bi/query` | Query direta em tabela (simples, limite 1000) |
|
||
|
||
#### Backups
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/bi/backup-jobs` | Lista jobs de backup |
|
||
| POST | `/api/bi/backup-jobs` | Cria job (full, schema, data, incremental) |
|
||
| POST | `/api/bi/backup-jobs/:id/run` | Executa backup |
|
||
| DELETE | `/api/bi/backup-jobs/:id` | Remove job |
|
||
| GET | `/api/bi/backup-artifacts` | Lista artefatos gerados |
|
||
|
||
### 3.3 — Upload & ETL (/api/upload/*, /api/staging/*)
|
||
|
||
#### Upload de Dados
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| POST | `/api/upload/file` | Upload de arquivo (CSV, JSON, Excel, SQL, BSON, ZIP) |
|
||
| POST | `/api/upload/analyze` | Analisa arquivo e sugere schema |
|
||
|
||
Formatos suportados (até 200MB):
|
||
- `.csv`, `.txt` → Parser CSV inteligente (suporta aspas)
|
||
- `.json` → Parse direto de arrays/objetos
|
||
- `.xlsx`, `.xls` → Leitura via SheetJS (XLSX)
|
||
- `.sql` → Detecção de INSERTs e criação de datasets
|
||
- `.bson` → Parse via biblioteca BSON
|
||
- `.zip` → Extração e processamento de conteúdo
|
||
|
||
#### Staging (Área de Preparação)
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/staging/tables` | Lista tabelas staged |
|
||
| GET | `/api/staging/tables/:id` | Detalhe de tabela staged |
|
||
| GET | `/api/staging/tables/:id/data` | Dados da tabela staged |
|
||
| POST | `/api/staging/tables/:id/mappings` | Cria mapeamento de colunas |
|
||
| GET | `/api/staging/tables/:id/mappings` | Lista mapeamentos |
|
||
| POST | `/api/staging/tables/:id/migrate` | Executa migração para tabela destino |
|
||
| DELETE | `/api/staging/tables/:id` | Remove tabela staged |
|
||
|
||
### 3.4 — Metabase Proxy (/metabase/*)
|
||
|
||
| Rota | Destino | Função |
|
||
|------|---------|--------|
|
||
| `/metabase/*` | `http://localhost:8088/*` | Proxy reverso completo para Metabase |
|
||
|
||
---
|
||
|
||
## 4. Banco de Dados — Tabelas do BI
|
||
|
||
### Objetos BI
|
||
|
||
```
|
||
┌─────────────────────────────┐ ┌──────────────────────────────┐
|
||
│ data_sources │ │ bi_datasets │
|
||
│ │ │ │
|
||
│ id, userId, name, │ │ id, userId, name, description,│
|
||
│ type (postgresql|mysql| │ │ dataSourceId, queryType │
|
||
│ mongodb|sqlite|internal), │ │ (table|sql|api), tableName, │
|
||
│ host, port, database, │ │ sqlQuery, columns, filters, │
|
||
│ username, password, │ │ isPublic, createdAt, updatedAt│
|
||
│ connectionString, isActive, │ │ │
|
||
│ lastTestedAt, createdAt │ └───────────────┬───────────────┘
|
||
└──────────────────────────────┘ │ 1:N
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ bi_charts │
|
||
│ │
|
||
│ id, userId, name, datasetId, chartType (bar|line|pie|area| │
|
||
│ scatter|table|metric|donut), config (JSON), xAxis, yAxis, │
|
||
│ groupBy, aggregation, colors, createdAt, updatedAt │
|
||
└──────────────────────────┬──────────────────────────────────────┘
|
||
│ N:M (via bi_dashboard_charts)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ bi_dashboards bi_dashboard_charts │
|
||
│ │
|
||
│ id, userId, name, id, dashboardId, │
|
||
│ description, layout (JSON), chartId, │
|
||
│ isPublic, createdAt, updatedAt positionX, positionY, │
|
||
│ width, height │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Backups
|
||
|
||
```
|
||
┌───────────────────────────────┐ ┌───────────────────────────────┐
|
||
│ backup_jobs │ │ backup_artifacts │
|
||
│ │ │ │
|
||
│ id, userId, name, │ │ id, backupJobId, filename, │
|
||
│ dataSourceId, backupType │ │ filePath, fileSize, status │
|
||
│ (full|schema|data|incremental),│ │ (running|completed|failed), │
|
||
│ includeSchema, includeTables, │ │ startedAt, completedAt, │
|
||
│ excludeTables, compressionType,│ │ errorMessage │
|
||
│ retentionDays, storageLocation,│ │ │
|
||
│ lastRunAt, isActive, createdAt │ │ │
|
||
└───────────────────────────────┘ └───────────────────────────────┘
|
||
```
|
||
|
||
### Staging & Migração
|
||
|
||
```
|
||
┌───────────────────────────────┐ ┌───────────────────────────────┐
|
||
│ staged_tables │ │ staging_mappings │
|
||
│ │ │ │
|
||
│ id, userId, name, │ │ id, stagedTableId, │
|
||
│ originalFilename, fileType, │ │ sourceColumn, targetTable, │
|
||
│ rowCount, columnCount, │ │ targetColumn, transformType, │
|
||
│ columns (JSON), sampleData, │ │ transformConfig, createdAt │
|
||
│ status, createdAt, updatedAt │ │ │
|
||
└───────────────────────────────┘ └───────────────────────────────┘
|
||
|
||
┌───────────────────────────────────────────────────────────────────┐
|
||
│ migration_jobs │
|
||
│ │
|
||
│ id, userId, name, stagedTableId, targetTable, status, │
|
||
│ (pending|running|completed|failed), totalRows, processedRows, │
|
||
│ errorLog, mappingConfig (JSON), createdAt, updatedAt │
|
||
└───────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Frontend — BiWorkspace.tsx (2.970 linhas)
|
||
|
||
### Tabs
|
||
|
||
| Tab | Valor | Descrição |
|
||
|-----|-------|-----------|
|
||
| **Overview** | `overview` | KPIs resumo: DataSources, Datasets, Charts, Dashboards, Backups |
|
||
| **Data Sources** | `datasources` | CRUD de fontes externas (PostgreSQL, MySQL, MongoDB, SQLite) + tabelas internas do sistema |
|
||
| **Upload** | `upload` | Importação de arquivos (CSV, Excel, JSON, SQL, BSON, ZIP) com preview automático |
|
||
| **Datasets** | `datasets` | Conjuntos de dados criados a partir de tabelas ou SQL, com execução e preview |
|
||
| **Charts** | `charts` | Criação de gráficos (8 tipos) a partir de datasets, com visualização Recharts |
|
||
| **Backups** | `backups` | Jobs de backup com execução e artefatos gerados |
|
||
| **Staging** | `staging` | Área de preparação: mapeamento de colunas, migração para tabelas destino |
|
||
| **Advanced** | `advanced` | BI Engine (link para Motor Python), Metabase (link para iframe), Assistente IA |
|
||
|
||
### Tipos de Gráficos Suportados (Recharts)
|
||
|
||
| Tipo | Componente | Uso |
|
||
|------|-----------|-----|
|
||
| `bar` | `BarChart + Bar` | Comparação entre categorias |
|
||
| `line` | `LineChart + Line` | Evolução temporal |
|
||
| `pie` | `PieChart + Pie + Cell` | Proporções (até 8 fatias) |
|
||
| `area` | `AreaChart + Area` | Tendências com preenchimento |
|
||
| `scatter` | (planejado) | Correlação entre variáveis |
|
||
| `table` | HTML Table | Dados tabulares |
|
||
| `metric` | Card KPI | Valor único com destaque |
|
||
| `donut` | `PieChart (innerRadius)` | Proporções com centro vazio |
|
||
|
||
### Assistente BI (IA)
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 🤖 Assistente BI │
|
||
│ │
|
||
│ • Chat conversacional com GPT-4o │
|
||
│ • Recebe dados do dataset ativo como contexto │
|
||
│ • Prompts rápidos pré-definidos: │
|
||
│ 📊 "Resumo Executivo" (principais métricas e insights) │
|
||
│ 🔍 "Anomalias" (outliers e desvios) │
|
||
│ 📈 "Tendências" (padrões temporais) │
|
||
│ 💡 "Recomendações" (ações sugeridas) │
|
||
│ • Formato de resposta: JSON { answer, insights[] } │
|
||
│ • Interface: chat bubble com histórico │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Categorias de Tabelas Internas
|
||
|
||
O BI mapeia automaticamente as tabelas do sistema em categorias:
|
||
|
||
| Categoria | Tabelas |
|
||
|-----------|---------|
|
||
| **Sistema** | users, applications, roles |
|
||
| **Process Compass** | pc_clients, pc_projects, pc_tasks |
|
||
| **CRM** | crm_clients, crm_contracts, crm_partners, crm_opportunities, crm_leads, crm_messages |
|
||
| **BI** | bi_datasets, bi_charts |
|
||
| **Conhecimento** | knowledge_base |
|
||
| **Manus** | manus_runs, agent_tasks |
|
||
| **Comunicação** | whatsapp_messages, conversations |
|
||
| **Outros** | Todas as demais tabelas (valuation_*, fin_*, etc.) |
|
||
|
||
---
|
||
|
||
## 6. Motor BI Python — Endpoints Detalhados
|
||
|
||
### POST /query — Execução SQL
|
||
|
||
```json
|
||
{
|
||
"sql": "SELECT status, COUNT(*) as total FROM sales_orders GROUP BY status",
|
||
"params": {},
|
||
"limit": 1000,
|
||
"use_cache": true
|
||
}
|
||
```
|
||
|
||
Retorno:
|
||
```json
|
||
{
|
||
"data": [{"status": "confirmed", "total": 45}, ...],
|
||
"columns": [{"name": "status", "type": "1043"}, ...],
|
||
"row_count": 3,
|
||
"elapsed_ms": 12.5,
|
||
"cached": false
|
||
}
|
||
```
|
||
|
||
### POST /chart-data — Dados para Gráficos
|
||
|
||
```json
|
||
{
|
||
"table": "sales_orders",
|
||
"x_axis": "created_at",
|
||
"y_axis": "total_amount",
|
||
"aggregation": "sum",
|
||
"time_grain": "month",
|
||
"group_by": "status",
|
||
"filters": [{"column": "status", "operator": "!=", "value": "cancelled"}],
|
||
"limit": 12
|
||
}
|
||
```
|
||
|
||
Retorno:
|
||
```json
|
||
{
|
||
"labels": ["2026-01", "2026-02", "2026-03"],
|
||
"series": {
|
||
"confirmed": [{"label": "2026-01", "value": 15000}, ...],
|
||
"delivered": [{"label": "2026-01", "value": 12000}, ...]
|
||
},
|
||
"row_count": 6,
|
||
"elapsed_ms": 18.3,
|
||
"query": "SELECT DATE_TRUNC('month', created_at) AS label, status AS series, SUM(total_amount) AS value FROM sales_orders WHERE status != 'cancelled' GROUP BY ...",
|
||
"cached": false
|
||
}
|
||
```
|
||
|
||
### POST /micro-bi — Métricas Rápidas
|
||
|
||
```json
|
||
{
|
||
"table": "fin_transactions",
|
||
"metrics": ["count", "sum:amount", "avg:amount"],
|
||
"dimension": "category",
|
||
"period": "month",
|
||
"compare_previous": true
|
||
}
|
||
```
|
||
|
||
Retorno:
|
||
```json
|
||
{
|
||
"current": [
|
||
{"dimension": "vendas", "count": 120, "sum_amount": 45000, "avg_amount": 375}
|
||
],
|
||
"previous": [
|
||
{"dimension": "vendas", "count": 98, "sum_amount": 38000, "avg_amount": 387.76}
|
||
],
|
||
"comparison": {
|
||
"count": {"current": 120, "previous": 98, "change": 22, "change_pct": 22.4, "trend": "up"}
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /analyze — Análise com Pandas
|
||
|
||
```json
|
||
{
|
||
"data": [{"col1": 10, "col2": "A"}, ...],
|
||
"question": "Quais são os outliers?"
|
||
}
|
||
```
|
||
|
||
Retorno: estatísticas por coluna (min, max, mean, median, std, sum), insights automáticos, sugestões de gráficos.
|
||
|
||
### Granularidades Temporais (time_grain)
|
||
|
||
| Valor | Função SQL | Exemplo |
|
||
|-------|-----------|---------|
|
||
| `day` | `DATE_TRUNC('day', col)` | 2026-03-16 |
|
||
| `week` | `DATE_TRUNC('week', col)` | 2026-03-11 |
|
||
| `month` | `DATE_TRUNC('month', col)` | 2026-03-01 |
|
||
| `quarter` | `DATE_TRUNC('quarter', col)` | 2026-01-01 |
|
||
| `year` | `DATE_TRUNC('year', col)` | 2026-01-01 |
|
||
|
||
### Funções de Agregação
|
||
|
||
| Valor | SQL | Uso |
|
||
|-------|-----|-----|
|
||
| `sum` | `SUM(col)` | Totalizador |
|
||
| `avg` | `AVG(col)` | Média |
|
||
| `count` | `COUNT(*)` | Contagem |
|
||
| `min` | `MIN(col)` | Mínimo |
|
||
| `max` | `MAX(col)` | Máximo |
|
||
|
||
---
|
||
|
||
## 7. Pipeline ETL — Fluxo de Ingestão
|
||
|
||
```
|
||
Arquivo (CSV/Excel/JSON/SQL/BSON/ZIP)
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ 1. UPLOAD (/api/upload/file) │
|
||
│ │
|
||
│ • Multer (disk storage) │
|
||
│ • Limite: 200 MB │
|
||
│ • Validação de extensão │
|
||
│ • Parse do conteúdo │
|
||
└──────────────────┬───────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ 2. STAGING (staged_tables) │
|
||
│ │
|
||
│ • Armazena headers e sample data │
|
||
│ • Detecta tipos de colunas │
|
||
│ • Preview para o usuário │
|
||
└──────────────────┬───────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ 3. MAPEAMENTO (staging_mappings) │
|
||
│ │
|
||
│ • sourceColumn → targetColumn │
|
||
│ • transformType (cast, rename, etc.)│
|
||
│ • Validação de compatibilidade │
|
||
└──────────────────┬───────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ 4. MIGRAÇÃO (migration_jobs) │
|
||
│ │
|
||
│ • Cria tabela destino se necessário │
|
||
│ • INSERT em lotes │
|
||
│ • Tracking: total/processed rows │
|
||
│ • Status: pending → running → │
|
||
│ completed/failed │
|
||
│ • Error log para debugging │
|
||
└──────────────────┬───────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ 5. DATASET (bi_datasets) │
|
||
│ │
|
||
│ • Dataset pronto para visualização │
|
||
│ • Pode criar charts e dashboards │
|
||
│ • Conecta com BI Engine e Metabase │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Integração entre Pilares
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ FLUXO DE DADOS │
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ Upload │────▶│ Staging │────▶│ Dataset │────▶│ Chart │ │
|
||
│ │ (ETL) │ │(Prepare) │ │ (Dados) │ │ (Visual) │ │
|
||
│ └──────────┘ └──────────┘ └────┬─────┘ └────┬─────┘ │
|
||
│ │ │ │
|
||
│ ┌─────▼──────┐ ┌────▼─────┐ │
|
||
│ │ BI Engine │ │Dashboard │ │
|
||
│ │ (Análise) │ │(Painel) │ │
|
||
│ └─────┬──────┘ └──────────┘ │
|
||
│ │ │
|
||
│ ┌──────────┐ ┌─────▼──────┐ │
|
||
│ │ Tabelas │─────────────────────▶│ Metabase │ │
|
||
│ │ Internas │ │ (Visual) │ │
|
||
│ │ (PG) │ └──────┬─────┘ │
|
||
│ └──────────┘ │ │
|
||
│ ┌─────▼──────┐ │
|
||
│ │ Cientista │ │
|
||
│ │ (IA/ML) │ │
|
||
│ └────────────┘ │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Como os pilares se conectam:
|
||
|
||
| De | Para | Como |
|
||
|----|------|------|
|
||
| Upload | Staging | Arquivo parseado → tabela staged |
|
||
| Staging | Dataset | Migração → dataset criado automaticamente |
|
||
| Tabela Interna | Dataset | `/api/bi/internal-tables/:name/create-dataset` |
|
||
| Dataset | BI Engine | SQL do dataset executado no Motor Python |
|
||
| Dataset | Chart | Chart referencia datasetId |
|
||
| Chart | Dashboard | `bi_dashboard_charts` com posição (X,Y,W,H) |
|
||
| Tabelas PG | Metabase | Conexão direta ao PostgreSQL |
|
||
| Dataset | Assistente IA | Dados enviados como contexto ao GPT-4o |
|
||
| Dados | Cientista | `analyze_data()`, `detect_patterns()`, `generate_insights()` |
|
||
|
||
---
|
||
|
||
## 9. Configuração e Variáveis de Ambiente
|
||
|
||
| Variável | Default | Usado por | Descrição |
|
||
|----------|---------|-----------|-----------|
|
||
| `DATABASE_URL` | - | BI Engine, Gateway | Conexão PostgreSQL |
|
||
| `BI_ENGINE_HOST` | `localhost` | Engine Proxy | Host do motor Python |
|
||
| `BI_PORT` | `8004` | BI Engine, Proxy | Porta do motor Python |
|
||
| `BI_ENGINE_TIMEOUT` | `30000` | Engine Proxy | Timeout de proxy (ms) |
|
||
| `METABASE_HOST` | `localhost` | Metabase Proxy | Host do Metabase |
|
||
| `METABASE_PORT` | `8088` | Metabase Proxy | Porta do Metabase |
|
||
| `METABASE_TIMEOUT` | `60000` | Metabase Proxy | Timeout do proxy (ms) |
|
||
| `OPENAI_API_KEY` | - | Assistente BI | API key para GPT-4o |
|
||
|
||
---
|
||
|
||
## 10. Arquivos-Chave
|
||
|
||
| Arquivo | Camada | Função | Linhas |
|
||
|---------|--------|--------|--------|
|
||
| `server/python/bi_engine.py` | Motor Python | SQL, Charts, Micro-BI, Cache, Análise | ~650 |
|
||
| `server/bi/routes.ts` | API Node | CRUD de DataSources, Datasets, Charts, Dashboards, Backups | ~700 |
|
||
| `server/bi/engine-proxy.ts` | Proxy | Proxy Gateway → BI Engine Python (:8004) | ~200 |
|
||
| `server/bi/upload.ts` | ETL | Upload de arquivos (CSV, Excel, JSON, SQL, BSON, ZIP) | ~1.060 |
|
||
| `server/bi/staging.ts` | ETL | Staging, mapeamento, migração de dados | ~408 |
|
||
| `server/metabase/proxy.ts` | Proxy | Proxy Gateway → Metabase (:8088) | ~42 |
|
||
| `client/src/pages/BiWorkspace.tsx` | Frontend | Interface principal do BI (8 tabs) | ~2.970 |
|
||
| `client/src/pages/MetabaseProxyPage.tsx` | Frontend | Página do Metabase embeddado | ~25 |
|
||
| `python-service/services/cientista.py` | IA/ML | Análise, padrões, insights, auto-programação | ~567 |
|
||
| `shared/schema.ts` | Schema | Tabelas BI (9 tabelas) | Parte do schema |
|
||
|
||
---
|
||
|
||
## 11. Deploy (Docker/Coolify)
|
||
|
||
### Container `arcadia-bi` (Motor Python)
|
||
|
||
```dockerfile
|
||
FROM python:3.11-slim
|
||
WORKDIR /app
|
||
RUN pip install fastapi uvicorn pydantic pandas numpy psycopg2-binary
|
||
COPY server/python/bi_engine.py ./main.py
|
||
EXPOSE 8004
|
||
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8004"]
|
||
```
|
||
|
||
### Container `metabase`
|
||
|
||
```yaml
|
||
metabase:
|
||
image: metabase/metabase:latest
|
||
restart: always
|
||
ports:
|
||
- "8088:3000"
|
||
environment:
|
||
MB_DB_TYPE: postgres
|
||
MB_DB_DBNAME: metabase
|
||
MB_DB_PORT: 5432
|
||
MB_DB_USER: ${PGUSER:-arcadia}
|
||
MB_DB_PASS: ${PGPASSWORD}
|
||
MB_DB_HOST: postgres
|
||
JAVA_TIMEZONE: America/Sao_Paulo
|
||
depends_on:
|
||
postgres:
|
||
condition: service_healthy
|
||
volumes:
|
||
- metabase-data:/metabase-data
|
||
networks:
|
||
- arcadia
|
||
```
|
||
|
||
### Variáveis no Gateway (Docker)
|
||
|
||
```yaml
|
||
gateway:
|
||
environment:
|
||
BI_ENGINE_HOST: bi
|
||
BI_PORT: 8004
|
||
METABASE_HOST: metabase
|
||
METABASE_PORT: 3000
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Resumo Visual
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ ARCÁDIA BI STACK │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||
│ │ FRONTEND: BiWorkspace.tsx + Recharts + Assistente IA (GPT) │ │
|
||
│ └────────────────────────────┬────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌─────────────────────┼─────────────────────┐ │
|
||
│ │ │ │ │
|
||
│ ┌──────▼──────┐ ┌────────▼────────┐ ┌────────▼────────┐ │
|
||
│ │ API BI │ │ BI Engine │ │ Metabase │ │
|
||
│ │ (Node.js) │ │ (Python:8004) │ │ (Java:8088) │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ CRUD │ │ SQL + Charts │ │ Dashboards │ │
|
||
│ │ Upload/ETL │ │ Micro-BI │ │ Visual Builder │ │
|
||
│ │ Staging │ │ Análise Pandas │ │ Alertas │ │
|
||
│ │ Backups │ │ Cache (5min) │ │ Exportação │ │
|
||
│ └──────┬──────┘ └────────┬────────┘ └────────┬────────┘ │
|
||
│ │ │ │ │
|
||
│ └────────────────────┼──────────────────────┘ │
|
||
│ │ │
|
||
│ ┌──────────▼──────────┐ │
|
||
│ │ PostgreSQL │ │
|
||
│ │ (Porta 5432) │ │
|
||
│ │ │ │
|
||
│ │ 9 tabelas BI + │ │
|
||
│ │ 100+ tabelas SOE │ │
|
||
│ └────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||
│ │ CIENTISTA (Python) — Análise, Padrões, Insights, AutoCode │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|