503 lines
21 KiB
Markdown
503 lines
21 KiB
Markdown
# 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`)
|