Transport & Logistics ERP System

Bürotaugliches Speditions-System mit MariaDB-Persistenz.

🚀 Schnellstart

1. Voraussetzungen

• .NET 10 SDK
• Docker Desktop
• Visual Studio 2022 oder VS Code

2. Nach dem Clone: Tools wiederherstellen

# EF Core Tools lokal installieren (konsistent über Team/CI)
dotnet tool restore

3. MariaDB starten

# Im Root-Verzeichnis des Projekts
docker compose up -d

Dies startet:

• MariaDB auf Port 3306
• phpMyAdmin auf Port 8081 (http://localhost:8081)

4. API und UI starten

Option A: Visual Studio (empfohlen)

1. Öffne TransportLogisticsERP.sln
2. Rechtsklick auf Solution → "Startprojekte festlegen"
3. Wähle "Mehrere Startprojekte"
4. Setze TransportLogisticsERP.API und OfficeUI auf "Starten"
5. Drücke F5

Option B: Kommandozeile

# Terminal 1 - API
cd src/API
dotnet run

# Terminal 2 - UI
cd src/OfficeUI
dotnet run

5. Anwendung öffnen

Dienst	URL
Office UI	http://localhost:5148
API	http://localhost:5147
API Dokumentation	http://localhost:5147/scalar/v1
phpMyAdmin	http://localhost:8081

📊 Funktionen

Dashboard

• Tagesübersicht mit Auftragsstatistiken
• Offene/Disponierte/Abrechnungsbereite Aufträge
• Umsatz heute

Aufträge

• Schnellerfassung per Telefon/E-Mail
• Kundenauswahl mit Inline-Anlage
• Automatische Preiskalkulation
• Workflow: Entwurf → Bestätigt → Disponiert → Erledigt → Abgerechnet

Abrechnung

• Ein-Klick-Rechnungserstellung
• Sammelrechnungen
• DATEV-Export

Mandanten

• Multi-Tenant-Fähigkeit
• Eigene Nummernkreise pro Mandant
• Individuelle Bankdaten/MwSt

⚙️ Konfiguration

ConnectionString (appsettings.json)

{
  "ConnectionStrings": {
    "MariaDb": "Server=localhost;Port=3306;Database=speditionsbuero;User=app;Password=app;TreatTinyAsBoolean=true;"
  },
  "DatabaseProvider": "MariaDb"
}

InMemory-Modus (ohne Docker)

Setze DatabaseProvider auf leer oder entferne es:

{
  "DatabaseProvider": ""
}

🔧 Entity Framework Commands

Nach dem Clone

dotnet tool restore

Migration erstellen

dotnet tool run dotnet-ef migrations add <MigrationName> \
  --context ErpDbContext \
  --startup-project src/API \
  --project src/Infrastructure

Datenbank aktualisieren

dotnet tool run dotnet-ef database update \
  --context ErpDbContext \
  --startup-project src/API \
  --project src/Infrastructure

Migration entfernen (letzte)

dotnet tool run dotnet-ef migrations remove \
  --context ErpDbContext \
  --startup-project src/API \
  --project src/Infrastructure

Wichtig: Verwende IMMER dotnet tool run dotnet-ef (nicht dotnet ef global)!
Grund: Garantiert konsistentes Scaffolding (9.0.1) über alle Entwickler/CI hinweg.

🐳 Docker Details

Container stoppen

docker compose down

Container mit Daten löschen

docker compose down -v

Logs anzeigen

docker compose logs -f mariadb

🔧 Troubleshooting

Port 3306 bereits belegt

# Prüfen was Port 3306 benutzt
netstat -an | findstr 3306

# MariaDB Container neu starten
docker compose restart mariadb

Datenbank-Migration fehlgeschlagen

# Migration manuell anwenden
cd src/API
dotnet ef database update --project ../Infrastructure/TransportLogisticsERP.Infrastructure.csproj

Seed-Daten fehlen

Die Seed-Daten werden nur beim ersten Start eingefügt. Zum Zurücksetzen:

docker compose down -v
docker compose up -d
# Dann API neu starten

📁 Projektstruktur

├── docker-compose.yml      # MariaDB + phpMyAdmin
├── src/
│   ├── API/               # REST API
│   ├── Core/              # Domain-Entities
│   ├── Infrastructure/    # EF Core, Repositories
│   │   └── Data/
│   │       └── Migrations/
│   ├── Modules/
│   │   ├── TMS/          # Transport Management
│   │   ├── WMS/          # Warehouse Management
│   │   ├── Billing/      # Abrechnung
│   │   └── Disposition/  # Disposition
│   └── OfficeUI/         # Blazor Frontend
└── tests/

🔐 Entwicklungsdaten

Nach dem ersten Start werden automatisch Testdaten angelegt:

Typ	Name	Details
Mandant	DEMO	Demo Spedition GmbH
Mandant	TEST	Test Transport AG
Kunde	Müller & Söhne KG	Berlin, 30 Tage Zahlungsziel
Kunde	Schmidt Handel GmbH	München, 14 Tage Zahlungsziel
Aufträge	3 Stück	Verschiedene Status

📡 API Endpoints

Prefix	Beschreibung
/api/office/*	Büro-Workflow (Aufträge, Rechnungen)
/api/driver/*	Mobile Driver App (Touren, GPS)
/api/ops/*	Verladung, Sendungsstatus
/api/auth/*	Authentication (Token, Login)
/api/setup/*	Owner-Setup (DB-Config, Migration, Status)
/scalar/v1	Interactive API Documentation

Setup & Status Endpoints

Endpoint	Auth	Beschreibung
GET /api/setup/status	❌ Nein	System-Status (hasBusinessDb, canConnect, isMigrated)
GET /api/setup/database/status	✅ Owner	Detaillierter DB-Status mit Migrations-Info
POST /api/setup/database/test	✅ Owner	Verbindung testen (mit Diagnose)
POST /api/setup/database/configure	✅ Owner	DB-Connection konfigurieren
POST /api/setup/database/migrate	✅ Owner	Migrations manuell ausführen
POST /api/setup/database/seed	✅ Owner	Demo-Daten anlegen

Error Codes

503 Service Unavailable mit Code BUSINESS_DB_NOT_CONFIGURED:

{
  "error": "BUSINESS_DB_NOT_CONFIGURED",
  "message": "Business-Datenbank ist nicht konfiguriert",
  "hint": "Bitte als Owner einloggen und Datenbank unter /owner/connections einrichten",
  "setupUrl": "/owner/connections",
  "statusUrl": "/api/setup/status"
}

Dieser Fehler wird zurückgegeben wenn:

• Business-DB nicht konfiguriert ist
• Ein Endpoint aufgerufen wird, der Business-DB benötigt
• Middleware schützt vor 500-Fehlern

🔄 Auto-Migration

Die API führt beim Start automatisch Migrations aus:

1. Settings-DB (SQLite) - Immer
2. Business-DB (MariaDB) - Falls konfiguriert und erreichbar

Robust: API startet auch wenn Business-DB nicht erreichbar ist!

# Status prüfen
curl http://localhost:5147/api/setup/status

# Migration manuell triggern
curl -X POST http://localhost:5147/api/setup/database/migrate \
  -H "Authorization: Bearer YOUR_TOKEN"

# Oder: Container neu starten
docker compose restart api

🏗️ Architektur

┌─────────────────────────────────────────────┐
│           OfficeUI (Blazor Server)          │
│  - Dashboard, Auftragserfassung, Abrechnung │
└──────────────────┬──────────────────────────┘
                   │ HTTP/Cookie+JWT
                   ▼
┌─────────────────────────────────────────────┐
│           REST API (ASP.NET Core)           │
│  - JWT Auth, Multi-Tenant, OpenAPI/Scalar  │
└──────────────────┬──────────────────────────┘
                   │
        ┌──────────┴──────────┐
        ▼                     ▼
┌──────────────┐      ┌──────────────┐
│ Settings-DB  │      │ Business-DB  │
│  (SQLite)    │      │  (MariaDB)   │
│  - Config    │      │  - Tenants   │
│  - Users     │      │  - Orders    │
│  - Roles     │      │  - Shipments │
└──────────────┘      └──────────────┘

Docker Setup mit Init-Container

docker compose up
    │
    ├─ db (MariaDB)
    │  └─ Healthcheck ✅
    │     │
    ├─ init (One-Shot) ← Wartet auf db
    │  ├─ Provision Business-DB Connection
    │  ├─ Run Migrations
    │  └─ Exit(0) ✅
    │     │
    ├─ api ← Wartet auf init completion
    │  └─ Settings-DB bereits konfiguriert
    │     │
    └─ officeui ← Wartet auf api
       └─ Ready ✅

Vorteil: API-Container bleibt sauber - Init-Container macht Setup!

Mobile readiness package

The _mobile_readiness_package/ directory contains a standalone deliverable and verification bundle that we keep outside Git. Review or publish it independently but do not track it in the main repo.