# 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)*