Functioneel Ontwerp OefenHub
Dit Functioneel Ontwerp beschrijft wat OefenHub functioneel moet doen, welke rollen en contexten bestaan, welke gegevens, schermen en domeinobjecten daarbij horen en welke grenzen gelden tussen gebruik, beheer, oefenruns, communicatie, meldingen, ondersteuning en technische context.
De opzet is bewust markdown-gebaseerd. In plaats van één groot document wordt het FO verdeeld over domeingerichte bestanden. Daardoor kunnen latere wijzigingen per onderwerp worden aangebracht, beoordeeld en verwerkt zonder het volledige ontwerp telkens als één groot document te hoeven converteren of renderen.
Het FO is bedoeld als functioneel contract tussen product, ontwerp, techniek en requirements. Het beschrijft functionele samenhang, bronpositie, domeingrenzen, autorisatieprincipes, schermrelaties en gedrag op hoofdlijnen. Detailflows blijven in usecases, schermspecifieke zichtbaarheid blijft in schermdocumentatie, persistente brondata blijft in database-informatie en technische implementatiekeuzes horen in het Technisch Ontwerp of de Software Requirements Specification waar zij niet functioneel normerend zijn.
Status van de huidige scope
| Veld | Waarde |
|---|---|
| FO-versie | FO v1.0 |
| Status | Definitieve FO-baseline |
| Doel | Functioneel ontwerp vastleggen als onderhoudbare, domeingerichte markdowndocumentatie. |
| Bronpositie | Gebaseerd op duurzame documentatiebronnen zoals usecases, database-informatie, ontwerpbronnen, schermdocumentatie, oefenmodule-documentatie, architectuurdocumentatie, mockups en FO-registers. |
| Niet-doel | Geen technisch ontwerp, geen volledige SRS-detailmatrix, geen database-DDL, geen pixel-perfect UI/CSS-specificatie en geen vrije kopie van alle brondocumenten. |
| Versiebeleid | Het FO-versienummer wordt alleen centraal op deze pagina vermeld. Andere FO-hoofdstukken en registers noemen geen eigen FO-versienummer. |
Het Functioneel Ontwerp beschrijft de actuele functionele baseline voor de belangrijkste OefenHub-domeinen. De domeinen rond oefencatalogus, oefenmodules, leerlingruns, resultaten/PDF, gedeelde oefeningen, docentfunctionaliteit, ouder-/voogdfunctionaliteit, live meekijken, beheerderfunctionaliteit, functionele architectuurcontext, productscope, bronnenbeleid, open punten en registers zijn in deze baseline als samenhangend geheel vastgelegd.
Formele reviewinformatie
Het FO bevat bewust geen handmatig bijgehouden akkoordpagina of wijzigingshistorietabel per wijziging. Formele review, accordering en wijzigingshistorie worden bijgehouden via Git version control, pull requests, commits, tags en eventuele releases.
| Onderdeel | Vastlegging |
|---|---|
| Documenteigenaar | Wordt projectmatig bepaald buiten het FO-bestand en is niet als losse tekstwaarde in dit document leidend. |
| Inhoudelijke akkoordgever | Wordt vastgelegd via de afgesproken review- en acceptatieflow in Git, bijvoorbeeld pull-requestreview, mergebesluit of releasegoedkeuring. |
| Documentstatus | Wordt centraal op deze pagina benoemd bij Status van de huidige scope. |
| Wijzigingshistorie | Git commits en pull requests vormen de formele wijzigingshistorie. Het FO bevat daarom geen handmatig onderhouden wijzigingstabel. |
| Versie-identificatie | Het FO-versienummer staat alleen centraal in intro.md; formele releases kunnen daarnaast via Git-tags of release-aanduidingen worden vastgelegd. |
| Accorderingsmoment | Het akkoordmoment volgt uit de afgesproken Git-/releaseflow en wordt niet als losse datum in het document gekopieerd. |
Deze keuze voorkomt dubbele administratie en tegenstrijdigheid tussen documentinhoud en repositoryhistorie. Waar in het FO wordt gesproken over status, akkoord, versie of wijziging, is de repositoryhistorie leidend voor de formele audittrail.
Leeswijzer
| Hoofdstuk | Doel |
|---|---|
| 00 — Bronnen en afbakening | Beschrijft bronhiërarchie, interpretatieregels, DRY-beleid en afbakening van het FO. |
| 01 — Productvisie en scope | Beschrijft productdoel, doelgroep, hoofdscope, niet-doelen en platformgrenzen. |
| 02 — Rollen, context en autorisatie | Beschrijft rollen, contextbepaling, combinatierollen, relatiecontexten en autorisatieprincipes. |
| 03 — Applicatieschil, header, footer en navigatie | Beschrijft algemene applicatieschil, header, footer, navigatiegedrag, badges en responsiviteit. |
| 04 — Frontpages en overzichtsschermen | Beschrijft frontpages als read-only oriëntatieschermen en de runtime-samenstelling per rolcontext. |
| 05 — Account, profiel, toegankelijkheid en voorkeuren | Beschrijft applicatieaccount, profiel, voorkeuren, toegankelijkheid, identity-providergrens en account lifecycle. |
| 06 — Relatiebeheer | Beschrijft vriendschappen, ouder-/voogdrelaties, docentrelaties, docent-docentrelaties en relatie-uitnodigingen. |
| 07 — Oefencatalogus, niveaus, categorieën en oefeningen | Beschrijft niveaus, centrale categorieën, niveaukoppelingen, concrete oefeningen, moduleconfiguratie en cataloguszichtbaarheid. |
| 08 — Leerling: oefenen, voortgang en resultaten | Beschrijft oefenrun-lifecycle, starten, hervatten, beantwoorden, afronden, resultaten, geschiedenis en anti-afleiding. |
| 09 — Gedeelde oefeningen | Beschrijft delen van afgeronde oefeningen, shared records, ontvangersruns, snapshots en systeemcommunicatie. |
| 10 — Docentfunctionaliteit | Beschrijft docentcontext, oefenaanbod, leerlingen, niveauautorisaties, resultaten, collaborators en eigenaarschap. |
| 11 — Ouder-/voogdfunctionaliteit | Beschrijft gekoppelde kinderen, resultaten, geschiedenis, PDF, online-overzicht, live meekijken en read-only grenzen. |
| 12 — Beheerderfunctionaliteit | Beschrijft beheerdercontext, accounts, rollen, site-instellingen, categorieën, modules, ondersteuning, logging en audit. |
| 13 — Berichten, communicatie en notificaties | Beschrijft mailbox-systeemberichten, privéberichtthreads, readstates, badges, systeemnotificaties en realtime signalen. |
| 14 — Meldingen en ticketafhandeling | Beschrijft meldingen/tickets, statusmodel, discussie, oplossingen, heropenen, TickerQ-verwerking en doorzetten naar docent. |
| 15 — Live meekijken | Beschrijft live meekijken door docent en ouder/voogd, read-only voortgang, browsemodus, reconnect en audit. |
| 16 — Contentbeheer, vaste pagina’s en footer | Beschrijft contentblokken, vaste pagina’s, URL-records, footersecties, footerlinks en geen-pagebuilder-grens. |
| 17 — Popups, templates, features en systeemnotificaties | Beschrijft popupregister, popupdetails, templates, featuretoggles, systeeminstellingen en systeemnotificaties. |
| 18 — PDF-export en resultaatpresentatie | Beschrijft resultaatpresentatie, historische runcontext, PDF-inhoud, bestandsnaamregels, privacy en roltoegang. |
| 19 — Functionele beslisregels en uitgangspunten | Bundelt overkoepelende functionele beslisregels die meerdere domeinen raken. |
| 20 — Open punten en buiten scope | Centraliseert open punten, documentatiehygiëne, beslispunten en expliciete buiten-scopeonderwerpen. |
| 21 — Schermlaag en UX-specificaties | Beschrijft de positie van schermdocumentatie, UX-regels, lege/fouttoestanden en schermlaagprincipes. |
| 22 — Oefenmodules en modulepayloads | Beschrijft modulecontract, payloadlagen, moduleKey, schemaVersion, modulebeheer, testzichtbaarheid en migratie. |
| 23 — Functionele architectuurcontext | Beschrijft functionele betekenis van systeemgrenzen, containers, brondata, readmodels, realtime, jobs en exports. |
Registers en bronbestanden
| Bestand | Doel |
|---|---|
| Usecase-index | Traceerbaarheid tussen duurzame usecasebestanden en FO-hoofdstukken. |
| Schermindex | Traceerbaarheid tussen schermdocumentatie, scherm-ID’s, rollen en FO-hoofdstukken. |
| Broninventaris overige markdown | Inventaris van duurzame niet-usecase- en niet-schermbronnen, zoals database-, ontwerp-, architectuur-, module-, mockup- en style-documentatie. |
| Bronnenoverzicht | Samenvatting van duurzame bronsets, bronhiërarchie, bronvolgorde en onderhoudsregels. |
| Extractie-notities | Duurzame extractieregels, interpretatieafspraken, reviewaanpak en kwaliteitscontrole voor FO/TO/SRS-documentatie. |
Centrale ontwerpprincipes
Voor het hele FO gelden de volgende overkoepelende principes.
| Principe | Betekenis |
|---|---|
| Server-side autorisatie | Iedere route, mutatie, detailweergave, export, liveactie en vervolgactie controleert server-side opnieuw de actuele rol-, relatie-, object- en domeincontext. |
| Zichtbare UI is geen autorisatiebewijs | Navigatie, knoppen, badges, filters, browsergeschiedenis, clientstate en routeparameters mogen toegang nooit verruimen. |
| Bron van waarheid blijft domeingebonden | Runs, relaties, berichten, tickets, content, modules, instellingen en audit blijven bronhoudend in hun eigen domein. |
| Readmodels zijn afgeleid | Frontpages, badges, tellers, mailboxoverzichten en samenvattingen zijn afgeleid en wijzigen geen brondata. |
| Historische context blijft reconstrueerbaar | Resultaten, gedeelde oefeningen, PDF-export, audit en history gebruiken opgeslagen historische context en worden niet herschreven door latere naam-, categorie- of modulewijzigingen. |
| Beheerdercontext is begrensd | Beheerderfunctionaliteit biedt beheer- en supportacties, maar is geen vrije bypass op leerling-, docent-, ouder-/voogd- of livefunctionaliteit. |
| Leerling-oefenen is afleidingsarm | Tijdens actieve oefenruns worden afleidende badges, systeemnotificaties en meldingenterugkoppelingen visueel uitgesteld zonder server-side data te verliezen. |
| FO blijft DRY | Usecaseflows, schermdetails, databasevelden, popupteksten, template-inhoud en mockupdetails worden niet onnodig gekopieerd in FO-hoofdstukken. |
Documentstatus en vervolg
Open punten en buiten scope bewaakt buiten-scopegrenzen, vastgelegde reviewbesluiten en normaal documentatieonderhoud.