Adminator
1e51ef7def
- Konzept/, didaktik_geografie/, didaktik_simulation/, v2-modules/, v2-platform/ - 12 code-workspace-Files - STATUS-*.md - viele M/D/R-Änderungen an bereits getrackten Files - .gitignore verstärkt: **/.humaninput/, **/secret_keys.txt Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
172 lines
6.2 KiB
Markdown
172 lines
6.2 KiB
Markdown
# 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](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_<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
|
||
|
||
```bash
|
||
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](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.
|