Phase 2: clinical adapters, multi-practitioner, claim awareness, appointment followup rewrite

[crewcricle]

Adds clinical booking-system adapters, multi-practitioner support, and claim awareness to the appointment followup pipeline. Five adapters (2 real, 3 stub), a canonical appointment shape, and practitioner-scoped followup with opt-out controls.

Changes

• 5 clinical adapters: Nookal (real, API key), Halaxy (real, OAuth2 FHIR), HotDoc/Jane/PracticePal (fail-safe stubs with adapter metadata)
• Canonical appointment shape in services/appointment_shape.py with adapter capability metadata (SUPPORTS_REBOOK, ID_COLUMN, CREDENTIAL_KEYS)
• Cliniko and Square adapters ported to emit the canonical shape with practitioner/claim fields
• Shared credential helper in services/booking_credentials.py (decrypts Fernet tokens from 012_booking_credentials migration — Phase 0)
• Practitioner upsert from adapter results into practitioners table, with GET /practitioners + opt-out PATCH + follow-up stats API
• Appointment followup rewrite: loops over the canonical shape using adapter.ID_COLUMN, respects practitioner-level do-not-contact, threads practitioner_name/claim_type into messaging
• Holiday gate at job level — skips entire followup run on AU public holidays (avoids wasting Claude credit)
• Claude-before-phone fix — phone-number check runs before Claude message generation, so no API cost for patients without a phone
• Claude prompt extended with practitioner_name and claim_type params; dollar amounts excluded from SMS copy
• Claim acquisition from PMS invoice/billing endpoints (Cliniko invoices, Nookal billing, Halaxy FHIR), best-effort
• Migrations 014-016: practitioners (with RLS), patient_external_ids, appointment_claim (claim columns + followup_error/followup_message/followup_sid)

Testing

cd backend && .venv/bin/python -m pytest tests/ -x -q

164 passed, 0 failed, 2 warnings (pre-existing deprecation warning + async mock warning in menu_sync test unrelated to this PR).

New test files:

• test_nookal_adapter.py — Nookal API adapter
• test_halaxy_adapter.py — Halaxy FHIR adapter
• test_stub_adapters.py — HotDoc/Jane/PracticePal stubs
• test_booking_credentials.py — credential decryption helper
• test_claude.py — Claude prompt with practitioner/claim params
• test_practitioners_api.py — practitioner CRUD + opt-out API
• Extended test_rebook.py — multi-system rebook tests

---

Session Details

• Session: View Session
• Requested by: Unknown
• Address comments on this PR. Add (aside) to your comment to have me ignore it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
localmate	Error		Jul 22, 2026 7:53pm