19 KiB
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/RowCommentReactionals Message/Reaction-Muster,realtime-SSE-Paket als Streaming-Vorlage,apps/hocuspocusals 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/realtimeist ein SSE-only Notification-Stream (4 Event-Namen, alle notification-bezogen), kein generischer WebSocket-Room-/Pub-Sub-Layer mitmessage.new/typing.*/presence.*/reaction.*(Block H.2).apps/hocuspocusist 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:213ff. (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ürTeamChatMessage+TeamChatReactionRowTask(title,description,assignedToUserId,deadline,completed) —prisma/schema/entityBuilder.prisma→ Vorbild für „Mark as Task" (Block G.3), aber Ziel-Modell ist M26-TaskCollabDoc(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-NamenChat/ChatMessagesind in der Boilerplate bereits belegt → HiveGrid-Chat-Modelle brauchen anderen Namespace (z.B.TeamChat/TeamChatMessagegemäß Spec Block A)
Lücken / komplett neu zu bauen
Datenmodell (Block A) — komplett neu, 7 Modelle (kein Boilerplate-Äquivalent):
TeamChat(Channel mitkindproject/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(bodyMarkdown,body_formatmarkdown/system,parent_message_idfü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 ausRowCommentReaction, aber eigenes ModellTeamChatThread(denormalisiertreply_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/chatmit 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/@hereSpezial-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 (keinActivity-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:
UserNotificationPreferencedeckt 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):
@toolctrl/foundation1:1 nutzen:permissions(Block L),audit(L.7/H.6),notifications(notify/bundleNotificationsfür I.2),errors/CatalogError(Block M),flags. Diese sind DoD-Pflicht.@toolctrl/i18n+ Namespacechatanlegen;@toolctrl/view-models(VMState,SidebarRegistryItem,RegistryGate) als Loader-/Registry-Fundament.@toolctrl/feature-flagsfür Modul-Gate.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).