breakpilot-compliance/docs-src/services/document-crawler/index.md

# Document Crawler & Auto-Onboarding

Der Document Crawler ist ein eigenstaendiger Python/FastAPI-Microservice, der automatisch lokale Dateisysteme nach bestehenden Compliance-Dokumenten durchsucht, diese mittels LLM klassifiziert, in IPFS archiviert und eine Compliance-Lueckenanalyse durchfuehrt.

## Architektur

```mermaid
graph LR
    FE[Frontend Admin-v2] -->|API Proxy| DC[Document Crawler :8098]
    DC -->|LLM Klassifizierung| SDK[AI Compliance SDK :8090]
    DC -->|IPFS Archivierung| DSMS[DSMS Gateway :8082]
    DC -->|Daten| PG[(PostgreSQL)]
```

| Eigenschaft | Wert |
|------------|-------|
| **Service** | `document-crawler` |
| **Port** | 8098 |
| **Container** | `bp-compliance-document-crawler` |
| **Sprache** | Python 3.11 / FastAPI |
| **Datenbank** | PostgreSQL (extern: `46.225.100.82:54321`, DB `postgres`, sslmode=require) |

## Features

- **Filesystem Crawling** — Automatisches Scannen lokaler Verzeichnisse und NAS-Shares
- **Delta-Erkennung** — SHA-256 Hash-basierte Aenderungserkennung, nur geaenderte Dateien werden erneut verarbeitet
- **Text-Extraktion** — PDF (PyMuPDF), DOCX (python-docx), XLSX (openpyxl), PPTX (python-pptx)
- **LLM-Klassifizierung** — Automatische Kategorisierung via AI Compliance SDK
- **Keyword-Fallback** — Heuristische Klassifizierung wenn LLM nicht verfuegbar (Confidence max 0.3)
- **IPFS-Archivierung** — Langzeit-Archivierung ueber DSMS Gateway
- **Gap-Analyse** — Vergleich gefundener Dokumente gegen Compliance-Matrix
- **Onboarding-Report** — Compliance-Score, fehlende Dokumente, Handlungsempfehlungen

## Dokumentklassifizierungen

| Kategorie | Beschreibung |
|-----------|-------------|
| VVT | Verzeichnis von Verarbeitungstaetigkeiten |
| TOM | Technische und organisatorische Massnahmen |
| DSE | Datenschutzerklaerung |
| AVV | Auftragsverarbeitungsvertrag |
| DSFA | Datenschutz-Folgenabschaetzung |
| Loeschkonzept | Loeschfristen und -verfahren |
| Einwilligung | Einwilligungserklaerungen |
| Vertrag | Vertraege mit Datenschutzbezug |
| Richtlinie | Interne Datenschutzrichtlinien |
| Schulungsnachweis | Datenschutz-Schulungszertifikate |
| Sonstiges | Nicht klassifizierbare Dokumente |

## Datenbank-Schema

4 Tabellen (Migration 014):

### `crawler_sources`
Konfigurierbare Crawl-Verzeichnisse mit Pfad, Dateityp-Filter, Tiefenbegrenzung und Ausschlussmustern.

### `crawler_jobs`
Jede Crawl-Ausfuehrung mit Status (pending/running/completed/failed), Typ (full/delta) und Statistiken.

### `crawler_documents`
Jede entdeckte Datei mit Metadaten, extrahiertem Text, Klassifizierung, Confidence-Score und Archivierungsstatus.

### `crawler_onboarding_reports`
Zusammenfassungsberichte mit Compliance-Score, Klassifizierungs-Aufschluesselung und Gap-Analyse.

## API Endpoints

Alle unter `/api/v1/crawler/`, benoetigen `X-Tenant-ID` Header.

### Quellen (Sources)

| Method | Endpoint | Beschreibung |
|--------|----------|-------------|
| GET | `/sources` | Crawl-Quellen auflisten |
| POST | `/sources` | Neue Quelle erstellen |
| PUT | `/sources/{id}` | Quelle aktualisieren |
| DELETE | `/sources/{id}` | Quelle loeschen |
| POST | `/sources/{id}/test` | Konnektivitaet testen |

### Jobs

| Method | Endpoint | Beschreibung |
|--------|----------|-------------|
| POST | `/jobs` | Crawl starten (full/delta) |
| GET | `/jobs` | Jobs auflisten |
| GET | `/jobs/{id}` | Job-Details + Fortschritt |
| POST | `/jobs/{id}/cancel` | Laufenden Job abbrechen |

### Dokumente

| Method | Endpoint | Beschreibung |
|--------|----------|-------------|
| GET | `/documents` | Dokumente auflisten (Filter: classification, status) |
| GET | `/documents/{id}` | Dokument-Details + Text-Vorschau |
| PUT | `/documents/{id}/classify` | Manuelle Klassifizierungs-Korrektur |
| POST | `/documents/{id}/archive` | In IPFS archivieren |
| POST | `/documents/archive-batch` | Bulk-Archivierung |

### Reports

| Method | Endpoint | Beschreibung |
|--------|----------|-------------|
| POST | `/reports/generate` | Onboarding-Report generieren |
| GET | `/reports` | Reports auflisten |
| GET | `/reports/{id}` | Report mit Gap-Analyse |

## Gap-Analyse

Die Gap-Analyse vergleicht gefundene Dokumenttypen gegen eine Pflichtdokumenten-Matrix:

| Dokument | Pflicht fuer | Severity |
|----------|-------------|----------|
| VVT | Alle Unternehmen | CRITICAL |
| TOM | Alle Unternehmen | CRITICAL |
| DSE | Alle Unternehmen | CRITICAL |
| Loeschkonzept | Alle Unternehmen | HIGH |
| AVV | Auftragsverarbeiter | HIGH |
| DSFA | KI-Nutzer, Hochrisiko-Verarbeitung | HIGH |
| Schulungsnachweis | Alle Unternehmen | MEDIUM |
| Richtlinie | Alle Unternehmen | MEDIUM |

## Frontend

4-Tab-Seite unter `/sdk/document-crawler`:

1. **Quellen** — Crawl-Verzeichnisse konfigurieren, Konnektivitaet testen
2. **Crawl-Jobs** — Crawl starten, Fortschrittsbalken mit Auto-Refresh, Job-Historie
3. **Dokumente** — Tabelle mit Klassifizierungs-Badges, Confidence-Bars, Reklassifizierung, Archivierung
4. **Onboarding-Report** — SVG Compliance-Score Ring, Gap-Analyse mit Severity-Cards

## Konfiguration

| Umgebungsvariable | Standard | Beschreibung |
|-------------------|----------|-------------|
| `PORT` | 8098 | Service-Port |
| `DATABASE_URL` | - | PostgreSQL Connection String |
| `LLM_GATEWAY_URL` | `http://ai-compliance-sdk:8090` | LLM Service URL |
| `DSMS_GATEWAY_URL` | `http://dsms-gateway:8082` | IPFS Service URL |
| `CRAWL_BASE_PATH` | `/data/crawl` | Basis-Pfad im Container |
| `MAX_FILE_SIZE_MB` | 50 | Maximale Dateigroesse |

## Health Check

```bash
curl http://localhost:8098/health
# {status: healthy, service: document-crawler}
```