bmc_hub/NEXTCLOUD_MODULE_PLAN.md

Nextcloud-modul – BMC Hub

1. Formål og rolle i Hubben

Nextcloud-modulet gør det muligt at sælge, administrere og supportere kunders Nextcloud‑løsninger direkte i Hubben.

Hubben er styrende system. Nextcloud er et eksternt drifts‑ og brugersystem, som Hubben taler med direkte (ingen gateway).

2. Aktivering af modulet

Modulet er kontekstbaseret og aktiveres via tag:

• Når Firma, Kontakt eller Sag har tagget nextcloud, vises en Nextcloud‑fane i UI.
• Uden tag vises ingen Nextcloud‑funktioner.

3. Kunde → Nextcloud‑fane (overblik)

Fanen indeholder:

1. Drifts‑ og systeminformation (read‑only)
2. Handlinger relateret til brugere
3. Historik (hvad Hubben har gjort mod instansen)

Fanen må aldrig blokere kundevisningen, selv hvis Nextcloud er utilgængelig.

4. Systemstatus og driftsinformation

Datakilde: Nextcloud Serverinfo API

• GET /ocs/v2.php/apps/serverinfo/api/v1/info
• Direkte kald til Nextcloud
• Autentificeret
• Read‑only
• Cached i DB med global TTL = 5 min

4.1 Overblik

Vises øverst i fanen:

• Instans‑status (Online / Offline / Ukendt)
• Sidst opdateret
• Nextcloud‑version
• PHP‑version
• Database‑type og ‑version

4.2 Ressourceforbrug

Vises som simple værdier/badges:

• CPU
• Load average (1 / 5 / 15 min)
• Antal kerner
• RAM (total + brug i %)
• Disk (total + brug i % + fri plads)

Ved kritiske værdier vises advarsel.

4.3 Nextcloud‑nøgletal

Hvor API tillader det:

• Antal brugere
• Aktive brugere
• Antal filer
• Samlet datamængde
• Status på: database, cache/Redis, cron/background jobs

5. Handlinger i Nextcloud‑fanen

Knapper:

• Tilføj ny bruger
• Reset password
• Luk bruger
• Gensend guide

Alle handlinger:

• udføres direkte mod Nextcloud
• logges i Hub
• kan spores i historik
• kan knyttes til sag

6. Tilføj ny bruger (primær funktion)

6.1 Start af flow

• Ved “Tilføj ny bruger” oprettes automatisk en ny Sag
• Sagstype: Nextcloud – Brugeroprettelse
• Ingen Nextcloud‑handling udføres uden en sag

6.2 Sag – felter og logik

Firma

• Vælg eksisterende firma
• Hub slår tilknyttet Nextcloud‑instans op i DB og vælger automatisk
• Instans kan ikke ændres manuelt

Kontaktperson

• Vælg eksisterende kontakt eller opret ny
• Bruges til kommunikation, velkomstmail og ejerskab af sag

Grupper

• Multiselect
• Hentes live fra Nextcloud (OCS groups API)
• Kun gyldige grupper kan vælges

Velkomstbrev

• Checkbox: skal velkomstbrev sendes?
  • Hvis ja: bruger oprettes, password genereres, guide + logininfo sendes
  • Hvis nej: bruger oprettes uden mail, sag forbliver åben til manuel opfølgning

7. Øvrige handlinger

Reset password

• Vælg eksisterende Nextcloud‑bruger
• Nyt password genereres
• Valg: send mail til kontakt eller kun log i sag

Luk bruger

• Bruger deaktiveres i Nextcloud
• Data bevares
• Kræver eksplicit bekræftelse
• Logges i sag og historik

Gensend guide

• Gensender velkomstmail og guide
• Password ændres ikke
• Kan udføres uden ny sag, men logges

8. Arkitekturprincipper

• Hub ejer: firma, kontakt, sag, historik
• Nextcloud ejer: brugere, filer, rettigheder
• Integration er direkte (ingen gateway)
• Per‑instans auth ligger krypteret i DB
• Global DB‑cache (5 min) for read‑only statusdata

9. Logning og sporbarhed

For hver handling gemmes:

• tidspunkt
• handlingstype
• udførende bruger
• mål (bruger/instans)
• teknisk resultat (success/fejl)

Audit‑log er separat pr. kunde, med manuel retention og tidsbaseret partitionering.

10. Afgrænsninger (v1)

Modulet indeholder ikke:

• ændring af server‑konfiguration
• håndtering af apps
• ændring af kvoter
• direkte admin‑login

11. Klar til udvidelse

Modulet er designet til senere udvidelser:

• overvågning → automatisk sag
• historiske grafer
• offboarding‑flows
• kvote‑styring
• SLA‑rapportering

12. Sikkerhed og drift

• Credentials krypteres med settings.NEXTCLOUD_ENCRYPTION_KEY
• Safety switches: NEXTCLOUD_READ_ONLY og NEXTCLOUD_DRY_RUN (default true)
• Ingen credentials i UI eller logs
• TLS‑only base URLs

13. Backend‑struktur (plan)

Placering: app/modules/nextcloud/

• backend/router.py
• backend/service.py
• backend/models.py

Alle eksterne kald går via service‑laget, som:

• loader instans fra DB
• dekrypterer credentials
• bruger global DB‑cache (5 min)
• skriver audit‑log pr. kunde

14. Database‑model (plan)

nextcloud_instances

• customer_id FK
• base_url
• auth_type
• username
• password_encrypted
• is_enabled, disabled_at
• created_at, updated_at, deleted_at

nextcloud_cache

• cache_key (PK)
• payload (JSONB)
• expires_at
• created_at

nextcloud_audit_log

• customer_id, instance_id
• event_type
• request_meta, response_meta
• actor_user_id
• created_at

Partitionering: månedlig range på created_at. Retention er manuel via admin‑UI.

15. API‑endpoints (v1)

Instanser (admin)

• GET /api/v1/nextcloud/instances
• POST /api/v1/nextcloud/instances
• PATCH /api/v1/nextcloud/instances/{id}
• POST /api/v1/nextcloud/instances/{id}/disable
• POST /api/v1/nextcloud/instances/{id}/enable
• POST /api/v1/nextcloud/instances/{id}/rotate-credentials

Status + grupper

• GET /api/v1/nextcloud/instances/{id}/status
• GET /api/v1/nextcloud/instances/{id}/groups

Brugere (handlinger)

• POST /api/v1/nextcloud/instances/{id}/users (opret)
• POST /api/v1/nextcloud/instances/{id}/users/{uid}/reset-password
• POST /api/v1/nextcloud/instances/{id}/users/{uid}/disable
• POST /api/v1/nextcloud/instances/{id}/users/{uid}/resend-guide

Alle endpoints skal:

• validere is_enabled = true
• håndhæve kundeejerskab
• skrive audit‑log
• respektere READ_ONLY/DRY_RUN

16. UI‑krav (plan)

Nextcloud‑fanen i kundevisning skal vise:

• Systemstatus
• Nøgletal
• Handlinger
• Historik

Admin‑UI (Settings) skal give:

• Liste over instanser
• Enable/disable
• Rotation af credentials
• Retentionstyring af audit‑log pr. kunde

17. Migrations (plan)

1. migrations/0XX_nextcloud_instances.sql
2. migrations/0XX_nextcloud_cache.sql
3. migrations/0XX_nextcloud_audit_log.sql (partitioneret)

18. Næste skridt

1. Opret migrationsfiler
2. Implementer kryptering helper
3. Implementer service‑lag
4. Implementer routere og schemas
5. Implementer UI‑fanen + admin‑UI
6. Implementer audit‑log viewer/export