## Plan: Manualmodul MVP i BMC Hub

Lever et API-first manualmodul med UUID-baseret datamodel, dedikeret oversigt/artikelsider, kontekstuel modalhjælp og admin CRUD i samme MVP. Implementer søgning med ILIKE nu for hurtig leverance og lav en klar fase-2 bane til PostgreSQL full-text + synonymer, så performance og AI-ready retning bevares uden at blokere MVP.

**Steps**
1. Fase 1: Datamodel + migrationer (blokkerende)
2. Definér og opret tabellerne manual_articles, manual_steps og manual_relations med UUID primary keys, timestamps og soft delete (deleted_at). Tilføj nødvendige indeks for slug-opslag, modulfiltrering, sværhedsgrad, og relation-opslag. Markér slug som unik.
3. Beslut relation mellem manualer og eksisterende tagsystem: brug enten direkte JSONB tags i manual_articles (hurtigst) eller kobling til eksisterende tags/entity_tags via entity_type=manual. For MVP anbefales begge: behold tags JSONB til hurtig filtrering og tilføj relation hooks til entity_tags for fremtidig konsolidering. Depends on step 2.
4. Fase 2: Backend API + services
5. Opret ny vertical slice for manualmodulet med router, models og service-lag efter eksisterende featurestruktur. Router skal registreres under /api/v1/manual i main app startup. Depends on fase 1.
6. Implementer endpoints: GET liste (filtre: module, tags, difficulty, search), GET by slug, POST create, PUT update, DELETE soft delete. Tilføj validering for slug-kollisioner og payload-format for steps/relations. Parallel with step 7 once models are in place.
7. Implementer nested håndtering af steps (sorteret efter step_number) og related-manuals retrieval i artikel-endpoint, så frontend kan rendere én samlet artikelvisning uden ekstra roundtrips. Parallel with step 6.
8. Implementer kontekst-endpoint (fx query param context_module eller context_tag) så ?-ikoner kan hente relevante manualer direkte fra aktivt modul. Depends on step 6.
9. Fase 3: Frontend visning + kontekstuel hjælp
10. Opret manualsider i eksisterende template-system: en oversigtsside og en artikelside. Bevar Nordic Top, eksisterende dark mode og CSS variable-tema. Depends on fase 2.
11. Implementer UI i oversigten: søgefelt, modulfilter, tagfilter, sværhedsgrad og sortering med mest brugte øverst (baseret på visningscounter eller fallback created/updated sort indtil metrics er tilføjet). Parallel with step 12.
12. Implementer artikelside med titel, summary, step-by-step blokke, media (lazy loading), relaterede manualer og Åbn i kontekst-links. Parallel with step 11.
13. Integrer ?-ikon i prioriterede moduler (Sag, Hardware, Mail) med modal viewer, der loader relevant manual via context query. Brug eksisterende Bootstrap modal-mønster i base layout. Depends on step 8 and step 10.
14. Fase 4: Admin CRUD UI (MVP-krav)
15. Opret admin-side til opret/rediger/slet manualer med markdown editor, preview, step-editor og relation-editor. Brug server-side forms + eksisterende komponentmønstre for hurtig stabil levering. Depends on fase 2.
16. Implementer upload flow for billeder/video med validering af filtype/størrelse og lagring via eksisterende uploadmønster i repo. Sørg for at manual media kan references fra manual_steps. Depends on step 15.
17. Fase 5: Performance + observability + hardening
18. Tilføj målrettede indeks og query tuning for liste/slug/kontekst-opslag så listekald kan holde sig under 200ms i normal drift. Depends on fase 2.
19. Tilføj simpel cache for populære manualer (fx memory/cache-lag på GET liste og GET by slug), med sikker invalidation ved POST/PUT/DELETE. Depends on step 6.
20. Tilføj audit/logging for admin-ændringer og basis metrics (views/use_count) til ranking af Mest brugte. Parallel with step 19.
21. Fase 6: Verifikation + release
22. Backend tests: endpoint-kontrakter, validering, soft delete, filtrering, søgning og slug-unikhed.
23. Frontend tests/smoke: dark/light mode, responsive layouts, modal-konteksthjælp i Sag/Hardware/Mail, lazy loading af media.
24. Performance test: mål API-responstid for GET /api/v1/manual under realistisk dataset og justér indeks/cache til målopfyldelse.
25. Dokumentér MVP scope, begrænsninger og fase-2 roadmap for full-text + synonym mapping + AI forslag.

**Relevant files**
- /Users/christianthomas/DEV/bmc_hub_dev/main.py — registrering af nye manual-routere under API v1.
- /Users/christianthomas/DEV/bmc_hub_dev/app/core/database.py — query-patterns, execute_query helpers, transaction-adfærd.
- /Users/christianthomas/DEV/bmc_hub_dev/app/tags/backend/router.py — reference for CRUD/filter/search endpoint struktur.
- /Users/christianthomas/DEV/bmc_hub_dev/app/modules/search/backend/router.py — reference for nuværende ILIKE-baseret søgeadfærd.
- /Users/christianthomas/DEV/bmc_hub_dev/app/shared/frontend/base.html — dark mode toggle, navbar, modal patterns og theming variables.
- /Users/christianthomas/DEV/bmc_hub_dev/app/modules/orders/templates/list.html — reference for liste-layout med filter/toolbar/stats.
- /Users/christianthomas/DEV/bmc_hub_dev/app/modules/hardware/templates/detail.html — reference for detailside mønster og infoblokke.
- /Users/christianthomas/DEV/bmc_hub_dev/migrations/027_tag_system.sql — eksisterende tag/entity_tags arkitektur til manual relation.

**Verification**
1. Kør backend tests for alle manual-endpoints inkl. edge cases: manglende slug, dobbelt slug, tomme steps, soft-deleted records.
2. Kør integrationstest med seedet data: filtrering (module/tags/difficulty), kontekst-lookup og related manuals.
3. Kør UI-smoke på desktop + mobil: manual oversigt, artikelside, admin editor, ?-ikon modal i 3 moduler.
4. Mål responstid på GET liste + GET slug med og uden cache; dokumentér baseline og efteroptimering.
5. Verificér accessibility basics: focus states, kontrast i dark/light, keyboard-lukning af modal.

**Decisions**
- UUID vælges til manualtabellerne, selvom øvrige features ofte bruger serial id.
- MVP inkluderer både dedikerede manualsider og modalbaseret konteksthjælp.
- MVP inkluderer fuld admin CRUD UI inkl. markdown, preview og media-upload.
- MVP bruger simpel ILIKE-søgning; FTS + synonym-mapping flyttes til fase 2.

**Scope boundaries**
- Inkluderet: manualliste, artikel, relationer til modul/tag/sag-type, kontekstuel ?-hjælp, admin CRUD, simpel søgning.
- Ekskluderet i MVP: AI chatbot, auto-generering af manualer, heatmaps, avanceret synonym-ranking i runtime.

**Further Considerations**
1. Fase-2 datamodel for synonymer bør designes nu (table for canonical_term/alias/context), men aktiveres først efter MVP-go-live.
2. Overvej at gøre use_count events asynkrone for at undgå write-overhead på hvert view-request.
3. Afklar tidligt om markdown rendering skal sanitizes ekstra hårdt (XSS policy) i både preview og public view.

**Sprint-opdeling (forslag)**
1. Sprint 1 (5-7 dage): Fundament + API basis
- Leverancer: migrationer (UUID), manual core models, CRUD endpoints (liste/by slug/create/update/delete), simpel ILIKE søgning, baseline tests for API kontrakter.
- Exit-kriterier: GET liste og GET slug stabile i testmiljø, soft delete virker, slug-unikhed håndhæves.
- Estimat: 30-40 timer.

2. Sprint 2 (5-7 dage): Frontend brugerflow + konteksthjælp
- Leverancer: /manual oversigt, /manual/{slug} artikel, filter/search UI, relaterede manualer, ?-ikon modal i Sag/Hardware/Mail med kontekst-filtrering.
- Exit-kriterier: Bruger kan finde manual på maks 2 klik fra modul, dark/light mode og mobil virker uden regressions.
- Estimat: 35-45 timer.

3. Sprint 3 (5-7 dage): Admin CRUD + media + hardening
- Leverancer: admin editor (markdown + preview), steps/relation editor, billede/video upload, caching af populære manualer, metrics/audit logging.
- Exit-kriterier: Admin kan vedligeholde manualer end-to-end uden DB-manualarbejde, liste-load holder performance mål i normal drift.
- Estimat: 40-55 timer.

4. Sprint 4 (2-4 dage): Stabilisering + release
- Leverancer: performance tuning (<200ms mål), integration/smoke tests, accessibility baseline, release notes + fase-2 backlog (FTS/synonymer/AI).
- Exit-kriterier: Produktionsklar MVP med dokumenteret teststatus og kendte begrænsninger.
- Estimat: 16-28 timer.

**Samlet estimat**
- Lavt/højt spænd: 121-168 timer.
- Anbefalet bemanding: 1 backend + 1 frontend (delvist parallelt) eller 1 fullstack med 20-30% længere kalenderforløb.

**Parallelisering pr. sprint**
1. Sprint 1: DB migration + API modelarbejde kan starte parallelt; endpoint wiring afhænger af migration.
2. Sprint 2: Oversigtsside og artikelside kan bygges parallelt; modal-integration afhænger af kontekst-endpoint.
3. Sprint 3: Admin editor og caching/metrics kan køre parallelt; upload flow afhænger af valgt storage pattern.
4. Sprint 4: Testautomatisering og performance profiling kan køre parallelt frem mod release cut.