care-api/docs/COVERAGE_SYSTEM.md

📊 Sistema de Coverage Reports - Care API

Sistema completo de análise de cobertura de código para o Care API Healthcare Management System.

🎯 Objectivos

• Relatórios HTML interactivos com interface personalizada
• Coverage mínimo 80% para classes críticas
• Integração CI/CD com GitHub Actions
• Tracking histórico de métricas de cobertura
• Alertas automáticos para degradação de coverage

🏗️ Arquitectura do Sistema

coverage-system/
├── bin/
│   ├── generate-coverage.sh      # Gerador principal
│   ├── monitor-coverage.sh       # Monitor de tendências
│   └── quality-gates.sh          # Validador de qualidade
├── templates/coverage/
│   └── custom.css                # Estilos personalizados
├── .github/workflows/
│   └── coverage.yml              # Pipeline CI/CD
├── coverage-reports/             # Relatórios detalhados
├── coverage-html/                # Interface HTML
└── coverage-dashboard.html       # Dashboard principal

🛠️ Componentes Principais

1. Gerador de Coverage (bin/generate-coverage.sh)

Script principal que orquestra todo o processo de geração de relatórios.

Funcionalidades:

• ✅ Verificação automática de pré-requisitos (Xdebug/PCOV)
• ✅ Múltiplos formatos de saída (HTML, XML, Texto)
• ✅ Coverage por test suite (Unit, Integration, Contract)
• ✅ Métricas de qualidade (PHPLOC, PHPCPD)
• ✅ Dashboard interactivo com JavaScript
• ✅ Extracto automático de métricas

Modos de Operação:

# Modo completo (padrão)
./bin/generate-coverage.sh full

# Modo rápido (apenas HTML)
./bin/generate-coverage.sh quick

# Coverage por suites
./bin/generate-coverage.sh suites

# Limpeza
./bin/generate-coverage.sh clean

Pré-requisitos Verificados:

• PHP 8.1+ com extensão coverage (Xdebug/PCOV)
• PHPUnit 10+
• Composer dependencies
• WordPress test environment

2. Monitor de Tendências (bin/monitor-coverage.sh)

Sistema de monitorização contínua que acompanha a evolução do coverage ao longo do tempo.

Funcionalidades:

• 📈 Tracking histórico com JSON storage
• 🎯 Alertas por threshold (Critical < 50%, Warning < 60%, Target < 70%)
• 📊 Análise de tendências (subida/descida de coverage)
• 🔗 Integração webhook para notificações
• 📝 Relatórios detalhados com classes problemáticas

Utilização:

# Monitorizar coverage actual
./bin/monitor-coverage.sh monitor

# Relatório detalhado
./bin/monitor-coverage.sh report

# Ver histórico
./bin/monitor-coverage.sh history

# Limpar dados
./bin/monitor-coverage.sh clean

Configuração de Webhooks:

export COVERAGE_WEBHOOK_URL="https://hooks.slack.com/your-webhook"
./bin/monitor-coverage.sh monitor

3. Quality Gates (bin/quality-gates.sh)

Validador de qualidade que implementa quality gates para deployment.

Gates Implementados:

1. Coverage Global (≥70%)
2. Coverage Classes Críticas (≥80%)
3. Complexidade Ciclomática (≤10)
4. Duplicação de Código (≤5%)
5. Padrões de Código (0 erros PHPCS)
6. Coverage por Suite (Unit ≥85%, Integration ≥70%, Contract ≥75%)

Utilização:

# Todos os gates
./bin/quality-gates.sh validate

# Apenas coverage
./bin/quality-gates.sh coverage-only

# Apenas padrões
./bin/quality-gates.sh standards-only

Resultados:

• ✅ PASS: Gate aprovado
• ⚠️ WARN: Gate com aviso (não bloqueia)
• ❌ FAIL: Gate crítico falhado (bloqueia deployment)

🎨 Interface e Relatórios

Dashboard Principal (coverage-dashboard.html)

Interface moderna e responsiva com:

• 📊 Métricas principais (Coverage global, classes, métodos, linhas)
• 🧪 Coverage por test suite com barras de progresso
• 📈 Métricas de qualidade (CRAP, duplicação, LOC)
• 🔗 Links para relatórios detalhados
• 🎯 Cores dinâmicas baseadas em thresholds

Relatórios HTML Detalhados

Gerados pelo PHPUnit com CSS personalizado:

• 🎨 Design moderno com gradientes e animações
• 📱 Layout responsivo para mobile/desktop
• 🌈 Código colorido com highlight de linhas cobertas/não cobertas
• 📊 Tabelas interactivas com hover effects
• 🌙 Suporte tema escuro (media query)

Estilos CSS Personalizados (templates/coverage/custom.css)

• 🎯 Cores semânticas (Verde ≥80%, Laranja 60-79%, Vermelho <60%)
• ⚡ Animações e transições suaves
• 🏥 Branding Care API integrado
• 📄 Print styles para relatórios em PDF
• 🔧 Utilitários CSS para customização

🚀 Pipeline CI/CD (.github/workflows/coverage.yml)

Workflow Completo:

1. Preparação

   • Detecção de mudanças em código PHP/testes
   • Skip inteligente quando não há alterações relevantes

2. Matrix Strategy

   • Testes paralelos com PCOV e Xdebug
   • Comparação de performance entre drivers

3. Ambiente de Teste

   • MySQL 8.0 service container
   • WordPress test environment
   • PHP 8.1 com extensões completas

4. Execução de Testes

   • Coverage por test suite separadamente
   • Geração de relatórios em múltiplos formatos
   • Merge de relatórios combinados

5. Quality Analysis

   • PHPLOC para métricas de código
   • PHPCPD para detecção de duplicação
   • PHPCS para padrões de código

6. Reporting

   • Upload de artifacts para GitHub
   • Integração com Codecov
   • Comentários automáticos em PRs
   • Validação de thresholds

7. Notificações

   • Alertas por falhas de threshold
   • Status badges para README
   • Webhooks para equipas

Triggers:

• ✅ Push para branches principais (main, develop, feature/*)
• ✅ Pull Requests para main/develop
• ✅ Schedule diário às 03:00 UTC
• ✅ Manual dispatch quando necessário

📋 Configuração e Setup

1. Instalação de Dependências

# Instalar dependências Composer
composer install

# Instalar extensão de coverage (escolher uma)
# PCOV (mais rápido)
pecl install pcov

# OU Xdebug (mais recursos)
sudo apt-get install php-xdebug

2. Configuração PHPUnit

O phpunit.xml está optimizado com:

• ✅ Coverage paths específicos para src/
• ✅ Exclusões apropriadas (vendor, deprecated)
• ✅ Múltiplos formatos de saída
• ✅ Thresholds configuráveis (lowUpperBound=60, highLowerBound=85)

3. Scripts Composer

# Coverage completo
composer run test:coverage

# Coverage HTML apenas
composer run test:coverage-html

# Coverage por formato
composer run test:coverage-clover
composer run test:coverage-text

# Merge de relatórios
composer run coverage:merge

# Limpeza
composer run coverage:clean

4. Configuração de Ambiente

Variáveis de ambiente suportadas:

# Webhook para alertas
export COVERAGE_WEBHOOK_URL="https://hooks.slack.com/webhook"

# Threshold personalizado
export COVERAGE_THRESHOLD=75

# Modo debug
export COVERAGE_DEBUG=1

📊 Métricas e Thresholds

Coverage Targets:

Componente	Target	Minimum	Critical
Global	85%	70%	50%
Unit Tests	90%	85%	70%
Integration	80%	70%	60%
Contract	85%	75%	65%
Classes Críticas	95%	80%	70%

Quality Gates:

Gate	Threshold	Blocking
Coverage Global	≥70%	✅
Coverage Critical	≥80%	✅
Code Standards	0 errors	✅
Complexity	≤10	❌
Duplication	≤5%	❌

🔍 Análise de Resultados

Interpretar Dashboard:

1. Verde (≥80%): Excelente cobertura
2. Laranja (60-79%): Cobertura aceitável, melhorar
3. Vermelho (<60%): Cobertura crítica, acção necessária

Classes Críticas Monitorizadas:

• class-auth-endpoints.php - Autenticação JWT
• class-patient-endpoints.php - Gestão de pacientes
• class-appointment-endpoints.php - Agendamentos
• class-security-manager.php - Segurança

Acções por Threshold:

• ≥85%: 🎯 Target atingido, manter qualidade
• 70-84%: ⚠️ Adicionar testes para melhorar
• 50-69%: 🚨 Prioridade alta, cobertura insuficiente
• <50%: ❌ Crítico, bloquear deployment

🛠️ Manutenção e Troubleshooting

Problemas Comuns:

1. Coverage 0%

   • Verificar extensão PCOV/Xdebug instalada
   • Validar paths no phpunit.xml
   • Confirmar bootstrap.php funcional

2. Performance Lenta

   • Usar PCOV em vez de Xdebug
   • Reduzir scope de coverage
   • Executar suites separadamente

3. Reports Inconsistentes

   • Limpar cache com coverage:clean
   • Verificar versões PHPUnit/PHP-Coverage
   • Validar configuração XML

Comandos de Debug:

# Verificar environment
php --version && php -m | grep -E "(pcov|xdebug)"

# Testar configuração
phpunit --configuration phpunit.xml --list-tests

# Coverage verbose
phpunit --coverage-text --verbose

# Validar XML
xmllint --noout phpunit.xml

📚 Recursos Adicionais

Links Úteis:

• 📖 PHPUnit Coverage Documentation
• 🔧 PCOV Extension
• 📊 Codecov Integration

Scripts de Exemplo:

#!/bin/bash
# Quick coverage check
composer run test:coverage-text | grep "Lines:" | awk '{print $2}'

# Deploy gate
if ./bin/quality-gates.sh validate; then
    echo "✅ Deploy autorizado"
    # deploy commands
else
    echo "❌ Deploy bloqueado"
    exit 1
fi

---

🏥 Care API Healthcare Management

Este sistema de coverage está integrado ao Care API, uma solução completa para gestão de clínicas e consultórios médicos baseada no plugin KiviCare para WordPress.

Desenvolvido por: 💚 Descomplicar® Crescimento Digital Versão: 1.0.0 Data: 2025-09-14

🎯 Quality Assurance

• ✅ Automated Testing com PHPUnit 10+
• ✅ Code Coverage tracking e reporting
• ✅ Quality Gates para deployment
• ✅ CI/CD Integration com GitHub Actions
• ✅ Performance Monitoring e alertas

Para suporte técnico: dev@descomplicar.pt