docs: add comprehensive technical wiki documentation and flaws analysis; remove legacy BRAIN.md

Doku/api/rest.md

@@ -0,0 +1,185 @@
+# 🔌 REST-API Referenz
+
+Die MindSift REST-API ermöglicht den vollständigen Zugriff auf Gedanken, Aufgaben, Workspace-Notizen, Listen, Benutzerkonten und Smarthome-Automationen.
+
+---
+
+## 🔐 1. Authentifizierung
+
+MindSift unterstützt zwei Authentifizierungsmethoden:
+
+1. **JSON Web Token (JWT Bearer):**  
+   Wird beim Login oder Setup erzeugt und im HTTP-Header mitgesendet:  
+   `Authorization: Bearer <jwt-token>`
+2. **Persönliche API-Schlüssel (Smarthome / Automatisierung):**  
+   Werden unter *Einstellungen ➔ Private Webhooks* erzeugt (Präfix `mindsift_sec_...`):  
+   - Per HTTP-Header: `X-API-Key: mindsift_sec_xxxxxxxxxxxx`
+   - Per Authorization-Header: `Authorization: Bearer mindsift_sec_xxxxxxxxxxxx`
+   - Per Query-Parameter: `?token=mindsift_sec_xxxxxxxxxxxx`
+
+---
+
+## 🚦 2. Status- & Fehler-Codes
+
+- `200 OK`: Erfolgreiche Abfrage oder Aktualisierung.
+- `201 Created`: Ressource erfolgreich angelegt.
+- `400 Bad Request`: Ungültiges JSON oder fehlende Pflichtfelder.
+- `401 Unauthorized`: Token ungültig, abgelaufen oder fehlend.
+- `403 Forbidden`: Unzureichende Berechtigungen (z.B. nur Server-Admin oder nur Lesezugriff).
+- `404 Not Found`: Ressource existiert nicht oder gehört einem anderen Benutzer.
+- `409 Conflict`: Ressource gesperrt (z.B. Dokument wird bereits von anderem Benutzer bearbeitet).
+
+Fehlerrückgaben erfolgen im einheitlichen Format:
+```json
+{
+  "error": "Fehlermeldung im Klartext"
+}
+```
+
+---
+
+## 📋 3. Endpunkte nach Modulen
+
+### 3.1 Authentifizierung & System-Status
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/api/v1/health` | Öffentlich | Liveness-Check (`{"status":"ok"}`) |
+| `GET` | `/api/v1/auth/status` | Öffentlich | Prüft ob Ersteinrichtung nötig ist (`needsSetup: true/false`) |
+| `POST` | `/api/v1/auth/setup` | Öffentlich | Führt First-Boot Setup durch (legt ersten Admin an) |
+| `POST` | `/api/v1/auth/register` | Öffentlich | Registrierung über Einladungscode (`inviteCode`) |
+| `POST` | `/api/v1/auth/login` | Öffentlich | Login via E-Mail oder Benutzername + Passwort |
+| `GET` | `/api/v1/auth/me` | JWT | Gibt das aktuelle Benutzerprofil zurück |
+| `PATCH` | `/api/v1/auth/settings` | JWT | Aktualisiert Profil, Passwort, Theme oder Alarm-Kanäle |
+| `POST` | `/api/v1/auth/alarms/test` | JWT | Sendet Test-Alarm an E-Mail, Discord oder Custom Webhook |
+
+#### Beispiel: `POST /api/v1/auth/login`
+```json
+// Request
+{
+  "login": "sandro",
+  "password": "geheimesPasswort123"
+}
+
+// Response (200 OK)
+{
+  "token": "eyJhbGciOiJIUzI1NiIs...",
+  "user": {
+    "id": "usr_abc123",
+    "email": "sandro@example.com",
+    "username": "sandro",
+    "displayName": "Sandro",
+    "role": "admin",
+    "alarmChannels": ["discord", "webhook"]
+  }
+}
+```
+
+---
+
+### 3.2 Triage & Instant Capture
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `POST` | `/api/v1/inbox` | JWT / API-Key | Erfasst einen neuen Quick Dump oder leitet direkt weiter |
+| `GET` | `/api/v1/triage/deck` | JWT | Liefert den Stapel aller noch nicht triagierten Gedanken (`status: 'inbox'`) |
+| `PATCH` | `/api/v1/triage/{id}` | JWT | Führt Triage-Aktion aus (`keep`, `discard`, `restore`) |
+
+#### Beispiel: `POST /api/v1/inbox`
+Ermöglicht flexible Direkt-Zuordnungen:
+```json
+// Request (Quick Dump in Triage-Deck)
+{
+  "content": "Kellerfeuchtigkeit über 68% gestiegen #smarthome #alarm",
+  "priority": "urgent"
+}
+
+// Request (Direkt als Aufgabe anlegen)
+{
+  "content": "Server Backup prüfen #devops",
+  "priority": "high",
+  "target": "task",
+  "dueDate": "2026-10-30"
+}
+```
+*Hinweis:* Wenn `/api/v1/inbox` über einen API-Key aufgerufen wird und kein `source` definiert ist, wird die Quelle automatisch als `"webhook"` markiert!
+
+---
+
+### 3.3 Aufgaben & Kanban-System
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/api/v1/tasks` | JWT | Liefert alle Aufgaben des Benutzers (inkl. geteilter Aufgaben) |
+| `POST` | `/api/v1/tasks/reorder` | JWT | Speichert Kanban-Status und Reihenfolge (`sort_order`) |
+| `GET` | `/api/v1/task-lists` | JWT | Liefert alle Aufgabenlisten (eigene & geteilte) |
+| `POST` | `/api/v1/task-lists` | JWT | Erstellt eine neue Aufgabenliste (mit Farbe & Spalten) |
+| `PUT` | `/api/v1/task-lists/{id}` | JWT | Ändert Titel, Farbe, Icon oder Kanban-Spalten |
+| `DELETE` | `/api/v1/task-lists/{id}` | JWT | Löscht Aufgabenliste |
+| `POST` | `/api/v1/task-lists/{id}/shares` | JWT | Teilt Liste mit Team oder Benutzer |
+
+---
+
+### 3.4 Workspace & Dokumente
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/api/v1/documents` | JWT | Liefert Liste aller Dokumente des Benutzers (Metadaten) |
+| `POST` | `/api/v1/documents` | JWT | Erstellt neues Notiz-Dokument (mit Blocks oder Markdown) |
+| `GET` | `/api/v1/documents/{id}` | JWT | Lädt komplettes Dokument inklusive aller Blöcke |
+| `PUT` | `/api/v1/documents/{id}` | JWT | Aktualisiert Dokumenttitel, Icon oder Ordnerpfad |
+| `PATCH` | `/api/v1/documents/{id}/blocks` | JWT | Granulares Patching von Dokument-Blöcken (Database-First) |
+| `DELETE` | `/api/v1/documents/{id}` | JWT | Löscht Dokument (Datenbank & physische Datei) |
+| `POST` | `/api/v1/documents/{id}/shares` | JWT | Notiz mit anderem Benutzer teilen (`read` / `write`) |
+| `GET` | `/api/v1/documents/{id}/lock` | JWT | Fragt Bearbeitungs-Sperrstatus ab |
+| `POST` | `/api/v1/documents/{id}/lock` | JWT | Sperrt Dokument für Bearbeitung (30s Lease) |
+| `DELETE` | `/api/v1/documents/{id}/lock` | JWT | Gibt Bearbeitungssperre wieder frei |
+
+---
+
+### 3.5 Workspace Ordner & Geteilte Ordner
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/api/v1/folders` | JWT | Liefert alle Ordnerpfade des Benutzers |
+| `POST` | `/api/v1/folders` | JWT | Legt neuen (auch leeren) Ordner an |
+| `POST` | `/api/v1/folders/move` | JWT | Benennt Ordner um oder verschiebt ihn hierarchisch |
+| `DELETE` | `/api/v1/folders` | JWT | Löscht Ordner und verschiebt Notizen |
+| `GET` | `/api/v1/workspace/folders/shared` | JWT | Liefert für den Benutzer freigegebene geteilte Ordner |
+| `POST` | `/api/v1/workspace/folders/shared` | JWT | Erstellt neuen geteilten Ordner |
+| `PUT` | `/api/v1/workspace/folders/shared/{id}/mount` | JWT | Ändert den lokalen Einhängepfad beim Empfänger |
+| `POST` | `/api/v1/workspace/folders/shared/{id}/shares` | JWT | Gibt Ordner für Teams oder Benutzer frei |
+
+---
+
+### 3.6 Geteilte Listen (Listen & Einkauf)
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/api/v1/lists` | JWT | Liefert alle geteilten Listen |
+| `POST` | `/api/v1/lists` | JWT | Erstellt neue geteilte Liste |
+| `GET` | `/api/v1/lists/{id}` | JWT | Lädt Liste inklusive aller Einträge |
+| `POST` | `/api/v1/lists/{id}/items` | JWT | Fügt Eintrag hinzu |
+| `PATCH` | `/api/v1/lists/{id}/items/{itemId}` | JWT | Hakt Eintrag ab (`isCompleted: true/false`) |
+| `POST` | `/api/v1/lists/{id}/items/reorder` | JWT | Speichert sortierte Einträge |
+| `POST` | `/api/v1/lists/{id}/clear-completed`| JWT | Löscht alle abgehakten Einträge |
+| `POST` | `/api/v1/lists/{id}/shares` | JWT | Teilt Liste mit Team oder Benutzer |
+
+---
+
+### 3.7 Smarthome Ingestion & Externe Webhooks
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `POST` | `/api/v1/webhooks/ingest` | Token / Key | Empfängt externe Webhook-Payloads von Home Assistant / n8n |
+
+#### Beispiel: `POST /api/v1/webhooks/ingest?token=mindsift_sec_...`
+Unterstützt flexible Payloads (JSON oder Plain Text):
+```json
+{
+  "title": "Waschmaschine Keller fertig",
+  "priority": "high",
+  "tags": ["smarthome", "keller"]
+}
+```
+*Live-Aktualisierung:* Sendet automatisch ein `TASK_CREATED` WebSocket-Event an alle Clients des Benutzers, sodass die neue Karte sofort ohne Neuladen im Triage-Deck erscheint!