descomplicar-meta-plugin/skills/db-maintenance-manager/SKILL.md

name, description, author, version, desk_task, allowed-tools

name	description	author	version	desk_task	allowed-tools
db-maintenance-manager	Manutenção automatizada das tabelas cr_* da infraestrutura Claude Code. Use when "manutenção BD", "limpeza órfãos", "migração schema", "backup tabelas", "archiving", "optimização BD", "database maintenance".	Descomplicar®	1.0.0	1441	Read, Glob, Grep, ToolSearch

DB Maintenance Manager

Gestão e manutenção automatizada das tabelas cr_* (Claude Resources) na base de dados Desk CRM.

Triggers

Esta skill deve ser activada quando:

• Utilizador menciona "manutenção BD", "database maintenance"
• Detectados órfãos nas tabelas de relacionamento
• Telemetria antiga (>90 dias) a ocupar espaço
• Necessidade de migração de schema
• Backup/restore de componentes

Schema das Tabelas cr_*

Core Tables (Entidades)

Tabela	Descrição	Manutenção
cr_agents	Agentes especializados	Sync, Backup
cr_skills	Skills invocáveis	Sync, Backup
cr_mcps	Servidores MCP	Sync, Backup
cr_lsps	Language Server Protocols	Sync, Backup
cr_sdks	Software Development Kits	Sync, Backup
cr_mcp_tools	Ferramentas por MCP	Sync
cr_plugins	Plugins instalados	Sync, Backup
cr_hooks	Hooks configurados	Sync, Backup

Relationship Tables (Limpeza de Órfãos)

Tabela	FK Agent	FK Resource	Cleanup Priority
cr_agent_mcps	agent_id → cr_agents	mcp_id → cr_mcps	Alta
cr_agent_lsps	agent_id → cr_agents	lsp_id → cr_lsps	Alta
cr_sdk_agents	sdk_id → cr_sdks	agent_id → cr_agents	Média
cr_sdk_skills	sdk_id → cr_sdks	skill_id → cr_skills	Média
cr_sdk_mcps	sdk_id → cr_sdks	mcp_id → cr_mcps	Média
cr_agent_skills	agent_id → cr_agents	skill_id → cr_skills	Alta
cr_skill_mcps	skill_id → cr_skills	mcp_id → cr_mcps	Alta
cr_agent_collaborations	agent_id → cr_agents	collaborator_id → cr_agents	Média

Telemetry Tables (Archiving)

Tabela	Retenção Activa	Archive After
cr_agent_usage	90 dias	cr_agent_usage_archive
cr_skill_usage	90 dias	cr_skill_usage_archive
cr_mcp_tool_usage	90 dias	cr_mcp_tool_usage_archive
cr_lsp_usage	90 dias	cr_lsp_usage_archive

Capabilities

1. Cleanup de Órfãos

Detecta e remove referências inválidas nas tabelas de relacionamento.

Detecção:

-- Órfãos em cr_agent_mcps
SELECT am.id, am.agent_id, am.mcp_id
FROM cr_agent_mcps am
LEFT JOIN cr_agents a ON am.agent_id = a.id
LEFT JOIN cr_mcps m ON am.mcp_id = m.id
WHERE a.id IS NULL OR m.id IS NULL;

Limpeza (com confirmação):

-- Backup antes de limpar
CREATE TABLE cr_agent_mcps_orphans_backup_YYYYMMDD AS
SELECT * FROM cr_agent_mcps am
WHERE agent_id NOT IN (SELECT id FROM cr_agents)
   OR mcp_id NOT IN (SELECT id FROM cr_mcps);

-- Limpar órfãos
DELETE FROM cr_agent_mcps
WHERE agent_id NOT IN (SELECT id FROM cr_agents)
   OR mcp_id NOT IN (SELECT id FROM cr_mcps);

2. Migração de Schema

Gestão de alterações estruturais nas tabelas cr_*.

Estrutura de Migrations:

migrations/
├── 001_initial_schema.sql
├── 002_add_lsp_tables.sql
├── 003_add_telemetry.sql
├── 004_add_archive_tables.sql
└── migrations_log.sql

Tabela de Controlo:

CREATE TABLE IF NOT EXISTS cr_migrations (
    id INT AUTO_INCREMENT PRIMARY KEY,
    migration_name VARCHAR(100) NOT NULL,
    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    checksum VARCHAR(64),
    status ENUM('applied', 'rolled_back', 'failed') DEFAULT 'applied'
);

3. Backup Selectivo

Backup apenas das tabelas cr_* (não toda a BD Desk).

Tabelas a incluir:

-- Lista de tabelas para backup
SELECT table_name
FROM information_schema.tables
WHERE table_schema = DATABASE()
  AND table_name LIKE 'cr_%';

Formato de Backup:

backups/
└── cr_backup_YYYYMMDD_HHMMSS/
    ├── manifest.json
    ├── cr_agents.sql
    ├── cr_skills.sql
    ├── cr_mcps.sql
    └── ... (todas as tabelas cr_*)

4. Archiving de Telemetria

Move dados antigos para tabelas de arquivo.

Processo:

-- 1. Criar tabela archive se não existir
CREATE TABLE IF NOT EXISTS cr_agent_usage_archive LIKE cr_agent_usage;

-- 2. Mover dados > 90 dias
INSERT INTO cr_agent_usage_archive
SELECT * FROM cr_agent_usage
WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY);

-- 3. Limpar tabela principal
DELETE FROM cr_agent_usage
WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY);

-- 4. Registar operação
INSERT INTO cr_maintenance_log (operation, table_name, rows_affected, executed_at)
VALUES ('archive', 'cr_agent_usage', ROW_COUNT(), NOW());

5. Optimização

Manutenção de performance das tabelas.

-- Optimizar tabelas fragmentadas
OPTIMIZE TABLE cr_agent_usage, cr_skill_usage, cr_mcp_tool_usage;

-- Analisar estatísticas
ANALYZE TABLE cr_agents, cr_skills, cr_mcps, cr_agent_mcps;

-- Verificar índices em falta
SELECT DISTINCT table_name, column_name
FROM information_schema.columns c
WHERE table_schema = DATABASE()
  AND table_name LIKE 'cr_%'
  AND column_name LIKE '%_id'
  AND NOT EXISTS (
    SELECT 1 FROM information_schema.statistics s
    WHERE s.table_schema = c.table_schema
      AND s.table_name = c.table_name
      AND s.column_name = c.column_name
  );

Workflow

ANALISAR → BACKUP → EXECUTAR → VALIDAR → REPORTAR

1. ANALISAR: Identificar necessidades de manutenção
2. BACKUP: Criar backup antes de operações destrutivas
3. EXECUTAR: Correr operação com transação
4. VALIDAR: Verificar integridade pós-operação
5. REPORTAR: Registar em cr_maintenance_log

Integrações

• MCP: desk-crm-v3 (operações MySQL)
• Commands:
  • /descomplicar:db-cleanup - Limpeza de órfãos
  • /descomplicar:db-migrate - Migração de schema
  • /descomplicar:db-backup - Backup selectivo
  • /descomplicar:db-archive - Archiving telemetria
• Skills: infrastructure-manager (detecção), quality-validator (validação)

Métricas de Sucesso

Métrica	Target
Órfãos	0
Telemetria activa	< 90 dias
Backup age	< 7 dias
Migrations pendentes	0

Exemplo de Uso

User: A BD tem dados antigos e órfãos. Limpa tudo.

DB Maintenance Manager:
1. [Analisa estado actual]
   - Órfãos: 12 em cr_agent_mcps, 3 em cr_skill_mcps
   - Telemetria: 45.000 registos > 90 dias
   - Último backup: há 15 dias

2. [Cria backup preventivo]
   ✓ Backup criado: cr_backup_20260204_163000/

3. [Executa limpeza órfãos]
   ✓ cr_agent_mcps: 12 órfãos removidos
   ✓ cr_skill_mcps: 3 órfãos removidos

4. [Executa archiving]
   ✓ cr_agent_usage: 15.000 → archive
   ✓ cr_skill_usage: 20.000 → archive
   ✓ cr_mcp_tool_usage: 10.000 → archive

5. [Valida resultado]
   ✓ Integridade OK
   ✓ 0 órfãos
   ✓ Telemetria < 90 dias

Resultado:
╔════════════════════════════════════════╗
║  DB MAINTENANCE COMPLETE               ║
╠════════════════════════════════════════╣
║  Órfãos removidos:     15              ║
║  Registos arquivados:  45.000          ║
║  Espaço libertado:     ~12 MB          ║
║  Backup:               ✓ Criado        ║
╚════════════════════════════════════════╝

Limites

• Não executa operações destrutivas sem backup prévio
• Archiving mantém dados (move, não apaga)
• Migrations requerem aprovação manual
• Backup não inclui tabelas não-cr_*
• Optimização pode demorar em tabelas grandes (>1M registos)
• Não substitui backups gerais do Desk CRM