UC-BEH-CAT-006 — Categorie migreren
1. Kerngegevens
| Veld | Waarde |
|---|---|
| Usecase-ID | UC-BEH-CAT-006 |
| Naam | Categorie migreren |
| Domein | Beheerder / Categorieën beheren |
| Primaire actor | Beheerder |
| Secundaire actor(en) | Frontend, backend, database, autorisatiecomponent, categoriebeheercomponent, historiecomponent, systeemberichtencomponent |
| Rolcontext | Actieve beheerdercontext; server-side bepaald vanuit de ingelogde gebruiker |
| Betrokken schermen | Content > Categorieën beheren |
| Gerelateerde usecases | UC-BEH-CAT-001, UC-BEH-CAT-002, UC-BEH-CAT-003, UC-BEH-CAT-004, UC-BEH-CAT-005, UC-BEH-CAT-007 |
| Primaire entiteiten | Categories, CategoryHistory, CategoryMigrations, TeacherLevelCategories, TeacherLevelCategoryExercises |
| Secundaire entiteiten / events | Users, SystemMessages, ExerciseRuns, SharedExercises, categoriebeheer-readmodels |
| Gerelateerde popups | POP-BEH-CAT-MIGRATION-CONFIRM |
| Popupregister | Ontwerpbronnen — Popup-register |
| MoSCoW | Must |
2. Omschrijving
Deze usecase beschrijft de daadwerkelijke migratie van een broncategorie naar een bestaande doelcategorie. De migratie wordt gebruikt wanneer dubbele of semantisch overlappende centrale categorieën zijn ontstaan.
De actie verplaatst relevante actieve koppelingen naar de doelcategorie, voorkomt dubbele records, legt de migratie vast in CategoryMigrations en schrijft CategoryHistory op zowel bron- als doelcategorie. De broncategorie blijft historisch bestaan maar wordt na succesvolle migratie niet langer als normale nieuwe keuze aangeboden. Betrokken docenten aan de bronkant worden via centrale systeemberichtcommunicatie geïnformeerd, zonder dat de usecase berichtteksten of knopteksten dupliceert.
Bestaande historische ExerciseRuns en gedeelde-oefening-snapshots worden niet herschreven; zij blijven de context tonen zoals die gold op het moment van maken of delen.
Uitgangspunten
- Categorieën zijn centrale onderwijsinhoud en geen private docentlabels.
- Naam, kleur en icoon vormen samen de centrale categorie-identiteit.
- Beheeracties op categorieën zijn volledig server-side gevalideerd.
- Historische resultaten behouden hun oorspronkelijke categoriecontext.
- Popupinhoud blijft bronhoudend in het centrale popupregister.
3. Scope
Deze usecase beschrijft:
- Transactioneel uitvoeren van een voorbereide categoriemigratie.
- Verplaatsen of samenvoegen van TeacherLevelCategories naar de doelcategorie.
- Verplaatsen of samenvoegen van TeacherLevelCategoryExercises zonder duplicaten.
- Vastleggen van CategoryMigrations met bron, doel, actor, moment en reden.
- Vastleggen van CategoryHistory op bron- en doelcategorie.
- Broncategorie na migratie niet meer nieuw selecteerbaar maken.
- Aanmaken van systeemberichten voor betrokken docenten op basis van de centrale systeemberichttemplate voor categoriemigratie.
Deze usecase beschrijft niet:
- Docentniveaubeheer, leerlingautorisaties of oefeningconfiguratie wijzigen; die blijven bronhoudend in docentflows of docentondersteuning.
- Nieuwe centrale categorieën aanmaken vanuit beheer; categorie-aanmaak is bronhoudend in de docentflow of via technische migratie wanneer dat expliciet nodig is.
- Historische exercise runs herschrijven; bestaande runs behouden hun oorspronkelijke categoriecontext.
- Popupteksten of knopteksten specificeren; usecases verwijzen uitsluitend naar PopupKey.
- Nieuwe doelcategorie aanmaken tijdens uitvoering.
- Historische runs, resultaten of PDF-contexten herschrijven.
- Systeemberichtteksten, knopteksten of template-inhoud uitschrijven; deze blijven bronhoudend in templatebeheer systeemberichten.
3.1 Afbakening met aangrenzende domeinen
| Onderdeel | Afbakening |
|---|---|
| Docent / Oefenaanbod | Docenten koppelen categorieën aan niveaus en maken waar toegestaan nieuwe centrale categorieën aan; beheer past de centrale identiteit en onderhoudsacties toe. |
| Beheerder / Docentondersteuning | Support op concrete docentstructuren mag categoriegebruik inspecteren, maar centrale categorie-identiteit wordt hier beheerd. |
| Leerling / Oefenaanbod | Leerlingen zien alleen afgeleide toegankelijke categorieën; deze bundel bepaalt niet zelfstandig leerlingtoegang. |
| Database-informatie | Categories, CategoryHistory en CategoryMigrations blijven de technische bron voor centrale categorie-identiteit en audit. |
4. Pre-condities
| ID | Voorwaarde |
|---|---|
| PRE-001 | De gebruiker is succesvol ingelogd in OefenHub. |
| PRE-002 | De backend heeft server-side vastgesteld dat de gebruiker een actieve beheerderrol heeft. |
| PRE-003 | De beheerder bevindt zich binnen de beheeromgeving via Content > Categorieën beheren. |
| PRE-004 | De pagina gebruikt actuele serverdata; clientstate, routeparameters of verborgen formuliervelden bepalen geen autorisatie of categorie-identiteit. |
| PRE-005 | Er bestaat een geldig migratievoorstel vanuit UC-BEH-CAT-005. |
| PRE-006 | Broncategorie en doelcategorie bestaan en zijn verschillend. |
| PRE-007 | Doelcategorie is actief. |
| PRE-008 | De beheerder heeft een verplichte reden ingevuld. |
5. Post-condities
| ID | Resultaat |
|---|---|
| POST-001 | Relevante actieve koppelingen gebruiken de doelcategorie of zijn conflictveilig samengevoegd. |
| POST-002 | Dubbelen in TeacherLevelCategories en TeacherLevelCategoryExercises zijn niet aangemaakt. |
| POST-003 | CategoryMigrations bevat de uitgevoerde migratie. |
| POST-004 | CategoryHistory bevat migratieregels voor bron en doel. |
| POST-005 | De broncategorie blijft historisch beschikbaar maar is niet langer nieuw kiesbaar. |
| POST-006 | Betrokken docenten aan de bronkant hebben een systeembericht ontvangen. |
| POST-007 | Historische ExerciseRuns blijven ongewijzigd. |
6. Trigger
De usecase start wanneer de beheerder vanuit een geldig migratievoorstel kiest voor migratie uitvoeren en de bevestiging met reden afrondt.
7. Normale processtroom
| Stap | Actor | Scherm / component | Actie | Systeemrespons | Data / regel |
|---|---|---|---|---|---|
| 1 | Beheerder | Migratievoorstel | Kiest Uitvoeren. | De frontend toont een bevestigingspopup met verplichte reden. | PopupKey POP-BEH-CAT-MIGRATION-CONFIRM. |
| 2 | Beheerder | Popup | Bevestigt met reden. | De backend ontvangt uitvoeropdracht. | Reason verplicht. |
| 3 | Backend | Autorisatiecomponent | Controleert beheerdercontext. | Alleen beheerder mag migratie uitvoeren. | Server-side autorisatie. |
| 4 | Backend | MigratieService | Herberekent bron, doel, impact en conflicten. | De voorbereiding wordt niet blind vertrouwd. | Categories en koppelingen. |
| 5 | Backend | MigratieService | Start transactie. | Alle mutaties slagen samen of worden teruggedraaid. | Transaction boundary. |
| 6 | Backend | MigratieService | Verwerkt TeacherLevelCategories. | Bestaande doelkoppelingen worden hergebruikt; ontbrekende doelkoppelingen worden aangemaakt of omgezet volgens migratieregels. | TeacherLevelCategories. |
| 7 | Backend | MigratieService | Verwerkt TeacherLevelCategoryExercises. | Bestaande oefenkoppelingen onder doelcategorie worden niet gedupliceerd; bronkoppelingen worden historisch/inactief of verplaatst. | TeacherLevelCategoryExercises. |
| 8 | Backend | MigratieService | Markeert broncategorie als niet nieuw selecteerbaar. | Broncategorie blijft historisch bestaan. | Categories.IsDeleted of equivalent statusgedrag. |
| 9 | Backend | MigratieService | Legt migratie vast. | CategoryMigrations wordt aangemaakt. | SourceCategoryId, TargetCategoryId, MigratedByUserId, Reason. |
| 10 | Backend | HistorieService | Schrijft historie op bron en doel. | ActionType MIGRATE_SOURCE_TO_TARGET en MIGRATE_TARGET_FROM_SOURCE. | CategoryHistory. |
| 11 | Backend | Systeemberichtencomponent | Bepaalt betrokken docenten en maakt systeemberichten aan. | Alleen docenten met actieve bronimpact worden geïnformeerd. | SystemMessages via centrale template. |
| 12 | Backend | Transactie | Commit transactie. | Alle wijzigingen zijn consistent opgeslagen. | Database. |
| 13 | Frontend | Detailweergave | Toont resultaat en vernieuwde impact. | De beheerder ziet nieuwe toestand. | Nieuw readmodel. |
8. Alternatieve en exceptionele processtromen
| ID | Vanaf stap | Situatie | Systeemgedrag | Popup / melding | Datamutatie |
|---|---|---|---|---|---|
| ALT-001 | 1 | Beheerder annuleert. | Er wordt geen migratie uitgevoerd. | POP-BEH-CAT-MIGRATION-CONFIRM. | Geen. |
| ALT-002 | 2 | Reden ontbreekt. | De bevestiging wordt geweigerd. | POP-BEH-CAT-MIGRATION-CONFIRM. | Geen. |
| ALT-003 | 4 | Bron of doel is gewijzigd sinds voorbereiding. | De migratie wordt geweigerd of het voorstel moet opnieuw worden berekend. | Niet van toepassing. | Geen. |
| ALT-004 | 4 | Doelcategorie is niet meer actief. | De migratie wordt geblokkeerd. | Niet van toepassing. | Geen. |
| ALT-005 | 6 | Doelkoppeling bestaat al op hetzelfde docentniveau. | De bestaande doelkoppeling wordt hergebruikt en bronkoppeling wordt conflictveilig verwerkt. | Niet van toepassing. | Transactie volgens migratieregels. |
| ALT-006 | 7 | Dezelfde oefening bestaat al actief onder de doelcategorie. | Er wordt geen dubbele oefenkoppeling aangemaakt. | Niet van toepassing. | Bronkoppeling wordt historisch/inactief verwerkt. |
| ALT-007 | 12 | Transactie faalt. | Alle mutaties inclusief history en systeemberichten worden teruggedraaid en de beheerder krijgt foutafhandeling. | Niet van toepassing. | Rollback. |
9. Business rules
| ID | Business rule |
|---|---|
| BR-001 | Een categoriemigratie vereist altijd een bestaande actieve doelcategorie. |
| BR-002 | Broncategorie en doelcategorie moeten verschillend zijn. |
| BR-003 | De backend herberekent impact vlak vóór uitvoering. |
| BR-004 | Migratie moet transactioneel zijn: koppelingen, CategoryMigrations en CategoryHistory blijven consistent. |
| BR-005 | Dubbele TeacherLevelCategories mogen niet blind worden aangemaakt. |
| BR-006 | Dubbele TeacherLevelCategoryExercises mogen niet blind worden aangemaakt. |
| BR-007 | Bestaande ExerciseRuns worden niet herschreven en behouden hun oorspronkelijke CategoryId-context. |
| BR-008 | Na succesvolle migratie is de broncategorie niet langer nieuw selecteerbaar voor docenten. |
| BR-009 | Migratie wordt in CategoryHistory zichtbaar op zowel bron- als doelcategorie. |
| BR-010 | Betrokken docenten worden geïnformeerd via centrale systeemberichtcommunicatie; berichtinhoud blijft bronhoudend in systeemberichttemplates. |
10. Datavalidatie
| ID | Validatie |
|---|---|
| VAL-001 | SourceCategoryId en TargetCategoryId zijn verplicht en verschillend. |
| VAL-002 | TargetCategoryId moet op uitvoermoment actief zijn. |
| VAL-003 | Reason is verplicht en maximaal 1000 tekens voor CategoryMigrations. |
| VAL-004 | MigratedByUserId is de actuele beheerder uit server-side sessiecontext. |
| VAL-005 | Voor iedere te migreren koppeling moet worden vastgesteld of een doelkoppeling al bestaat. |
| VAL-006 | Voor iedere onderliggende oefenkoppeling moet worden vastgesteld of dezelfde oefening al actief onder de doelcategorie bestaat. |
| VAL-007 | De volledige migratie moet binnen één database-transactie worden uitgevoerd. |
| VAL-008 | Ontvangers van migratiecommunicatie worden server-side bepaald uit actieve bronkoppelingen en niet uit clientinvoer. |
11. Datamutaties en events
| ID | Mutatie / event | Toelichting |
|---|---|---|
| MUT-001 | TeacherLevelCategories update/create/deactivate | Bronkoppelingen worden overgezet of conflictveilig samengevoegd met doelkoppelingen. |
| MUT-002 | TeacherLevelCategoryExercises update/create/deactivate | Onderliggende oefenkoppelingen worden overgezet zonder actieve duplicaten. |
| MUT-003 | Categories update | Broncategorie wordt niet langer nieuw selecteerbaar gemaakt. |
| MUT-004 | CategoryMigrations CREATE | Migratie wordt append-only vastgelegd met bron, doel, actor, tijdstip en reden. |
| MUT-005 | CategoryHistory CREATE | Bron- en doelcategorie krijgen elk leesbare migratiehistorie. |
| MUT-006 | SystemMessages CREATE | Betrokken docenten aan de bronkant worden geïnformeerd via de centrale systeemberichttemplate voor categoriemigratie. |
12. Geen datamutaties
| ID | Geen mutatie | Reden |
|---|---|---|
| NO-001 | ExerciseRuns | Historische runs behouden LevelId, CategoryId, ExerciseId en modulecontext. |
| NO-002 | SharedExercises | Snapshotteksten van gedeelde oefeningen worden niet herschreven. |
| NO-003 | Exercises | Concrete oefeningconfiguraties worden niet aangepast door categoriemigratie. |
| NO-004 | Users | Rollen en relaties worden niet aangepast. |
| NO-005 | PrivateMessages | Er wordt geen privébericht aangemaakt door de migratie zelf. |
13. State diagram
14. Decision flow
15. Data lifecycle diagram
16. Sequence diagrammen
17. Popupverwijzingen
Deze usecase verwijst uitsluitend naar PopupKey. Popupteksten, knopteksten, inputlabels, acties en themakeuzes blijven bronhoudend in het popupregister en popup-themes.
| PopupKey | Gebruik |
|---|---|
| POP-BEH-CAT-MIGRATION-CONFIRM | Definitieve bevestiging van categoriemigratie met verplichte reden. |
18. Afleiding naar Functioneel Ontwerp / Technisch Ontwerp / Software Requirements Specification
| Document | Afleiding |
|---|---|
| Functioneel Ontwerp | Categoriemigratie zet broncategorie om naar bestaande doelcategorie, houdt bron historisch herleidbaar en informeert betrokken docenten. |
| Technisch Ontwerp | Technisch Ontwerp: oefencatalogus, databaseontwerp en historie en background jobs beschrijven de technische uitwerking. Uitvoering vereist transactionele verwerking van koppelingen, migratierecord, historyregels en systeemberichten. |
| Software Requirements Specification | SRS moet duplicaatpreventie, rollbackgedrag, reason-validatie, docentcommunicatie en niet-herschrijven van historische runs eisen. |
| Database | Gebruikt CategoryMigrations, CategoryHistory, Categories, TeacherLevelCategories, TeacherLevelCategoryExercises en SystemMessages. |
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 |
|---|---|---|
UC-BEH-CAT-006-REQ-001 | SRS-CAT-004 SRS-ADM-006 SRS-ADM-001 AC-CAT-004 AC-ADM-006 AC-ADM-001 | Categoriemigratie alleen uitvoeren na bevestiging met verplichte reden |
UC-BEH-CAT-006-REQ-002 | SRS-ADM-001 AC-ADM-001 | Impact vlak vóór uitvoering opnieuw berekenen |
UC-BEH-CAT-006-REQ-003 | SRS-ADM-001 AC-ADM-001 | Migratie transactioneel uitvoeren |
UC-BEH-CAT-006-REQ-004 | SRS-ADM-001 AC-ADM-001 | Bestaande doelkoppelingen hergebruiken in plaats van dupliceren |
UC-BEH-CAT-006-REQ-005 | SRS-CAT-001 SRS-ADM-001 AC-CAT-001 AC-ADM-001 | Bestaande oefenkoppelingen onder de doelcategorie hergebruiken in plaats van dupliceren |
UC-BEH-CAT-006-REQ-006 | SRS-ADM-001 SRS-NFR-AUD-001 AC-ADM-001 AC-NFR-AUD-001 | CategoryMigrations vastleggen met bron, doel, beheerder, tijdstip en reden |
UC-BEH-CAT-006-REQ-007 | SRS-CAT-001 SRS-ADM-001 SRS-NFR-AUD-001 AC-CAT-001 AC-ADM-001 AC-NFR-AUD-001 | CategoryHistory vastleggen op bron- en doelcategorie |
UC-BEH-CAT-006-REQ-008 | SRS-CAT-004 SRS-ADM-006 SRS-ADM-001 AC-CAT-004 AC-ADM-006 AC-ADM-001 | De broncategorie na migratie niet langer nieuw selecteerbaar maken |
UC-BEH-CAT-006-REQ-009 | SRS-CAT-004 SRS-LRN-009 SRS-ADM-006 SRS-ADM-001 AC-CAT-004 AC-LRN-009 AC-ADM-006 AC-ADM-001 | Historische ExerciseRuns niet herschrijven door een categoriemigratie |
UC-BEH-CAT-006-REQ-010 | SRS-MSG-001 SRS-TCH-001 SRS-ADM-001 AC-MSG-001 AC-TCH-001 AC-ADM-001 | Betrokken docenten aan de bronkant informeren via centrale systeemberichtcommunicatie |
UC-BEH-CAT-006-REQ-011 | SRS-ADM-001 AC-ADM-001 | Bij fout de volledige migratie terugdraaien |