v1.16: SparkReceipt-Schnittstelle - Belege per Webhook importieren und als Kostenposition uebernehmen

kimi.md

@@ -189,6 +189,36 @@ tar -czf mp-dist.tar.gz -C dist .
 
 ## 8. Verlauf / offene Punkte
 
+**Erledigt 04.10. (v1.16):** SparkReceipt-Schnittstelle für gescannte Belege.
+SparkReceipt bietet Webhooks (Doku: sparkreceipt.com/integrations/webhooks)
+– POST auf eine URL bei document created/updated/deleted, Standard-Verzögerung
+10 min, Event-Log mit „Send now". Setup beim Nutzer: SparkReceipt →
+Integrationen → Webhooks → URL
+`https://mieterportal.hocks.eu/api/belege/webhook?token=<SPARKRECEIPT_WEBHOOK_TOKEN>`
+(Token liegt in /opt/mieterportal/portal.env, Stand 04.10.:
+0e8c671ca1c4df3668bac6b2b57602f49ad0f4db8366cc42 – bei Rotation Eintrag in
+portal.env ersetzen + `docker compose up -d`). NEUE TABELLE `belege`
+(quelle, externe_id, haendler, betrag, waehrung, datum, jahr, kategorie,
+notiz, datei_url, zugeordnet, erfasst_am; UNIQUE(quelle, externe_id)).
+API: POST /api/belege/webhook (KEINE Session – Token per ?token= ODER
+x-webhook-token-Header; ohne gesetztes Env → 503; toleranten Feld-Aliasen –
+Payload ggf. unter body.document verschachtelt, Aliase merchant/vendor/total/
+amount/date/category/file_url u. a.; delete-Events werden ignoriert;
+INSERT ... ON CONFLICT (quelle, externe_id) DO UPDATE → idempotent).
+PATCH /api/belege/:id (adminOnly) setzt zugeordnet. Bootstrap liefert belege
+nur an die Verwaltung. Frontend: Tabs auf /kosten („Kostenpositionen" /
+„Spark-Receipt-Belege", Admin-only) – Info-Box mit der Webhook-URL, Filter
+Alle/Nicht zugeordnet, Tabelle mit Übernehmen-Button (öffnet KostenDialog
+vorbelegt mit Betrag/Jahr/Notiz „SparkReceipt · Händler (#ID)";
+onGespeichert markiert den Beleg zugeordnet) plus Beleg-Link (datei_url).
+KostenDialog hat neue Props vorbefuellung/onGespeichert/triggerLabel.
+E2E verifiziert (simulierte SR-Payloads): 401 ohne Token, Create, Update
+selbe externe_id ohne Duplikat, Jahr-Ableitung aus Datum, Mieter 403, Admin
+zugeordnet, Testbeleg per SQL entfernt. OFFEN: echtes Feld-Mapping gegen
+ein echtes SparkReceipt-Event prüfen (Event-Log in SR zeigt das Payload –
+ggf. Aliase in belegFelder() nachpflegen); Beleg-PDF-Download aus SR
+nachrüsten, falls die datei_url ein öffentlicher Link ist.
+
 **Erledigt 04.10. (v1.15):** Struktur „1 Haus → mehrere Wohneinheiten" in der
 Verwaltung verankert + Bugfix Haus-Umbenennung. BUGFIX (wichtig): der FK
 `costs_building_fkey` aus v1.14 hatte kein ON UPDATE CASCADE → jede