scripte/nexarch
1
0 Fork 0
Code Issues 1 Pull Requests 21 Actions 7 Packages Projects Releases Wiki Activity

DOC-04: Vorschau- & Thumbnail-Pipeline #12

Closed
patrick wants to merge 0 commits from feature/doc-04-vorschau-thumbnail-pipeline into main
pull from: feature/doc-04-vorschau-thumbnail-pipeline
merge into: scripte:main
Conversation 0 Commits - Files Changed -
patrick commented 2026-09-17 19:42:43 +02:00
Owner
Copy link
Copy source

Prüfungen

  1. Beschädigte PDF-Datei führt zu Fehlerstatus statt Absturz, blockiert andere Jobs nicht — TestHandler_CorruptedPDFResultsInFailedStatusNotCrash PASS
  2. Durchsatztest mit 500 Dokumenten — TestThroughput_500DocumentsAllProcessedSuccessfully PASS (500/500, ~15s)
  3. Cache-Invalidierung bei neuer Revision belegt — TestGetCurrentForDocument_ResolvesToCurrentRevisionAfterNewRevision PASS

Content-Type ausschließlich über Magic-Bytes (net/http.DetectContentType), PDF via pdftoppm, Bilder via abhängigkeitsfreiem Nearest-Neighbor-Resizer. Anbindung an DOC-01 (upload.Service.SetThumbnailEnqueuer) ohne bestehende Signatur zu brechen. Regressionsfrei: 13 bestehende upload-/jobqueue-Tests PASS.

Details siehe dms/docs/DOC-04-PRUEFPROTOKOLL.md.

## Prüfungen 1. Beschädigte PDF-Datei führt zu Fehlerstatus statt Absturz, blockiert andere Jobs nicht — TestHandler_CorruptedPDFResultsInFailedStatusNotCrash PASS 2. Durchsatztest mit 500 Dokumenten — TestThroughput_500DocumentsAllProcessedSuccessfully PASS (500/500, ~15s) 3. Cache-Invalidierung bei neuer Revision belegt — TestGetCurrentForDocument_ResolvesToCurrentRevisionAfterNewRevision PASS Content-Type ausschließlich über Magic-Bytes (net/http.DetectContentType), PDF via pdftoppm, Bilder via abhängigkeitsfreiem Nearest-Neighbor-Resizer. Anbindung an DOC-01 (upload.Service.SetThumbnailEnqueuer) ohne bestehende Signatur zu brechen. Regressionsfrei: 13 bestehende upload-/jobqueue-Tests PASS. Details siehe dms/docs/DOC-04-PRUEFPROTOKOLL.md.
patrick added 9 commits 2026-09-17 19:42:43 +02:00
FDN-01: repository & projektgerüst 08d54715d4 
DMS-Modul-Grundgerüst als Unterordner im bestehenden nexarch-Monorepo
(dms/), eigenes Go-Modul (gitea.perlbach24.de/scripte/nexarch/dms),
getrennt von Core. App/Worker-Trennung nach paperless-ngx-Vorbild (lange
Aufgaben blockieren nie eine Anfrage): cmd/app (HTTP, /healthz),
cmd/worker (Hintergrund-Dienst-Stub), internal/shared.

golangci-lint (govet/staticcheck/errcheck/unused/ineffassign/gofmt/
goimports) + Makefile-Targets (install/run/lint/fmt/test). Auf
192.168.1.131 verifiziert: build/fmt/lint/test clean, absichtlich
eingefuegter Lint-Verstoss bricht den Build wie gefordert ab (Exit 2),
make run startet App+Worker und /healthz antwortet innerhalb 2s.

Siehe dms/docs/FDN-01-PRUEFPROTOKOLL.md fuer alle Pruefungsergebnisse.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
FDN-02: datenmodell & migrationen 9d4c2bae4a 
Kern-Entitaeten (Dokument, Datei-Revision, Ordner, Tag, Metadatenfeld) als
tenant-scoped SQL-Migration (Modell C, keine tenant_id-Spalte), FK auf
users(id) aus Core IAM-01 (Auth bleibt vollstaendig in Core). Eigener,
minimaler Migrations-Runner (internal/migrate, kein ORM) mit
schema_migrations-Tracking fuer Idempotenz. Seed-Skript fuer Entwicklung.

Auf 192.168.1.131 verifiziert: Migration auf leerer+bestehender DB,
Rollback stellt Vorzustand wieder her, 4 FK-Negativtests, Seed-Skript
end-to-end gegen frische DB. go.sum committet (Lock-Datei-Lehre aus dem
Ticket). build/vet/lint/test clean.

Siehe dms/docs/FDN-02-PRUEFPROTOKOLL.md fuer alle Pruefungsergebnisse.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
FDN-03: objekt-storage-abstraktion 442bb674e9 
Ein Driver-Interface, zwei austauschbare Treiber: LocalDriver (Entwicklung,
Dateisystem, HMAC-signierte URLs) und S3Driver (Produktion, S3-kompatibel
via aws-sdk-go-v2, echte presigned URLs). Pfadschema documents/<id>/
revisions/<id> innerhalb des mandantenspezifischen Buckets. Service
verbindet Driver mit Nutzungsmeldung an Core LIC-05 (HTTPUsageReporter,
Vertrag von internal/resync.Handler nachgebildet, DMS kann Cores internal/-
Pakete als eigenes Modul nicht importieren).

Auf 192.168.1.131 verifiziert, S3-Treiber gegen echtes lokal installiertes
MinIO (kein Mock): Round-Trip beide Treiber, abgelaufene presigned URL real
mit 403 abgewiesen (manuell zusaetzlich zum Unit-Test verifiziert), klare
ErrNotFound bei fehlendem Objekt beide Treiber, Nutzungsmeldung mit
korrektem Tenant/Metrik/Delta bei Put/Delete.

Befund dokumentiert: Cores internal/resync.Handler (Gegenstelle fuer die
Nutzungsmeldung) ist noch in keinem cmd/*/main.go verdrahtet (dieselbe
Fehlerklasse wie QA-05/AUD-06) - HTTPUsageReporter daher gegen den
dokumentierten Vertrag getestet, nicht gegen eine laufende Core-Instanz.
Siehe dms/docs/FDN-03-PRUEFPROTOKOLL.md.

golangci-lint auf v2.1.6 aktualisiert (v1.63.4 konnte go1.24-Zielstand
nicht linten), .golangci.yml auf v2-Konfigurationsformat migriert.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
FDN-03: Protokoll ergaenzt - offener Punkt Pruefsummen-Schreibpfad a9ede93176 
checksum_sha256 (FDN-02) wird von keinem Schreibpfad in FDN-03 befuellt.
Nachgetragen als AC/Pruefung in DOC-01 (Upload-API), Voraussetzung fuer
Archive BAK-08 (neues Ticket: Checksum-basierte Objekt-Integritaetspruefung
fuer extern eingebundenes, nicht selbst ueberwachtes Kunden-S3-Storage).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
FDN-04: job-queue & worker-runtime bfea94b032 
Postgres-Jobqueue (processing_jobs, FOR UPDATE SKIP LOCKED), In-Prozess-
Worker-Goroutinen, kein Redis/AMQP. Enqueue mit Idempotency-Key-Dedup,
Dequeue mit Stale-Lock-Wiedervorlage (Absturzsicherheit), Fail mit
arithmetischem Backoff und Dead-Letter-Queue nach erschoepften Versuchen,
RequeueDeadLetter fuer manuelle Wiederholung.

Auf 192.168.1.131 verifiziert: Absturz-Wiedervorlage (Job von einem
"abgestuerzten" Worker nie completed/failed, zweiter Worker holt ihn nach
Ablauf der Sperre erneut), Idempotenz bei Doppelzustellung (gleicher
idempotency_key erzeugt nur 1 Zeile), DLQ-Eintrag manuell wiederholbar.

Vier reale Fehler beim Testen gefunden und behoben: zwei pgx-Typinferenz-
Bugs im SQL-Parameterhandling (toter workerID-Parameter ohne Referenz in
der Query; untypisiertes any statt []string fuer den ::text[]-Cast), sowie
zwei Testinfrastruktur-Bugs (dms_tenant_test sammelte schema_migrations-
Zustand ueber Sitzungen hinweg an, jobqueue-Testfixture raeumte
processing_jobs nicht auf) - neues scripts/reset-test-env.sh + make check
(-p 1) analog Core behoben.

Siehe dms/docs/FDN-04-PRUEFPROTOKOLL.md fuer alle Pruefungsergebnisse.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
FDN-09: verschluesselung at rest & schluesselverwaltung bf7559e118 
Envelope-Encryption: DEK (32 Byte) frisch je Objekt, AES-256-GCM fuer
Objektinhalt, DEK selbst mit Tenant-KEK verpackt (WrapDEK/UnwrapDEK). KEK
kommt ausschliesslich ueber HTTPKEKProvider von Core API-10
(internal/kek.Handler.TenantKEKHandler-Vertrag, Service-Credential-
authentifiziert), wird nie persistiert - jeder Seal/Open-Aufruf bezieht ihn
frisch. RewrapDEK fuer KEK-Rotation ohne Neuverschluesselung der Objekte
(nur der DEK-Wrapper wird neu verpackt, Chiffretext bleibt unveraendert).

Auf 192.168.1.131 verifiziert: Round-Trip Encrypt/Decrypt, manipulierter
Chiffretext UND falscher Schluessel werden beide ueber GCM-Auth-Tag
abgelehnt, KEK-Rotation real getestet (RewrapDEK, altes Objekt danach mit
neuem KEK weiterhin lesbar, alter KEK funktioniert nicht mehr).

Befund dokumentiert: Cores internal/kek.Handler (Gegenstelle fuer den
KEK-Bezug) ist noch in keinem cmd/*/main.go verdrahtet, dieselbe
Fehlerklasse wie FDN-03/QA-05/AUD-06. HTTPKEKProvider daher gegen den
dokumentierten Vertrag getestet, nicht gegen eine laufende Core-Instanz.
Siehe dms/docs/FDN-09-PRUEFPROTOKOLL.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
DOC-01: upload-api & chunk-handling 9a374dd91e 
Fortsetzbarer Server-seitiger Upload: upload_sessions (bytes_received,
GREATEST-Update verhindert Rueckschritt bei erneut zugestellten Chunks),
Staging via os.File.WriteAt (beliebige Chunk-Reihenfolge/-Wiederholung),
MIME-/Groessen-Validierung vor jedem Byte. Complete() liest Klartext einmal
via io.TeeReader fuer SHA-256 UND Verschluesselung gleichzeitig (Reihenfolge
Hash->verschluesseln->ablegen eingehalten), legt Dokument+Revision
transaktional an (neue Spalte file_revisions.wrapped_dek fuer FDN-09).

Auf 192.168.1.131 verifiziert: Resume nach simuliertem Abbruch bei 50%
liefert identische Endpruefsumme, 20 parallele Uploads ohne Kollision/
Datenverlust, Pruefsumme entspricht exakt dem Klartext, transaktionale
Dokument+Revision-Anlage bestaetigt.

Reale Skalierungs-Einschraenkung gefunden: echter 1-GiB-Durchlauf endete
mit OOM (4GB-RAM-Testhost ohne Swap, FDN-03/FDN-09 puffern vollstaendig im
Speicher statt zu streamen). Auf 300 MiB reduziert vollstaendig verifiziert
(Upload/Verschluesselung/Ablage/Checksumme/Entschluesselungs-Round-Trip
alles exakt) - Ressourcen-, keine Korrektheitsfrage, dokumentiert als
Folgeticket-Kandidat statt stillschweigend uebergangen.

Siehe dms/docs/DOC-01-PRUEFPROTOKOLL.md fuer alle Pruefungsergebnisse.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ
DOC-16: ret-05-client-aufbewahrungsklasse-registrieren-vernichtungs-rueckruf 9843275e9c 
- dms/internal/retentionclient: HTTP-Client fuer Archive RET-05/RET-09
- dms/internal/retentiondestroy: RegisterOrRequeue (FDN-04-Requeue bei
  Fehlschlag, kein Absturz/stilles Verwerfen), DestroyCallbackHandler
  (physische Loeschung aller Datei-Revisionen ueber storage.Service,
  markiert Dokument als vernichtet, 2xx erst danach)
- dms/cmd/app: mountet destroy-callback, registriert beim Start
- dms/cmd/worker: verarbeitet Requeue-Jobs (Retry)
- nur dms_document registriert (DOC-01/FDN-02 kennen keinen separaten
  Anhang-Typ, kein Umbau angrenzender Bereiche)
- real getestet: registrierung gegen echten fake-RET-05-Server, echte
  Loeschung inkl. Storage-Byte-Nachweis, echter Requeue-Eintrag bei
  Fehlschlag, erfolgreicher Retry
- live auf 131 gegen echten RET-09-Dienst (Port 8095) verifiziert,
  echter curl-Vernichtungs-Rueckruf mit real geloeschter Datei
- reale Core-API-06-Deploy-Luecke dokumentiert (nicht verschwiegen):
  /internal/resync/usage auf 131 aktuell nicht gemountet

Pruefungen siehe dms/docs/DOC-16-PRUEFPROTOKOLL.md
DOC-04: Vorschau- & Thumbnail-Pipeline 08584b0c5f 
internal/thumbnail: Vorschau-Zustand je Datei-Revision als explizite
State-Machine (pending/processing/ready/failed, revision_thumbnails)
statt Ableitung aus Dateiendung. Content-Type wird ausschliesslich ueber
Magic-Bytes bestimmt (net/http.DetectContentType gegen die entschluesselten
Bytes) - der in "Bekannte Fehler vermeiden" beschriebene Fehler eines
Vorgaengerprojekts (fragile Erkennung ueber Dateiendung) wird damit
vermieden.

PDF-Rasterung ueber pdftoppm (Poppler), Bild-Thumbnails ueber einen
minimalen, abhaengigkeitsfreien Nearest-Neighbor-Resizer auf Basis der
Standardbibliothek. Original wird ueber FDN-09 (dmscrypto) entschluesselt,
Thumbnail wird ebenfalls verschluesselt im Objekt-Storage abgelegt -
gleiches Schutzniveau wie das Original.

upload.Service bekommt SetThumbnailEnqueuer (neue, optionale Methode -
bestehende Aufrufer/Tests unveraendert funktionsfaehig) und reiht nach
erfolgreichem Complete() die Vorschau-Erzeugung ein; ein Fehlschlag dabei
laesst den bereits abgeschlossenen Upload nicht ruecktwirkend fehlschlagen.

Pruefungen:
1. Beschaedigte PDF-Datei -> Fehlerstatus statt Absturz, blockiert andere
   Jobs nicht (echter pdftoppm-Fehlschlag, echte SKIP-LOCKED-Job-Queue)
2. Durchsatztest: 500 echte PDFs, alle erfolgreich, ~15s Gesamtlaufzeit
3. Cache-Invalidierung bei neuer Revision: GetCurrentForDocument loest
   nachweislich auf die neue statt die alte Revision auf

Regressionsfrei: 13 bestehende upload-/jobqueue-Tests unveraendert PASS.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
patrick closed this pull request 2026-09-26 00:24:42 +02:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
patrick
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: scripte/nexarch#12