msolarczekandClaude Opus 5
c8e6f30a27
Unveränderter Stand von certvia/dev (a48c5fb) plus Craftvia-Spezifikation und Brandbook unter docs/craftvia/. ISMS-Module werden im Folgecommit entfernt. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
120 lines
6.1 KiB
Markdown
120 lines
6.1 KiB
Markdown
# 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).
|