Dave opencare corefeat(appointments): Implement Appointment Scheduling API for Patient-Health Worker Bookings

[King24Dave]

📌 Related Issue

Closes #7

📋 Summary

This PR implements a fully functional Appointment Scheduling API for
OpenCare-Africa. Patients can now book, reschedule, and cancel
appointments with health workers. The system enforces availability
checks, prevents double-booking, and triggers Celery-based reminder
notifications. All appointment actions are tracked in the AuditTrail.

🔧 Changes Made

New Files

• apps/patients/models.py — Appointment model with status transitions
• apps/api/serializers/appointment_serializer.py — Request/response serializers
• apps/api/views/appointment_views.py — Appointment viewsets
• apps/api/tests/test_appointments.py — Unit and integration tests
• config/tasks/appointment_reminders.py — Celery reminder task

Modified Files

• apps/api/urls.py — registered /api/v1/appointments/ routes
• config/urls.py — included appointment URLs
• config/celery.py — registered reminder task
• apps/core/models.py — extended AuditTrail for appointments
• docs/appointments.md — updated with final API usage and safeguards

📅 Appointment Status Flow

pending → confirmed → completed
                   ↘ cancelled

🔐 Role Permission Table

Action	Patient	Health Worker	Admin
Book appointment	✅	❌	✅
Cancel appointment	✅	✅	✅
Accept/Reject	❌	✅	✅
View all appointments	❌	✅	✅
View own appointments	✅	✅	✅

🧪 How to Test

1. Apply the migration:

docker-compose exec web python manage.py migrate
# OR locally:
python manage.py migrate

2. Run the test suite:

# Run all tests
python manage.py test apps.patients
python manage.py test apps.api

# Run with coverage
coverage run --source='.' manage.py test
coverage report

3. Test via Swagger UI:

docker-compose up -d
# Visit http://localhost:8000/api/docs/
# Navigate to /api/v1/appointments/

4. Test key scenarios manually:

# Book an appointment
POST /api/v1/appointments/

# Reschedule
PATCH /api/v1/appointments/{id}/

# Cancel
DELETE /api/v1/appointments/{id}/

# Check double-booking (should return 409)
POST /api/v1/appointments/ # same worker, same time slot

✅ Checklist

• Appointment model created with correct status transitions
• Double-booking prevention returns 409 Conflict
• Health worker availability validated via WorkSchedule
• Celery reminder task registered and tested
• All actions logged in AuditTrail
• API documented in Swagger at /api/docs/
• docs/appointments.md updated
• Tests written and passing
• No breaking changes to existing endpoints
• Follows PEP 8 style guidelines