🔧 ToolTrackr

Local Asset & Tool Management for SMEs

Werkzeuge, Prüfmittel & Betriebsmittel verwalten — ohne teures ERP, ohne Cloud-Zwang.

---

📌 Worum geht es?

Viele kleine und mittlere Betriebe — Werkstätten, Produktion, Metallbau, Handwerk und Instandhaltung — verwalten ihre Werkzeuge, Prüfmittel und Betriebsmittel bis heute mit Excel, Papier oder Zuruf. Das führt zu typischen Problemen:

Wo liegt welches Werkzeug? Wer hat es zuletzt benutzt? Ist es einsatzbereit? Wann muss es geprüft oder gewartet werden? Welche Werkzeuge sind defekt? Was muss bald ersetzt werden?

ToolTrackr ist ein leichtgewichtiges, local-first Asset-Management-System, das genau diese Fragen beantwortet — als schlankes ERP-Modul, aber ohne die Kosten und Komplexität eines großen ERP und ohne SaaS-Abo. Es läuft auf einem PC im Werk, die Daten bleiben im Haus.

---

🖥️ Screenshots

Dashboard	Asset-Übersicht

Asset-Detailseite (mit QR-Code & Historie)	Prüfung & Wartung

Business Impact

---

✨ Features

• 📊 Dashboard – KPI-Karten (Gesamt, verfügbar, ausgeliehen, defekt, Prüfung bald/überfällig, Wartung überfällig, kritischer Bestand) plus Fälligkeits- und Auslastungs-Übersichten.
• 🧰 Asset-Verwaltung – Voller CRUD für Werkzeuge, Prüfmittel, Maschinen, Vorrichtungen, Ersatzteile, IT-Geräte u. v. m. mit Status, Zustand, Standort, Verantwortungsbereich, Lebensdauer/Einsätzen und Notizen.
• 🔄 Ausleihe & Rückgabe – Wer hat was, seit wann und mit welcher geplanten Rückgabe? Status wechselt automatisch; defekte Rückgaben bleiben gesperrt.
• 🛡️ Prüf- & Wartungsmanagement – Fällige und überfällige Prüfungen, automatische Berechnung der nächsten Fälligkeit, automatische Sperrung bei „durchgefallen".
• 🏷️ QR-Codes – Pro Asset ein QR-Code, der auf die Detailseite zeigt: anzeigen, als PNG herunterladen oder als Label-PDF (70×45 mm) drucken.
• 🔎 Suche & Filter – Volltextsuche (Name, Inventar-/Seriennummer) plus Filter nach Kategorie, Status, Zustand, Standort und Fälligkeit, sortierbar.
• 📄 Exporte – Asset-Steckbrief (PDF), gesamte Bestandsliste (CSV, Excel-tauglich mit Umlauten), Prüf-/Wartungsliste (PDF), QR-Label (PDF).
• 🌱 Demo-Daten – Ein Klick erzeugt einen realistischen Beispielbestand einer kleinen Produktionsfirma inkl. Ausleih-, Prüf- und Wartungshistorie.
• 🎨 Hochwertiges UI – Dunkles, modernes Dashboard mit Status-Badges, Warnfarben und responsivem Layout.

---

🧱 Tech Stack

Schicht	Technologie
Frontend	React 18 · Vite · TypeScript · Tailwind CSS · TanStack Query · React Router · lucide-react
Backend	FastAPI · SQLAlchemy 2 · Pydantic v2 · Uvicorn
Datenbank	SQLite (datei­basiert, kein Server nötig)
QR / PDF / CSV	qrcode + Pillow · reportlab · Python-csv
Deployment	Docker Compose (FastAPI-Container + nginx-Container)

---

🚀 Schnellstart

Variante A — Docker (empfohlen)

Voraussetzung: Docker & Docker Compose.

git clone https://github.com/MauricePutinas/ToolTrackr.git
cd ToolTrackr
docker compose up --build

Dann öffnen:

• App: http://localhost:8080
• API-Dokumentation (Swagger): http://localhost:8000/docs

Beim ersten Start werden die Demo-Daten automatisch geladen (AUTO_SEED=true).

Variante B — Lokal ohne Docker

1) Backend

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate   |   macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

2) Frontend (zweites Terminal)

cd frontend
npm install
npm run dev

Dann öffnen: http://localhost:5173 (das Vite-Dev-Setup leitet /api automatisch an das Backend auf Port 8000 weiter).

💡 Demo-Daten laden: Button „Demo-Daten laden" in der Sidebar oder POST http://localhost:8000/api/demo/seed.

---

🔌 API-Dokumentation

Interaktive Doku (OpenAPI/Swagger): /docs · ReDoc: /redoc

Methode	Endpoint	Beschreibung
GET	/api/health	Health-Check
GET	/api/meta	Erlaubte Werte (Kategorien, Status, Zustände, Prüfergebnisse)
GET	/api/dashboard	KPIs + Fälligkeits-/Auslastungslisten
GET	/api/assets	Assets auflisten (Filter: q, category, status, condition, location, due, sort)
POST	/api/assets	Asset anlegen
GET	/api/assets/{id}	Asset-Detail inkl. Historien
PUT	/api/assets/{id}	Asset aktualisieren
DELETE	/api/assets/{id}	Asset löschen
POST	/api/assets/{id}/checkout	Ausleihen
POST	/api/assets/{id}/return	Zurückgeben
POST	/api/assets/{id}/maintenance	Wartung erfassen
POST	/api/assets/{id}/inspection	Prüfung erfassen
GET	/api/assets/{id}/qrcode	QR-Code als PNG
GET	/api/assets/{id}/qrcode/label.pdf	QR-Label als PDF
GET	/api/assets/{id}/export/pdf	Asset-Steckbrief als PDF
GET	/api/export/assets.csv	Alle Assets als CSV
GET	/api/export/maintenance.pdf	Prüf-/Wartungsliste als PDF (?only_due=true nur Fällige)
POST	/api/demo/seed	Demo-Daten laden (?reset=true)

Beispiel: Asset anlegen

curl -X POST http://localhost:8000/api/assets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Messschieber digital 150 mm",
    "category": "Prüfmittel",
    "inventory_number": "PM-0307",
    "location": "QS-Labor / Schrank 2",
    "condition": "gut",
    "status": "verfügbar",
    "maintenance_interval_days": 365,
    "next_inspection_date": "2026-09-01"
  }'

---

🗃️ Datenmodell

Asset 1───* Checkout       (Ausleihen)
      1───* Maintenance    (Wartungen)
      1───* Inspection     (Prüfungen)

Asset: id, name, category, inventory_number, serial_number, location, condition, status, responsible_area, purchase_date, last_inspection_date, next_inspection_date, maintenance_interval_days, max_uses, current_uses, notes, photo_url, qr_code_id, created_at, updated_at

Checkout: id, asset_id, employee_name, area, checkout_date, planned_return_date, actual_return_date, return_condition, notes

Maintenance: id, asset_id, maintenance_date, performed_by, description, next_due_date, notes

Inspection: id, asset_id, inspection_date, performed_by, result, next_inspection_date, notes

Kontrollierte Werte

Feld	Werte
Kategorie	Werkzeug · Prüfmittel · Ersatzteil · Maschine · Vorrichtung · Betriebsmittel · IT-Gerät · Sonstiges
Status	verfügbar · ausgeliehen · in Wartung · defekt · gesperrt · verschrottet
Zustand	neu · gut · gebraucht · kritisch · defekt

Wichtige Geschäftsregeln

• Ausleihe setzt den Status auf ausgeliehen; ein bereits ausgeliehenes oder defektes/verschrottetes Asset kann nicht erneut ausgeliehen werden.
• Rückgabe zählt einen Einsatz hoch und setzt zurück auf verfügbar — außer der Rückgabezustand ist defekt (→ bleibt defekt).
• Prüfung „durchgefallen" sperrt das Asset (gesperrt); erst eine bestandene Prüfung gibt es wieder frei.
• Wartung kann ein defektes/in Wartung-Asset wieder auf verfügbar setzen.
• Fälligkeiten werden automatisch aus Intervallen bzw. den letzten Einträgen berechnet.

---

📁 Projektstruktur

ToolTrackr/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI-App, CORS, Startup, Auto-Seed
│   │   ├── config.py        # Konfiguration via Env-Variablen
│   │   ├── database.py      # Engine, Session, init_db
│   │   ├── models.py        # SQLAlchemy-Modelle
│   │   ├── schemas.py       # Pydantic-Schemas (Request/Response)
│   │   ├── enums.py         # Kategorien, Status, Zustände
│   │   ├── services.py      # Geschäftslogik (Lifecycle, KPIs, Health)
│   │   ├── qrcodes.py       # QR-Code-Erzeugung
│   │   ├── exports.py       # CSV- & PDF-Rendering (reportlab)
│   │   ├── seed.py          # Realistische Demo-Daten
│   │   └── routers/         # assets, dashboard, exports, demo
│   ├── tests/               # pytest (21 Tests, alle Kernflüsse)
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── pages/           # Dashboard, Assets, AssetDetail, Maintenance, BusinessImpact
│   │   ├── components/      # Layout, Modals, Badges, KPI-Karten, QR-Karte …
│   │   ├── api/client.ts    # Typisierter API-Client
│   │   └── types.ts
│   ├── package.json
│   ├── nginx.conf
│   └── Dockerfile
├── docs/screenshots/
├── docker-compose.yml
└── README.md

---

🧪 Tests

cd backend
pip install -r requirements.txt pytest httpx
pytest -q

Die Suite deckt alle Kernfunktionen ab: Anlegen, Validierung, Ausleihe/Rückgabe (inkl. Defekt-Logik), Prüfungen (inkl. Sperrung), Wartungen, Suche/Filter, QR-PNG, PDF- und CSV-Export sowie das Demo-Seeding.

---

💼 Business Impact

Nutzen	Wirkung
⏱️ Weniger Suchzeiten	Fester Standort + QR-Scan statt Lager durchforsten
🛡️ Bessere Prüfmittelkontrolle	Keine abgelaufenen Prüfmittel mehr im Einsatz
📉 Weniger doppelte Bestellungen	Bestand & Zustand vor jeder Bestellung sichtbar
👁️ Mehr Transparenz	Lückenlose Ausleih- und Zustandshistorie
🚀 Einfacher Einstieg	Local-first, in Minuten startklar, keine Lizenzkosten

---

🗺️ Roadmap

• Mehrbenutzer-Authentifizierung & Rollen (Werker / Meister / Admin)
• E-Mail-/Push-Erinnerungen für fällige Prüfungen
• Foto-Upload statt Foto-URL
• Barcode-/QR-Scanner direkt im Browser (Kamera)
• Mandantenfähigkeit für mehrere Standorte
• Audit-Log & Excel-Import
• Optionaler Wechsel auf PostgreSQL für größere Bestände

---

📜 Lizenz

MIT © 2026 Maurice Putinas

_{Gebaut als local-first Werkzeug für echte Betriebe — kein SaaS, kein Vendor-Lock-in.}