# ecoDMS → Paperless-ngx

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.