docs: rewrite documentation and README from current codebase, add flaw analysis
MindSift CI & Docker Release / Build, Test in Container & Push (push) Successful in 8s
MindSift CI & Docker Release / Build, Test in Container & Push (push) Successful in 8s
Remove outdated claims (CRDT, DocRooms, presence, .md files on disk) and document the actual architecture, API, permissions and known flaws. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
sandrodachandClaude Sonnet 5.5 committed
1 parent
4e9c4ffa8c
commit
bc13235da6
14 files changed
+733
-1618
No files matched your search
+25
-77
@@ -1,88 +1,36 @@
|
||||
# 📥 Kernmodul 1: Triage & Quick-Dump Engine
|
||||
# Modul: Schnellerfassung & Triage
|
||||
|
||||
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**.
|
||||
Ziel: Gedanken in Sekunden festhalten und später in Ruhe sortieren. Code: [InstantCaptureBar.tsx](../../frontend/src/features/capture/InstantCaptureBar.tsx), [TriageDeck.tsx](../../frontend/src/features/triage/TriageDeck.tsx), Backend `handleCaptureInbox`, `handleTriageAction` und `Store.UpdateThoughtTriage`.
|
||||
|
||||
---
|
||||
## Erfassung
|
||||
|
||||
## 💡 1. Das 2-Phasen-Konzept
|
||||
- Die Eingabeleiste sitzt im Header; `C` oder `/` fokussiert sie (außer beim Tippen in einem Feld).
|
||||
- Ziel (`target`): **Posteingang** (`inbox`, Standard), **Direkt-Aufgabe** (`task`), **Listeneintrag** (`list_item`, mit Zielliste) oder **Direkt-Notiz** (`document`).
|
||||
- Mehrzeilige Eingabe wird unterstützt. Spracheingabe nutzt die Web Speech API des Browsers; Quelle `voice` fügt den Tag `#diktat` an.
|
||||
- Quelle `webhook` (per API-Key/Webhook) fügt den Tag `#webhook` an. Hashtags im Text werden als Tags extrahiert (`domain.ExtractTags`).
|
||||
- Per API: `POST /inbox` und `POST /webhooks/ingest` (siehe [rest.md](../api/rest.md)).
|
||||
|
||||
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.
|
||||
## Triage-Deck
|
||||
|
||||
---
|
||||
Der Posteingang (`status = inbox`) wird Karte für Karte abgearbeitet.
|
||||
|
||||
## 🔄 2. Triage State Machine
|
||||
| Aktion | Desktop | Mobil | Ergebnis |
|
||||
|---|---|---|---|
|
||||
| Verwerfen | `H` oder `←` | Wischen links | `status = discarded` (Papierkorb) |
|
||||
| Zur Aufgabe | `L` oder `→` | Wischen rechts | `kept`/`converted` als Aufgabe |
|
||||
| Aufgabe mit Termin | `T` | Aktionsmenü | wie oben, mit Fälligkeit |
|
||||
| In Notiz wandeln | `D` | Aktionsmenü | neues Dokument, Gedanke wird `converted` (`document`) |
|
||||
| Später | Leertaste | Aktionsmenü | Karte ans Stapelende |
|
||||
| Menü schließen | `Esc` | – | – |
|
||||
|
||||
```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')
|
||||
Die Umwandlung in eine Notiz übernimmt Titel, Erledigt-Status, Notizen, Unteraufgaben sowie Fälligkeit und Priorität als eingerückte Blöcke. Eine Umwandlung in einen Listeneintrag legt einen Eintrag in der gewählten Liste an und benachrichtigt deren Teilnehmer.
|
||||
|
||||
state Inbox {
|
||||
[*] --> ActiveCard: Oben auf Stapel
|
||||
ActiveCard --> Skipped: Leertaste / Später (Ans Ende)
|
||||
Skipped --> ActiveCard
|
||||
}
|
||||
## Zustände eines Gedankens
|
||||
|
||||
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'
|
||||
```
|
||||
inbox ──keep──▶ kept ──convert──▶ converted (task | document | list_item)
|
||||
│ │
|
||||
└─discard─▶ discarded ──restore──▶ inbox (Papierkorb leeren: DELETE /thoughts/discarded/purge)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🖐️ 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.
|
||||
Ein Gedanke mit `status = kept` zählt bereits als Aufgabe und erscheint in der Aufgabenansicht.
|
||||
Reference in new issue
Block a user