operations_research/PLAN.md

# PLAN — Optimierte Entscheidungsfindung mit Python, Version 04

**Zweck dieser Datei:** Sie hält den *vollständigen* Umbauplan von Version 03 zu Version 04
fest, mit allen Phasen, Konventionen und Prüfschritten — unabhängig davon, wie weit die
Arbeit gediehen ist. Was davon bereits erledigt ist, steht in **[PROGRESS.md](PROGRESS.md)**.

> **Arbeitsteilung der beiden Planungsdateien**
>
> | Datei | Inhalt | ändert sich |
> | --- | --- | --- |
> | `PLAN.md` (diese Datei) | das Ziel und der Weg dorthin | selten — nur bei Kurswechsel |
> | `PROGRESS.md` | der erreichte Stand, mit Zahlen und Funden | nach jedem Arbeitsschritt |
>
> Beide liegen im **Repo-Wurzelverzeichnis**, nicht im Kapitelverzeichnis: Sie regieren
> sechs Verzeichnisse, nicht nur die Kapitelquellen, und stehen dort neben `CLAUDE.md`, das
> als einzige Datei von jeder neuen Sitzung automatisch gelesen wird und auf sie verweist.
>
> Die frühere `Operations_Research_mit_Python_Version_04/ARBEITSPLAN.md` ist am
> 7. September 2026 in diesen beiden Dateien aufgegangen und wurde gelöscht (Commit-Historie
> bewahrt sie auf). Eine Sache an zwei Stellen zu pflegen ist genau der Fehler, an dem in
> diesem Projekt schon einmal Buch und Programme-Verzeichnis auseinandergelaufen sind.

**Stand des Plans:** 7. September 2026 · Branch `main` · Version 03 bleibt unangetastet und
weiter baubar; Version 04 ist ein paralleler Strang.

---

## 1. Warum es Version 04 gibt

Grundlage ist die Rezension in `Kritik_und_Verbesserungsvorschlaege/Kritik.md`. Sie benennt
drei Schwächen von Version 03:

1. den steilen thematischen Bruch zwischen Logistik (Teil II/III) und Finanzmärkten (Teil IV),
2. die hohe mathematische und architektonische Einstiegshürde,
3. die Lücke bei Metaheuristiken und nicht-konvexer Optimierung.

Version 03 ist ein fachlich starkes, aber akademisch getaktetes Kompendium (22 Dateien,
~13 650 Zeilen, 42 Beispielprogramme). Version 04 baut es vom **Nachschlagewerk zum
Kursbegleiter** um: Die Teilnehmer sollen schnelle, messbare Erfolge erleben und die
Verfahren am nächsten Arbeitstag anwenden können.

### Die drei Leitprinzipien

1. **Time-to-First-Success minimieren** — ein lauffähiges Aha-Erlebnis *vor* der formalen
   Theorie.
2. **Kognitive Entlastung** — Formeln konsequent in Klartext, Alltagssprache und Geometrie
   übersetzen.
3. **Robuste Praxistauglichkeit** — Typsicherheit, echte Datenpipelines, ehrliches
   Debugging statt idealisierter Beispiele.

### Getroffene Grundsatzentscheidungen

| Frage | Entscheidung |
| --- | --- |
| Bilder | eigenes `bilder_04/`, damit V03 eingefroren bleibt |
| Fremdbibliotheken | polars, pyomo, linopy, pymoo, celery, cvxpylayers **installiert** — die Programme laufen wirklich. Ipopt/CyIpopt und Redis/Docker bleiben illustrativ mit dokumentiertem Fallback |
| Notebooks | lokal in `Notebooks_04/`, Colab-Link aus **einer** Konstanten `COLAB_BASIS_URL` in `build_version_04.py` |
| Plotly | zweigleisig: Matplotlib/Graphviz bleibt PDF-Quelle, Plotly zusätzlich in die Website eingebettet |
| Nicht ausführbare Inhalte | ausdrücklich als solche kennzeichnen (z. B. MINLP/Ipopt) statt Ausgaben zu erfinden |

---

## 2. Zielstruktur

22 → 29 Textdateien. Neue Kapitel **fett**. Kapitelnummern entstehen automatisch aus
`{#kap:label}`, Querverweise laufen über `{ref:...}`, Abschnittsnummern vergibt der Build —
Einfügen ist daher an keiner Stelle mit Handarbeit verbunden.

| Teil | Kapitel |
| --- | --- |
| I Grundlagen | 1 Einführung · 2 Fundament · 3 Python-Ökosystem · **4 Vom Management-Wunsch zum Modell** |
| II Kernverfahren | *Entscheidungs-Flussdiagramm* · 5 LP · 6 MILP · 7 CP-SAT · 8 Graphen/Touren · **9 Metaheuristiken** |
| III Nichtlinearität/Unsicherheit | *Entscheidungs-Flussdiagramm* · 10 QP/NLP/MINLP · 11 Unsicherheit · 12 Dynamische Programmierung · **13 Mehrziel & Pareto** |
| IV Brücke & Vertiefung | **14 Strukturbrücke Logistik ↔ Finance** · **15 Predict-then-Optimize** · **16 Supply-Chain & Energieeinsatz unter Unsicherheit** |
| V Finanzmärkte (Vertiefung) | 17 Finanzdaten · 18 Markowitz · 19 CVaR · 20 Handelsmaschine |
| VI Praxis | 21 Praxisfallen · **22 Testing, Benchmarking, Deployment** · Projektwerkstatt |
| Anhänge | A Lösungen · B Modellierungsmuster · C Fehlerdiagnose & IIS · **D Spickzettel** · E Glossar/Literatur |

Teil V (Finanzmärkte) wird im Vorwort und im Teil-Auftakt ausdrücklich als **spezialisierte
Vertiefungsdomäne** gekennzeichnet; Kapitel 16 ist die gleichwertige Nicht-Finanz-Alternative
mit denselben Werkzeugen.

### Verzeichnisse

```
Operations_Research_mit_Python_Version_04/            Quelle: Kapiteldateien + Build-Skripte
Operations_Research_mit_Python_Version_04_Programme/  generiert: Beispielprogramme
Notebooks_04/                                         generiert: ein .ipynb je Kapitel
bilder_04/                                            Quelle: Diagramme + Generatorskripte
OR_HTML_04/                                           generiert: Mehrseiten-Website
Operations_Research_mit_Python_Version_04.md / .pdf   generiert
```

---

## 3. Phase 0 — Infrastruktur

*Voraussetzung für alles Weitere; wird zuerst und vollständig abgeschlossen.*

**`build_version_04.py`** — Fork von `build_version_03.py` mit vier Eingriffen; alles andere
bleibt identisch:

1. **Pfadkonstanten zentralisieren.** Ein Versionsblock am Dateikopf: `ZIEL_MD`,
   `PDF_DATEINAME`, `PROGRAMME_VERZ`, `BUILD_BASISNAME`, `BILDER_NAME/VERZ`,
   `HTML_NAME/VERZ`, `NOTEBOOK_NAME/VERZ`, `COLAB_BASIS_URL`.
2. **Bildpfade.** V04-Markdown referenziert `bilder_04/…`. Fürs PDF löst Pandoc relativ zum
   Repo-Wurzelverzeichnis auf; für die Website spiegelt `spiegle_bilder()` das Verzeichnis
   nach `OR_HTML_04/`.
3. **Automatische Abschnittsnummerierung.** `nummeriere_abschnitte()` vergibt `## 5.4 Titel`
   (im Anhang `## C.4 Titel`) beim Bauen; `ABSCHNITT_RE` erwartet im Quelltext **keine**
   Nummer mehr. Analog in `baue_seiten_registry()` / `resolve_numbering_seite()`. **Ohne
   diesen Eingriff zöge jedes eingefügte Kapitel Handarbeit in allen Folgekapiteln nach
   sich.**
4. **Neue Bausteine.** `resolve_plotly()` + `kopiere_plotly_bibliothek()` (Plotly-Fragmente
   in die Kapitelseiten einbetten, im PDF statischer Ersatz), `baue_notebooks()` +
   `ergaenze_notebook_hinweis()` + `spiegle_notebooks()`, erweitertes `markiere_karten()`
   für die neuen Kartentypen, `KEINE_KAPITELDATEIEN`.

**`extract_programme_04.py`** — Fork von `extract_programme.py`, nur `ZIEL_DIR`/`HIER` und
die README-Vorlage umgestellt. Extraktionsmuster (`#!/usr/bin/env python3`, Leerzeile,
`# Name.py`) bleibt unverändert.

**`OR_HTML_04/assets/site.css`** — neue Boxklassen für 5-Minuten-Box, Formel-Übersetzer,
Excel-Brücke, Micro-Quiz und Denkfehler-Aufgabe.

**Abschluss:** `--check`, `--pdf` und `--html` laufen mit inhaltlich unverändertem V03-Text
sauber durch. Erst dann beginnt inhaltliche Arbeit.

---

## 4. Phase 1 — Didaktik-Layer über alle bestehenden Kapitel

Pro Kapitel, in Lesereihenfolge, jeweils dieselben Bausteine (siehe Abschnitt 8):

* **„In 5 Minuten gelöst“** als erster Abschnitt: 4–6 Zeilen Daten, ≤ 15 Zeilen Code,
  betriebswirtschaftlich sofort lesbares Ergebnis — danach erst „Warum funktioniert das?“.
* **Formel-Übersetzer-Tabellen** (zweispaltig Mathematik | Alltagssprache) an jeder
  zentralen Formel; die bestehenden „Lesehilfe“-Blöcke gehen darin auf.
* **Micro-Quiz** (genau 3 Multiple-Choice-Fragen) und **„Finde den Denkfehler“**
  (lauffähiger Code mit betriebswirtschaftlich unsinnigem Ergebnis: `>=` statt `<=`,
  vergessene Ganzzahligkeit, Big-M zu klein, Zirkelbezug) je Kapitelende; Lösungen nach
  Anhang A.
* **Notebook-Badge** im „Kapitel auf einen Blick“-Block.

### Kapitelspezifische Ergänzungen

| Kapitel | Ergänzung |
| --- | --- |
| 1 Einführung | **Excel-zu-Python-Brücke:** Excel-Solver-Modell Zelle für Zelle übersetzt, `pandas.read_excel()` → Modell → formatierter Export |
| 2 Fundament | **Numerik-Deep-Dive:** Konditionszahl $\kappa(A)$ als Experiment (Kosten $10^7$ gegen Toleranzen $10^{-6}$ → falsches `INFEASIBLE`), Ruiz-Equilibrierung, Geometrie vor Algebra |
| 3 Ökosystem | Pyomo/Linopy im Vergleich zu CVXPY/OR-Tools; vektorisierte Modellgenerierung (NumPy, Polars) gegen `for`-Schleifen gebenchmarkt; wiederverwendbare Excel-/CSV-Pipeline |
| 4 LP | Primal-/Dual-/Integralitätstoleranzen, Degeneriertheit als Vorschau auf Anhang C |
| 5 MILP | MIP-Gap, Time-Limit, Warm-Starts (`SetHint`/`highspy`), warum `0.99999998` nicht `int()` verträgt |
| 6 CP-SAT | vollständige Statusauswertung, interaktives Gantt (Plotly) |
| Teil-Auftakte II und III | Entscheidungs-Flussdiagramm „Welcher Solver passt zu meinem Problem?“ (Graphviz) |

---

## 5. Phase 2 — Code-Architektur auf Enterprise-Niveau

Neues gemeinsames Modul **`or_kern.py`** im Programme-Verzeichnis (folgt dem
Extraktionsmuster, wird also mitgeneriert) — der greifbare Beleg für Clean Architecture:

```
Rohdaten (Excel/CSV)
    → Domänenmodell (Pydantic, geprüft)
        → Modellbauer (solverabhängig)
            → Lösung (DTO, solverunabhängig)
                → Abnahmeprüfung
```

* **Pydantic-v2-Basismodelle** für Ressourcen, Bedarfe, Kosten- und Renditematrizen mit
  Validierung beim Einlesen (strikt positive Kapazitäten, Wahrscheinlichkeiten summieren
  auf 1, Spaltenzuordnung über Namen statt Positionen).
* **Einheitliches `Loesung`-DTO** plus `SolverStatus`-Enum (`OPTIMAL`, `ZULAESSIG`,
  `UNZULAESSIG`, `UNBESCHRAENKT`, `ZEITLIMIT`, `FEHLERHAFT`, `UNBEKANNT`) mit Übersetzern
  für pywraplp, CP-SAT, highspy, SciPy und CVXPY. **Lazy imports**, weil `ortools` und
  `highspy` sich nicht gemeinsam importieren lassen.
* **Excel-/CSV-Ein- und -Ausgabe** (`lade_produktionsproblem()`, `schreibe_ergebnis()`),
  pandas als optionale Abhängigkeit.

Alle bestehenden Programme werden darauf umgestellt: durchgängige Type Hints
(mypy-kompatibel), Domäne strikt vom Solver getrennt, keine impliziten
Optimalitätsannahmen mehr. Der **Solver-Austausch HiGHS ↔ CP-SAT** wird an einem Beispiel
real vorgeführt.

> **Maßstab bei jeder Umstellung:** Wird das Programm dadurch kürzer *und* klarer? Wenn
> nicht, bleibt es. Ein Lehrbeispiel darf nicht an Architektur ersticken — das gilt
> besonders für die frühen Kapitel, wo die Leser das Modul noch nicht kennen.

---

## 6. Phase 3 — Neue Kapitel

* **Kap. 4 Vom Management-Wunsch zum Modell** — Anforderungsanalyse für OR-Projekte,
  realistischer Dialog („Kosten senken, aber die Mitarbeiter sollen nicht meckern“),
  systematische Zerlegung in Entscheidungsvariablen / harte vs. weiche Restriktionen
  (Strafkosten) / fehlanreizfreie Zielfunktion.
* **Kap. 9 Metaheuristiken** — wenn HiGHS/CP-SAT skalierungsbedingt aussteigen: lokale
  Suche mit Kostenänderung in $O(1)$, Simulated Annealing samt Kalibrierung der Temperatur,
  der gemessene Umschlagpunkt gegen den exakten Solver, Large Neighborhood Search
  (zerstören / exakt reparieren).
  **Dekomposition wurde aus diesem Kapitel herausgenommen** und ist ein eigener offener
  Punkt: Spaltengenerierung gibt eine *andere* Antwort auf dieselbe Frage — sie approximiert
  nicht die Lösung, sondern formuliert das Modell um. Genetische Algorithmen (`pymoo`) und
  Tabu-Suche sind im Kapitel benannt und eingeordnet, aber nicht ausgeführt: Für Reihenfolgen
  ist die „Kreuzung“ zweier Lösungen gerade der schwierige Teil, und ein halbherziges
  Beispiel dazu wäre irreführend.
* **Kap. 13 Mehrziel & Pareto** — warum lineare Skalarisierung bei nicht-konvexen Fronten
  versagt; $\epsilon$-Constraint und lexikografische Optimierung an Kosten vs. CO₂ in der
  Tourenplanung; exakte Pareto-Front, statisch fürs PDF und interaktiv (Plotly) auf der
  Website.
* **Kap. 14 Strukturbrücke** — dieselbe Mathematik, zwei Welten: Ressourcenallokation ↔
  Kapitalallokation, Lieferausfall-Robustheit ↔ Worst-Case-Risikomaße; Gegenüberstellung
  als Tabelle plus ein Modell, das beide Datensätze frisst.
* **Kap. 15 Predict-then-Optimize** — Nachfrageprognose → Lagerbestand: ein Modell mit
  kleinerem MSE erzeugt teurere Entscheidungen; Entscheidungskosten statt Prognosefehler
  messen; Ausblick `cvxpylayers`/PyTorch.
* **Kap. 16 Supply-Chain & Energieeinsatz unter Unsicherheit** — die Nicht-Finanz-Alternative
  zu Teil V mit denselben Werkzeugen (Szenarien, CVaR, DP): Netzwerkdesign mit
  Standortentscheidungen, Kraftwerkseinsatzplanung.
* **Kap. 22 Testing, Benchmarking, Deployment** — pytest-Framework für Optimierungsmodelle
  (Regression gegen Benchmark-Instanzen, Restriktionsverletzungs-Checks,
  Skalierungsinvarianz), reproduzierbare Benchmark-Pipeline SciPy/HiGHS/OR-Tools/CVXPY über
  $N \in \{10^2, 10^3, 10^4\}$ (Zeit und Speicher), FastAPI-Microservice mit asynchroner
  Job-Queue und schlankem `Dockerfile`.

### Empfohlene Reihenfolge

Nicht strikt nach Kapitelnummer, sondern nach Nutzen — falls vor einem Kurstermin ein
brauchbarer Zwischenstand gebraucht wird:

1. **Kap. 9 Metaheuristiken** — schließt die von der Rezension am schärfsten benannte Lücke.
2. **Kap. 22 Testing/Deployment** — zweite große Lücke; der Unterbau (`or_kern.py`) steht
   bereits und ist genau das, was sich testen lässt.
3. **Kap. 4 Vom Management-Wunsch zum Modell** — kurz, didaktisch tragend, ohne neue
   Bibliotheken.
4. **Kap. 13 Mehrziel**, **Kap. 14 Strukturbrücke**, **Kap. 15 Predict-then-Optimize**.
5. **Kap. 16 Supply-Chain & Energie** — die aufwendigste Einheit und am ehesten verzichtbar,
   falls der Umfang begrenzt werden muss.

---

## 7. Phase 4 — Anhänge · Phase 5 — Medien, Rahmen, Gesamtbau

### Phase 4 — Anhänge

* **Anhang C → vollwertiges Troubleshooting-Handbuch:** IIS/Conflict Refiner in Python
  (deletion filter, der aus tausenden Restriktionen die minimale widersprüchliche Teilmenge
  isoliert), duale Entartung und instabile Schattenpreise, Toleranzkunde
  (`feasibility_tolerance` HiGHS vs. OR-Tools), Skalierung/Ruiz.
* **Anhang D (neu) Spickzettel** — je eine Seite SciPy, HiGHS, CP-SAT, CVXPY, Pyomo/Linopy:
  Variablentypen, Big-M-Entweder-Oder, weiche Restriktionen mit Slack, Dualwerte und Status
  abfragen.
* **Anhang B** — Rezeptkarten für Alltagsfragen (Mindestabnahmemengen, Rüstzeiten,
  Budgetlimit), abgestimmt auf Anhang D.
* **Anhang A** — Lösungen für alle neuen Aufgaben, Micro-Quizzes und Denkfehler-Übungen;
  läuft parallel zu jeder Phase mit.

### Phase 5 — Medien, Rahmen, Gesamtbau

* **Diagramme** in `bilder_04/`: zwei Entscheidungs-Flussdiagramme, Branch-and-Bound-Baum,
  Pareto-Front, Konditionszahl-Experiment, Metaheuristik-Landschaft,
  Clean-Architecture-Schichten, FastAPI-Deployment — Graphviz bzw. Matplotlib, jeweils
  SVG + PNG. **Diesmal mit mitgelieferten Generatorskripten** (`bilder_04/erzeuge_*.py`);
  in V03 fehlen die Diagrammquellen.
* **Plotly-Figuren** nach `bilder_04/plotly/*.html`, vom Build in die Kapitelseiten
  eingebettet; im PDF steht die statische Variante.
* **Notebooks** je Kapitel nach `Notebooks_04/`, aus den Kapitel-Codeblöcken generiert, mit
  `pip install`-Startzelle.
* **Rahmen aktualisieren:** Vorwort (Lernpfade um die neuen Kapitel und den
  Finanz-/Industrie-Gabelpunkt erweitert), Notation, Projektwerkstatt (Projekte zu
  Metaheuristik, Mehrziel und Deployment), Programme-README-Vorlage, `requirements.txt`,
  `CLAUDE.md` um den V04-Strang ergänzt.
* **Abschluss:** vollständiger Bau von Markdown, PDF und Website.

---

## 8. Der Kapitel-Baukasten

Jedes Kapitel der Version 04 erhält dieselben Bausteine in derselben Reihenfolge:

```
# Kapitel: <Titel> {#kap:<label>}

> 📌 Kapitel auf einen Blick        (Worum / Voraussetzungen / Danach / Zeitbedarf / Programme)
                                     Der Notebook-Hinweis wird vom Build ergänzt.

## In 5 Minuten gelöst {#sec:<label>-schnellstart}
   > 🚀 …    4–6 Zeilen Daten, ≤15 Zeilen Code, sofort lesbares Ergebnis
   danach im Fließtext: „Und jetzt der Punkt“ + „Warum funktioniert das?“

## Lernziele
## <Fachabschnitte>                  darin: > 🔤 Formel-Übersetzer an jeder zentralen Formel
## Übungsaufgaben
## Finde den Denkfehler {#sec:<label>-denkfehler}
   > 🐛 …    Code läuft fehlerfrei, Ergebnis ist betriebswirtschaftlich Unsinn
## Micro-Quiz {#sec:<label>-quiz}
   > ❓ …    genau 3 Multiple-Choice-Fragen
## Selbsttest                        (offene Fragen, aus V03 übernommen)
## Zusammenfassung
```

**Kartentypen** (Erkennung am führenden Emoji, `KARTEN_TYPEN` in `build_version_04.py`):

| Emoji | CSS-Klasse | Verwendung |
| --- | --- | --- |
| 📌 | `card-blick` | Kapitel auf einen Blick |
| 🚀 | `card-schnellstart` | In 5 Minuten gelöst |
| 🔤 | `card-formel` | Formel-Übersetzer (zweispaltig: Mathematik \| Alltagssprache) |
| 📊 | `card-excel` | Excel-Brücke |
| ❓ | `card-quiz` | Micro-Quiz |
| 🐛 | `card-denkfehler` | Finde den Denkfehler |
| 📎 | *(Blockquote)* | Verweis auf ein Modul oder einen späteren Abschnitt |

Bestehende Blockquotes (🎯 Merksatz, ⚠️ Typische Fehler, ✏️ Handrechnung, 💻 Code-Durchgang,
📖 Definition, 📐 Formel-Lesehilfe, 💡 Hinweis) bleiben unverändert und werden weiter
verwendet.

---

## 9. Regeln, die eingehalten werden müssen

1. **Abschnittsnummern nicht in den Quelltext schreiben.** `## Titel {#sec:label}` genügt;
   die Nummer vergibt der Build. Verweise im Fließtext immer als `{ref:sec:label}`.
2. **Keine Abschnittsnummern in Code-Kommentaren.** Dort den Abschnitts*titel* nennen —
   Nummern verschieben sich beim Einfügen neuer Kapitel.
3. **Bildpfade heißen `bilder_04/…`** — fürs PDF löst Pandoc relativ zur Repo-Wurzel auf,
   für die Website spiegelt der Build das Verzeichnis.
4. **Jede abgedruckte Ausgabe stammt aus einem echten Lauf.** Programm ausführen, Ausgabe
   kopieren, nicht plausibel erfinden. Bei Zufallszahlen: festen Seed setzen und
   Determinismus durch mehrfachen Lauf prüfen.
5. **Jede Solver-Auswertung behandelt alle Statusfälle explizit** — `OPTIMAL`, `FEASIBLE`,
   `INFEASIBLE`, `UNBOUNDED`, `TIME_LIMIT`.
6. **Änderungen an Programmen gehören in den Kapitel-Codeblock**, danach
   `extract_programme_04.py` laufen lassen. Das Programme-Verzeichnis ist ein Artefakt,
   keine zweite Quelle.
7. **Neue `{idx:…}`-Begriffe vorher prüfen:**
   `grep -ohE '\{idx:[^}]+\}' Operations_Research_mit_Python_Version_04/*.md | sort -u`
8. **Neues Programm ⇒ drei Stellen pflegen:** Kapitelkopf („Programme:“), Vorwort
   („Verzeichnis der Beispielprogramme“), bei neuer Abhängigkeit `requirements.txt`.
9. **Vor jedem neuen Programm prüfen, ob der Stoff schon abgedeckt ist.** Erst die
   vorhandenen Programme des Kapitels lesen, dann schreiben — ein Denkfehler kann auch auf
   einem bestehenden Programm aufbauen.
10. **Nach jedem Ersetzen eines Codeblocks die Codezäune zählen.** Ein fehlender
    schließender ` ``` ` fällt weder Pandoc noch dem Auge auf, lässt aber
    `reflow_markdown()` den gesamten Rest der Datei zu Fließtext falten — im PDF steht dann
    Programmcode als Absatz. `--check` prüft das seit Phase 2 automatisch
    (`pruefe_dateien()`).
11. **Am Ende jeder Phase die GESAMTE Programmsuite laufen lassen**, nicht nur die
    angefassten Programme. Der Durchlauf dauert wenige Minuten und ist die einzige Prüfung,
    die Altlasten findet.
12. **Keine Kapitelnummern in Programm-Docstrings.** Dort den Kapitel*namen* nennen —
    `Kapitel Metaheuristiken:` statt `Kapitel 9:`, so wie es die Code-Kommentare ohnehin
    halten („siehe Kapitel Oekosystem“). Nach zwei eingefügten Kapiteln waren 66 von 67
    Programmen falsch nummeriert; die Nummer im Buch stimmt automatisch, die im Docstring
    nicht. Gleiches gilt für Abschnittsnummern (Regel 2) und Dateinamen.
13. **`PROGRESS.md` gehört in denselben Commit wie die Arbeit, die sie beschreibt.**
    Nicht „danach mal nachziehen“ — dann steht dort früher oder später etwas, das nicht mehr
    stimmt. Eine Fortschrittsdatei, die hinterherhinkt, ist schlimmer als gar keine, weil man
    ihr glaubt: Man verlässt sich auf einen Stand, den es nicht gibt. Genau an dieser
    Trennung sind in diesem Projekt schon einmal Buch und Programme-Verzeichnis
    auseinandergelaufen. Mitzupflegen sind der Phasenstand, die Referenzwerte und der
    Abschnitt *Was als Nächstes ansteht*.

---

## 10. Verifikation

```bash
cd ~/Python_Programs/OR_mit_Python/Version_04

# 1. Struktur und Querverweise (meldet unbekannte {ref:...}-Labels und fehlende Codezäune)
python3 Operations_Research_mit_Python_Version_04/build_version_04.py --check

# 2. Programme extrahieren und jedes einzeln ausführen
python3 Operations_Research_mit_Python_Version_04/extract_programme_04.py
MPLBACKEND=Agg bash -c 'for p in Operations_Research_mit_Python_Version_04_Programme/*.py; do
  echo "== $p"; timeout 600 python3 "$p" >/dev/null || echo "FEHLER: $p"; done'

# 3. Testsuite aus dem Kapitel "Testen, Messen, Ausliefern"
#    (liegt flach im Programme-Verzeichnis, nicht in einem tests/-Unterordner)
pytest Operations_Research_mit_Python_Version_04_Programme/test_or_kern.py -q

# 4. PDF und Website
python3 Operations_Research_mit_Python_Version_04/build_version_04.py --pdf --html

# 5. Gegenprobe: Version 03 muss unverändert bauen
python3 Operations_Research_mit_Python_Version_03/build_version_03.py --check
```

Zusätzlich sichtprüfen: `OR_HTML_04/index.html` (Landing-Page, Sidebar, Volltextsuche,
Stichwortverzeichnis), eine Kapitelseite mit den neuen Karten und einer eingebetteten
Plotly-Figur, seitenübergreifende Querverweise (`andere-seite.html#anker`).

**Prüfmaßstab pro Kapitel:** jeder abgedruckte Codeblock wurde ausgeführt, die im Buch
gezeigte Ausgabe stammt aus diesem Lauf, und jede Solver-Auswertung behandelt alle
Statusfälle explizit.

---

## 11. Umfang und Reihenfolge

Der Umfang entspricht etwa einer Verdopplung des Buches: 7 neue Kapitel, ein neuer Anhang,
Didaktik-Layer und Code-Refactoring über 22 Bestandsdateien. Die Arbeit läuft in der
Phasenreihenfolge 0 → 5; **nach jeder Phase ist der Stand baubar und lauffähig**, sodass
Zwischenstände begutachtet werden können.

Phase 0 wird zuerst und vollständig abgeschlossen, weil ohne automatische
Abschnittsnummerierung jedes eingefügte Kapitel Handarbeit in allen Folgekapiteln nach sich
zöge.

**Sprache:** Kommentare, Ausgaben und Fließtext sind durchgängig Deutsch.