nexarch/mail/docs/SRC-04-PRUEFPROTOKOLL.md

SRC-04 – Prüfprotokoll: Such-Oberfläche mit Hervorhebung

Voraussetzung SRC-03 (Fertig), SHL-01 (Core-Board, Fertig).

Umsetzung

• web/mail-search: eigenständige Next.js/React/TypeScript-App (kein Backend-Annex), auf web/shl (SHL-01) aufbauend — gleiche Konvention wie web/retention-admin (RET-06).
• app/api/search/route.ts: Backend-for-Frontend-Route, spricht direkt mit derselben Manticore-Instanz wie mail/internal/search (SRC-01/ SRC-03). Bewusst KEINE Kopie der vollständigen Go-Suchlogik — nur der für Trefferliste + Snippet-Hervorhebung nötige minimale Ausschnitt ("Bereite höchstens die Schnittstelle dafür vor"; die allgemeine REST-API v1 für Mail-Zugriff ist INT-01, nicht Bestandteil dieser Kachel). Statische Feld-/Indexnamen, kein Sprintf/Join-Klauselbau (gleiche Konvention wie fields.go). Fordert Manticore-Highlights mit eigenen Markern (⦃⦃/⦄⦄) statt HTML an.
• lib/highlight.ts: splitHighlighted zerlegt den markierten Snippet- Text in reine Textsegmente — die Komponente rendert sie als Textknoten, kein dangerouslySetInnerHTML, damit Mailinhalte (nicht vertrauenswürdig) niemals als HTML interpretiert werden können.
• app/page.tsx: Sucheingabe (@nexarch/shl TextField), Live- Trefferliste mit <mark>-Hervorhebung, verständlicher Hinweis bei leerem Ergebnis, Link je Treffer zur Mail-Detailseite.
• app/mail/[messageId]/page.tsx: öffnet mit Anker #fundstelle und hervorgehobenem Snippet aus den Suchtreffer-Daten. Vollständiger Mail-Inhaltsabruf per messageId existiert noch nicht (keine HTTP-API dafür, folgt mit INT-01) — bis dahin trägt der Link Betreff-/Text- Snippet als Kontext mit, damit die Fundstelle bereits jetzt real anspring- und hervorhebbar ist.
• lib/contrast.ts/lib/highlightColors.ts: reale WCAG-2.1- Kontrastberechnung statt behaupteter Werte.
• Kein Umbau: mail/internal/*, web/shl, web/retention-admin unverändert.

Prüfungen

#	Prüfung	Ergebnis
1	Manueller Test mit typischen Suchanfragen bestätigt korrekte Hervorhebung	bestanden – echter next build + next start auf 192.168.1.131 gegen die live laufende Manticore-Instanz: GET /api/search?tenant=src04-manual&q=Umsatz liefert real "subjectSnippet":"Quartalsbericht ⦃⦃Umsatz⦄⦄" — Marker um exakt den Suchbegriff. Zusätzlich automatisiert in app/page.test.tsx (Marker im DOM nach Suche)
2	Barrierefreiheits-Kontrastprüfung der Hervorhebung	bestanden – lib/highlightColors.test.ts: echte WCAG-2.1-Berechnung, Hell-Modus 14,29:1, Dunkel-Modus 6,43:1 (beide ≥ 4.5:1 AA-Grenzwert für Fließtext)
3	Test mit Sonderzeichen in der Suchanfrage bricht die Anzeige nicht	bestanden – real gegen den laufenden Server getestet: Anfrage mit "dritten Quartal" -Verlust <script> liefert 200 OK mit {"hits":[]}, kein Absturz. Zusätzlich automatisiert lib/highlight.test.ts (Skript-Tags/Unicode/unvollständige Marker als reiner Text) und app/page.test.tsx (kein <script>-Element im DOM, da kein dangerouslySetInnerHTML)

Zusätzlich (Akzeptanzkriterium 2/3, real geprüft): GET /mail/m-manual-1?subject=... liefert 200 OK; automatisiert app/page.test.tsx bestätigt Link-Struktur (/mail/<id>?...#fundstelle) und den "Keine Treffer"-Hinweis bei leerem Ergebnis.

Build/Test-Ergebnis (192.168.1.131)

npx tsc --noEmit                              -> clean
npx next build                                -> Compiled successfully (4 Routen)
npx vitest run                                -> 3 Testdateien, 12/12 bestanden
next start (real) + curl gegen Manticore live -> Hervorhebung, leeres Ergebnis,
                                                   Sonderzeichen alle real bestätigt

Testprozess (next start -p 4711) und Testdokument (mail_documents-ID 992001) nach Prüfung entfernt.

Gesamtergebnis

Bestanden. Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen real erfüllt. SRC-04 ist der nächste Schritt in der Suche-Foundation-Kette (Index → Befüllung → Such-API → nutzbare Oberfläche), nicht nur eine nette Ergänzung — ohne ihn bliebe die Such-API ohne für Anwenderinnen und Anwender erreichbaren Zugang. Entsperrt QA-03 (gemeinsam mit SRC-02).