Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P15b.md
T

13 KiB
Raw Blame History

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

  • WebSocket-Real-Time: Presence, Typing, Read-Receipts, Redis-Pub/Sub (AD-9), Optimistic-UI, Reconnect
  • 3 Channel-Typen: public/private Group, DM, entity-linked (Projekt) mit ProjektMitglied-Sync
  • @Mentions mit Autocomplete + Threads + Reactions + Pins (max 50; nicht in DMs) + File-Uploads (Files) + einfache Voice Notes ohne Transkript + Link-Previews + Mark-as-Task
  • Channel-Index (Filter/Suche/Pin/Mute/Archiv + Channel-Browser) + Cross-Channel-Suche + Mentions-Aggregat
  • Entity-linked Channel erscheint im Projekt-Detail (P8/P9)
  • Admin-Audit (read_all_channels): Begründungs-Pflicht je Session + DM-Audit-Banner, audit-geloggt
  • 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)
  • 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.