Strukturiere Marktmanagement-Konzept

2026-09-19 08:20:56 +02:00
1 parent 7c2d1cedb6
commit 8492db2e39
@@ -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
+Schnittstellenentscheidungen sind im
-[market_management.hermes_mcp.md](integrations/market_management.hermes_mcp.md)
+[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.
@@ -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
+Eine Kategorie enthält beliebig viele Marktdefinitionen. Jede Marktdefinition
-Zuordnung Kategorie–Markt `1:n` oder `n:m` ist, bleibt offen.
+gehört genau einer Kategorie.
 ### Kategorie
-Eine Kategorie ordnet Märkte fachlich. Die konkrete Kategorisierung und die
+Eine Kategorie ordnet Märkte fachlich. Fabienne darf die deterministische
-zulässigen Kategorieattribute sind noch nicht weiter spezifiziert.
+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
+Eine Marktdefinition ist die übergeordnete fachliche Identität, unter der
-Durchführungen geführt werden können. Der zentrale Marktstamm enthält nur den
+mehrere konkrete Durchführungen geführt werden können. Der zentrale Marktstamm
-Marktnamen und die Marktart/Kategorie aus einer deterministischen Liste.
+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`?
+- Eine Durchführung ist eine konkrete Teilnahme bzw. Veranstaltungsausgabe.
- Ist eine Durchführung immer eine konkrete Teilnahme oder eine allgemeine
+- Jeder Durchführungstag ist eine eigene Subdurchführung mit eigenen OTC-
-  Veranstaltungsausgabe?
+  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`.
@@ -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.
@@ -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.
@@ -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.
@@ -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
@@ -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
@@ -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
+- Ein Markt gehört genau einer Kategorie.
-  offen; insbesondere ist noch nicht entschieden, ob ein Markt mehreren
+- Fabienne darf die deterministische Kategorie-/Marktartliste erweitern.
-  Kategorien gleichzeitig zugeordnet werden darf.
+- 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.
+Der Erlös wird nicht manuell erfasst, sondern aus den OTC-Verkäufen berechnet.
-Bei mehrtägigen Märkten wird der Erlös je Markttag separat erfasst.
+Bei mehrtägigen Märkten wird der Erlös je Durchführungstag separat ermittelt.
-Pro Markttag:
+Pro Durchführungstag:
 - Datum
- Bruttoerlös
+- Bruttoerlös aus OTC-Verkäufen
- Anzahl verkaufter Artikel
+- Anzahl verkaufter Artikel aus OTC-Positionen
 - Besondere Ereignisse oder Beobachtungen
 Automatisch zu berechnen: