tryton-db-migration/doc/UPDATEANALYSE.md

# Tryton DB-Migrationsanalyse (AST-Zweig)

Analysiert per statischem Code-Scan, welche Datenbank-Operationen die
`__register__`-Methoden aller Tryton-Module über mehrere Versionen hinweg
ausführen – ohne die Module tatsächlich zu installieren/upzudaten.

## Workflow

```bash
./run.sh
```

Checkt der Reihe nach jeden Versions-Branch (`5.0` bis `8.0`) im
Tryton-Repo aus, lässt `extract_updates.py` pro Version über alle konfigurierten
Module laufen (Ergebnis: `data/<version>/<modul>.json`), und ruft danach
`compare_updates.py` auf, das daraus die aggregierten Reports in `reports/updateChanges/*.md`
erzeugt (ein Report pro Modul, gegliedert nach Tabelle und Version).

Einzeln aufrufbar:
```bash
python3 extract_updates.py --repo <pfad-zum-tryton-clone> --output data
python3 compare_updates.py
```

## Was `extract_updates.py` erkennt

- Erkannte DB-Operationen (`column_rename`, `add_column`, `update`,
  `insert`, `execute`, ... – siehe `INTERESTING_OPS`) inkl. Tabelle(n),
  Zeile, Bedingung (`if`-Kontext), Phase (`before_super`/`after_super`).
- Steigt in `for`/`while`/`with`/`try` ab (nicht nur `if`).
- Löst Aufrufe an Helper-Methoden derselben Klasse auf
  (`cls._migrate_x(...)`) und markiert die gefundenen Operationen mit
  `"via": [{"method": ..., "line": ...}]`.
- Loggt alle sonstigen, nicht erkannten Aufrufe zusätzlich als
  `"unresolved": true` – Rohmaterial für die manuelle Sichtung, gefiltert
  um bekanntes Rauschen (`Pool()`, `Transaction()`, `cursor`, `.append`,
  `pool.get`, `logger.*`, `__table__`/`__table_handler__`).

## Was `extract_updates.py` NICHT erkennt (bewusste Grenzen)

- **Cross-Datei-Aufrufe**: Ruft `__register__` eine Funktion aus einem
  anderen Modul/Utility-Modul auf (z. B. `migrate_property(...)` aus
  `trytond.model.modelstorage`), wird das nicht verfolgt – landet als
  `unresolved`, der eigentliche DB-Zugriff bleibt unsichtbar.
- **XML-Datendateien** (`ir.model.data`) – bewusst ausgeklammert, da
  Konfigurationsdaten ohnehin manuell geprüft werden müssen.
- **`.sql`-Dateien** in Modulen – werden nicht gescannt.
- **Implizite Schema-Änderungen** durch reine Feldtyp-Änderungen im
  Python-Code (ohne expliziten `add_column`/`alter_size`-Aufruf).

## `compare_updates.py` – Aggregation & Dedup

Fasst pro Tabelle die Operationen aller Versionen zusammen und zeigt eine
Operation nur dann erneut an, wenn sie sich vom **tatsächlichen,
vollständigen Bestand der unmittelbar vorherigen Version** unterscheidet
(nicht: irgendwann schon mal gesehen). Das behandelt korrekt sowohl den
Normalfall (Migrationscode bleibt über viele Versionen unverändert – wird
nur einmal angezeigt) als auch den Fall, dass ein Block zwischenzeitlich
durch etwas anderes ersetzt und später identisch wieder eingeführt wird
(taucht dann korrekt erneut auf).

Zeigt keine "wurde entfernt"-Markierung – nur Neues/Verändertes.

## Konfiguration

- Modul-/Repo-Defaults: oben in `extract_updates.py` (`DEFAULT_REPO`,
  `DEFAULT_MODULES`).
- Versions-Range: `START`/`END` in `run.sh`.
- Rauschfilter für `unresolved`: `IGNORED_UNRESOLVED_*` in `extract_updates.py` –
  bei Bedarf erweitern, wenn sich beim Sichten neue, eindeutig irrelevante
  Muster zeigen (siehe Git-Historie für die bisherige Herleitung).

## Verwandter Zweig

Ergänzender, unabhängiger Ansatz: Proteus-basierter Vergleich (echte
Testdaten in zwei frisch installierten Versionen anlegen, Fehler/
Reformatierung erkennen) – siehe [doc/TESTDATEN.md](TESTDATEN.md) und
[doc/MODELLVERGLEICH.md](MODELLVERGLEICH.md).