# FilaMan - Filament Management System

### Unterstütze das FilaMan Projekt
[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/X8X51V6SLP)

### ♻️ Unterstütze die Recycling Fabrik
Leere Spulen gehören nicht in den Müll! Wir unterstützen die [Recycling Fabrik](https://recyclingfabrik.com/). Sende deine leeren Filamentspulen und 3D-Druck-Reste dorthin, damit daraus wieder neues Filament gewonnen werden kann.

**Spannende Neuigkeiten:** Die Recycling Fabrik ist der erste Hersteller, der demnächst damit starten wird, seine Filamentspulen ab Werk mit vorprogrammierten, FilaMan-kompatiblen RFID-Tags auszuliefern!

*Auf der Suche nach der englischen Version? Lese die [README.md](README.md).*

## Über das Projekt
FilaMan ist ein umfassendes System zur Verwaltung von 3D-Druck-Filamenten. Es hilft dir dabei, den Überblick über deine Filamentspulen, Hersteller, Farben und den aktuellen Bestand zu behalten. Zudem bietet es Schnittstellen zu Druckern und AMS (Automatic Material System) Einheiten.

### Dokumentation
Das vollständige Handbuch ist verfügbar unter **[docu.filaman.app](https://docu.filaman.app)**.

### 💡 Hardware-Erweiterung: FilaMan ESP32-Waage
Um das volle Potenzial dieses Systems auszuschöpfen, empfehlen wir unser zugehöriges Hardware-Projekt:
**[FilaMan-System-ESP32](https://github.com/Fire-Devils/FilaMan-System-ESP32)**
Mit dieser ESP32-basierten smarten Waage samt RFID-Integration kannst du deine Spulen auflegen, das Restgewicht automatisch messen und die Daten via RFID-Tag direkt mit dieser Software synchronisieren!

### 🏠 Home Assistant Integration
Für Nutzer von Home Assistant gibt es ein eigenes Add-on-Repository:
**[Fire-Devils/filaman-ha-app](https://github.com/Fire-Devils/filaman-ha-app)**
Diese URL unter Einstellungen → Add-ons → Add-on-Store → ⋮ → Repositories hinzufügen, danach FilaMan installieren und direkt in der Home-Assistant-Umgebung betreiben.

### 🎋 Bambuddy Integration
Verbinde FilaMan über das
**[Bambuddy Treiber-Plugin](https://github.com/Fire-Devils/filaman-bambuddy-plugin)**
mit Bambu Lab Druckern und AMS-Einheiten.
Die Integration hält Spulen- und AMS-Informationen synchron, unterstützt die
automatische Zuweisung nach dem Wiegen und Einlegen einer Spule und meldet den
Filamentverbrauch zurück an FilaMan.

Zusammen mit Bambuddy kann FilaMan außerdem deine eigenen, über die Bambu Cloud
synchronisierten Slicer-Profile automatisch anwenden, sobald eine Spule in einen
AMS-Slot eingelegt wird. Das passende Materialprofil steht dann sowohl im AMS als
auch in Bambu Studio bereit. Damit erhalten eigene und Drittanbieter-Filamente
nahezu denselben nahtlosen Ablauf wie eine originale Bambu RFID-Spule.

## Features
- **Spulen-Verwaltung:** Restgewicht, geschätzte Restlänge und Restmenge in Prozent, Lagerort und Status verfolgen.
- **Filament- und Spulendetails:** Einheitliche, responsive Seiten mit Schnellaktionen und Bearbeitung direkt auf der Detailseite.
- **Standard-Filamenteigenschaften:** Temperaturbereiche, Trocknungsempfehlungen, Druckeinstellungen und Abmessungen neben typisierten Zusatzfeldern.
- **Kataloge und Import:** Filamentdaten in FilaManDB suchen und vorhandenen Bestand aus Spoolman importieren.
- **Zwei RFID-Tags:** Zwei RFID-Tag-UIDs pro Spule speichern, sodass eine Spule mit Tags auf beiden Seiten über jede Seite als derselbe Bestandseintrag erkannt wird.
- **Mandantenfähigkeit:** Multi-User-Unterstützung mit Rollensystem.
- **Drucker-Integration:** Plugin-System zur Anbindung von 3D-Druckern und AMS-Einheiten.
- **Bambuddy Integration:** Spulenbestand und AMS-Zuweisungen synchronisieren, Filamentverbrauch erfassen und eigene Bambu Cloud Slicer-Profile automatisch anwenden.
- **Druckbare Labels:** Spulen- und Filament-Labels mit QR-Codes, eigenen Layouts, gruppierten und durchsuchbaren Feld-Tokens sowie Etikettenbogen-Ausgabe drucken und exportieren.
- **Datenbank-Support:** Kompatibel mit SQLite (Standard), MySQL und PostgreSQL.
- **Responsive UI:** Modernes Design (Hell, Dunkel und Brand-Theme).
- **OIDC (OAuth2) Login:** Single Sign-On (SSO) über OpenID Connect für bestehende Benutzer.

## 🗺️ Roadmap
Wir haben spannende Pläne für die Zukunft von FilaMan:
- **Drucker-Plugins:** Entwicklung von Plugins für die Verbindung zu verschiedenen 3D-Druckern (Beiträge durch die Community sind sehr willkommen!).
- **Mobile Apps:** Native Apps für iOS und Android.

## Installation

### Schnellstart (Docker)
Der einfachste Weg, FilaMan zu starten, ist über Docker:

```bash
docker run -d \
  --name filaman-system-app \
  --restart unless-stopped \
  --pull always \
  -p 8083:8000 \
  -v filaman_data:/app/data \
  ghcr.io/fire-devils/filaman-system:latest
```

Die Anwendung ist anschließend unter `http://localhost:8083` erreichbar.
- **Standard E-Mail:** `admin@example.com`
- **Standard Passwort:** `admin123`

Labels verwenden den gemeinsamen SVG/WASM-Renderer für Designer, Export und
API. Das Image enthält Node 20 und Schriftarten; Chromium ist nicht erforderlich.
SVG ist der einzige Label-Renderer; eine Renderer-Auswahl oder ein Fallback
ist nicht erforderlich.
Container-Prüfungen auf nativem ARM64 sowie emuliertem AMD64/ARMv7 sind bestanden;
die Abnahme durch echte Druck- und Scan-Tests steht noch aus.
Siehe [API-Dokumentation](docs/label-api.md).

### Docker Container selber bauen

#### Voraussetzungen
- Docker
- Docker Buildx mit Multi-Architektur-Unterstützung (für ARM/AMD)

#### Build & Ausführen
```bash
git clone https://github.com/Fire-Devils/filaman-system.git && cd filaman-system

# .env bei Bedarf erstellen und anschließend konfigurieren.
test -e .env || cp .env.example .env

# Image bauen
docker build -t filaman-system:latest .

# Oder Docker Compose verwenden (vorher den Daten-Volume-Pfad anpassen)
PORT=8083 docker compose -f docker-compose.build.yml up --build

# Container starten
docker run -d \
  --name filaman-system-app \
  --restart unless-stopped \
  -p 8083:8000 \
  -v filaman_data:/app/data \
  -e DEBUG=false \
  -e SECRET_KEY=your-secret-key \
  -e CSRF_SECRET_KEY=your-csrf-secret \
  -e ADMIN_EMAIL=admin@example.com \
  -e ADMIN_PASSWORD=your-admin-password \
  filaman-system:latest
```

## Lokale Entwicklung

#### Voraussetzungen
- Python 3.11+
- Node.js 20.3+
- uv (Python Package Manager)

#### Backend starten
```bash
cd backend
uv sync
uv run uvicorn app.main:app --reload
```
Das Backend ist unter `http://localhost:8000` verfügbar.

#### Frontend starten
```bash
cd frontend
npm install
npm run dev
```
Das Frontend ist unter `http://localhost:4321` verfügbar.

#### Frontend für Produktion bauen
```bash
cd frontend
BUILD_MODE=static npx astro build
```
Die statischen Dateien liegen in `frontend/dist/`.

## Konfiguration (Umgebungsvariablen)
Erstelle eine `.env` Datei im Projektverzeichnis. Verwende `.env.example` als Vorlage:

```bash
# Datenbank-Konfiguration
# SQLite (Standard):
DATABASE_URL=sqlite+aiosqlite:///./filaman.db

# MySQL:
# DATABASE_URL=mysql+aiomysql://username:password@hostname:3306/database

# PostgreSQL:
# DATABASE_URL=postgresql+asyncpg://username:password@hostname:5432/database
```

#### Secrets generieren
```bash
# Einzelne Secrets generieren
openssl rand -hex 32

# Alle Secrets auf einmal generieren
echo "SECRET_KEY=$(openssl rand -hex 32)"
echo "CSRF_SECRET_KEY=$(openssl rand -hex 32)"
echo "OIDC_ENC_KEY=$(openssl rand -hex 32)"
```

#### OIDC / SSO Konfiguration
Um OIDC (OpenID Connect) Login zu aktivieren, setze folgende Umgebungsvariable:

```bash
# Erforderlich für die Verschlüsselung des OIDC Client Secrets in der Datenbank
OIDC_ENC_KEY=dein-fernet-key
```

#### Worker-Prozesse
Das Docker-Image startet standardmäßig 4 Worker-Prozesse. Jeder hält eine vollständige Kopie der Anwendung (etwa 90 MB), auf einem kleinen Rechner wie einem Raspberry Pi können es also weniger sein:

```bash
# Standard: 4. Ein einzelner Worker führt die Druckertreiber selbst, nichts wird weitergeleitet.
WEB_CONCURRENCY=1
```

**Hinweis:** Bei Verwendung von MySQL oder PostgreSQL muss das Backup vom Administrator extern verwaltet werden. Das automatische SQLite-Backup ist in diesem Fall deaktiviert.

## Projektstruktur

```text
/
├── backend/
│   ├── app/
│   │   ├── core/          # Konfiguration, Datenbank, Sicherheit
│   │   ├── models/        # Datenbankmodelle
│   │   ├── services/      # Gemeinsame Fachlogik
│   │   └── plugins/       # Drucker-Plugins
│   ├── alembic/           # Datenbank-Migrationen
│   └── tests/             # Backend-Tests
├── frontend/
│   ├── src/
│   │   ├── pages/         # Astro-Seiten
│   │   ├── layouts/       # Seiten-Layouts
│   │   └── components/    # UI-Komponenten
│   └── dist/              # Produktions-Build
└── docs/                  # Projektdokumentation
```

## Technologie

**Backend:**
- FastAPI
- SQLAlchemy 2.0 + Alembic
- Python 3.11+

**Frontend:**
- Astro + Tailwind CSS
- Statischer Docker-Build; Node-Server-Ausgabe bei Quellcode-Builds

## Lizenz
MIT