Lumina-MSK/proj_level_reading/DEMO_EXP/Use_Cases.md

DEMO_EXP — Use Cases (Demo UCs)

Status: Draft — Demo & Testing Only Date: June 25, 2026 Engineer: Đạt Trần Tiến (Daves Tran) Scope: These Use Cases describe the Demo-FR interactions for the "Synchronized Ritual" experiments. They are not production UCs and shall be tracked separately from FR_25_UC_SPEC.md.

---

UC-48377: View Patient List with Clinical Summary

Field	Value
UC-ID	UC-48377
Title [Verb + Noun]	View Patient List with Clinical Summary
Actor	UP5 (Diagnostic Radiologist)
System Actor	System (Backend)
Date Added	June 25, 2026
Engineer	Đạt Trần Tiến (Daves Tran)
Interaction	User-to-System
Platform	Mobile Web (PWA)
FR Link	FR-26 (VIEW PATIENT LIST WITH RESPONSIBILITY DETAILS)
Demo-FR Extensions	Demo-FR-01 (Morning Cohort Ritual — context strip), Demo-FR-02 (Agreement Moment — sign-off cascade trigger), Demo-FR-04 (Journey Mirror — longitudinal timeline entry point)

Goal: Access a structured list of patients under the user's clinical responsibility to monitor active diagnostic cases and treatment tracks.

Preconditions:

• User has valid authentication credentials and active session with the Mobile Web PWA.
• User has at least one patient case assigned under their clinical responsibility scope.

Postconditions (Success State):

• Patient roster list is fully rendered in the mobile viewport.
• Each list entry contains anonymized patient ID, scan type, diagnostic status, prescription summary, and workflow stage.
• (Demo extension) Each entry also shows synchronized context: last action actor + timestamp, active-role indicators, and pending-action flags.

Stimulus: The user clicks the "View Patient List" button in the Mobile Web PWA dashboard.

System Response: The system retrieves the authenticated user's patient roster and displays a scrollable list, each entry showing patient anonymized ID, most recent scan type, current diagnostic status (e.g., AI-graded, pending review, finalized), prescription summary, and active workflow stage. (Demo extension) The system enriches each card with synchronized context data drawn from EMR sign-off logs, scan session state, and PT scheduling records.

Verbose Form: The use case 'View Patient List with Clinical Summary' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to access a structured list of patients under the user's clinical responsibility to monitor active diagnostic cases and treatment tracks. This workflow is triggered when the user clicks the "View Patient List" button in the Mobile Web PWA dashboard, causing the system to respond by providing the system retrieves the authenticated user's patient roster and displays a scrollable list, each entry showing patient anonymized ID, most recent scan type, current diagnostic status, prescription summary, and active workflow stage.

Main Success Scenario (Happy Path):

1. Diagnostic Radiologist taps the "My Patients" navigation chip on the PWA dashboard.
2. System validates the active JWT token and queries the backend patient roster endpoint.
3. System retrieves the authenticated user's assigned patient list with associated clinical metadata (scan type, AI grade status, prescription summary, workflow stage).
4. System renders a scrollable, paginated list on the mobile viewport, with each card showing anonymized patient ID, most recent scan modality, current diagnostic status tag, and active treatment workflow indicator.
5. (Demo extension) System enriches each card entry with synchronized context strip: last action metadata, active-role indicators, and pending-action flags.
6. System enables pull-to-refresh to reload the roster without full page reload.

Alternative & Exception Flows:

• Exception A: Empty Patient Roster — If the authenticated user has no assigned patients, the system displays a placeholder state with a "No patients assigned" message and a contact administrator prompt.
• Exception B: Network Timeout / Session Expiry — If the backend request times out or the session token is invalid, the system displays a non-blocking connection error banner with a retry action.

Demo Scenario:

"The radiologist opens the app on their mobile device. Instead of a flat list of anonymized IDs, each patient card now shows a thin contextual bar: 'Case #VN-2048 — Surgeon Dr. Nguyen reviewed protocol 14:22 today | PT session scheduled 16:00 | Awaiting your grading on Scan #7'. The radiologist immediately understands where they fit in the collective care chain, without clicking into anything."

---

UC-48378: Filter Patient List by Clinical Status

Field	Value
UC-ID	UC-48378
Title [Verb + Noun]	Filter Patient List by Clinical Status
Actor	UP5 (Diagnostic Radiologist)
System Actor	System (Backend)
Date Added	June 25, 2026
Engineer	Đạt Trần Tiến (Daves Tran)
Interaction	User-to-System
Platform	Mobile Web (PWA)
FR Link	FR-26 (VIEW PATIENT LIST WITH RESPONSIBILITY DETAILS)
Demo-FR Extensions	Demo-FR-01 (Morning Cohort Ritual — context strip preserved across filters), Demo-FR-02 (Agreement Moment — filtering before sign-off)

Goal: Narrow the patient roster to a specific diagnostic or treatment sub-population to reduce cognitive load during high-volume clinical sessions.

Preconditions:

• Full patient roster is loaded and displayed in the PWA viewport (UC-48377).
• At least one filter dimension is available (status, scan type, date range).

Postconditions (Success State):

• List viewport is updated to show only matching patient entries.
• Active filter chips are rendered to indicate current constraint state.
• Context strip from UC-48377 is preserved on all filtered entries.

Stimulus: The user applies a filter (by status, scan type, or date range) to the currently displayed patient list.

System Response: The system immediately updates the list to show only patients matching the selected criteria, with visible filter chips indicating active constraints. Context strips remain intact on all visible entries.

Verbose Form: The use case 'Filter Patient List by Clinical Status' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to narrow the patient roster to a specific diagnostic or treatment sub-population to reduce cognitive load during high-volume clinical sessions. This workflow is triggered when the user applies a filter (by status, scan type, or date range) to the currently displayed patient list, causing the system to respond by providing the system immediately updates the list to show only patients matching the selected criteria, with visible filter chips indicating active constraints.

Main Success Scenario (Happy Path):

1. Diagnostic Radiologist taps a filter chip or dropdown control above the patient list (e.g., "Pending Review", "AI-Graded", "Sup-Long", "Last 7 Days").
2. System captures the selected filter parameters and re-queries the patient roster endpoint with applied constraints.
3. System updates the rendered list in-place, preserving the scroll position and context strips on all matching entries.
4. System displays active filter chips above the list to provide clear visual feedback of current constraints.
5. System enables the user to stack additional filters or clear all filters with a single "Reset" action.

Alternative & Exception Flows:

• Exception A: No Results After Filter — If the applied filter yields zero matching patients, the system displays a "No patients match current filters" empty state with a direct "Clear Filters" action button.
• Exception B: Partial Filter Failure — If one of multiple selected filters fails to apply (e.g., server timeout on a date-range constraint), the system retains the last successfully filtered list state and highlights the failed filter chip in an error state.

---

UC-48379: Navigate to Patient Detail Record

Field	Value
UC-ID	UC-48379
Title [Verb + Noun]	Navigate to Patient Detail Record
Actor	UP5 (Diagnostic Radiologist)
System Actor	System (Backend)
Date Added	June 25, 2026
Engineer	Đạt Trần Tiến (Daves Tran)
Interaction	User-to-System
Platform	Mobile Web (PWA)
FR Link	FR-26 (VIEW PATIENT LIST WITH RESPONSIBILITY DETAILS)
Demo-FR Extensions	Demo-FR-01 (Morning Cohort Ritual — navigation from enriched list), Demo-FR-02 (Agreement Moment — detail view before sign-off), Demo-FR-04 (Journey Mirror — detail view as timeline entry point)

Goal: Drill into a specific patient's consolidated clinical workspace to review full diagnostic history, AI-generated overlays, and treatment context before rendering a final judgment.

Preconditions:

• Patient roster list is rendered in the PWA viewport (UC-48377).
• Patient record contains at least one diagnostic session entry accessible by the authenticated user.

Postconditions (Success State):

• Full patient workspace is loaded, showing consolidated diagnostic history, AI overlays, prescription summaries, and active treatment protocol notes.
• All displayed data is Decree 13-scrubbed (no raw PII visible to the user).
• (Demo extension) Longitudinal timeline entry point is accessible from the detail view, enabling navigation to Demo-FR-04 Journey Mirror.

Stimulus: The user taps a specific patient entry from the list (filtered or unfiltered).

System Response: The system navigates to the patient's full clinical workspace, displaying longitudinal diagnostic history, AI-segmented anatomical overlays with GradCAM heatmaps, prescription and diagnosis summaries, and current treatment protocol notes.

Verbose Form: The use case 'Navigate to Patient Detail Record' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to drill into a specific patient's consolidated clinical workspace to review full diagnostic history, AI-generated overlays, and treatment context before rendering a final judgment. This workflow is triggered when the user taps a specific patient entry from the list (filtered or unfiltered), causing the system to respond by providing the system navigates to the patient's full clinical workspace, displaying longitudinal diagnostic history, AI-segmented anatomical overlays with GradCAM heatmaps, prescription and diagnosis summaries, and current treatment protocol notes.

Main Success Scenario (Happy Path):

1. Diagnostic Radiologist taps a patient card entry from the displayed roster list.
2. System sends a detail-record fetch request to the backend with the patient session identifier.
3. System retrieves longitudinal diagnostic history, including prior scan metadata, AI-generated segmentation overlays, GradCAM heatmaps, prescription summaries, and active treatment protocol notes.
4. System validates that all data has been through the Decree 13 scrubbing layer before rendering.
5. System renders the consolidated patient workspace, displaying a timeline of prior scans, the most recent AI-graded overlays, and current prescription and diagnosis summaries in a single rapid-consumption view.
6. (Demo extension) System enables navigation to the Journey Mirror timeline view (Demo-FR-04) from within the patient workspace.
7. System enables the radiologist to tap any historical scan entry to load the full diagnostic workspace (UC-48376).

Alternative & Exception Flows:

• Exception A: Patient Record Locked or Restricted — If the patient record is flagged with an access restriction (e.g., different responsible clinician), the system displays an "Access Restricted" dialog with a request access action rather than exposing partial data.
• Exception B: Incomplete Scrubbing Detected — If the scrubbing validation layer detects residual PII tokens in the payload, the system halts rendering and triggers a server-side re-scrubbing cycle before presenting the record.

Demo Scenario:

"The radiologist taps a patient card. The system loads the full workspace: a timeline of past scans on the left, the most recent AI overlay in the center, prescription summary below. The radiologist reviews the GradCAM heatmap, sees the Surgeon's treatment protocol note from 14:22 today, and is ready to finalize — all without leaving the mobile viewport."

---

End of Use Cases — Demo UCs (3 total)