geograsim/App/sims/_inbox/logistik/2026-04-19-2315-kickoff-briefing.md

von, an, datum, status, betrifft

von	an	datum	status	betrifft
atlas	logistik	2026-04-19 23:15	neu	Kickoff-Briefing — Simulation „Logistik Europa"

Willkommen, Logistik-Instanz

Thomas baut mit dir das anspruchsvollste Modul der Plattform: eine europaweite Logistik-Simulation auf OSM-Basis. Ein ausführliches Pflichtenheft (64 Seiten, extern verfasst) liegt vor. Dieses Briefing übersetzt es in unsere Arbeitsweise — unsere Plattform-Konventionen haben Vorrang vor dem Pflichtenheft.

---

1. Deine Rolle

Du bist die Logistik-Instanz. Du besitzt:

• App/sims/logistik/ (Gerüst wird von Atlas noch angelegt)
• App/pages/logistik.php, App/pages/modul-logistik.php
• App/php/api/logistik-*.php (neue API-Endpunkte)
• Ggf. neue MySQL-Tabellen unter Präfix lg_… (Vorschläge erst mit Atlas abstimmen — mehr dazu unten)

Atlas bleibt Plattform-Zentrale. Anfragen dafür schickst du an _inbox/zentrale/.

---

2. Pflichtenheft-Referenz

Datei: .humanInput/Pflichtenheft Geo Gra Sim Logistik Europa.pdf

Wichtig: Das Dokument wurde extern verfasst und an mehreren Stellen in Konflikt zu unserem bestehenden System. Ich habe es durchgearbeitet und die Übersetzungen in die folgenden Abschnitte geschrieben.

Besonders wertvoll aus dem Pflichtenheft:

• Kap 3.4 — 28 didaktische Kernziele (exakte Vorlage für Lehrplan-Anker)
• Kap 13 — Level-Vereinfachungsstrategie (Level 1 / 2 / 3 / spätere)
• Kap 14 — UI-Zonen (Karte + Aufträge + Fahrzeuge + Status + Ereignisse + Hilfe)
• Kap 17 — Datenmodell-Vorschläge (als Inspiration, nicht als Pflicht)
• Kap 19 — Balancing-Grundsätze
• Kap 34 — Testfälle (fachlich, didaktisch, technisch)
• Kap 42–51 — Enums, Interfaces, Tick-Pipeline, Bewegungslogik, Events
• Kap 65 — konkrete Parameterwerte (verbindliche Startwerte; siehe unten)

---

3. Plattform-Konventionen haben Vorrang

❌ Nicht übernehmen (Pflichtenheft-Vorschläge, die unserem System widersprechen)

Pflichtenheft	Unsere Entscheidung
TypeScript (Kap 40.2, 43, 47)	Vanilla JS mit JSDoc-Types wie Klima/Fluss. Keine Build-Pipeline für dieses Modul.
Monorepo /geograsim/packages/* (Kap 41)	Flache Struktur wie bestehende Module: App/sims/logistik/, App/pages/, App/php/api/.
Redux Toolkit / Vue Pinia (Kap 53.2)	Einfache Zustandsobjekte nach Klima-Vorbild (window.LogistikEngine).
Node.js-Backend (Kap 7.3)	PHP 8 + PDO (MySQL utf8mb4). Wie alle anderen Module.
25 eigene DB-Tabellen (Kap 17)	Nur das persistieren, was wirklich persistiert werden muss. Vieles läuft als JSON in bestehenden Tabellen (game_levels.params, game_saves.save_data) oder als Seed-Dateien unter App/assets/data/.
KI zur Laufzeit (Kap 16, 20)	Keine KI im Produkt. Text-/Bild-/Audio-Generierung nur in der Entwicklung (wie bei Glossar-Bildern), nicht zur Laufzeit. Grund: Kosten, Latenz, Datenschutz, deterministisches Balancing.
„Collections" / NoSQL-Wording (Kap 17)	MySQL, relational, normalisiert.

🔧 Anpassen (inhaltlich übernehmen, in unsere Formate übersetzen)

• Savegame-Format (Kap 54) → unsere Tabelle game_saves (Feld save_data als JSON-Text, save_version). Kein eigenes Savegame-System bauen.
• API-Design (Kap 55) → als PHP-Endpunkte App/php/api/logistik-contracts.php, logistik-sessions.php, logistik-routes.php, logistik-hints.php, logistik-minigame.php. Kein REST-Framework, einfach PHP-Skripte mit JSON-Responses (Pattern wie App/php/api/glossar.php).
• State Machine (Kap 44) → einfache String-Konstanten in JS. Die Zustände INIT/LOADING/READY/PLANNING/RUNNING/PAUSED_BY_EVENT/PAUSED_BY_ARRIVAL/MINIGAME/LEVEL_SUCCESS/LEVEL_FAILED/SAVING/ERROR sind aber gut durchdacht — übernimm sie als LogistikEngine.STATE Enum.
• Routing-Adapter (Kap 47) → Interface OK, aber erste Implementierung: internes vereinfachtes Modell. Luftlinie * Umwegfaktor oder vordefinierte Polylines zwischen Hauptknoten. OSRM/GraphHopper erst, wenn die Kern-Simulation steht.
• Bahnnetz-Modell (Kap 48, 65.8) → als JSON-Datei App/assets/data/lg-railnet.json mit nodes[] und edges[]. Dijkstra in Vanilla JS implementieren — ist ~50 Zeilen.
• Tick-System (Kap 45) → clientseitiger requestAnimationFrame-Loop mit deltaMs → simulatedMinutes Umrechnung. Nicht serverseitig. Thomas' Geräte sind Schulen-Geräte, Server-Ticks sind Overkill.

✅ Direkt übernehmen

• Leaflet + OSM-Tiles (wie Heli)
• 28 Kompetenzziele aus Kap 3.4 als Lehrplan-Basis
• Hilfestufen-System (Kap 10.3): BLINK_EXACT / SHOW_COUNTRY / SHOW_REGION / DISTANCE_FEEDBACK / NONE
• Konkrete Parameterwerte aus Kap 65 (siehe Balance-Kapitel unten)
• Level-Progression (Kap 13): Level 1 / 2 / 3 / spätere
• Teststrategie (Kap 34, 61)
• Offline-Fallback (Kap 25)

---

4. Pflicht-Konventionen unserer Plattform

4a — Sprachregel: keine Spielsprache

Nie „spielen", „Spiel", „Spieler:in", „Game Over", „Punkte sammeln". Stattdessen „arbeiten mit", „Simulation", „Bearbeiter:in", „Durchgang beendet", „Kennzahl". Bildungstheoretische Grundlage: Wygotski, Lernarbeit statt Spiel. Das Pflichtenheft verwendet oft „Spiel/Spieler" — das musst du in allen UI-Texten ersetzen. Interne Variablennamen (gameState, GameState, game.tick) dürfen bleiben.

Siehe App/docs/module-interface.md Abschnitt 4a.

4b — Leichte Sprache

Per Schüler:in-Flag in DB. Fallback-Pattern pickText(). Wichtig: Auftragstexte, Hilfe, Fehlermeldungen, Event-Meldungen müssen eine Leichte-Sprache-Variante haben.

4c — iPad als Referenzgerät

1180×820 Landscape. Touch-Ziele min 36 px, touch-action: manipulation, kein Hover-Kleber (@media (hover: hover) für Desktop-only). Leaflet Touch-Support aktivieren.

7b — Autosave-Pflicht

Alle state.relevanten Zustandsübergänge → Autosave. Thomas hat explizit nach persistenter Session gefragt. Pattern: lokal in localStorage + bei Session optional an Server. Siehe App/docs/module-interface.md.

Inbox-Check vor „Fertig"

Bevor du „fertig" meldest: _inbox/logistik/ prüfen. Sonst gehen Antworten verloren.

Commit-Format

Logistik: <Kurzbeschreibung> — z.B. Logistik: Tick-Engine + Fahrzeug-Bewegung.

_status.md

Lege dir eines an unter App/sims/_inbox/logistik/_status.md: Rolle, aktueller Stand, offene Aufgaben, Blocker. Aktualisiere nach jeder Phase.

Keine KI im Produkt

(Siehe oben.) Wenn du Auftragstexte, Event-Meldungen, Hilfetexte vorgenerieren willst — mach das in der Entwicklung, commite die generierten Texte als statische Dateien (JSON/Content-Tabelle).

---

5. Balance-First-Approach (WICHTIGSTER Punkt)

Thomas' explizite Vorgabe: Die Simulation muss von Anfang an balanciert sein.

• Level 1 (Lernen): komfortabel zu schaffen, auch bei Anfänger-Fehlern. Ziel: >90 % der 13-15jährigen Schüler:innen schließen Level 1 im ersten Durchgang positiv ab.
• Level 3 (Profi): knapp zu schaffen. Jede Fehlentscheidung (Leerfahrt, falsches Fahrzeug, Hilfe-Überbeanspruchung) spürbar. Ziel: ~50 % schaffen es mit positivem Kontostand im ersten Versuch, ~90 % im dritten.

5.1 — Bevor du ein Feature baust: Balance-Matrix

Erster Schritt in Phase 0 (vor jeder Implementierung):

Erstelle App/sims/logistik/balance-matrix.md mit:

Parameter	Level 1	Level 2	Level 3	Quelle (Pflichtenheft)
Startbudget (€)	8.000	5.000	2.500	(deine Schätzung, testen!)
Anzahl Aufträge parallel	1	3	6	Kap 13.3
Anzahl Fahrzeuge	1	3	5	Kap 13.3
Fristlänge-Multiplikator	*1.5	*1.2	*1.0	Kap 65.6
Hilfestufe	BLINK_EXACT	SHOW_REGION	NONE	Kap 10.3
Event-Wahrscheinlichkeit (%/h)	2	5	10	Kap 65.5 (halbiert für L1)
Verspätungsstrafe (% Wert/h)	10	20	30	Kap 65.2
Miete Fahrzeug (€/Tag)	0	200	500	Kap 65.2
Min Ziel-Erlös	3.000 €	10.000 €	20.000 €	eigene Schätzung
Zeitlimit (Spielstunden)	24	48	72	eigene Schätzung

Das ist ein Vorschlag als Startpunkt. Testen, justieren, ins game_levels.params persistieren.

5.2 — Konkrete Pflichtwerte aus Kap 65 (verbindlich)

Fahrzeuge:

• Kleiner LKW: 70 km/h, 1 Container, 1.20 €/km, 25 €/h, Lade-/Entladezeit 5 min
• Großer LKW: 60 km/h, 3 Container, 2.50 €/km, 45 €/h, Lade-/Entladezeit 8 min
• Zug: 90 km/h, 20 Container, 8 €/km, 150 €/h, Lade-/Entladezeit 20 min pro 10er-Block

Aufträge:

• Standard: Basis 1.000 €, 1-3 Container, Frist = Distanz/60 * 1.5 Stunden
• Eilauftrag: Basis 1.500 €, Frist = Distanz/70

Bonus/Malus:

• Pünktlich: +10 %
• Optimal (keine Leerfahrt): +20 %
• Strafe pro Stunde Verspätung: 20 % vom Auftragswert

Event-Wahrscheinlichkeiten (pro Stunde):

• Unfall: 5 % (Geschwindigkeit * 0.5)
• Schnee in Alpen: 10 % (Geschwindigkeit * 0.7)
• Hafenüberlastung: 8 % (Ladezeit * 1.5)

Zeit-Skala:

• 1 Tick = 250 ms Echtzeit
• 1× = 1 min Spielzeit / s Echtzeit
• 4× = 4 min/s, 8× = 8 min/s

Referenz-Distanzen (zum Testen der Routing-Logik):

• Wien → Salzburg: 300 km (~4.5 h LKW)
• Wien → Hamburg: 950 km (~14 h LKW)
• Hamburg → München: 800 km (~12 h LKW)
• Rotterdam → Wien: 1.100 km (~16 h LKW)

Bahnnetz-Kernknoten (Kap 65.8): Wien, München, Hamburg, Rotterdam, Paris

• Wien–München: 400 km
• München–Hamburg: 800 km
• Hamburg–Rotterdam: 500 km

5.3 — Regressionstests-Pflicht vor neuen Features

In App/sims/logistik/tests/ lege Regressionstests an (Vanilla JS, keine Test-Runner-Pipeline — einfache Self-Tests via <script> in einer test.html). Jedes neue Feature kommt mit Test.

Pflichttests von Anfang an:

1. Fahrkosten-Formel: distanz=300, costPerKm=1.2, fahrzeit=4.5, costPerHour=25 → 472.50 €
2. Route-Interpolation: Fahrzeug bei 50 % Progress steht auf Mittelpunkt der Polyline
3. Strafkosten: Auftragswert 1.000 €, Verspätung 2 h → 400 € Abzug
4. Bonus-Kombi: Pünktlich + optimal → +30 %
5. Event-Auswirkung: Unfall während Fahrt halbiert Geschwindigkeit für Event-Dauer
6. Savegame-Roundtrip: Zustand X → serialisieren → deserialisieren → Zustand X (deep-equal)
7. Bahnrouting Dijkstra: Wien → Hamburg über München → Hamburg = 1.200 km

Seeded-Random-Tests: Gleicher Seed → gleicher Session-Verlauf. Sonst ist Balancing nicht reproduzierbar messbar.

5.4 — Automatisierbare Balance-Tests

Für das eigentliche Balancing: Bau einen Headless-Runner, der einen Level einmal spielen kann (deterministisch, ohne UI) und am Ende Kennzahlen ausspuckt:

runLevel(levelId, seed, strategy) → {
  successful: boolean,
  endBalance: number,
  completedContracts: number,
  lateDeliveries: number,
  durationHours: number,
  hintUsages: number
}

Mit 3 Strategien: naive (erstes Fahrzeug, nächster Auftrag), greedy (höchster Wert zuerst), optimal (Orakel, best case). Wenn optimal Level 3 gerade so schafft und naive Level 1 ohne Probleme schafft, hast du Balance.

---

6. Phasenplan (inkrementell)

Phase 0 — Balance-Matrix + Test-Infrastruktur (KEIN Feature-Code!)

• balance-matrix.md mit Werten pro Level
• test.html mit Regressionstest-Harness (in Vanilla JS)
• Die oben genannten 7 Pflichttests implementiert (auch wenn die zu testenden Funktionen noch Stubs sind)
• Headless-Runner-Skelett
• → Atlas-Review, bevor Phase 1 startet

Phase 1 — Fundament

• engine.js mit State Machine + Tick-Loop
• Seed-Daten laden: lg-locations.json (~30 Städte + 5 Häfen + 3 Bahnterminals)
• Leaflet-Karte rendern, Marker platzieren
• Keine Aufträge, keine Fahrzeuge — nur Karte + Daten
• Pflichttest: seeded-Karte lädt reproduzierbar

Phase 2 — Kern-Loop (Level 1 spielbar)

• 1 Fahrzeug, 1 Auftrag, gerader-Luftlinie-Route, Tick-Bewegung
• Start/Ziel auswählen, Fahrt starten, Ankunft erkennen, Erlös buchen
• Minimalste UI: Auftragskarte + Fahrzeugpanel + Status + Zeit-Controls
• Level 1 muss hier spielbar sein — nicht mehr, nicht weniger
• → Thomas testet live, bevor Phase 3 startet

Phase 3 — Kostenmodell + Mehrfahrzeuge + mehr Aufträge

• Alle 3 Fahrzeugtypen
• Kostenformel (Kap 65)
• Mehrere Aufträge parallel
• Level 2 wird spielbar

Phase 4 — Bahn + Häfen + Intermodal

• Bahnnetz-Dijkstra (5 Knoten, 3 Kanten)
• Häfen mit Container-Ankunft als Auftragsquelle
• Intermodale Aufträge (Leg1 LKW → Leg2 Zug → Leg3 LKW)
• Verladezeiten
• Level 3 wird spielbar

Phase 5 — Hilfestufen + Events

• Hilfesystem (5 Stufen)
• Event-Engine mit deterministischer Seed
• Event-Auswirkungen (Speed/Cost/Block)

Phase 6 — Minigames + Sprachregel-Check + Leichte Sprache

• 1 Minigame (An-die-Rampe-Einparken) als erstes
• Volle 4a/4b-Durchsicht aller UI-Texte
• Glossar-Anfrage für Logistik-Begriffe (Kontainer, Intermodal, Umschlag, Luftlinie, Dijkstra-anschaulich)

Phase 7 — Lehrkraftmodus + Analytics + Polish

• Lehrkraft kann Level konfigurieren, Hilfen schalten
• Analytics-Dashboard mit Kennzahlen aus Kap 23.2

---

7. Datenmodell — unser Vorschlag

Statt 25 neue Tabellen: nur das persistieren, was wirklich persistiert werden muss.

Neue MySQL-Tabellen (Vorschlag — mit Atlas abstimmen)

-- Seed-Daten (Orte, Fahrzeugtypen, Bahnnetz) — kann initial auch als JSON-Datei
-- unter App/assets/data/ liegen und nur falls nötig später in DB migriert werden.

CREATE TABLE lg_locations (
  id VARCHAR(32) PRIMARY KEY,
  country_code CHAR(2),
  region_id VARCHAR(32),
  name VARCHAR(100),
  type ENUM('CAPITAL','CITY','PORT','TERMINAL','INDUSTRY','CUSTOMER'),
  lat DECIMAL(8,5),
  lon DECIMAL(8,5),
  osm_id VARCHAR(32) NULL,
  visible_from_level TINYINT,
  didactic_difficulty TINYINT,
  meta_json JSON
);

-- Aktive Laufzeit-Daten
CREATE TABLE lg_contracts_log (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  session_id CHAR(36),
  level_id INT UNSIGNED,
  contract_code VARCHAR(32),
  assigned_vehicle VARCHAR(32),
  state VARCHAR(16),
  final_balance INT,
  late_minutes INT,
  hint_usages INT,
  completed_at TIMESTAMP
  -- für Lehrkraft-Analytics, nicht für Spielstand
);

Bestehende Tabellen nutzen

• module_info: Eintrag logistik (Atlas legt an)
• game_levels: Einträge Level 1-3 mit params JSON (enthält Balance-Matrix)
• game_saves: save_data JSON = voller GameState
• student_sessions, students: unverändert

Was NICHT in DB, sondern als JSON-Seed unter App/assets/data/

• Länder, Regionen (selten änderbar, sinnvoll als Content-File)
• Bahnnetz-Knoten/Kanten (5 Knoten — DB wäre Overkill)
• Fahrzeugtypen (3 Typen — Overkill)
• Warentypen (8 Kategorien — Overkill)
• Event-Templates
• Auftrags-Templates
• Minigame-Definitionen

Regel: Wenn es <50 Einträge sind und selten geändert wird → JSON-Datei. Wenn Admin-UI nötig ist oder Änderungen häufig → DB.

---

8. UI-Layout (mit Heli-Kompromiss-Note von Thomas)

Thomas' Beobachtung: Heli-Kartenansicht ist ein Kompromiss, mehr Steuerung wäre schön. Für Logistik planen wir deshalb Karte als Canvas-Zentrum, aber mit reichhaltigem Drumherum (Kap 14.2):

┌────────────────────────────────────────────────────────────┐
│ Header (Logo · Speed · Save/Load · Lehrplan · 🏠)         │
├───────────┬──────────────────────────────────┬─────────────┤
│           │                                  │             │
│ Aufträge  │                                  │  Fahrzeuge  │
│ (Panel    │     Europa-Karte (Leaflet)       │  (Panel     │
│  links)   │                                  │   rechts)   │
│           │  • Marker: Städte, Häfen,        │             │
│           │    Terminals, Fahrzeuge          │             │
│           │  • Layer: Länder, Bahnlinien,    │             │
│           │    Routen                        │             │
├───────────┴──────────────────────────────────┴─────────────┤
│ Status-Leiste: Zeit · Kontostand · Score · Ereignisfenster │
├────────────────────────────────────────────────────────────┤
│ Hilfebereich / Didaktikfenster (einklappbar)               │
└────────────────────────────────────────────────────────────┘

Auf iPad Landscape (1180×820):

• Auftragsliste 240 px
• Karte füllt den Rest
• Fahrzeugliste 240 px
• Status-Leiste 56 px hoch
• Didaktikfenster ausblendbar → 36 px hoch im eingeklappten Zustand

Design-System-Klassen (sind alle schon da): .ggs-header, .ggs-btn, .ggs-card, .ggs-badge, .ggs-level-grid, .ggs-level-card, .ggs-graph-card, .ggs-music, Glossar-Popup-System. Keine neuen Klassen ohne Abstimmung mit Atlas.

---

9. Was Atlas als Vorarbeit macht (parallel)

Nach deiner Empfangsbestätigung baue ich das Gerüst:

1. module_info-Eintrag logistik (Status: in_entwicklung)
2. Landing-Card auf App/index.html (als LOCKED-Card mit Platzhalter-Detailseite)
3. App/pages/modul-logistik.php Platzhalter-Detailseite
4. App/pages/logistik.php Wrapper-Skelett
5. App/sims/logistik/game.html Skelett nach Template
6. App/sims/logistik/engine.js Skelett (leere State Machine)
7. App/sims/logistik/test.html Test-Harness-Skelett
8. Leere Seed-Dateien unter App/assets/data/lg-*.json

Dauer: ~2 Sessions. Dann ist dein Arbeitsplatz bereit.

---

10. Komplexitäts-Einschätzung (Atlas)

Dies ist das anspruchsvollste Modul der Plattform. Zum Vergleich:

Modul	Komplexität	Sessions (geschätzt)
Fluss	mittel	~10
Klima 2D	mittel-hoch	~15
Klima 3D	hoch	~12 (nach 2D-Engine-Basis)
Heli	hoch	~20
Logistik Europa	sehr hoch	30–50

Gründe:

• 3 Fahrzeugtypen mit getrennter Routing-Logik (Straße vs. Bahn)
• Wirtschaftsmodell mit vielen Formel-Bestandteilen
• Tick-basierte Simulation mit Balancing über Seeds
• Intermodale Aufträge (Ketten aus bis zu 3 Legs)
• Bahn-Dijkstra
• Mindestens 4 Minigames
• Event-Engine mit deterministischer Reproduzierbarkeit
• Lehrkraft-Konfiguration
• Europa-weite Geografie statt regional

Thomas hat in früheren Diskussionen 20–30 Sessions geschätzt — das war vor vollständigem Pflichtenheft-Lesen. Mit den 64 Seiten Anforderungen ist 30–50 realistischer. Das soll dich aber nicht bremsen, sondern Phasen sauber abschneiden lassen.

---

11. Deine ersten Schritte

1. Empfangsbestätigung + erste Einschätzung an _inbox/zentrale/
2. _inbox/logistik/_status.md anlegen
3. App/docs/module-interface.md Abschnitte 4a/b/c, 7b lesen
4. Pflichtenheft PDF lesen (.humanInput/Pflichtenheft Geo Gra Sim Logistik Europa.pdf) — 64 Seiten, aber die Hälfte ist Architektur-Philosophie, die durch mein Briefing schon übersetzt ist. Fokus auf Kap 3.4, 13, 14, 19, 34, 65.
5. Phase 0 starten: balance-matrix.md + test.html-Harness. NICHT mit Feature-Code anfangen.
6. Sobald Balance-Matrix + Test-Harness stehen → Atlas-Review in _inbox/zentrale/ anfordern.

---

12. Offene Fragen, die Thomas oder Atlas klären müssen

• Lehrplan-Anker: Die 28 didaktischen Kernziele aus Kap 3.4 sollen in unser Lehrplan-System (App/php/api/lehrplan.php). Lehrplan-Instanz bekommt von mir eine Anfrage, sobald Seed-Daten stehen.
• Routing-Strategie Phase 2: Nur Luftlinie * 1.3? Oder direkt eine vereinfachte Autobahn-Polyline für die 20 wichtigsten Strecken hand- gepflegt? Schlage beides vor, lass Thomas wählen.
• Admin-UI für Level-Konfiguration: Bauen wir eine Erweiterung von admin-levels.html oder separat? Das klären wir, wenn Phase 7 ansteht.

---

13. Bestätigen

• status: gelesen
• Empfangsbestätigung + Rückfragen (wenn welche) an _inbox/zentrale/
• Nach Bestätigung baut Atlas das Gerüst. Dann loslegen mit Phase 0.

Viel Erfolg. Das wird ein Brocken, aber ein wichtiges Modul.

— Atlas