docs: migrar SPEC/PLAN para docs/SPECS e docs/PLANS e adicionar ficheiros de contexto do projecto
This commit is contained in:
@@ -0,0 +1,10 @@
|
||||
---
|
||||
type: Brainstorm
|
||||
title: 'Brainstorm — DashDescomplicar'
|
||||
timestamp: 2026-06-30
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# BRAINSTORM — DashDescomplicar
|
||||
|
||||
Estrutura padrão aplicada.
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
layer: wiki
|
||||
type: Document
|
||||
title: "PLAN — DashDescomplicar"
|
||||
description: >-
|
||||
Plano operacional do DashDescomplicar v2.7.3. Roadmap de manutenção, deploys e expansões.
|
||||
Ciclo PDCA: versão atual em produção, próximas iterações planejadas.
|
||||
tags: [plan, dashboard, operacional, pdca, roadmap]
|
||||
timestamp: 2026-06-30T00:00:00+01:00
|
||||
---
|
||||
|
||||
# PLAN — DashDescomplicar
|
||||
|
||||
**Versão Atual:** 2.7.3 · **Data:** 2026-06-30 · **Status:** 🟢 Operacional
|
||||
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Dashboard interno de monitorização operacional (React 19 + Express + TypeScript) com 8 painéis ativos. Corre em EasyPanel Swarm (`easy.descomplicar.pt`) com MySQL no CWP. Ciclo de releases: manutenção mensal + features trimestrais.
|
||||
|
||||
---
|
||||
|
||||
## Roadmap Operacional (Q3-Q4 2026)
|
||||
|
||||
### Q3 2026 — Consolidação
|
||||
|
||||
| Sprint | Objetivo | Proprietário | Estado |
|
||||
|--------|----------|-------------|--------|
|
||||
| Q3-S1 (Jul) | Audit segurança completo + certificado de revisão | Claude Code | 📋 Planeado |
|
||||
| Q3-S2 (Ago) | Painel Cron Dev (visibilidade de agentes cron) | Claude Code | 📋 Planeado |
|
||||
| Q3-S3 (Set) | Reintrodução progressiva Paperclip (renegociação) | Claude Code | 📋 Planeado |
|
||||
| Q3-S4 (Out) | Sincronização multi-máquina (HP + desktop) | Claude Code | 📋 Planeado |
|
||||
|
||||
### Q4 2026 — Expansão Estratégica
|
||||
|
||||
| Sprint | Objetivo | Proprietário | Estado |
|
||||
|--------|----------|-------------|--------|
|
||||
| Q4-S1 (Nov) | Integração Wiki Descomplicar (leitura de artigos) | Claude Code | 📋 Backlog |
|
||||
| Q4-S2 (Dez) | Painel Inteligência Stack — melhorias | Claude Code | 📋 Backlog |
|
||||
|
||||
---
|
||||
|
||||
## Ciclos de Manutenção
|
||||
|
||||
### Semanal (2ªf)
|
||||
|
||||
- ✅ Verificar saúde do serviço: `curl -sf https://dash.descomplicar.pt/api/dashboard`
|
||||
- ✅ Revisar logs de erro no EasyPanel
|
||||
- ✅ Sincronização manual de sessões se necessário: `rsync -av ~/IJFW/sessions/ easy:/var/dash-sessions/`
|
||||
|
||||
### Mensal (último Fri)
|
||||
|
||||
- ✅ Audit de dependências: `npm audit`
|
||||
- ✅ Atualizar ficheiro STATUS.md com métricas de uptime
|
||||
- ✅ Revisar tickets de sugestões e bugs abertos
|
||||
|
||||
### Trimestral (fim de trimestre)
|
||||
|
||||
- ✅ Revisão de segurança (OWASP top 10)
|
||||
- ✅ Testes de carga/stress (Load testing)
|
||||
- ✅ Atualização de documentação (AGENTS.md, SPEC.md, CHANGELOG.md)
|
||||
- ✅ Release notes e bump de versão
|
||||
|
||||
---
|
||||
|
||||
## Processo de Deploy
|
||||
|
||||
### Pré-requisitos
|
||||
|
||||
1. Branch `main` deve estar com todos os testes a passar: `npm test`
|
||||
2. Lint sem erros: `npm run lint`
|
||||
3. Build local validado: `npm run build`
|
||||
4. STATUS.md actualizado com versão nova
|
||||
|
||||
### Passos do Deploy (SSH directo no EasyPanel)
|
||||
|
||||
```bash
|
||||
# 1. SSH para o servidor
|
||||
ssh root@easy.descomplicar.pt
|
||||
|
||||
# 2. Navegar para a pasta do projeto
|
||||
cd /etc/easypanel/projects/descomplicar/dashboard_descomplicar/code
|
||||
|
||||
# 3. Pull da branch main
|
||||
git pull origin main
|
||||
|
||||
# 4. Build da imagem Docker
|
||||
docker build -t easypanel/descomplicar/dashboard_descomplicar:latest .
|
||||
|
||||
# 5. Forçar reinicialização do serviço
|
||||
docker service update --force descomplicar_dashboard_descomplicar
|
||||
|
||||
# 6. Verificação pós-deploy
|
||||
curl -sf https://dash.descomplicar.pt/api/dashboard && echo "✅ Deploy OK" || echo "❌ Deploy FALHOU"
|
||||
```
|
||||
|
||||
**Tempo estimado:** 3-5 minutos (pull + build + restart)
|
||||
|
||||
### Rollback (se necessário)
|
||||
|
||||
```bash
|
||||
# Voltar para versão anterior
|
||||
git revert HEAD
|
||||
git push origin main
|
||||
# Repetir deploy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estrutura de Features
|
||||
|
||||
### Painéis Ativos (v2.7.3)
|
||||
|
||||
| ID | Painel | Rota | Ficheiros | Status |
|
||||
|----|----|------|-----------|--------|
|
||||
| 1 | Dashboard | `/` | `pages/Monitor.tsx` | 🟢 Activo |
|
||||
| 2 | Monitor | `/monitor` | `pages/Monitor.tsx` | 🟢 Activo |
|
||||
| 3 | Financeiro | `/financial` | `pages/Financial.tsx` | 🟢 Activo |
|
||||
| 4 | MCPs | `/mcps` | `pages/McpMonitor.tsx` | 🟢 Activo |
|
||||
| 5 | n8n | `/n8n` | `pages/N8nMonitor.tsx` | 🟢 Activo |
|
||||
| 6 | Paperclip | `/paperclip` | `pages/Paperclip.tsx` | 🟡 Suspenso |
|
||||
| 7 | IA/Claude | `/ai` | `pages/AiOverview.tsx` | 🟢 Activo |
|
||||
| 8 | Operações | `/operations` | `pages/Operations.tsx` | 🟢 Activo |
|
||||
| 9 | Sessions (Observabilidade) | `/sessions` | `pages/Sessions.tsx` + `pages/SessionDetail.tsx` | 🟢 Activo |
|
||||
|
||||
### Painéis Planeados
|
||||
|
||||
- **Cron Dev** (Q3 2026) — visibilidade de agentes systemd-user cron
|
||||
- **Wiki Integration** (Q4 2026) — busca e leitura de artigos do Hub
|
||||
- **Inteligência Stack** (Q4 2026) — melhorias e recomendações de stack
|
||||
|
||||
---
|
||||
|
||||
## Dependências Críticas
|
||||
|
||||
### Infraestrutura
|
||||
|
||||
- **EasyPanel:** `easy.descomplicar.pt` (5.9.90.70) — serviço `descomplicar_dashboard_descomplicar`
|
||||
- **MySQL:** `176.9.3.158` (CWP) — DB `desscomplicar`, tabelas `tbl_eal_*`
|
||||
- **MCP Gateway:** `gateway.descomplicar.pt` — estado de 39 MCPs
|
||||
- **Desk CRM:** MySQL interno — tarefas, tickets, projecto
|
||||
|
||||
### Serviços Externos
|
||||
|
||||
- **n8n:** workflows automação
|
||||
- **Moloni API:** dados financeiros
|
||||
- **Hetzner Cloud API:** métricas servidores VPS
|
||||
- **IJFW:** sessões Claude Code (SQLite local)
|
||||
- **SSH (CWP + EasyPanel):** coleta de métricas
|
||||
|
||||
---
|
||||
|
||||
## Processo de Contribuição
|
||||
|
||||
### 1. Local Development
|
||||
|
||||
```bash
|
||||
cd /media/ealmeida/Dados/Dev/DashDescomplicar
|
||||
npm install
|
||||
npm run dev # Vite + Express em paralelo
|
||||
npm run test # Vitest
|
||||
npm run lint # ESLint
|
||||
```
|
||||
|
||||
### 2. Branch Workflow
|
||||
|
||||
```bash
|
||||
git checkout -b feature/meu-painel
|
||||
# ... fazer changes ...
|
||||
npm run build # Validar build
|
||||
npm run lint # Lint
|
||||
npm test # Testes
|
||||
git add .
|
||||
git commit -m "feat: novo painel..."
|
||||
git push origin feature/meu-painel
|
||||
# Criar PR no Gitea
|
||||
```
|
||||
|
||||
### 3. Code Review
|
||||
|
||||
- [ ] Build passa
|
||||
- [ ] Lint passa
|
||||
- [ ] Testes adicionados/passam
|
||||
- [ ] Documentação actualizada
|
||||
- [ ] Sem hardcoded secrets
|
||||
- [ ] Validação Zod em todas as rotas novas
|
||||
|
||||
### 4. Merge & Deploy
|
||||
|
||||
Após aprovação:
|
||||
```bash
|
||||
git merge feature/meu-painel
|
||||
git tag v2.7.4 # Nova versão
|
||||
npm run build
|
||||
npm start # Local test
|
||||
# Seguir "Processo de Deploy" acima
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Rápido
|
||||
|
||||
### Serviço não responde
|
||||
|
||||
```bash
|
||||
# 1. SSH no EasyPanel
|
||||
ssh root@easy.descomplicar.pt
|
||||
|
||||
# 2. Verificar logs
|
||||
docker logs descomplicar_dashboard_descomplicar
|
||||
|
||||
# 3. Reiniciar serviço
|
||||
docker service update --force descomplicar_dashboard_descomplicar
|
||||
```
|
||||
|
||||
### Build local falha
|
||||
|
||||
```bash
|
||||
# Limpar cache e reinstalar
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
### DB não responde
|
||||
|
||||
```bash
|
||||
# Verificar conectividade MySQL
|
||||
mysql -h 176.9.3.158 -u [user] -p [pass] desscomplicar
|
||||
# Se falhar, contactar administrador de infraestrutura
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Métricas de Saúde
|
||||
|
||||
Monitorar semanalmente:
|
||||
|
||||
- **Uptime:** > 99.5% (target SLA)
|
||||
- **Response time:** < 500ms (p95)
|
||||
- **Error rate:** < 0.5% (5xx errors)
|
||||
- **DB connections:** < 80% do pool máximo
|
||||
- **Disk space:** > 10% livre em EasyPanel
|
||||
- **Session sync:** < 5min de lag
|
||||
|
||||
Alertas automáticos configurados em `monitor-alerts` (Desk #2323 com regra DO monitor).
|
||||
|
||||
---
|
||||
|
||||
## Contactos & Escalação
|
||||
|
||||
| Cenário | Contacto | Nível |
|
||||
|---------|----------|-------|
|
||||
| Bug/Feature Request | Comentário em Desk #65 | Prioridade normal |
|
||||
| Incidente crítico (site down) | Usar CodeRED: `curl -X POST https://codered.descomplicar.pt/v1/trigger/RED-ZMT3FCU8` | P0 |
|
||||
| Questão técnica | IRC com Claude Code (`DocFaseA-DashDescomplicar`) | On-demand |
|
||||
| Deploy urgente | SSH directo + pós-deploy verification | On-demand |
|
||||
|
||||
---
|
||||
|
||||
**Próxima revisão de plano:** 2026-09-30 (fim Q3)
|
||||
+9
-6
@@ -1,15 +1,18 @@
|
||||
---
|
||||
title: PLAN Conductor — Expansão DashDescomplicar
|
||||
description: >-
|
||||
Spec: `docs/SPECS/SPEC-dashboard-expansion-q2-2026.md`
|
||||
date: 2026-04-06
|
||||
type: plan
|
||||
status: active
|
||||
spec: SPEC-dashboard-expansion-q2-2026.md
|
||||
tags: [conductor, plan, dashboard, parallel]
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Plano Conductor — Expansão DashDescomplicar
|
||||
|
||||
**Spec:** `docs/SPEC-dashboard-expansion-q2-2026.md`
|
||||
**Spec:** `docs/SPECS/SPEC-dashboard-expansion-q2-2026.md`
|
||||
**Projecto:** `/media/ealmeida/Dados/Dev/DashDescomplicar/`
|
||||
**Método:** Conductor parallel sprints — agentes independentes por domínio
|
||||
|
||||
@@ -62,7 +65,7 @@ Cada painel (backend + frontend) é **independente** — ficheiros distintos, se
|
||||
Estás a trabalhar no projecto DashDescomplicar (/media/ealmeida/Dados/Dev/DashDescomplicar/).
|
||||
Stack: React 19 + Vite + Tailwind CSS 4 + Express 4 + TypeScript.
|
||||
|
||||
Lê a spec completa em docs/SPEC-dashboard-expansion-q2-2026.md, secção 4.1 (Painel MCPs).
|
||||
Lê a spec completa em docs/SPECS/SPEC-dashboard-expansion-q2-2026.md, secção 4.1 (Painel MCPs).
|
||||
|
||||
Cria 3 ficheiros:
|
||||
|
||||
@@ -117,7 +120,7 @@ Não alteres nenhum ficheiro existente. Apenas cria os 3 novos.
|
||||
Estás a trabalhar no projecto DashDescomplicar (/media/ealmeida/Dados/Dev/DashDescomplicar/).
|
||||
Stack: React 19 + Vite + Tailwind CSS 4 + Express 4 + TypeScript.
|
||||
|
||||
Lê a spec completa em docs/SPEC-dashboard-expansion-q2-2026.md, secção 4.2 (Painel n8n).
|
||||
Lê a spec completa em docs/SPECS/SPEC-dashboard-expansion-q2-2026.md, secção 4.2 (Painel n8n).
|
||||
|
||||
Cria 3 ficheiros:
|
||||
|
||||
@@ -159,7 +162,7 @@ Não alteres nenhum ficheiro existente. Apenas cria os 3 novos.
|
||||
Estás a trabalhar no projecto DashDescomplicar (/media/ealmeida/Dados/Dev/DashDescomplicar/).
|
||||
Stack: React 19 + Vite + Tailwind CSS 4 + Express 4 + TypeScript.
|
||||
|
||||
Lê a spec completa em docs/SPEC-dashboard-expansion-q2-2026.md, secção 4.3 (Painel Paperclip).
|
||||
Lê a spec completa em docs/SPECS/SPEC-dashboard-expansion-q2-2026.md, secção 4.3 (Painel Paperclip).
|
||||
|
||||
O pacote `pg` já foi instalado (npm install pg @types/pg).
|
||||
|
||||
@@ -211,7 +214,7 @@ Não alteres nenhum ficheiro existente. Apenas cria os 4 novos.
|
||||
Estás a trabalhar no projecto DashDescomplicar (/media/ealmeida/Dados/Dev/DashDescomplicar/).
|
||||
Stack: React 19 + Vite + Tailwind CSS 4 + Express 4 + TypeScript.
|
||||
|
||||
Lê a spec completa em docs/SPEC-dashboard-expansion-q2-2026.md, secção 4.4 (Painel Claude Code / IA).
|
||||
Lê a spec completa em docs/SPECS/SPEC-dashboard-expansion-q2-2026.md, secção 4.4 (Painel Claude Code / IA).
|
||||
|
||||
Cria 3 ficheiros:
|
||||
|
||||
@@ -261,7 +264,7 @@ Não alteres nenhum ficheiro existente. Apenas cria os 3 novos.
|
||||
Estás a trabalhar no projecto DashDescomplicar (/media/ealmeida/Dados/Dev/DashDescomplicar/).
|
||||
Stack: React 19 + Vite + Tailwind CSS 4 + Express 4 + TypeScript.
|
||||
|
||||
Lê a spec em docs/SPEC-dashboard-expansion-q2-2026.md, secção 4.5 (Painel Operações).
|
||||
Lê a spec em docs/SPECS/SPEC-dashboard-expansion-q2-2026.md, secção 4.5 (Painel Operações).
|
||||
|
||||
A BD MySQL (Desk CRM) já tem conexão configurada em api/db.ts (export default pool mysql2/promise).
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
type: Plan
|
||||
title: 'PLAN — DashDescomplicar'
|
||||
timestamp: 2026-06-30
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# PLAN — DashDescomplicar
|
||||
|
||||
1. Estruturação\n2. Validação\n3. Manutenção
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
type: Brief
|
||||
title: 'Briefing — DashDescomplicar'
|
||||
timestamp: 2026-06-30
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# BRIEF — DashDescomplicar
|
||||
|
||||
Projecto DashDescomplicar do ecossistema Descomplicar.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
type: Specification
|
||||
title: Spec
|
||||
description: >-
|
||||
Especificação do projecto DashDescomplicar, agregando os projectos activos — nomeadamente o painel Observabilidade (replay de sessões Claude Code com indexer, SQLite, API e UI timeline).
|
||||
timestamp: 2026-04-27T10:15:35.733200+00:00
|
||||
layer: wiki
|
||||
---
|
||||
<!-- APPROVED: 2026-04-23 by ealmeida -->
|
||||
# SPEC — DashDescomplicar
|
||||
|
||||
## Projectos activos
|
||||
|
||||
### Observabilidade (Espelho) — Claude Session Replay
|
||||
**SPEC autoritativo:** `/media/ealmeida/Dados/Hub/05-Projectos/Observabilidade/SPEC.md`
|
||||
**PLAN:** `/media/ealmeida/Dados/Hub/05-Projectos/Observabilidade/PLAN.md`
|
||||
**Branch:** `feat/observabilidade-espelho`
|
||||
**Desk task:** #2059
|
||||
|
||||
Painel `/sessions` para replay de sessões Claude Code. Indexer + SQLite + API + UI timeline.
|
||||
|
||||
## Projectos anteriores
|
||||
Ver `CHANGELOG.md` para histórico.
|
||||
+3
@@ -1,10 +1,13 @@
|
||||
---
|
||||
title: SPEC — Expansão DashDescomplicar Q2 2026
|
||||
description: >-
|
||||
O DashDescomplicar é o painel de gestão interno da Descomplicar®. Stack: React 19 + Vite + Tailwind CSS 4 + Express 4 + …
|
||||
date: 2026-04-06
|
||||
type: spec
|
||||
status: active
|
||||
desk_project: 65
|
||||
tags: [dashboard, expansion, mcps, paperclip, n8n, claude-code]
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# SPEC — Expansão DashDescomplicar Q2 2026
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
type: Spec
|
||||
title: 'SPEC — DashDescomplicar'
|
||||
status: draft
|
||||
timestamp: 2026-06-30
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# SPEC — DashDescomplicar
|
||||
|
||||
Projecto em estruturação.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
type: Note
|
||||
title: 'Pesquisa — DashDescomplicar'
|
||||
timestamp: 2026-06-30
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Pesquisa
|
||||
|
||||
Documentar pesquisa aqui.
|
||||
Reference in New Issue
Block a user