2026-06-02 09:42:12 +02:00

15 KiB

Raw Blame History

Depoformance Property Match — Backend über PORTA

Beschreibung und Kontext

Depoformance betreibt mit Property Match ein fertiges Frontend für Gewerbeimmobilien-Matching (Supply/Demand), das heute auf Mock-Daten läuft. In ihrer Techdoku (Kap. 11) beschreiben sie, was sie vom „Backend-Team (PowerOn)" brauchen — formuliert in ihrer Sprache (generische REST-API, OpenRouter-Proxy, „CI/CD einrichten", JWT-Felder usw.). Sie kennen unser Backend nicht und beschreiben deshalb eine selbstgebaute Backend-Infrastruktur.

Dieses Dokument übersetzt ihre Wünsche in PORTA-Begriffe: nicht die Schlagworte wörtlich umsetzen, sondern prüfen, was sie fachlich meinen — und es auf vorhandene PORTA-Plattform-Bausteine abbilden. Kernpunkt: Fast alles, was sie als „muss noch gebaut werden" auflisten, ist in PORTA bereits Plattform-Standard. Statt eines projektspezifischen Backends bekommen sie die PORTA-Plattform als Backend; ihr Frontend bleibt unverändert und spricht echte PORTA-Endpunkte statt Mock-Provider an.

Business-Treiber: Depoformance wird als Partner nach unserem Standard-Partner-Modell eingebunden — eigenes UI auf dem PORTA-Backend via API-Vertrag. Kein Sonderfall, sondern der reguläre Partner-Onboarding-Weg.

Grundprinzip der Übersetzung

Ihre Formulierung	Was sie meinen	PORTA-Realität
„Ihr müsst die REST-API für 18 Interfaces bauen"	Sie brauchen persistente, gesicherte CRUD-Endpunkte pro Entität	PORTA hat eine generische, RBAC-gefilterte CRUD-/Tabellen-Schicht — Endpunkte entstehen aus dem Datenmodell, werden nicht pro Entität handgeschrieben
„OpenRouter-Proxy `POST /api/ai/chat/completions`"	Sie brauchen serverseitigen, abgesicherten Modellzugang	PORTA hat ein eigenes AI-Gateway (`serviceAi`) über mehrere Provider — unser AI-Service, kein OpenRouter
„CI/CD müsst ihr entscheiden/einrichten"	Sie wollen Qualitäts-/Deploy-Sicherheit	PORTA hat automatisierte Tests + Deploy-Pipeline bereits etabliert — kein Thema für sie
„JWT mit `role`/`workspaces`/`organizationId`"	Sie wollen Identität + Mandantentrennung + Rollen	PORTA hat JWT-Auth + 4-Stufen-RBAC + Mandantentrennung — wird auf ihre Begriffe gemappt

Architektur: dedizierter Partner-Router

Wir bauen für Depoformance einen eigenen Partner-Router (z. B. unter /api/v1/depoformance/*), der genau die von ihnen benötigten Endpunkte exponiert und intern auf die bestehenden PORTA-Services durchschleift. Depoformance sieht nur diesen stabilen Vertrag und kennt unsere internen Routen nicht.

Depoformance-App
      |  Authorization: Bearer <service-token>
      v
PORTA Partner-Router  /api/v1/depoformance/*   (eigene Routendatei)
      |   schleift durch auf ...
      |-- AI            -> serviceAi (Modell-Auswahl, Audit, Streaming)
      |-- Daten/CRUD    -> generische RBAC-CRUD-/Tabellen-Schicht
      |-- Datenanbindung-> Konnektoren / serviceWeb / serviceKnowledge / serviceExtraction
      |-- Messaging     -> serviceMessaging (Mail/Notifications)

Vorteile:

Stabiler, versionierter Vertrag — entkoppelt von internen Routenänderungen.
Response-Adapter an genau ihr Format ({data} / {data,total} / {code,message}) an einer Stelle.
Pro-Partner Auth, Rate-Limit, Billing-Zuordnung zentral im Router.
Wiederverwendbar als Muster für weitere Partner.

Mapping: Ihre Wünsche (Doku Kap. 11) → PORTA-Fähigkeit

11.1 / 11.2 — Persistenz + 18 Provider-Interfaces (CRUD)

Sie wollen pro Entität gespeicherte, abrufbare, gesicherte Daten. In PORTA wird das Property-Match-Domänenmodell als Feature-Datenmodell abgebildet (analog zu bestehenden Feature-Modulen wie Trustee/RealEstate). Daraus ergeben sich automatisch:

CRUD + Pagination: generische, RBAC-gefilterte Endpunkte (getRecordsetPaginatedWithRBAC), limit/offset (deckt ihren Pagination-Wunsch aus 11.7).
Mandantentrennung: serverseitiger SQL-Filter nach mandateId (= ihre organizationId), aus dem Token, nicht aus dem Request (deckt Security #2).
FK-Auflösung / Labels, einheitliche Antwortstruktur.

Gruppierung ihrer 18 Interfaces nach PORTA-Baustein:

Ihre Interfaces	PORTA-Baustein
Property, Need, Unit, Match, Inquiry, Offer, Shortlist, Pipeline, Reminder, ReviewQueue	Generische RBAC-CRUD-Datentabellen + domänenspezifische Aktions-Endpunkte (`approve`, `moveStage`, `addMessage`, `snooze` …)
FutureSignal, LatentNeed, MarktHinweis, MarketIntelligence, SignalPipeline, DataSource	Datenanbindungen: Konnektoren, Web-Scraping (`serviceWeb`/Tavily), RAG/semantische Suche (`serviceKnowledge`) → speisen diese „Signal"-Entitäten
Dashboard (`getSupplyStats`/`getDemandStats`)	Aggregations-/Report-Endpunkte (FormGenerator Report / Dashboard-Aggregation)
AIMonitoring (`getOutputs`, `updateReviewStatus`)	AI-Audit-Log (AI-Datenfluss-Log) — protokolliert ohnehin jede KI-Ausgabe

Domänenspezifische „Spezialmethoden" (z. B. pipeline.moveStage, inquiry.addMessage) werden als Feature-Endpunkte bzw. Workflow-Aktionen umgesetzt — nicht als handgeschriebene Einzel-APIs.

11.3 — Authentifizierung & Session → PORTA Auth + RBAC

PORTA stellt Login/Refresh/Logout/„me" und Session-Mechanik (Token-Refresh, Expiry, Idle-Timeout) bereits bereit. Ihre JWT-Felder werden gemappt:

Ihr JWT-Feld	PORTA
`id`	User-ID
`role` (PROPERTY_MANAGER, TENANT, STAFF)	PORTA-Rollen (Mandant- bzw. Feature-Instanz-Rollen)
`workspaces` (SUPPLY, DEMAND)	Feature-Zugriff / UI-Sichtbarkeit (RBAC-UI-Items)
`organizationId`	`mandateId` (Mandantentrennung)

Deckt Security #3 (echte Auth, Expiry) und #8 (Session-Mechanik).

11.4 — KI-Proxy → unser AI-Service (kein OpenRouter)

Statt OpenRouter bekommen sie unseren AI-Service (serviceAi): Modell-Auswahl über mehrere Provider (Anthropic, OpenAI, Mistral, Perplexity, Private LLM), Streaming, Billing und KI-Audit-Log (Model-ID, Prompt-Hash, User-ID — deckt Security #9), serverseitige Schlüsselhaltung (deckt #4) und Rate-Limiting (deckt #6). Optional steht der Agent (Tools, Memory) zur Verfügung.

Voller Modellzugang — sie nutzen die Modelle, wie sie wollen. Keine Neutralisierung in diesem Pfad; Datenschutz/Datenminimierung verantwortet Depoformance selbst (bzgl. Security #7 gilt: CH-Datenhaltung garantiert, Provider-DPAs sind unsere).
Ihre 9 KI-Funktionen (parseNeed, generateMatchExplanation, summarizeTradeOffs, generateDecisionBrief, classifyMarketSignal, generateOfferEmail …) rufen unseren AI-Endpunkt; Output validieren sie wie gehabt frontendseitig (Zod).

11.5 — Response-Format

Ihr erwartetes Format ({data} / {data,total} / {code,message}) wird vom PORTA-API-Vertrag bedient (PORTA liefert bereits paginierte data+total-Antworten; Fehlerhülle wird angeglichen).

11.7 — „Offene Punkte" → bereits PORTA-Plattformfunktionen

Ihr offener Punkt	PORTA
Echtzeit-Updates (WebSocket/SSE)	SSE wird in PORTA bereits eingesetzt (Dashboard, Live-Sessions) — verfügbar statt Polling
Datei-Upload (Dokumente)	Datei-/Ordner-Verwaltung + Dokument-Extraktion (`serviceExtraction`: PDF/DOCX/XLSX) vorhanden
E-Mail-Versand	`serviceMessaging` (E-Mail-Versand) vorhanden — sie erzeugen Text, PORTA versendet
Benachrichtigungen	Notifications über `serviceMessaging`
Mehrsprachigkeit (i18n)	DB-basiertes i18n mit AI-Übersetzung vorhanden
Pagination (`limit/offset`)	Standard in der CRUD-Schicht
CI/CD	Automatisierte Tests + Deploy-Pipeline bereits Standard — kein Thema für sie

11.8 — Deployment / Hosting → PORTA-Infrastruktur (CH)

Backend-REST, PostgreSQL, CORS, HTTPS stellt PORTA bereit; Datenresidenz CH garantiert. Ihr Frontend bleibt ein statisches Build und spricht die PORTA-API an.

11.9 — Security-Go-Live-Gate (10 Punkte) → weitgehend PORTA-Standard

#	Anforderung	PORTA
1	Serverseitige Autorisierung pro Endpunkt	RBAC erzwingt das zentral (CRITICAL ✓)
2	Mandantentrennung aus dem Token	SQL-Filter nach `mandateId` aus dem Token (✓)
3	Echte Auth, JWT-Expiry, kein Demo-Login	JWT-Auth + Expiry vorhanden (✓)
4	KI-Key serverseitig	AI-Gateway, Keys serverseitig (✓)
5	Prompt-Injection-Härtung	im AI-Gateway adressierbar (Delimiter/Längen)
6	Rate-Limiting KI-Calls	Limiter vorhanden (✓)
7	Datenschutz/DPA bei KI	CH-Hosting + Provider-DPAs unsererseits; Private LLM für sensible Daten möglich
8	Session-Mechanik	Token-Refresh/Expiry vorhanden (✓)
9	KI-Audit-Log	AI-Datenfluss-Log vorhanden (✓)
10	Transport-/Browser-Härtung	HTTPS/CSP/SameSite/CSRF vorhanden (✓)

Was bei Depoformance bleibt

Frontend (alle Seiten, UI-State) — unverändert.
Matching-Engine (scoreCalculator, mustHaveScorer, rankingEngine, tradeOffAnalyzer) — läuft heute im Frontend; bleibt dort (sofern sie es nicht aktiv ins Backend verlagern wollen).
Domänenlogik der UI — Darstellung, Workflows, Validierung im Frontend.

Was Depoformance einhalten muss (Integrations-Standards)

Authentifizierung gegen PORTA (Login/Token); Aufrufe mit dem von PORTA ausgestellten Token. Secret nie im Browser-Code.
Server-zu-Server aus ihrer App; kein direkter Browser-Call gegen PORTA.
Response-/Fehlerformat und Pagination (limit/offset) gemäss PORTA-Vertrag konsumieren.
Rate-Limits beachten (429 mit Backoff).
Async: lange Operationen (Extraktion, Ingestion) als Job-ID → Polling.
Versionierter Vertrag /api/v1/....
Datenanbindungen spezifizieren (welche Quellen) — Anbindung läuft über PORTAs Konnektor-Schicht, Datenhaltung CH.

Billing / Pricing (selbst kalkuliert)

Zwei Komponenten: einmalige Umsetzung (Partner-Router + Anbindung) und laufende API-Nutzung.

A) Einmalig — Umsetzung

Kalkulationsbasis: Aufwand für Partner-Router, Auth/Token, AI-Durchschleifung, Daten-/Konnektor-Endpunkte, Response-Adapter, OpenAPI-Doku, Tenant-/Billing-Setup, Tests und Integrationsbegleitung.

Posten	Aufwand
Partner-Router + Auth/Token + Tenant-Setup	~4–5 PT
AI-Endpunkt(e) durchschleifen (serviceAi)	~3–4 PT
Daten-/Konnektor-Endpunkte + Response-Adapter	~6–8 PT
OpenAPI-Doku + Integrationsbegleitung + Tests	~3–4 PT
Summe	~16–21 PT

Bei einem Satz von CHF 180/h (8 h/PT = CHF 1'440/PT) ergibt das CHF 23'000–30'000 als T&M-Äquivalent.

Fixpreis-Paket Umsetzung: CHF 24'000 einmalig (Planungssicherheit statt T&M). Founding-/Pilot-Option: CHF 15'000 gegen Referenz/Case-Study.

B) Laufend — API-Nutzung

Position	Wert	Begründung
API-Grundgebühr	CHF 600 / Monat	Betrieb + Wartung Partner-Router, CH-Hosting, Verfügbarkeit, Support, Vertragspflege
inkl. API-Calls (Fair-Use)	bis 100'000 Calls/Monat	im Grundpreis enthalten
API-Calls darüber	CHF 0.40 / 1'000 Calls	nutzungsbasiert
AI-Verbrauch	pay-as-you-go in CHF, +15 % Plattformaufschlag auf Modellkosten, Cost-Cap pro Mandant	transparent nach Verbrauch

Beispiel-Monat: Grundgebühr 600 + 50k Calls (inkl.) + AI-Verbrauch CHF 200 + 15 % = ca. CHF 830 / Monat.

Kein User-/Seat-/Subscription-Pricing. Depoformance verrechnet seinen Endkunden eigenständig. Alle Preise CHF, exkl. MWST, Vorschlag/freibleibend. Stand 30.05.2026.

Betroffene Module

platform-core:
- Partner-Router /api/v1/depoformance/* (eigene Routendatei) — exponiert ihre Endpunkte, schleift intern durch + Response-Adapter auf ihr Format.
- Property-Match Feature-Datenmodell + RBAC-Katalog (Entitäten, Aktions-Endpunkte) → nutzt generische CRUD-/Pagination-/RBAC-Schicht.
- AI-Zugang über serviceAi (Modell-Auswahl, Audit, Streaming) — kein OpenRouter.
- Datenanbindungen via Konnektoren / serviceWeb / serviceKnowledge / serviceExtraction.
- Wiederverwendung: serviceMessaging (Mail/Notifications), i18n, SSE, Auth/RBAC, Rate-Limiting, AI-Audit-Log.
- OpenAPI-Doku für den Partner-Router.
platform: Mandant Depoformance + Feature-Instanz; CH-Residenz; Abrechnung (einmalig + API-Nutzung).
DB-Migration: ja (Property-Match-Domänenmodell).
ui-nyla: nicht betroffen.
Neutralisierung: in diesem Pfad bewusst nicht aktiv.

Entscheidungen

Datum	Entscheidung	Begründung
2026-05-30	Dedizierter Partner-Router `/api/v1/depoformance/*`, der ihre Endpunkte durchschleift	Stabiler Vertrag, entkoppelt von internen Routen, pro-Partner Auth/Rate-Limit/Billing
2026-05-30	Ihre Wünsche auf PORTA-Plattformbausteine abbilden statt projektspezifisches Backend bauen	Fast alles ist bereits Plattform-Standard
2026-05-30	Unser AI-Service statt OpenRouter	Modell-Auswahl, Billing, Audit, Streaming bereits vorhanden
2026-05-30	Keine Neutralisierung in diesem Pfad	Freier Modellzugang; Datenschutz verantwortet Depoformance
2026-05-30	Kein End-User-Management/Subscription über PORTA	Steht nicht in ihrer Doku; ihr UI ist eigenständig
2026-05-30	Pricing: einmalig CHF 24'000 + API-Grundgebühr CHF 600/Mo + AI pay-as-you-go	Einmalaufwand gedeckt, laufend nutzungsbasiert
2026-05-30	CH-Datenresidenz garantiert	Kundenanforderung

Offene Punkte (Produkt-/Business — keine Backend-Technik)

Datenhoheit/Umfang: Welche Entitäten hostet PORTA, was bleibt in ihrer App? Bleibt die Matching-Engine im Frontend oder soll sie ins Backend?
Welche Datenquellen sollen angebunden werden (Konnektor-Aufwand)?
Erwarteter AI-Verbrauch + Cost-Cap.
Vertragspartner und Go-Live-Termin.

Aufwand (grob, Richtwert, 1 Dev)

Siehe Kalkulation unter Pricing A) — ~16–21 PT für Partner-Router, AI-Durchschleifung, Daten-/Konnektor-Endpunkte, Response-Adapter, OpenAPI, Tenant-/Billing-Setup und Tests. Umfang skaliert mit dem Domänenanteil, den PORTA hostet (offener Punkt). Vorherige Detail-Schätzung:

Property-Match-Datenmodell + RBAC-Katalog + Aktions-Endpunkte: ~8–15 PT (Umfang abhängig vom gehosteten Domänenanteil)
AI-Zugang als /api/v1-Vertrag (Wrapper um serviceAi): ~3–5 PT
Datenanbindungen produktisieren: ~4–8 PT
OpenAPI-Doku + Tenant-/Billing-Setup: ~3–5 PT

15 KiB Raw Blame History Unescape Escape