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>
105 lines
5.9 KiB
Markdown
105 lines
5.9 KiB
Markdown
# 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](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/<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](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.
|