feat(bausteine): Abschnitte, die mehrere Vorlagen teilen (#57)

docs/anleitung/04-vorlagen.md

@@ -190,6 +190,55 @@ und für `{{generiertes_passwort}}` entsteht **kein** Passwort — dort steht
 Nutz sie vor dem Veröffentlichen, besonders bei Befehlen: erst hier sieht man, ob der fertige Befehl
 so aussieht, wie er aussehen soll.
 
+## Bausteine: ein Abschnitt für mehrere Vorlagen
+
+„Datensicherung prüfen“ steht in vier der sieben mitgelieferten Vorlagen, wortgleich. Wer den Ablauf
+ändert, ändert ihn viermal — oder dreimal und vergisst den vierten. Ein **Baustein** ist ein
+Abschnitt, den mehrere Vorlagen teilen und der an einer Stelle gepflegt wird.
+
+Die Liste steht hinter dem Knopf **Bausteine** oben auf der Vorlagenseite. Ein Baustein wird dort
+angelegt (nur ein Name), bekommt dann einen Titel und seine Schritte, und wird **veröffentlicht** —
+genau wie eine Vorlage, mit denselben Regeln: höchstens ein Entwurf, und eine veröffentlichte
+Fassung wird nie wieder verändert.
+
+### Einsetzen
+
+Im Editor einer Vorlage steht unten neben **Abschnitt hinzufügen** das Feld **Baustein einsetzen**.
+Angeboten werden nur veröffentlichte Fassungen nicht archivierter Bausteine. Der Abschnitt erscheint
+dann als Einheit: mit dem Kennzeichen „Baustein“, dem Namen der Quelle und der Zahl seiner Schritte.
+
+**Titel und Schritte lassen sich dort nicht ändern.** Beides kommt beim Veröffentlichen aus dem
+Baustein — ein Feld, das man ausfüllen kann und das danach überschrieben wird, wäre eine Falle.
+Geändert wird am Baustein.
+
+### Was eine Änderung am Baustein bewirkt — und was nicht
+
+Das ist der Punkt, den man einmal verstanden haben muss:
+
+- **Schon veröffentlichte Vorlagenversionen ändern sich nicht.** Sie tragen beim Veröffentlichen
+  eingesetzte **Kopien** der Schritte. Ein Lauf von vor zwei Jahren zeigt genau das, was damals
+  abgearbeitet wurde — daran ändert kein Baustein etwas.
+- **Laufende Arbeiten ändern sich nicht.** Aus demselben Grund.
+- **Die neue Fassung wirkt in der nächsten veröffentlichten Version** einer Vorlage. Wer sie dort
+  haben will, legt einen neuen Entwurf an und veröffentlicht ihn.
+
+Auf der Seite eines Bausteins steht unter **Wo er steckt**, in welchen Vorlagen er vorkommt und
+welche **Fassung** dort eingesetzt ist. Vor einer Änderung ist das die Liste, die man lesen will.
+
+### Archivieren
+
+Gelöscht wird ein Baustein nie: veröffentlichte Vorlagenversionen tragen seine Herkunft. Archiviert
+lässt er sich nicht mehr neu einsetzen, bleibt aber in jeder Vorlage lesbar, die ihn schon benutzt.
+Steht er noch in einem **Entwurf**, weist Laufzettel das Archivieren ab — diese Vorlage ließe sich
+danach nicht mehr veröffentlichen.
+
+### In einer Austauschdatei steht kein Baustein
+
+Ein Export trägt die **aufgelösten** Schritte, keinen Verweis. Eine Kennung aus dieser Installation
+bedeutet in einer anderen nichts, und ein Verweis auf einen Baustein, den es dort nicht gibt, wäre
+eine Vorlage, die sich nicht veröffentlichen lässt. Wer einen Baustein mitgeben will, exportiert die
+Vorlage und legt den Baustein in der anderen Installation neu an.
+
 ## Veröffentlichen
 
 Im Abschnitt **Veröffentlichen** trägst du eine **Änderungsnotiz (optional)** ein — ein Satz, was

docs/issues/030-bausteine.md

@@ -1,10 +1,10 @@
 # #030 M17 – Wiederverwendbare Bausteine
 
-**Status:** offen
+**Status:** erledigt
 **Im Tracker:** [#50](https://git.wilde-server.de/florian.wilde/Laufzettel/issues/50)
 **Meilenstein:** v0.2.0
 **Labels:** phase-2, backend, frontend
-**Geschätzt:** 12 h   **Tatsächlich:** –
+**Geschätzt:** 12 h   **Tatsächlich:** 2 h 25 min
 
 ## Ziel
 
@@ -20,7 +20,7 @@ wurden. Ein Baustein, der sich ändert, darf das nicht antasten.
 
 ## Zu entscheiden
 
-- [ ] **Baustein mit eigener Version, beim Veröffentlichen tief kopiert** — Empfehlung. Ein
+- [x] **Baustein mit eigener Version, beim Veröffentlichen tief kopiert** — Empfehlung. Ein
       Entwurf **verweist** auf einen Baustein; beim Veröffentlichen löst der Dienst den Verweis in
       echte Abschnitte und Schritte auf. Damit bleibt alles, was danach kommt, unberührt: `Lauf`,
       `Schrittergebnis`, Druckansicht und Archiv sehen weiterhin konkrete Schritte und müssen nichts
@@ -28,32 +28,55 @@ wurden. Ein Baustein, der sich ändert, darf das nicht antasten.
       Die Alternative — Läufe verweisen zur Laufzeit auf den Baustein — hieße, dass die Unveränder-
       lichkeit an einer zweiten Stelle durchgesetzt werden muss, und dass jede Abfrage über Schritte
       zwei Wege kennen muss. Das ist der Preis für eine Bequemlichkeit, die niemand verlangt hat.
-- [ ] **Was „Baustein aktualisieren“ für laufende Arbeiten bedeutet:** nichts. Eine neue
+- [x] **Was „Baustein aktualisieren“ für laufende Arbeiten bedeutet:** nichts. Eine neue
       Baustein-Version wirkt erst in der **nächsten** veröffentlichten Vorlagenversion. Das muss die
       Oberfläche sagen, sonst erwartet man Durchschlag.
 
 ## Aufgaben
 
-- [ ] Modelle `Baustein` und `BausteinVersion` mit denselben Regeln wie bei Vorlagen: höchstens ein
+- [x] Modelle `Baustein` und `BausteinVersion` mit denselben Regeln wie bei Vorlagen: höchstens ein
       Entwurf, veröffentlichte Version unveränderlich (Trigger, nicht nur Dienst)
-- [ ] `VorlagenAbschnitt` kann statt eigener Schritte einen Baustein nennen — nur im **Entwurf**
-- [ ] Veröffentlichen löst auf: tiefe Kopie der Baustein-Abschnitte und -Schritte in die Version,
+- [x] `VorlagenAbschnitt` kann statt eigener Schritte einen Baustein nennen — nur im **Entwurf**
+- [x] Veröffentlichen löst auf: tiefe Kopie der Baustein-Abschnitte und -Schritte in die Version,
       mit Vermerk, aus welchem Baustein und welcher Version sie stammen
-- [ ] Editor: Baustein einfügen, als Einheit anzeigen, nicht Schritt für Schritt bearbeitbar; ein
+- [x] Editor: Baustein einfügen, als Einheit anzeigen, nicht Schritt für Schritt bearbeitbar; ein
       Hinweis nennt Baustein und Version
-- [ ] Eigene Verwaltung für Bausteine, Recht `vorlagenBearbeiten` (wer Vorlagen pflegt, pflegt
+- [x] Eigene Verwaltung für Bausteine, Recht `vorlagenBearbeiten` (wer Vorlagen pflegt, pflegt
       Bausteine)
-- [ ] „Wo wird dieser Baustein benutzt“ — vor dem Ändern will man das wissen
-- [ ] Anleitung Kapitel 04
+- [x] „Wo wird dieser Baustein benutzt“ — vor dem Ändern will man das wissen
+- [x] Anleitung Kapitel 04
 
 ## Akzeptanzkriterien
 
-- [ ] Test: eine neue Baustein-Version ändert **keine** veröffentlichte Vorlagenversion und **keinen**
+- [x] Test: eine neue Baustein-Version ändert **keine** veröffentlichte Vorlagenversion und **keinen**
       laufenden Lauf
-- [ ] Test: die Druckansicht eines archivierten Laufs ist nach einer Baustein-Änderung Zeichen für
+- [x] Test: die Druckansicht eines archivierten Laufs ist nach einer Baustein-Änderung Zeichen für
       Zeichen dieselbe
-- [ ] Test: die nächste veröffentlichte Vorlagenversion enthält die neue Baustein-Version
-- [ ] Test: ein Baustein lässt sich nicht löschen, solange eine Vorlage ihn im Entwurf nennt
-- [ ] Test: Export und Import einer Vorlage mit Baustein ergeben eine inhaltsgleiche Vorlage — die
+- [x] Test: die nächste veröffentlichte Vorlagenversion enthält die neue Baustein-Version
+- [x] Test: ein Baustein lässt sich nicht löschen, solange eine Vorlage ihn im Entwurf nennt
+- [x] Test: Export und Import einer Vorlage mit Baustein ergeben eine inhaltsgleiche Vorlage — die
       Datei trägt die aufgelösten Schritte, keinen Verweis auf einen Baustein, den die andere
       Installation nicht hat
+
+## Beim Umsetzen dazugekommen
+
+- **Ein Baustein ist genau ein Abschnitt**, nicht eine Gruppe davon. Das stand so im Auftrag
+  („Abschnitte, die mehrere Vorlagen teilen“) und spart eine Verschachtelungsebene, die niemand
+  gebraucht hätte.
+- **Der Verweis bleibt nach dem Veröffentlichen stehen** und ist dann nur noch Herkunft. Welche der
+  beiden Lesarten gilt, sagt der Status der Version — ein zweites Feld dafür wäre eine zweite
+  Wahrheit. Die Seite eines Bausteins liest daraus „Wo er steckt“, mit der Fassung je Vorlage.
+- **Der Titel kommt aus dem Baustein**, nicht aus dem Abschnitt der Vorlage. Sonst müsste man ihn in
+  jeder Vorlage einzeln pflegen, und zwei Vorlagen zeigten denselben Baustein unter verschiedenen
+  Namen.
+- **Vier Garantien liegen in der Datenbank**, nicht nur im Dienst: höchstens ein Entwurf (partieller
+  Index), eine veröffentlichte Fassung ist unveränderlich (Trigger), der Weg zurück zum Entwurf ist
+  versperrt (Trigger), und ein Abschnitt kann nur auf eine **veröffentlichte** Fassung verweisen
+  (Trigger). Beim Aufräumen der Testdaten hat der zweite sofort zugeschlagen — gut so.
+- **Das Durchklicken des gebauten Stands fand einen Fehler**, den die Suite nicht gesehen hätte:
+  `neuerBausteinAbschnitt` legt Platzhalter-Schritte **ohne Titel** an, damit die Anzahl in der Karte
+  stimmt. `alsStruktur` schickte sie mit, und `SchrittSchema` wies den ganzen Entwurf ab — das
+  Speichern scheiterte. Behoben, mit Test und Gegenprobe.
+- Dabei habe ich **zweimal mein eigenes Prüfskript** für den Fehler gehalten: einmal griff ein zu
+  weiter `role=status`-Selektor den falschen Text, einmal eine Prüfung nach dem Neuladen. Die
+  Datenbank hat beides geklärt — sie ist der einzige Zeuge, der nicht lügt.

docs/issues/README.md

@@ -34,10 +34,10 @@ Diese Dateien sind die Quelle; `pnpm issues:sync` spiegelt sie in den Gitea-Trac
 | #027 | [Die Editor-Abläufe lassen ihre Vorlagen stehen](027-e2e-reste-vorlagen.md) | offen | v0.2.0 | 1 h | – |
 | #028 | [M15 – Quellenarten und Microsoft-Graph-Quelle](028-graph-quelle.md) | offen | v0.2.0 | 10 h | – |
 | #029 | [M16 – SCIM-Endpunkt als Alternative zum Abgleich](029-scim-endpunkt.md) | offen | v0.2.0 | 12 h | – |
-| #030 | [M17 – Wiederverwendbare Bausteine](030-bausteine.md) | offen | v0.2.0 | 12 h | – |
+| #030 | [M17 – Wiederverwendbare Bausteine](030-bausteine.md) | erledigt | v0.2.0 | 12 h | 2 h 25 min |
 | #031 | [M18 – Abteilungsspezifische Zusatzabschnitte](031-abteilungsabschnitte.md) | offen | v0.2.0 | 8 h | – |
 | #032 | [M19 – Anhänge und Fotos an Schritten](032-anhaenge.md) | offen | v0.2.0 | 10 h | – |
 | #033 | [M20 – Live-Aktualisierung per SSE statt Polling](033-sse-live.md) | offen | v0.2.0 | 6 h | – |
 | #034 | [M21 – Benachrichtigungen per Mail und Webhook](034-benachrichtigungen.md) | offen | v0.2.0 | 10 h | – |
 | #035 | [M22 – Mitarbeiter-Selbstauskunft](035-selbstauskunft.md) | offen | v0.2.0 | 8 h | – |
-| | **Summe** | | | **229 h** | **41 h 20 min** |
+| | **Summe** | | | **229 h** | **43 h 45 min** |