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