leeres repo mit mds
This commit is contained in:
br committed
1 parent
5126decf36
commit
4a6d56432d
4 files changed
+317
-8
No files matched your search
@@ -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
|
||||
"""
|
||||
<Einzeiliger Modultitel>
|
||||
|
||||
<Optionale längere Beschreibung.>
|
||||
|
||||
:author: Vorname Nachname <email@beispiel.de>
|
||||
:date: YYYY-MM-DD
|
||||
:version: 1.0
|
||||
"""
|
||||
```
|
||||
|
||||
**Jinja2/HTML (`.html`)**:
|
||||
```html
|
||||
{#
|
||||
Datei: templates/beispiel.html
|
||||
Autor: Vorname Nachname <email@beispiel.de>
|
||||
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 |
|
||||
@@ -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 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# AI.md — Strukturvorgaben für neue Applikation
|
||||
|
||||
**Autoren:** Björn Runden, Gerd Goldberg
|
||||
**Autoren:** Björn Runden <br@chamaeleoncloud.de>, Gerd Goldberg <Gerd.Goldberg@outlook.com>, Bruno Runden <mail@bruno.zone>
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
@@ -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
|
||||
Reference in new issue
Block a user