msk_admin/Lumina-MSK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update the codebase poc ver1

Browse Source
This commit is contained in:
DatTT127
2026-07-07 15:54:17 +07:00
parent fed5f277f4
commit 1622dc8fc5
452 changed files with 83999 additions and 66328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
proj_level_reading/DEMO_EXP/Functional_Requirements.md Normal file
View File

@@ -0,0 +1,110 @@
# DEMO_EXP — Functional Requirements (Demo-FRs)
> **Status:** Draft — Demo & Testing Only
> **Date:** June 25, 2026
> **Engineer:** Đạt Trần Tiến (Daves Tran)
> **Scope:** These Demo-FRs are experimental add-ons layered onto the existing VKIST FR architecture. They are **not** production FRs and shall be tracked separately from `FR_Engineer_DB_Mobile.csv`.
---
## Demo-FR-01: "Morning Cohort Ritual" — Synchronized Patient List Entry
| Field | Value |
| :--- | :--- |
| **Demo-FR ID** | Demo-FR-01 |
| **Title** | Morning Cohort Ritual — Synchronized Patient List Entry |
| **Platform** | Mobile Web (PWA) |
| **Component** | Patient Responsibility Dashboard (extends FR-26) |
| **User Profile** | UP5 (Diagnostic Radiologist) |
| **Interaction** | User-to-System |
| **Base FR** | FR-26 (`UC-48377`: View Patient List with Clinical Summary) |
| **Sprint** | Sprint 3 (The Collaborative Workspace) |
| **Priority** | Demo / Proof-of-Concept |
| **Precondition** | User has valid authentication and FR-26 patient roster is loaded. |
| **Postcondition** | Each patient card in the roster displays a context strip showing: (1) the last collective action taken on the case (with actor + timestamp), (2) which other roles are currently active on this case, and (3) any pending action required from the radiologist. No extra navigation is required. |
| **Trigger** | When the user opens the Patient Responsibility Dashboard (`UC-48377`), the system enriches each patient card entry with synchronized context data drawn from EMR sign-off logs, scan session state, and PT scheduling records. |
| **Stimulus** | User taps "My Patients" / "View Patient List" button on the Mobile Web PWA dashboard. |
| **System Response** | System retrieves the authenticated user's patient roster AND enriches each entry with: (a) last-signal metadata (who acted, when, what action), (b) active-role indicators (Surgeon? PT? both?), (c) pending-action flags (e.g., "Awaiting your grading on Scan #7"). Renders enriched cards in-place. |
| **NFR Constraints** | Zero extra clicks — context strip rendered inline on existing cards. All data passes through Decree 13 scrub layer. Compatible with zero-GPU fallback rendering. |
**Motivation:**
Transforms a sterile data lookup into a collective handoff moment. The radiologist opens the list and instantly understands *where they fit in the care chain* — who else is working on this case, what was the last decision, and what is pending their action.
---
## Demo-FR-02: "Agreement Moment" — Sign-Off Cascade
| Field | Value |
| :--- | :--- |
| **Demo-FR ID** | Demo-FR-02 |
| **Title** | Agreement Moment — Synchronized Sign-Off Cascade |
| **Platform** | Mobile Web (PWA) |
| **Component** | Report Finalization Layer (extends FR-25) |
| **User Profile** | UP5 (Diagnostic Radiologist), Surgeon, PT, Patient/Caregiver |
| **Interaction** | User-to-System (multi-role) |
| **Base FR** | FR-25 / `UC-92006` (Finalize & Sign Electronic Record) |
| **Sprint** | Sprint 3 (The Collaborative Workspace) |
| **Priority** | Demo / Proof-of-Concept |
| **Precondition** | Radiologist has completed grading review and is ready to sign the diagnostic report. All 4 roles have active accounts in the system. |
| **Postcondition** | Upon radiologist's cryptographic seal: (1) Surgeon's dashboard receives a real-time pulse notification with finalized report summary, (2) PT's read-only view is updated with the new PT protocol card, (3) Patient/Caregiver portal receives a plain-language notification of the result, (4) EMR log entry is created. All 3 downstream notifications fire within the same synchronization window. |
| **Trigger** | Radiologist taps "Finalize & Sign" on the diagnostic report screen. |
| **Stimulus** | User (UP5) confirms sign-off action. System displays a single confirmation: "This will notify the care team and patient. Proceed?" |
| **System Response** | Upon confirmation: (1) cryptographic seal applied, (2) EMR log entry created (`UC-02423`), (3) Surgeon dashboard pulse notification dispatched via existing event bus, (4) PT protocol card delivered to PT workspace via existing FR-30 send pipeline, (5) plain-language patient notification dispatched via existing FR-19 push infrastructure. All fires within <= 2 seconds of sign-off. |
| **NFR Constraints** | Zero extra workflow steps — sign-off is a single tap. Notification infrastructure reuses existing FR-19/FR-30 pipelines. All data passes through Decree 13 scrub. No external APIs — all sync over local K3s cluster. |
**Motivation:**
Elevates the act of signing from a bureaucratic checkbox into a *synchronized collective event*. The radiologist's single action of clinical judgment becomes the trigger that unlocks the next phase of care for every other participant. The radiologist *feels* that their signature has weight and consequence.
---
## Demo-FR-03: "Daily Progress Ritual" — Synchronized PT–Patient Journal
| Field | Value |
| :--- | :--- |
| **Demo-FR ID** | Demo-FR-03 |
| **Title** | Daily Progress Ritual — Synchronized PT–Patient Journal |
| **Platform** | Mobile Web (PWA) |
| **Component** | Patient Education / Care Logic Module (extends FR-28, FR-29) |
| **User Profile** | UP8 (MSK Patient & Family Caregiver), UP6 (Physical Therapist) |
| **Interaction** | User-to-System (dual-user, time-shifted) |
| **Base FR** | FR-28 (CREATE patient treatment journal), FR-29 (UPDATE patient treatment journal) |
| **Sprint** | Sprint 4 (Patient-Facing PWA) |
| **Priority** | Demo / Proof-of-Concept |
| **Precondition** | Patient treatment journal has been initialized and is within the active treatment monitoring period. |
| **Postcondition** | Patient journal entry is saved with timestamp and trend indicator. PT dashboard for that patient is updated with a soft indicator showing the latest entry timestamp, pain level delta, and trend direction. Patient receives positive visual feedback upon submission. |
| **Trigger** | Patient submits a journal update (pain slider adjustment, symptom checkbox, or free-text entry). |
| **Stimulus** | Patient interacts with the journal entry UI on their mobile device. |
| **System Response** | (1) Journal entry is saved with timestamp and anonymized patient ID, (2) Decree 13 scrub layer validates no PII in entry, (3) PT dashboard for that patient is updated with a soft indicator: latest entry timestamp, pain level delta (e.g., "from 7 to 3"), trend arrow, (4) Patient sees positive ritual feedback (e.g., progress arc animation, culturally appropriate encouragement text). |
| **NFR Constraints** | Journal data already scrubbed before PT view (Decree 13). Ritual UI overlay is a lightweight animation layer on existing journal UI — no new screens. Zero-GPU compatible. No open-ended communication loops — data flows one-way (patient -> PT), gated by existing FR-30 send pipeline. |
**Motivation:**
Transforms a repetitive, lonely self-reporting task into a *shared daily ritual*. The patient feels *seen* — their effort is acknowledged, not just logged. The PT enters the session already connected to the patient's lived experience, turning a generic protocol execution into a continuation of a shared story of progress.
---
## Demo-FR-04: "Journey Mirror" — Longitudinal Synchronized Progress View
| Field | Value |
| :--- | :--- |
| **Demo-FR ID** | Demo-FR-04 |
| **Title** | Journey Mirror — Longitudinal Synchronized Progress View |
| **Platform** | Mobile Web (PWA) |
| **Component** | Patient Portal / History Module (extends FR-16, FR-31, FR-12) |
| **User Profile** | UP8 (MSK Patient & Family Caregiver), UP5 (Diagnostic Radiologist), UP7 (Surgeon/Orthopedic) |
| **Interaction** | User-to-System (dual-lens, same data) |
| **Base FR** | FR-16 (TRA CUU lich su kham benh), FR-31 (INTERPRET diagnostic report from Clinic to Patient), FR-12 (SYNCHRONIZE hardware-adaptive musculoskeletal models) |
| **Sprint** | Sprint 4-5 (Patient-Facing PWA -> Feedback Pipeline & Hardening) |
| **Priority** | Demo / Proof-of-Concept |
| **Precondition** | Patient has >= 2 historical scan sessions in the system. FR-16 history data is accessible. FR-31 plain-language interpretation layer is active. |
| **Postcondition** | Both clinician and patient can view the same longitudinal timeline: (1) Clinician lens shows scan dates, AI grades, GradCAM overlays, EMR sign-off timestamps, surgical decisions, (2) Patient lens shows the same timeline nodes with 3D visit thumbnails and plain-language captions. Timeline updates are synchronized — when a clinician adds a new scan, the patient's mirror view reflects it. |
| **Trigger** | User (either role) opens the "My Journey" / "Patient Journey" timeline view. |
| **Stimulus** | User navigates to the longitudinal history view from their dashboard. |
| **System Response** | (1) System retrieves full patient visit history from FR-16 history store, (2) Renders timeline nodes: each node populated from scan session data (FR-25/UC-48376), signed report metadata (FR-25/UC-92006), and plain-language interpretation (FR-31), (3) Clinician view: renders with AI grades, GradCAM overlay thumbnails, EMR timestamps, (4) Patient view: renders with zero-GPU 3D sprite-sheet thumbnails (FR-12) and plain-language captions, (5) Both views reference the same timeline data — synchronized by patient ID and visit date. |
| **NFR Constraints** | Zero-GPU fallback renders sprite-sheet thumbnails on legacy devices (FR-12). Decree 13: clinician view shows anonymized ID; patient view shows only their own record. All rendering over local K3s cluster, no external CDN. |
**Motivation:**
Creates a **shared narrative** of the patient's healing journey. Both the clinician and the patient are telling the *same story* — the clinician through clinical precision, the patient through plain language and visual empathy. The timeline becomes a ritual object that both parties return to, reinforcing trust and shared understanding across the entire care arc.
---
*End of Functional Requirements — Demo-FRs (4 total)*

100
proj_level_reading/DEMO_EXP/Motivation.md Normal file
View File

@@ -0,0 +1,100 @@
# DEMO_EXP — Motivation: "Synchronized Ritual" Concept
> **Status:** Draft — Concept Note for Demo Session
> **Date:** June 25, 2026
> **Engineer:** Đạt Trần Tiến (Daves Tran)
> **Context:** VKIST-PILOT MSK Pilot Workspace (Sprint 1-6, June 2 - September 2, 2026)
---
## 1. The UX Concept: What Is a "Synchronized Ritual"?
In UX and digital design, a **Synchronized Ritual** is the intentional creation of shared digital experiences or synchronous interactions that connect users **across time and space**. It takes a basic, habitual app action and elevates it into an emotionally resonant, collective, or deeply personalized experience.
A ritual is not just a repeated action. A *synchronized* ritual is one where:
- **Multiple users** feel connected to the **same event** at the same moment, even if they are physically apart
- **Past, present, and future** are visible in a single view — the user feels the *arc* of what they are part of
- A **basic action** (open a list, tap a button) carries **emotional weight** beyond its functional outcome
---
## 2. Why This Concept Matters for VKIST Specifically
PILOT's user research reveals **three structural loneliness problems** that Synchronized Ritual directly addresses:
### Problem 1: The Isolated Radiologist
Radiologists work in **dark, quiet reading rooms**, detached from direct patient contact and from the downstream clinicians who consume their reports. Their work is invisible until a Surgeon or PT reads it — sometimes hours or days later.
> "They are the vital gatekeepers of clinical safety. Engagement and UX research should be focused entirely on invisible workflow optimization." — User Research Result, UP5 profile
**Synchronized Ritual response:** Create moments where the radiologist's action *immediately ripples outward*. When they sign a report, they see — in real time — that the Surgeon's dashboard has pulsed, the PT's session has updated, and the patient has been notified. The radiologist *feels* their work is part of a collective machine.
### Problem 2: The Anxious, Information-Starved Patient
Patients and their caregivers are **anxious and overwhelmed**, often turning to dangerous folk remedies (leaf-wrapping, aggressive manual adjustment) because no one has translated their scan into understandable terms. The hospital consultation is brief; the patient leaves confused.
> "If the AI is expertly presented as a high-tech, highly objective authority that visually validates their human doctor's hurried diagnosis, it can significantly and immediately increase institutional trust." — User Research Result, UP8 profile
**Synchronized Ritual response:** Transform the AI-generated report into a **shared artifact** — the doctor's clinical precision and the patient's emotional understanding, synchronized in one view. The patient sees their own healing arc as a narrative of progress, not a stack of confusing documents.
### Problem 3: The Information-Siloed PT
Physical Therapists receive only **brief text prescriptions** — they lack visibility into the radiologist's scan findings, the surgeon's protocol, or the patient's subjective experience. They execute treatment in semi-blindness.
> "Vietnamese Physiotherapists struggle to accurately target internal tissue pathologies during therapy because doctors rarely share full digital DICOM imaging data down the chain, providing only brief text prescription sheets, leading to semi-blind therapeutic execution." — User Research Result, UP6 profile
**Synchronized Ritual response:** Synchronize the PT's treatment session with the radiologist's scan finding and the surgeon's protocol. The PT enters the session already connected to the full clinical chain — not just a one-page prescription.
---
## 3. The Four Demo-FRs: How Ritual Maps to Existing FR Scope
Each Demo-FR is an **add-on layer** on top of existing Functional Requirements. No new backend pipelines are required — the rituals reuse data and infrastructure that already exists or is already planned.
| Demo-FR | Ritual Moment | What Becomes Shared | Base FR(s) |
| :--- | :--- | :--- | :--- |
| **01: Morning Cohort Ritual** | Opening the patient list | The *collective context* of each case — who else is working on it, what was last decided | FR-26, FR-25/UC-92006 |
| **02: Agreement Moment** | Signing a diagnostic report | The *act of clinical judgment* ripples to Surgeon, PT, Patient simultaneously | FR-25/UC-92006, FR-19, FR-30 |
| **03: Daily Progress Ritual** | Patient logging symptoms | The *daily narrative* of recovery, shared between patient and PT before the session begins | FR-28, FR-29, FR-30, FR-20 |
| **04: Journey Mirror** | Viewing the patient's history | The *longitudinal arc* of healing, seen through two synchronized lenses (clinical + patient) | FR-16, FR-31, FR-12 |
---
## 4. The Engineering Rationale: Why This Is Not "Just UX Polish"
The Synchronized Ritual concept is grounded in PILOT's **hard NFRs and constraints**, not in abstract UX theory:
| PILOT NFR | How Demo-FRs Respect It |
| :--- | :--- |
| **Zero Workflow Friction** — no extra clicks, no extra screens | All rituals are embedded in existing actions: opening a list, signing a report, logging a symptom. The ritual is the *enriched rendering* of data that already exists. |
| **Decree 13 / Data Privacy** — strict scrubbing | Ritual data (timestamps, actor names, status chips) is already available in scrubbed form in EMR logs and scan session metadata. No new PII is introduced. |
| **Hardware Heterogeneity** — low-spec phones, old GPUs | Ritual UI uses existing rendering pipelines: patient cards, status chips, sprite-sheet thumbnails. Zero-GPU fallback is already required by FR-12. |
| **Air-Gapped Infrastructure** — no cloud, no external APIs | All synchronization happens over the local K3s cluster / FastAPI backend. The "sync" in Synchronized Ritual is *local data propagation*, not cloud-based real-time networking. |
| **Sprint 6 Deadline** — only 6 sprints | Demo-FRs are achieved by **recomposing existing data** (EMR logs, scan sessions, journal entries) into new UI patterns — not by building new data pipelines or ML models. |
---
## 5. The Stakeholder Narrative: How to Present This
The Synchronized Ritual Demo is not a feature demo. It is a **values demo**.
> "We are not showing you what the system does. We are showing you how it makes every person in this care chain feel connected to each other's work. That is the difference between a tool that processes data and a platform that honors the clinical relationship."
**The demo opens with Demo-FR-02 (Agreement Moment)** — it has the highest emotional impact: one tap, four lives informed simultaneously. Then peel back to show how each layer (01, 03, 04) builds on the same principle.
**The closing argument:**
> "All of this runs locally at PILOT. No data leaves the hospital. No extra clicks were added to anyone's workflow. And yet — the radiologist who signs a report at 14:30 knows that at 14:30, a surgeon in the OR, a PT in the treatment room, and a patient at home all received a piece of that same moment. That is what we mean by Synchronized Ritual."
---
## 6. Risks & Guardrails
| Risk | Mitigation |
| :--- | :--- |
| Ritual UI perceived as "extra work" by busy clinicians | All rituals are **implicit** — they appear in existing views (list cards, sign-off confirmation, journal screen). No new buttons or new screens. |
| Patient-facing rituals trigger anxiety (e.g., "pain went up" notification) | Ritual feedback uses **positive framing** — progress arcs, encouragement text, trend arrows. No alarmist language. |
| Synchronized data introduces a privacy concern | All ritual data is already present in EMR logs and scan sessions. The ritual layer only *re-frames* existing data — it does not aggregate new data sources. |
| Demo feels "theatrical" rather than substantive | Demo scripts use **realistic synthetic data** (e.g., "Case #VN-2048", "Dr. Nguyen", "pain 7->3") and avoid cartoonish UI flourishes. The emotional weight comes from the *logic of connection*, not decorative animation. |
| Clinician rejection of "patient-facing" features | Demo-FR-02 and Demo-FR-04 are presented from the **clinician's perspective first** — the ritual is about *their* sense of impact, not about "making patients happy." |
---
*End of Motivation — Synchronized Ritual Concept for PILOT Demo Session*

167
proj_level_reading/DEMO_EXP/Use_Cases.md Normal file
View File

@@ -0,0 +1,167 @@
# 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)*