Projektwissen/docs/tests/verfahrensgebiet-eigentuemersuche.md

# Testkonzept: Eigentümersuche im Tab „Eigentümer“

Plugin: `sn_verfahrensgebiet` · Stand: 06.10.2026 · Pflege: bei jeder Änderung an diesem Ablauf

## Worum es fachlich geht

Im Termin mit Eigentümern gleicht die Sachbearbeitung die gespeicherten Personendaten ab: Name, Anschrift und
E-Mail. Grundlage ist der Serienbriefexport als CSV-Datei, den die Sachbearbeitung von Hand ins Projekt lädt.
Sie sucht nach Name und/oder Vorname. Die Trefferliste fasst Einträge derselben Person mit derselben Anschrift
zusammen, denn im Export steht eine Person für jedes Eigentumskonto einmal. Dieselbe Person mit einer anderen
Anschrift bleibt ein eigener Eintrag. Damit fällt eine abweichende Anschrift sofort auf. Verstorbene und
Rechtspersonen sind in der Liste gekennzeichnet:
verstorben als Hinweis (`PER_VERSTORBEN` = 1), die Art der Person als Rohwert von `PER_RECHTSPERSON`
(0, 1, 5 oder 9; die Bedeutung der Werte wird später entschlüsselt).

Die Trefferliste sieht nur die Sachbearbeitung. Wie die gewählten Einträge dem Eigentümer angezeigt und korrigiert
werden, beschreibt [`verfahrensgebiet-eigentuemer-anzeige.md`](verfahrensgebiet-eigentuemer-anzeige.md).

## Der Ablauf

```mermaid
flowchart TD
    A["1 Anwender lädt den Serienbriefexport<br/>als CSV-Layer ins Projekt"] --> B["2 Eigentümerdatei wählen<br/>(nur Layer mit Nachname und Vorname)"]
    B --> C{"3 Eigentümerdatei<br/>gewählt?"}
    C -->|nein| D["Hinweis: CSV laden und wählen"]
    C -->|ja| E{"4 Name oder Vorname<br/>eingegeben?"}
    E -->|nein| F["Hinweis: Namen eingeben"]
    E -->|ja| G["5 Einträge suchen<br/>(Teilwort, Groß-/Kleinschreibung<br/>und Umlaute egal)"]
    G --> H["6 Gleiche Person mit gleicher<br/>Anschrift zusammenfassen"]
    H --> I{"7 Treffer?"}
    I -->|nein| J["Hinweis: keine Einträge<br/>(ohne den Namen zu wiederholen)"]
    I -->|ja| K["8 Trefferliste mit Anschrift, E-Mail,<br/>Rechtsperson-Wert, verstorben;<br/>Mehrfachauswahl"]

    style D fill:#fff4e6,stroke:#d9822b
    style F fill:#fff4e6,stroke:#d9822b
```

## Was geprüft wird

Die Tests liegen in `Plugin_SN_Verfahrensgebiet/tests/test_eigentuemer_suche.py` (Suchlogik),
`tests/test_eigentuemer_tab.py` (Bedienung, Trefferliste) und `tests/test_verfahrensgebiet_dialoge.py`
(gemeinsame Auswahltabelle).

| # | Schritt | Wird geprüft durch | Ebene |
|---|---|---|---|
| 2 | Nur Layer mit Nachname und Vorname, auch mit BOM oder anderer Schreibweise | `test_layer_mit_name_und_vorname_ist_eigentuemerlayer`, `test_eigentuemerlayer_im_projekt` | Mock |
| 3 | Keine Eigentümerdatei gewählt | `test_ohne_eigentuemerdatei_warnung` | Mock |
| 3 | Layer ohne die nötigen Spalten | `test_layer_ohne_pflichtspalten` | Mock |
| 4 | Ohne Eingabe keine Komplettliste | `test_ohne_eingabe_fehler`, `test_suchfehler_als_warnung` | Mock |
| 5 | Teilwort, Groß-/Kleinschreibung | `test_teilstring_ohne_gross_kleinschreibung` | Mock |
| 5 | Umlaute und ß | `test_umlaute_und_eszett` | Mock |
| 6 | Zusammenfassen, Konten und E-Mails sammeln | `test_gleiche_person_gleiche_anschrift_zusammengefasst` | Mock |
| 6 | Andere Anschrift bleibt eigener Eintrag | `test_andere_anschrift_eigener_treffer` | Mock |
| 7 | Kein Treffer, Meldung ohne Namen | `test_kein_treffer_ohne_namen_in_meldung` | Mock |
| 8 | Trefferliste öffnen, alte ersetzen | `test_treffer_oeffnen_trefferliste_und_ersetzen_die_alte` | Mock |
| 8 | Spalten der Trefferliste, Kennzeichen | `test_trefferzeile_mit_hinweis`, `test_kennzeichen_verstorben`, `test_rechtsperson_als_rohwert` | Mock |
| 8 | Ausgewählte Einträge, auch nach Umsortieren | `test_ausgewaehlte_eigentuemer`, `test_auswahl_nach_umsortieren` | Mock |
| 8 | Suchfeld in der Trefferliste | `test_suchfilter_ueber_alle_spalten` | Mock |
| — | Keine Personendaten auf der Konsole | `test_suche_gibt_nichts_aus` | Mock |
| — | Sieht das in QGIS richtig aus? | manueller Test | manuell |

Ebene: `Mock` (ohne QGIS, Sekunden) · `QGIS` (gegen echtes QGIS) · `manuell` (Mensch in QGIS).

## Fachliche Sonderfälle

| Sonderfall | Kommt vor bei | Wird geprüft durch |
|---|---|---|
| Eine Person mit mehreren Eigentumskonten | Regelfall im Serienbriefexport | `test_gleiche_person_gleiche_anschrift_zusammengefasst` |
| Schreibweise weicht ab (Groß-/Kleinschreibung, Leerzeichen) | Handeingaben über Jahre | `test_gleiche_person_gleiche_anschrift_zusammengefasst` |
| `Müller` gesucht, `Mueller` gespeichert | ältere Datenbestände | `test_umlaute_und_eszett` |
| PLZ ohne führende Null (`1067`) | QGIS erkennt beim CSV-Laden die Spalte als Zahl | `test_plz_mit_fuehrender_null` |
| `PER_VERSTORBEN` als Text oder als Zahl gelesen | QGIS erkennt beim CSV-Laden die Spalte als Zahl | `test_kennzeichen_verstorben` |
| Eine Person mit verschiedenen `PER_RECHTSPERSON`-Werten | mehrere Konten mit unterschiedlicher Erfassung | `test_rechtsperson_als_rohwert` (Werte werden gesammelt) |
| Leere Felder bzw. QGIS-NULL | unvollständige Datensätze | `test_kennzeichen_verstorben`, `test_rechtsperson_als_rohwert` |
| Rechtsperson ohne Vornamen (z. B. Gemeinde) | Körperschaften als Eigentümer | `test_name_und_anschrift`, `test_rechtsperson_als_rohwert` |

## Bewusst nicht getestet

| Was | Warum | Wie stattdessen abgesichert |
|---|---|---|
| Aufbau von Trefferfenster und Auswahltabelle mit echten Qt-Widgets | im Mock-Modus gibt es keine Widgets; die Filter- und Zuordnungslogik ist als reine Funktion getestet | manueller Test in QGIS |
| Echter Serienbriefexport | personenbezogen, gehört nicht ins Repository | erfundene Testzeilen mit der Kopfzeile der Blanko-Vorlage aus dem Issue |

## Bekannte Lücken

| Lücke | Auswirkung | Issue |
|---|---|---|
| Der manuelle QGIS-Test steht aus, auch für den Landkreis-Dialog, dessen Tabelle jetzt aus der gemeinsamen Funktion kommt | Ein Fehler beim Herauslösen der Tabelle bliebe in beiden Dialogen unbemerkt | Verfahrensgebiet #56 |