Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,148 @@
|
||||
# Team-Chat: v1-Produkt- und UX-Vertrag
|
||||
|
||||
**Stand:** 2026-07-15
|
||||
|
||||
**Ticket:** `AK-P15b` / HIVEGRID-45
|
||||
|
||||
**Architektur:** Bespoke WebSocket-Chat nach AD-9, kein Hocuspocus
|
||||
|
||||
Dieses Dokument konkretisiert die bereits beauftragten Chat-Funktionen als belastbaren Produktvertrag. Es
|
||||
trennt notwendige Ausführungsqualität von späteren Erweiterungen und verhindert, dass die Interim-UI einen
|
||||
technisch vollständigen, aber im Alltag hakeligen Chat verdeckt.
|
||||
|
||||
## 1. Produktprinzipien
|
||||
|
||||
1. **Sofort reagieren, serverseitig entscheiden.** Senden, Reactions und Pins erscheinen optimistisch. Die
|
||||
Datenbank bleibt autoritativ; Fehler bleiben am betroffenen Element sichtbar und können dort erneut versucht
|
||||
werden.
|
||||
2. **Kein Verlust und keine Duplikate.** Jeder Schreibvorgang besitzt vor dem ersten Versuch eine stabile
|
||||
Client-ID. Wiederholungen mit derselben ID liefern dasselbe Resultat.
|
||||
3. **Realtime ist ein Beschleuniger, nicht die Datenbank.** Redis verteilt Events; nach Reconnect werden Lücken
|
||||
per Cursor aus PostgreSQL geschlossen.
|
||||
4. **Ruhe beim Lesen.** Neue Nachrichten reißen Nutzer nicht ans Listenende. Wer hochgescrollt hat, sieht einen
|
||||
Hinweis mit Anzahl und Sprungaktion.
|
||||
5. **Mobile und Tastatur sind Primärpfade.** Alle Aktionen funktionieren per Touch, Tastatur und Screenreader.
|
||||
|
||||
## 2. Nachrichten- und Reconnect-Vertrag
|
||||
|
||||
### Optimistisches Senden
|
||||
|
||||
- UI-Zustände: `sending → sent` oder `sending → failed`. Einen erfundenen gerätebezogenen
|
||||
`delivered`-Zustand gibt es in v1 nicht.
|
||||
- `clientMessageId` wird vor dem ersten Versuch erzeugt und bei Retry wiederverwendet. Der Server hält
|
||||
`(tenantId, authorUserId, clientMessageId)` eindeutig und antwortet bei Wiederholung mit derselben Nachricht.
|
||||
- Die Local-Echo-Nachricht erscheint sofort mit dezentem Sendestatus. Server-Antwort und WebSocket-Echo werden
|
||||
gegen die Client-ID abgeglichen und dürfen weder doppelte Zeilen noch doppelte Reaktionen erzeugen.
|
||||
- Fehler entfernen den Text nicht. Direkt an der Nachricht stehen „Erneut versuchen" und „Verwerfen"; kein
|
||||
Toast-Spam. Automatischer Retry gilt nur für Timeout, `429` mit `Retry-After` und `5xx`, mit Backoff und Jitter.
|
||||
- Innerhalb eines Channels/Threads bleibt die Reihenfolge stabil; unabhängige Channels dürfen parallel senden.
|
||||
|
||||
### Verbindung und Gap-Fill
|
||||
|
||||
- Sichtbare Zustände: `connecting`, `online`, `reconnecting`, `offline`, `blocked`.
|
||||
- Nach Reconnect sendet der Client den letzten bestätigten Cursor und erhält verpasste persistente Events in
|
||||
stabiler Reihenfolge. Erst danach gilt die Verbindung als vollständig synchronisiert.
|
||||
- Presence, Typing und Transportstatus sind flüchtig und werden nicht als Chat-Historie gespeichert.
|
||||
- Queue-Grenzen und `WebSocket.bufferedAmount` werden überwacht, weil der klassische Browser-WebSocket keine
|
||||
Backpressure bereitstellt.
|
||||
- Vollständiges Offline-Senden über Reload oder Background Sync ist nicht Teil von v1. Entwürfe bleiben lokal
|
||||
erhalten; ein offline ausgelöster Send bleibt sichtbar fehlgeschlagen und kann nach Reconnect wiederholt
|
||||
werden.
|
||||
|
||||
## 3. Lesen, Scrollen und Entwürfe
|
||||
|
||||
- History wird cursorbasiert paginiert. Beim Nachladen älterer Nachrichten bleibt der visuelle Scroll-Anker
|
||||
stabil.
|
||||
- Automatisches Scrollen ans Ende erfolgt nur, wenn der Nutzer bereits am Ende ist oder selbst sendet. Sonst
|
||||
erscheint „N neue Nachrichten".
|
||||
- Read-Cursor sind monoton. Eine Nachricht wird nur als gelesen gewertet, wenn Channel und Dokument aktiv sind
|
||||
und die Nachricht sichtbar war; Updates werden gebündelt. Eigene Nachrichten erzeugen kein Unread.
|
||||
- Channel zeigen getrennt Gesamt-Unread und Mention-Marker. Mute unterdrückt Benachrichtigungen, aber niemals
|
||||
Unread; direkte User-Mentions und DMs umgehen Mute gemäß aktivem Chat-Vertrag (`AK-P15b`).
|
||||
- Der Composer speichert Textentwürfe debounced pro `Tenant + User + Channel` lokal und tenant-isoliert. Ein
|
||||
Entwurf wird erst nach erfolgreichem Server-Ack gelöscht. Datei-Binaries landen nicht im Local Storage.
|
||||
|
||||
## 4. Composer und Nachrichten-QoL
|
||||
|
||||
- `Enter` sendet, `Shift+Enter` erzeugt eine neue Zeile. Während IME-Composition darf `Enter` nicht senden.
|
||||
- Markdown bleibt auf den freigegebenen Umfang beschränkt und wird serverseitig sanitisiert.
|
||||
- Eigene Nachrichten können innerhalb von 24 Stunden editiert werden; Änderungen tragen einen
|
||||
„bearbeitet"-Marker. Löschen erzeugt einen Tombstone, damit Threads und Antworten verständlich bleiben.
|
||||
- Hover-Aktionen sind identisch per Fokus und Mobile-Long-Press erreichbar: Reaktion, Thread, Bearbeiten,
|
||||
Löschen, Pin und Als-Aufgabe-markieren gemäß Berechtigung.
|
||||
- Mentions verwenden eine zugängliche Combobox mit Pfeiltasten, `Enter` und `Escape`. Autocomplete und
|
||||
Benachrichtigung zeigen beziehungsweise adressieren nur Nutzer, die den Channel lesen dürfen.
|
||||
- Reactions werden optimistisch gesetzt und bei Fehler zurückgerollt. Gleiche Reaktion eines Users auf dieselbe
|
||||
Nachricht ist eindeutig.
|
||||
- Voice Notes sind einfache Audio-Anhänge mit Aufnahme-/Upload-Fortschritt, Dauer, Abspielen, Abbrechen und
|
||||
Retry. Es gibt kein Transkript und keine KI-Verarbeitung.
|
||||
- Uploads nutzen die bestehende Files-Pipeline inklusive AV-Prüfung. Bilder unterstützen Vorschau und
|
||||
verständlichen Alternativtext; Mobile bietet den direkten Kamera-Input.
|
||||
|
||||
## 5. Presence, Typing, Threads und Pins
|
||||
|
||||
- Typing startet erst nach echter Eingabe, wird gedrosselt, läuft nach kurzer TTL aus und endet bei Senden,
|
||||
Leeren, Channelwechsel oder Disconnect. Die UI zeigt höchstens zwei Namen plus „N weitere".
|
||||
- Presence wird aus aktiven Sessions abgeleitet und läuft über TTL aus; sie ist kein belastbarer
|
||||
Arbeitszeitnachweis.
|
||||
- Threads haben genau eine Ebene. Desktop nutzt ein Seitenpanel, Mobile eine eigene Detailansicht. Wer erstellt,
|
||||
antwortet oder erwähnt wird, folgt dem Thread automatisch.
|
||||
- Message-Pins sind in Group- und Projekt-Channels auf 50 begrenzt. Nach bestätigtem Produktentscheid gibt es
|
||||
in DMs keine Message-Pins. Der persönliche Channel-Pin bleibt ein getrenntes Modell.
|
||||
|
||||
## 6. Benachrichtigungen und bestätigte v1-Grenzen
|
||||
|
||||
- Mentions, DMs und Thread-Antworten laufen über `notify()` und öffnen per Deep Link die exakte Nachricht.
|
||||
- Der allgemeine Browser-Web-Push inklusive Permission-Prompt bleibt bei `VA-P27a`; Chat-v1 liefert In-App-
|
||||
Notifications und Deep Links.
|
||||
- Tenant-Admin-Audit liegt unter `/settings/chat/audit`. Eine kurzlebige Audit-Session verlangt einen Grund;
|
||||
jeder fremde Lesezugriff wird auditiert und DMs zeigen den Audit-Banner.
|
||||
- `FileEntityType` wird minimal um `chat_message` erweitert, damit Anhänge die bestehende `FileEntityLink`-
|
||||
Pipeline nutzen und kein paralleles Datei-System entsteht.
|
||||
|
||||
## 7. Accessibility und Mobile
|
||||
|
||||
- Die Nachrichtenliste ist ein benanntes `role="log"` ohne pauschales Live-Announcement. Separate,
|
||||
dosierte `aria-live="polite"`-Statusbereiche melden nur neue fremde Nachrichten; initial geladene Historie
|
||||
und eigene Local Echoes werden nicht doppelt angesagt.
|
||||
- Verbindungs- und Sendestatus verwenden einen separaten Statusbereich und nie nur Farbe.
|
||||
- Fokus bleibt nach Send im Composer; Drawer/Dialog geben Fokus kontrolliert zurück. Channel-, Message- und
|
||||
Picker-Listen sind vollständig per Tastatur bedienbar.
|
||||
- Mobile verwendet Master/Detail-Navigation, mindestens 44 Pixel große Touch-Ziele, Safe-Area am sticky
|
||||
Composer und behält Draft sowie Scrollposition beim Channelwechsel.
|
||||
|
||||
## 8. Wiederverwendung des HiveGrid-UI-Baukastens
|
||||
|
||||
| Fläche | Vorhandene Bausteine | Neuer chat-spezifischer Verbund |
|
||||
|---|---|---|
|
||||
| Shell | `SubframeAppShell`, `PageShell`, `SidebarInside`, `ResizablePanel` | `ChatWorkspace` |
|
||||
| Channel-Liste | `SearchInput`, `Avatar`, `BadgeFeedback`, `DropdownMenu`, `ContextMenu`, `Tooltip` | `ChatChannelRow` |
|
||||
| Verlauf | `Avatar`, `Button`, `IconButton`, `ContextMenu`, `ScrollArea`, `Skeleton` | `ChatMessageList`, `ChatMessageRow` |
|
||||
| Composer | `TextArea`, `IconButton`, `Progress`, `BannerOffline` | `ChatComposer`, `ChatAttachmentTray` |
|
||||
| Threads | `Drawer`, `Dialog`, `Accordion` | `ThreadDrawer` |
|
||||
| Mentions/Suche | `SearchInput`, `Command`, `Avatar` | `MentionAutocomplete`, `ChatSearchResults` |
|
||||
| States | `EmptyState`, `Alert`, `BannerOffline`, `Skeleton`, `LoadingIndicatorSkeleton` | nur Chat-Kompositionen |
|
||||
| Medien | `uploadFileInChunks`, `AudioOrVideoPlayer`, `Progress` | Voice-Note- und Attachment-Steuerung |
|
||||
|
||||
Die bestehenden visuellen Primitives werden direkt genutzt. Nicht wiederverwendet werden die rein visuellen,
|
||||
nicht interaktiven `FileUpload`-/`Combobox`-Attrappen und der für Chat zu schwere Legacy-Rich-Text-Editor.
|
||||
|
||||
## 9. Bewusst später
|
||||
|
||||
- persistente Offline-Outbox und Background Sync über Reload
|
||||
- Scheduled Messages, Erinnerungen und „Für später speichern"
|
||||
- gerätebezogener `delivered`-Status und Read-Receipt-Privacy-Schalter
|
||||
- Slack-Power-Shortcuts, frei konfigurierbares Sendeverhalten und Pop-out-Threads
|
||||
- server-/geräteübergreifend synchronisierte Drafts
|
||||
- GIF-/Sticker-Apps, Huddles, Audio-/Videoanrufe und KI-Transkription
|
||||
|
||||
## Research-Quellen
|
||||
|
||||
- [React `useOptimistic`](https://react.dev/reference/react/useOptimistic)
|
||||
- [Matrix Client-Server API: Transaction IDs, Local Echo, Receipts, Typing, Threads](https://spec.matrix.org/latest/client-server-api/)
|
||||
- [MDN WebSocket API und fehlende Backpressure](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
|
||||
- [Slack: Send, read and manage drafts](https://slack.com/help/articles/201457107-Send-and-read-messages)
|
||||
- [Slack: Threads](https://slack.com/help/articles/115000769927-Use-threads-to-organize-discussions)
|
||||
- [Slack: Keyboard navigation](https://slack.com/help/articles/115003340723-Navigate-Slack-with-your-keyboard)
|
||||
- [W3C ARIA23: `role=log`](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23)
|
||||
- [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
|
||||
Reference in new issue
Block a user