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,98 @@
+# Article Data Manager
+
+Article Data Manager ist ein eigenständiges Python-Projekt zur Pflege, Validierung und späteren Erzeugung der statischen `article-data.json` für den bestehenden Roll Calculator.
+
+Status: frühe Entwicklungsphase. Phase 0 legt Struktur, Dokumentation, Beispieldaten und erste technische Leitplanken an. Der produktive Merge-Prozess und eine Weboberfläche sind noch nicht implementiert.
+
+## Problemstellung
+
+Die Artikeldaten für RollCalc sollen langfristig aus mehreren Quellen nachvollziehbar zusammengeführt werden:
+
+- bestehende RollCalc-Artikeldaten
+- ERP-Export im CSV-Format
+- manuell gepflegte Zusatz- und Korrekturdaten
+- später weitere technische oder produktionsbezogene Quellen
+
+Das Projekt trennt Quelldaten, manuelle Daten und generierte Ergebnisse, damit keine stillen Datenkorrekturen oder unklare Überschreibungen entstehen.
+
+## Abgrenzung zum Roll Calculator
+
+Der Roll Calculator bleibt externer Konsument der erzeugten `article-data.json`. Article Data Manager wird nicht in das RollCalc-Repository integriert. Importlogik, Datenvalidierung, Merge-Regeln und Reports werden hier entwickelt, damit RollCalc nicht mit Datenpflege- und ERP-Komplexität belastet wird.
+
+## Datenfluss
+
+```text
+ERP-Export
+     +
+bestehende RollCalc-Daten
+     +
+manuelle Zusatzdaten
+     |
+     v
+Import -> Normalisierung -> Validierung -> Merge -> Export
+     |
+     +--> Reports
+     |
+     +--> article-data.json fuer RollCalc
+```
+
+## Verzeichnisstruktur
+
+```text
+src/article_data_manager/   Python-Paket
+tests/                      Tests und nicht vertrauliche Fixtures
+examples/                   reduzierte Beispieldaten
+data/source/                lokale echte Quelldaten, nicht versioniert
+data/manual/                lokale manuelle Daten, nicht versioniert
+data/generated/             generierte Artefakte, nicht versioniert
+data/reports/               Reports, nicht versioniert
+docs/                       Architektur, Datenmodell und Regeln
+scripts/                    spaetere Hilfsskripte
+```
+
+## Ausgangsdaten und Analyse
+
+Die lokalen Ausgangsdateien wurden unter `incoming/` gefunden und werden nicht versioniert:
+
+- `incoming/article-data_.json`
+- `incoming/Liste Schluesseldaten Produktion.csv`
+
+Beobachtungen:
+
+- RollCalc-JSON: 274 Artikel, Felder `nr`, `name`, `thickness`, `area_weight`, `core_type`.
+- `nr` ist im JSON durchgehend String; mindestens eine Artikelnummer beginnt mit `0`.
+- ERP-CSV: 1786 Datenzeilen, UTF-8 mit BOM, Delimiter `,`.
+- ERP-CSV enthaelt deutsche Dezimalzahlen wie `"6,00"` und Werte mit Punkt wie `1.548`.
+- `SL_ITEM_NO` ist in allen ERP-Zeilen befuellt; mindestens eine Artikelnummer beginnt mit `0`.
+- Es wurden 247 Artikelnummern mit mehrfachen ERP-Treffern erkannt. Die fachliche Bedeutung ist offen.
+
+## Installation
+
+Voraussetzung: Python 3.12 oder neuer.
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+## Geplante CLI-Nutzung
+
+```bash
+article-data-manager inspect-csv data/source/erp/production-key-data.csv
+article-data-manager merge
+article-data-manager validate data/generated/article-data.json
+```
+
+Die CLI-Kommandos sind in Phase 0 nur als Platzhalter vorgesehen.
+
+## Tests
+
+```bash
+ruff check .
+pytest
+```
+
+## Umgang mit produktiven ERP-Daten
+
+Produktive ERP-Exporte, RollCalc-Quelldateien, manuelle Arbeitsdateien, Reports und generierte Dateien duerfen nicht ungeprueft in Git eingecheckt werden. Versioniert werden nur anonymisierte oder reduzierte Beispiele und Fixtures.