triqura-ecd/docs/swift/fo-agenda-afspraken.md

🧩 Functioneel Ontwerp (FO) – Swift Agenda & Afspraken

Projectnaam: Swift - Agenda & Afspraken Module Versie: v1.0 Datum: 27-12-2024 Auteur: Colin Lit

---

1. Doel en relatie met het PRD

🎯 Doel van dit document: Dit Functioneel Ontwerp beschrijft hoe de agenda- en afsprakenfunctionaliteit binnen Swift werkt. Swift is een conversational medical scribe interface waarin gebruikers via natuurlijke taal (Nederlands) afspraken kunnen opvragen, aanmaken, wijzigen en annuleren. Dit FO beschrijft de gebruikerservaring, UI-interacties en AI-functionaliteit.

📘 Relatie met andere documenten:

• PRD: Ephemeral UI visie (nextgen-epd-prd-ephemeral-ui-epd.md) - Conversational interface voor EPD
• Swift FO v3.0: fo-swift-medical-scribe-v3.md - Basis conversational interface architectuur
• Klassieke Agenda: /app/epd/agenda - Bestaande visuele kalender (blijft bestaan voor complexe planning)
• Bouwplan: bouwplan-swift-standalone-module.md - Development roadmap

Kernprincipe:

Gebruikers kunnen via natuurlijke taal (chat of spraak) snel afspraken beheren zonder door menu's te klikken. Voor visueel overzicht en complexe planning blijft de klassieke kalender beschikbaar. Swift is de snelle, hands-free interface; klassieke agenda is de visuele planner.

Toegevoegde waarde:

Aspect	Klassieke Agenda	Swift Agenda
Gebruik	Visuele weekplanning	Quick actions, queries
Input	Klikken, formulieren	Natuurlijke taal, spraak
Snelheid	~30-60 sec voor nieuwe afspraak	~10-15 sec via chat/voice
Ideaal voor	Weekplanning, drag-drop	Tijdens telefoongesprek, hands-free

---

2. Overzicht van de belangrijkste onderdelen

🎯 Doel: Overzicht van de functionaliteit binnen de Swift Agenda module.

Hoofdonderdelen

1. Agenda Queries - Afspraken opvragen ("afspraken vandaag", "wat is volgende afspraak")
2. Quick Create - Snel afspraak maken ("maak afspraak jan morgen 14:00")
3. Cancel Flow - Afspraak annuleren ("annuleer afspraak jan")
4. Reschedule Flow - Afspraak verzetten ("verzet 14:00 naar 15:00")
5. AgendaBlock - UI component toont afspraken lijst en formulieren
6. Intent Detection - AI herkent wat gebruiker wil doen

Artifact: AgendaBlock

Het AgendaBlock is het centrale UI-component met 4 modes:

Mode	Functie	Trigger
List View	Toont chronologische lijst afspraken	"afspraken vandaag"
Create Form	Formulier voor nieuwe afspraak	"maak afspraak jan"
Cancel View	Confirmation dialog	"annuleer afspraak"
Reschedule Form	Datum/tijd aanpassing	"verzet afspraak"

---

3. User Stories

🎯 Doel: Beschrijven wat gebruikers moeten kunnen doen vanuit hun perspectief.

Primaire User Stories (P1)

ID	Rol	Doel / Actie	Verwachte waarde	Prio
US-24	Verpleegkundige	Snel overzicht afspraken vandaag	"afspraken vandaag" → lijst in AgendaBlock, <3 sec	🔴 P1
US-25	Verpleegkundige	Check volgende afspraak tijdens werk	"wat is mijn volgende afspraak?" → directe info	🔴 P1
US-27	Verpleegkundige	Snelle afspraak tijdens telefoongesprek	"maak afspraak jan morgen 14:00" → prefilled form, <15 sec	🔴 P1
US-28	Verpleegkundige	Context-aware planning	"maak afspraak met deze patiënt" → gebruikt actieve patiënt	🔴 P1
US-29	Verpleegkundige	Voice input tijdens consult	Hands-free afspraak maken via spraak	🔴 P1
US-30	Verpleegkundige	Annuleren via chat	"annuleer afspraak jan" → confirmation → done	🔴 P1
US-31	Verpleegkundige	Snel verzetten	"verzet 14:00 naar 15:00" → tijd update	🔴 P1

Secundaire User Stories (P2)

ID	Rol	Doel / Actie	Verwachte waarde	Prio
US-26	Verpleegkundige	Weekoverzicht bekijken	"agenda deze week" → gefilterde lijst	🟡 P2
US-32	Verpleegkundige	Disambiguation bij meerdere matches	Systeem vraagt "Welke Jan?" → lijst opties	🟡 P2

---

4. Functionele werking per onderdeel

🎯 Doel: Per hoofdonderdeel beschrijven wat de gebruiker kan doen en wat het systeem doet.

4.1 Agenda Query (Afspraken opvragen)

Wat doet de gebruiker:

• Typt of spreekt: "afspraken vandaag", "wat is mijn volgende afspraak", "agenda morgen"

Wat doet het systeem:

1. Intent detection: Herkent dat gebruiker afspraken wil opvragen
2. Datum parsing: Vertaalt "vandaag", "morgen", "deze week" naar datumbereik
3. Data ophalen: Haalt afspraken op uit database
4. AI response: Chat toont samenvatting: "Je hebt vandaag 3 afspraken..."
5. AgendaBlock opent: Rechts verschijnt lijst met afspraken

AgendaBlock List View bevat:

• Header met datumbereik ("Afspraken Vandaag - 27 december")
• Per afspraak: tijd, patiënt (klikbaar), type badge, locatie
• Actions per afspraak: [Details] [Annuleren]
• Footer: Link naar volledige klassieke agenda

States:

• Loading: Spinner tijdens data fetch
• Lijst met afspraken: Chronologisch geordend
• Empty state: "Geen afspraken gevonden voor [datum]" + knop "Maak nieuwe afspraak"
• Error: "Fout bij ophalen afspraken" + link naar klassieke agenda

Voorbeeld interactie:

User: "afspraken vandaag"
           ↓
AI: "Je hebt vandaag 3 afspraken:
     - 09:00 Intake Jan de Vries
     - 11:30 Behandeling Marie Jansen
     - 14:00 Vervolggesprek Piet Bakker"
           ↓
[AgendaBlock opens rechts met lijst van 3 afspraken]

---

4.2 Quick Create (Afspraak maken)

Wat doet de gebruiker:

• Typt: "maak afspraak jan morgen 14:00"
• Of spreekt via voice input (spatie-knop)

Wat doet het systeem:

1. Intent detection: Herkent 'create_appointment' intent
2. Entity extraction:
   • Patient: "jan" (fuzzy search in database)
   • Datum: "morgen" → parses naar 28-12-2024
   • Tijd: "14:00"
   • Type: default "behandeling" (kan gespecificeerd worden: "maak intake...")
3. AI response: "Ik maak een afspraak voor Jan de Vries op 28 december om 14:00."
4. AgendaBlock opent: Create form met pre-filled velden
5. Gebruiker bevestigt of past aan
6. Opslaan: Server action → database → toast "Afspraak aangemaakt!"

AgendaBlock Create Form bevat:

• Patiënt: Autocomplete dropdown (pre-filled "Jan de Vries")
• Datum: Date picker (pre-filled: 28-12-2024)
• Tijd: Time picker (pre-filled: 14:00)
• Type: Radio buttons (Intake, Behandeling, Vervolg, Telefonisch, Crisis, etc.)
• Locatie: Radio buttons (Praktijk, Online, Thuis)
• Notities: Optionele textarea
• Conflict warning: "⚠️ Je hebt al een afspraak om 14:00 met Marie" (indien van toepassing)
• Actions: [Annuleren] [✓ Afspraak maken]

Form validatie:

• Patiënt is verplicht
• Datum kan niet in het verleden
• Tijd moet binnen 07:00-20:00

Voorbeeld interactie (voice):

User: [Drukt spatie] "maak intake met Jan de Vries morgen 14:00"
           ↓
[Deepgram transcribeert live]
           ↓
AI: "Ik maak een intake-afspraak voor Jan de Vries op 28 december om 14:00."
           ↓
[AgendaBlock create form opent met prefill]
           ↓
User: [Klikt "Afspraak maken"]
           ↓
Toast: "✓ Afspraak aangemaakt!"
Chat: "Afspraak ingepland voor Jan de Vries op 28 december om 14:00."

Edge cases:

• Patiënt niet gevonden: "Ik vond geen patiënt met de naam 'jan'. Bedoel je Jan de Vries of Jan Bakker?" (disambiguation)
• Meerdere Jan's: Toont lijst met opties in AgendaBlock
• Tijd onduidelijk: "Hoe laat wil je de afspraak plannen?"
• Incomplete info: "maak afspraak" → vraagt eerst om patiënt, dan datum/tijd

---

4.3 Cancel Flow (Afspraak annuleren)

Wat doet de gebruiker:

• Typt: "annuleer afspraak jan" of "annuleer de 14:00 afspraak"

Wat doet het systeem:

1. Intent detection: Herkent 'cancel_appointment'
2. Search matching appointments:
   • Op patiëntnaam: zoekt "jan"
   • Op tijd: zoekt afspraak om 14:00 vandaag
3. Disambiguation (indien meerdere):
   • Toont lijst van matching afspraken in AgendaBlock
   • Gebruiker selecteert welke
4. Confirmation dialog:
   • Toont details van geselecteerde afspraak
   • Waarschuwing: "Deze actie kan niet ongedaan worden gemaakt"
5. Bevestigen: Status → 'cancelled', toast + chat confirmation

AgendaBlock Cancel View:

Single Match:

┌─────────────────────────────────────────┐
│ ❌ Afspraak Annuleren              [×] │
├─────────────────────────────────────────┤
│                                         │
│ Wil je deze afspraak annuleren?        │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ 28-12-2024 14:00 - 15:00            │ │
│ │ Jan de Vries - Intake               │ │
│ │ Praktijk                            │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ ⚠️ Actie kan niet ongedaan gemaakt     │
│                                         │
├─────────────────────────────────────────┤
│ [Terug]              [✓ Annuleren]     │
└─────────────────────────────────────────┘

Multiple Matches (Disambiguation):

┌─────────────────────────────────────────┐
│ ❌ Afspraak Annuleren              [×] │
├─────────────────────────────────────────┤
│ Welke afspraak wil je annuleren?       │
│                                         │
│ ○ 28-12 09:00 - Jan de Vries (Intake)  │
│ ○ 28-12 14:00 - Jan de Vries (Vervolg) │
│ ○ 03-01 11:00 - Jan de Vries (Behndl)  │
│                                         │
├─────────────────────────────────────────┤
│ [Annuleren]           [Volgende →]     │
└─────────────────────────────────────────┘

Voorbeeld interactie:

User: "annuleer afspraak jan"
           ↓
[Systeem vindt 3 afspraken met "jan"]
           ↓
AI: "Je hebt 3 afspraken met Jan. Welke wil je annuleren?"
           ↓
[AgendaBlock toont disambiguation list]
           ↓
User: [Selecteert 14:00 afspraak]
           ↓
[Confirmation dialog]
           ↓
User: [Klikt "Annuleren"]
           ↓
Toast: "Afspraak geannuleerd"
Chat: "Afspraak met Jan de Vries op 28 december om 14:00 is geannuleerd."

---

4.4 Reschedule Flow (Afspraak verzetten)

Wat doet de gebruiker:

• Typt: "verzet 14:00 naar 15:00" of "verzet jan naar dinsdag"

Wat doet het systeem:

1. Intent detection: Herkent 'reschedule_appointment'
2. Parse old & new time:
   • Oude afspraak: "14:00" vandaag
   • Nieuwe tijd: "15:00"
3. Find appointment: Zoekt matching afspraak
4. AgendaBlock opent: Edit form
5. Conflict check: Controleert of nieuwe tijd vrij is
6. Bevestigen: Update afspraak → toast + chat

AgendaBlock Reschedule Form:

┌─────────────────────────────────────────┐
│ 🔄 Afspraak Verzetten             [×]  │
├─────────────────────────────────────────┤
│                                         │
│ Afspraak                                │
│ Jan de Vries - Intake                   │
│                                         │
│ Huidige tijd                            │
│ 28-12-2024  14:00 - 15:00               │
│ (strikethrough)                         │
│                                         │
│ Nieuwe datum/tijd *                     │
│ [28-12-2024 ▼]  [15:00 ▼]              │
│                                         │
│ ✅ Geen conflicten gevonden             │
│                                         │
├─────────────────────────────────────────┤
│ [Annuleren]          [✓ Verzetten]     │
└─────────────────────────────────────────┘

Voorbeeld interactie:

User: "verzet de 14:00 naar 15:00"
           ↓
AI: "Ik verzet je afspraak van 14:00 met Jan naar 15:00."
           ↓
[AgendaBlock reschedule form opent]
           ↓
User: [Bevestigt of past aan]
           ↓
User: [Klikt "Verzetten"]
           ↓
Toast: "Afspraak verzet naar 15:00"
Chat: "Afspraak verzet naar 15:00."

---

4.5 AgendaBlock States & Lifecycle

Artifact Lifecycle:

1. Closed (default): Geen artifact zichtbaar
2. Opening: Slide-in animation (200ms from right)
3. Active: Gebruiker kan interacteren
4. Submitting: Form disabled, spinner op submit button
5. Success: Toast + chat confirmation → artifact sluit (of blijft voor volgende)
6. Error: Error message in artifact, re-enable form

Max artifacts: 3 tegelijk (tabs bovenaan bij meerdere)

• Bij 4e artifact: oudste sluit automatisch

Keyboard shortcuts:

• ⌘K / Ctrl+K - Focus chat input
• Escape - Sluit artifact
• Enter - Submit form (in form fields)

---

5. UI-overzicht (visuele structuur)

🎯 Doel: Inzicht geven in de globale schermopbouw.

Split-Screen Layout (Command Center)

┌───────────────────────────────────────────────────────────────┐
│ Context Bar: 🕐 Ochtend | 8 ptn    Jan de Vries ▼      👤 SV │
├─────────────────────────────┬─────────────────────────────────┤
│                             │                                 │
│  CHAT PANEL (40%)           │  ARTIFACT AREA (60%)            │
│                             │                                 │
│  👤 "afspraken vandaag"     │  ┌───────────────────────────┐ │
│                             │  │ 📅 Afspraken Vandaag      │ │
│  🤖 Je hebt vandaag 3       │  │                           │ │
│     afspraken:              │  │ 09:00 - Intake            │ │
│     - 09:00 Intake Jan      │  │ Jan de Vries              │ │
│     - 11:30 Behandeling     │  │ 📍 Praktijk               │ │
│     - 14:00 Vervolg         │  │ [Details] [Annuleren]     │ │
│                             │  │                           │ │
│  👤 "maak afspraak jan      │  │ 11:30 - Behandeling       │ │
│     morgen 14:00"           │  │ Marie Jansen              │ │
│                             │  │ 🌐 Online                 │ │
│  🤖 Ik maak een afspraak    │  │ [Details] [Annuleren]     │ │
│     voor Jan de Vries...    │  │                           │ │
│                             │  │ 14:00 - Vervolg           │ │
│     [AgendaBlock opent →]   │  │ Piet Bakker               │ │
│                             │  │ 📍 Praktijk               │ │
│                             │  │ [Details] [Annuleren]     │ │
│                             │  │                           │ │
│                             │  │ [📅 Open volledige        │ │
│                             │  │     agenda →]             │ │
│                             │  └───────────────────────────┘ │
│                             │                                 │
├─────────────────────────────┤                                 │
│ 💬 Typ of spreek...    🎤   │                                 │
└─────────────────────────────┴─────────────────────────────────┘

AgendaBlock Modes (UI varianten)

Mode 1: List View

• Header: Datum range + close button
• Body: Scrollable lijst van appointment cards
• Footer: Link naar klassieke agenda

Mode 2: Create Form

• Header: "Nieuwe Afspraak" + close button
• Body: Form velden (patient, datum, tijd, type, locatie, notities)
• Footer: [Annuleren] [✓ Afspraak maken]

Mode 3: Cancel View

• Header: "Afspraak Annuleren" + close button
• Body: Appointment details + warning message
• Footer: [Terug] [✓ Annuleren]

Mode 4: Reschedule Form

• Header: "Afspraak Verzetten" + close button
• Body: Huidige tijd (readonly) + nieuwe tijd (editable)
• Footer: [Annuleren] [✓ Verzetten]

Design Tokens

Colors:

• Primary: Teal-700 (#0F766E)
• User message: Amber-50 bg, amber-200 border
• AI message: Slate-100 bg, slate-300 border
• Appointment types: Blauw (intake), groen (behandeling), rood (crisis)

Spacing:

• Context bar: h-12 (48px)
• Chat/artifact gap: 16px
• Card spacing: space-y-4

Typography:

• Chat messages: text-sm
• Headers: text-base font-medium

---

6. Interacties met AI (functionele beschrijving)

🎯 Doel: Uitleggen waar AI in de flow voorkomt en wat de gebruiker ziet.

AI-functies

Locatie	AI-actie	Trigger	Input	Output
Chat Input	Intent detection	User message	"afspraken vandaag"	Intent: 'agenda_query', confidence: 1.0
Chat Input	Entity extraction	User message	"maak afspraak jan morgen 14:00"	Patient: "jan", date: tomorrow, time: "14:00"
Chat Input	Verduidelijkingsvraag	Incomplete info	"maak afspraak"	"Met welke patiënt wil je afspreken?"
Chat Panel	Streaming response	Intent detected	—	"Je hebt vandaag 3 afspraken..." (typed effect)
Patient Search	Fuzzy matching	"jan" input	Database query	Matches: "Jan de Vries", "Jan Bakker"
Date Parser	Natural language parsing	"morgen", "volgende week dinsdag"	Date string	ISO date: 2024-12-28

AI Intent Detection (Two-Tier)

Tier 1: Local Pattern Matching (<50ms)

• Fast regex-based matching
• Client-side execution
• Confidence >= 0.8 → direct gebruiken

Voorbeelden:

• "afspraken vandaag" → Pattern: /^afspraken?\b/i → Match! (confidence: 1.0)
• "maak afspraak" → Pattern: /^maak\s+afspraak/i → Match! (confidence: 1.0)

Tier 2: AI Fallback (Claude Haiku) (~400ms)

• Voor onduidelijke/complexe input
• Server-side execution
• Triggered als local confidence <0.8

Voorbeelden:

• "ik wil graag een gesprek plannen" → AI: intent: 'create_appointment', confidence: 0.75
• "verzet hem naar volgende week" → AI: intent: 'reschedule', confidence: 0.7 (patient onduidelijk)

Confidence Thresholds:

Confidence	Actie	Voorbeeld
>0.9	Direct artifact openen	"afspraken vandaag"
0.7-0.9	Artifact + bevestigingsvraag	"maak afspraak jan" (tijd ontbreekt)
0.5-0.7	Verduidelijkingsvraag in chat	"maak afspraak"
<0.5	Fallback: "Ik begrijp het niet"	Gibberish input

Voice Input (Deepgram)

Functionaliteit:

• Live transcription tijdens spreken
• Pause detection (1.5s stilte) → auto-submit
• Nederlands language model

User experience:

1. User drukt spatie (of klikt mic icon)
2. Mic wordt rood 🔴, waveform animatie
3. Live transcript verschijnt in input field
4. Na 1.5s stilte: auto-submit
5. Intent detection + artifact opening

Voorbeeld:

User: [Drukt spatie]
→ Mic: 🔴 LIVE
→ User spreekt: "maak afspraak met jan morgen om twee uur"
→ Transcript: "maak afspraak met jan morgen om twee uur"
→ [1.5s pause]
→ Auto-submit
→ AI parses: "twee uur" → "14:00"
→ AgendaBlock opent

---

7. Gebruikersrollen en rechten

🎯 Doel: Beschrijven welke rollen toegang hebben tot agenda functionaliteit.

Rol	Toegang	Beperkingen
Verpleegkundige	Eigen afspraken maken/wijzigen/annuleren	Alleen eigen practitioner_id
Behandelaar	Eigen afspraken + caseload patiënten	Alleen eigen + team afspraken
Manager	Lezen alle afspraken	Geen create/update/delete
Demo-user	Volledige functionaliteit met fictieve data	Alleen lezen

Permissies:

Actie	Verpleegkundige	Behandelaar	Manager
Agenda query (eigen)	✅	✅	✅
Agenda query (team)	❌	✅	✅
Create appointment	✅	✅	❌
Cancel appointment (eigen)	✅	✅	❌
Reschedule (eigen)	✅	✅	❌

Database-level (RLS):

• Filter op practitioner_id = current_user_id
• Voor managers: read-only view

---

8. Bijlagen & Referenties

🎯 Doel: Linken naar overige documenten.

Gerelateerde Documenten

Swift Documentatie:

• Swift FO v3.0: docs/swift/fo-swift-medical-scribe-v3.md - Basis conversational interface
• Swift Bouwplan: docs/swift/bouwplan-swift-standalone-module.md - Development roadmap
• Developer Guide Intent System: docs/swift/developer-guide-intent-system.md - Technische details intent detection
• Scalability Architecture: docs/swift/architecture-intent-scalability.md - Schaalbaarheid optimalisaties

Agenda Implementatie:

• Klassieke Agenda: /app/epd/agenda - Bestaande visuele kalender
• Agenda Actions: /app/epd/agenda/actions.ts - Server actions (wordt hergebruikt)
• Encounters Schema: Database schema voor afspraken

Design & UX:

• PRD Ephemeral UI: Conversational interface visie
• UX Research: Chat + artifacts pattern analyse

Technische Specs (voor developers)

• Gedetailleerd FO Agenda Planning: docs/swift/fo-swift-agenda-planning.md - Uitgebreide technische specificatie
• Intent Classifier: lib/swift/intent-classifier.ts - Local pattern matching
• AI Classifier: lib/swift/intent-classifier-ai.ts - Claude Haiku fallback
• Types: lib/swift/types.ts - TypeScript type definitions

Out of Scope (Toekomstige Versies)

❌ Niet in MVP:

• Full calendar grid view (blijft in klassieke agenda)
• Drag-and-drop rescheduling
• Recurring appointments ("elke dinsdag om 10:00")
• Beschikbaarheidscheck ("wanneer ben ik vrij")
• Conflict detection & resolution
• Multi-practitioner scheduling
• SMS/email notificaties

---

Wijzigingslog

Versie	Datum	Wijzigingen	Auteur
v1.0	27-12-2024	Initial version - Agenda & afspraken functionaliteit in Swift volgens FO template	Colin Lit

---

Goedkeuring:

• Product Owner: _________________________
• Lead Developer: _________________________
• UX Designer: _________________________

Status: Draft - Ter review

Volgende stappen:

1. Review met stakeholders
2. UX wireframes maken op basis van dit FO
3. Technical implementation planning
4. User testing scenario's opstellen