<!-- status: idea -->
<!-- started: 2026-05-30 -->
<!-- component: platform-core | platform -->

# 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)

1. **Authentifizierung gegen PORTA** (Login/Token); Aufrufe mit dem von PORTA ausgestellten Token. Secret nie im Browser-Code.
2. **Server-zu-Server** aus ihrer App; kein direkter Browser-Call gegen PORTA.
3. **Response-/Fehlerformat** und **Pagination** (`limit`/`offset`) gemäss PORTA-Vertrag konsumieren.
4. **Rate-Limits** beachten (429 mit Backoff).
5. **Async**: lange Operationen (Extraktion, Ingestion) als Job-ID → Polling.
6. **Versionierter Vertrag** `/api/v1/...`.
7. **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

## Links

- Depoformance Techdoku: `pamocreate/projects/poweron/customer-depoformance/Techdoku_Depoformance_Property Match_Mai_2026.pdf`
- Pricing-Grundmodell: `pamocreate/projects/poweron/product-pricing/20-pricing-20260530/20260530-pricing-modelle.md`
- Referenzen: `b-reference/platform-core/architecture.md`, `b-reference/platform/rbac.md`, `b-reference/platform-core/billing.md`, `b-reference/platform/audit.md`, `b-reference/ui-nyla/formgenerator.md`