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

2026-10-26 13:27:35 +01:00
1 parent 10d5c6d563
commit 3480859d8a
@@ -0,0 +1,62 @@
+# 🛒 Kernmodul 4: Geteilte Listen & Kollaboration
+
+Das Modul für geteilte Listen ([`SharedListsView.tsx`](../../frontend/src/features/lists/SharedListsView.tsx)) ist auf **Echtzeit-Kollaboration im Alltag** ausgelegt (z.B. gemeinsamer Wocheneinkauf im Supermarkt, Packlisten für Reisen, Inventarlisten oder schnelle Checklisten).
+
+---
+
+## 🛍️ 1. Listen-Typen & Kategorien
+
+Jede Liste besitzt einen Typ, ein Icon und eine Farb-Codierung:
+
+| Listen-Typ | Icon | Einsatzzweck | Typische Kategorien |
+| :--- | :--- | :--- | :--- |
+| `shopping` | 🛒 | Supermarkt- & Lebensmitteleinkauf | Obst & Gemüse, Kühlregal, Vorrat, Drogerie |
+| `packing` | 🎒 | Urlaubs- & Reise-Packlisten | Kleidung, Elektronik, Dokumente, Kosmetik |
+| `inventory` | 📦 | Vorratskammer, Keller, Homelab-Hardware | Regal 1, Gefrierschrank, Server-Rack |
+| `todo` | 📝 | Einfache Gruppen-Checklisten | Heute, Später, Ideen |
+
+### Automatische Kategorisierung & Mengenangaben
+- Einträge können mit einer Mengenangabe (z.B. `3x`, `500g`, `1 Kasten`) versehen werden.
+- Die intelligente Eingabe erkennt Einheiten automatisch oder trennt Mengen über Eingabefelder.
+- Einträge werden übersichtlich nach Kategorien gruppiert. Jede Kategorie kann zur besseren Übersicht eingeklappt werden.
+
+---
+
+## ⚡ 2. Echtzeit-Abhaken (Multi-User Live Sync)
+
+Wenn mehrere Familienmitglieder oder Teammitglieder gleichzeitig im Supermarkt unterwegs sind, synchronisiert MindSift jeden Schritt in Echtzeit über WebSockets:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Alice as Alice (im Markt)
+    participant WS as WebSocket Hub
+    actor Bob as Bob (zu Hause)
+
+    Alice->>WS: PATCH /items/123 (isCompleted: true)
+    WS->>Bob: Event: ITEM_TOGGLED (itemId: "123", completedBy: "Alice")
+    Note over Bob: Eintrag wird sofort durchgestrichen<br/>Grünes Badge "von Alice" erscheint
+```
+
+- **Transparenz:** Beim Abhaken speichert MindSift `completed_by_name`. Ein dezentes grünes Pillen-Badge zeigt an, wer den Artikel eingepackt hat.
+- **Erledigte Einträge:** Abgehakte Artikel wandern nach unten in einen einklappbaren Bereich „Erledigt".
+- **Liste leeren:** Ein Klick auf „Erledigte entfernen" löscht alle abgehakten Einträge (`LIST_CLEARED`) für alle Teilnehmer.
+
+---
+
+## 🖐️ 3. Drag & Drop Umsortierung
+
+Innerhalb einer Liste können Einträge frei per Drag & Drop sortiert werden:
+1. **Innerhalb einer Kategorie:** Ändert die Reihenfolge (`sort_order`).
+2. **Kategorie-Übergreifend:** Zieht der Benutzer einen Eintrag in eine andere Kategorie (z.B. von „Kühlregal" nach „Obst & Gemüse"), aktualisiert das Frontend optimistisch die Kategorie und sendet das Update ans Backend.
+
+---
+
+## 👥 4. Freigaben & Berechtigungen
+
+Listen können über den einheitlichen Freigabe-Dialog ([`UnifiedShareModal.tsx`](../../frontend/src/components/UnifiedShareModal.tsx)) geteilt werden:
+- **Freigabe für Teams:** Alle aktuellen und zukünftigen Mitglieder der gewählten Gruppe erhalten automatisch Zugriff.
+- **Freigabe für Einzelbenutzer:** Gezielter Zugriff für einzelne Personen.
+- **Rollen:**
+  - `editor`: Darf Einträge hinzufügen, bearbeiten, abhaken und löschen.
+  - `viewer`: Nur Lesezugriff (Einträge ansehen, aber nicht verändern).
@@ -0,0 +1,86 @@
+# 📋 Kernmodul 2: Aufgaben & Kanban-System
+
+Das Aufgaben-Modul ([`TasksView.tsx`](../../frontend/src/features/triage/TasksView.tsx)) bietet eine flexible Aufgabenverwaltung mit frei konfigurierbaren Listen, Kanban-Boards, Subtask-Checklisten und einem automatisierten Multi-Channel Alarm-System.
+
+---
+
+## 🗂️ 1. Datenmodell & Listen-Hierarchie
+
+Aufgaben basieren technisch auf der Tabelle **`thoughts`** in SQLite. Ein Eintrag gilt als Aufgabe, wenn `status = 'kept'` oder `(status = 'converted' AND converted_type = 'task')` zutrifft.
+
+```
+Benutzer (users)
+  └── Aufgabenlisten (task_lists)
+        ├── Eigene Listen (z.B. "Privat", "Homelab")
+        └── Mit Teams geteilte Listen (task_list_shares)
+              └── Aufgaben (thoughts)
+                    ├── Kanban-Status (todo, in_progress, done)
+                    ├── Priorität (low, normal, high, urgent)
+                    ├── Fälligkeitsdatum (dueDate)
+                    ├── Notizen (notes)
+                    └── Subtasks (JSON Array von Teilaufgaben)
+```
+
+### Listen-Sharing & Avatar-Stack
+Aufgabenlisten können für Gruppen/Teams freigegeben werden. Ein Avatar-Stack im Listen-Header und in der Tab-Leiste visualisiert alle Mitglieder, die Zugriff auf die jeweilige Liste haben.
+
+---
+
+## 🖥️ 2. Ansichten: Liste vs. Kanban-Board
+
+Der Benutzer kann jederzeit nahtlos zwischen zwei Ansichten umschalten:
+
+### 1. Kompakte Listenansicht
+- Optimiert für schnelles Abarbeiten und Tastatursteuerung.
+- Zeigt Checkbox, Titel, Prioritäts-Badge, Herkunfts-Pille (`Webhook`, `Diktat`), Fälligkeitsdatum und Subtask-Zähler (`2/5`).
+- 1-Klick-Prioritäts-Wechsel: Klick auf ein Badge rotiert durch die Prioritäten.
+
+### 2. Kanban-Board (Drag & Drop)
+- Standardmäßig 3 Spalten: **Zu erledigen** (`todo`), **In Arbeit** (`in_progress`) und **Erledigt** (`done`).
+- **Freie Spalten-Konfiguration:** Über das Spalten-Menü können Spalten umbenannt, farblich markiert oder neue Spalten hinzugefügt werden.
+- **Drag & Drop:** Aufgaben können per HTML5 Drag & Drop zwischen Spalten verschoben werden. Das Backend speichert die relative Position (`sort_order`) und den neuen `kanban_status` automatisch.
+
+---
+
+## 🎯 3. Prioritäten & Subtasks
+
+### 4-Stufen-Prioritätensystem
+Aufgaben unterstützen vier einheitliche Prioritätsstufen:
+- **Niedrig (`low`):** Dezent grau hinterlegt.
+- **Normal (`normal`):** Akzentfarbe.
+- **Wichtig (`high`):** Gelb hervorgehoben mit Warndreieck (`⚠️ Wichtig`).
+- **Dringend (`urgent`):** Rot pulsierend mit Flammen-Icon (`🔥 Dringend`).
+
+### Subtasks (Teilaufgaben)
+Jede Aufgabe kann eine hierarchische Checkliste von Subtasks enthalten:
+- Gespeichert als JSON in der Spalte `subtasks`.
+- Fortschrittsanzeige im Kartenkopf (z.B. `3/5 erledigt`).
+- Einzelnes Abhaken synchronisiert direkt in die Datenbank.
+
+---
+
+## ⏰ 4. Multi-Channel Alarm-Scheduler
+
+MindSift enthält einen serverseitigen Hintergrund-Ticker in Go ([`internal/api/server.go`](../../internal/api/server.go)), der fällige Aufgaben proaktiv an externe Kanäle meldet.
+
+```mermaid
+flowchart TD
+    Ticker["Go Background Ticker (alle 30s)"] --> Query["SELECT thoughts WHERE due_date <= now + Vorwarnzeit AND alarm_sent = 0"]
+    Query --> CheckChannels{"Welche Kanäle sind beim User aktiv?"}
+    
+    CheckChannels -->|email| SendSMTP["E-Mail via SMTP versenden"]
+    CheckChannels -->|discord| SendDiscord["Discord Webhook POST"]
+    CheckChannels -->|webhook| SendCustom["Custom HTTP POST Webhook"]
+    
+    SendSMTP --> MarkSent["UPDATE thoughts SET alarm_sent = 1"]
+    SendDiscord --> MarkSent
+    SendCustom --> MarkSent
+```
+
+### Alarm-Konfiguration
+1. **Vorwarnzeit:** Einstellbar in Minuten (z.B. 15, 30, 60 Minuten vor Fälligkeit).
+2. **Kanal-Multi-Select:** Benutzer können beliebig viele Kanäle parallel aktivieren:
+   - **E-Mail:** Versand über den in den Admin-Einstellungen hinterlegten SMTP-Server.
+   - **Discord:** Benachrichtigung mit formatierter Embed-Karte in einen Discord-Kanal.
+   - **Eigener Webhook:** Beliebige HTTP POST JSON Endpunkte (z.B. Gotify, Ntfy, Home Assistant).
+3. **Schutz vor Doppel-Alarmen:** Sobald ein Alarm abgesetzt wurde, wird `alarm_sent = 1` gesetzt. Wird das Datum der Aufgabe später geändert, setzt der Server `alarm_sent = 0` automatisch zurück.
@@ -0,0 +1,88 @@
+# 📥 Kernmodul 1: Triage & Quick-Dump Engine
+
+Das Triage-Modul von MindSift basiert auf dem *Getting Things Done (GTD)*-Prinzip. Es trennt die **Erfassung von Gedanken** strikt von der **Entscheidung, was damit geschehen soll**.
+
+---
+
+## 💡 1. Das 2-Phasen-Konzept
+
+1. **Phase 1: Schnelles Erfassen (Instant Dump)**  
+   Ein Gedanke, ein Anruf, eine Idee oder ein Server-Alarm wird ohne Reibung erfasst. Der Benutzer muss in diesem Moment weder ein Projekt auswählen, noch Fälligkeitsdaten eingeben oder Ordner durchsuchen.
+2. **Phase 2: Fokussierte Triage (Inbox Zero)**  
+   Zu einem späteren Zeitpunkt (z.B. morgens oder beim Feierabend) sichtet der Benutzer den Stapel im Triage-Deck Karte für Karte und trifft für jeden Eintrag eine eindeutige Entscheidung.
+
+---
+
+## 🔄 2. Triage State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Capture: Gedanke erfasst (Desktop / Mobile / Webhook)
+    
+    Capture --> Inbox: Standard (status: 'inbox')
+    Capture --> Task: Direkt als Aufgabe (target: 'task')
+    Capture --> Document: Direkt als Notiz (target: 'document')
+    Capture --> ListItem: Direkt auf Liste (target: 'list_item')
+
+    state Inbox {
+        [*] --> ActiveCard: Oben auf Stapel
+        ActiveCard --> Skipped: Leertaste / Später (Ans Ende)
+        Skipped --> ActiveCard
+    }
+
+    ActiveCard --> Discarded: Swipe links / H (Wegwerfen)
+    ActiveCard --> Task: Swipe rechts / L (Als Aufgabe)
+    ActiveCard --> TaskDated: T (Mit Fälligkeitsdatum)
+    ActiveCard --> Document: D (In Notiz umwandeln)
+    ActiveCard --> ListItem: Auf Liste schieben
+
+    Discarded --> Trash: status: 'discarded'
+    Task --> TasksModule: status: 'kept', converted: 'task'
+    TaskDated --> TasksModule: status: 'kept', converted: 'task', dueDate
+    Document --> WorkspaceModule: status: 'converted', converted: 'document'
+    ListItem --> ListsModule: status: 'converted', converted: 'list_item'
+```
+
+---
+
+## 🖐️ 3. Steuerung & Gesten (Mobile vs. Desktop)
+
+### Desktop-Bedienung (Tastatur-First)
+- `C` oder `/`: Fokussiert sofort die Eingabeleiste oben im Header.
+- `Enter`: Speichert den Gedanken sofort im Deck.
+- `←` oder `H`: Aktive Karte wegwerfen (`discard`).
+- `→` oder `L`: Aktive Karte sofort zur Aufgabe machen (`task`).
+- `T`: Datumsauswahl für Termin-Aufgabe öffnen.
+- `D`: Aktive Karte in eine vollwertige Workspace-Notiz umwandeln.
+- `Leertaste`: Karte überspringen und ans Ende des Stapels schieben („Später").
+
+### Mobile Bedienung (Touch & Swipe)
+- **Mittlerer Plus-Button (`+`):** Öffnet das design-angeglichene Bottom-Sheet mit Spracheingabe, 4 Prioritäts-Buttons (`Niedrig`, `Normal`, `Wichtig`, `Dringend`) und Fälligkeitsdatum.
+- **Wischgeste nach links (Swipe Left):** Roter Indikator erscheint, Karte wird verworfen.
+- **Wischgeste nach rechts (Swipe Right):** Grüner Indikator erscheint, Karte wird sofort zur Aufgabe.
+- **Long-Press (Langes Drücken auf Karte):** Öffnet das Schnell-Aktions-Menü (Auf Liste, Mit Termin, Als Notiz, Später).
+
+---
+
+## 🎙️ 4. Spracheingabe (Speech-to-Text)
+
+In der Desktop-Schnelleingabeleiste ([`InstantCaptureBar.tsx`](../../frontend/src/features/capture/InstantCaptureBar.tsx)) sowie im mobilen Triage-Modal ([`App.tsx`](../../frontend/src/App.tsx)) ist ein nativer Browser-Sprachassistent integriert:
+- Verwendet die standardisierte `SpeechRecognition` bzw. `webkitSpeechRecognition` API.
+- Erkennt Sprache auf Deutsch (`lang: 'de-DE'`).
+- Live-Transkription: Gesprochener Text wird in Echtzeit in das Textfeld eingefügt.
+- Haptisches Feedback: Vibrieren beim Starten und Stoppen der Aufnahme.
+- Markiert erfasste Gedanken automatisch mit dem Herkunfts-Attribut `source: 'voice'` (Diktat-Badge).
+
+---
+
+## ⚡ 5. Webhook-Ingestion & Smarthome-Pille
+
+MindSift kann externe Alarme (Home Assistant, Zigbee2MQTT, n8n, Proxmox, Monitoring) automatisch ins Triage-Deck einspeisen:
+
+### Herkunftserkennung
+1. Wird ein Gedanke über `/api/v1/inbox` mit `X-API-Key` oder über `/api/v1/webhooks/ingest` eingeliefert, setzt das Backend automatisch `source = "webhook"`.
+2. Im Frontend visualisiert die Triage-Karte eine dezente Webhook-Pille (`<Webhook className="w-3 h-3 text-accent" /> Webhook`).
+3. Diese Kennzeichnung bleibt auch erhalten, wenn die Karte später zu einer Aufgabe umgewandelt wird.
+
+### Live-WebSocket Update
+Nach erfolgreichem Ingest sendet der Server sofort ein `TASK_CREATED` Event über den WebSocket-Hub. Das geöffnete Triage-Deck fügt die neue Alarm-Karte sofort oben in den Stapel ein – ohne dass der Benutzer die Seite neu laden muss.
@@ -0,0 +1,82 @@
+# 📝 Kernmodul 3: Workspace Outliner-Engine, Wiki-Links & Disk-Sync
+
+Der MindSift Workspace ([`WorkspaceView.tsx`](../../frontend/src/features/workspace/WorkspaceView.tsx)) kombiniert ein **hierarchisches Bullet-Point Notizsystem (inspiriert von Logseq)** mit einem **persönlichen Markdown-Wiki** und einem **globalen To-Do Rollup Dashboard**.
+
+---
+
+## 🌳 1. Die Logseq-Outliner-Engine
+
+Im Gegensatz zu klassischen Fließtext-Editoren basiert der MindSift Workspace auf **Blöcken** (`document_blocks` in SQLite). Jeder Block ist ein gedanklicher Knotenpunkt mit einer flexiblen Einrückungsebene (`level: 0, 1, 2, ...`).
+
+```
+• Projekt MindSift v2.0 (level 0)
+  • Architektur-Entscheidung (level 1)
+    - [x] Database-First Blocks implementieren (level 2)
+    - [ ] Performance Benchmark mit 10.000 Blöcken (level 2)
+  • Notizen aus dem Dev-Meeting (level 1)
+    > Wichtig: Keine verschachtelten SQLite Queries ausführen! (level 2)
+```
+
+### Tastatur-Navigation & Shortcuts
+- `Enter`: Erstellt einen neuen Block auf derselben Hierarchieebene.
+- `Tab`: Rückt den aktuellen Block ein (wird Kindknoten des vorherigen Blocks).
+- `Shift + Tab`: Rückt den Block um eine Ebene aus (verringert die Tiefe).
+- `Shift + Enter`: Weicher Zeilenumbruch innerhalb desselben Blocks (z.B. für mehrzeilige Notizen oder Code).
+- `Backspace` (auf leerem Block): Rückt den Block aus oder löscht ihn, wenn er auf Level 0 ist.
+- `/` (Slash-Commands): Öffnet das Umwandlungsmenü (`/todo`, `/h1`, `/h2`, `/h3`, `/code`, `/callout`, `/quote`, `/divider`).
+
+### Zoom-In Hoisting (Fokus-Modus)
+Klickt der Benutzer auf den Bullet-Dot (`•`) eines Blocks, blendet der Editor alle übergeordneten und benachbarten Blöcke aus und zoomt **ausschließlich in diesen Ast** hinein. 
+- Eine dezente Breadcrumb-Leiste oben zeigt den Pfad an (z.B. `Workspace / Projekte / MindSift / Architektur`).
+- Ein Klick auf ein beliebiges Breadcrumb-Element zoomt sofort auf die jeweilige Ebene zurück.
+
+### Drag & Drop von Blöcken
+Der Bullet-Dot dient gleichzeitig als Drag-Anfasser. Wird ein Block verschoben, erkennt die Engine automatisch alle untergeordneten Kind-Blöcke (`isDescendantBlock`) und verschiebt den **kompletten Unterbaum** an die neue Zielposition.
+
+---
+
+## 🔗 2. Wiki-Links (`[[Link]]`) & Hashtags
+
+1. **Interne Wiki-Links:**
+   - Text in doppelten eckigen Klammern (z.B. `[[Reiseplanung 2026]]`) wird automatisch als klickbarer Link gerendert.
+   - Ein Klick darauf durchsucht die Notizen des Benutzers und öffnet das Ziel-Dokument direkt im Editor.
+2. **Hashtags (`#tag`):**
+   - Hashtags im Fließtext werden automatisch indiziert (`doc_block_tags`-Tabelle).
+   - In der linken Leiste listet der Tag-Explorer alle verwendeten Schlagworte auf. Klick auf ein Tag filtert alle Dokumente und Blöcke, die dieses Tag enthalten.
+
+---
+
+## 💾 3. Dual-Storage: Database-First & Disk-Mirroring
+
+MindSift löst das Dilemma zwischen schneller relationaler Abfrage und portabler Dateispeicherung durch ein **synchrones Dual-Storage-Modell**:
+
+```
+Client (Block-Editor)
+        │ PATCH /api/v1/documents/:id/blocks
+        ▼
+   Backend Engine
+   ┌──────────────────────────────────────────────┐
+   │ 1. Transaktion in SQLite (document_blocks)   │
+   │    -> Sort-Order, Content, Level, Checked    │
+   │ 2. Volltext-Generierung (Markdown-String)    │
+   │ 3. Schreiben auf Disk (/data/workspace/...)  │
+   └──────────────────────────────────────────────┘
+```
+
+1. **Präzision & Geschwindigkeit (SQLite):**
+   - Jeder Block besitzt eine eindeutige ID (`blk_...`) und eine Gleitkomma-Reihenfolge (`sort_order REAL`).
+   - Schnelle Status-Updates (z.B. Checkbox abhaken) schreiben nur genau eine Zeile in die Datenbank.
+2. **Datensouveränität & Portabilität (Disk-Mirror):**
+   - Zeitgleich spiegelt der Server das Dokument als Standard-`.md`-Datei unter `/data/workspace/<user_id>/<ordner>/<dateiname>.md`.
+   - Einrückungen werden nach dem 2-Leerzeichen-Standard (`  - [ ] `) formatiert.
+   - Administratoren können das Verzeichnis jederzeit mit externen Werkzeugen (Obsidian, Logseq, Git, rsync) sichern.
+
+---
+
+## 📊 4. Globaler To-Do Rollup Dashboard
+
+Über den Tab **„Globale To-Dos"** bietet der Workspace eine aggregierte Übersicht aller im gesamten Wiki verteilten Aufgaben:
+- Scannt in Echtzeit alle unvollendeten `- [ ] ` Checkboxen über alle Ordner und Notizen hinweg.
+- Übersichtliche Gruppierung nach **Ordner ➔ Dokument ➔ Aufgabe**.
+- **Ordner-Filter:** Klick auf einen Ordner isoliert nur dessen Aufgaben für fokussiertes Arbeiten.
+- **2-Wege-Live-Sync:** Wird eine Checkbox im Rollup abgehakt, wird der Block in SQLite sofort auf `checked = 1` aktualisiert und die physische `.md`-Datei synchronisiert.