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:

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)

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.