ct/bmc_hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
770f822fc6
bmc_hub/static/js/## Plan: Manualmodul MVP i BMC Hub.prompt.md
Christian ceb560e2f2 feat: Add bottom bar functionality with real-time updates and manual endpoint tests 
- Implemented a new bottom bar feature in `bottom-bar.js` that fetches and displays various notifications and statuses in real-time.
- Added functions for handling visibility, state updates, and user interactions within the bottom bar.
- Introduced WebSocket connection for real-time updates and fallback polling mechanism.
- Created a manual testing script `test_manual.py` to validate API endpoints for the manual module.
- Included tests for various paths to ensure expected responses from the server.
2026-04-12 02:27:01 +02:00

8.7 KiB
Raw Blame History

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.
  1. 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.
  1. 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.
  1. 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.