chap 4: Konzeption; lookup trade-off table; longtable fix for runaway float loop

chapters/conception/s3-layout.tex

@@ -1,14 +1,59 @@
 \section{Ablagekonzept im S3-Speicher}
 \label{sec:s3-layout}
 
-% TODO: Ordnerbaum (Feature 484):
-%   Bucket → Kundenordner [meta: efecte_org-id] → Typordner/ → Dokumente
-% Typ = Unterordner, nicht Metadatum an der Datei
-% Leere Ordner werden nicht angezeigt
+Das Ablagekonzept bildet die Grundlage für alle weiteren Entwurfsentscheidungen. Es muss zwei Aufgaben gleichzeitig erfüllen: Es muss festlegen, welche Dokumente zu welchem Kunden gehören, und es muss den fachlichen Typ eines Dokuments abbilden. Beides geschieht ausschließlich über die Struktur im Speicher, ohne eine zusätzliche Datenbank.
 
-% \begin{figure}[H]
-%   \centering
-%   \includegraphics[width=0.75\textwidth]{figures/diagrams/s3-layout.pdf}
-%   \caption{S3-Ablagestruktur}
-%   \label{fig:s3-layout}
-% \end{figure}
+\subsection{Präfixe statt Ordner}
+
+S3 kennt technisch keine Ordner. Jedes Objekt wird über einen Schlüssel adressiert, der als Zeichenkette in einem flachen Namensraum liegt. Die scheinbare Hierarchie entsteht erst beim Auflisten: Übergibt man der Operation \texttt{ListObjectsV2} ein Präfix und ein Trennzeichen, liefert der Dienst nur die Objekte unterhalb dieses Präfixes zurück sowie die gemeinsamen Teilpräfixe der nächsten Ebene \autocite{aws-listobjectsv2}. Ein Schlüssel wie
+
+\begin{quote}
+\texttt{Beispielkunde GmbH/Service-Protokoll/Protokoll-2026-07.pdf}
+\end{quote}
+
+wird in einem Dateibrowser wie Filestash als zweistufige Ordnerhierarchie dargestellt, ist im Speicher jedoch nur eine einzelne Zeichenkette. Diese Eigenschaft ist für das Konzept vorteilhaft, weil sie das Auflisten eines Kundenordners auf eine einzige Präfixabfrage reduziert. Sie hat aber auch eine Konsequenz, die im weiteren Verlauf noch bedeutsam wird: Ein „Ordner" existiert erst dann, wenn mindestens ein Objekt mit dem entsprechenden Präfix vorhanden ist. Ein leerer Ordner lässt sich nur simulieren, indem ein Platzhalterobjekt angelegt wird, dessen Schlüssel auf das Trennzeichen endet.
+
+Abbildung~\ref{fig:s3-layout} zeigt die resultierende Struktur.
+
+\begin{figure}[H]
+    \centering
+    \includegraphics[width=0.85\textwidth]{figures/diagrams/s3-layout.pdf}
+    \caption{Ablagestruktur im S3-Speicher}
+    \label{fig:s3-layout}
+\end{figure}
+
+\subsection{Kundenzuordnung über ein Marker-Objekt}
+
+Auf der obersten Ebene des Buckets liegt für jeden Kunden genau ein Ordner. Um diesen Ordner einer Organisation zuzuordnen, wird an dem Platzhalterobjekt, das den Ordner repräsentiert, ein benutzerdefiniertes Metadatum \texttt{efecte-org-id} hinterlegt. Dieses Objekt wird im Folgenden als \emph{Marker} bezeichnet.
+
+Der Marker erfüllt zwei Zwecke gleichzeitig. Erstens sorgt er dafür, dass der Kundenordner auch dann existiert, wenn noch kein einziges Dokument abgelegt wurde — andernfalls wäre ein frisch angelegter Kunde im Speicher unsichtbar. Zweitens trägt er die Information, welcher Organisation der Ordner gehört. Damit ist die Zuordnung an genau einer Stelle hinterlegt und muss nicht an jedem einzelnen Dokument wiederholt werden.
+
+Die Entscheidung, die Organisations-ID als Metadatum und nicht als Bestandteil des Ordnernamens zu führen, wurde in der Feature-Analyse getroffen (siehe Abschnitt~\ref{sec:feature-analysis}). Sie ist fachlich motiviert: Die Ordner werden von den Kundenbetreuern über Filestash gepflegt, und ein Ordnername wie \texttt{42} oder \texttt{Beispielkunde GmbH (42)} wäre dort schwer zu handhaben. Der lesbare Firmenname bleibt daher der Ordnername, die technische Zuordnung wandert in die Metadaten.
+
+Genau diese Entscheidung erzeugt allerdings das zentrale technische Problem des Projekts, das in Abschnitt~\ref{sec:lookup-research} behandelt wird: Houston kennt aus dem Authentifizierungstoken die Organisations-ID, muss daraus aber den Ordnernamen ermitteln — und S3 bietet keine Möglichkeit, Objekte nach Metadaten zu durchsuchen.
+
+\subsection{Typisierung über Unterordner}
+
+Innerhalb des Kundenordners liegt für jeden der sieben fachlichen Dokumententypen ein Unterordner. Der Typ eines Dokuments ergibt sich daraus, in welchem Unterordner es abgelegt ist. Dokumente, die direkt im Kundenordner liegen, gelten als untypisiert.
+
+Auch diese Festlegung stammt aus der Feature-Analyse. Die Alternative wäre gewesen, den Typ als Metadatum an jeder einzelnen Datei zu hinterlegen. Der Vergleich beider Ansätze fällt eindeutig aus:
+
+\begin{itemize}
+    \item \textbf{Pflegeaufwand:} Ein Metadatum müsste bei jedem Upload manuell gesetzt werden. Filestash bietet hierfür keine komfortable Unterstützung. Das Ablegen in einem Ordner ist dagegen die natürliche Bedienhandlung.
+    \item \textbf{Abfragbarkeit:} Der Typ ist als Präfixbestandteil unmittelbar aus dem Schlüssel ablesbar. Beim Auflisten fällt er ohne Zusatzkosten mit an. Ein Metadatum müsste dagegen für jedes Objekt einzeln abgerufen werden, da \texttt{ListObjectsV2} benutzerdefinierte Metadaten nicht mitliefert. Bei $n$ Dokumenten wären das $n$ zusätzliche Aufrufe.
+    \item \textbf{Filterung:} Eine Filterung nach Typ reduziert sich auf eine Präfixabfrage und ist damit serverseitig umsetzbar.
+\end{itemize}
+
+Dem stehen zwei Nachteile gegenüber. Zum einen kann ein Dokument nur genau einen Typ haben, da es nur an einer Stelle liegen kann; eine Mehrfachzuordnung ist ausgeschlossen. Zum anderen erfordert die Typisierung, dass die Ordner überhaupt existieren — was die automatische Anlage der Ordnerstruktur zu einer eigenen Anforderung macht (FA-13). Beide Einschränkungen wurden bewusst in Kauf genommen.
+
+\subsection{Sichtbarkeitsregeln}
+
+Für die Darstellung gelten drei Regeln, die sich aus der Feature-Beschreibung ergeben:
+
+\begin{enumerate}
+    \item \textbf{Ordner werden nicht als Einträge angezeigt.} Die Liste zeigt ausschließlich Dokumente; die Ordnerstruktur wird über Typ-Icons und Filter abgebildet, nicht über eine navigierbare Hierarchie. Der Benutzer sieht also eine flache Liste aller seiner Dokumente.
+    \item \textbf{Leere Typordner erscheinen nicht.} Ein Kunde, für den noch keine Monitoring-Reports abgelegt wurden, sieht diesen Typ nicht als leere Kategorie.
+    \item \textbf{Ordner ohne gültiges Marker-Metadatum werden ignoriert.} Legt jemand versehentlich einen Ordner auf oberster Ebene an, ohne eine Organisations-ID zu hinterlegen, bleibt dieser für alle Kunden unsichtbar. Der Fall wird protokolliert, führt aber nicht zu einem Fehler und niemals zu einem Zugriff.
+\end{enumerate}
+
+Die dritte Regel ist eine Sicherheitsmaßnahme: Sie stellt sicher, dass ein Ordner nur dann für einen Kunden sichtbar wird, wenn seine Zugehörigkeit ausdrücklich hinterlegt ist. Ein fehlendes Metadatum führt zum Ausschluss, nicht zu einer Vermutung.