# Spec v1.0-stable — 2026-05-17

Alle [REVIEW]-Punkte mit Thomas geklärt, Spec einbau-fertig für
Modul-Instanzen.

## Was sich seit gestern geändert hat

### Spec-Files: alle [REVIEW]-Stellen durch konkrete Entscheidungen ersetzt

| File | Entscheidung |
|---|---|
| [README.md](v2-modules/_spec/README.md) | Status v1.0-stable, neue Sektion „Geklärt mit Thomas" mit allen 11 Kernentscheidungen |
| [module-manifest.md](v2-modules/_spec/module-manifest.md) | `adminFieldsFile` als Pflicht-Feld, Difficulty-Level frei pro Modul |
| [input-api.md](v2-modules/_spec/input-api.md) | Neue API `/api/runtime-config`, Profil liefert `nachteilsausgleich` + `levelUnlocks`, drei Modi mit Override |
| [output-api.md](v2-modules/_spec/output-api.md) | Lehrplan-Codes mit Land-Prefix, Klarnamen bestätigt, Level-Unlock-Auto-Update server-seitig |
| [telemetry-api.md](v2-modules/_spec/telemetry-api.md) | Heartbeat-Frequenz aus runtime-config (10–30s default), Stuck zentral konfiguriert |
| [delivery-format.md](v2-modules/_spec/delivery-format.md) | Hybrid-Konformitäts-Check (PHP+Headless), Versionierungs-Update-Logik (Patch auto / Major Atlas-Review) |
| [platform-standards.md](v2-modules/_spec/platform-standards.md) | API-Keys nur lokal, UI-Tokens strikt, Sound-Library Phase 2, Stimmen-Pool Atlas-gepflegt |
| [migration-from-v1.md](v2-modules/_spec/migration-from-v1.md) | Wellen-Reihenfolge bestätigt, V1 bleibt parallel, kein Daten-Bridge (cleaner Schnitt) |
| **NEU** [level-unlock-konzept.md](v2-modules/_spec/level-unlock-konzept.md) | Anhang: Drei Modi (frei / Auftrag / Nachteilsausgleich-Override), Auto-Unlock-Logik |

**Total**: 9 Files, 2026 Zeilen Spec.

### Plattform-Code (V2): neue Tabellen + APIs

DB-Schema in [v2-platform/db/init.sql](v2-platform/db/init.sql):
- **`platform_config_v2`** — 8 Default-Konfig-Einträge (Heartbeat, Token-TTL, Rate-Limits etc.) für Admin-Board-Tuning
- **`health_metrics_v2`** — Antwortzeit-Statistiken pro Endpoint (Vorbereitung für Phase-2-Auto-Tuning)
- **`class_assignments_v2`** — V2-Aufträge mit `difficulty` + `custom_params` (V3-Vorbereitung)
- **`student_level_unlock_v2`** — pro Schüler*in × Modul (`highest_unlocked_level`, `highest_completed_level`, `best_score_per_level`, `attempts_per_level`)
- **`students.nachteilsausgleich`** — neue Spalte additiv

APIs:
- **NEU**: [v2-platform/php/api/runtime-config.php](v2-platform/php/api/runtime-config.php) + Mock — liefert Plattform-Tuning-Werte
- **erweitert**: `/api/student/me` liefert jetzt `nachteilsausgleich` + `levelUnlocks` (Map pro Modul)
- **Mock**: dritte Test-Schüler*in Sofia hat `nachteilsausgleich = true` für Tests

### Globale Begriffsänderung: Lehrkraft → Lehrperson

Alle V2-Spec-Files, Plattform-Code, Mock-Code, Briefings und Hallo-Welt-Modul auf „Lehrperson" umgestellt (Sed-Lauf über bekannte Pfade). V1-Code unverändert — alte Begriffe bleiben dort.

Plus neue Memory-Datei [feedback_lehrperson_nicht_lehrkraft.md](memory/feedback_lehrperson_nicht_lehrkraft.md) — Konvention dauerhaft festgehalten.

## Was als nächstes ansteht

Aus deinem Auftragsstapel, Reihenfolge nach Sinn:

1. **Konformitäts-Check-Skript** bauen (PHP + Headless-Chrome) — damit Modul-Instanzen ihre Lieferungen selbst prüfen können bevor sie an Atlas schicken
2. **Telemetry-Client-JS-Lib** (`v2-platform/lib/telemetry-client.js`) — nimmt Modul-Instanzen Boilerplate ab (Heartbeat-Loop, Token-Refresh, Stuck-Detection)
3. **V2-Cockpit + Login** — Lehrer-Live-Dashboard, Schüler-Cockpit mit Lerngeschichte, Modul-Auswahl, Admin-Board mit Plattform-Config-Sektion
4. **Meister informieren** — sobald V2-Cockpit substantiv steht, briefen für `/v2beta`-Apache-Alias

Reihenfolge ist mein Vorschlag — du entscheidest. Mein Tipp: 1 + 2 sind klein und konkret (jeweils paar Stunden), 3 ist groß (Tage), 4 ist nur eine Inbox-Mail.

## Offene Detail-Fragen für später

Drei Punkte, die jetzt entschieden sind, aber bei der Implementierung wahrscheinlich nochmal auftauchen:

- **Admin-Board-Konfig-UI**: ich integriere sie ins bestehende V1-Admin-Board oder baue V2-eigenes Admin? V1 hat schon das `admin-fields.json`-Pattern, das wir wiederverwenden.
- **Konformitäts-Check Headless-Chrome**: brauchen wir eine Node-Dependency oder können wir Playwright als Standalone-Binary nutzen? Ich tendiere zu Node-frei.
- **Token-Auto-Refresh-Logik**: in der Telemetry-Client-Lib einbauen — Modul muss nichts machen. Lib pollt 5min vor Ablauf einen Refresh-Endpoint und tauscht Token transparent.

Diese Punkte muss ich nicht heute klären — kommt bei der Implementierung.

## Test der Live-Mock (immer noch wie gestern)

Lokal: `http://localhost/geograsim/v2-modules/hallo-welt/tests/mock-platform.html` — funktioniert weiter, plus Sofia (Student 44) ist jetzt mit `nachteilsausgleich = true` markiert.

— Atlas, 2026-05-17