docs: Atualizar documentação completa do projeto
README.md: - Transformado de template Next.js em documentação profissional - Adicionadas badges (Next.js, React, TypeScript, Tailwind, Prisma) - Documentado sistema de 5 camadas de defesa - Setup completo (pré-requisitos, instalação, configuração) - Documentação API endpoints com validações - Estrutura do projeto explicada - Metabase integration documentada - Deploy EasyPanel e Docker - Security: reportar vulnerabilidades, audit pre-commit DEPLOY-STATUS.md: - Actualizado com security hardening (14/02/2026) - Adicionada tabela vulnerabilidades corrigidas - Sistema de 5 camadas documentado - Histórico completo (deploy inicial + security fix) - Pendentes organizados por prioridade (Alta/Média/Baixa) - Lições aprendidas (Deploy + Segurança) - Métricas completas (deploy + security fix) - Links para toda a documentação package.json: - Adicionados 9 scripts úteis (lint:fix, typecheck, db:*, audit, security) - Implementação da recomendação [O-003] do AUDIT-REPORT Melhoria: Documentação agora production-ready Referências: AUDIT-REPORT.md, SECURITY-FIX.md, CHANGELOG.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
430
README.md
430
README.md
@@ -1,36 +1,424 @@
|
||||
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
|
||||
# BI Descomplicar
|
||||
|
||||
## Getting Started
|
||||
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.
|
||||
|
||||
First, run the development server:
|
||||
[](https://nextjs.org/)
|
||||
[](https://react.dev/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://tailwindcss.com/)
|
||||
[](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
|
||||
npm run dev
|
||||
# or
|
||||
yarn dev
|
||||
# or
|
||||
pnpm dev
|
||||
# or
|
||||
bun dev
|
||||
git clone git@git.descomplicar.pt:ealmeida/bi-descomplicar.git
|
||||
cd bi-descomplicar
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
||||
### 2. Instalar Dependências
|
||||
|
||||
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
|
||||
### 3. Configurar Variáveis de Ambiente
|
||||
|
||||
## Learn More
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
To learn more about Next.js, take a look at the following resources:
|
||||
Editar `.env` com as configurações corretas:
|
||||
|
||||
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
|
||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
||||
```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"
|
||||
|
||||
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
|
||||
# Node Environment
|
||||
NODE_ENV=development
|
||||
|
||||
## Deploy on Vercel
|
||||
# API Security
|
||||
# Gerar chave segura: openssl rand -base64 32
|
||||
API_SECRET_KEY="sua-chave-secreta-aqui"
|
||||
```
|
||||
|
||||
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
|
||||
### 4. Gerar Prisma Client
|
||||
|
||||
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
|
||||
```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)
|
||||
|
||||
Reference in New Issue
Block a user