diff --git a/docs/modules/market_management/README.md b/docs/modules/market_management/README.md index 832a24a..d7225aa 100644 --- a/docs/modules/market_management/README.md +++ b/docs/modules/market_management/README.md @@ -38,8 +38,8 @@ Die App behält die Kontrolle über: - Audit- und Quelleninformationen Hermes erhält keinen direkten Zugriff auf die Datenbank. Das Zielbild und die -offenen Schnittstellenentscheidungen sind in -[market_management.hermes_mcp.md](integrations/market_management.hermes_mcp.md) +Schnittstellenentscheidungen sind im +[market_management_hermes_mcp_konzept.md](konzepte/market_management_hermes_mcp_konzept.md) dokumentiert. ## Abgrenzung @@ -53,7 +53,9 @@ dokumentiert. - [Anforderungsprofil](requirements/market_management_requirements.md) - [Datenarchitektur](data/market_management_data_architecture.md) -- [Technisches Konzept](konzepte/market_management_technical_concept.md) +- [Technisches Tabellen- und Prozesskonzept](konzepte/market_management_technisches_konzept.md) +- [Hermes-MCP-Konzept](konzepte/market_management_hermes_mcp_konzept.md) +- [DB-Ownership-Konzept](konzepte/market_management_db_ownership.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/data/market_management_data_architecture.md b/docs/modules/market_management/data/market_management_data_architecture.md index b4c37a5..bf8902f 100644 --- a/docs/modules/market_management/data/market_management_data_architecture.md +++ b/docs/modules/market_management/data/market_management_data_architecture.md @@ -1,7 +1,7 @@ # market_management_data_architecture Stand: 2026-09-18 -Status: Bestätigtes Datenarchitektur-Zielbild; einzelne Kardinalitäten offen +Status: Bestätigtes Datenarchitektur-Zielbild ## 1. Ziel @@ -12,22 +12,23 @@ der Daten abbilden können. ## 2. Bestätigte Hierarchie ```text -Kategorie ─── Markt 1 ─── n Durchführung 1 ─── n Durchführungstag +Kategorie 1 ─── n Marktdefinition 1 ─── n Durchführung 1 ─── n Durchführungstag ``` -Für Kategorie und Markt werden beliebig viele Datensätze unterstützt. Ob die -Zuordnung Kategorie–Markt `1:n` oder `n:m` ist, bleibt offen. +Eine Kategorie enthält beliebig viele Marktdefinitionen. Jede Marktdefinition +gehört genau einer Kategorie. ### Kategorie -Eine Kategorie ordnet Märkte fachlich. Die konkrete Kategorisierung und die -zulässigen Kategorieattribute sind noch nicht weiter spezifiziert. +Eine Kategorie ordnet Märkte fachlich. Fabienne darf die deterministische +Kategorie-/Marktartliste erweitern. Hermes darf bestehende Kategorien +verwenden, aber keine Kategorien anlegen. -### Markt +### Marktdefinition -Ein Markt ist die übergeordnete fachliche Identität, unter der mehrere konkrete -Durchführungen geführt werden können. Der zentrale Marktstamm enthält nur den -Marktnamen und die Marktart/Kategorie aus einer deterministischen Liste. +Eine Marktdefinition ist die übergeordnete fachliche Identität, unter der +mehrere konkrete Durchführungen geführt werden können. Der zentrale Marktstamm +enthält nur den eindeutigen Marktnamen und die Marktart/Kategorie. ### Durchführung @@ -93,8 +94,11 @@ Logistik, Kosten, Zahlung, Vertragslink und Notizen. - Fremde Modul- oder DB-Ownership wird durch diese Datenarchitektur nicht eingeführt. -## 5. Offene fachliche Fragen +## 5. Bestätigte Ergänzungen -- Ist die Zuordnung Kategorie–Markt `1:n` oder `n:m`? -- Ist eine Durchführung immer eine konkrete Teilnahme oder eine allgemeine - Veranstaltungsausgabe? +- Eine Durchführung ist eine konkrete Teilnahme bzw. Veranstaltungsausgabe. +- Jeder Durchführungstag ist eine eigene Subdurchführung mit eigenen OTC- + Verkäufen und abgeleiteten Tageswerten. +- Markt und Durchführung werden unabhängig voneinander archiviert und + reaktiviert. +- Der Zahlungsstatus ist manuell und besitzt nur `paid` oder `unpaid`. diff --git a/docs/modules/market_management/integrations/market_management.hermes_mcp.md b/docs/modules/market_management/integrations/market_management.hermes_mcp.md deleted file mode 100644 index f06f1df..0000000 --- a/docs/modules/market_management/integrations/market_management.hermes_mcp.md +++ /dev/null @@ -1,92 +0,0 @@ -# market_management.hermes_mcp - -Stand: 2026-09-18 -Status: Verbindliches Architektur-Zielbild; technische Schnittstellendetails offen - -## 1. Zweck - -Das MCP-Interface ermöglicht Hermes Agent, Unterlagen zu analysieren und -freigegebene erkannte Datenpunkte über das Marktmanagement-Modul in die App zu -übergeben. - -## 2. Rollen und Verantwortungen - -### App / Market Management - -Die App stellt den MCP-Server bereit und bleibt das führende System für alle -Marktdaten. Das Marktmanagement-Modul verantwortet insbesondere: - -- Benutzer- und Modulberechtigungsprüfung im vorhandenen Zugriffskontext -- Validierung der Hermes-Eingaben -- fachliche Feldzuordnung -- zulässige Schreiboperationen -- Persistierung in den eigenen Datenstrukturen -- Quellen-, Lauf- und Auditinformationen -- Rückgabe des Persistierungsergebnisses an Hermes - -### Hermes Agent - -Hermes ist MCP-Client. Hermes analysiert übergebene Unterlagen und ruft nur die -von der App veröffentlichten MCP-Tools auf. Hermes besitzt keinen direkten -Zugriff auf Datenbank, interne Services oder interne Dateien der App. - -## 3. Kontrollfluss - -```text -Hermes Agent - → MCP-Aufruf -MCP-Server der App - → Authentifizierung und Berechtigung -Market-Management-Service - → Validierung und fachliche Feldzuordnung -Eigene Datenbank der App - → strukturiertes Ergebnis -Hermes Agent -``` - -## 4. Architekturgrenzen - -- Der MCP-Server ist eine externe Schnittstelle der App. -- Die MCP-Schicht enthält keine eigene Marktfachlogik. -- Jeder Schreibvorgang läuft über die interne Schnittstelle des - Marktmanagement-Moduls. -- Generische SQL-, Tabellen- oder beliebige Feldschreibwerkzeuge werden nicht - veröffentlicht. -- Hermes darf keine fremden Modul- oder technischen Interna direkt nutzen. -- Lizenz-/Entitlement-Ownership bleibt offen und wird durch dieses Interface - nicht festgelegt. - -## 5. Fachliche Schreibregel - -Hermes darf grundsätzlich alle vom Marktmanagement-Modul ausdrücklich -freigegebenen Datenpunkte über MCP übermitteln, zum Beispiel Kontaktperson, -Anmeldefrist, Zahlungsfrist, Standgebühr oder Infrastrukturangaben. - -Die App entscheidet pro Aufruf, ob ein Wert: - -- direkt persistiert werden darf, -- als unsicherer Prüfwert gespeichert wird oder -- wegen fehlender oder widersprüchlicher Informationen abgewiesen wird. - -Die konkrete Freigabelogik ist noch nicht vollständig definiert. - -## 6. Offene Schnittstellenentscheidungen - -Folgende technische Angaben sind noch offen und müssen vor der Implementierung -explizit festgelegt werden: - -- MCP-Transport und erreichbarer Endpoint -- Authentifizierung und technische Identität von Hermes -- Zuordnung von Hermes-Aufrufen zu Benutzeridentität und Modulrecht -- veröffentlichte MCP-Tools und deren Eingabe-/Ausgabeschemas -- Dokumentübergabe: Upload, App-interner Dokumentlink oder anderer Weg -- Synchrones Ergebnis oder asynchrone Rückmeldung -- Idempotenzschlüssel und Wiederholungsverhalten -- Umgang mit Konfidenzwerten, Konflikten und manueller Freigabe -- Umfang der Audit- und Herkunftsdaten - -## 7. Architekturstatus - -Das Verhältnis „App als MCP-Server, Hermes als MCP-Client“ ist bestätigt. Die -offenen Punkte betreffen die konkrete technische Ausgestaltung und begründen -kein weiteres Hauptmodul. diff --git a/docs/modules/market_management/konzepte/market_management_db_ownership.md b/docs/modules/market_management/konzepte/market_management_db_ownership.md new file mode 100644 index 0000000..30019e9 --- /dev/null +++ b/docs/modules/market_management/konzepte/market_management_db_ownership.md @@ -0,0 +1,57 @@ +# Market Management: DB-Ownership-Konzept + +Stand: 2026-09-19 +Status: Verbindliches DB-Ownership-Konzept + +## 1. Owned Tabellen des Moduls + +| Tabelle | Ownership | Schreibverantwortung | +|---|---|---| +| `market_category` | `market_management` | Marktmanagement-Service | +| `market_definition` | `market_management` | Marktmanagement-Service | +| `market_occurrence` | `market_management` | Marktmanagement-Service | +| `market_occurrence_organizer` | `market_management` | Marktmanagement-Service über Kontakt-Schnittstelle | +| `market_occurrence_day` | `market_management` | Marktmanagement-Service | +| `market_occurrence_cost_item` | `market_management` | Marktmanagement-Service | +| `market_municipality_reference` | `market_management` | Referenzdatenprozess | +| `market_mcp_idempotency` | `market_management` | MCP-Submodul | + +## 2. Fremde Datenreferenzen + +### Kontaktmodul + +Das Marktmanagement-Modul speichert nur die stabilen IDs von Organisation und +Kontaktperson. Es schreibt keine Kontakt-, Organisations- oder Adressdaten in +fremde Tabellen. + +### OTC-/Direktverkaufsmodul + +Das OTC-Modul bleibt Owner seiner Verkaufstabellen. Jeder neue OTC-Verkauf +referenziert einen gültigen `market_occurrence_day_id`. Marktmanagement liest +die Verkaufsdaten ausschließlich über die definierte Schnittstelle für die +Umsatz- und Artikelmengenaggregation. + +## 3. Schreibgrenzen + +- Direkte Cross-Modul-Writes sind verboten. +- Marktmanagement schreibt nicht in OTC-, Kontakt- oder Organisations-Tabellen. +- Das OTC-Modul schreibt nicht in Marktmanagement-Tabellen. +- MCP schreibt nie direkt in Tabellen. +- Alle Marktmanagement-Writes laufen über den owning Modul-Service. + +## 4. Referenzdaten + +Der Gemeindereferenzbestand verwendet die BFS-Gemeindenummer als stabile +fachliche Referenz und speichert den Datenstand zur Nachvollziehbarkeit. + +Die Kategorie-/Marktartliste gehört zum Marktmanagement und wird durch Fabienne +gepflegt. Hermes darf sie nur lesen. + +## 5. Technische Änderungsregeln + +- Tabellen- und Constraint-Änderungen erfolgen ausschließlich über versionierte + Migrationen. +- Fachliche Constraints werden im DB- und Prozessvertrag gespiegelt. +- Aggregierte Umsatzwerte werden nicht als unabhängige Fachwahrheit gespeichert. +- Archivierte Datensätze bleiben erhalten. +- Markt und Durchführung besitzen getrennte Archivstatus. diff --git a/docs/modules/market_management/konzepte/market_management_hermes_mcp_konzept.md b/docs/modules/market_management/konzepte/market_management_hermes_mcp_konzept.md new file mode 100644 index 0000000..9ce4a2d --- /dev/null +++ b/docs/modules/market_management/konzepte/market_management_hermes_mcp_konzept.md @@ -0,0 +1,88 @@ +# Market Management: Hermes-MCP-Konzept + +Stand: 2026-09-19 +Status: Verbindliches Schnittstellenkonzept + +## 1. Zweck + +Die App stellt einen geschützten MCP-Server bereit. Hermes Agent ist MCP-Client +und arbeitet im Benutzerkontext. Hermes kann Marktmanagement-Daten suchen, +anlegen, ändern, archivieren und reaktivieren. + +## 2. Verantwortungen + +Die App kontrolliert: + +- Authentifizierung +- Benutzer- und Modulberechtigung +- Eingabevalidierung +- fachliche Feldzuordnung +- Persistierung +- Audit- und Herkunftsdaten +- Idempotenz + +Hermes besitzt keinen direkten Zugriff auf Datenbank, interne Services oder +fremde Module. + +## 3. Schnittstellenmodell + +Der MCP-Server veröffentlicht fachliche Tools, keine generischen Datenbank- +oder Tabellenoperationen. + +Vorgesehene Toolgruppen: + +- Märkte suchen und lesen +- Märkte anlegen, ändern, archivieren und reaktivieren +- Durchführungen suchen und lesen +- Durchführungen anlegen, ändern, archivieren und reaktivieren +- Durchführungstage anlegen, ändern und entfernen +- Kategorien, Kantone und Gemeinden lesen +- Kosten und Zahlungsstatus ändern +- Übersichtsdaten lesen + +Hermes darf bestehende Kategorien verwenden, aber keine Kategorien anlegen. +Umsatz- und Artikelmengen werden nicht über Hermes geschrieben, sondern aus den +OTC-Verkäufen abgeleitet. + +## 4. Authentifizierung und Autorisierung + +- MCP-Endpunkt über geschütztes HTTPS +- OAuth-/OIDC-basierte Benutzerautorisierung +- Token mit Benutzeridentität, Zielgruppe und Modul-Scope +- getrennte Scopes für Lesen, Schreiben und Archivieren +- Prüfung an der Transportgrenze +- zusätzliche Prüfung im jeweiligen Tool-Handler +- keine langlebigen gemeinsamen Zugangsdaten + +Die fachliche Ownership der Lizenz-/Entitlement-Daten bleibt offen. Die +Schnittstelle prüft nur die über den bestehenden Zugriffskontext gelieferte +Modulberechtigung. + +## 5. Schreibregeln + +- Jeder Tool-Aufruf ist atomar. +- Fehlgeschlagene Aufrufe erzeugen keine Teilpersistierung. +- Alle Schreibvorgänge laufen über die interne Modul-API. +- Hermes darf bei einem neuen Markt nur eine bestehende Kategorie referenzieren. +- Dokumentlinks können optional als Herkunftsinformation mitgegeben werden. +- Unsichere Erkennung wird nicht durch eine zusätzliche App-Freigabelogik + behandelt; die fachliche Qualitätssicherung liegt im Hermes-Training. + +## 6. Wiederholungsschutz + +Schreibende Aufrufe können eine Idempotenzreferenz übergeben. Die App speichert +Client, Benutzer, Tool, Schlüssel, Request-Hash und Verarbeitungsergebnis in +`market_mcp_idempotency`. + +Ein wiederholter Aufruf mit gleichem Schlüssel und gleichem Request liefert das +bereits bekannte Ergebnis. Ein gleicher Schlüssel mit verändertem Request wird +abgewiesen. + +## 7. Daten- und Modulgrenzen + +- Marktmanagement schreibt nur in eigene Tabellen. +- Das OTC-Modul schreibt die Verkaufstabelle und referenziert den + `market_occurrence_day_id`. +- Kontakt- und Organisationsdaten werden über das Kontaktmodul referenziert. +- Gemeindedaten werden über den eigenen Referenzbestand gelesen. +- MCP-Komposition enthält keine Marktfachlogik. diff --git a/docs/modules/market_management/konzepte/market_management_technical_concept.md b/docs/modules/market_management/konzepte/market_management_technical_concept.md deleted file mode 100644 index ea11bb7..0000000 --- a/docs/modules/market_management/konzepte/market_management_technical_concept.md +++ /dev/null @@ -1,385 +0,0 @@ -# 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 diff --git a/docs/modules/market_management/konzepte/market_management_technisches_konzept.md b/docs/modules/market_management/konzepte/market_management_technisches_konzept.md new file mode 100644 index 0000000..771da29 --- /dev/null +++ b/docs/modules/market_management/konzepte/market_management_technisches_konzept.md @@ -0,0 +1,358 @@ +# Market Management: Normatives Tabellen- und Prozesskonzept + +Stand: 2026-09-19 +Status: Verbindliches Konzept für das Modul `market_management` + +## 1. Übersicht + +Tabellen: + +- `market_category` +- `market_definition` +- `market_occurrence` +- `market_occurrence_organizer` +- `market_occurrence_day` +- `market_occurrence_cost_item` +- `market_municipality_reference` +- `market_mcp_idempotency` + +Bestehende Integrationsreferenz: + +- `sales_order.market_occurrence_day_id` im owning OTC-/Direktverkaufsmodul + +Prozessbereiche: + +- zentrale Marktdefinition verwalten +- Durchführung verwalten +- Durchführungstage verwalten +- Kosten und Zahlungsstatus verwalten +- OTC-Verkäufe einem Durchführungstag zuordnen +- Umsatz- und Artikelmengen lesen und aggregieren +- Marktübersicht lesen +- Hermes-MCP-Zugriff ausführen +- Referenzdaten verwalten + +## 2. Zweck und Scope + +Dieses Dokument beschreibt das normative technische Zielbild für die Umsetzung +bis einschließlich Punkt 10 des Anforderungsprofils. + +Enthalten sind: + +- zentrale Marktdefinition mit eindeutigem Namen und genau einer Kategorie +- beliebig viele Durchführungen je Markt +- mindestens ein Durchführungstag je Durchführung +- veranstaltungs-, tages-, kosten- und zahlungsbezogene Daten +- OTC-basierte Umsatz- und Artikelmengenermittlung +- Archivierung von Markt und Durchführung auf getrennten Ebenen +- serverseitige Übersichtsdaten +- Benutzer- und Modulberechtigung +- Hermes als MCP-Client der App + +Nicht enthalten sind Punkt 11 und folgende, insbesondere intelligente +Auswertungen, Korrelationen und wirtschaftliche Gemeindedaten. + +GUI-Details, konkrete HTTP-Komposition und technische Hermes-Implementierung +werden in den zugehörigen Detaildokumenten beschrieben. + +## 3. Normatives Datenmodell + +```text +Kategorie / Marktart +└── Marktdefinition + └── Durchführung + └── Durchführungstag / Subdurchführung + └── OTC-Verkäufe +``` + +### 3.1 `market_category` + +Deterministische Kategorie-/Marktartliste. + +Normativ: + +- Kategorienamen sind eindeutig. +- Fabienne darf die Liste erweitern. +- Hermes darf bestehende Kategorien auswählen, aber keine Kategorien anlegen. +- Deaktivierte Kategorien bleiben für historische Zuordnungen erhalten. + +### 3.2 `market_definition` + +Zentrale fachliche Marktdefinition. + +Normativ: + +- jeder Markt besitzt genau einen eindeutigen Namen +- jeder Markt besitzt genau eine Kategorie +- der Markt enthält keine Durchführungs-, Kontakt-, Kosten-, Zahlungs- oder + Erlösdaten +- Markt und Durchführungen werden getrennt archiviert und reaktiviert + +### 3.3 `market_occurrence` + +Konkrete Teilnahme bzw. Veranstaltungsausgabe eines Marktes. + +Normativ: + +- jede Durchführung gehört genau einer Marktdefinition +- jede Durchführung besitzt mindestens einen Durchführungstag +- variable Veranstaltungs-, Kontakt-, Orts-, Logistik-, Kosten- und + Zahlungsdaten gehören zur Durchführung +- der Status gehört zur Durchführung +- Zahlungsstatus und Marktstatus sind unabhängig +- der Zahlungsstatus ist manuell `paid` oder `unpaid` + +### 3.4 `market_occurrence_organizer` + +Veranstalterbeziehung einer Durchführung. + +Normativ: + +- der Veranstalter ist eine Organisation aus dem Kontaktmodul +- jede Durchführung besitzt höchstens genau einen Veranstalterdatensatz +- der Veranstalterdatensatz referenziert genau eine Kontaktperson +- Kontakt- und Organisationsdaten werden nicht im Marktmanagement dupliziert + +### 3.5 `market_occurrence_day` + +Einzelner Durchführungstag bzw. Subdurchführung. + +Normativ: + +- jeder Tag gehört genau einer Durchführung +- das Datum ist je Durchführung eindeutig +- Stand-, Aufbau-, Abbau- und tagesbezogene Anlieferungszeiten gehören hierher +- Ereignisse und Beobachtungen gehören hierher +- OTC-Verkäufe werden eindeutig diesem Datensatz zugeordnet + +### 3.6 `market_occurrence_cost_item` + +Einzelne Kostenposition einer Durchführung. + +Normativ: + +- jede Kostenposition gehört genau einer Durchführung +- CHF ist die einzige Währung +- Bruttobetrag wird erfasst +- steuerfreie Positionen sind zulässig +- Netto- und Steuerbetrag werden aus Brutto und Steuerart/-satz berechnet +- Gesamtkosten sind die Summe der Kostenpositionen und nicht manuell + überschreibbar + +### 3.7 `market_municipality_reference` + +Technischer Referenzbestand des offiziellen Schweizer Gemeindeverzeichnisses. + +Normativ: + +- Gemeinden werden über BFS-Gemeindenummern referenziert +- Gemeindename und Kantonszuordnung stammen aus dem Referenzbestand +- nur gültige Gemeinden stehen für neue Eingaben zur Auswahl +- der Datenstand wird versioniert gespeichert + +### 3.8 `market_mcp_idempotency` + +Technischer Idempotenzbestand für wiederholte Hermes-Schreibaufrufe. + +Normativ: + +- derselbe Client und Idempotenzschlüssel erzeugen keine doppelte Wirkung +- ein abweichender Request mit demselben Schlüssel wird abgewiesen +- der gespeicherte Verarbeitungsausgang bleibt nachvollziehbar + +### 3.9 OTC-Integration + +Das OTC-Modul bleibt Owner seiner Verkaufstabellen. Jeder neue OTC-Verkauf +referenziert eindeutig einen `market_occurrence_day_id`. Markt, Durchführung, +Datum, Umsatz und Artikelmengen werden daraus ermittelt. + +Historische OTC-Verkäufe ohne diese Zuordnung werden nicht migriert. + +## 4. Normatives Prozessmodell + +Alle fachlichen Prozesse gehören zum owning Modul `market_management`, außer der +OTC-Verkaufsprozess selbst. Die OTC-Integration erfolgt ausschließlich über die +öffentliche Marktmanagement-Schnittstelle. + +### 4.1 Zentrale Marktdefinition verwalten + +Fachliche Aufgabe: + +- Marktdefinition mit eindeutigem Namen und Kategorie anlegen, ändern, + archivieren oder reaktivieren + +Liest: + +- Kategorien +- bestehende Marktdefinitionen + +Schreibt: + +- `market_category`, sofern Fabienne eine Kategorie erweitert +- `market_definition` + +### 4.2 Durchführung verwalten + +Fachliche Aufgabe: + +- eine konkrete Durchführung eines Marktes anlegen, bearbeiten, archivieren + oder reaktivieren + +Liest: + +- Marktdefinition +- Kontaktmodul +- Gemeindereferenz + +Schreibt: + +- `market_occurrence` +- `market_occurrence_organizer` + +### 4.3 Durchführungstage verwalten + +Fachliche Aufgabe: + +- Durchführungstage anlegen, bearbeiten und entfernen + +Liest: + +- Durchführung + +Schreibt: + +- `market_occurrence_day` + +### 4.4 Kosten und Zahlungsstatus verwalten + +Fachliche Aufgabe: + +- Kostenpositionen und manuelle Zahlungsinformationen pflegen + +Liest: + +- Durchführung +- bestehende Kostenpositionen + +Schreibt: + +- `market_occurrence_cost_item` +- Zahlungsfelder in `market_occurrence` + +### 4.5 OTC-Verkauf einem Durchführungstag zuordnen + +Fachliche Aufgabe: + +- beim OTC-Verkauf einen gültigen Durchführungstag auswählen und referenzieren + +Liest: + +- verfügbare Märkte, Durchführungen und Durchführungstage über die + Marktmanagement-Schnittstelle + +Schreibt: + +- ausschließlich das OTC-Modul in seine eigene Verkaufstabelle + +### 4.6 Umsatz- und Artikelmengen lesen + +Fachliche Aufgabe: + +- Umsatz und Artikelmengen für Tag, Durchführung und Markt aus den OTC-Daten + aggregieren + +Liest: + +- zugeordnete OTC-Verkäufe und Verkaufspositionen +- Markt-, Durchführungs- und Tagesdaten + +Schreibt: + +- keine fachlichen Umsatzsummen; die Werte sind abgeleitet + +### 4.7 Marktübersicht lesen + +Fachliche Aufgabe: + +- Märkte, Durchführungen und Tage serverseitig suchen, filtern, sortieren und + aggregiert ausgeben + +Liest: + +- alle owned Marktmanagement-Daten +- Kontakt- und Gemeindereferenzen +- OTC-Aggregate + +Schreibt: + +- nichts + +### 4.8 Hermes-MCP-Zugriff + +Fachliche Aufgabe: + +- Hermes über die kontrollierte MCP-Schnittstelle suchen, anlegen, ändern, + archivieren und reaktivieren lassen + +Liest: + +- Marktmanagement-Daten und erlaubte Referenzdaten + +Schreibt: + +- ausschließlich über die internen Marktmanagement-Services +- `market_mcp_idempotency` für Wiederholungsschutz + +Die konkrete MCP-Schnittstelle ist in +[market_management_hermes_mcp_konzept.md](market_management_hermes_mcp_konzept.md) +dokumentiert. + +## 5. Normative Betriebsregeln + +- Marktname und Kategorie sind zentrale Stammdaten. +- Alle variablen Veranstaltungsdaten werden je Durchführung gepflegt. +- Tageswerte werden je Durchführungstag gepflegt. +- Wochentag, Saison, Datumsbereich, Gesamtkosten, offener Betrag, Umsatz und + Artikelmengen werden abgeleitet. +- Umsatz und Artikelmengen stammen ausschließlich aus OTC-Verkäufen. +- Stornos und Rückerstattungen werden in den Aggregaten abgezogen. +- Markt- und Durchführungarchivierung sind unabhängig. +- Der erste Status ist `offen`. +- `durchgefuehrt` wird nach dem letzten Durchführungstag automatisch gesetzt, + sofern die Durchführung nicht `abgesagt` ist. +- Die GUI enthält keine fachliche Primärlogik. +- Hermes erhält keinen direkten DB-Zugriff. +- Punkt 11 und folgende sind nicht Teil dieses Zielbilds. + +## 6. Ausgabevertrag + +Das Modul liefert: + +- eindeutige Markt-, Durchführungs- und Tagesidentitäten +- validierte Stammdaten und Referenzen +- unabhängigen Markt- und Zahlungsstatus +- berechnete Kosten-, Umsatz- und Artikelmengenwerte +- serverseitig filter- und sortierbare Übersichtsdaten +- kontrollierte MCP-Ergebnisse für Hermes + +## 7. Erfolgskriterien + +- Marktdefinitionen sind eindeutig und genau einer Kategorie zugeordnet. +- Durchführungen und Durchführungstage sind unabhängig und vollständig + verwaltbar. +- Jeder neue OTC-Verkauf ist genau einem Durchführungstag zugeordnet. +- Umsatz und Artikelmengen werden nicht manuell doppelt erfasst. +- Kontakt- und Gemeindedaten werden über definierte Referenzen verwendet. +- Archivierung funktioniert getrennt für Markt und Durchführung. +- MCP-Schreibvorgänge sind authentifiziert, berechtigt und idempotent. +- Die fachliche Logik bleibt im owning Modul. + +## 8. Noch nicht normative Detailverträge + +Die folgenden Dokumente werden erst nach expliziter Prozessdefinition als +normative Verträge erstellt: + +- Hauptprozesse unter `processes/main/` +- Sub-Prozesse unter `processes/sub_processes/` +- konkrete API-Schemas der Marktmanagement-Schnittstelle +- GUI- und View-Verträge diff --git a/docs/modules/market_management/requirements/market_management_requirements.md b/docs/modules/market_management/requirements/market_management_requirements.md index f78c2ce..38e6321 100644 --- a/docs/modules/market_management/requirements/market_management_requirements.md +++ b/docs/modules/market_management/requirements/market_management_requirements.md @@ -28,9 +28,9 @@ Kategorie ``` - Es können beliebig viele Kategorien und Märkte existieren. -- Die genaue Kardinalität der Zuordnung zwischen Kategorien und Märkten ist noch - offen; insbesondere ist noch nicht entschieden, ob ein Markt mehreren - Kategorien gleichzeitig zugeordnet werden darf. +- Ein Markt gehört genau einer Kategorie. +- Fabienne darf die deterministische Kategorie-/Marktartliste erweitern. +- Hermes darf bestehende Kategorien auswählen, aber keine Kategorien anlegen. - Ein Markt kann beliebig viele Durchführungen enthalten. - Eine Durchführung kann beliebig viele Durchführungstage enthalten. - Erlös- und Verkaufsdaten werden auf Ebene des Durchführungstags erfasst und @@ -54,7 +54,7 @@ und Verkaufsdaten werden pro Durchführungstag erfasst. ## 5. Marktarten -Erfassbare Marktarten: +Initial verfügbare Marktarten: - Herbstmärkte - Weihnachtsmärkte @@ -167,6 +167,7 @@ Abgeleitete Werte werden nicht manuell eingegeben: Folgende Marktstatus sollen verfügbar sein: +- Offen - Warteliste - Angemeldet - Bestätigung ausstehend @@ -174,7 +175,10 @@ Folgende Marktstatus sollen verfügbar sein: - Abgesagt - Durchgeführt -Der aktuelle Status ist in der Übersicht sofort erkennbar und manuell änderbar. +Der initiale Status ist `Offen`. Die Statuswerte werden grundsätzlich manuell +gesetzt. `Durchgeführt` wird nach dem letzten Durchführungstag automatisch +gesetzt, sofern die Durchführung nicht abgesagt ist. Manuelle Korrektur bleibt +möglich. ## 8. Bezahlung @@ -183,8 +187,6 @@ Der Zahlungsstatus wird unabhängig vom allgemeinen Marktstatus gespeichert. Zahlungsstatus: - Nicht bezahlt -- Zahlung ausstehend -- Teilweise bezahlt - Bezahlt Zusätzliche Zahlungsinformationen: @@ -195,14 +197,14 @@ Zusätzliche Zahlungsinformationen: ## 9. Erlöserfassung -Nach der Durchführung soll der Erlös pro Markt erfasst werden können. -Bei mehrtägigen Märkten wird der Erlös je Markttag separat erfasst. +Der Erlös wird nicht manuell erfasst, sondern aus den OTC-Verkäufen berechnet. +Bei mehrtägigen Märkten wird der Erlös je Durchführungstag separat ermittelt. -Pro Markttag: +Pro Durchführungstag: - Datum -- Bruttoerlös -- Anzahl verkaufter Artikel +- Bruttoerlös aus OTC-Verkäufen +- Anzahl verkaufter Artikel aus OTC-Positionen - Besondere Ereignisse oder Beobachtungen Automatisch zu berechnen: