erp_naurua/docs/architektur/modulkarte.md

Modulkarte ERP Naurua

Stand: 2026-06-15 Status: Architektur-Arbeitskarte

1. Zweck

Diese Modulkarte ordnet das System in klar getrennte fachliche Hauptmodule, Submodule und technische Querschnittsbereiche. Sie dient als Zielbild fuer die saubere Trennung von Ownership, Schnittstellen und wiederverwendbaren shared-Bausteinen.

2. Leitlinien

• Jedes Hauptmodul besitzt genau eine Primaerverantwortung.
• Submodule sind nur interne fachliche Zuschnitte innerhalb eines Hauptmoduls.
• shared enthaelt nur fachlich neutrale, wiederverwendbare Bausteine.
• system enthaelt nur technische Runtime-, Start-, Trigger- und Laufzeitlogik.
• Fachliche Logik bleibt immer im owning Modul.
• Cross-Modul-Zugriffe erfolgen nur ueber explizite Schnittstellen.

3. Moduluebersicht

Modul	Typ	Submodule	Primaerverantwortung	Owned Daten / Artefakte	Writes	Reads	Public Interface	shared-Bedarf
Kontakte	Hauptmodul	Stammdaten, Adressen, Kommunikationsdaten	Kunden-, Lieferanten- und Kontaktstamm	party, address, contact	Kontaktstamm, Adressen, Kommunikationsdaten	Referenzen aus Bestellungen, Buchhaltung, Beratung	Kontakt-API, Such- und Lookup-Schnittstellen	Validierung, Formatierung, UI-Bausteine
Bestellungen	Hauptmodul	Bestellkopf, Positionen, Status	Operative Bestellverarbeitung	sales_order, sales_order_line, Statusdaten	Bestellanlage, Status, Zuordnung	Kontakte, Artikel-Mapping, Lager	Bestell-API, Status-API	Geld-/Datumsformat, Tabellen- und Status-Patterns
Lager	Hauptmodul	Chargen, Bewegungen, Bestandsfuehrung	Bestand, Charge, MHD, Bewegungen	product, stock_lot, stock_move, v_stock_lot_balance	Warenzugang, -abgang, Umlagerung, Chargenpflege	Bestellungen, Import, Direktverkauf	Lager-API, Bestands- und Chargen-Schnittstellen	Listen-, Detail- und Statusdarstellung
Artikel-Mapping	Hauptmodul	Externe Artikel, interne Artikel, Zuordnung	Aufloesung externer Shopdaten auf interne Artikel	sellable_item, external_item_alias, sellable_item_component	Aliaspflege, Zuordnung, Bundle-/Komponentenpflege	Bestellungen, Import	Mapping-API	Suchlogik, Tabellenmuster, Normalisierung
Import / Integration	Hauptmodul	Webhooks, Import-Routing, externe Adapter	Annahme und Verteilung externer Eingangsdaten	Integrationsdaten, Importzustand, technische Events	Importausloesung, technische Events	Externe Quellen, operative Kernmodule	Webhook- und Import-Schnittstellen	HTTP-nahe Bausteine, Parsing, technische Validierung
Direktverkauf	Hauptmodul	Tageserfassung, Sammelverkauf	Manuelle Erfassung von Direktverkaeufen	Direktverkaufsbelege, Erfassungsdaten	Direktverkauf, Ausloesung operativer Folgeschritte	Kontakte optional, Lager, Bestellungen	Direktverkaufs-UI und API	Erfassungsmuster, Formularbausteine
Buchhaltung	Hauptmodul	Debitoren, Kreditoren, Hauptbuch, Nebenbuecher	Finanzbuchhaltung, Kontierung, Abschluss, Steuerlogik	Buchungssaetze, Konten, OP-Positionen, Steuerdaten	Verbuchung, OP-Pflege, Abschlusslaeufe	Freigegebene ERP-Belege, Zahlungsdaten, Kontenplan	Buchhaltungs-API, Buchungsimport, Zahlungsabgleich	Geld-/Steuerformat, Listen, Prüf- und Statusmuster
Kundenberatung	Hauptmodul	Gespraechserfassung, Empfehlungen, Follow-ups	Beratungsfall, Bedarf, Empfehlung, Rueckmeldung	Beratungsgespräche, Empfehlungen, Rueckmeldungen	Gespraech, Notizen, Follow-ups	Kontakte, Produkte, Bestellungen	Beratungs-API, Fall- und Verlaufsschnittstellen	Formular- und Verlaufsmuster
shared	Technischer Bereich	UI, Helpers, technische Services	Fachlich neutrale Wiederverwendung	Wiederverwendbare technische Bausteine	Keine fachlichen Writes	Mehrere Module	Gemeinsame technische APIs und Komponenten	Kernbereich
system	Technischer Bereich	Runtime, Trigger, Scheduler, Supervisor	Technische Laufzeit und Ausfuehrungslogik	Jobs, Trigger, technische Laufzeiten	Systemnahe Laufzeitlogik	Technische Zustandsdaten	Systeminterne technische Schnittstellen	Laufzeit-, Job- und Triggerbausteine

4. Modulzuschnitt im Zielbild

4.1 ERP-Kern

Der ERP-Kern besteht aus:

• Kontakte
• Bestellungen
• Lager
• Artikel-Mapping
• Import / Integration
• Direktverkauf

Diese Module bilden die operative Kernverarbeitung. Sie duerfen Buchhaltung nur ueber klare Integrationsschnittstellen versorgen.

4.2 Buchhaltungssystem

Die Buchhaltung ist ein eigenes Hauptmodul mit eigener fachlicher Ownership.

Es erhaelt aus dem ERP:

• freigegebene Rechnungen oder Erlosereignisse
• Zahlungsinformationen
• relevante Debitoren-/Kreditoren-Referenzen
• Buchungsgrundlagen aus operativen Belegen

Es fuehrt selbst:

• Kontierung
• Hauptbuch
• Nebenbuecher
• OP-Verwaltung
• Zahlungslauf
• Mahnwesen
• Abschluss und Steuerlogik

4.3 Kundenberatung

Kundenberatung ist ein eigenes Hauptmodul fuer fall- und gespraechsbezogene Arbeit.

Es erhaelt aus dem ERP:

• Kundenstamm
• Kaufhistorie
• produktbezogene Referenzen

Es fuehrt selbst:

• Gespraechserfassung
• Bedarfserhebung
• Produktempfehlungen
• Rueckmeldungen
• Follow-up-Logik

5. shared-Regeln fuer das Zielbild

In shared gehoeren nur Bausteine, die fachlich neutral sind und in mehreren Modulen wiederverwendet werden koennen:

• UI-Komponenten und Layout-Bausteine
• Tabellen, Formulare, Statusdarstellung
• Validierung ohne Fachentscheidungen
• Datums-, Geld- und Formatierungshelfer
• technische API-Clients
• Logging, Auth- und Session-nahe Hilfen
• generische Fehler- und Ladezustandsmuster

Nicht in shared gehoeren:

• Buchhaltungsregeln
• Lagerlogik
• Beratungslogik
• Bestellfachlogik
• modulpezifische Dateninterpretation

6. Naechste Strukturierungsarbeit

Aus dieser Modulkarte folgen als naechste Dokumente:

1. Modulvertraege je Hauptmodul
2. Owned-DB-Register je Modul
3. Prozessvertraege fuer die Hauptprozesse je Modul
4. Liste der wiederverwendbaren shared-Bausteine