Dokumente und Anhänge

Zweck

In SpeamCore ist jedes hochgeladene Dokument ein Document-Datensatz, dessen Datei in MinIO (S3-kompatibel) liegt. Dokumente werden über das polymorphe Modell DocumentParent an Domain-Entitaeten gehaengt — ein Dokument kann gleichzeitig an mehreren Parents haengen.

Die Sicht-Routen sind:

• Document-Center — globale Browse-Sicht über alle Dokumente.
• Documents Detail — pro Dokument: Tabs Stammdaten, ZIP-Inhalte, Versionen, Aktivitäten, Public-Links, Parents.

Diese Grundlage erklaert das Persistenz- und Verknuepfungs-Modell, damit du in jeder Modul-Doku nicht jedes Detail wiederholen musst.

Modell-Aufbau

Document (Datei + Metadaten)

Feld	Bedeutung
documentType	Klassifizierung (image, signature, scorm, pdf, csv, ...)
fileName, bucketName	MinIO-Lokation
originalFileName	Name beim Upload
thumbnailFileName, mediumFileName, largeFileName, xlargeFileName	Auto-erzeugte Bild-Varianten
etag, fileHash, fileSize	Integritaets- und Größen-Daten
currentVersion, versionCount	Versions-Tracking
isPublic, publicAccessKey, publicExpiresAt	Public-Link-Konfiguration
sharedByEmployeeId	wer das Dokument freigegeben hat
contentAnalyzed	wurde der Inhalt automatisch analysiert (OCR/AI)
parentId, parentType	optionaler Direkt-Parent (selten, meist via DocumentParent)

DocumentParent (polymorphe Verknuepfung)

DocumentParent {
  documentId: UUID
  parentId:   UUID
  parentType: string  // z.B. "Customer", "SalesDocument", "Workorder", "Mail", "Expense"
  title?:     string  // optional Anzeigename am Parent
  description?: string
}

Mehrfach-Verknuepfung: Ein Dokument kann an N Entitaeten gleichzeitig haengen. Beispiel: eine Vertrags-PDF haengt an Customer + SalesDocument + Project.

DocumentVersion

Jede neue Datei-Version legt einen DocumentVersion-Eintrag an. currentVersion zeigt auf die aktive. Frueheres Wiederherstellen über /documents/:id/versions.

DocumentActivity

Audit-Log pro Dokument: öffnen, herunterladen, ändern, public-Link erzeugen.

DocumentPublicLink

Anonymer Download-Link mit Token (publicAccessKey) und optionalem Ablaufdatum (publicExpiresAt).

Pattern in Modul-Doku

Wenn ein Modul „Dokumente" als Sub-Liste hat (z. B. /customers/:id/documents, /expenses/:id/documents, /employees/:id/documents), gilt:

1. DataGrid mit DocumentParent-Einträgen, gefiltert auf parentType = aktuelles Modell und parentId = aktueller Datensatz.
2. Upload-Button — legt Document + DocumentParent in einem Zug an.
3. Klick auf Zeile → Drilldown auf /documents/:id.

Felder am Anhang-Punkt (typisch)

Die folgenden Felder sind in den meisten Modul-Listen sichtbar:

Feld	Quelle	Bedeutung
originalFileName	Document	Datei-Name.
documentType	Document	Klassifizierung.
title	DocumentParent	Optionaler Anzeige-Titel am Parent.
uploadedAt	Document	Upload-Zeitpunkt.
fileSize	Document	Datei-Größe.
version	Document	aktuelle Version.
sharedByEmployee	Document	wer hat geteilt.

Berechtigungen

Action	Subject	Wirkung	Keycloak-Rolle
view	Document	Liste/Detail aufrufbar	APP_SPEAMCORE_VIEW_DOCUMENT
create	Document	Upload	APP_SPEAMCORE_CREATE_DOCUMENT
update	Document	Metadaten/Version ändern	APP_SPEAMCORE_UPDATE_DOCUMENT
delete	Document	Soft-Delete	APP_SPEAMCORE_DELETE_DOCUMENT
view/create/delete	DocumentParent	Verknuepfung pflegen	APP_SPEAMCORE_VIEW/CREATE/DELETE_DOCUMENT_PARENT
view/create	DocumentPublicLink	Public-Link verwalten	APP_SPEAMCORE_VIEW/CREATE_DOCUMENT_PUBLIC_LINK
view	DocumentActivity	Audit-Log	APP_SPEAMCORE_VIEW_DOCUMENT_ACTIVITY

Wiederverwendbare Konzepte

• Polymorpher Parent-Pattern — DocumentParent ist das prominenteste Beispiel.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

Praktisch jedes Modul, das eine documents-Sub-Route hat, baut auf diesem Pattern auf:

• Document-Center — globale Browse-Sicht.
• Documents Detail — pro Datei alle Versions/Activity/Parents.
• Mail — Anhänge sind Documents.
• Sales-/Purchase-Documents — Beleg-Anhänge.
• Mitarbeiter — Personalakte als Documents.
• Vehicles — Verträge, KFZ-Brief, Protokolle.
• Course-Certificates — Logo, Unterschrift, Zertifizierung als Documents.

Versionshinweise

• 2026-04-30: Initiale Veroeffentlichung als Querschnitts-Grundlage.