Sprint 3: Kontroll-Kern (Statusmaschine, Objekt-Sperre, automatische Fehlbestand-Erzeugung)

- Kontrolle/Kontrollposition-Modelle: Kontrolle ändert NIEMALS Objektposition.istmenge
  (Vier-Kernbegriffe-Tabelle, Prompt 02.9) - reine Erfassung/Snapshot
- Objekt-Sperre (Prompt 02.8): Kontrolle.status='in_bearbeitung' + benutzer_id IST die
  Sperre, kein separates Sperr-Modell. Zweiter Zugriff -> 409 mit wer/seit; Übernahme
  bricht alte Kontrolle ab (Datensatz bleibt, Prompt 16.6-Analogie) und protokolliert
  das Ereignis in einer neuen, minimalen Historie-Tabelle (volle Ausbaustufe Sprint 5)
- Automatische Fehlbestand-Erzeugung bei Ist < Soll (U1), Überbestand erzeugt
  ausdrücklich KEINEN Fehlbestand (Prompt 02.4); Korrektur vor Abschluss möglich
  (von derselben Kontrolle erzeugter Fehlbestand ist bis zum Abschluss nicht final)
- Abschluss verweigert bei unbestätigten Positionen, liefert deren IDs (U11)
- Abbruch verwirft Kontrollpositionen UND von dieser Kontrolle erzeugte Fehlbestände,
  Kontrolle selbst bleibt als Datensatz mit Status "abgebrochen" erhalten (U12)
- Tests: U1, U11, U12, Sperre/409, Übernahme, Fremdzugriff/403, parallele Objekte

Mitarbeiter-UI (PWA-Frontend) ist bewusst noch nicht Teil dieses Commits - eigenes
Techstack-Setup, wird als nächster Schritt separat angegangen.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L85hmKbvX7Cqkq47KnQhFt

backend/app/models/__init__.py

@@ -1,4 +1,7 @@
 from app.models.auth import Benutzer, BenutzerRolle, RolleTyp, Systemknoten, KnotenTyp
+from app.models.fehlbestand import Fehlbestand, FehlbestandStatus
+from app.models.historie import Historie
+from app.models.kontrolle import Kontrolle, KontrollStatus, Kontrollposition
 from app.models.objekt import Objekt, ObjektStatus
 from app.models.objektposition import Objektposition, ObjektpositionStatus
 from app.models.stammdaten import Bereich, Kategorie, Material, MaterialTyp, Objekttyp, Standort
@@ -11,6 +14,12 @@ __all__ = [
     "RolleTyp",
     "Systemknoten",
     "KnotenTyp",
+    "Fehlbestand",
+    "FehlbestandStatus",
+    "Historie",
+    "Kontrolle",
+    "KontrollStatus",
+    "Kontrollposition",
     "Objekt",
     "ObjektStatus",
     "Objektposition",

backend/app/models/fehlbestand.py

@@ -0,0 +1,47 @@
+import enum
+import uuid
+from datetime import datetime
+from decimal import Decimal
+
+from sqlalchemy import ForeignKey, Numeric, String
+from sqlalchemy.dialects.postgresql import ENUM as PgEnum, TIMESTAMP, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class FehlbestandStatus(str, enum.Enum):
+    offen = "offen"
+    in_bearbeitung = "in_bearbeitung"
+    nachgefuellt_teilweise = "nachgefuellt_teilweise"
+    erledigt = "erledigt"
+
+
+fehlbestand_status_pg = PgEnum(FehlbestandStatus, name="fehlbestand_status", create_type=False)
+
+
+class Fehlbestand(Base):
+    """Prompt 03: automatisch entstandener Vorgang bei Ist < Soll, ändert selbst
+    NIEMALS die Ist-Menge (nur Nachfüllung tut das, Sprint 4). Sollmenge/Istmenge/
+    Fehlmenge hier sind Snapshot-Werte zum Feststellungszeitpunkt, nicht live
+    referenziert (Prompt 03 Punkt 2: "Sollmenge zum Zeitpunkt der Feststellung")."""
+
+    __tablename__ = "fehlbestand"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    erzeugt_von_server_id: Mapped[int] = mapped_column(ForeignKey("systemknoten.id"), nullable=False)
+    objekt_id: Mapped[int] = mapped_column(ForeignKey("objekt.id"), nullable=False)
+    material_id: Mapped[int] = mapped_column(ForeignKey("material.id"), nullable=False)
+    standort_id: Mapped[int] = mapped_column(ForeignKey("standort.id"), nullable=False)
+    sollmenge: Mapped[Decimal] = mapped_column(Numeric, nullable=False)
+    istmenge: Mapped[Decimal] = mapped_column(Numeric, nullable=False)
+    fehlmenge: Mapped[Decimal] = mapped_column(Numeric, nullable=False)
+    entstanden_am: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), nullable=False)
+    festgestellt_von: Mapped[int] = mapped_column(ForeignKey("benutzer.id"), nullable=False)
+    kontrolle_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("kontrolle.id"))
+    ursache: Mapped[str | None] = mapped_column(String)
+    verantwortlicher_id: Mapped[int | None] = mapped_column(ForeignKey("benutzer.id"))
+    status: Mapped[FehlbestandStatus] = mapped_column(
+        fehlbestand_status_pg, nullable=False, default=FehlbestandStatus.offen
+    )
+    erledigt_am: Mapped[datetime | None] = mapped_column(TIMESTAMP(timezone=True))

backend/app/models/historie.py

@@ -0,0 +1,27 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.dialects.postgresql import JSONB, TIMESTAMP, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Historie(Base):
+    """Prompt 13: vollständige Audit-Protokollierung ist Sprint 5. Hier bereits
+    angelegt, weil Sprint 3 (Objekt-Übernahme, Prompt 02.8) einen ersten
+    Ereignistyp braucht – append-only, kein Update/Delete durch die Anwendung."""
+
+    __tablename__ = "historie"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    erzeugt_von_server_id: Mapped[int] = mapped_column(ForeignKey("systemknoten.id"), nullable=False)
+    zeitpunkt: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), nullable=False)
+    benutzer_id: Mapped[int | None] = mapped_column(ForeignKey("benutzer.id"))
+    ereignistyp: Mapped[str] = mapped_column(String, nullable=False)
+    entitaet_typ: Mapped[str] = mapped_column(String, nullable=False)
+    entitaet_id: Mapped[str] = mapped_column(String, nullable=False)
+    alter_wert: Mapped[dict | None] = mapped_column(JSONB)
+    neuer_wert: Mapped[dict | None] = mapped_column(JSONB)
+    begruendung: Mapped[str | None] = mapped_column(String)

backend/app/models/kontrolle.py

@@ -0,0 +1,53 @@
+import enum
+import uuid
+from datetime import datetime
+from decimal import Decimal
+
+from sqlalchemy import Boolean, ForeignKey, Numeric, String
+from sqlalchemy.dialects.postgresql import ENUM as PgEnum, TIMESTAMP, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class KontrollStatus(str, enum.Enum):
+    nicht_gestartet = "nicht_gestartet"
+    in_bearbeitung = "in_bearbeitung"
+    abgeschlossen = "abgeschlossen"
+    abgebrochen = "abgebrochen"
+
+
+kontroll_status_pg = PgEnum(KontrollStatus, name="kontroll_status", create_type=False)
+
+
+class Kontrolle(Base):
+    """Prompt 02: Kontrolle ändert NIEMALS Ist-Menge, ist reine Erfassung (Punkt 9,
+    Vier-Kernbegriffe-Tabelle). Status='in_bearbeitung' IST die Objekt-Sperre
+    (Punkt 8) – kein separates Sperr-Modell nötig."""
+
+    __tablename__ = "kontrolle"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    erzeugt_von_server_id: Mapped[int] = mapped_column(ForeignKey("systemknoten.id"), nullable=False)
+    objekt_id: Mapped[int] = mapped_column(ForeignKey("objekt.id"), nullable=False)
+    benutzer_id: Mapped[int] = mapped_column(ForeignKey("benutzer.id"), nullable=False)
+    status: Mapped[KontrollStatus] = mapped_column(
+        kontroll_status_pg, nullable=False, default=KontrollStatus.in_bearbeitung
+    )
+    gestartet_am: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), nullable=False)
+    beendet_am: Mapped[datetime | None] = mapped_column(TIMESTAMP(timezone=True))
+    abbruch_grund: Mapped[str | None] = mapped_column(String)
+    signatur: Mapped[bytes | None] = mapped_column()
+
+
+class Kontrollposition(Base):
+    __tablename__ = "kontrollposition"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    kontrolle_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("kontrolle.id"), nullable=False
+    )
+    material_id: Mapped[int] = mapped_column(ForeignKey("material.id"), nullable=False)
+    sollmenge_snapshot: Mapped[Decimal] = mapped_column(Numeric, nullable=False)
+    istmenge_erfasst: Mapped[Decimal] = mapped_column(Numeric, nullable=False)
+    abweichung: Mapped[bool] = mapped_column(Boolean, nullable=False)