# 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 ausschließlich individuell verwaltete Betriebsmittel oder Anlagegüter, zum Beispiel ein Messgerät oder Fahrzeugzubehör. Sie sind für die Lagerbestandsführung vollständig irrelevant. 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 werden nicht zur Bestandsführung von Artikeln verwendet. Insbesondere wird `inventoryitems` weder in Bestandsberechnungen noch in Lagerbuchungen oder in die Bestandsmigration einbezogen. Andernfalls entstünden 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. **Negativbestände sind zulässig und sichtbar:** Verkäufe dürfen einen Bestand unter null buchen, wenn die Ware bereits berechnet, aber noch nicht geliefert beziehungsweise beschafft wurde. Ein Negativbestand wird als Handlungsbedarf hervorgehoben und niemals stillschweigend ausgeblendet. 7. **Reserviert ist nicht entnommen:** Reservierungen reduzieren den verfügbaren, aber nicht den buchmäßigen Bestand. 8. **Seriennummern und Chargen sind Bewegungsdaten:** Sie gehören zu konkreten Bestandseinheiten und nicht als Liste in eine allgemeine Buchungszeile. 9. **Bestätigen ist endgültig:** Entwürfe sind änderbar; bestätigte Buchungen sind unveränderlich. 10. **Ein Verkauf wird nur einmal gebucht:** Lieferschein und Rechnung werden positions- und mengenbezogen gegeneinander abgeglichen. ## 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; für den festgelegten Verkaufsprozess standardmäßig `true` | | `minimumStock` | mandantenweiter Mindestbestand, optional | | `reorderPoint` | Meldebestand, optional | | `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. Lagerplatzarten werden nicht als festes Enum programmiert, sondern je Mandant in `space_types` frei gepflegt. `space_types` enthält mindestens `id`, `tenant`, `name`, `code`, `description`, `stockEnabledByDefault`, `icon`, `sortOrder` und `archived`. So können Mandanten beispielsweise „Hauptlager“, „Regal“, „Fach“, „Fahrzeug“, „Baustellencontainer“ oder eigene Begriffe anlegen, ohne eine neue Softwareversion zu benötigen. `spaces` wird ergänzt um: | Feld | Bedeutung | | --- | --- | | `spaceTypeId` | frei pflegbare Lagerplatzart | | `branchId` | zugehörige Niederlassung | | `stockEnabled` | an diesem Knoten darf Bestand liegen | | `barcode` | scanbare eindeutige Kennung | | `sortOrder` | stabile Reihenfolge in der Lageransicht | Jedes Lager gehört zu einer vorhandenen FEDEO-Niederlassung (`branches`). Untergeordnete Lagerplätze übernehmen diese Niederlassung; zur schnellen Filterung wird `branchId` auch auf ihnen gespeichert und beim Verschieben im Baum konsistent aktualisiert. Umlagerungen zwischen Niederlassungen sind normale, atomare Umlagerungsbuchungen und können gesondert ausgewertet werden. Für Mandanten ohne bisherige Niederlassung wird bei der Migration eine Standardniederlassung benötigt. Jede Niederlassung erhält optional `defaultReceiptSpaceId` und `defaultIssueSpaceId`. Diese Standardplätze müssen zur jeweiligen Niederlassung gehören und Bestand erlauben. So besitzt nicht der Artikel ein einziges mandantenweites Standardlager, sondern jede Niederlassung kann denselben Artikel aus ihrem eigenen Lager beziehen. Ein typischer Baum lautet beispielsweise `Niederlassung München > Hauptlager > Halle A > Regal 03 > Fach 02`. Nur 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. Typ, übergeordneter Platz und Niederlassung müssen stets demselben Mandanten angehören. ### Lagerbeleg und Buchungszeilen Für die belastbare Umsetzung empfiehlt sich ein Belegkopf mit mehreren Buchungszeilen: #### `stock_transactions` - `id` als UUID - `tenant` - `number` als lesbare Lagerbelegnummer - `type`: `opening`, `receipt`, `transfer`, `issue`, `return`, `adjustment`, `count`, `production`, `reversal` - `status`: `draft`, `posted`, `reversed` - `bookingDate` - `notes` - 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. ### Verknüpfung mit Rechnungen und Lieferscheinen Damit Rechnung und Lieferschein nicht dieselbe Menge doppelt ausbuchen, wird zusätzlich `stock_document_allocations` eingeführt: - `tenant` - `createdDocumentId` - `sourceLineId` als dauerhafte UUID der Belegposition - `productId` - `quantity` - `stockTransactionLineId` - `reversedAt`, optional Jede artikelbezogene Belegposition benötigt eine stabile `sourceLineId`. Beim Ableiten eines Lieferscheins oder einer Rechnung wird diese Herkunfts-ID in die neue Position übernommen. So kann das Backend auch Teilmengen durch die gesamte Belegkette verfolgen. Rechnungen und Lieferscheine erhalten eine verpflichtende `branchId` sowie einen vorbelegten `issueSpaceId`. Der Ausgabeplatz stammt standardmäßig aus `branches.defaultIssueSpaceId`, kann aber vor dem endgültigen Bestätigen geändert werden. Für Sonderfälle kann eine Position einen abweichenden Ausgabeplatz tragen. Beleg, Niederlassung und alle gewählten Ausgabeplätze müssen zum aktiven Mandanten gehören; bei abweichenden Niederlassungen verlangt FEDEO eine bewusste Bestätigung. Bei der Bestätigung eines Verkaufsbelegs wird je Position berechnet: ```text noch zu buchen = Belegmenge - bereits wirksam gebuchte Menge der Belegkette ``` Ein bestätigter Lieferschein bucht seine noch offene Menge sofort aus. Eine bestätigte Rechnung bucht nur die Menge aus, die nicht bereits durch einen zugehörigen Lieferschein oder eine frühere Rechnung wirksam gebucht wurde. Das funktioniert auch bei Teil- und Sammellieferungen. Ist die Rechnung bereits zuerst gebucht worden, erzeugt der später daraus erstellte Lieferschein keine zweite Lagerentnahme. Das Erzeugen, Ändern oder Speichern eines Entwurfs löst keine Buchung aus. Erst der fachliche Statuswechsel auf einen endgültigen beziehungsweise bestätigten Zustand ruft den Lagerbuchungsservice auf. Storno und Rücknahme erzeugen Gegenbuchungen und markieren die betroffenen Zuordnungen als aufgehoben. ### Chargen und Seriennummern `stock_lots` bildet Chargen ab: - Artikel, Chargennummer, optional Lieferantencharge - Herstellungs- und Ablaufdatum - optionale Lieferanten- und Wareneingangsreferenz - mandantenweit eindeutige Kombination aus Artikel und Chargennummer `stock_serials` bildet einzelne Seriennummern ab: - Artikel und Seriennummer - Status: `in_stock`, `reserved`, `issued`, `installed`, `scrapped` - aktueller Lagerplatz als performanter Cache - 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: - `tenant`, `productId`, `spaceId`, optional `lotId` - `quantityBooked` - `quantityReserved` - `averageUnitCost` - `updatedAt` `quantityAvailable` wird als `quantityBooked - quantityReserved` berechnet. `quantityBooked` ist der buchmäßige Sollbestand. Er kann negativ sein und zeigt dann eine bereits verkaufte, aber noch nicht vorhandene beziehungsweise gelieferte Menge. 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 und bei gesperrtem Negativbestand ablehnen; bei erlaubtem Negativbestand die Unterdeckung für Warnungen und Nachbeschaffung festhalten. 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 atomische SQL-Updates abgesichert werden. Falls ein Artikel oder Vorgang keinen Negativbestand erlaubt, muss die Bestandsbedingung Teil desselben atomischen Updates sein. Eine reine Prüfung im Frontend ist auch bei grundsätzlich zulässigen Negativbeständen nicht ausreichend, weil Buchungen und Bewertung sonst verloren gehen können. ### 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. Bei einem Abgang in den Negativbestand bleibt der letzte bekannte Durchschnittspreis als vorläufiger Wert erhalten. Ein späterer Zugang deckt zuerst die negative Menge. Die Differenz zwischen vorläufigem Abgangswert und tatsächlichem Zugangspreis wird als Preisabweichung protokolliert; erst eine darüber hinausgehende positive Restmenge bildet einen neuen Durchschnitt. Damit führt ein Vorzeichenwechsel nicht zu einer Division durch null oder einem wirtschaftlich unsinnigen Durchschnittspreis. ## 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. ### Verkauf über Lieferschein und Rechnung Beim endgültigen Bestätigen eines Lieferscheins wird die noch nicht gebuchte Artikelmenge der Belegkette aus dem gewählten Lager beziehungsweise Lagerplatz entnommen. Beim endgültigen Bestätigen einer Rechnung erfolgt dieselbe Prüfung; die Rechnung bucht ausschließlich noch nicht durch zugehörige Lieferscheine abgedeckte Mengen. Reicht der Bestand nicht aus, wird trotzdem gebucht und der Bestand negativ. Die Oberfläche weist die Unterdeckung unmittelbar aus. Dadurch ist sichtbar, welche bereits verkaufte Menge noch geliefert oder beschafft werden muss. Der auslösende Beleg, seine Position und die Niederlassung bleiben an der Lagerbuchung nachvollziehbar. Belegpositionen ohne verknüpften lagergeführten Artikel lösen keine Lagerbuchung aus. Vor der Bestätigung zeigt FEDEO eine Vorschau mit zu buchenden, bereits gebuchten und nicht zuordenbaren Positionen. Nicht zuordenbare Positionen verhindern die Belegbestätigung nicht, erzeugen aber einen deutlichen Hinweis. ### Reservierung Material wird für ein Projekt vorgemerkt. Der buchmäßige 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. Die Gegenbuchung übernimmt Menge und Wert des Originals exakt. Entsteht dadurch eine Unterdeckung, bleibt sie als negativer Bestand sichtbar und wird nicht durch eine abweichende Korrekturmenge kaschiert. ## 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/transactions` | paginierbares Lagerjournal | | `GET /stock/transactions/:id` | Lagerbeleg mit Zeilen und Historie | | `POST /stock/transactions` | Entwurf anlegen | | `PATCH /stock/transactions/:id` | Entwurf ändern | | `POST /stock/transactions/:id/post` | atomar bestätigen | | `POST /stock/transactions/:id/reverse` | Gegenbuchung erzeugen | | `POST /stock/reservations` | Bestand reservieren | | `POST /stock/counts` | Inventur eröffnen | | `POST /stock/counts/:id/complete` | Differenzen verbuchen | | `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 endgültig bestätigter Lieferschein löst die Entnahme seiner noch offenen Menge aus. - Eine endgültig bestätigte Rechnung löst ebenfalls eine Entnahme aus, aber nur für Mengen, die in derselben Belegkette noch nicht durch Lieferscheine oder frühere Rechnungen gebucht wurden. - Eine Stornorechnung ist nicht automatisch ein physischer Warenrückgang; die tatsächliche Rücknahme wird gesondert gebucht. - Das betriebliche Inventar (`inventoryitems`) bleibt vollständig unabhängig vom Lager und wird niemals automatisch aus einer Lagerbuchung erzeugt oder verändert. - Kundeninventar kann in einem getrennten späteren Prozess aus gelieferten Serienartikeln entstehen, beeinflusst aber keinen eigenen Lagerbestand. 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 - Eindeutigkeit der Lagerplatzart-Codes je Mandant - gültige Niederlassung und einheitliche Niederlassung innerhalb eines Lagerplatzbaums - positive Buchungsmenge und voneinander verschiedene Quell- und Zielplätze - höchstens eine wirksame Lagerzuordnung je Belegposition und gebuchter Teilmenge - 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 und Dezimalmengen unterstützen - frei pflegbare Lagerplatzarten einführen - Lagerplätze mit Niederlassung, Bestandsfreigabe und Barcode verbinden - Lagerbeleg, Buchungszeilen und Bestandsprojektion einführen - Anfangsbestand, Wareneingang, Entnahme, Rückgabe, Umlagerung und Storno - automatische, gegen Doppelbuchungen geschützte Entnahme durch bestätigte Lieferscheine und Rechnungen - Bestandsübersicht und Lagerjournal - Projekt- und Niederlassungsbezug, Negativbestände mit sichtbarer Unterdeckung - 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 - Fahrzeuglager und komplexere niederlassungsübergreifende Logistik - 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 Artikel, Lagerplätze und die vorhandene Tabelle `movements` tatsächlich verwendet wurden. `inventoryitems` gilt verbindlich als reines Inventar und bleibt von der Lagermigration ausgeschlossen. Empfohlenes Vorgehen: 1. Bestehende Niederlassungen prüfen und bei Bedarf eine Standardniederlassung anlegen. 2. Frei pflegbare Lagerplatzarten anlegen und vorhandene `spaces.type` zuordnen. 3. Bestehende Lagerplätze bereinigen, einer Niederlassung zuordnen und eindeutig nummerieren. 4. Lagergeführte Artikel bestimmen; Mengen werden ausschließlich auf Basis von `products` übernommen. 5. Zu einem gemeinsam festgelegten Stichtag je Artikel und Lagerplatz eine bestätigte Anfangsbestandsbuchung erzeugen. 6. Historische `movements` nur übernehmen, wenn ihre Semantik und Vollständigkeit verlässlich geklärt werden können; andernfalls revisionssicher als Altbestand erhalten. 7. Summen und Bestandswerte mit einem Migrationsbericht abstimmen. Bestehende `inventoryitems` werden weder automatisch umgewandelt noch zur Ermittlung eines Anfangsbestands herangezogen. ## Abnahmekriterien für das MVP - Zwei parallele Entnahmen gehen nicht verloren und ergeben exakt die Summe beider Buchungen; falls Negativbestand für einen Vorgang gesperrt ist, können sie 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. - Teil- und Sammellieferungen werden mengenbezogen abgeglichen; Lieferschein und Rechnung buchen gemeinsam niemals mehr als die wirksame Verkaufsmenge. - Negative Bestände bleiben mit auslösendem Verkaufsbeleg und Niederlassung nachvollziehbar. - Inventarartikel verändern Lagerbestände unter keinen Umständen. - 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 automatische Verkaufsentnahme durch Lieferschein und Rechnung** umgesetzt werden. Dieser Schnitt erzwingt bereits das richtige Buchungsmodell, Dezimalmengen, Negativbestände, Niederlassungszuordnung, stabile Belegpositions-IDs, Schutz vor Doppelbuchungen, Mandantensicherheit und Berechtigungen. Danach folgen Umlagerung und Projektentnahme; Reservierungen, Inventur und Tracking lassen sich anschließend 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.