sysops
15a5da33fd
Serves the static OpenAPI YAML via go:embed. Completes the last open acceptance criterion for PROJ-13. PROJ-44 marked Deployed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
188 lines
10 KiB
Markdown
188 lines
10 KiB
Markdown
# PROJ-44: OCR-GUI-Integration (Status, Download, Such-Highlight)
|
|
|
|
## Status: Deployed
|
|
**Created:** 2026-05-08
|
|
**Last Updated:** 2026-05-11
|
|
|
|
## Dependencies
|
|
|
|
- Requires: PROJ-35 (OCR & Anhang-Volltext-Indexierung) — liefert `ocr_status` + `attachment_text`
|
|
- Requires: PROJ-6 (Volltext-Suche & Filterung) — Suche-Endpoint wird erweitert
|
|
- Requires: PROJ-7 (E-Mail-Ansicht) — Mail-Detail-Seite wird erweitert
|
|
|
|
## Motivation
|
|
|
|
PROJ-35 hat den OCR-Pipeline gebaut, aber die Resultate sind bisher nur indirekt sichtbar (über Volltext-Suche, die plötzlich mehr findet). Nutzer und Auditoren sollen:
|
|
|
|
- erkennen können, dass OCR auf einer Mail gelaufen ist und den Status sehen
|
|
- den extrahierten Text als Reintext-Datei (`.txt`) herunterladen können (für GoBD-konforme Archivierung des erkannten Inhalts neben dem Original-PDF)
|
|
- bei Suchergebnissen sehen, dass ein Treffer aus dem OCR-Text kam — und welche Stelle es war (Snippet)
|
|
|
|
## User Stories
|
|
|
|
- Als **Nutzer** möchte ich auf der Mail-Detail-Seite sehen, ob die Anhänge bereits OCR-verarbeitet wurden, damit ich weiß, ob die Suche im Volltext greift.
|
|
- Als **Auditor** möchte ich den extrahierten Reintext einer Mail als `.txt`-Datei herunterladen, damit ich ihn unabhängig vom Original-PDF archivieren oder weiterverarbeiten kann.
|
|
- Als **Nutzer** möchte ich in der Trefferliste der Volltext-Suche erkennen, ob ein Treffer aus dem Mail-Body, dem Subject oder dem OCR-Anhang-Text kam — und idealerweise ein Textauszug der Fundstelle.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `MailDetail`-Response (`/api/mails/{id}`) enthält neue Felder `ocr_status` und `ocr_chars` (Anzahl extrahierter Zeichen, 0 wenn nichts gefunden)
|
|
- [ ] Mail-Detail-Seite zeigt OCR-Badge im Header neben den anderen Status-Badges (verify_ok, threading)
|
|
- `done` → grünes Badge „OCR ✓"
|
|
- `failed` → rotes Badge „OCR ✗"
|
|
- `skipped` → graues Badge „OCR n/a"
|
|
- `pending` → blaues Badge „OCR …"
|
|
- `disabled` → kein Badge
|
|
- [ ] Neuer Endpoint `GET /api/mails/{id}/ocr-text` liefert den extrahierten Text als `text/plain; charset=utf-8` mit `Content-Disposition: attachment; filename="<message-id>.ocr.txt"`
|
|
- [ ] Mail-Detail-Seite hat einen Button „OCR-Text herunterladen", der nur erscheint wenn `ocr_status='done'` und `ocr_chars > 0`
|
|
- [ ] Such-Endpoint `/api/search` liefert pro Treffer ein neues Feld `snippet` (Markdown-style mit `<b>`-Tags um Match-Wörter) und `match_field` (z.B. `body`, `subject`, `attachment_text`)
|
|
- [ ] Such-UI zeigt unter Subject/From eine zweite Zeile mit dem Snippet und einem kleinen Badge, das die Quelle benennt (z.B. „📄 aus PDF-Anhang")
|
|
- [ ] Audit-Log: jeder OCR-Text-Download wird als `mail:ocr_download` erfasst
|
|
- [ ] Externe v1-API: das gleiche `ocr_status`-Feld liegt im JSON von `/api/v1/mails/{id}`
|
|
|
|
## Edge Cases
|
|
|
|
- Mail ohne OCR-Daten (`skipped`, kein `attachment_text`) → Download-Endpoint liefert 404 mit klarer Fehlermeldung
|
|
- Mail mit `ocr_status='pending'` → 202 Accepted + Hinweis „OCR läuft noch, bitte später erneut"
|
|
- Snippet-Generierung schlägt fehl (Manticore-Highlight-Fehler) → Treffer wird ohne Snippet zurückgegeben, kein Hard-Error
|
|
- Tenant-Isolation: OCR-Text-Endpoint prüft Mail-Zugriff genau wie `/raw` (PROJ-7)
|
|
- Sehr lange OCR-Texte (>1 MB) → Endpoint streamt direkt aus Manticore, kein Buffer im Memory
|
|
|
|
## Technical Requirements
|
|
|
|
### Backend
|
|
|
|
**Erweiterung `internal/api/mails.go`:**
|
|
```go
|
|
type MailDetail struct {
|
|
// ... bestehende Felder
|
|
OCRStatus string `json:"ocr_status"` // pending|done|failed|skipped|disabled
|
|
OCRChars int `json:"ocr_chars"` // 0 wenn kein Text
|
|
}
|
|
```
|
|
|
|
Neuer Helper auf `*storage.Store`:
|
|
```go
|
|
func (s *Store) GetOCRStatus(ctx context.Context, id string) (status string, chars int, err error)
|
|
```
|
|
Liest `ocr_status` aus PostgreSQL und holt die `attachment_text`-Länge aus Manticore (oder cached die Länge in einer neuen Spalte `ocr_chars` — siehe Tech Design).
|
|
|
|
**Neuer Handler `handleGetOCRText`** in `internal/api/mails.go`:
|
|
```go
|
|
GET /api/mails/{id}/ocr-text
|
|
→ 200 OK + text/plain wenn vorhanden
|
|
→ 202 Accepted wenn ocr_status='pending'
|
|
→ 404 Not Found wenn skipped/failed/no text
|
|
→ 401/403 wie bei /raw
|
|
```
|
|
|
|
**Erweiterung `internal/index/index.go::Hit`:**
|
|
```go
|
|
type Hit struct {
|
|
ID string `json:"id"`
|
|
Score float64 `json:"score"`
|
|
Snippet string `json:"snippet,omitempty"` // Manticore SNIPPET() output
|
|
MatchField string `json:"match_field,omitempty"` // body|subject|attachment_text|...
|
|
}
|
|
```
|
|
|
|
**Erweiterung `internal/index/manticore.go::Search`:**
|
|
- Pro Hit ein zweiter Query-Pass mit `CALL SNIPPET(text, query, table_name)` — oder direkt im SELECT mit `HIGHLIGHT()` (Manticore-Funktion)
|
|
- `MatchField` wird heuristisch ermittelt: pro Feld separate Queries und sehen, welches Feld als erstes matcht — alternativ über `WEIGHT()`-Inspection
|
|
|
|
### Frontend
|
|
|
|
**`src/components/ocr-badge.tsx`** (neu):
|
|
- Kleine wiederverwendbare Badge-Komponente, die anhand des `ocr_status`-Werts die richtige Farbe + den richtigen Text rendert
|
|
|
|
**`src/app/mail/[id]/page.tsx`:**
|
|
- Badge in den Header (neben Verifikation)
|
|
- Download-Button „OCR-Text" wenn `ocr_chars > 0`
|
|
|
|
**`src/app/search/page.tsx`:**
|
|
- Such-Treffer-Komponente um Snippet + Quellen-Badge erweitern
|
|
- Snippet wird über `dangerouslySetInnerHTML` gerendert (nur `<b>`-Tags, vorher per HTML-Sanitizer wrappen — Manticore liefert nur diese eine Markup-Form)
|
|
|
|
### DB-Schema (optional)
|
|
|
|
Optional kann `attachment_text`-Länge als `emails.ocr_chars BIGINT` cached werden, um den `Manticore SELECT length(attachment_text)`-Roundtrip pro Mail-Detail zu sparen. Tradeoff: zusätzliche Spalte vs. eine zusätzliche Manticore-Query pro Detail-Aufruf. **Entscheidung: Cache in PostgreSQL** — wird beim OCR-Worker mit dem Status zusammen geschrieben.
|
|
|
|
```sql
|
|
ALTER TABLE emails ADD COLUMN IF NOT EXISTS ocr_chars BIGINT DEFAULT 0;
|
|
```
|
|
|
|
## Tech Design
|
|
|
|
### Datenfluss für OCR-Text-Download
|
|
|
|
```
|
|
Frontend (Mail-Detail)
|
|
├ getMail(id) → MailDetail mit ocr_status + ocr_chars
|
|
└ Wenn ocr_chars > 0: Button rendern
|
|
└ Click → GET /api/mails/{id}/ocr-text
|
|
├ Backend: ACL-Check (requireMailAccess)
|
|
├ Backend: hole attachment_text aus Manticore SELECT
|
|
├ Backend: Audit-Log "mail:ocr_download"
|
|
└ Response: text/plain + Content-Disposition
|
|
```
|
|
|
|
### Datenfluss für Such-Snippet
|
|
|
|
```
|
|
Frontend (Suche)
|
|
└ POST /api/search { query: "rechnungsnummer" }
|
|
└ Backend Search:
|
|
├ Manticore SELECT mit MATCH() + WEIGHT() pro Treffer
|
|
├ Pro Treffer: CALL SNIPPET(field_value, query) für Snippet
|
|
├ Heuristik für match_field: prüfe welches Text-Feld den Query enthält
|
|
└ Response: Hits mit snippet + match_field
|
|
```
|
|
|
|
### Audit-Log-Erweiterung
|
|
|
|
Neue Aktion: `mail:ocr_download` mit `mail_id` als Subject. Bestehende Audit-Pipeline (`s.audlog.Log(...)`) wird weiterverwendet.
|
|
|
|
## Nicht in Scope
|
|
|
|
- OCR-Text-Bearbeitung oder -Korrektur durch Nutzer (nur Lesen + Download)
|
|
- Inline-Anzeige des OCR-Texts auf der Mail-Detail-Seite (nur Download — der Reintext wäre oft mehrere Seiten lang)
|
|
- Neuverarbeitung über die GUI (das geht nur per CLI `archivmail ocr-reprocess`)
|
|
- Sprachen jenseits dessen, was PROJ-35 ohnehin unterstützt (deu+eng)
|
|
|
|
## Implementation Notes
|
|
|
|
**Implementiert (alle Akzeptanzkriterien erfüllt):**
|
|
|
|
- DB-Schema: `ALTER TABLE emails ADD COLUMN IF NOT EXISTS ocr_chars BIGINT DEFAULT 0` als idempotente Migration in `internal/storage/storage.go`. Storage-Helper `SetOCRResult` / `GetOCRMeta` in `internal/storage/ocr.go`.
|
|
- OCR-Worker schreibt `ocr_chars` zusammen mit `ocr_status`. Nutzt jetzt die kanonische `emails.tenant_id` aus PostgreSQL (nicht mehr `Job.TenantID`), damit CLI-Reprocess (`tenantID == nil`) korrekt im Tenant-Index landet.
|
|
- API-Endpoint `GET /api/mails/{id}/ocr-text` in `internal/api/ocr_handlers.go` mit ACL wie `/raw`, Status-Mapping 200/202/404 und Audit-Event `mail:ocr_download`. Endpoint löst den Manticore-Reader ebenfalls über die DB-Tenant-ID auf — gleicher Strukturfix wie im Worker.
|
|
- `MailDetail` (+ externes v1-API) liefert `ocr_status` und `ocr_chars`.
|
|
- Such-Hits liefern `snippet` + `match_field`. Heuristik: probiert `subject > body > attachment_text > attachment_names > from_addr > to_addr` durch MATCH()-Tests; Snippet via `SELECT SNIPPET(text, query) FROM table` (CALL SNIPPETS scheitert am Go-MySQL-Driver-Packet, Manticore 25 akzeptiert keine Options-Args).
|
|
- Frontend: `OcrBadge`-Komponente, Download-Button auf Mail-Detail-Seite, Snippet + Quellen-Badge in Trefferliste. `sanitizeSnippet` mit Whitelist nur für `<b>`-Tags.
|
|
- IMAP- und POP3-Live-Import triggern jetzt den OCR-Worker via Function-Pointer-Pattern (`SetOCRSubmit`) — vermeidet Zirkularimport. Vorher blieben neu importierte Mails ewig in `ocr_status='pending'`.
|
|
|
|
**Bugfixes während Implementierung:**
|
|
|
|
- **Live-Import-Bug:** IMAP/POP3 hatten keinen `ocrWorker.Submit`-Call → neue Mails standen 4 Tage auf 132 in `pending` (54 Mails bestätigt). Fix: `SetOCRSubmit`-Hook in `cmd/archivmail/main.go` verdrahtet.
|
|
- **Tenant-Isolation-Strukturbug:** Worker und Endpoint lasen unterschiedliche Tenant-Quellen (Submitter-Kontext vs. Session) → Schreib- und Lese-Pfad landeten in verschiedenen Manticore-Indizes; Tenant-User sahen eigenen OCR-Text nicht. Fix: Beide Pfade lesen `emails.tenant_id` als Single Source of Truth.
|
|
- **Manticore 25 / Go-MySQL-Treiber:** CALL SNIPPETS Options-Args weggekürzt, dann komplett auf `SELECT SNIPPET(...)` umgestellt — CALL-Antworten lassen sich vom Treiber nicht parsen.
|
|
|
|
## QA Test Results
|
|
|
|
Verifiziert auf **192.168.1.132** mit Commit `16013e8`:
|
|
|
|
| Szenario | Erwartung | Ergebnis |
|
|
|---|---|---|
|
|
| Tenant-2-User, eigene Mail (Anhang mit OCR-Text) | 200 + Text | OK |
|
|
| Tenant-2-User, Mail aus Tenant-1 | 403/404 | 403 access denied — Isolation greift |
|
|
| Admin, Tenant-Mail | 403 (SEC-29: Admin sieht keine Mail-Inhalte) | 403 — korrekt |
|
|
| Auditor, globale Mail (tenant_id IS NULL) | 200 + Text | OK |
|
|
| Auditor, Tenant-Mail | 403 | OK |
|
|
| DB-Migration `ocr_chars` | Spalte vorhanden | Vorhanden + Index `idx_emails_ocr_status` |
|
|
| Manticore-Routing | attachment_text liegt in emails_tenant_N, nicht global | Bestätigt |
|
|
|
|
## Deployment
|
|
|
|
- **2026-05-11 — 192.168.1.132 (Test):** Commit `16013e8` aktiv, alle Dienste running, QA grün.
|
|
- **2026-05-29 — 192.168.1.131 (Prod):** Commit `fa9f777` aktiv (inkl. Security-Fixes), api 1.8 / storage 1.9, alle Dienste running.
|