eigenes Kapitel zu den möglicherweise auftreteneden Fehlerfällen und deren Ursachen erstellt

2025-12-02 12:43:09 +01:00
parent a869b52406
commit c5f4aafcca
1 changed files with 77 additions and 0 deletions
@@ -173,6 +173,83 @@ Dieses Worksheet gibt für jede Artikelnummer aus, **welchem Unterverteiler (UV)

 Hinweis: Diese Ansicht ist besonders nützlich zur **vorbereitenden Bestellplanung pro UV**.

+# Fehlerfälle und Fehlerbehandlung
+
+## Übersicht
+
+Das Programm führt während der Verarbeitung umfassende Validierungen durch und erkennt verschiedene Arten von Fehlern im Layout. Falls Fehler auftreten, schreibt `getpositions` **automatisch** eine JSON-Datei mit allen erkannten Fehlern und Warnungen in den `work`-Ordner. Diese Datei hat den Namen `*_errors.json` (wobei `*` der Name der verarbeiteten DXF-Datei ist).
+
+Die Fehlerbehandlung unterscheidet zwischen zwei Kategorien:
+
+- **Fehler (errors)**: Schwerwiegende Probleme, die die Korrektheit der Ausgabe beeinträchtigen oder zum Abbruch führen
+- **Warnungen (warnings)**: Hinweise auf potenzielle Probleme, die Programm kann aber fortfahren
+
+Im Ordner [testdata/](testdata/) finden sich Beispiel-DXF-Dateien, die gezielt bestimmte Fehlerfälle demonstrieren (z.B. [easy_3tunnels_errors.json](testdata/easy_3tunnels_errors.json), [easy_tunnelerror1.json](testdata/easy_tunnelerror1.json)).
+
+## Fehlertypen und ihre Bedeutung
+
+Die folgende Tabelle zeigt alle möglichen Fehler- und Warnungstypen, die von `getpositions.py` erkannt werden:
+
+| Fehlertyp | Kategorie | Beschreibung | Ursache | Behebung | Code-Zeile |
+|-----------|-----------|--------------|---------|----------|------------|
+| `double_ids` | Fehler | Mehrere Blöcke haben dieselbe ID (z.B. MA0062@1) | Doppelte Bauteile mit identischer Kennzeichnung und SPS-Präfix im Layout | IDs eindeutig vergeben oder doppelte Blöcke entfernen | 373-374 |
+| `missing_attributes` | Warnung | Block hat fehlende oder unvollständige Attribute | Block enthält z.B. nur A, B, C, ARTINR aber keine SPS-, IO- oder KENNZEICHNUNG-Attribute | Fehlende Attribute im DXF-Block ergänzen (z.B. SPS, KENNZEICHNUNG) | 362, 376 |
+| `missing_distributors` | Fehler | Unterverteiler in KENNZEICHNUNG erwähnt aber nicht im Layout | Sensor verweist auf UV (z.B. UH01) in KENNZEICHNUNG, aber UV-Symbol fehlt im Layout | Unterverteiler-Block im Layout positionieren oder KENNZEICHNUNG korrigieren | 818 |
+| `missing_sensors` | Fehler | Sensor/Aktor nicht gefunden | Sensor wird in Mappings referenziert, aber Block fehlt oder hat ungültige Attribute | Sensor-Block im Layout ergänzen oder fehlerhafte Attribute korrigieren | 824 |
+| `missing_tunnel` | Fehler | Tunnel hat weniger als 2 Positionen | Tunnel-Eingang oder -Ausgang fehlt (TUNNEL-Block oder MTEXT mit Muster `TUNNEL<nr>-<länge>`) | Zweiten Tunnel-Eingang/Ausgang im Layout ergänzen | 831 |
+| `overdefined_tunnel` | Fehler | Tunnel hat mehr als 2 Positionen | Mehr als zwei TUNNEL-Blöcke mit demselben Namen (z.B. TUNNEL2 dreimal) | Überzählige Tunnel-Positionen entfernen | 835 |
+| `mapping_warnings` → `keine KENNZEICHNUNG vorhanden` | Warnung | KENNZEICHNUNG-Attribut fehlt komplett | Block hat kein KENNZEICHNUNG-Attribut | KENNZEICHNUNG-Attribut im Format `=<Anlage>+<UV>-<Karte>` ergänzen | 472 |
+| `mapping_warnings` → `Ungültiger Pfad in Kennzeichnung` | Warnung | KENNZEICHNUNG hat falsches Format | Trennzeichen `+`, `-` oder `=` fehlen oder falsch positioniert | KENNZEICHNUNG-Format korrigieren (z.B. `=A01+UH01-KF1DQ04`) | 486, 489 |
+| `missing_sps_prefix` | Fehler | SPS-Präfix fehlt für Block-ID | Beim Zusammenführen von Blöcken fehlt der SPS-Präfix | SPS-Attribut in Block ergänzen | 430 |
+
+## Struktur der Error-JSON-Datei
+
+Die `*_errors.json`-Datei ist wie folgt strukturiert:
+
+```json
+{
+  "errors": {
+    "missing_distributors": ["UH02", "UC05"],
+    "overdefined_tunnel": ["TUNNEL2"],
+    ...
+  },
+  "warnings": {
+    "missing_attributes": {
+      "BX0101": "Nur ein Block und/oder fehlende Attribute: dict_keys([...])"
+    },
+    "mapping_warnings": {
+      "MA0099": "keine KENNZEICHNUNG vorhanden"
+    }
+  }
+}
+```
+
+Jeder Fehlertyp enthält entweder:
+- Eine **Liste** von betroffenen IDs/Namen (z.B. `["UH02", "UC05"]`)
+- Ein **Dictionary** mit IDs als Keys und detaillierten Beschreibungen als Values
+
+## Arbeiten mit Fehlerfällen
+
+**Empfohlene Vorgehensweise:**
+
+1. **Programm ausführen** – Das Programm läuft auch bei Fehlern durch und erstellt soweit möglich Ausgaben
+2. **Error-Datei prüfen** – Falls `*_errors.json` erstellt wurde, enthält sie alle erkannten Probleme
+3. **Fehler beheben** – Layout gemäß Tabelle oben korrigieren
+4. **Erneut ausführen** – Nach Korrektur sollte keine Error-Datei mehr erstellt werden
+
+**Hinweis:** Die Error-Datei wird **nur dann** erstellt, wenn tatsächlich Fehler oder Warnungen erkannt wurden. Fehlt die Datei, ist die Verarbeitung fehlerfrei verlaufen.
+
+## Beispiele aus Testdaten
+
+Im Ordner [testdata/](testdata/) befinden sich mehrere Beispieldateien, die gezielt Fehlerfälle demonstrieren:
+
+| DXF-Datei | Fehlertyp | Beschreibung |
+|-----------|-----------|--------------|
+| [easy_tunnelerror1.dwg](testdata/easy_tunnelerror1.dwg) | `overdefined_tunnel`, `missing_attributes` | TUNNEL2 hat 3 Positionen statt 2; Block BX0101 hat fehlende Attribute |
+| [easy_3tunnels.dxf](testdata/easy_3tunnels.dxf) | Diverse Tunnel-Fehler | Demonstriert verschiedene Tunnel-Konfigurationen |
+
+Diese Testdateien können als Referenz dienen, um Fehler im eigenen Layout zu verstehen und zu beheben.
+
 # Anpassung des Verhaltens des Programms:

 ## Verwendete Konfigurationsdateien