fotospiel-app/docs/superadmin-kb/de/06-ai-operations/01-ai-magic-edits-ops.md

title

title
AI Magic Edits (Ops Runbook)

Dieses Runbook beschreibt den operativen Betrieb von AI Magic Edits (AI Styling) inklusive Entitlements, Provider-Betrieb, Monitoring, Recovery und Incident-Handling.

1. Scope und aktueller Stand

• Feature-Name im System: ai_styling (User-facing: "AI Magic Edits"/"AI-Styling").
• Architektur ist provider-agnostisch umgesetzt (AiImageProvider Interface), aktuell ist runware.ai als erster Provider aktiv.
• Das Guest-PWA-Rollout ist derzeit clientseitig hinter einem Flag deaktiviert:
  • resources/js/guest-v2/lib/featureFlags.ts → GUEST_AI_MAGIC_EDITS_ENABLED = false.
• Im Event Admin Control Room wird der AI-Bereich nur angezeigt, wenn das Event das Capability ai_styling hat.

2. Entitlements und Freischaltung

2.1 Paket-/Addon-Logik

• Erforderliches Paket-Feature: ai_styling (config/ai-editing.php).
• Standard-Addon-Key: ai_styling_unlock (config/ai-editing.php, config/package-addons.php).
• Entitlement wird event-spezifisch aufgelöst über:
  • aktives Event-Paket (eventPackage.package.features, Tabelle event_packages)
  • aktive, abgeschlossene Addons (eventPackage.addons, Tabelle event_package_addons, status=completed, optionales Ablaufdatum in metadata).
• Quelle der Berechtigung:
  • granted_by=package (Feature im Paket enthalten, z.B. Premium)
  • granted_by=addon (Addon für Event aktiv)
  • sonst gesperrt (feature_locked).

2.2 Superadmin-Konfiguration

• Paket-Feature-Verwaltung erfolgt über die bestehende Package-Resource (Feature ai_styling setzen).
• Addon-Katalog:
  • Key ai_styling_unlock in config/package-addons.php
  • kaufbar nur, wenn im Checkout-Katalog ein valider Preis hinterlegt ist.

3. Runtime-Steuerung (Superadmin)

Die zentrale Laufzeitsteuerung liegt in AI Editing Settings (Rare Admin Cluster):

• is_enabled: Globaler Kill-Switch.
• status_message: Text bei globaler Deaktivierung (feature_disabled).
• default_provider: aktuell runware.
• fallback_provider: reserviert für späteres Failover.
• runware_mode: live oder fake.
• queue_auto_dispatch: automatische Queue-Dispatches direkt nach Request-Erstellung.
• queue_name: Ziel-Queue für AI Jobs.
• queue_max_polls: maximale Poll-Versuche für Provider-Status.
• blocked_terms: globale Prompt-Blockliste.

Wichtiger Betriebsaspekt:

• Standard ist queue_auto_dispatch=false. In diesem Modus werden neue Requests zwar erstellt, aber nicht automatisch verarbeitet.
• Für Live-Betrieb muss entweder queue_auto_dispatch=true gesetzt oder ein separater Dispatch-Prozess etabliert sein.

4. Styles und Event-Policy

4.1 Globale Styles

• Verwaltung über AI Styles Resource.
• Styles definieren u.a.:
  • provider/provider_model
  • prompt_template/negative_prompt_template
  • is_active, is_premium
  • optionales Entitlement-Metadatenprofil (metadata.entitlements.*).

4.2 Event-spezifische Policy

Event-Settings unter settings.ai_editing unterstützen:

• enabled (Feature pro Event an/aus)
• allow_custom_prompt
• allowed_style_keys (leer = alle erlaubten Styles)
• policy_message (Rückmeldung bei Blockierung/Deaktivierung)

5. API/Queue-Verarbeitung

5.1 Endpunkte

• Guest:
  • POST /api/v1/events/{token}/photos/{photo}/ai-edits
  • GET /api/v1/events/{token}/ai-edits/{requestId}
  • GET /api/v1/events/{token}/ai-styles
• Tenant:
  • GET /api/v1/tenant/events/{eventSlug}/ai-edits
  • GET /api/v1/tenant/events/{eventSlug}/ai-edits/summary
  • POST /api/v1/tenant/events/{eventSlug}/ai-edits
  • GET /api/v1/tenant/events/{eventSlug}/ai-edits/{aiEditRequest}
  • GET /api/v1/tenant/events/{eventSlug}/ai-styles

5.2 Schutzschichten pro Request

Reihenfolge der Kernprüfungen:

1. Global aktiviert (is_enabled)
2. Entitlement vorhanden (Paket/Addon)
3. Event-Policy erlaubt Request
4. Budget erlaubt Request (Soft/Hard Cap)
5. Style-Zulässigkeit
6. Prompt-Safety (blocked terms)
7. Queue/Provider-Verarbeitung

5.3 Queue-Jobs

• ProcessAiEditRequest: Provider-Submit und ggf. Übergang in Polling.
• PollAiEditRequest: Provider-Statusabfrage bis queue_max_polls.
• Terminalstatus:
  • succeeded
  • failed
  • blocked

5.4 Output-Speicherung und Wasserzeichen

• Bei erfolgreichem Provider-Result versucht das Backend, den Output lokal zu persistieren:
  • Download von provider_url
  • Speicherung unter Event-Pfad (events/{eventSlug}/ai-edits/...)
  • Watermark-Anwendung über dieselbe Logik wie normale Uploads (WatermarkConfigResolver + ImageHelper).
• Primäre Auslieferung erfolgt über lokale storage_path/url; provider_url bleibt als Fallback erhalten.
• Backfill für Alt-Daten ohne lokale Pfade:
  • php artisan ai-edits:backfill-storage

6. Provider-Betrieb (Runware)

6.1 Erforderliche ENV/Config

• RUNWARE_API_KEY
• RUNWARE_BASE_URL (Default https://api.runware.ai/v1)
• RUNWARE_TIMEOUT (Sekunden)
• AI_EDITING_DEFAULT_PROVIDER (Default runware)
• AI_EDITING_RUNWARE_MODE (live oder fake)

6.2 Fake-Mode

• runware_mode=fake liefert synthetische Antworten ohne externen API-Call.
• Geeignet für interne Validierung von Flow/UI/Queue-Logik.
• Nicht für Kosten- oder Qualitätsaussagen nutzen.

7. Monitoring und Alerts

7.1 Wichtige Kennzahlen

• Request-Statusverteilung je Event (queued, processing, succeeded, failed, blocked)
• Failure-Rate
• Moderation-Hit-Rate
• Provider-Failure-Rate
• durchschnittliche Provider-Latenz
• Monatsausgaben (ai_usage_ledgers)

Das Tenant-Summary-Endpoint liefert diese Daten inkl. Alert-Flags:

• observability.alerts.failure_rate_threshold_reached
• observability.alerts.latency_threshold_reached

7.2 Schwellenwerte aus Config

• ai-editing.observability.failure_rate_alert_threshold (Default 0.35)
• ai-editing.observability.failure_rate_min_samples (Default 10)
• ai-editing.observability.latency_warning_ms (Default 15000)
• Budget-Alert-Cooldown: ai-editing.billing.budget.alert_cooldown_minutes (Default 30)
• Abuse-Eskalation: ai-editing.abuse.escalation_threshold_per_hour (Default 25)

7.3 Relevante Log-Signale

• AI provider latency warning
• AI failure-rate alert threshold reached
• AI budget threshold reached
• AI abuse escalation threshold reached

8. Betriebs-Kommandos

8.1 Stuck Requests analysieren/recovern

• Dry-run:
  • php artisan ai-edits:recover-stuck --minutes=30
• Requeue:
  • php artisan ai-edits:recover-stuck --minutes=30 --requeue
• Hart auf failed setzen:
  • php artisan ai-edits:recover-stuck --minutes=30 --fail

8.2 Retention-Pruning

• Dry-run:
  • php artisan ai-edits:prune --pretend
• Ausführen (mit optionalen Overrides):
  • php artisan ai-edits:prune --request-days=90 --ledger-days=365

Retention Defaults:

• Requests: AI_EDITING_REQUEST_RETENTION_DAYS (90)
• Ledger: AI_EDITING_USAGE_LEDGER_RETENTION_DAYS (365)

Hinweis:

• ai-edits:prune läuft täglich per Scheduler (02:30), kann aber bei Bedarf manuell ausgeführt werden.

8.3 Backfill lokaler AI-Outputs

• Dry-run:
  • php artisan ai-edits:backfill-storage --pretend
• Ausführen:
  • php artisan ai-edits:backfill-storage --limit=200
• Für einzelne Request-ID:
  • php artisan ai-edits:backfill-storage --request-id=123

9. Incident-Playbooks

9.1 Provider-Ausfall / hohe Failure-Rate

1. is_enabled=false als Kill-Switch setzen (optional mit status_message).
2. runware_mode=fake nur für interne Funktionstests aktivieren.
3. Queue-Backlog prüfen, ggf. ai-edits:recover-stuck --requeue nach Stabilisierung.
4. Fehlerraten im Summary pro Event kontrollieren.

9.2 Kostenanstieg / Budget-Hard-Cap

1. Budget-Alerts (ai_budget_soft_cap/ai_budget_hard_cap) prüfen.
2. Tenant-Budget in tenant.settings.ai_editing.budget.* validieren.
3. Bei Bedarf zeitweises Override override_until setzen.
4. Bei Missbrauchsspitzen zusätzlich Abuse-Signale prüfen.

9.3 Safety-/Abuse-Spike

1. blocked_terms nachschärfen.
2. Event-Policy enger setzen (allow_custom_prompt=false, allowed_style_keys einschränken).
3. Warn-Logs mit scope_hash, event_id, tenant_id korrelieren.

10. Datenschutz und Datenhaltung

• Keine Secrets in Logs/Docs schreiben (RUNWARE_API_KEY, .env).
• Prompt-/Negativprompt-Inhalte liegen in ai_edit_requests; mit PII vorsichtig umgehen.
• Nur notwendige Aufbewahrungsdauer halten; Pruning regelmäßig durchführen.
• Keine Erweiterung der Retention ohne abgestimmte Privacy-Änderung.

11. Go-Live-Checkliste

1. Paket-/Addon-Freischaltung verifiziert (ai_styling, ai_styling_unlock).
2. RUNWARE_API_KEY gesetzt und Provider-Erreichbarkeit geprüft.
3. queue_auto_dispatch=true und Worker auf korrekter Queue aktiv.
4. Budget-Limits und Alerting pro Tenant geprüft.
5. Safety-Baseline (blocked_terms) gesetzt.
6. Recovery- und Prune-Commands in Ops-Routine aufgenommen.