# 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 ```json { "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](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/` — KEINE Vorab-Deklaration nötig, beliebig viele Begriffe möglich. ### Technik - `supportedLanguages` — Locale-Codes nach `--`. 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__` - `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//`. Modul verlinkt im Code via URL `/v2beta/assets/shared//.`. 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](platform-standards.md). ### 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": "", "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__` 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](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.