Atlas: Phase A Integrations-Konzept + Cockpit + End-Screen

- Integrations-Konzept dokumentiert (App/docs/integration-konzept.md) - Module-IDs vereinheitlicht: sim-XX -> semantische IDs (klima/heli/fluss/logistik/...) - class_modules um current_level + quiz_enabled Spalten erweitert - modules.php liefert dynamisch aus module_info, inkl. forcedLevel, quizEnabled, play_url, dueDate; neuer Filter ?module_id=X fuer einzeln - schueler.html Cockpit: komplett API-first, teacher_started-Sektion als Auftrags-Block, neue IDs, Sprachregel 4a (Starten statt Spielen) - teacher.html: Hardcoded ALL_MODS entfernt, laedt dynamisch - Design-System: .ggs-endscreen-Komponente fuer einheitliche Modul-Abschluesse - index.html Landing-Links gefixt: App/modul-X -> modul-X, V1-HTMLs auf Front-Controller-Routen (fluss, heli-game, stadt) - 6 Inbox-Auftraege an Instanzen (Klima/Heli/Fluss/Logistik/Lehrplan/Glossar) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 11:42:19 +02:00
parent b94658f57c
commit b356c79134
14 changed files with 1266 additions and 101 deletions
@@ -0,0 +1,463 @@
+# GeoGraSim — Integrations-Konzept
+
+**Stand:** 2026-04-23
+**Autor:** Atlas (Plattform-Instanz)
+**Status:** Entwurf zur Abstimmung mit Thomas, danach Auftrags-Generierung
+
+---
+
+## 0. Zweck des Dokuments
+
+Dieses Papier beschreibt, **wie Schüler:innen, Lehrkräfte, Module und Auswertungen
+ineinandergreifen sollen**. Es definiert den gemeinsamen Mechanismus, an den
+sich alle Module halten, damit der Gesamt-Flow stimmig wird.
+
+Es ist **kein** Implementierungsplan für einzelne Module — das bleibt bei den
+jeweiligen Instanzen. Es ist **ein** Vertrag: wer wohin springt, welche Daten
+wohin wandern, welche UI-Zustände es gibt.
+
+---
+
+## 1. Zwei Rollen + öffentliche Demo
+
+| Rolle | Einstieg | Hauptaufgabe |
+|-------|----------|--------------|
+| **Schüler:in** | `login.html` mit Klassen-Code + Benutzername | Lernt mit Modulen, sieht eigenen Fortschritt |
+| **Lehrkraft** | `login.html` mit eigenem Account | Steuert Klassen, gibt Module frei, wertet aus |
+| **Admin (Thomas)** | `admin.html` mit Admin-PIN | Verwaltet Module, Lehrkräfte, Lizenzen, Level-Parameter |
+
+**Öffentliche Demo** (ohne Rolle): Über die Landing-Seite `geograsim.at/` kann
+jede:r auf „▶ Sofort probieren" klicken und ein freigegebenes Modul direkt
+spielen. **Kein persistenter Fortschritt**, kein Account, keine Auswertung.
+Nur Schaufenster-Funktion, damit Schulleitungen und Eltern sehen können, was
+die App leistet.
+
+---
+
+## 2. Bestehendes Datenmodell (Ist-Stand auf Prod)
+
+### User-Daten — unverändert zu bewahren
+```
+teachers          (9 Zeilen)   → Lehrer-Accounts
+students          (32 Zeilen)  → Schüler-Accounts (pro Klasse)
+student_sessions  (24 Zeilen)  → UUID-Sessions (auch Autodidakt)
+classes           (7 Zeilen)   → Klassen pro Lehrer (mit join_code)
+licenses          (500 Zeilen) → Lizenzcodes
+admin_users       (1 Zeile)    → Thomas' Admin-Account
+```
+
+### Steuerung der Modul-Freigabe — existiert
+```
+class_modules (class_id, module_id, enabled, mode, started_at, due_date)
+  mode: 'locked' | 'free' | 'teacher_started'
+  
+student_modules (student_id, module_id, mode)
+  → Per-Schüler-Override einer Klassen-Einstellung
+```
+
+### Inhalt pro Modul
+```
+module_info (module_id, title, icon, short_desc, long_desc, learning_goals,
+             status, sort_order, + Leichte-Sprache-Varianten)
+game_levels (id, game_id, level_name, scenario, params JSON, sort_order)
+game_saves (session_id, save_key, save_data JSON)  → pro Schüler ein Autosave
+```
+
+### Auswertung — existiert, wird bisher kaum genutzt
+```
+assessments (session_id, sim_id, class_id, process_log, predictions,
+             results, reflections, duration_ms, completed_phases, submitted_at)
+assessment_answers (session_id, sim_id, phase pre/post, question_id,
+                    answer, correct)
+lg_contracts_log (modul-spezifisch für Logistik — Pattern für andere Module)
+```
+
+### Lehrplan-Verknüpfung — existiert
+```
+kompetenzen (slug, name, description)           → 4 Kompetenzen
+kompetenz_modules (kompetenz_id, module_id)     → Verknüpfung
+lehrplan_anchors (kompetenz_id, country, anchor_type, title, reference,
+                  quote)                         → 78 Anker (AT-Fokus)
+```
+
+---
+
+## 3. Flow 1 — Schüler:in mit Klassenzugehörigkeit
+
+### 3.1 Einstieg
+```
+geograsim.at/login  
+  ├─ Klassencode (6-stellig) + Benutzername + Passwort
+  └─ oder "Ich habe keinen Code" → Autodidakt-Modus
+```
+
+Nach Login: **Cockpit** (`sim.html`).
+
+### 3.2 Cockpit = Modul-Auswahl
+
+Cockpit zeigt **alle Module der Lehrkraft-Freigabe**:
+
+```
+API: GET /api/modules?student=1
+→ [
+    {id:'klima',    name:'Klimawächter',   icon:'🌍', mode:'free'},
+    {id:'heli',     name:'Heli-Navigation',icon:'🚁', mode:'teacher_started'},
+    {id:'logistik', name:'Logistik Europa',icon:'🚚', mode:'locked'},
+    ...
+  ]
+```
+
+Visualisierung je nach `mode`:
+
+| Mode | Card-Anzeige | Klick-Verhalten |
+|------|--------------|-----------------|
+| `free` | Normal, voll klickbar | Springt direkt zum Modul-Einstieg |
+| `teacher_started` | Highlighted (Lehrer-Impuls) + „Jetzt dran" | Springt direkt ins **Lehrer-gewählte Level** |
+| `locked` | Ausgegraut, Schloss-Icon | Tooltip „Noch nicht freigegeben" — kein Klick |
+
+Zusätzlich: **Fortschritts-Badge** pro Card wenn `game_saves` vorhanden („zuletzt bei Level 2 · 45 %").
+
+### 3.3 Modul-Einstieg (einheitlich für ALLE Module)
+
+Jedes Modul hat eine **Einstiegs-URL** (z.B. `/klima-2d`, `/heli-game`, `/logistik`). Diese entscheidet beim Laden:
+
+```
+Pseudocode in <modul>.php Wrapper:
+─────────────────────────────────
+1. Session-ID aus Cookie lesen (oder Autodidakt-UUID erzeugen)
+2. GET /api/modules?student=1&module_id=<X>
+   → Antwort: { mode, forcedLevel, allowedLevels, due_date }
+3. Je nach mode:
+   - 'free'             → Level-Picker anzeigen (Lernen / Üben / Profi)
+   - 'teacher_started'  → automatisch forcedLevel starten, kein Picker
+   - 'locked'           → Sperrseite anzeigen, zurück zum Cockpit
+4. In jedem Fall: Autosave aus game_saves vorladen wenn vorhanden
+```
+
+### 3.4 Während des Spiels
+
+- **Autosave**: Bei jedem state-relevanten Übergang → POST `/api/<modul>-saves.php`
+  (Logistik hat das schon, Klima/Heli/Fluss müssen nachziehen)
+- **Assessment-Capture** (optional, aber empfohlen):
+  - **Pre-Quiz** am Anfang: 3 kurze Fragen → `assessment_answers`
+  - **Post-Quiz** am Ende: dieselben Fragen → Delta = Lernzuwachs
+- **Events** für Lehrer-Live-Sicht: alle 30 s ein Ping POST `/api/assessment.php`
+  mit Zwischenstand (Kennzahlen des Moduls)
+
+### 3.5 Modul-Abschluss
+
+End-Screen jedes Moduls hat **einheitliche Buttons**:
+
+```
+┌──────────────────────────────────────────┐
+│ Durchgang abgeschlossen · {module-name}  │
+│ {Auswertung spezifisch pro Modul}        │
+│                                          │
+│ [ 🏠 Zurück zum Cockpit ]                │
+│ [ ↻ Neuer Durchgang ]                    │
+│ [ 📊 Auswertung ansehen ] (optional)     │
+└──────────────────────────────────────────┘
+```
+
+„Zurück zum Cockpit" führt immer nach `/sim` (nicht zur Landing). Das ist ein **Plattform-Invariant**.
+
+---
+
+## 4. Flow 2 — Lehrkraft
+
+### 4.1 Einstieg
+```
+geograsim.at/login  
+  → Teacher-Login (Benutzername + Passwort)
+  → teacher-dashboard.html
+```
+
+### 4.2 Dashboard-Hauptbereiche
+
+```
+┌─ Klassen-Liste (links) ────────────────────────┐
+│ - 1A (1. Klasse, 18 Schüler:innen)             │
+│ - 2B (2. Klasse, 15 Schüler:innen)             │
+│ - +-Neue-Klasse                                │
+└────────────────────────────────────────────────┘
+
+Nach Klassen-Klick → drei Tabs:
+
+[Übersicht] [Modul-Steuerung] [Auswertung]
+```
+
+#### Tab „Übersicht" (existiert sinngemäß schon)
+- Aktuell anwesende Schüler:innen (live via `last_seen`)
+- Wer bei welchem Modul
+- Heatmap: Aktivität pro Modul × pro Schüler
+
+#### Tab „Modul-Steuerung" (teilweise da — ausbauen)
+Matrix: Module (Zeilen) × Schüler (Spalten). Pro Zelle Drop-down:
+- Default (Klassen-Einstellung übernehmen)
+- Frei wählbar
+- Vom Lehrer gestartet (Level 1 / 2 / 3)
+- Gesperrt
+
+Ober-Reihe („Alle Schüler"): Klassen-Default setzen. Spalten-Kopf pro Schüler: individuelles Override.
+
+Plus Live-Button: **„Jetzt Modul X, Level Y für alle starten"** → setzt `teacher_started` + notification an alle anwesenden Schüler → Cockpit refresht → neuer Modul-Impuls erscheint.
+
+#### Tab „Auswertung" (FEHLT — ist Neubau)
+Pro Modul:
+- Durchschnittlicher Fortschritt
+- Pre-vs-Post-Quiz Delta (Lernzuwachs)
+- Wer hat abgeschlossen, wer hängt
+- Modul-spezifische Kennzahlen (aus `assessments.results` + modul-eigene Logs wie `lg_contracts_log`)
+- Drill-Down: einzelne Schüler:innen-Session im Detail
+
+### 4.3 Pro Modul einheitliche Auswertungs-Seite
+
+Jedes Modul liefert Kennzahlen nach einem **Standard-Schema**. Details siehe §6.
+
+---
+
+## 5. Flow 3 — Öffentliche Demo (Landing)
+
+Über `geograsim.at/` klickt ein Besucher auf „▶ Sofort probieren" eines
+Moduls:
+
+```
+geograsim.at/  →  Card „▶ Sofort probieren"  →  Modul startet direkt
+```
+
+- Kein Login, keine Klasse, keine Zuordnung zu einem Account
+- **Kein persistenter Fortschritt** — bei Reload ist alles weg
+- Keine Assessment-Calls, keine DB-Schreibzugriffe
+- Ausschließlich Schaufenster-Funktion für Interessierte,
+  Schulleitungen, Eltern
+
+Technisch: Der Modul-Wrapper erkennt „keine Session vorhanden" und läuft
+im **Demo-Modus** (nur In-Memory-State). Kein `game_saves`-Eintrag,
+kein `assessments`-Eintrag.
+
+Die „Sofort probieren"-Cards auf der Landing sind nur für Module mit
+Status `aktiv` (in `module_info`) sichtbar. Geplante/Beta-Module bleiben
+ausgegraut („LOCKED"-Optik).
+
+---
+
+## 6. Modul-Interface-Vertrag
+
+Jedes Modul (Klima, Heli, Fluss, Logistik, Stadt, Erdbeben, Energiemix,
+Lieferketten, Regenwald, zukünftige Module) muss folgende Schnittstellen
+bedienen:
+
+### 6.1 URL-Einstieg
+- **Primäre URL**: `/<modul-id>` (z.B. `/logistik`) — lädt Modul direkt
+- **Mit Level**: `/<modul-id>?level=N` — springt zu bestimmtem Level
+- **Detail-Seite**: `/modul-<modul-id>` — Info-Seite ohne Spielstart
+- **Wrapper muss**: `window.<MODUL>_MODE` aus API-Call setzen
+  (`free`/`teacher_started`/`locked`), Level-Picker je nach Mode anzeigen
+
+### 6.2 Level-Start einheitlich
+Beim Start eines Levels (egal welches Modul):
+1. Prüfen ob `game_saves` für diese Session+Modul+Level existiert
+2. Falls ja: „Weitermachen" oder „Neu starten" fragen
+3. Level-Params aus `game_levels.params` laden
+4. **Optional Pre-Quiz** anzeigen (3 Fragen, 30 s)
+5. Modul-Simulation beginnt
+
+### 6.3 Fortschritts-Meldung während Spiel
+```js
+// Alle 30 s oder bei wichtigen Milestones
+POST /api/assessment.php
+{
+  sessionId: "...",
+  simId: "logistik",
+  phase: "running",
+  kennzahlen: { /* modul-spezifisch */ },
+  completedPhases: 2,
+  durationMs: 123000
+}
+```
+
+### 6.4 Abschluss-Meldung
+```js
+POST /api/assessment.php
+{
+  sessionId: "...",
+  simId: "logistik",
+  phase: "completed",
+  results: { /* Module liefert strukturierte Kennzahlen */ },
+  reflections: { /* Schüler-Eingaben */ },
+  durationMs: 1234567,
+  completedPhases: 7
+}
+```
+
+Modul-spezifische Tabellen (wie `lg_contracts_log`) zusätzlich für tiefere
+Analyse — aber `assessments` ist der **Haupt-Hook**, auf den das
+Lehrer-Dashboard zugreift.
+
+### 6.5 End-Screen-Buttons
+Siehe §3.5 — immer dieselben drei: Cockpit / Neu / Auswertung.
+
+### 6.6 Sprachregel + Leichte Sprache
+- Sprachregel 4a (keine „Spiel/Spieler"-Wörter) — **Pflicht**
+- Leichte Sprache via `pickText({standard, easy})` — **Pflicht** bei UI-Kernelementen
+- easy-Flag kommt aus `students.easy_language` → per Wrapper an Modul durchgereicht
+
+### 6.7 Lehrplan-Anker
+- Modul muss in `kompetenz_modules` mit den Kompetenzen verknüpft sein, die es trainiert
+- Kompetenz-Anker in `lehrplan_anchors` müssen für mindestens AT vorliegen
+- Modul kann über `/api/dashboard.php?module_id=X&country=AT` Anker abrufen und
+  im Didaktikfenster zeigen
+
+---
+
+## 7. Gaps — was heute fehlt
+
+### 7.1 Cockpit (sim.html)
+- **Aktuell**: Platzhalter-Modul-Auswahl, teilweise mit falschen Links
+- **Fehlt**: echte Anbindung an `/api/modules?student=1`, korrekte Routing je mode, Fortschritts-Badges
+
+### 7.2 Lehrer-Dashboard
+- **Aktuell**: „Klasse 1A — Übersicht" steht, aber meiste Tabs sind Mockup
+- **Fehlt**: Modul-Steuerungs-Matrix live-bindend, Live-Impuls-Button, Auswertungs-Tab
+  komplett
+
+### 7.3 Modul-Wrapper (alle Module uneinheitlich)
+- Klima, Heli, Fluss, Logistik haben **jeweils eigene** Start-Patterns
+- **Pflicht-Umstellung**: alle müssen auf den einheitlichen Level-Start + mode-check
+  wechseln
+- Logistik ist am weitesten, kann Vorbild werden
+
+### 7.4 Lehrplan-Anker pro Modul (teilweise da)
+- AT: 78 Anker, gut verteilt, aber **für Logistik komplett fehlend** (weil neues Modul)
+- Logistik-Kompetenzen-JSON existiert als `App/sims/logistik/kompetenzen.json` —
+  muss ins DB-Format übertragen werden (via Lehrplan-Instanz)
+
+### 7.5 Assessment-Anbindung pro Modul
+- **Aktuell**: `assessments`-Tabelle leer auf allen Instanzen (lokal + prod)
+- **Fehlt**: jedes Modul ruft `/api/assessment.php` auf (bei Start, alle 30 s,
+  am Ende)
+
+### 7.6 Pre/Post-Quiz-Infrastruktur
+- **Aktuell**: Tabelle `assessment_answers` existiert, UI-Komponente fehlt
+- **Fehlt**: wiederverwendbarer Mini-Quiz-Dialog als Design-System-Komponente
+
+### 7.7 Kaputte Links
+- Landing-Cards zeigen teilweise auf `App/modul-X` statt `/modul-X` (dank
+  BASE_PATH-Umbiegung funktionierts zufällig)
+- Einige `.html`-Direkt-Links werden ignoriert weil Front-Controller-Routing
+- Lehrplan-Link in Logistik zeigt auf leere Kompetenz-Anzeige (Gap 7.4)
+- „Zurück"-Buttons in einigen Modulen führen nach Landing statt Cockpit
+
+---
+
+## 8. Phasenplan für die Umsetzung
+
+### Phase A — Fundament (Atlas, 1 Tag)
+- Cockpit (`sim.html`) mit echter Modul-API-Bindung
+- Lehrer-Dashboard Modul-Steuerungs-Matrix live-bindend
+- Link-Audit: alle Navigation-Endpunkte prüfen + fixen
+- Einheitliche End-Screen-Komponente im Design-System (`.ggs-endscreen`)
+
+### Phase B — Module einheitlich machen (alle Modul-Instanzen parallel, 2-3 Tage)
+- Jede Modul-Instanz zieht auf das §6-Interface um
+- Konkrete Aufträge:
+  - **Klima** (Klima-Instanz): Level-Start mit mode-check, Assessment-Calls
+  - **Heli** (Heli-Instanz): Level-Start + Phasen-Meldung; dazu Mission-Bilder abschließen
+  - **Fluss** (Fluss-Instanz): Level-Start + Assessment-Calls, Phase 2 weitermachen
+  - **Logistik** (Logistik-Instanz): bereits am nächsten dran, letzte Verfeinerungen
+- **Lehrplan-Instanz**: Logistik-Kompetenzen und -Anker in DB übertragen
+
+### Phase C — Auswertung (Atlas, 1-2 Tage)
+- Lehrer-Dashboard Tab „Auswertung" pro Modul
+- Pre/Post-Quiz-Komponente im Design-System
+- Drill-Down-Ansichten einzelner Schüler-Sessions
+
+### Phase D — Autodidakt-Flow (Atlas, 0,5 Tag)
+- Landing-Seite „Sofort probieren" ohne Login-Redirect
+- Session-Transfer wenn Autodidakt sich doch einloggt (Nice-to-have, kann später)
+
+### Phase E — Feinschliff (alle, 1 Tag)
+- Sprachregel-Durchlauf durch alle UIs
+- Leichte-Sprache-Durchlauf durch alle UIs
+- Browser-Test auf iPad
+- Deploy auf Prod
+
+**Gesamt: ~5-7 Arbeitstage**, verteilt auf alle Instanzen + Atlas. Nicht linear,
+vieles parallelisierbar.
+
+---
+
+## 9. Konkrete Aufträge, die aus diesem Konzept entstehen
+
+### An Lehrplan-Instanz
+- **Logistik-Lehrplan-Anker anlegen**: aus `App/sims/logistik/kompetenzen.json`
+  die 23 Anker in `lehrplan_anchors` übertragen, mit AT-Fokus
+  (Vorschläge: „GW Sek I: Europa-Wirtschaftsräume", „Verkehrs- und
+  Güterströme Europas")
+- **Modul-Klima-Toggle** (alte Anfrage, immer noch offen): 2D/3D-Launcher auf
+  `modul-klima.php`
+
+### An Klima-Instanz
+- **Level-Start auf Standard-Pattern umstellen**: mode-check + Pre-Quiz-Hook
+- **Assessment-Calls** einbauen: start, 30s-Ping, end
+- **End-Screen** auf neue `.ggs-endscreen`-Komponente umstellen (kommt aus Phase A)
+
+### An Heli-Instanz
+- **Level-Start vereinheitlichen** — Aktuell hat Heli eigenes Auftrag-Wahl-Muster;
+  muss auf „Vom Lehrer gestartet" + „Frei wählbar" reagieren
+- **Mission-Bilder abschließen** (offen seit langem)
+- **Assessment-Calls** einbauen
+
+### An Fluss-Instanz
+- **Level-Start vereinheitlichen**
+- **Phase 2 (Spiellogik-Port)** weiter
+- **Assessment-Calls** einbauen
+
+### An Logistik-Instanz
+- **admin-fields.json** liefern (aus Phase-7-Entscheidung, steht in Inbox)
+- Phase 7b Rest: API-Endpunkte + Analytics-Logging (läuft)
+- **Endscreen-Adaption** wenn `.ggs-endscreen` da ist
+
+### An Glossar-Instanz
+- **13 Logistik-Begriffe** liefern (Erinnerung, Anfrage seit 3 Tagen)
+- **Hafen**, **Luftlinie** auf Doppelnutzung prüfen
+
+### An Atlas (selbst)
+- Phase A, C, D — im Phasenplan eingeteilt
+- `.ggs-endscreen`-Komponente im Design-System
+- Link-Audit
+- Konzept mit Thomas abstimmen, committen, dann umsetzen
+
+---
+
+## 10. Entscheidungen (von Thomas, 2026-04-23)
+
+1. **Autodidakt**: existiert nicht als eigene Rolle. Landing hat „Sofort
+   probieren" als flüchtige Demo ohne Persistenz.
+2. **Live-Impuls**: 5-Sekunden-Polling (robust, ausreichend).
+3. **Pre/Post-Quiz**: optional, von Lehrkraft pro Modul aktivierbar.
+   Aktivierter Quiz erscheint im Schüler-Cockpit als **„Auftrag"**
+   (mit Deadline, wenn gesetzt). Schüler:in kann ihn im Cockpit starten.
+4. **Link-Audit**: nach Phase B (wenn Module sowieso umgebaut werden —
+   viele Links richten sich durch das neue Interface von selbst).
+5. **Phasen**: A und B **parallel**, C nach deren Abschluss.
+
+---
+
+## 11. Grundsätze, die das Konzept trägt
+
+- **Einheitlichkeit vor Komfort**: lieber ein Modul auf Standard umbauen als
+  Sonderlocke pflegen
+- **Datenfluss einfach**: Schüler → `assessments` + `game_saves` → Lehrer-Dashboard
+- **Progressive Enhancement**: auch Offline-/Autodidakt-Modus funktioniert
+- **Plattform-Invarianten** (Cockpit, End-Screen, Level-Start) werden von
+  Atlas gebaut, Module nutzen sie
+- **Keine KI im Produkt** (bestehende Regel) — Auswertungen parametrisch
+- **Sprachregel 4a** (keine Spielsprache) durchgezogen
+- **Produktions-User bewahren** — bei jedem Deploy Zeilenzahlen verifizieren
+
+---
+
+**Ende des Konzept-Dokuments.** Thomas: bitte die fünf offenen Entscheidungen
+in §10 beantworten, dann generiert Atlas die konkreten Inbox-Aufträge an die
+Instanzen.