UC-BEH-SYSMSG-004 — Templatevalidatie en placeholders controleren
1. Kerngegevens
| Veld | Waarde |
|---|---|
| Usecase-ID | UC-BEH-SYSMSG-004 |
| Naam | Templatevalidatie en placeholders controleren |
| Domein | Beheerder / Systeemberichtenbeheer |
| Primaire actor | Beheerder |
| Secundaire actor(en) | Frontend, backend, autorisatiecomponent, database, historyservice |
| Rolcontext | Actieve beheerdercontext; overige combinatierollen geven geen extra beheerrechten binnen deze usecase |
| Betrokken schermen | Site Instellingen > Systeemberichten, templateoverzicht, templatedetail, template-editor, templategeschiedenis |
| Gerelateerde usecases | UC-BEH-SYSMSG-003, UC-BEH-SYSMSG-002, generieke berichtenusecases |
| Primaire entiteiten | SystemMessageTemplates, SystemMessageTemplateHistory |
| Secundaire entiteiten / events | SystemMessageType, ButtonTheme, Users, SystemMessages |
| Gerelateerde popups | Niet van toepassing |
| Popupregister | Ontwerpbronnen — Popup-register |
| MoSCoW | Must |
2. Omschrijving
Het systeem controleert templategrenzen en toegestane placeholders voordat een systeemberichttemplate kan worden opgeslagen.
De placeholder-allowlist is codegedreven per ReferenceName; onbekende placeholders en ontbrekende verplichte placeholders worden server-side geweigerd.
Systeemberichtenbeheer beheert bestaande systeemberichtsjablonen. Runtime-berichten in mailboxen blijven aparte SystemMessages-records; templatebeheer wijzigt alleen de broninhoud voor toekomstige systeemcommunicatie.
De runtime-foundation voor deze templates kan al door Feature 11 Batch 4 worden gebruikt. Deze beheerusecase bouwt geen nieuwe technische referenties, geen templateversie-FK op runtimeberichten en geen RowVersion-verplichting.
De usecase gebruikt als functionele basis: SystemMessageTemplates voor bestaande codegedreven sjablonen. Dit betekent dat de beheerinterface geen vrije technische constructies introduceert, maar alleen werkt binnen de bestaande sleutelsets, records en codevaste ankers.
De usecase is bedoeld als definitieve functionele beschrijving voor het verdere FO-, TO- en SRS-traject. Daarom wordt expliciet vastgelegd welke gegevens wel worden gelezen of gewijzigd, welke gegevens bewust niet worden gewijzigd en welke validaties altijd server-side moeten plaatsvinden.
Uitgangspunten
- De beheerdercontext is altijd server-side leidend.
- De beheerinterface maakt onderscheid tussen beheerbare inhoud en technische ankers.
- History is onderdeel van het functionele resultaat wanneer een beheerder een wijziging opslaat.
- Zoeken, filteren, contextselectie en detailopenen zijn read-only totdat expliciet wordt opgeslagen.
- Onbekende of gemanipuleerde identifiers worden veilig geblokkeerd.
- De gebruikersinterface toont geen technische stacktraces of interne databasefouten.
- Domeinoverschrijdende bijwerkingen zijn uitgesloten tenzij een usecase die expliciet benoemt.
- De uitwerking volgt de centrale popup-, DRY- en ontwerpbronafspraken.
3. Scope
Deze usecase beschrijft:
- Het systeem controleert templategrenzen en toegestane placeholders voordat een systeemberichttemplate kan worden opgeslagen.
- Server-side controleren dat de gebruiker beheerder is.
- Werken binnen de afbakening van Beheerder / Systeemberichtenbeheer.
- Gebruik van SystemMessageTemplates voor bestaande codegedreven sjablonen.
- Scheiding tussen beheerbare velden en codegedreven of read-only velden.
- Veilige fout-, lege-staat- en blokkadeafhandeling.
- History of auditregistratie wanneer de usecase een wijziging uitvoert.
- Readmodelverversing na selectie, validatie of opslaan.
- Voorkomen dat deze beheeractie onbedoeld andere domeinen wijzigt.
Deze usecase beschrijft niet:
- Nieuwe systeemberichttemplates aanmaken via de GUI.
- Technische referentienaam of codegestuurde actie wijzigen.
- Bestaande verzonden SystemMessages met terugwerkende kracht aanpassen of koppelen aan een verplichte templateversie.
- Systeemberichten uitschakelen via een actief/in-gebruik schakelaar.
- Vrije of onbeperkte placeholderdefinities invoeren.
- Wijzigen van accounts, rollen of sessies buiten de autorisatiecontrole.
- Maken of wijzigen van oefenruns, resultaten, relaties, meldingen of privéberichten.
- Aanpassen van onderliggende code, migraties of seeddefinities via de beheerinterface.
4. Pre-condities
| ID | Voorwaarde |
|---|---|
| PRE-001 | De gebruiker is ingelogd en heeft een actief intern OefenHub-account. |
| PRE-002 | De gebruiker bezit een actieve beheerderrol. |
| PRE-003 | De beheerder opent de relevante route via Site Instellingen of een onderliggende beheerpagina. |
| PRE-004 | De relevante records of contexten voor Beheerder / Systeemberichtenbeheer zijn aanwezig of kunnen als veilige lege staat worden getoond. |
| PRE-005 | De server-side autorisatiecomponent is beschikbaar. |
| PRE-006 | De database en historytabellen zijn beschikbaar voor read-only of muterende acties. |
| PRE-007 | De frontend gebruikt de actuele serverrespons en niet alleen eerder opgeslagen clientstate. |
| PRE-008 | Eventuele feature- of routebeschikbaarheid is door de applicatieconfiguratie toegestaan. |
5. Post-condities
| ID | Resultaat |
|---|---|
| POST-001 | De template-invoer is server-side gecontroleerd op autorisatie, recordversie, veldrechten, lengte-eisen en placeholdergebruik. |
| POST-002 | Bij geldige invoer ontvangt de aanroepende wijzigingsflow een akkoord om door te gaan met opslaan. |
| POST-003 | Bij ongeldige invoer ontvangt de beheerder veldspecifieke validatiefouten. |
| POST-004 | Deze validatieflow heeft zelf geen SystemMessageTemplates-record opgeslagen of gewijzigd. |
| POST-005 | Reeds verzonden SystemMessages, privéberichtthreads, relaties, meldingen en oefendata zijn niet gewijzigd. |
6. Trigger
De usecase start wanneer de beheerder de actie Templatevalidatie en placeholders controleren uitvoert binnen het beheeronderdeel Beheerder / Systeemberichtenbeheer.
7. Normale processtroom
| Stap | Actor | Scherm / component | Actie | Systeemrespons | Data / regel |
|---|---|---|---|---|---|
| 1 | Beheerder | Template-editor | Kiest opslaan of expliciete validatie. | Frontend verzamelt de actuele invoer, template-id en recordversie. | Payload uit editorstate. |
| 2 | Frontend | Validatielaag | Voert ondersteunende basiscontrole uit. | Direct zichtbare lengte- of verplichte-veldenfouten kunnen al worden gemarkeerd. | Clientcontrole is niet leidend. |
| 3 | Backend | Autorisatiecomponent | Controleert actieve beheerdercontext. | Zonder beheerderrol stopt de controle en worden geen templategegevens vrijgegeven. | Server-side autorisatie. |
| 4 | Backend | Recordservice | Laadt het bestaande template en de actuele recordversie. | Het systeem controleert of de template nog bestaat en bewerkbaar is. | SystemMessageTemplates. |
| 5 | Backend | Veldrechtencontrole | Controleert of de payload alleen beheerbare velden bevat. | Wijzigingen aan referentienaam, actiecode of andere technische velden worden geblokkeerd. | Read-only grenzen. |
| 6 | Backend | Lengtevalidatie | Controleert onderwerp, tekst en eventuele knoptekst. | Overschrijding leidt tot veldspecifieke foutmeldingen. | 50 / 1000 / 20 tekens. |
| 7 | Backend | Sleutelsetcontrole | Controleert domein en type tegen toegestane waarden. | Onbekende of niet-toegestane waarden worden geweigerd. | SystemMessageType en domeinclassificatie. |
| 8 | Backend | Placeholdercontrole | Detecteert placeholders in onderwerp, tekst en knoptekst. | Alleen expliciet ondersteunde placeholders worden geaccepteerd. | Codegedreven placeholderset. |
| 9 | Backend | Actieknopcontrole | Controleert of knoptekst beheerbaar is voor deze bestaande template. | Knoptekst wordt alleen toegestaan wanneer de achterliggende codegestuurde actie dat ondersteunt. | Geen actiecodewijziging. |
| 10 | Backend | Validatierespons | Bundelt validatieresultaat. | De aanroepende wijzigingsflow krijgt akkoord of veldspecifieke fouten. | Geen opslag. |
| 11 | Frontend | Editor | Toont resultaat. | Bij fouten blijft de beheerder in de editor; bij akkoord kan de wijzigingsflow verder met opslaan. | Geen domeinmutatie. |
8. Alternatieve en exceptionele processtromen
| ID | Vanaf stap | Situatie | Systeemgedrag | Popup / melding | Datamutatie |
|---|---|---|---|---|---|
| ALT-001 | 3 | De gebruiker heeft geen actieve beheerderrol. | Backend blokkeert de controle en geeft geen template-inhoud terug. | Inline toegang geweigerd of veilige redirect. | Geen. |
| ALT-002 | 4 | Het template bestaat niet meer. | Het systeem toont een veilige niet-beschikbaarafhandeling. | Inline melding. | Geen. |
| ALT-003 | 4 | De recordversie is intussen gewijzigd. | Opslaan wordt geblokkeerd totdat de beheerder actuele waarden opnieuw laadt. | Inline conflictmelding. | Geen. |
| ALT-004 | 5 | De payload bevat een read-only veld. | De backend weigert de payload als ongeldig. | Inline foutmelding. | Geen. |
| ALT-005 | 6 | Onderwerp, tekst of knoptekst overschrijdt de grens. | Het systeem retourneert veldspecifieke validatiefouten. | Inline validatie. | Geen. |
| ALT-006 | 7 | Domein of type is onbekend of niet toegestaan. | Het systeem weigert opslaan via de aanroepende wijzigingsflow. | Inline validatie. | Geen. |
| ALT-007 | 8 | Een onbekende placeholder wordt gebruikt. | Het systeem toont welke placeholder niet is toegestaan. | Inline validatie. | Geen. |
| ALT-008 | 9 | Knoptekst wordt meegestuurd terwijl de template geen beheerbare knoptekst ondersteunt. | De payload wordt geweigerd of het veld blijft buiten de toegestane wijzigingsset. | Inline validatie. | Geen. |
| ALT-009 | 10 | De validatieservice faalt technisch. | Er wordt geen akkoord voor opslaan gegeven en de beheerder krijgt een veilige foutmelding. | Veilige foutmelding. | Geen. |
9. Business rules
| ID | Regel |
|---|---|
| BR-UC-BEH-SYSMSG-004-001 | Templatevalidatie is altijd server-side leidend, ook wanneer de frontend al voorvalidatie uitvoert. |
| BR-UC-BEH-SYSMSG-004-002 | De referentienaam, actiecode, entiteitroutering en technische sleutelvelden zijn read-only. |
| BR-UC-BEH-SYSMSG-004-003 | Alleen beheerbare velden van een bestaand template mogen in de wijzigingspayload staan. |
| BR-UC-BEH-SYSMSG-004-004 | Onderwerp, tekst en knoptekst moeten binnen de vastgestelde lengte-eisen blijven. |
| BR-UC-BEH-SYSMSG-004-005 | Alleen expliciet ondersteunde placeholders mogen worden gebruikt. |
| BR-UC-BEH-SYSMSG-004-006 | Validatie zelf schrijft geen history en voert geen templatewijziging uit. |
| BR-UC-BEH-SYSMSG-004-007 | Reeds verzonden SystemMessages mogen nooit door templatevalidatie worden aangepast. |
10. Datavalidatie
| Veld / object | Validatie |
|---|---|
| Beheerdercontext | De gebruiker moet server-side een actieve beheerderrol hebben. |
| Recordtoegang | Het record, blok of template moet binnen het gevraagde subdomein bestaan. |
| Read-only velden | Technische sleutels, actie-identifiers en codegedreven velden mogen niet via de GUI worden gewijzigd. |
| Concurrency | Opslaan moet de actuele recordversie controleren zodat overschrijven van nieuwere wijzigingen wordt voorkomen. |
| Subject | Maximaal 50 tekens. |
| Text | Maximaal 1000 tekens. |
| ButtonText | Maximaal 20 tekens wanneer een codegestuurde actieknop beschikbaar is. |
| ReferenceName | Moet bestaan en is read only. |
| SystemMessageType | Moet Info, Success, Warning, Error of Critical zijn. |
| Placeholders | Alleen expliciet toegestane variabelen zijn toegestaan. |
| Auditactor | UpdatedByUserId of ChangedByUserId moet naar de uitvoerende beheerder of systeemactor verwijzen. |
| Tijdstip | Wijzigingsmomenten worden in UTC vastgelegd. |
| Rendering | Beheerbare tekst moet veilig worden opgeslagen en gerenderd zonder actieve inhoud. |
| Lege waarden | Verplichte zichtbare velden mogen niet leeg worden opgeslagen wanneer de runtime ze nodig heeft. |
11. Datamutaties en events
| Stap | Type | Entiteit / event | Mutatie |
|---|---|---|---|
| Alle stappen | Database | Niet van toepassing | Deze usecase voert uitsluitend validatie uit en schrijft geen template-, history- of runtimeberichtrecords. |
Transactionele uitgangspunten
- Deze usecase geeft alleen een validatie-akkoord of validatiefouten terug aan de aanroepende wijzigingsflow.
- Opslag van
SystemMessageTemplatesenSystemMessageTemplateHistorygebeurt uitsluitend in de wijzigingsflow die na geslaagde validatie doorloopt. - Bij technische fouten wordt geen opslagakkoord gegeven.
- Readmodelverversing na een eventuele opvolgende opslag is afgeleid en vormt geen extra bronrecord.
12. Geen datamutaties
| Entiteit | Reden |
|---|---|
| Users, Roles en UserRoles | Worden alleen gebruikt voor autorisatiecontrole; rollen of accounts worden niet gewijzigd. |
| Runtime gebruikersdata | Deze beheerusecase wijzigt geen leerling-, docent- of ouder-/voogddata. |
| Tickets en meldingen | Meldingenbeheer blijft in het generieke meldingendomein. |
| ExerciseRuns en resultaten | Oefenruns, geschiedenis en resultaten worden niet aangepast. |
| Relaties en uitnodigingen | Relatiebeheer wordt niet vanuit deze beheerpagina uitgevoerd. |
| SystemMessages | Reeds verzonden mailbox-systeemberichten worden niet met terugwerkende kracht aangepast. |
| Technische template-referenties | Nieuwe referenties en actiecodes ontstaan alleen via code en migraties. |
13. State diagram
Niet van toepassing. Deze usecase wijzigt geen persistente template- of runtimeberichtstatus. Autorisatie, selectie, validatie en historyweergave zijn read-only of controlelogica en vormen geen eigen statusmodel.
14. Decision flow
15. Data lifecycle diagram
16. Sequence diagrammen
Hoofdsequence
Foutsequence
17. Popupverwijzingen
Usecases verwijzen alleen naar PopupKey. Popupteksten, knopteksten, acties, inputvelden en themakeuzes worden centraal beheerd in het popupregister en de popup-themes.
| PopupKey | Moment | Doel |
|---|---|---|
| Niet van toepassing | Geen bevestigings- of invoerpopup in de normale processtroom. | Inline meldingen, lege staten of veilige redirects volstaan. |
18. Afleiding naar Functioneel Ontwerp / Technisch Ontwerp / Software Requirements Specification
| Doeldocument | Afleiding |
|---|---|
| Functioneel Ontwerp | Beschrijft welke validaties gelden voor systeemberichttemplates en hoe veldspecifieke fouten aan de beheerder worden getoond. |
| Technisch Ontwerp | Technisch Ontwerp: communicatie en systeemberichten, databaseontwerp en privacy en retentie beschrijven de technische uitwerking. Beschrijf server-side autorisatie, recordversiecontrole, placeholderdetectie, sleutelsetvalidatie en veilige rendering. |
| Software Requirements Specificatie | Beschrijft requirements voor lengte-eisen, read-only technische velden, toegestane placeholders, concurrency en foutafhandeling. |
| Database-informatie | Beschrijft of templatevelden, lengteconstraints en sleutelsets aansluiten op SystemMessageTemplates. |
| Ontwerpbronnen en registers | Beschrijven business rules en autorisatiematrix bij; deze validatieflow vraagt geen zelfstandig domeinevent of popupdetail buiten PopupKey-verwijzingen. |
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-BEH-SYSMSG-004-001 | SRS-ADM-001 SRS-POP-004 AC-ADM-001 AC-POP-004 | Templatevalidatie uitsluitend uitvoeren binnen een actieve beheerdercontext |
REQ-UC-BEH-SYSMSG-004-002 | SRS-AUTH-001 SRS-ADM-002 SRS-ADM-001 SRS-POP-004 AC-AUTH-001 AC-ADM-002 AC-ADM-001 AC-POP-004 | De bestaande template en actuele recordversie server-side controleren voordat validatie akkoord kan geven |
REQ-UC-BEH-SYSMSG-004-003 | SRS-AUTH-001 SRS-ADM-001 AC-AUTH-001 AC-ADM-001 | Wijzigingen aan technische sleutels, referentienaam, actiecode en doelroutering weigeren |
REQ-UC-BEH-SYSMSG-004-004 | SRS-ADM-001 AC-ADM-001 | Onderwerp, tekst en knoptekst valideren op de vastgestelde maximale lengtes |
REQ-UC-BEH-SYSMSG-004-005 | SRS-ADM-002 SRS-ADM-001 AC-ADM-002 AC-ADM-001 | Domein en type controleren tegen de toegestane sleutelsets |
REQ-UC-BEH-SYSMSG-004-006 | SRS-ADM-001 SRS-POP-004 AC-ADM-001 AC-POP-004 | Alleen expliciet ondersteunde placeholders accepteren |
REQ-UC-BEH-SYSMSG-004-007 | SRS-ADM-001 AC-ADM-001 | Veldspecifieke validatiefouten teruggeven zonder technische details te tonen |
REQ-UC-BEH-SYSMSG-004-008 | SRS-MSG-001 SRS-LRN-009 SRS-ADM-001 SRS-POP-004 SRS-NFR-AUD-001 AC-MSG-001 AC-LRN-009 AC-ADM-001 AC-POP-004 AC-NFR-AUD-001 | Binnen deze validatie-usecase geen template-, history- of runtimeberichtrecords schrijven |
REQ-UC-BEH-SYSMSG-004-009 | SRS-AUTH-001 SRS-ADM-002 SRS-ADM-001 AC-AUTH-001 AC-ADM-002 AC-ADM-001 | Een validatie-akkoord alleen teruggeven wanneer alle server-side controles slagen |
REQ-UC-BEH-SYSMSG-004-010 | SRS-ADM-001 AC-ADM-001 | Reeds verzonden SystemMessages buiten de validatieflow houden |