# GeoGraSim V2-Plattform

**Status:** Skelett-Build (2026-05-16, Atlas-Nachtschicht)
**Lebensstand:** lokal, nicht deployed, kein V1-Eingriff

Dieses Verzeichnis enthält die V2-Plattform — Cockpit, Lehrer-/
Schüler-Bereich, API-Schicht, Telemetry-Aufnahme. Module liegen
parallel in `../v2-modules/<slug>/` und werden über die in
`../v2-modules/_spec/` definierte Schnittstelle integriert.

## Aufbau

```
v2-platform/
├── README.md                    ← du bist hier
├── .env.example                 ← Template für lokale .env.local
├── .gitignore
├── .htaccess                    ← Apache-Rewrite für /v2beta
├── db/
│   └── init.sql                 ← additive V2-Tabellen (IF NOT EXISTS)
├── php/
│   ├── config.php               ← Konstanten, Pfade, ENV-Loader
│   ├── bootstrap.php            ← Common-Includes, Error-Handling
│   ├── lib/
│   │   ├── db.php               ← PDO-Wrapper
│   │   ├── auth.php             ← Session-Token (JWT-light)
│   │   ├── response.php         ← JSON-Response-Helpers
│   │   └── validation.php       ← Request-Validation
│   └── api/
│       ├── student/me.php       ← GET — Profil
│       ├── module/state.php     ← GET + PUT — Resume-State
│       ├── result.php           ← POST — Endergebnis
│       ├── telemetry.php        ← POST — Heartbeat/Milestone/Stuck
│       ├── artifact.php         ← POST — Datei-Upload
│       ├── glossary.php         ← GET — Glossar-Eintrag
│       ├── lehrplan/anker.php   ← GET — Lehrplan-Anker
│       └── teacher/live-stream.php  ← Server-Sent-Events für Cockpit
├── assets/
│   ├── css/
│   │   └── design-system-v2.css ← V2-Tokens inkl. A11y / High-Contrast
│   └── js/
│       └── (kommt später)
├── lib/
│   └── telemetry-client.js      ← (kommt später) ESM-Bibliothek für Module
├── mock/                        ← Standalone-Mock für Modul-Entwicklung
└── tools/
    ├── conformance-check/       ← (kommt später) Modul-Validierung
    └── asset-gen/               ← (kommt später) DALL-E/ElevenLabs-Wrapper
```

## Lokal laufen lassen

1. `.env.example` nach `.env.local` kopieren und Werte eintragen
2. DB-Schema einspielen:
   ```bash
   mysql -u root -p geograsim < db/init.sql
   ```
   (Idempotent — kann mehrfach laufen, alle CREATE/ALTER mit IF NOT EXISTS)
3. XAMPP Apache starten
4. Im Browser: `http://localhost/geograsim/v2-platform/php/api/student/me`
   (sollte 401 ohne Token zurückgeben)

Für komplette V2-Integration siehe später kommende Doku zu Cockpit/Login.

## Was bereits funktioniert

- DB-Schema (alle V2-Tabellen)
- 8 API-Endpoints als funktionierende Skelette mit Auth, Validierung, Responses
- Mock-Plattform unter `mock/` für Modul-Entwicklung
- A11y-Tokens in design-system-v2.css

## Was fehlt (TODO)

- Cockpit-UIs (Lehrer/Schüler) — folgt nach Spec-Stable
- Login-Seite und Token-Issuance — derzeit Test-Token im Mock
- Konformitäts-Check-Skript
- Asset-Generierungs-Tools (DALL-E/ElevenLabs-Proxy)
- Telemetry-Client-JS-Bibliothek
- Live-Stream-Push für Lehrer-Dashboard (SSE)

## Wichtig für Mit-Atlas-Sessions

- **V1 NICHT anfassen**, kein Deploy ohne Thomas-Go
- DB-Änderungen sind additiv (`*_v2`-Suffix, IF NOT EXISTS)
- Authentifizierung läuft über Stateless-JWT-light (HMAC-SHA256), kein
  Session-State auf Plattform-Seite zwingend nötig
- Spec ist verbindlich — siehe `../v2-modules/_spec/`