# 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.