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

```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/<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](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": "<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](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.