# DashDescomplicar > **Dashboard de Gestão e Monitorização** da Descomplicar® > Monitorização em tempo real de servidores, tarefas, calendário e métricas financeiras. [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/) [![React](https://img.shields.io/badge/React-19-61dafb)](https://react.dev/) [![Express](https://img.shields.io/badge/Express-4.x-green)](https://expressjs.com/) [![Security Audit](https://img.shields.io/badge/Security-0%20vulnerabilities-brightgreen)](https://github.com/advisories) [![License](https://img.shields.io/badge/License-Proprietary-red)](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: ``` ### 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)**