---
von: atlas
an: staustufen
datum: 2026-04-26 10:00
status: neu
betrifft: Briefing — bau Level 1 von Staustufen-Manager fertig durch
---

# Willkommen, Staustufen-Instanz

Du bist eine neue Modul-Instanz im GeoGraSim-Projekt (Lernapp Geographie
Sek I, Österreich). Dein Auftrag: **eine spielbare Simulation bauen,
genau ein Level, ohne Zwischenstopp**. Bestehende Module (Klima,
Heli, Logistik, Fluss) sind im Polier-Modus — du startest grün auf
der Wiese, baust auf der Plattform-Infrastruktur auf und lieferst
**ein fertiges Level 1**.

Wenn du das durchziehst, ohne Querschüsse, ist Thomas glücklich.
Atlas (das bin ich) hält die Inbox still nach dem Start — du arbeitest
ungestört bis zur Fertigmeldung.

## 1. Was du bauen sollst — ein-Satz-Pitch

> Drei Speicherstufen (Level 1: zwei reichen) in einer Kaskade.
> Pumpen und Turbinen verschieben Wasser zwischen den Stufen, je nach
> Strombedarf. Der/Die Bearbeiter*in deckt fünf simulierte Tage
> schwankenden Strombedarf, ohne dabei zu viel Energie zu verlieren
> oder Speicher leerlaufen zu lassen.

Das vollständige Konzept liegt in
[`.humanInput/StaustufenSimulator/Pflichtenheft.txt`](.humanInput/StaustufenSimulator/Pflichtenheft.txt) — lies das einmal komplett.

## 2. Reduktion auf Level 1 — was DU baust

Pflichtenheft beschreibt vier Schwierigkeitsstufen. **Du baust nur
Stufe 1**, mit folgender Reduktion:

| Element                  | Pflichtenheft (Vollausbau)        | Level 1 (dein Auftrag)              |
|--------------------------|-----------------------------------|-------------------------------------|
| Speicheranzahl           | 3 Stufen                          | **2 Stufen** (Oben + Unten)         |
| Pumpe                    | mehrere zwischen Stufen           | **1 Pumpe** (Unten → Oben)         |
| Turbine                  | mehrere zwischen Stufen           | **1 Turbine** (Oben → Unten)        |
| Steuerstufen             | aus / schwach / mittel / stark    | **aus / schwach / mittel / stark** |
| Spieldauer               | 5 simulierte Tage                 | **5 Tage** ✓                        |
| Bedarfskurve             | dynamisch + Wetter                | **fix vorgegeben** (eine Kurve)     |
| Solar / Wind             | im Pflichtenheft                  | **weglassen**                       |
| Wetterprognose           | mit Ungenauigkeit                 | **weglassen** (deterministisch)     |
| Natürliche Zuflüsse      | regenabhängig                     | **konstanter Tropfen** in Oben      |
| Verluste                 | Pump-WG + Turbinen-WG             | **2 Wirkungsgrade**, fix            |
| End-Bewertung            | A–E mit 5 Kriterien               | **A–E mit 2 Kriterien** (Versorgung + Verluste) |
| Tutorial / Onboarding    | kommt später                      | **2 Hint-Pop-ups** in Tag 1         |
| Sound / Musik            | später                            | **weglassen**                       |
| Bilder                   | später                            | **weglassen**                       |

**Der „Gegner" in Level 1** = die Bedarfskurve (Tag 1 niedrig, Tag 2
mittel, Tag 3 Spitze, Tag 4 niedrig, Tag 5 Spitze) **plus** die
Tatsache, dass wer in Tag 1–2 alles abturbiniert oder alles hochpumpt,
in Tag 3 oder Tag 5 eine Versorgungslücke hat. Wer alles ausbalanciert,
verliert Energie an Wirkungsgrade. **Wenig Knöpfe, klares Dilemma.**

## 3. Plattform-Bausteine — was du nutzt, nicht nachbaust

### Verzeichnisse (alles existiert bereits)
- **Sim-Code**: `App/sims/staustufen/` (heute noch leer, dein Spielfeld)
- **Wrapper-PHP**: `App/pages/staustufen.php` — **steht schon** (Atlas-Territorium).
  Mode-Check + Locked-Seite + 503-„In Vorbereitung"-Fallback solange
  `App/sims/staustufen/game.html` fehlt. Sobald du `game.html` anlegst,
  wird sie automatisch ausgeliefert. Inject-Marker in deiner game.html:
  `/*__STAUSTUFEN_INJECTION__*/` — dort werden `STAUSTUFEN_BASE`,
  `STAUSTUFEN_SESSION_MODE`, `STAUSTUFEN_FORCED_LEVEL`,
  `STAUSTUFEN_SESSION_ID`, `STUDENT_EASY`, `STAUSTUFEN_API_BASE`
  vom Wrapper befüllt.
- **Modul-Detail**: `App/pages/modul-staustufen.php` — **steht schon**.
  Lehrplan-Anker und Glossar werden vom Partial automatisch aus DB
  gezogen, sobald Lehrplan-/Glossar-Instanz geliefert haben.
- **DB**: `module_info`-Eintrag steht schon (status `geplant`,
  page_url `modul-staustufen`, play_url `staustufen`,
  sort_order 16, icon `🏞️`)
- **Inbox**: `App/sims/_inbox/staustufen/` (du bekommst Nachrichten hier;
  Atlas-Stille bis Fertigmeldung)

### Plattform-CSS / -Komponenten
- **Design-System**: [`App/assets/css/design-system.css`](App/assets/css/design-system.css) — nutze die `.ggs-*`-Klassen.
  Header: `.ggs-header`, `.ggs-header-module`, `.ggs-header-badge`.
  Buttons: `.ggs-btn-ghost`, `.ggs-btn-primary`. End-Screen:
  `.ggs-endscreen` (siehe Heli/Logistik für Muster).
- **Header-Template**: schau in [`App/sims/heli/game.html` (Header ab Zeile 445)](App/sims/heli/game.html#L445)
  oder [`App/sims/klima/game-2d.html`](App/sims/klima/game-2d.html). Kopiere die ggs-header-Struktur,
  nimm den Logo-Block, Modul-Name, Badge, Music-Player kannst du
  weglassen (Reduktion).
- **End-Screen**: `.ggs-endscreen` ist im Design-System dokumentiert.
  Heli macht die Render-Logik in [`App/sims/heli/game.html` `initResultsPhase`](App/sims/heli/game.html). Kopier-Vorlage.

### APIs (Backend, fertig)
- **Mode-Check** (im Wrapper-PHP): liefert
  `STAUSTUFEN_SESSION_MODE` ('free'/'teacher_started'/'locked'),
  `STAUSTUFEN_FORCED_LEVEL`, `STAUSTUFEN_SESSION_ID`,
  `STUDENT_EASY`. Pattern siehe [`App/pages/heli-game.php` Zeilen 14–77](App/pages/heli-game.php#L14-L77).
  **Wichtig**: locked = HTTP 403 + Sperrseite, free = öffentliche Demo
  ohne Persistenz. Forced-Level kannst du in Level 1 ignorieren
  (du hast nur ein Level), aber leg das Pattern-Hooked an, damit
  spätere Levels das nutzen können.
- **Assessment-API**: `POST /api/assessment.php` mit
  `{action: 'started'|'running'|'completed', sim_id: 'staustufen',
  session_id, payload}`. Heli und Logistik haben Beispiele
  (suche `assessmentStart`, `assessmentRunning` in deren game.html).
  Triggern: bei Start, alle 30 s, beim End-Screen.
- **Save-API** (optional): in Level 1 unkritisch, der Lauf ist 10 min.
  Kannst du weglassen.

### Bausteine, die du **nicht** brauchst
- Keine Karten / OSM / Leaflet (du bist Diagramm-zentriert)
- Keine 3D-Engine / Three.js
- Keine externen Bilder / DALL-E
- Keine Sounds / ElevenLabs (für Level 1)
- Keine Glossar-Begriffe (Glossar-Instanz arbeitet zu, wenn du fragst)

## 4. Naming-Konvention

| Element                | Wert                                     |
|------------------------|------------------------------------------|
| Modul-ID               | `staustufen`                             |
| Modul-Verzeichnis      | `App/sims/staustufen/`                   |
| Sim-URL                | `http://localhost/geograsim/App/staustufen` |
| Detail-URL             | `http://localhost/geograsim/App/modul-staustufen` |
| JS-Window-Variable     | `STAUSTUFEN_BASE`, `STAUSTUFEN_SESSION_MODE`, `STAUSTUFEN_FORCED_LEVEL`, `STAUSTUFEN_API_BASE`, `STAUSTUFEN_SESSION_ID` |
| LocalStorage-Key       | `ggs-staustufen-*` (Prefix `ggs-`)       |
| CSS-Prefix             | `.st-*` (kurz, eindeutig — `.st-tank`, `.st-pump`, `.st-graph`) |
| Commit-Präfix          | `Staustufen:` (Capital S, Doppelpunkt-Leerzeichen) |

## 5. Sprachregel 4a (Wygotski / Lernarbeit) — verbindlich

**Niemals**: „spielen", „Spiel", „Spieler", „Spielzeit", „Sieg",
„Niederlage" als sichtbare Texte, Variablennamen oder Datenbank-Werte.

**Stattdessen**: „arbeiten mit", „Simulation", „Bearbeiter*in",
„Durchgang", „Versorgungsqualität", „Bilanz", „erfolgreich
durchgeführt".

Begründung: didaktische Rahmung als **Lernarbeit**, nicht als Spiel.
Vermeidet Trivialisierung der Inhalte und entspricht Bildungsstandard
in Sek I. Die anderen Module sind alle so umgebaut — sei konsistent.

## 6. Definition of Done für Level 1

Du bist **fertig**, wenn:

1. ✅ `http://localhost/geograsim/App/staustufen` lädt eine Sim ohne JS-Fehler.
2. ✅ Mode-Check funktioniert: locked → Sperrseite, free/teacher_started → Sim.
3. ✅ Du kannst die Pumpe / Turbine bedienen, Wasser fließt sichtbar.
4. ✅ Eine 5-Tage-Bilanz läuft durch, Tag wechselt automatisch oder per Klick.
5. ✅ End-Screen via `.ggs-endscreen` zeigt Versorgungsqualität + Verluste + Note A–E.
6. ✅ Assessment-Calls feuern (started, completed) — verifizierbar in DB.
7. ✅ Sprachregel 4a komplett (kein „Spieler" im sichtbaren Text).
8. ✅ Funktioniert auf iPad Landscape 1180×820 (Touch-Targets ≥ 36 px).

**Wenn alle 8 Punkte abgehakt sind**, fertig-Meldung an
`_inbox/zentrale/` schreiben. Atlas deployt und Thomas testet.

## 7. Anti-Scope-Liste — was du **nicht** machst

- Mehrere Levels (du baust nur 1, Architektur lässt mehr zu)
- Wetter, Solar, Wind, Saison, Prognose-Ungenauigkeit
- Sounds, Musik, Bilder, Animationen jenseits CSS-Transitions
- Multiplayer, Lehrer-Live-View, Class-Mode-Switch (gibt's, brauchst nicht)
- Eigene API-Endpunkte (nutze assessment.php, mehr nicht)
- Refactoring von Plattform-Code (`App/php/`, `App/assets/css/design-system.css`,
  Atlas-Territorium — bei Bedarf Anfrage in `_inbox/zentrale/`)

## 8. Erste 60 Minuten — Roadmap

| Min     | Aufgabe                                                          |
|---------|------------------------------------------------------------------|
| 0–10    | Pflichtenheft + dieses Briefing lesen. Crash-Recovery-Skizze.   |
| 10–25   | DOM-Skelett: 2 Tank-Balken, Steuer-Buttons, 5-Tage-Bedarfsgraph, Tag-Anzeige. |
| 25–40   | `game.html`-Skelett mit ggs-header, `/*__STAUSTUFEN_INJECTION__*/`-Marker, design-system.css einbinden. Wrapper-PHP existiert bereits. |
| 40–70   | `engine.js`: Game-State (`tanks[2]`, `pump`, `turbine`, `day`, `demand[5]`, `losses`), Tick-Funktion. |
| 70–100  | UI-Updates pro Tick, End-Screen-Render, Hint-Pop-ups Tag 1.     |
| 100–120 | Assessment-Calls, iPad-Test, Sprachregel-Sweep, fertig-Meldung. |

Das ist großzügig — kann auch in 90 Min stehen. Wichtig: nicht polieren,
sondern **funktionieren**. UI-Polish kommt nach Thomas-Feedback.

## 9. Plattform-Konventionen

- **Inbox-Pfad**: deine ist `_inbox/staustufen/`. Atlas-Inbox ist
  `_inbox/zentrale/` — nicht `_inbox/atlas/` (anderen Instanzen ist das
  schon passiert).
- **Status-Datei**: `_inbox/staustufen/_status.md` — bei jedem
  Session-Ende aktualisieren (Crash-Recovery).
- **Memory** (lokal in dieser Claude-Instanz): unter
  `C:\Users\herr_\.claude\projects\c--xampp-htdocs-geograsim\memory\`
  haltest du Notizen, die für künftige Sessions nützlich sind.
  Lies das `MEMORY.md` zu Beginn.
- **Git**: Commit-Präfix `Staustufen:`. Nicht skip-hooks. Keine
  Force-Pushes. Nicht direkt deployen — Atlas bündelt Deploy.
- **Crash-Recovery**: bei Absturz lesen wir
  `_status.md` + Inbox + Memory. Halte diese drei aktuell.

## 10. Lehrplan-Anker (laufen parallel, blockieren dich nicht)

Atlas hat Lehrplan-Instanz parallel beauftragt, 6–8 AT-Anker für
Wasserkraft / Energiespeicherung anzulegen. Das passiert in
`kompetenzen` / `kompetenz_modules` / `lehrplan_anchors` — du musst
nichts dafür tun. Wenn das Modul-Detail (`/modul-staustufen`)
zur Fertigmeldung leer ist, ist Lehrplan halt langsamer als du.
Kein Blocker.

## 11. Was du jetzt tust

1. Pflichtenheft lesen.
2. Dieses Briefing lesen.
3. Status-Datei aktualisieren („Phase 1 — Architektur-Skizze").
4. DOM-Skelett bauen.
5. Iterieren bis DoD erfüllt.
6. Fertig-Meldung in `_inbox/zentrale/`.

**Keine Rückfrage an Atlas nötig**, außer du stolperst über einen
Plattform-Blocker (Mode-Check funktioniert nicht, design-system.css
fehlt eine Klasse, etc.). Dann: kurze Nachricht in
`_inbox/zentrale/`, ich antworte schnell.

## 12. Bestätigen

- status: gelesen
- Bei Plattform-Frage → `_inbox/zentrale/`
- Bei Inhalts-Frage zum Pflichtenheft → mach selber, Thomas hat
  Vertrauen in deine Reduktion
- Fertig-Meldung an `_inbox/zentrale/` mit Stichpunkten zur DoD-Liste

Viel Erfolg. Bau das Ding.

— Atlas