craftvia/docs/_certvia-archiv/DEVOPS-INTEGRATION-RUNBOOK.md

DevOps-Integrations-Runbook — 2-Lane-Entwicklung (Onboarding-Wizard)

Zweck: DevOps übernimmt das Integrieren der Feature-Branches nach dev (Merge, Validierung, Doku-Pflege, Push). Entwickler committen nur auf ihren Feature-Branches und müssen sich um Merge/Konsolidierung nicht mehr kümmern. Basis-Doku: docs/STAND-dev-branch.md (Single Source of Truth), docs/HANDOVER-DEV.md.

---

1. Setup (Ist-Zustand)

• Zwei Git-Worktrees desselben Repos, die sich eine lokale Postgres-DB teilen:
  • ~/Projects/ISMS-Tool → Integrations-Branch dev (hier arbeitet DevOps).
  • ~/Projects/ISMS-Tool-devB → Dev-B-Worktree (Feature-Branch).
• Branch-Modell: Integrationsbranch dev; Feature-Branches mit Bindestrich (dev-a1-wizard-shell, dev-b1-tasks-erweiterung, dev-b2-regel-engine, …). ⚠️ Nicht dev/x verwenden: Git kann nicht gleichzeitig Branch dev und dev/x führen (D/F-Konflikt) — deshalb Bindestrich.
• main ist das spätere Merge-Ziel (hier nicht angefasst).
• Gitea (Remote) ist aktuell zeitweise offline → Pushes erst, wenn erreichbar. Durch das geteilte Repo sehen alle Worktrees ein aktualisiertes dev sofort (ohne Push).

2. Verantwortungs-Split (neu)

Rolle	macht	macht nicht
Entwickler (A/B)	Feature-Branch, kleine Commits je Story, Rebase auf dev vor dem Erzeugen einer Migration	Merge nach dev, Doku-Pflege, Push
DevOps	Merge Feature-Branch → dev, Validierungs-Gate, STAND-dev-branch.md pflegen, Push (wenn Gitea da)	Fachlogik implementieren

3. Integrations-Ablauf (pro fertigem Feature-Branch)

# 0) Im Entwickler-Worktree: sauber & auf dev rebased?
git -C ~/Projects/ISMS-Tool-devB status --porcelain     # leer = sauber

# 1) Ins Integrations-Worktree, auf dev, sauberer Tree
cd ~/Projects/ISMS-Tool
git checkout dev
git status --porcelain                                   # leer = sauber

# 2) Konfliktvorschau (optional)
git merge-tree $(git merge-base dev <feature-branch>) dev <feature-branch> | grep -i "changed in both" || echo "keine Konflikte"

# 3) Nicht-destruktiv mergen (Entwickler-Branch bleibt unangetastet)
git merge --no-ff <feature-branch> -m "Merge <lane>: <Stories> in dev"

Konflikte treten fast nur in den Naht-Dateien auf — additiv auflösen, nie die Ergänzungen der anderen Lane löschen: prisma/schema.prisma · scripts/check-module-guards.ts · messages/de.json/en.json · seed/isms-vorlagenpaket-v2/variables.schema.json.

4. Validierungs-Gate (muss komplett grün sein)

npx prisma generate \
 && npx prisma migrate status \
 && npx tsc --noEmit \
 && npm run lint \
 && npm run build \
 && python3 seed/isms-vorlagenpaket-v2/_verify.py    # nur nötig, wenn seed/variables geändert

• migrate status muss „Database schema is up to date!" melden (sonst → §6).
• build führt den Modul-Guard-Vollständigkeitscheck als prebuild aus.

5. Doku + Branch-Sync + Push

# STAND aktualisieren (Executive-Summary-Lane-Zeilen, Migrations-Liste, Commit-Übersicht)
$EDITOR docs/STAND-dev-branch.md
git add docs/STAND-dev-branch.md
git commit -m "Doku: STAND — <Story> integriert"

# Aktive Feature-Branch-Zeiger auf dev nachziehen (optional, Komfort)
git branch -f dev-a1-wizard-shell dev

# Push NUR wenn Gitea erreichbar:
git fetch                                  # prüfen, ob origin/dev jemand vorausgezogen hat
git push origin dev                        # bei Divergenz NICHT force-pushen — abstimmen

Commit-Konvention: deutsch, granular, Trailer Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>.

6. Bekannte Stolpersteine (durch die geteilte DB)

• Migrations-Timestamp-Diskrepanz nach Rebase: Wird eine Migration im Branch neu erzeugt (neuer Timestamp) und die geteilte DB hat noch die alte angewandt, meldet migrate status „applied ≠ lokal". Fix ohne Datenverlust (kein SQL läuft neu):

  # stalen DB-Eintrag entfernen …
  npx prisma db execute --schema prisma/schema.prisma --stdin <<< \
    "DELETE FROM \"_prisma_migrations\" WHERE migration_name='<ALT_TIMESTAMP>_<name>';"
  # … und die committete Migration als angewandt markieren
  npx prisma migrate resolve --applied <NEU_TIMESTAMP>_<name>
  

• migrate diff --from-config-datasource zeigt Fremd-Änderungen: Da beide Lanes dieselbe DB teilen, will der Diff die Spalten/Objekte der anderen Lane droppen. Beim Erzeugen einer Migration nur die eigenen DDL-Blöcke übernehmen (Entwickler-Aufgabe; DevOps sollte es kennen).
• Neue RBAC-Rechte/Rollen wirken erst nach DB-Grant: Permissions werden beim Login aus der DB aufgelöst. Neue Einträge in ROLE_DEFS brauchen für bestehende Mandanten einen Grant (Re-Seed/Re-Provisioning oder gezieltes SQL). Neue Mandanten bekommen sie automatisch.
• Veraltetes JWT nach Re-Seed: Nach einem Re-Seed zeigen offene Sessions auf alte User-IDs → Screen „Konto deaktiviert". Fix: ab-/neu anmelden (/api/auth/signout) — das JWT wird neu aufgelöst.
• Turbopack-Cache: Nach Rewrites von Server-Actions kann die Browser-Konsole veraltete HMR-Fehler zeigen. Maßgeblich sind tsc/build + preview_logs (Server) — bei Zweifel Dev-Server neu starten.

7. Nicht-destruktive Regeln

• Feature-Branches in dev mergen (--no-ff) — nie die Entwickler-Branches rebasen/umschreiben.
• Einen in einem Worktree ausgecheckten Branch nicht löschen.
• Vollständig gemergte Branches (z. B. dev-b1, sobald dev-b2 gelandet ist) dürfen aufgeräumt (gelöscht) werden — nur wenn nicht ausgecheckt.
• Bei origin/dev-Divergenz kein --force — abstimmen und mergen.

8. Aktueller Stand (zum Zeitpunkt der Runbook-Erstellung)

• dev enthält beide Lanes bis: A1-1, F2, A1-2 (Dev A) und F1, B1, F4 (Dev B), konsolidiert.
• Feature-Branches: dev-a1-wizard-shell (= dev), dev-b2-regel-engine (Dev B, offene Stories).
• Offene Stories: A2 (Scoping + AL zentral), A3, F3+B2 (Regel-Engine), B3 (Fragebogen), B4 (Richtlinien).
• Migrationen auf dev: siehe docs/STAND-dev-branch.md (Liste + Reihenfolge).