0. Template en minimale verwachtingen voor moduledossiers

Dit hoofdstuk legt vast hoe technische oefenmodules binnen oefen_modules worden gedocumenteerd. Het doel is dat iedere module als zelfstandig dossier gelezen kan worden, terwijl de centrale Software Requirements Specification, het Functioneel Ontwerp en het Technisch Ontwerp bronhoudend blijven voor generieke eisen en platformafspraken.

0.1 Plaatsing en naamgeving

Iedere concrete module wordt geplaatst onder een functionele modulecategorie:

oefen_modules/
  <modulecategorie>/
    <module_slug>/
      index.md
      01_overzicht.md
      02_requirements_en_acceptatiecriteria.md
      03_functioneel_gedrag.md
      04_schermen_en_states.md
      05_payloads_en_datacontract.md
      06_technisch_ontwerp.md
      07_testgevallen_en_randgevallen.md

Voorbeelden van categorieën zijn rekenen, taal, klokkijken of studievaardigheden. De slug is technisch stabiel, lowercase en URL-vriendelijk, bijvoorbeeld optellen_en_aftrekken_simpel.

0.2 Minimale dossierinhoud

Bestand	Minimale inhoud	Doel
index.md	Korte module-intro, leeswijzer en links naar alle dossierdelen.	Navigatiepunt voor Docusaurus en startpunt voor reviewers.
01_overzicht.md	Modulefamilie, modulefunctie, doelgroep, generieke engine versus moduleverantwoordelijkheid, module-identiteit en scope.	Snel bepalen wat de module doet en wat buiten de module valt.
02_requirements_en_acceptatiecriteria.md	Modulespecifieke eisen, classificatie en trace naar centrale SRS/AC-dekking.	Voorkomen dat module-eisen losraken van de centrale requirementbasis.
03_functioneel_gedrag.md	Docentconfiguratie, leerlingruntime, feedbackgedrag, randgevallen en generieke flowcontext.	Functionele leeslaag voor ontwerp, review en acceptatie.
04_schermen_en_states.md	Screenshots/mockups, schermmetadata, UI-elementen, velddefinities, waardelagen en statevarianten.	Schermspecifieke uitwerking van de module.
05_payloads_en_datacontract.md	Configuratiepayload, vraagpayload, antwoordstate, schemaVersion en databetekenis.	Contract tussen module en generieke oefenengine.
06_technisch_ontwerp.md	Module-entrypoints, implementatiegrenzen, dependencies, versiecompatibiliteit en koppeling aan centrale TO-hoofdstukken.	Technische bouw- en integratiecontext.
07_testgevallen_en_randgevallen.md	Testmatrix voor configuratie, generatie, validatie, runtime states, hervatten, history/PDF/live waar relevant.	Minimale modulegerichte validatie.

0.3 Bronlagen en verantwoordelijkheid

Laag	Bronhoudend voor	Gebruik binnen moduledossier
Software Requirements Specification	Centrale requirements, prioriteiten, acceptatiecriteria en traceability.	Alleen verwijzen naar centrale requirements/AC's en module-eisen classificeren.
Functioneel Ontwerp	Functioneel kader, rollen, lifecycle, domeinregels en schermoverschrijdend gedrag.	Modulegedrag aansluiten op bestaande rollen en flows.
Technisch Ontwerp	Implementatie, modulecontract, services, payloadregels, jobs, frontend, tests en beheerbeleid.	Module-specifieke implementatie invullen binnen centrale technische grenzen.
Schermdocumentatie/mockups	UI-context, labels, schermstates en lokale gebruikerscontext.	Screens en states beschrijven; niet gebruiken als technische codebasis.
Database-informatie	Tabellen, kolommen, constraints, enumwaarden en relaties.	Alleen verwijzen naar bestaande platformtabellen; modulepayloads niet onnodig relationeel uitsplitsen.

0.4 Regels voor hergebruik en mockups

HTML-mockups zijn zelfstandige ontwerpbestanden en mogen niet worden overgenomen als productieopbouw. Voor implementatie geldt:

• bouw layouts opnieuw in Blazor;
• gebruik MudBlazor als technische componentbasis waar passend;
• gebruik OefenHub-wrappercomponenten voor terugkerende patronen;
• herhaal geen pagina-specifieke HTML/CSS wanneer een herbruikbaar component logisch is;
• beschouw PNG's en HTML als visuele en functionele referentie, niet als broncode;
• leg afwijkingen tussen mockup en implementatie vast in het moduledossier wanneer die functioneel relevant zijn.

0.5 Minimale modulemetadata

Ieder moduledossier bevat minimaal:

Metadata	Toelichting
Modulefamilie	Functionele categorie, bijvoorbeeld Rekenen.
Modulefunctie	Korte omschrijving van het oefendoel.
Technische modulesleutel	Stabiele sleutel voor administratieve registratie en runtimekoppeling.
SchemaVersion	Versie van het module-specifieke configuratie- en payloadschema.
Configuratiebron	Generieke opslagplek voor moduleconfiguratie.
Vraag-/antwoordstate	Generieke opslagplek voor runtimevraag en voortgang.
Module-entrypoints	Contractfuncties of componenten die de generieke engine aanspreekt.
Centrale dekking	Relevante SRS/AC-, FO- en TO-verwijzingen.

0.6 Validatie per nieuw moduledossier

Voor iedere nieuwe module wordt minimaal gecontroleerd:

• alle dossierbestanden zijn aanwezig of bewust niet van toepassing gemaakt;
• Docusaurus-links zijn extensieloos;
• lokale links verwijzen naar bestaande documenten;
• documentatiestatus gebruikt volledige documentnamen, geen afkortingsbundels zoals Functioneel Ontwerp, Technisch Ontwerp, Software Requirements Specification;
• module-eisen verwijzen naar het oefenmodule-eisenregister;
• payloadvoorbeelden bevatten geen persoonsgegevens of productiedata;
• schermstates zijn states binnen een view wanneer er geen aparte route bestaat;
• moduleverantwoordelijkheden dupliceren geen generieke engineverantwoordelijkheden.