docs(okf): entidades e relacionamentos OKF do DashDescomplicar

2026-10-28 16:01:20 +00:00
parent f063a2ec8c
commit 61ae4697f9
48 changed files with 2610 additions and 0 deletions
@@ -0,0 +1,65 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, integracao, csr, cache, fetch]
+title: "CSR-Integration"
+---
+
+# CSR-Integration
+
+Camada de integração Cliente-Servidor do DashDescomplicar. Gere fetch de dados da API, cache local, reconnection logic e tratamento de erros para todos os painéis.
+
+## Responsabilidades
+
+- **Fetch API**: Chamadas HTTP à Express-API com tipagem TypeScript
+- **Cache Local**: Estado React (`useState` + `useCallback`) para evitar refetchs desnecessários
+- **Reconnection**: Lógica de retry em falhas de rede (sem exponential backoff — simplicidade)
+- **Error Handling**: Erros capturados com `console.error`, estados de loading/error nos painéis
+- **Refresh Manual**: Botão "Actualizar" (RefreshCw) em cada painel com animação de spinner
+
+## Padrão de Fetch
+
+```typescript
+const [data, setData] = useState<T | null>(null)
+const [loading, setLoading] = useState(true)
+const [refreshing, setRefreshing] = useState(false)
+
+const fetchData = useCallback(async () => {
+  setRefreshing(true)
+  try {
+    const response = await fetch('/api/<endpoint>')
+    if (!response.ok) throw new Error('Failed')
+    setData(await response.json())
+  } catch {
+    console.error('Failed to fetch <endpoint>')
+  } finally {
+    setLoading(false)
+    setRefreshing(false)
+  }
+}, [])
+
+useEffect(() => { fetchData() }, [fetchData])
+```
+
+## Estados de UI
+
+- **Loading**: Spinner animado com ícone específico do painel
+- **Error**: Console.error (sem toast — minimalista)
+- **Empty**: `if (!data) return null` (protecção de render)
+- **Refreshing**: Ícone RefreshCw com animação `animate-spin`
+
+## Localizações
+
+- **Código**: Padrão replicado em cada `src/pages/*.tsx` (não extraído para hook — simplicidade)
+- **Sessions API**: `src/lib/api/sessions.ts` (único módulo de API extraído)
+
+## Dependências
+
+- **Express-API**: Todos os endpoints REST
+- **Dashboard-Engine**: Ciclo de vida React (mount/unmount)
+- **Metrics**: Eventos de fetch (latência, erros)
+
+## Fornece a
+
+- **Todos os 9 painéis**: Dados actualizados da API
+- **Metrics**: Telemetria de fetch (tempo de resposta, taxa de erro)
@@ -0,0 +1,75 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, engine, frontend, core]
+title: "Dashboard-Engine"
+---
+
+# Dashboard-Engine
+
+Motor central da aplicação DashDescomplicar. Orquestra layout, navegação, autenticação e ciclo de dados entre API e painéis.
+
+## Responsabilidades
+
+- **Layout**: Sidebar (9 itens) + Main Content area com glass-morphism design
+- **Roteamento**: React Router DOM 7 — `/` (Dashboard), `/monitor`, `/financial`, `/mcps`, `/n8n`, `/paperclip`, `/ai`, `/operations`, `/sessions`
+- **Autenticação**: OIDC opcional (`react-oidc-context`) + rate-limit (100 req/15min)
+- **Data Fetching**: `useEffect` + `useCallback` com reconnection logic
+- **Componentes Compartilhados**: `HeroStat`, `GlassCard`, `Sparkline`, `StatusPill`, `ProgressRing`, `ListItem`, `SummaryWidget`
+- **Animações**: Framer Motion (`containerVariants`, `itemVariants` com stagger)
+- **Dashboard Principal**: 16 queries paralelas ao Desk CRM (tarefas, tickets, leads, projectos, calendário, pipeline, timesheet, billing 360)
+
+## Stack
+
+- **React 19** + TypeScript 5.9
+- **Vite 7** (build, proxy `/api` → `localhost:3001`)
+- **Tailwind CSS 4** (glass-card, dark theme)
+- **Framer Motion 12** (stagger animations, spring physics)
+- **Lucide React** (ícones — 25+ importados)
+- **Recharts 3** (gráficos: Bar, Pie, Line, Sparkline)
+- **React Router DOM 7** (BrowserRouter, Routes, Link)
+
+## Localizações
+
+- **Código**: `Dev/DashDescomplicar/src/App.tsx` (894 linhas)
+- **Layout**: `src/components/Layout.tsx` (sidebar, navegação)
+- **Deploy**: `dash.descomplicar.pt` (EasyPanel Swarm)
+- **Repo**: `git.descomplicar.pt/ealmeida/DashDescomplicar`
+- **Proxy Dev**: Vite proxy `/api` → `http://localhost:3001`
+
+## Arquitectura de Componentes
+
+```
+App.tsx
+├── Layout.tsx (sidebar + Outlet)
+│   ├── Logo + Nome
+│   ├── NavItem ×9 (Dashboard, Monitor, Financial, MCPs, n8n, Paperclip, AI, Operations, Sessions)
+│   └── Footer (versão, status)
+├── Páginas (lazy-loaded via React Router)
+│   ├── Dashboard (/) — App.tsx interno
+│   ├── Monitor (/monitor)
+│   ├── Financial (/financial)
+│   ├── McpMonitor (/mcps)
+│   ├── N8nMonitor (/n8n)
+│   ├── Paperclip (/paperclip)
+│   ├── AiOverview (/ai)
+│   ├── Operations (/operations)
+│   ├── Sessions (/sessions)
+│   └── SessionDetail (/sessions/:id)
+└── Componentes compartilhados
+    ├── GlassCard, HeroStat, Sparkline
+    ├── StatusPill, ProgressRing
+    └── SummaryWidget, ListItem
+```
+
+## Dependências
+
+- **Express-API**: 15 endpoints REST para dados
+- **CSR-Integration**: Camada de fetch, cache, reconnection
+- **Metrics**: Telemetria de renderização e interacção
+- **Todos os 9 painéis**: Renderizados via React Router
+
+## Fornece a
+
+- **Todos os painéis**: Layout, navegação, autenticação
+- **Utilizador**: Interface unificada `dash.descomplicar.pt`
@@ -0,0 +1,81 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, infra, docker, easypanel, deploy]
+title: "Docker-Deploy"
+---
+
+# Docker-Deploy
+
+Pipeline de containerização e deploy do DashDescomplicar via Docker + EasyPanel Swarm no servidor `easy` (VM 101, Proxmox).
+
+## Responsabilidades
+
+- **Build**: Imagem Docker multi-stage (`node:22-alpine`) com `npm ci` + build TypeScript
+- **Deploy**: `docker service update --force` no EasyPanel Swarm
+- **Runtime**: Node.js 22 Alpine, porta 3001, `NODE_ENV=production`
+- **Static Serving**: Express serve o bundle Vite (`dist/`) em produção
+- **Health**: `curl -sf https://dash.descomplicar.pt/api/health`
+
+## Stack
+
+- **Dockerfile**: 26 linhas, `node:22-alpine`
+- **Build**: `tsc -b && vite build && tsc -p api/tsconfig.json`
+- **Start**: `node api/dist/server.js` (compilado TS → JS)
+- **Procfile**: `web: node api/dist/server.js` (EasyPanel)
+- **Repo**: Gitea (`git.descomplicar.pt/ealmeida/DashDescomplicar`)
+
+## Pipeline de Deploy
+
+1. **Validar build local**: `npx tsc -b && npx vite build && npx tsc -p api/tsconfig.json`
+2. **Push Gitea**: `git push origin main` (HTTPS, owner `ealmeida`)
+3. **SSH easy**: `docker build -t easypanel/descomplicar/dashboard_descomplicar:latest .`
+4. **Redeploy**: `docker service update --force descomplicar_dashboard_descomplicar`
+5. **Verificar**: `curl -sf https://dash.descomplicar.pt/api/dashboard`
+
+## Variáveis de Ambiente (Container)
+
+```
+DB_HOST=176.9.3.158
+DB_USER=...
+DB_PASS=...
+DB_NAME=...
+WP_MONITOR_API_KEY=...
+HETZNER_TOKEN=...
+N8N_API_KEY=...
+BESZEL_URL=...
+BESZEL_EMAIL=...
+BESZEL_PASSWORD=...
+EASY_HOST=5.9.90.70
+EASY_USER=root
+EASY_PASS=...
+MCP_GATEWAY_URL=https://gateway.descomplicar.pt
+OBSERVABILIDADE_DB=/data/sessions.db
+NODE_ENV=production
+API_PORT=3001
+FRONTEND_URL=https://dash.descomplicar.pt
+```
+
+## Volumes
+
+- `/root/data/dashboard-descomplicar/sessions.db:/data/sessions.db` (SQLite sessions)
+
+## Localizações
+
+- **Dockerfile**: `Dev/DashDescomplicar/Dockerfile`
+- **Procfile**: `Dev/DashDescomplicar/Procfile`
+- **Código no servidor**: `/etc/easypanel/projects/descomplicar/dashboard_descomplicar/code/`
+- **Deploy**: `dash.descomplicar.pt` (EasyPanel Swarm, Traefik reverse proxy)
+
+## Dependências
+
+- **Gitea**: Push de código (`git.descomplicar.pt/ealmeida/DashDescomplicar`)
+- **EasyPanel Server**: SSH (`5.9.90.70:22`, user `root`, password auth)
+- **Express-API**: Servidor Node.js dentro do container
+- **MySQL-Pool**: Conexão ao CWP (`176.9.3.158:3306`)
+
+## Notas Operacionais
+
+- EasyPanel MCP (`redeploy_service`) está quebrado — usar SEMPRE SSH directo
+- Pre-commit hook (`Regra #47`): `npm audit --audit-level=moderate`
+- `.env` no `.gitignore` — nunca commitar credenciais
@@ -0,0 +1,82 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, express, api, core]
+title: "Express-API"
+---
+
+# Express-API
+
+Servidor backend Express 4 que expõe a REST API do DashDescomplicar. Orquestra 15 rotas, middleware de segurança e serve o frontend estático em produção.
+
+## Responsabilidades
+
+- **Roteamento**: 15 rotas REST (`/api/dashboard`, `/api/monitor`, `/api/hetzner`, `/api/wp-monitor`, `/api/server-metrics`, `/api/financial`, `/api/mcps`, `/api/n8n`, `/api/paperclip`, `/api/operations`, `/api/ai`, `/api/beszel`, `/api/sessions`, `/api/diagnostic`, `/api/health`)
+- **Segurança**: Rate limiting (100 req/15min produção, 1000/15min dev), CORS restrito, validação Zod em todas as rotas, OIDC opcional
+- **Error Handling**: UUIDs para tracking de erros, sem stack traces em produção, logs estruturados
+- **Static Serving**: Serve o bundle Vite (React SPA) em produção na porta 3001
+- **Health Check**: Endpoint `/health` (público) e `/api/health` (autenticado)
+
+## Stack
+
+- **Runtime**: Node.js 22+ (Alpine no Docker)
+- **Framework**: Express 4.19+ com TypeScript 5.9
+- **Validação**: Zod 4.3 (`z.object()`, `.passthrough()`, `z.coerce`)
+- **Rate Limit**: `express-rate-limit` 8.2
+- **CORS**: `cors` 2.8
+- **Auth**: `express-openid-connect` (opcional, via `OIDC_ENABLED`)
+- **DB Drivers**: `mysql2` 3.11 (promise), `ssh2` 1.17, `better-sqlite3` 12.9
+- **Observabilidade**: SQLite local (`~/.claude-work/sessions.db`) para sessões Claude Code
+
+## Localizações
+
+- **Código**: `Dev/DashDescomplicar/api/server.ts` (238 linhas)
+- **Rotas**: `api/routes/` (14 ficheiros)
+- **Serviços**: `api/services/` (16 ficheiros)
+- **Middleware**: `api/middleware/validation.ts`
+- **DB Pool**: `api/db.ts`
+- **Deploy**: `dash.descomplicar.pt:3001` (EasyPanel Swarm)
+- **Dev**: `http://localhost:3001` (tsx watch)
+
+## Rotas Expostas
+
+| Rota | Ficheiro | Fonte Dados |
+|---|---|---|
+| `GET /api/dashboard` | `routes/dashboard.ts` | Desk CRM MySQL (16 queries paralelas) |
+| `GET /api/monitor` | `routes/monitor.ts` | `tbl_eal_monitoring` (MySQL) |
+| `GET /api/diagnostic` | `routes/diagnostic.ts` | Testes de conectividade (17 checks) |
+| `GET/POST /api/hetzner` | `routes/hetzner.ts` | Hetzner Cloud API + MySQL |
+| `GET/POST /api/wp-monitor` | `routes/wp-monitor.ts` | Plugin WP → MySQL (API key auth) |
+| `POST /api/server-metrics` | `routes/server-metrics.ts` | SSH2 (EasyPanel) + MySQL |
+| `GET /api/financial` | `routes/financial.ts` | Desk CRM MySQL (7 queries) |
+| `GET /api/mcps` | `routes/mcps.ts` | MCP Gateway (HTTP ping, cache 60s) |
+| `GET /api/n8n` | `routes/n8n.ts` | n8n REST API (cache 300s) |
+| `GET /api/paperclip` | `routes/paperclip.ts` | PostgreSQL Paperclip (com fallback) |
+| `GET /api/operations` | `routes/operations.ts` | Desk CRM MySQL (4 queries) |
+| `GET /api/ai` | `routes/ai.ts` | Dados estáticos (snapshot STK) |
+| `GET /api/beszel` | `routes/beszel.ts` | Beszel PocketBase API + MySQL |
+| `GET /api/sessions` | `routes/sessions.ts` | SQLite local (better-sqlite3) |
+
+## Dependências
+
+- **MySQL-Pool**: Conexão ao Desk CRM (`176.9.3.158`)
+- **Variáveis de Ambiente**: `DB_*`, `HETZNER_TOKEN`, `WP_MONITOR_API_KEY`, `N8N_API_KEY`, `BESZEL_*`, `EASY_*`, `MCP_GATEWAY_*`, `OIDC_*`, `OBSERVABILIDADE_DB`
+- **Docker-Deploy**: Empacotado via `Dockerfile` → EasyPanel Swarm
+- **Observabilidade-Sessions**: Abre ligação SQLite para sessões Claude Code
+
+## Consome de
+
+- Desk CRM (MySQL — `176.9.3.158:3306`)
+- Hetzner Cloud API (`api.hetzner.cloud/v1`)
+- MCP Gateway (`gateway.descomplicar.pt`)
+- n8n API (`automator.descomplicar.pt/api/v1`)
+- Paperclip PostgreSQL (container Docker)
+- Beszel PocketBase API
+- EasyPanel Server (SSH2 porta 22)
+- Sistema de ficheiros local (SQLite sessions.db)
+
+## Fornece a
+
+- Todos os 8 painéis frontend (via fetch à API)
+- Dashboard-Engine (dados agregados para `App.tsx`)
+- Sistema de diagnóstico (`/api/diagnostic`)
@@ -0,0 +1,55 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, integracao, beszel, monitorizacao]
+title: "Integracao-Beszel"
+---
+
+# Integracao-Beszel
+
+Integração com Beszel Hub (PocketBase API) para monitorização de frota de sistemas. Recolhe métricas de CPU, RAM, disco, containers e uptime de múltiplos hosts.
+
+## Responsabilidades
+
+- **Auth**: Autenticação PocketBase (token JWT com cache)
+- **Fleet Collection**: Recolher métricas de todos os sistemas Beszel
+- **Storage**: Guardar métricas em `tbl_eal_monitoring` (MySQL)
+- **Dashboard**: Agregar total/up/down por sistema
+
+## Stack
+
+- **API**: PocketBase (`descomplicar-beszel.i7zsqo.easypanel.host`)
+- **Auth**: Email + password → JWT token (cache em memória)
+- **Validação**: Zod 4.3 (`BeszelSystemInfo`, `BeszelSystem`, `BeszelListResponse`)
+- **DB**: MySQL via `db.ts`
+
+## Rotas
+
+| Método | Rota | Função |
+|---|---|---|
+| `GET` | `/api/beszel` | Fleet data do MySQL |
+| `POST` | `/api/beszel/collect` | Trigger fresh collection |
+
+## Sistemas Ignorados
+
+- `black`, `hp`, `kriku` — Tor exit nodes que duplicam máquinas reais
+
+## Tipos de Dados
+
+- `FleetSummary`: total, up, down, systems[]
+- `FleetSystem`: name, host, status, cpu, mem, disk, containers, load, uptime
+
+## Localizações
+
+- **Código**: `api/services/beszel.ts` (249 linhas), `api/routes/beszel.ts` (37 linhas)
+- **DB**: `tbl_eal_monitoring` (category=beszel)
+
+## Dependências
+
+- **Beszel Hub**: PocketBase API (`BESZEL_URL`, `BESZEL_EMAIL`, `BESZEL_PASSWORD`)
+- **MySQL-Pool**: Armazenamento de métricas
+
+## Fornece a
+
+- **Painel-Monitor**: Dados de fleet exibidos na secção "Frota Beszel"
+- **Express-API**: Rota `/api/beszel`
@@ -0,0 +1,57 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, integracao, hetzner, api]
+title: "Integracao-Hetzner"
+---
+
+# Integracao-Hetzner
+
+Integração com Hetzner Cloud API para monitorização de servidores VPS. Sincroniza lista de servidores, recolhe métricas (CPU, disco, rede) e armazena histórico na MySQL do Desk CRM.
+
+## Responsabilidades
+
+- **Sync**: Sincronizar lista de servidores da API Hetzner → `tbl_eal_hetzner_servers`
+- **Métricas**: Recolher CPU%, disk IOPS, network BPS via `/servers/{id}/metrics`
+- **Dashboard**: Agregar servidores + últimas métricas para o painel Monitor
+- **Histórico**: Armazenar métricas em `tbl_eal_hetzner_metrics` para gráficos
+- **Cleanup**: Limpeza de métricas antigas (>30 dias)
+
+## Stack
+
+- **API**: `https://api.hetzner.cloud/v1` (Bearer token `HETZNER_TOKEN`)
+- **DB**: MySQL via `db.ts` (pool)
+- **Validação**: Tipos TypeScript (sem Zod nesta rota)
+
+## Rotas
+
+| Método | Rota | Função |
+|---|---|---|
+| `GET` | `/api/hetzner` | Dashboard (servidores + últimas métricas) |
+| `POST` | `/api/hetzner/sync` | Sincronizar lista de servidores |
+| `POST` | `/api/hetzner/collect` | Recolher métricas de todos os servidores |
+| `POST` | `/api/hetzner/collect/:hetzner_id` | Recolher métricas de servidor específico |
+| `GET` | `/api/hetzner/history/:server_id` | Histórico de métricas para gráficos |
+| `POST` | `/api/hetzner/cleanup` | Limpar métricas antigas |
+
+## Servidores Monitorizados
+
+- **CWP Server** (VM 100): IP `5.9.90.105` — hosting clientes
+- **EasyPanel** (VM 101): IP `5.9.90.70` — Docker Swarm (46 serviços)
+- **Gateway** (VM 103): proxy Nginx
+- **Proxmox Host**: hypervisor físico
+
+## Localizações
+
+- **Código**: `api/services/hetzner.ts` (266 linhas), `api/routes/hetzner.ts` (141 linhas)
+- **DB**: `tbl_eal_hetzner_servers`, `tbl_eal_hetzner_metrics`
+
+## Dependências
+
+- **Hetzner Cloud API**: Token `HETZNER_TOKEN` em `.env`
+- **MySQL-Pool**: Armazenamento de servidores e métricas
+
+## Fornece a
+
+- **Painel-Monitor**: Dados de servidores exibidos na secção "Servidores"
+- **Express-API**: Rota `/api/hetzner`
@@ -0,0 +1,58 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, integracao, mcp, gateway]
+title: "Integracao-MCP-Gateway"
+---
+
+# Integracao-MCP-Gateway
+
+Monitorização do MCP Gateway (`gateway.descomplicar.pt`). Faz ping paralelo a 32 MCPs registados e expõe estado (online/offline/disabled) com cache de 60 segundos.
+
+## Responsabilidades
+
+- **Ping Paralelo**: Verifica health de cada MCP via HTTP (timeout 5s)
+- **Gateway Status**: Verifica se o gateway está online
+- **Categorização**: CRM, Infra, AI, Tools, External, Gateway, Project
+- **Cache**: 60 segundos TTL para evitar sobrecarga
+- **Auth Info**: Expõe método de autenticação e expiração do token
+
+## Stack
+
+- **Gateway**: `https://gateway.descomplicar.pt`
+- **Auth**: `MCP_GATEWAY_TOKEN` (Bearer)
+- **Ping**: HTTP GET com timeout 5s por MCP
+- **Cache**: Em memória, 60s TTL
+
+## MCPs Monitorizados (32)
+
+| Categoria | MCPs | Exemplos |
+|---|---|---|
+| CRM | 2 | desk-crm-v3 (3150), desk-project-minimal (3153, disabled) |
+| Infra | 3 | ssh-unified (3192), filesystem, chrome-devtools |
+| AI | 5 | lightrag (3160), memory-supabase (3151), notebooklm (3190) |
+| Tools | 5 | mcp-time (3155), deepl (3188), pexels, vimeo, drawio |
+| External | 9 | google-workspace (3156), gitea (3162), moloni (3158), n8n |
+| Gateway | 4 | authentik, spaceship, puppeteer, lighthouse |
+| Project | 2 | carl-mcp, reonic |
+
+## Rotas
+
+| Método | Rota | Função |
+|---|---|---|
+| `GET` | `/api/mcps` | Dashboard com estado de todos os MCPs |
+
+## Localizações
+
+- **Código**: `api/services/mcps.ts` (219 linhas), `api/routes/mcps.ts` (24 linhas)
+
+## Dependências
+
+- **MCP Gateway**: `MCP_GATEWAY_URL` e `MCP_GATEWAY_TOKEN`
+- **Express-API**: Rota `/api/mcps`
+
+## Fornece a
+
+- **Painel-MCPs**: Estado de todos os MCPs (online/offline/disabled)
+- **Painel-IA**: Camada 1 (Claude Code) — contagem de MCPs
+- **Express-API**: Rota `/api/mcps`
@@ -0,0 +1,50 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, integracao, n8n, automacoes]
+title: "Integracao-N8n-API"
+---
+
+# Integracao-N8n-API
+
+Integração com a API REST do n8n para monitorização de workflows determinísticos. Consulta workflows e execuções e expõe dashboard agregado com cache de 5 minutos.
+
+## Responsabilidades
+
+- **Workflows**: Listar todos os workflows (activos/inactivos)
+- **Execuções**: Última execução por workflow (status, duração)
+- **Falhas 24h**: Contagem de execuções com erro nas últimas 24h
+- **Cache**: 300 segundos TTL em memória para evitar sobrecarga da API n8n
+
+## Stack
+
+- **API**: `automator.descomplicar.pt/api/v1` (REST)
+- **Auth**: `X-N8N-API-KEY` header
+- **Cache**: Em memória (objecto, não Redis), 300s TTL
+- **Validação**: Tipos TypeScript (sem Zod)
+
+## Tipos
+
+- `N8nWorkflow`: id, name, active, last_execution, tags
+- `N8nDashboard`: total, active, inactive, failed_24h, workflows[], last_updated
+
+## Rotas
+
+| Método | Rota | Função |
+|---|---|---|
+| `GET` | `/api/n8n` | Dashboard agregado |
+
+## Localizações
+
+- **Código**: `api/services/n8n.ts` (183 linhas), `api/routes/n8n.ts` (24 linhas)
+
+## Dependências
+
+- **n8n API**: `N8N_API_KEY` e `N8N_API_URL` em `.env`
+- **Express-API**: Rota `/api/n8n`
+
+## Fornece a
+
+- **Painel-N8n**: Workflows, execuções, falhas
+- **Painel-IA**: Camada 2 (Determinístico) — contagem de workflows
+- **Express-API**: Rota `/api/n8n`
@@ -0,0 +1,53 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, integracao, ssh, metricas]
+title: "Integracao-SSH-Metrics"
+---
+
+# Integracao-SSH-Metrics
+
+Colector de métricas de servidores via SSH (biblioteca `ssh2`). Recolhe CPU, RAM, disco, load e containers do EasyPanel Server.
+
+## Responsabilidades
+
+- **SSH Connection**: Ligação ao EasyPanel (`5.9.90.70:22`) com password auth
+- **Métricas**: Executa comandos remotos para recolher CPU%, RAM%, disco%, load avg, nº containers
+- **Parsing**: Extrai valores de output formatado (`CPU:`, `MEM:`, `DISK:`, `LOAD:`, `CONTAINERS:`)
+- **Sync**: Sincroniza servidores Hetzner para `tbl_eal_monitoring`
+
+## Stack
+
+- **Library**: `ssh2` 1.17 (Client, exec)
+- **Timeout**: 20 segundos por ligação SSH
+- **Auth**: Password (não suporta chave privada no container)
+
+## Servidores
+
+| Nome | Host | Porta | Auth | Notas |
+|---|---|---|---|---|
+| EasyPanel | `5.9.90.70` | 22 | Password | Docker Swarm — 46 serviços |
+| CWP Server | `5.9.90.105` | 22 | ❌ Chave ed25519 | NÃO acessível do container |
+
+## Rotas
+
+| Método | Rota | Função |
+|---|---|---|
+| `POST` | `/api/server-metrics/collect` | Recolher todas as métricas |
+| `POST` | `/api/server-metrics/ssh` | Apenas métricas SSH |
+| `POST` | `/api/server-metrics/hetzner` | Sync Hetzner → monitoring |
+
+## Localizações
+
+- **Código**: `api/services/server-metrics.ts` (188 linhas), `api/routes/server-metrics.ts` (68 linhas)
+- **DB**: `tbl_eal_monitoring`
+
+## Dependências
+
+- **EasyPanel Server**: SSH acesso (`.env`: `EASY_HOST`, `EASY_USER`, `EASY_PASS`)
+- **MySQL-Pool**: Armazenamento de métricas
+
+## Fornece a
+
+- **Painel-Monitor**: Métricas SSH exibidas na secção "Infraestrutura"
+- **Express-API**: Rota `/api/server-metrics`
@@ -0,0 +1,56 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, integracao, wordpress, monitorizacao]
+title: "Integracao-WordPress"
+---
+
+# Integracao-WordPress
+
+Ingestão de dados de monitorização de sites WordPress. Recebe dados do plugin "Descomplicar Monitor" instalado em cada site cliente e armazena na base de dados para o painel Monitor.
+
+## Responsabilidades
+
+- **Ingestão**: Endpoint POST para receber dados dos plugins WP (versão WP, plugins, temas, health status)
+- **API Key Auth**: Validação obrigatória via header `x-api-key` ou query param `key`
+- **Determinação de Status**: Algoritmo que classifica o site como `ok`, `warning` ou `critical` baseado em:
+  - Core/plugins/themes desactualizados
+  - Erros de saúde (health check)
+  - Versão PHP
+- **Listagem**: GET para listar todos os sites monitorizados
+- **Connection Test**: `GET ?test` para verificar conectividade
+
+## Stack
+
+- **Validação**: Zod (`wpMonitorSchema`) com `.passthrough()` para campos extra de plugins
+- **Auth**: `WP_MONITOR_API_KEY` obrigatória (crash ao iniciar se ausente)
+- **DB**: MySQL via `db.ts`
+
+## Schema de Dados (Plugin WP → API)
+
+Recebe: `site_url`, `wp_version`, `php_version`, `plugins[]`, `themes[]`, `health_status`, `server_info`
+
+## Rotas
+
+| Método | Rota | Auth | Função |
+|---|---|---|---|
+| `GET` | `/api/wp-monitor` | API Key | Listar sites monitorizados |
+| `GET` | `/api/wp-monitor?test` | API Key | Teste de conectividade |
+| `POST` | `/api/wp-monitor` | API Key + Zod | Receber dados do plugin WP |
+
+## Localizações
+
+- **Código**: `api/routes/wp-monitor.ts` (148 linhas)
+- **DB**: `tbl_eal_monitoring` (category=wordpress)
+- **Plugin**: "Descomplicar Monitor" (instalado nos sites cliente)
+
+## Dependências
+
+- **MySQL-Pool**: Armazenamento de dados
+- **WP_MONITOR_API_KEY**: Chave de API em `.env`
+- **Plugins WP nos sites cliente**: Enviam dados periodicamente
+
+## Fornece a
+
+- **Painel-Monitor**: Secção "Sites WordPress" e "WP Updates"
+- **Express-API**: Rota `/api/wp-monitor`
@@ -0,0 +1,91 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, telemetria, observabilidade, metricas]
+title: "Metrics"
+---
+
+# Metrics
+
+Sistema de telemetria e observabilidade do DashDescomplicar. Recolhe métricas de performance, disponibilidade e negócio em todas as camadas (frontend, API, infraestrutura).
+
+## Responsabilidades
+
+- **API Performance**: Tempo de resposta por endpoint, latência, taxa de erro
+- **Frontend**: Tempo de renderização, tamanho de bundle, LCP, FID, CLS
+- **Infraestrutura**: CPU, RAM, Disk dos servidores monitorados (via SSH + Hetzner + Beszel)
+- **Disponibilidade**: Uptime dos sistemas integrados (MCP Gateway, n8n, Paperclip)
+- **Negócio**: Vendas, despesas, lucro, tickets, leads (via Desk CRM)
+- **Observabilidade**: Sessões Claude Code, tool calls, skills, padrões de uso
+
+## Dimensões Recolhidas
+
+### API
+- Latência por endpoint (ms)
+- Taxa de erro (4xx/5xx)
+- Rate limit hits
+
+### Frontend
+- Tempo de renderização inicial (mount → data)
+- Tamanho de bundle (Vite build)
+- Core Web Vitals (LCP, FID, CLS)
+
+### Infraestrutura
+- CPU% por servidor (Hetzner, Beszel, SSH)
+- RAM% por servidor
+- Disk% por servidor
+- Load average
+- Containers Docker activos
+
+### Disponibilidade
+- MCP Gateway (32 MCPs — online/offline)
+- n8n workflows (activos/falhas)
+- Paperclip agentes (activos/idle/erro)
+- Sites WordPress (ok/warning/critical)
+
+### Negócio
+- Vendas mês/ano (EUR)
+- Despesas mês/ano (EUR)
+- Tickets abertos/prioridade
+- Leads em pipeline
+
+### Observabilidade (Sessões)
+- Sessões Claude Code / dia
+- Tool calls / sessão
+- Skills invocadas
+- Projectos activos
+- Padrões de erro
+- Duração média de sessão
+
+## Stack
+
+- **Colectores**: Scripts Python (Gemini), Node.js (sessions-indexer), MySQL queries
+- **Armazenamento**: SQLite (`sessions.db`), MySQL (`tbl_eal_monitoring`, `tbl_eal_hetzner_metrics`)
+- **Exposição**: Endpoints REST (não Prometheus — planeado)
+- **Logs**: `logs/performance-metrics.json` (180B — inicial)
+
+## Localizações
+
+- **Logs**: `logs/performance-metrics.json`
+- **Sessions DB**: `~/.claude-work/sessions.db`
+- **Monitoring DB**: `tbl_eal_monitoring` (MySQL)
+- **Hetzner Metrics**: `tbl_eal_hetzner_metrics` (MySQL)
+- **Gemini Logs**: `~/.claude-work/tool-invocations.jsonl`
+
+## Consome de
+
+- **Dashboard-Engine**: Eventos de renderização
+- **Express-API**: Latência, erros (middleware)
+- **Painéis**: Eventos de interacção, fetch timing
+- **Systemd-Timers**: Indexação de sessões
+- **Monitorizacao-Gemini**: Telemetria Gemini
+- **Integracao-Hetzner**: Métricas de servidores
+- **Integracao-SSH-Metrics**: Métricas SSH
+- **Integracao-Beszel**: Fleet metrics
+
+## Fornece a
+
+- **Painel-Monitor**: Métricas de infra agregadas
+- **Painel-Financeiro**: Métricas de negócio
+- **Painel-Sessoes**: Dados de observabilidade
+- **Sistema IA**: Padrões de uso, anomalias
@@ -0,0 +1,61 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, infra, monitorizacao, gemini, telemetria]
+title: "Monitorizacao-Gemini"
+---
+
+# Monitorizacao-Gemini
+
+Sistema de telemetria para hooks do Gemini CLI. Recolhe métricas de tool calls do Gemini e escreve no mesmo ficheiro JSONL usado pelo Claude Code para métricas unificadas.
+
+## Responsabilidades
+
+- **Hook AfterTool**: Captura tool_name, session_id, success/error, duration
+- **Formato Unificado**: Escreve em `~/.claude-work/tool-invocations.jsonl` com campo `engine: gemini`
+- **Pré-Telemetria**: Script `gemini-pre-telemetry.py` regista timestamp de início para cálculo de duração
+- **Health Check**: `gemini-health.sh` verifica conectividade do Gemini CLI
+
+## Stack
+
+- **Python 3**: Scripts de hook (piped via stdin/stdout do Gemini CLI)
+- **Formato**: JSONL (compatível com Claude Code)
+- **Ficheiro**: `~/.claude-work/tool-invocations.jsonl`
+
+## Scripts
+
+| Script | Função | Trigger |
+|---|---|---|
+| `gemini-telemetry.py` (2.3KB) | Hook AfterTool — captura e regista métricas | Gemini CLI after tool call |
+| `gemini-pre-telemetry.py` (1.0KB) | Hook BeforeTool — regista timestamp início | Gemini CLI before tool call |
+| `gemini-health.sh` (1.0KB) | Health check conectividade Gemini | Manual/agendado |
+
+## Formato de Log
+
+```json
+{
+  "ts": "2026-06-30T12:00:00Z",
+  "session": "<session_id>",
+  "tool_name": "read_file",
+  "success": true,
+  "error": "",
+  "duration": 1.23,
+  "engine": "gemini"
+}
+```
+
+## Localizações
+
+- **Scripts**: `Dev/DashDescomplicar/monitorizacao/` (3 ficheiros)
+- **Output**: `~/.claude-work/tool-invocations.jsonl`
+- **Temp**: `~/.gemini/tmp/telemetry/<session_id>.start`
+
+## Dependências
+
+- **Gemini CLI**: Pipe stdin/stdout para hooks Python
+- **Sistema de Ficheiros**: `~/.claude-work/`, `~/.gemini/tmp/`
+
+## Fornece a
+
+- **Observabilidade-Sessions**: Dados de telemetria Gemini unificados com Claude
+- **Sistema IA**: Métricas cross-engine (Claude + Gemini + Hermes + OpenCode)
@@ -0,0 +1,57 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, mysql, database, core]
+title: "MySQL-Pool"
+---
+
+# MySQL-Pool
+
+Pool de ligações MySQL2 (promise) ao Desk CRM Perfex. Fonte de verdade para dados de tarefas, projectos, tickets, facturação, despesas, leads e monitorização.
+
+## Responsabilidades
+
+- **Connection Pool**: 10 ligações máx, timeout 10s connect / 15s acquire / 30s query
+- **Validação**: Credenciais obrigatórias (`DB_USER`, `DB_PASS`, `DB_NAME`) — crash ao iniciar se ausentes
+- **Charset**: `utf8mb4` para suporte completo a caracteres PT-PT
+- **Health Check**: Teste automático ao iniciar (`pool.getConnection()`)
+
+## Stack
+
+- **Driver**: `mysql2` 3.11 (modo promise)
+- **Host**: `176.9.3.158` (servidor CWP)
+- **Base de Dados**: `ealmeida_desk24` (Perfex CRM)
+- **Prefixo**: `DB_*` (NÃO `MYSQL_*`)
+
+## Tabelas Consumidas
+
+| Tabela | Consumidor | Uso |
+|---|---|---|
+| `tbltasks` | dashboard.ts, operations.ts | Tarefas (urgentes, alta, vencidas) |
+| `tblprojects` | dashboard.ts | Projectos (JOIN com tasks) |
+| `tbltickets` | dashboard.ts, operations.ts | Tickets suporte (abertos, prioridade, departamento) |
+| `tblinvoices` | financial.ts | Facturas (vendas mês/ano, evolução) |
+| `tblexpenses` | financial.ts | Despesas (mês/ano, categorias) |
+| `tblexpenses_categories` | financial.ts | Categorias despesas (JOIN) |
+| `tblleads` | dashboard.ts | Leads (contactar, followup, proposta) |
+| `tbltaskstimers` | dashboard.ts | Timesheet (horas registadas) |
+| `tbldepartments` | operations.ts | Departamentos tickets |
+| `tbl_eal_monitoring` | monitoring.ts | Monitorização (items, categorias, status) |
+| `tbl_eal_hetzner_servers` | hetzner.ts | Servidores Hetzner (sync, métricas) |
+| `tbl_eal_hetzner_metrics` | hetzner.ts | Histórico métricas Hetzner |
+
+## Localizações
+
+- **Código**: `Dev/DashDescomplicar/api/db.ts` (42 linhas)
+- **Config**: `.env` (`DB_HOST`, `DB_USER`, `DB_PASS`, `DB_NAME`)
+- **Host**: CWP Server (VM 100, IP `5.9.90.105`)
+
+## Dependências
+
+- `.env` com `DB_HOST`, `DB_USER`, `DB_PASS`, `DB_NAME`
+- Servidor MySQL no CWP (porta 3306, reachable do EasyPanel)
+
+## Fornece a
+
+- **Express-API**: Todas as rotas que consomem Desk CRM
+- **Serviços**: dashboard, financial, operations, monitoring, hetzner, server-metrics
@@ -0,0 +1,80 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, observabilidade, sessoes, sqlite, systemd]
+title: "Observabilidade-Sessions"
+---
+
+# Observabilidade-Sessions
+
+Sistema de observabilidade de sessões Claude Code (Espelho). Indexa, armazena e expõe dados de sessões de múltiplos motores IA (Claude Code, Hermes, OpenCode) via SQLite local.
+
+## Responsabilidades
+
+- **Indexação**: Watcher incremental de ficheiros JSONL (Claude Code) + import de BD (Hermes SQLite, OpenCode SQLite)
+- **Armazenamento**: SQLite local (`~/.claude-work/sessions.db`) com schema optimizado
+- **Worklog Import**: Import de worklogs Desk CRM (discussions #31/#32/#33)
+- **Pattern Detection**: Detecção semanal de padrões de uso (tools, skills, erros)
+- **API**: Rota `/api/sessions` (lista + detalhe com eventos)
+- **Sincronização**: Volume bind EasyPanel (`/root/data/dashboard-descomplicar/sessions.db` → `/data/sessions.db`)
+
+## Stack
+
+- **DB**: `better-sqlite3` 12.9 (síncrono, zero-deps)
+- **Watcher**: `chokidar` 5.0 (file system events)
+- **Parser**: `node-html-parser` 7.1 (extração HTML de worklogs)
+- **Runtime**: Node.js 22 via `tsx` (systemd services)
+
+## Componentes do Sistema
+
+| Componente | Ficheiro | Função |
+|---|---|---|
+| Indexer | `api/scripts/sessions-indexer.ts` | Watcher incremental de JSONL |
+| Patterns | `api/scripts/sessions-patterns.ts` | Detector semanal de padrões |
+| Worklog Import | `api/scripts/sessions-worklog-import.ts` | Import de worklogs Desk |
+| DB Layer | `api/services/sessions/db.ts` | Schema, queries, CRUD |
+| Parser | `api/services/sessions/parser.ts` | Parse de ficheiros JSONL |
+| Claude Indexer | `api/services/sessions/indexer.ts` | Indexação específica Claude |
+| Hermes Indexer | `api/services/sessions/hermes-indexer.ts` | Indexação Hermes (`~/.hermes/state.db`) |
+| OpenCode Indexer | `api/services/sessions/opencode-indexer.ts` | Indexação OpenCode (`~/.local/share/opencode/opencode.db`) |
+| MCP Client | `api/services/sessions/mcp-client.ts` | Cliente MCP para Desk CRM |
+| Watcher | `api/services/sessions/watcher.ts` | File watcher eventos |
+| Patterns Engine | `api/services/sessions/patterns.ts` | Análise de padrões (19KB) |
+
+## Fontes de Dados
+
+- **Claude Code**: `~/.claude/projects/*/sessions/*.jsonl` (JSONL)
+- **Hermes**: `~/.hermes/state.db` (SQLite)
+- **OpenCode**: `~/.local/share/opencode/opencode.db` (SQLite)
+- **Gemini**: `~/.claude-work/tool-invocations.jsonl` (via Gemini-Telemetry)
+- **Desk CRM**: Discussions #31, #32, #33 (worklogs)
+
+## Systemd Timers
+
+| Timer | Schedule | Função |
+|---|---|---|
+| `observabilidade-indexer.service` | Sempre ligado (simple) | Watcher incremental |
+| `observabilidade-worklog-import.timer` | Diário 03:00 | Import worklogs Desk |
+| `observabilidade-patterns.timer` | Dom 23:00 | Detecção de padrões |
+
+## Localizações
+
+- **SQLite DB**: `~/.claude-work/sessions.db` (local) / `/data/sessions.db` (container)
+- **Código**: `api/services/sessions/` (10 ficheiros, ~56KB)
+- **Scripts**: `api/scripts/sessions-*.ts` (3 scripts)
+- **Systemd**: `systemd/observabilidade-*.{service,timer}` (5 ficheiros)
+- **Volume**: `/root/data/dashboard-descomplicar/sessions.db` → container
+
+## Dependências
+
+- **Systemd-Timers**: Execução agendada dos scripts
+- **Gemini-Telemetry**: Dados de telemetria Gemini
+- **MySQL-Pool**: Worklogs Desk CRM (discussions)
+- **Express-API**: Rota `/api/sessions` expõe dados
+- **Sistema de Ficheiros**: `~/.claude/`, `~/.hermes/`, `~/.local/share/opencode/`
+
+## Fornece a
+
+- **Painel-Sessoes**: Dados para listagem e detalhe
+- **Express-API**: Rota `/api/sessions`
+- **Sistema IA**: Métricas de uso, padrões, anomalias
@@ -0,0 +1,35 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, cron, proposto]
+title: "Painel-CronDev"
+---
+
+# Painel-CronDev
+
+Painel para todas as acções cron do servidor `dev` (CT 102 / systemd user timers).
+
+## Status
+
+- **Proposto** — não implementado ainda
+- Requisição: visibilidade agregada dos 9 agentes cron
+
+## Conteúdo planeado
+
+- Lista de jobs cron activos (schedule, último run, próximo run, duração, exit code)
+- Estado: OK / Warning / Erro / Stale (>24h sem correr)
+- Logs recentes (tail) por job, filtro e pesquisa
+- Alertas para falhas consecutivas (>2)
+- Acção manual "Run now" (opcional, autenticada)
+- Métricas: total jobs, sucessos 24h, falhas 24h, tempo médio
+
+## Fonte planeada
+
+- SSH ao `dev`
+- Leitura de `/var/log/` e logs de agentes
+- `systemctl --user list-timers`
+
+## Componente
+
+- **Localização**: `src/pages/CronDev.tsx` (proposto)
+- **Route**: `/cron-dev` (proposto)
@@ -0,0 +1,66 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, dashboard, home]
+title: "Painel-Dashboard"
+---
+
+# Painel-Dashboard
+
+Página principal (home) do DashDescomplicar. Hero stats agregados do Desk CRM com resumo do dia, tarefas, tickets, leads, projectos, pipeline e métricas de tempo.
+
+## Responsabilidades
+
+- **Hero Stats**: 5 métricas principais com sparklines, gradientes e tendências
+- **Resumo do Dia**: Data formatada PT-PT, eventos hoje, tarefas urgentes/alta, tickets abertos
+- **Tarefas**: Urgentes (priority 4), Alta (priority 3), Vencidas, Em Testes, Esta Semana
+- **Leads**: Contactar, Follow-up, Proposta — com pipeline stage
+- **Projectos**: Lista de projectos activos com progresso
+- **Calendário**: Eventos de hoje e da semana (Google Calendar via Desk)
+- **Timesheet**: Horas registadas hoje/semana
+- **Billing 360**: Facturação do mês com progress ring
+- **Pipeline**: Leads em pipeline por stage
+- **Monday Mood**: Frase motivacional (apenas às segundas)
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Framer Motion**: Stagger + spring + hover animations
+- **Lucide React**: 25+ ícones (Calendar, AlertTriangle, Clock, RefreshCw, etc.)
+- **Tailwind CSS**: Glass cards, gradientes, status pills
+- **Recharts**: Sparkline (mini gráfico de tendência)
+
+## Componentes
+
+- `HeroStat`: Métrica grande com ícone, gradiente, sparkline, tendência
+- `GlassCard`: Card com accent color e contador
+- `Sparkline`: Mini gráfico SVG de tendência
+- `StatusPill`: Badge de status (emerald, amber, red)
+- `ProgressRing`: Anel de progresso SVG circular
+- `SummaryWidget`: Widget bento-style com resumo do dia
+- `ListItem`: Item de lista com hover e badges
+
+## Tipos
+
+- `DashboardData`: date, day_of_week, is_monday, monday_mood, tarefas (urgente, alta, vencidas, em_testes, esta_semana), tickets (abertos, alta_prioridade), leads (contactar, proposta, followup), projectos[], pipeline[], eventos (hoje[], semana[]), timesheet (hoje, semana), billing_360, resumo
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| Dashboard | `GET /api/dashboard` | 16 queries paralelas ao Desk CRM |
+
+## Localizações
+
+- **Código**: `src/App.tsx` (função App(), linhas 416-818 + mock data)
+- **Rota**: `/`
+
+## Dependências
+
+- **Express-API**: Rota `/api/dashboard` (16 queries)
+- **MySQL-Pool**: Dados do Desk CRM (tarefas, tickets, leads, projectos, calendário, timesheet, facturação)
+- **Dashboard-Engine**: Layout (sidebar + header)
+
+## Estado
+
+- Activo
@@ -0,0 +1,63 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, financeiro, metricas]
+title: "Painel-Financeiro"
+---
+
+# Painel-Financeiro
+
+Painel de métricas financeiras do negócio Descomplicar®. Exibe receitas, despesas e lucro com gráficos de evolução e distribuição por categoria.
+
+## Responsabilidades
+
+- **Métricas Principais**: Vendas Mês, Vendas Ano, Despesas Mês, Despesas Ano, Lucro/Prejuízo
+- **Gráfico de Evolução**: Receita vs Despesa (últimos 12 meses) — Recharts BarChart
+- **Distribuição**: Despesas por categoria (pie chart visual)
+- **Formatação**: EUR com locale `pt-PT` (`formatEUR`)
+- **Estados**: Loading (pulse animation), Empty (null check), Error (console)
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Recharts 3**: BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, Legend
+- **Framer Motion**: Stagger animations
+- **Lucide React**: DollarSign, TrendingUp, TrendingDown, Receipt, PiggyBank
+- **Tailwind CSS**: Glass cards, status colors (emerald para lucro, red para prejuízo)
+
+## Tipos
+
+- `FinancialData`: vendas_mes, vendas_ano, despesas_mes, despesas_ano, lucro_mes, lucro_ano, categorias[] (name, value), evolucao[] (mes, receita, despesa)
+
+## Componentes
+
+- `StatCard`: Card de métrica com label, valor formatado, ícone, cor
+- `CustomTooltip`: Tooltip do Recharts com formatação EUR
+- `formatEUR`: Conversor para locale PT-PT
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| Financial | `GET /api/financial` | Agregados de vendas/despesas MySQL |
+
+## Fontes de Dados (via API)
+
+- **`tblinvoices`**: Facturas (não-draft, não-canceladas) — vendas mês/ano, evolução 12 meses
+- **`tblexpenses`**: Despesas — despesas mês/ano, categorias, evolução 12 meses
+- **`tblexpenses_categories`**: JOIN para nomes de categorias
+
+## Localizações
+
+- **Código**: `src/pages/Financial.tsx` (251 linhas)
+- **Rota**: `/financial`
+
+## Dependências
+
+- **Express-API**: Rota `/api/financial`
+- **MySQL-Pool**: Dados de facturação do Desk CRM
+- **Dashboard-Engine**: Layout, navegação
+
+## Estado
+
+- Activo
@@ -0,0 +1,62 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, ia, claude-code, stack]
+title: "Painel-IA"
+---
+
+# Painel-IA
+
+Painel de overview do ecossistema de IA Descomplicar®. Visualiza as 3 camadas de execução (Claude Code, n8n, Paperclip), sistemas transversais e configuração CARL.
+
+## Responsabilidades
+
+- **3 Camadas**: Claude Code (interactivo), n8n (determinístico), Paperclip (autónomo)
+- **Métricas por Camada**: Skills (189), Agents (72), MCPs (39), Hooks (9), Plugins (23), Workflows (14), Agentes Paperclip (16), Routines (5)
+- **Sistemas Transversais**: RAG/CARL, Anti-alucinação, Knowledge Graph (LightRAG), Auto-melhoria, Design
+- **CARL Config**: 8 domínios, 45 regras
+- **Notebooks**: 58 notebooks NotebookLM
+- **Design Visual**: Gradientes únicos por camada (violet=Claude, amber=n8n, cyan=Paperclip), glow effects
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Framer Motion**: Stagger + spring animations
+- **Lucide React**: Brain, Cpu, Bot, Zap, Shield, Database, BookOpen, Layers
+- **Tailwind CSS**: Gradient cards, badges coloridos
+
+## Tipos
+
+- `AiLayer`: name, label, items[] (metric, value, detail)
+- `TransversalSystem`: name, status (active|warning|inactive), detail
+- `CarlConfig`: domains[], total_rules
+- `AiDashboard`: layers[], transversal[], carl, notebooks, last_updated
+
+## Configuração Visual por Camada
+
+| Camada | Gradiente | Cor | Ícone |
+|---|---|---|---|
+| Claude Code | violet-500 → purple-500 | `text-violet-300` | Brain |
+| n8n | amber-500 → orange-500 | `text-amber-300` | Zap |
+| Paperclip | cyan-500 → teal-500 | `text-cyan-300` | Bot |
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| AI | `GET /api/ai` | Dados estáticos do stack (snapshot STK-Estado-Actual.md) |
+
+## Localizações
+
+- **Código**: `src/pages/AiOverview.tsx` (452 linhas)
+- **Rota**: `/ai`
+
+## Dependências
+
+- **Express-API**: Rota `/api/ai`
+- **STK-Estado-Actual.md**: Fonte estática de dados do stack
+- **Dashboard-Engine**: Layout, navegação
+
+## Estado
+
+- Activo — dados estáticos (snapshot 06-04-2026), a evoluir para dados dinâmicos
@@ -0,0 +1,57 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, mcps, gateway, monitorizacao]
+title: "Painel-MCPs"
+---
+
+# Painel-MCPs
+
+Painel de estado dos 39 MCPs do ecossistema Descomplicar®. Visualização em tempo real do gateway com categorização, status indicators e refresh manual.
+
+## Responsabilidades
+
+- **Visão Agregada**: Contadores Online / Offline / Disabled / Total
+- **Gateway Status**: Indicador de estado do gateway (online/offline)
+- **Categorização**: 7 categorias (CRM, Infra, AI, Tools, External, Gateway, Project) com ordenação fixa
+- **Detalhe por MCP**: Nome, porta, status, response time, tools count, última verificação
+- **Refresh Manual**: Botão "Actualizar" para forçar re-ping
+- **Auth Info**: Método de autenticação + expiração do token
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Framer Motion**: Stagger + spring animations
+- **Lucide React**: Network, Wifi, WifiOff, Server, CheckCircle2, XCircle, Clock
+- **Tailwind CSS**: Status colors (emerald=online, red=offline, zinc=disabled), glow effects
+
+## Tipos
+
+- `McpStatus`: name, port, category, enabled, status (online|offline|disabled|unknown), response_time_ms, last_check, tools_count
+- `McpDashboard`: gateway_status, total, online, offline, disabled, mcps[], auth
+
+## Componentes
+
+- `StatusIndicator`: Bolinha pulsante (online=emerald glow, offline=red pulse, disabled=zinc)
+- `McpCard`: Card individual com status, porta, response time
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| MCPs | `GET /api/mcps` | Gateway health + 32 MCPs com cache 60s |
+
+## Localizações
+
+- **Código**: `src/pages/McpMonitor.tsx` (362 linhas)
+- **Rota**: `/mcps`
+
+## Dependências
+
+- **Integracao-MCP-Gateway**: Ping aos 32 MCPs via gateway
+- **Express-API**: Rota `/api/mcps`
+- **Dashboard-Engine**: Layout, navegação
+
+## Estado
+
+- Activo
@@ -0,0 +1,62 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, monitor, infraestrutura]
+title: "Painel-Monitor"
+---
+
+# Painel-Monitor
+
+Painel de monitorização de infraestrutura e WordPress. Visualiza estado de servidores Proxmox, containers Docker, sites WordPress, backups e frota Beszel em tempo real.
+
+## Responsabilidades
+
+- **Infraestrutura**: Load, storage (NVMe, RAID1), containers Docker por servidor
+- **Servidores**: CWP Server (VM 100, QEMU), EasyPanel (VM 101, QEMU), Gateway (VM 103), Proxmox Host
+- **WordPress**: Sites monitorizados (status, actualizações pendentes)
+- **Frota Beszel**: Sistemas agregados via Beszel Hub (CPU, RAM, disco, containers, uptime)
+- **Backups**: Estado dos backups (último, tamanho, status)
+- **Alertas**: Itens com status warning/critical destacados
+- **Categorização**: Itens agrupados por categoria (infra, wordpress, backups, beszel, hetzner)
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Framer Motion** (stagger animations)
+- **Lucide React** (15+ ícones: Server, Container, HardDrive, Globe, Wifi, etc.)
+- **Tailwind CSS** (glass-card, status colors)
+
+## Tipos
+
+- `MonitorItem`: id, name, category, status, details (JSON), last_check
+- `CategorySummary`: category, total, ok, warning, critical
+- `MonitorData`: items (Record<category, MonitorItem[]>), summary, overall, stats
+- `VMConfig`: name, id, type (QEMU/LXC), ip, role, icon, accent colors
+- `FleetSystem`: name, host, status, cpu, mem, disk, containers, load, uptime
+- `FleetData`: total, up, down, systems[]
+
+## APIs Consumidas
+
+| API | Rota | Dados |
+|---|---|---|
+| Monitor | `GET /api/monitor` | Items de monitorização (MySQL `tbl_eal_monitoring`) |
+| Beszel | `GET /api/beszel` | Frota de sistemas Beszel |
+| Hetzner | `GET /api/hetzner` | Servidores Hetzner + métricas |
+
+## Localizações
+
+- **Código**: `src/pages/Monitor.tsx` (788 linhas — maior página)
+- **Rota**: `/monitor`
+
+## Dependências
+
+- **Express-API**: Rotas `/api/monitor`, `/api/beszel`, `/api/hetzner`
+- **Dashboard-Engine**: Layout, navegação
+- **Integracao-Hetzner**: Dados de servidores
+- **Integracao-Beszel**: Fleet data
+- **Integracao-WordPress**: Dados de sites WP
+- **Integracao-SSH-Metrics**: Métricas SSH
+
+## Estado
+
+- Activo (Fase C — com frota Beszel integrada 2026-06)
@@ -0,0 +1,57 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, n8n, automacoes, workflows]
+title: "Painel-N8n"
+---
+
+# Painel-N8n
+
+Painel de monitorização de workflows n8n (Camada 2 — Determinístico). Exibe estado de todos os workflows, execuções recentes e falhas.
+
+## Responsabilidades
+
+- **Métricas Principais**: Total Workflows, Activos, Inactivos, Falhas (24h)
+- **Lista de Workflows**: Nome, estado (activo/inactivo), última execução, duração, tags
+- **Status Badges**: Sucesso (emerald), Erro (red), Running, Pendente
+- **Formatação**: Duração em ms/s/min, datas em locale PT-PT
+- **Cache**: Dados com cache de 300s no backend
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Framer Motion**: Stagger animations
+- **Lucide React**: GitBranch, Play, Pause, CheckCircle2, XCircle, Clock, AlertTriangle
+- **Tailwind CSS**: Glass cards, highlight para falhas (borda red)
+
+## Tipos
+
+- `N8nWorkflow`: id, name, active, last_execution (status, started_at, finished_at, duration_ms), tags
+- `N8nDashboard`: total, active, inactive, failed_24h, workflows[], last_updated
+
+## Componentes
+
+- `StatCard`: Métrica agregada com highlight condicional (red se falhas > 0)
+- `StatusBadge`: Pill com ícone e cor por status
+- `formatDuration`, `formatDate`, `formatLastUpdated`: Utilitários PT-PT
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| n8n | `GET /api/n8n` | Workflows + execuções (cache 300s) |
+
+## Localizações
+
+- **Código**: `src/pages/N8nMonitor.tsx` (382 linhas)
+- **Rota**: `/n8n`
+
+## Dependências
+
+- **Integracao-N8n-API**: n8n REST API (`automator.descomplicar.pt`)
+- **Express-API**: Rota `/api/n8n`
+- **Dashboard-Engine**: Layout, navegação
+
+## Estado
+
+- Activo
@@ -0,0 +1,71 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, operacoes, tickets, procs]
+title: "Painel-Operacoes"
+---
+
+# Painel-Operacoes
+
+Painel de gestão operacional via Desk CRM. Exibe tickets abertos, prioridades, distribuição por departamento e cobertura de PROCs.
+
+## Responsabilidades
+
+- **Tickets**: Total abertos (Open, In Progress, Answered), Alta Prioridade, Tempo Médio Resposta (90 dias)
+- **Distribuição**: Tickets por departamento (gráfico de barras)
+- **Cobertura PROCs**: Barra de progresso por departamento com percentagem
+- **Thresholds**: ≥80% verde, ≥50% amarelo, <50% vermelho
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Recharts 3**: BarChart para tickets por departamento
+- **Framer Motion**: Stagger animations
+- **Lucide React**: Ticket, AlertTriangle, Clock, FileText, Building2
+- **Tailwind CSS**: Glass cards, progress bars coloridas
+
+## Tipos
+
+- `TicketsByDept`: dept, count
+- `CoverageItem`: dept, procs, total_expected, pct
+- `OperationsData`: tickets (open, high_priority, avg_response_hours, by_department), procedures (total, departments, coverage)
+
+## Componentes
+
+- `StatCard`: Métrica com label, valor, ícone, cor
+- `ProgressBar`: Barra de progresso com cor condicional (emerald ≥80%, amber ≥50%, red <50%)
+- `CustomTooltip`: Tooltip do Recharts
+
+## Cobertura de PROCs (Dados Estáticos)
+
+| Departamento | PROCs | Esperado | % |
+|---|---|---|---|
+| D7 — Tecnologia | 18 | 20 | 90% |
+| D6 — Gestão | 8 | 10 | 80% |
+| D1 — Comercial | 5 | 8 | 62% |
+| D5 — Marketing | 5 | 8 | 62% |
+| Cross-Departamental | 5 | 6 | 83% |
+| D3 — Contabilidade | 3 | 5 | 60% |
+| D2 — Suporte | 3 | 6 | 50% |
+| D4 — RH | 1 | 4 | 25% |
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| Operations | `GET /api/operations` | Tickets Desk CRM + cobertura PROCs |
+
+## Localizações
+
+- **Código**: `src/pages/Operations.tsx` (323 linhas)
+- **Rota**: `/operations`
+
+## Dependências
+
+- **Express-API**: Rota `/api/operations`
+- **MySQL-Pool**: Dados de tickets do Desk CRM
+- **Dashboard-Engine**: Layout, navegação
+
+## Estado
+
+- Activo
@@ -0,0 +1,53 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, paperclip, agentes, automacao]
+title: "Painel-Paperclip"
+---
+
+# Painel-Paperclip
+
+Painel do orquestrador autónomo Paperclip (Camada 3 — Autónomo). Monitoriza agentes (64), routines e issues. Suspenso desde 08-04-2026, mantido para reintrodução progressiva.
+
+## Responsabilidades
+
+- **Agentes**: Total, Activos, Idle, Erro — agrupados por role hierárquico (Board → CEO → C-Level → Director → Specialist)
+- **Routines**: Total, Activas, com cron expression e última execução
+- **Issues**: Abertas, Em Progresso, Fechadas (7d)
+- **Fallback**: Dados zeros quando BD Paperclip inacessível (sem erro 500)
+- **Ordenação Hierárquica**: Roles ordenadas por senioridade (ROLE_ORDER map)
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Framer Motion**: Stagger + spring animations
+- **Lucide React**: Bot, Users, Calendar, CheckCircle2, AlertTriangle, Activity, Zap
+- **Tailwind CSS**: Glass cards, status colors
+
+## Tipos
+
+- `PaperclipAgent`: id, name, role, status (active|idle|error|archived), last_heartbeat, last_run, total_runs
+- `PaperclipRoutine`: id, name, cron, active, last_run, last_status, next_run
+- `PaperclipDashboard`: agents (total, active, idle, error, list), routines (total, active, list), issues (open, in_progress, closed_7d)
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| Paperclip | `GET /api/paperclip` | PostgreSQL Paperclip (com fallback) |
+
+## Localizações
+
+- **Código**: `src/pages/Paperclip.tsx` (546 linhas)
+- **Rota**: `/paperclip`
+
+## Dependências
+
+- **Express-API**: Rota `/api/paperclip`
+- **Paperclip PostgreSQL**: Base de dados de agentes/routines
+- **Dashboard-Engine**: Layout, navegação
+
+## Estado
+
+- **Suspenso** (08-04-2026) — reintrodução progressiva planeada
+- Painel mantido para monitorização durante reintrodução
@@ -0,0 +1,62 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, frontend, painel, sessoes, claude-code]
+title: "Painel-Sessoes"
+---
+
+# Painel-Sessoes
+
+Painel de observabilidade de sessões Claude Code. Lista sessões indexadas com filtros (projecto, tool, skill, pesquisa) e navega para detalhe com visualização de eventos.
+
+## Responsabilidades
+
+- **Listagem**: 50 sessões por página com paginação (offset)
+- **Filtros**: Dias (7 default), projecto, tool, skill, pesquisa textual
+- **Navegação**: Link para `/sessions/:id` (detalhe da sessão)
+- **Detalhe**: Visualização de eventos com filtros (all, no-system, tools-only, prompts-only)
+- **Estado**: Loading, error, e empty states com fallback
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Framer Motion** (animações)
+- **React Router DOM 7** (`useParams`, `Link`)
+- **Tailwind CSS** (glass-card, bordas, estados)
+
+## Componentes
+
+| Componente | Ficheiro | Função |
+|---|---|---|
+| `Sessions` | `src/pages/Sessions.tsx` | Página listagem (130 linhas) |
+| `SessionDetail` | `src/pages/SessionDetail.tsx` | Página detalhe (83 linhas) |
+| `FilterBar` | `src/components/sessions/FilterBar.tsx` | Barra de filtros (projecto, tool, skill, search) |
+| `SessionRow` | `src/components/sessions/SessionRow.tsx` | Linha de sessão na tabela |
+| `EventBlock` | `src/components/sessions/EventBlock.tsx` | Bloco de evento no detalhe |
+
+## Tipos
+
+- `SessionMeta`: session_id, project_slug, started_at, duration_sec, event_count, tool_calls, skills_invoked, outcome, jsonl_path, first_prompt
+- `SessionEvent`: index, type (user|system|assistant), tool_name, tool_result, content
+- `ListResponse`: total + items[]
+- `Filters`: days, project, tool, skill, q
+
+## API Consumida
+
+- `GET /api/sessions` — lista paginada com filtros (Zod validation)
+- `GET /api/sessions/:id` — detalhe com meta + eventos
+
+## Rota
+
+- `/sessions` — Lista de sessões
+- `/sessions/:id` — Detalhe da sessão
+
+## Dependências
+
+- **Observabilidade-Sessions**: SQLite local (`sessions.db`) + indexer
+- **Express-API**: Rota `/api/sessions`
+- **Dashboard-Engine**: Layout + navegação sidebar
+
+## Estado
+
+- Activo (Fase C — implementado 2026-06)
@@ -0,0 +1,69 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, infra, systemd, timers, observabilidade]
+title: "Systemd-Timers"
+---
+
+# Systemd-Timers
+
+Timers systemd (user) que executam scripts de observabilidade do DashDescomplicar no desktop local (`dev`). Gerem indexação de sessões, import de worklogs e detecção de padrões.
+
+## Responsabilidades
+
+- **Indexação contínua**: Watcher incremental de ficheiros JSONL (Claude Code)
+- **Import worklogs**: Import diário de worklogs Desk CRM (discussions #31/#32/#33)
+- **Detecção padrões**: Análise semanal de padrões de uso (tools, skills, erros)
+- **Publicação**: Resultados publicados para consulta pela API
+
+## Serviços e Timers
+
+| Ficheiro | Tipo | Schedule | Função |
+|---|---|---|---|
+| `observabilidade-indexer.service` | simple (always-on) | — | Watcher incremental ficheiros JSONL |
+| `observabilidade-worklog-import.service` | oneshot | — | Import worklogs Desk |
+| `observabilidade-worklog-import.timer` | timer | Diário 03:00 | Dispara import worklogs |
+| `observabilidade-patterns.service` | oneshot | — | Detecção de padrões |
+| `observabilidade-patterns.timer` | timer | Dom 23:00 | Dispara detecção semanal |
+| `observabilidade-patterns.env.example` | env | — | Template variáveis ambiente |
+
+## Stack
+
+- **Runtime**: Node.js 22.22.2 via `npx tsx`
+- **Working Directory**: `/media/ealmeida/Dados/Dev/DashDescomplicar`
+- **DB Path**: `~/.claude-work/sessions.db`
+- **Logs**: `~/.claude-work/observabilidade-*.log`
+
+## Comandos Executados
+
+```
+# Indexer (always-on)
+npx tsx api/scripts/sessions-indexer.ts --watch
+
+# Worklog Import (daily 03:00)
+npx tsx api/scripts/sessions-worklog-import.ts --discussion all --since-days 7
+
+# Patterns (weekly Sun 23:00)
+npx tsx api/scripts/sessions-patterns.ts --publish
+```
+
+## Localizações
+
+- **Systemd files**: `Dev/DashDescomplicar/systemd/` (5 ficheiros)
+- **Scripts**: `Dev/DashDescomplicar/api/scripts/sessions-*.ts`
+- **Logs**: `~/.claude-work/observabilidade-*.log`
+- **DB**: `~/.claude-work/sessions.db`
+- **Env file**: `~/.claude-work/observabilidade-patterns.env`
+
+## Dependências
+
+- **Node.js 22**: `/home/ealmeida/.nvm/versions/node/v22.22.2/bin/`
+- **Observabilidade-Sessions**: Scripts e lógica de indexação
+- **Gemini-Telemetry**: Dados de telemetria Gemini no mesmo DB
+- **Sistema de Ficheiros**: `~/.claude/projects/`, `~/.hermes/`, `~/.local/share/opencode/`
+
+## Fornece a
+
+- **Observabilidade-Sessions**: Execução agendada dos scripts
+- **Painel-Sessoes**: Dados actualizados para consulta
+- **Express-API**: Sessões indexadas disponíveis via `/api/sessions`