janpeter/Scrum4Me
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 10
Scrum4Me/docs/architecture/product-docs.md
Madhura68 d32b39f62f
Some checks are pending
CI / Lint, Typecheck, Test & Build (pull_request) Waiting to run
Details
CI / Detect deploy-relevant changes (pull_request) Blocked by required conditions
Details
CI / Deploy Preview (PR) (pull_request) Blocked by required conditions
Details
CI / Deploy Production (main) (pull_request) Blocked by required conditions
Details
CI / Deploy Manual (workflow_dispatch) (pull_request) Waiting to run
Details
docs(PBI-96/T-1076): architecture breadcrumb + F-15 functional spec 
- docs/architecture/product-docs.md: nieuw topical doc met folder-set,
  datamodel, P1/P2 review-fixes, server-actions tabel, UI-routes en
  editor-extractie. Verwijst naar plan + recommendations + relevante
  bestanden.
- docs/architecture.md: breadcrumb-rij naar product-docs.md.
- docs/specs/functional.md: F-15-sectie "Per-product documentatie
  (Product Docs)" met acceptatiecriteria voor overzicht/aanmaken/
  bewerken/verwijderen/folder-config/demo-policy/toegang + randgevallen.
- INDEX.md regen automatisch via pre-commit hook.

ST-F is hiermee compleet — ALLE 18 PBI-96 taken klaar.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-16 14:38:15 +02:00

4.1 KiB
Raw Blame History

title status audience language last_updated applies_to
Product Docs (per-product documentatie) active
maintainer
contributor
nl 2026-05-16 PBI-96

Per-product documentatie (Product Docs)

Elk product in de app krijgt een sjabloon-documentatiestructuur met 8 kern-folders, configureerbaar per product, en beheerd via een in-app markdown-editor. Voor het volledige implementatieplan: docs/plans/PBI-96-product-docs.md.

Folder-sjabloon

Identiek aan de Scrum4Me-eigen docs/-tree:

Folder Doel
adr Architecture Decision Records
architecture Topische arch-bestanden
patterns Herbruikbare code-patronen
plans Feature- en PBI-plannen
runbooks Operationele procedures
specs Functionele specificaties
manual Developer manual
api API-contract details

Per product configureerbaar via Product.enabled_doc_folders (Postgres array van ProductDocFolder-enum). Default: alle 8 enabled. Toggleable in /products/[id]/docs/settings (owner-only).

Datamodel

  • ProductDoc (prisma/schema.prisma:527): id, product_id, folder, slug (uniek per (product_id, folder)), title + status (uit frontmatter gesynct), content_md (raw markdown met YAML-frontmatter), created_by, timestamps.
  • ProductDocLog: audit-trail met actor_user_id (denormalized, geen FK), type (CREATED|UPDATED|DELETED|FOLDER_ENABLED|FOLDER_DISABLED), metadata (Json). doc_id is nullable + SetNull zodat delete-rijen overleven (zie P1-fix hieronder).

Belangrijke design-keuzes

  • title/status als gerepliceerde kolommen — list-queries hoeven MD niet te parsen.
  • status als VARCHAR i.p.v. enum — frontmatter is user-input; geen schema-migratie bij nieuwe waarde.
  • Actor-velden denormalized (geen FK) — minder schema-coupling voor v1; index voor toekomstige timeline-queries staat klaar. Migratie naar FK is reversible.

Review-fixes (P1 + P2)

Verwerkt vanuit docs/recommendations/product-docs-storage-system-review-2026-05-16.md:

  • P1 (delete-audit) — deleteProductDocAction schrijft de DELETED-log met doc_id: null vóór de delete in dezelfde $transaction; geen FK-race.
  • P2 (frontmatter-sync) — createProductDocAction en updateProductDocAction synchroniseren title + status uit parsed.frontmatter naar de kolommen; last_updated wordt server-side overschreven via setProductDocFrontmatterFields.
  • Disabled-folder semantiek — verborgen op INDEX/nav, maar directe URLs blijven leesbaar met een banner. Anti-data-loss.

Server-actions

actions/product-docs.ts implementeert 5 actions volgens docs/patterns/server-action.md:

Action Demo-403 Owner-only Notes
createProductDocAction ✅ nee (ProductMember ook) P2: title/status sync, P2: last_updated normalisatie
updateProductDocAction ✅ nee UPDATED-log met prev_status/new_status
deleteProductDocAction ✅ nee P1: log met doc_id:null vóór delete
toggleProductDocFolderAction ✅ ja folder-config = product-setting
listProductDocsAction nee nee demo MAG lezen

UI

Routes onder app/(app)/products/[id]/docs/:

  • page.tsx — INDEX-grid van enabled folders
  • settings/page.tsx — folder-toggle UI
  • [folder]/page.tsx — folder-listing tabel
  • [folder]/[slug]/page.tsx — viewer/editor

Sub-navigatie via components/products/product-subnav.tsx (tabs: Backlog/Sprint/Solo/Docs/Instellingen).

Editor-extractie

components/shared/markdown-doc-editor.tsx is geëxtraheerd uit idea-md-editor.tsx. Beide Ideas en Product Docs gebruiken dezelfde editor-stack (Cmd+S, localStorage-draft, live yaml-validatie). De wrappers (idea-md-editor.tsx, product-doc-editor.tsx) injecteren de entity-specifieke validator + save-action.