Initial import: Rechte/Pflichten/Regelwerk fuer Modul-Entwickler

2026-07-28 20:13:09 +02:00
commit 02c1542868
11 changed files with 633 additions and 0 deletions
@@ -0,0 +1,51 @@
+# Core-API-Referenz für Module
+
+*(Quelle: `docs/core/core-api-implementation-plan.md` §3a/§9, `docs/core/hubrobotix-manifest.md`
+Gesetz 1/2, interne Server-Details entfernt)*
+
+## Grundprinzip
+
+Dein Modul-Code hält **nie** ein Datenbank-Passwort — auch nicht für dein eigenes Schema. Jeder
+Datenzugriff läuft über HTTP-Aufrufe gegen die Core-API, authentifiziert mit einem
+**pro-Modul-scoped Token** (`Authorization: Bearer <token>` + `X-Module-Key: <dein_module_key>`).
+
+## Zwei Endpunkt-Familien
+
+### 1. `mod/data/*` — deine eigenen Tabellen
+
+Eine generische, auf dein eigenes Schema (`mod_<dein_key>`) beschränkte Endpunkt-Familie für
+CRUD auf deinen eigenen Tabellen. Dein Token kann ausschließlich auf `mod_<dein_key>.*` zugreifen —
+selbst ein Bug in deinem Code kann nie eine fremde Tabelle erreichen (das ist keine reine
+Anwendungslogik-Prüfung, sondern serverseitig auf Datenbank-Rollen-Ebene erzwungen).
+
+### 2. Freigegebene Querschnittsdienste
+
+Für Funktionen, die dein Modul braucht, die aber Core-Daten betreffen (kein eigenes Schema):
+
+| Endpunkt | Zweck |
+|---|---|
+| `auth/verify` | JWT-Verifikation eines eingeloggten Nutzers |
+| `llm/complete` | KI-Vervollständigung (Anthropic/OpenAI/Ollama je nach Mandanten-Konfiguration) |
+| `prompt/get` | Lädt einen deklarierten Prompt-Text (System-Standard oder Mandanten-Override) |
+| `authz/check` | Prüft Modul-Freischaltung + Nutzerrechte für den aktuellen Request |
+| `template/render` | Rendert ein E-Mail-Template mit Platzhaltern |
+| `email/send` | Versendet eine E-Mail über den zentralen SMTP-Dienst |
+| `log/write` | Schreibt einen strukturierten Log-Eintrag |
+
+**Wichtig:** Für komplexere eigene Server-Logik (Joins, Transaktionen über mehrere eigene Tabellen,
+eigene Business-Regeln) gibt es **keinen** bespoken Custom-Endpunkt in der Core-API — diese Logik
+gehört in deinen eigenen Workflow/Dienst, der mehrere `mod/data/*`-Aufrufe kombiniert.
+
+## Fehlerbehandlung
+
+Jede Antwort mit HTTP-Status ≥ 400 enthält `{ "error": "<Nachricht>" }`. Statuscode 5xx zeigt einen
+internen Fehler an unsererseits (dein Modul sollte das nicht als Nutzerfehler behandeln), 4xx zeigt
+einen Fehler auf deiner Seite (falscher Scope, ungültige Parameter etc.).
+
+## Contract-Versionierung
+
+Die Core-API-Endpunkte stehen unter `/v1/...`. Dein `manifest.json` deklariert `"api_contract": "v1"`
+— ein zukünftiger `/v2`-Bruch wird rechtzeitig angekündigt und betrifft dich nur, wenn du selbst auf
+`v2` migrierst.
+
+Weiter mit [03-security-rules.md](03-security-rules.md).