backupchecks/TODO-audit-logging.md

# TODO: Audit Logging Uitbreiding - Vervolg

**Branch:** `v20260206-10-audit-logging-expansion`
**Datum:** 2026-02-07
**Status:** Deel 1 compleet, deel 2 nog te doen

---

## ✅ Wat is al gedaan (Deel 1)

### Model & Database
- ✅ Model hernoemd: `AdminLog` → `AuditLog`
- ✅ Database migratie toegevoegd: `migrate_rename_admin_logs_to_audit_logs()`
  - Hernoemt tabel `admin_logs` → `audit_logs`
  - Idempotent en veilig
- ✅ Backwards compatibility: `AdminLog = AuditLog` alias

### Code Updates
- ✅ `admin_logging.py`: `log_admin_event()` → `log_audit_event()` (met alias)
- ✅ `routes_core.py`: Updated naar `AuditLog`
- ✅ `routes_shared.py`: Updated naar `AuditLog`
- ✅ Gecommit en gepusht naar Gitea

---

## 🔄 Wat moet nog (Deel 2)

### 1. UI Updates

**Bestand:** `containers/backupchecks/src/templates/main/logging.html`

**Te wijzigen:**
- Page title: "Admin Activity" → "System Audit Log" of "Activity Log"
- Breadcrumb indien aanwezig

**Huidige code zoeken naar:**
```html
<h1>Admin Activity</h1>
<!-- of -->
<title>Admin Activity</title>
```

---

### 2. Settings Logging Toevoegen

**Locatie:** `containers/backupchecks/src/backend/app/main/routes_settings.py`

**Routes die logging nodig hebben:**

#### A. General Settings (`/settings/general` POST)
```python
# Na regel waar settings worden opgeslagen
# Voeg toe na db.session.commit()

from ..admin_logging import log_audit_event
import json

# Track wat er gewijzigd is
changes = {}
if old_value != new_value:
    changes['setting_name'] = {'old': old_value, 'new': new_value}

if changes:
    log_audit_event(
        event_type="settings_general",
        message=f"Updated {len(changes)} general setting(s)",
        details=json.dumps(changes, indent=2)
    )
```

**Settings om te tracken:**
- `ui_timezone`
- `require_daily_dashboard_visit`
- `is_sandbox_environment`
- Andere SystemSettings velden

#### B. Mail Settings (`/settings/mail` POST)
```python
log_audit_event(
    event_type="settings_mail",
    message="Updated mail settings",
    details=json.dumps({
        'imap_server': settings.imap_server,
        'auto_import_enabled': settings.auto_import_enabled,
        # etc.
    }, indent=2)
)
```

#### C. Autotask Settings (`/settings/autotask` POST)
```python
log_audit_event(
    event_type="settings_autotask",
    message="Updated Autotask integration settings",
    details=json.dumps({
        'url': settings.autotask_url,
        'username': settings.autotask_username,
        # NIET het wachtwoord loggen!
        'enabled': settings.autotask_enabled
    }, indent=2)
)
```

**BELANGRIJK:** Wachtwoorden NOOIT loggen in details!

---

### 3. Export Logging Toevoegen

#### A. Customers Export (`/customers/export`)

**Huidige code:** `routes_customers.py` regel ~421

**Toevoegen:**
```python
# Voor return Response(...)
from ..admin_logging import log_audit_event

log_audit_event(
    event_type="export_customers",
    message=f"Exported {len(items)} customers to CSV",
    details=f"format=CSV, count={len(items)}"
)
```

#### B. Jobs Export (`/settings/jobs/export`)

**Huidige code:** `routes_settings.py` regel ~207

**Toevoegen:**
```python
# Voor return send_file(...)
log_audit_event(
    event_type="export_jobs",
    message=f"Exported jobs configuration",
    details=json.dumps({
        'format': 'JSON',
        'schema': 'approved_jobs_export_v1',
        'customers_count': len(payload['customers']),
        'jobs_count': len(payload['jobs'])
    }, indent=2)
)
```

---

### 4. Import Logging Toevoegen

#### A. Customers Import (`/customers/import`)

**Huidige code:** `routes_customers.py` regel ~448

**Toevoegen:**
```python
# Na db.session.commit()
log_audit_event(
    event_type="import_customers",
    message=f"Imported customers from CSV",
    details=json.dumps({
        'format': 'CSV',
        'created': created,
        'updated': updated,
        'skipped': skipped
    }, indent=2)
)
```

#### B. Jobs Import (`/settings/jobs/import`)

**Huidige code:** `routes_settings.py` regel ~263

**Is al deels aanwezig, maar uitbreiden:**
```python
# Na db.session.commit()
log_audit_event(
    event_type="import_jobs",
    message="Imported jobs configuration",
    details=json.dumps({
        'format': 'JSON',
        'schema': payload.get('schema'),
        'customers_created': created_customers,
        'customers_updated': updated_customers,
        'jobs_created': created_jobs,
        'jobs_updated': updated_jobs
    }, indent=2)
)
```

---

### 5. Changelog Updaten

**Bestand:** `docs/changelog-claude.md`

**BELANGRIJK:** De datum is nu **2026-02-07**, niet 2026-02-06!

**Toevoegen aan de changelog:**

```markdown
## [2026-02-07]

### Changed
- Renamed AdminLog to AuditLog for better semantic clarity:
  - **Model**: AdminLog → AuditLog (backwards compatible alias maintained)
  - **Table**: admin_logs → audit_logs (automatic migration)
  - **Function**: log_admin_event() → log_audit_event() (alias provided)
  - Better reflects purpose as comprehensive audit trail for both user and system events

### Added
- Expanded audit logging for critical operations:
  - **Settings Changes**: Now logs all changes to General, Mail, Autotask, and Navigation settings
    - Tracks which settings changed (old value → new value)
    - Excludes sensitive data (passwords)
  - **Export Operations**: Logs when users export data
    - Customers export (CSV): count and format
    - Jobs export (JSON): schema version, customer/job counts
  - **Import Operations**: Logs when users import data
    - Customers import (CSV): created/updated/skipped counts
    - Jobs import (JSON): schema version, all operation counts
  - All logging uses event_type for filtering and includes detailed JSON in details field
  - Maintains 7-day retention policy
  - No performance impact (async logging)
```

---

## 📝 Implementatie Tips

### Settings Changes Detecteren

Voor elke setting die je wilt tracken:

```python
# Voor de save
old_value = settings.some_setting

# Na form processing
new_value = form.some_setting.data

# Track change
if old_value != new_value:
    changes['some_setting'] = {
        'old': str(old_value),
        'new': str(new_value)
    }
```

### JSON Serialization

Gebruik `json.dumps()` voor details:

```python
import json

details = json.dumps({
    'key': 'value',
    'count': 123
}, indent=2)
```

### Event Types

**Consistent naming:**
- `settings_general`
- `settings_mail`
- `settings_autotask`
- `export_customers`
- `export_jobs`
- `import_customers`
- `import_jobs`

---

## 🎯 Volgende Stappen (Morgen)

1. UI updaten (logging.html page title)
2. Settings logging implementeren (General, Mail, Autotask)
3. Export logging implementeren (Customers, Jobs)
4. Import logging implementeren (Customers, Jobs)
5. Changelog updaten met **correcte datum 2026-02-07**
6. Testen of logging werkt
7. Committen en pushen

---

## 🔍 Test Checklist

Na implementatie testen:

- [ ] Wijzig general setting → check /logging
- [ ] Wijzig mail setting → check /logging
- [ ] Wijzig Autotask setting → check /logging
- [ ] Export customers → check /logging
- [ ] Export jobs → check /logging
- [ ] Import customers → check /logging
- [ ] Import jobs → check /logging
- [ ] Check of user naam correct is
- [ ] Check of details field JSON bevat
- [ ] Check of event_type correct is

---

## 📂 Belangrijke Bestanden

```
containers/backupchecks/src/backend/app/
├── admin_logging.py              # log_audit_event() functie
├── models.py                      # AuditLog model
├── migrations.py                  # migrate_rename_admin_logs_to_audit_logs()
└── main/
    ├── routes_settings.py         # Settings routes (toevoegen logging)
    ├── routes_customers.py        # Customer export/import (toevoegen logging)
    ├── routes_core.py             # Logging page
    └── routes_shared.py           # _log_admin_event() wrapper

containers/backupchecks/src/templates/main/
└── logging.html                   # UI update (page title)

docs/
└── changelog-claude.md            # Changelog (datum 2026-02-07!)
```

---

## ⚠️ Let Op!

1. **Wachtwoorden NOOIT loggen** in details veld
2. **Datum in changelog: 2026-02-07** (niet 06!)
3. **Event types consistent** houden (lowercase, underscore)
4. **JSON format** voor details veld (makkelijk te parsen)
5. **Backwards compatibility** behouden (aliases)