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