--- von: atlas an: logistik datum: 2026-04-19 23:15 status: neu betrifft: 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: ` — 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 `