geograsim/App/docs/integration-konzept.md

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

// 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

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.