chapters: Fliesstext auf 57 reine Textseiten kuerzen

Zwei Kompressionsdurchgaenge ueber Kapitel 2-7. Entfernt wurden
Redundanzen, Meta-Kommentare, Ueberklaerungen und Fuellsaetze;
Fakten, Namen, Daten, Entscheidungen samt Begruendung sowie alle
Abbildungen und Tabellen bleiben unveraendert.

Reine Textseiten: 78 -> 57 (Woerter 19613 -> 12451).
Gesamt-PDF: 138 -> 116 Seiten.

chapters/conception/authorization.tex

@@ -1,38 +1,38 @@
 \section{Autorisierungskonzept}
 \label{sec:authorization}
 
-Der Dokumentenbereich verarbeitet Vertragsunterlagen, Abrechnungsdaten und Security Assessments. Ein fehlerhafter Zugriff hätte damit unmittelbar die Offenlegung vertraulicher Kundendaten zur Folge. Das Autorisierungskonzept arbeitet deshalb zweistufig: Eine Rollenprüfung entscheidet, \emph{ob} ein Benutzer den Bereich überhaupt betreten darf, und eine Mandantenprüfung entscheidet, \emph{welche} Dokumente er darin sieht.
+Der Dokumentenbereich verarbeitet Vertragsunterlagen, Abrechnungsdaten und Security Assessments. Das Autorisierungskonzept arbeitet zweistufig: Eine Rollenprüfung entscheidet, \emph{ob} ein Benutzer den Bereich betreten darf, eine Mandantenprüfung, \emph{welche} Dokumente er sieht.
 
 \subsection{Authentifizierung und Claims}
 
-Die Authentifizierung erfolgt wie in der übrigen Houston-Anwendung über Microsoft Entra~ID. Nach erfolgreicher Anmeldung erhält Houston ein Token, das neben der Identität des Benutzers zwei für dieses Projekt wesentliche Angaben enthält:
+Die Authentifizierung erfolgt über Microsoft Entra~ID. Das Token enthält zwei für dieses Projekt wesentliche Angaben:
 
 \begin{itemize}
     \item die \textbf{Efecte-Organisations-ID} des Benutzers, über die seine Zugehörigkeit zu einem Kunden bestimmt wird,
     \item den \textbf{Efecte-Firmennamen}, der über den Claim \texttt{efecte:company\_name} bereitgestellt wird.
 \end{itemize}
 
-Beide Werte lagen bereits vor Projektbeginn im Token vor und mussten nicht neu eingeführt werden. Dass der Firmenname verfügbar ist, wurde erst im Rahmen der Recherche zum Kundenordner-Lookup als relevant erkannt — er ermöglicht es, den Ordnernamen ohne zusätzlichen Efecte-Aufruf zu bestimmen (siehe Abschnitt~\ref{sec:lookup-decision}).
+Beide Werte lagen bereits vor Projektbeginn im Token vor. Dass der Firmenname verfügbar ist, wurde erst bei der Recherche zum Kundenordner-Lookup erkannt — er ermöglicht die Bestimmung des Ordnernamens ohne zusätzlichen Efecte-Aufruf (siehe Abschnitt~\ref{sec:lookup-decision}).
 
 \subsection{Anwendungsrolle Documents.Read}
 
-Für den Zugriff auf den Dokumentenbereich wurde in Entra~ID die Anwendungsrolle \texttt{Documents.Read} angelegt. In der Feature-Analyse war ausdrücklich geklärt worden, dass keine feingranulareren Berechtigungen unterhalb der Menüpunkt-Ebene erforderlich sind: Ein Benutzer sieht entweder alle Dokumente seiner Organisation oder gar keine. Eine Differenzierung nach Dokumententyp — etwa ein Zugriff auf Monitoring-Reports ohne Zugriff auf Vertragsunterlagen — wurde bewusst nicht vorgesehen.
+Für den Zugriff auf den Dokumentenbereich wurde in Entra~ID die Anwendungsrolle \texttt{Documents.Read} angelegt. Eine Differenzierung nach Dokumententyp ist nicht vorgesehen: Ein Benutzer sieht entweder alle Dokumente seiner Organisation oder gar keine.
 
-Die Rolle wirkt an zwei Stellen. Erstens steuert sie die Sichtbarkeit des Navigationspunkts: Ohne die Rolle erscheint „Dokumente" nicht im Menü. Zweitens schützt sie die Seite selbst gegen den direkten Aufruf über die URL. Die zweite Prüfung ist die eigentlich sicherheitsrelevante; das Ausblenden des Menüpunkts ist reine Benutzerführung und darf nicht als Schutzmaßnahme betrachtet werden.
+Die Rolle wirkt an zwei Stellen: Sie steuert die Sichtbarkeit des Navigationspunkts und schützt die Seite gegen direkten URL-Aufruf. Die zweite Prüfung ist sicherheitsrelevant; das Ausblenden des Menüpunkts ist reine Benutzerführung.
 
 \subsection{403 statt 404}
 
-Ein diskutierter Punkt war die Frage, welche Antwort ein Benutzer ohne Berechtigung beim direkten Aufruf von \texttt{/documents} erhalten soll. Die ursprüngliche Fassung der Anforderung sah eine 404-Antwort vor. Die Überlegung dahinter ist verbreitet: Eine 404-Antwort verrät nicht, dass die Ressource überhaupt existiert, und verhindert damit Rückschlüsse auf vorhandene Funktionen.
+Ein diskutierter Punkt war die Antwort bei unberechtigtem Zugriff auf \texttt{/documents}. Die ursprüngliche Anforderung sah 404 vor, um die Existenz der Ressource zu verbergen.
 
-Im Verlauf der Umsetzung wurde die Anforderung auf eine 403-Antwort geändert. Ausschlaggebend waren zwei Argumente. Zum einen ist die Existenz des Dokumentenbereichs kein Geheimnis — es handelt sich um eine allgemein bekannte Funktion des Kundenportals, nicht um eine verborgene Ressource. Der Informationsgewinn eines Angreifers ist damit gleich null. Zum anderen erschwert eine 404-Antwort die Fehlersuche erheblich: Ein Benutzer, dem versehentlich die Rolle fehlt, erhält dieselbe Antwort wie bei einem Tippfehler in der Adresse. Genau dieser Fall trat später im Abnahmetest tatsächlich ein (siehe Abschnitt~\ref{sec:acceptance-testing}) und bestätigte die Entscheidung.
+Die Anforderung wurde auf 403 geändert. Die Existenz des Dokumentenbereichs ist kein Geheimnis. Zudem erschwert 404 die Fehlersuche: Ein Benutzer ohne Rolle erhält dieselbe Antwort wie bei einem Tippfehler. Dieser Fall trat später im Abnahmetest ein (siehe Abschnitt~\ref{sec:acceptance-testing}) und bestätigte die Entscheidung.
 
-Der Trade-off lautet also: minimaler, hier praktisch nicht vorhandener Informationsgewinn für einen Angreifer gegen deutlich bessere Diagnostizierbarkeit im Betrieb. Die Entscheidung fiel zugunsten der Diagnostizierbarkeit.
+Der Trade-off: minimaler Informationsgewinn für einen Angreifer gegen deutlich bessere Diagnostizierbarkeit.
 
 \subsection{Mandantentrennung}
 
-Die zweite Stufe stellt sicher, dass ein berechtigter Benutzer ausschließlich die Dokumente seiner eigenen Organisation sieht. Sie beruht vollständig auf dem Ablagekonzept aus Abschnitt~\ref{sec:s3-layout}: Aus der Organisations-ID im Token wird der zugehörige Kundenordner aufgelöst, und sämtliche Abfragen an den Speicher werden auf dieses Präfix eingeschränkt.
+Die zweite Stufe stellt sicher, dass ein berechtigter Benutzer ausschließlich die Dokumente seiner Organisation sieht. Aus der Organisations-ID wird der zugehörige Kundenordner aufgelöst, und alle Abfragen werden auf dieses Präfix eingeschränkt (siehe Abschnitt~\ref{sec:s3-layout}).
 
-Entscheidend ist dabei, dass die Einschränkung nicht nachträglich auf ein bereits geladenes Ergebnis angewendet wird, sondern bereits Bestandteil der Abfrage ist. Houston lädt zu keinem Zeitpunkt Dokumente fremder Kunden in den Speicher, um sie anschließend herauszufiltern. Ein Fehler in der Darstellungsschicht kann damit nicht zu einer Offenlegung führen.
+Entscheidend ist, dass die Einschränkung bereits Bestandteil der Abfrage ist — Houston lädt nie Dokumente fremder Kunden, um sie nachträglich herauszufiltern. Ein Fehler in der Darstellungsschicht kann damit nicht zu einer Offenlegung führen.
 
 Abbildung~\ref{fig:auth-sequence} stellt den vollständigen Ablauf dar.
 
@@ -45,8 +45,8 @@ Abbildung~\ref{fig:auth-sequence} stellt den vollständigen Ablauf dar.
 
 \subsection{Absicherung der Einzelzugriffe}
 
-Die Auflistung ist nicht der einzige Zugriffspfad. Auch der Download einzelner Dokumente, der ZIP-Download, die PDF-Vorschau und die Freigabelinks nehmen jeweils einen Dokumentschlüssel entgegen. Für jeden dieser Pfade gilt dieselbe Regel: Der angeforderte Schlüssel wird gegen das aufgelöste Kundenpräfix geprüft, bevor auf den Speicher zugegriffen wird.
+Auch Download, ZIP-Download, PDF-Vorschau und Freigabelinks nehmen jeweils einen Dokumentschlüssel entgegen. Für jeden Pfad wird der angeforderte Schlüssel gegen das aufgelöste Kundenpräfix geprüft, bevor auf den Speicher zugegriffen wird.
 
-Zusätzlich wird der übergebene Pfad daraufhin untersucht, ob er Bestandteile enthält, mit denen sich der Kundenordner verlassen ließe. Ohne diese Prüfung könnte ein Benutzer durch Manipulation des Parameters auf fremde Ordner zugreifen, obwohl das Präfix zunächst korrekt gesetzt war. Diese Anforderung (NFA-6) wurde im Approval-Termin ausdrücklich in die Akzeptanzkriterien aufgenommen.
+Zusätzlich wird der Pfad auf Bestandteile untersucht, mit denen sich der Kundenordner verlassen ließe (NFA-6). Ohne diese Prüfung könnte ein Benutzer durch Manipulation des Parameters auf fremde Ordner zugreifen.
 
-Die Freigabelinks stellen dabei keine Ausnahme dar: Sie enthalten keine Anmeldeinformationen und gewähren keinen eigenständigen Zugriff. Ein Empfänger, der nicht über die Rolle und die passende Organisationszugehörigkeit verfügt, erhält beim Aufruf dieselbe 403-Antwort wie bei jedem anderen Zugriffsversuch. Der Link dient ausschließlich dazu, innerhalb des berechtigten Personenkreises auf ein bestimmtes Dokument zu verweisen.
+Freigabelinks stellen keine Ausnahme dar: Sie enthalten keine Anmeldeinformationen und gewähren keinen eigenständigen Zugriff. Ein Empfänger ohne Rolle und passende Organisationszugehörigkeit erhält dieselbe 403-Antwort. Der Link verweist lediglich innerhalb des berechtigten Personenkreises auf ein Dokument.

chapters/conception/document-types.tex

@@ -3,7 +3,7 @@
 
 \subsection{Der Typenkatalog}
 
-Die sieben Dokumententypen wurden fachlich in der Feature-Beschreibung festgelegt und im Projektverlauf nicht verändert. Sie bilden die Kategorien ab, in denen WorkSimple gegenüber Kunden regelmäßig Unterlagen bereitstellt. Tabelle~\ref{tab:document-types} zeigt den Katalog mit dem jeweiligen Ordnernamen im Speicher.
+Die sieben Dokumententypen wurden in der Feature-Beschreibung festgelegt und im Projektverlauf nicht verändert. Tabelle~\ref{tab:document-types} zeigt den Katalog mit dem jeweiligen Ordnernamen im Speicher.
 
 \begin{table}[H]
 \centering
@@ -26,24 +26,24 @@ Die sieben Dokumententypen wurden fachlich in der Feature-Beschreibung festgeleg
 
 \subsection{Feste Kodierung statt Konfiguration}
 
-Im Approval-Termin stellte \emph{Timo Walter} die Frage, ob die Kategorien konfigurierbar sein sollen und ob im Betrieb weitere Typen hinzukommen können. Die Entscheidung fiel auf eine feste Kodierung in Houston. Dafür sprechen mehrere Überlegungen.
+Im Approval-Termin stellte \emph{Timo Walter} die Frage, ob die Kategorien konfigurierbar sein sollen. Die Entscheidung fiel auf eine feste Kodierung in Houston.
 
-Der Typenkatalog ist fachlich stabil. Er leitet sich aus den Leistungen ab, die WorkSimple erbringt, und ändert sich allenfalls im Rhythmus von Jahren. Eine Konfigurierbarkeit würde für diesen Änderungsrhythmus eine Verwaltungsoberfläche, ein Speicherformat und eine Migrationsstrategie erfordern — ein Aufwand, der in keinem Verhältnis zum Nutzen steht.
+Der Typenkatalog ist fachlich stabil und ändert sich allenfalls im Rhythmus von Jahren. Konfigurierbarkeit würde Verwaltungsoberfläche, Speicherformat und Migrationsstrategie erfordern — ein unverhältnismäßiger Aufwand.
 
-Hinzu kommt, dass die Typen nicht nur als Beschriftung auftreten. Jeder Typ benötigt ein Icon und eine Übersetzung, und beide müssten bei einem frei konfigurierbaren Katalog ebenfalls hinterlegbar sein. Ein neuer Typ ohne Icon fiele in der Oberfläche unangenehm auf. Die feste Kodierung stellt sicher, dass Ordnername, Anzeigetext und Icon stets gemeinsam gepflegt werden.
+Hinzu kommt, dass jeder Typ ein Icon und eine Übersetzung benötigt, die bei einem frei konfigurierbaren Katalog ebenfalls hinterlegbar sein müssten. Die feste Kodierung stellt sicher, dass Ordnername, Anzeigetext und Icon gemeinsam gepflegt werden.
 
-Der Preis dieser Entscheidung ist, dass das Hinzufügen eines Typs eine Codeänderung und ein Release erfordert. Angesichts der erwarteten Änderungshäufigkeit ist das vertretbar.
+Der Preis: Das Hinzufügen eines Typs erfordert eine Codeänderung und ein Release. Angesichts der erwarteten Änderungshäufigkeit ist das vertretbar.
 
 \subsection{Verhalten bei unbekannten Ordnern}
 
-Aus der festen Kodierung ergibt sich unmittelbar die Frage, wie mit Unterordnern umzugehen ist, die nicht im Katalog stehen. Ein Kundenbetreuer könnte in Filestash versehentlich einen Ordner \texttt{Sonstiges} anlegen oder sich beim Namen vertippen.
+Aus der festen Kodierung ergibt sich die Frage, wie mit Unterordnern umzugehen ist, die nicht im Katalog stehen — etwa einem Ordner \texttt{Sonstiges} in Filestash.
 
-Das Konzept sieht vor, dass Dokumente in solchen Ordnern nicht verschwinden. Sie werden angezeigt und erhalten ein neutrales Standard-Icon; lediglich die Typzuordnung entfällt. Die Alternative — solche Dokumente auszublenden — wurde verworfen, weil sie ein stilles Fehlverhalten erzeugen würde: Ein hochgeladenes Dokument wäre für den Kunden unsichtbar, ohne dass dies für den Betreuer erkennbar wäre.
+Dokumente in solchen Ordnern werden angezeigt und erhalten ein neutrales Standard-Icon; lediglich die Typzuordnung entfällt. Ausblenden wurde verworfen, weil es stilles Fehlverhalten erzeugen würde: Ein Dokument wäre unsichtbar, ohne dass der Betreuer dies bemerkt.
 
-Zu unterscheiden ist dieser Fall vom Umgang mit unbekannten Ordnern auf der \emph{obersten} Ebene. Dort führt ein fehlendes Marker-Metadatum zum vollständigen Ausschluss (siehe Abschnitt~\ref{sec:s3-layout}). Der Unterschied ist beabsichtigt: Auf oberster Ebene entscheidet die Struktur über die Mandantentrennung, hier gilt im Zweifel Ausschluss. Innerhalb eines Kundenordners ist die Zugehörigkeit dagegen bereits geklärt, und ein unbekannter Unterordner ist lediglich ein Darstellungsproblem.
+Zu unterscheiden ist dieser Fall vom Umgang mit unbekannten Ordnern auf der \emph{obersten} Ebene, wo ein fehlendes Marker-Metadatum zum vollständigen Ausschluss führt (siehe Abschnitt~\ref{sec:s3-layout}). Der Unterschied ist beabsichtigt: Auf oberster Ebene entscheidet die Struktur über die Mandantentrennung; innerhalb eines Kundenordners ist die Zugehörigkeit bereits geklärt.
 
 \subsection{Übersetzung der Anzeigenamen}
 
-Die Ordnernamen im Speicher dienen zwei verschiedenen Zielgruppen. Für die Kundenbetreuer, die in Filestash arbeiten, müssen sie lesbar und eindeutig sein. Für den Kunden in Houston sollen sie sich in die Oberfläche einfügen.
+Die Ordnernamen im Speicher dienen zwei Zielgruppen: Für die Kundenbetreuer in Filestash müssen sie lesbar und eindeutig sein, für den Kunden in Houston sollen sie sich in die Oberfläche einfügen.
 
-Aus diesem Grund wird der Ordnername nicht unverändert angezeigt, sondern über eine Ressourcendatei auf einen Anzeigetext abgebildet. Dieses Vorgehen entspricht dem in Houston bereits etablierten Muster zur Lokalisierung und erlaubt es, den Anzeigetext zu ändern, ohne die Struktur im Speicher anzufassen — eine Umbenennung dort würde bedeuten, sämtliche betroffenen Objekte umzukopieren.
+Der Ordnername wird nicht unverändert angezeigt, sondern über eine Ressourcendatei auf einen Anzeigetext abgebildet. Dies entspricht dem in Houston etablierten Lokalisierungsmuster und erlaubt Änderungen am Anzeigetext, ohne die Speicherstruktur anzufassen — eine Umbenennung dort würde das Umkopieren sämtlicher betroffenen Objekte erfordern.

chapters/conception/lookup-decision.tex

@@ -3,31 +3,31 @@
 
 \subsection{Die zugrunde liegende Idee}
 
-Alle in Abschnitt~\ref{sec:lookup-research} betrachteten Ansätze versuchen, die Zuordnung zwischen Organisations-ID und Ordnername \emph{zusätzlich} irgendwo zu hinterlegen — in einem Cache, in einem Token, in Efecte oder in einer Zuordnungsdatei. Jeder dieser Ansätze führt damit eine zweite Datenhaltung ein, die mit der ersten konsistent gehalten werden muss.
+Alle in Abschnitt~\ref{sec:lookup-research} betrachteten Ansätze hinterlegen die Zuordnung \emph{zusätzlich} irgendwo — in Cache, Token, Efecte oder einer Zuordnungsdatei. Jeder führt eine zweite, konsistent zu haltende Datenhaltung ein.
 
-Die schließlich gewählte Lösung dreht die Fragestellung um. Statt die Zuordnung nachzuschlagen, wird sie \emph{berechenbar} gemacht: Wenn der Ordnername sich deterministisch aus dem Firmennamen ableiten lässt und dieser Firmenname bereits im Anmeldetoken steht, kann Houston den erwarteten Ordnernamen ohne jeden Nachschlagevorgang bestimmen. Aus der Suche wird ein direkter Zugriff.
+Die gewählte Lösung dreht die Fragestellung um: Lässt sich der Ordnername deterministisch aus dem Firmennamen ableiten und steht dieser im Token, kann Houston den Ordnernamen ohne Nachschlagevorgang bestimmen. Aus der Suche wird ein direkter Zugriff.
 
-Voraussetzung dafür ist, dass die Ordner im Speicher tatsächlich so heißen, wie Houston es erwartet. Genau hier setzt die eigentliche Entscheidung an: \textbf{Houston wird zur führenden Instanz für die Namensgebung der Kundenordner.} Weicht ein Ordner vom erwarteten Namen ab, wird nicht der Erwartungswert angepasst, sondern der Ordner umbenannt.
+Voraussetzung ist, dass die Ordner tatsächlich so heißen, wie Houston es erwartet. \textbf{Houston wird zur führenden Instanz für die Namensgebung der Kundenordner.} Weicht ein Ordner ab, wird er umbenannt.
 
-Diese Festlegung ist deshalb vertretbar, weil Houston die Ordnerstruktur ohnehin selbst anlegt (FA-13). Wenn die Anwendung neue Kundenordner erzeugt, ist es folgerichtig, dass sie auch deren Benennung verantwortet. Die Kundenbetreuer verlieren dadurch nichts: Der Ordner heißt weiterhin nach dem Kunden, nur eben in einer normalisierten Form.
+Diese Festlegung ist vertretbar, weil Houston die Ordnerstruktur ohnehin selbst anlegt (FA-13). Die Kundenbetreuer verlieren nichts: Der Ordner heißt weiterhin nach dem Kunden, nur normalisiert.
 
 \subsection{Ableitung des Ordnernamens}
 
-Der Firmenname aus dem Token kann nicht unverändert als Ordnername verwendet werden. Er kann Zeichen enthalten, die im Schlüssel problematisch sind, führende oder abschließende Leerzeichen aufweisen oder beliebig lang sein. Er wird deshalb durch eine Normalisierungsfunktion geführt, die im weiteren Verlauf als \emph{Slug} bezeichnet wird.
+Der Firmenname aus dem Token kann nicht unverändert als Ordnername dienen — er kann problematische Zeichen, führende Leerzeichen oder beliebige Länge aufweisen. Er wird durch eine Normalisierungsfunktion geführt, im Folgenden \emph{Slug} genannt.
 
-Die Normalisierung folgt zwei Leitgedanken. Sie muss \textbf{deterministisch} sein — derselbe Firmenname muss stets denselben Ordnernamen ergeben, sonst funktioniert der direkte Zugriff nicht. Und sie muss das Ergebnis \textbf{lesbar} halten, weil der Ordner in Filestash von Menschen bedient wird. Aus dem zweiten Punkt folgt eine bewusste Abweichung von der üblichen Praxis: Umlaute werden \emph{nicht} ersetzt. Eine Firma „Müller GmbH" erhält den Ordner \texttt{Müller GmbH} und nicht \texttt{Mueller GmbH}, weil der Betreuer sie andernfalls in der alphabetischen Liste an unerwarteter Stelle suchen müsste. Die Zulässigkeit solcher Zeichen in Objektschlüsseln wurde anhand der Herstellerdokumentation geprüft \autocite{aws-s3-naming, ibm-s3-naming}; die Frage war auch Gegenstand des Code-Reviews.
+Die Normalisierung muss \textbf{deterministisch} sein — derselbe Firmenname muss stets denselben Ordnernamen ergeben — und das Ergebnis \textbf{lesbar} halten, weil der Ordner in Filestash von Menschen bedient wird. Umlaute werden bewusst \emph{nicht} ersetzt: „Müller GmbH" erhält den Ordner \texttt{Müller GmbH}, nicht \texttt{Mueller GmbH}, weil der Betreuer die Firma sonst in der alphabetischen Liste an unerwarteter Stelle suchen müsste. Die Zulässigkeit solcher Zeichen in Objektschlüsseln wurde anhand der Herstellerdokumentation geprüft \autocite{aws-s3-naming, ibm-s3-naming}.
 
 \subsection{Umgang mit Namenskollisionen}
 
-Firmennamen sind nicht garantiert eindeutig. Efecte lässt zwei Organisationen mit identischem Namen grundsätzlich zu, und sobald der Ordnername aus dem Firmennamen abgeleitet wird, treffen beide auf denselben Zielnamen. Da eine Verwechslung hier unmittelbar bedeuten würde, dass ein Kunde die Dokumente eines anderen sieht, muss dieser Fall abgedeckt sein.
+Firmennamen sind nicht garantiert eindeutig. Efecte lässt zwei Organisationen mit identischem Namen zu, und beide würden auf denselben Ordnernamen treffen. Da eine Verwechslung bedeuten würde, dass ein Kunde fremde Dokumente sieht, muss der Fall abgedeckt sein.
 
-Das Konzept löst ihn nach dem Prinzip „wer zuerst kommt, mahlt zuerst": Die erste Organisation, die den Namen beansprucht, erhält ihn. Jede weitere erhält einen Ordner, dem die Organisations-ID in Klammern angehängt wird, also etwa \texttt{Beispielkunde GmbH (77)}. Dieser Name ist eindeutig, bleibt lesbar und sortiert weiterhin unmittelbar neben dem gleichnamigen Ordner.
+Die erste Organisation, die den Namen beansprucht, erhält ihn. Jede weitere erhält einen Ordner mit angehängter Organisations-ID, etwa \texttt{Beispielkunde GmbH (77)} — eindeutig, lesbar und alphabetisch neben dem gleichnamigen Ordner.
 
-Maßgeblich ist dabei eine Sicherheitsregel: Ein Zielname wird nur dann beansprucht, wenn er entweder frei ist oder ausweislich seines Markers bereits der eigenen Organisation gehört. Ein fremder Kundenordner wird unter keinen Umständen überschrieben oder umbenannt. Die Zuordnung entscheidet also immer das Metadatum, niemals der Name — der Name ist nur die Optimierung.
+Sicherheitsregel: Ein Zielname wird nur beansprucht, wenn er frei ist oder ausweislich seines Markers der eigenen Organisation gehört. Ein fremder Kundenordner wird unter keinen Umständen überschrieben. Die Zuordnung entscheidet immer das Metadatum, nie der Name.
 
 \subsection{Der resultierende Ablauf}
 
-Aus diesen Überlegungen ergibt sich ein dreistufiges Verfahren, das in Abbildung~\ref{fig:lookup-flow} dargestellt ist.
+Aus diesen Überlegungen ergibt sich ein dreistufiges Verfahren (Abbildung~\ref{fig:lookup-flow}).
 
 \begin{figure}[H]
     \centering
@@ -37,21 +37,21 @@ Aus diesen Überlegungen ergibt sich ein dreistufiges Verfahren, das in Abbildun
 \end{figure}
 
 \begin{enumerate}
-    \item \textbf{Direktzugriff.} Houston bildet den erwarteten Ordnernamen aus dem Firmennamen und ruft die Metadaten des zugehörigen Markers ab. Existiert er und trägt er die richtige Organisations-ID, ist die Auflösung mit einem einzigen Aufruf abgeschlossen. Dies ist der Regelfall.
-    \item \textbf{Kollisionsprüfung.} Schlägt der erste Schritt fehl — weil der Marker fehlt oder eine fremde Organisations-ID trägt — wird derselbe Zugriff mit dem um die Organisations-ID ergänzten Namen wiederholt. Damit ist der Kollisionsfall mit zwei Aufrufen abgedeckt.
-    \item \textbf{Rückfallebene.} Erst wenn auch das nicht greift, kommt das ursprüngliche, lineare Verfahren zum Einsatz. Wird dabei ein Ordner mit passender Organisations-ID gefunden, trägt er offenbar einen abweichenden Namen und wird auf den kanonischen Namen umbenannt. Wird kein Ordner gefunden, existiert der Kunde im Speicher noch nicht und die vollständige Struktur wird angelegt.
+    \item \textbf{Direktzugriff.} Houston bildet den erwarteten Ordnernamen aus dem Firmennamen und ruft die Metadaten des Markers ab. Stimmt die Organisations-ID, ist die Auflösung mit einem Aufruf abgeschlossen. Dies ist der Regelfall.
+    \item \textbf{Kollisionsprüfung.} Fehlt der Marker oder trägt er eine fremde ID, wird der Zugriff mit dem um die Organisations-ID ergänzten Namen wiederholt — zwei Aufrufe für den Kollisionsfall.
+    \item \textbf{Rückfallebene.} Erst dann kommt das lineare Verfahren zum Einsatz. Wird ein Ordner mit passender ID gefunden, wird er auf den kanonischen Namen umbenannt. Wird keiner gefunden, wird die vollständige Struktur angelegt.
 \end{enumerate}
 
 \subsection{Selbstheilung}
 
-Die entscheidende Eigenschaft dieses Verfahrens liegt im dritten Schritt. Die Rückfallebene beseitigt nicht nur den unmittelbaren Fehlschlag, sondern auch dessen Ursache: Nach der Umbenennung trägt der Ordner den erwarteten Namen, und der nächste Zugriff derselben Organisation wird wieder über den Direktzugriff abgewickelt.
+Die entscheidende Eigenschaft liegt im dritten Schritt: Die Rückfallebene beseitigt nicht nur den Fehlschlag, sondern auch dessen Ursache. Nach der Umbenennung trägt der Ordner den erwarteten Namen, und der nächste Zugriff läuft direkt.
 
-Der teure Pfad wird damit pro Kunde höchstens einmal durchlaufen. Bestehende Ordner, die vor Einführung des Verfahrens angelegt wurden und beliebige Namen tragen, migrieren sich beim ersten Zugriff des jeweiligen Kunden von selbst. Eine gesonderte Migration ist nicht erforderlich.
+Der teure Pfad wird pro Kunde höchstens einmal durchlaufen. Bestehende Ordner migrieren sich beim ersten Zugriff von selbst — eine gesonderte Migration entfällt.
 
-Ebenso wenig erfordert das Verfahren eine zusätzliche Datenhaltung. Es gibt keinen Cache, der invalidiert werden müsste, kein Feld in einem Fremdsystem und keine Zuordnungsdatei. Der Zustand liegt vollständig im Speicher selbst, und die Anwendung ist zu jedem Zeitpunkt in der Lage, aus einem beliebigen Ausgangszustand den Sollzustand herzustellen.
+Das Verfahren erfordert keine zusätzliche Datenhaltung: keinen Cache, kein Feld in einem Fremdsystem, keine Zuordnungsdatei. Der Zustand liegt vollständig im Speicher, und die Anwendung kann aus jedem Ausgangszustand den Sollzustand herstellen.
 
 \subsection{Bewusst offen gelassener Bereich}
 
-Das Verfahren hat einen Preis, der bei der Entscheidung bekannt war: Die Rückfallebene ist nicht mehr nur lesend. Sie benennt Ordner um und legt sie an — und das im Rahmen einer gewöhnlichen Seitenanfrage. Da Houston in mehreren Instanzen betrieben wird, können zwei solche Anfragen gleichzeitig auf denselben Ordner treffen.
+Die Rückfallebene ist nicht nur lesend: Sie benennt Ordner um und legt sie an — im Rahmen einer gewöhnlichen Seitenanfrage. Da Houston in mehreren Instanzen läuft, können zwei Anfragen gleichzeitig denselben Ordner betreffen.
 
-Dieser Umstand wurde während der Umsetzung erkannt, in seinen Auswirkungen analysiert und als eigenes Backlog Item vom laufenden Pull Request abgegrenzt. Die Entscheidung, die Abgrenzung so vorzunehmen, wurde mit dem Team abgestimmt. Abschnitt~\ref{sec:race-conditions} behandelt die konkreten Fehlerszenarien und die erwogenen Gegenmaßnahmen im Detail.
+Dieser Umstand wurde analysiert und als eigenes Backlog Item vom laufenden Pull Request abgegrenzt. Abschnitt~\ref{sec:race-conditions} behandelt die Szenarien und erwogenen Gegenmaßnahmen.

chapters/conception/lookup-research.tex

@@ -3,52 +3,46 @@
 
 \subsection{Entstehung}
 
-Der Document Explorer war zum Zeitpunkt seines Merges am 31.~Juli 2026 funktionsfähig, enthielt aber eine Schwäche, die bereits im Code-Review angesprochen worden war. Um den Kundenordner zu einer Organisations-ID zu finden, listete Houston sämtliche Ordner auf der obersten Ebene des Buckets auf, rief für jeden davon die Metadaten ab und verglich die hinterlegte \texttt{efecte-org-id} mit der des angemeldeten Benutzers.
+Der Document Explorer war zum Zeitpunkt seines Merges am 31.~Juli 2026 funktionsfähig, enthielt aber eine im Code-Review angesprochene Schwäche. Um den Kundenordner zu einer Organisations-ID zu finden, listete Houston sämtliche Ordner auf oberster Ebene auf, rief für jeden die Metadaten ab und verglich die \texttt{efecte-org-id} mit der des Benutzers.
 
-Die Ursache liegt in der bereits beschriebenen Eigenschaft von S3: Objekte lassen sich nicht anhand ihrer benutzerdefinierten Metadaten suchen. Die Operation \texttt{ListObjectsV2} liefert Schlüssel, Größe und Änderungszeitpunkt, aber keine benutzerdefinierten Metadaten \autocite{aws-listobjectsv2}. Um an das Marker-Metadatum zu gelangen, ist für jeden Kandidaten ein eigener Aufruf nötig.
+Die Ursache: S3 bietet keine Suche nach benutzerdefinierten Metadaten. \texttt{ListObjectsV2} liefert Schlüssel, Größe und Änderungszeitpunkt, aber keine benutzerdefinierten Metadaten \autocite{aws-listobjectsv2}. Für jeden Kandidaten ist ein eigener Aufruf nötig.
 
-Damit wächst der Aufwand für die Auflösung des Kundenordners linear mit der Anzahl der Kunden — und zwar bei \emph{jedem} Seitenaufruf jedes Benutzers. Bei einer zweistelligen Kundenzahl fällt das kaum auf; bei einigen hundert Kunden bedeutet es einige hundert Netzwerkaufrufe, bevor überhaupt das erste Dokument geladen wird. Das Problem ist also nicht akut, aber strukturell: Es verschlechtert sich mit dem Erfolg des Produkts.
+Der Aufwand wächst linear mit der Kundenzahl — bei \emph{jedem} Seitenaufruf. Bei einigen hundert Kunden bedeutet das einige hundert Netzwerkaufrufe, bevor das erste Dokument geladen wird. Das Problem ist nicht akut, aber strukturell.
 
-Aus dieser Erkenntnis entstand am 28.~Juli ein eigenes Backlog Item. Bemerkenswert ist, dass es bewusst nicht als Umsetzungs-, sondern als \emph{Recherche}-Item angelegt wurde. Das Akzeptanzkriterium lautete nicht „das Problem ist behoben", sondern „es ist sich für einen Lösungsansatz entschieden worden". Diese Zuschnitt-Entscheidung trennt die Frage, welche Lösung die richtige ist, von der Frage, wie sie umzusetzen ist — und macht den Rechercheaufwand als eigenständige Leistung sichtbar, statt ihn in einer Implementierungsaufgabe zu verstecken.
+Am 28.~Juli entstand daraus ein eigenes Backlog Item, bewusst als \emph{Recherche}-Item. Das Akzeptanzkriterium lautete nicht „das Problem ist behoben", sondern „es ist sich für einen Lösungsansatz entschieden worden". So wird der Rechercheaufwand als eigenständige Leistung sichtbar.
 
 \subsection{Untersuchte Lösungsansätze}
 
-Im Zuge der Recherche wurden sechs Ansätze betrachtet und mit \emph{Timo Walter} sowie den Ansprechpartnern für die Speicherinfrastruktur diskutiert. Tabelle~\ref{tab:lookup-tradeoffs} im Anhang fasst die Bewertung zusammen; im Folgenden werden die Ansätze und ihre jeweiligen Schwächen erläutert.
+Sechs Ansätze wurden betrachtet und mit \emph{Timo Walter} sowie den Ansprechpartnern für die Speicherinfrastruktur diskutiert. Tabelle~\ref{tab:lookup-tradeoffs} im Anhang fasst die Bewertung zusammen.
 
 \subsubsection{In-Memory-Cache}
 
-Der naheliegendste Ansatz ist, das Ergebnis der Auflösung im Arbeitsspeicher der Anwendung zwischenzuspeichern. Der erste Aufruf bleibt teuer, alle folgenden sind kostenlos.
+Der naheliegendste Ansatz: das Auflösungsergebnis im Arbeitsspeicher zwischenspeichern. Der erste Aufruf bleibt teuer, alle folgenden sind kostenlos.
 
-Der Ansatz behebt das Problem jedoch nur oberflächlich. Houston läuft in mehr als einer Instanz, sodass jede Instanz ihren eigenen Cache aufbauen müsste. Nach jedem Neustart oder jeder Bereitstellung ist der Cache leer, und es entsteht ein Ansturm teurer Auflösungen. Vor allem aber bleibt der zugrunde liegende lineare Aufwand unverändert bestehen — er wird lediglich seltener bezahlt. Ein Cache ist eine Optimierung, keine Lösung.
+Houston läuft jedoch in mehreren Instanzen, sodass jede ihren Cache aufbauen müsste. Nach jedem Neustart ist der Cache leer, und es entsteht ein Ansturm teurer Auflösungen. Der lineare Aufwand bleibt unverändert — er wird lediglich seltener bezahlt.
 
 \subsubsection{Speicherung im Anmeldetoken}
 
-Alternativ ließe sich der Ordnername bei der Anmeldung ermitteln und als zusätzlicher Claim im Token ablegen. Gegenüber dem Cache verschiebt das den Aufwand von jedem Seitenaufruf auf jede Anmeldung.
-
-Auch hier bleibt der lineare Aufwand erhalten. Hinzu kommt ein Konsistenzproblem: Ein Token ist über seine Laufzeit unveränderlich. Wird der Ordner im Speicher umbenannt, während ein Benutzer angemeldet ist, zeigt der Claim auf einen nicht mehr existierenden Ordner, bis das Token erneuert wird.
+Der Ordnername könnte bei der Anmeldung ermittelt und als Claim im Token abgelegt werden. Der lineare Aufwand bliebe erhalten. Hinzu kommt: Ein Token ist über seine Laufzeit unveränderlich. Wird der Ordner umbenannt, zeigt der Claim auf einen nicht mehr existierenden Ordner, bis das Token erneuert wird.
 
 \subsubsection{Speicherung als Feld in Efecte}
 
-Der Ordnername könnte auch als zusätzliches Feld an der Organisation in Efecte gepflegt werden. Houston würde ihn dann gemeinsam mit den übrigen Organisationsdaten laden.
-
-Dieser Ansatz löst das Problem technisch, führt aber eine neue Abhängigkeit ein und verlagert die Pflege in ein weiteres System. Die Zuordnung zwischen Kunde und Ordner läge damit an zwei Stellen — im Efecte-Feld und im Marker-Metadatum — die auseinanderlaufen können. Zudem müsste das Feld für jeden Bestandskunden nachgepflegt werden.
+Der Ordnername könnte als Feld an der Organisation in Efecte gepflegt werden. Das löst das Problem technisch, führt aber eine Abhängigkeit ein: Die Zuordnung läge an zwei Stellen — im Efecte-Feld und im Marker-Metadatum — die auseinanderlaufen können. Zudem müsste das Feld für jeden Bestandskunden nachgepflegt werden.
 
 \subsubsection{S3 Select}
 
-Die Operation \texttt{SelectObjectContent} erlaubt es, den \emph{Inhalt} eines Objekts serverseitig per SQL-ähnlicher Abfrage zu filtern \autocite{aws-s3-select}. Denkbar wäre gewesen, eine Zuordnungstabelle als Datei im Bucket abzulegen und den passenden Eintrag serverseitig herauszufiltern.
+\texttt{SelectObjectContent} filtert den \emph{Inhalt} eines Objekts serverseitig per SQL-ähnlicher Abfrage \autocite{aws-s3-select}. Denkbar wäre eine Zuordnungstabelle als Datei im Bucket, aus der der passende Eintrag gefiltert wird.
 
-Die Freischaltung wurde beantragt und am 7.~August durch den Betreiber bestätigt (siehe Abschnitt~\ref{sec:infrastructure}). Bei genauerer Betrachtung erwies sich der Ansatz jedoch als unpassend: S3 Select filtert Inhalte einzelner Objekte, nicht Metadaten mehrerer Objekte. Eine Zuordnungsdatei wäre eine zusätzliche, manuell oder programmatisch zu pflegende Struktur — mit demselben Konsistenzproblem wie beim Efecte-Feld, nur ohne dessen Werkzeugunterstützung.
+Die Freischaltung wurde beantragt und am 7.~August bestätigt (siehe Abschnitt~\ref{sec:infrastructure}). S3 Select filtert jedoch Inhalte einzelner Objekte, nicht Metadaten mehrerer Objekte. Eine Zuordnungsdatei wäre eine zusätzlich zu pflegende Struktur mit demselben Konsistenzproblem wie beim Efecte-Feld, nur ohne dessen Werkzeugunterstützung.
 
 \subsubsection{StorageGRID Search Integration}
 
-Der Search Integration Service spiegelt Objektmetadaten in einen Elasticsearch-Index und ermöglicht damit genau das, was S3 selbst nicht bietet: eine echte Suche über Metadaten \autocite{storagegrid-search-integration}. Fachlich wäre dies die sauberste Lösung gewesen, da sie das Problem an der Wurzel behebt, ohne eine zweite Datenhaltung einzuführen.
-
-Die Anfrage über den Betreiber ergab am 17.~August, dass die Funktion derzeit nicht angeboten wird. Damit schied der Ansatz aus. Er wurde in den Ausblick übernommen (siehe Abschnitt~\ref{sec:outlook}).
+Der Search Integration Service spiegelt Objektmetadaten in einen Elasticsearch-Index und ermöglicht eine echte Metadatensuche \autocite{storagegrid-search-integration}. Fachlich die sauberste Lösung, da sie das Problem an der Wurzel behebt, ohne eine zweite Datenhaltung einzuführen. Die Anfrage ergab am 17.~August, dass die Funktion derzeit nicht angeboten wird; der Ansatz wurde in den Ausblick übernommen (siehe Abschnitt~\ref{sec:outlook}).
 
 \subsubsection{Organisations-ID im Ordnernamen}
 
-Der technisch einfachste Ansatz wäre gewesen, die Organisations-ID zum Bestandteil des Ordnernamens zu machen — etwa als Präfix \texttt{42\_Beispielkunde GmbH}. Der Lookup reduzierte sich dann auf eine einzige Präfixabfrage.
+Der einfachste Ansatz: die Organisations-ID zum Bestandteil des Ordnernamens machen — etwa \texttt{42\_Beispielkunde GmbH}. Der Lookup reduzierte sich auf eine Präfixabfrage.
 
-Dieser Ansatz scheiterte an einer fachlichen Anforderung. In der Abstimmung mit \emph{Ralf Schulte} wurde deutlich, dass die Kundenbetreuer die Ordner in Filestash nach Kundennamen sortiert vorfinden müssen, um damit arbeiten zu können. Ein vorangestellter Zahlenschlüssel zerstört diese Sortierung. Der Konflikt ist damit klar benannt: Houston autorisiert über die Organisations-ID, die Betreuer arbeiten über den Kundennamen, und der Speicher bietet keinen Mechanismus, zwischen beiden zu vermitteln.
+In der Abstimmung mit \emph{Ralf Schulte} wurde deutlich, dass die Kundenbetreuer die Ordner in Filestash nach Kundennamen sortiert vorfinden müssen. Ein vorangestellter Zahlenschlüssel zerstört diese Sortierung. Der Konflikt: Houston autorisiert über die Organisations-ID, die Betreuer arbeiten über den Kundennamen, und der Speicher vermittelt nicht zwischen beiden.
 
-Die entscheidende Beobachtung war jedoch, dass die Anforderung eine Sortierung nach Kundennamen verlangt — nicht zwingend, dass der Ordnername \emph{ausschließlich} aus dem Kundennamen besteht. Diese Unterscheidung eröffnete den Weg zu der in Abschnitt~\ref{sec:lookup-decision} beschriebenen Lösung.
+Die entscheidende Beobachtung war, dass die Anforderung eine Sortierung nach Kundennamen verlangt — nicht zwingend, dass der Ordnername \emph{ausschließlich} aus dem Kundennamen besteht. Diese Unterscheidung eröffnete den Weg zur in Abschnitt~\ref{sec:lookup-decision} beschriebenen Lösung.

chapters/conception/s3-layout.tex

@@ -1,17 +1,17 @@
 \section{Ablagekonzept im S3-Speicher}
 \label{sec:s3-layout}
 
-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.
+Das Ablagekonzept muss zwei Aufgaben erfüllen: die Zuordnung von Dokumenten zu Kunden und die Abbildung des fachlichen Dokumententyps. Beides geschieht ausschließlich über die Struktur im Speicher, ohne eine zusätzliche Datenbank.
 
 \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
+S3 kennt technisch keine Ordner. Jedes Objekt wird über einen Schlüssel in einem flachen Namensraum adressiert. Die scheinbare Hierarchie entsteht beim Auflisten: \texttt{ListObjectsV2} liefert mit Präfix und Trennzeichen nur die Objekte unterhalb eines Präfixes 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.
+erscheint in Filestash als zweistufige Ordnerhierarchie, ist im Speicher aber nur eine Zeichenkette. Ein „Ordner" existiert erst, wenn mindestens ein Objekt mit dem entsprechenden Präfix vorhanden ist; ein leerer Ordner lässt sich nur durch ein Platzhalterobjekt simulieren, dessen Schlüssel auf das Trennzeichen endet.
 
 Abbildung~\ref{fig:s3-layout} zeigt die resultierende Struktur.
 
@@ -24,36 +24,36 @@ Abbildung~\ref{fig:s3-layout} zeigt die resultierende Struktur.
 
 \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.
+Auf der obersten Ebene des Buckets liegt für jeden Kunden ein Ordner. Dessen Platzhalterobjekt trägt ein benutzerdefiniertes Metadatum \texttt{efecte-org-id} zur Zuordnung an eine Organisation und 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.
+Er sorgt dafür, dass der Kundenordner auch ohne Dokumente existiert, und trägt die Organisationszugehörigkeit an genau einer Stelle.
 
-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.
+Die Organisations-ID wird als Metadatum statt als Bestandteil des Ordnernamens geführt (siehe Abschnitt~\ref{sec:feature-analysis}). Die Ordner werden von Kundenbetreuern über Filestash gepflegt; ein Name wie \texttt{42} wäre dort schwer handhabbar. 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.
+Genau diese Entscheidung erzeugt das zentrale technische Problem des Projekts (Abschnitt~\ref{sec:lookup-research}): Houston kennt die Organisations-ID, muss daraus den Ordnernamen ermitteln — und S3 bietet keine Suche nach Metadaten.
 
 \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.
+Innerhalb des Kundenordners liegt für jeden der sieben Dokumententypen ein Unterordner. Der Typ ergibt sich aus dem Unterordner; direkt im Kundenordner liegende Dokumente 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:
+Die Alternative — den Typ als Metadatum an jeder Datei zu hinterlegen — wurde verglichen:
 
 \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{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 die natürliche Bedienhandlung.
+    \item \textbf{Abfragbarkeit:} Der Typ ist als Präfixbestandteil unmittelbar aus dem Schlüssel ablesbar. Ein Metadatum müsste dagegen für jedes Objekt einzeln abgerufen werden, da \texttt{ListObjectsV2} benutzerdefinierte Metadaten nicht mitliefert — bei $n$ Dokumenten also $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.
+Dem stehen zwei Nachteile gegenüber: Ein Dokument kann nur einen Typ haben, und die Ordner müssen existieren — die automatische Anlage wird damit zu einer eigenen Anforderung (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:
+Für die Darstellung gelten drei Regeln:
 
 \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.
+    \item \textbf{Ordner werden nicht als Einträge angezeigt.} Die Liste zeigt ausschließlich Dokumente; die Ordnerstruktur wird über Typ-Icons und Filter abgebildet. Der Benutzer sieht eine flache Liste aller seiner Dokumente.
+    \item \textbf{Leere Typordner erscheinen nicht.}
+    \item \textbf{Ordner ohne gültiges Marker-Metadatum werden ignoriert.} Fehlt die Organisations-ID, bleibt der Ordner unsichtbar. Der Fall wird protokolliert, führt aber nicht zu einem Fehler.
 \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.
+Die dritte Regel ist eine Sicherheitsmaßnahme: Ein fehlendes Metadatum führt zum Ausschluss, nicht zu einer Vermutung.

chapters/conception/ui-concept.tex

@@ -3,17 +3,17 @@
 
 \subsection{Zuarbeit über einen Clickdummy}
 
-Das Oberflächenkonzept wurde nicht als Mockup in einem Entwurfswerkzeug erstellt, sondern von \emph{Hanna Ebner} als lauffähiger Clickdummy in einem eigenen Branch des Houston-Repositories umgesetzt und am 22.~Juli 2026 am Feature verlinkt.
+Das Oberflächenkonzept wurde von \emph{Hanna Ebner} als lauffähiger Clickdummy in einem eigenen Branch des Houston-Repositories umgesetzt und am 22.~Juli 2026 am Feature verlinkt.
 
-Diese Form der Zuarbeit hat gegenüber einem Bildentwurf spürbare Vorteile. Der Clickdummy verwendet die bestehenden Komponenten und Stile der Anwendung, wodurch das Ergebnis von vornherein zum übrigen Portal passt. Fragen zu Abständen, Schriftgrößen oder Farben stellen sich gar nicht erst, weil sie durch das vorhandene Stylesheet beantwortet werden. Zudem ist das Ergebnis unmittelbar bedienbar: Interaktionen wie das Ein- und Ausklappen von Filtern lassen sich ausprobieren, statt sie aus einer statischen Abbildung erschließen zu müssen. Für die Umsetzung bedeutete das, dass der Clickdummy als Referenz für das Markup dienen konnte und in mehreren Product Backlog Items ausdrücklich als solche benannt wurde.
+Der Clickdummy verwendet die bestehenden Komponenten und Stile der Anwendung, wodurch Fragen zu Abständen, Schriftgrößen oder Farben durch das vorhandene Stylesheet beantwortet werden. Interaktionen wie das Ein- und Ausklappen von Filtern lassen sich ausprobieren statt aus einer statischen Abbildung erschlossen werden. Der Clickdummy diente als Referenz für das Markup und wurde in mehreren Product Backlog Items als solche benannt.
 
 \subsection{Flache Liste statt navigierbarer Hierarchie}
 
-Die auffälligste Entwurfsentscheidung ist, dass der Dokumentenbereich trotz seiner Bezeichnung als „Document Explorer" keine navigierbare Ordnerhierarchie darstellt. Der Benutzer sieht eine flache Liste aller seiner Dokumente; die Typzugehörigkeit wird über ein Icon und über Filter ausgedrückt, nicht über ein Hineinnavigieren in Ordner.
+Der Dokumentenbereich stellt trotz seiner Bezeichnung als „Document Explorer" keine navigierbare Ordnerhierarchie dar. Der Benutzer sieht eine flache Liste aller Dokumente; die Typzugehörigkeit wird über Icons und Filter ausgedrückt.
 
-Der Grund liegt im erwarteten Nutzungsverhalten. Ein Kunde sucht in aller Regel ein bestimmtes Dokument — den letzten Monitoring-Report oder einen konkreten Vertrag. Bei einer Hierarchie müsste er zunächst wissen, in welcher Kategorie es abgelegt ist, und sich dorthin durchklicken. Die flache Liste erlaubt es dagegen, unmittelbar zu suchen oder zu filtern. Da die Hierarchie ohnehin nur zwei Ebenen tief ist und die zweite Ebene aus sieben festen Kategorien besteht, wäre der Navigationsaufwand in keinem Verhältnis zum Nutzen gestanden.
+Ein Kunde sucht in der Regel ein bestimmtes Dokument. Bei einer Hierarchie müsste er zunächst die Kategorie kennen und sich dorthin durchklicken. Die flache Liste erlaubt unmittelbares Suchen und Filtern. Da die Hierarchie nur zwei Ebenen mit sieben festen Kategorien umfasst, stünde der Navigationsaufwand in keinem Verhältnis zum Nutzen.
 
-Diese Entscheidung schlug sich auch in der Formulierung der Anforderungen nieder: Die ursprüngliche Beschreibung sprach von Dokumenten als Kacheln, wurde im Verlauf jedoch auf eine Zeilendarstellung in einer Liste geändert. Eine Zeile bietet Platz für Icon, Name, Auswahlbox und Aktionsschaltflächen und lässt sich später um weitere Spalten erweitern.
+Die ursprüngliche Beschreibung sah Dokumentkacheln vor, wurde jedoch auf Zeilendarstellung geändert. Eine Zeile bietet Platz für Icon, Name, Auswahlbox und Aktionsschaltflächen und lässt sich um Spalten erweitern.
 
 \subsection{Aufbau der Seite}
 
@@ -23,15 +23,15 @@ Die Seite gliedert sich von oben nach unten in vier Bereiche:
     \item Eine \textbf{Suchleiste} am oberen Rand, über die nach dem Dokumentnamen gesucht wird.
     \item Darunter eine Reihe von \textbf{Filterelementen}, je eines pro Dokumententyp, mit denen sich Typen ein- und ausblenden lassen.
     \item Die \textbf{Dokumentenliste} als Tabelle. Jede Zeile enthält das Typ-Icon, den Dokumentnamen sowie die Aktionen Herunterladen, Teilen und — bei PDF-Dateien — Vorschau. Eine Auswahlbox am Zeilenanfang dient der Mehrfachauswahl für den ZIP-Download.
-    \item Am unteren Rand die \textbf{Blätterelemente} zum Wechsel zwischen den Seiten sowie die Auswahl der Seitengröße.
+    \item Am unteren Rand die \textbf{Blätterelemente} zum Seitenwechsel sowie die Auswahl der Seitengröße.
 \end{enumerate}
 
-Die Tabellenstruktur wurde bewusst erweiterbar angelegt. In der Feature-Beschreibung ist ausdrücklich festgehalten, dass weitere Spalten — etwa für eine Vorschau oder zusätzliche Auswahlmöglichkeiten — ergänzt werden können, ohne den Aufbau zu verändern.
+Die Tabellenstruktur ist erweiterbar: Weitere Spalten können ergänzt werden, ohne den Aufbau zu verändern.
 
 \subsection{Konsistenz zur bestehenden Anwendung}
 
-Eine durchgängige Vorgabe war, dass sich der Dokumentenbereich wie die übrigen Houston-Seiten bedienen lassen soll (NFA-4). Das betrifft insbesondere die Paginierung, die wie an anderer Stelle eine benutzerseitig wählbare Seitengröße anbietet, und die Suche, die dem gewohnten Verhalten folgen soll.
+Eine durchgängige Vorgabe war, dass sich der Dokumentenbereich wie die übrigen Houston-Seiten bedienen lässt (NFA-4).
 
-Wie genau diese Vorgabe zu verstehen ist, zeigte sich erst im Abnahmetest: Die zunächst umgesetzte Suchleiste blendete nach einer Eingabe eine Schaltfläche zum Leeren des Feldes ein — eine für sich genommen sinnvolle Funktion, die es auf den übrigen Seiten jedoch nicht gibt. Der Unterschied wurde als Fehler gemeldet (siehe Abschnitt~\ref{sec:acceptance-testing}). Das Beispiel verdeutlicht, dass eine Konsistenzanforderung sich nicht vollständig aus einer Beschreibung ableiten lässt, sondern letztlich am Vergleich mit dem Bestand geprüft werden muss.
+Wie genau diese Vorgabe zu verstehen ist, zeigte sich erst im Abnahmetest: Die Suchleiste blendete nach einer Eingabe eine Schaltfläche zum Leeren ein — eine sinnvolle Funktion, die es auf den übrigen Seiten nicht gibt. Der Unterschied wurde als Fehler gemeldet (siehe Abschnitt~\ref{sec:acceptance-testing}). Das Beispiel verdeutlicht, dass eine Konsistenzanforderung am Vergleich mit dem Bestand geprüft werden muss.
 
-Ein zweiter Punkt betrifft das Zusammenspiel von Freigabelinks und Paginierung. Ein Link, der auf ein bestimmtes Dokument verweist, muss auch dann funktionieren, wenn dieses Dokument nicht auf der ersten Seite liegt. Das Konzept sieht deshalb vor, dass der Freigabelink nicht nur das Dokument benennt, sondern beim Weiterleiten auch die passenden Abfrageparameter setzt, sodass die richtige Seite geladen und an die entsprechende Stelle gesprungen wird.
+Ein Freigabelink, der auf ein bestimmtes Dokument verweist, muss auch funktionieren, wenn dieses nicht auf der ersten Seite liegt. Der Link setzt daher beim Weiterleiten die passenden Abfrageparameter, sodass die richtige Seite geladen und an die entsprechende Stelle gesprungen wird.