care-api/specs/001-care-api-sistema/data-model.md

Data Model: Care API System

Feature: Care API - Sistema de gestão de cuidados de saúde
Date: 2025-09-12
Based on: KiviCare 35-table database schema

Core Entities

Clinic

Purpose: Healthcare facility management Table: wp_kc_clinics Fields:

• id (bigint, PK): Unique clinic identifier
• name (varchar 191): Clinic name
• email (varchar 191): Contact email
• telephone_no (varchar 191): Phone number
• specialties (longtext): JSON array of medical specialties
• address (text): Physical address
• city, state, country (varchar 191): Location details
• postal_code (varchar 191): ZIP/postal code
• status (tinyint): Active/inactive status
• clinic_admin_id (bigint): Administrator user ID
• created_at (datetime): Record creation timestamp

Validation Rules:

• Name: Required, 1-191 characters
• Email: Valid email format, unique per clinic
• Status: Must be 0 (inactive) or 1 (active)
• Admin ID: Must reference valid wp_users record

Relationships:

• Has many doctors (via wp_kc_doctor_clinic_mappings)
• Has many patients (via wp_kc_patient_clinic_mappings)
• Has many appointments
• Belongs to admin user (wp_users)

Patient

Purpose: Individual receiving healthcare Tables: wp_users + wp_kc_patient_clinic_mappings Fields (combined):

• ID (bigint, PK): WordPress user ID
• user_login (varchar 60): Username
• user_email (varchar 100): Email address
• display_name (varchar 250): Full name
• clinic_id (bigint): Associated clinic
• registration_date (datetime): Account creation
• Meta fields: phone, birth_date, gender, address

Validation Rules:

• Email: Required, valid format, unique
• Display name: Required, 1-250 characters
• Phone: Valid phone number format
• Birth date: Valid date, not future
• Gender: M/F/Other or empty

Relationships:

• Belongs to clinic (wp_kc_clinics)
• Has many appointments
• Has many encounters
• Has many prescriptions
• Has medical history entries

Doctor

Purpose: Healthcare provider Tables: wp_users + wp_kc_doctor_clinic_mappings Fields (combined):

• ID (bigint, PK): WordPress user ID
• user_login (varchar 60): Username
• user_email (varchar 100): Email address
• display_name (varchar 250): Full name
• clinic_id (bigint): Primary clinic
• Meta fields: specialization, qualifications, schedule

Validation Rules:

• Must have 'doctor' role in WordPress
• Specialization: From predefined list
• Schedule: Valid time slots format

Relationships:

• Belongs to clinics (many-to-many)
• Has many appointments
• Conducts encounters
• Creates prescriptions

Appointment

Purpose: Scheduled healthcare visit Table: wp_kc_appointments Fields:

• id (bigint, PK): Unique appointment ID
• appointment_start_date (date): Visit date
• appointment_start_time (time): Start time
• appointment_end_date (date): End date
• appointment_end_time (time): End time
• visit_type (varchar 191): consultation/follow-up/emergency
• clinic_id (bigint): FK to wp_kc_clinics
• doctor_id (bigint): FK to wp_users
• patient_id (bigint): FK to wp_users
• description (text): Appointment notes
• status (tinyint): 0=cancelled, 1=scheduled, 2=completed, 3=no-show
• created_at (datetime): Record creation

Validation Rules:

• Start time must be before end time
• Cannot schedule in the past (except admin override)
• Doctor and patient must belong to same clinic
• Status: Must be valid enum value

State Transitions:

scheduled → completed (normal flow)
scheduled → cancelled (user action)
scheduled → no-show (admin action)
completed → [terminal state]

Relationships:

• Belongs to clinic, doctor, patient
• Has many service mappings
• May have one encounter
• May generate bills

Encounter

Purpose: Actual medical consultation record Table: wp_kc_patient_encounters Fields:

• id (bigint, PK): Unique encounter ID
• encounter_date (date): Consultation date
• clinic_id (bigint): FK to wp_kc_clinics
• doctor_id (bigint): FK to wp_users
• patient_id (bigint): FK to wp_users
• appointment_id (bigint): FK to wp_kc_appointments
• description (text): Medical notes/diagnosis
• status (tinyint): 0=draft, 1=completed
• added_by (bigint): Creating user ID
• created_at (datetime): Record creation
• template_id (bigint): Optional template reference

Validation Rules:

• Must link to valid appointment
• Doctor must match appointment doctor
• Status: 0 or 1 only
• Description: Required for completed encounters

Relationships:

• Belongs to appointment, clinic, doctor, patient
• Has many prescriptions
• Has medical history entries
• May generate bills

Prescription

Purpose: Medication orders Table: wp_kc_prescription Fields:

• id (bigint, PK): Unique prescription ID
• encounter_id (bigint): FK to wp_kc_patient_encounters
• patient_id (bigint): FK to wp_users
• name (text): Medication name
• frequency (varchar 199): Dosage frequency
• duration (varchar 199): Treatment duration
• instruction (text): Special instructions
• added_by (bigint): Prescribing doctor ID
• created_at (datetime): Record creation

Validation Rules:

• Name: Required medication name
• Frequency: Standard medical frequency format
• Duration: Valid time period
• Must be created by doctor role user

Relationships:

• Belongs to encounter and patient
• Created by doctor (added_by)

Bill

Purpose: Financial records for services Table: wp_kc_bills Fields:

• id (bigint, PK): Unique bill ID
• encounter_id (bigint): FK to wp_kc_patient_encounters
• appointment_id (bigint): FK to wp_kc_appointments
• title (varchar 191): Bill description
• total_amount (varchar 50): Total charges
• discount (varchar 50): Discount applied
• actual_amount (varchar 50): Final amount
• status (bigint): Bill status
• payment_status (varchar 10): paid/pending/overdue
• created_at (datetime): Record creation
• clinic_id (bigint): FK to clinic

Validation Rules:

• Amounts: Valid decimal format
• Payment status: Must be valid enum
• Total = actual + discount

Relationships:

• Belongs to encounter, appointment, clinic
• May have payment records

Service

Purpose: Medical services offered Table: wp_kc_services Fields:

• id (bigint, PK): Service ID
• type (varchar): Service category
• name (varchar): Service name
• price (decimal): Service cost
• status (tinyint): Active/inactive
• created_at (datetime): Record creation

Validation Rules:

• Name: Required, unique per clinic
• Price: Non-negative decimal
• Status: 0 or 1

Relationships:

• Can be mapped to appointments
• Used in billing calculations

Entity Relationships Summary

Clinic (1) ←→ (M) Doctor (M) ←→ (M) Patient
   ↓              ↓                ↓
Appointments ←→ Encounters ←→ Prescriptions
   ↓              ↓
Services ←→ Bills

Data Integrity Constraints

1. Referential Integrity: All foreign keys must reference valid records
2. Clinic Isolation: Users can only access data from their authorized clinics
3. Role Constraints: Only doctors can create encounters and prescriptions
4. Temporal Constraints: Appointments cannot be scheduled in conflicting time slots
5. Status Consistency: Related records must maintain consistent status values

Performance Considerations

Indexes Required:

• wp_kc_appointments: (doctor_id, appointment_start_date)
• wp_kc_patient_encounters: (patient_id, encounter_date)
• wp_kc_bills: (clinic_id, status)
• wp_kc_prescription: (encounter_id)

Caching Strategy:

• Patient encounters: 1 hour TTL
• Appointment schedules: 30 minutes TTL
• Clinic information: 24 hours TTL

---

Data Model Complete: Ready for API contract generation