@maestro-ai/mcp-server 1.1.0 → 2.0.0

package/dist/content/skills/specialist-dados-analytics-ia/resources/checklists/analytics-validation.md

@@ -0,0 +1,519 @@
+# ✅ Checklist de Validação - Dados e Analytics
+
+## Visão Geral
+
+Checklist automatizado para validação da qualidade e completude de pipelines de dados, modelagem dimensional e dashboards analytics.
+
+## 🎯 Critérios de Validação
+
+### 1. Fontes de Dados (20 pontos)
+
+#### ✅ Fontes Mapeadas (5 pontos)
+- [ ] Todas as fontes de dados identificadas e documentadas
+- [ ] Conexões testadas e validadas
+- [ ] Credenciais seguras e armazenadas adequadamente
+- [ ] Responsáveis por fonte definidos
+- [ ] SLAs de disponibilidade estabelecidos
+
+#### ✅ Schema Validado (5 pontos)
+- [ ] Schema de entrada validado e documentado
+- ] Tipos de dados corretos para cada campo
+- ] Chaves primárias e estrangeiras definidas
+- ] Constraints e regras de integridade implementadas
+- ] Versionamento do schema controlado
+
+#### ✅ Qualidade da Fonte (5 pontos)
+- [ ] Confiabilidade da fonte avaliada (Alta/Média/Baixa)
+- ] Frequência de atualização documentada
+- ] Volume de dados estimado corretamente
+- ] Histórico de disponibilidade analisado
+- ] Mecanismos de backup definidos
+
+#### ✅ Acesso e Segurança (5 pontos)
+- [ ] Permissões de acesso configuradas
+- ] Autenticação implementada (OAuth/API Keys/etc)
+- ] Criptografia de dados sensíveis
+- ] Logs de acesso configurados
+- ] Auditoria de acesso habilitada
+
+### 2. Pipeline ETL/ELT (25 pontos)
+
+#### ✅ Extração (8 pontos)
+- [ ] Método de extração definido (Full/Incremental/CDC)
+- [ ] Tratamento de erros implementado
+- [ ] Logs detalhados do processo
+- [ ] Monitoramento de performance ativo
+- [ ] Recuperação de falhas configurada
+- [ ] Idempotência garantida
+- [ ] Validação de dados na origem
+- [ ] Concorrência controlada
+
+#### ✅ Transformação (9 pontos)
+- [ ] Regras de limpeza implementadas
+- ] Validação de qualidade aplicada
+- ] Enriquecimento de dados realizado
+- ] Normalização e padronização aplicada
+- ] Deduplicação implementada
+- ] Agregações corretas conforme negócio
+- ] Transformações testadas unitariamente
+- ] Documentação de transformações
+- ] Performance otimizada
+
+#### ✅ Carga (8 pontos)
+- [ ] Destino configurado corretamente
+- [ ] Schema do destino validado
+- [ ] Estratégia de particionamento implementada
+- ] Método de atualização definido (Insert/Update/Upsert)
+- ] Performance de carga otimizada
+- ] Índices criados adequadamente
+- ] Backup de dados configurado
+- ] Rollback implementado
+
+### 3. Modelagem Dimensional (20 pontos)
+
+#### ✅ Design Dimensional (7 pontos)
+- [ ] Star Schema implementado corretamente
+- [ ] Tabelas de fato identificadas
+- [ ] Dimensões identificadas
+- [ ] Granularidade definida para cada fato
+- [ ] Relacionamentos corretos entre tabelas
+- [ ] Surrogate keys implementadas
+- [ ] Slowly Changing Dimensions planejadas
+
+#### ✅ Qualidade do Modelo (7 pontos)
+- [ ] Normalização aplicada (3NF)
+[ ] Desnormalização justificada (performance)
+[ ] Chaves primárias definidas
+[ ] Chaves estrangeiras implementadas
+[ ] Integridade referencial garantida
+[ ] Consistência de dados mantida
+[ ] Documentação do modelo completa
+
+#### ✅ Performance do Modelo (6 pontos)
+- [ ] Índices criados para queries críticas
+[ ] Particionamento estratégico implementado
+[ ] Consultas otimizadas
+[ ] Materialized views usadas quando apropriado
+[ ] Estatísticas de tabelas atualizadas
+[ ] Performance de queries aceitável (< 10s)
+
+### 4. Qualidade de Dados (15 pontos)
+
+#### ✅ Completude (4 pontos)
+[ ] Taxa de nulidade em campos obrigatórios ≥ 98%
+[ ] Percentual de registros completos ≥ 95%
+[ ] Campos críticos sempre preenchidos
+[ ] Validação de completude automatizada
+
+#### ✅ Acurácia (4 pontos)
+[ ] Taxa de acurácia ≥ 99%
+[ ] Validação cruzada com fontes originais
+[ ] Testes de precisão implementados
+[ ] Discrepâncias identificadas e corrigidas
+
+#### ✅ Consistência (4 pontos)
+[ ] Integridade referencial mantida
+[ ] Formatos consistentes entre fontes
+[ ] Valores dentro de domínios esperados
+[ ] Regras de negócio validadas
+
+#### ✅ Atualização (3 pontos)
+[ ] Freshness dos dados dentro do SLA
+[ ] Timestamps de última atualização
+[ ] Alertas para dados obsoletos
+[ ] Processo de atualização automatizado
+
+### 5. Dashboards e Visualização (20 pontos)
+
+#### ✅ Funcionalidade (8 pontos)
+- [ ] KPIs principais exibidos corretamente
+[ ] Fórmulas de cálculo implementadas
+[ ] Filtros interativos funcionando
+- ] Drill-down disponível onde aplicável
+[ ] Comparação com períodos anteriores
+- ] Exportação de dados disponível
+[ ] Responsividade em diferentes dispositivos
+[ ] Acessibilidade (WCAG 2.1) implementada
+
+#### ✅ Performance (6 pontos)
+[ ] Tempo de carregamento < 5 segundos (P95)
+[ ] Tempo de resposta a filtros < 1 segundo
+[ ] Número de usuários simultâneos suportado
+[ ] Uso eficiente de cache
+[ ] Otimização de consultas
+[ ] Métricas de performance monitoradas
+
+#### ✅ Usabilidade (6 pontos)
+- [ ] Interface intuitiva e fácil de usar
+- **Navegação clara** entre seções
+- **Legendas e rótulos** informativos
+- **Cores e formatação** consistentes
+- **Ajuda contextual** disponível
+- **Feedback visual** para ações
+- **Treinamento mínimo** necessário
+
+### 6. Monitoramento e Alertas (10 pontos)
+
+#### ✅ Monitoramento (5 pontos)
+[ ] Métricas de pipeline coletadas
+[ ] Performance de queries monitorada
+[ ] Qualidade de dados rastreada
+[ ] Disponibilidade dos serviços verificada
+[ ] Dashboard de operações funcionando
+
+#### ✅ Alertas (5 pontos)
+- [ ] Alertas críticas configuradas
+- ] Canais de notificação definidos
+- ] Escalonamento de alertas implementado
+- **Falsos positivos minimizados**
+- ] Processo de resposta a incidentes
+
+---
+
+## 📊 Cálculo de Score
+
+### Fórmula
+```
+Score Total = Σ (Pontos Obtidos / Pontos Possíveis) × 100
+```
+
+### Thresholds
+- **Aprovação Automática**: ≥ 80 pontos
+- **Revisão Manual**: 60-79 pontos
+- **Reconfiguração Obrigatória**: < 60 pontos
+
+### Exemplo de Cálculo
+```
+Fontes de Dados: 18/20 (90%)
+Pipeline ETL: 22/25 (88%)
+Modelagem Dimensional: 17/20 (85%)
+Qualidade de Dados: 14/15 (93%)
+Dashboards: 18/20 (90%)
+Monitoramento: 9/10 (90%)
+
+Score Total = (18+22+17+14+18+9) / (20+25+20+15+20+10) × 100
+Score Total = 98 / 110 × 100 = 89 pontos ✅
+```
+
+## 🔍 Validação Automática
+
+### Checks de Sintaxe
+```python
+def validate_pipeline_structure(pipeline_config):
+    """Valida estrutura do pipeline"""
+    required_components = [
+        "sources",
+        "extract",
+        "transform",
+        "load",
+        "monitoring"
+    ]
+    
+    for component in required_components:
+        if component not in pipeline_config:
+            return False, f"Componente obrigatório ausente: {component}"
+    
+    return True, "Estrutura válida"
+```
+
+### Checks de Qualidade
+```python
+def validate_data_quality(data_warehouse):
+    """Validação automática de qualidade de dados"""
+    issues = []
+    
+    # Verificar completude
+    null_checks = """
+    SELECT 
+        table_name,
+        COUNT(*) as total,
+        COUNT(CASE WHEN critical_field IS NULL THEN 1 END) as nulos,
+        (COUNT(*) - COUNT(CASE WHEN critical_field IS NULL THEN 1 END)) * 100.0 / COUNT(*) as completude
+    FROM data_quality_metrics 
+    WHERE validation_date = CURRENT_DATE
+    GROUP BY table_name
+    """
+    
+    # Verificar unicidade
+    duplicate_checks = """
+    SELECT 
+        table_name,
+        COUNT(*) as total,
+        COUNT(DISTINCT unique_key) as unicos,
+        COUNT(*) - COUNT(DISTINCT unique_key) as duplicatas
+    FROM data_quality_metrics
+    WHERE validation_date = CURRENT_DATE
+    GROUP BY table_name
+    """
+    
+    # Verificar atualização
+    freshness_checks = """
+    SELECT 
+        table_name,
+        MAX(last_updated) as ultima_atualizacao,
+        CURRENT_TIMESTAMP - MAX(last_updated) as idade_dados
+    FROM data_quality_metrics
+    GROUP BY table_name
+    """
+    
+    return {
+        "null_checks": null_checks,
+        "duplicate_checks": duplicate_checks,
+        "freshness_checks": freshness_checks,
+        "issues": issues
+    }
+```
+
+### Checks de Performance
+```python
+def validate_dashboard_performance(dashboard_metrics):
+    """Validação de performance do dashboard"""
+    issues = []
+    
+    # Verificar tempo de carregamento
+    load_time_check = dashboard_metrics.get("p95_load_time", 0)
+    if load_time_check > 5000:  # 5 segundos
+        issues.append(f"Tempo de carregamento muito alto: {load_time_check}ms")
+    
+    # Verificar taxa de erro
+    error_rate = dashboard_metrics.get("error_rate", 0)
+    if error_rate > 0.01:  # 1%
+        issues.append(f"Taxa de erro alta: {error_rate:.2%}")
+    
+    # Verificar concorrência
+    concurrent_users = dashboard_metrics.get("concurrent_users", 0)
+    if concurrent_users < 10:
+        issues.append(f"Baixa capacidade de usuários simultâneos: {concurrent_users}")
+    
+    return {
+        "load_time": load_time_check,
+        "error_rate": error_rate,
+        "concurrent_users": concurrent_users,
+        "issues": issues
+    }
+```
+
+## 🔄 Fluxo de Validação
+
+### 1. Validação Inicial
+```python
+async def validate_analytics_feature(feature_content):
+    """Validação inicial da feature de analytics"""
+    
+    # Validação de estrutura
+    structure_valid, structure_msg = validate_feature_structure(feature_content)
+    if not structure_valid:
+        return {"success": False, "error": structure_msg}
+    
+    # Validação de conteúdo
+    content_valid, content_msg = validate_feature_content(feature_content)
+    if not content_valid:
+        return {"success": False, "error": content_msg}
+    
+    # Validação de lógica
+    logic_valid, logic_issues = validate_feature_logic(feature_content)
+    if not logic_valid:
+        return {"success": False, "errors": logic_issues}
+    
+    return {"success": True, "message": "Validação inicial aprovada"}
+```
+
+### 2. Cálculo de Score
+```python
+def calculate_analytics_score(feature_content):
+    """Calcula score de qualidade da feature"""
+    
+    score_breakdown = {
+        "data_sources": validate_data_sources_score(feature_content),
+        "pipeline": validate_pipeline_score(feature_content),
+        "data_modeling": validate_modeling_score(feature_content),
+        "data_quality": validate_data_quality_score(feature_content),
+        "dashboards": validate_dashboards_score(feature_content),
+        "monitoring": validate_monitoring_score(feature_content)
+    }
+    
+    total_score = sum(score_breakdown.values())
+    max_score = 110  # 20+25+20+15+20+10
+    
+    return {
+        "total_score": total_score,
+        "max_score": max_score,
+        "percentage": (total_score / max_score) * 100,
+        "breakdown": score_breakdown,
+        "can_proceed": total_score >= 80
+    }
+```
+
+### 3. Geração de Relatório
+```python
+def generate_validation_report(feature_content, score_result):
+    """Gera relatório detalhado de validação"""
+    
+    report = {
+        "validation_timestamp": datetime.now().isoformat(),
+        "feature_id": feature_content.get("id", "unknown"),
+        "score": score_result,
+        "status": "approved" if score_result["can_proceed"] else "rejected",
+        "recommendations": generate_recommendations(feature_content, score_result),
+        "next_actions": generate_next_actions(score_result)
+    }
+    
+    return report
+```
+
+## 📊 Métricas de Validação
+
+### KPIs do Processo
+- **Tempo médio de validação:** < 2 minutos
+- **Taxa de aprovação:** > 85%
+- **Score médio qualidade:** > 85 pontos
+- **Falsos positivos:** < 5%
+
+### Métricas de Qualidade
+- **Coverage de validação:** 100%
+- **Precisão das recomendações:** > 90%
+- **Tempo de correção:** < 10 minutos
+- **Satisfação do usuário:** > 95%
+
+---
+
+## 🔄 Validação Contínua
+
+### Monitoramento de Drift
+```python
+def detect_analytics_drift(current_state, expected_state):
+    """Detecta drift nos dados e analytics"""
+    
+    drift_report = {
+        "timestamp": datetime.now().isoformat(),
+        "drift_detected": False,
+        "drifts": []
+    }
+    
+    # Comparar métricas atuais vs esperadas
+    for metric in expected_state:
+        if current_state.get(metric, 0) != expected_state[metric]:
+            drift_report["drift_detected"] = True
+            drift_report["drifts"].append({
+                "metric": metric,
+                "expected": expected_state[metric],
+                "current": current_state.get(metric, 0),
+                "deviation": current_state.get(metric, 0) - expected_state[metric]
+            })
+    
+    return drift_report
+```
+
+### Validação de Compliance
+```python
+def validate_compliance_requirements(feature_content):
+    """Valida requisitos de compliance"""
+    
+    compliance_checks = {
+        "lgpd": {
+            "data_anonymization": feature_content.get("anonymize_pii", False),
+            "retention_policy": feature_content.get("retention_days", 0) >= 365,
+            "access_control": feature_content.get("rbac_enabled", False)
+        },
+        "pci_dss": {
+            "encryption_at_rest": feature_content.get("encryption_enabled", False),
+            "audit_logs": feature_content.get("audit_logging", False),
+            "network_security": feature_content.get("firewall_enabled", False)
+        },
+        "sox": {
+            "financial_reporting": feature_content.get("financial_controls", False),
+            "change_management": feature_content.get("change_control", False),
+            "internal_controls": feature_content.get("internal_audits", False)
+        }
+    }
+    
+    compliance_score = 0
+    total_checks = len(compliance_checks) * 3  # 3 checks por framework
+    
+    for framework, checks in compliance_checks.items():
+        framework_score = sum(checks.values()) / len(checks) * 100
+        compliance_score += framework_score
+    
+    return {
+        "compliance_score": compliance_score / total_checks * 100,
+        "checks": compliance_checks,
+        "compliant": compliance_score >= 80
+    }
+```
+
+## 📋 Recomendações Automáticas
+
+### Para Score < 80
+```python
+def generate_recommendations(feature_content, score_result):
+    """Gera recomendações baseadas no score e feature"""
+    
+    recommendations = []
+    
+    # Recomendações baseadas no score
+    if score_result["score"] < 60:
+        recommendations.append("⚠️ Score baixo (< 60). Reconfiguração obrigatória recomendada.")
+    elif score_result["score"] < 80:
+        recommendations.append("⚠️ Score médio (60-79). Revisar e corrigir issues críticos.")
+    else:
+        recommendations.append("✅ Score bom (≥ 80). Configuração aprovada.")
+    
+    # Recomendações baseadas no breakdown
+    breakdown = score_result["breakdown"]
+    
+    if breakdown["data_sources"] < 15:
+        recommendations.append("🔗 Complete o mapeamento de fontes de dados")
+    
+    if breakdown["pipeline"] < 20:
+        recommendations.append("🔄 Implemente pipeline ETL/ELT completo")
+    
+    if breakdown["data_modeling"] < 15:
+        recommendations.append("📊 Refine a modelagem dimensional")
+    
+    if breakdown["data_quality"] < 12:
+        recommendations.append("🔍 Melhore a qualidade dos dados")
+    
+    if breakdown["dashboards"] < 15:
+        recommendations.append("📈 Otimize os dashboards")
+    
+    if breakdown["monitoring"] < 8:
+        recommendations.append("📊 Configure monitoramento e alertas")
+    
+    return recommendations
+```
+
+## 🔄 Validação de Implementação no MCP
+
+### Função de Validação
+```python
+async def validate_analytics_quality(params):
+    """Função MCP para validação automatizada"""
+    
+    feature_content = params["feature_content"]
+    validation_level = params.get("validation_level", "complete")
+    
+    # Validação inicial
+    initial_validation = await validate_analytics_feature(feature_content)
+    if not initial_validation["success"]:
+        return initial_validation
+    
+    # Cálculo de score
+    score_result = calculate_analytics_score(feature_content)
+    
+    # Validação de compliance
+    compliance_validation = validate_compliance_requirements(feature_content)
+    
+    # Geração de relatório
+    report = generate_validation_report(feature_content, score_result)
+    
+    return {
+        "success": True,
+        "validation_report": report,
+        "score": score_result,
+        "can_proceed": score_result["can_proceed"],
+        "compliance_status": compliance_validation,
+        "next_actions": generate_next_actions(score_result)
+    }
+```
+
+Este checklist garante qualidade consistente e validação automatizada para todas as configurações de analytics.