Bronnen en afbakening

0.1 Doel

Dit hoofdstuk beschrijft welke bronlagen voor het Functioneel Ontwerp worden gebruikt, hoe die bronlagen zich tot elkaar verhouden en wat het FO wel en niet vastlegt.

Het hoofdstuk voorkomt dat het FO verandert in:

• een volledige kopie van alle usecases;
• een technisch ontwerp;
• een databaseontwerp;
• een schermspecificatie op pixelniveau;
• een SRS-requirementmatrix;
• een verzameling losse verwijzingen zonder bronhiërarchie.

Het FO is een functioneel samenhangdocument. Het legt vast hoe OefenHub zich functioneel gedraagt, welke domeinen bestaan, welke rollen en contexten relevant zijn, welke grenzen tussen domeinen gelden en waar bronhoudende details terug te vinden zijn.

0.2 Bronpositie van het FO

Het FO is niet de enige bron van waarheid voor OefenHub.

Het FO vat domeinen samen en legt functionele samenhang vast. De bronhoudende details blijven zoveel mogelijk in de bronbestanden waar zij thuishoren.

Bronlaag	Rol in de documentatieset
FO	Functionele samenhang, domeincontracten, rolgrenzen, procesgrenzen en verwijzingen naar bronbestanden.
Usecases	Procesgedrag, actoren, triggers, hoofdflows, alternatieve flows en mutatievoorwaarden.
Database-informatie	Domeinobjecten, readmodels, history, audit, persistente grenzen en opslagbetekenis.
Ontwerpbronnen	Business rules, autorisatiematrix, statusmodellen, popupregister, command-register en event-register.
Schermdocumentatie	Schermdoel, schermcontext, zichtbare velden, acties, lege toestanden, fouttoestanden en waardelagen per scherm.
Oefenmodule-documentatie	Modulespecifieke configuratie, payloadvelden, modulegedrag en modulegrenzen.
Architectuurdocumentatie	Systeemgrens, externe systemen, containercontext en functionele implicaties van de architectuur.
Mockupdocumentatie	Visuele interpretatie, layoutindicatie en schermopbouw ter ondersteuning van tekstuele bronnen.
Registers	Traceerbaarheid naar usecases, schermen en overige bronbestanden.

Het FO gebruikt deze bronlagen om consistente functionele domeinbeschrijvingen te maken. Wanneer een detail al in een bronbestand leidend is uitgewerkt, verwijst het FO daarnaar en dupliceert het detail niet onnodig.

0.3 Duurzame bronsets

De duurzame bronsets voor het FO zijn de markdown- en documentatiebronnen die ook na afronding van FO, TO en SRS onderdeel blijven van de OefenHub-documentatiestructuur.

Bronset	Gebruik in het FO
Usecases	Leidend voor gebruikers- en beheerflows, triggers, actoren, hoofdscenario's, alternatieve scenario's en actievoorwaarden.
Database-informatie	Leidend voor domeinobjecten, readmodels, history, audit, statusvelden en functionele opslaggrenzen.
Ontwerpbronnen	Leidend voor domeinbrede business rules, autorisatiematrix, statusmodellen, popupkeys, commands en events.
Schermdocumentatie	Leidend voor schermspecifieke zichtbaarheid, acties, filtergedrag, lege toestanden, fouttoestanden en UI-betekenis.
Oefenmodules	Leidend voor modulespecifieke configuratie, vraagopbouw, antwoordcontrole, payloadbetekenis en modulepresentatie.
Architectuur	Contextbron voor systeemgrens, externe systemen, hoofdcontainers en functionele architectuurimplicaties.
Mockups HTML	Ondersteunende bron voor visuele interpretatie en schermopbouw, maar niet leidend voor dynamische waarden of definitieve domeinregels.
Functioneel ontwerp-registers	Traceerbaarheid naar gebruikte usecases, schermdocumentatie en overige bronbestanden.

Tijdelijke ruwe werkdocumenten, conversiebestanden, tussenextracties of documenten die verdwijnen zodra FO, TO en SRS definitief zijn, worden niet als duurzame bronverwijzing in FO-hoofdstukken opgenomen.

Zulke tijdelijke input kan gebruikt zijn bij de totstandkoming van de documentatieset, maar heeft geen blijvende waarde als verwijzing voor lezers of toekomstige onderhoudsrondes.

0.4 Afbakening van het FO

Het FO beschrijft wat OefenHub functioneel moet doen.

Het FO legt minimaal vast:

• welke rollen en contexten bestaan;
• welke functionele domeinen bestaan;
• welke acties gebruikers kunnen uitvoeren;
• welke voorwaarden voor zichtbaarheid, raadpleging, mutatie, export en live-acties gelden;
• welke brondata en readmodels functioneel relevant zijn;
• waar historische context leidend blijft;
• welke domeingrenzen niet overschreden mogen worden;
• welke lege toestanden normaal zijn;
• welke fouttoestanden veilig moeten worden afgehandeld;
• welke documenten bronhoudend zijn voor details.

Het FO beschrijft niet:

• concrete C#-classes;
• Blazor-componentnamen;
• database-DDL;
• migratiescripts;
• volledige API-contracten;
• CSS-detailgedrag;
• pixelperfecte mockupuitwerking;
• volledige SRS-requirements op atomair niveau;
• testcases;
• implementatievolgorde;
• sprintplanning;
• deploymentinrichting;
• infrastructuurdetails die geen functionele betekenis hebben.

0.5 Functioneel ontwerp versus technisch ontwerp

Het FO kan technische begrippen noemen wanneer die functionele betekenis hebben.

Voorbeelden:

• ExerciseRuns kan genoemd worden omdat het functioneel het hoofdrecord van een unieke oefenrun is.
• SystemMessages.EntityType + EntityId kan genoemd worden omdat dit functioneel bepaalt naar welk domeinobject een systeembericht verwijst.
• moduleKey en schemaVersion kunnen genoemd worden omdat zij nodig zijn voor functionele payloadherleidbaarheid.
• TickerQ kan genoemd worden wanneer het functioneel relevant is dat een verwerking periodiek en idempotent is.
• SignalR kan genoemd worden als realtime transport, maar niet als bron van waarheid.

Technische begrippen worden in het FO alleen gebruikt om functionele grenzen, verantwoordelijkheid of herleidbaarheid duidelijk te maken.

Het FO schrijft geen implementatiedetail voor wanneer de functionele eis ook zonder die technische keuze beschreven kan worden.

0.6 Functioneel ontwerp versus SRS

Het FO is geen volledige SRS.

Het FO beschrijft domeinregels en functionele samenhang in leesbare hoofdstukken. Een SRS kan daar later atomair toetsbare requirements uit afleiden.

FO	SRS
Beschrijft functionele domeinen en samenhang.	Splitst gedrag op in toetsbare requirements.
Geeft context, randvoorwaarden en uitzonderingen.	Geeft eenduidige acceptatie- en verificatiepunten.
Verwijst naar bronbestanden voor detail.	Kan per requirement naar FO en bronbestanden verwijzen.
Mag uitleg en rationale bevatten.	Moet compact, toetsbaar en traceerbaar zijn.

Een FO-hoofdstuk hoeft dus niet iedere requirement afzonderlijk te formuleren. Wel moet het voldoende duidelijk zijn om requirements betrouwbaar uit af te leiden.

0.7 Functioneel ontwerp versus schermdocumentatie

Het FO en de schermdocumentatie vullen elkaar aan.

Het FO beschrijft de functionele samenhang en grenzen van een domein. De schermdocumentatie beschrijft hoe die functionaliteit op concrete schermen zichtbaar wordt.

Onderwerp	Leidende bron
Domeindoel en afbakening	FO
Rol- en contextgrenzen	FO en autorisatiematrix
Procesflow	Usecases
Zichtbare velden per scherm	Schermdocumentatie
Knoppen, filters en schermacties	Schermdocumentatie en usecases
Lege toestanden per scherm	Schermdocumentatie, samengevat in FO waar domeinbreed relevant
Waardelagen en dynamische schermwaarden	Schermdocumentatie en database-informatie
Popupkeys	Popupregister en ontwerpbronnen
Exacte styling	Mockups en stylebronnen, tenzij styling functionele betekenis heeft

Het FO dupliceert niet alle velden, labels en acties uit de schermdocumentatie. Het benoemt alleen schermgedrag wanneer dat nodig is om domeingrenzen, autorisatie, lifecycle of functionele samenhang te begrijpen.

0.8 Functioneel ontwerp versus database-informatie

Database-informatie beschrijft brondata, opslaggrenzen, history, audit en readmodels.

Het FO gebruikt database-informatie om functioneel te duiden:

• welke objecten bronhoudend zijn;
• welke objecten alleen readmodels zijn;
• welke objecten history of audit vertegenwoordigen;
• welke statusvelden functionele betekenis hebben;
• welke historische context niet herschreven mag worden;
• welke gegevens niet als aparte bron van waarheid geïntroduceerd mogen worden.

Het FO schrijft geen volledige database-implementatie uit.

Wanneer het FO een object of veld noemt, betekent dat niet automatisch dat het FO nieuwe databasevelden introduceert. Nieuwe velden of tabellen worden alleen functioneel voorgeschreven wanneer dat expliciet noodzakelijk en bronconsistent is.

0.9 Functioneel ontwerp versus ontwerpbronnen

Ontwerpbronnen zijn domeinbrede contractbronnen.

Ontwerpbron	Gebruik in FO
Business rules	Domeinbrede regels die meerdere flows of rollen raken.
Autorisatiematrix	Object-, route- en actiegrenzen per rol/context.
Statusmodellen	Statuswaarden, statusovergangen en gebruikersgerichte statusafleidingen.
Command-register	Functionele mutatiecommands en commandgrenzen.
Event-register	Domeingebeurtenissen en audit-/integratiebetekenis.
Popup-register	Popupkeys, popupcontext, feedbackintentie en fout-/bevestigingsfeedback.
Popup-themes	Standaard popupvarianten en presentatie-intenties.
Header, footer en navigatie	Overkoepelende navigatie- en shellregels.

Usecases en schermdocumentatie verwijzen bij feedback bij voorkeur naar popupkeys. Het FO dupliceert geen popupteksten, knopteksten of themekeuzes wanneer het popupregister leidend is.

0.10 Functioneel ontwerp versus mockups

Mockups ondersteunen interpretatie, maar zijn niet zelfstandig leidend voor functionele brondata.

Mockups zijn nuttig voor:

• globale schermopbouw;
• visuele groepering;
• relatieve plaatsing van onderdelen;
• interpretatie van schermdocumentatie;
• herkenning van gebruikerstaal;
• responsive of layoutindicatie waar tekstuele bronnen dat ondersteunen.

Mockups zijn niet leidend voor:

• definitieve aantallen;
• testnamen;
• voorbeelddata;
• datums;
• gebruikersnamen;
• rollen;
• autorisaties;
• statusmodellen;
• exacte tellerdefinities;
• brondata;
• storagekeuzes;
• beveiligingsregels.

Wanneer een mockup en een tekstuele bron van elkaar afwijken, is de tekstuele bron leidend tenzij expliciet wordt besloten dat de mockup een nieuwere functionele keuze bevat.

0.11 Bronhiërarchie bij interpretatie

Wanneer bronnen overlappen, geldt geen simpele absolute rangorde voor alle situaties. De leidende bron hangt af van het type vraag.

Vraagtype	Primaire bron
Welke actor start een flow?	Usecases
Welke stappen en alternatieve flows bestaan?	Usecases
Welke data is bronhoudend opgeslagen?	Database-informatie
Welke statuswaarden bestaan?	Statusmodellen en database-informatie
Welke statusovergang is toegestaan?	Statusmodellen, business rules en usecases
Welke rol mag een actie uitvoeren?	Autorisatiematrix, usecases en FO-contexthoofdstukken
Welke velden zijn zichtbaar op een scherm?	Schermdocumentatie
Welke popupkey hoort bij feedback?	Popupregister
Welke tellerwaarde wordt getoond?	Schermdocumentatie, database-informatie en FO-teldefinitie
Welke modulepayloadvelden zijn modulespecifiek?	Oefenmodule-documentatie
Welke systeemgrens geldt?	Architectuurdocumentatie en FO-architectuurcontext
Welke styling is indicatief?	Mockups en stylebronnen

Bij conflicten wordt niet automatisch één bron genegeerd. Het conflict wordt geïnterpreteerd op basis van de vraagsoort en waar nodig als open punt vastgelegd.

0.12 Conflictregels

Bij tegenstrijdige bronnen gelden de volgende interpretatieregels.

0.12.1 Recente geconsolideerde markdown gaat vóór oudere ruwe input

Actuele usecases, database-informatie, ontwerpbronnen, schermdocumentatie en FO-hoofdstukken zijn leidend boven tijdelijke of vervallen werkdocumenten.

Tijdelijke ruwe consolidatiedocumenten worden niet als blijvende bronverwijzing opgenomen.

0.12.2 Procesbron en databron hebben elk hun eigen grens

Usecases zijn leidend voor procesgedrag. Database-informatie is leidend voor objectbetekenis en opslaggrenzen.

Wanneer een usecase een actie beschrijft die niet past bij de databron, wordt niet automatisch een nieuw databaseobject geïntroduceerd. Eerst wordt bepaald of de actie met bestaande objecten en domeinregels kan worden verklaard.

0.12.3 Schermzichtbaarheid is geen autorisatiebewijs

Een knop, teller, schermregel, menu-item of mockupwaarde bewijst nooit dat de gebruiker autorisatie heeft.

Iedere route, detailweergave, export, mutatie en liveactie controleert opnieuw server-side de actuele context.

0.12.4 Historische reconstructie gaat vóór actuele naamgeving

Resultaten, geschiedenis, gedeelde oefeningen, PDF-export en audit gebruiken historische context waar dat functioneel nodig is.

Latere wijzigingen aan categorieën, modules, oefeningnamen, rollen of relaties mogen historische runcontext niet stilzwijgend herschrijven.

0.12.5 Geen onnodige nieuwe bron van waarheid

Het FO introduceert geen nieuwe brondata wanneer bestaande brondata of payloadvelden al voldoende zijn.

Voor moduleherleidbaarheid gelden bijvoorbeeld bestaande payloadvelden zoals moduleKey en schemaVersion als functioneel voldoende, tenzij een bron later expliciet anders bepaalt.

0.12.6 Afgeleide waarden blijven readmodels

Tellers, badges, frontpageblokken, samenvattingen, online-overzichten en mailboxweergaven zijn afgeleide readmodels tenzij een bron expliciet anders vastlegt.

Een readmodel is geen zelfstandige autorisatiebron en geen vervanging van brondata.

0.12.7 Exports en realtime transport zijn geen brondata

PDF-export, SignalR-updates, live-viewpresentatie en browsermarkers zijn geen bron van waarheid.

Zij presenteren of transporteren informatie uit brondata, maar mogen brondata niet vervangen.

0.12.8 Beheercontext is geen vrije bypass

Een beheerder heeft brede beheerrechten, maar krijgt niet automatisch vrije eindgebruikersrechten.

Beheeracties blijven scoped, server-side geautoriseerd en auditbaar. Beheerdercontext geeft bijvoorbeeld geen regulier recht om live mee te kijken met actieve leerlingruns.

0.13 DRY-principes

Het FO moet DRY blijven.

Dat betekent:

• usecases worden niet volledig overgenomen;
• schermdocumentatie wordt niet volledig herhaald;
• database-informatie wordt niet omgezet naar DDL in het FO;
• popupteksten en template-inhoud worden niet gedupliceerd wanneer registers of templates leidend zijn;
• waardelijsten worden alleen opgenomen wanneer zij functioneel nodig zijn voor domeinbegrip;
• bronverwijzingen worden gebruikt om detailinformatie vindbaar te houden;
• hoofdstukken verwijzen naar elkaar wanneer een onderwerp elders bronhoudend is uitgewerkt.

Een FO-hoofdstuk mag wel samenvatten wat essentieel is om het domein te begrijpen.

Een samenvatting is passend wanneer zij:

• domeingrenzen verduidelijkt;
• rollen en contexten afbakent;
• lifecycle of statusgedrag samenvat;
• bron-van-waarheidregels benoemt;
• uitzonderingen of fouttoestanden uitlegt;
• voorkomt dat lezers verkeerde conclusies trekken uit UI, mockups of losse bronfragmenten.

0.14 Linkbeleid

FO-hoofdstukken gebruiken klikbare relatieve Docusaurus-links naar bronbestanden.

Voorbeelden:

Type verwijzing	Vorm
Naar ander FO-hoofdstuk	[Rollen, context en autorisatie](./02-rollen-context-en-autorisatie)
Naar usecase	[Leerling-frontpage bekijken](../usecases/leerling/frontpage-en-niveaucontext/uc-lln-fp-001_leerling-frontpage-bekijken)
Naar database-informatie	[Oefenruns, delen en voortgang](../database_informatie/07_oefenruns-delen-en-voortgang)
Naar ontwerpbron	[Autorisatiematrix](../ontwerpbronnen/autorisatiematrix)
Naar schermdocumentatie	[Leerling oefening](../schermdocumentatie/leerling/04_oefening)
Naar oefenmodule	[Optellen en aftrekken simpel](../oefen_modules/rekenen/optellen_en_aftrekken_simpel/intro)

FO-hoofdstukken mogen geen verwijzingen bevatten zoals “zie de docs” of “zoek in de bronbestanden” zonder klikbare link.

Wanneer een bron nog ontbreekt of niet betrouwbaar geopend kan worden, wordt dat als open punt of extractienotitie vastgelegd.

0.15 Markdownbeleid

FO-hoofdstukken worden in markdown onderhouden.

Daarvoor gelden minimaal de volgende regels:

• tabellen zijn echte markdown-tabellen;
• tabelachtige platte tekst wordt vervangen door echte tabellen;
• koppen volgen een logische hiërarchie;
• lange opsommingen worden waar mogelijk thematisch gegroepeerd;
• bronverwijzingen staan in een herkenbare tabel of paragraaf;
• technische identifiers worden alleen genoemd wanneer zij functionele betekenis hebben;
• versie-informatie wordt niet per hoofdstuk herhaald;
• relatieve links worden gebruikt voor interne Docusaurus-documenten.

0.16 Versiebeleid

Versie-informatie hoort centraal in Functioneel Ontwerp OefenHub.

Afzonderlijke FO-hoofdstukken noemen geen eigen FO-versie zoals v0.x.

Wanneer een hoofdstuk inhoudelijk wordt herwerkt, blijkt dat uit:

• de gitgeschiedenis;
• het commitbericht;
• de reviewnotities;
• eventuele bron- of extractienotities;
• de centrale versiepagina wanneer een formele FO-versie wordt verhoogd.

Dit voorkomt dat losse hoofdstukken verschillende versienummers blijven tonen.

0.17 Hoofdstukstijl

Nieuwe of gerefactorde FO-hoofdstukken gebruiken bij voorkeur dezelfde structuur.

Een hoofdstuk bevat waar relevant:

• doel;
• domeinafbakening;
• bronpositie;
• bron-van-waarheidregels;
• rollen en contexten;
• lifecycle of proceslagen;
• zichtbaarheid en autorisatie;
• mutatiegrenzen;
• readmodels en tellers;
• audit, history en logging;
• privacy- en veiligheidsgrenzen;
• lege toestanden;
• fouttoestanden;
• relatie tot andere FO-hoofdstukken;
• gerelateerde bronverwijzingen.

Niet ieder hoofdstuk hoeft al deze secties te bevatten. De structuur wordt toegepast voor zover zij functioneel waarde toevoegt.

0.18 Domeincontractstijl

Voor grote functionele domeinen wordt het FO-hoofdstuk behandeld als een domeincontract.

Een domeincontract beschrijft:

Vraag	Betekenis
Wat is dit domein?	Doel, scope en afbakening.
Welke brondata hoort erbij?	Bronobjecten, readmodels, history en audit.
Welke aanpalende domeinen lijken erop maar zijn anders?	Grenzen met bijvoorbeeld berichten, popups, systeemnotificaties, content of modules.
Welke rollen hebben toegang?	Rolcontexten en relatiecontexten.
Welke acties bestaan?	Raadplegen, aanmaken, wijzigen, verwijderen, exporteren, live volgen of beheren.
Welke acties bestaan juist niet?	Expliciete niet-doelen en niet-toegestane shortcuts.
Wat gebeurt met historie?	Historische reconstructie, snapshots en niet-herschrijven.
Wat gebeurt bij lege data?	Geldige lege toestanden.
Wat gebeurt bij fouten?	Veilige foutafhandeling zonder datalekken.
Waar staat het detail?	Klikbare bronverwijzingen.

Deze stijl voorkomt dat het FO alleen een korte samenvatting is en helpt toekomstige TO- en SRS-uitwerking.

0.19 Brongebruik per functioneel domein

Per functioneel domein kunnen andere bronlagen zwaarder wegen.

Domein	Zwaartepunt in bronnen
Rollen en autorisatie	Autorisatiematrix, usecases, database-informatie en FO-contextregels.
Frontpages	Usecases, schermdocumentatie, contentbeheer, systeemnotificaties en database-readmodels.
Account en profiel	Accountusecases, identitygrens, database-informatie en schermdocumentatie.
Relatiebeheer	Relatieusecases, database-informatie, berichten en autorisatiebronnen.
Oefencatalogus	Docentusecases, database-informatie, modulebronnen, beheerusecases en schermdocumentatie.
Leerlingruns	Leerlingusecases, database-informatie, modulepayloads, live-viewbronnen en resultaatbronnen.
Gedeelde oefeningen	Leerlingdeelusecases, relatiebeheer, database-informatie en communicatiebronnen.
Docentfunctionaliteit	Docentusecases, database-informatie, schermdocumentatie en autorisatiematrix.
Ouder-/voogdfunctionaliteit	Ouder-/voogdusecases, relatiebeheer, oefenrunbronnen en live-viewbronnen.
Beheerderfunctionaliteit	Beheerusecases, database-informatie, ontwerpbronnen, beheerlogging en schermdocumentatie.
Berichten en notificaties	Communicatie-database, berichtenusecases, systeemnotificatiebronnen en popupregister.
Meldingen	Ticketusecases, statusmodellen, database-informatie, berichten en beheerflows.
PDF-export	Resultaatusecases, database-informatie, module-exportrepresentatie en PDF-afbakening.
Architectuurcontext	C4-documentatie, database-informatie en functionele domeingrenzen.

0.20 Autorisatie als overkoepelende interpretatieregel

Autorisatie is een server-side verantwoordelijkheid.

Voor alle FO-hoofdstukken geldt:

• clientstate bepaalt geen rechten;
• zichtbare navigatie bepaalt geen rechten;
• routeparameters bepalen geen rechten;
• filters bepalen geen rechten;
• browsergeschiedenis bepaalt geen rechten;
• bookmarks bepalen geen rechten;
• badges bepalen geen rechten;
• readmodels bepalen geen rechten;
• exports controleren opnieuw autorisatie;
• live-acties controleren opnieuw autorisatie;
• mutaties controleren opnieuw autorisatie.

De frontend mag gebruikers helpen navigeren, maar mag toegang nooit verruimen.

0.21 Historische context als overkoepelende interpretatieregel

Historische data moet functioneel reconstrueerbaar blijven.

Dit geldt onder meer voor:

• afgeronde oefenruns;
• resultaten;
• geschiedenis;
• PDF-export;
• gedeelde oefeningen;
• ticketgeschiedenis;
• relatiegeschiedenis;
• beheerhistory;
• modulemigraties;
• categoriemigraties;
• accountlifecycle;
• systeemberichtcontext waar relevant.

Latere wijzigingen aan live configuratie mogen historische context niet onbedoeld herschrijven.

0.22 Readmodels, tellers en badges

Readmodels, tellers en badges zijn afgeleide waarden.

Voor iedere teller of badge moet functioneel duidelijk zijn:

Aspect	Vraag
Bronobject	Welke bronobjecten worden geteld?
Statusfilter	Welke statussen tellen mee?
Contextfilter	Welke rol-, relatie-, niveau- of objectcontext begrenst de telling?
Tijdvenster	Geldt een periode of peilmoment?
Activiteitsfilter	Tellen inactieve, verlopen of soft-deleted records mee?
Testdata	Tellen testrecords mee?
Distinct-logica	Worden unieke objecten geteld of koppelingen?
Autorisatie	Wordt uitsluitend data geteld die de gebruiker mag zien?

Tellerwaarden in mockups zijn voorbeeldwaarden, tenzij een tekstuele bron expliciet anders bepaalt.

0.23 Privacy- en veiligheidsregels

FO-hoofdstukken moeten privacy- en veiligheidsgrenzen expliciet benoemen waar zij domeinrelevant zijn.

Algemene regels:

• toon geen technische payloads aan gewone gebruikers;
• toon geen stacktraces, tokens, secrets of interne identifiers in gebruikersfeedback;
• toon geen inhoud van objecten waarvoor autorisatie ontbreekt;
• lek geen kindnamen, antwoorden, runinhoud of relatiegegevens bij geweigerde toegang;
• log technische fouten herleidbaar maar zonder gevoelige gegevens;
• anonimisering bewaart functionele reconstructie zonder actuele persoonsgegevens;
• beheeracties zijn auditbaar;
• exportacties controleren opnieuw toegang.

0.24 Featuretoggles en systeeminstellingen

Featuretoggles en systeeminstellingen zijn verschillende domeinen.

Begrip	Betekenis
Featuretoggle	Schakelt een expliciet togglebare functie aan of uit.
Systeeminstelling	Bevat een beheerbare waarde met datatype en invoervorm.
Popup	Actie- of foutfeedback via popupkey.
Systeemnotificatie	Tijdelijke of geplande overlay na frontpageload.
Contentblok	Tekstuele inhoud op een vaste plek.

FO-hoofdstukken mogen deze mechanismen niet door elkaar halen.

Een contentblok is geen featuretoggle. Een systeemnotificatie is geen popupregister-popup. Een mailbox-systeembericht is geen systeemnotificatie.

0.25 Oefenmodules en payloads

Oefenmodule-documentatie is leidend voor modulespecifieke configuratie en payloadbetekenis.

Het FO bewaakt daarbij de generieke platformgrens:

• OefenHub beheert rollen, context, autorisatie en run-lifecycle;
• OefenHub bewaart generieke runmetadata, totalen, statistieken en geschiedenis;
• de module levert modulespecifieke configuratie, vraaggeneratie en antwoordcontrole;
• modulepayloads blijven modulespecifiek;
• uniforme velden blijven generiek uitleesbaar;
• bestaande payloadvelden zoals moduleKey en schemaVersion zijn leidend voor schemaherleidbaarheid;
• historische runs worden niet herschreven door latere modulewijzigingen.

0.26 Realtime, jobs en exports

Realtime transport, background jobs en exports hebben functionele betekenis, maar zijn geen primaire brondata.

Mechanisme	FO-betekenis
SignalR / realtime	Transport voor snelle updates, live meekijken en badges. Geen bron van waarheid.
TickerQ / periodieke jobs	Periodieke, idempotente verwerking waar functioneel nodig. Geen losse gebruikersactie.
QuestPDF / PDF-export	Exportrepresentatie van historische resultaatdata. Geen permanent PDF-domeinrecord tenzij later expliciet toegevoegd.
Browserwaarden	Lokale presentatie- of voorkeursspiegeling. Geen autorisatiebron.

0.27 Lege toestanden in het FO

Lege toestanden zijn normale functionele toestanden wanneer toegang wel bestaat maar relevante data ontbreekt.

Voorbeelden:

• geen gekoppelde leerlingen;
• geen gekoppelde kinderen;
• geen toegankelijke oefeningen;
• geen afgeronde resultaten;
• geen openstaande meldingen;
• geen berichten;
• geen actieve systeemnotificaties;
• geen beschikbare modules;
• geen contentgeschiedenis;
• geen zoekresultaten;
• geen online kinderen of leerlingen;
• geen hervatbare oefenrun.

Een lege toestand is geen autorisatiefout, tenzij de bron expliciet anders bepaalt.

Lege toestanden mogen informatief zijn en naar een passende vervolgstap verwijzen, maar mogen geen verborgen data of autorisatie-informatie lekken.

0.28 Fouttoestanden in het FO

Fouttoestanden ontstaan wanneer een gevraagde context niet veilig kan worden opgebouwd of wanneer een actie niet geldig is.

Voorbeelden:

• account is inactief;
• rolcontext ontbreekt;
• relatie is beëindigd;
• niveauautorisatie is ingetrokken;
• oefening is in onderhoud;
• module is niet beschikbaar;
• run bestaat niet;
• run is niet afgerond terwijl resultaatdetail wordt gevraagd;
• ticket is niet toegankelijk;
• systeemnotificatie heeft ongeldige datums;
• popupkey bestaat niet;
• exportcontext is niet geautoriseerd;
• live-meekijkcontext is vervallen;
• een mutatie botst met actuele status.

Fouttoestanden worden veilig afgehandeld zonder technische details, gevoelige data of gedeeltelijke objectinhoud te tonen buiten de toegestane context.

0.29 Open punten en buiten scope

Niet ieder open punt hoort in ieder hoofdstuk.

Structurele open punten en buiten-scope-afspraken worden centraal verzameld in Open punten en buiten scope.

Een domeinhoofdstuk mag een specifiek open punt benoemen wanneer het nodig is voor de interpretatie van dat domein.

Voorbeelden:

• een nog te kiezen SystemMessages.EntityType voor gedeelde oefeningen;
• een nog niet volledig uitgewerkt retentiebeleid;
• een toekomstige uitbreiding rond bijlagen;
• een toekomstige publieke API;
• een toekomstige mobiele app;
• een toekomstige workflow buiten de initiële scope.

Wanneer het open punt meerdere domeinen raakt, hoort het uiteindelijk ook centraal in hoofdstuk 20 te staan.

0.30 Onderhouds- en reviewregels

Bij onderhoud van FO-hoofdstukken gelden de volgende regels:

• controleer het relevante FO-hoofdstuk;
• raadpleeg de bronbestanden die bij het domein horen;
• trek zelf conclusies wanneer bronnen eenduidig zijn;
• stel alleen vragen wanneer bronnen elkaar tegenspreken, een productkeuze nodig is, iets scopegevoelig is of een bron ontbreekt;
• lever wijzigingen als compleet .md-bestand of duidelijke patch;
• gebruik echte markdown-tabellen;
• gebruik relatieve Docusaurus-links;
• voeg per wijziging een kort Engels commitbericht toe;
• benoem open punten expliciet;
• vermijd verwijzingen naar tijdelijke of vervallen werkdocumenten;
• voorkom dat versie-informatie buiten de centrale intro wordt herhaald.

0.31 Relatie tot andere FO-hoofdstukken

Hoofdstuk	Relatie
Productvisie en scope	Beschrijft productkader, doelgroep, scope en niet-doelen.
Rollen, context en autorisatie	Werkt autorisatie, rolcontext, relatiecontext en server-side controle uit.
Applicatieschil, header, footer en navigatie	Beschrijft navigatie, badges, profielmenu en shellregels rond alle domeinen.
Frontpages en overzichtsschermen	Beschrijft read-only frontpages, tellers en overzichtscontexten.
Schermlaag en UX-specificaties	Beschrijft de rol van schermdocumentatie, UX-principes, popupkeys en read-only schermgedrag.
Oefenmodules en modulepayloads	Beschrijft modulecontract, payloadgrenzen en schemaherleidbaarheid.
Functionele architectuurcontext	Verbindt functionele domeinen aan systeemgrens, containers, readmodels, events, jobs, realtime en exports.
Open punten en buiten scope	Centraliseert domeinoverstijgende open punten en expliciete buiten-scope-afspraken.

0.32 Gerelateerde bronverwijzingen

Bron	Link
Technisch Ontwerp — scope en uitgangspunten	Intro, scope en uitgangspunten
Technisch Ontwerp — besluitenregister	Open punten, ontwerpbesluiten en besluitenregister
Functioneel Ontwerp — intro	Functioneel Ontwerp OefenHub
Bronnenoverzicht	Bronnenoverzicht
Extractie-notities	Extractie-notities
Usecases	Usecases
Database-informatie	Database-informatie
Ontwerpbronnen	Ontwerpbronnen
Schermdocumentatie	Schermdocumentatie
Mockups HTML	Mockups HTML
Oefenmodules	Oefenmodules
Architectuur	Architectuur
Usecase-index	FO usecase-index
Schermindex	FO scherm-index
Broninventaris overige markdown	FO broninventaris overige markdown
FO — Productvisie en scope	Productvisie en scope
FO — Rollen, context en autorisatie	Rollen, context en autorisatie
FO — Schermlaag en UX-specificaties	Schermlaag en UX-specificaties
FO — Functionele architectuurcontext	Functionele architectuurcontext
FO — Open punten en buiten scope	Open punten en buiten scope