claude-plugins/core-tools/skills/db-maintenance-manager/SKILL.md

---
name: db-maintenance-manager
description: Manutenção automatizada das tabelas cr_* da infraestrutura Claude Code — limpeza de órfãos, migração de schema, backups e optimização.
disable-model-invocation: true
allowed-tools: Read, Glob, Grep, ToolSearch
layer: wiki
---

# 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_plugins` | 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_plugin_agents` | sdk_id → cr_plugins | agent_id → cr_agents | Média |
| `cr_plugin_skills` | sdk_id → cr_plugins | skill_id → cr_skills | Média |
| `cr_plugin_mcps` | sdk_id → cr_plugins | 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:**
```sql
-- Ó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):**
```sql
-- 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:**
```sql
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:**
```sql
-- 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:**
```sql
-- 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.

```sql
-- 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
SE