DashDescomplicar/CLAUDE.md

layer, type, title, description, tags, timestamp

layer	type	title	description	tags	timestamp
wiki	Document	CLAUDE — DashDescomplicar	Instruções operacionais para Claude Code no projecto DashDescomplicar. Stack React 19 + Express + EasyPanel Swarm.	claude operacional dashboard deploy react express	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

# 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

# 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:

   git push origin main
   # Se necessário: git pull --rebase origin main
   

3. Rebuild e redeploy no servidor (SSH easy):

   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:

   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_*)

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