# 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.**