KiviCare API - Plugin WordPress Completo

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

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

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

# Testar endpoint de saúde
curl -X GET http://yoursite.com/wp-json/kivicare/v1/health

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

---

🎯 ENDPOINTS PRINCIPAIS

Autenticação

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

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

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

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

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

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

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

---

🔐 AUTENTICAÇÃO

Login & Token JWT

# 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

# 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

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

# 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

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

'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

# 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

# Verificar dependências
wp plugin list --status=active | grep kivicare

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

❌ Erro 500 nos endpoints

# 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

# 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

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

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

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

// 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 - Instalação e configuração
• Especificações Técnicas - Documentação completa
• Exemplos de Código - 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 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

---

🏥 KiviCare API v1.0.0

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

Desenvolvido com ❤️ pela Descomplicar® Crescimento Digital

---

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