Christoph Kroczek
6e6cb0dc8d
- doc/architecture.md: arc42-Detaildokument mit Mermaid-Diagrammen (Bausteinsicht, Klassendiagramm, Statusmodell, 5 Sequenzdiagramme), Speicherkonzept, DEC-01..19-Entscheidungen mit Trade-offs - doc/requirements/: 7 Features als Gherkin-Szenarien (TDD-Grundlage) mit Traceability-Tabellen Szenario <-> Stdlib-Testname - doc/openapi.yaml: API-Vertrag fuer alle 9 Endpunkte (Quelle der Wahrheit) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
# 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` |
|