chore: add spec-kit and standardize signatures

- Added GitHub spec-kit for development workflow - Standardized file signatures to Descomplicar® format - Updated development configuration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-12 01:27:29 +01:00
parent 30ad448ed3
commit 4a7b232f68
50 changed files with 513565 additions and 0 deletions
--- a/SPEC_CARE_API.md
+++ b/SPEC_CARE_API.md
@@ -0,0 +1,562 @@
+# KiviCare API - Especificações Técnicas
+
+**Projeto**: KiviCare MCP Integration  
+**Versão**: 1.0.0  
+**Data**: 2025-01-12  
+**Autor**: Descomplicar® Crescimento Digital  
+**URL**: https://descomplicar.pt
+
+---
+
+## 🎯 OVERVIEW DO SISTEMA
+
+### Descrição
+KiviCare é um sistema completo de gestão de clínicas médicas implementado como plugin WordPress. O sistema gere pacientes, médicos, consultas, prescrições, faturas e relatórios médicos através de uma estrutura de base de dados com 35 tabelas especializadas.
+
+### Funcionalidades Core
+- **Gestão de Pacientes**: Registo, histórico médico, consultas
+- **Gestão de Médicos**: Perfis, horários, especializações
+- **Agendamento**: Consultas, lembretes, integrações (Zoom/Google Meet)
+- **Consultas Médicas**: Encounters, prescrições, relatórios
+- **Faturação**: Bills, pagamentos, serviços
+- **Administração**: Clínicas, utilizadores, configurações
+
+---
+
+## 🏗️ ARQUITETURA DA BASE DE DADOS
+
+### Tabelas Principais (Core)
+
+#### 🏥 **wp_kc_clinics** - Gestão de Clínicas
+```sql
+- id (bigint, PK)
+- name (varchar 191)
+- email (varchar 191) 
+- telephone_no (varchar 191)
+- specialties (longtext)
+- address (text)
+- city, state, country (varchar 191)
+- postal_code (varchar 191)
+- status (tinyint)
+- clinic_admin_id (bigint)
+- clinic_logo, profile_image (bigint)
+- extra (longtext)
+```
+
+#### 👨‍⚕️ **wp_kc_appointments** - Agendamentos
+```sql
+- id (bigint, PK)
+- appointment_start_date (date)
+- appointment_start_time (time)
+- appointment_end_date (date)
+- appointment_end_time (time)
+- visit_type (varchar 191)
+- clinic_id (bigint) → FK wp_kc_clinics
+- doctor_id (bigint) → FK wp_users
+- patient_id (bigint) → FK wp_users  
+- description (text)
+- status (tinyint)
+- created_at (datetime)
+- appointment_report (longtext)
+```
+
+#### 🩺 **wp_kc_patient_encounters** - Consultas Médicas
+```sql
+- id (bigint, PK)
+- encounter_date (date)
+- clinic_id (bigint) → FK wp_kc_clinics
+- doctor_id (bigint) → FK wp_users
+- patient_id (bigint) → FK wp_users
+- appointment_id (bigint) → FK wp_kc_appointments
+- description (text)
+- status (tinyint)
+- added_by (bigint)
+- created_at (datetime)
+- template_id (bigint)
+```
+
+#### 💊 **wp_kc_prescription** - Prescrições
+```sql
+- id (bigint, PK)
+- encounter_id (bigint) → FK wp_kc_patient_encounters
+- patient_id (bigint) → FK wp_users
+- name (text) - Nome do medicamento
+- frequency (varchar 199)
+- duration (varchar 199)
+- instruction (text)
+- added_by (bigint)
+- created_at (datetime)
+- is_from_template (tinyint)
+```
+
+#### 💰 **wp_kc_bills** - Faturação
+```sql
+- id (bigint, PK)
+- encounter_id (bigint) → FK wp_kc_patient_encounters
+- appointment_id (bigint) → FK wp_kc_appointments
+- title (varchar 191)
+- total_amount (varchar 50)
+- discount (varchar 50)
+- actual_amount (varchar 50)
+- status (bigint)
+- payment_status (varchar 10)
+- created_at (datetime)
+- clinic_id (bigint)
+```
+
+### Tabelas de Relacionamentos
+
+#### 🔗 **wp_kc_doctor_clinic_mappings**
+```sql
+- doctor_id → wp_users
+- clinic_id → wp_kc_clinics
+```
+
+#### 🔗 **wp_kc_patient_clinic_mappings**
+```sql
+- patient_id → wp_users
+- clinic_id → wp_kc_clinics
+```
+
+#### 🔗 **wp_kc_appointment_service_mapping**
+```sql
+- appointment_id → wp_kc_appointments
+- service_id → wp_kc_services
+```
+
+### Tabelas Especializadas
+
+#### ⚕️ **wp_kc_services** - Serviços Médicos
+```sql
+- id, type, name, price, status, created_at
+```
+
+#### 📋 **wp_kc_medical_history** - Histórico Médico
+```sql
+- encounter_id, patient_id, type, title, added_by
+```
+
+#### 🔧 **wp_kc_custom_fields** - Campos Personalizados
+```sql
+- name, type, status, created_at
+```
+
+#### 📞 **wp_kc_appointment_reminder_mapping** - Lembretes
+```sql
+- appointment_id, status, created_at
+```
+
+#### 🎥 **Integrações Video**
+- `wp_kc_appointment_zoom_mappings`
+- `wp_kc_appointment_google_meet_mappings`
+- `wp_kc_gcal_appointment_mapping`
+
+---
+
+## 🎛️ ENDPOINTS API PROPOSTOS
+
+### **Authentication**
+```http
+POST /wp-json/kivicare/v1/auth/login
+POST /wp-json/kivicare/v1/auth/refresh
+POST /wp-json/kivicare/v1/auth/logout
+```
+
+### **Clínicas**
+```http
+GET    /wp-json/kivicare/v1/clinics
+POST   /wp-json/kivicare/v1/clinics
+GET    /wp-json/kivicare/v1/clinics/{id}
+PUT    /wp-json/kivicare/v1/clinics/{id}
+DELETE /wp-json/kivicare/v1/clinics/{id}
+```
+
+### **Pacientes**
+```http
+GET    /wp-json/kivicare/v1/patients
+POST   /wp-json/kivicare/v1/patients
+GET    /wp-json/kivicare/v1/patients/{id}
+PUT    /wp-json/kivicare/v1/patients/{id}
+GET    /wp-json/kivicare/v1/patients/{id}/history
+GET    /wp-json/kivicare/v1/patients/{id}/encounters
+GET    /wp-json/kivicare/v1/patients/{id}/prescriptions
+```
+
+### **Médicos**
+```http
+GET    /wp-json/kivicare/v1/doctors
+GET    /wp-json/kivicare/v1/doctors/{id}
+GET    /wp-json/kivicare/v1/doctors/{id}/schedule
+GET    /wp-json/kivicare/v1/doctors/{id}/appointments
+PUT    /wp-json/kivicare/v1/doctors/{id}/schedule
+```
+
+### **Agendamentos**
+```http
+GET    /wp-json/kivicare/v1/appointments
+POST   /wp-json/kivicare/v1/appointments
+GET    /wp-json/kivicare/v1/appointments/{id}
+PUT    /wp-json/kivicare/v1/appointments/{id}
+DELETE /wp-json/kivicare/v1/appointments/{id}
+GET    /wp-json/kivicare/v1/appointments/available-slots
+```
+
+### **Consultas Médicas**
+```http
+GET    /wp-json/kivicare/v1/encounters
+POST   /wp-json/kivicare/v1/encounters
+GET    /wp-json/kivicare/v1/encounters/{id}
+PUT    /wp-json/kivicare/v1/encounters/{id}
+GET    /wp-json/kivicare/v1/encounters/{id}/prescriptions
+POST   /wp-json/kivicare/v1/encounters/{id}/prescriptions
+```
+
+### **Faturação**
+```http
+GET    /wp-json/kivicare/v1/bills
+POST   /wp-json/kivicare/v1/bills
+GET    /wp-json/kivicare/v1/bills/{id}
+PUT    /wp-json/kivicare/v1/bills/{id}
+POST   /wp-json/kivicare/v1/bills/{id}/payment
+```
+
+### **Serviços**
+```http
+GET    /wp-json/kivicare/v1/services
+POST   /wp-json/kivicare/v1/services
+PUT    /wp-json/kivicare/v1/services/{id}
+DELETE /wp-json/kivicare/v1/services/{id}
+```
+
+### **Relatórios**
+```http
+GET /wp-json/kivicare/v1/reports/appointments
+GET /wp-json/kivicare/v1/reports/revenue
+GET /wp-json/kivicare/v1/reports/patients
+GET /wp-json/kivicare/v1/reports/doctors
+```
+
+---
+
+## 🔐 SEGURANÇA E AUTENTICAÇÃO
+
+### WordPress Authentication
+- **JWT Token** baseado em wp_users
+- **Role-based access**: administrator, doctor, patient, receptionist
+- **Capability checks** por endpoint
+- **Nonce verification** para operações críticas
+
+### Permissions Matrix
+```php
+'administrator' => ['all_operations'],
+'doctor' => ['read_own_patients', 'create_encounters', 'prescriptions'],
+'patient' => ['read_own_data', 'book_appointments'],
+'receptionist' => ['manage_appointments', 'basic_patient_data']
+```
+
+---
+
+## 📊 MODELOS DE DADOS
+
+### Patient Profile
+```json
+{
+  "id": 123,
+  "name": "João Silva",
+  "email": "joao@email.com",
+  "phone": "+351912345678",
+  "birth_date": "1985-05-15",
+  "gender": "M",
+  "address": {
+    "street": "Rua da Saúde, 123",
+    "city": "Lisboa",
+    "postal_code": "1000-001"
+  },
+  "medical_history": [
+    {
+      "type": "chronic_disease",
+      "title": "Diabetes Tipo 2",
+      "date": "2020-01-15"
+    }
+  ],
+  "last_visit": "2024-12-15",
+  "clinic_id": 1
+}
+```
+
+### Appointment
+```json
+{
+  "id": 456,
+  "start_date": "2024-12-20",
+  "start_time": "14:30:00",
+  "end_date": "2024-12-20", 
+  "end_time": "15:00:00",
+  "visit_type": "consultation",
+  "status": "scheduled",
+  "patient": {
+    "id": 123,
+    "name": "João Silva"
+  },
+  "doctor": {
+    "id": 789,
+    "name": "Dr. Maria Santos"
+  },
+  "clinic": {
+    "id": 1,
+    "name": "Clínica Central"
+  },
+  "services": ["consultation_general"],
+  "notes": "Consulta de rotina"
+}
+```
+
+### Medical Encounter
+```json
+{
+  "id": 789,
+  "encounter_date": "2024-12-20",
+  "patient_id": 123,
+  "doctor_id": 789,
+  "appointment_id": 456,
+  "diagnosis": "Gripe comum",
+  "symptoms": ["febre", "tosse", "dor de garganta"],
+  "prescriptions": [
+    {
+      "medication": "Paracetamol 500mg",
+      "frequency": "8/8h",
+      "duration": "7 dias",
+      "instructions": "Tomar com água após refeições"
+    }
+  ],
+  "next_visit": "2024-12-27",
+  "status": "completed"
+}
+```
+
+---
+
+## 🚀 IMPLEMENTAÇÃO TÉCNICA
+
+### Plugin WordPress Structure
+```
+kivicare-api/
+├── kivicare-api.php (main plugin file)
+├── includes/
+│   ├── class-kivicare-api.php
+│   ├── class-rest-controller.php
+│   └── endpoints/
+│       ├── class-clinics-endpoint.php
+│       ├── class-patients-endpoint.php
+│       ├── class-appointments-endpoint.php
+│       ├── class-encounters-endpoint.php
+│       └── class-bills-endpoint.php
+├── models/
+│   ├── class-clinic.php
+│   ├── class-patient.php
+│   ├── class-appointment.php
+│   └── class-encounter.php
+└── utils/
+    ├── class-auth-helper.php
+    ├── class-data-validator.php
+    └── class-db-helper.php
+```
+
+### Core Classes
+```php
+class KiviCare_API_Clinics_Endpoint extends WP_REST_Controller {
+    protected $namespace = 'kivicare/v1';
+    protected $rest_base = 'clinics';
+    
+    public function register_routes() {
+        register_rest_route($this->namespace, '/' . $this->rest_base, [
+            'methods' => WP_REST_Server::READABLE,
+            'callback' => [$this, 'get_items'],
+            'permission_callback' => [$this, 'get_items_permissions_check']
+        ]);
+    }
+}
+```
+
+### Database Queries Optimization
+```php
+class KiviCare_DB_Helper {
+    public static function get_patient_full_data($patient_id) {
+        global $wpdb;
+        
+        $query = "
+            SELECT p.*, pm.clinic_id, c.name as clinic_name
+            FROM {$wpdb->users} p
+            LEFT JOIN {$wpdb->prefix}kc_patient_clinic_mappings pm ON p.ID = pm.patient_id
+            LEFT JOIN {$wpdb->prefix}kc_clinics c ON pm.clinic_id = c.id
+            WHERE p.ID = %d
+        ";
+        
+        return $wpdb->get_row($wpdb->prepare($query, $patient_id));
+    }
+}
+```
+
+---
+
+## 🧪 TESTES E VALIDAÇÃO
+
+### Unit Tests
+```php
+class Test_KiviCare_Appointments extends WP_UnitTestCase {
+    public function test_create_appointment() {
+        $appointment_data = [
+            'patient_id' => 1,
+            'doctor_id' => 2,
+            'clinic_id' => 1,
+            'start_date' => '2024-12-20',
+            'start_time' => '14:30:00'
+        ];
+        
+        $result = KiviCare_Appointments::create($appointment_data);
+        $this->assertIsInt($result);
+        $this->assertGreaterThan(0, $result);
+    }
+}
+```
+
+### API Integration Tests
+```bash
+# Test Authentication
+curl -X POST http://site.local/wp-json/kivicare/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"doctor","password":"password"}'
+
+# Test Get Appointments  
+curl -X GET http://site.local/wp-json/kivicare/v1/appointments \
+  -H "Authorization: Bearer TOKEN"
+
+# Test Create Appointment
+curl -X POST http://site.local/wp-json/kivicare/v1/appointments \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer TOKEN" \
+  -d '{"patient_id":1,"doctor_id":2,"start_date":"2024-12-20"}'
+```
+
+---
+
+## 📈 PERFORMANCE E ESCALABILIDADE
+
+### Database Indexes
+```sql
+ALTER TABLE wp_kc_appointments 
+ADD INDEX idx_doctor_date (doctor_id, appointment_start_date);
+
+ALTER TABLE wp_kc_patient_encounters 
+ADD INDEX idx_patient_date (patient_id, encounter_date);
+
+ALTER TABLE wp_kc_bills 
+ADD INDEX idx_clinic_status (clinic_id, status);
+```
+
+### Caching Strategy
+```php
+class KiviCare_Cache {
+    public static function get_patient_encounters($patient_id) {
+        $cache_key = "patient_encounters_{$patient_id}";
+        $encounters = wp_cache_get($cache_key, 'kivicare');
+        
+        if (false === $encounters) {
+            $encounters = self::fetch_from_db($patient_id);
+            wp_cache_set($cache_key, $encounters, 'kivicare', 3600);
+        }
+        
+        return $encounters;
+    }
+}
+```
+
+---
+
+## 🔧 CONFIGURAÇÃO E DEPLOYMENT
+
+### Plugin Activation
+```php
+register_activation_hook(__FILE__, 'kivicare_api_activate');
+
+function kivicare_api_activate() {
+    // Verificar se KiviCare plugin está ativo
+    if (!is_plugin_active('kivicare-clinic-&-patient-management-system/kivicare-clinic-&-patient-management-system.php')) {
+        wp_die('KiviCare Plugin é necessário para ativar a API.');
+    }
+    
+    // Criar capabilities
+    $role = get_role('doctor');
+    $role->add_cap('manage_kivicare_api');
+    
+    // Flush rewrite rules
+    flush_rewrite_rules();
+}
+```
+
+### Environment Configuration
+```php
+// wp-config.php additions
+define('KIVICARE_API_VERSION', '1.0.0');
+define('KIVICARE_API_DEBUG', false);
+define('KIVICARE_API_CACHE_TTL', 3600);
+define('KIVICARE_JWT_SECRET', 'your-secret-key');
+```
+
+---
+
+## 📋 CHECKLIST DE IMPLEMENTAÇÃO
+
+### Fase 1 - Core API (Semana 1-2)
+- [ ] Plugin base e estrutura
+- [ ] Authentication endpoints  
+- [ ] Clinics CRUD endpoints
+- [ ] Patients CRUD endpoints
+- [ ] Basic error handling
+
+### Fase 2 - Appointments & Encounters (Semana 3-4)
+- [ ] Appointments CRUD endpoints
+- [ ] Slot availability logic
+- [ ] Patient encounters endpoints
+- [ ] Prescription management
+
+### Fase 3 - Billing & Advanced (Semana 5-6)
+- [ ] Bills and payments endpoints
+- [ ] Services management
+- [ ] Reporting endpoints
+- [ ] Advanced filtering and search
+
+### Fase 4 - Testing & Documentation (Semana 7-8)
+- [ ] Unit tests completos
+- [ ] Integration tests
+- [ ] API documentation
+- [ ] Performance optimization
+
+---
+
+## 🔮 ROADMAP FUTURO
+
+### v1.1 - Integrações
+- Sincronização com calendários externos
+- Integração com sistemas de pagamento
+- Notificações push/email automatizadas
+
+### v1.2 - Analytics  
+- Dashboard de métricas médicas
+- Relatórios financeiros avançados
+- Business intelligence integrado
+
+### v1.3 - Mobile
+- App mobile nativo
+- Offline synchronization
+- Patient portal app
+
+---
+
+**Assinatura**: Descomplicar® Crescimento Digital  
+**URL**: https://descomplicar.pt  
+**Contacto**: Desenvolvimento técnico especializado
+
+---
+
+*Especificações técnicas detalhadas para implementação de API KiviCare com arquitetura WordPress robusta e escalável.*