Gruppen und Kategorien getrennt, EAN-Codes an der Gruppe automatisch gefuehrt

Die Umbenennung von Gruppen in "Kategorien" war falsch: Es sind zwei
verschiedene Dinge. Sie ist zurueckgenommen, Kategorien kommen als eigene Ebene
dazu.

GRUPPE zaehlt Bestaende mehrerer Marken zusammen - Mehl von Rewe, Aldi und
Migros ergeben "5 kg Mehl". Dafuer Mindestbestand mit Einheit und EAN-Codes.
KATEGORIE ordnet allein die Artikelliste ("zeig mir alle Suesswaren"), ist
verschachtelbar wie ein Lagerort und hat weder Bestand noch EAN-Codes. Ein
Artikel kann beides, eines oder keines haben.

Die Vermischung war aelter als die Umbenennung: guessGroup in offUtils.js hat
aus der Open-Food-Facts-KATEGORIE eine GRUPPE geraten. Das ist entfernt. Die
OFF-Einordnung steuert jetzt die Kategorie, wo sie hingehoert; eine Gruppe
entsteht nur ueber einen hinterlegten Gruppen-Code oder bewusste Auswahl.

EAN-Codes an der Gruppe: Das war kein Anzeigefehler. Beim Anlegen eines Artikels
wurde ausschliesslich group_id gesetzt - ein Gruppen-Code entstand nie, die
Liste war tatsaechlich leer. Die Meldung "bereits vergeben" kam daher, dass der
Code am Artikel hing. Jetzt pflegt services/group_codes.py den Code mit: beim
Zuordnen kommt er hinzu, beim Gruppenwechsel wandert er mit, beim Entfernen der
Gruppe oder Loeschen des Artikels verschwindet er. Beim Scannen aendert sich
nichts an der Reihenfolge - der Artikel wird weiterhin zuerst gefunden; der
Gruppen-Eintrag ist Beleg in der Verwaltung und Rueckfall. Traegt man denselben
Code von Hand nach, ist das kein Fehler mehr, sondern die Auskunft, dass er ueber
den Artikel bereits dort steht.

Kategorien im Backend: neue Tabelle mit parent_id (Muster von Location),
products.category_id per ADD COLUMN IF NOT EXISTS nachgezogen, deutsche
zweistufige Startliste analog zu den eingebauten Einheiten. Die Startliste wird
nur angelegt, wenn ueberhaupt noch keine Kategorie existiert - wer sie bewusst
leerraeumt, findet sie nicht wieder. Beim Setzen einer Oberkategorie wird
geprueft, dass keine Kategorie sich selbst oder einem eigenen Nachfahren
untergeordnet wird; sonst entstuende ein Ring und jede Baumdarstellung liefe
endlos. Der Produktfilter schliesst Unterkategorien ein, category_id=0 liefert
die Artikel ohne Kategorie. Export und Import fuehren die Kategorie als Pfad
("Suesswaren & Snacks > Schokolade") in einer Spalte, damit die CSV in Excel
bedienbar bleibt.

Web: neue Seite Kategorien mit Baumdarstellung, Filter ueber der Produktliste,
getrennte Auswahlfelder im Produktformular mit je einer Zeile Erklaerung, und
beim Einlagern laesst sich eine Gruppe samt Einheit und Mindestbestand direkt
anlegen, ohne den Vorgang zu verlassen.

iOS: Kategorie-Filter ueber der Produktliste, Unterkategorien eingerueckt. Die
Artikelzeile nennt jetzt das Gebinde und warnt, wenn der Mindestbestand
unterschritten ist (rot) oder weniger als ein Viertel Luft bleibt (orange).
Getrennte Auswahlfelder fuer Kategorie und Gruppe, Gruppe direkt anlegbar.

Ausserdem die Eingabefelder in der App: .textFieldStyle(.roundedBorder) zeichnet
in der dunklen Darstellung einen fast schwarzen Kasten. Ersetzt durch eine
Systemfuellung, die sich Hell und Dunkel anpasst und zurueckhaltend bleibt.

Getestet: 54 pytest-Tests gruen, 14 davon neu (Nachfahren-Sammler, OFF-Zuordnung
inklusive Vorrang der Unterkategorie, und die komplette Codepflege an der
Gruppe). Gegen die laufende API geprueft: Startliste ohne Dubletten, Filter auf
Ober- und Unterkategorie, Ringschutz, Loeschen einer Kategorie laesst Artikel
und Unterkategorien bestehen, Export/Import-Rundlauf mit Kategoriepfad, und der
Durchlauf aus der Meldung - Artikel mit Gruppe anlegen, Code steht danach in der
Gruppe. Web-Build und iOS-Geraetebuild fehler- und warnungsfrei.
Die Oberflaechen habe ich nicht selbst bedient.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/app/crud.py

@@ -30,6 +30,7 @@ def product_to_out(db: Session, product: Product) -> ProductOut:
         BarcodeOut.model_validate(b)
         for b in db.query(Barcode).filter(Barcode.product_id == product.id).order_by(Barcode.id).all()
     ]
+    out.category_name = product.category.name if product.category else None
     out.kind = KIND_OF_BASE[product.base_unit].value
     name, factor = display_unit_info(product)
     out.unit_name = name

backend/app/main.py

@@ -10,6 +10,7 @@ from .routers import (
     api_tokens,
     auth,
     branding,
+    categories,
     groups,
     locations,
     products,
@@ -20,7 +21,7 @@ from .routers import (
     users,
     views,
 )
-from .seed import ensure_builtin_units, ensure_first_admin
+from .seed import ensure_builtin_categories, ensure_builtin_units, ensure_first_admin
 
 settings = get_settings()
 
@@ -49,6 +50,8 @@ def _ensure_schema() -> None:
         "NOT NULL DEFAULT 'day'",
         "ALTER TABLE lots ADD COLUMN IF NOT EXISTS best_before_precision VARCHAR(8) "
         "NOT NULL DEFAULT 'day'",
+        "ALTER TABLE products ADD COLUMN IF NOT EXISTS category_id INTEGER "
+        "REFERENCES categories(id) ON DELETE SET NULL",
     ]
     with engine.begin() as conn:
         for stmt in stmts:
@@ -63,6 +66,7 @@ async def lifespan(app: FastAPI):
     db = SessionLocal()
     try:
         ensure_builtin_units(db)
+        ensure_builtin_categories(db)
         ensure_first_admin(db)
     finally:
         db.close()
@@ -100,3 +104,4 @@ app.include_router(transfer.router)
 app.include_router(api_tokens.router)
 app.include_router(settings_router.router)
 app.include_router(branding.router)
+app.include_router(categories.router)

backend/app/models.py

@@ -111,6 +111,27 @@ class Location(Base):
     )
 
 
+class Category(Base):
+    """Einordnung eines Artikels **allein für den Überblick**.
+
+    Nicht zu verwechseln mit :class:`Group`: Eine Gruppe fasst Bestände mehrerer
+    Marken zusammen (5 kg Mehl, egal von wem) und trägt Mindestbestand und
+    EAN-Codes. Eine Kategorie tut nichts dergleichen – sie hilft nur, in einer
+    langen Artikelliste "zeig mir alle Süßwaren" sagen zu können.
+
+    Beliebig tief verschachtelbar (Süßwaren → Schokolade), wie :class:`Location`.
+    """
+
+    __tablename__ = "categories"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(120), nullable=False)
+    parent_id: Mapped[int | None] = mapped_column(
+        ForeignKey("categories.id", ondelete="SET NULL"), nullable=True
+    )
+    is_builtin: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
+
 class Product(Base):
     __tablename__ = "products"
     __table_args__ = (UniqueConstraint("barcode", name="uq_products_barcode"),)
@@ -140,9 +161,15 @@ class Product(Base):
         server_default=DatePrecision.day.value,
     )
 
+    # Gruppe: zaehlt Bestaende mehrerer Marken zusammen.
     group_id: Mapped[int | None] = mapped_column(
         ForeignKey("groups.id", ondelete="SET NULL"), nullable=True
     )
+    # Kategorie: reine Ordnungshilfe fuer die Artikelliste, voellig unabhaengig
+    # von der Gruppe. Ein Artikel kann beides, eines oder keines haben.
+    category_id: Mapped[int | None] = mapped_column(
+        ForeignKey("categories.id", ondelete="SET NULL"), nullable=True
+    )
     min_stock: Mapped[float | None] = mapped_column(Float, nullable=True)  # in base units
     # In welcher Einheit der Mindestbestand erfasst wurde (nur für die Anzeige).
     min_stock_unit_id: Mapped[int | None] = mapped_column(
@@ -157,6 +184,7 @@ class Product(Base):
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
 
     group: Mapped[Group | None] = relationship(back_populates="products")
+    category: Mapped[Category | None] = relationship()
     display_unit: Mapped[Unit | None] = relationship(foreign_keys=[display_unit_id])
     min_stock_unit: Mapped[Unit | None] = relationship(foreign_keys=[min_stock_unit_id])
     lots: Mapped[list[Lot]] = relationship(

backend/app/routers/categories.py

@@ -0,0 +1,125 @@
+"""Kategorien: Einordnung der Artikel allein für den Überblick.
+
+Bewusst ohne Bestand, Mindestbestand und EAN-Codes – das ist Sache der Gruppen
+(siehe routers/groups.py). Kategorien sind verschachtelbar wie Lagerorte.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.responses import Response
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..deps import get_current_user, require_admin
+from ..models import Category, Product, User
+from ..schemas import CategoryCreate, CategoryOut, CategoryUpdate
+
+router = APIRouter(prefix="/categories", tags=["categories"])
+
+
+def descendant_ids(db: Session, category_id: int) -> set[int]:
+    """Die Kategorie samt allen Unterkategorien.
+
+    Wird für den Produktfilter gebraucht: Wer auf "Süßwaren" filtert, will auch
+    die Artikel aus "Schokolade" sehen. Die Menge ist klein, deshalb in Python
+    statt mit einer rekursiven Abfrage.
+    """
+    alle = db.query(Category.id, Category.parent_id).all()
+    kinder: dict[int, list[int]] = {}
+    for kid, parent in alle:
+        kinder.setdefault(parent, []).append(kid)
+
+    gefunden: set[int] = set()
+    offen = [category_id]
+    while offen:
+        aktuell = offen.pop()
+        if aktuell in gefunden:
+            continue          # schützt zusätzlich vor einem Ring in den Daten
+        gefunden.add(aktuell)
+        offen.extend(kinder.get(aktuell, []))
+    return gefunden
+
+
+def _to_out(db: Session, category: Category) -> CategoryOut:
+    out = CategoryOut.model_validate(category)
+    out.product_count = (
+        db.query(Product).filter(Product.category_id == category.id).count()
+    )
+    return out
+
+
+@router.get("", response_model=list[CategoryOut])
+def list_categories(
+    db: Session = Depends(get_db), _: User = Depends(get_current_user)
+) -> list[CategoryOut]:
+    rows = db.query(Category).order_by(Category.name).all()
+    return [_to_out(db, c) for c in rows]
+
+
+@router.post("", response_model=CategoryOut, status_code=status.HTTP_201_CREATED)
+def create_category(
+    payload: CategoryCreate,
+    db: Session = Depends(get_db),
+    _: User = Depends(require_admin),
+) -> CategoryOut:
+    if payload.parent_id is not None and db.get(Category, payload.parent_id) is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Oberkategorie nicht gefunden")
+    category = Category(name=payload.name, parent_id=payload.parent_id)
+    db.add(category)
+    db.commit()
+    db.refresh(category)
+    return _to_out(db, category)
+
+
+@router.patch("/{category_id}", response_model=CategoryOut)
+def update_category(
+    category_id: int,
+    payload: CategoryUpdate,
+    db: Session = Depends(get_db),
+    _: User = Depends(require_admin),
+) -> CategoryOut:
+    category = db.get(Category, category_id)
+    if category is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Kategorie nicht gefunden")
+
+    data = payload.model_dump(exclude_unset=True)
+    if "parent_id" in data and data["parent_id"] is not None:
+        neuer_elternteil = data["parent_id"]
+        if db.get(Category, neuer_elternteil) is None:
+            raise HTTPException(status.HTTP_404_NOT_FOUND, "Oberkategorie nicht gefunden")
+        # Ohne diese Prüfung entstünde ein Ring und jede Baumdarstellung
+        # (Oberfläche wie Filter) liefe endlos.
+        if neuer_elternteil in descendant_ids(db, category_id):
+            raise HTTPException(
+                status.HTTP_400_BAD_REQUEST,
+                "Eine Kategorie kann nicht sich selbst oder einer ihrer "
+                "Unterkategorien untergeordnet werden.",
+            )
+
+    for field, value in data.items():
+        setattr(category, field, value)
+    db.commit()
+    db.refresh(category)
+    return _to_out(db, category)
+
+
+@router.delete("/{category_id}")
+def delete_category(
+    category_id: int,
+    db: Session = Depends(get_db),
+    _: User = Depends(require_admin),
+) -> Response:
+    """Artikel und Unterkategorien bleiben bestehen, sie verlieren nur die Zuordnung."""
+    category = db.get(Category, category_id)
+    if category is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Kategorie nicht gefunden")
+
+    # SQLite setzt Fremdschlüssel nicht ohne Weiteres um, deshalb ausdrücklich.
+    db.query(Product).filter(Product.category_id == category_id).update(
+        {Product.category_id: None}
+    )
+    db.query(Category).filter(Category.parent_id == category_id).update(
+        {Category.parent_id: None}
+    )
+    db.delete(category)
+    db.commit()
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

backend/app/routers/groups.py

@@ -111,23 +111,40 @@ def update_group(
     return _group_to_out(db, group)
 
 
-def _describe_conflict(db: Session, code: str) -> str | None:
+def _describe_conflict(db: Session, code: str, group_id: int) -> str | None:
     """Sagt, wem ein Code schon gehört – "bereits vergeben" allein half nicht weiter."""
     product = db.query(Product).filter(Product.barcode == code).first()
     existing = db.query(Barcode).filter(Barcode.code == code).first()
 
     if existing is not None and existing.product_id:
         product = db.get(Product, existing.product_id) or product
+
     if product is not None:
+        if product.group_id == group_id:
+            # Der Code steht durch den Artikel ohnehin schon in dieser Gruppe.
+            return (
+                f"Dieser Code gehört zum Artikel \"{product.name}\" und ist über ihn "
+                "bereits in dieser Gruppe."
+            )
+        if product.group_id is not None:
+            other = db.get(Group, product.group_id)
+            name = other.name if other else "einer anderen Gruppe"
+            return (
+                f"Dieser Code gehört zum Artikel \"{product.name}\", der in der Gruppe "
+                f"\"{name}\" liegt. Ändere die Gruppe des Artikels, statt den Code hier "
+                "einzutragen."
+            )
         return (
-            f"Dieser Code gehört bereits zum Artikel \"{product.name}\". "
-            "Artikel-Codes müssen hier nicht eingetragen werden – beim Scannen "
-            "wird immer zuerst der Artikel gefunden, und dessen Kategorie zählt."
+            f"Dieser Code gehört bereits zum Artikel \"{product.name}\". Ordne den "
+            "Artikel dieser Gruppe zu – sein Code erscheint dann automatisch hier."
         )
+
+    if existing is not None and existing.group_id == group_id:
+        return "Dieser Code ist in dieser Gruppe bereits hinterlegt."
     if existing is not None and existing.group_id:
         other = db.get(Group, existing.group_id)
-        name = other.name if other else "einer anderen Kategorie"
-        return f"Dieser Code ist bereits der Kategorie \"{name}\" zugeordnet."
+        name = other.name if other else "einer anderen Gruppe"
+        return f"Dieser Code ist bereits der Gruppe \"{name}\" zugeordnet."
     if existing is not None:
         return "Dieser Code ist bereits vergeben."
     return None
@@ -145,7 +162,7 @@ def add_group_barcode(
     if group is None:
         raise HTTPException(status.HTTP_404_NOT_FOUND, "Gruppe nicht gefunden")
     code = payload.code.strip()
-    conflict = _describe_conflict(db, code)
+    conflict = _describe_conflict(db, code, group.id)
     if conflict:
         raise HTTPException(status.HTTP_409_CONFLICT, conflict)
     db.add(Barcode(code=code, note=(payload.note or None), group_id=group.id))

backend/app/routers/products.py

@@ -4,10 +4,13 @@ from sqlalchemy.orm import Session
 from ..crud import product_to_out
 from ..database import get_db
 from ..deps import get_current_user, require_admin
-from ..models import Barcode, BaseUnit, Group, Product, User
+from ..models import Barcode, BaseUnit, Category, Group, Product, User
 from ..off import lookup_barcode
 from ..schemas import BarcodeCreate, LookupResult, ProductCreate, ProductOut, ProductUpdate
+from ..services.categories import suggest_category
+from .categories import descendant_ids
 from ..services.conversion import ConversionError, resolve_product_unit
+from ..services.group_codes import detach as detach_group_code, sync as sync_group_code
 
 router = APIRouter(prefix="/products", tags=["products"])
 
@@ -15,13 +18,24 @@ router = APIRouter(prefix="/products", tags=["products"])
 @router.get("", response_model=list[ProductOut])
 def list_products(
     q: str | None = None,
+    category_id: int | None = None,
     db: Session = Depends(get_db),
     _: User = Depends(get_current_user),
 ) -> list[ProductOut]:
+    """Artikel auflisten, optional nach Name und Kategorie eingegrenzt.
+
+    ``category_id=0`` liefert die Artikel ohne Kategorie. Bei einer echten
+    Kategorie zählen die Unterkategorien mit: Wer auf "Süßwaren" filtert, will
+    auch "Schokolade" sehen.
+    """
     query = db.query(Product)
     if q:
         like = f"%{q}%"
         query = query.filter(Product.name.ilike(like))
+    if category_id == 0:
+        query = query.filter(Product.category_id.is_(None))
+    elif category_id is not None:
+        query = query.filter(Product.category_id.in_(descendant_ids(db, category_id)))
     products = query.order_by(Product.name).all()
     return [product_to_out(db, p) for p in products]
 
@@ -52,9 +66,14 @@ def lookup(
             group_id, group_name = group.id, group.name
 
     suggestion = lookup_barcode(code)
+    # Die OFF-Einordnung steuert die KATEGORIE (Ueberblick), nicht die Gruppe.
+    category = suggest_category(db, suggestion)
+    category_id = category.id if category else None
+    category_name = category.name if category else None
     if suggestion:
         return LookupResult(
-            found=True, suggestion=suggestion, group_id=group_id, group_name=group_name
+            found=True, suggestion=suggestion, group_id=group_id, group_name=group_name,
+            category_id=category_id, category_name=category_name,
         )
     return LookupResult(found=False, group_id=group_id, group_name=group_name)
 
@@ -101,12 +120,15 @@ def create_product(
         package_label=payload.package_label or None,
         date_precision=payload.date_precision.value,
         group_id=payload.group_id,
+        category_id=payload.category_id,
         min_stock=payload.min_stock,
         min_stock_unit_id=payload.min_stock_unit_id,
         min_stock_in_packages=bool(payload.min_stock_in_packages),
         source="manual",
     )
     db.add(product)
+    db.flush()                      # product.id fuer den Gruppen-Code
+    sync_group_code(db, product)
     db.commit()
     db.refresh(product)
     return product_to_out(db, product)
@@ -153,6 +175,8 @@ def update_product(
         data["date_precision"] = data["date_precision"].value
     for field, value in data.items():
         setattr(product, field, value)
+    # Gruppe oder Barcode koennen sich geaendert haben - Code nachziehen.
+    sync_group_code(db, product)
     db.commit()
     db.refresh(product)
     return product_to_out(db, product)
@@ -207,5 +231,6 @@ def delete_product(
     product = db.get(Product, product_id)
     if product is None:
         raise HTTPException(status.HTTP_404_NOT_FOUND, "Produkt nicht gefunden")
+    detach_group_code(db, product)
     db.delete(product)
     db.commit()

backend/app/routers/transfer.py

@@ -18,8 +18,10 @@ from sqlalchemy.orm import Session
 from ..database import get_db
 from ..deps import get_current_user, require_admin
 from ..services.dates import MONTH, clean_precision, normalize_best_before
+from ..services.group_codes import sync as sync_group_code
 from ..models import (
     BaseUnit,
+    Category,
     DatePrecision,
     Group,
     Location,
@@ -37,7 +39,7 @@ router = APIRouter(tags=["transfer"])
 
 CSV_FIELDS = [
     "barcode", "name", "marke", "einheit", "packungsgroesse", "gebinde",
-    "gruppe", "mindestbestand", "menge", "menge_einheit", "mhd", "lagerort",
+    "gruppe", "kategorie", "mindestbestand", "menge", "menge_einheit", "mhd", "lagerort",
 ]
 PACKAGE_TOKENS = {"packung", "package", "pkg", "pack"}
 
@@ -73,6 +75,7 @@ def export_stock_csv(
             product.package_size if product.package_size else "",
             product.package_label or "",
             product.group.name if product.group else "",
+            _category_path(db, product.category),
             product.min_stock if product.min_stock is not None else "",
         ]
         lots = (
@@ -149,6 +152,7 @@ def export_backup_json(
                 "package_label": p.package_label,
                 "date_precision": p.date_precision,
                 "group": p.group.name if p.group else None,
+                "category": _category_path(db, p.category),
                 "min_stock": p.min_stock,
                 "min_stock_unit": p.min_stock_unit.name if p.min_stock_unit else None,
                 "min_stock_in_packages": bool(p.min_stock_in_packages),
@@ -269,6 +273,45 @@ def _get_or_create_location(db: Session, name: str | None) -> Location | None:
     return loc
 
 
+def _category_path(db: Session, category: Category | None) -> str:
+    """Unterkategorien als "Süßwaren & Snacks > Schokolade" in EINE Spalte.
+
+    So bleibt die CSV in Excel bedienbar, statt für jede Ebene eine eigene
+    Spalte zu brauchen.
+    """
+    if category is None:
+        return ""
+    teile = [category.name]
+    aktuell, tiefe = category, 0
+    while aktuell.parent_id is not None and tiefe < 10:   # Schutz vor einem Ring
+        aktuell = db.get(Category, aktuell.parent_id)
+        if aktuell is None:
+            break
+        teile.append(aktuell.name)
+        tiefe += 1
+    return " > ".join(reversed(teile))
+
+
+def _get_or_create_category(db: Session, path: str | None) -> Category | None:
+    """Legt den ganzen Pfad an, falls Teile davon fehlen."""
+    path = (path or "").strip()
+    if not path:
+        return None
+    parent: Category | None = None
+    for name in [t.strip() for t in path.split(">") if t.strip()]:
+        query = db.query(Category).filter(Category.name == name)
+        query = query.filter(
+            Category.parent_id == (parent.id if parent else None)
+        )
+        node = query.first()
+        if node is None:
+            node = Category(name=name, parent_id=parent.id if parent else None)
+            db.add(node)
+            db.flush()
+        parent = node
+    return parent
+
+
 def _get_or_create_group(db: Session, name: str | None) -> Group | None:
     name = (name or "").strip()
     if not name:
@@ -300,6 +343,7 @@ def _get_or_create_product(db: Session, row: dict, created: list[str]) -> Produc
     if unit is None:
         raise ValueError(f"Unbekannte Einheit: {row.get('einheit')}")
     group = _get_or_create_group(db, row.get("gruppe"))
+    category = _get_or_create_category(db, row.get("kategorie"))
     product = Product(
         barcode=barcode,
         name=name,
@@ -311,11 +355,15 @@ def _get_or_create_product(db: Session, row: dict, created: list[str]) -> Produc
         # Nur im JSON-Backup enthalten; aus der CSV kommt hier nichts.
         date_precision=clean_precision((row.get("mhd_genauigkeit") or "").strip() or None),
         group_id=group.id if group else None,
+        category_id=category.id if category else None,
         min_stock=_num(row.get("mindestbestand")),
         source="import",
     )
     db.add(product)
     db.flush()
+    # Damit ein eingelesenes Backup denselben Stand erzeugt wie das Anlegen
+    # ueber die Oberflaeche.
+    sync_group_code(db, product)
     created.append(product.name)
     return product
 
@@ -454,6 +502,7 @@ def _import_json(db: Session, content: bytes, user: User, mode: str) -> dict:
                 "packungsgroesse": entry.get("package_size") or "",
                 "gebinde": entry.get("package_label") or "",
                 "mhd_genauigkeit": entry.get("date_precision") or "",
+                "kategorie": entry.get("category") or "",
                 "gruppe": entry.get("group") or "",
                 "mindestbestand": entry.get("min_stock") if entry.get("min_stock") is not None else "",
             }

backend/app/schemas.py

@@ -116,6 +116,27 @@ class GroupUpdate(BaseModel):
     min_stock_unit_id: int | None = None
 
 
+# ---- Categories ----
+class CategoryOut(BaseModel):
+    """Reine Ordnungshilfe – kein Bestand, kein Mindestbestand, keine EAN-Codes."""
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    name: str
+    parent_id: int | None = None
+    is_builtin: bool = False
+    product_count: int = 0
+
+
+class CategoryCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=120)
+    parent_id: int | None = None
+
+
+class CategoryUpdate(BaseModel):
+    name: str | None = Field(default=None, min_length=1, max_length=120)
+    parent_id: int | None = None
+
+
 # ---- Locations ----
 class LocationOut(BaseModel):
     model_config = ConfigDict(from_attributes=True)
@@ -144,6 +165,8 @@ class ProductBase(BaseModel):
     # Voreingestellte MHD-Genauigkeit dieses Produkts (z.B. Konserven: nur Monat).
     date_precision: DatePrecision = DatePrecision.day
     group_id: int | None = None
+    # Kategorie: nur fuer den Ueberblick, unabhaengig von der Gruppe.
+    category_id: int | None = None
     min_stock: float | None = Field(default=None, ge=0)  # immer in Basiseinheiten
     # Nur für die Anzeige: in welcher Einheit der Mindestbestand erfasst wurde.
     min_stock_unit_id: int | None = None
@@ -165,6 +188,7 @@ class ProductUpdate(BaseModel):
     package_label: str | None = Field(default=None, max_length=32)
     date_precision: DatePrecision | None = None
     group_id: int | None = None
+    category_id: int | None = None
     min_stock: float | None = Field(default=None, ge=0)
     min_stock_unit_id: int | None = None
     min_stock_in_packages: bool | None = None
@@ -183,6 +207,8 @@ class ProductOut(BaseModel):
     package_label: str | None = None
     date_precision: DatePrecision = DatePrecision.day
     group_id: int | None
+    category_id: int | None = None
+    category_name: str | None = None
     min_stock: float | None
     min_stock_unit_id: int | None = None
     min_stock_in_packages: bool = False
@@ -208,6 +234,9 @@ class LookupResult(BaseModel):
     # Ist der Code einer Gruppe zugeordnet (z.B. "Mehl"), wird sie hier gemeldet.
     group_id: int | None = None
     group_name: str | None = None
+    # Aus der Open-Food-Facts-Kategorie abgeleiteter Vorschlag (nur Vorschlag).
+    category_id: int | None = None
+    category_name: str | None = None
 
 
 class BarcodeCreate(BaseModel):

backend/app/seed.py

@@ -3,7 +3,7 @@
 from sqlalchemy.orm import Session
 
 from .config import get_settings
-from .models import Role, Unit, UnitKind, User
+from .models import Category, Role, Unit, UnitKind, User
 from .security import hash_password
 
 # (Name, Art, Faktor zur kanonischen Basiseinheit)
@@ -26,6 +26,43 @@ def ensure_builtin_units(db: Session) -> None:
         db.commit()
 
 
+# Startliste für den Überblick über den Vorrat. Zweistufig, damit die
+# Verschachtelung von Anfang an sichtbar ist. Alles frei änderbar –
+# umbenennen, löschen und eigene ergänzen ist ausdrücklich vorgesehen.
+BUILTIN_CATEGORIES: list[tuple[str, list[str]]] = [
+    ("Obst & Gemüse", []),
+    ("Molkereiprodukte", ["Käse", "Joghurt & Quark"]),
+    ("Fleisch & Fisch", []),
+    ("Brot & Backwaren", []),
+    ("Trockenwaren & Teigwaren", ["Mehl & Zucker", "Nudeln & Reis"]),
+    ("Konserven & Gläser", []),
+    ("Tiefkühl", []),
+    ("Süßwaren & Snacks", ["Schokolade", "Chips & Salziges"]),
+    ("Getränke", ["Kaffee & Tee"]),
+    ("Gewürze & Saucen", []),
+    ("Frühstück", []),
+    ("Haushalt & Hygiene", []),
+]
+
+
+def ensure_builtin_categories(db: Session) -> None:
+    """Legt nur an, was fehlt – gelöschte Kategorien kommen nicht zurück.
+
+    Anders als bei den Einheiten prüfen wir zusätzlich, ob überhaupt schon
+    Kategorien existieren: Wer die Startliste bewusst leergeräumt hat, soll sie
+    beim nächsten Start nicht wiederfinden.
+    """
+    if db.query(Category).first() is not None:
+        return
+    for name, children in BUILTIN_CATEGORIES:
+        parent = Category(name=name, is_builtin=True)
+        db.add(parent)
+        db.flush()
+        for child in children:
+            db.add(Category(name=child, parent_id=parent.id, is_builtin=True))
+    db.commit()
+
+
 def ensure_first_admin(db: Session) -> None:
     settings = get_settings()
     has_users = db.query(User).first() is not None

backend/app/services/categories.py

@@ -0,0 +1,70 @@
+"""Schlägt aus den Open-Food-Facts-Angaben eine Kategorie vor.
+
+OFF liefert die Einordnung auf Englisch und sehr fein gegliedert
+("Plant-based foods and beverages, Cereals and potatoes, Breakfasts"). Diese
+Werte direkt als Kategorien zu übernehmen, ergäbe hunderte unbrauchbare
+Einträge – deshalb eine Zuordnung auf die überschaubare eigene Liste.
+
+Der Vorschlag ist nur ein Vorschlag: In der Oberfläche ist er vorbelegt und
+jederzeit änderbar.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from ..models import Category
+
+# Stichwort -> Name der Kategorie. Reihenfolge zählt: Die erste Zeile, die
+# passt, gewinnt. Feineres steht deshalb oben, damit "chocolate" in der
+# Unterkategorie "Schokolade" landet und nicht im allgemeinen "Süßwaren".
+KEYWORD_MAP: list[tuple[tuple[str, ...], str]] = [
+    (("chocolat", "schokolade", "cocoa"), "Schokolade"),
+    (("chips", "crisps", "salty-snack", "apéritif", "aperitif"), "Chips & Salziges"),
+    (("cheese", "fromage", "käse", "kaese"), "Käse"),
+    (("yogurt", "yoghurt", "joghurt", "quark", "skyr"), "Joghurt & Quark"),
+    (("flour", "sugar", "mehl", "zucker", "farine"), "Mehl & Zucker"),
+    (("pasta", "noodle", "rice", "nudel", "reis", "spaghetti"), "Nudeln & Reis"),
+    (("coffee", "tea", "kaffee", "tee"), "Kaffee & Tee"),
+
+    (("dairy", "dairies", "milk", "milch", "cream", "rahm", "butter"), "Molkereiprodukte"),
+    (("sweet", "candy", "candies", "biscuit", "cookie", "confectioner",
+      "süßwaren", "bonbon"), "Süßwaren & Snacks"),
+    (("fruit", "vegetable", "obst", "gemüse", "gemuese", "salad"), "Obst & Gemüse"),
+    (("meat", "fish", "seafood", "fleisch", "wurst", "sausage", "poultry"), "Fleisch & Fisch"),
+    (("bread", "bakery", "brot", "backwaren", "pastry"), "Brot & Backwaren"),
+    (("canned", "conserve", "konserve", "tinned"), "Konserven & Gläser"),
+    (("frozen", "tiefkühl", "tiefkuehl", "surgelé", "surgele"), "Tiefkühl"),
+    (("beverage", "drink", "getränk", "getraenk", "water", "juice", "soda"), "Getränke"),
+    (("spice", "sauce", "condiment", "gewürz", "gewuerz", "vinegar", "oil"), "Gewürze & Saucen"),
+    (("breakfast", "cereal", "müsli", "muesli", "jam", "honey", "frühstück"), "Frühstück"),
+    (("cleaning", "hygiene", "detergent", "haushalt", "soap"), "Haushalt & Hygiene"),
+]
+
+
+def suggest_category(db: Session, suggestion: dict | None) -> Category | None:
+    """Passende vorhandene Kategorie zu einem OFF-Vorschlag, sonst ``None``.
+
+    Es wird nichts angelegt: Fehlt die Kategorie (weil sie gelöscht oder
+    umbenannt wurde), gibt es eben keinen Vorschlag.
+    """
+    if not suggestion:
+        return None
+
+    haystack = " ".join(
+        [
+            str(suggestion.get("category_suggestion") or ""),
+            *[str(t) for t in (suggestion.get("category_tags") or [])],
+        ]
+    ).lower()
+    if not haystack:
+        return None
+
+    for keywords, name in KEYWORD_MAP:
+        if any(word in haystack for word in keywords):
+            treffer = db.query(Category).filter(Category.name == name).first()
+            if treffer is not None:
+                return treffer
+            # Kategorie gibt es nicht (mehr) - weitersuchen, vielleicht passt
+            # eine gröbere Zeile weiter unten.
+    return None

backend/app/services/group_codes.py

@@ -0,0 +1,74 @@
+"""Pflegt die EAN-Codes an einer Gruppe automatisch mit.
+
+Bisher entstand ein Gruppen-Code ausschließlich von Hand. Wurde ein Artikel
+einer Gruppe zugeordnet, blieb dessen EAN-Code dort unsichtbar – die Gruppe
+zeigte „0 EANs", obwohl Artikel darin lagen, und der Versuch, den Code
+nachzutragen, scheiterte mit „bereits vergeben" (er hing ja am Artikel).
+
+Jetzt wandert der Haupt-Barcode eines Artikels automatisch an die Gruppe:
+
+* beim Anlegen und beim Zuordnen einer Gruppe → Code kommt hinzu
+* beim Wechsel der Gruppe → Code wandert mit
+* beim Entfernen der Gruppe oder Löschen des Artikels → Code verschwindet
+
+Beim Scannen ändert das nichts an der Reihenfolge: ``routers.products.lookup``
+findet weiterhin zuerst den Artikel, dessen Gruppe zählt. Der Gruppen-Eintrag
+ist Beleg in der Verwaltung und Rückfall, falls der Artikel später verschwindet.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from ..models import Barcode, Product
+
+
+def _group_row(db: Session, code: str) -> Barcode | None:
+    """Vorhandene Gruppen-Zeile zu diesem Code (nicht: Artikel-Alias)."""
+    return (
+        db.query(Barcode)
+        .filter(Barcode.code == code, Barcode.group_id.isnot(None))
+        .first()
+    )
+
+
+def sync(db: Session, product: Product) -> None:
+    """Bringt den Gruppen-Code eines Artikels auf den aktuellen Stand.
+
+    Deckt Anlegen, Ändern und Entfernen der Gruppe gleichermaßen ab, damit die
+    Aufrufer sich nicht merken müssen, was vorher galt.
+    """
+    code = (product.barcode or "").strip()
+    if not code:
+        return
+
+    row = _group_row(db, code)
+
+    # Keine Gruppe mehr: einen früher angelegten Eintrag wieder entfernen.
+    if product.group_id is None:
+        if row is not None:
+            db.delete(row)
+        return
+
+    if row is not None:
+        # Gruppe gewechselt: Zeile umhängen statt löschen und neu anlegen,
+        # damit eine hinterlegte Notiz erhalten bleibt.
+        row.group_id = product.group_id
+        return
+
+    # Hängt der Code bereits als Alias an einem Artikel, gehört er dort hin -
+    # code ist eindeutig, eine zweite Zeile wäre nicht möglich.
+    if db.query(Barcode).filter(Barcode.code == code).first() is not None:
+        return
+
+    db.add(Barcode(code=code, group_id=product.group_id))
+
+
+def detach(db: Session, product: Product) -> None:
+    """Vor dem Löschen eines Artikels dessen Gruppen-Code aufräumen."""
+    code = (product.barcode or "").strip()
+    if not code:
+        return
+    row = _group_row(db, code)
+    if row is not None:
+        db.delete(row)