Adminator
1e51ef7def
- Konzept/, didaktik_geografie/, didaktik_simulation/, v2-modules/, v2-platform/ - 12 code-workspace-Files - STATUS-*.md - viele M/D/R-Änderungen an bereits getrackten Files - .gitignore verstärkt: **/.humaninput/, **/secret_keys.txt Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
5.9 KiB
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/<slug>/
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 | Sich über manifest.json deklarieren (Slug, Version, Difficulty, Lehrplan, Glossar-Schwerpunkte, Lieferpfade) |
| Input-API | 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 | Am Ende ein Result-Objekt an /api/result posten (Score, Coverage, Artefakte) |
| Telemetry-API | telemetry-api.md | Pflicht. Während der Sitzung Heartbeat + Milestones + Stuck-Signale an /api/telemetry pushen |
| Lieferformat | delivery-format.md | Den Modulordner exakt nach Schema strukturieren, Mock-Platform-Test bestehen |
| Plattform-Standards | 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 | 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.
✅ 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.jsonPflicht 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/<slug> |
GET | Glossar-Eintrag (Modul kann tooltips bauen) |
/v2beta/api/lehrplan/anker/<code> |
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 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.