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

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