chore(ST-806): cleanup debug-pages, document realtime, restore strict mode
M8 acceptance heeft de end-to-end pipeline bevestigd: trigger → NOTIFY → SSE → store → View Transition. De cycling-symptomen waren een artefact van testen via terminal (alt-tab triggert visibility-pause-by-design), geen bug. Tijd om de tijdelijke instrumentatie en debug-pagina's weg te halen en de architectuur op te schrijven. - Verwijder /debug-realtime, /(app)/debug-realtime-app, /api/debug/* - Strip debug-logs uit /api/realtime/solo (closed-reden alleen in dev) - reactStrictMode weer aan - CONNECTING_INDICATOR_DELAY_MS 2s → 4s (minder flikker bij micro-disconnects) - Nieuwe sectie "Realtime updates (M8)" in scrum4me-architecture.md: diagram, NOTIFY-bron, server-filter, connection lifecycle inclusief visibility-pause + bekende beperking, animatie, auth - DIRECT_URL env-rij uitgebreid met realtime-doel - GET /api/realtime/solo gedocumenteerd in API.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
7e4b6a20fa
commit
cefd54e56d
12 changed files with 125 additions and 899 deletions
48
docs/API.md
48
docs/API.md
|
|
@ -275,6 +275,54 @@ Nieuwe todo voor de tokengebruiker.
|
|||
|
||||
---
|
||||
|
||||
### `GET /api/realtime/solo?product_id=...`
|
||||
|
||||
Server-Sent Events stream voor het Solo Paneel. Wordt gebruikt door de browser-UI (`useSoloRealtime`); voor Claude Code zelden relevant, maar gedocumenteerd voor volledigheid.
|
||||
|
||||
**Auth:** iron-session cookie of Bearer-token. Demo-tokens mogen lezen.
|
||||
**Query params:** `product_id` (verplicht).
|
||||
**Response:** `text/event-stream`. Stream blijft open tot de client sluit of de server na 240s een hard-close doet (client herconnect dan transparant).
|
||||
|
||||
**Events:**
|
||||
- `event: ready` — eenmalig direct na connect, met `{ product_id, sprint_id }` als payload.
|
||||
- `event: error` — bij interne fouten (pg connect mislukt e.d.).
|
||||
- `data: {...}` — task/story mutaties die binnen scope vallen (zie hieronder). Payload-shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "I" | "U" | "D",
|
||||
"entity": "task" | "story",
|
||||
"id": "cmof...",
|
||||
"story_id": "cmof...",
|
||||
"product_id": "cmof...",
|
||||
"sprint_id": "cmog..." ,
|
||||
"assignee_id": "cmof..." ,
|
||||
"task_status": "TO_DO" | "IN_PROGRESS" | "REVIEW" | "DONE",
|
||||
"task_title": "...",
|
||||
"task_sort_order": 1,
|
||||
"changed_fields": ["status", "updated_at"]
|
||||
}
|
||||
```
|
||||
|
||||
Niet alle velden zijn altijd aanwezig — `task_*` alleen voor `entity: "task"`, idem `story_*`. `task_status` gebruikt de **DB-enum** (UPPER_SNAKE), niet de lowercase API-vorm.
|
||||
|
||||
- `: heartbeat` — SSE-comment elke 25s, om proxies keep-alive te houden. Kan genegeerd worden.
|
||||
|
||||
**Server-side filter:**
|
||||
- `product_id` matcht de query-param
|
||||
- `sprint_id` matcht de actieve sprint van het product
|
||||
- `assignee_id` is gelijk aan de ingelogde user (of `null` voor unassigned-story claims)
|
||||
|
||||
Niet-matchende events worden gedropt — clients ontvangen geen irrelevante data.
|
||||
|
||||
**Voorbeeld (browser):**
|
||||
```js
|
||||
const source = new EventSource('/api/realtime/solo?product_id=cmof...')
|
||||
source.onmessage = (e) => console.log(JSON.parse(e.data))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Voorbeeldworkflow voor Claude Code
|
||||
|
||||
1. **Probe:** `GET /api/health?db=1` — bevestig dat de service en DB bereikbaar zijn.
|
||||
|
|
|
|||
|
|
@ -771,12 +771,79 @@ interface ProductStore {
|
|||
|
||||
---
|
||||
|
||||
## Realtime updates (M8)
|
||||
|
||||
Het Solo Paneel update live als andere gebruikers, scripts of admin-tools een task of story muteren. De pijplijn:
|
||||
|
||||
```
|
||||
┌─────────────────────────┐
|
||||
│ Mutatie (Prisma write) │ PATCH /api/tasks/:id
|
||||
└────────────┬────────────┘ Server Action, MCP, etc.
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ Postgres row trigger │ AFTER INSERT/UPDATE/DELETE
|
||||
│ scrum4me_notify_change()│ bouwt JSON payload
|
||||
└────────────┬────────────┘
|
||||
▼ pg_notify('scrum4me_changes', json)
|
||||
┌─────────────────────────┐
|
||||
│ /api/realtime/solo │ Node runtime, dedicated pg.Client
|
||||
│ LISTEN scrum4me_changes │ filtert op product + sprint + assignee
|
||||
└────────────┬────────────┘
|
||||
▼ text/event-stream
|
||||
┌─────────────────────────┐
|
||||
│ EventSource (browser) │ beheerd door useSoloRealtime
|
||||
│ → solo-store.handleEvent│ via flushSync + startViewTransition
|
||||
└────────────┬────────────┘
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ SoloBoard re-render │ kanban-kaartje animeert naar
|
||||
│ (View Transitions API) │ zijn nieuwe kolom
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
**Keuze:** Postgres LISTEN/NOTIFY in plaats van polling, websockets of een externe broker (Pusher, Ably, Supabase Realtime).
|
||||
**Rationale:** Eén Neon-database is al een verplichte dependency; LISTEN/NOTIFY voegt geen nieuwe infrastructuur toe. Polling zou voor één gebruiker prima werken maar schaalt slecht; een externe broker introduceert kosten, een tweede auth-laag, en synchronisatie-races tussen DB-writes en push-events.
|
||||
**Trade-off:** Vereist een direct (unpooled) connection per open tab — Neon pooler ondersteunt LISTEN niet. Bij veel gelijktijdige gebruikers een keer her-evalueren.
|
||||
|
||||
### Mutaties die NOTIFY triggeren
|
||||
|
||||
De row trigger zit op `task` en `story`. Elke INSERT/UPDATE/DELETE op die tabellen — onafhankelijk van de bron (Prisma, MCP-server, raw SQL) — vuurt een NOTIFY met de geüpdate kolommen. Andere tabellen (Sprint, Product, etc.) doen dat niet; die hebben geen live-view in M8.
|
||||
|
||||
### Server-side filter
|
||||
|
||||
`/api/realtime/solo?product_id=...` filtert NOTIFY-payloads op:
|
||||
- `product_id` matcht de query-param
|
||||
- `sprint_id` matcht de actieve sprint van het product (resolve éénmaal per connect)
|
||||
- `assignee_id` is gelijk aan de ingelogde `userId` (of `null` voor unassigned-story-claims)
|
||||
|
||||
Niet-matchende events worden server-side gedropt zodat de browser geen irrelevante data ontvangt en de solo-store geen onnodige diff-checks doet.
|
||||
|
||||
### Connection lifecycle
|
||||
|
||||
- **Open**: `EventSource('/api/realtime/solo?product_id=...')` zodra de gebruiker op `/solo` is.
|
||||
- **Reconnect**: exponential backoff bij `onerror` (1s → 30s, reset bij `ready` event).
|
||||
- **Pause op tab-hidden**: `document.visibilityState === 'hidden'` sluit de stream actief. Bij `visible` wordt opnieuw verbonden. Dit voorkomt dat inactieve tabs DB-connecties open houden.
|
||||
- **Hard close**: server sluit zelf na 240s (Vercel `maxDuration` is 300s); client herconnect transparant.
|
||||
- **Heartbeat**: server stuurt elke 25s een `: heartbeat`-comment om proxies te keep-alive'n.
|
||||
|
||||
**Bekende beperking M8**: events die binnenkomen terwijl de tab `hidden` is, worden niet vervangen bij heropening. De gebruiker ziet de meest recente Postgres-state pas bij een page-refresh of een nieuwe mutatie. Voor v1 acceptabel; in M9+ overwegen we een replay-fetch op visibility-resume.
|
||||
|
||||
### Animatie
|
||||
|
||||
Voor `task UPDATE`-events wordt de store-update gewikkeld in `document.startViewTransition(() => flushSync(() => handleEvent(payload)))`. `flushSync` dwingt React om binnen de transition-callback synchroon te renderen, zodat View Transitions de oude en nieuwe DOM correct snapshot. Vereist `view-transition-name` op de task-cards (gezet op task-id). INSERT/DELETE-events animeren niet — die mutaties komen typisch met een page-load.
|
||||
|
||||
### Auth
|
||||
|
||||
Iron-session cookie of Bearer-token (demo). De auth-check loopt éénmalig bij de connect-request; tijdens de stream zelf is er geen herauth, dus een ingetrokken sessie blijft live tot de stream sluit (heartbeat-fail of hard-close). Voor M8 acceptabel — sessies expireren na 30 dagen.
|
||||
|
||||
---
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variabele | Doel | Waar te vinden |
|
||||
|---|---|---|
|
||||
| `DATABASE_URL` | Prisma database-verbinding | Neon dashboard → Connection string (pooled) |
|
||||
| `DIRECT_URL` | Directe verbinding voor migraties (Neon) | Neon dashboard → Connection string (unpooled) |
|
||||
| `DIRECT_URL` | Directe verbinding voor migraties én voor de LISTEN/NOTIFY-verbinding van het Solo Paneel realtime-endpoint | Neon dashboard → Connection string (unpooled) |
|
||||
| `SESSION_SECRET` | Versleutelingssleutel voor iron-session | Genereer met `openssl rand -base64 32` |
|
||||
| `NODE_ENV` | Omgevingsmodus | Automatisch gezet door Vercel / Node |
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue