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