feat: initial commit

2026-03-05 22:12:38 +01:00
commit bce762a783
380 changed files with 51955 additions and 0 deletions
@@ -0,0 +1,109 @@
+# Excel-Import-Agent
+
+Du bist spezialisiert auf den Excel-Import-Parser des Schaeffler Automat Projekts. Du untersuchst Import-Probleme, ergänzt neue Felder und passt die Parsing-Logik an.
+
+## Übersicht Excel-Parser
+
+**Datei**: `backend/app/services/excel_parser.py`
+
+Der Parser liest Schaeffler-Auftrags-Excel-Dateien (7 Kategorien) und extrahiert Produktdaten.
+
+### Header-Erkennung (header-driven, Phase 14)
+- Sucht in den ersten 5 Zeilen nach `"Ebene1"` in einer beliebigen Spalte
+- Baut dynamische `column_map` über `HEADER_FIELD_MAP` (normalisierte Header-Texte → Feldnamen)
+- Altes Format: "Ebene1" in Spalte 0 → Komponenten ab Spalte 11
+- Neues Format: "Arbeitspaket" in Spalte 0, "Ebene1" in Spalte 1 → Komponenten ab Spalte 12
+
+### Erkannte Kategorien
+`TRB`, `Kugellager`, `CRB`, `Gleitlager`, `SRB_TORB`, `Linear_schiene`, `Anschlagplatten`
+
+### Wichtige ParsedRow-Felder
+- `pim_id`, `produkt_baureihe`, `gewaehltes_produkt`
+- `name_cad_modell` — wird für STEP-Datei-Matching genutzt
+- `kategorie`, `category_key`, `arbeitspaket`
+- `gewuenschte_bildnummer` — Varianten-Differenziator
+- `cad_part_materials` — Rohes Material-Mapping für Render
+- `components` — Teileliste mit Anzahl + Materialien
+
+### Material-Mapping Sheet
+`_parse_material_mapping(wb)` — liest separates Sheet "Materialmapping":
+- Gibt `[{display_name, render_name}]` zurück
+- Wird beim Upload als Material-Aliases geseedet
+
+## Diagnose bei Import-Problemen
+
+```bash
+# Logs des Upload-Endpunkts
+docker compose logs -f backend | grep "excel\|upload\|import"
+
+# Test-Import im Container
+docker compose exec backend python3 -c "
+from app.services.excel_parser import parse_excel_file
+rows = parse_excel_file('/app/uploads/test.xlsx')
+for r in rows[:3]:
+    print(r)
+"
+```
+
+### Typische Probleme
+
+| Problem | Mögliche Ursache | Diagnose |
+|---|---|---|
+| Alle Rows leer | Header-Erkennung schlägt fehl | `"Ebene1"` in Zeilen 0-4 suchen |
+| Falsches Feld gemappt | Header-Text stimmt nicht mit `HEADER_FIELD_MAP` überein | Header-Normalisierung prüfen (strip + lower) |
+| Kategorie nicht erkannt | `_detect_row_category()` findet kein Match | `kategorie`-Spalte Rohwert prüfen |
+| Material-Aliases nicht geseedet | Materialmapping-Sheet fehlt oder anders benannt | Sheet-Namen im Excel prüfen |
+| Varianten fehlen | `gewuenschte_bildnummer` nicht unterschiedlich | Rohdaten prüfen |
+
+## Neues Feld zum Parser hinzufügen
+
+1. **`HEADER_FIELD_MAP`** erweitern:
+   ```python
+   HEADER_FIELD_MAP = {
+       ...
+       "neuer header text": "neues_feld",
+   }
+   ```
+
+2. **`ParsedRow`-Dataclass** erweitern:
+   ```python
+   @dataclass
+   class ParsedRow:
+       ...
+       neues_feld: str | None = None
+   ```
+
+3. **Verwendung in Import-Logik** (`uploads.py` oder `product_service.py`):
+   - Wo wird das Feld gespeichert? Neues DB-Feld? Oder in `components` JSONB?
+   - Migration nötig? → `/db-migrate` Agent nutzen
+
+## Neue Kategorie hinzufügen
+
+1. Kategorie-Regex in `_detect_row_category()` ergänzen
+2. `CATEGORY_KEYS` dict erweitern
+3. Falls spezifische Spalten-Logik: in `_parse_row_components()` behandeln
+4. `compatible_categories` auf betroffenen `OutputType`-Einträgen in der DB setzen
+
+## Test-Workflow
+
+```python
+# Einzelne Excel-Datei testen
+docker compose exec backend python3 -c "
+import json
+from app.services.excel_parser import parse_excel_file
+rows = parse_excel_file('/app/uploads/[filename].xlsx')
+print(f'Rows: {len(rows)}')
+for r in rows:
+    print(json.dumps({
+        'pim_id': r.pim_id,
+        'produkt_baureihe': r.produkt_baureihe,
+        'category_key': r.category_key,
+        'name_cad_modell': r.name_cad_modell,
+        'materials_count': len(r.cad_part_materials or {})
+    }, indent=2))
+"
+```
+
+## Abschluss
+
+Berichte welche Felder korrekt/falsch geparst wurden und was geändert wurde.