From 4a6d56432d9444445ebafdb35f41167612b1ebd9 Mon Sep 17 00:00:00 2001 From: Bjoern Runden Date: Thu, 18 Jun 2026 10:03:19 +0200 Subject: [PATCH] leeres repo mit mds --- CLAUDE.md | 111 ++++++++++++++ README.md | 17 ++- ai-context/AI-operative_Vorgaben.md | 2 +- ai-context/grob-kozept-vom-interview.md | 195 ++++++++++++++++++++++++ 4 files changed, 317 insertions(+), 8 deletions(-) create mode 100644 CLAUDE.md create mode 100644 ai-context/grob-kozept-vom-interview.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ebd2316 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,111 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Projekt + +**kbcrm** ist eine Flask-basierte Webanwendung zur Unterstützung der Kundenakquise. Sie verwaltet Kunden, Kontakte, Projekte, Kontaktadressen (Anrufziele) und Gesprächsnotizen. Authentifizierung wird vollständig an Zitadel (OIDC-IdP) delegiert; Benutzer- und Rollendaten werden lokal in SQLite gehalten. + +## Befehle + +```bash +# Lokale Entwicklung +python3 -m venv venv +source venv/bin/activate +pip install -r requirements.txt +cp .env.example .env # Zitadel-Credentials eintragen +flask db-init # Datenbankschema anlegen +flask seed-db # Testdaten mit Zitadel-User-IDs einspielen +flask run # http://localhost:5000 + +# Sphinx-Dokumentation +sphinx-apidoc -o docs/source/ app/ +cd docs/ && make html # Ergebnis: docs/_build/html/index.html +``` + +## Architektur + +``` +app/ +├── __init__.py # App-Factory, Flask-Initialisierung, CLI-Kommandos (db-init, seed-db) +├── config.py # Konfiguration aus .env (12-Factor) +├── database.py # SQLAlchemy-Instanz und Session-Setup +├── models.py # Alle ORM-Modelle (siehe Datenmodell unten) +├── auth.py # Zitadel-OIDC-Flow via Authlib; Rollen aus Token-Claims +├── routes.py # Flask-Blueprints und View-Funktionen +├── templates/ # Jinja2-Templates +└── static/ # CSS, JS, Assets +data/ # SQLite-Datenbankdatei (nicht im Docker-Image, persistiert als Volume) +wsgi.py # Gunicorn-Einstiegspunkt +``` + +## Datenmodell + +| Tabelle | Zweck | +|---|---| +| `Benutzer` | Anwendungsnutzer; Primärschlüssel ist der Zitadel-`sub` | +| `Kunden` | Kundenstamm (Firmen oder Privatpersonen) | +| `Kontakte` | Ansprechpartner bei einem Kunden (FK → Kunden) | +| `Projekte` | Akquise-Projekte, einem Kunden zugeordnet | +| `Benutzer_Projekt` | n:m-Zuordnung Benutzer ↔ Projekte (Zugriffskontrolle) | +| `Kontaktadressen` | Anrufziele innerhalb eines Projekts; importierbar via CSV/Excel (FK → Projekte) | +| `Gesprächsnotizen` | Anrufdokumentation mit Metadaten, Freitext und Tags (FK → Kontaktadressen) | +| `Tags` | Benutzerdefinierte Kategorien für Gesprächsnotizen | +| `Gesprächsnotizen_Tags` | n:m-Verknüpfung Gesprächsnotizen ↔ Tags | + +## Authentifizierung & Autorisierung + +- Authlib übernimmt den OIDC Authorization-Code-Flow gegen `https://id.vmlx.de`. +- Die drei Rollen (`Admin`, `Mitarbeiter`, `Kunde`) werden in Zitadel definiert und landen als Claims im Token. +- `auth.py` liest den `sub`-Wert und die Rollen aus dem Token; beim ersten Login wird der Benutzer lokal angelegt. +- Projektzugriff: Normale Benutzer sehen nur ihre zugewiesenen Projekte; Admins haben vollen Zugriff. +- Zitadel-Einrichtung (Projekt, Rollen, Testnutzer, Client-Credentials) ist in `ai-context/AI-auth-vorgaben.md` Schritt für Schritt beschrieben. + +## Pflicht-Dateiheader + +Jede neue Quelldatei beginnt mit einem standardisierten Header. + +**Python (`.py`)** — wird von Sphinx ausgewertet: +```python +""" + + + + +:author: Vorname Nachname +:date: YYYY-MM-DD +:version: 1.0 +""" +``` + +**Jinja2/HTML (`.html`)**: +```html +{# + Datei: templates/beispiel.html + Autor: Vorname Nachname + Datum: YYYY-MM-DD + Zweck: Kurze Beschreibung der Seite und erwarteter Jinja2-Variablen +#} +``` + +Vorlagen liegen unter `_templates/_template.py` und `_templates/_template.html`. + +## Konfiguration + +Alle Laufzeitvariablen kommen aus `.env` (nie in Git einchecken): + +```env +ZITADEL_CLIENT_ID=... +ZITADEL_CLIENT_SECRET=... +ZITADEL_DISCOVERY_URL=https://id.vmlx.de/.well-known/openid-configuration +SECRET_KEY=... +``` + +## Weitere Vorgabedokumente + +| Datei | Inhalt | +|---|---| +| `ai-context/AI-operative_Vorgaben.md` | Tech-Stack, Verzeichnisstruktur, Docker-Setup | +| `ai-context/strukturelle-vorgaben.md` | Dateiheader-Konventionen, Sphinx-Setup | +| `ai-context/AI-auth-vorgaben.md` | Zitadel-Einrichtung Schritt für Schritt | +| `ai-context/grob-kozept-vom-interview.md` | Vollständige fachliche Anforderungen und UX-Workflows | diff --git a/README.md b/README.md index fdb3fe6..10a3f26 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,16 @@ Benutzer- und Rollenverwaltung über SQLite. ## Technologie-Stack -| Komponente | Technologie | -|---|---| -| Backend | Python Flask 2.x | -| OIDC-Client | Authlib | -| Datenbank | SQLite via SQLAlchemy | -| IdP | Zitadel | -| Produktion | Docker / gunicorn | +| Komponente | Technologie | +| -------------| -----------------------| +| Backend | Python Flask 2.x | +| OIDC-Client | Authlib | +| Datenbank | SQLite via SQLAlchemy | +| IdP | Zitadel | +| Produktion | Docker / waitress | +| web-js-frontend | mithril.js | + + --- diff --git a/ai-context/AI-operative_Vorgaben.md b/ai-context/AI-operative_Vorgaben.md index 4b1bb47..abce55d 100644 --- a/ai-context/AI-operative_Vorgaben.md +++ b/ai-context/AI-operative_Vorgaben.md @@ -1,6 +1,6 @@ # AI.md — Strukturvorgaben für neue Applikation -**Autoren:** Björn Runden, Gerd Goldberg +**Autoren:** Björn Runden , Gerd Goldberg , Bruno Runden **Zweck dieses Dokuments:** Verbindliche strukturelle, betriebliche und infrastrukturelle Vorgaben für eine neue Python-Applikation. Applikationslogik, Routing und Frontend sind bewusst nicht Teil dieses Dokuments. --- diff --git a/ai-context/grob-kozept-vom-interview.md b/ai-context/grob-kozept-vom-interview.md new file mode 100644 index 0000000..f7477fd --- /dev/null +++ b/ai-context/grob-kozept-vom-interview.md @@ -0,0 +1,195 @@ +# Konzept: Webanwendung zur Unterstützung der Kundenakquise + +Datum: 08. Juni 2026 +Verantwortlich: Gerd Goldberg + +## 1. Einleitung + +Dieses Dokument beschreibt das Konzept für eine neue Webanwendung, die eine bestehende +Anwendung zur Kundenakquise ablösen soll. Die neue Lösung ermöglicht die Verwaltung von +Kunden, Kontakten, Projekten und Gesprächsnotizen sowie die manuelle und optionale +telefonieintegrierte Erfassung von Anrufen, um Akquise-Prozesse effizient zu unterstützen. +Ziel ist die Ablösung der bestehenden Anwendung, um die Effizienz, Benutzerfreundlichkeit +und Transparenz der Akquise-Prozesse zu steigern. Alle relevanten Informationen werden zentral +verwaltet und können einfach ausgewertet werden. + +--- + +## 2. Zielsetzung + +Die neue Webanwendung soll folgende Hauptziele erfüllen: + +- Ablösung der bestehenden Anwendung durch eine moderne, webbasierte Lösung. +- Zentrale Verwaltung von Kunden, Kontakten und Projekten. +- Dokumentation von Akquise-Aktivitäten (Anrufe, Gesprächsnotizen, Tags). +- Manuelle Erfassung von Anrufen (ausgehend und eingehend). +- Flexible Import-Schnittstelle für Kontaktadressen (Excel/CSV). +- Optionale Telefonie-Integration (für spätere Entwicklung vorgesehen). +- Auswertungen und Exporte zur Analyse der Akquise-Erfolge. +- Mehrbenutzerfähigkeit mit projektbasierten Zugriffsrechten. + +--- + +## 3. Funktionsumfang + +### 3.1 Kunden- und Kontaktverwaltung + +- **Kundenstamm:** Verwaltung aller Kunden (Firmen oder Privatpersonen) mit allen + relevanten Daten (Name, Adresse, Kontaktdaten). +- **Kontakte:** + - Definition: Ansprechpartner beim Kunden (Auftraggeber). + - Jeder Kunde kann mehrere Kontakte (Ansprechpartner) mit individuellen Daten + (Name, Position, Telefonnummer, E-Mail) haben. + - Jeder Kontakt ist genau einem Kunden zugeordnet. + +### 3.2 Projektverwaltung + +- Jeder Kunde kann ein oder mehrere Projekte haben. +- Projekte dienen der Strukturierung der Akquise-Aktivitäten und können mit Benutzern + verknüpft werden. + +### 3.3 Kontaktadressen und Gesprächsnotizen + +- **Kontaktadressen:** + - Definition: Kontakte, die im Rahmen eines Projekts angerufen werden sollen. + - Dies können Firmen oder Privatpersonen sein, die als potenzielle Interessenten + oder Zielgruppen für die Akquise infrage kommen. + - Jede Kontaktadresse enthält Informationen wie Name, Telefonnummer, E-Mail, + Firma (falls zutreffend) und weitere Details. + - Zuordnung zu Projekten: Jede Kontaktadresse ist genau einem Projekt zugeordnet. + - Importfunktion: Kontaktadressen können per Excel oder CSV importiert werden + (siehe Abschnitt 3.4). +- **Gesprächsnotizen:** + - Zu jedem Anruf (manuell oder telefonieintegriert) an eine Kontaktadresse wird eine + Notiz erfasst, die folgende Informationen enthält: + - Metadaten: Datum, Uhrzeit, Anrufer (Benutzer), angerufene + Kontaktadresse, Projekt, Anrufrichtung (ausgehend/eingehend), Dauer. + - Inhalt: Freier Text zur Dokumentation des Gesprächs. + - Tags: Benutzerdefinierte Kennzeichen zur Kategorisierung (z. B. „Unterlagen + schicken", „Kein Interesse", „Wiedervorlage"). + +### 3.4 Import-Schnittstelle für Kontaktadressen + +- **Flexibler Import:** + - Unterstützte Formate: Excel (XLSX) und CSV. + - Feldzuordnung: Der Benutzer kann die Spalten der Importdatei den Feldern der + Anwendung zuordnen (z. B. Name → Name, Telefonnummer → Telefonnummer). + - Validierung: Automatische Prüfung der Daten auf Vollständigkeit und Konsistenz + (z. B. Telefonnummernformat). + - Fehlerbehandlung: Anzeige von Fehlern (z. B. fehlende Pflichtfelder) und + Möglichkeit zur Korrektur vor dem Import. + - Projektzuordnung: Beim Import kann das Zielprojekt ausgewählt werden, dem die + Kontaktadressen zugeordnet werden sollen. + +### 3.5 Manuelle Anrufverarbeitung + +- **Erfassung von Anrufen:** + - Benutzer können manuell ausgehende und eingehende Anrufe erfassen. + - Formular zur manuellen Eingabe von Anrufdaten (Datum, Uhrzeit, + Kontaktadresse, Notiz, Tags). + - Flexibilität: Ermöglicht die Nutzung der Anwendung unabhängig von einer + Telefonie-Integration. + +### 3.6 Optionale Telefonie-Integration (für spätere Entwicklung) + +- **Zukünftige Erweiterung:** + - Outbound-Calls: Direktes Anrufen von Kontaktadressen aus der Anwendung heraus + (über JavaScript-Bibliotheken wie SIP.js oder Anbieter-SDKs). + - Inbound-Calls: Automatische Anzeige des zugehörigen Kunden oder Kontakts bei + eingehenden Anrufen. + - Call-Logging: Automatische Speicherung von Anrufdaten (Datum, Uhrzeit, Dauer) + und Zuordnung zu Gesprächsnotizen. + - Hinweis: Diese Funktion ist optional und für eine spätere Entwicklungsphase + vorgesehen. + +### 3.7 Auswertungen und Exporte + +- Statistiken: Anzahl der Kontakte, Erfolgsquoten, Bearbeitungszeiten. +- Filterfunktionen: Auswertungen nach Kunde, Projekt, Benutzer, Tag oder Zeitrahmen. +- Exportformate: CSV, Excel (XLSX), PDF. + +### 3.8 Mehrbenutzerfähigkeit + +- Benutzerverwaltung: Jeder Benutzer hat einen eigenen Account mit Login-Daten. +- Projektzuordnung: Benutzer werden einem oder mehreren Projekten zugeordnet und + dürfen nur in diesen Projekten arbeiten. +- Rollen und Rechte: Admin-Benutzer können alle Daten verwalten, während normale + Benutzer nur auf ihre zugewiesenen Projekte zugreifen können. + +--- + +## 4. Technische Umsetzung + +### 4.1 Architektur + +- Frontend: Webanwendung (HTML, CSS, JavaScript) für alle gängigen Browser. +- Backend: Python mit Flask als Web-Framework. +- Datenbank: SQLite (lokal oder serverbasiert). + +### 4.2 Sicherheit + +- Authentifizierung: Sichere Benutzeranmeldung mit verschlüsselten Passwörtern. +- Autorisierung: Projektbasierte Zugriffskontrolle. +- Datenvalidierung: Serverseitige Prüfung aller Eingaben. + +### 4.3 Voraussetzungen + +- Server: Lokale Installation oder Cloud-Hosting (z. B. auf einem VPS). +- Telefonie-Integration (optional): Falls später gewünscht, muss die Telefonanlage eine + JavaScript-API oder SDK bereitstellen. +- Import-Bibliotheken: Nutzung von Bibliotheken wie `pandas` (Python) für den Import von + Excel/CSV-Dateien. + +--- + +## 5. Datenmodell + +Die Anwendung basiert auf folgenden Kern-Tabellen: + +| Tabelle | Beschreibung | +|---|---| +| Kunden | Verwaltung der Kunden (Firmen oder Privatpersonen) mit allen relevanten Daten. | +| Kontakte | Ansprechpartner der Kunden (Name, Position, Telefonnummer, E-Mail). Enthält einen Foreign-Key zur Kunden-ID, um die Zuordnung zu genau einem Kunden herzustellen. | +| Projekte | Projekte, die einem Kunden zugeordnet sind. | +| Benutzer | Benutzer der Anwendung mit Login-Daten und Rollen. | +| Benutzer_Projekt | Zuordnung von Benutzern zu Projekten (n:m-Beziehung). | +| Kontaktadressen | Kontakte, die im Rahmen eines Projekts angerufen werden (Firmen oder Privatpersonen). Enthält einen Foreign-Key zur Projekt-ID, um die Zuordnung zu genau einem Projekt herzustellen. | +| Gesprächsnotizen | Dokumentation von Anrufen (Datum, Uhrzeit, Anrufer, Kontaktadresse, Notiz, Tags). Enthält einen Foreign-Key zur Kontaktadressen-ID. | +| Tags | Benutzerdefinierte Tags zur Kategorisierung von Gesprächsnotizen. | +| Gesprächsnotizen_Tags | Verknüpfungstabelle für die n:m-Beziehung zwischen Gesprächsnotizen und Tags. | + +--- + +## 6. Benutzererlebnis (UX) + +### 6.1 Oberflächen-Design + +- Intuitive Bedienung: Klare Struktur und einfache Navigation. +- Responsive Design: Optimiert für Desktop und Tablet. + +### 6.2 Workflow-Beispiel + +1. **Import von Kontaktadressen:** + - Benutzer lädt eine Excel- oder CSV-Datei hoch. + - System zeigt eine Vorschau der Daten mit Zuordnung der Spalten zu den Feldern der + Anwendung. + - Benutzer bestätigt den Import oder korrigiert Fehler. + - Kontaktadressen werden dem ausgewählten Projekt zugeordnet. + +2. **Manueller Anruf (ausgehend):** + - Benutzer wählt eine Kontaktadresse aus der Liste aus. + - Benutzer erfasst manuell die Gesprächsnotiz (Datum, Uhrzeit, Notiz, Tags). + +3. **Manueller Anruf (eingehend):** + - Benutzer erfasst den eingehenden Anruf manuell und ordnet ihn einer + Kontaktadresse zu. + - Benutzer kann direkt eine Gesprächsnotiz anlegen. + +4. **Auswertungen:** + - Benutzer filtert Gesprächsnotizen nach Projekt, Tag oder Zeitrahmen. + - Export der Daten als CSV/Excel/PDF. + + +# Kundenanmerkungen +zu Punkt 2, Export soll auch flexibel möglich sein. Kunden und Projetbezogene Dublettenprüfung fehlt noch. +Ausserdem müssen wir die Möglichkeit haben, nach Kontakten zu suchen. Name, Ort, Tags usw. Momentan können wir das über die Startseite der alt-Anwendung filtern \ No newline at end of file