Atlas/GOOGLE-VISION-SETUP.md

Google Cloud Vision API Setup

Die Google Cloud Vision API wird für die automatische Unterschriftenerkennung bei hochgeladenen PDFs verwendet.

Einrichtung

1. Google Cloud Projekt erstellen

1. Gehe zu Google Cloud Console
2. Erstelle ein neues Projekt oder wähle ein bestehendes aus
3. Aktiviere die Vision API:
   • Navigiere zu "APIs & Services" → "Enable APIs and Services"
   • Suche nach "Cloud Vision API"
   • Klicke auf "Enable"

2. Service Account erstellen

1. Gehe zu "IAM & Admin" → "Service Accounts"
2. Klicke auf "Create Service Account"
3. Name: savethemoment-vision
4. Role: Cloud Vision API User
5. Klicke auf "Done"

3. JSON-Schlüssel herunterladen

1. Klicke auf den erstellten Service Account
2. Gehe zu "Keys" → "Add Key" → "Create new key"
3. Wähle JSON als Format
4. Speichere die Datei als google-vision-key.json im Projekt-Root (wird von .gitignore ignoriert)

4. Umgebungsvariable setzen

Füge in .env hinzu:

GOOGLE_APPLICATION_CREDENTIALS="./google-vision-key.json"

Alternativ für Produktion (Vercel):

GOOGLE_CLOUD_PROJECT_ID="dein-projekt-id"
GOOGLE_CLOUD_CLIENT_EMAIL="dein-service-account@projekt.iam.gserviceaccount.com"
GOOGLE_CLOUD_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Kosten

• Kostenlos: 1.000 Anfragen pro Monat
• Danach: ~1,50€ pro 1.000 Anfragen
• Bei unter 100 Buchungen/Monat → komplett kostenlos

Funktionsweise

Wenn ein Admin ein signiertes PDF hochlädt:

1. PDF wird gespeichert
2. Google Vision API analysiert das Dokument
3. Sucht nach:
   • Keyword "Unterschrift" oder "Signature"
   • Handschriftliche Elemente (niedriger Confidence-Score)
   • Textdichte-Variationen
4. Gibt true zurück wenn Unterschrift erkannt
5. Vertrag wird als "unterschrieben" markiert

Fallback

Falls die API nicht konfiguriert ist:

• Upload funktioniert weiterhin
• Unterschrift wird als vorhanden angenommen
• Admin muss manuell prüfen

Testing ohne API

Für lokale Tests ohne Google Cloud:

1. Kommentiere einfach die GOOGLE_APPLICATION_CREDENTIALS aus
2. Das System akzeptiert alle hochgeladenen PDFs
3. Logs zeigen: "Google Vision API not configured"

Produktions-Setup (Vercel)

1. Gehe zu Vercel Dashboard → Settings → Environment Variables
2. Füge die Umgebungsvariablen hinzu
3. Redeploy das Projekt

Troubleshooting

"Service account key file not found"

→ Prüfe den Pfad in .env

"Permission denied"

→ Service Account braucht "Cloud Vision API User" Role

"API not enabled"

→ Aktiviere Cloud Vision API im Google Cloud Projekt

Monitoring

Überwache die API-Nutzung:

• Google Cloud Console → APIs & Services → Dashboard
• Dort siehst du die Anzahl der Anfragen pro Tag