effigenix/backend/docs/QUICK_START.md

Quick Start Guide - Effigenix ERP

Schnelleinstieg für lokale Entwicklung.

Prerequisites

• ✅ Java 21+ (JDK)
• ✅ Maven 3.9+
• ✅ PostgreSQL 15+ (oder Docker)
• ✅ IDE (IntelliJ IDEA empfohlen)

1. Datenbank Setup

Option A: Docker (empfohlen)

docker run --name effigenix-postgres \
  -e POSTGRES_DB=effigenix \
  -e POSTGRES_USER=effigenix \
  -e POSTGRES_PASSWORD=effigenix \
  -p 5432:5432 \
  -d postgres:15

Option B: Lokale PostgreSQL Installation

CREATE DATABASE effigenix;
CREATE USER effigenix WITH PASSWORD 'effigenix';
GRANT ALL PRIVILEGES ON DATABASE effigenix TO effigenix;

2. Projekt klonen & bauen

cd /home/sebi/git/effigenix
mvn clean install

3. Anwendung starten

mvn spring-boot:run

Die Anwendung läuft auf: http://localhost:8080

4. Seed-Daten erstellen (Initial Admin User)

Erstelle eine zusätzliche Flyway-Migration für einen Admin-User:

-- src/main/resources/db/migration/V004__seed_admin_user.sql

-- Admin User: username=admin, password=admin123
-- BCrypt hash für "admin123" mit strength 12
INSERT INTO users (id, username, email, password_hash, branch_id, status, created_at, last_login)
VALUES (
    'admin-001',
    'admin',
    'admin@effigenix.com',
    '$2a$12$SJmX80hUZoA66W77CX7cHeRw1TPscXD6S8HYEZfhJ5PxTfkbwbLdi',  -- "admin123"
    NULL,  -- Kein Branch = globaler Zugriff
    'ACTIVE',
    CURRENT_TIMESTAMP,
    NULL
);

-- Admin Rolle zuweisen
INSERT INTO user_roles (user_id, role_id)
SELECT 'admin-001', id FROM roles WHERE name = 'ADMIN';

Dann:

mvn flyway:migrate
# oder neu starten: mvn spring-boot:run

5. API testen

Swagger UI (empfohlen)

Öffne: http://localhost:8080/swagger-ui/index.html

1. Klicke auf POST /api/auth/login
2. "Try it out" → Eingabe:

   {
     "username": "admin",
     "password": "admin123"
   }
   

3. "Execute" → accessToken kopieren
4. Klicke oben rechts auf "Authorize"
5. Eingabe: Bearer {accessToken}
6. Jetzt kannst du alle geschützten Endpoints testen!

curl Beispiel

# Login
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Response (Token kopieren):
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 28800,
  ...
}

# User erstellen (mit Token)
export TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

curl -X POST http://localhost:8080/api/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jdoe",
    "email": "jdoe@example.com",
    "password": "SecurePass123!",
    "roleNames": ["PRODUCTION_WORKER"],
    "branchId": null
  }'

6. BCrypt-Hash generieren

Beim Anlegen von Seed-Daten (SQL-Migrations) werden BCrypt-Hashes benötigt. Da verschiedene Tools unterschiedliche Hashes erzeugen (gleiche Ausgabe, verschiedenes Salt – das ist gewollt), muss der Hash mit Spring's BCryptPasswordEncoder generiert werden, damit er zur App-Konfiguration passt.

Wichtig: Niemals einen Hash aus einem anderen Tool (htpasswd, online-Generatoren etc.) in Seed-Daten verwenden – nur Spring-generierte Hashes verifizieren korrekt.

# Hash für ein Passwort generieren (Strength 12 wie in der App konfiguriert)
SPRING_CRYPTO=$(find ~/.m2/repository/org/springframework/security -name "spring-security-crypto-*.jar" | tail -1)
COMMONS=$(find ~/.m2/repository/commons-logging -name "*.jar" | tail -1)

cat > /tmp/GenHash.java << 'EOF'
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
public class GenHash {
    public static void main(String[] args) throws Exception {
        String password = args.length > 0 ? args[0] : "admin123";
        BCryptPasswordEncoder enc = new BCryptPasswordEncoder(12);
        System.out.println(enc.encode(password));
    }
}
EOF

javac -cp "$SPRING_CRYPTO:$COMMONS" /tmp/GenHash.java -d /tmp
java -cp "/tmp:$SPRING_CRYPTO:$COMMONS" GenHash "meinPasswort"

7. Datenbank erkunden

# PostgreSQL CLI
docker exec -it effigenix-postgres psql -U effigenix -d effigenix

# Queries
\dt                                  -- Alle Tabellen
SELECT * FROM users;                 -- Alle User
SELECT * FROM roles;                 -- Alle Rollen
SELECT * FROM role_permissions;      -- Rollen-Permissions
SELECT * FROM audit_logs ORDER BY timestamp DESC LIMIT 10;  -- Letzte 10 Audit Logs

8. Development Workflow

Code-Änderungen testen

# Neubauen
mvn clean compile

# Tests ausführen
mvn test

# Integration Tests
mvn verify

Neue Flyway Migration hinzufügen

1. Erstelle: src/main/resources/db/migration/V005__my_new_feature.sql
2. Schema-Änderungen in SQL schreiben
3. Starte Anwendung neu (Flyway migriert automatisch)

Hot Reload (Spring Boot DevTools)

Bereits in pom.xml enthalten - Code-Änderungen werden automatisch neu geladen.

9. Typische Entwicklungs-Szenarien

Neuen User erstellen (via API)

POST /api/users
{
  "username": "production_lead",
  "email": "lead@effigenix.com",
  "password": "ProductionPass123!",
  "roleNames": ["PRODUCTION_MANAGER"],
  "branchId": "branch-001"
}

User sperren/entsperren

# Sperren
POST /api/users/{userId}/lock

# Entsperren
POST /api/users/{userId}/unlock

Passwort ändern

PUT /api/users/{userId}/password
{
  "currentPassword": "OldPass123!",
  "newPassword": "NewPass456!"
}

10. Fehlersuche

Port 8080 bereits belegt

# Anderer Port in application.yml:
server.port=8081

PostgreSQL Connection Failed

# Docker läuft?
docker ps | grep effigenix-postgres

# Connection String prüfen:
spring.datasource.url=jdbc:postgresql://localhost:5432/effigenix

Flyway Migration Failed

# Flyway-Status prüfen
mvn flyway:info

# Reparieren (bei Bedarf)
mvn flyway:repair

11. Nächste Schritte

• 📖 Lies USER_MANAGEMENT.md für Details
• 🧪 Schreibe Integration Tests
• 🔒 Konfiguriere Production-Security (HTTPS, Rate Limiting)
• 🚀 Deploy auf Server (Docker, Kubernetes, etc.)

Hilfe

• Swagger UI: http://localhost:8080/swagger-ui/index.html
• H2 Console (Test): http://localhost:8080/h2-console (nur in Tests)
• Logs: tail -f logs/spring.log (wenn konfiguriert)

Viel Erfolg! 🎉