Initialize Article Data Manager project

2026-07-29 10:53:21 +02:00
commit 83639b9957
51 changed files with 1100 additions and 0 deletions
@@ -0,0 +1,58 @@
+# Architektur
+
+## Systemkontext
+
+Article Data Manager ist ein lokales Werkzeug zur Erzeugung einer RollCalc-kompatiblen `article-data.json`. RollCalc ist ein externer Konsument und bleibt technisch getrennt.
+
+## Verantwortlichkeiten
+
+- Import vorhandener RollCalc-Artikeldaten.
+- Import eines ERP-CSV-Exports.
+- Import manuell gepflegter Zusatzdaten.
+- Normalisierung technischer Formate, ohne fachliche Bedeutungen zu erraten.
+- Validierung und Konflikterkennung.
+- Deterministischer Export fuer RollCalc.
+- Reports fuer Treffer, Nicht-Treffer, Konflikte und Validierungsfehler.
+
+## Modulgrenzen
+
+- `models`: interne Datenmodelle.
+- `importers`: Lesen von JSON- und CSV-Quellen.
+- `validation`: Format-, Typ- und Fachvalidierung.
+- `merge`: Merge-Regeln, Konflikterkennung und Prioritaeten.
+- `exporters`: Ausgabe der RollCalc-kompatiblen JSON-Datei.
+- `cli`: spaetere Kommandozeile.
+
+## Datenfluss
+
+```text
+data/source/erp/production-key-data.csv
+data/source/rollcalc/article-data.json
+data/manual/article-manual-data.csv
+        |
+        v
+Import -> Normalisierung -> Validierung -> Merge -> Export
+        |
+        +--> data/reports/
+        +--> data/generated/article-data.json
+```
+
+## Datentrennung
+
+Quelldaten, manuelle Daten und generierte Daten bleiben physisch und logisch getrennt. Produktive Dateien in `data/` und `incoming/` werden nicht versioniert.
+
+## Erweiterbarkeit
+
+Weitere Quellen sollen als eigene Importer angebunden werden. Jede Quelle muss Originalfeldnamen, Einheiten, Prioritaet und Konfliktverhalten dokumentieren.
+
+## Spaetere Weboberflaeche
+
+Eine lokale Weboberflaeche ist erst nach einem reproduzierbaren CLI-Merge sinnvoll. Sie soll manuelle Zusatzdaten pflegen, ERP-Werte anzeigen und Eingaben validieren, aber keine Quelldaten direkt ueberschreiben.
+
+## Spaetere Datenhaltung
+
+Phase 4 kann SQLite als lokale Datenbasis einfuehren. PostgreSQL ist nur sinnvoll, wenn Mehrbenutzerbetrieb, zentrale Freigaben oder Integrationen dies tatsaechlich erfordern.
+
+## RollCalc als externer Konsument
+
+RollCalc konsumiert ausschliesslich die exportierte `article-data.json`. Aenderungen am Ausgabeformat muessen mit der RollCalc-Kompatibilitaet abgeglichen und dokumentiert werden.