CL-PM Integration Contract: Telehealth

PM-03: Appointment created with is_telehealth = true
  ↓
PM-13: Telehealth session created, platform link generated
  (pm_telehealth_sessions.appointment_id → pm_appointments.id)
  (session_status = 'scheduled', telehealth_modality set)
  ↓
PM-13: Session starts → session_status = 'active'
  → publishes telehealth_session_started event
  ↓
PM-03: Encounter created when appointment starts
  (pm_encounters.id created)
  ↓
PM-13: Session ends → session_status = 'completed'
  → publishes telehealth_session_completed event
  (payload includes telehealth_modality, patient_location, provider_location)
  ↓
CL-04: Clinician documents visit, captures telehealth clinical fields
  (cl_progress_notes with is_telehealth, modality, locations)
  ↓
CL-04: Note finalized → clinical_note_finalized event
  (includes is_telehealth, telehealth_modality in payload)
  ↓
PM-07: Charge capture applies telehealth modifiers
  (95 for synchronous audio/video, FQ for audio-only, GQ for store-forward)
  (POS = 10 for patient at home, 02 for telehealth)

appointment_id   → pm_appointments(id)
encounter_id     → pm_encounters(id)     -- link to encounter
platform         TEXT                     -- 'zoom' | 'doxy' | 'teams' etc.
session_url      TEXT
session_status   TEXT                     -- 'scheduled' | 'active' | 'completed' | 'no_show'
telehealth_modality TEXT                  -- 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring'
is_audio_only    BOOLEAN                  -- DEPRECATED: use telehealth_modality. Sunset target: 2026-Q4.
patient_location TEXT                     -- State/location of patient
provider_location TEXT                    -- State/location of provider
patient_joined_at  TIMESTAMPTZ
provider_joined_at TIMESTAMPTZ
session_ended_at   TIMESTAMPTZ
duration_minutes   INTEGER

is_telehealth       BOOLEAN DEFAULT false
telehealth_modality TEXT     -- 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring'
patient_location    TEXT     -- State/location of patient during session
provider_location   TEXT     -- State/location of provider during session
place_of_service    TEXT     -- Overrides default POS for telehealth

payload: {
  session_id: string;
  appointment_id: string;
  encounter_id?: string;
  organization_id: string;
  telehealth_modality: 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring';
  platform: string;
}

payload: {
  session_id: string;
  appointment_id: string;
  encounter_id?: string;
  organization_id: string;
  telehealth_modality: 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring';
  /** @deprecated Use `telehealth_modality` instead. Sunset target: 2026-Q4. */
  is_audio_only: boolean; // backward compat for PM-07 modifier-logic.ts until migration completes
  patient_location?: string;
  provider_location?: string;
  duration_minutes?: number;
}

payload: {
  // ... other fields
  is_telehealth: boolean;
  telehealth_modality?: 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring';
  patient_location?: string;
  provider_location?: string;
}