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.

[![Next.js](https://img.shields.io/badge/Next.js-16.1.6-black)](https://nextjs.org/)
[![React](https://img.shields.io/badge/React-19.2.3-blue)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)](https://www.typescriptlang.org/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4-38bdf8)](https://tailwindcss.com/)
[![Prisma](https://img.shields.io/badge/Prisma-5.22.0-2D3748)](https://www.prisma.io/)

---

## 🎯 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](./AUDIT-REPORT.md) - Relatório de auditoria completo
- [SECURITY-FIX.md](./SECURITY-FIX.md) - Detalhes técnicos das correções
- [CHANGELOG.md](./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

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

### 2. Instalar Dependências

```bash
pnpm install
```

### 3. Configurar Variáveis de Ambiente

```bash
cp .env.example .env
```

Editar `.env` com as configurações corretas:

```bash
# 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

```bash
pnpm prisma generate
```

### 5. Executar Migrações (opcional)

```bash
pnpm prisma migrate dev
```

---

## 💻 Desenvolvimento

### Servidor de Desenvolvimento

```bash
pnpm dev
```

Aceder: http://localhost:3000

### Build de Produção

```bash
pnpm build
pnpm start
```

### Linting

```bash
pnpm lint
```

### Security Audit

```bash
pnpm audit
```

---

## 🐳 Docker

### Build

```bash
docker build -t bi-descomplicar .
```

### Run

```bash
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:

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

**Gerar API Key:**
```bash
openssl rand -base64 32
```

---

## 📡 API Endpoints

### GET /api/sites
Lista todos os sites activos.

**Autenticação:** Requerida
**Resposta:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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](./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:
```bash
pnpm audit
```

Ver [SECURITY-FIX.md](./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](https://git.descomplicar.pt/ealmeida/bi-descomplicar)
- [Metabase BI](https://bi.descomplicar.pt)
- [Next.js Docs](https://nextjs.org/docs)
- [Prisma Docs](https://www.prisma.io/docs)
- [Tailwind CSS Docs](https://tailwindcss.com/docs)