Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M13-team-chat.md
T

19 KiB
Raw Blame History

Boilerplate-Abgleich — M13 Team-Chat (intern)

  • Modul-ID: M13 (Modul 13)
  • Name: Team-Chat (intern) — Quiply-Ablösung, drei Ebenen (Projekt-Channel / Gruppen-Channel / DM)
  • Milestones: M110 (Channel-Modell + Permissions), M111 (Nachrichten + Threads + Pinned + Reactions), M112 (Datei/Foto-Anhänge), M113 (Modul-Verknüpfungen / Auto-Lifecycle / Mark-as-Task), M114 (Mentions + Push + Lese-Bestätigungen)
  • Block: Block 5 (_bmad-output/pflichtenheft/blocks/block5.md), Abschnitte 13.1–13.3
  • Reuse-Level: low — kein einziges Chat-Datenmodell in der Boilerplate; das Modul ist im Datenkern komplett neu zu bauen. Wiederverwendbar sind ausschließlich Querschnitts-Bausteine (Notifications, Push/DeviceToken, Storage+AV, Audit, Permissions, i18n, Feature-Flags, Search, View-Model-Konvention, App-Shell) und konzeptionelle Vorlagen (RowComment/RowCommentReaction als Message/Reaction-Muster, realtime-SSE-Paket als Streaming-Vorlage, apps/hocuspocus als Standalone-Realtime-Service-Muster).

Wichtigster Befund: Die im Auftrag erwähnten „packages/realtime + apps/hocuspocus + collabDocs" lösen nicht die Chat-Echtzeit-Anforderung aus Block H. @toolctrl/realtime ist ein SSE-only Notification-Stream (4 Event-Namen, alle notification-bezogen), kein generischer WebSocket-Room-/Pub-Sub-Layer mit message.new/typing.*/presence.*/reaction.* (Block H.2). apps/hocuspocus ist ein Y.js/CRDT-Collab-Doc-Server (für Live-Editing geteilter Dokumente), kein Chat-Channel-Broadcast. CollabDoc (collabDocs.prisma) speichert CRDT-Binärzustand pro Resource, kein Message-/Thread-/Reaction-Modell. Beide sind als Architektur-Vorlage und Infrastruktur-Bauteil nützlich, decken die Chat-Domäne fachlich aber nicht ab.


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
prisma/schema/notifications.prisma (NotificationDelivery, UserNotificationPreference, DeviceToken + Enums NotificationDeliveryStatus, NotificationPreferenceChannel) In-App- + E-Mail-Notification-Delivery, per-Channel/Category-Preference, Push-Device-Token (APNs/FCM/WebPush, revokedAt) 1:1 — deckt Block I.2 (Notification-Trigger/Status), Block J.2 (Push-Token-Registry) und Quiet-Hours-Speicherort-Vorbild ab. category/messageKey/sourceKey direkt für Chat-Notification-Bündelung nutzbar
packages/foundation/src/notifications.ts (notify, notifyMany, bundleNotifications, isNotificationEnabled, assertI18nKey) Tenant-pflichtige Notifications mit Preference-Check, Upsert per sourceKey, Metadata-Redaction, Bündelung pro Tenant/User/Channel/Category 1:1 — entspricht DoD-Pflicht „Notifications via notify() (M011), nicht direkt"; bundleNotifications deckt Block I.2 Anti-Spam-Bündelung (>5 Msg/Min) direkt ab
apps/worker/src/jobs/push-notification.ts Worker-Job für Push-Versand (DeviceToken-basiert) 1:1 / anpassen — Push-Pipeline für Block J.2 wiederverwenden; Chat-Payload-Datenschutz (nur Channel-Name + Sender-Vorname + Snippet 100 Zeichen, Block J.2) als Payload-Builder ergänzen
apps/mobile/src/pushRegistration.ts + apps/mobile/capacitor.config.ts (Plugin push-notifications, local-notifications) Capacitor-Push-Registration gegen Backend + native Shell (WebView um Web-Build) als-vorlage — PWA-Web-Push (Phase 1) + späteres Native (Phase 2). Block J Mobile-First-Hülle
packages/storage/src/scan/* (createMagicBytesScanAdapter, clamav-scanner, DEFAULT_ALLOW_LIST/resolveAllowList, s3-quarantine, ScanVerdict) + apps/worker/src/scanService.ts Pre-Upload Magic-Bytes-Check, ClamAV-Scan, S3-Quarantäne, Datei-Typ-Allowlist 1:1 — Block G.1 Anti-Virus-Scan + Datei-Typ-Whitelist (überlappt mit M23)
packages/storage/src/index.ts + ./signed + ./access S3-Adapter, Signed-Upload/Download-URLs, Access-Helper 1:1 — Block G.1 Chat-File-Upload-Pipeline (tenants/{tenantId}/chat/{chatId}/...)
prisma/schema/core.prisma FileObject (+ FileUploadProgress, FileChunk) Storage-Metadaten-Modell (provider/bucket/key/contentType/byteSize/checksum) anpassen — Datei-Records für Chat-Attachments. Caveat: FileObject ist nicht tenant-scoped (kein tenantId/userId-Feld) — für Chat-Attachment-Backlinks (TeamChatMessage.attachments[] → File-Record mit Backlink auf Source-Message, Block A/G) braucht es ein tenant-scoped Join-/Attachment-Modell (M23-Abhängigkeit)
prisma/schema/entityBuilder.prisma RowComment + RowCommentReaction (+ RowTag/EntityTag, RowTask) Comment-mit-Reactions-Muster: value, createdByUserId, isDeleted, reactions[] (emoji als reaction String); RowTask als „Aufgabe aus Eintrag"-Muster als-vorlage — direktes konzeptionelles Vorbild für TeamChatMessage + TeamChatReaction (Soft-Delete-Flag, Reaction als String, Author-FK). NICHT 1:1 übernehmbar: es fehlen Thread/parent_message_id, mentions[], attachments[], link_previews[], System-Events, Read-Receipts, Channel-Membership
packages/realtime/src/{events,server,client}.ts (REALTIME_EVENT_NAMES, validateRealtimeEvent, serializeRealtimeEvent, subscribeToRealtime mit Reconnect-Backoff + Diagnostics) SSE-Event-Contract + deterministische Frame-Serialisierung + Browser-Subscriber mit Exponential-Backoff-Reconnect, Cursor-Resume, Status-Transitions, Redaction als-vorlage — das Reconnect-/Cursor-/Diagnostics-Muster (client.ts) ist direkte Vorlage für Block H.3 (Reconnect-Strategie, Cursor-Resume) und Block M (Verbindungs-Banner). Die Event-Union ist chat-fremd und muss um message.*/typing.*/presence.*/reaction.*/thread.reply/read.receipt/link_preview.ready (Block H.2) erweitert oder ersetzt werden. Für viele Channels + bidirektionales Typing/Presence ist SSE allein unzureichend → echter WebSocket-Layer nötig
apps/hocuspocus/ (Server-Bootstrap, createAuthExtension mit JWT HS256 + Tenant-Parity-Check, eigenes Dockerfile, Standalone-Container-Pattern) Standalone-Node-Realtime-Service: JWT-Handshake-Auth, Tenant-Isolation pro Connection, eigener Container als-vorlage — Architektur-Blueprint für den /ws/chat-WebSocket-Server (Block H.1): separater EU-gehosteter Container (LP-13), Connection-Auth bei Handshake, Tenant-Scope. JWT-Auth-Extension + Tenant-Parity-Logik wiederverwendbar. Yjs/CRDT-Teil ist NICHT relevant
packages/shared-store/src (createSharedStore, RedisAdapter, Pub/Sub-Channel, createSlidingWindowRateLimiter, createFixedWindowRateLimiter, createIdempotencyStore) Redis-KV mit Pub/Sub-Channel + Rate-Limiter + Idempotenz; DB-Index-Allokation (2 = Pub/Sub) 1:1 / anpassen — Block H.1 Redis-Pub/Sub als Message-Broker zwischen WS-Server-Instanzen (Multi-Pod); Rate-Limiter für Anti-Spam (Reactions/Messages); Presence-State (online/away/offline, Block H.5) und Typing-Throttle (Block H.4) als KV mit TTL
packages/foundation/src/permissions.ts (requirePermission, withTenantScope, withPermission, withOwnerCheck) Tenant-Scoping + Permission-/Owner-Gating, Fail = CatalogError(notFound) (404 statt 403) 1:1 — Block L (alle Chat-Permissions), DoD „Permission-Filter via withTenantScope() + withPermission()"; withOwnerCheck für Membership-/Author-Checks (Block L.6); 404-statt-403 deckt Block M („Du bist kein Mitglied dieses Channels")
packages/foundation/src/audit.ts (auditEvent, withAuditMiddleware) + prisma/schema/core.prisma AuditEvent (Hash-Chain previousHash/eventHash, dataSensitivity, regulatoryScope[]) Audit-Middleware für mutierende Aktionen, manipulationssichere Event-Kette 1:1 — Block L.7 (Tenant-Admin-DM-Audit mit Begründungs-Pflicht), Block H.6 (audit-relevante Events: member_added, channel_archived), AV #6 (Audit-Default für schreibende Aktionen)
packages/foundation/src/errors.ts (CatalogError, catalogRegistry, foundationErrors) Klartext-Fehler mit code/status/i18nKey/details 1:1 — Block M (alle Klartext-Hinweise/-Fehler), DoD „Fehler-Texte aus M002-Catalog"
packages/foundation/src/flags.ts + packages/feature-flags/src (evaluateFlag, FeatureFlagProvider, useFeatureFlagEnabled) + prisma/schema/featureFlags.prisma Feature-Flag-Engine (Targeting, Cache, React-Hooks, Audit-Trail) 1:1 — DoD „Feature-Flag-fähig (M006) — Modul ohne Deploy abschaltbar"; Chat-Modul als gegateter Block
packages/i18n/src (useTranslate, Namespaces, defaultLocale="de") + assertI18nKey/assertI18nLabel Locale-Config, ICU-MessageFormat, i18n-Key-Disziplin (verify:i18n-Gate) 1:1 — DoD „Alle UI-Texte als i18n-Keys"; neuer Namespace chat analog zu crm/billing
packages/view-models/src/index.ts (VMState/VMStatus, SidebarRegistryItem, MobileRegistryItem, RegistryGate, assertI18nLabel) VM-State-Maschine (idle/loading/ready/empty/error mit i18n-Key) + Shell-Navigations-Registry-Typen (permission+flag-gegated) 1:1 — DoD „Loader baut View-Model; UI-Component empfängt nur VM"; Sidebar-/Mobile-Tab-Eintrag „Chat" mit Unread-Badge (Block B) via SidebarRegistryItem + RegistryGate (Permission chat.read_own_channels)
packages/ui-app/src/index.ts (AppShell, createSidebarRegistry, createMobileRegistry, createShellRegistries, EmptyPage) App-Shell + Sidebar-/Mobile-Registry-Factories + Empty-Page-Pattern 1:1 — Erreichbarkeits-DoD (Sidebar §1, Mobile-Tab-Bar §13); Empty-State-Pattern für Block M („Du bist noch in keinem Channel")
packages/search/src (createSearchClient, createSearchIndex, Tenant-Filter-Zwang, Meilisearch-Wrapper) + Worker search-indexer* + Outbox-Prefix search.index. Tenant-scoped Volltext-Suche (Meilisearch), Index-Registrierung via Outbox 1:1 / anpassen — Block B/D Cross-Channel-Suche (/{tenant}/chat/search), DoD „Search-Index registriert in indexed-entities.ts". Trigram-In-Channel-Suche (Block A Indizes) ist DB-seitig (Postgres) separat
apps/worker/src/outbox/{dispatcher,event-router}.ts (resolveOutboxQueueName, Prefixe notification./audit./search.index./workflow.) + prisma/schema/outbox.prisma Transactional-Outbox (FOR UPDATE SKIP LOCKED) + Event-Routing nach Prefix 1:1 / anpassen — zuverlässige Event-Auslieferung für Chat→Notification/Audit/Activity/Search; neuer Prefix chat. für Activity-Stream-Integration (Block K)
apps/worker/src/handlers.ts (buildHandlerRegistry, HandlerDependencies, createRegisteredProcessor) + apps/worker/src/queues.ts (Cron-Muster) Worker-Handler-Registry + Cron-/Queue-Muster (DI-Seams) als-vorlage — Block C.1 Auto-Archive-Cron (Projekt-Chat 7d nach Abschluss), Block G.2 Link-Preview-Async-Job, Read-Receipt-Batch

Vorhandene Daten-Modelle (konkret)

Direkt nutzbare Querschnitts-Modelle:

  • NotificationDelivery, UserNotificationPreference, DeviceToken — prisma/schema/notifications.prisma (Block I.2 + J.2)
  • AuditEvent — prisma/schema/core.prisma:213-Umfeld bzw. core (Hash-Chain) (Block L.7, H.6)
  • FileObject, FileUploadProgress, FileChunk — prisma/schema/core.prisma:213 ff. (Block G.1, nicht tenant-scoped → Caveat)
  • FeatureFlag, FeatureFlagFilter, FeatureFlagAudit — prisma/schema/featureFlags.prisma (DoD Feature-Flag)
  • Outbox — prisma/schema/outbox.prisma (Event-Auslieferung)

Als konzeptionelle Vorlage (Muster, nicht 1:1):

  • RowComment (value, createdByUserId, isDeleted, reactions[]) + RowCommentReaction (reaction String, createdByUserId) — prisma/schema/entityBuilder.prisma:409/:424 → Vorbild für TeamChatMessage + TeamChatReaction
  • RowTask (title, description, assignedToUserId, deadline, completed) — prisma/schema/entityBuilder.prisma → Vorbild für „Mark as Task" (Block G.3), aber Ziel-Modell ist M26-Task
  • CollabDoc (ydocState Bytes, version, @@unique([tenantId, resourceType, resourceId])) — prisma/schema/collabDocs.prisma → nicht für Chat verwendbar (CRDT-Binär, kein Message-Modell)
  • Chat/ChatMessage/ChatMessagePart — prisma/schema/ai.prisma:1/:31/:44 → AI-Assistent-Chat (LLM-Konversation), namentlich kollidierend aber fachlich irrelevant für Team-Chat. Vorsicht: Modell-Namen Chat/ChatMessage sind in der Boilerplate bereits belegt → HiveGrid-Chat-Modelle brauchen anderen Namespace (z.B. TeamChat/TeamChatMessage gemäß Spec Block A)

Lücken / komplett neu zu bauen

Datenmodell (Block A) — komplett neu, 7 Modelle (kein Boilerplate-Äquivalent):

  • TeamChat (Channel mit kind project/group/dm, project_id, is_private, archived_at/archived_reason, last_message_at, notification_default, Partial-Unique-Index pro Projekt)
  • TeamChatMember (M:N, role_in_chat, notification_pref, last_read_message_id, is_pinned, left_at, Last-Admin-Logik)
  • TeamChatMessage (body Markdown, body_format markdown/system, parent_message_id für Threads, mentions[] JSON, attachments[], link_previews[], edited_at/deleted_at, system_event_kind, GIN-Index auf mentions, Trigram-Index auf body)
  • TeamChatPinnedMessage (max 50/Channel, note)
  • TeamChatReaction (Unique (message_id, user_id, emoji), Anti-Spam-Limits) — Muster aus RowCommentReaction, aber eigenes Modell
  • TeamChatThread (denormalisiert reply_count/last_reply_at/participant_user_ids[])
  • TeamChatRead (Read-Receipt pro User/Message, Aggregat „X von Y gelesen")

Echtzeit (Block H) — größte Lücke:

  • Generischer WebSocket-Server /ws/chat mit Rooms-pro-Channel-Modell, bidirektionalem Typing/Presence — existiert NICHT. realtime (SSE-Notification) + hocuspocus (CRDT) sind nur Vorlagen.
  • Chat-Event-Union (message.new/edited/deleted, reaction.added/removed, thread.reply, read.receipt, typing.start/stop, channel.*, presence.*, link_preview.ready) — komplett neu (Block H.2)
  • Typing-Indikator (Block H.4), Presence online/away/offline (Block H.5) — neu (shared-store als KV-Fundament)
  • Per-Event-Auth-Revalidation (Block H.6, AV) — neu
  • Optimistic-UI + Initial-50 + Cursor-Infinite-Scroll (Block E) — neu

Mentions mit Auto-Verknüpfung (Block F.4) — neu:

  • Mention-Resolver über User/Project(M4)/Deal(M3)/Contact/Company(M1) mit Permission-Filter, Auto-Complete-Lookup, @channel/@here Spezial-Trigger, Mass-Mention-Confirm, Mention-Markdown-Syntax-Rendering. Kein Boilerplate-Baustein.

Modul-Verknüpfungen (Block C/K, M113) — neu (Cross-Modul-Wiring zu noch zu bauenden HiveGrid-Modulen):

  • Auto-Projekt-Channel-Anlage bei Project-Anlage (M4), Member-Sync, Auto-Archive-Cron (7d, pipeline-konfigurierbar), Reaktivierung
  • Activity-Stream-Erzeugung chat.message/chat.mention/… (Block K) — Ziel-Activity-Modul (M045) noch nicht in Boilerplate (kein Activity-Modell gefunden)
  • „Mark as Task" → M26-Task mit Backlink (Block G.3)

Link-Previews (Block G.2) — neu:

  • EU-self-hosted OG-Tag/oEmbed-Microservice (LP-13), Async-Job, link_previews[]-Speicherung. Kein Boilerplate-Baustein (api-client-ts ist nur SDK-Wrapper).

Quiet-Hours / Override-Hierarchie (Block I) — teils neu:

  • UserNotificationPreference deckt per-Category-Enable; Quiet-Hours-Zeitfenster + 4-stufige Override-Hierarchie (Channel-Mute > Quiet-Hours > User-Default > Channel-Default) ist neu (gehört zu M116 User-Settings).

UI (Block D/E/F/J) — komplett neu:

  • Kein Chat-UI-Component-Set in packages/ui/ui-app/ui-subframe (nur generische Primitive: Avatar, Toast, Textarea, EmptyState). Channel-Index, Chat-Verlauf mit Date-Buckets, Compose-Editor mit @-Mention/Emoji-Picker/Drag-Drop, Thread-Panel, Reactions-Badges, Read-Receipt-Anzeige, Mobile-First-Foto/Voice-Note — alles neu zu designen (Subframe, separat).

HiveGrid-Repo-Status: /Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud hat aktuell kein packages/ oder apps/ (nur docs, _bmad-output, prisma). Die Boilerplate-Pakete sind Quelle/Vorlage; das Chat-Modul wird gegen die noch zu portierende HiveGrid-Code-Basis gebaut.


Empfohlenes Vorgehen

Phase 0 — Querschnitt aus Boilerplate übernehmen (vor Chat-Logik):

  1. @toolctrl/foundation 1:1 nutzen: permissions (Block L), audit (L.7/H.6), notifications (notify/bundleNotifications für I.2), errors/CatalogError (Block M), flags. Diese sind DoD-Pflicht.
  2. @toolctrl/i18n + Namespace chat anlegen; @toolctrl/view-models (VMState, SidebarRegistryItem, RegistryGate) als Loader-/Registry-Fundament. @toolctrl/feature-flags für Modul-Gate.
  3. notifications.prisma (NotificationDelivery/UserNotificationPreference/DeviceToken) 1:1 ins HiveGrid-Schema übernehmen — deckt Block I.2 + J.2.

Phase 1 — M110 Datenmodell + Permissions (neu, mit Mustern): 4. 7 TeamChat*-Prisma-Modelle neu schreiben (Block A) — RowComment/RowCommentReaction als strukturelles Vorbild für Message/Reaction; eigener Namespace (Chat/ChatMessage sind in ai.prisma belegt). Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD). 5. Channel-Lifecycle + Membership + Last-Admin-Block über withTenantScope/withPermission/withOwnerCheck. Sidebar-Eintrag „Chat" via createSidebarRegistry + RegistryGate (Permission chat.read_own_channels).

Phase 2 — M111 Echtzeit (größter Eigenbau): 6. Redis-Pub/Sub-Broker via @toolctrl/shared-store aufsetzen (DB-Index 2). Presence/Typing als KV mit TTL. 7. WebSocket-Server /ws/chat neu bauen — apps/hocuspocus als Container-/Auth-Blueprint (JWT-Handshake + Tenant-Parity), aber eigene Room-/Event-Logik (Chat-Event-Union). EU-Hosting (LP-13). 8. Browser-Subscriber: Reconnect-/Cursor-/Diagnostics-Muster aus packages/realtime/src/client.ts übernehmen (Exponential-Backoff, Status-Banner Block M). 9. Messages/Threads/Reactions/Pinned mit Optimistic-UI.

Phase 3 — M112 Anhänge: 10. @toolctrl/storage (signed-URLs) + scan/* (ClamAV + Magic-Bytes + Allowlist + Quarantäne) 1:1 für Upload-Pipeline. FileObject als Metadaten-Basis, tenant-scoped Attachment-Join neu (FileObject hat kein tenantId). Image-Compression client-seitig (browser-image-compression, Block J.3).

Phase 4 — M114 Mentions + Push + Read-Receipts: 11. Mention-Resolver neu (Block F.4) — permission-aware Lookup über CRM-Module. 12. Push via vorhandenem apps/worker/src/jobs/push-notification.ts + DeviceToken; Chat-Payload-Builder mit Datenschutz-Snippet (Block J.2) ergänzen. 13. notify/bundleNotifications für Notification-Trigger + Anti-Spam-Bündelung; Quiet-Hours-Override-Hierarchie neu (mit M116).

Phase 5 — M113 Modul-Verknüpfungen (zuletzt, da Cross-Modul-abhängig): 14. Auto-Projekt-Channel + Member-Sync + Auto-Archive-Cron (Worker-Handler-Registry-Muster) — abhängig von M4-Projekt-Modul. 15. Activity-Stream-Integration (Block K) via Outbox-Prefix chat. — abhängig von Activity-Modul (M045, in Boilerplate noch nicht vorhanden). 16. „Mark as Task" → M26.

Link-Previews (Block G.2): EU-Microservice separat (Phase-2-nah), Async-Job über Worker-Muster.

Reihenfolge-Kernaussage: Zuerst alle Foundation-Querschnitte 1:1 ziehen (sofortiger DoD-Gewinn), dann das Datenmodell + die Echtzeit-Schicht als Hauptaufwand neu bauen (mit hocuspocus/realtime/shared-store als Infrastruktur-Vorlagen, nicht als fertige Lösung), zuletzt die Cross-Modul-Verzahnung (abhängig von M4/M3/M1/M26/M45).