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/execution/folder-management.tex

@@ -3,36 +3,30 @@
 
 \subsection{Gemeinsame Umsetzung zweier Backlog Items}
 
-Die automatische Anlage der Ordnerstruktur und der neue Kundenordner-Lookup wurden ursprünglich als getrennte Backlog Items geführt und in einem gemeinsamen Pull Request umgesetzt. Der Grund ist in der Beschreibung des Pull Requests festgehalten: Der Lookup benötigt in seiner Rückfallebene ohnehin den Fall, dass kein Ordner existiert und die Struktur angelegt werden muss. Die Ordneranlage getrennt zu implementieren hätte bedeutet, an dieser Stelle zunächst einen Platzhalter einzufügen, um ihn im unmittelbar folgenden Pull Request wieder zu entfernen.
-
-Die Zusammenlegung wurde nicht stillschweigend vorgenommen, sondern in der Beschreibung begründet und beide Items wurden verknüpft. Damit bleibt der Zusammenhang zwischen Planung und Umsetzung nachvollziehbar, auch wenn die Aufteilung nicht eingehalten wurde.
+Die automatische Ordneranlage und der neue Kundenordner-Lookup wurden in einem gemeinsamen Pull Request umgesetzt. Der Lookup benötigt in seiner Rückfallebene den Fall, dass kein Ordner existiert und die Struktur angelegt werden muss. Eine getrennte Implementierung hätte einen Platzhalter erfordert, der im nächsten Pull Request entfernt worden wäre. Die Zusammenlegung wurde begründet und beide Items verknüpft.
 
 \subsection{Normalisierung des Firmennamens}
 
-Der erwartete Ordnername entsteht aus dem Firmennamen des angemeldeten Benutzers. Da dieser Name aus einem Fremdsystem stammt und beliebige Zeichen enthalten kann, wird er zuvor normalisiert. Die Normalisierung entfernt umschließende Leerzeichen, ersetzt Zeichen, die im Schlüssel eine strukturelle Bedeutung haben oder nicht darstellbar sind, verhindert führende und abschließende Punkte und begrenzt die Länge.
+Der erwartete Ordnername entsteht aus dem Firmennamen des Benutzers. Da dieser aus einem Fremdsystem stammt und beliebige Zeichen enthalten kann, wird er normalisiert: umschließende Leerzeichen entfernt, strukturell bedeutsame oder nicht darstellbare Zeichen ersetzt, führende und abschließende Punkte verhindert, die Länge begrenzt.
 
-Zwei Eigenschaften sind dabei entscheidend. Die Normalisierung ist \textbf{deterministisch} — derselbe Eingabename ergibt stets denselben Ordnernamen, was die Voraussetzung dafür ist, dass der Direktzugriff überhaupt funktionieren kann. Und sie erhält \textbf{Umlaute}, weil der Ordner in Filestash von Menschen gelesen wird; die Zumutung, eine Firma „Müller GmbH" unter \texttt{Mueller GmbH} zu suchen, wäre der Bedienbarkeit abträglich.
+Zwei Eigenschaften sind entscheidend. Die Normalisierung ist \textbf{deterministisch} — derselbe Eingabename ergibt stets denselben Ordnernamen, Voraussetzung für den Direktzugriff. Sie erhält \textbf{Umlaute}, weil der Ordner in Filestash von Menschen gelesen wird.
 
-Im Review fragte \emph{Robin Noack}, ob die gewählten Einschränkungen ausreichen. Die Frage ist berechtigt, denn eine zu schwache Normalisierung führt zu Schlüsseln, die der Speicher zurückweist oder anders interpretiert als erwartet — und beides wäre nicht bei der Entwicklung, sondern erst bei einem Kunden mit einem ungewöhnlichen Firmennamen aufgefallen. Die Antwort verwies auf die Herstellerdokumentation zu den Namensbeschränkungen \autocite{ibm-s3-naming, aws-s3-naming}. Der Punkt ist erwähnenswert, weil er zeigt, dass eine solche Zusicherung sich belegen lassen muss und nicht auf einer Vermutung beruhen darf.
+Im Review fragte \emph{Robin Noack}, ob die Einschränkungen ausreichen. Eine zu schwache Normalisierung führt zu Schlüsseln, die der Speicher zurückweist — das wäre erst bei einem Kunden mit ungewöhnlichem Firmennamen aufgefallen. Die Antwort verwies auf die Herstellerdokumentation \autocite{ibm-s3-naming, aws-s3-naming}.
 
 \subsection{Umsetzung des Lookups}
 
-Die in Abschnitt~\ref{sec:lookup-decision} beschriebene dreistufige Auflösung wurde in einer Methode des Dienstes zusammengefasst. Sie ist die einzige Stelle, an der ein Kundenpräfix entsteht; alle übrigen Zugriffe erhalten das Ergebnis als bereits aufgelösten Wert.
+Die in Abschnitt~\ref{sec:lookup-decision} beschriebene dreistufige Auflösung wurde in einer Methode zusammengefasst — der einzigen Stelle, an der ein Kundenpräfix entsteht. Der erste Schritt fragt die Metadaten des erwarteten Markers ab. Der zweite wiederholt dies mit dem um die Organisations-ID ergänzten Namen (Kollisionsfall). Erst der dritte greift auf das lineare Verfahren zurück.
 
-Der erste Schritt fragt die Metadaten des erwarteten Markers ab. Ist er vorhanden und trägt die Organisations-ID des Benutzers, endet die Auflösung. Der zweite Schritt wiederholt dies mit dem um die Organisations-ID ergänzten Namen und deckt damit den Kollisionsfall ab. Erst der dritte Schritt greift auf das ursprüngliche, lineare Verfahren zurück.
-
-Beim Prüfen, ob ein Zielname beansprucht werden darf, wird nicht nur der Marker betrachtet, sondern zusätzlich geprüft, ob unterhalb des Zielpräfixes bereits Objekte liegen. Dazu genügt eine Auflistung, die nach dem ersten Treffer abbricht. Ein Zielname gilt nur dann als frei, wenn dort weder ein fremder Marker liegt noch bereits Inhalte vorhanden sind.
+Beim Prüfen, ob ein Zielname frei ist, wird nicht nur der Marker betrachtet, sondern auch geprüft, ob bereits Objekte unterhalb des Zielpräfixes liegen. Ein Zielname gilt nur als frei, wenn weder ein fremder Marker noch Inhalte vorhanden sind.
 
 \subsection{Umbenennen als Kopiervorgang}
 
-Der Speicher kennt keine Umbenennung. Ein Objekt lässt sich nur unter einem neuen Schlüssel kopieren und anschließend unter dem alten löschen. Für einen Ordner mit vielen Dokumenten bedeutet das entsprechend viele Einzelvorgänge.
+Der Speicher kennt keine Umbenennung. Ein Objekt lässt sich nur kopieren und anschließend löschen. Eine Umbenennung ist daher nicht unteilbar — sie kann abbrechen, und Objekte liegen teils am alten, teils am neuen Ort.
 
-Daraus folgt, dass eine Umbenennung nicht unteilbar ist. Sie kann in der Mitte abbrechen — etwa durch einen Netzwerkfehler —, und dann liegen die Objekte teils am alten, teils am neuen Ort. Die Akzeptanzkriterien verlangten für diesen Fall ausdrücklich, dass keine Dokumente verloren gehen.
+Umgesetzt wurde dies über zwei Maßnahmen. Erstens wird der \textbf{Marker zuletzt kopiert}: Solange er fehlt, wird das Ziel von einer parallelen Anfrage nicht als Kundenordner erkannt. Zweitens entfernt die Fehlerbehandlung bereits erzeugte Teilkopien, damit der Vorgang wiederholbar ist.
 
-Umgesetzt wurde dies über zwei Maßnahmen. Erstens wird der \textbf{Marker zuletzt kopiert}. Solange er fehlt, gilt das Ziel als unvollständig und wird von einer parallelen Anfrage nicht als bestehender Kundenordner erkannt. Der Zielordner wird also erst in dem Moment „gültig", in dem er vollständig ist. Zweitens versucht die Fehlerbehandlung, die bereits erzeugten Teilkopien wieder zu entfernen, damit das Ziel leer bleibt und der Vorgang wiederholbar ist.
-
-Die zweite Maßnahme beruht auf einer Annahme, die sich später als nicht allgemeingültig erwies — sie gilt nur, solange kein zweiter Vorgang dieselbe Umbenennung ausführt. Dieser Fall ist Gegenstand des folgenden Abschnitts.
+Die zweite Maßnahme gilt nur, solange kein zweiter Vorgang dieselbe Umbenennung ausführt. Dieser Fall ist Gegenstand des folgenden Abschnitts.
 
 \subsection{Stand bei Abgabe}
 
-Der zugehörige Pull Request war zum Zeitpunkt der Erstellung dieser Dokumentation noch offen. Die inhaltlichen Anmerkungen aus dem Review waren geschlossen, die abschließende Freigabe stand jedoch aus. Der Abschnitt beschreibt damit — anders als die vorangegangenen — Arbeit, die fachlich fertiggestellt, aber noch nicht in den Hauptbranch übernommen war.
+Der zugehörige Pull Request war zum Zeitpunkt der Erstellung dieser Dokumentation noch offen. Die inhaltlichen Anmerkungen waren geschlossen, die abschließende Freigabe stand aus.