# 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)

```bash
# 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)

```bash
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

```bash
# 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):
  ```bash
  # 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).