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

156 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.**