Erstelle technisches Marktmanagement-Konzept

docs/modules/market_management/README.md

@@ -53,6 +53,7 @@ dokumentiert.
 
 - [Anforderungsprofil](requirements/market_management_requirements.md)
 - [Datenarchitektur](data/market_management_data_architecture.md)
+- [Technisches Konzept](konzepte/market_management_technical_concept.md)
 - Prozessdokumente werden unter `processes/main/` und
   `processes/sub_processes/` angelegt, sobald die fachlichen Prozesse explizit
   definiert sind.

docs/modules/market_management/konzepte/market_management_technical_concept.md

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