# Kernkonzepte

## Projektübersicht

Sphinx-basiertes Dokumentationssystem für Transport- und Hängefördersysteme.
JSON-gesteuerter Build erzeugt aus modularen Textbausteinen mehrsprachige PDF-Dokumentationen (250+ Seiten).
Zwei-Repo-Architektur: allgemeine Ressourcen (Base-Repo) + projektspezifische Anpassungen (Projekt-Repo).

Auftraggeber: Firma Schönenberger
Umsetzung: Mista GmbH

## Architektur

### Zwei-Repo-Trennung

- **transport-docs-base** (Gitea): Alle wiederverwendbaren Inhalte – Module, Kapitelgerüste, Assets, Glossar, Sphinx-Extensions, LaTeX-Templates, Hilfsskripte. Semver-versioniert (VERSION-Datei).
- **projekt-kunde-xyz** (pro Anlage): anlage.json (ERP-Export), projektspezifische Bilder, Overrides, Zusatzkapitel, conf.py, build.py. Das Base-Repo wird beim Build als Mount/Share unter `transport-docs-base/` bereitgestellt.

### Technologie-Stack

| Komponente       | Technologie                                      |
|------------------|--------------------------------------------------|
| Build-System     | Sphinx (Python)                                  |
| Textformat       | reStructuredText (rST)                           |
| Templating       | Jinja2 (Rahmenkapitel, Titelseite)               |
| PDF-Erzeugung    | LaTeX (pdflatex/lualatex)                        |
| Versionierung    | Git (Gitea auf Hetzner)                          |
| Konfiguration    | JSON (ERP-Export) + YAML (Modul-Metadaten)       |
| CI/Automatisierung | Gitea Actions oder n8n                         |
| Bildkonvertierung | ezdxf → SVG, Pillow (Optimierung)               |

## Repo-Struktur

### Base-Repo: transport-docs-base

```
transport-docs-base/
├── conf_base.py                        # Sphinx-Basiskonfiguration (wird importiert)
├── VERSION                             # Semver der Dokumentationsbasis
├── _ext/
│   ├── anlagen_builder.py              # Hauptextension: JSON → Buchstruktur
│   ├── localized_figure.py             # Sprachauflösung für Bilder
│   └── glossary_loader.py              # CSV → Glossar-Direktive
├── _templates/
│   ├── latex/
│   │   ├── preamble.tex                # Firmen-CI: Fonts, Farben, Kopfzeilen
│   │   ├── titlepage.tex               # Titelseite-Template (Jinja2)
│   │   └── maketitle.tex
│   └── common/
│       └── header_footer.rst
├── assets/
│   ├── shared/                         # Sprachneutrale Bilder (~90%)
│   │   ├── photos/
│   │   │   ├── weiche_typ_a_foto_01.jpg
│   │   │   ├── hubstation_foto_01.jpg
│   │   │   └── antrieb_sew_foto_01.jpg
│   │   ├── drawings/                   # Technische Zeichnungen (DXF → SVG/PDF)
│   │   │   ├── weiche_typ_a_layout.svg
│   │   │   └── hubstation_schnitt.pdf
│   │   ├── symbols/                    # ISO 7010 Sicherheitssymbole
│   │   │   ├── W001_warnung.svg
│   │   │   └── M004_augenschutz.svg
│   │   └── diagrams/                   # Schaltpläne, Pneumatik
│   │       └── stromlaufplan_weiche_a.pdf
│   └── localized/                      # Sprachspezifische Bilder
│       ├── de/
│       │   ├── screenshots/
│       │   │   └── hmi_hauptmenu.png
│       │   └── diagramme/
│       │       └── risikograph_weiche_a.svg
│       ├── en/
│       │   ├── screenshots/
│       │   │   └── hmi_hauptmenu.png
│       │   └── diagramme/
│       │       └── risikograph_weiche_a.svg
│       └── fr/
│           └── ...
├── modules/                            # Textbausteine pro Maschinentyp
│   ├── weiche_typ_a/
│   │   ├── meta.yaml                   # Abhängigkeiten + Kapitelzuordnung
│   │   ├── beschreibung.de.rst
│   │   ├── beschreibung.en.rst
│   │   ├── risikomatrix.de.rst
│   │   ├── risikomatrix.en.rst
│   │   ├── wartung.de.rst
│   │   └── images/
│   │       └── montage_detail_01.jpg
│   ├── hubstation/
│   │   ├── meta.yaml
│   │   ├── beschreibung.de.rst
│   │   ├── technische_daten.de.rst
│   │   ├── wartung.de.rst
│   │   └── images/
│   │       └── hubmechanik_detail.jpg
│   ├── antrieb_sew/
│   │   ├── meta.yaml
│   │   └── ...
│   └── steuerung_siemens_s7/
│       ├── meta.yaml
│       └── ...
├── chapters/                           # Rahmenkapitel (Gerüst)
│   ├── 01_einleitung/
│   │   ├── template.de.rst             # Jinja2-Template mit Platzhaltern
│   │   └── template.en.rst
│   ├── 02_sicherheit/
│   │   ├── allgemein.de.rst            # Immer dabei
│   │   ├── allgemein.en.rst
│   │   ├── normen_ce.de.rst            # EU-Konformität
│   │   └── normen_ukca.en.rst          # UK-spezifisch
│   ├── 03_anlagenbeschreibung/
│   │   └── template.de.rst             # Hier werden Module eingefügt
│   ├── 04_betrieb/
│   │   └── template.de.rst
│   ├── 05_wartung/
│   │   ├── allgemein.de.rst
│   │   └── schmierplan_template.de.rst
│   ├── 06_ersatzteile/
│   │   └── template.de.rst
│   └── 07_anhang/
│       └── template.de.rst
├── glossary/
│   ├── terms.de.csv                    # "Begriff;Definition;Kategorie"
│   ├── terms.en.csv
│   └── terms.fr.csv
├── styles/
│   ├── firma_logo.pdf
│   ├── firma_logo_sw.pdf
│   └── color_scheme.yaml              # CI-Farben für LaTeX und SVG
├── scripts/
│   ├── dxf2svg.py                     # DXF → SVG Konvertierung
│   ├── optimize_images.py             # Bildoptimierung vor Commit
│   └── validate_modules.py            # Prüft meta.yaml Konsistenz
```

### Projekt-Repo: projekt-kunde-xyz

```
projekt-kunde-xyz-2026/
├── conf.py                             # Importiert conf_base.py vom Base-Repo
├── anlage.json                         # ERP-Export: Maschinenauswahl + Metadaten
├── build.py                            # Hauptbuild-Skript
├── Makefile
├── README.md
├── images/                             # Projektspezifische Bilder
│   ├── aufstellplan_halle3.pdf
│   ├── foto_abnahme_01.jpg
│   └── kundenlogo.pdf
├── overrides/                          # Projektspezifische Überschreibungen
│   ├── modules/
│   │   └── weiche_typ_a/
│   │       └── beschreibung.de.rst     # Überschreibt Basis wenn vorhanden
│   └── chapters/
│       └── 01_einleitung/
│           └── template.de.rst         # Kundenspezifische Einleitung
├── additional/                         # Kapitel die NUR dieses Projekt hat
│   ├── sonderausfuehrung_xyz.de.rst
│   └── sonderausfuehrung_xyz.en.rst
└── transport-docs-base/  ──────────── # Symlink/Mount zum Base-Repo (Share)
```
### anlage.json (ERP-Export)

Steuert die Zusammenstellung. Enthält Projektmetadaten, Zielsprachen, Normenregion, Liste verbauter Maschinen und Referenzen auf Zusatzkapitel.

**Beispiel:**

```json
{
  "projekt": {
    "nummer": "P-2026-0042",
    "kunde": "Müller Automotive GmbH",
    "kunde_logo": "images/kundenlogo.pdf",
    "standort": "Werk Ingolstadt, Halle 3",
    "sprachen": ["de", "en"],
    "normen_region": "EU",
    "base_version": ">=1.0.0"
  },
  "maschinen": [
    {
      "modul": "weiche_typ_a",
      "anzahl": 4,
      "positionen": ["W01", "W02", "W03", "W04"],
      "variante": "standard"
    },
    {
      "modul": "hubstation",
      "anzahl": 2,
      "positionen": ["H01", "H02"],
      "variante": "schwerlast",
      "optionen": ["hydraulisch"]
    },
    {
      "modul": "antrieb_sew",
      "anzahl": 12,
      "positionen": ["A01-A12"]
    },
    {
      "modul": "steuerung_siemens_s7",
      "anzahl": 1,
      "positionen": ["SPS01"],
      "optionen": ["profinet", "hmi_tp700"]
    }
  ],
  "zusatz_kapitel": [
    "additional/sonderausfuehrung_xyz"
  ]
}
```

### meta.yaml (Modul-Metadaten)

Pro Maschinentyp-Modul. Definiert Bezeichner, mehrsprachigen Namen, Kapitelzuordnung, Bildreferenzen und Abhängigkeiten.

**Beispiel** (`modules/weiche_typ_a/meta.yaml`):

```yaml
module: weiche_typ_a
display_name:
  de: "Weiche Typ A"
  en: "Switch Type A"

chapters:
  - 02_sicherheit:
      sections: [risikomatrix]
  - 03_anlagenbeschreibung:
      sections: [beschreibung, technische_daten]
  - 05_wartung:
      sections: [wartung, schmierplan]

images:
  shared:
    - photos/weiche_typ_a_foto_01.jpg
    - drawings/weiche_typ_a_layout.svg
    - diagrams/stromlaufplan_weiche_a.pdf
  localized:
    - diagramme/risikograph_weiche_a.svg
    - screenshots/hmi_hauptmenu.png
  module_local:
    - montage_detail_01.jpg

requires:
  - antrieb_sew
```

### conf.py (Projekt-Konfiguration)

Importiert die Basiskonfiguration vom gemounteten Base-Repo und setzt projektspezifische Overrides.

**Beispiel** (`projekt-kunde-xyz-2026/conf.py`):

```python
import sys
import os
from pathlib import Path

# ══ Pfad zum Base-Repo (Share/Mount) ══
BASE_DOCS = Path(os.environ.get(
    "DOCS_BASE_PATH",
    Path(__file__).parent / "transport-docs-base"
))

# Extensions und Basiskonfiguration importieren
sys.path.insert(0, str(BASE_DOCS / "_ext"))
sys.path.insert(0, str(BASE_DOCS))
from conf_base import *  # noqa: F401, F403

# ══ Projektspezifische Overrides ══
project = "Anlagendokumentation P-2026-0042"
release = "1.0"
author = "Mista GmbH"
copyright = "2026, Mista GmbH"

# Bildpfade: Projekt → Overrides → Base (Reihenfolge = Priorität)
image_search_path = [
    "images",                                   # Projektbilder
    "overrides",                                # Überschreibungen
    str(BASE_DOCS / "assets" / "shared"),       # Sprachneutrale Basis
    str(BASE_DOCS / "assets" / "localized"),    # Sprachspezifische Basis
    str(BASE_DOCS / "modules"),                 # Modulbilder
]

# Sphinx-Extensions aus Base-Repo laden
extensions += [
    "anlagen_builder",
    "localized_figure",
    "glossary_loader",
]

# Glossar-Pfad
glossary_csv_path = str(BASE_DOCS / "glossary")

# LaTeX-Templates aus Base-Repo
templates_path.insert(0, str(BASE_DOCS / "_templates"))

# LaTeX-spezifisch
latex_elements = {
    "preamble": open(BASE_DOCS / "_templates" / "latex" / "preamble.tex").read(),
    "maketitle": open(BASE_DOCS / "_templates" / "latex" / "maketitle.tex").read(),
    "papersize": "a4paper",
    "pointsize": "11pt",
}
```

### Override-Mechanismus

Suchreihenfolge beim Build:
1. `projekt/overrides/` (projektspezifisch)
2. `transport-docs-base/modules/` bzw. `chapters/` (allgemein)

Ermöglicht kundenspezifische Anpassungen ohne Base-Repo-Änderung.

### Versionskontrolle

Base-Repo hat Semver in `VERSION`. Projekt-Repo kann `"base_version": ">=2.1.0"` in anlage.json setzen. build.py prüft Kompatibilität vor dem Build.

## Mehrsprachigkeit

### Drei Ebenen

1. **Textbausteine**: Dateinamenskonvention `{name}.{lang}.rst`. Fallback auf `de` bei fehlender Übersetzung.
2. **Bilder**: `localized-figure`-Direktive löst `assets/localized/{lang}/pfad/bild.png` auf. Fallback auf `de`. Optional: Jinja2-SVG-Templates für Diagramme mit Text.
3. **Glossar**: CSV pro Sprache (`terms.{lang}.csv`), `glossary_loader.py` erzeugt Sphinx-Glossardirektiven. Im Text via `:term:`Fachbegriff`` verlinkt.

### Sprachspezifische Normen

Gesteuert über `normen_region` in anlage.json. Kapitel 02_sicherheit enthält z.B. `normen_ce.de.rst` (EU) und `normen_ukca.en.rst` (UK), Build wählt nach Region.

## Bildverwaltung

| Kategorie        | Pfad                              | Beispiele                                    |
|------------------|-----------------------------------|----------------------------------------------|
| Sprachneutral    | `assets/shared/{typ}/`            | Fotos, DXF/SVG-Zeichnungen, ISO-Symbole     |
| Sprachspezifisch | `assets/localized/{lang}/{typ}/`  | HMI-Screenshots, Risikographen, Typenschilder|
| Modulspezifisch  | `modules/{modul}/images/`         | Montagedetails                               |
| Projektspezifisch| `projekt/images/`                 | Aufstellpläne, Abnahmefotos, Kundenlogo      |

Formate: SVG/PDF für Zeichnungen (vektoriell), JPG für Fotos (max 2000px, 85% Qualität).

## Build-Prozess

```
anlage.json ──→ build.py
                  │
                  ├─ Phase 1: Konfiguration einlesen, Versionscheck
                  ├─ Phase 2: Abhängigkeiten auflösen (meta.yaml, transitiv)
                  │           Overrides anwenden (Projekt > Base)
                  │           Fehlende Module/Bilder/Übersetzungen melden
                  ├─ Phase 3: Sphinx-Quellen generieren (index.rst, toctrees)
                  │           Glossar aus CSV erzeugen
                  │           Jinja2-Templates mit Projektdaten füllen
                  └─ Phase 4: sphinx-build -b latex → pdflatex → PDF (pro Sprache)

Ausgabe:
  _output/P-2026-0042_Dokumentation_DE.pdf
  _output/P-2026-0042_Documentation_EN.pdf
```

## Sphinx-Extensions (zu implementieren)

### anlagen_builder.py
- Liest anlage.json + meta.yaml aller referenzierten Module
- Löst Abhängigkeiten auf (topologisch, transitiv)
- Generiert toctree-Einträge pro Kapitel
- Wendet Override-Logik an

### localized_figure.py
- Neue Direktive `.. localized-figure::` 
- Löst Bildpfad nach Build-Sprache auf
- Fallback: `de` wenn Sprachversion fehlt

### glossary_loader.py
- Liest `terms.{lang}.csv` (Semikolon-getrennt)
- Erzeugt `.. glossary::` Blöcke
- Ermöglicht `:term:` Verlinkung im gesamten Dokument

## Hilfsskripte

- `scripts/dxf2svg.py` – DXF → SVG Konvertierung (ezdxf)
- `scripts/optimize_images.py` – Bildoptimierung vor Commit (Pillow, max 2000px)
- `scripts/validate_modules.py` – Prüft meta.yaml-Konsistenz, fehlende Dateien/Übersetzungen

## Infrastruktur

- Hetzner-Server: Gitea (Repos), n8n (CI-Automatisierung), Nextcloud (Dateiablage)
- Build-Umgebung: Python 3.11+, Sphinx, LaTeX-Distribution (texlive)
- CI: Gitea Actions oder n8n-Webhook → Build → PDF nach Nextcloud

## Umsetzungsphasen

### Methodik (nach Alistair Cockburn)

Jeder Use Case durchläuft sieben Schritte bis zur Umsetzungsreife:

| Schritt | Aktivität                                              | Verantwortung |
|---------|--------------------------------------------------------|---------------|
| 1       | Titel / Teaser, Prosa-Story                            | C (Kunde/PO)  |
| 2       | Stakeholder & Interessen / Anwender-Ziele identifizieren | T (Dev Team)  |
| 3       | Standard-Ablauf entwerfen (primäres Erfolgsszenario)   | M (Member)    |
| 4       | Ausnahmen und Erweiterungen sammeln                    | T (Dev Team)  |
| 5       | Ausnahmen detaillieren, Schneiden in User Stories      | M (Member)    |
| 6       | Business Value schätzen / Aufwand schätzen             | T (Dev Team)  |
| 7       | Review: Prüfe alle Interessen, Definition of Ready     | C (Kunde/PO)  |

**Legende Verantwortung:**
- **C** = Kunde / Product Owner (N.Sch, M.Ro)
- **T** = Dev Team (F.Ve, A.Sch, M.St, D.Fe)
- **M** = Einzelnes Dev Team Member

### Personen

| Kürzel | Rolle                  | Schwerpunkt           |
|--------|------------------------|-----------------------|
| N.Sch  | Stakeholder / PO       | Fachliche Anforderungen |
| M.Ro   | Stakeholder / PO       | Fachliche Anforderungen |
| F.Ve   | Dev Team               | IT und KI             |
| A.Sch  | Dev Team               | Redaktion / Inhalte   |
| M.St   | Dev Team               | IT und KI             |
| D.Fe   | Dev Team               | Redaktion / Inhalte   |

### Produktprogramm-Umfang

Basis für die Aufwandsschätzung: **1388 eindeutige Produktnummern** in 70 Produktgruppen über 5 Produktfamilien (CPC, GERÜST, ILS 2100, OMNIFLO, Trolleyprogramm). 129 Nummern erscheinen in mehreren Kapiteln.

### Projektplan

| Phase | Beschreibung | Aufwand | Beteiligte |
|-------|--------------|---------|------------|
| 0 | **Use-Case-Definition & Anforderungen** | | |
| 0.1 | Story & Teaser: Zieldokumentation beschreiben, Prosa-Story je Produktfamilie | 2 Tage | D.Fe, A.Sch, M.St |
| 0.2 | Stakeholder-Analyse: Alle Akteure und deren Interessen/Ziele auflisten | 1 Tag | F.Ve, A.Sch, M.St, D.Fe |
| 0.3 | Standard-Ablauf entwerfen: Build-Pipeline, Redaktionsworkflow, Freigabeprozess | 2 Tage | M.St |
| 0.4 | Ausnahmen sammeln: Sonderfälle (Mehrfachverwendung der 129 Nummern, Varianten, fehlende Übersetzungen) | 1 Tag | F.Ve, A.Sch, M.St, D.Fe |
| 0.5 | Ausnahmen detaillieren, in User Stories schneiden | 2 Tage | F.Ve, M.St |
| 0.6 | Aufwandsschätzung & Business Value für alle Stories | 1 Tag | F.Ve, A.Sch, M.St, D.Fe |
| 0.7 | Review & DOR: Prüfung aller Interessen, Freigabe für Umsetzung | 1 Tag | N.Sch, M.Ro |
| | | | |
| 1 | **PoC: Proof of Concept** | | |
| 1.1 | Ein Modul (z.B. OMNIFLO Weiche), ein Kapitel, zwei Sprachen (DE/EN), PDF-Ausgabe | 3 Tage | M.St, F.Ve |
| 1.2 | LaTeX-Template mit Firmen-CI erstellen und validieren | 2 Tage | M.St, F.Ve, A.Sch |
| 1.3 | PoC-Review mit Stakeholdern | 0,5 Tage | N.Sch, M.Ro, A.Sch |
| | | | |
| 2 | **Base-Repo & Infrastruktur** | | |
| 2.1 | Repo-Struktur anlegen (transport-docs-base), Sphinx-Projekt initialisieren | 1 Tag | M.St |
| 2.2 | Sphinx-Extensions implementieren (anlagen_builder, localized_figure, glossary_loader) | 4 Tage | M.St |
| 2.3 | build.py: JSON-Parsing, Abhängigkeitsauflösung, Override-Mechanismus | 3 Tage | F.Ve, M.St |
| 2.4 | CI/CD: Gitea Actions für automatischen Build | 2 Tage | M.St |
| | | | |
| 3 | **Produktprogramm-Strukturierung** | | |
| 3.1 | Modulstruktur & meta.yaml-Schema je Produktfamilie definieren (5 Familien) | 3 Tage | A.Sch, M.St, D.Fe |
| 3.2 | Nummernkreis-Mapping: 1388 Produkte auf Module abbilden, Gruppierung festlegen | 3 Tage | A.Sch, F.Ve, M.St |
| 3.3 | Vorlage-Templates pro Kapiteltyp erstellen (Beschreibung, Wartung, Ersatzteile) | 2 Tage | A.Sch, M.St |
| | | | |
| 4 | **Content-Migration (Hauptaufwand)** | | |
| 4.1 | CPC-Familie: 126 Produkte in 11 Gruppen – rST-Bausteine erstellen | 2 Wochen | A.Sch, F.Ve |
| 4.2 | GERÜST-Familie: 263 Produkte in 14 Gruppen – rST-Bausteine erstellen | 1 Wochen | A.Sch, F.Ve |
| 4.3 | ILS 2100-Familie: 396 Produkte in 27 Gruppen – rST-Bausteine erstellen | 3 Wochen | A.Sch, F.Ve |
| 4.4 | OMNIFLO-Familie: 453 Produkte in 14 Gruppen – rST-Bausteine erstellen | 4 Wochen | A.Sch, F.Ve |
| 4.5 | Trolleyprogramm: 191 Produkte in 4 Gruppen – rST-Bausteine erstellen | 2 Wochen | A.Sch, F.Ve |
| 4.6 | KI-gestützte Textgenerierung: Vorlagen automatisiert befüllen (Beschreibungen, techn. Daten, Logische Schalter) | parallel | F.Ve, M.St |
| 4.7 | Bildmaterial: Fotos/Zeichnungen zuordnen, optimieren, Pfadstruktur aufbauen | parallel | A.Sch, F.Ve |
| | | | |
| 5 | **Glossar & Mehrsprachigkeit** | | |
| 5.1 | Glossar DE aufbauen (Fachbegriffe aus allen 5 Produktfamilien) | 1 Woche | A.Sch, D.Fe, M.St |
| 5.2 | Glossar EN übersetzen | 1 Woche | A.Sch, D.Fe, M.St, V.Fe |
| 5.3 | Stichproben-Übersetzung: 10% der Module auf EN migrieren | 2 Wochen | A.Sch, D.Fe, F.Ve |
| | | | |
| 6 | **ERP-Integration & Automatisierung** | | |
| 6.1 | JSON-Export-Format mit ERP abstimmen (anlage.json-Schema) | 2 Tage | M.St, A.Jakob |
| 6.2 | Validierungsskripte: meta.yaml-Konsistenz, fehlende Dateien/Übersetzungen | 2 Tage | M.St |
| 6.3 | Hilfsskripte: dxf2svg, optimize_images | 2 Tage | F.Ve |
| | | | |
| 7 | **Pilotprojekt** | | |
| 7.1 | Erste vollständige Anlagendokumentation (reales Kundenprojekt) generieren | 1 Woche | A.Sch, M.St, F.Ve |
| 7.2 | Review mit Stakeholdern, Korrekturrunde | 3 Tage | N.Sch, M.Ro, A.Sch |
| 7.3 | Lessons Learned, Backlog-Pflege | 1 Tag | F.Ve, A.Sch, M.St, D.Fe |

### Aufwandszusammenfassung

| Phase | Dauer (geschätzt) |
|-------|-------------------|
| 0 – Use-Case-Definition | ~2 Wochen |
| 1 – PoC | ~1 Woche |
| 2 – Base-Repo & Infrastruktur | ~2 Wochen |
| 3 – Produktprogramm-Strukturierung | ~2 Wochen |
| 4 – Content-Migration | ~10-12 Wochen (2 Redakteure parallel + KI-Unterstützung) |
| 5 – Glossar & Mehrsprachigkeit | ~4 Wochen |
| 6 – ERP-Integration | ~1 Woche |
| 7 – Pilotprojekt | ~2 Wochen |
| **Gesamt** | **~24 Wochen (6 Monate)** |

**Anmerkungen:**
- Phase 4 ist der Hauptaufwand. Bei 1388 Produkten und 2 Redakteurinnen (A.Sch, F.Ve) parallel ergibt sich ca. 10 Wochen netto für die Content-Erstellung.
- KI-gestützte Textgenerierung (F.Ve, M.St) kann den Aufwand in Phase 4 um geschätzt 30–50% reduzieren.
- Phasen 4, 5 und 6 können teilweise parallelisiert werden, wodurch die Gesamtlaufzeit auf ca. 5 Monate verkürzt werden kann.
- Die Schätzung basiert auf ~20 Produkte/Woche pro Redakteur bei mittlerer Komplexität (Beschreibung, techn. Daten, Wartungshinweise als rST-Bausteine).

## Coding-Konventionen

- Python: Type Hints, Docstrings, pyright-kompatibel
- rST: Eine Datei pro Section, Dateiname = Section-Slug
- YAML: 2 Spaces Einrückung, keine Tabs
- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`)
- Bilder: Dateinamen lowercase, Underscores, beschreibend (`weiche_typ_a_foto_01.jpg`)
