109 lines
4.0 KiB
Markdown
109 lines
4.0 KiB
Markdown
|
|
## 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 # Waitress-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 |
|