UC-LLN-OEF-003 — Nieuwe oefening starten

1. Kerngegevens

Veld	Waarde
Usecase-ID	UC-LLN-OEF-003
Naam	Nieuwe oefening starten
Domein	Leerling / Oefenen en voortgang
Primaire actor	Leerling
Secundaire actor(en)	OefenHub frontend, OefenHub backend, routeguard, autorisatielaag, technische module, database, SignalR-service
Rolcontext	Ingelogde leerling met geldige toegang tot de gekozen oefening binnen de actieve niveaucontext.
Betrokken schermen	Oefening-startpagina, aantal-vragen-invoer, oefenscherm, vraagcomponent, voortgangscomponent.
Gerelateerde usecases	UC-LLN-OEF-001 — Oefening-startpagina openen; UC-LLN-OEF-004 — Vraag beantwoorden; UC-LLN-OEF-006 — Geen idee gebruiken; UC-LLN-OEF-007 — Oefening onderbreken; UC-LLN-OEF-008 — Oefening afronden; UC-LLN-TOEG-003 — Oefeningstoegang controleren bij openen
Primaire entiteiten	ExerciseRuns, Exercises, ExerciseModules, TeacherLevels, TeacherLevelCategories, Users
Secundaire entiteiten / events	ExerciseRunCreated, ModuleExercisesGenerated, ExerciseRunStarted, ExerciseRunStartBlocked
Gerelateerde popups	Niet van toepassing
Popupregister	Niet van toepassing
MoSCoW	Must

2. Omschrijving

Deze usecase beschrijft hoe een leerling vanaf de oefening-startpagina een nieuwe oefening start. De leerling vult alleen het aantal vragen in. Er wordt geen apart configuratiescherm getoond. Na het kiezen van Start nieuwe genereert OefenHub direct een nieuwe exercise run en opent het oefenscherm met de eerste vraag.

De nieuwe run wordt gekoppeld aan de actuele leerling, het actieve niveau, de categorie, de concrete oefening en de technische module die bij die oefening hoort. De module levert de module-specifieke vraaginhoud, terwijl OefenHub de uniforme runmetadata, voortgangsstructuur, opslag en latere statistiekverwerking centraal beheert.

De usecase omvat het aanmaken van de run en het tonen van de eerste vraag. Het beantwoorden van de vraag, tussentijds opslaan na antwoord, Geen idee, onderbreken en afronden vallen onder vervolgusecases. De startactie mag geen bestaande niet-afgeronde run overschrijven; meerdere niet-afgeronde runs kunnen naast elkaar bestaan, waarbij Verder gaan later de laatst gestarte niet-afgeronde run gebruikt.

3. Scope

Deze usecase omvat wel:

• kiezen van Start nieuwe op de oefening-startpagina
• valideren van het ingevoerde aantal vragen
• opnieuw server-side controleren van leerlingcontext en oefeningtoegang
• aanroepen van de technische module voor vraaggeneratie
• aanmaken van een nieuwe ExerciseRuns-registratie
• vastleggen van uniforme runmetadata en module-specifieke payload
• initialiseren van server-side voortgangsstructuur
• openen van het oefenscherm met de eerste vraag
• beschikbaar maken van de runcontext voor latere live-meekijkscenario's

Deze usecase omvat niet:

• tonen van een apart configuratiescherm
• docent-testmodus; die hoort bij docentusecases
• beantwoorden of beoordelen van een vraag
• opslaan van voortgang na antwoord
• markeren van Geen idee
• afronden van de run en berekenen van eindstatistieken
• PDF-export of geschiedenisweergave
• wijzigen van oefeningconfiguratie of technische modulemetadata
• maken of wijzigen van niveauautorisaties

DRY-afbakening voor deze usecase: moduleconfiguratie en docentbeheer blijven bij docent- en modulebeheerusecases. Deze usecase gebruikt alleen de reeds bestaande concrete oefeningconfiguratie om een leerlingrun te genereren.

4. Pre-condities

ID	Voorwaarde
PRE-001	De leerling is ingelogd en heeft een actieve leerlingrol.
PRE-002	De leerling bevindt zich op een toegankelijke oefening-startpagina.
PRE-003	De concrete oefening is actief en gekoppeld aan een beschikbare technische module.
PRE-004	De actuele niveaucontext is geldig.
PRE-005	De leerling heeft server-side toegang tot de oefening binnen deze context.
PRE-006	Het aantal vragen is ingevuld of valt terug op een geldige standaardwaarde.
PRE-007	De technische module kan voor deze oefening vraaginhoud genereren.
PRE-008	De database is beschikbaar voor het transactioneel vastleggen van de nieuwe run.

5. Post-condities

ID	Resultaat
POST-001	Er bestaat een nieuwe exercise run voor de leerling, oefening en actieve niveaucontext.
POST-002	De run is niet afgerond en bevat de gegenereerde vraagpayload en initiële voortgang.
POST-003	De leerling ziet het oefenscherm met de eerste vraag.
POST-004	De run is beschikbaar voor vervolgflows zoals beantwoorden, onderbreken, hervatten en afronden.
POST-005	Er zijn geen eindstatistieken berekend.
POST-006	Bestaande niet-afgeronde runs blijven bestaan en worden niet overschreven.
POST-007	Bij een fout is geen half bruikbare run zichtbaar of hervatbaar gemaakt.

6. Trigger

De usecase start wanneer de leerling op de oefening-startpagina het aantal vragen bevestigt via de actie Start nieuwe.

7. Normale processtroom

Stap	Actor	Scherm / component	Actie	Systeemrespons	Data / regel
1	Leerling	Oefening-startpagina	Controleert of past het aantal vragen aan.	Frontend valideert basisinvoer.	Standaardwaarde is 15 vragen tenzij anders bepaald.
2	Leerling	Oefening-startpagina	Klikt op Start nieuwe.	Frontend verstuurt startverzoek.	Geen apart configuratiescherm.
3	OefenHub frontend	Routeguard	Controleert actuele sessie.	Alleen geldige sessie gaat door.	Server-side sessie is leidend.
4	OefenHub backend	Autorisatielaag	Controleert leerlingrol, niveaucontext en oefeningtoegang opnieuw.	Start wordt alleen toegestaan bij actuele toegang.	UC-LLN-TOEG-003.
5	OefenHub backend	Invoervalidatie	Valideert het aantal vragen.	Ongeldige invoer wordt geweigerd of teruggebracht naar toegestane waarde.	Positief aantal binnen grenzen.
6	OefenHub backend	Oefeningservice	Laadt oefening, categorie, niveaucontext en modulekoppeling.	Generatiecontext wordt opgebouwd.	Exercises, ExerciseModules.
7	OefenHub backend	Technische module	Roept de module aan om vragen te genereren.	Module levert module-specifieke vraagpayload.	GenerateModuleExercisesContext.
8	OefenHub backend	Runservice	Maakt nieuwe exercise run aan.	Uniforme runmetadata wordt gevuld.	Gebruiker, niveau, categorie, oefening, module, aantal.
9	OefenHub backend	Runservice	Slaat modulepayload op.	Vraaginhoud wordt JSON/base64 of equivalent opgeslagen.	Module-specifieke inhoud blijft in payload.
10	OefenHub backend	Progressservice	Initialiseert voortgangsstructuur.	Eerste vraag is klaar voor rendering; run is niet afgerond.	Vraagregels startstatus.
11	OefenHub backend	Oefenscherm-readmodel	Bouwt weergave voor vraag 1 op.	Eerste vraag en voortgang worden geretourneerd.	Bijvoorbeeld Vraag 1 van n.
12	OefenHub frontend	Oefenscherm	Rendert de eerste vraag.	Leerling kan de oefening maken.	Vervolg via UC-LLN-OEF-004.
13	OefenHub backend	Realtime / runstatus	Maakt runstatus beschikbaar voor bevoegde meekijkers.	Latere voortgangsupdates kunnen worden gedeeld.	Geen meekijkactie door leerling.

8. Alternatieve en exceptionele processtromen

ID	Vanaf stap	Situatie	Systeemgedrag	Popup / melding	Datamutatie
ALT-001	1	Aantal vragen is leeg	Systeem gebruikt geldige standaardwaarde of toont invoerfout.	Componentmelding	Geen bij fout
ALT-002	5	Aantal vragen is ongeldig	Start wordt geblokkeerd totdat invoer geldig is.	Componentmelding	Geen
ALT-003	4	Toegang tot oefening is vervallen	Start wordt geblokkeerd.	Componentmelding / toegangafhandeling	Geen
ALT-004	6	Oefening is inactief of module ontbreekt	Start wordt geblokkeerd; er wordt geen run gemaakt.	Componentmelding / foutafhandeling	Geen
ALT-005	7	Modulegeneratie faalt	Transactie wordt afgebroken; geen half bruikbare run.	Componentmelding / foutafhandeling	Geen blijvende run
ALT-006	8	Opslaan van runmetadata faalt	Startactie wordt teruggedraaid.	Componentmelding / foutafhandeling	Geen bruikbare run
ALT-007	9	Opslaan van payload faalt	Run wordt niet zichtbaar of hervatbaar gemaakt.	Componentmelding / foutafhandeling	Rollback
ALT-008	10	Initialiseren van voortgang faalt	Runcreatie wordt teruggedraaid of technisch onbruikbaar geblokkeerd.	Componentmelding / foutafhandeling	Rollback of technische blokkade
ALT-009	12	Leerling sluit pagina direct na start	Run blijft niet-afgerond met opgeslagen initiële context.	Niet van toepassing	ExerciseRuns blijft niet-afgerond
ALT-010	13	Geen live-meekijkers bevoegd	Er wordt geen voortgang naar derden gestuurd.	Niet van toepassing	Geen extra mutatie

9. Business rules

ID	Regel
BR-001	Start nieuwe genereert direct een nieuwe exercise run en opent meteen het oefenscherm.
BR-002	Er wordt geen apart configuratiescherm getoond voor leerlingen.
BR-003	De leerling mag alleen het aantal vragen invullen op de oefening-startpagina.
BR-004	De standaardwaarde voor het aantal vragen is 15 zolang geen andere centrale configuratiewaarde actief is.
BR-005	Nieuwe runs worden gekoppeld aan leerling, actieve niveaucontext, categorie, oefening en technische module.
BR-006	Module-specifieke vraaginhoud wordt in payload opgeslagen; uniforme runmetadata staat in vaste velden.
BR-007	Een nieuwe run overschrijft bestaande niet-afgeronde runs niet.
BR-008	De nieuwe run is pas afgerond na de latere afrondingsflow.
BR-009	Eindstatistieken worden niet bij start berekend.
BR-010	Toegang tot de oefening wordt op het moment van starten opnieuw server-side gecontroleerd.
BR-011	Een generatiefout mag geen half zichtbare of half hervatbare oefening opleveren.
BR-012	De technische module levert inhoud, maar centrale opslag, voortgang en statistiekkolommen blijven OefenHub-verantwoordelijkheid.
BR-013	Testoefeningen van docenten vallen niet onder deze leerlingusecase.
BR-014	De leerling ziet functionele voortgang zoals Vraag 1 van n, geen technische identifiers.

10. Datavalidatie

Veld / object	Validatie
Aantal vragen	Verplicht of standaardwaarde, positief geheel getal en binnen toegestane grenzen.
Leerlingcontext	Moet server-side actief en geldig zijn.
Niveaucontext	Moet overeenkomen met de context waarin de oefening beschikbaar is.
Oefening	Moet bestaan, actief en toegankelijk zijn.
ExerciseModule	Moet beschikbaar zijn voor generatie.
ModuleConfigurationJsonBase64	Moet bruikbaar zijn voor de technische module.
Gegenereerde payload	Moet voldoende vragen en noodzakelijke vraagdata bevatten.
ExerciseRun	Moet uniforme metadata bevatten voor gebruiker, niveau, categorie, oefening, module, aantallen en startinformatie.
Progressstructuur	Moet consistent zijn met het aantal gegenereerde vragen.
Transactie	Mag geen bruikbare partial state achterlaten bij fout.

11. Datamutaties en events

Stap	Type	Entiteit / event	Mutatie
8	Datamutatie	ExerciseRuns	Nieuwe run wordt aangemaakt met uniforme metadata, leerling, niveau, categorie, oefening, module en startinformatie.
9	Datamutatie	ExerciseRuns / payloadveld	Module-specifieke vraaginhoud wordt opgeslagen als JSON/base64 of equivalent.
10	Datamutatie	ExerciseRunProgress of voortgangsopslag	Initiële voortgangsregels worden aangemaakt of voorbereid.
8	Event	ExerciseRunCreated	Nieuwe run is aangemaakt.
7	Event	ModuleExercisesGenerated	Technische module heeft vraaginhoud gegenereerd voor deze run.
12	Event	ExerciseRunStarted	Nieuwe run is beschikbaar gemaakt voor het oefenscherm.
ALT-005	Event	ExerciseRunStartBlocked	Start is geblokkeerd of afgebroken door fout of ontbrekende voorwaarden.

12. Geen datamutaties

Entiteit	Reden
UserSettings	Starten van een oefening wijzigt geen niveaukeuze of voorkeuren.
StudentLevelAuthorizations	Toegang wordt gelezen maar niet gewijzigd.
Exercises	De concrete oefeningconfiguratie wordt niet aangepast.
ExerciseModules	De technische module wordt aangeroepen maar niet gewijzigd.
Eindstatistiekvelden	Worden pas berekend en gevuld bij afronding.
SystemMessages	Starten van een oefening maakt geen systeembericht aan.
PrivateMessages	Starten van een oefening maakt geen privébericht aan.
Ticket-entiteiten	Starten van een oefening maakt geen melding/ticket aan.

13. State diagram

14. Decision flow

15. Data lifecycle diagram

16. Sequence diagrammen

16.1 Nieuwe oefening succesvol starten

16.2 Starten faalt zonder half bruikbare run

17. Popupverwijzingen

PopupKey	Moment	Doel
Niet van toepassing	Niet van toepassing	Nieuwe oefening starten gebruikt geen domeinspecifieke popupregister-popup. Invoer- en toegangsfouten worden als component-/routeafhandeling verwerkt.

18. Afleiding naar Functioneel Ontwerp / Technisch Ontwerp / Software Requirements Specification

Doeldocument	Afleiding
Functioneel Ontwerp	Functioneel Ontwerp beschrijft starten, hervatten, beantwoorden, Geen idee, onderbreken, afronden en resultaatnavigatie binnen de leerling-oefenflow.
Technisch Ontwerp	Technisch Ontwerp: oefencatalogus, oefenmodulecontract, oefenruns en voortgang, live meekijken en frontend-oefencontext beschrijft de technische afbakening, server-side brondata, autorisatie en UI-compositie voor deze usecase.
Software Requirements Specification	Software Requirements Specification bevat centrale eisen en acceptatiecriteria voor oefenruns, voortgangsopslag, modulegedrag, foutafhandeling en veilige server-side verwerking.
Database-informatie	Database-informatie blijft bron voor ExerciseRuns, ExerciseRunProgress, payloadvelden, snapshots en soft links richting gebruiker en catalogus.
Ontwerpbronnen	Ontwerpbronnen bevatten aanvullende businessregels voor oefenflow, modulepayloads, Geen idee en voortgangsregistratie.

19. SRS-trace

Deze usecase bevat geen normatieve requirementtekst. De centrale eis en acceptatiecriteria staan in de SRS; onderstaande tabel koppelt de usecase-afleiding alleen aan centrale SRS-*- en AC-*-items.

Usecase-afleiding	Dekt	Usecasecontext
REQ-UC-LLN-OEF-003-001	SRS-RDM-001 SRS-RDM-002 SRS-RDM-003 SRS-RDM-005 SRS-LRN-001 AC-RDM-001 AC-RDM-002 AC-RDM-003 AC-RDM-005 AC-LRN-001	Een leerling vanaf de oefening-startpagina een nieuwe oefening kunnen laten starten met alleen het aantal vragen als invoer
REQ-UC-LLN-OEF-003-002	SRS-LRN-001 AC-LRN-001	Voor leerlingen geen apart configuratiescherm tonen tussen Start nieuwe en het oefenscherm
REQ-UC-LLN-OEF-003-003	SRS-LRN-009 AC-LRN-009	Het aantal vragen valideren voordat een run wordt aangemaakt
REQ-UC-LLN-OEF-003-004	SRS-AUTH-001 SRS-LRN-001 AC-AUTH-001 AC-LRN-001	Op het startmoment opnieuw server-side controleren of de leerling de oefening mag starten
REQ-UC-LLN-OEF-003-005	SRS-CAT-001 SRS-LRN-009 SRS-MOD-003 AC-CAT-001 AC-LRN-009 AC-MOD-003	Een nieuwe exercise run koppelen aan leerling, niveau, categorie, oefening en technische module
REQ-UC-LLN-OEF-003-006	SRS-LRN-009 SRS-MOD-003 AC-LRN-009 AC-MOD-003	De technische module aanroepen om module-specifieke vraaginhoud te genereren
REQ-UC-LLN-OEF-003-007	SRS-LRN-009 SRS-MOD-003 AC-LRN-009 AC-MOD-003	Module-specifieke vraaginhoud opslaan in de daarvoor bedoelde payloadstructuur
REQ-UC-LLN-OEF-003-008	SRS-LRN-003 AC-LRN-003	Initiële voortgang aanmaken of voorbereiden voordat de eerste vraag wordt getoond
REQ-UC-LLN-OEF-003-009	SRS-LRN-009 AC-LRN-009	De eerste vraag direct openen na succesvolle runcreatie
REQ-UC-LLN-OEF-003-010	SRS-LRN-008 AC-LRN-008	Bestaande niet-afgeronde runs niet overschrijven wanneer een nieuwe run wordt gestart
REQ-UC-LLN-OEF-003-011	SRS-LRN-002 SRS-LRN-007 AC-LRN-002 AC-LRN-007	Bij generatie- of opslagfouten voorkomen dat een half bruikbare run zichtbaar of hervatbaar wordt
REQ-UC-LLN-OEF-003-012	SRS-LRN-001 AC-LRN-001	Bij het starten van een nieuwe run geen eindstatistieken berekenen
REQ-UC-LLN-OEF-003-013	SRS-LRN-002 SRS-LRN-007 SRS-LIVE-001 AC-LRN-002 AC-LRN-007 AC-LIVE-001	De nieuwe run beschikbaar maken voor latere voortgangsopslag, hervatten, onderbreken, afronden en live meekijken