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>
3.0 KiB
3.0 KiB
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.
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 |