care-api/README.md

# KiviCare API - Plugin WordPress Completo

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/descomplicar/kivicare-api)
[![WordPress](https://img.shields.io/badge/WordPress-6.0%2B-blue.svg)](https://wordpress.org)
[![PHP](https://img.shields.io/badge/PHP-8.1%2B-purple.svg)](https://php.net)
[![License](https://img.shields.io/badge/license-GPL%20v2%2B-green.svg)](https://www.gnu.org/licenses/gpl-2.0.html)

> **Sistema completo de gestão de clínicas médicas via REST API**

---

## 🏥 VISÃO GERAL

O **KiviCare API** é um plugin WordPress completo que transforma qualquer instalação KiviCare num sistema de gestão de clínicas médicas com REST API robusta, segura e escalável.

### ✨ FUNCIONALIDADES PRINCIPAIS

- **🔐 Autenticação JWT** - Sistema de autenticação seguro
- **👥 Gestão Completa** - Pacientes, médicos, clínicas, consultas
- **📅 Agendamentos** - Sistema avançado com slots disponíveis
- **💊 Prescrições** - Gestão completa de medicamentos
- **💰 Faturação** - Sistema de faturas e pagamentos
- **📊 Relatórios** - Analytics e estatísticas detalhadas
- **🚀 Performance** - Cache avançado e monitorização
- **🔒 Segurança** - Isolamento por clínica e controle de acesso
- **🧪 Testing** - Suite completa de testes unitários

---

## 📋 REQUISITOS

### Sistema
- WordPress 6.0+
- PHP 8.1+
- MySQL 5.7+ / MariaDB 10.3+
- Memória: 512MB+ (recomendado: 1GB+)

### Dependências
- Plugin KiviCare base instalado e ativo
- mod_rewrite ativado (Apache) ou configuração equivalente (Nginx)

---

## 🚀 INSTALAÇÃO RÁPIDA

### 1. Download & Upload
```bash
# Download do plugin
wget https://github.com/descomplicar/kivicare-api/releases/latest/download/kivicare-api.zip

# Upload para WordPress
wp plugin install kivicare-api.zip --activate
```

### 2. Configuração (wp-config.php)
```php
// Configurações obrigatórias
define('KIVICARE_API_VERSION', '1.0.0');
define('KIVICARE_JWT_SECRET', 'your-secure-secret-key-here');

// Configurações opcionais
define('KIVICARE_API_DEBUG', true);       // Apenas desenvolvimento
define('KIVICARE_API_CACHE_TTL', 3600);   // Cache TTL em segundos
```

### 3. Verificação
```bash
# Testar endpoint de saúde
curl -X GET http://yoursite.com/wp-json/kivicare/v1/health

# Resposta esperada: {"status": "healthy", ...}
```

---

## 🎯 ENDPOINTS PRINCIPAIS

### **Autenticação**
```http
POST /wp-json/kivicare/v1/auth/login     # Login utilizador
POST /wp-json/kivicare/v1/auth/logout    # Logout  
GET  /wp-json/kivicare/v1/auth/profile   # Perfil do utilizador
```

### **Clínicas** 
```http
GET    /wp-json/kivicare/v1/clinics           # Listar clínicas
POST   /wp-json/kivicare/v1/clinics           # Criar clínica
GET    /wp-json/kivicare/v1/clinics/{id}      # Obter clínica
PUT    /wp-json/kivicare/v1/clinics/{id}      # Atualizar clínica
DELETE /wp-json/kivicare/v1/clinics/{id}      # Eliminar clínica
```

### **Pacientes**
```http
GET  /wp-json/kivicare/v1/patients              # Listar pacientes
POST /wp-json/kivicare/v1/patients              # Criar paciente
GET  /wp-json/kivicare/v1/patients/{id}         # Obter paciente
PUT  /wp-json/kivicare/v1/patients/{id}         # Atualizar paciente
GET  /wp-json/kivicare/v1/patients/{id}/history # Histórico médico
```

### **Agendamentos**
```http
GET    /wp-json/kivicare/v1/appointments                    # Listar agendamentos
POST   /wp-json/kivicare/v1/appointments                    # Criar agendamento
GET    /wp-json/kivicare/v1/appointments/{id}               # Obter agendamento
PUT    /wp-json/kivicare/v1/appointments/{id}               # Atualizar agendamento
GET    /wp-json/kivicare/v1/appointments/available-slots    # Slots disponíveis
DELETE /wp-json/kivicare/v1/appointments/{id}               # Cancelar agendamento
```

### **Consultas Médicas**
```http
GET  /wp-json/kivicare/v1/encounters                     # Listar encounters
POST /wp-json/kivicare/v1/encounters                     # Criar encounter
GET  /wp-json/kivicare/v1/encounters/{id}                # Obter encounter
PUT  /wp-json/kivicare/v1/encounters/{id}                # Atualizar encounter
GET  /wp-json/kivicare/v1/encounters/{id}/prescriptions  # Prescrições do encounter
```

### **Prescrições**
```http
GET    /wp-json/kivicare/v1/prescriptions         # Listar prescrições
POST   /wp-json/kivicare/v1/prescriptions         # Criar prescrição
GET    /wp-json/kivicare/v1/prescriptions/{id}    # Obter prescrição
PUT    /wp-json/kivicare/v1/prescriptions/{id}    # Atualizar prescrição
DELETE /wp-json/kivicare/v1/prescriptions/{id}    # Eliminar prescrição
```

### **Faturação**
```http
GET  /wp-json/kivicare/v1/bills              # Listar faturas
POST /wp-json/kivicare/v1/bills              # Criar fatura
GET  /wp-json/kivicare/v1/bills/{id}         # Obter fatura
PUT  /wp-json/kivicare/v1/bills/{id}         # Atualizar fatura
POST /wp-json/kivicare/v1/bills/{id}/payment # Registar pagamento
```

**📚 [Ver documentação completa de endpoints](SPEC_CARE_API.md)**

---

## 🔐 AUTENTICAÇÃO

### Login & Token JWT
```bash
# Login
curl -X POST http://yoursite.com/wp-json/kivicare/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

# Resposta
{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 1,
      "user_type": "admin",
      "full_name": "Administrator"
    }
  }
}
```

### Usar Token nas Requisições
```bash
# Incluir token no header Authorization
curl -X GET http://yoursite.com/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
```

---

## 🏗️ ARQUITETURA

### **Estrutura do Plugin**
```
kivicare-api/
├── kivicare-api.php              # Plugin principal
├── QUICKSTART.md                 # Guia rápido
├── SPEC_CARE_API.md             # Especificações técnicas
├── src/
│   ├── includes/
│   │   ├── class-api-init.php    # Inicialização principal
│   │   ├── models/               # Modelos de dados (8 entidades)
│   │   ├── endpoints/            # Endpoints REST API (7 controllers)
│   │   ├── services/             # Serviços de negócio (15 serviços)
│   │   ├── middleware/           # Middleware JWT & segurança
│   │   ├── utils/                # Utilitários (validação, logs, cache)
│   │   └── testing/              # Suite de testes unitários
└── tests/                        # Testes automatizados
```

### **97+ Endpoints REST Funcionais**
- **Authentication**: 3 endpoints
- **Clinics**: 12 endpoints  
- **Patients**: 15 endpoints
- **Doctors**: 10 endpoints
- **Appointments**: 18 endpoints
- **Encounters**: 13 endpoints  
- **Prescriptions**: 12 endpoints
- **Bills**: 11 endpoints
- **Utilities**: 3 endpoints

---

## ⚡ PERFORMANCE & CACHE

### Sistema de Cache Inteligente
```php
// Cache automático para consultas frequentes
$patient = Cache_Service::get_patient($patient_id, true);
$statistics = Cache_Service::get_clinic_statistics($clinic_id);
$available_slots = Cache_Service::get_available_slots($doctor_id, $date);
```

### Monitorização em Tempo Real
```bash
# Métricas de performance
curl -X GET http://yoursite.com/wp-json/kivicare/v1/system/performance \
  -H "Authorization: Bearer TOKEN"

# Response time, memory usage, query count, cache hits/misses
```

---

## 🧪 TESTES & QUALIDADE

### Suite de Testes Completa
```php
// Executar todos os testes
$results = \KiviCare_API\Testing\Unit_Test_Suite::run_all_tests([
    'verbose' => true,
    'timeout' => 60
]);

// Testes por categoria
$validation_tests = Unit_Test_Suite::run_category_tests('validation');
$security_tests = Unit_Test_Suite::run_category_tests('security');
$performance_tests = Unit_Test_Suite::run_category_tests('performance');
```

### Categorias Testadas
- **✅ Input Validation** - Validação de dados
- **✅ Error Handling** - Tratamento de erros  
- **✅ Authentication** - Sistema de autenticação
- **✅ Security** - Testes de segurança
- **✅ Performance** - Benchmarks de performance
- **✅ Integration** - Testes de integração
- **✅ Database** - Operações de base de dados

---

## 🔒 SEGURANÇA & COMPLIANCE

### Funcionalidades de Segurança
- **🔐 JWT Authentication** - Tokens seguros com expiração
- **🏥 Clinic Isolation** - Isolamento rigoroso entre clínicas  
- **👤 Role-based Access** - Controle de acesso por função
- **🛡️ Input Validation** - Validação completa de inputs
- **📝 Audit Logging** - Logs detalhados de segurança
- **🚫 Rate Limiting** - Proteção contra abuse

### Matriz de Permissões
```php
'administrator' => ['all_operations'],
'doctor' => ['read_own_patients', 'create_encounters', 'prescriptions'],
'patient' => ['read_own_data', 'book_appointments'],
'receptionist' => ['manage_appointments', 'basic_patient_data']
```

---

## 📊 MONITORIZAÇÃO & LOGS

### Sistema de Logging Avançado
```bash
# Localização dos logs
/wp-content/uploads/kivicare-api-logs/
├── api-requests.log        # Requests da API
├── authentication.log      # Eventos de autenticação
├── performance.log         # Métricas de performance
├── security.log           # Eventos de segurança
├── database.log           # Operações da BD
└── business-logic.log      # Lógica de negócio
```

### Alertas Automáticos
- **🚨 Performance degradado** - Response time > 3s
- **⚠️ Memória alta** - Uso > 80% do limite
- **🔒 Tentativas de login falhadas** - Múltiplas tentativas
- **💾 Base de dados lenta** - Queries > 500ms

---

## 🔧 TROUBLESHOOTING

### Problemas Comuns

#### ❌ Plugin não ativa
```bash
# Verificar dependências
wp plugin list --status=active | grep kivicare

# Verificar logs
tail -f /wp-content/debug.log | grep kivicare
```

#### ❌ Erro 500 nos endpoints
```bash
# Verificar permissões
find /wp-content/plugins/kivicare-api -type f -exec chmod 644 {} \;
find /wp-content/plugins/kivicare-api -type d -exec chmod 755 {} \;

# Verificar memory limit
wp config get WP_MEMORY_LIMIT
```

#### ❌ Problemas de autenticação
```bash
# Apache - adicionar ao .htaccess
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

# Nginx - configuração
location ~ \.php$ {
    fastcgi_param HTTP_AUTHORIZATION $http_authorization;
}
```

---

## 🎯 EXEMPLOS PRÁTICOS

### Criar Paciente Completo
```bash
curl -X POST http://yoursite.com/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "João",
    "last_name": "Silva",
    "user_email": "joao.silva@email.com",
    "contact_no": "+351912345678",
    "dob": "1985-05-15",
    "gender": "male",
    "clinic_id": 1,
    "address": "Rua da Saúde, 123",
    "city": "Lisboa",
    "postal_code": "1000-001"
  }'
```

### Workflow Completo: Paciente → Agendamento → Consulta → Prescrição
```javascript
// 1. Criar agendamento
const appointment = await fetch('/wp-json/kivicare/v1/appointments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_id: 123,
    doctor_id: 456,
    clinic_id: 1,
    appointment_start_date: '2025-01-15',
    appointment_start_time: '14:30:00'
  })
});

// 2. Criar encounter
const encounter = await fetch('/wp-json/kivicare/v1/encounters', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_id: 123,
    doctor_id: 456,
    clinic_id: 1,
    appointment_id: appointment.data.id,
    description: 'Consulta de rotina'
  })
});

// 3. Adicionar prescrição
const prescription = await fetch('/wp-json/kivicare/v1/prescriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encounter_id: encounter.data.id,
    patient_id: 123,
    medication_name: 'Paracetamol 500mg',
    frequency: '8/8h',
    duration: '7 dias',
    instructions: 'Tomar com água após refeições'
  })
});
```

---

## 🛠️ DESENVOLVIMENTO & EXTENSÕES

### Hooks Disponíveis
```php
// Antes de criar paciente
add_action('kivicare_before_patient_create', function($patient_data) {
    // Custom logic
});

// Após criar agendamento  
add_action('kivicare_appointment_created', function($appointment_id, $appointment_data) {
    // Enviar notificações, etc.
});

// Filtros de validação
add_filter('kivicare_validate_patient_data', function($is_valid, $data) {
    // Custom validation
    return $is_valid;
}, 10, 2);
```

### Registar Serviços Personalizados
```php
// Registar novo serviço
KiviCare_API\Services\Integration_Service::register_service(
    'my_custom_service',
    'MyNamespace\\MyCustomService'
);

// Usar o serviço
$service = Integration_Service::get_service('my_custom_service');
```

---

## 📈 ROADMAP

### v1.1 - Integrações Externas
- [ ] Sincronização calendários (Google Calendar, Outlook)
- [ ] Integração sistemas pagamento (Stripe, PayPal, Multibanco)
- [ ] Notificações automáticas (Email, SMS, Push)
- [ ] Integração Zoom/Google Meet para teleconsultas

### v1.2 - Analytics Avançadas  
- [ ] Dashboard métricas médicas
- [ ] Relatórios financeiros avançados
- [ ] Business intelligence integrado
- [ ] Previsões AI/ML

### v1.3 - Mobile & Offline
- [ ] App mobile nativo (iOS/Android)
- [ ] Sincronização offline
- [ ] Patient portal app
- [ ] Progressive Web App (PWA)

---

## 👥 CONTRIBUIÇÕES

### Como Contribuir
1. **Fork** do repositório
2. **Criar branch** para feature (`git checkout -b feature/nova-funcionalidade`)
3. **Commit** mudanças (`git commit -am 'Adicionar nova funcionalidade'`)
4. **Push** para branch (`git push origin feature/nova-funcionalidade`)
5. **Pull Request**

### Diretrizes
- Seguir padrões WordPress Coding Standards
- Incluir testes unitários
- Documentar mudanças no README
- Manter compatibilidade retroativa

---

## 📞 SUPORTE

### Desenvolvimento Técnico
- **Empresa**: Descomplicar® Crescimento Digital
- **Website**: https://descomplicar.pt
- **Email**: dev@descomplicar.pt

### Documentação
- **[Guia de Início Rápido](QUICKSTART.md)** - Instalação e configuração
- **[Especificações Técnicas](SPEC_CARE_API.md)** - Documentação completa
- **[Exemplos de Código](examples/)** - Implementações práticas

### Comunidade
- **GitHub Issues**: Reportar bugs e solicitar features
- **Discussions**: Discussões técnicas e dúvidas
- **Wiki**: Documentação colaborativa

---

## 📄 LICENÇA

Este projeto está licenciado sob a **GPL v2 ou posterior** - ver ficheiro [LICENSE](LICENSE) para detalhes.

### Termos de Uso
- ✅ Uso comercial permitido
- ✅ Modificação permitida  
- ✅ Distribuição permitida
- ❗ Deve manter copyright e licença
- ❗ Modificações devem ser GPL

---

## 🎉 AGRADECIMENTOS

- **WordPress Community** - Pela plataforma fantástica
- **KiviCare Team** - Pelo plugin base excelente
- **Contribuidores** - Pela dedicação e feedback

---

<div align="center">

**🏥 KiviCare API v1.0.0**

*Sistema completo de gestão de clínicas médicas via REST API*

**Desenvolvido com ❤️ pela [Descomplicar® Crescimento Digital](https://descomplicar.pt)**

[![Descomplicar](https://img.shields.io/badge/Powered%20by-Descomplicar-blue.svg)](https://descomplicar.pt)

</div>

---

*© 2025 Descomplicar® Crescimento Digital. Todos os direitos reservados.*