classify_visit_decision_tree.md

Visit Classification Decision Tree

Decision logic used by MergeService#classify_visit when merging an UnknownClinicPatient into an existing patient.

Source: Design: Visit Type Handling When Merging Unknown Patients

flowchart TD
    Start([Unknown Visit]) --> DateCheck{admission_date == today?}

    DateCheck -->|Yes| ExistsA{Existing visit for eye + date + clinic?}
    DateCheck -->|No| ExistsB{Existing visit for eye + date + clinic?}

    ExistsA -->|Yes| ScansA{Existing visit has scans?}
    ExistsA -->|No| CreateA[/"Create visit eye.this_visit_type created_live = true"/]

    ScansA -->|Yes| Blocked[/"BLOCK entire merge"/]
    ScansA -->|No| Attach[/"Attach scan to existing visit"/]

    ExistsB -->|Yes| ScansB{Existing visit has scans?}
    ExistsB -->|No| CreateB[/"Create RetrospectiveVisit created_live = false"/]

    ScansB -->|Yes| Blocked
    ScansB -->|No| Attach

    style Blocked fill:#f87171,stroke:#dc2626,color:#fff
    style CreateA fill:#60a5fa,stroke:#2563eb,color:#fff
    style CreateB fill:#a78bfa,stroke:#7c3aed,color:#fff
    style Attach fill:#4ade80,stroke:#16a34a,color:#fff
    style Start fill:#94a3b8,stroke:#64748b,color:#fff

Loading

Outcomes:

• 🔴 Red — Block (merge cannot proceed, existing visit already has scans)
• 🟢 Green — Attach scan to existing visit (shared by both Rule A and Rule B)
• 🔵 Blue — Create visit from current eye state (Rule A — same-day only)
• 🟣 Purple — Create RetrospectiveVisit (Rule B — historical only)