# Feature: Nachvollziehbarkeit, Event Sourcing und Wiederaufnahme

Als Betreiber möchte ich jede Zustandsänderung eines Dokuments lückenlos nachvollziehen,
den Zustand aus den Ereignissen rekonstruieren und fehlgeschlagene Verarbeitung
gezielt wiederaufnehmen können.

```gherkin
Funktionalität: Event Sourcing und Audit-Trail

  Szenario: Jede Zustandsänderung ist als Event nachvollziehbar
    Angenommen ein vollständig verarbeitetes Dokument
    Wenn GET /v1/documents/{id}/events aufgerufen wird
    Dann enthält die Antwort die lückenlose Eventfolge von DocumentReceived bis DocumentFiled
    Und jedes Event enthält seq, event_type, payload und created_at

  Szenario: Der Zustand ist aus den Events rekonstruierbar
    Angenommen die aufgezeichnete Eventfolge eines Dokuments
    Wenn die Events per Replay gefaltet werden
    Dann entspricht das Ergebnis exakt der documents-Projektion

  Szenario: Konkurrierende Änderungen werden erkannt
    Angenommen zwei Schreiber mit derselben erwarteten Version eines Aggregats
    Wenn beide Events anhängen wollen
    Dann gelingt genau ein Append und der zweite erhält einen Konsistenzfehler

  Szenario: Events und Projektion sind transaktional konsistent
    Angenommen ein Append von Events schlägt in der Projektion fehl
    Wenn die Transaktion zurückgerollt wird
    Dann sind weder Events noch Projektionsänderung gespeichert

Funktionalität: Wiederaufnahme nach Fehlern

  Szenario: Neustart verliert keine Arbeit
    Angenommen ein Dokument war beim Absturz des Systems in Verarbeitung
    Wenn das System neu startet und der Claim-Lease abläuft
    Dann wird die Verarbeitung automatisch wiederaufgenommen

  Szenario: Wiederaufnahme setzt an der richtigen Stelle an
    Angenommen ein Dokument mit fehlgeschlagener OCR-Stage und Status "failed"
    Wenn POST /v1/documents/{id}/reprocess aufgerufen wird
    Dann wird ein Event "RetryRequested" aufgezeichnet
    Und die Verarbeitung setzt bei der OCR-Stage wieder an
    Und bereits abgeschlossene Stages laufen nicht erneut

  Szenario: Wiederaufnahme während laufender Verarbeitung wird abgelehnt
    Angenommen ein Dokument, das aktuell von einem Worker geclaimt ist
    Wenn POST /v1/documents/{id}/reprocess aufgerufen wird
    Dann antwortet das System mit 409
```

## Traceability

| Szenario | Go-Test (Pakete `internal/events`, `internal/pipeline`, `internal/api`) |
|---|---|
| Jede Zustandsänderung ist als Event nachvollziehbar | `TestGetEvents_ReturnsCompleteTrail` |
| Der Zustand ist aus den Events rekonstruierbar | `TestReplay_MatchesProjection` |
| Konkurrierende Änderungen werden erkannt | `TestAppend_ConcurrencyConflictReturnsError` |
| Events und Projektion sind transaktional konsistent | `TestAppend_RollbackLeavesNoPartialState` |
| Neustart verliert keine Arbeit | `TestQueue_ExpiredLeaseIsReclaimed` |
| Wiederaufnahme setzt an der richtigen Stelle an | `TestReprocess_ResumesFromFailedStage` |
| Wiederaufnahme während laufender Verarbeitung wird abgelehnt | `TestReprocess_ClaimedDocumentReturns409` |