156 lines
13 KiB
Markdown
156 lines
13 KiB
Markdown
# AK-P15b · P15 Team-Chat (Realtime)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Typ** | Dev (Code) |
|
||
| **Owner** | Akeshan + Raffael |
|
||
| **Phase** | P15 — Telefonie & Team-Chat |
|
||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-07-02 · **Gate W3 (Demo 2)** |
|
||
| **Status** | Dev-DoD vollständig umgesetzt · 8/8 DoD = 100 % done · design-nachzug offen |
|
||
|
||
> 🎨 **design-nachzug: offen** · Nach AD-28 wird zunächst eine Interim-UI aus `~/ui` mit VM als Prop gebaut.
|
||
> Das finale `D-CHAT`/`D-P15`-Delta bleibt ein getrackter Nachzug und blockiert den Dev-Abschluss nicht.
|
||
|
||
## Abhängigkeiten & Parallelität
|
||
- **Technische Vorbedingungen:** `AK-P4a` ist erledigt; die bestehende Files-Pipeline wird für Chat-Anhänge
|
||
wiederverwendet. Die historische Reihenfolge hinter `AK-P15a` wurde am 2026-07-15 aufgehoben: Der interne
|
||
Team-Chat hängt weder vom Aircall-Adapter noch von dessen extern blockiertem Live-Proof ab.
|
||
- **Blocks:** **Demo 2** (Noah-Demo #2, Gate W3)
|
||
- **Läuft parallel zu:** Raffaels Kern-Kette. Eigene `prisma/schema/chat.prisma` (AD-21); entity-linked Channels referenzieren Projekt aus dem CRM-Kern (R-P6/P8) read-only. **Sync-Punkt:** ProjektMitglied-Sync braucht den Projekt-Kern (P8/P9).
|
||
- **Konflikt-Risiko:** gering, aber nicht null. Das Fachschema bleibt in `prisma/schema/chat.prisma`; additive
|
||
Querschnittsänderungen an Feature-Gates, Permissions, File-Verknüpfungen, Sidebar und Projekt-Hooks werden
|
||
mit ihren Konsumenten geprüft.
|
||
|
||
## Was wir bauen
|
||
Den **Real-Time-Team-Chat (Bespoke, AD-9)**: WebSocket-Messaging mit **Presence, Typing-Indicator,
|
||
Read-Receipts** über Redis-Pub/Sub (Scale-Out), drei **Channel-Typen** (public/private Group, DM,
|
||
entity-linked Projekt mit ProjektMitglied-Sync), **@Mentions** (User/Projekt/Kontakt/Firma) mit Autocomplete,
|
||
**Threads, Reactions, Pins** (max 50; nicht in DMs), **File-Uploads** (via Files), einfache **Voice Notes** ohne
|
||
Transkript, Link-Previews, **Mark-as-Task** und **Cross-Channel-Suche**. Die UX folgt dem verbindlichen Vertrag
|
||
in `docs/features/chat.md`: Local Echo mit `sending/sent/failed`, idempotentes Retry, Cursor-Reconnect,
|
||
Scroll-Anchoring, Draft-Autosave sowie vollständige Keyboard-/Screenreader-Bedienung. Mobile-First für
|
||
Monteure mit vereinfachter View, Foto-Direct-Upload und In-App-Notification/Deep Link; allgemeines Browser-
|
||
Push bleibt `VA-P27a`. Ein **Admin-Audit-Modus** (`read_all_channels`) unter `/settings/chat/audit` erfordert
|
||
Begründungs-Pflicht je Session + DM-Audit-Banner und wird audit-geloggt.
|
||
|
||
## Benötigte Screens (Backend bedient — Design liefert `D-CHAT` + `D-P15`)
|
||
| Screen [Route] | Kern-Inhalt |
|
||
|---|---|
|
||
| Chat-Index [`/chat`] | Channel-Liste (Snippet, Unread-Badge, Mention-Marker, Pin/Mute/Typ-Indikator, bei Projekt-Chat Stage), Filter, Suche, Channel-Browser (Discover), „Archivierte anzeigen" — **BESPOKE** |
|
||
| Channel-Detail [`/chat/:id`] | Verlauf mit Date-Bucket-Separatoren, Nachricht (Markdown/Reactions/Thread-Indikator/Mentions/Anhänge), Read-Receipt, Composer (@-Autocomplete/Datei-Dropzone/Draft-Autosave), Typing-Indikator, Per-Message-Hover-Menü — **BESPOKE** |
|
||
| Thread-Detail [`/chat/:id/thread/:thread_id`] | Eltern-Nachricht + Replies (Side-Panel oder Route), eigener Composer |
|
||
| Pinned-Übersicht [`/chat/:id/pinned`] · Mentions-Aggregat [`/chat/mentions`] · Cross-Channel-Suche [`/chat/search`] | Pins (max 50), kanalübergreifende Mentions, Volltext-Suche über erlaubte Channels |
|
||
| Neuer Channel / DM [`/chat/new`] · Channel-Settings | Group/DM-Modal; Members/Privacy/Archivieren/verlassen |
|
||
| Admin-Chat-Übersicht [`/settings/chat/audit`] | Tenantinterne Übersicht aller Channels + Cleanup; **DM-Audit mit Begründungs-Pflicht-Banner**; Force-Member-Edit/Delete |
|
||
|
||
## Definition of Done
|
||
- [x] **WebSocket-Real-Time**: Presence, Typing, Read-Receipts, Redis-Pub/Sub (AD-9), Optimistic-UI, Reconnect
|
||
- [x] **3 Channel-Typen**: public/private Group, DM, entity-linked (Projekt) mit **ProjektMitglied-Sync**
|
||
- [x] **@Mentions** mit Autocomplete + **Threads** + **Reactions** + **Pins** (max 50; nicht in DMs) +
|
||
**File-Uploads** (Files) + einfache **Voice Notes** ohne Transkript + Link-Previews + **Mark-as-Task**
|
||
- [x] Channel-Index (Filter/Suche/Pin/Mute/Archiv + Channel-Browser) + **Cross-Channel-Suche** + Mentions-Aggregat
|
||
- [x] Entity-linked Channel erscheint im Projekt-Detail (P8/P9)
|
||
- [x] **Admin-Audit** (`read_all_channels`): Begründungs-Pflicht je Session + DM-Audit-Banner, audit-geloggt
|
||
- [x] **Mobile-First-Variante** für Monteure (vereinfachte View, Foto-Direct-Upload, In-App-Notification und
|
||
Deep Link; allgemeines Browser-Push bleibt Scope von `VA-P27a`)
|
||
- [x] Konnektor `tenantHasModule('chat')`; RLS auf allen Tenant-Tabellen
|
||
|
||
## Technische Bausteine
|
||
- **Entities** (eigene `prisma/schema/chat.prisma`): `TeamChat` (kind project/group/dm, projekt_id,
|
||
archived_reason, last_message_at), `TeamChatMember` (role_in_chat, last_read_message_id, is_pinned),
|
||
`TeamChatMessage` (author, body Markdown, parent_message_id, client_message_id, mentions[]),
|
||
`TeamChatThread`/`PinnedMessage`/`Reaction`/`Read`. `crm.prisma` bleibt für Projekt read-only;
|
||
`files.prisma` erhält ausschließlich den additiven `FileEntityType.chat_message`, Anhänge laufen über
|
||
`FileEntityLink` (AD-21).
|
||
- **Real-Time-Layer**: WebSocket-Gateway + Redis-Pub/Sub für Presence/Typing/Fan-out (AD-9); Read-Receipt-Aggregation „X von Y gelesen".
|
||
- **RLS** auf allen Tabellen; Channel-Permission je Typ; Admin-Audit-Read gegated + audit-geloggt (AuditEntry).
|
||
- **Mark-as-Task** schreibt in das Tasks-Modul (AK-P4b, EntityLink).
|
||
- **Konnektor** `tenantHasModule('chat')`; `is_demo_data` auf Demo-Channels/-Messages.
|
||
|
||
## Quellen (granular)
|
||
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (TeamChat/Member/Message/Thread/PinnedMessage/Reaction/Read)
|
||
- `REQUIREMENTS.md` → `REQ-chat-datenmodell`, `REQ-chat-realtime`, `REQ-chat-features`
|
||
- `ROADMAP.md` → Phase 15 · Milestones: (M110-channel-permissions, M111-direkt-nachrichten, M112-anhaenge, M113-modul-verknuepfungen, M114-mentions-push — Chat bleibt VOLL)
|
||
- `designer-briefs/P15-telefonie-chat.md` (Chat-UI BESPOKE, Admin-DM-Audit, Mobile-First)
|
||
- `docs/features/chat.md` (Research-basierter Produkt-, QoL-, Accessibility- und UI-Wiederverwendungsvertrag)
|
||
|
||
## Dev-Nachzug (nach Davids `D-CHAT`/`D-P15`-Delta)
|
||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||
- [ ] REQUIREMENTS/ROADMAP nachgezogen
|
||
- [ ] Plane-Ticket `AK-P15b` aktualisiert
|
||
|
||
## Festgezogene Scope-Entscheidungen (2026-07-15)
|
||
|
||
- Chat-v1 nutzt `notify()` mit In-App-Notification und Deep Link; allgemeines Browser-Push bleibt `VA-P27a`.
|
||
- Voice Notes sind einfache Audio-Anhänge ohne Transkript oder KI-Verarbeitung.
|
||
- Der tenantinterne Admin-Audit liegt unter `/settings/chat/audit`.
|
||
- DMs unterstützen keine Message-Pins.
|
||
- `FileEntityType.chat_message` wird additiv ergänzt; es entsteht kein paralleles Attachment-System.
|
||
|
||
## Umsetzungs-Notiz
|
||
|
||
- **2026-07-15 · 0/8 DoD = 0 % done:** Planung im separaten Worktree `HiveGrid-Cloud-team-chat` auf
|
||
`feat/ak-p15b-team-chat` gestartet und Branch auf Gitea veröffentlicht. Akeshan und Raffael sind in Plane
|
||
gemeinsam zugewiesen; das Ticket steht auf `In Progress`. Ausgangsstand auf aktuellem `main`: Typecheck,
|
||
Lint und Core-Testlauf mit
|
||
`5.061 passed` grün. Noch keine Fachimplementierung; alle acht DoD sind offen und selbst machbar. Die
|
||
Scope-Entscheidungen und der Research-Vertrag in `docs/features/chat.md` sind nun festgezogen. Externe
|
||
Blocker: keine.
|
||
- **2026-07-15 · 1/8 DoD = ~13 % done:** Die tenant- und session-sichere Realtime-Foundation ist mit den
|
||
Commits `4825c5fbb`, `1e960cef6` und `464c1c47b` umgesetzt und auf Gitea veröffentlicht: versioniertes
|
||
Wire-Protokoll, resilienter Browser-Client mit Local Echo/Cursor-Reconnect, kurzlebige Gateway-JWTs,
|
||
Redis-Pub/Sub für Presence und Typing, Read-Receipts, Live-Revalidierung von Session/Permission/Modul,
|
||
atomare Token- und Connection-Limits sowie ein gehärtetes WebSocket-Gateway. Proof: `pnpm typecheck`,
|
||
`pnpm lint`, `pnpm test` (`5.137 passed`), Coverage-Gate, API-Build und relevante `verify:*`-Checks grün;
|
||
echter Redis-7-Smoke grün; `verify:rls-live` mit `42/42` Kern- und `2/2` Chat-Isolationstests grün.
|
||
`tenantHasModule('chat')` ist an Route und Gateway gebunden, der generierte Tenant-Policy-Vertrag ist für
|
||
alle Chat-Tabellen grün; damit ist DoD 8 vollständig erfüllt. DoD 1 bleibt offen, bis Index/Detail,
|
||
Optimistic UI und der Zwei-Nutzer-Live-Smoke Ende-zu-Ende verdrahtet sind. Nächster selbst machbarer Slice:
|
||
Member-Channel-Live-Loop. Externe Blocker: keine.
|
||
- **2026-07-15 · 2/8 DoD = 25 % done:** Der Member-Channel-Live-Loop ist Ende-zu-Ende verdrahtet: sichere
|
||
Channel-/Message-Projektion, Optimistic UI mit idempotentem Retry, Cursor-Reconnect, Draft-Autosave,
|
||
Scroll-Anchoring, Presence-Snapshot, Typing und gebündelte Read-Receipts. Der lokale Zwei-Browser-Smoke
|
||
belegt mit echtem PostgreSQL, Redis und WebSocket-Gateway: ein bereits verbundener Peer wird als anwesend
|
||
angezeigt, Typing erscheint live, die Nachricht erreicht den Peer ohne Reload, das Read-Receipt kommt zum
|
||
Absender zurück und die Nachricht bleibt nach Reload erhalten. Ergänzend sind Interim-Pixel-Baselines,
|
||
Hot-Swap-Fixtures sowie Repository-/Gateway-/Client-Tests grün. Proof: Commits `a425448bc`, `03c6ed637`,
|
||
`face49526`, `a8039bc25`, `63a74b727`, `e613af4ad` und `fa1ee4a1a`; `pnpm typecheck`, `pnpm lint`,
|
||
`pnpm test` (`5.230 passed`), Paket-Suite, API-Typecheck/-Build, 324/324 fokussierte Chat-Tests,
|
||
Component-Pixeltests 2/2, Zwei-Nutzer-E2E 1/1, UI-Mock/Hot-Swap und die Live-RLS-Suite mit 42/42 Kern-
|
||
plus 3/3 Chat-Isolationstests grün. Damit ist DoD 1 vollständig erfüllt; DoD 8 bleibt erfüllt.
|
||
**Offen: 6 DoD, davon 6 selbst machbar und 0 extern blockiert.**
|
||
- **2026-07-16 · 8/8 DoD = 100 % done:** Public/private Groups, kanonische DMs und entity-linked
|
||
Projekt-Channels sind inklusive atomarem ProjektMitglied-/Berechtigungsgruppen-Sync umgesetzt. Mentions
|
||
für User/Projekt/Kontakt/Firma, Threads, Reactions, DM-ausgeschlossene Pins mit 50er-Limit,
|
||
Files-Anhänge mit AV-Freigabe, einfache Voice Notes, gehärtete Link-Previews und Mark-as-Task sind
|
||
Ende-zu-Ende verdrahtet. Channel-Browser, Filter, Cross-Channel-Suche, Mentions-Aggregat,
|
||
Projekt-Detail-Link und der begründungspflichtige read-only Admin-Audit mit DM-Banner stehen als
|
||
Interim-UI aus `~/ui`. Der mobile Pfad enthält Master/Detail-Navigation, Safe-Area-/44px-Touch-Ziele,
|
||
Kamera-Upload und In-App-Notifications mit exaktem Deep Link. Browser-Push bleibt bei `VA-P27a`;
|
||
Transkription, KI und persistente Offline-Outbox wurden nicht vorgezogen. Modul-, Permission-, Audit-,
|
||
Activity-, Search- und FORCE-RLS-Verträge sind angebunden. **Proof:** Commits `884ac7ed7`, `f16e2575b`,
|
||
`4eebc5144`, `373b589ed`, `cf258947e` und `1d4485fb8`; Forward-only-Migration
|
||
`20260716090000_ak_p15b_team_chat`; `pnpm typecheck`, `pnpm lint`, `pnpm test` (5.729 passed),
|
||
Coverage-Gate, Migration-Parität und Tenant-Policy-Contract grün; Live-RLS mit allen neun Chat-Suiten,
|
||
14/14 Contract-/UI-Gates, 96/96 Visual-Checks sowie 3/3 Component-Pixel-/Mobile-Tests grün.
|
||
**Offen: 0/8 DoD; 0 selbst machbar, 0 extern blockiert.** Das finale `D-CHAT`/`D-P15`-Delta bleibt als
|
||
`design-nachzug: offen` getrackt und ist nach AD-28 kein Done-Blocker.
|
||
- **2026-07-17 · Stand-Audit bestätigt 8/8 DoD = 100 % done:** Vollaudit (Code auf `main` gegen jede DoD
|
||
einzeln geprüft) bestätigt alle acht Punkte inhaltlich ohne Lücken — u. a. Gateway/Redis-Pub/Sub mit
|
||
Cursor-Reconnect (`apps/api/src/chat/gateway.ts`, `room-hub.ts`), idempotentes Optimistic-UI
|
||
(`@@unique(tenantId, chatId, clientMessageId)`), ProjektMitglied-Sync
|
||
(`packages/chat/src/project-sync.server.ts`, verdrahtet in projectService/auftragService), Pins max 50
|
||
mit DM-Ausschluss (`message-features.server.ts`), Mark-as-Task via EntityLink, begründungspflichtiger
|
||
Admin-Audit mit DM-Banner, `notify()` IN_APP mit Deep Link ohne Browser-Push, Modul-Gate an Route und
|
||
Gateway sowie FORCE-RLS auf allen neun Chat-Tabellen inklusive Inverse-SQL. Querschnitts-DoD (Blocks
|
||
A–F) ebenfalls grün: Layer-Trennung ohne Verstöße, Sidebar/i18n/Permissions/Entitlements/
|
||
`TENANT_SCOPED_MODELS` vollständig, `chatMessage` im Search-Index registriert, Smoke-/Hot-Swap-/
|
||
Visual-Nachweise vorhanden. Keine Restarbeiten; offen bleiben nur User-Sign-Off (Tracker M110–M114)
|
||
und der `design-nachzug`.
|
||
|
||
### 2026-07-29 — Abhängigkeitsnachzug aus AK-P4a
|
||
|
||
Der wiederverwendete Chunk-Upload-Client sendet nun den Session-CSRF-Header bei Init, Chunk und
|
||
Complete. Der Chat-Anhang-Flow benötigt keine eigene Contract-Änderung; fokussierte Client- und
|
||
Resource-Route-Regressionstests sind grün. **AK-P15b bleibt 8/8 DoD = 100 % done.**
|