CL-PM Integration Contract: Encounter-to-Billing Pipeline

CREATE TABLE pm_encounters (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES pf_organizations(id),
  patient_id UUID NOT NULL,
  appointment_id UUID REFERENCES pm_appointments(id),
  encounter_date DATE NOT NULL,
  encounter_type TEXT NOT NULL CHECK (encounter_type IN (
    'outpatient', 'residential_daily', 'iop', 'php',
    'crisis', 'group', 'telehealth', 'evaluation'
  )),
  status TEXT NOT NULL DEFAULT 'scheduled' CHECK (status IN (
    'scheduled', 'checked_in', 'in_progress', 'documented',
    'charge_captured', 'billed', 'cancelled', 'no_show'
  )),
  rendering_provider_id UUID NOT NULL,
  supervising_provider_id UUID,
  service_location_id UUID,
  place_of_service TEXT NOT NULL DEFAULT '11',
  -- Populated by CL-04 via event
  clinical_note_id UUID,
  note_finalized_at TIMESTAMPTZ,
  -- Populated by PM-07 via charge capture
  charge_id UUID,
  charge_captured_at TIMESTAMPTZ,
  -- Populated by PM-08 via claim submission
  claim_id UUID,
  -- Standard columns
  custom_fields JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  created_by UUID REFERENCES pf_profiles(id),
  updated_by UUID REFERENCES pf_profiles(id),
  deleted_at TIMESTAMPTZ
);

-- Indexes
CREATE INDEX idx_pm_encounters_org ON pm_encounters(organization_id);
CREATE INDEX idx_pm_encounters_patient ON pm_encounters(organization_id, patient_id);
CREATE INDEX idx_pm_encounters_date ON pm_encounters(organization_id, encounter_date);
CREATE INDEX idx_pm_encounters_status ON pm_encounters(organization_id, status)
  WHERE deleted_at IS NULL;

-- RLS
ALTER TABLE pm_encounters ENABLE ROW LEVEL SECURITY;
ALTER TABLE pm_encounters FORCE ROW LEVEL SECURITY;

-- Uses pf_has_org_access SECURITY DEFINER helper (never query RLS-protected tables in policies)
CREATE POLICY pm_encounters_select ON pm_encounters
  FOR SELECT USING (pf_has_org_access(organization_id, auth.uid()));

CREATE POLICY pm_encounters_insert ON pm_encounters
  FOR INSERT WITH CHECK (pf_has_org_access(organization_id, auth.uid()));

CREATE POLICY pm_encounters_update ON pm_encounters
  FOR UPDATE
  USING (pf_has_org_access(organization_id, auth.uid()))
  WITH CHECK (pf_has_org_access(organization_id, auth.uid()));

CREATE POLICY pm_encounters_delete ON pm_encounters
  FOR DELETE USING (pf_is_org_admin(auth.uid(), organization_id));

PM-03 Appointment created → encounter status = 'scheduled'
Patient checks in         → encounter status = 'checked_in'
Clinician starts session  → encounter status = 'in_progress'
CL-04 note finalized      → encounter status = 'documented'
                             (via clinical_note_finalized event)
PM-07 charge captured      → encounter status = 'charge_captured'
PM-08 claim submitted      → encounter status = 'billed'

interface ClinicalNoteFinalized {
  event: 'clinical_note_finalized';
  publisher: 'CL';
  subscriber: ['PM'];
  payload: {
    note_id: uuid;
    encounter_id: uuid;           // Links to pm_encounters
    patient_id: uuid;
    provider_id: uuid;            // Rendering provider
    supervising_provider_id?: uuid;
    service_date: string;         // ISO date
    begin_time: string;           // HH:MM:SS
    end_time: string;             // HH:MM:SS
    duration_minutes: number;
    note_type: string;            // 'individual' | 'group' | 'crisis' | 'family' etc.
    service_line: string;         // 'outpatient' | 'residential' | 'iop' | 'php' etc.
    cpt_code?: string;            // Suggested CPT from note type/duration
    diagnosis_codes: string[];    // ICD-10-CM codes
    place_of_service: string;     // POS code
    is_telehealth: boolean;
    telehealth_modality?: string; // 'audio_video' | 'audio_only'
    is_group: boolean;
    group_participant_count?: number;
    treatment_goal_ids: uuid[];   // Linked treatment goals
    modifiers_suggested: string[]; // Suggested modifiers (HQ, GT, 95, etc.)
  };
  metadata: {
    organization_id: uuid;
    site_id?: uuid;
    user_id: uuid;
    timestamp: string;            // ISO timestamp
    correlation_id: uuid;
    idempotency_key: uuid;        // Prevents duplicate charge creation
  };
}

-- Trigger on CL-04 note finalization
CREATE OR REPLACE FUNCTION cl_publish_note_finalized()
RETURNS TRIGGER AS $$
BEGIN
  IF NEW.status IN ('signed', 'cosigned') AND OLD.status NOT IN ('signed', 'cosigned') THEN
    PERFORM pg_notify('cl_pm_events', json_build_object(
      'event', 'clinical_note_finalized',
      'publisher', 'CL',
      'payload', json_build_object(
        'note_id', NEW.id,
        'encounter_id', NEW.encounter_id,
        'patient_id', (SELECT patient_id FROM cl_patient_charts WHERE id = NEW.chart_id),
        'provider_id', NEW.clinician_id,
        'service_date', NEW.service_date,
        'begin_time', NEW.begin_time,
        'end_time', NEW.end_time,
        'duration_minutes', NEW.duration_minutes,
        'diagnosis_codes', ARRAY[NEW.diagnosis_code],
        'is_telehealth', COALESCE(NEW.is_telehealth, false),
        'is_group', (NEW.note_type = 'group')
      ),
      'metadata', json_build_object(
        'organization_id', NEW.organization_id,
        'user_id', NEW.clinician_id,
        'timestamp', now(),
        'correlation_id', gen_random_uuid(),
        'idempotency_key', NEW.id
      )
    )::text);
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER trigger_note_finalized
AFTER UPDATE ON cl_progress_notes
FOR EACH ROW
EXECUTE FUNCTION cl_publish_note_finalized();

interface ChargeStatusChanged {
  event: 'charge_status_changed';
  publisher: 'PM';
  subscriber: ['CL'];
  payload: {
    charge_id: uuid;
    encounter_id: uuid;
    patient_id: uuid;
    old_status: string;
    new_status: string;  // 'pending' | 'reviewed' | 'approved' | 'billed' | 'void'
    cpt_code: string;
    total_charge: number;
  };
  metadata: {
    organization_id: uuid;
    user_id: uuid;
    timestamp: string;
    correlation_id: uuid;
  };
}