Initial commit

README.md

@@ -1,3 +1,152 @@
-# migrate-ecodms-to-paperless
+# ecoDMS → Paperless-ngx
 
-Migration eines ecoDMS-Datenbestandes in einen Datenbestand, der mit Paperless-NGX fortgeführt werden kann.
+Werkzeuge und Anleitung für die Migration eines ecoDMS-Archivs nach
+Paperless-ngx — mit Versionsketten, Berechtigungen, Klassifizierung und
+Notizen.
+
+Erprobt an einem Bestand von rund 11.000 Dokumenten mit 12.000 Versionen,
+gewachsen über zwölf Jahre.
+
+---
+
+## Was übernommen wird
+
+| ecoDMS | Paperless-ngx |
+|---|---|
+| Dokument | Dokument |
+| Dateiversionen | Versionskette (`versions`, ab Paperless 3.0) |
+| Ordnerhierarchie | Tags, je Ebene einer |
+| Dokumentart | Dokumenttyp |
+| Status | Tag `Status: …` |
+| Bemerkung | Titel |
+| `cdate` | Erstellungsdatum |
+| Versions-Zeitstempel | `added` je Version (per Nachbearbeitung) |
+| Dokument-ID | Archiv-Seriennummer + Zusatzfeld |
+| Dynamische Attribute | Zusatzfelder (Custom Fields) |
+| Wiedervorlage (`defdate`) | Zusatzfeld |
+| Rollenrechte | Eigentümer + Objektberechtigungen |
+| Notizen (`econotice`) | Notizen |
+
+## Was nicht übernommen wird
+
+| Element | Grund |
+|---|---|
+| Klassifizierungshistorie | Paperless kennt keine Metadaten-Historie |
+| Verknüpfungen zwischen Dokumenten | im Export nicht enthalten |
+| Nicht unterstützte Dateitypen | `.html`, `.zip`, `.indd` und andere |
+| E-Mail-Anhänge als eigene Dokumente | Paperless belässt sie in der `.eml` |
+
+Für die letzten drei Punkte erzeugen die Werkzeuge Listen zur Nacharbeit.
+
+---
+
+## Aufbau
+
+Die Migration läuft in zwei getrennten Stufen. Die Trennung ist Absicht:
+Stufe 1 ist offline, beliebig wiederholbar und ihr Ergebnis lässt sich
+ansehen, bevor irgendetwas geschrieben wird.
+
+```
+ecoDMS-Export ──▶ ecodms_extract.py ──▶ Manifest (JSON) ──▶ paperless_import.py ──▶ Paperless
+   (Tranche)          Stufe 1              + Prüfbericht         Stufe 2            (REST-API)
+                                           + Ausschlussliste
+                                                                        │
+                                                                        ▼
+                                                              migration.sqlite
+                                                                  (Journal)
+```
+
+Das **Journal** ist der Kern. Es hält je Dokument fest, was importiert
+wurde und was nicht. Dadurch ist der Import wiederaufsetzbar, Tranchen
+dürfen sich überschneiden, und die Zuordnung bleibt tranchenübergreifend
+auswertbar.
+
+---
+
+## Dateien
+
+| Datei | Zweck |
+|---|---|
+| `ecodms_extract.py` | Stufe 1: Export → Manifest |
+| `paperless_import.py` | Stufe 2: Manifest → Paperless |
+| `ecodms_notizen.py` | Notizen aus `econotice` übertragen |
+| `docker-compose.yml` | Paperless-Instanz für die Migration |
+| `Dockerfile` | optional: Image mit E-Rechnungs-Parser |
+| `.env.example` | Konfigurationsvorlage |
+| `rollen.yml.example` | Übersetzung der ecoDMS-Rollen |
+
+## Anleitung
+
+1. [Paperless-Instanz vorbereiten](docs/01-paperless-vorbereiten.md)
+2. [Export aus ecoDMS](docs/02-export-aus-ecodms.md)
+3. [Extraktion und Prüfung](docs/03-extraktion.md)
+4. [Import](docs/04-import.md)
+5. [Nacharbeit](docs/05-nacharbeit.md)
+
+Dazu als Nachschlagewerk: [Das ecoDMS-Exportformat](docs/referenz-ecodms-exportformat.md)
+— die Eigenheiten des Formats, die während der Migration aufgedeckt wurden.
+Wer nur eine Sache liest, sollte es diese sein.
+
+---
+
+## Voraussetzungen
+
+- Paperless-ngx **3.0 oder neuer** (Versionierung)
+- ecoDMS mit Datenexport-Funktion (im Lizenzumfang, keine API nötig)
+- Python 3.11+ mit `requests` und `PyYAML`
+- Speicherplatz: etwa das Doppelte des ecoDMS-Bestands
+
+---
+
+## Schnelleinstieg
+
+```bash
+# 1. Instanz starten (siehe docs/01)
+docker compose up -d
+
+# 2. Je Tranche extrahieren
+python3 ecodms_extract.py /pfad/export1/archive -t export1 \
+        -o export1.json --skipped-csv export1-nacharbeit.csv
+
+# 3. Prüfbericht lesen. Ernsthaft.
+
+# 4. Stammdaten anlegen, dann probeweise zwei Dokumente
+export PT=dein_api_token
+python3 paperless_import.py export1.json --setup
+python3 paperless_import.py export1.json --limit 2 --stop-on-error
+
+# 5. Volle Tranche, danach prüfen
+python3 paperless_import.py export1.json
+python3 paperless_import.py --verify
+
+# 6. Nach ALLEN Tranchen
+python3 paperless_import.py --emit-timestamps > fix_added.py
+docker compose exec -T webserver python manage.py shell < fix_added.py
+python3 ecodms_notizen.py --dry-run --csv notizen.csv
+```
+
+---
+
+## Lizenz
+
+MIT, siehe [LICENSE](LICENSE). Vor einer Veröffentlichung den
+Rechteinhaber eintragen.
+
+## Haftung
+
+Die Werkzeuge lesen aus ecoDMS ausschließlich, schreiben aber in Paperless.
+**Vor jedem Lauf ein Backup oder einen Dateisystem-Snapshot anlegen.**
+
+Sie wurden an einem gewachsenen Bestand erprobt, nicht formal getestet. Die
+MIT-Lizenz schließt jede Gewährleistung aus — das ist hier nicht nur
+Formsache: Eine Migration verändert einen Dokumentenbestand, und die
+Eigenheiten des Exportformats sind nicht dokumentiert, sondern durch
+Beobachtung erschlossen. Ein anderer Bestand kann Fälle enthalten, die hier
+nie aufgetreten sind.
+
+Deshalb der Ablauf in [docs/03-extraktion.md](docs/03-extraktion.md): erst
+extrahieren, **Prüfbericht lesen**, dann zwei Dokumente probeweise
+importieren, dann die volle Tranche.
+
+Jede Anwendung dieses Skript- und Softwarepakets erfolgt auf eigene Gefahr
+und ohne jegliche Gewähr. Jede Haftung wird ausgeschlossen.