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>
This commit is contained in:
Emanuel Almeida
252
specs/001-care-api-sistema/data-model.md
Normal file
252
specs/001-care-api-sistema/data-model.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user