AFC-Demo/docs/developer-setup-guide.md

# Entwickler-Setup-Guide: Risk Intelligence Platform

## 📋 Inhaltsverzeichnis

1. [Voraussetzungen](#voraussetzungen)
2. [Schnellstart](#schnellstart)
3. [Detaillierte Installation](#detaillierte-installation)
4. [Datenbank-Setup](#datenbank-setup)
5. [Environment-Konfiguration](#environment-konfiguration)
6. [Frontend-Assets](#frontend-assets)
7. [Erste Schritte](#erste-schritte)
8. [Development-Workflow](#development-workflow)
9. [Troubleshooting](#troubleshooting)
10. [Nützliche Commands](#nützliche-commands)

---

## Voraussetzungen

### Erforderliche Software

| Software | Mindestversion | Empfohlen | Installation |
|----------|---------------|-----------|--------------|
| **PHP** | 8.2 | 8.4.14+ | [Laravel Herd](https://herd.laravel.com) |
| **Composer** | 2.0 | Latest | Via Herd oder [getcomposer.org](https://getcomposer.org) |
| **Node.js** | 18.x | 20.x+ | [nodejs.org](https://nodejs.org) |
| **npm** | 9.x | Latest | Mit Node.js installiert |
| **PostgreSQL** | 14.x | 16.x+ | [postgresql.org](https://www.postgresql.org) |
| **Git** | 2.x | Latest | [git-scm.com](https://git-scm.com) |

### Empfohlene Tools

- **Laravel Herd** - Lokale PHP-Entwicklungsumgebung (macOS)
- **TablePlus** / **pgAdmin** - PostgreSQL GUI
- **VS Code** - Editor mit PHP/Laravel Extensions
- **Postman** / **Insomnia** - API Testing (optional)

### PHP Extensions

Folgende PHP Extensions werden benötigt:

```bash
# Prüfe installierte Extensions
php -m

# Benötigte Extensions:
- pdo_pgsql      # PostgreSQL Driver
- mbstring       # Multibyte String
- xml            # XML Support
- curl           # HTTP Client
- bcmath         # Precision Math
- fileinfo       # File Information
- json           # JSON Support
- openssl        # Encryption
- tokenizer      # PHP Tokenizer
- zip            # ZIP Archive
```

---

## Schnellstart

Für erfahrene Entwickler - vollständige Installation in 5 Minuten:

```bash
# 1. Repository klonen
git clone <repository-url> risk-platform
cd risk-platform

# 2. Dependencies installieren & Setup ausführen
composer setup

# 3. PostgreSQL-Datenbank erstellen (siehe unten)
# Anpassen: .env mit DB-Credentials

# 4. Migrations ausführen
php artisan migrate --seed

# 5. Development-Server starten
composer run dev
```

**Fertig!** Die Applikation läuft auf [http://localhost:8000](http://localhost:8000)

---

## Detaillierte Installation

### Schritt 1: Repository klonen

```bash
# Via HTTPS
git clone https://github.com/your-org/risk-platform.git
cd risk-platform

# Oder via SSH
git clone git@github.com:your-org/risk-platform.git
cd risk-platform
```

### Schritt 2: PHP Dependencies installieren

```bash
composer install
```

**Was passiert dabei?**
- Installiert alle Laravel-Pakete
- Installiert Livewire, Flux UI, Fortify
- Installiert Dev-Dependencies (Pest, Pint, Boost)
- Generiert Autoload-Files

### Schritt 3: Environment-Datei erstellen

```bash
# .env.example nach .env kopieren
cp .env.example .env

# Application Key generieren
php artisan key:generate
```

### Schritt 4: Node Dependencies installieren

```bash
npm install
```

**Was passiert dabei?**
- Installiert Vite
- Installiert Tailwind CSS v4
- Installiert Build-Tools

---

## Datenbank-Setup

### PostgreSQL Installation

#### macOS (mit Homebrew)

```bash
# PostgreSQL installieren
brew install postgresql@16

# Als Service starten
brew services start postgresql@16

# Verbindung testen
psql postgres
```

#### macOS (mit Postgres.app)

1. Download von [postgresapp.com](https://postgresapp.com)
2. App starten
3. Default Server initialisieren

#### Ubuntu/Debian

```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

### Datenbank erstellen

```bash
# Als postgres User einloggen
psql postgres

# Oder direkt mit spezifischem User
sudo -u postgres psql
```

```sql
-- Datenbank erstellen
CREATE DATABASE risk_platform_db;

-- User erstellen (optional)
CREATE USER risk_user WITH ENCRYPTED PASSWORD 'your_secure_password';

-- Rechte vergeben
GRANT ALL PRIVILEGES ON DATABASE risk_platform_db TO risk_user;

-- In PostgreSQL 15+ auch Schema-Rechte vergeben
\c risk_platform_db
GRANT ALL ON SCHEMA public TO risk_user;

-- Exit
\q
```

### Schemas erstellen

```sql
-- Verbindung zur DB
psql -U risk_user -d risk_platform_db

-- PUBLIC Schema (wird automatisch erstellt)
-- BACKEND Schema erstellen
CREATE SCHEMA IF NOT EXISTS backend;

-- Rechte für BACKEND Schema
GRANT ALL ON SCHEMA backend TO risk_user;

-- Exit
\q
```

### Verbindung testen

```bash
# Direkter Connect
psql -h 127.0.0.1 -p 5432 -U risk_user -d risk_platform_db

# Mit Laravel Tinker
php artisan tinker
>>> DB::connection('pgsql_second')->select('SELECT version()');
>>> DB::connection('backend')->select('SELECT current_schema()');
```

---

## Environment-Konfiguration

### .env Datei anpassen

```bash
# .env öffnen und anpassen
nano .env
```

#### Grundkonfiguration

```ini
APP_NAME="Risk Intelligence Platform"
APP_ENV=local
APP_KEY=base64:xxx  # Wird von key:generate erstellt
APP_DEBUG=true
APP_URL=http://localhost:8000

APP_LOCALE=de
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=de_DE
```

#### Datenbank-Konfiguration (Wichtig!)

```ini
# Default Connection (PUBLIC Schema)
DB_CONNECTION=pgsql
DB_CONNECTION2=pgsql
DB_HOST2=127.0.0.1
DB_PORT2=5432
DB_DATABASE2=risk_platform_db
DB_USERNAME2=risk_user
DB_PASSWORD2=your_secure_password
```

**Wichtig:** Die Applikation nutzt `DB_*2` Variablen für PostgreSQL!

#### Cache & Session

```ini
CACHE_STORE=database
SESSION_DRIVER=database
QUEUE_CONNECTION=database
```

**Warum database?**
- Einfaches Setup ohne Redis
- Funktioniert out-of-the-box
- Für Produktion: Wechsel zu Redis empfohlen

#### Mail-Konfiguration (Development)

```ini
MAIL_MAILER=log
MAIL_FROM_ADDRESS="noreply@risk-platform.test"
MAIL_FROM_NAME="${APP_NAME}"
```

Mails werden in `storage/logs/laravel.log` gespeichert.

#### Optional: Redis (für bessere Performance)

```ini
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
```

### Vollständige .env Vorlage

<details>
<summary>Klicken für vollständige .env Beispiel-Datei</summary>

```ini
APP_NAME="Risk Intelligence Platform"
APP_ENV=local
APP_KEY=base64:xxx
APP_DEBUG=true
APP_URL=http://localhost:8000

APP_LOCALE=de
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=de_DE

APP_MAINTENANCE_DRIVER=file
PHP_CLI_SERVER_WORKERS=4
BCRYPT_ROUNDS=12

LOG_CHANNEL=stack
LOG_STACK=single
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

# PostgreSQL Configuration
DB_CONNECTION=pgsql
DB_CONNECTION2=pgsql
DB_HOST2=127.0.0.1
DB_PORT2=5432
DB_DATABASE2=risk_platform_db
DB_USERNAME2=risk_user
DB_PASSWORD2=your_secure_password

# Session & Cache
SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=false
SESSION_PATH=/
SESSION_DOMAIN=null

CACHE_STORE=database
QUEUE_CONNECTION=database

# Broadcasting & Filesystem
BROADCAST_CONNECTION=log
FILESYSTEM_DISK=local

# Mail
MAIL_MAILER=log
MAIL_FROM_ADDRESS="noreply@risk-platform.test"
MAIL_FROM_NAME="${APP_NAME}"

# Vite
VITE_APP_NAME="${APP_NAME}"
```
</details>

---

## Frontend-Assets

### Assets kompilieren

```bash
# Development Build (einmalig)
npm run build

# Development mit Hot Reload
npm run dev
```

### Was macht `npm run dev`?

```
┌─────────────────────────────────────────────────┐
│  VITE v7.0.4  ready in X ms                     │
│                                                  │
│  ➜  Local:   http://localhost:5173/             │
│  ➜  Network: use --host to expose               │
│                                                  │
│  ➜  Laravel: http://localhost:8000              │
└─────────────────────────────────────────────────┘

✓ compiled successfully
```

- Startet Vite Dev-Server auf Port 5173
- Hot Module Replacement (HMR) aktiviert
- Tailwind CSS v4 wird kompiliert
- Livewire-Assets werden gebundled

### Production Build

```bash
npm run build

# Output:
# dist/assets/app-xxxxx.js
# dist/assets/app-xxxxx.css
```

---

## Erste Schritte

### 1. Migrations ausführen

```bash
# Alle Migrations ausführen
php artisan migrate

# Mit Seeding (Test-Daten)
php artisan migrate --seed

# Migration-Status prüfen
php artisan migrate:status
```

**Erwartete Tabellen nach Migration:**

```
┌──────────────────────────────────┬────────┐
│ Migration                        │ Ran?   │
├──────────────────────────────────┼────────┤
│ 0001_01_01_000000_create_users   │ Yes    │
│ 0001_01_01_000001_create_cache   │ Yes    │
│ 0001_01_01_000002_create_jobs    │ Yes    │
│ 2025_09_02_075243_add_two_factor │ Yes    │
│ 2025_10_20_181750_create_companies │ Yes  │
│ 2025_10_20_181753_create_transactions │ Yes │
│ 2025_11_16_140224_add_output_columns │ Yes │
│ 2025_11_16_150000_create_backend_data_pool │ Yes │
│ ...                              │        │
└──────────────────────────────────┴────────┘
```

### 2. Test-User erstellen

```bash
php artisan tinker
```

```php
// Test-User erstellen
$user = App\Models\User::create([
    'name' => 'Admin User',
    'email' => 'admin@example.com',
    'password' => bcrypt('password'),
    'email_verified_at' => now(),
]);

// Oder mit Factory
App\Models\User::factory()->create([
    'email' => 'test@example.com',
]);

exit
```

### 3. Development-Server starten

#### Option A: Composer Dev Command (Empfohlen)

```bash
composer run dev
```

**Startet parallel:**
- `php artisan serve` → http://localhost:8000
- `php artisan queue:listen` → Queue Worker
- `php artisan pail` → Live Logs
- `npm run dev` → Vite Dev Server

#### Option B: Einzelne Services manuell

```bash
# Terminal 1: Laravel Server
php artisan serve

# Terminal 2: Vite Dev Server
npm run dev

# Terminal 3 (optional): Queue Worker
php artisan queue:work

# Terminal 4 (optional): Logs
php artisan pail
```

#### Option C: Laravel Herd (macOS)

Wenn du Laravel Herd nutzt:

1. Projekt in Herd-Verzeichnis verschieben
2. Automatische Domain: `risk-platform.test`
3. HTTPS automatisch aktiviert
4. Kein `php artisan serve` notwendig

```bash
# In Herd-Verzeichnis verschieben
mv ~/risk-platform ~/Herd/risk-platform

# Browser öffnen
open https://risk-platform.test
```

### 4. Applikation öffnen

Browser öffnen: [http://localhost:8000](http://localhost:8000)

**Login-Credentials:**
- Email: `test@example.com`
- Password: `password`

---

## Development-Workflow

### Typischer Entwicklungstag

```bash
# 1. Morgen: Repository aktualisieren
git pull origin main

# 2. Dependencies aktualisieren (falls composer.lock geändert)
composer install
npm install

# 3. Neue Migrations (falls vorhanden)
php artisan migrate

# 4. Dev-Server starten
composer run dev

# 5. Am Ende: Code formatieren
vendor/bin/pint

# 6. Tests ausführen
php artisan test

# 7. Commit & Push
git add .
git commit -m "feat: neue feature"
git push
```

### Code-Formatierung

```bash
# Alle Dateien formatieren
vendor/bin/pint

# Nur geänderte Dateien
vendor/bin/pint --dirty

# Test-Modus (ohne Änderungen)
vendor/bin/pint --test
```

### Tests ausführen

```bash
# Alle Tests
php artisan test

# Nur Feature Tests
php artisan test --testsuite=Feature

# Nur Unit Tests
php artisan test --testsuite=Unit

# Spezifische Test-Datei
php artisan test tests/Feature/CompanyTest.php

# Mit Filter
php artisan test --filter=testCompanyCreation

# Mit Coverage (benötigt Xdebug)
php artisan test --coverage
```

### Backend-Daten synchronisieren

```bash
# Stats anzeigen (kein Sync)
php artisan backend:sync-data-pool --stats

# Incremental Sync
php artisan backend:sync-data-pool --incremental

# Full Sync
php artisan backend:sync-data-pool --full

# Transformation
php artisan backend:transform-data-pool

# Kompletter Rebuild
php artisan backend:rebuild
```

### Scheduler lokal testen

```bash
# Schedule Worker (läuft dauerhaft)
php artisan schedule:work

# Oder: Nächste Due-Tasks anzeigen
php artisan schedule:list

# Einzelnen Task testen
php artisan schedule:test sync-backend-data-pool-incremental
```

---

## Troubleshooting

### Problem: "SQLSTATE[08006] Connection refused"

**Ursache:** PostgreSQL läuft nicht oder falsche Credentials

**Lösung:**
```bash
# PostgreSQL-Status prüfen
brew services list | grep postgresql

# PostgreSQL starten
brew services start postgresql@16

# Verbindung testen
psql -h 127.0.0.1 -p 5432 -U risk_user -d risk_platform_db

# .env prüfen
cat .env | grep DB_
```

---

### Problem: "Class 'PDO' not found"

**Ursache:** PHP PostgreSQL Extension fehlt

**Lösung:**
```bash
# Installierte Extensions prüfen
php -m | grep pdo

# Mit Herd (macOS)
# Extensions sind normalerweise vorinstalliert

# Oder PHP neu installieren via Homebrew
brew reinstall php@8.4
```

---

### Problem: "Vite manifest not found"

**Ursache:** Frontend-Assets nicht kompiliert

**Lösung:**
```bash
# Development Build
npm run build

# Oder Dev-Server starten
npm run dev
```

---

### Problem: "419 Page Expired" bei Forms

**Ursache:** CSRF-Token ungültig (Session abgelaufen)

**Lösung:**
```bash
# Cache leeren
php artisan config:clear
php artisan cache:clear
php artisan view:clear

# Browser: Hard Refresh (Cmd+Shift+R / Ctrl+Shift+R)
```

---

### Problem: Migrations laufen nicht

**Ursache:** Datenbank-Schema fehlt oder keine Rechte

**Lösung:**
```bash
# Schema-Rechte prüfen
psql -U risk_user -d risk_platform_db

# In psql:
SELECT schema_name FROM information_schema.schemata;

# Rechte vergeben
GRANT ALL ON SCHEMA public TO risk_user;
GRANT ALL ON ALL TABLES IN SCHEMA public TO risk_user;

# Migration erneut versuchen
php artisan migrate
```

---

### Problem: Queue-Jobs laufen nicht

**Ursache:** Queue-Worker läuft nicht

**Lösung:**
```bash
# Queue-Worker starten
php artisan queue:work

# Oder mit Auto-Restart bei Code-Änderungen
php artisan queue:listen

# Failed Jobs anzeigen
php artisan queue:failed

# Failed Jobs erneut versuchen
php artisan queue:retry all
```

---

### Problem: "Class not found" Fehler

**Ursache:** Autoload-Cache veraltet

**Lösung:**
```bash
# Autoload neu generieren
composer dump-autoload

# Alle Caches leeren
php artisan optimize:clear

# Oder einzeln:
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
```

---

### Problem: Livewire-Components laden nicht

**Ursache:** Volt-Components nicht registriert

**Lösung:**
```bash
# Volt Provider prüfen
cat bootstrap/providers.php | grep Volt

# Cache leeren
php artisan optimize:clear

# Browser Cache leeren
# Cmd+Shift+R (macOS) oder Ctrl+Shift+R (Windows/Linux)
```

---

### Problem: Styling fehlt / Tailwind funktioniert nicht

**Ursache:** Vite-Server läuft nicht oder falsche Konfiguration

**Lösung:**
```bash
# Vite Dev-Server neu starten
npm run dev

# Oder Production-Build
npm run build

# Tailwind-Config prüfen
cat tailwind.config.js

# Node-Modules neu installieren
rm -rf node_modules package-lock.json
npm install
```

---

## Nützliche Commands

### Laravel Artisan

```bash
# Liste aller Commands
php artisan list

# Command-Hilfe
php artisan help migrate

# Interaktive Shell
php artisan tinker

# Cache Management
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan optimize:clear     # Alle Caches auf einmal

# Database
php artisan db:show            # DB-Info anzeigen
php artisan migrate:status     # Migration-Status
php artisan migrate:fresh --seed  # DB neu aufsetzen + Seeds

# Make Commands
php artisan make:model Company
php artisan make:controller CompanyController
php artisan make:migration create_companies_table
php artisan make:livewire CompanySearch
php artisan make:test CompanyTest
php artisan make:class Services/MyService

# Routes
php artisan route:list         # Alle Routes anzeigen
php artisan route:list --path=companies  # Gefiltert
```

### Composer

```bash
# Dependencies installieren
composer install

# Development-Dependencies überspringen
composer install --no-dev

# Einzelnes Package installieren
composer require laravel/telescope

# Package entfernen
composer remove laravel/telescope

# Autoload regenerieren
composer dump-autoload

# Setup ausführen (custom script)
composer setup

# Dev-Server starten (custom script)
composer run dev

# Tests ausführen (custom script)
composer test
```

### NPM

```bash
# Dependencies installieren
npm install

# Dev-Server starten
npm run dev

# Production Build
npm run build

# Package installieren
npm install alpine.js

# Package entfernen
npm uninstall alpine.js

# Outdated Packages prüfen
npm outdated

# Updates installieren
npm update
```

### Git

```bash
# Aktueller Branch
git branch

# Neuen Branch erstellen
git checkout -b feature/neue-funktion

# Änderungen anzeigen
git status
git diff

# Commit
git add .
git commit -m "feat: neue funktion"
git push origin feature/neue-funktion

# Main aktualisieren
git checkout main
git pull origin main
```

### PostgreSQL

```bash
# Verbinden
psql -U risk_user -d risk_platform_db

# In psql:
\dt                    # Alle Tabellen
\d companies          # Tabellen-Schema anzeigen
\dn                   # Alle Schemas
\du                   # Alle User
\l                    # Alle Datenbanken
\q                    # Exit

# Backup erstellen
pg_dump -U risk_user risk_platform_db > backup.sql

# Backup einspielen
psql -U risk_user risk_platform_db < backup.sql
```

---

## Nächste Schritte

Nach erfolgreichem Setup:

1. **Architektur-Dokumentation lesen** → [docs/architecture-overview.md](architecture-overview.md)
2. **Backend-Sync Commands kennenlernen** → [docs/backend-sync-commands.md](backend-sync-commands.md)
3. **Code-Konventionen studieren** → [CLAUDE.md](../CLAUDE.md)
4. **Tests schreiben & ausführen** → `php artisan test`
5. **Erste Änderungen committen** → `git commit`

---

## Hilfe & Support

### Dokumentation

- **Architektur-Übersicht:** [docs/architecture-overview.md](architecture-overview.md)
- **Backend-Sync:** [docs/backend-sync-commands.md](backend-sync-commands.md)
- **Scheduling:** [docs/scheduling-setup.md](scheduling-setup.md)
- **Migration:** [docs/sync-migration-instructions.md](sync-migration-instructions.md)

### Laravel Dokumentation

- **Laravel 12:** [https://laravel.com/docs/12.x](https://laravel.com/docs/12.x)
- **Livewire 3:** [https://livewire.laravel.com](https://livewire.laravel.com)
- **Flux UI:** [https://flux.laravel.com](https://flux.laravel.com)
- **Pest Testing:** [https://pestphp.com](https://pestphp.com)

### Logs prüfen

```bash
# Application Logs (Live)
tail -f storage/logs/laravel.log

# Nur Fehler
tail -f storage/logs/laravel.log | grep ERROR

# Mit Laravel Pail (farbig)
php artisan pail
```

### Debugging

```bash
# Laravel Debugbar (installiert)
# Aktiviert automatisch wenn APP_DEBUG=true
# Erscheint am unteren Bildschirmrand im Browser

# Tinker für schnelle Tests
php artisan tinker
>>> App\Models\Company::count()
>>> DB::table('transactions')->latest()->first()
```

---

**Setup-Zeit:** ~15-30 Minuten
**Erstellt:** 2025-11-24
**Version:** 1.0
**Autor:** Risk Intelligence Platform Team

Viel Erfolg beim Entwickeln! 🚀