care-api/specs/001-care-api-sistema/quickstart.md

# Quickstart Guide: Care API System

**Feature**: Care API - Sistema de gestão de cuidados de saúde  
**Date**: 2025-09-12  
**Prerequisites**: WordPress + KiviCare plugin installed

## Quick Setup

### 1. Plugin Installation
```bash
# Clone/download plugin to WordPress plugins directory
wp plugin activate kivicare-api

# Verify KiviCare dependency
wp plugin is-active kivicare-clinic-patient-management-system
```

### 2. Authentication Setup
```bash
# Test JWT authentication
curl -X POST http://your-site.local/wp-json/kivicare/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"doctor_user","password":"password"}'

# Expected response:
# {"token":"eyJ0eXAiOiJKV1QiLCJhbGc...","user_id":123,"role":"doctor"}
```

### 3. Basic API Testing

#### Create a Patient
```bash
export TOKEN="your_jwt_token_here"

curl -X POST http://your-site.local/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "João Silva",
    "user_email": "joao@example.com",
    "clinic_id": 1,
    "phone": "+351912345678"
  }'
```

#### Schedule an Appointment
```bash
curl -X POST http://your-site.local/wp-json/kivicare/v1/appointments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_start_date": "2025-01-15",
    "appointment_start_time": "14:30:00",
    "appointment_end_date": "2025-01-15",
    "appointment_end_time": "15:00:00",
    "doctor_id": 2,
    "patient_id": 123,
    "clinic_id": 1,
    "visit_type": "consultation",
    "description": "Consulta de rotina"
  }'
```

#### Create Medical Encounter
```bash
curl -X POST http://your-site.local/wp-json/kivicare/v1/encounters \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": 456,
    "description": "Patient presents with mild fever. Diagnosed with common cold. Prescribed rest and medication.",
    "status": 1
  }'
```

#### Add Prescription
```bash
curl -X POST http://your-site.local/wp-json/kivicare/v1/encounters/789/prescriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Paracetamol 500mg",
    "frequency": "Every 8 hours",
    "duration": "7 days",
    "instruction": "Take with water after meals"
  }'
```

## User Story Validation

### Story 1: Doctor Creates Patient Record
```bash
# Test: Create patient → Verify in database
curl -X POST .../patients -d '{"display_name":"Test Patient","user_email":"test@example.com","clinic_id":1}'
# Expected: Patient ID returned, entries in wp_users and wp_kc_patient_clinic_mappings

# Validate:
wp db query "SELECT u.ID, u.display_name, pcm.clinic_id FROM wp_users u 
             JOIN wp_kc_patient_clinic_mappings pcm ON u.ID = pcm.patient_id 
             WHERE u.user_email = 'test@example.com'"
```

### Story 2: Doctor Creates Encounter with Prescriptions
```bash
# Test: Create encounter → Add prescriptions → Verify linkage
curl -X POST .../encounters -d '{"appointment_id":123,"description":"Test encounter"}'
curl -X POST .../encounters/456/prescriptions -d '{"name":"Test Med","frequency":"Daily","duration":"5 days"}'

# Validate:
wp db query "SELECT e.id, e.description, p.name, p.frequency FROM wp_kc_patient_encounters e
             JOIN wp_kc_prescription p ON e.id = p.encounter_id WHERE e.id = 456"
```

### Story 3: Multi-Doctor Clinic Data Access
```bash
# Test: Doctor A creates encounter → Doctor B retrieves patient data
# (Using different JWT tokens for each doctor)

# Doctor A creates encounter
curl -X POST .../encounters -H "Authorization: Bearer $DOCTOR_A_TOKEN" -d '{...}'

# Doctor B retrieves patient encounters
curl -X GET .../patients/123/encounters -H "Authorization: Bearer $DOCTOR_B_TOKEN"
# Expected: Both doctors see the same encounter data (same clinic)
```

### Story 4: Automatic Billing Generation
```bash
# Test: Complete encounter → Verify bill creation
curl -X PUT .../encounters/456 -d '{"status":1,"description":"Completed consultation"}'

# Validate billing:
wp db query "SELECT b.id, b.encounter_id, b.total_amount FROM wp_kc_bills b 
             WHERE b.encounter_id = 456"
# Expected: Bill record automatically created
```

### Story 5: Role-Based Access Control
```bash
# Test receptionist access
curl -X GET .../appointments -H "Authorization: Bearer $RECEPTIONIST_TOKEN"
# Expected: Success - receptionists can manage appointments

curl -X GET .../encounters -H "Authorization: Bearer $RECEPTIONIST_TOKEN"  
# Expected: Error 403 - receptionists cannot access medical data

curl -X GET .../encounters -H "Authorization: Bearer $PATIENT_TOKEN"
# Expected: Only own encounters returned
```

## Performance Validation

### Response Time Tests
```bash
# Test appointment listing performance
time curl -X GET "http://your-site.local/wp-json/kivicare/v1/appointments?doctor_id=2&date=2025-01-15" \
  -H "Authorization: Bearer $TOKEN"
# Target: < 500ms response time

# Test patient encounter history
time curl -X GET "http://your-site.local/wp-json/kivicare/v1/patients/123/encounters" \
  -H "Authorization: Bearer $TOKEN"
# Target: < 500ms for 100+ encounters
```

### Concurrent User Test
```bash
# Simulate 10 concurrent appointment creations
for i in {1..10}; do
  curl -X POST .../appointments -H "Authorization: Bearer $TOKEN" -d '{...}' &
done
wait
# Expected: All succeed without conflicts
```

## Error Handling Validation

### Authentication Errors
```bash
# Test invalid token
curl -X GET .../patients -H "Authorization: Bearer invalid_token"
# Expected: 401 {"code":"rest_forbidden","message":"..."}

# Test expired token
curl -X GET .../patients -H "Authorization: Bearer expired_token"  
# Expected: 401 with token expiry message
```

### Data Validation Errors
```bash
# Test invalid patient data
curl -X POST .../patients -d '{"user_email":"invalid-email","clinic_id":"not_a_number"}'
# Expected: 400 {"code":"rest_invalid_param","message":"Validation failed","data":{...}}

# Test conflicting appointment
curl -X POST .../appointments -d '{"doctor_id":2,"appointment_start_date":"2025-01-15","appointment_start_time":"14:30:00",...}'
curl -X POST .../appointments -d '{"doctor_id":2,"appointment_start_date":"2025-01-15","appointment_start_time":"14:45:00",...}'
# Expected: Second request fails with time conflict error
```

### Database Integrity Tests
```bash
# Test foreign key constraints
curl -X POST .../encounters -d '{"appointment_id":99999,"description":"Test"}'
# Expected: 400 error - invalid appointment_id

# Test clinic isolation
curl -X GET .../patients?clinic_id=2 -H "Authorization: Bearer $CLINIC_1_DOCTOR_TOKEN"
# Expected: 403 error - cannot access other clinic's data
```

## Success Criteria Checklist

- [ ] All REST endpoints respond with correct HTTP status codes
- [ ] JWT authentication works for all user roles
- [ ] Role-based permissions enforced correctly
- [ ] Database transactions maintain referential integrity
- [ ] API response times < 500ms for standard operations
- [ ] Error responses include helpful debugging information
- [ ] Concurrent operations handle conflicts gracefully
- [ ] All user stories validate successfully
- [ ] No data corruption in existing KiviCare tables
- [ ] Plugin activation/deactivation works without errors

## Troubleshooting

### Common Issues
1. **Plugin Activation Fails**: Verify KiviCare plugin is active first
2. **JWT Token Invalid**: Check WordPress JWT configuration
3. **Database Errors**: Verify WordPress database permissions
4. **API 404 Errors**: Flush WordPress rewrite rules
5. **CORS Issues**: Configure WordPress CORS headers for cross-origin requests

### Debug Mode
```bash
# Enable WordPress debug mode
wp config set WP_DEBUG true
wp config set WP_DEBUG_LOG true

# Check error logs
tail -f wp-content/debug.log
```

---

**Quickstart Complete**: Ready for integration testing