# GeoGraSim V2 — Modul-Schnittstellen-Spec **Status:** v1.0-stable (2026-05-17) — alle [REVIEW]-Punkte mit Thomas geklärt, Modul-Instanzen dürfen jetzt nach dieser Spec bauen **Geltungsbereich:** alle V2-Module unter `v2-modules//` **Plattform-Vertragspartner:** Atlas (V2-Plattform unter `v2-platform/`) --- ## Was ist das hier Diese Spec ist **der einzige Vertrag**, über den V2-Module mit der V2-Plattform sprechen. Wer sich daran hält, wird in `/v2beta` integriert. Wer nicht, fliegt zurück. **Designprinzip**: Module sind **integrationsfähige Komponenten**, keine Insel-Apps. Sie kennen die Plattform-APIs, aber nicht den Plattform-Code. Sie liefern Telemetry und Ergebnisse über definierte Endpoints. Alles andere (Login, Klassen, Glossar, Lehrplan-Anzeige, Easy-Sprache-Auswertung, Lehrer-Live-Dashboard) macht die Plattform. ## Die fünf Verträge plus Plattform-Standards | Vertrag | File | Was das Modul tun muss | |---|---|---| | **Manifest** | [module-manifest.md](module-manifest.md) | Sich über `manifest.json` deklarieren (Slug, Version, Difficulty, Lehrplan, Glossar-Schwerpunkte, Lieferpfade) | | **Input-API** | [input-api.md](input-api.md) | Beim Start die Plattform-API für User-Profil und Resume-State abrufen (NICHT direkt auf DB) | | **Output-API** | [output-api.md](output-api.md) | Am Ende ein Result-Objekt an `/api/result` posten (Score, Coverage, Artefakte) | | **Telemetry-API** | [telemetry-api.md](telemetry-api.md) | **Pflicht.** Während der Sitzung Heartbeat + Milestones + Stuck-Signale an `/api/telemetry` pushen | | **Lieferformat** | [delivery-format.md](delivery-format.md) | Den Modulordner exakt nach Schema strukturieren, Mock-Platform-Test bestehen | | **Plattform-Standards** | [platform-standards.md](platform-standards.md) | **Pflicht.** Design-Prinzipien (Wygotski, keine Spielsprache, Anrede „Lehrperson" nicht „Lehrkraft", keine KI im Produkt), iPad-Layout-Pattern, Bildstil, UI-Tokens, Avatar-Pool, zentrale API-Keys (DALL-E / ElevenLabs / Tile-Proxy), Multi-Locale-Strategie, **Barrierefreiheit (WCAG 2.1 AA)** | | **Level-Unlock-Konzept** | [level-unlock-konzept.md](level-unlock-konzept.md) | **Pflicht.** Drei Modi (frei / Auftrag / Nachteilsausgleich), Level-Freischaltung pro Schüler*in × Modul, Lehrperson-Aufträge mit fester Schwierigkeit. | Plus eine **Migrations-Anleitung** für die Übernahme bestehender V1-Module: [migration-from-v1.md](migration-from-v1.md). ## ✅ Geklärt mit Thomas (Spec-Reviews 2026-05-16/17) Alle [REVIEW]-Punkte aus den vorigen Iterationen sind beantwortet — siehe einzelne Files. Wichtigste Entscheidungen: - **Telemetrie-Frequenz + Token-TTL**: nicht in Modulen hardcoded, sondern aus zentraler Plattform-Konfig (`/api/runtime-config`, im Admin-Board justierbar) - **API-Keys (DALL-E, ElevenLabs)**: nur lokal, niemals auf Server — Assets vor Deploy generieren - **Konformitäts-Check**: automatisch bei Patch-Updates, Atlas-Review zwingend bei Major-Updates - **Migrations-Reihenfolge**: Plattform-Services (Glossar, Lehrplan) → kleine Module → große Module - **Freitext-Antworten**: mit Klarnamen an Lehrperson (wie V1) - **V1 + V2 parallel**: V1-Module bleiben voll nutzbar bis Stable-Switch - **UI-Konsistenz**: strikt — nur `var(--ggs-*)` erlaubt, Spezialfarben pro Modul auf Antrag - **`admin-fields.json` Pflicht** in jedem V2-Modul (modul-eigene Tuning-Parameter) - **Level-Unlock**: pro Schüler*in × Modul gespeichert (`student_level_unlock_v2`), L1 startet immer freigeschaltet, L2 nach L1-Erfolg - **Nachteilsausgleich**: Flag auf Schüler*in (`students.nachteilsausgleich`), darf alle Level frei wählen — auch im Auftragsmodus - **Lehrperson** statt „Lehrkraft" in allen sichtbaren Texten ## Geltung der Verträge - Alle fünf Verträge sind **Pflicht**, kein „kommt später" - Atlas integriert nur Module, die alle fünf erfüllen — überprüft per automatisiertem Konformitäts-Check (siehe `delivery-format.md`) - Spec-Änderungen passieren nur in Abstimmung mit allen aktiven Modul-Instanzen plus Atlas plus Thomas-Approval ## Versionierung Diese Spec ist **v1.0-draft**. Erst nach Thomas-Review wird sie zu **v1.0-stable** und Modul-Instanzen können losbauen. Spätere Spec-Änderungen sind: - **Patch (1.0.x)**: Klarstellungen, neue Felder mit Defaults — keine Modul-Anpassung nötig - **Minor (1.x.0)**: neue optionale Verträge — Module können sie übernehmen, müssen aber nicht - **Major (x.0.0)**: Breaking Change — alle Module müssen migrieren, Plattform muss kompatibel bleiben für eine Übergangszeit ## Zentrale Pfade in der Plattform | Endpoint | Methode | Zweck | |---|---|---| | `/v2beta/api/student/me` | GET | Profil des aktuell eingeloggten Schüler*in | | `/v2beta/api/module/state` | GET | Letzter Stand für Resume | | `/v2beta/api/result` | POST | Endergebnis bei Modul-Abschluss | | `/v2beta/api/telemetry` | POST | Live-Events (Heartbeat/Milestone/Stuck) | | `/v2beta/api/glossary/` | GET | Glossar-Eintrag (Modul kann tooltips bauen) | | `/v2beta/api/lehrplan/anker/` | GET | Lehrplan-Beschreibung | Vollständige API-Doku → siehe einzelne Vertrags-Dateien. ## Was die Spec NICHT regelt - **Modul-interne Architektur**: HTML/Vue/React/Vanilla — egal, solange das Lieferformat passt - **Modul-eigene PHP-Endpoints**: erlaubt, aber nur für interne Modul-Logik (z.B. Strecken-Daten laden) — nicht für User/Auth - **Pädagogisches Konzept** (Aufgabenstellung, Levels, Storylines) — das bleibt Modul-Sache (Plattform liefert nur Lehrplan-Anker zur Auswahl) **Aber:** Was die Spec sehr wohl regelt ist die **visuelle und didaktische Konsistenz** (Bildstil, UI-Tokens, Sprache, iPad-Patterns) — das steht in [platform-standards.md](platform-standards.md) und ist für jedes Modul verbindlich. ## Diskussionspunkte für Thomas-Review Markiert in den einzelnen Files mit `> [REVIEW]:`. Bitte beim Durchlesen darauf achten und Entscheidung treffen.