bi-descomplicar/README.md

BI Descomplicar

Dashboard custom em Next.js para métricas de Business Intelligence da Descomplicar®, integrando Google Analytics 4 (GA4) e Google Search Console (GSC) com total liberdade criativa.

---

🎯 Visão Geral

Sistema de Business Intelligence customizado que agrega dados de múltiplas fontes (GA4, GSC) numa interface visual moderna e responsiva. Desenvolvido com Next.js 16 App Router, React Server Components e otimizado para performance.

Principais Features:

• 📊 Dashboards interativos com métricas GA4 e GSC
• 🔄 Atualização em tempo real de métricas
• 📈 Gráficos customizados (Recharts)
• 🎨 Design system próprio (shadcn/ui)
• 🔒 Sistema de autenticação API key
• ✅ Validação de inputs com Zod
• 🐳 Docker multi-stage optimizado

---

🏗️ Stack Tecnológica

Frontend

• Next.js 16.1.6 - App Router + React Server Components
• React 19.2.3 - UI Library
• TypeScript 5 - Type Safety
• Tailwind CSS 4 - Styling
• shadcn/ui - Component Library
• Recharts 3.7 - Data Visualization

Backend

• Prisma 5.22 - ORM multi-schema (staging/production)
• PostgreSQL - Database
• Zod 4.3.6 - Runtime Validation

DevOps

• Docker - Multi-stage build (Debian slim)
• pnpm - Package Manager
• ESLint - Code Quality

---

🔒 Segurança

O projeto implementa um sistema de 5 camadas de defesa:

1. Autenticação API Key

• Middleware Next.js (src/middleware.ts)
• Validação via header x-api-key
• Protege todas as rotas /api/* (exceto /api/health)

2. Validação de Inputs

• Schemas Zod (src/lib/validations.ts)
• Previne SQL injection, NaN, inputs maliciosos
• Validação de siteId (inteiro positivo)
• Validação de period (1-365 dias, formato: 30d)

3. Type Safety

• TypeScript strict mode
• Zero any types
• ESLint configurado com @typescript-eslint/no-explicit-any

4. Audit Automatizado

• pnpm audit obrigatório pre-commit
• Zero vulnerabilidades (críticas, altas, moderadas, baixas)
• 521 dependências verificadas

5. Documentação

• AUDIT-REPORT.md - Relatório de auditoria completo
• SECURITY-FIX.md - Detalhes técnicos das correções
• CHANGELOG.md - Histórico de versões

CVSS Score: 0.0 (anteriormente 7.5)

---

🚀 Setup

Pré-requisitos

• Node.js 20+
• pnpm 9+
• PostgreSQL 14+
• Acesso SSH ao servidor de base de dados (para desenvolvimento)

1. Clonar Repositório

git clone git@git.descomplicar.pt:ealmeida/bi-descomplicar.git
cd bi-descomplicar

2. Instalar Dependências

pnpm install

3. Configurar Variáveis de Ambiente

cp .env.example .env

Editar .env com as configurações corretas:

# Database Connection
# Para desenvolvimento local, usar SSH tunnel:
# ssh -L 5432:descomplicar_metabase-db:5432 easy
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=staging"

# Node Environment
NODE_ENV=development

# API Security
# Gerar chave segura: openssl rand -base64 32
API_SECRET_KEY="sua-chave-secreta-aqui"

4. Gerar Prisma Client

pnpm prisma generate

5. Executar Migrações (opcional)

pnpm prisma migrate dev

---

💻 Desenvolvimento

Servidor de Desenvolvimento

pnpm dev

Aceder: http://localhost:3000

Build de Produção

pnpm build
pnpm start

Linting

pnpm lint

Security Audit

pnpm audit

---

🐳 Docker

Build

docker build -t bi-descomplicar .

Run

docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e API_SECRET_KEY="..." \
  bi-descomplicar

---

🔑 Autenticação

Todas as rotas /api/* (exceto /api/health) requerem autenticação via header:

curl -H "x-api-key: sua-chave-aqui" \
  http://localhost:3000/api/sites

Gerar API Key:

openssl rand -base64 32

---

📡 API Endpoints

GET /api/sites

Lista todos os sites activos.

Autenticação: Requerida Resposta:

{
  "success": true,
  "sites": [
    {
      "id": 1,
      "siteName": "Exemplo",
      "siteUrl": "https://exemplo.pt",
      "ga4PropertyId": "123456789",
      "gscSiteUrl": "https://exemplo.pt"
    }
  ]
}

GET /api/metrics/[siteId]?period=30d

Retorna métricas agregadas para um site específico.

Autenticação: Requerida Parâmetros:

• siteId (path): ID do site (inteiro positivo)
• period (query): Período de análise (7d, 30d, 90d) - máximo 365d

Validação:

• siteId validado como inteiro positivo
• period validado com regex ^\d+d$ e limites 1-365

Resposta:

{
  "success": true,
  "site": {
    "id": 1,
    "name": "Exemplo"
  },
  "period": {
    "days": 30,
    "startDate": "2026-01-15T00:00:00.000Z"
  },
  "metrics": {
    "visitors": 12500,
    "visitorsChange": 15.3,
    "sessions": 18700,
    "sessionsChange": 12.1,
    "pageViews": 45600,
    "pageViewsChange": 8.9
  },
  "charts": {
    "dailyTraffic": [...],
    "trafficSources": [...],
    "topQueries": [...]
  }
}

Erros:

• 400 Bad Request - Input inválido (detalhes no campo details)
• 401 Unauthorized - API key ausente ou inválida
• 404 Not Found - Site não encontrado ou GA4 não configurado
• 500 Internal Server Error - Erro do servidor

GET /api/health

Health check endpoint (sem autenticação).

Resposta:

{
  "status": "ok",
  "timestamp": "2026-02-14T03:30:00.000Z"
}

---

📂 Estrutura do Projeto

bi-descomplicar/
├── prisma/
│   └── schema.prisma          # Schemas Prisma (multi-schema)
├── src/
│   ├── app/
│   │   ├── api/              # API Routes
│   │   │   ├── health/       # Health check
│   │   │   ├── sites/        # Lista de sites
│   │   │   └── metrics/      # Métricas por site
│   │   ├── dashboard/        # Dashboard pages
│   │   └── layout.tsx        # Root layout
│   ├── components/
│   │   ├── dashboard/        # Dashboard components
│   │   └── ui/               # shadcn/ui components
│   ├── lib/
│   │   ├── auth.ts           # Autenticação utilities
│   │   ├── prisma.ts         # Prisma singleton
│   │   ├── utils.ts          # Utilities
│   │   └── validations.ts    # Zod schemas
│   └── middleware.ts          # Middleware de autenticação
├── .env.example              # Template de variáveis de ambiente
├── AUDIT-REPORT.md           # Relatório de auditoria
├── CHANGELOG.md              # Histórico de versões
├── Dockerfile                # Multi-stage build
├── SECURITY-FIX.md           # Documentação de segurança
└── README.md                 # Este ficheiro

---

🔍 Schemas Prisma

O projeto usa multi-schema para separar ambientes:

• staging - Dados de desenvolvimento/staging
• production - Dados de produção

Principais Models:

• Site - Sites monitorizados
• GA4DailyTraffic - Métricas diárias GA4
• GA4TrafficSources - Fontes de tráfego
• GSCSearchPerformance - Performance de pesquisa GSC

---

📊 Metabase Integration

Base de dados partilhada com Metabase BI (bi.descomplicar.pt).

Conexão:

• Host: descomplicar_metabase-db (via SSH tunnel)
• Porta: 5432
• Database: metabase

---

🚢 Deploy

EasyPanel (Recomendado)

1. Criar projeto: descomplicar

2. Criar serviço: bi-descomplicar

3. Configurar variáveis de ambiente:

   • DATABASE_URL
   • API_SECRET_KEY
   • NODE_ENV=production

4. Deploy via Git:

   • Repo: git@git.descomplicar.pt:ealmeida/bi-descomplicar.git
   • Branch: main
   • Build command: pnpm install && pnpm build
   • Start command: pnpm start

Manual

1. Build da imagem Docker
2. Configurar variáveis de ambiente
3. Expor porta 3000
4. Configurar reverse proxy (Traefik/Nginx)

---

📝 Changelog

Ver CHANGELOG.md para histórico completo de versões.

Última versão: 0.1.1 (2026-02-14)

• ✅ Corrigidas 3 vulnerabilidades críticas
• ✅ Implementado sistema de autenticação
• ✅ Adicionada validação de inputs
• ✅ CVSS Score: 7.5 → 0.0

---

🔐 Segurança

Reportar Vulnerabilidades

Para reportar vulnerabilidades de segurança:

• Email: emanuel@descomplicar.pt
• Assunto: [SECURITY] BI Descomplicar

Security Audit

Executar antes de cada commit:

pnpm audit

Ver SECURITY-FIX.md para detalhes do sistema de segurança.

---

📄 Licença

Propriedade de Descomplicar® - Todos os direitos reservados.

---

👨‍💻 Autor

Emanuel Almeida Email: emanuel@descomplicar.pt Empresa: Descomplicar®

---

🔗 Links Úteis

• Repositório Git
• Metabase BI
• Next.js Docs
• Prisma Docs
• Tailwind CSS Docs