Queue Feature Developer Guide

                      Appointment (queue entry)
                           |
                  +-----------------+
                  |                 |
              Fixed/Tele       Walk-In
           (booked ahead)   (created at check-in)
                  |                 |
                  v                 v
             Encounter         Encounter
          (created later)   (created immediately)

# Association to Encounter (one-to-one)
has_one :encounter, class_name: 'Clinical::Encounter', dependent: :nullify

# Transient attribute set by GenerateToday (not persisted)
attr_accessor :time_to_doctor_ts

# Queue scopes
scope :for_date, ->(date) { where('DATE(start_time) = ?', date) }
scope :today, -> { where('DATE(start_time) = ?', Date.current) }
scope :not_cancelled, -> { where.not(status: %w[cancelled noshow]) }

proposed -> pending -> booked -> arrived -> fulfilled
                  \         \         \
                   -> cancelled   -> noshow

{
  "data": {
    "queue": [
      {
        "id": "01234567-...",
        "status": "arrived",
        "appointment_type": "walk_in",
        "start_time": "2025-01-15T10:00:00Z",
        "end_time": "2025-01-15T10:15:00Z",
        "note": "Chest pain",
        "time_to_doctor_ts": "2025-01-15T10:00:00Z",
        "queue_status": "in_progress",
        "legacy_status": "WITH_DOCTOR",
        "encounter": {
          "id": "01234567-...",
          "status": "in_progress",
          "start_time": "2025-01-15T10:02:00Z",
          "length_minutes": 15
        },
        "patient": {
          "id": "01234567-...",
          "name": "John Doe",
          "phone": "9876543210"
        },
        "practitioner": {
          "id": "01234567-...",
          "display_name": "Dr. Smith"
        }
      }
    ],
    "statistics": {
      "total_patients": 12,
      "in_progress": 1,
      "waiting": 8,
      "completed": 3,
      "avg_duration": 15
    },
    "date": "2025-01-15",
    "facility_id": "01234567-..."
  }
}

{
  "data": {
    "id": "01234567-...",
    "status": "arrived",
    "appointment_type": "walk_in",
    "start_time": "2025-01-15T10:30:00Z",
    "queue_status": "arrived",
    "legacy_status": "IN_QUEUE",
    "patient": { "id": "...", "name": "Jane Doe", "phone": "..." },
    "practitioner": { "id": "...", "display_name": "Dr. Smith" }
  }
}

{
  "errors": ["Patient is required"]
}

{
  "data": [
    {
      "id": "01234567-...",
      "display_name": "Dr. Smith",
      "role_type": "physician",
      "specialty": "General Medicine"
    }
  ]
}

{
  "data": {
    "queue": [ ... ],
    "statistics": { ... },
    "practitioner_id": "01234567-..."
  }
}

Clinical::Queue::GenerateToday.call(
  practitioner: practitioner,
  facility: facility,
  date: Date.current   # optional, defaults to today
)

result.data[:queue]            # Array of Clinical::Appointment with time_to_doctor_ts set
result.data[:statistics]       # Hash with :total_patients, :in_progress, :waiting, :completed, :avg_duration, :next_available
result.data[:practitioner_id]  # UUID

Clinical::Appointment
  .for_practitioner(practitioner.id)
  .for_facility(facility.id)
  .for_date(date)
  .not_cancelled
  .includes(:patient, :encounter, :facility, :practitioner)
  .order(:start_time)

Clinical::Encounters::TodaysQueueService.call(
  facility: facility,
  date: Date.current,     # optional
  current_user: user      # optional, for authorization context
)

result.data[:queue]        # Array of hashes (already serialized via AppointmentBlueprint :queue)
result.data[:statistics]   # Aggregated stats across all practitioners
result.data[:date]         # ISO 8601 date string
result.data[:facility_id]  # UUID

Clinical::Encounters::CheckInService.call(
  tenant: tenant,
  patient: patient,
  facility: facility,
  practitioner: practitioner,
  params: { notes: 'Fever', priority: 'urgent', telemedicine: 'true' }
)

Queue Build Order:
  1. In-progress appointments (time_to_doctor = encounter.start_time)
  2. Past fixed appointments sorted by start_time
  3. Walk-ins fitted into gaps before each future fixed appointment
  4. Future fixed appointments sorted by start_time
  5. Remaining walk-ins appended at the end

gap_minutes = (fixed_appt.start_time - time_cursor) / 60

If gap_minutes >= avg_duration (15 min):
  - Assign time_cursor to walk-in's time_to_doctor_ts
  - Advance cursor by avg_duration
  - Repeat until no gap or no more walk-ins

Then add the fixed appointment with time_to_doctor_ts = start_time

10:00 - Walk-in 1 (fitted before 10:30 fixed)
10:15 - Walk-in 2 (fitted before 10:30 fixed)
10:30 - Fixed appointment (no more gap)
10:45 - Walk-in 3 (fitted before 11:00 fixed)
11:00 - Fixed appointment

If encounter present:
  queue_status = encounter.status     (e.g., "in_progress", "finished")
Else:
  queue_status = appointment.status   (e.g., "booked", "arrived")

Frontend                    Controller                  CheckInService
   |                            |                            |
   |-- POST /queue/check_in -->|                            |
   |                            |-- resolve_patient -------->|
   |                            |   (find by ID or create)   |
   |                            |                            |
   |                            |-- CheckInService.call ---->|
   |                            |                            |-- Transaction:
   |                            |                            |   1. Create Appointment (booked, walk_in)
   |                            |                            |   2. Create Encounter (planned, ambulatory)
   |                            |                            |   3. Add primary participant
   |                            |                            |   4. Transition appt -> arrived
   |                            |                            |   5. Transition encounter -> arrived
   |                            |                            |
   |                            |<-- { appointment, encounter }
   |                            |                            |
   |                            |-- Serialize with Blueprint |
   |<-- 201 { data: ... } -----|                            |

cd backend

# All queue tests
bundle exec rspec domains/clinical/spec/models/appointment_spec.rb \
                   domains/clinical/spec/services/queue/generate_today_spec.rb \
                   domains/clinical/spec/services/encounters/check_in_service_spec.rb \
                   domains/clinical/spec/services/encounters/todays_queue_service_spec.rb \
                   domains/clinical/spec/requests/queue_spec.rb

# Single file
bundle exec rspec domains/clinical/spec/services/queue/generate_today_spec.rb

before do
  skip 'Clinical schema not available' unless Clinical::Appointment.table_exists?
end