docs(ST-1108): add F-11b — Claude question-channel to functional spec

Voegt feature-omschrijving toe naast bestaande F-11 (Claude Code REST API).
Beschrijft het verloop (Claude → MCP-tool → DB → trigger → SSE → user → answer
→ trigger → Claude polls), acceptatiecriteria (8 items), randgevallen (offline-
Claude, assignee-change, expiry, abuse) en datamodel (claude_questions tabel).

Persona Lars als primair, Dina secundair voor klant-werk.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-04-28 00:33:59 +02:00
parent 99561d6964
commit 2d98a4386c

View file

@ -424,6 +424,44 @@ Een REST API waarmee Claude Code stories en taken kan ophalen, de taakvolgorde k
---
### F-11b: Vraag-antwoord-kanaal Claude ↔ user
**Prioriteit:** v1 — Verdiept de Claude-integratie (richting B uit strategisch overleg)
**Persona:** Lars (primair), Dina (idem voor klant-werk)
**Omschrijving:**
Wanneer Claude Code tijdens het implementeren van een story een keuze niet uit de acceptance-criteria kan afleiden, post hij een gestructureerde vraag naar Scrum4Me via een MCP-tool. De Scrum4Me-app toont een notificatie-badge voor iedereen met toegang tot het product. Een gebruiker beantwoordt de vraag in de UI; Claude leest het antwoord (sync via een polling-tool of in een latere sessie) en gaat door zonder te raden of te wachten in de Claude Code-sessie.
**Verloop:**
1. Claude heeft een vraag → roept MCP-tool `ask_user_question` aan met `{ story_id, question, options?, wait_seconds? }`. Tool schrijft een rij naar `claude_questions` met status `open`, vervaltijd 24 u.
2. Postgres-trigger emit op het bestaande `scrum4me_changes`-kanaal met `entity: 'question'`. De Scrum4Me-app heeft een user-scoped SSE-stream die filter't op product-toegang.
3. NavBar-bell krijgt een badge met de count van open vragen voor deze gebruiker. Story-assignee ziet een visuele *"wacht op jou"*-emphase.
4. Klik op bell → slide-over met lijst → klik op item → modal met de volledige vraag, story-context-link en (optionele) keuze-opties. Submit verstuurt het antwoord via Server Action.
5. Trigger fired opnieuw, alle SSE-clients zien het item verdwijnen. Claude's tool-poller (als `wait_seconds` was meegegeven) krijgt het antwoord direct terug; anders haalt Claude het later op via `get_question_answer`.
**Acceptatiecriteria:**
- [ ] Claude kan via MCP een vraag stellen (`ask_user_question`); demo-tokens krijgen permission-denied
- [ ] Bell-icon in NavBar toont badge met aantal open vragen voor de ingelogde gebruiker
- [ ] Iedere gebruiker met product-toegang kan antwoorden; story-assignee krijgt visuele markering
- [ ] Demo-gebruiker kan vragen lezen maar de Verstuur-knop is uitgeschakeld met tooltip
- [ ] Optionele `wait_seconds` (max 600) laat de MCP-tool blijven pollen; bij timeout retourneert hij `status: 'pending'`
- [ ] Concurrent dubbele submit op zelfde vraag: één wint via atomic `updateMany`, ander krijgt foutmelding "al beantwoord"
- [ ] Vragen ouder dan 24 u worden via een Vercel cron op `expired` gezet
- [ ] Cross-product-isolatie: een gebruiker ziet alleen vragen van producten waar hij toegang toe heeft
**Randgevallen:**
- Claude vraagt iets en is daarna offline (Claude Code-sessie afgesloten) → vraag blijft in DB; volgende sessie roept `list_open_questions` of `get_question_answer` op
- Story-assignee verandert nadat de vraag is gesteld → de vraag blijft beantwoordbaar door iedereen met product-toegang; visuele emphase volgt de actuele assignee
- Vraag verloopt voordat iemand antwoord geeft → cron zet 'm op `expired`; Claude's `get_question_answer` retourneert `status: 'expired'`
- Phishing/abuse: alleen geverifieerde Claude-tokens kunnen vragen stellen; Scrum4Me-gebruikers zien alleen vragen van hun eigen producten
**Data:**
- Nieuw: `claude_questions` (id, story_id, task_id?, product_id, asked_by, question, options?, status, answer?, answered_by?, answered_at?, created_at, expires_at)
- Postgres-trigger op `claude_questions` publiceert via `pg_notify('scrum4me_changes', ...)`
- Nieuwe MCP-tools in scrum4me-mcp: `ask_user_question`, `get_question_answer`, `list_open_questions`, `cancel_question`
---
### F-12: API-tokenbeheer
**Prioriteit:** v1 — Vereiste voor Claude Code-integratie