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)

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

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

## 2. Projekt klonen & bauen

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

## 3. Anwendung starten

```bash
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:

```sql
-- 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:
```bash
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:
   ```json
   {
     "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

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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)

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

### User sperren/entsperren

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

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

### Passwort ändern

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

## 10. Fehlersuche

### Port 8080 bereits belegt
```bash
# Anderer Port in application.yml:
server.port=8081
```

### PostgreSQL Connection Failed
```bash
# Docker läuft?
docker ps | grep effigenix-postgres

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

### Flyway Migration Failed
```bash
# Flyway-Status prüfen
mvn flyway:info

# Reparieren (bei Bedarf)
mvn flyway:repair
```

## 11. Nächste Schritte

- 📖 Lies [USER_MANAGEMENT.md](./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! 🎉