From 7c2d1cedb64f7898eeba68b69b40bc83992dc64f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mathias=20Gla=CC=88ser?= Date: Sat, 19 Sep 2026 08:11:02 +0200 Subject: [PATCH] Erstelle technisches Marktmanagement-Konzept --- docs/modules/market_management/README.md | 1 + .../market_management_technical_concept.md | 385 ++++++++++++++++++ 2 files changed, 386 insertions(+) create mode 100644 docs/modules/market_management/konzepte/market_management_technical_concept.md diff --git a/docs/modules/market_management/README.md b/docs/modules/market_management/README.md index 9bdd22e..832a24a 100644 --- a/docs/modules/market_management/README.md +++ b/docs/modules/market_management/README.md @@ -53,6 +53,7 @@ dokumentiert. - [Anforderungsprofil](requirements/market_management_requirements.md) - [Datenarchitektur](data/market_management_data_architecture.md) +- [Technisches Konzept](konzepte/market_management_technical_concept.md) - Prozessdokumente werden unter `processes/main/` und `processes/sub_processes/` angelegt, sobald die fachlichen Prozesse explizit definiert sind. diff --git a/docs/modules/market_management/konzepte/market_management_technical_concept.md b/docs/modules/market_management/konzepte/market_management_technical_concept.md new file mode 100644 index 0000000..ea11bb7 --- /dev/null +++ b/docs/modules/market_management/konzepte/market_management_technical_concept.md @@ -0,0 +1,385 @@ +# market_management_technical_concept + +Stand: 2026-09-19 +Status: Freigegebenes technisches Zielkonzept für die Umsetzung bis Punkt 10 + +## 1. Geltungsbereich + +Dieses Konzept beschreibt die technische Umsetzung des Marktmanagement-Moduls +für die Punkte 1 bis 10 des Anforderungsprofils: + +- Markt- und Durchführungserfassung +- Durchführungstage +- Statusverwaltung +- manuelle Zahlungsstatusverwaltung +- OTC-basierte Erlös- und Artikelmengenermittlung +- Marktübersicht als serverseitige Daten-/API-Funktion +- Hermes-MCP-Integration +- Archivierung +- Benutzer- und Modulberechtigung + +Nicht enthalten sind die Punkte 11 und folgende: intelligente Auswertungen, +Korrelationen, Saisonvergleiche, Gemeinde-Einkommensdaten und sonstige +analytische Funktionen. + +## 2. Fachliches Zielmodell + +```text +Kategorie / Marktart +└── Markt + └── Durchführung + └── Durchführungstag / Subdurchführung + └── OTC-Verkäufe +``` + +### 2.1 Markt + +Der Markt ist die zentrale Stammdatendefinition. Er enthält ausschließlich: + +- eindeutigen Marktnamen +- genau eine Kategorie / Marktart +- Archivstatus + +Die Kategorie-/Marktartliste ist deterministisch und darf durch Fabienne +erweitert werden. Hermes darf bestehende Kategorien auswählen, aber keine neuen +Kategorien anlegen. + +### 2.2 Durchführung + +Eine Durchführung ist eine konkrete Teilnahme bzw. Veranstaltungsausgabe eines +Marktes. Sie besitzt mindestens einen Durchführungstag. Alle veränderlichen +Angaben werden auf dieser Ebene geführt, sofern sie nicht tagesbezogen sind. + +### 2.3 Durchführungstag / Subdurchführung + +Jeder Durchführungstag ist eine eigene Subdurchführung mit: + +- eigenem Datum +- eigenen tagesbezogenen Zeiten +- eigenen OTC-Verkäufen +- daraus abgeleitetem Umsatz +- daraus abgeleiteter Artikelmenge +- eigenen Ereignissen und Beobachtungen + +Ein Markt kann mehrere Durchführungen und jede Durchführung mehrere Tage +besitzen. + +## 3. Datenbankmodell und Ownership + +Die Tabellen gehören fachlich dem Modul `market_management`, außer den bereits +bestehenden OTC-Tabellen. Das Marktmanagement-Modul schreibt ausschließlich in +seine eigenen Tabellen. Das OTC-Modul schreibt ausschließlich in seine eigenen +Verkaufstabellen und erhält die Zuordnung zum Durchführungstag über die +definierte Modul-Schnittstelle. + +### 3.1 `market_category` + +Deterministische Kategorie-/Marktartliste. + +Wesentliche Felder: + +- `id` +- `name` +- `is_active` +- `created_at` +- `updated_at` + +`name` ist eindeutig. Das Deaktivieren ersetzt keine historische Zuordnung. + +### 3.2 `market` + +Zentrale Marktdefinition. + +Wesentliche Felder: + +- `id` +- `name` — eindeutig +- `category_id` — genau eine Kategorie +- `archived_at` +- `created_at` +- `updated_at` + +Keine Durchführungs-, Kontakt-, Kosten-, Zahlungs- oder Erlösfelder werden in +dieser Tabelle gespeichert. + +### 3.3 `market_occurrence` + +Konkrete Durchführung eines Marktes. + +Wesentliche Felder: + +- `id` +- `market_id` +- `status` +- `archived_at` +- `registration_deadline` +- `request_or_registration_date` +- `confirmation_date` +- Veranstaltungsort und Adresse +- Gemeinde-Referenz +- Kanton-Referenz +- Notizen +- Standgröße und Infrastrukturmerkmale +- Anfahrts- und Logistikangaben +- Zahlungsstatus `paid` / `unpaid` +- Zahlungsdatum, optional +- bezahlter Betrag, optional +- Vertragsordner-Link, optional +- `created_at` +- `updated_at` + +Kalenderdaten der Durchführung werden aus den zugehörigen Tagen abgeleitet. + +### 3.4 `market_occurrence_organizer` + +Eigener Datensatz für den Veranstalter einer Durchführung. + +Wesentliche Felder: + +- `id` +- `occurrence_id` — genau eine Zuordnung pro Durchführung +- `organization_contact_id` — Organisation aus dem Kontaktmodul +- `contact_person_id` — genau eine Kontaktperson aus dem Kontaktmodul +- `created_at` +- `updated_at` + +Kontakt- und Organisationsdaten werden nicht dupliziert. Die Referenzen werden +über die definierte Kontaktmodul-Schnittstelle validiert. + +### 3.5 `market_occurrence_day` + +Einzelner Durchführungstag / Subdurchführung. + +Wesentliche Felder: + +- `id` +- `occurrence_id` +- `date` +- Standbeginn und Standende +- Auf- und Abbauzeiten +- Anlieferungszeitfenster, sofern tagesbezogen +- Ereignisse und Beobachtungen +- `created_at` +- `updated_at` + +Die Kombination aus `occurrence_id` und `date` ist eindeutig. Ein Datum kann in +derselben Durchführung nicht doppelt vorkommen. + +### 3.6 `market_occurrence_cost_item` + +Einzelne Kostenposition einer Durchführung. + +Wesentliche Felder: + +- `id` +- `occurrence_id` +- Kostenart +- Bezeichnung +- Bruttobetrag +- Steuerart bzw. steuerfrei +- Steuersatz, sofern steuerpflichtig +- berechneter Nettobetrag +- berechneter Steuerbetrag +- `created_at` +- `updated_at` + +Gesamtkosten und offener Betrag werden berechnet und nicht manuell +überschrieben. Steuerfreie Positionen sind zulässig. + +### 3.7 `municipality_reference` + +Technischer Referenzbestand des offiziellen Schweizer Gemeindeverzeichnisses. + +Wesentliche Felder: + +- BFS-Gemeindenummer +- Gemeindename +- Kantonsnummer bzw. Kantonscode +- Gültigkeitsstand / Datenversion +- `is_active` + +Die Gemeindeauswahl wird über die BFS-Gemeindenummer gespeichert. Namen und +Kantonszuordnung werden nicht als freie, unkontrollierte Fachwerte gespeichert. + +### 3.8 `market_mcp_idempotency` + +Technischer Idempotenzbestand für wiederholte Hermes-Schreibaufrufe. + +Wesentliche Felder: + +- `id` +- Benutzeridentität +- Hermes-/Client-Identität +- `idempotency_key` +- Toolname bzw. Operation +- Request-Hash +- Ergebnisstatus +- Ergebnisreferenz, sofern ein Datensatz erzeugt oder geändert wurde +- `created_at` +- `expires_at` + +Die Kombination aus Client-Identität und Idempotenzschlüssel ist eindeutig. +Ein wiederholter Aufruf mit demselben Schlüssel und abweichendem Request-Hash +wird abgewiesen. + +### 3.9 OTC-Zuordnung + +Jeder neue OTC-Verkauf erhält eine eindeutige Zuordnung zu einem +`market_occurrence_day_id`. Markt, Durchführung und Datum werden daraus +ermittelt und im OTC-Formular sichtbar ausgewählt beziehungsweise angezeigt. + +Das Marktmanagement-Modul schreibt keine OTC-Verkäufe. Das OTC-Modul validiert +die Zuordnung über die öffentliche Schnittstelle des Marktmanagement-Moduls. +Historische OTC-Verkäufe ohne Zuordnung werden nicht nachträglich migriert. + +## 4. Berechnungen und abgeleitete Werte + +Nicht manuell eingegeben werden: + +- Wochentag aus `market_occurrence_day.date` +- Saison aus dem Kalenderdatum +- Beginn und Ende einer Durchführung aus dem ersten und letzten Tag +- Gesamtkosten aus den Kostenpositionen +- offener Betrag aus Gesamtkosten und bezahltem Betrag +- Bruttoerlös je Durchführungstag aus den zugeordneten OTC-Verkäufen +- Artikelanzahl je Durchführungstag aus den OTC-Positionen +- Gesamtumsatz und Artikelanzahl einer Durchführung aus ihren Tagen +- Gesamtumsatz und Artikelanzahl eines Marktes aus seinen Durchführungen + +Stornos und Rückerstattungen werden bei Umsatz und Artikelanzahl entsprechend +abgezogen. Der Bruttoerlös ist nicht manuell editierbar. + +## 5. Statusmodell + +Die Statuswerte gehören zur Durchführung: + +1. `offen` +2. `warteliste` +3. `angemeldet` +4. `bestaetigung_ausstehend` +5. `bestaetigt` +6. `abgesagt` +7. `durchgefuehrt` + +Die technischen Werte sind sprachunabhängig. Die Anzeige erfolgt über deutsche +i18n-Texte. + +Die ersten sechs Status werden manuell gesetzt. `durchgefuehrt` wird nach dem +Ende des letzten Durchführungstags automatisch gesetzt, sofern die Durchführung +nicht `abgesagt` ist. Manuelle Korrektur bleibt möglich. + +Der Zahlungsstatus ist unabhängig und besitzt nur: + +- `paid` +- `unpaid` + +Er wird manuell gepflegt, da kein Zahlungssystem angebunden wird. + +## 6. Prozesse und Verantwortungen + +Die folgenden Prozesse sind als technische/fachliche Prozesskandidaten für die +anschließende normative Prozessdokumentation vorgesehen. Sie bleiben jeweils im +Owning-Modul `market_management`. + +| Prozess | Trigger | Reads | Writes / Ergebnis | +|---|---|---|---| +| Markt verwalten | UI oder MCP | Kategorie- und Marktdaten | Markt anlegen, ändern, archivieren, reaktivieren | +| Durchführung verwalten | UI oder MCP | Markt, Kontakte, Gemeinden | Durchführung anlegen, ändern, archivieren, reaktivieren | +| Durchführungstag verwalten | UI, MCP oder Durchführung | Durchführung | Tage anlegen, ändern und entfernen | +| Kosten verwalten | UI oder MCP | Durchführung, Kostenpositionen | Kostenpositionen und berechnete Summen | +| Zahlungsstatus verwalten | UI oder MCP | Durchführung, Kosten | `paid` / `unpaid`, Zahlungsdatum, bezahlter Betrag | +| OTC-Verkauf zuordnen | OTC-Formular | Marktmanagement-Schnittstelle | OTC-eigene Referenz auf Durchführungstag | +| Erlös ermitteln | Übersicht/API | OTC-Verkäufe, Durchführungstage | berechnete Umsatz- und Artikelwerte | +| Marktübersicht lesen | UI/API/MCP | Märkte, Durchführungen, Tage, Berechnungen | gefiltertes und sortiertes Ergebnis | +| Hermes-Datenzugriff | MCP-Client Hermes | Marktmanagement-Daten | validierte Anlage, Änderung oder Archivierung | +| Referenzdaten pflegen | Fabienne / technischer Import | BFS-Quelle, Kategorien, Kantone | Kategorie- und Gemeindereferenzen | + +Formale Haupt- und Sub-Prozessverträge werden anschließend unter +`processes/main/` und `processes/sub_processes/` mit der verbindlichen +Prozessnotation erstellt. + +## 7. Marktübersicht als API-Vertrag + +Die serverseitige Übersicht unterstützt: + +- Gruppierung nach Markt +- Aufklappen auf Durchführungen +- Aufklappen auf Durchführungstage +- Filter nach Kategorie, Status, Gemeinde und Ort +- serverseitige Volltextsuche +- Sortierung nach erstem Durchführungstag und Umsatz +- Anzeige von Status, Kosten, Zahlungsstatus und berechnetem Bruttoerlös +- Kennzeichnung kommender Durchführungen +- Kennzeichnung überfälliger Anmeldungen und Zahlungen + +Die konkrete visuelle Oberfläche wird in einem späteren GUI-Schritt erarbeitet. + +## 8. Hermes-MCP-Submodul + +Hermes ist MCP-Client; die App stellt den MCP-Server bereit. + +### 8.1 Fachliche Tools + +Das Submodul veröffentlicht fachlich begrenzte Tools für: + +- Markt suchen und lesen +- Markt anlegen, ändern, archivieren und reaktivieren +- Durchführung suchen und lesen +- Durchführung anlegen, ändern, archivieren und reaktivieren +- Durchführungstag anlegen und ändern +- Referenzwerte lesen +- Kosten, Zahlungsstatus und Durchführungsattribute aktualisieren + +Generische SQL-, Tabellen- oder beliebige Feldschreibtools werden nicht +veröffentlicht. + +### 8.2 Authentifizierung und Berechtigung + +- MCP-Endpunkt ausschließlich über geschütztes HTTPS +- OAuth-/OIDC-basierte Benutzerautorisierung +- Hermes arbeitet im Kontext des angemeldeten Benutzers +- Benutzeridentität und Modulberechtigung werden serverseitig geprüft +- Lesen, Schreiben und Archivieren werden als getrennte Berechtigungen geführt +- die Prüfung erfolgt an der Transportgrenze und nochmals im Tool-Handler + +Die Ownership der Lizenz-/Entitlement-Daten bleibt außerhalb dieses Konzepts. + +### 8.3 Schreibregeln + +- jeder MCP-Aufruf ist atomar +- ein fehlgeschlagener Schreibvorgang erzeugt keine Teilpersistierung +- alle Schreibvorgänge laufen über die interne Modul-API +- Hermes darf neue Märkte nur mit bestehenden Kategorien anlegen +- jede Wiederholung wird über eine Idempotenzreferenz und fachliche Unique-Regeln + sicher behandelt +- Dokumentlinks dürfen optional als Herkunftsinformation übergeben werden + +## 9. Archivierung + +Markt und Durchführung werden separat archiviert. + +- Archivierung eines Marktes archiviert nicht automatisch die Durchführungen. +- Archivierung einer Durchführung archiviert nicht den zentralen Markt. +- Archivierte Datensätze werden standardmäßig aus aktiven Übersichten entfernt. +- Reaktivierung erfolgt auf derselben Ebene wie die Archivierung. +- Historische OTC-Zuordnungen bleiben unverändert. + +## 10. Berechtigungen + +Die Modulnutzung wird an die Benutzeridentität gebunden. Fabienne ist der erste +berechtigte Benutzer. Die Rechteprüfung erfolgt vor jeder Datenlieferung und +vor jeder schreibenden oder archivierenden Aktion. + +Die fachliche Ownership der Lizenz-/Entitlement-Daten bleibt offen. + +## 11. Nicht enthaltene Entscheidungen + +Bewusst nicht Bestandteil dieses ersten Umsetzungsschritts: + +- intelligente Auswertungen ab Punkt 11 +- externe wirtschaftliche Gemeindedaten +- automatische Hermes-Konfidenz- oder Freigabelogik +- Fileserver-Integration und Dokumentenscan +- historische OTC-Nachmigration +- konkrete GUI-Gestaltung +- fachliche Ownership von Lizenz-/Entitlement-Daten