Emanuel Almeida
3283d338ce
LOW-SEVERITY FIXES: 1. README Genérico (Vulnerabilidade 4.4) ✅ 2. Ausência de Testes (Vulnerabilidade 4.3) ✅ 3. Logs Verbosos em Produção (Vulnerabilidade 4.5) ✅ FILES: README.md, package.json, vitest.config.ts, src/test/* Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
435 lines
9.7 KiB
Markdown
Executable File
435 lines
9.7 KiB
Markdown
Executable File
# DashDescomplicar
|
|
|
|
> **Dashboard de Gestão e Monitorização** da Descomplicar®
|
|
> Monitorização em tempo real de servidores, tarefas, calendário e métricas financeiras.
|
|
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://react.dev/)
|
|
[](https://expressjs.com/)
|
|
[](https://github.com/advisories)
|
|
[](LICENSE)
|
|
|
|
---
|
|
|
|
## 📋 Índice
|
|
|
|
- [Sobre](#sobre)
|
|
- [Stack Tecnológica](#stack-tecnológica)
|
|
- [Funcionalidades](#funcionalidades)
|
|
- [Requisitos](#requisitos)
|
|
- [Instalação](#instalação)
|
|
- [Configuração](#configuração)
|
|
- [Desenvolvimento](#desenvolvimento)
|
|
- [Produção](#produção)
|
|
- [Segurança](#segurança)
|
|
- [API Endpoints](#api-endpoints)
|
|
- [Arquitectura](#arquitectura)
|
|
- [Testes](#testes)
|
|
- [Contribuir](#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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
### Variáveis Obrigatórias
|
|
|
|
```env
|
|
# 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)
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```env
|
|
OIDC_ENABLED=true
|
|
OIDC_SECRET=seu_secret_aqui
|
|
OIDC_ISSUER=https://auth.descomplicar.pt
|
|
OIDC_CLIENT_ID=seu_client_id
|
|
```
|
|
|
|
---
|
|
|
|
## 💻 Desenvolvimento
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Build completo (frontend + backend)
|
|
npm run build
|
|
|
|
# Verificar output
|
|
ls -lh dist/
|
|
ls -lh api/dist/
|
|
```
|
|
|
|
### Deploy
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```env
|
|
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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://www.conventionalcommits.org/)
|
|
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](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](https://git.descomplicar.pt/ealmeida)
|
|
|
|
**Descomplicar®**
|
|
- Website: https://descomplicar.pt
|
|
- CRM: https://desk.descomplicar.pt
|
|
|
|
---
|
|
|
|
**Desenvolvido com ❤️ por [Descomplicar®](https://descomplicar.pt)**
|