220 lines
15 KiB
Markdown
220 lines
15 KiB
Markdown
<!-- 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`
|