From 2d98a4386c19cbd288a8d655653a9a778afeac9f Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Tue, 28 Apr 2026 00:33:59 +0200 Subject: [PATCH] =?UTF-8?q?docs(ST-1108):=20add=20F-11b=20=E2=80=94=20Clau?= =?UTF-8?q?de=20question-channel=20to=20functional=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/scrum4me-functional-spec.md | 38 ++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/scrum4me-functional-spec.md b/docs/scrum4me-functional-spec.md index 4fa4236..9b5712e 100644 --- a/docs/scrum4me-functional-spec.md +++ b/docs/scrum4me-functional-spec.md @@ -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