Erstelle technisches Marktmanagement-Konzept

2026-09-19 08:11:02 +02:00
1 parent 2d49840aba
commit 7c2d1cedb6
@@ -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.
@@ -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