Initial commit: Konzept v2 + Etappe 1 (Blueprints + Login + Profile)

Schwester-Projekt zu arduino.lehrstun.de fuer die 3D-Druck-AG am
Lessing-Gymnasium. Offene jahrelange Nachmittags-AG (kein Trimester),
8-10 Einzel-SuS mit optionalen 2er-Paarungen, 4 Bambu-Lab-Drucker
(3 geschlossen + 1 A1 mini).

Konzept v2 (Reality-Check-Iteration 2026-05-24):
- Onboarding-Pfad statt Pflicht-Lektionen (L1-L3 selbst-zertifiziert)
- Selbstlern-Loop als Kern: SuS-Projekte wachsen die interne Bibliothek
- Drill-Down-Lehrer-Dashboard (Wer ist hier / Wartet Review / Haengt fest)
- Cockpit progressiv: zeigt nur was zum Status passt
- Bambu-Cloud-API fuer Drucker-Live-Status (fragil + Fallback manuell)
- Three.js-Vorschau fuer Cover-aus-3D-Ansicht (Etappe 6)
- Vollstaendige Doku als Obsidian-Vault (24 Markdown-Dateien)
- Entscheidungen E-001 bis E-022 in docs/decisions.md

Etappe 1 lauffaehig (~1800 Zeilen Code):
- Blueprint-Struktur (V8): routes/oeffentlich+profil+admin+api,
  services/auth+bambu+datei
- Komplettes Schema in database.py (14 Tabellen, idempotent)
- Login mit bcrypt + persistentem Lockout in DB (V7, verbessert ggue
  Arduino-Kurs der In-Memory-Dict nutzt)
- Admin-Login + Profile-CRUD + PIN-Reset + PIN-Karten-Druckbogen
- Inline-Edit-Endpunkt mit Whitelist + Audit-Log
- Seeds: AG lessing-3d-ag + 4 Drucker + Default-Einstellungen
- Smoke-Test bestanden (Login, Profil-Anlage, Lockout-Logging)

Nicht im Repo (.gitignore): .env, *.db, venv/, .obsidian/workspace.json

services/__init__.py

@@ -0,0 +1,9 @@
+"""Services-Package fuer 3d.lehrstun.de.
+
+Externe Anbindungen und abstrahierte Helfer, getrennt von HTTP-Routen.
+
+Module:
+- bambu: Bambu-Cloud-API-Wrapper (Etappe 4/5)
+- datei: File-BLOB-Handling, abstrahiert fuer spaetere S3-Migration (Etappe 6)
+- auth: Login-Helfer, persistenter Lockout, bcrypt-PIN-Check
+"""

services/auth.py

@@ -0,0 +1,156 @@
+"""Login-/Auth-Helper.
+
+Konventionen:
+- PIN-Hashing: bcrypt
+- Persistenter Login-Lockout in DB-Tabelle login_lockout (V7, siehe decisions.md#E-020)
+- Decorators: @login_required (Profil-Session), @admin_required (Admin-Session),
+  @onboarding_l1_fertig (V2)
+"""
+import os
+from datetime import datetime, timedelta
+from functools import wraps
+
+import bcrypt
+from flask import session, redirect, url_for, flash, request
+
+from database import get_db
+
+# Lockout-Konfiguration
+LOCKOUT_FENSTER_MINUTEN = 5      # Fehlversuche werden innerhalb dieses Fensters gezaehlt
+LOCKOUT_MAX_VERSUCHE = 5         # Nach so vielen Fehlversuchen: Sperre
+LOCKOUT_DAUER_MINUTEN = 15       # So lange wird gesperrt
+ONBOARDING_L1 = 1                # Lektions-Nummer von L1 (Sicherheits-Lektion)
+
+
+# ===========================================================================
+# PIN-Handling
+# ===========================================================================
+
+def pin_hashen(pin: str) -> str:
+    """Hasht eine PIN mit bcrypt. Default cost ist OK fuer 4-stellige PINs."""
+    return bcrypt.hashpw(pin.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def pin_pruefen(pin: str, hash_str: str) -> bool:
+    """Prueft eine PIN gegen den gespeicherten Hash."""
+    try:
+        return bcrypt.checkpw(pin.encode("utf-8"), hash_str.encode("utf-8"))
+    except (ValueError, TypeError):
+        return False
+
+
+# ===========================================================================
+# Persistenter Login-Lockout (V7, verbessert ggue Arduino-Kurs)
+# ===========================================================================
+
+def ist_gesperrt(profil_id: int) -> tuple[bool, int]:
+    """Liefert (gesperrt: bool, sek_rest: int)."""
+    conn = get_db()
+    row = conn.execute(
+        "SELECT sperre_bis FROM login_lockout WHERE profil_id = ? "
+        "ORDER BY id DESC LIMIT 1",
+        (profil_id,)
+    ).fetchone()
+    conn.close()
+    if not row or not row["sperre_bis"]:
+        return (False, 0)
+    try:
+        sperre_bis = datetime.fromisoformat(row["sperre_bis"])
+    except (ValueError, TypeError):
+        return (False, 0)
+    jetzt = datetime.now()
+    if sperre_bis <= jetzt:
+        return (False, 0)
+    return (True, int((sperre_bis - jetzt).total_seconds()))
+
+
+def fehlversuch_loggen(profil_id: int) -> None:
+    """Loggt einen Fehlversuch. Bei zu vielen innerhalb des Fensters: setzt Sperre."""
+    conn = get_db()
+    jetzt = datetime.now()
+    fenster_start = (jetzt - timedelta(minutes=LOCKOUT_FENSTER_MINUTEN)).isoformat()
+
+    # Zaehle Fehlversuche im Fenster (ungelaufene, also ohne aktive Sperre)
+    versuche_im_fenster = conn.execute(
+        "SELECT COUNT(*) AS n FROM login_lockout "
+        "WHERE profil_id = ? AND letzter_versuch_am > ?",
+        (profil_id, fenster_start)
+    ).fetchone()["n"]
+
+    sperre_bis = None
+    if versuche_im_fenster + 1 >= LOCKOUT_MAX_VERSUCHE:
+        sperre_bis = (jetzt + timedelta(minutes=LOCKOUT_DAUER_MINUTEN)).isoformat()
+
+    conn.execute(
+        "INSERT INTO login_lockout (profil_id, versuche_count, sperre_bis, letzter_versuch_am) "
+        "VALUES (?, ?, ?, ?)",
+        (profil_id, versuche_im_fenster + 1, sperre_bis, jetzt.isoformat())
+    )
+    conn.commit()
+    conn.close()
+
+
+def lockout_zuruecksetzen(profil_id: int) -> None:
+    """Bei erfolgreichem Login: alte Lockout-Eintraege loeschen."""
+    conn = get_db()
+    conn.execute("DELETE FROM login_lockout WHERE profil_id = ?", (profil_id,))
+    conn.commit()
+    conn.close()
+
+
+# ===========================================================================
+# Decorators
+# ===========================================================================
+
+def login_required(f):
+    """Profil muss eingeloggt sein, sonst Redirect zum Login."""
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        if not session.get("profil_id"):
+            flash("Bitte erst einloggen.", "error")
+            return redirect(url_for("profil.login"))
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def admin_required(f):
+    """Admin-Session noetig."""
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        if not session.get("admin"):
+            return redirect(url_for("admin.admin_login"))
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def onboarding_l1_fertig(f):
+    """V2: blockiert Slot-Routes, bis L1 (Sicherheits-Lektion) abgeschlossen ist."""
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        if not session.get("profil_id"):
+            flash("Bitte erst einloggen.", "error")
+            return redirect(url_for("profil.login"))
+        conn = get_db()
+        row = conn.execute(
+            "SELECT status FROM profil_lektion_status "
+            "WHERE profil_id = ? AND lektion_nummer = ?",
+            (session["profil_id"], ONBOARDING_L1)
+        ).fetchone()
+        conn.close()
+        if not row or row["status"] != "fertig":
+            flash(
+                "Du musst erst die Onboarding-Lektion L1 (Sicherheit) abschliessen, "
+                "bevor du Drucker reservieren darfst.",
+                "error"
+            )
+            return redirect(url_for("profil.cockpit"))
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def admin_passwort_pruefen(eingegeben: str) -> bool:
+    """Prueft Admin-Passwort aus .env."""
+    erwartet = os.environ.get("ADMIN_PASSWORT", "")
+    if not erwartet:
+        return False
+    return eingegeben == erwartet

services/bambu.py

@@ -0,0 +1,20 @@
+"""Bambu-Cloud-API-Wrapper (Stub fuer Etappe 1).
+
+Voll implementiert in Etappe 4/5. Siehe docs/druckerapi.md.
+
+Architektur-Idee:
+- get_drucker_status(serial_nr) -> dict mit status, job_name, progress_pct, restzeit_min
+- poll_alle_drucker() -> wird vom Hintergrund-Worker oder einem Cron-Tick aufgerufen
+- Bei API-Fehler: stille Rueckgabe von None, kein Crash — Aufrufer entscheidet,
+  ob alter Wert weiter angezeigt wird oder "Status veraltet"-Banner kommt.
+"""
+
+
+def get_drucker_status(serial_nr: str) -> dict | None:
+    """Stub: gibt None zurueck, bis Etappe 5 implementiert ist."""
+    return None
+
+
+def poll_alle_drucker() -> None:
+    """Stub: tut nichts, bis Etappe 5 implementiert ist."""
+    return None

services/datei.py

@@ -0,0 +1,47 @@
+"""File-BLOB-Handling, abstrahiert fuer spaetere Object-Storage-Migration.
+
+Aktuell: speichert direkt in SQLite-BLOBs (projekt_datei.inhalt).
+Spaeter (wenn DB > 5 GB): Migration auf Hetzner Object-Storage / S3,
+ohne dass aufrufende Routes geaendert werden muessen.
+
+Limits siehe docs/decisions.md#E-016:
+- 30 MB pro Datei (App-Logik, kein DB-Constraint)
+"""
+from typing import Optional
+
+# 30 MB als App-Logik-Limit
+MAX_DATEI_GROESSE = 30 * 1024 * 1024
+
+
+def datei_speichern(
+    projekt_id: int,
+    dateiname: str,
+    mime_type: str,
+    inhalt: bytes,
+    art: str,
+    hochgeladen_von: int,
+) -> tuple[bool, str]:
+    """Speichert eine Datei zum Projekt. Stub fuer Etappe 1, voll in Etappe 6.
+
+    Returns: (erfolg, fehlertext_oder_id)
+    """
+    # Etappe 6: Groessen-Check, INSERT in projekt_datei, return id
+    return (False, "Noch nicht implementiert (Etappe 6)")
+
+
+def datei_laden(datei_id: int) -> Optional[dict]:
+    """Laedt eine Datei (inhalt + meta). Stub fuer Etappe 1, voll in Etappe 6."""
+    return None
+
+
+def datei_loeschen(datei_id: int, durch_profil_id: int) -> bool:
+    """Loescht eine Datei. Stub fuer Etappe 1, voll in Etappe 6."""
+    return False
+
+
+def groesse_pruefen(inhalt: bytes) -> tuple[bool, str]:
+    """Universal-Helfer: prueft 30-MB-Limit."""
+    if len(inhalt) > MAX_DATEI_GROESSE:
+        mb = len(inhalt) / 1024 / 1024
+        return (False, f"Datei zu gross ({mb:.1f} MB, max. 30 MB)")
+    return (True, "")