Tabelle für Umsetzungsphasen und Coding Conventions in docu dazu. Projektübersicht und erster Wurf für Folder rein

doc/Kernkonzepte.md

@@ -1,5 +1,162 @@
 # 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.
@@ -220,3 +377,28 @@ Ausgabe:
 - `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
+
+| Phase | Beschreibung                                                  | Aufwand   |
+|-------|---------------------------------------------------------------|-----------|
+| 1     | PoC: Ein Modul, ein Kapitel, zwei Sprachen, PDF               | 2–3 Tage  |
+| 2     | Base-Repo aufsetzen: Sphinx, Extensions, LaTeX-CI             | 3–5 Tage  |
+| 3     | Erste 5–10 Module migrieren, Glossar aufbauen                 | 1–2 Wochen|
+| 4     | JSON-Export aus ERP definieren, build.py fertigstellen         | 2–3 Tage  |
+| 5     | Pilotprojekt: Erste vollständige Anlagendokumentation         | 1 Woche   |
+| 6     | CI/CD: Automatischer Build via Gitea Actions oder n8n         | 1–2 Tage  |
+
+## 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`)