Backup

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-27

Tägliche Sicherung aller wichtigen Daten um 03:00 Uhr. Bei Datenverlust oder Fehlkonfiguration kann der Zustand der letzten 7 Tage wiederhergestellt werden.

Was wird gesichert

• etc.tar.gz - /etc Konfigurationen
• www.tar.gz - /var/www Web-Dateien
• mariadb_all.sql.gz - Alle Datenbanken
• qdrant.tar.gz - Vektor-Storage
• ollama.tar.gz - LLM Modelle

Manuelles Backup

/opt/scripts/backup.sh

Restore Beispiele

Einzelne Datei wiederherstellen

# Datei aus www.tar.gz extrahieren
tar -xzf /backup/2025-12-20_03-00/www.tar.gz -C / var/www/dev.campus.systemische-tools.de/src/Controller/HomeController.php

Datenbank wiederherstellen

# Dump entpacken
gunzip /backup/2025-12-20_03-00/mariadb_all.sql.gz

# Alle Datenbanken wiederherstellen
mariadb < /backup/2025-12-20_03-00/mariadb_all.sql

# Einzelne Datenbank extrahieren (aus Dump)
sed -n '/^-- Current Database: `ki_dev`/,/^-- Current Database:/p' mariadb_all.sql > ki_dev.sql

Qdrant Storage wiederherstellen

# Qdrant stoppen
systemctl stop qdrant

# Storage wiederherstellen
tar -xzf /backup/2025-12-20_03-00/qdrant.tar.gz -C /

# Qdrant starten
systemctl start qdrant

Backup-Status prüfen

# Log des letzten Backups
tail -20 /var/log/backup.log

# Backup-Größen
du -sh /backup/*

# Inhalt eines Backups
ls -lh /backup/2025-12-20_03-00/

Cron-Job

Das Backup wird automatisch täglich um 03:00 Uhr ausgeführt.

# /etc/cron.d/backup
0 3 * * * root /opt/scripts/backup.sh >> /var/log/backup.log 2>&1

Verwandte Themen

• Scheduling - Alle automatisierten Tasks
• File Backup Hook - Automatisches Backup bei Dateiänderungen

Scheduling & Automatisierung

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Übersicht aller automatisierten Tasks: Cron-Jobs und Systemd Timer.

Cron-Jobs (/etc/cron.d/)

Backup

Cron-Eintrag

0 3 * * * root /var/www/scripts/backup.sh >> /var/log/backup.log 2>&1

Was wird gesichert

• etc.tar.gz - System-Konfigurationen (/etc)
• www.tar.gz - Web-Dateien (/var/www)
• mariadb_all.sql.gz - Alle Datenbanken
• qdrant.tar.gz - Vektor-Storage
• ollama.tar.gz - LLM Modelle

Retention

Backups älter als 7 Tage werden automatisch gelöscht.

Log prüfen

tail -50 /var/log/backup.log

Mehr Details: Backup-Dokumentation

SSL-Zertifikate (Certbot)

Aktiver Timer

# Status prüfen
systemctl status certbot.timer

# Nächste Ausführung
systemctl list-timers certbot.timer

PHP Session Cleanup

e2scrub_all

Systemd Timer

Übersicht aller Timer

systemctl list-timers --all

Wichtige Timer

Timer-Befehle

# Alle Timer anzeigen
systemctl list-timers --all

# Bestimmten Timer prüfen
systemctl status certbot.timer

# Timer manuell triggern
systemctl start certbot.service

# Timer Logs anzeigen
journalctl -u certbot.service --since today

Scheduling-Zeitplan

Täglicher Ablauf

00:00  dpkg-db-backup (Systemd)
03:00  Backup Script (/var/www/scripts/backup.sh)
05:00  apt-daily (Systemd)
06:00  apt-daily-upgrade (Systemd)
06:25  cron.daily (apache2, apt, dpkg, logrotate)
--:09  PHP Session Cleanup (alle 30 min, Systemd)
--:39  PHP Session Cleanup (alle 30 min, Systemd)
*/12h  Certbot Renewal Check (Systemd)

Wöchentlicher Ablauf

Montag   fstrim (SSD TRIM)
Sonntag  cron.weekly (man-db)
Sonntag  e2scrub_all (Filesystem Check)

Eigene Cron-Jobs erstellen

Methode 1: Datei in /etc/cron.d/

# /etc/cron.d/mein-job
# Format: Minute Stunde Tag Monat Wochentag User Befehl
30 4 * * * root /var/www/scripts/mein-script.sh >> /var/log/mein-job.log 2>&1

Methode 2: Crontab bearbeiten

crontab -e

Cron-Syntax

# ┌───────────── Minute (0-59)
# │ ┌───────────── Stunde (0-23)
# │ │ ┌───────────── Tag des Monats (1-31)
# │ │ │ ┌───────────── Monat (1-12)
# │ │ │ │ ┌───────────── Wochentag (0-7, 0 und 7 = Sonntag)
# │ │ │ │ │
# * * * * * Befehl

# Beispiele:
0 3 * * *     # Täglich um 03:00
*/15 * * * *  # Alle 15 Minuten
0 */2 * * *   # Alle 2 Stunden
0 9 * * 1-5   # Werktags um 09:00
0 0 1 * *     # Am 1. jeden Monats um Mitternacht

Troubleshooting

Cron-Job läuft nicht

# Cron-Daemon Status
systemctl status cron

# Cron Logs prüfen
grep CRON /var/log/syslog | tail -20

# Syntax prüfen
crontab -l

Systemd Timer läuft nicht

# Timer Status
systemctl status timer-name.timer

# Service Logs
journalctl -u service-name.service --since today

# Timer manuell starten
systemctl start service-name.service

Deployment & Rollback

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Synchronisiert Code-Änderungen von der Entwicklungsumgebung zur Produktion. Ermöglicht sicheres Testen auf dev bevor Änderungen live gehen. Bei Problemen kann auf den letzten Stand zurückgerollt werden.

Pre-Deployment Checks

Das Sync-Script führt automatisch alle Quality- und Security-Checks durch. Bei Fehlern wird der Sync abgebrochen.

Check 1: Contract Validation

Script: /var/www/scripts/contract-check.sh

Dokumentation: Contracts

Check 2: PHP Quality Check

Check 3: PHPUnit Tests

Alle Unit-Tests im tests/ Verzeichnis müssen bestehen.

Bei fehlgeschlagenen Checks

# Contract Validation fehlgeschlagen:
❌ SYNC ABGEBROCHEN: Contract Validation fehlgeschlagen
   Behebe die Contract-Violations und versuche es erneut.
   Tipp: /var/www/scripts/contract-check.sh

# PHP Quality Check fehlgeschlagen:
❌ SYNC ABGEBROCHEN: PHP Quality Check fehlgeschlagen
   Behebe die Fehler und versuche es erneut.
   Tipp: /var/www/scripts/php-check.sh /var/www/dev.campus.systemische-tools.de --fix

Deployment ausführen

Standard-Deployment

/var/www/scripts/sync-dev-prod.sh

Erwartete Ausgabe (Erfolg)

=== Sync Dev → Prod: Sat Dec 20 10:00:00 CET 2025 ===

=== Contract Validation ===
[1/6] View Structure Contract v1.0
  OK tasks/*
  OK content/*
...

=== PHP Quality Check ===
[1/4] PHPStan - Static Analysis + Strict Rules
✓ PHPStan: OK
...

=== Summary ===
All checks passed!

=== PHPUnit Tests ===
PHPUnit 12.5.4
✓ All tests passed!

sending incremental file list
...
=== Sync abgeschlossen ===

Was wird synchronisiert

Was wird NICHT synchronisiert

• config/config.php - Umgebungsspezifische Einstellungen (APP_DEBUG=false, DB-Credentials)
• storage/ - Logs, Cache, Sessions
• *.log - Log-Dateien werden via --exclude ausgeschlossen
• public/static-docs/ - Statische Dokumentation

Nach dem Sync

Das Script führt automatisch /var/www/scripts/fix-permissions.sh aus, um die Dateiberechtigungen (www-data:www-data, 755) zu setzen.

Rollback-Verfahren

Bei Problemen nach dem Deployment kann der vorherige Stand aus dem Backup wiederhergestellt werden.

Schritt 1: Backup identifizieren

# Verfügbare Backups anzeigen
ls -la /backup/

Schritt 2: Vollständiger Rollback (prod)

# Prod-Verzeichnis komplett wiederherstellen
cd /
tar -xzf /backup/2025-12-20_03-00/www.tar.gz var/www/prod.campus.systemische-tools.de

# Berechtigungen setzen
/var/www/scripts/fix-permissions.sh

Schritt 3: Datenbank-Rollback (falls nötig)

# Dump entpacken
gunzip -k /backup/2025-12-20_03-00/mariadb_all.sql.gz

# Datenbank wiederherstellen
mariadb < /backup/2025-12-20_03-00/mariadb_all.sql

# Oder einzelne Datenbank:
sed -n '/^-- Current Database: `ki_dev`/,/^-- Current Database:/p' \
    /backup/2025-12-20_03-00/mariadb_all.sql > /tmp/ki_dev.sql
mariadb ki_dev < /tmp/ki_dev.sql

Notfall-Rollback (Schnell)

# Letztes Backup finden
LATEST=$(ls -1d /backup/*/ | tail -1)

# Vollständiger Prod-Rollback
cd / && tar -xzf "${LATEST}www.tar.gz" var/www/prod.campus.systemische-tools.de

# Berechtigungen
/var/www/scripts/fix-permissions.sh

# Verifizieren
curl -I https://campus.systemische-tools.de

Workflow

┌─────────────────────────────────────────────────────────────┐
│                    DEPLOYMENT WORKFLOW                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. ENTWICKLUNG                                              │
│     └── Änderungen auf dev.campus.systemische-tools.de      │
│                          ↓                                   │
│  2. TESTEN                                                   │
│     └── Funktionalität auf dev prüfen                       │
│                          ↓                                   │
│  3. PRE-CHECKS (automatisch)                                │
│     ├── Contract Validation (6 Contracts)                   │
│     ├── PHPStan (Typen, Bugs)                               │
│     ├── PHP-CS-Fixer (Style)                                │
│     ├── Composer Audit (CVEs)                               │
│     ├── Semgrep (Security)                                  │
│     └── PHPUnit (Tests)                                     │
│              ↓ OK              ↓ FAIL                        │
│  4. SYNC                    ABBRUCH                          │
│     └── rsync dev → prod       └── Fehler beheben           │
│              ↓                                               │
│  5. VERIFIZIEREN                                            │
│     └── Produktion prüfen                                   │
│              ↓ OK              ↓ PROBLEM                     │
│        FERTIG              ROLLBACK                          │
│                                └── Aus Backup wiederherstellen│
│                                                              │
└─────────────────────────────────────────────────────────────┘

Checkliste vor Deployment

• Änderungen auf dev getestet?
• Browser-Cache gelöscht beim Testen?
• Keine sensiblen Daten im Code?
• Datenbank-Migrationen berücksichtigt?
• Backup vorhanden? (ls /backup/)

Verwandte Themen

• Backup - Tägliche Sicherung
• Contracts - Contract-System
• PHP-Quality - Qualitätsprüfung

Contracts

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Contracts sind normative YAML-Dokumente, die verbindliche Regeln für Code, Architektur und Dokumentation definieren. Sie ermöglichen automatisierte Validierung und stellen Qualitätsstandards sicher.

Was sind Contracts?

• Normativ: Verbindliche Regeln, keine Empfehlungen
• Maschinenlesbar: YAML-Format für automatisierte Prüfung
• Versioniert: Änderungen erfordern explizite Versionierung
• Validierbar: Klare Pass/Fail-Kriterien

Wann werden Contracts geprüft?

Contract-Management

Contracts werden in der Datenbank verwaltet und sind über Web-UI und MCP-API zugänglich.

Web-UI Features

• /contracts - Liste aller Contracts mit Filter
• /contracts/new - Neuen Contract erstellen
• /contracts/{id} - Contract-Details, YAML-Inhalt, Validierungshistorie
• /contracts/{id}/edit - Contract bearbeiten (erzeugt neue Version)
• Validierung direkt aus der UI auslösen
• Versionshistorie mit Diff-Ansicht

MCP-Tools (mcp-contracts)

Für Details siehe MCP-Contracts Tools.

Aktive Contracts (15)

Severity Levels

Pass-Schwelle

• 0 critical violations (sonst: rejected)
• max 2 major violations (sonst: revision required)
• max 5 minor violations (sonst: approved with notes)

Automatische Validierung

Alle Contracts werden automatisch vor dem Sync zu Produktion geprüft.

Pre-Sync Hook

Manuell ausführen

# Alle Contracts prüfen
/var/www/scripts/contract-check.sh

# Mit spezifischem Pfad
/var/www/scripts/contract-check.sh /var/www/dev.campus.systemische-tools.de

Verwandte Themen

• MCP-Contracts Server - Technische Dokumentation
• Qualität - Quality Gates und Code Hygiene

File Backup Hook

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Automatisches Backup-System, das Dateien in der Datenbank sichert, bevor Claude Code sie mit Edit/Write Tools ändert.

Funktionsweise

Claude Edit/Write → PreToolUse Hook → file_backup_hook.py
                                           │
                                           ▼
                                    Datei existiert?
                                    In BACKUP_DIRS?
                                    Hash geändert?
                                           │
                                           ▼
                              ki_dev.file_backup_history
                              (version++, changed_by='claude-code-hook')

Gesicherte Verzeichnisse

• /var/www/dev.campus.systemische-tools.de/src/
• /var/www/dev.campus.systemische-tools.de/public/
• /var/www/dev.campus.systemische-tools.de/scripts/
• /var/www/dev.campus.systemische-tools.de/includes/
• /var/www/dev.campus.systemische-tools.de/config/
• /var/www/prod.campus.systemische-tools.de/* (analog)

Ausgeschlossene Patterns

• /vendor/, /node_modules/, /.git/
• /backups/, /tmp/, /logs/, /cache/
• .log, .cache, .tmp
• Dateien > 10 MB

Datenbank-Schema

Features

• Hash-Vergleich: Vor jedem Backup wird der aktuelle Hash mit dem letzten verglichen. Bei identischem Hash wird kein neues Backup erstellt.
• Versionierung: Jede Datei hat eine eigene Versionsnummer (1, 2, 3, ...)
• Non-blocking: Der Hook gibt immer {"continue": true} zurück und blockiert nie Claude Code.

Hooks-Konfiguration

In /root/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "/var/www/tools/ki-protokoll/claude-hook/file_backup_hook.py",
          "timeout": 10
        }]
      }
    ]
  }
}

Manueller Test

echo '{"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "/var/www/dev.campus.systemische-tools.de/src/Controller/DocsController.php"}}' | /var/www/tools/ki-protokoll/claude-hook/file_backup_hook.py

Backups abfragen

Mit MCP-DB (empfohlen)

# Letzte Backups anzeigen (via MCP-DB Tool)
# Verwendet automatisch sichere Authentifizierung ohne Passwort-Eingabe

# Bestimmte Datei-History
SELECT version, file_size, changed_at
FROM file_backup_history
WHERE file_path = '/pfad/zur/datei.php'
ORDER BY version DESC;

# Inhalt einer Version
SELECT file_content
FROM file_backup_history
WHERE id = 1;

Mit direktem MySQL (Legacy, nicht empfohlen)

# Hinweis: Direkter mysql-Zugriff erfordert Passwort-Eingabe
# Besser: Verwende MCP-DB Tool für sichere Authentifizierung

mysql -u <username> -p ki_dev -e "SELECT id, file_path, version FROM file_backup_history LIMIT 10;"

Unterschied zu anderen Systemen

Verwandte Module

• Claude Hooks - Übersicht aller Hooks
• System Backup - Tägliche Vollsicherung
• MCP-DB - Datenbank-Zugriff

Claude Hooks

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-27

Python-Hooks für Claude Code Integration mit Protokollierung, Backup, Task-Erstellung, Workflow-Validierung und Architektur-Guards.

Übersicht

Prozess-Dokumentation: Claude Pre-/Post-Hook Prozess

log_to_db.py

Protokolliert alle Claude Code Events in der Datenbank.

Features

• Request/Response-Pairing: PreToolUse → PostToolUse werden verknüpft
• Duration-Tracking: Millisekunden-genaue Zeiterfassung
• Token-Schätzung: ~4 Zeichen = 1 Token
• Sensible Daten: Automatische Maskierung (Passwörter, API-Keys, JWTs)
• Session-Tracking: Temporäre Dateien in /tmp/claude_hooks/

Verarbeitete Events

Datenbank-Tabelle

ki_dev.protokoll
├── id, timestamp
├── request_ip, client_name
├── request, request_timestamp
├── response, response_timestamp
├── duration_ms
├── tokens_input, tokens_output, tokens_total
├── model_name, status

file_backup_hook.py

Sichert Dateien automatisch BEVOR sie geändert werden.

Trigger

• PreToolUse → Edit
• PreToolUse → Write

Backup-Verzeichnisse

/var/www/dev.campus.systemische-tools.de/src
/var/www/dev.campus.systemische-tools.de/public
/var/www/dev.campus.systemische-tools.de/scripts
/var/www/dev.campus.systemische-tools.de/config
/var/www/prod.campus.systemische-tools.de/src
...

Features

• Versionierung: Automatische Version pro Datei
• Hash-Prüfung: Skip bei unveränderter Datei
• Größenlimit: Max 10 MB pro Datei
• Non-Blocking: Hook blockiert nie

Datenbank-Tabelle

ki_dev.file_backup_history
├── id, file_path, version
├── file_content, content_hash, file_size
├── change_type, changed_by, reason
├── created_at

task_hook.py

Erstellt automatisch Tasks aus Patterns in User-Prompts.

Erkannte Patterns

TODO: <text>    → Task erstellen
TASK: <text>    → Task erstellen
@task <text>    → Task erstellen
#task <text>    → Task erstellen

task_completion_guard.py

Blockiert tasks_status(completed) wenn kein Result existiert. Erzwingt korrekten Workflow.

Trigger

• PreToolUse → mcp__mcp-tasks__tasks_status
• Nur bei status="completed"

Prüflogik

1. Prüft ob status == "completed"
2. DB-Query: SELECT COUNT(*) FROM task_results WHERE task_id = ?
3. Wenn count = 0 → Block mit Exit-Code 2

Details: Task-Completion Guard Prozess

block_direct_db.py

Blockiert direkte Datenbank-Zugriffe via Bash. Erzwingt Nutzung von MCP-DB.

Trigger

• PreToolUse → Bash
• Prüft Command auf mysql/mariadb-Patterns

Blockierte Patterns

mysql ...
mariadb ...
sudo mysql ...
sudo mariadb ...

Erlaubt

MCP-Tools: mcp__mcp-db__db_select, mcp__mcp-db__db_insert, etc.

architecture_guard.py

Prüft Architektur-Regeln bei PHP-Datei-Erstellung.

Trigger

• PreToolUse → Write (*.php)

Geprüfte Regeln

• Layer-Grenzen (Controller darf nicht direkt auf Repository zugreifen)
• Namespace-Konventionen
• Dependency Injection Patterns

hook_dispatcher.py

Zentraler Dispatcher für Quality-Gates. Lädt Regeln dynamisch.

Trigger

• PreToolUse → Write (BLOCK-Regeln)
• PostToolUse → Write, Edit (WARN-Regeln)

Quality-Regeln

quality/
├── pre_rules.py        ← BLOCK-Regeln
├── post_rules.py       ← WARN-Regeln
└── task_creator.py     ← Violations → Tasks

Details: Quality Gates

Konfiguration

Hooks werden in /root/.claude/settings.json registriert:

{
  "hooks": {
    "UserPromptSubmit": [...],
    "PreToolUse": [
      {"matcher": "Bash", "hooks": [...]},
      {"matcher": "mcp__mcp-tasks__tasks_status", "hooks": [
        {"type": "command", "command": ".../task_completion_guard.py", "timeout": 5}
      ]},
      {"matcher": "Edit|Write", "hooks": [...]},
      {"matcher": "", "hooks": [...]}
    ],
    "PostToolUse": [...]
  }
}

Environment-Variablen

In .env im Hook-Verzeichnis:

CLAUDE_DB_HOST=localhost
CLAUDE_DB_PORT=3306
CLAUDE_DB_USER=root
CLAUDE_DB_PASSWORD=***
CLAUDE_DB_NAME=ki_dev

Verwandte Themen

• Claude Hooks Prozess - Ablaufdiagramme und Workflow
• Quality Gates - Code-Qualitätsprüfung
• File Backup Hook - Detaillierte Backup-Dokumentation

DB Hooks

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Security-Hooks die direkte Datenbankzugriffe blockieren und MCP-Server erzwingen.

Übersicht

block_direct_db.py

Verhindert Bash-Befehle mit direktem Datenbank-Login.

Blockierte Patterns

mysql -u user -ppassword
mariadb -u user -p
mysql --password=xxx
mariadb --password=xxx

Fehlermeldung

BLOCKIERT: Direkte Datenbankzugriffe sind aus Sicherheitsgründen nicht erlaubt.

Verwende stattdessen die MCP-DB Tools:
  - db_select(query, params)  : SELECT-Abfragen ausführen
  - db_schema()               : Datenbank-Schema anzeigen
  - db_stats()                : Statistiken abrufen

Vorteile von MCP-DB:
  - Keine Credentials im Code/Verlauf
  - Automatische Query-Validierung
  - SQL-Injection Schutz
  - Audit-Logging aller Abfragen
  - Enforced Read-Only Zugriff

block_direct_task_db.py

Verhindert direkte SQL-Operationen auf Task-Tabellen.

Blockierte Patterns

INSERT INTO tasks ...
UPDATE tasks SET ...
DELETE FROM tasks ...
INSERT INTO task_assignments ...
UPDATE task_results ...
DELETE FROM task_comments ...

Fehlermeldung

BLOCKIERT: Direkte SQL-Operationen auf Task-Tabellen sind nicht erlaubt.

Verwende stattdessen die MCP-Tasks Tools:
  - tasks_list()              : Tasks auflisten
  - tasks_create(title, ...)  : Task erstellen
  - tasks_get(id)             : Task-Details abrufen
  - tasks_update(id, ...)     : Task aktualisieren
  - tasks_status(id, status)  : Status ändern
  - tasks_assign(id, ...)     : Task zuweisen
  - tasks_result(id, ...)     : Ergebnis speichern
  - tasks_execute(id, model)  : Mit Ollama ausführen

block_password_exposure.py

Verhindert Passwort-Exposition in Bash-Commands. Passwörter im Klartext sind sichtbar in ps aux, /proc/*/cmdline, bash_history und Logs.

Blockierte Patterns

DB_PASSWORD="wert"
MARIADB_ROOT_PASSWORD="wert"
API_KEY="wert"
TOKEN="wert"
SECRET="wert"
--password=wert

Erlaubte Patterns

$DB_PASSWORD              # Variable verwenden
${DB_PASSWORD}            # Variable verwenden
DB_PASSWORD=""            # Leere Zuweisung
get_db_password()         # Getter-Funktion

Fehlermeldung

BLOCKIERT: Passwort-Exposition im Bash-Command erkannt!

RICHTIG: Passwort aus Environment laden
  ./venv/bin/python script.py
  # Script lädt Passwort via get_db_password()

FALSCH:
  DB_PASSWORD="xxx" ./venv/bin/python script.py

Verhalten

Erfolg (erlaubt)

{
  "allowed": true,
  "message": ""
}
Exit Code: 0

Blockiert

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "BLOCKIERT: ..."
  }
}
Exit Code: 1

Fehler (Fail-Open)

{
  "allowed": true,
  "message": "Hook error (fail-open): ..."
}
Exit Code: 0

Konfiguration

In /root/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {"type": "command", "command": "/var/www/scripts/hooks/block_direct_db.py"},
          {"type": "command", "command": "/var/www/scripts/hooks/block_direct_task_db.py"},
          {"type": "command", "command": "/var/www/scripts/hooks/block_password_exposure.py"}
        ]
      }
    ]
  }
}

Sicherheitskonzept

┌─────────────────────────────────────────────┐
│  Claude Code                                │
│  └─ Bash Tool → mysql -u root -p...         │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│  PreToolUse Hook                            │
│  ├─ block_direct_db.py                      │
│  ├─ block_direct_task_db.py                 │
│  └─ block_password_exposure.py              │
│     └─ Pattern Match? → BLOCK (Exit 1)      │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│  MCP-Server (stattdessen)                   │
│  ├─ MCP-DB: db_select(), db_schema()        │
│  └─ MCP-Tasks: tasks_*(), quality_*()       │
└─────────────────────────────────────────────┘

Verwandte Dokumentation

• MCP-DB Server
• MCP-Tasks Server
• Claude Hooks

Contract-Enforcement-System

Erstellt: 2025-12-22 | Aktualisiert: 2025-12-27

Das Enforcement-System stellt sicher, dass alle Code-Qualitätsstandards und Architektur-Regeln automatisch durchgesetzt werden.

Architektur-Übersicht

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Contracts     │────▶│    Validator    │────▶│     Hooks       │
│  (YAML in DB)   │     │ (contract-check)│     │ (Python Scripts)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP-Contracts  │     │  sync-dev-prod  │     │   Claude Code   │
│    (API)        │     │    (Workflow)   │     │  (PreToolUse)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Komponenten

1. Contracts (Datenbank)

Contracts sind in ki_protokoll.contracts gespeichert und definieren Regeln im YAML-Format.

2. Validator (contract-check.sh)

Führt Contract-Validierungen aus:

/opt/scripts/contract-check.sh /var/www/dev.campus.systemische-tools.de

3. Hooks (PreToolUse)

Blockieren Architektur-Verletzungen BEVOR Code geschrieben wird:

Workflow

Pre-Sync Validierung

1. Contract-Check: Alle Contracts werden validiert
2. PHP Quality: PHPStan, PHP-CS-Fixer, Semgrep
3. Unit Tests: PHPUnit ausführen
4. Entscheidung: Critical=Block, Major=Warn, Minor=Log

PreToolUse Hooks

1. Claude Code ruft Write/Edit/Bash auf
2. Hook prüft Content/Command
3. Bei Violation: Exit 2 → Block + Fehlermeldung
4. Bei OK: Exit 0 → Durchlassen

MCP-Tools

contracts_list

contracts_list(compact=True)

Listet alle Contracts auf.

contracts_validate

contracts_validate(name="code-quality-standards")

Validiert einen Contract gegen die Codebase.

contracts_create/update

contracts_create(name="...", yaml_content="...", version="1.0")

Erstellt oder aktualisiert einen Contract.

Troubleshooting

"Mein Code wird blockiert"

1. Prüfe welcher Hook blockiert (Fehlermeldung)
2. Prüfe welche Regel verletzt wird
3. Behebe das Problem (z.B. Service extrahieren statt PDO in Controller)

"Contract-Validierung findet nichts"

1. Prüfe ob Contract aktiv ist: contracts_get(name="...")
2. Prüfe Scope-Pfade im Contract
3. Prüfe ob Dateien existieren

"Sync wird blockiert"

1. Führe /opt/scripts/contract-check.sh aus
2. Prüfe Critical/Major Violations
3. Behebe alle Critical-Violations
4. Major-Violations können als Baseline akzeptiert werden

Baseline für Legacy-Code

Aktuell akzeptierte Legacy-Violations (nicht für neue Code):

• SemanticExplorerRepository.php: 797 LOC
• SystemExplorerRepository.php: 709 LOC
• ChunkSyncService.php: 551 LOC

Neue Violations in diesen Dateien werden trotzdem blockiert.

Architektur

Erstellt: 2025-12-27 | Aktualisiert: 2025-12-31

Clean Architecture Übersicht für das Campus-System. Strikte Trennung zwischen Backend (MVC), Frontend (MVP) und Infrastruktur.

Backend-Architektur (MVC)

Pfad: /src/

Layer-Regeln

Controller → UseCase → Repository (via Interface)
     ↓          ↓              ↓
   Request   Business     Infrastructure
   Handler    Logic         (MySQL, API)

VERBOTEN:
- Controller → Repository direkt (muss über UseCase)
- UseCase → Infrastructure konkret (nur Interface)
- View → Database (niemals)

Frontend-Architektur (MVP)

Pfad: /app/

MVP-Prinzip

• Model: Domain-Entities (aus /src/Domain)
• View: Passive Templates, keine Logik
• Presenter: Bereitet Daten für View auf, enthält UI-Logik

Datenbanken

Zugriff

Kein direkter SQL-Zugriff! Immer über MCP-DB:

mcp__mcp-db__db_select(query, database="ki_dev")
mcp__mcp-db__db_insert(table, data, database="ki_content")

Verzeichnisstruktur

/var/www/dev.campus.systemische-tools.de/
├── app/                    # Frontend (MVP)
│   ├── Presenter/          # UI-Logik
│   └── View/               # Passive Views
├── bin/                    # CLI-Binaries
├── cli/                    # CLI-Commands
├── composer.json           # PHP Dependencies
├── composer.lock           # Lock-File
├── config/                 # Konfiguration
│   ├── config.php          # App-Config
│   ├── autoload.php        # PSR-4 Autoloader
│   ├── database.php        # DB-Config
│   └── profiles/           # Author-Profile
├── contracts/              # Architecture Contracts (YAML)
├── database/               # Migrations, Seeds
├── docs/                   # Projekt-Dokumentation
├── phpstan.neon            # PHPStan Config
├── phpstan-baseline.neon   # PHPStan Baseline
├── .php-cs-fixer.dist.php  # PHP-CS-Fixer Config
├── public/                 # Web-Root
│   ├── index.php           # Entry Point
│   ├── css/                # Stylesheets
│   ├── js/                 # JavaScript
│   ├── images/             # Bilder
│   └── static-docs/        # Statische Docs
├── routes/                 # Route-Definitionen
│   ├── web.php             # Web-Routes
│   └── api.php             # API-Routes
├── src/                    # Backend (MVC)
│   ├── Framework/          # App, Router, Controller-Base
│   ├── Controller/         # HTTP Controller
│   ├── Domain/             # Entity, Repository-Interfaces
│   ├── UseCases/           # Anwendungsfälle
│   ├── Infrastructure/     # DB, External Services
│   └── View/               # Server-Templates
├── storage/                # Logs, Cache, Sessions
│   ├── logs/               # Application Logs
│   ├── cache/              # Cache-Dateien
│   └── sessions/           # PHP-Sessions
├── tests/                  # Unit-Tests
│   └── Unit/               # PHPUnit Tests
└── vendor/                 # Composer Dependencies

Dependency Injection

Der DI-Container in /src/services.php bindet Interfaces an Implementierungen:

// Interface → Implementation
TaskRepositoryInterface::class => TaskRepository::class
OllamaServiceInterface::class => OllamaService::class

// Controller bekommt Dependencies via Constructor
class TaskController extends Controller {
    public function __construct(
        private TaskRepositoryInterface $taskRepository,
        private CreateTaskUseCase $createTask
    ) {}
}

Request-Lifecycle

1. Request → public/index.php
2. App::bootstrap() → Autoload, Config, DI-Container
3. Router::dispatch() → Route matchen
4. Controller::action() → UseCase aufrufen
5. UseCase → Repository → Database
6. View::render() → HTML Response
7. Response → Browser

Code-Analyse

Vor Refactoring immer MCP-Code nutzen:

# Klasse finden
mcp__mcp-code__code_search("TaskController")

# Dependencies prüfen
mcp__mcp-code__code_dependencies("Controller\\TaskController")

# Impact vor Änderung
mcp__mcp-code__code_impact("Domain\\Entity\\Task")

Verwandte Themen

• Regeln - Entwicklungs-Regeln
• PHP-Quality - Code-Qualität
• MCP-Code - Code-Analyse Tools
• MCP-DB - Datenbankzugriff

Regeln

Erstellt: 2025-12-27 | Aktualisiert: 2025-12-27

Verbindliche Entwicklungs- und Betriebsregeln für das Campus-System. Diese Regeln werden durch Hooks und Quality-Gates durchgesetzt.

1. Kein Git

2. MCP nutzen

Statt:

mysql -u root -p ki_dev -e "SELECT * FROM tasks"

Verwende:

mcp__mcp-db__db_select("SELECT * FROM tasks", database="ki_dev")

Verfügbare MCP-Server

3. Dev first

Umgebungen

4. Quality vor Sync

Quality-Checks

• PHPStan: Typen, Null-Safety, Bugs
• PHP-CS-Fixer: PSR-12 Code Style
• Composer Audit: Dependency CVEs
• Semgrep: OWASP Security
• Contracts: Architecture + View-Struktur

Manuell prüfen

/var/www/scripts/php-check.sh /var/www/dev.campus.systemische-tools.de

5. Task-Pflicht

Workflow

# 1. Task erstellen
tasks_create(title="Feature X implementieren", type="ai_task")

# 2. Status setzen
tasks_status(id=123, status="in_progress")

# 3. Arbeit dokumentieren
tasks_result(id=123, response="...", executor="claude", executor_type="claude")

# 4. Abschließen
tasks_status(id=123, status="completed")

6. Layer-Grenzen

Erlaubt

// Controller → UseCase → Repository
$this->createTaskUseCase->execute($data);

Verboten

// Controller → Repository direkt
$this->taskRepository->save($task);

7. HTMX statt fetch()

Beispiel

<button hx-post="/tasks/123/complete"
        hx-headers='{"X-CSRF-TOKEN": "..."}'
        hx-confirm="Wirklich abschließen?">
    Abschließen
</button>

Zusammenfassung

Verwandte Themen

• Architektur - System-Architektur
• Claude Hooks - Hook-System
• Deployment - Sync-Prozess
• Quality Gates - Code-Qualität