Assessor_2.0/docs/RECOGNITION_ENGINE.md

Erkennungs- und Mapping-Engine

Stand: 2026-07-17
Ergebnisversion: 1

Zweck

Die Erkennungsengine bewertet ein ImportDocument, bevor werkzeugspezifische Darstellung oder Normalisierung erfolgt. Sie erkennt wahrscheinliche Quellwerkzeuge, relevante Tabellen und semantische Spaltenrollen. Jede Entscheidung bleibt nachvollziehbar und korrigierbar.

Ergebnis

Ein ImportRecognitionResult enthält:

• ausgewähltes Quellwerkzeug und alternative Kandidaten
• Tabellenrelevanz und automatische Tabellenauswahl
• vorgeschlagene und tatsächlich angewendete Feldrollen
• numerischen Score, Konfidenzklasse und Begründungen
• einzelne Evidenzsignale mit ihrem Scorebeitrag
• Entscheidungsquelle automatic, user-confirmed oder fallback
• Kennzeichnung, ob eine Bestätigung erforderlich ist

Das verbindliche Schema steht in src/domain/import-recognition.ts. Die deterministische Auswertung befindet sich in src/recognition/recognition-engine.ts.

Konfidenzklassen

Score	Klasse	Verhalten
0,82 bis 1,00	high	automatische Anwendung
0,62 bis unter 0,82	medium	automatische Anwendung mit sichtbarem Hinweis in einer späteren UI-Phase
0,35 bis unter 0,62	low	nur Vorschlag; Bestätigung erforderlich
unter 0,35	unknown	keine semantische Anwendung; Originalfeld bleibt additional

Erkennungssignale

Quelle

• Dateiname
• Inhalt beziehungsweise Werkzeugmarker
• Tabellen- und Sheetnamen
• Kopfzeilen
• typische Zellwerte und Regel-IDs
• Kombination mehrerer voneinander unabhängiger Signale

Die aktuelle Signaturbasis erkennt Purple Knight, PingCastle, CIS-CAT und Maester. Ein einzelner schwacher Marker reicht bewusst nicht für eine sichere Werkzeugzuordnung.

Tabellenrelevanz

• Tabellenname
• vorhandene Datenzeilen
• Anzahl sicher erkannter semantischer Rollen
• Kombination aus Finding-Identität und Bewertung
• negative Signale für Zusammenfassungen, Profile oder reine Metadaten

Eine nicht ausgewählte Tabelle wird nicht gelöscht. Sie bleibt vollständig im ImportDocument und im bisherigen Dataset verfügbar.

Feldrollen

Unterstützte Rollen entsprechen dem kanonischen Modell:

• Regel-ID, Titel und Beschreibung
• Kategorie
• Schweregrad und Status
• Score
• Asset beziehungsweise betroffenes Objekt
• Evidenz und Empfehlung
• Frameworkreferenz
• additional als verlustfreier Fallback

Die Engine kombiniert Kopfzeilensynonyme mit Werteform, Werteverteilung, erkanntem Datentyp und Textlänge. Alternative Rollen werden mit eigenen Scores aufbewahrt.

Bestätigung und Korrektur

applyRecognitionOverrides kann Quelle, Tabellenauswahl und Feldrollen ausdrücklich bestätigen oder korrigieren. Bestätigte Werte erhalten die Entscheidungsquelle user-confirmed, volle Konfidenz und benötigen keine weitere Bestätigung. Die importierten Zeilen und Rohwerte werden dabei nicht verändert.

Die Benutzeroberfläche für diese Korrekturen folgt mit Importvorschau und Mappingdialog in einer späteren Workflowphase. Die fachliche Korrekturschnittstelle ist bereits plattformneutral vorhanden.

Integration und Abgrenzung

Die plattformneutrale Importengine speichert das Erkennungsergebnis im ImportedDataset. Ein mit hoher oder mittlerer Konfidenz erkanntes Werkzeug wird als scanTool angezeigt. Bestehende Importprofile bleiben weiterhin für Sortierung, Filter und Darstellung zuständig.

Phase 6 überführt die Werkzeugsignaturen und Darstellungsregeln in vollständig deklarative, versionierte Toolprofile. Phase 7 verwendet die erkannten Rollen anschließend für automatische Filter und Darstellung.