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
-[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.
@@ -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`.
@@ -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
-  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: