docs: migrar SPEC/PLAN para docs/SPECS e docs/PLANS e adicionar ficheiros de contexto do projecto

2026-10-28 16:01:30 +00:00
parent 61ae4697f9
commit f39c6212a3
22 changed files with 1065 additions and 6 deletions
@@ -0,0 +1,181 @@
+---
+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