# Anhang: Migration von V1 nach V2 Nicht alle Module starten auf der grünen Wiese. Die meisten existieren bereits als V1 unter `App/sims//` und sind seit 2026-05-04 live mit echten Schul-Accounts. Diese Anleitung beschreibt, wie ein V1-Modul nach V2 portiert wird. ## Grundregeln 1. **V1 bleibt unangetastet.** `App/sims//` wird NICHT geändert, außer für echte Bugfixes (siehe `feedback_live_betrieb_versionen.md`). 2. **V2 entsteht parallel** in `v2-modules//` als self-contained Lieferpaket nach dieser Spec. 3. **Daten bleiben kompatibel.** V2-Tabellen sind additiv. Alte V1-Daten werden NICHT migriert — sie bleiben in V1-Tabellen, neue V2-Sitzungen schreiben in V2-Tabellen mit Versions-Marker. 4. **Modul-Instanz entscheidet selbst**, ob V2 neuer Code oder refaktorierter V1-Code wird. Empfehlung: bei kleinen Modulen neu, bei großen gezielt refaktorieren. ## Schritt-für-Schritt ### Schritt 1: V1-Bestandsaufnahme Modul-Instanz schreibt eine kurze `MIGRATION-NOTES.md` mit: - Aktuelle V1-Architektur (welche Files, wie viele Zeilen) - V1-Tabellen-Schema - V1-Asset-Liste - Bekannte Probleme / Tech-Debt - Was in V2 anders/besser werden soll Lege diese Notes in `v2-modules//docs/MIGRATION-NOTES.md` ab. ### Schritt 2: Lieferordner anlegen ``` v2-modules// ├── manifest.json ← neu schreiben nach Spec ├── README.md ← neu schreiben ├── public/ │ ├── game.html ← kopiert oder neu, mit Spec-Anpassungen │ └── assets/ ← Bilder/Audio/Daten aus V1 kopieren ├── db/ │ └── migrations.sql ← neue m__*-Tabellen oder leer └── tests/ └── mock-platform.html ← neu schreiben ``` ### Schritt 3: Easy-Sprache hinzufügen V1-Module hatten Easy-Sprache uneinheitlich. V2 verlangt sie **für alle sichtbaren Texte**. Modul-Instanz muss: 1. Alle UI-Texte als i18n-Keys auslagern 2. Easy-Variante für jeden Text schreiben (Netzwerk-Leichte-Sprache- Regeln, A1–A2-Niveau) 3. `public/i18n/de-AT-standard.json` und `de-AT-easy.json` anlegen 4. Beim Start aus `lang`-URL-Param laden ### Schritt 4: Telemetry-Hooks einbauen V1 kannte keine Telemetry. V2 verlangt drei Event-Typen (siehe [telemetry-api.md](telemetry-api.md)): 1. **Heartbeat-Loop** auf 15-Sekunden-Intervall starten, sobald Schüler*in aktiv ist 2. **Milestone-Calls** an allen definierten Erfolgs-Punkten einbauen (zuerst im Manifest deklarieren!) 3. **Stuck-Detection** — letzten User-Input-Timestamp tracken, bei 90s+ Stuck-Event posten Hilfsbibliothek **wird** Atlas in `v2-platform/lib/telemetry-client.js` als ESM-Modul anbieten, das Module einbinden können statt selbst zu implementieren. ### Schritt 5: Result-Output anpassen V1-Module schickten Ergebnisse an unterschiedliche Endpoints (`/api/save_assessment.php`, `/api/level_complete.php`, etc.). V2 hat einen einheitlichen Endpoint: ```http POST /v2beta/api/result ``` Modul muss alle alten Ergebnis-Calls auf diesen Endpoint zusammenziehen (siehe [output-api.md](output-api.md)). ### Schritt 6: Direkten DB-Zugriff entfernen V1-Module hatten teils direkten Zugriff auf `students`, `classes`, `assessments`. V2 verlangt API-Zugriff via Plattform-Endpoints. Modul muss: 1. Alle SQL-Queries auf Plattform-Tabellen entfernen 2. Stattdessen `/v2beta/api/student/me` und `/v2beta/api/module/state` nutzen 3. Eigene Modul-Tabellen mit Prefix `m__` neu anlegen (V1-Tabellen werden NICHT mitgenutzt) ### Schritt 7: Lehrplan-Anker und Glossar deklarieren Modul-Instanz pflegt im Manifest: - `lehrplanAnker` — Codes aus AT-GW-Lehrplan, die das Modul wirklich trainiert (mit Lehrplan-Instanz abstimmen) - `glossarBegriffe` — Slugs aus `glossar`-Tabelle, die das Modul voraussichtlich verwendet (mit Glossar-Instanz abstimmen) ### Schritt 8: Konformitäts-Check ```bash cd v2-modules/ php ../../v2-platform/tools/conformance-check/check.php ``` Bei „LIEFERBEREIT": Inbox an Atlas. Bei Fehlern: fixen. ### Schritt 9: Atlas-Integration und Live-Deploy Siehe [delivery-format.md](delivery-format.md) ab Abschnitt „Lieferprozess". ## Reihenfolge der Modul-Migration (Roadmap) Thomas-Vorgabe (2026-05-16): „Erst die einfachen, dann die schwierigen. Updates in Modulen sind dabei OK." Vorschlag-Reihenfolge: | Welle | Module | Begründung | |---|---|---| | 1 | Glossar, Lehrplan | Fundament für alle anderen — müssen als erstes V2 sein | | 2 | Sonnensystem, Entscheidungstag | Kompakt, klar abgegrenzt | | 3 | Energiemanager, Heli, Busfahrt, Farmer | Mittelgroß | | 4 | Klima, Logistik | Größte/komplexeste Module zuletzt | | – | Fluss, Staustufen | Status klären (Fluss aktiv? Staustufen pausiert) | Genaue Reihenfolge wird mit Modul-Instanzen abgestimmt, sobald die Spec stable ist. ## Was passiert mit V1? - V1 bleibt während der gesamten V2-Migration produktiv unter `geograsim.at/` - Sobald ein Modul V2 hat und freigeschaltet ist: - Lehrer*innen können in V2-Cockpit das V2-Modul wählen - V1-Modul bleibt parallel verfügbar in V1-Cockpit (für Klassen, die mitten in V1-Stunde sind) - Wenn alle Module V2 haben: - Stable-Switch (siehe [project_v2_arbeitsmodell.md](../../memory)) - V1 wandert nach `/v1archiv` - V1-Code wird 6+ Monate als Notfall-Rollback aufbewahrt - V1-Daten bleiben **dauerhaft erhalten** — nichts wird gelöscht ## ✅ Geklärt mit Thomas (2026-05-17) - **Migrations-Wellen**: bestätigt — Plattform-Services (Glossar, Lehrplan) zuerst (Welle 1), dann kompakte Module (Sonnensystem, Entscheidungstag — Welle 2), dann mittelschwere (Energiemanager, Heli, Busfahrt, Farmer — Welle 3), zuletzt die komplexen (Klima, Logistik — Welle 4). Fluss + EU-Werkstatt: Status vorher klären. - **V1 bleibt parallel voll nutzbar** bis zum Stable-Switch. Keine Read-only-Markierung pro Modul. Lehrperson entscheidet selbst, wann sie ihre Klasse auf V2 umzieht. V2 erscheint zunächst als „Beta"- Angebot im V1-Cockpit. - **Keine Daten-Bridge zwischen V1 und V2**: cleaner Schnitt. Schüler*in startet in V2 frisch (alle Module L1, Lerngeschichte leer). Hintergrund: V1-XP-Level ≠ V2-Difficulty-Level (V1 hat das vermischt, V2 trennt es sauber). V1-Daten bleiben in V1-Tabellen als historische Auswertung sichtbar.