Add RollCalc JSON importer

2026-07-29 11:31:17 +02:00
parent 6c07d1cc7b
commit be599d28b3
8 changed files with 569 additions and 4 deletions
@@ -0,0 +1,60 @@
+# Importer
+
+## RollCalc-JSON-Importer
+
+Der RollCalc-JSON-Importer liest die bestehende RollCalc-Datei `article-data.json` ein und überführt gültige Datensätze in typisierte `RollCalcArticle`-Objekte.
+
+Öffentliche API:
+
+```python
+from pathlib import Path
+
+from article_data_manager.importers.rollcalc_json import load_rollcalc_articles
+
+articles = load_rollcalc_articles(Path("data/source/rollcalc/article-data.json"))
+```
+
+## Eingabeformat
+
+Erwartet wird eine UTF-8-Datei mit einem JSON-Array. Jeder Array-Eintrag muss ein JSON-Objekt sein.
+
+Pflichtfelder:
+
+- `nr`
+- `name`
+- `thickness`
+- `area_weight`
+- `core_type`
+
+Datentypen:
+
+- `nr`: String, nicht leer, ohne führende oder nachgestellte Leerzeichen
+- `name`: String
+- `thickness`: JSON-Zahl, kein Boolean
+- `area_weight`: JSON-Zahl, kein Boolean
+- `core_type`: JSON-Zahl, kein Boolean
+
+Integer-Zahlen aus JSON werden intern als Python-`float` gespeichert, sofern sie in numerischen Feldern stehen. Strings wie `"6.722"`, `null` und Booleans werden nicht als Zahlen akzeptiert.
+
+## Unbekannte Felder
+
+Zusätzliche unbekannte Felder werden akzeptiert und ignoriert. Sie werden nicht in das aktuelle interne Modell übernommen. Dadurch bleibt der Importer kompatibel mit möglichen RollCalc-Erweiterungen, validiert die bekannten Felder aber weiterhin strikt.
+
+## Dubletten
+
+Doppelte Artikelnummern innerhalb einer Datei sind ein Validierungsfehler. Maßgeblich ist die exakte Stringdarstellung, daher sind `"00001"` und `"1"` unterschiedliche Artikelnummern.
+
+## Fehlerverhalten
+
+Der Importer verwendet eigene Exceptions:
+
+- `RollCalcImportError`
+- `RollCalcFileError`
+- `RollCalcJsonSyntaxError`
+- `RollCalcValidationError`
+
+Fehlermeldungen enthalten Datei, Datensatzindex und Feldname, soweit anwendbar. Vollständige Datensätze werden nicht in Fehlermeldungen ausgegeben.
+
+## Quelldatei
+
+Der Importer liest die Quelldatei nur. Er schreibt, verändert oder repariert die Datei nicht und erzeugt keine Ausgabe auf stdout oder stderr.