# Dokumentation: `pivot_analysis.php`

## 1. Zweck

[`pivot_analysis.php`](pivot_analysis.php) ist eine einseitige Web-Anwendung (PHP und HTML in einer Datei) zur Prüfung von Treffern („Review of Matches“). Sie liest Datensätze aus der Tabelle `review` der Datenbank `preq` und zeigt sie als Pivot-Tabelle an. Pro Suchbegriff können Benutzer festlegen, wie mit den Treffern verfahren werden soll (anonymisieren, ignorieren, Datei löschen usw.). Die Entscheidung wird in der Spalte `user_defined_action` gespeichert.

---

## 2. Fachlicher Ablauf

1. Der Benutzer wählt eine Datenquelle (Kombination aus `tenant` und `Caseid`).
2. Die Anwendung lädt alle Datensätze dieser Quelle und verdichtet sie zu einer Pivot-Tabelle.
3. Der Benutzer filtert optional nach Search Term, PP Action oder User Defined Action.
4. Der Benutzer legt Aktionen fest, auf eine von zwei Arten:
   - **Sammelbearbeitung:** Eine Aktion gilt für alle Datensätze eines Search Terms.
   - **Einzelbearbeitung:** Im Detaildialog wird für jeden Datensatz einzeln eine Aktion gewählt.
5. Die Änderungen werden in der Datenbank gespeichert. Danach lädt die Seite neu.

### Aktionscodes (`user_defined_action`)

| Code | Bedeutung | Interner Aktionsname (Sammelbearbeitung) |
| :--- | :--- | :--- |
| `A` | Anonymisieren | `anonymize` |
| `I` | Match ignorieren | `ignore` |
| `D` | Datei löschen | `delete` |
| `N` | Keine Aktion | `none` |
| `-` | Zurücksetzen / keine Entscheidung | `reset` |

---

## 3. Konfiguration

Die Konfiguration steht als Variablen am Dateianfang:

| Variable | Wert / Bedeutung |
| :--- | :--- |
| `$dbHost` | Datenbankserver (`localhost`) |
| `$dbUser`, `$dbPassword` | Zugangsdaten (im Quelltext hinterlegt) |
| `$dbName` | Datenbank `preq` |
| `$dbCharset` | Zeichensatz `utf8` |
| `$dbTable` | Tabelle `review` |

Laufzeit-Einstellungen:

- `error_reporting(E_ALL)` und `display_errors = 1`
- `memory_limit = 512M`
- `set_time_limit(120)`
- `session_start()` zu Beginn für Auswahl und Meldungen

---

## 4. Datenmodell

Die Anwendung verwendet folgende Spalten der Tabelle `review`:

| Spalte | Verwendung |
| :--- | :--- |
| `_id` | Eindeutige ID des Datensatzes. Sie dient als Schlüssel beim Aktualisieren. |
| `tenant` | Mandant. Er bildet zusammen mit `Caseid` die Datenquelle. |
| `Caseid` | Fall-ID. |
| `search_term` | Suchbegriff. Er ist das Gruppierungsmerkmal der Pivot-Tabelle. |
| `pp_action` | Vom System vorgeschlagene Aktion (PP Action). |
| `user_defined_action` | Vom Benutzer gewählte Aktion. Nur diese Spalte wird geschrieben. |
| `match_csvt` | Treffertext. Er wird im Detaildialog angezeigt, gekürzt auf 80 Zeichen. |
| `full_path` | Dateipfad. Er wird im Detaildialog angezeigt. |

Die Anwendung lädt mit `SELECT *` alle Spalten. Neben den oben genannten werden keine weiteren ausgewertet.

---

## 5. PHP-Funktionen

### `getDbConnection(): PDO`
Baut die Datenbankverbindung auf und gibt sie bei weiteren Aufrufen wieder zurück (`static`, also eine Verbindung pro Request). Fehler werden als Exceptions gemeldet, Ergebniszeilen als assoziative Arrays geliefert.

### `getSelectionOptions(PDO $pdo, string $tableName): array`
Liest alle verschiedenen Paare aus `tenant` und `Caseid`, bei denen beide Felder nicht leer sind. Sortiert wird nach `tenant`, dann `Caseid`. Rückgabe ist eine Liste mit `value` (`tenant|Caseid`) und `label` (`tenant/Caseid`) für das Auswahlfeld.

```sql
SELECT DISTINCT `tenant`, `Caseid`
FROM `review`
WHERE `tenant` IS NOT NULL AND TRIM(`tenant`) <> ''
  AND `Caseid` IS NOT NULL AND TRIM(`Caseid`) <> ''
ORDER BY `tenant`, `Caseid`
```

### `loadReviewData(PDO $pdo, string $tableName, ?string $selection): array`
Lädt die Datensätze der aktiven Auswahl. Der String `tenant|Caseid` wird am ersten `|` getrennt und als Prepared-Statement-Parameter (`:tenant`, `:caseid`) gebunden. Ist keine gültige Auswahl vorhanden, werden **alle** Datensätze geladen.

Rückgabe: `[$data, $headers]`
- `$data`: Liste der Datensätze, wobei `_id` in einen String umgewandelt wird.
- `$headers`: Spaltennamen, abgeleitet aus der ersten Zeile.

### `saveRowActions(PDO $pdo, string $tableName, array $rowActions): int`
Speichert viele Aktionen mit **einem** `UPDATE`. Eingabe ist ein Array `[_id => Aktionscode]`. Ein leerer Code wird als `-` gespeichert. Rückgabe ist die Anzahl der übergebenen Einträge, nicht die Zahl der tatsächlich geänderten Zeilen.

```sql
UPDATE `review`
SET `user_defined_action` = CASE `_id`
        WHEN :id_101 THEN :action_101
        WHEN :id_102 THEN :action_102
        ELSE `user_defined_action`
    END
WHERE `_id` IN (:id_101, :id_102)
```

Die Parameternamen entstehen aus der `_id`, wobei Sonderzeichen durch `_` ersetzt werden. Alle Werte werden gebunden.

---

## 6. Request-Verarbeitung (Serverseite)

Die Verarbeitung läuft im PHP-Teil vor der HTML-Ausgabe in dieser Reihenfolge:

| Nr. | Auslöser | Verhalten |
| :--- | :--- | :--- |
| 1 | `GET ?reset=1` | Löscht `$_SESSION['active_selection']`, setzt eine Info-Meldung und leitet auf die URL ohne Query-String um. |
| 2 | `GET ?select_source=<tenant>\|<Caseid>` | Speichert die Auswahl in `$_SESSION['active_selection']` und leitet auf die URL ohne Query-String um. |
| 3 | Initiales Laden | Liest die Auswahl aus der Session, holt die Auswahloptionen und lädt die Daten. Datenbankfehler landen in `$dbError`. |
| 4 | `POST ?save_individual_actions=1` | JSON-Schnittstelle zum Speichern (siehe unten). |
| 5 | Sonstiger `POST` | Fallback für klassische Formular- oder JSON-Posts (siehe unten). |
| 6 | Aufbereitung | Berechnet Pivot-Daten und Kennzahlen und gibt die HTML-Seite aus. |

### JSON-Schnittstelle `POST ?save_individual_actions=1`

Das ist der Weg, den die Oberfläche tatsächlich nutzt, sowohl für die Einzel- als auch für die Sammelbearbeitung.

- **Anfrage** (`Content-Type: application/json`):
  ```json
  { "row_actions": { "101": "A", "102": "I", "103": "-" } }
  ```
- **Erfolgsantwort:**
  ```json
  { "success": true, "updatedCount": 3, "message": "Änderungen erfolgreich gespeichert." }
  ```
- **Fehlerantworten** (`success: false`) gibt es bei:
  - falscher Request-Methode (nicht POST),
  - fehlendem oder ungültigem `row_actions`,
  - einer Datenbankausnahme beim Speichern.

### Fallback-Verarbeitung (klassischer POST)

Dieser Zweig verarbeitet POST-Anfragen ohne `save_individual_actions=1`. Er akzeptiert:
- `row_actions` (JSON-String) und speichert diese direkt,
- `action` zusammen mit `search_term`. Dann werden alle Datensätze der aktiven Auswahl mit diesem `search_term` auf den passenden Code gesetzt.

Bei Erfolg schreibt er eine Meldung in die Session und leitet um. Bei JSON-Anfragen antwortet er mit JSON. Die aktuelle Oberfläche fängt das Absenden des Sammelformulars per JavaScript ab, daher dient dieser Zweig im Normalfall nur als Rückfallebene.

### Datenaufbereitung (Pivot)

Alle geladenen Datensätze werden nach dem Schlüssel `search_term | pp_action | user_defined_action` gruppiert und gezählt. Das Ergebnis `$pivotData` wird absteigend nach Anzahl sortiert.

Kennzahlen:

| Variable | Bedeutung |
| :--- | :--- |
| `$totalRecords` | Anzahl aller geladenen Datensätze |
| `$uniqueSearchTerms` | Anzahl verschiedener nicht leerer Suchbegriffe |
| `$uniquePpActions` | Anzahl verschiedener nicht leerer PP Actions |
| `$uniqueUserActions` | Anzahl verschiedener nicht leerer User Actions |

---

## 7. Benutzeroberfläche

### 7.1 Meldungen
Meldungen (`$_SESSION['message']`, grün) und Fehler (`$_SESSION['error']`) werden einmalig angezeigt und danach aus der Session entfernt.

### 7.2 Datenquelle
- Auswahlfeld `tenant / Caseid` mit dem Button **„Aktivieren“** (sendet `select_source`).
- Anzeige der aktiven Auswahl, sonst ein Hinweis „Keine Auswahl aktiv“.
- Button **„Auswahl zurücksetzen“** (`?reset=1`) mit Bestätigungsdialog.

### 7.3 Kennzahlen
Vier Karten: Gesamt Einträge, Suchbegriffe, PP Actions, User Actions.

### 7.4 Filter
Drei Auswahlfelder: Search Term, PP Action und User Defined Action. Sie senden beim Ändern sofort per GET (`filter_search_term`, `filter_pp_action`, `filter_user_action`). Die Filter wirken **serverseitig auf die Pivot-Tabelle**. Die Kennzahlen bleiben davon unberührt. Der Link „Filter zurücksetzen“ erscheint, sobald ein Filter gesetzt ist.

### 7.5 Pivot-Tabelle
Spalten: Search Term, PP Action, User Defined Action, Anzahl und Aktion.
- Ein Klick auf den **Search Term** öffnet den Detaildialog.
- Der Button **„Bearbeiten“** öffnet den Dialog für die Sammelaktion.
- Die letzte Zeile zeigt die **Gesamtsumme** der gefilterten Zeilen.
- Ohne Treffer erscheint „Keine Daten gefunden“.

### 7.6 Dialog „Aktion für Search Term“ (Sammelbearbeitung)
- Zeigt Search Term, PP Action, aktuelle User Action und Anzahl.
- Auswahl per Radiobutton: Anonymisieren, Match ignorieren, Datei löschen, Keine Aktion, Zurücksetzen.
- Die aktuelle Aktion ist vorausgewählt.
- Beim Speichern prüft JavaScript, ob ein Search Term und eine Aktion gewählt sind, und ermittelt alle Datensätze dieses Search Terms aus den bereits geladenen Daten. Diese werden in **Paketen zu je 100** nacheinander an die JSON-Schnittstelle gesendet. Ein Fortschrittsbalken zeigt den Stand. Danach lädt die Seite neu.

### 7.7 Dialog „Alle Einträge für Search Term“ (Einzelbearbeitung)
- Listet alle Datensätze des gewählten Search Terms mit Match (`match_csvt`, gekürzt auf 80 Zeichen), PP Action, einem Auswahlfeld für die Aktion (`-`, A, I, D, N) und der Datei (`full_path`).
- **„Individuelle Änderungen speichern“** sendet **alle** angezeigten Zeilen mit ihrem aktuellen Auswahlwert in einer Anfrage an die JSON-Schnittstelle. Der Auswahlwert `-` wird als leerer String gesendet und serverseitig als `-` gespeichert.

### 7.8 Fortschrittsanzeige
Beim Speichern erscheint ein Overlay mit Fortschrittsbalken und Text. Bei Fehlern wird es ausgeblendet, der Button zurückgesetzt und eine Fehlermeldung als `alert` angezeigt.

### 7.9 Bedienung
Die Dialoge schließen sich über das ×, den Button „Abbrechen“ / „Schließen“, einen Klick neben den Dialog oder die ESC-Taste.

---

## 8. JavaScript-Funktionen (Überblick)

| Funktion | Aufgabe |
| :--- | :--- |
| `allData` | Alle geladenen Datensätze, vom Server als JSON in die Seite geschrieben |
| `openModal` / `closeModal` | Dialog der Sammelbearbeitung öffnen und schließen |
| `openDetailModal` / `closeDetailModal` | Detaildialog füllen, öffnen und schließen |
| `getBulkActionValue` | Wandelt den Aktionsnamen in den Code (`A`, `I`, `D`, `N`, `-`) um |
| `saveBulkActionsWithProgress` | Sammelbearbeitung in Paketen zu je 100 Datensätzen |
| `saveIndividualActions` | Speichert die Auswahl im Detaildialog |
| `setSaveProgress` / `hideSaveProgress` | Fortschrittsanzeige ein- und ausblenden |
| `showBulkSaveProgress` / `animateBulkProgress` | Berechnung und Animation des Fortschritts |

---

## 9. Hinweise und Besonderheiten

- **Zugangsdaten im Quelltext:** Das Datenbankpasswort steht im Klartext in der Datei. Es sollte in eine Konfiguration außerhalb des Web-Verzeichnisses verlagert werden.
- **Fehleranzeige:** `display_errors` ist aktiv. Fehlermeldungen können dadurch technische Details preisgeben.
- **Keine Authentifizierung und kein CSRF-Schutz:** Wer die Seite erreicht, kann Datensätze ändern.
- **Auswahl ohne Filter:** Ist keine Auswahl aktiv, werden alle Datensätze aller Mandanten geladen und angezeigt.
- **Keine Prüfung der Aktionscodes:** `saveRowActions()` speichert jeden übergebenen Wert, nicht nur A, I, D, N und `-`.
- **Keine Mandantenprüfung beim Speichern:** Die JSON-Schnittstelle aktualisiert jede übergebene `_id`, unabhängig von der aktiven Auswahl.
- **Rückgabewert `updatedCount`:** Er gibt die Zahl der übergebenen Einträge zurück, nicht die tatsächlich geänderten Zeilen.
- **Ausgabe im Detaildialog:** Werte aus `match_csvt`, `full_path` und `pp_action` werden per `innerHTML` ohne Escaping eingefügt. Das kann zu Darstellungsfehlern oder Script-Einschleusung führen.
- **Nach dem Speichern** wird auf die Seite ohne Query-String geleitet. Gesetzte Filter gehen dabei verloren, die Auswahl bleibt über die Session erhalten.
- **Spaltenüberschrift:** Die Spalte „Anzahl von match_csvt“ zeigt die Anzahl der Datensätze je Gruppe.
- **Ungenutzte Elemente:** Das versteckte Feld `row_id` im Sammelformular wird serverseitig nicht ausgewertet. Die Debug-Ausgabe (`$debugInfo`) ist auskommentiert.
