cbazza/AFC-Demo

Fork 0

Files

T

cbazza 2f7bd923df

Build and Push Docker Image only on Conventional Commits / build (push) Has been cancelled

Details

local-docker-db branch openend

2025-12-03 12:59:30 +01:00

19 KiB

Raw Blame History

Entwickler-Setup-Guide: Risk Intelligence Platform

📋 Inhaltsverzeichnis

Voraussetzungen
Schnellstart
Detaillierte Installation
Datenbank-Setup
Environment-Konfiguration
Frontend-Assets
Erste Schritte
Development-Workflow
Troubleshooting
Nützliche Commands

Voraussetzungen

Erforderliche Software

Software	Mindestversion	Empfohlen	Installation
PHP	8.2	8.4.14+	Laravel Herd
Composer	2.0	Latest	Via Herd oder getcomposer.org
Node.js	18.x	20.x+	nodejs.org
npm	9.x	Latest	Mit Node.js installiert
PostgreSQL	14.x	16.x+	postgresql.org
Git	2.x	Latest	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:

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

# 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

Detaillierte Installation

Schritt 1: Repository klonen

# 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

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

# .env.example nach .env kopieren
cp .env.example .env

# Application Key generieren
php artisan key:generate

Schritt 4: Node Dependencies installieren

npm install

Was passiert dabei?

Installiert Vite
Installiert Tailwind CSS v4
Installiert Build-Tools

Datenbank-Setup

PostgreSQL Installation

macOS (mit Homebrew)

# PostgreSQL installieren
brew install postgresql@16

# Als Service starten
brew services start postgresql@16

# Verbindung testen
psql postgres

macOS (mit Postgres.app)

Download von postgresapp.com
App starten
Default Server initialisieren

Ubuntu/Debian

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

Datenbank erstellen

# Als postgres User einloggen
psql postgres

# Oder direkt mit spezifischem User
sudo -u postgres psql

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

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

# 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

# .env öffnen und anpassen
nano .env

Grundkonfiguration

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

# 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

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)

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)

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

Klicken für vollständige .env Beispiel-Datei

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}"

Frontend-Assets

Assets kompilieren

# 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

npm run build

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

Erste Schritte

1. Migrations ausführen

# 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

php artisan tinker

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

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

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

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

# 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

Login-Credentials:

Email: test@example.com
Password: password

Development-Workflow

Typischer Entwicklungstag

# 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

# 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

# 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

# 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

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

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

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

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

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

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

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

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

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

# 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

# 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

# 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

# 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

# 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

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

Architektur-Dokumentation lesen → docs/architecture-overview.md
Backend-Sync Commands kennenlernen → docs/backend-sync-commands.md
Code-Konventionen studieren → CLAUDE.md
Tests schreiben & ausführen → php artisan test
Erste Änderungen committen → git commit

Hilfe & Support

Dokumentation

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

Laravel Dokumentation

Laravel 12: https://laravel.com/docs/12.x
Livewire 3: https://livewire.laravel.com
Flux UI: https://flux.laravel.com
Pest Testing: https://pestphp.com

Logs prüfen

# 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

# 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! 🚀

19 KiB Raw Blame History

Entwickler-Setup-Guide: Risk Intelligence Platform

📋 Inhaltsverzeichnis

Voraussetzungen

Erforderliche Software

Empfohlene Tools

PHP Extensions

Schnellstart

Detaillierte Installation

Schritt 1: Repository klonen

Schritt 2: PHP Dependencies installieren

Schritt 3: Environment-Datei erstellen

Schritt 4: Node Dependencies installieren

Datenbank-Setup

PostgreSQL Installation

macOS (mit Homebrew)

macOS (mit Postgres.app)

Ubuntu/Debian

Datenbank erstellen

Schemas erstellen

Verbindung testen

Environment-Konfiguration

.env Datei anpassen

Grundkonfiguration

Datenbank-Konfiguration (Wichtig!)

Cache & Session

Mail-Konfiguration (Development)

Optional: Redis (für bessere Performance)

Vollständige .env Vorlage

Frontend-Assets

Assets kompilieren

Was macht npm run dev?

Production Build

Erste Schritte

1. Migrations ausführen

2. Test-User erstellen

3. Development-Server starten

Option A: Composer Dev Command (Empfohlen)

Option B: Einzelne Services manuell

Option C: Laravel Herd (macOS)

4. Applikation öffnen

Development-Workflow

Typischer Entwicklungstag

Code-Formatierung

Tests ausführen

Backend-Daten synchronisieren

Scheduler lokal testen

Troubleshooting

Problem: "SQLSTATE[08006] Connection refused"

Problem: "Class 'PDO' not found"

Problem: "Vite manifest not found"

Problem: "419 Page Expired" bei Forms

Problem: Migrations laufen nicht

Problem: Queue-Jobs laufen nicht

Problem: "Class not found" Fehler

Problem: Livewire-Components laden nicht

Problem: Styling fehlt / Tailwind funktioniert nicht

Nützliche Commands

Laravel Artisan

Composer

NPM

Git

PostgreSQL

Nächste Schritte

Hilfe & Support

Dokumentation

Laravel Dokumentation

Logs prüfen

Debugging

19 KiB

Raw Blame History

Was macht `npm run dev`?