# 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 .php Wrapper: ───────────────────────────────── 1. Session-ID aus Cookie lesen (oder Autodidakt-UUID erzeugen) 2. GET /api/modules?student=1&module_id= → 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/-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**: `/` (z.B. `/logistik`) — lädt Modul direkt - **Mit Level**: `/?level=N` — springt zu bestimmtem Level - **Detail-Seite**: `/modul-` — Info-Seite ohne Spielstart - **Wrapper muss**: `window._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.