docs: adiciona especificação da integração Metaset BI

- Documenta arquitetura e componentes - Lista rotas e variáveis de ambiente - Descreve fluxo de navegação - Inclui troubleshooting
2026-04-08 14:40:32 -03:00 · 2026-04-08 14:40:32 -03:00 · b296638888
parent 5554e9d613
commit b296638888
1 changed files with 127 additions and 0 deletions
--- a/docs/METASET_INTEGRATION.md
+++ b/docs/METASET_INTEGRATION.md
@ -0,0 +1,127 @@
+# Integração Metaset BI - Especificações
+
+## Visão Geral
+Integração do Metaset BI (Apache Superset modificado) na Arcadia Suite, permitindo acesso via navegação interna sem sair da aplicação.
+
+## Arquitetura
+
+### Componentes
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Arcadia Suite                            │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │   Navbar     │  │  BrowserFrame │  │   Metaset.tsx   │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+│                                                           │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │              iframe src="/metaset"                   │  │
+│  └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Proxy /metaset (metaset-proxy.ts)              │
+│         pathRewrite: "^/metaset" → ""                       │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Serviço Metaset (Docker)                       │
+│              http://metaset:8100                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Arquivos
+
+### Backend
+- `server/bi/metaset-proxy.ts` - Proxy web para o serviço Metaset
+- `server/routes.ts` - Registro do proxy no servidor Express
+
+### Frontend
+- `client/src/pages/Metaset.tsx` - Página React com iframe
+- `client/src/App.tsx` - Rota `/metaset`
+- `client/src/components/Browser/BrowserFrame.tsx` - Item na navbar
+
+### Proxy Configuração
+```typescript
+const METASET_HOST = process.env.METASET_HOST || "metaset";
+const METASET_PORT = parseInt(process.env.METASET_PORT || "8100", 10);
+
+createProxyMiddleware({
+  target: `http://${METASET_HOST}:${METASET_PORT}`,
+  changeOrigin: true,
+  pathRewrite: { "^/metaset": "" },
+  // ...error handling
+});
+```
+
+## Rotas
+
+| Rota | Descrição |
+|------|-----------|
+| `/metaset` | Página React do módulo Metaset |
+| `/metaset/*` | Proxy para serviço Metaset (8100) |
+| `/api/bi/metaset/*` | API REST do Metaset (já existente) |
+
+## Variáveis de Ambiente
+
+```env
+METASET_HOST=metaset        # hostname do container
+METASET_PORT=8100           # porta do serviço
+```
+
+## Fluxo de Navegação
+
+1. Usuário clica em "Metaset" na navbar
+2. Navegação React para rota `/metaset`
+3. `Metaset.tsx` renderiza iframe apontando para `/metaset`
+4. Proxy redireciona para `http://metaset:8100`
+5. Interface Metaset carrega dentro do iframe
+6. Navbar Arcadia permanece visível
+
+## Estados da UI
+
+### Loading
+- Spinner animado com texto "Carregando Metaset..."
+- Overlay sobre o iframe
+
+### Erro (Serviço Offline)
+- Alert vermelho com mensagem de erro
+- Botão "Tentar novamente" para reload
+- Health check via `/api/bi/metaset/health`
+
+### Sucesso
+- iframe carrega interface completa do Metaset
+- Navegação suave entre módulos Arcadia
+
+## Segurança
+
+- Proxy preserva cookies/sessão
+- Health check requer autenticação
+- PathRewrite remove prefixo /metaset antes de enviar ao serviço
+- Headers Location são reescritos para manter contexto
+
+## Troubleshooting
+
+### Erro: "Conexão recusada"
+Verificar se container Metaset está rodando:
+```bash
+docker ps | grep metaset
+docker logs metaset
+```
+
+### Erro: "Metaset indisponível"
+Verificar health endpoint:
+```bash
+curl /api/bi/metaset/health
+```
+
+### iframe não carrega
+Verificar se Metaset permite embed (X-Frame-Options):
+- Verificar configuração do Superset/TALISMAN_ENABLED
+
+## Referências
+
+- Proxy similar: `server/superset/proxy.ts`
+- Cliente API: `server/bi/metaset-client/`
+- Rotas API: `server/bi/routes.ts`