DashDescomplicar/CLAUDE.md

---
layer: wiki
type: Document
title: "CLAUDE — DashDescomplicar"
description: >-
  Instruções operacionais para Claude Code no projecto DashDescomplicar. Stack React 19 + Express + EasyPanel Swarm.
tags: [claude, operacional, dashboard, deploy, react, express]
timestamp: 2026-06-29T23:00:00+01:00
---
# CLAUDE — DashDescomplicar

Instruções operacionais para agentes

## OKF — Organizational Knowledge Framework (OBRIGATÓRIO)

Este projecto tem um mapeamento OKF interno em `okf/`. **Antes de qualquer acção, consultar o OKF.**

| Regra | Detalhe |
|-------|---------|
| **Consultar antes de agir** | Ler `okf/index.md` ao iniciar sessão. Ver entidades relevantes ao contexto. |
| **Manter actualizado** | Se criares, alterares ou removeres um componente, actualizar a ficha OKF correspondente. |
| **Novo componente = nova ficha** | Qualquer novo serviço, módulo, integração ou script → criar `5W2H-PDCA.md` em `okf/entidades/`. |
| **Validar antes de commit** | `okf-validate.sh --project .` — 0 erros para commit. |
| **Relacionamentos bidirecionais** | Se A depende de B, tanto A como B devem registar a relação. |

**Estrutura:** `okf/index.md` → índice geral. `okf/entidades/` → uma pasta por componente com `5W2H-PDCA.md`.
 IA a trabalhar neste projecto.

## Contexto

- **Projecto:** DashDescomplicar — dashboard interno `dash.descomplicar.pt`
- **Desk:** Projecto #65
- **Versão actual:** 2.7.3 (ver `CHANGELOG.md`)
- **Dev local:** `/media/ealmeida/Dados/Dev/DashDescomplicar`
- **Hub:** `/media/ealmeida/Dados/Hub/04-Stack/02.05-Aplicações/DashDescomplicar/`

## Stack

| Camada | Tecnologias |
|--------|-------------|
| Frontend | React 19, TypeScript 5.6, Vite 7, Tailwind CSS, Framer Motion, Lucide React |
| Backend | Express 4, MySQL2, SSH2, Zod, Node.js 18+ |
| Observabilidade | better-sqlite3, chokidar, node-html-parser |
| DevOps | Docker, Gitea (HTTPS), EasyPanel Swarm |

## Desenvolvimento Local

```bash
# Modo desenvolvimento completo
npm run dev

# Apenas frontend (porta 5173)
npm run dev:client

# Apenas backend (porta 3001)
npm run dev:server
```

- Frontend: `http://localhost:5173`
- API: `http://localhost:3001/api`
- Health: `http://localhost:3001/api/health`
- Proxy Vite: `/api` → `localhost:3001`

## Build e Validação

```bash
# Build completo (validação antes de commit)
npx tsc -b && npx vite build && npx tsc -p api/tsconfig.json

# Build rápido
npm run build
```

## Pipeline de Deploy

1. **Validar build localmente** (obrigatório)
2. **Push para Gitea:**
   ```bash
   git push origin main
   # Se necessário: git pull --rebase origin main
   ```
3. **Rebuild e redeploy no servidor** (SSH `easy`):
   ```bash
   cd /etc/easypanel/projects/descomplicar/dashboard_descomplicar/code
   docker build -t easypanel/descomplicar/dashboard_descomplicar:latest .
   docker service update --force descomplicar_dashboard_descomplicar
   ```
4. **Verificar:**
   ```bash
   curl -sf https://dash.descomplicar.pt/api/dashboard
   curl -sf https://dash.descomplicar.pt/api/health
   ```

> **IMPORTANTE:** EasyPanel MCP (`redeploy_service`) está quebrado. Usar **sempre** SSH directo para redeploy.

## Variáveis de Ambiente

Prefixo correcto: `DB_*` (NÃO `MYSQL_*`)

```env
DB_HOST=176.9.3.158
DB_USER=ealmeida_desk24
DB_PASS=...
DB_NAME=ealmeida_desk24
WP_MONITOR_API_KEY=...
HETZNER_TOKEN=...
NODE_ENV=production
FRONTEND_URL=https://dash.descomplicar.pt
API_PORT=3001
```

## Segurança

- Pre-commit hook (`Regra #47`): corre `npm audit --audit-level=moderate`
  - Pode falhar sem rede — tratar como erro de rede, não vulnerabilidade
  - `npm audit fix --force` pode fazer breaking changes — verificar build depois
- Credenciais: **nunca** hardcodar; validação obrigatória em `api/db.ts`
- `.env` está no `.gitignore` — nunca commitar

## Arquitectura de Ficheiros Relevantes

```
src/
  App.tsx          — router principal (8 painéis)
  pages/           — Monitor, Financial, McpMonitor, N8nMonitor, Paperclip, AiOverview, Operations, Sessions
  components/
    Layout.tsx     — sidebar com navegação

api/
  server.ts        — Express com rate-limit, CORS, Zod
  db.ts            — MySQL2 connection pool
  routes/          — wp-monitor, monitor, hetzner, sessions, ...
  services/        — monitoring, server-metrics, calendar, dashboard, ...
  scripts/         — sessions-indexer, sessions-patterns, check-sites, ...
```

## Padrões de Código

- Validação Zod em todas as rotas API
- `.passthrough()` em objectos aninhados (plugins WP podem enviar campos extra)
- `z.string()` em vez de `z.enum()` para health status (plugins enviam qualquer string)
- `z.any().optional()` para arrays complexos aninhados
- Error handling: sem stack traces em produção; error IDs UUID para tracking
- Rate limiting: 100 req/15min produção, 1000/15min dev

## Observabilidade (Sessões Claude Code)

- SQLite local: `~/.claude-work/sessions.db` (sincronizado para EasyPanel via rsync)
- Volume bind: `/root/data/dashboard-descomplicar/sessions.db → /data/sessions.db`
- Env var servidor: `OBSERVABILIDADE_DB=/data/sessions.db`
- Timer sync: `obs-index-sync.timer` (cada 15min)
- Fontes: Claude Code JSONL, Hermes (`~/.hermes/state.db`), OpenCode (`~/.local/share/opencode/opencode.db`)

## Gitea

- Owner: `ealmeida` (NÃO `descomplicar`)
- Repo: `DashDescomplicar`
- HTTPS funciona directamente via `git push origin main`
- Gitea MCP não é necessário para push

## OKF — Grafo de Conhecimento

- **Índice:** `okf/index.md` — 25 entidades + 17 relacionamentos (Deep OKF)
- **Entidades:** `okf/entidades/` — um ficheiro por componente (painéis, API, integrações, infra)
- **Relacionamentos:** `okf/relacionamentos/` — arestas com taxonomia (roteia, alimenta, serve, exibe)
- **Navegação:** Usar `[[Nome-Entidade]]` para saltar entre entidades

## WP-CLI em CWP

- Contas CWP têm shells `nologin` — usar sempre `--allow-root`
- Com `--skip-plugins --skip-themes`, fazer `require_once` manual do plugin antes de `do_action`

## Referências

- `SYS-DashDescomplicar.md` — descrição geral do sistema e painéis
- `okf/index.md` — grafo de conhecimento completo (Deep OKF)
- `MEMORY.md` — memórias operacionais acumuladas
- `CHANGELOG.md` — histórico de versões
- `docs/SPECS/SPEC-dashboard-expansion-q2-2026.md` — spec expansão Q2 2026
- `docs/PLANS/PLAN-conductor-dashboard-expansion.md` — plano de expansão
- `AUDIT-REPORT.md` — auditoria de segurança