paperlessmanager/docs/superpowers/specs/2026-11-02-duplikat-neue-version-design.md

# Duplikat → neue Version (Design)

Stand: 02.11.2026

## Worum es geht

Wird ein Beleg ein zweites Mal mit derselben **internen Belegnummer** nach
Paperless gebracht, soll er nicht als zweites, eigenständiges Dokument landen.
Stattdessen sieht der Benutzer beide Belege nebeneinander und entscheidet:

- **Als neue Version hinzufügen** – die Datei wird über die Versionsfunktion
  von Paperless-NGX an das vorhandene Dokument gehängt.
- **Verwerfen** – der Beleg wird nicht importiert.

Typische Fälle:

1. **Korrigierte Rechnung**: Lieferant schickt eine fehlerbereinigte Fassung mit
   derselben Rechnungsnummer.
2. **Nachträglich geteilt**: Ein Dokument enthielt zwei Belege. Der Benutzer
   teilt das PDF **von Hand** und sendet es neu; der Teil mit der bereits
   vergebenen Belegnummer wird zur neuen Version.

## Ziele

- Gleicher Vergleichsdialog im **E-Mail-Import** und im **Posteingang (Scanner)**.
- Oben im Dialog eine Leiste mit **Auffälligkeiten**: abweichende
  **Seitenzahl** und abweichende **Wortzahl**. Darunter beide PDFs nebeneinander.
- Maßgeblich für „Belegnummer existiert schon“ ist **Paperless** (Custom Field 7
  = interne Belegnummer). Das ist die wichtige Prüfung.

## Nicht-Ziele

- Umbau der Task-Bearbeitung – läuft unverändert weiter.
- **Checksummen-Duplikate umgehen** (gleiche Datei erneut importieren) – bleibt
  wie heute, wird in `docs/todos.md` notiert.
- Inhaltliche Analyse (Beträge, Datum, Positionen) für die Auffälligkeiten –
  dafür gibt es noch keine Auswertung.
- Metadaten des vorhandenen Dokuments ändern (Titel, Tags, Custom Fields,
  Korrespondent bleiben unverändert; nur die Datei kommt als Version dazu).
- Nachgelagerte Automatik für die Version (Postprocessing-Regeln, Mail,
  WebDAV-Export, Agrarmonitor-Austausch/Storno) – wird vorerst **unterdrückt**,
  die fachliche Logik kommt später (siehe Todos).

## Anti-Ziele (wäre ein Fehlschlag, auch wenn es „funktioniert“)

- Ein Beleg mit vorhandener Belegnummer landet doch als zweites Dokument in
  Paperless, ohne dass der Benutzer es so entschieden hat.
- Eine Version wird an das **falsche** Dokument gehängt.
- „Verwerfen“ lässt eine reservierte Belegnummer oder einen halb angelegten
  Task zurück.

## Paperless-API (am Live-System geprüft, API v10)

- `POST /api/documents/{id}/update_version/` – multipart, Feld `document`
  (Datei, Pflicht), `version_label` (optional, max. 64 Zeichen). Antwort: String
  (vermutlich die Consume-Task-ID; Verarbeitung asynchron).
- `PATCH|DELETE /api/documents/{id}/versions/{version_id}/` – Label ändern/löschen.
- `DocumentVersionInfo`: `id`, `added`, `version_label`, `checksum`, `is_root`.

## Ablauf E-Mail-Import (`MailImportWizard.tsx`)

Schritte: 0 Zuordnung → 1 Bearbeitung → 2 Abschluss.

1. In Schritt 1 („Bearbeitung“) hat ein Beleg den Modus **Manuell** und eine
   Belegnummer (Jahr + 6-stellige Nummer → `JJJJ-NNNNNN`).
2. Beim Klick auf **Weiter** (Schritt 1 → 2) prüft das Backend für jeden
   manuellen Beleg in Paperless, ob die Belegnummer schon vergeben ist (CF7 und
   ASN, siehe „Eindeutigkeit des Treffers“).
3. Gibt es Treffer, öffnet sich **vor** dem Schrittwechsel der Vergleichsdialog
   – nacheinander für jeden betroffenen Beleg.
   - Links: vorhandenes Dokument aus Paperless. Rechts: der neue Beleg (bei
     geteilten Anhängen nur die gewählten Seiten).
   - **Als neue Version hinzufügen** → Beleg wird für den Import als
     „Version zu Dokument X“ markiert.
   - **Verwerfen** → Beleg wird auf `IGNORE` gestellt. Stehen danach alle Belege
     der Mail auf `IGNORE`, greift die bestehende Logik (Mail als ignoriert
     markieren).
   - Dialog schließen (X) ohne Entscheidung → kein Schrittwechsel, der Benutzer
     bleibt in Schritt 1.
4. Beim **Import ausführen** werden Version-Belege nicht per `post_document`
   hochgeladen, sondern per `update_version` an Dokument X gehängt.
   - Die ASN-Sperre (`validateAsnNotExists`) und der Belegnummer-Duplikatcheck
     entfallen für diese Belege – sonst würde der Import abbrechen.
   - Hochgeladen wird wie beim normalen Import das Original-PDF bzw. die
     gewählten Seiten, ohne eingebrannten Stempel.
   - Kein neuer Enrichment-Task in der `tasks`-Tabelle nötig (Metadaten bleiben).
   - Im `Attachment`-Datensatz wird die Dokument-ID X unter dem jeweiligen
     Bereich eingetragen, damit der Anhang als importiert gilt.
5. Die Checksummen-Prüfung (`recheckDuplicates`) bleibt unverändert.

## Ablauf Posteingang (`InboxDetailPage.tsx`, `inbox-postprocessor`)

Heute: `runPaperless` meldet ein Duplikat mit `duplicateOfDocumentId`; der
Wizard bietet „Neue Version erstellen“ (= Duplikatprüfung überspringen und als
zweites Dokument hochladen), „Vergleichen“ und „Überspringen“. Im
Vergleichsdialog ist „Neue Version anlegen“ noch ein TODO.

Neu:

- Liefert der Duplikat-Treffer eine Paperless-Dokument-ID, öffnet sich der
  Vergleichsdialog **automatisch**.
- **Als neue Version hinzufügen** → Backend verarbeitet den Abschnitt erneut,
  lädt die fertige PDF (nach allen Bearbeitungen/Stempeln) aber per
  `update_version` an Dokument X hoch statt per `post_document`. Danach ist der
  Abschnitt „erfolgreich“.
- **Verwerfen** → entspricht dem heutigen „Überspringen“ (Text wird umbenannt).
- Der bisherige Weg „Duplikatprüfung überspringen und als eigenes Dokument
  hochladen“ entfällt in der Oberfläche.
- Duplikate **ohne** Dokument-ID (Checksumme, lokaler Task ohne
  `PaperlessDocumentID`) behalten den heutigen Weg: nur Verwerfen/Überspringen.
- Rechts im Dialog wird der **betroffene Abschnitt** gezeigt, nicht das ganze
  Inbox-Dokument (heute zeigt der Dialog das ganze Dokument).

## Nachgelagerte Automatik unterdrücken

Entscheidung des Nutzers: Nach dem Hinzufügen einer Version bekommt das
(Stamm-)Dokument den Tag **„neue Version hochgeladen“ (ID 21)**. Der Nutzer
konfiguriert die Postprocessing-Regeln so, dass Belege mit Tag 21 ignoriert
werden. Im Code gibt es **keine** eigene Unterdrückung (keine Markierung, keine
Änderung an der Webhook-Warteschlange).

- Reihenfolge: **erst** Tag 21 setzen (Tags lesen, 21 ergänzen, vorhandene
  behalten), **dann** `update_version`. Schlägt der Versions-Upload fehl, wird
  Tag 21 wieder entfernt – aber nur, wenn er vorher nicht schon gesetzt war.
- Entfernen von Tag 21 ist Sache des Nutzers.
- Die Anreicherung in `processDocumentById` (Tag 17, bereit/nicht bereit,
  Titel-Template) läuft beim Webhook weiterhin – nur die Regeln greifen nicht.

Im **Posteingang** betrifft die Abfrage nur die Aktion „An Paperless senden“.
Die übrigen Aktionen des Barcode-Templates (MAIL, EXPORT) davor und danach
laufen normal: Die Aktionen davor sind beim Erkennen des Duplikats bereits
gelaufen und werden nicht wiederholt; die Aktionen danach werden nach der
Entscheidung (Version **oder** Verwerfen) ganz normal ausgeführt.

## Vergleichsdialog (gemeinsame Komponente)

- Eine Komponente für beide Stellen (aus `CompareModal` herauslösen).
- Titel z. B. „Belegnummer 2026-000123 existiert bereits“.
- **Auffälligkeiten-Leiste** oben (Ant Design `Alert`/`Tag`s):
  - Seitenzahl: „Seiten: 2 (vorhanden) → 3 (neu)“ – hervorgehoben bei Abweichung.
  - Wortzahl: „Wörter: 412 → 398“ – hervorgehoben bei Abweichung.
  - Ist eine Zahl nicht ermittelbar (z. B. PDF ohne Textebene), steht dort
    „nicht ermittelbar“ statt einer Abweichung.
  - Keine Abweichung → kurzer neutraler Hinweis „Seiten- und Wortzahl gleich“.
- Darunter beide PDFs nebeneinander (mobil untereinander), wie heute.
- Knöpfe: **Verwerfen** / **Als neue Version hinzufügen** (primär).

### Kennzahlen ermitteln (Backend-Endpunkt)

- Vorhanden (Paperless): Seitenzahl aus `page_count` des Dokuments, Wortzahl aus
  dessen `content` (OCR-Text von Paperless). Verglichen wird mit der aktuellen
  (neuesten) Fassung des Dokuments.
- Neu: Seitenzahl per `pdf-lib`, Wortzahl aus der Textebene per `pdf-parse`
  (beides bereits Abhängigkeiten im Backend). Keine Textebene → „nicht
  ermittelbar“.
- Wortzählung: Text an Leerraum trennen, nur Tokens mit mindestens einem
  Buchstaben oder einer Ziffer zählen.

## Versionsbezeichnung

`version_label` = „Korrektur vom TT.MM.JJJJ“ (Datum des Hinzufügens). Max. 64 Zeichen.

## Eindeutigkeit des Treffers

Geprüft wird immer gegen Paperless, und zwar über **beide** Merkmale, die aus
der internen Belegnummer folgen:

- CF7 = interne Belegnummer (z. B. `2026-000123`)
- ASN = interne Belegnummer ohne Bindestrich (z. B. `2026000123`) – auch im
  Posteingang, unabhängig von einem im Template separat hinterlegten ASN-Feld.

„Als neue Version hinzufügen“ wird nur angeboten, wenn alle Treffer auf **genau
ein** Dokument zeigen. Zeigen CF7- und ASN-Treffer auf verschiedene Dokumente
oder gibt es mehrere CF7-Treffer, zeigt der Dialog einen Hinweis und bietet nur
**Verwerfen** an. Dafür muss die Suche alle Treffer liefern, nicht nur den ersten.

## Am Live-System zu prüfen (vor/bei der Umsetzung)

- Antwort von `update_version` (Task-ID?) und wie der Abschluss erkennbar ist.
- Liefern CF7-Suche, `GET /documents/{id}/` (`content`, `page_count`) und
  `/download/` bei einem versionierten Dokument die Stamm-ID bzw. die neueste
  Fassung? `update_version` muss immer auf die Stamm-ID zielen.

## Todos-Einträge

In `docs/todos.md` ergänzen:

1. „Duplikatprüfung per Checksumme gezielt umgehen können, wenn ein bereits
   importiertes Dokument bewusst erneut importiert (z. B. geteilt) werden soll.“
2. „Neue Version eines Belegs in Agrarmonitor nachziehen (derzeit unterdrückt):
   - Beleg noch im AM-Posteingang → dort löschen und neue Fassung senden.
   - Beleg verarbeitet, aber nicht gebucht → im jeweiligen Einkauf das
     vorhandene Dokument löschen und die neue Fassung hochladen.
   - Beleg bereits gebucht → Storno-Beleg zum gebuchten Beleg erstellen und die
     neue Fassung über die jeweilige E-Mail-Adresse neu in den AM-Posteingang
     senden.
   Außerdem klären, ob Postprocessing-Regeln (Mail an Buchhaltung, Export) für
   Versionen laufen sollen.“
3. „Task-Bearbeitung (`PaperlessTaskProcessorService`, 30-s-Cron) auf den
   Paperless-Webhook umstellen. Beim Upload werden die Metadaten schon gesetzt;
   übrig bleiben Owner entfernen, Notizen, Anlage-Verknüpfung (Feld 8) und die
   lokale Buchführung (Task/Attachment/documents) – die brauchen die
   Dokument-ID nach dem Consume.“

## Dem Umsetzer überlassen

- Schnitt der Backend-Endpunkte (eigener Endpunkt für „Belegnummern prüfen“ und
  „Kennzahlen“, oder zusammengefasst).
- Wie das Ergebnis von `update_version` verfolgt wird (Task-Polling wie beim
  normalen Upload, sofern die Antwort eine Task-ID ist).
- Tests: mindestens Unit-Tests für Wortzählung/Auffälligkeiten und für die
  Entscheidung Upload vs. Version im Backend.

## Eigene Entscheidungen (nicht ausdrücklich vom Nutzer)

- Versionsbezeichnung „Korrektur vom …“.
- Version nur bei eindeutigem Treffer (CF7 und ASN zeigen auf dasselbe
  Dokument); sonst nur Verwerfen.
- E-Mail-Import: Version wird wie normale Importe ohne eingebrannten Stempel
  hochgeladen; keine erneute Barcode-Notiz (die hat das Stammdokument schon).

- Automatisches Öffnen des Dialogs im Posteingang; Wegfall von „als eigenes
  Dokument hochladen“.
- Dialog schließen ohne Entscheidung = im Schritt bleiben.
- Rechts nur der betroffene Abschnitt statt des ganzen Inbox-Dokuments.

## Ergebnisse Live-Prüfung (02.11.2026, nur lesend)

- `GET /api/documents/` liefert je Dokument `root_document` (bei Stammdokumenten
  `null`) und `versions` (Liste inkl. des Stamms selbst mit `is_root: true`).
  Normalisierung `root_document ?? id` ist damit tragfähig.
- Im System gibt es derzeit kein Dokument mit mehr als einer Version; ob
  Versionen in Listen-/Suchergebnissen als eigene Einträge auftauchen, ist
  daher offen – die Normalisierung deckt beide Fälle ab.
- Der schreibende Teil (Test-Upload einer Version, Antwortformat, Webhook)
  wird bei der Abnahme in Task 7 mit Freigabe des Nutzers nachgeholt.