DashDescomplicar

Dashboard de Gestão e Monitorização da Descomplicar® Monitorização em tempo real de servidores, tarefas, calendário e métricas financeiras.

---

📋 Índice

• Sobre
• Stack Tecnológica
• Funcionalidades
• Requisitos
• Instalação
• Configuração
• Desenvolvimento
• Produção
• Segurança
• API Endpoints
• Arquitectura
• Testes
• Contribuir

---

🎯 Sobre

DashDescomplicar é um dashboard interno de gestão desenvolvido para centralizar a monitorização e gestão operacional da Descomplicar®. Integra dados de múltiplas fontes (CRM Desk, Hetzner Cloud, servidores SSH, WordPress sites) num interface unificado e em tempo real.

Objectivos

• Visibilidade completa de todas as operações
• Monitorização proactiva de infraestrutura
• Centralização de métricas de negócio
• Resposta rápida a incidentes

---

🛠️ Stack Tecnológica

Frontend

• React 19 - UI library com Server Components
• TypeScript 5.6 - Type safety
• Vite 7.3 - Build tool moderna
• Tailwind CSS - Utility-first CSS
• Framer Motion - Animações
• Lucide React - Icons

Backend

• Express 4.x - API server
• MySQL2 - Database driver
• Node.js 18+ - Runtime
• SSH2 - SSH connections
• Zod - Schema validation

DevOps

• Docker - Containerização
• Gitea - Git repository
• EasyPanel - Deployment platform

Segurança

• express-rate-limit - Rate limiting
• CORS - Cross-origin protection
• Zod - Input validation
• OIDC - Autenticação (opcional)

---

✨ Funcionalidades

📊 Dashboard Principal

• Hero Stats - Métricas principais (tarefas, calendário, servidores)
• Gráficos - Visualização de tendências
• Status real-time - Monitorização ao vivo

🖥️ Monitorização

• Servidores Hetzner - CPU, RAM, Disk, Network
• Servidores SSH - Métricas via SSH (CWP, EasyPanel)
• WordPress Sites - Health checks, updates, database
• Containers - Status de Docker containers
• Backups - Estado de backups automáticos

📅 Calendário

• Eventos Google Calendar - Integração nativa
• Tarefas da semana - Vista semanal
• Deadlines - Alertas de prazos

💰 Financeiro

• Receitas/Despesas - Tracking financeiro
• Gráficos - Evolução temporal
• Resumos - Totais e médias

🎨 Design

• Glass morphism - Interface moderna
• Dark mode nativo - UI optimizada para trabalho nocturno
• Responsive - Mobile-first design
• Animações - Micro-interactions com Framer Motion

---

⚙️ Requisitos

• Node.js >= 18.0.0
• npm >= 9.0.0
• MySQL >= 8.0
• Git

Serviços Externos

• Desk CRM - Base de dados (tbl_eal_*)
• Hetzner Cloud API - Métricas de servidores
• Google Calendar API - Eventos (opcional)
• Servidores SSH - Acesso para métricas (opcional)

---

🚀 Instalação

# Clone o repositório
git clone git@git.descomplicar.pt:ealmeida/DashDescomplicar.git
cd DashDescomplicar

# Instalar dependências
npm install

# Verificar vulnerabilidades
npm audit

---

🔧 Configuração

1. Variáveis de Ambiente

Copiar .env.example para .env e configurar:

cp .env.example .env

Variáveis Obrigatórias

# Database
DB_HOST=localhost
DB_USER=ealmeida_desk24
DB_PASS=sua_password_aqui
DB_NAME=ealmeida_desk24

# WordPress Monitor
WP_MONITOR_API_KEY=sua_api_key_segura_aqui

# Hetzner Cloud (opcional)
HETZNER_TOKEN=seu_token_hetzner

# SSH Servers (recomendado: key-based)
SSH_PRIVATE_KEY_PATH=/home/user/.ssh/dashboard-descomplicar

2. Migrar para SSH Key-Based Auth (Recomendado)

# Executar script de migração
/media/ealmeida/Dados/Dev/ClaudeDev/migrate-ssh-keys.sh

# Seguir instruções do script
# Remove passwords do .env após migração

3. OIDC Authentication (Opcional)

Para ativar autenticação nas APIs:

OIDC_ENABLED=true
OIDC_SECRET=seu_secret_aqui
OIDC_ISSUER=https://auth.descomplicar.pt
OIDC_CLIENT_ID=seu_client_id

---

💻 Desenvolvimento

# Modo desenvolvimento (frontend + backend)
npm run dev

# Apenas frontend
npm run dev:client

# Apenas backend
npm run dev:server

# Build TypeScript
npm run build

# Linting
npm run lint

URLs de Desenvolvimento

• Frontend: http://localhost:5173
• API: http://localhost:3001/api
• Health check: http://localhost:3001/api/health

---

🏭 Produção

Build

# Build completo (frontend + backend)
npm run build

# Verificar output
ls -lh dist/
ls -lh api/dist/

Deploy

# Usando Docker
docker build -t dash-descomplicar .
docker run -p 3001:3001 --env-file .env dash-descomplicar

# Usando EasyPanel
# Push para Gitea e trigger deploy automático
git push origin main

Variáveis de Produção

NODE_ENV=production
FRONTEND_URL=https://dash.descomplicar.pt
API_PORT=3001

---

🔒 Segurança

Auditorias Realizadas

✅ 0 vulnerabilidades críticas ✅ 0 vulnerabilidades altas ✅ 0 vulnerabilidades médias ✅ npm audit: 0 vulnerabilities

Medidas Implementadas

1. Rate Limiting - 100 req/15min (produção)
2. CORS Restrito - Whitelist de domínios
3. Input Validation - Zod schemas em todas as rotas
4. Error Handling - Sem vazamento de stack traces
5. SSH Key-Based Auth - Sem passwords em plaintext
6. Environment Variables - Credenciais nunca hardcoded

Auditoria Automática

Pre-commit hook (Regra #47) executa npm audit antes de cada commit.

# Executar auditoria manual
npm audit

# Fix automático de vulnerabilidades
npm audit fix

---

📡 API Endpoints

Dashboard

GET /api/dashboard?week=2026-02-10
GET /api/health

Monitorização

GET /api/monitor
GET /api/hetzner/servers
GET /api/server-metrics/collect

WordPress Monitor

POST /api/wp-monitor
GET /api/wp-monitor?test
Headers: x-api-key: <WP_MONITOR_API_KEY>

Financeiro

GET /api/financial?month=2026-02
GET /api/financial/calendar

Diagnóstico

GET /api/diagnostic

---

🏗️ Arquitectura

DashDescomplicar/
├── src/                    # Frontend React
│   ├── App.tsx            # Componente principal
│   ├── pages/             # Páginas (Monitor, Financial)
│   ├── auth/              # OIDC authentication
│   └── index.css          # Tailwind styles
├── api/                   # Backend Express
│   ├── server.ts          # API server
│   ├── db.ts              # MySQL pool
│   ├── routes/            # API routes
│   ├── services/          # Business logic
│   ├── middleware/        # Validation, auth
│   └── scripts/           # Cron jobs
├── public/                # Assets estáticos
├── dist/                  # Build output
└── .env                   # Configuração (gitignored)

Fluxo de Dados

┌──────────────┐
│   React UI   │ ← Fetch data via /api/*
└──────┬───────┘
       │
┌──────▼───────┐
│ Express API  │ ← Validação Zod, Rate Limiting
└──────┬───────┘
       ├─────────→ MySQL (Desk CRM)
       ├─────────→ Hetzner Cloud API
       ├─────────→ SSH Servers (metrics)
       └─────────→ WordPress Sites (monitor)

---

🧪 Testes

# Executar testes unitários
npm run test

# Coverage
npm run test:coverage

# E2E tests
npm run test:e2e

Nota: Suite de testes em desenvolvimento (Vulnerabilidade 4.3).

---

👥 Contribuir

Este é um projeto proprietário da Descomplicar®.

Workflow

1. Criar feature branch - git checkout -b feature/nome
2. Implementar - Seguir padrões do projeto
3. Commit - Seguir Conventional Commits
4. Push - git push origin feature/nome
5. Pull Request - Para main branch

Standards

• TypeScript strict mode habilitado
• ESLint rules obrigatórias
• Security audit obrigatório (pre-commit hook)
• CHANGELOG.md atualizado em cada release

---

📝 Changelog

Ver CHANGELOG.md para histórico detalhado de alterações.

Versão Actual: 2.6.0

• ✅ 3 vulnerabilidades críticas corrigidas
• ✅ 6 vulnerabilidades altas corrigidas
• ✅ 6 vulnerabilidades médias corrigidas
• ✅ 0 vulnerabilidades npm audit

---

📄 Licença

Proprietary - © 2026 Descomplicar®. Todos os direitos reservados.

Uso não autorizado, cópia, modificação ou distribuição deste software é estritamente proibido.

---

📧 Contacto

Emanuel Almeida

• Email: emanuel@descomplicar.pt
• Gitea: @ealmeida

Descomplicar®

• Website: https://descomplicar.pt
• CRM: https://desk.descomplicar.pt

---

Desenvolvido com ❤️ por Descomplicar®