klassifikationspflege

Klassifikationsnummern-Pflege

Wartungs-Workflow für die klassifikationsnummern-Tabelle in Contradoo. Neue Klassifikationsnummern werden beim EDI-Import automatisch angelegt, oft ohne category_id. Fehlende Kategorien führen dazu, dass CostOverviewService::shouldShowInCostTable() diese ignoriert und Kostenpositionen in der PDF-Kostenübersicht fehlen.

Workflow

Phase 1: Unkategorisierte finden

Tinker-Abfrage ausführen, um alle Einträge ohne category_id zu identifizieren:

$uncategorized = \App\Models\Klassifikationsnummer::whereNull('category_id')->count();

Falls 0: Dem User mitteilen, dass keine offenen Einträge existieren. Workflow beenden.

Phase 2: Einträge gruppieren

Drei Gruppen unterscheiden:

ELMO-Format (Telekom) — 12-stellige numerische ELMONUMBER (z.B. 010000046989):

->whereRaw("\"ELMONUMBER\" ~ '^[0-9]{12}$'")

Text-basiert (O2/Vodafone) — ELMOTEXT-basierte Nummern mit Datums-/Lizenz-Suffixen.

Leer — Leerer ELMOTEXT (Kundennummern etc.), in der Regel irrelevant.

Phase 3: Automatisches Matching

ELMO-Format Matching

Referenz-Einträge anhand von ELMONUMBER-Prefix und Namensmustern finden:

Prefix	Typische Kategorie	type-Flag
010	2 (Basispreise) oder 10 (Optionspreise)	tariff=true oder costs=true
020	12 (Gebuchte Datenpässe) oder 31 (Datenpässe Roaming TZ)	costs=true
080	26 (Einmalige Gebühren)	costs=true
090	1 (Rabatte auf Basispreise) oder 8 (Rabatte auf Optionen)	tariffrebate=true oder costsrebate=true

Wichtig: Prefix allein reicht nicht! Immer einen kategorisierten Referenz-Eintrag mit ähnlichem ELMOTEXT suchen und die Zuordnung bestätigen:

$ref = \App\Models\Klassifikationsnummer::with('category')
    ->whereNotNull('category_id')
    ->where('ELMONUMBER', 'like', $prefix . '%')
    ->where('ELMOTEXT', 'like', '%' . substr($elmotext, 0, 20) . '%')
    ->first();

Text-basiertes Matching

ELMOTEXT bereinigen (Datums-Suffixe, Lizenzanzahlen, anteilige Tage entfernen) und dann die ersten 25 Zeichen gegen bestehende kategorisierte Einträge vergleichen:

$clean = preg_replace('/\s*-\s*\d{2}\.\d{2}\.\d{4}$/', '', $text);
$clean = preg_replace('/\s*\(?\d{2}\.\d{2}\.\d{4}\s*-\s*\d{2}\.\d{2}\.\d{4}\)?/', '', $clean);
$clean = preg_replace('/\s*\(anteilig \d+ Tage\)/', '', $clean);
$clean = preg_replace('/\s*\d+\s*Lizenz(en)?/', '', $clean);
$clean = preg_replace('/\s*\d+\s*Minute\(n\)/', '', $clean);
$clean = preg_replace('/\s*\d+\s*(MB|GB)/', '', $clean);
$short = substr(trim($clean), 0, 25);

$match = \App\Models\Klassifikationsnummer::with('category')
    ->whereNotNull('category_id')
    ->where('ELMOTEXT', 'like', $short . '%')
    ->first();

Phase 4: Ergebnisse dem User präsentieren

Übersichtliche Tabelle mit allen gefundenen Einträgen zeigen, gruppiert nach:

1. Sicher zuordenbar (ELMO mit Referenz-Match oder Text-Match) — mit vorgeschlagener Kategorie
2. Nicht zuordenbar (kein Referenz-Match) — manuell zu prüfen
3. Irrelevant (leerer ELMOTEXT)

Dem User die Zahlen und vorgeschlagenen Zuordnungen zeigen. Erst nach User-Bestätigung weiter.

Phase 5: Migration erstellen

Nach Bestätigung eine Laravel-Migration generieren mit folgenden Anforderungen:

• Branch: hotfix/fix-missing-klassifikationsnummer-categories (oder ähnlich)
• Idempotent: Nur updaten wenn category_id IS NULL
• Abgesichert gegen frische DBs: Prüfen ob Tabelle und IDs existieren
• Reversibel: down() setzt category_id auf NULL zurück
• Dokumentiert: Docblock mit Root Cause, betroffenen Einträgen, und Referenz-Quellen

Migrations-Template:

public function up(): void
{
    if (! DB::getSchemaBuilder()->hasTable('klassifikationsnummern')) {
        return;
    }

    $mappings = $this->getMappings();
    $existingIds = DB::table('klassifikationsnummern')
        ->whereIn('id', array_keys($mappings))
        ->whereNull('category_id')
        ->pluck('id')
        ->all();

    if (empty($existingIds)) {
        Log::info('Migration: No matching Klassifikationsnummern to fix');
        return;
    }

    $updated = 0;
    foreach ($existingIds as $id) {
        [$categoryId, $type] = $mappings[$id];
        DB::table('klassifikationsnummern')
            ->where('id', $id)
            ->update([
                'category_id' => $categoryId,
                'type' => json_encode($type),
                'updated_at' => now(),
            ]);
        $updated++;
    }

    Log::info("Migration: Fixed {$updated} Klassifikationsnummern");
}

Phase 6: Nach Deployment

Den User darauf hinweisen, dass nach dem Deployment die PDF-Kostenübersichten für betroffene Kunden neu generiert werden müssen. Betroffene EdiCostOverviews identifizieren durch Verknüpfung der gefixten Klassifikationsnummern mit EdiFactDocuments.

Kategorie-Referenz

ID	Name	Beschreibung
1	Rabatte auf Basispreise	Rabatte auf Tarif-Grundpreise
2	Basispreise	Tarif-Grundpreise (Mobilfunk, Festnetz)
8	Rabatte auf Optionen	Rabatte auf gebuchte Optionen
10	Optionspreise	Gebuchte Optionen/Zusatzpakete
12	Gebuchte Datenpässe	Datenpässe national
18	# INFOTEXT	Info-Texte, keine Kosten
21	# Undefiniert	Undefiniert, wird ausgeblendet
26	Einmalige Gebühren	Bereitstellung, Anschlusspreise
27	Drittanbieterkosten (brutto)	Kosten von Drittanbietern
31	Datenpässe Roaming (TZ)	Roaming-Datenpässe

Type-Flags

Jede Klassifikationsnummer hat ein type JSON-Feld mit 5 Flags:

Flag	Bedeutung	Wann true
tariff	Ist ein Tarif	Basispreise (010-Prefix)
costs	Kostenposition	Optionen, Einmalige, Datenpässe
costsrebate	Rabatt auf Kosten	Rabatte auf Optionen (090 + Option)
tariffrebate	Rabatt auf Tarif	Rabatte auf Basispreise (090 + Basis)
info	Nur Info	INFOTEXT-Kategorie

Wichtige Hinweise

• shouldShowInCostTable() prüft zuerst category_id != NULL, dann ob Kategorie in COST_CATEGORIES ist oder type.costs/type.costsrebate true ist
• Einträge mit category_id = NULL werden immer ignoriert — sie tauchen nie in Kostenübersichten auf
• Die klassifikationsnummern-Tabelle hat Soft Deletes (deleted_at)
• Alle Kategorien abrufbar via: \App\Models\KlassifikationsnummerCategory::all(['id', 'name'])