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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
# 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**

```bash
# 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**

```bash
# 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:

```bash
# 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:

```bash
# 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](https://phpunit.de/documentation.html)
- 🔧 [PCOV Extension](https://github.com/krakjoe/pcov)
- 📊 [Codecov Integration](https://codecov.io/)

### Scripts de Exemplo:

```bash
#!/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