geograsim/v2-modules/_spec/migration-from-v1.md

Anhang: Migration von V1 nach V2

Nicht alle Module starten auf der grünen Wiese. Die meisten existieren bereits als V1 unter App/sims/<slug>/ 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/<slug>/ wird NICHT geändert, außer für echte Bugfixes (siehe feedback_live_betrieb_versionen.md).
2. V2 entsteht parallel in v2-modules/<slug>/ 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/<slug>/docs/MIGRATION-NOTES.md ab.

Schritt 2: Lieferordner anlegen

v2-modules/<slug>/
├── 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_<slug>_*-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):

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:

POST /v2beta/api/result

Modul muss alle alten Ergebnis-Calls auf diesen Endpoint zusammenziehen (siehe 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_<slug>_ 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

cd v2-modules/<slug>
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 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)
  • 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.