UC-DOC-RES-005 - Resultaat als PDF downloaden binnen docentcontext
1. Kerngegevens
| Veld | Waarde |
|---|---|
| Usecase-ID | UC-DOC-RES-005 |
| Naam | Resultaat als PDF downloaden binnen docentcontext |
| Domein | Docent |
| Subdomein | Resultaten en geschiedenis binnen docentcontext |
| Primaire actor | Docent |
| Secundaire actor(en) | Systeem, Leerling |
| Rolcontext | Actieve docentcontext met geldige docentrol en resultaatinzage binnen eigen geautoriseerde niveaucontext |
| Betrokken schermen | Docent - Resultaatdetail, PDF-download |
| Gerelateerde usecases | UC-DOC-RES-003, UC-DOC-RES-004, UC-DOC-RES-006, UC-LLN-RES-004 |
| Primaire entiteiten | ExerciseRuns, ExerciseRunProgress, Exercises, Categories, TeacherLevels |
| Secundaire entiteiten / events | QuestPDF-exportservice, bestandsnaamgenerator, autorisatiecontrole |
| Gerelateerde popups | Niet van toepassing |
| Popupregister | Niet van toepassing |
| MoSCoW | Must |
2. Omschrijving
Deze usecase beschrijft hoe een docent een toegestaan leerlingresultaat als PDF downloadt binnen de eigen docentcontext.
De PDF gebruikt dezelfde historische resultaatcontext en inhoud als de detailweergave. De export is geen nieuwe beoordeling en wijzigt geen rungegevens.
De technische PDF-generatie is generiek en moet dezelfde autorisatiegrenzen respecteren als de schermweergave.
3. Scope
3.1 Binnen scope
- Starten van PDF-export vanuit een toegestaan resultaatdetail.
- Server-side controleren dat de docent de run mag zien.
- Samenstellen van PDF-inhoud uit historische runcontext, samenvatting, details en statistieken.
- Genereren van een veilige bestandsnaam.
- Aanbieden van het PDF-bestand als download zonder domeinmutatie.
3.2 Buiten scope
- PDF-layoutbeheer door docent.
- Wijzigen van resultaatinhoud voor export.
- Opslaan van PDF als domeinrecord.
- Exporteren van resultaten buiten docentcontext.
- Bulkexport van meerdere resultaten tegelijk.
3.3 DRY-afbakening
- Leerlingresultaten en statistiekdefinities blijven inhoudelijk bronhoudend in de leerlingresultaat- en centrale FO/TO/SRS-regels.
- Docentniveau-autorisaties worden hier toegepast, maar het wijzigen ervan blijft bronhoudend in het subdomein Leerlingen en niveau-autorisaties.
- Relatievorming en relatieontkoppeling blijven bronhoudend in het generieke relatiedomein.
- PDF-layoutregels worden niet per usecase als nieuwe bronwaarheid herhaald, maar verwijzen naar de centrale resultaat- en PDF-afspraken.
- Deze usecases maken geen eigen kopie van oefenruns, statistieken of histories voor docenten.
- Directe toegang via URL, filter of exportverzoek blijft altijd onder dezelfde autorisatiegrens vallen.
- Systeemberichten, privéberichten en meldingen worden niet aangemaakt door het bekijken van resultaten.
- Module-specifieke payload blijft eigendom van de technische module; de docentweergave gebruikt veilige representaties.
4. Pre-condities
| ID | Voorwaarde |
|---|---|
| PRE-001 | De gebruiker is succesvol ingelogd. |
| PRE-002 | De gebruiker heeft een actieve docentrol. |
| PRE-003 | De OefenHub-sessiecontext is server-side opgebouwd. |
| PRE-004 | De betrokken leerling, run of resultatenlijst valt potentieel binnen de docentcontext. |
| PRE-005 | De backend kan actuele autorisatie-, relatie- en resultaatgegevens ophalen. |
| PRE-006 | De relevante resultaatdata is beschikbaar in de persistente run- en voortgangsopslag. |
5. Post-condities
| ID | Resultaat |
|---|---|
| POST-001 | De docent ziet uitsluitend resultaten die binnen de eigen docentcontext vallen. |
| POST-002 | Geen resultaat, oefenrun, autorisatie of profielgegeven is gewijzigd door deze read-only flow. |
| POST-003 | Een verboden of verouderd verzoek is veilig geblokkeerd zonder contextlek. |
| POST-004 | De frontend toont een actuele lijst, detailweergave, export of veilige afwijzing. |
| POST-005 | Fout- en blokkadesituaties worden veilig afgehandeld zonder nieuwe domeinentiteiten te introduceren. |
| POST-006 | Vervolgacties blijven binnen de daarvoor bedoelde usecases. |
6. Trigger
De docent kiest binnen een toegestaan resultaat voor Download als PDF.
7. Normale processtroom
| Stap | Actor | Scherm / component | Actie | Systeemrespons | Data / regel |
|---|---|---|---|---|---|
| 1 | Docent | Resultaatdetail | Klikt op Download als PDF | Frontend stuurt exportverzoek | ExerciseRunId |
| 2 | Frontend | Exportactie | Stuurt verzoek naar backend | Backend start server-side controle | Geen clientexport als bron |
| 3 | Systeem | Autorisatieservice | Controleert docenttoegang tot run | Blokkeert buiten context | TeacherStudentLevelAccess |
| 4 | Systeem | Resultatenservice | Laadt historische runcontext | Bouwt exportmodel | ExerciseRuns, Exercises, Categories |
| 5 | Systeem | Resultatenservice | Laadt vraagdetails en statistieken | Vult PDF-inhoud | Runvelden en payloadrepresentatie |
| 6 | Systeem | Bestandsnaamservice | Genereert veilige bestandsnaam | Normaliseert ongeldige tekens | yyyy_MM_dd-HH.mm, categorie, oefening |
| 7 | Systeem | QuestPDF-service | Genereert PDF | Past tabel- en pagina-eindregels toe | QuestPDF |
| 8 | Systeem | Downloadresponse | Stuurt PDF naar frontend | Browser start download | application/pdf |
| 9 | Frontend | Browser | Biedt download aan | Docent ontvangt bestand | Geen domeinmutatie |
8. Alternatieve en exceptionele processtromen
| ID | Vanaf stap | Situatie | Systeemgedrag | Popup / melding | Datamutatie |
|---|---|---|---|---|---|
| ALT-001 | 3 | Docent heeft geen toegang tot resultaat | Systeem weigert export en toont geen PDF. | Niet van toepassing | Geen |
| ALT-002 | 4 | Run bestaat niet of is niet afgerond | Systeem weigert export. | Niet van toepassing | Geen |
| ALT-003 | 5 | Vraagrepresentatie is niet exporteerbaar | Systeem gebruikt veilige fallback of weigert export met generieke foutafhandeling. | Niet van toepassing | Geen |
| ALT-004 | 6 | Bestandsnaam bevat ongeldige tekens | Systeem schoont naamdelen op en begrenst lengte. | Niet van toepassing | Geen |
| ALT-005 | 7 | PDF-generatie faalt technisch | Systeem breekt download af en logt technische fout. | Niet van toepassing | Geen |
| ALT-006 | 8 | Download wordt door browser geannuleerd | Systeem wijzigt geen domeindata. | Niet van toepassing | Geen |
9. Business rules
| ID | Regel |
|---|---|
| BR-001 | PDF-export binnen docentcontext gebruikt dezelfde autorisatiecontrole als resultaatdetailweergave. |
| BR-002 | PDF-export wijzigt geen exercise run, geen statistieken en geen geschiedenis. |
| BR-003 | De PDF gebruikt historische runcontext zoals die voor het resultaat beschikbaar is. |
| BR-004 | QuestPDF is de technische richting voor PDF-generatie. |
| BR-005 | Bestandsnamen worden veilig opgeschoond en begrensd. |
| BR-006 | Vraag- en antwoordweergave mag module-specifieke exportrepresentatie gebruiken wanneer beschikbaar. |
| BR-007 | Een tabelrij mag functioneel niet onleesbaar of afgesneden worden door exportregels. |
| BR-008 | Een vervolgpagina moet voldoende context houden via herhaalde headers of vervolgmarkering volgens centrale PDF-regels. |
| BR-009 | Export buiten docentcontext is verboden. |
| BR-010 | PDF-bestanden worden niet als apart domeinrecord opgeslagen in deze flow. |
| BR-011 | PDF-export introduceert geen blijvend PDF-record en geen aparte resultaatgeschiedenis. |
| BR-012 | Een mislukte export mag geen gedeeltelijke domeinmutatie achterlaten. |
10. Datavalidatie
| Veld / object | Validatie |
|---|---|
| DocentUserId | Moet overeenkomen met de server-side ingelogde gebruiker en mag niet uit formulierinvoer worden vertrouwd. |
| StudentUserId | Moet binnen de toegestane docentcontext vallen voordat resultaten worden gelezen. |
| ExerciseRunId | Moet bestaan, afgerond zijn en binnen de toegestane context vallen. |
| TeacherLevelId | Moet onderdeel zijn van de eigen docentcontext of historische resultaatcontext waar de docent recht op heeft. |
| CategoryId | Mag alleen als filter worden toegepast binnen de reeds toegestane dataset. |
| ExerciseId | Mag alleen als filter of context worden gebruikt binnen de toegestane dataset. |
| Periodefilter | Moet geldige datums bevatten en mag niet leiden tot datasetuitbreiding buiten autorisatie. |
| Paginering | Moet worden begrensd op toegestane waarden en bij lege pagina veilig terugvallen. |
| PDF-bestandsnaam | Moet worden opgeschoond van ongeldige tekens en lengtebeperkingen respecteren. |
| Modulepayload | Mag alleen via veilige render- of exportrepresentatie worden gebruikt. |
11. Datamutaties en events
| Stap | Type | Entiteit / readmodel | Gedrag |
|---|---|---|---|
| 1 | Query | Docentcontext-readmodel | Controleert docenttoegang tot de run vóór PDF-generatie. |
| 2 | Query | ExerciseRuns / ExerciseRunProgress | Leest dezelfde historische resultaatbron als de schermweergave. |
| 3 | Tijdelijke verwerking | QuestPDF-exportservice | Bouwt een PDF-response op basis van het exportmodel zonder blijvend PDF-domeinrecord. |
| 4 | Tijdelijke verwerking | Bestandsnaamgenerator | Genereert een veilige bestandsnaam voor de downloadresponse. |
| 5 | Geen domeinmutatie | ExerciseRuns / ExerciseRunProgress | PDF-export wijzigt geen run, score, antwoord, statistiek of geschiedenis. |
| 6 | Geen domeinmutatie | TeacherStudentLevelAccess | Autorisaties worden toegepast, niet gewijzigd. |
| 7 | Geen domeinmutatie | SystemMessages / PrivateMessages / Tickets | PDF-export maakt geen systeemcommunicatie of melding aan. |
12. Geen datamutaties
| Entiteit | Reden |
|---|---|
| Users | Resultaat- en geschiedenisweergave wijzigt geen gebruikersaccount. |
| UserRoles / Roles | Bekijken of exporteren van resultaten wijzigt geen rollen. |
| UserRelationships | Docent-leerlingrelaties worden alleen gecontroleerd, niet gewijzigd. |
| TeacherStudentLevelAccess | Autorisaties worden gecontroleerd, niet aangepast. |
| TeacherLevels | Niveaucontext wordt gelezen en niet gewijzigd. |
| Categories | Categoriecontext wordt gelezen en niet gewijzigd. |
| Exercises | Oefeningcontext wordt gelezen en niet gewijzigd. |
| ExerciseRuns | Bekijken, filteren of exporteren wijzigt de run niet. |
| ExerciseRunProgress | Vraagdetails worden gelezen en niet aangepast. |
| SystemMessages | Resultaatinzage maakt geen systeemberichten aan. |
| PrivateMessages | Resultaatinzage maakt geen privéberichten aan. |
| Tickets | Resultaatinzage maakt geen melding aan. |
13. State diagram
Niet van toepassing als persistent statusmodel. De usecase leest bestaande oefenrunstatussen en autorisatiecontext, maar introduceert geen nieuwe status voor docentresultaatinzage.
14. Decision flow
15. Data lifecycle diagram
Deze usecase maakt geen nieuwe resultaatdata aan. Het lifecyclebeeld toont dat bestaande runs alleen worden gelezen.
16. Sequence diagrammen
16.1 PDF downloaden
16.2 Directe route of verouderde clientstate blokkeren
17. Popupverwijzingen
| PopupKey | Moment | Doel |
|---|---|---|
| Niet van toepassing | Alle momenten | Resultaatinzage, filtering, export en blokkades gebruiken geen nieuwe domeinspecifieke popupregister-popup. |
| Niet van toepassing | PDF-downloadfout | Een exportfout wordt via generieke foutafhandeling verwerkt zonder popupteksten in de usecase te dupliceren. |
18. Afleiding naar Functioneel Ontwerp / Technisch Ontwerp / Software Requirements Specification
| Doeldocument | Afleiding |
|---|---|
| Functioneel Ontwerp | Docentresultaten moeten expliciet contextgebonden worden beschreven: alleen resultaten van niveaus die de docent zelf aan de leerling heeft geautoriseerd of waarvoor de docent volgens de geldende docentcontext inzagerecht heeft. |
| Technisch Ontwerp | Technisch Ontwerp: oefenruns, resultaten en PDF-brondata, PDF-export, readmodels en resultaatlezers en autorisatie beschrijven de technische uitwerking. Backendqueries voor geschiedenis, filters, resultaatdetails en PDF-export moeten altijd eerst autorisatiecontext toepassen en daarna pas filters, sortering of exportlogica. |
| Software Requirements Specification | Requirements moeten vastleggen dat directe URL-toegang, filterparameters en exportverzoeken geen toegang buiten docentcontext mogen opleveren. |
| Database-informatie | ExerciseRuns en gerelateerde resultaatdata blijven bronhoudend; er is geen aparte docentresultatentabel nodig. |
| Ontwerpbronnen | Autorisatiematrix, business rules en usecase-matrices moeten docentresultaatinzage en blokkades buiten context opnemen. Read-only resultaatinzage vraagt geen nieuw domeinevent. |
| Privacy/AVG | Resultaatinzage door docenten moet dataminimalisatie respecteren en geen resultaten buiten onderwijscontext zichtbaar maken. |
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-DOC-RES-005-001 | SRS-TCH-004 SRS-PDF-001 AC-TCH-004 AC-PDF-001 | Een toegestaan resultaat als PDF kunnen exporteren |
REQ-UC-DOC-RES-005-002 | SRS-AUTH-001 SRS-TCH-001 SRS-PDF-001 AC-AUTH-001 AC-TCH-001 AC-PDF-001 | PDF-export buiten docentcontext blokkeren |
REQ-UC-DOC-RES-005-003 | SRS-LRN-009 SRS-TCH-001 SRS-PDF-001 AC-LRN-009 AC-TCH-001 AC-PDF-001 | PDF-inhoud baseren op historische runcontext |
REQ-UC-DOC-RES-005-004 | SRS-TCH-001 SRS-NFR-SEC-001 AC-TCH-001 AC-NFR-SEC-001 | Veilige bestandsnamen genereren |
REQ-UC-DOC-RES-005-005 | SRS-TCH-001 SRS-PDF-001 SRS-NFR-SEC-001 AC-TCH-001 AC-PDF-001 AC-NFR-SEC-001 | PDF-generatiefouten veilig afhandelen |
REQ-UC-DOC-RES-005-006 | SRS-TCH-004 AC-TCH-004 | Geen resultaatdata wijzigen door export |
REQ-UC-DOC-RES-005-007 | SRS-AUTH-001 SRS-LRN-009 SRS-TCH-001 AC-AUTH-001 AC-LRN-009 AC-TCH-001 | Toegang tot leerlingresultaten altijd server-side valideren |
REQ-UC-DOC-RES-005-008 | SRS-LRN-009 SRS-TCH-005 AC-LRN-009 AC-TCH-005 | Testruns uitsluiten van docentresultaten |
REQ-UC-DOC-RES-005-009 | SRS-LRN-006 SRS-TCH-004 SRS-NFR-AUD-001 AC-LRN-006 AC-TCH-004 AC-NFR-AUD-001 | Niet-afgeronde runs buiten resultaatgeschiedenis houden |
REQ-UC-DOC-RES-005-010 | SRS-TCH-001 AC-TCH-001 | Technische identifiers niet als gebruikersgerichte herkenningsgegevens tonen |
REQ-UC-DOC-RES-005-011 | SRS-TCH-004 AC-TCH-004 | Resultaatinzage zonder domeinmutatie verwerken |