geograsim/v2-modules/_spec/module-manifest.md

Vertrag 1: Module Manifest

Jedes V2-Modul deklariert sich über eine manifest.json im Modul-Wurzelordner. Atlas liest diese Datei beim Integrieren und beim Update.

Pflichtfelder

{
  "specVersion": "1.0",
  "slug": "logistik",
  "displayName": "Logistik Europa",
  "displayNameEasy": "Lkw und Bahn in Europa",
  "version": "2.0.0",
  "icon": "🚚",
  "shortDescription": "Plane Lkw- und Bahn-Aufträge in Europa.",
  "shortDescriptionEasy": "Du planst, wie Sachen mit dem Lkw oder der Bahn fahren.",
  "longDescription": "...",
  "longDescriptionEasy": "...",
  "estimatedDurationMin": 25,
  "difficultyLevels": [
    { "id": "L1", "label": "Einsteiger", "labelEasy": "Leicht" },
    { "id": "L2", "label": "Fortgeschritten", "labelEasy": "Schwer" }
  ],
  "supportedLanguages": ["de-AT-standard", "de-AT-easy"],
  "entryHtml": "public/game.html",
  "cardImage": "public/assets/card.png",
  "screenshots": [
    "public/assets/screenshot-01.png",
    "public/assets/screenshot-02.png"
  ],
  "lehrplanAnker": [
    "AT-GW-1.4.2",
    "AT-GW-2.1.1",
    "AT-GW-3.5.4"
  ],
  "glossarSchwerpunkte": [
    "logistik",
    "intermodalverkehr",
    "container",
    "transeuropaeische-netzwerke"
  ],
  "dbTables": [
    "m_logistik_orders",
    "m_logistik_routes",
    "m_logistik_save"
  ],
  "moduleEndpoints": [
    "/v2beta/sims/logistik/api/orders.php",
    "/v2beta/sims/logistik/api/routes.php"
  ],
  "telemetryMilestones": [
    { "id": "first-order-accepted", "label": "Erster Auftrag angenommen" },
    { "id": "level-1-cleared", "label": "Level 1 geschafft" },
    { "id": "all-orders-of-day", "label": "Tag erfolgreich beendet" }
  ],
  "sharedAssets": {
    "cities": ["wien", "muenchen", "rotterdam"],
    "icons": ["sound-on", "sound-off", "pause", "check", "cross"],
    "bg-music": ["fjord-calm"]
  },
  "adminFieldsFile": "admin-fields.json",
  "maintainerInstance": "logistik",
  "lastUpdated": "2026-06-12"
}

Feld-Erklärungen

Identität

• specVersion — gegen welche Spec-Version das Modul gebaut wurde (Major.Minor)
• slug — Modul-Identifier, lowercase, alphanumerisch + Bindestrich, einmalig im System
• version — semver des Moduls selbst (Modul-Iteration, nicht Spec)
• displayName / displayNameEasy — Standard- und Easy-Sprache-Titel
• icon — Emoji für Cockpit-Karte (Fallback wenn Card-Bild fehlt)

Beschreibungen (alle vier Felder Pflicht)

• shortDescription (1 Satz, ~60 Zeichen) — für Karten-Vorschau
• shortDescriptionEasy — Easy-Sprache-Variante
• longDescription (3–5 Sätze) — für Modul-Detail-Seite
• longDescriptionEasy — Easy-Sprache-Variante

Pädagogische Metadaten

• estimatedDurationMin — Richtwert für Lehrperson-Planung
• difficultyLevels — Array, mind. 1 Level
• lehrplanAnker — Codes aus einem lokalisierten Lehrplan-Pool, mit Land-Prefix. Heute nur AT (AT-GW-1.4.2), später auch DE (DE-NRW-GEO-7-3) oder CH (CH-LP21-RZG-2.2). Plattform validiert gegen lehrplan_anchors_v2-Tabelle. Multi-Land-fähig im Schema, aber heute nur AT gefüllt — siehe platform-standards.md.
• glossarSchwerpunkte — Schlüssel-Begriffe (max ~10), die das Modul didaktisch wirklich vermitteln will. Plattform nutzt das fürs Lehrplan-Mapping und die Auswertung („Dieses Modul lehrt: Klimazone, Anbaugrenze"). Tooltips für alle anderen Fachbegriffe holt das Modul on-demand via /api/glossary/<slug> — KEINE Vorab-Deklaration nötig, beliebig viele Begriffe möglich.

Technik

• supportedLanguages — Locale-Codes nach <sprache>-<land>-<variante>. Heute Pflicht: de-AT-standard und de-AT-easy. Spätere Erweiterungen (de-DE-standard, de-DE-easy, de-CH-standard) ohne Schema-Change möglich. Easy-Sprache ist immer Pflicht für jede unterstützte Sprache (Inklusion).
• entryHtml — Pfad zum Entry-Point relativ zum Modul-Wurzelordner
• cardImage / screenshots — Asset-Pfade für Cockpit-Anzeige
• dbTables — alle eigenen Tabellen, Pflicht-Prefix m_<slug>_
• moduleEndpoints — eigene PHP-Endpoints (nur für Modul-interne Logik, NICHT für User/Auth)

Telemetry-Vorab-Deklaration

• telemetryMilestones — Liste aller Milestone-IDs, die das Modul emittieren wird. Plattform nutzt das fürs Lehrer-Dashboard (Vorschau „erwartete Schritte"). Erweiterung erlaubt, aber nur über Spec-Update.

Gemeinsame Ressourcen (sharedAssets)

Module deklarieren, welche Plattform-Pool-Assets sie nutzen (Stadt- Bilder, Icons, Glossar-Bilder, Hintergrundmusik, UI-Sounds). Atlas pflegt die Pools unter v2-platform/assets/shared/<kategorie>/. Modul verlinkt im Code via URL /v2beta/assets/shared/<kategorie>/<slug>.<ext>.

Vorteil: jedes Asset wird nur einmal generiert (Stilkonsistenz + Kosten + Lizenzklarheit). Konformitäts-Check prüft, dass alle deklarierten Assets im Pool existieren.

Wenn ein Asset noch nicht im Pool ist: Modul-Instanz pingt Atlas via Inbox (_inbox/zentrale/), Atlas generiert oder beschafft das Asset, committet in den Pool und antwortet mit URL.

Pool-Kategorien siehe platform-standards.md § 11.

Admin-Konfigurierbarkeit (Pflicht)

• adminFieldsFile — Pfad zur admin-fields.json im Modul-Wurzelordner (relativ). Definiert das Schema der Modul-eigenen Tuning-Parameter (Startbudget, Zeitlimit, Hilfestufe etc.) für das Admin-Board. Werte liegen in der DB (module_params_v2), Schema im Modul.

  Beispiel siehe App/sims/logistik/admin-fields.json (V1). Struktur: Gruppen mit Feldern (type: number/enum/boolean/text, min/max/default, label + labelEasy, help-Text). Wenn dein Modul keine Tuning-Parameter braucht: leere Datei mit {"moduleId": "<slug>", "groups": []}.

Wartung

• maintainerInstance — welche Claude-Instanz das Modul betreut (für Inbox-Routing)
• lastUpdated — ISO-Datum

Validierung

Atlas prüft beim Lieferungs-Empfang:

1. JSON-Schema (Pflichtfelder vorhanden, Typen korrekt)
2. slug einmalig (nicht schon vergeben)
3. lehrplanAnker existieren in lehrplan_anchors_v2 (mit korrektem Land-Prefix)
4. glossarSchwerpunkte existieren in glossar und sind ≤ 10 Einträge
5. dbTables haben Pflicht-Prefix m_<slug>_
6. entryHtml existiert physisch im Lieferpaket
7. cardImage und alle screenshots existieren physisch
8. Für jede supportedLanguages-Variante existiert ein i18n-File (siehe delivery-format.md)

Bei Fehler: Lieferung wird abgewiesen, Modul-Instanz bekommt Fehler-Inbox-Mail mit Liste der Probleme.

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

• Glossar: glossarSchwerpunkte max ~10 im Manifest, alles weitere on-demand
• Multi-Locale: Schema heute schon mehrsprachig, gefüllt nur AT
• Lehrplan-Codes: mit Land-Prefix (AT-GW-...)
• Difficulty-Levels: frei definierbar pro Modul (keine starre Standardisierung — Module brauchen unterschiedliche Tiefe). Aber: Display-Reihenfolge ist Pflicht (Level mit Index 0 = leichteste, höchster Index = schwerste). Default-Pattern empfohlen: L1 (Einsteiger) / L2 (Fortgeschritten) / L3 (Profi).
• Maintainer-Instanz: Pflicht. Wechsel ist möglich durch Update des Feldes bei nächster Modul-Lieferung — der/die alte Maintainer dokumentiert die Übergabe in docs/HANDOVER.md.
• adminFieldsFile: Pflicht ab Spec v1.0. Auch wenn leer (Modul ohne Tuning-Parameter), muss die Datei vorhanden und valides JSON sein.