feat: zentrale selfhost-dienste bereitstellen

push-server/README.md

@@ -1,6 +1,6 @@
-# FEDEO Push Server
+# FEDEO Central Services
 
-Eigenständiger Stack für den zentralen FEDEO Push-Transportdienst. Selfhosted FEDEO-Instanzen registrieren Geräte lokal und leiten nur technische Push-Aufträge an diesen Dienst weiter. Die Instanzen authentifizieren sich mit einem rotierbaren Schlüssel, der im Admin-Dashboard gepflegt wird.
+Eigenständiger Stack für zentrale FEDEO-Dienste. Neben Push können Selfhost-Instanzen darüber freigeschaltete und verbrauchsabhängig erfasste KI- und Banking-Dienste verwenden. Die Instanzen authentifizieren sich mit einem rotierbaren HMAC-Schlüssel, der im Admin-Dashboard gepflegt wird.
 
 ## Bestandteile
 
@@ -9,6 +9,8 @@ Eigenständiger Stack für den zentralen FEDEO Push-Transportdienst. Selfhosted
 - `packages/db`: Drizzle Schema und Migrationen für PostgreSQL
 - `docker-compose.yml`: lokaler Stack aus Postgres, API und Admin
 
+Provider-Schlüssel wie `OPENAI_API_KEY` und die GoCardless-Zugangsdaten liegen ausschließlich in diesem zentralen Stack. Selfhost-Instanzen erhalten nur Instanz-ID und Instanzschlüssel.
+
 ## Entwicklung
 
 ```bash
@@ -20,6 +22,16 @@ npm run dev:api
 npm run dev:admin
 ```
 
+Für den dauerhaften Betrieb:
+
+```bash
+cp .env.example .env
+# .env mit sicheren Zugangsdaten und Provider-Schlüsseln befüllen
+docker compose up -d --build
+```
+
+Der API-Container wendet Datenbankmigrationen vor jedem Start automatisch an. PostgreSQL-Daten liegen im Volume `push_postgres_data`. Für ein öffentliches Deployment müssen API und Admin hinter einem TLS-Reverse-Proxy betrieben und `PUBLIC_API_BASE_URL` auf die öffentliche API-Adresse gesetzt werden.
+
 Standardports:
 
 - API: `http://localhost:4020`
@@ -70,6 +82,13 @@ const signature = createHmac("sha256", clientSecret).update(canonical).digest("h
 - `DELETE /v1/devices/:centralDeviceId`
 - `POST /v1/push`
 - `GET /v1/push/:deliveryJobId`
+- `POST /v1/services/ai/chat-completions`
+- `GET /v1/services/banking/institutions`
+- `POST /v1/services/banking/requisitions`
+- `GET /v1/services/banking/requisitions/:id`
+- `GET /v1/services/banking/accounts/:id`
+- `GET /v1/services/banking/accounts/:id/balances`
+- `GET /v1/services/banking/accounts/:id/transactions`
 
 Admin:
 
@@ -80,6 +99,19 @@ Admin:
 - `POST /admin/instances/:id/rotate-secret`
 - `GET /admin/instances/:id/devices`
 - `GET /admin/instances/:id/jobs`
+- `GET /admin/instances/:id/services`
+- `PUT /admin/instances/:id/services/:service`
+- `GET /admin/instances/:id/usage`
+- `GET /admin/usage/summary`
+
+## Freischaltung und Abrechnung
+
+Die Dienste `ai` und `banking` sind für neue Instanzen standardmäßig gesperrt. Im Instanzdetail des Admin-Dashboards werden sie einzeln aktiviert. Pro Dienst können ein Monatslimit und ein Preis in Mikro-Euro je Einheit gepflegt werden.
+
+- KI wird anhand der von OpenAI gemeldeten Gesamt-Token erfasst.
+- Banking wird je erfolgreichem Provider-Aufruf erfasst.
+- Fehlgeschlagene Aufrufe werden technisch protokolliert, aber mit `0` Einheiten und `0` Kosten verbucht.
+- Usage Events enthalten technische Metadaten, aber keine Prompts, Bankumsätze oder sonstigen fachlichen Nutzdaten.
 
 ## Apple Push Notification service
 
@@ -106,6 +138,9 @@ Implementiert:
 - Zustelljobs mit Idempotenzschlüssel
 - APNs-Zustellung für iOS
 - technische Status- und Fehlererfassung
+- dienstbezogene Freischaltungen und Monatslimits
+- unveränderliche Usage Events samt Kostenwert
+- zentraler OpenAI- und GoCardless-Zugang
 
 Vorbereitet, aber noch nicht vollständig implementiert:
 
@@ -113,3 +148,4 @@ Vorbereitet, aber noch nicht vollständig implementiert:
 - FCM Zustellung
 - asynchrone Queue/Worker-Verarbeitung
 - produktive Rate-Limits pro Instanz
+- Rechnungsstellung beziehungsweise Export an ein Buchhaltungssystem