geograsim/v2-modules/_spec/delivery-format.md

# Vertrag 5: Delivery Format

Wie ein Modul-Paket aussehen muss, damit Atlas es integrieren kann.

## Verbindliche Ordnerstruktur

```
v2-modules/<slug>/
├── manifest.json                  ← Vertrag 1, Pflicht
├── README.md                      ← Überblick für Atlas + Modul-Dokumentation
├── CHANGELOG.md                   ← Pflicht ab Modul-Version 1.1.0
├── public/                        ← alles was im Browser ausgeliefert wird
│   ├── game.html                  ← Entry Point (Pfad in manifest.entryHtml)
│   ├── assets/
│   │   ├── card.png               ← Cockpit-Karten-Bild (manifest.cardImage)
│   │   ├── screenshot-01.png
│   │   ├── screenshot-02.png
│   │   ├── img/                   ← weitere Bilder
│   │   ├── audio/
│   │   ├── data/
│   │   └── ...
│   ├── js/
│   │   └── *.js                   ← Modul-eigenes JS
│   └── css/
│       └── *.css                  ← Modul-eigenes CSS
├── server/                        ← optional: Modul-eigene PHP-Endpoints
│   ├── api/
│   │   └── orders.php
│   └── lib/
│       └── helpers.php
├── db/
│   ├── migrations.sql             ← Pflicht: additive Schema-Änderungen
│   └── seed.sql                   ← optional: Initial-Daten für m_<slug>_*-Tabellen
├── tests/
│   ├── mock-platform.html         ← Pflicht: Standalone-Test mit Mock-Plattform
│   └── conformance-report.json    ← wird vom Konformitäts-Check generiert
└── docs/                          ← optional: Modul-spezifische Doku
    ├── architecture.md
    └── content-spec.md
```

## Pflicht-Files

| File | Zweck |
|---|---|
| `manifest.json` | Modul-Deklaration (Vertrag 1) |
| `README.md` | Was macht das Modul, wie wird es bedient, bekannte Probleme |
| `public/game.html` (oder anderer Entry) | Browser-Einstieg |
| `public/assets/card.png` | Cockpit-Karten-Bild, mind. 800×600px |
| `db/migrations.sql` | Additive Schema-Änderungen (kann leer sein wenn keine eigenen Tabellen) |
| `tests/mock-platform.html` | Standalone-Lauf gegen Mock-API zum Selbsttest |

## Pflicht-Konventionen

### Pfade
- Alle Asset-Pfade in `manifest.json` und im Code **relativ** zum
  Modul-Wurzel (z.B. `public/assets/foo.png`, NICHT `/v2beta/sims/...`)
- Atlas rewrited Pfade beim Integrieren auf den richtigen Browser-Pfad

### Datenbank
- Alle eigenen Tabellen mit Prefix `m_<slug>_` (z.B. `m_logistik_orders`)
- `migrations.sql` muss **idempotent** sein (`CREATE TABLE IF NOT EXISTS`,
  `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`)
- Jede Tabelle hat Spalten `id`, `created_at`, `updated_at`,
  `created_by_version` (default `'v2'`)
- Foreign Keys nur auf platform-stable Tabellen (`students`, `classes`)
  oder auf eigene `m_<slug>_*`-Tabellen

### Sprache
- ALLE im Browser sichtbaren Texte als i18n-Key, mit mindestens
  `de-AT-standard` und `de-AT-easy` Variante
- Empfehlung: simples JSON-File `public/i18n/de-AT-standard.json` und
  `public/i18n/de-AT-easy.json`, dynamisch geladen je nach `lang`-Param
- Bei fehlender Easy-Variante: Atlas weist Lieferung ab

### Telemetry
- Alle in `manifest.telemetryMilestones` deklarierten Milestones
  müssen mindestens einmal in `tests/mock-platform.html` ausgelöst
  werden (Konformitäts-Check)

## Konformitäts-Check (vor Lieferung selbst durchführen)

Atlas stellt unter `v2-platform/tools/conformance-check/` ein
Skript bereit:

```bash
cd v2-modules/<slug>
php ../../v2-platform/tools/conformance-check/check.php
```

Prüft:
1. ✅ Manifest-Schema (alle Pflichtfelder, Typen, Werte)
2. ✅ Pflicht-Files vorhanden
3. ✅ Asset-Pfade in Manifest existieren physisch
4. ✅ DB-Migrations sind idempotent (Trockenlauf in Sandbox-DB)
5. ✅ Mock-Platform-Test läuft durch (Headless Chrome)
6. ✅ Alle deklarierten Milestones werden im Test ausgelöst
7. ✅ Easy-Sprache-i18n vorhanden
8. ✅ Telemetry-Endpoint wird mindestens 5× im Test aufgerufen
9. ✅ Result-POST mit allen Pflichtfeldern wird einmal aufgerufen
10. ✅ Keine `console.error` während Test
11. ✅ **A11y-Audit (axe-core)**: keine Critical/Serious-Issues
12. ✅ **Kontrast-Audit**: alle Text/Hintergrund ≥ 4.5:1
13. ✅ **Keyboard-Navigation**: alle interaktiven Elemente per Tab erreichbar
14. ✅ **Focus-Indikator**: kein `outline: none` ohne Ersatz
15. ✅ **Reduced-Motion-Test**: keine Auto-Animation bei `prefers-reduced-motion: reduce`
16. ✅ **High-Contrast-Test**: Modul rendert mit `body[data-high-contrast="true"]` alle Texte sichtbar
17. ✅ **Alt-Texte vorhanden** auf allen `<img>`
18. ✅ **Semantische Buttons**: keine `<div onclick>` für Aktionen

(Punkte 11–18 entsprechen [platform-standards.md § 9.13](platform-standards.md))

Schreibt `tests/conformance-report.json` mit Resultaten. Bei Erfolg:
„LIEFERBEREIT". Bei Fehler: Liste der Probleme.

## Lieferprozess

1. **Modul-Instanz** committed in `v2-modules/<slug>/` und führt
   Konformitäts-Check aus
2. **Modul-Instanz** schreibt Inbox-Mail an `_inbox/zentrale/` mit:
   - Slug
   - Version
   - Link zu `conformance-report.json`
   - Was neu/geändert ist gegenüber Vorgänger-Version
3. **Atlas** prüft Mail + Report:
   - Bei „LIEFERBEREIT": Atlas integriert (siehe unten)
   - Bei Fehlern: Atlas schickt Inbox-Antwort mit Liste, Modul-Instanz
     fixt und liefert neu
4. **Atlas Integration**:
   a. Kopiert `v2-modules/<slug>/` nach `/v2beta/sims/<slug>/` auf
      Lokal-Dev (XAMPP)
   b. Fährt `db/migrations.sql` gegen Lokal-DB
   c. Fährt `db/seed.sql` falls vorhanden
   d. Registriert Modul in `module_info_v2`-Tabelle
   e. Lehrplan-Anker und Glossar-Begriffe verknüpfen
   f. Manueller Smoke-Test im V2-Cockpit
   g. Wenn OK → Meister-Mail mit Deploy-Auftrag
5. **Meister** deployed `/v2beta/sims/<slug>/` auf Server, fährt
   Migration, OPcache-Reset, smoke-tested live
6. **Atlas** schickt Erfolgs-Inbox an Modul-Instanz + Thomas

## Versionierung von Modul-Lieferungen

- Erste Lieferung: `version: "2.0.0"`
- Bug-Fix: `2.0.1` (kein Manifest-Schema-Change)
- Feature/UI-Update: `2.1.0` (neue Milestones, neue Difficulty-Level)
- Breaking Change (z.B. Output-Schema-Anpassung): `3.0.0` (Atlas-Review
  besonders genau, evtl. Daten-Migration nötig)

CHANGELOG ab `2.1.0` Pflicht.

## Was im Lieferpaket NICHT drin sein darf

- ❌ V1-Code (`App/sims/<slug>/` bleibt unangerührt — keine Symlinks)
- ❌ Andere Modul-Verzeichnisse referenziert
- ❌ Plattform-Code referenziert (`v2-platform/*`)
- ❌ Sensible Daten (`.env`, Credentials, Schul-Echtdaten)
- ❌ `node_modules/`, `.git/`, IDE-Config-Files
- ❌ Großdateien > 50 MB (Audio/Video extern hosten)

## Beispiel: minimales lieferbares Modul

```
v2-modules/hallo-welt/
├── manifest.json
├── README.md
├── public/
│   ├── game.html              ← zeigt "Hallo!" und triggered 1 Heartbeat + 1 Milestone + 1 Result
│   └── assets/
│       └── card.png
├── db/
│   └── migrations.sql         ← leer (CREATE-Block kommentiert)
└── tests/
    └── mock-platform.html     ← lädt game.html, prüft 3 API-Calls
```

Atlas baut so ein Beispiel-Modul `hallo-welt/` als Referenz und
lebenden Test der Plattform.

## ✅ Geklärt mit Thomas (2026-05-17)

- **Konformitäts-Check Implementierung**: Hybrid — PHP für Schema/
  File-Checks (Manifest, Migrations, Pflicht-Files), Node/Headless-
  Chrome für Browser-Tests (A11y-axe, Telemetry-Events, i18n-Check).
  Beides aufrufbar als ein `php check.php` aus dem Modul-Wurzelordner.
- **Großdateien-Limit**: 50 MB Default, Ausnahmen pro Modul auf
  Antrag (Inbox an Atlas mit Begründung). Sonnensystem-Audio und
  Heli-Sounds bekommen Ausnahme — Atlas notiert das in
  `module_info_v2.notes`.
- **Lieferungs-Integration**:
  - **Patch-Updates (2.0.x)**: Auto-Check entscheidet, Atlas integriert
    automatisch wenn alle Prüfungen grün.
  - **Minor-Updates (2.x.0)**: Auto-Check entscheidet, Atlas
    benachrichtigt Thomas aber wartet nicht auf Freigabe.
  - **Major-Updates (x.0.0)**: Atlas-Review PFLICHT — Modul wird in
    Staging eingespielt, Atlas testet, Thomas-Freigabe nötig.
  - Modul-Instanz markiert die Update-Klasse im CHANGELOG.