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
```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.