# Fach- und Technikkonzept für das FEDEO-Lagersystem
## Zielbild
FEDEO soll Artikelbestände je Lagerplatz nachvollziehbar führen und die täglichen Vorgänge Wareneingang, Umlagerung, Reservierung, Projektverbrauch, Rückgabe und Inventur unterstützen. Jede Bestandsänderung wird als unveränderliche Buchung protokolliert. Der aktuelle Bestand ist damit kein frei editierbares Feld, sondern das Ergebnis aller bestätigten Lagerbuchungen.
Das Zielbild trennt drei heute teilweise vermischte Begriffe:
- **Artikel** (`products`) beschreiben einen wiederverwendbaren Material- oder Handelsartikel, zum Beispiel „Kabel NYM-J 3×1,5“.
- **Bestand** beschreibt, welche Menge eines Artikels sich an welchem Lagerplatz befindet.
- **Inventarartikel** (`inventoryitems`) sind individuell verwaltete Betriebsmittel oder Anlagegüter, zum Beispiel ein Messgerät oder Fahrzeugzubehör. Sie können eine Seriennummer und einen aktuellen Standort haben, sind aber kein mengenmäßig geführter Lagerbestand.
Kundeninventar bleibt ebenfalls ein eigener Bereich. Ein beim Kunden verbautes oder betreutes Gerät ist nicht automatisch eigener verfügbarer Lagerbestand.
## Vorhandene Basis und Handlungsbedarf
FEDEO bringt bereits wesentliche Bausteine mit:
- Artikelstammdaten mit Einheit, Artikelnummer, EAN, Barcodes, Preisen, Hersteller und Lieferantenzuordnung
- hierarchische eigene Lagerplätze und Kundenlagerplätze
- eigenes Inventar und Kundeninventar einschließlich Seriennummern
- Projekte und Belege, die später als Herkunft oder Ziel einer Lagerbuchung dienen können
- Rollen, Mandantentrennung, Änderungshistorie und Nummernkreise
- die Tabelle `movements` mit Artikel, Menge, Lagerplatz, Projekt und Seriennummern
Die vorhandene Tabelle `movements` ist jedoch noch kein belastbares Lagerbuch. Ihr fehlen unter anderem Buchungsart und -status, Gegenlager bei Umlagerungen, Belegreferenz, Stornobeziehung, Chargenmodell, Reservierungen und Schutz vor doppelter Verarbeitung. Zudem wird sie aktuell weder über eine eigene Route noch über eine Oberfläche genutzt.
Die Mengenfelder von Inventar und Kundeninventar sollten nicht zur Bestandsführung von Artikeln verwendet werden. Andernfalls entstehen parallele Wahrheiten zwischen Artikel, Inventar und Lagerbewegung.
## Fachliche Leitlinien
1.**Buchungen statt Überschreiben:** Bestände werden ausschließlich durch bestätigte Lagerbuchungen verändert.
2.**Keine stillen Korrekturen:** Fehlerhafte Buchungen werden durch eine Gegenbuchung storniert, nicht gelöscht oder nachträglich verändert.
3.**Ein Vorgang, eine Transaktion:** Alle Positionen eines Wareneingangs oder einer Umlagerung werden vollständig oder gar nicht gebucht.
4.**Mandantentrennung in jeder Abfrage:** Artikel, Lagerplätze, Buchungen und Referenzen müssen zum aktiven Mandanten gehören.
5.**Nachvollziehbare Herkunft:** Jede Buchung speichert Benutzer, Zeitpunkt, Buchungsgrund und optional Projekt, Lieferant oder FEDEO-Beleg.
6.**Reserviert ist nicht entnommen:** Reservierungen reduzieren den verfügbaren, aber nicht den physischen Bestand.
7.**Seriennummern und Chargen sind Bewegungsdaten:** Sie gehören zu konkreten Bestandseinheiten und nicht als Liste in eine allgemeine Buchungszeile.
8.**Bestätigen ist endgültig:** Entwürfe sind änderbar; bestätigte Buchungen sind unveränderlich.
## Fachliches Datenmodell
### Artikelstamm erweitern
`products` bleibt der zentrale Artikelstamm und erhält lagerbezogene Einstellungen:
| Feld | Bedeutung |
| --- | --- |
| `stockManaged` | Artikel wird im Lager geführt |
| `trackingMode` | `none`, `lot` oder `serial` |
| `allowNegativeStock` | negativer Bestand erlaubt; standardmäßig `false` |
| `valuationMethod` | zunächst fest `moving_average`, für spätere Erweiterung vorbereitet |
Die bestehende `unit` ist die Bestandsbasiseinheit. Mengen sollten als `numeric`, nicht als `bigint`, gespeichert werden, da Einheiten wie Meter, Stunden oder Kilogramm Dezimalmengen benötigen. Die erlaubte Genauigkeit kann aus `units.step` abgeleitet werden.
### Lagerstruktur
Die bestehenden `spaces` können als hierarchische Lagerstruktur weiterverwendet werden. Ergänzt werden sollten:
| `stockEnabled` | an diesem Knoten darf Bestand liegen |
| `barcode` | scanbare eindeutige Kennung |
| `sortOrder` | stabile Reihenfolge in der Lageransicht |
Ein typischer Baum lautet beispielsweise `Hauptlager > Halle A > Regal 03 > Fach 02`. Nur Blattknoten beziehungsweise ausdrücklich aktivierte Knoten dürfen Bestand tragen. Die Kombination aus `tenant` und `space_number` sowie ein gesetzter Barcode müssen eindeutig sein. Ein Lagerplatz darf nicht sich selbst oder einen seiner Nachfolger als übergeordneten Lagerplatz erhalten.
### Lagerbeleg und Buchungszeilen
Für die belastbare Umsetzung empfiehlt sich ein Belegkopf mit mehreren Buchungszeilen:
- optionale Referenzen auf `project`, `vendor`, `createddocument` und einen späteren Einkaufsbeleg
-`externalReference` für Lieferschein- oder Fremdbelegnummern
-`idempotencyKey` zum Schutz vor Doppelbuchungen durch API, Scanner oder Wiederholungsversuche
-`reversalOf` beziehungsweise `reversedBy`
-`createdAt`, `createdBy`, `postedAt`, `postedBy`
#### `stock_transaction_lines`
-`id` als UUID
-`transactionId`
-`position`
-`productId`
-`quantity` als positiver `numeric`-Wert
-`fromSpaceId`, optional
-`toSpaceId`, optional
-`unitCost`, optional
-`lotId`, optional
-`notes`, optional
Mindestens eine Seite einer Zeile muss gesetzt sein. Ein Wareneingang besitzt nur `toSpaceId`, eine Entnahme nur `fromSpaceId`, eine Umlagerung beide Seiten. Die Buchungsart bestimmt zusätzlich, welche Kombination erlaubt ist. Dadurch lässt sich eine Umlagerung atomar abbilden, ohne zwei lose Bewegungen erzeugen zu müssen.
- optionale Verbindung zu Inventar oder Kundeninventar, wenn ein ausgegebenes Gerät dort weitergeführt wird
Bei Seriennummern entspricht jede gebuchte Einheit genau einer Seriennummer. Bei Chargen muss die Summe der Chargenmengen der Buchungsmenge entsprechen.
### Bestände und Reservierungen
`stock_balances` ist eine technisch gepflegte Projektion für schnelle Listen und Prüfungen:
`quantityAvailable` wird als `quantityOnHand - quantityReserved` berechnet. Die eindeutige Kombination verhindert doppelte Bestandszeilen. Die Buchungszeilen bleiben die fachliche Wahrheit; `stock_balances` kann aus ihnen jederzeit neu aufgebaut und geprüft werden.
`stock_reservations` enthält reservierte Mengen für ein Projekt, eine Aufgabe oder einen Beleg. Zustände sind `active`, `partially_fulfilled`, `fulfilled`, `cancelled` und `expired`. Eine spätere Entnahme erfüllt die Reservierung in derselben Datenbanktransaktion.
Für das MVP kann auf Chargen, Seriennummern und Reservierungen zunächst verzichtet werden. Das Schema der Buchungen sollte diese Erweiterungen aber bereits ermöglichen.
## Buchungslogik
Beim Bestätigen eines Lagerbelegs führt das Backend in **einer Datenbanktransaktion** folgende Schritte aus:
1. Mandant, Berechtigung, Status und Eindeutigkeit des `idempotencyKey` prüfen.
2. Alle Artikel und Lagerplätze laden und ihre Zugehörigkeit zum Mandanten validieren.
3. Einheiten, Trackingregeln, Mengen und Pflichtangaben prüfen.
4. Betroffene `stock_balances` in einer stabilen Reihenfolge sperren.
5. Verfügbarkeit prüfen; bei einer Umlagerung ist die Quellseite maßgeblich.
6. Beleg und Zeilen als `posted` speichern und Bestandsprojektion aktualisieren.
7. Seriennummern, Chargen, Reservierungen und gleitenden Durchschnittspreis aktualisieren.
8. Einen verständlichen Historieneintrag erzeugen.
Bestandsrelevante Endpunkte dürfen nicht über die generische CRUD-Route umgesetzt werden, weil dort die fachlichen Invarianten, Sperren und Statusübergänge nicht sicher erzwungen werden können. Dafür wird ein eigener Lagermodul-Service verwendet.
Parallelzugriffe müssen über Zeilensperren oder ein atomisches SQL-Update wie `quantity_on_hand >= benötigte_menge` abgesichert werden. Eine reine Prüfung im Frontend verhindert keine Überentnahme.
### Bewertung
Für die erste Version bietet sich der **gleitende Durchschnittspreis** an:
```text
neuer Durchschnitt =
(alter Bestand × alter Durchschnitt + Zugangsmenge × Zugangspreis)
/ (alter Bestand + Zugangsmenge)
```
Abgänge werden mit dem zum Buchungszeitpunkt gültigen Durchschnitt bewertet. Der Wert wird auf der Buchungszeile festgeschrieben, damit spätere Preisänderungen historische Projektkosten nicht verändern. Stornozeilen übernehmen exakt Menge und Wert der Ursprungsbuchung mit umgekehrter Wirkung.
## Kernabläufe
### Wareneingang
1. Lieferant und optionale Lieferscheinnummer wählen.
2. Artikel scannen oder suchen, Menge, Zielplatz und Einkaufspreis erfassen.
3. Bei Bedarf Charge oder Seriennummern erfassen.
4. Als Entwurf speichern oder direkt bestätigen.
5. Bestand und gleitenden Durchschnittspreis erhöhen; optional Etiketten drucken.
Ein Eingangsrechnungsimport darf einen Wareneingang vorbereiten, aber nicht automatisch bestätigen. Rechnung und tatsächliche Warenannahme können zeitlich und mengenmäßig abweichen.
### Umlagerung
Quelle scannen, Artikel und Menge erfassen, Ziel scannen und bestätigen. Quellabgang und Zielzugang sind eine gemeinsame Buchung. Für mobile Lagerarbeit sollte dieser Ablauf mit wenigen Eingaben und großen Scanflächen umgesetzt werden.
### Projektentnahme und Rückgabe
Eine Entnahme reduziert Bestand und schreibt Menge sowie Wert einem Projekt zu. Rückgaben referenzieren nach Möglichkeit die ursprüngliche Entnahme. Damit können FEDEO-Projekte tatsächliche Materialkosten statt nur kalkulierter Materialpreise ausweisen.
### Reservierung
Material wird für ein Projekt vorgemerkt. Der physische Bestand bleibt unverändert, der verfügbare Bestand sinkt. Beim Kommissionieren oder bei der Entnahme wird die Reservierung ganz oder teilweise erfüllt.
### Inventur
1. Inventurzählung für Lager oder Teilbaum eröffnen und optional Plätze für normale Buchungen sperren.
2. Sollmengen als unveränderlichen Start-Snapshot speichern.
3. Zählmengen mobil erfassen; bei Bedarf Vier-Augen-Freigabe ab einer Differenzschwelle.
4. Differenzen prüfen und freigeben.
5. Nur die Differenzen als `count`- beziehungsweise `adjustment`-Buchung verbuchen.
Der gezählte Wert überschreibt niemals direkt den Bestand.
### Storno
Ein bestätigter Beleg erhält eine Gegenbuchung mit Referenz auf das Original. Ein erneutes Storno desselben Belegs ist ausgeschlossen. Kann die Gegenbuchung wegen zwischenzeitlich fehlenden Bestands nicht durchgeführt werden, braucht es eine berechtigte Korrekturbuchung statt einer stillen negativen Menge.
## API-Schnittstellen
Vorgeschlagene dedizierte Endpunkte:
| Methode und Pfad | Zweck |
| --- | --- |
| `GET /stock/overview` | Bestände, verfügbar/reserviert, Wert und Meldebestand |
| `GET /stock/products/:id` | Bestand eines Artikels nach Platz und Charge |
| `GET /stock/spaces/:id` | Inhalt eines Lagerplatzes einschließlich Unterplätzen |
| `GET /stock/scan/:code` | Artikel, Seriennummer oder Lagerplatz auflösen |
Schreibende Aufrufe akzeptieren einen Idempotenzschlüssel. Fehlerantworten sollen fachlich verwertbare Codes liefern, zum Beispiel `INSUFFICIENT_STOCK`, `SERIAL_ALREADY_IN_STOCK`, `LOCATION_NOT_STOCK_ENABLED` oder `TRANSACTION_ALREADY_POSTED`.
Die wichtigsten Lese- und Buchungsfunktionen können anschließend auch als MCP-Werkzeuge registriert werden. Schreibende MCP-Werkzeuge sollten denselben Service und dieselben Berechtigungsprüfungen wie die HTTP-API verwenden.
## Oberfläche
Unter dem bestehenden Navigationspunkt **Lager** werden folgende Bereiche ergänzt:
- **Übersicht:** Bestandswert, Artikel unter Meldebestand, offene Reservierungen und letzte Buchungen
- **Bestände:** Artikelsicht und Lagerplatzsicht mit Suche, Filtern und Export
- **Buchen:** Wareneingang, Entnahme, Rückgabe, Umlagerung und Korrektur
- **Reservierungen:** offene und teilweise erfüllte Reservierungen
- **Inventur:** Zähllisten, Fortschritt, Differenzen und Freigabe
- **Lagerjournal:** unveränderliche Historie aller bestätigten Buchungen
- **Stammdaten:** vorhandene Artikel, Lagerplätze, Inventar und Kundeninventar
Die Bestandsansicht zeigt mindestens Ist-Bestand, reserviert, verfügbar, Durchschnittspreis, Bestandswert und Meldebestandsstatus. Von Artikel, Lagerplatz, Projekt und Beleg führt jeweils ein Link in die zugehörige Detailansicht.
Für Smartphone und Tablet sind Kamera-Barcodescan und optional RFID sinnvoll. Ein Scan-Endpunkt sollte Codes typisiert auflösen, damit derselbe Ablauf Artikelbarcodes, Lagerplatzcodes und Seriennummern unterscheiden kann. Die vorhandene Geräteanbindung kann später für stationäre Scanner und Etikettendruck genutzt werden.
## Rollen und Berechtigungen
Die bisherige Sammelberechtigung `inventory` sollte mindestens in folgende Rechte aufgeteilt werden:
-`stock-view`
-`stock-receive`
-`stock-transfer`
-`stock-issue`
-`stock-reserve`
-`stock-adjust`
-`stock-count`
-`stock-count-approve`
-`stock-reverse`
-`stock-value-view`
-`stock-settings`
Einkaufs- und Bestandswerte können damit vor operativen Lagerbenutzern verborgen werden. Korrektur, Inventurfreigabe und Storno sollten restriktiver vergeben werden als normale Ein- und Auslagerungen.
## Abgrenzung zu Belegen und Inventar
- Ein Angebot reserviert und bucht keinen Bestand.
- Ein Auftrag kann optional reservieren.
- Ein Lieferschein beziehungsweise eine ausdrücklich bestätigte Materialausgabe löst die Entnahme aus.
- Eine Rechnung bucht nicht nochmals, wenn bereits ein Lieferschein oder eine Materialausgabe gebucht wurde.
- Eine Stornorechnung ist nicht automatisch ein physischer Warenrückgang; die tatsächliche Rücknahme wird gesondert gebucht.
- Seriengeführte Ware kann bei Ausgabe optional einen Inventar- oder Kundeninventardatensatz erzeugen. Die Verbindung bleibt nachvollziehbar, die beiden Bereiche werden aber nicht zu einer Tabelle verschmolzen.
Diese Trennung verhindert doppelte Buchungen und bildet kaufmännische sowie physische Ereignisse korrekt ab.
## Datenintegrität und Betrieb
Wichtige Datenbankregeln und Indizes:
- Eindeutigkeit von Lagerbelegnummer und Idempotenzschlüssel je Mandant
- Eindeutigkeit von Lagerplatznummer und Lagerplatzbarcode je Mandant
- positive Buchungsmenge und voneinander verschiedene Quell- und Zielplätze
- Seriennummer je Mandant und Artikel eindeutig
- Indizes auf `(tenant, productId, spaceId)`, `(tenant, bookingDate)`, Projekt- und Belegreferenzen
- Fremdschlüssel möglichst mit `RESTRICT`; gebuchte Stammdaten werden archiviert, nicht gelöscht
-`posted`-Buchungen auf Datenbank- beziehungsweise Serviceebene unveränderlich
Ein periodischer Integritätsjob vergleicht `stock_balances` mit der Summe des Lagerjournals und meldet Abweichungen. Backups müssen Buchungen und Projektion gemeinsam erfassen; die Projektion bleibt dennoch vollständig rekonstruierbar.
## Einführung in Stufen
### Stufe 1 – belastbares MVP
- Artikel als lagergeführt kennzeichnen
- Lagerplätze um Typ, Bestandsfreigabe und Barcode ergänzen
- Lagerbeleg, Buchungszeilen und Bestandsprojektion einführen
- Anfangsbestand, Wareneingang, Entnahme, Rückgabe, Umlagerung und Storno
- Bestandsübersicht und Lagerjournal
- Projektbezug, negativer Bestand standardmäßig gesperrt
- Rollen und serverseitige Berechtigungen
Damit ist bereits ein produktiv nutzbares Lager mit vollständiger Nachvollziehbarkeit vorhanden.
### Stufe 2 – operative Unterstützung
- Reservierungen und Kommissionierung
- Inventurworkflow
- Meldebestand und Benachrichtigungen
- Kamera-Scan, Lagerplatz- und Artikeletiketten
- Materialkosten in Projekten und vorbereitete Buchung aus Belegen
- Im- und Export für Anfangsbestände
### Stufe 3 – erweiterte Logistik
- Chargen, Ablaufdaten und Seriennummern
- mehrere Lager beziehungsweise Niederlassungen und Fahrzeuglager
- Bestellvorschläge und Einkaufsprozess
- Kunden- oder Konsignationsbestand mit explizitem Eigentümer
- FIFO als optionale Bewertungsmethode
- RFID- und Geräteagent-Integration
## Migration des aktuellen Datenbestands
Vor der Einführung wird pro Mandant ausgewertet, wie `inventoryitems.quantity`, `inventoryitems.currentSpace` und die vorhandene Tabelle `movements` tatsächlich verwendet wurden.
Empfohlenes Vorgehen:
1. Bestehende Artikel und Lagerplätze bereinigen und Lagerplätze eindeutig nummerieren.
2. Inventarartikel klassifizieren: individuelles Betriebsmittel, mengenmäßiger Altbestand oder fehlerhafte Dublette.
3. Echte Betriebsmittel im Inventar belassen; mengenmäßige Bestände einem `product` zuordnen.
4. Zu einem gemeinsam festgelegten Stichtag je Artikel und Lagerplatz eine bestätigte Anfangsbestandsbuchung erzeugen.
5. Historische `movements` nur übernehmen, wenn ihre Semantik und Vollständigkeit verlässlich geklärt werden können; andernfalls revisionssicher als Altbestand erhalten.
6. Summen, Bestandswerte und Seriennummern mit einem Migrationsbericht abstimmen.
7. Danach direkte Mengenänderungen am Inventar nicht mehr als Lagerbuchung zulassen.
Eine automatische Eins-zu-eins-Migration von `inventoryitems` wäre riskant, weil ein Datensatz heute sowohl ein einzelnes Gerät als auch eine Menge ähnlicher Gegenstände beschreiben kann.
## Abnahmekriterien für das MVP
- Zwei parallele Entnahmen können gemeinsam nie mehr als den verfügbaren Bestand ausgeben.
- Jede Bestandszahl lässt sich bis zu ihren bestätigten Buchungen zurückverfolgen.
- Eine Umlagerung verändert den Gesamtbestand nicht und wird atomar gebucht.
- Ein Storno stellt Menge und Wertwirkung der Ursprungsbuchung exakt wieder her.
- Wiederholte API-Anfragen mit demselben Idempotenzschlüssel erzeugen keine Doppelbuchung.
- Benutzer ohne Wertberechtigung sehen weder Einkaufspreis noch Bestandswert.
- Artikel und Lagerplätze eines anderen Mandanten können weder gelesen noch verbucht werden.
- Dezimalmengen werden entsprechend der Artikeleinheit korrekt gebucht.
- Aus dem Lagerjournal neu berechnete Bestände entsprechen vollständig `stock_balances`.
- Projektentnahmen erscheinen mit dem zum Buchungszeitpunkt festgeschriebenen Materialwert am Projekt.
## Empfohlene erste Umsetzung
Als erster vertikaler Schnitt sollte **manueller Wareneingang plus Umlagerung plus Projektentnahme** umgesetzt werden. Dieser Schnitt erzwingt bereits das richtige Buchungsmodell, die Bestandsprüfung, Mandantensicherheit, Berechtigungen und eine brauchbare Oberfläche. Reservierungen, Inventur und Tracking lassen sich danach ergänzen, ohne das Fundament erneut umzubauen.
Die vorhandene Tabelle `movements` sollte dabei nicht schrittweise zu einer universellen CRUD-Tabelle ausgebaut werden. Sauberer ist eine neue, transaktionale Struktur aus `stock_transactions`, `stock_transaction_lines` und `stock_balances`. `movements` bleibt während der Migration lesbar und kann nach einer geprüften Übernahme später außer Betrieb genommen werden.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
