11. Fallstudie: Die Anwendung RdvMedecins
11.1. Die Aufgabenstellung
Die Anwendung RdvMedecins verwaltet die Termine einer Arztpraxis. Jeder Arzt hat Zeitfenster (zum Beispiel von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten); ein Termin besteht aus einem Tag, einem Zeitfenster und einem Client (einem Patienten). Dies ist die exakte Portierung der Anwendung [Flask] in [Spring MVC] aus der vorigen Lektion (die ihrerseits von der Version in [ASP.NET Core MVC] portiert wurde): dieselbe Datenbank, dieselben Geschäftsregeln, dieselben Seiten, dieselben URLs, dieselben Übersetzungswörterbücher. Die HTML-Seiten werden vom Server mit [Jinja2]-Views erzeugt; der Datenbankzugriff erfolgt über [SQLAlchemy].
Drei Benutzerrollen teilen sich die Anwendung:
Rolle | Wer | Was sie tun können |
ADMIN | Der Administrator ([admin]) | Terminkalender einsehen, Termine für jeden Patienten vereinbaren und stornieren; Ärzte und Clients verwalten (auflisten, hinzufügen, bearbeiten, löschen) |
DOCTOR | Ärzte | Terminkalender einsehen, Termine vereinbaren und Termine für jeden Patienten stornieren |
USER | Clients (Patienten) | Terminkalender einsehen, ohne die Namen anderer Patienten zu sehen; einen Termin für sich selbst buchen; ihren Termin stornieren; ihr Konto verwalten; ein Konto erstellen |
Wichtige Verwaltungsregeln:
- Keine Termine in der Vergangenheit;
- Ein Zeitfenster kann pro Tag nur einmal gebucht werden;
- Ein Patient darf jeweils nur einen künftigen Termin haben;
- Zwei Ärzte (oder zwei Clients) dürfen nicht denselben Vor- und Nachnamen haben, und ein Login gehört nur zu einem Konto;
- Ein Arzt mit Terminen kann nicht gelöscht werden; ein Client wird zusammen mit seinen Terminen gelöscht;
- Die Anmeldeseite ist gegen Bots geschützt (CAPTCHA, begrenzte Versuche), und das Erstellen eines Client-Kontos erfordert zuvor das Lösen des CAPTCHA auf dieser Seite.
11.2. Die Anwendung benutzen
11.2.1. Die Anmeldeseite

Die Seite zeigt zwei Schaltflächen: Anmelden und Patientenkonto erstellen. Bei beiden müssen Sie die im Bild gezeigten Zeichen eingeben. Die Schaltflächen FR / EN wechseln die Sprache:

Ein Fehler (hier ein falsch eingegebenes CAPTCHA) wird am Seitenende auf hellrosa Hintergrund angezeigt:

11.2.2. Der Kalender aus Sicht des Administrators und der Ärzte
Nach der Anmeldung gelangt der Administrator auf die Kalenderseite. Er wählt einen Arzt und einen Tag aus:


Jedes Zeitfenster ist entweder frei (Schaltfläche Buchen) oder belegt (Name des Patienten, Schaltfläche Stornieren). Ein Klick auf Buchen öffnet ein Fenster, das nach den Angaben zum Patienten fragt. Dieses Fenster wird wie der Rest der Seite vom Server erzeugt: Die URL enthält nun den Parameter [book=4], die Nummer des ausgewählten Zeitfensters:

Nach der Buchung bestätigt eine Meldung den Termin:

Ein Klick auf „Stornieren“ löst eine Bestätigungsabfrage aus (hier durch Dr. Pélissier, dessen Navigationsleiste die Verwaltungsmenüs nicht enthält):

11.2.3. Das Patientenportal
Ein Patient (Rolle USER) gelangt zu „Mein Bereich“: sein künftiger Termin, den er stornieren kann, und Links zur Verwaltung seines Kontos und zur Ansicht seines Kalenders. Hier hat er noch keinen Termin:

Im Kalender sieht er die Namen anderer Patienten nicht; sie werden durch „Gebucht“ ersetzt: Dieser Name steht nicht einmal im Quelltext der Seite. Er kann ein freies Zeitfenster buchen:

Das Buchungsfenster fordert ihn nicht auf, einen Patienten auszuwählen: Er bucht den Termin für sich selbst.


Seine Übersicht zeigt nun seinen künftigen Termin, den er stornieren kann:

Da er einen künftigen Termin hat, kann er keinen weiteren vereinbaren: Die Schaltfläche „Buchen“ wird nicht angezeigt, und im Kalender eines anderen Tages oder eines anderen Arztes erklärt eine Meldung den Grund:

Kontoverwaltung: die eigenen Angaben bearbeiten, das Passwort ändern oder das Konto (und die Termine) löschen. Für jede Änderung ist das aktuelle Passwort erforderlich:

Ein Patient, der versucht, eine dem Administrator vorbehaltene Seite zu öffnen (hier [/doctors], von Hand eingegeben), erhält eine Fehlerseite:

11.2.4. Ärzte und Patienten verwalten
Der Administrator hat zwei zusätzliche Menüs, Ärzte und Patienten:


Das Formular zum Hinzufügen eines Arztes, mit Fehlern abgeschickt:

Ein Name, der mit dem eines bestehenden Arztes übereinstimmt, wird abgelehnt, auch wenn er kleingeschrieben ist (die Datenbank selbst vergleicht Namen ohne Unterscheidung von Groß- und Kleinbuchstaben und Akzenten; siehe Beispiel 28):

Das Löschen eines Patienten erfordert eine Bestätigung:

11.2.5. Ein Patientenkonto erstellen
Auf der Anmeldeseite öffnet die Schaltfläche „Patientenkonto erstellen“ das Formular nur, wenn das CAPTCHA korrekt eingegeben wurde:

Nach der Erstellung des Kontos wird der Benutzer zur Anmeldeseite zurückgeleitet, mit bereits ausgefülltem Benutzernamen:

11.2.6. Ende der Sitzung
Das Login-Token ist zwei Stunden lang gültig. Nach Ablauf dieser Zeit (oder wenn das Token manipuliert wurde) leitet die angeforderte Seite mit der folgenden Meldung auf die Anmeldeseite um:

11.3. Installation und Ausführung
Die Anwendung befindet sich im Ordner [rdvmedecins2-flask], neben dem Ordner [examples]. Es ist ein eigenständiges Projekt mit eigener Datei [requirements.txt] und eigener virtueller Umgebung. Die Datei [README.md] im Ordner enthält alles Folgende. Die Einführung dieses Dokuments hat die Installation bereits beschrieben; hier liefern wir weitere Einzelheiten.
11.3.1. Erforderliche Software
Zwei Softwarepakete genügen:
- [Python] 3.12 oder höher (die Anwendung verwendet die in Version 3.12 eingeführte Syntax für generische Klassen). Überprüfen Sie die Installation in einem Terminal:
- ein [MySQL]-8- Server, zum Beispiel der von [Laragon] unter [Windows] (siehe Anhänge). [MariaDB] funktioniert ebenfalls: Die Anwendung wurde damit getestet.
Die Bibliotheken werden von [pip] aus dem Repository [PyPI] (*Python Package Index*) heruntergeladen: Sie müssen daher während der Installation mit dem Internet verbunden sein. Als Editor empfehlen wir [Visual Studio Code] mit der [Python]-Erweiterung von Microsoft (siehe Anhänge); alles lässt sich jedoch auch über die Befehlszeile erledigen.
11.3.2. Die Datenbank erstellen
Die Datenbank [dbrdvmedecins2] wird durch das Skript [database/dbrdvmedecins2.sql] erstellt. Öffnen Sie mit [Laragon] das Werkzeug [HeidiSQL] (Schaltfläche Datenbank) und führen Sie das Skript über das Menü Datei / SQL-Datei ausführen aus. In der Befehlszeile, im Anwendungsordner:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
Die Option [-p] fragt nach dem Passwort für [root]; lassen Sie sie weg, wenn das Konto kein Passwort hat (wie bei [Laragon]). Es ist dieselbe Datenbank wie bei den Versionen [ASP.NET Core] und [Spring MVC]: Wenn sie bereits existiert, ist dieser Schritt optional. Das Skript kann jederzeit ausgeführt werden, um zu den ursprünglichen Daten zurückzukehren.
11.3.3. Den Datenbankzugriff konfigurieren
Alle Konfigurationseinstellungen stehen in der Datei [config.py] (weiter unten besprochen). Standardmäßig verbindet sich die Anwendung mit [MySQL] auf [localhost], Port 3306, mit dem Benutzer [root] ohne Passwort: Das sind die Standardeinstellungen von [Laragon]. Hat Ihr Konto [root] ein Passwort, tragen Sie es am einfachsten in diese Datei ein, in die Zeile [DB_PASSWORD = ""]. Um kein Passwort in eine Projektdatei zu schreiben, können Sie es auch über eine Umgebungsvariable angeben, die Vorrang vor der Datei hat. Ihr Name ist der der Variablen in der Datei, mit vorangestelltem [FLASK_] (Beispiel 25):
| export FLASK_DB_PASSWORD=myPassword # Linux, macOS
set FLASK_DB_PASSWORD=myPassword # Windows (cmd)
$env:FLASK_DB_PASSWORD="myPassword" # Windows (PowerShell)
|
Die Variable gilt nur für das Terminal, in dem sie definiert wurde; die Anwendung wird dann von dort aus gestartet.
11.3.4. Die Anwendung starten
In einem Terminalfenster, geöffnet im Ordner [rdvmedecins2-flask], mit erstellter und aktivierter virtueller Umgebung und installierten Bibliotheken (siehe Einführung):
Die Einführung hat die Konsolenausgabe gezeigt. Öffnen Sie anschließend die URL [http://localhost:8081] in einem Browser und beenden Sie die Anwendung mit [Ctrl-C].
11.3.5. Demo-Konten
Das Passwort jedes Kontos ist sein Benutzername; zusätzlich müssen Sie die Zeichen aus dem Bild eingeben, in Groß- oder Kleinbuchstaben:
Logins | Rolle |
[admin] | ADMIN (der Administrator) |
[pelissier], [tatou], [dupont] | DOCTOR (Ärzte) |
[martin], [durand], [bistrou], [german] | USER (Patienten) |
Eine Anleitung zum Erkunden der Anwendung:
- [admin]: Terminkalender, Frau Marie PELISSIER, heute: Ein Zeitfenster ist bereits von Frau Brigitte BISTROU gebucht. Buchen Sie ein Zeitfenster für Herrn Jean MARTIN und versuchen Sie dann, einen zweiten Termin für ihn zu buchen (abgelehnt). Menüs Ärzte und Patienten: hinzufügen, bearbeiten, löschen (Dr. PELISSIER, die Termine hat, kann nicht gelöscht werden);
- [pelissier]: Sein Tageskalender wird direkt angezeigt; die von Hand eingegebene Adresse [/doctors] liefert eine Fehlerseite 403;
- [martin]: Mein Bereich, sein Termin, der Kalender, in dem andere Patienten als „Gebucht“ erscheinen; Mein Konto verwalten;
- Anmeldeseite: Patientenkonto erstellen, dann mit dem neuen Konto anmelden;
- Schaltflächen FR / EN: Die gesamte Oberfläche wechselt die Sprache, einschließlich der Datumsangaben.
11.3.6. Entwicklungsmodus
Die Datei [app.py] startet die Anwendung mit dem [dev]-Profil (der Datei [config_dev.py], später besprochen): Die Konsole zeigt dann jeden von [SQLAlchemy] an die Datenbank gesendeten SQL-Befehl an. Der Debug-Modus des Entwicklungsservers bietet zwei weitere Funktionen:
- das automatische Neuladen: Die Anwendung startet automatisch neu, sobald eine [.py]-Datei geändert wird. Eine geänderte [templates/*.html]-View wird bei der nächsten Anzeige der Seite neu geladen;
- die Debug-Seite für Ausnahmen (Beispiel 03), die hier durch die Einstellung [PROPAGATE_EXCEPTIONS = False] deaktiviert ist (siehe unten): Die Anwendung zeigt auch während der Entwicklung ihre eigene Fehlerseite an, und der Aufrufstapel der Ausnahme wird in die Konsole geschrieben.
Der [Visual Studio Code]-Debugger erlaubt es ebenfalls, die Anwendung schrittweise auszuführen: Setzen Sie einen Haltepunkt, indem Sie in den Rand einer Codezeile klicken, und starten Sie dann die Datei [app.py] über das Menü Ausführen / Debugging starten (Taste [F5]), wobei Sie „Python Debugger“ und dann „Python-Datei“ auswählen. Das automatische Neuladen sollte vermieden werden (es startet die Anwendung in einem separaten Prozess, den der Debugger nicht verfolgt): Deaktivieren Sie es, indem Sie die Anwendung mit dem Befehl [flask --app rdvmedecins run --port 8081] (ohne [--debug]) starten.
11.3.7. Ein Produktionsserver
Der Entwicklungsserver [Werkzeug] ist nicht für den Produktivbetrieb gedacht: Er weist beim Start selbst darauf hin. In der Produktion wird die Anwendung auf einem WSGI-Server bereitgestellt (siehe das Kapitel über den Lebenszyklus). Die Anwendung deklariert in ihrer Datei [requirements.txt] einen solchen: [Waitress], ein in [Python] geschriebener Server, der unter [Windows] ebenso gut läuft wie unter [Linux]. Er ist bereits in der virtuellen Umgebung installiert:
| waitress-serve --port=8081 --call rdvmedecins:create_app
|
| INFO:waitress:Serving on http://0.0.0.0:8081
|
Die Option [--call] gibt eine Factory an, die aufgerufen wird ([create_app], im Paket [rdvmedecins]), um die Anwendung abzurufen. Bei einem Start auf diese Weise hat die Anwendung nicht das Profil [dev] (die Konsole zeigt die SQL-Befehle nicht an) und befindet sich auch nicht im Debug-Modus. [Waitress] verarbeitet mehrere Anfragen parallel in mehreren Threads (standardmäßig vier; Option [--threads]). Unter [Linux] ist auch [Gunicorn] weit verbreitet; er funktioniert jedoch nicht unter [Windows]. In beiden Fällen wird der WSGI-Server üblicherweise hinter einen Webserver gestellt ([nginx], [Apache]), der Anfragen per HTTPS entgegennimmt und an die Anwendung weiterleitet.
In der Produktion müssen Sie außerdem die geheimen Schlüssel ändern und über Umgebungsvariablen angeben, dass die Website über HTTPS ausgeliefert wird:
| export FLASK_SECRET_KEY="<a long random string>"
export FLASK_JWT_SECRET="<another long random string>"
export FLASK_COOKIE_SECURE=true
|
Eine geeignete Zufallszeichenfolge erhalten Sie mit [Python] selbst: [python -c "import secrets; print(secrets.token_urlsafe(48))"].
11.3.8. Häufige Probleme
Beim Start liest die Anwendung die Listen der Ärzte und Clients: Ist die Datenbank nicht erreichbar, bricht die Anwendung sofort ab, mit einem Fehler in der Konsole. Diesem Fehler geht ein langer Aufrufstapel voraus; die relevante Meldung steht am Ende, vor der Zeile [(Background on this error at: ...)]. Zum Beispiel bei einer nicht existierenden Datenbank:
| ...
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (1049, "Unknown database 'dbunknown'")
(Background on this error at: https://sqlalche.me/e/21/e3q8)
|
Die häufigsten Meldungen:
Meldung | Ursache |
[Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)] ([[WinError 10061]] unter [Windows]) | [MySQL] wurde nicht gestartet oder lauscht nicht auf [localhost:3306] |
[Access denied for user 'root'@'localhost'] | Das Passwort für [MySQL] muss eingetragen werden (siehe „Den Datenbankzugriff konfigurieren“) |
[Unknown database 'dbrdvmedecins2'] | Das Skript [database/dbrdvmedecins2.sql] wurde nicht ausgeführt |
[JWT_SECRET must be at least 32 characters long (see config.py).] | Der geheime Token-Schlüssel in [config.py] (oder in der Variablen [FLASK_JWT_SECRET]) ist zu kurz |
[ModuleNotFoundError: No module named 'flask'] | Die virtuelle Umgebung ist nicht aktiviert, oder die Bibliotheken wurden darin nicht installiert |
[Address already in use] oder [Port 8081 is in use by another program] | Port 8081 wird bereits verwendet (läuft die Version [Spring MVC] noch?): Beenden Sie sie oder ändern Sie den Port in [app.py] |
['cryptography' package is required for sha256_password or caching_sha2_password auth methods] | Das Konto [MySQL] verwendet die Authentifizierungseinstellungen von [MySQL] 8: Die Bibliothek [cryptography], die von [PyMySQL[rsa]] installiert wird (siehe [requirements.txt]), fehlt |
[SyntaxError] beim Start, in einer [class ...[T: ...]]-Zeile | Die Version von [Python] ist älter als 3.12 |
11.4. Die Architektur der Anwendung

- Der Browser sendet seine Anfragen an den Server (den Entwicklungsserver [Werkzeug] oder [Waitress]), der sie an die [Flask]-Anwendung weiterleitet. Jede Anfrage durchläuft zunächst die Funktionen [before_request] (siehe das Kapitel über den Lebenszyklus): die Sprache der Anfrage, dann den Benutzer – anhand des JWT-Tokens in seinem Cookie identifiziert – und die Zugriffsregel, die geschützte Seiten für Besucher sperrt, die sie nicht einsehen dürfen ([auth/security.py]);
- [controllers]: Controller der Web-Schicht, ein Blueprint pro Anwendungsteil. Sie laufen alle über ein einziges Objekt, [ApplicationModel] (Ordner [web]), das die Listen der Ärzte und Clients im Arbeitsspeicher hält und andere Anfragen an die Geschäftsschicht weiterleitet;
- [auth]: Authentifizierung, JWT-Tokens, CAPTCHA, Begrenzung der Versuche und Kontoerstellung;
- [web]: gemeinsame Elemente der Web-Schicht: der Cache und die Fassade [ApplicationModel], Übersetzung, Flash-Meldungen, Validierung, für alle Views gemeinsame Variablen und Fehlerseiten; [forms]: Formulare; [WTForms]; [models]: View-Modelle;
- [business]: Geschäftsregeln und Transaktionen;
- [repositories]: die DAO-Schicht, eine Klasse pro Tabelle;
- [entities]: die Entitäten, die [SQLAlchemy] aus der Datenbank liest und in sie schreibt; [domain]: die Kalenderobjekte, die von der Geschäftsschicht berechnet werden;
- [templates]: die [Jinja2]-Views, die die HTML-Seiten erzeugen; [i18n]: die Wörterbücher, die vom Übersetzer verwendet werden; [static]: das Stylesheet, das Seitenskript und [Bootstrap];
- [rdvmedecins/__init__.py]: der Builder [create_app], der alles zusammensetzt; [config.py]: die Konfiguration.
Der Anwendungsordner:
| rdvmedecins2-flask/
├── app.py
├── config.py
├── config_dev.py
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── rdvmedecins/
│ ├── __init__.py
│ ├── auth/
│ │ ├── auth_service.py
│ │ ├── captcha.py
│ │ ├── captcha_drawing.py
│ │ ├── connected_user.py
│ │ ├── limiter.py
│ │ ├── passwords.py
│ │ ├── README.md
│ │ ├── registration_pass.py
│ │ └── security.py
│ ├── business/
│ │ ├── business.py
│ │ ├── dates.py
│ │ ├── exception.py
│ │ ├── person_data.py
│ │ ├── README.md
│ │ └── service.py
│ ├── controllers/
│ │ ├── area.py
│ │ ├── auth.py
│ │ ├── clients.py
│ │ ├── doctors.py
│ │ ├── language.py
│ │ ├── persons.py
│ │ ├── README.md
│ │ ├── registration.py
│ │ └── schedule.py
│ ├── domain/
│ │ ├── README.md
│ │ └── schedule.py
│ ├── entities/
│ │ ├── appointment.py
│ │ ├── base.py
│ │ ├── person.py
│ │ ├── README.md
│ │ ├── role.py
│ │ ├── slot.py
│ │ └── user.py
│ ├── forms/
│ │ ├── forms.py
│ │ ├── README.md
│ │ └── rules.py
│ ├── i18n/
│ │ ├── en.json
│ │ └── fr.json
│ ├── models/
│ │ ├── README.md
│ │ └── view_models.py
│ ├── repositories/
│ │ ├── appointment_repository.py
│ │ ├── client_repository.py
│ │ ├── doctor_repository.py
│ │ ├── person_repository.py
│ │ ├── README.md
│ │ ├── slot_repository.py
│ │ └── user_repository.py
│ ├── static/
│ │ ├── css/
│ │ │ └── styles.css
│ │ ├── js/
│ │ │ └── app.js
│ │ └── lib/
│ │ └── bootstrap/
│ ├── templates/
│ │ ├── account.html
│ │ ├── area.html
│ │ ├── error.html
│ │ ├── fragments/
│ │ │ ├── booking.html
│ │ │ ├── captcha.html
│ │ │ ├── confirmation.html
│ │ │ ├── errors.html
│ │ │ ├── flash.html
│ │ │ ├── navbar.html
│ │ │ └── person_fields.html
│ │ ├── layout.html
│ │ ├── login.html
│ │ ├── persons/
│ │ │ ├── form.html
│ │ │ └── list.html
│ │ ├── README.md
│ │ ├── registration.html
│ │ └── schedule.html
│ └── web/
│ ├── application_model.py
│ ├── common_model.py
│ ├── errors.py
│ ├── flash.py
│ ├── README.md
│ ├── services.py
│ ├── translator.py
│ ├── utils.py
│ └── validation.py
├── README.md
└── requirements.txt
|
Jeder Paketordner enthält außerdem eine Datei namens [__init__.py] – in der Regel leer –, die den Ordner zu einem [Python]-Paket macht: Dadurch kann [from rdvmedecins.entities import Doctor] geschrieben werden. [Bootstrap] ist diesmal Teil der Anwendung (Ordner [static/lib/bootstrap]): Die Fallstudie ist in sich geschlossen.
Beachten Sie die Wahl für das Paket [rdvmedecins]: Die Anwendung ist nicht mehr ein einfaches Modul [app.py], sondern ein Paket, dessen Datei [__init__.py] die Factory [create_app] enthält. Dies ist die Struktur, die die Dokumentation von [Flask] für eine Anwendung dieser Größe empfiehlt: Die Datei [app.py] im Wurzelverzeichnis dient nur noch dazu, den Entwicklungsserver zu starten.
11.5. Die Datenbank
Die Datenbank [dbrdvmedecins2] hat fünf Tabellen:
- [users]: Benutzer, die sich anmelden dürfen;
- [doctors] und [clients]: Ärzte und Patienten, jeweils mit ihren Benutzerkonten verknüpft;
- [slots]: die verfügbaren Zeitfenster jedes Arztes;
- [appointments]: Termine, ein Client pro Zeitfenster an einem bestimmten Tag.
11.5.1. database/dbrdvmedecins2.sql
| -- =========================================================================
-- Datenbank [dbrdvmedecins2] - MySQL 8
--
-- Weiterentwicklung von [dbrdvmedecins]:
-- 1. Die Tabellen [doctors] und [clients] erhalten eine Spalte [user],
-- Fremdschlüssel auf users(id): Jeder Arzt und jeder Client ist
-- nun auch ein Benutzer, der sich anmelden kann;
-- 2. Eine dritte Rolle kommt hinzu: DOCTOR (zusätzlich zu ADMIN und USER);
-- 3. Das Skript legt für jeden Arzt (Rolle DOCTOR)
-- und für jeden Client (Rolle USER) eine Zeile in [users] an:
-- - login = Nachname in Kleinbuchstaben
-- - password = Nachname in Kleinbuchstaben, mit bcrypt gehasht (10 Runden)
-- - Anzeigename = Vorname + Nachname
--
-- 4. Eindeutigkeitsbedingungen, alle BENANNT (die Anwendung erkennt
-- den Namen der verletzten Bedingung in der MySQL-Fehlermeldung):
-- - unq_users_login : Ein Login gehört nur zu einem Konto;
-- - unq_doctors_first_name_last_name : Zwei Ärzte dürfen nicht denselben
-- Vor- und Nachnamen haben;
-- - unq_clients_first_name_last_name : dasselbe für die Clients.
-- Vorsicht: Die Kollation utf8mb4_unicode_ci vergleicht unabhängig von
-- Groß-/Kleinschreibung und Akzenten - "Hélène DUPONT" und "helene dupont"
-- gelten daher als identisch.
--
-- Die Tabelle [users] muss nun VOR [doctors] und [clients] angelegt werden
-- (diese verweisen auf sie) und NACH ihnen gelöscht werden.
-- =========================================================================
-- Das Skript ist in UTF-8 geschrieben
SET NAMES utf8mb4;
-- Bei jeder Ausführung des Skripts beginnen wir mit einer leeren Datenbank (praktisch in der Entwicklung)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;
-- Löschreihenfolge: von den "Kind"-Tabellen zu den "Eltern"-Tabellen
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;
-- -------------------------------------------------------------------------
-- Tabelle [users]: die Benutzer, die sich an der Anwendung anmelden dürfen
-- -------------------------------------------------------------------------
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
login VARCHAR(30) NOT NULL, -- login identifier
password VARCHAR(100) NOT NULL, -- HASHED password (bcrypt) - never in clear
name VARCHAR(40) NOT NULL, -- name displayed once logged in
role VARCHAR(10) NOT NULL, -- 'ADMIN', 'DOCTOR' or 'USER'
-- Ein Login darf nur zu einem Konto gehören
CONSTRAINT unq_users_login UNIQUE (login)
);
-- -------------------------------------------------------------------------
-- Tabelle [doctors]: die Ärzte der Praxis
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
id INT AUTO_INCREMENT PRIMARY KEY, -- primary key (technical identifier)
version INT NOT NULL DEFAULT 0, -- row version number (optimistic lock)
title VARCHAR(5) NOT NULL, -- Melle, Mme, Mr
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
-- ein Konto pro Arzt und ein Arzt pro Konto
CONSTRAINT unq_doctors_user UNIQUE (`user`),
-- Zwei Ärzte dürfen nicht denselben Vor- und Nachnamen haben
CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- Tabelle [clients]: die Patienten der Ärzte
-- -------------------------------------------------------------------------
CREATE TABLE clients (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
title VARCHAR(5) NOT NULL,
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
-- ein Konto pro Client und ein Client pro Konto
CONSTRAINT unq_clients_user UNIQUE (`user`),
-- Zwei Clients dürfen nicht denselben Vor- und Nachnamen haben
CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- Tabelle [slots]: die Zeitfenster jedes Arztes
-- -------------------------------------------------------------------------
CREATE TABLE slots (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
doctor_id INT NOT NULL, -- foreign key -> doctors(id)
start_hour INT NOT NULL, -- start hour of the slot
start_minute INT NOT NULL, -- start minute of the slot
end_hour INT NOT NULL, -- end hour of the slot
end_minute INT NOT NULL, -- end minute of the slot
CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);
-- -------------------------------------------------------------------------
-- Tabelle [appointments]: die von den Clients gebuchten Termine
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
day DATE NOT NULL, -- day of the appointment
slot_id INT NOT NULL, -- foreign key -> slots(id)
client_id INT NOT NULL, -- foreign key -> clients(id)
CONSTRAINT fk_appointments_slot FOREIGN KEY (slot_id) REFERENCES slots(id),
CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
-- Dasselbe Zeitfenster darf am selben Tag nur einmal gebucht werden
CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);
-- =========================================================================
-- Demodaten
-- =========================================================================
-- die Benutzer: Passwörter mit bcrypt gehasht (10 Salt-Runden)
-- admin/admin (ADMIN)
-- ein DOCTOR-Konto pro Arzt, ein USER-Konto pro Client
-- (das Demokonto user/user entfällt: Ein USER-Konto ist
-- nun IMMER das Konto eines Clients, der Termine buchen und das Konto verwalten kann)
-- (Login = Passwort = Nachname in Kleinbuchstaben)
INSERT INTO users (login, password, name, role) VALUES
('admin', '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator', 'ADMIN'),
-- doctors
('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER', 'DOCTOR'),
('tatou', '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU', 'DOCTOR'),
('dupont', '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT', 'DOCTOR'),
-- clients
('martin', '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN', 'USER'),
('durand', '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND', 'USER'),
('bistrou', '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
('german', '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN', 'USER');
-- die Ärzte: Die Spalte [user] wird anhand des Logins ermittelt,
-- statt die Werte der Primärschlüssel von [users] vorauszusetzen
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
('Mme', 'PELISSIER', 'Marie', (SELECT id FROM users WHERE login = 'pelissier')),
('Mr', 'TATOU', 'Paul', (SELECT id FROM users WHERE login = 'tatou')),
('Melle','DUPONT', 'Sophie', (SELECT id FROM users WHERE login = 'dupont'));
INSERT INTO clients (title, last_name, first_name, `user`) VALUES
('Mr', 'MARTIN', 'Jean', (SELECT id FROM users WHERE login = 'martin')),
('Mme', 'DURAND', 'Alice', (SELECT id FROM users WHERE login = 'durand')),
('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
('Mr', 'GERMAN', 'Luc', (SELECT id FROM users WHERE login = 'german'));
-- Zeitfenster von Arzt PELISSIER (doctor_id = 1): von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
(1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
(1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
(1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);
-- Zeitfenster von Arzt TATOU (doctor_id = 2): von 14:00 bis 18:00 Uhr in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
(2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
(2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
(2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);
-- ein bereits gebuchter Termin, um ein belegtes Zeitfenster sofort im Terminkalender zu sehen
INSERT INTO appointments (day, slot_id, client_id) VALUES
(CURDATE(), 2, 3);
|
- Zeile 33: Die Datenbank wird erstellt, falls sie nicht existiert, mit dem Zeichensatz [utf8mb4] und der Kollation [utf8mb4_unicode_ci], die Zeichenketten ohne Rücksicht auf Groß- und Kleinschreibung und Akzente vergleicht (Beispiel 28);
- Zeilen 37–41: Die Tabellen werden gelöscht und anschließend neu erstellt; das Skript stellt die Datenbank in ihren Ausgangszustand zurück. Die Reihenfolge ist wichtig: Eine Tabelle kann nicht gelöscht werden, solange eine andere Tabelle sie über einen Fremdschlüssel referenziert;
- Zeilen 46–54: users: ein Login, ein Passwort, das von [bcrypt] als Hash abgelegt wird (Beispiel 25), der Anzeigename nach der Anmeldung und die Rolle ([ADMIN], [DOCTOR], oder [USER]). Die Bedingung [unq_users_login] stellt sicher, dass ein Benutzername nur zu einem Konto gehört;
- Zeilen 60–71: Jede Tabelle hat einen von der Datenbank erzeugten Primärschlüssel [id] und eine Spalte [version], die das optimistische Sperren darstellt (Beispiel 28). Die Spalte [user] ist ein Fremdschlüssel , der auf [users(id)] verweist: Die Datenbank weist jeden Wert zurück, der nicht die ID eines vorhandenen Benutzers ist. Da [user] in SQL ein reserviertes Wort ist, wird es in Backticks gesetzt. Drei Bedingungen: [fk_doctors_user] (der Fremdschlüssel), [unq_doctors_user] (ein Konto pro Arzt und ein Arzt pro Konto) und [unq_doctors_first_name_last_name] (keine Namensvetter). Alle Bedingungen sind benannt: Die Anwendung erkennt eine verletzte Bedingung an ihrem Namen;
- Zeilen 77–88: Die Tabelle [clients] hat exakt dieselben Spalten;
- Zeilen 94–102: Ein Zeitfenster gehört zu einem Arzt; Beginn und Ende werden in Stunden und Minuten gespeichert;
- Zeilen 108–117: Ein Termin besteht aus einem Tag (Typ [DATE], ohne Uhrzeit), einem Zeitfenster und einem Client. Die Bedingung [unq1_appointments] verhindert, dass dasselbe Zeitfenster am selben Tag zweimal gebucht wird: Die Datenbank erzwingt diese Regel, selbst wenn zwei Benutzer es gleichzeitig buchen;
- Zeilen 130–140: Demo-Benutzer, deren Passwort ihr Login ist. Die Hashes beginnen mit [$2b$10$]: dem Algorithmus ([bcrypt], Variante [2b]) und dem Kostenfaktor (10). Es folgen der Salt und der Hash;
- Zeilen 144–147: Die Spalte [user] jedes Arztes wird über eine Unterabfrage anhand des Logins ermittelt, statt Werte des Primärschlüssels anzunehmen;
- Zeilen 170–171: ein bereits vereinbarter Termin für heute ([CURDATE()]) im zweiten Zeitfenster von Dr. PELISSIER für Frau BISTROU: Der Kalender zeigt somit sofort ein gebuchtes Zeitfenster.
11.6. Projektkonfiguration
11.6.1. requirements.txt
| # die Bibliotheken der Anwendung: pip install -r requirements.txt
Flask==3.1.3
Flask-WTF==1.3.0
SQLAlchemy==2.1.1
PyMySQL[rsa]==1.2.3
PyJWT==2.15.0
bcrypt==5.0.0
Babel==2.18.0
# ein WSGI-Server für die Produktion (siehe README.md)
waitress==3.0.2
|
Die Bibliotheken der Anwendung mit ihren exakten Versionen ([==]). Die Angabe der Versionen stellt sicher, dass die Anwendung auf allen Rechnern gleich funktioniert, auch in einem Jahr noch. [PyMySQL[rsa]] installiert den Treiber [PyMySQL] samt seinen optionalen Abhängigkeiten [rsa], das heißt der Bibliothek [cryptography], die für die Authentifizierungsmethoden von [MySQL] 8 erforderlich ist. [pip install -r requirements.txt] installiert diese Bibliotheken und die, von denen sie abhängen ([Werkzeug], [Jinja2], [WTForms] ...). Der Befehl [pip freeze] zeigt die vollständige Liste dessen an, was in der virtuellen Umgebung installiert ist.
11.6.2. config.py
| # =========================================================================
# config.py - die Konfiguration der Anwendung.
#
# Flask behält nur die Variablen in GROSSBUCHSTABEN (siehe rdvmedecins/__init__.py,
# app.config.from_pyfile). Jeder Wert kann, ohne diese
# Datei zu ändern, durch eine Umgebungsvariable mit dem Präfix FLASK_ ersetzt werden:
# DB_PASSWORD wird dann FLASK_DB_PASSWORD geschrieben (app.config.from_prefixed_env).
# Die Werte dieser Variablen werden, wenn möglich, als JSON gelesen:
# FLASK_LOGIN_MAX_FAILURES=3 ergibt die Zahl 3, FLASK_COOKIE_SECURE=true den booleschen Wert True.
# =========================================================================
# ---- die MySQL-Datenbank [dbrdvmedecins2] (Skript: database/dbrdvmedecins2.sql):
# der Server, sein Port, der Benutzer und sein Passwort (die von Laragon:
# root, ohne Passwort), die Datenbank
DB_HOST = "localhost"
DB_PORT = 3306
DB_USER = "root"
DB_PASSWORD = ""
DB_NAME = "dbrdvmedecins2"
# True: die an die Datenbank gesendeten SQL-Anweisungen werden in der Konsole angezeigt
SQL_ECHO = False
# ---- der geheime Schlüssel von Flask: er SIGNIERT das Session-Cookie (Flash-
# Meldungen, Anti-CSRF-Token). Muss in der Produktion unbedingt geändert werden.
SECRET_KEY = "change-me-too-to-a-long-random-string"
# ---- Authentifizierung (siehe rdvmedecins/auth/)
# geheimer Schlüssel der JWT-Tokens: mindestens 32 Zeichen (HMAC-SHA256).
# Muss in der Produktion unbedingt geändert werden (langer, zufälliger String).
JWT_SECRET = "change-me-to-a-long-random-string"
# Gültigkeitsdauer eines Tokens in Sekunden (7200 s = 2 h); das Cookie, das
# das Token trägt, hat dieselbe Lebensdauer
JWT_EXPIRES_IN_SECONDS = 7200
# True in der Produktion (über HTTPS ausgelieferte Website): die Cookies der Anwendung
# werden dann nie über eine unverschlüsselte Verbindung gesendet
COOKIE_SECURE = False
# ---- Schutz vor Robotern (siehe rdvmedecins/auth/limiter.py)
# Login: erlaubte Fehlversuche für denselben Login von derselben IP-Adresse ...
LOGIN_MAX_FAILURES = 5
# ... vor einer Sperre dieser Dauer (die gesamte IP-Adresse wird ebenfalls gesperrt,
# wenn sie 5-mal so viele Fehlversuche ansammelt, alle Logins zusammen)
LOGIN_BLOCK_MINUTES = 15
# Anlegen von Client-Konten: maximal angelegte Konten pro Stunde und pro IP-
# Adresse. In einem Klassenraum gehen oft alle Rechner über dieselbe Adresse ins Netz:
# bei Bedarf erhöhen.
REGISTRATION_MAX_PER_HOUR = 10
|
Die Anwendungskonfiguration, gelesen von [app.config.from_pyfile] (Beispiel 25):
- Zeilen 15–19: Datenbankzugriff: der Server, sein Port, Benutzername und Passwort sowie die Datenbank. Aus diesen Werten wird die Verbindungs-URL für [SQLAlchemy] gebildet (siehe unten);
- Zeile 22: Anzeige der SQL-Befehle, standardmäßig deaktiviert;
- Zeile 26: der geheime Schlüssel für [Flask], der das Sitzungs-Cookie signiert (Beispiel 20);
- Zeilen 31–34: der Schlüssel, der die JWT-Tokens signiert, und ihre Lebensdauer: zwei Stunden;
- Zeile 37: In der Produktion tragen die Cookies der Anwendung das Attribut [Secure]; der Browser sendet sie nur über eine HTTPS-Verbindung;
- Zeilen 41–48: Einstellungen zum Bot-Schutz: die Anzahl der erlaubten fehlgeschlagenen Anmeldeversuche und die Dauer der daraus folgenden Sperre; die Anzahl der Client-Konten, die eine einzelne IP-Adresse pro Stunde erstellen darf.
Jeder Wert kann durch eine Umgebungsvariable mit dem Präfix [FLASK_] ersetzt werden. Die beiden geheimen Schlüssel in der Datei sind nur Entwicklungswerte: In der Produktion müssen sie ersetzt werden (siehe „Ein Produktionsserver“).
11.6.3. config_dev.py
| # =========================================================================
# config_dev.py - ergänzt config.py in der Entwicklung (siehe app.py, das die
# Anwendung mit dem Profil "dev" startet): die von SQLAlchemy
# gesendeten SQL-Anweisungen werden in der Konsole angezeigt.
# =========================================================================
SQL_ECHO = True
|
Das Entwicklungs-Profil: eine zweite Datei, die nach [config.py] gelesen wird und deren Werte die der ersten Datei ersetzen. Es gibt nur einen: die Anzeige der SQL-Befehle. Man könnte auch eine [config_test.py] für Tests schreiben, die eine andere Datenbank verwendet.
11.7. Die Anwendung starten
11.7.1. app.py
| # =========================================================================
# app.py - startet die Anwendung IN DER ENTWICKLUNG: python app.py
#
# Der Flask-Entwicklungsserver (Werkzeug) auf Port 8081, mit:
# - dem Profil "dev" (config_dev.py: die SQL-Anweisungen werden angezeigt);
# - debug=True: die Anwendung startet von selbst neu, sobald eine .py-Datei
# geändert wird, und eine geänderte View wird beim erneuten Laden der Seite neu gelesen.
# In der Produktion wird ein echter WSGI-Server verwendet (siehe README.md: waitress).
# =========================================================================
from rdvmedecins import create_app
if __name__ == "__main__":
create_app(profile="dev").run(port=8081, debug=True)
|
Die Datei, die die Anwendung in der Entwicklung startet: Die Factory [create_app] wird mit dem Profil [dev] aufgerufen, dann wird die Anwendung im Debug-Modus an den Entwicklungsserver auf Port 8081 übergeben. In der Produktion wird diese Datei nicht verwendet: Der WSGI-Server ruft [create_app] auf (siehe „Ein Produktionsserver“).
11.7.2. rdvmedecins/__init__.py
Der Builder der Anwendung. Diese Datei führt alles andere zusammen: Sie ist der „Bauplan“ der Anwendung.
| # =========================================================================
# rdvmedecins/__init__.py
# -------------------------------------------------------------------------
# Die Anwendungs-FACTORY (siehe Beispiel 02): create_app erstellt und
# konfiguriert die Flask-Anwendung. Hier wird alles zusammengesetzt:
# 1. die Konfiguration (config.py, config_dev.py, Variablen FLASK_...);
# 2. der Datenbankzugriff: die Engine und die Session-Factory von SQLAlchemy;
# 3. die gemeinsamen Objekte: DAO -> Geschäftsschicht -> Cache (ApplicationModel),
# Authentifizierung, CAPTCHA, Limiter, Registrierungs-Pässe, Übersetzer -
# das ist Dependency Injection, "von Hand" geschrieben;
# 4. was bei jeder Anfrage läuft: Sprache, Authentifizierung;
# 5. die Blueprints (die Controller), die Fehlerbehandler, der
# Anti-CSRF-Schutz.
#
# Diese Datei macht [rdvmedecins] zu einem Python-PAKET: "from rdvmedecins
# import create_app" führt diese Datei aus.
# =========================================================================
from pathlib import Path
from flask import Flask, g, request
from flask_wtf.csrf import CSRFProtect
from sqlalchemy import URL, create_engine
from sqlalchemy.orm import sessionmaker
from rdvmedecins.auth import security
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.controllers.schedule import schedule
from rdvmedecins.controllers.auth import auth
from rdvmedecins.controllers.clients import clients
from rdvmedecins.controllers.area import area
from rdvmedecins.controllers.registration import registration
from rdvmedecins.controllers.language import language
from rdvmedecins.controllers.doctors import doctors
from rdvmedecins.business.service import BusinessService
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
from rdvmedecins.web import errors, common_model, translator
from rdvmedecins.web.application_model import ApplicationModel
from rdvmedecins.web.translator import Translator
# der Projektordner (der, der config.py enthält), Elternordner dieses Pakets
ROOT = Path(__file__).resolve().parent.parent
def create_app(profile: str | None = None) -> Flask:
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
# ---- 1. die Konfiguration: config.py, dann config_<profile>.py, falls es
# ein Profil gibt, dann die Umgebungsvariablen FLASK_...
app.config.from_pyfile(ROOT / "config.py")
if profile:
app.config.from_pyfile(ROOT / f"config_{profile}.py")
app.config.from_prefixed_env()
app.config.update(
# das Flask-Session-Cookie (Flash-Meldungen, Anti-CSRF-Token)
SESSION_COOKIE_NAME="rdvmedecins_session",
SESSION_COOKIE_SAMESITE="Lax",
SESSION_COOKIE_SECURE=app.config["COOKIE_SECURE"],
# das Anti-CSRF-Token bleibt gültig, solange die Browser-Session dauert
WTF_CSRF_TIME_LIMIT=None,
# eine unbehandelte Exception wird an unsere Fehlerbehandler übergeben
# (Seite 500), auch im Debug-Modus
PROPAGATE_EXCEPTIONS=False,
)
# ---- 2. der Datenbankzugriff. Die SQLAlchemy-Verbindungs-URL
# (mysql+pymysql://root:@localhost:3306/dbrdvmedecins2?charset=utf8mb4),
# von URL.create erstellt: ein Passwort, das Sonderzeichen enthält
# (@, :, / ...), wird darin korrekt kodiert. str(...): eine Variable
# FLASK_DB_PASSWORD=123456 würde als ZAHL gelesen (siehe config.py)
url = URL.create("mysql+pymysql", username=str(app.config["DB_USER"]),
password=str(app.config["DB_PASSWORD"]), host=app.config["DB_HOST"],
port=int(app.config["DB_PORT"]), database=app.config["DB_NAME"],
query={"charset": "utf8mb4"})
# Die Engine verwaltet einen Verbindungs-POOL; pool_pre_ping: eine Verbindung wird
# vor der Wiederverwendung getestet; pool_recycle: sie wird nach
# einer Stunde erneuert (MySQL schließt Verbindungen, die zu lange
# im Leerlauf waren, von selbst)
engine = create_engine(url, echo=app.config["SQL_ECHO"], pool_pre_ping=True,
pool_recycle=3600)
# expire_on_commit=False: die gelesenen Objekte bleiben nach dem Ende
# der Transaktion verwendbar (durch die Views, durch den Cache)
sessions = sessionmaker(engine, expire_on_commit=False)
# ---- 3. die gemeinsamen Objekte, ein für alle Mal erstellt
business = BusinessService(sessions, DoctorRepository(), ClientRepository(),
SlotRepository(), AppointmentRepository(), UserRepository())
# der Cache liest die Ärzte und die Clients: eine nicht erreichbare Datenbank stoppt
# die Anwendung HIER, beim Start
app.extensions["rdvmedecins.application"] = ApplicationModel(business)
auth_service = AuthService(sessions, UserRepository(), app.config["JWT_SECRET"],
app.config["JWT_EXPIRES_IN_SECONDS"], app.config["COOKIE_SECURE"])
app.extensions["rdvmedecins.auth"] = auth_service
app.extensions["rdvmedecins.captchas"] = CaptchaService()
app.extensions["rdvmedecins.limiter"] = AttemptLimiter(
app.config["LOGIN_MAX_FAILURES"], app.config["LOGIN_BLOCK_MINUTES"],
app.config["REGISTRATION_MAX_PER_HOUR"])
app.extensions["rdvmedecins.passes"] = RegistrationPass()
trans = Translator(Path(app.root_path) / "i18n")
# ---- 4. bei jeder Anfrage, in der Reihenfolge der Registrierung:
# die Sprache (Cookie rdvmedecins_language, sonst Englisch) ...
@app.before_request
def set_language():
g.language = translator.language(request.cookies.get(translator.LANGUAGE_COOKIE))
# ... dann der Benutzer und die Zugriffsregel (siehe auth/security.py)
security.register(app, auth_service)
# die allen Views gemeinsamen Variablen
common_model.register(app, trans)
# ---- 5. die Controller, die Fehlerseiten, der Anti-CSRF-Schutz
for blueprint in (auth, language, schedule, doctors, clients, registration, area):
app.register_blueprint(blueprint)
errors.register(app)
# jede POST-Anfrage muss das Anti-CSRF-Token der Seite zurücksenden
# (verstecktes Feld csrf_token): andernfalls Antwort 400
CSRFProtect(app)
return app
|
- Zeile 48: der Projektordner, der [config.py] enthält: der übergeordnete Ordner ([parent.parent]) des Ordners dieser Datei;
- Zeilen 52–54: die Anwendung; [__name__] entspricht hier [rdvmedecins], dem Paketnamen: [Flask] sucht die Ordner [templates] und [static] daher im Paketordner;
- Zeilen 58–61: die Konfiguration in drei Schritten: die Datei [config.py], die Profildatei (falls vorhanden) und die Umgebungsvariablen. Jede Quelle überschreibt die Werte der vorherigen;
- Zeilen 62–71: einige Einstellungen für [Flask] und [Flask-WTF], die hier statt in [config.py] stehen, weil sie nicht zur Änderung vorgesehen sind. [SESSION_COOKIE_NAME] benennt das Sitzungs-Cookie um (Standard: [session]), damit es nicht mit dem einer anderen, über [localhost] ausgelieferten Anwendung kollidiert, wie in den Beispielen gezeigt; [SESSION_COOKIE_SAMESITE] und [SESSION_COOKIE_SECURE] weisen ihm die Attribute [SameSite=Lax] und, in der Produktion, [Secure] zu (Beispiel 25). [WTF_CSRF_TIME_LIMIT=None]: Standardmäßig ist ein Anti-CSRF-Token nur eine Stunde lang gültig, und ein länger geöffnetes Formular würde abgelehnt; hier bleibt es für die Dauer der Browsersitzung gültig. [PROPAGATE_EXCEPTIONS=False]: Im Debug-Modus lässt [Flask] bestimmte Ausnahmen bis zur Debug-Seite weiterlaufen; diese Einstellung stellt sicher, dass sie unsere Fehlerbehandler durchlaufen;
- Zeilen 79–82: die Verbindungs-URL für [SQLAlchemy] (Beispiel 28), erzeugt von [URL.create] aus ihren Bestandteilen. Bei handgeschriebenen URLs sollten die Sonderzeichen eines Passworts kodiert werden ([@], [:], [/] ...), die innerhalb einer URL eine eigene Bedeutung haben; [URL.create] erledigt dies von selbst. [str(...)] und [int(...)] schützen vor Typumwandlungen bei Umgebungsvariablen: [FLASK_DB_PASSWORD=123456] würde als Zahl interpretiert;
- Zeilen 87–88: die Engine und ihr Verbindungspool. [pool_recycle=3600] erneuert eine Verbindung nach einer Stunde; [MySQL] schließt zu lange inaktive Verbindungen automatisch (standardmäßig nach acht Stunden);
- Zeile 91: die Session-Factory (Beispiel 28);
- Zeilen 94–106: gemeinsame Objekte, einmalig erstellt und in [app.extensions] abgelegt (Beispiel 06). Dies ist Dependency Injection, von Hand geschrieben: Jedes Objekt erhält die Objekte, die es benötigt, in seinem Konstruktor. Die Geschäftsschicht erhält die Session-Factory und die fünf Klassen der DAO-Schicht; der [ApplicationModel]-Cache erhält die Geschäftsschicht; der Authentifizierungsservice erhält die Session-Factory, die DAO-Klasse für Benutzer und die Token-Konfiguration. Die Schlüssel in [app.extensions] tragen das Präfix [rdvmedecins.] , um Konflikte mit denen der Erweiterungen zu vermeiden ([Flask-WTF] legt dort ebenfalls seine Objekte ab). Der Konstruktor von [ApplicationModel] liest die Liste der Ärzte und Clients: Ist die Datenbank nicht erreichbar, bricht die Anwendung hier beim Start ab, statt erst bei der ersten Anfrage;
- Zeile 107: der Übersetzungsservice (Beispiel 22);
- Zeilen 111–113: Die erste Funktion, [before_request], ermittelt die Sprache der Anfrage aus dem Cookie [rdvmedecins_language];
- Zeile 116: die zweite Variable: der Benutzer der Anfrage und die Zugriffsregel (siehe [auth/security.py]). Die Reihenfolge ist wichtig: Die Anmeldeseite, auf die ein nicht autorisierter Besucher umgeleitet wird, muss die Sprache kennen;
- Zeile 118: die für alle Views gemeinsamen Variablen (der Context Processor aus Beispiel 15, siehe [web/common_model.py]);
- Zeilen 121–122: die sieben Blueprints der Anwendung;
- Zeile 123: die Fehlerbehandler (siehe [web/errors.py]);
- Zeile 126: CSRF-Schutz für alle Anfragen (POST, Beispiel 21).
Diese Datei entspricht der Startklasse und den Konfigurationsklassen einer [Spring Boot]-Anwendung sowie der Datei [Program.cs] einer [ASP.NET Core]-Anwendung. Der Hauptunterschied: [Flask] erstellt oder injiziert nichts von selbst. Alles, was in der Anwendung existiert, wurde hier explizit erstellt, und Sie können jedes Objekt von seiner Erstellung bis zu seiner Verwendung verfolgen.
11.8. Entitäten
Der Ordner [entities] enthält eine Klasse pro Tabelle: die Entitäten, die [SQLAlchemy] aus der Datenbank liest und in sie schreibt (Beispiel 28). Ihre Attribute sind nach den Spalten benannt, sofern nicht anders angegeben.
11.8.1. entities/base.py
| # =========================================================================
# entities/base.py
# -------------------------------------------------------------------------
# Die Elternklasse aller Entitäten und die beiden Spalten, die allen
# Tabellen gemeinsam sind: der Bezeichner [id] und die Versionsnummer [version].
#
# "Deklaratives" SQLAlchemy: jede Kindklasse von Base beschreibt eine Tabelle
# (__tablename__), jedes Attribut Mapped[...] eine Spalte. SQLAlchemy liest
# diese Deklarationen beim Start, um zu wissen, welche Klasse zu welcher
# Tabelle und welches Attribut zu welcher Spalte gehört.
# =========================================================================
from sqlalchemy.orm import DeclarativeBase, Mapped, declared_attr, mapped_column
class Base(DeclarativeBase):
pass
# ein MIXIN: eine Klasse ohne Tabelle, deren Spalten zu denen der
# Klassen hinzugefügt werden, die von ihr erben (Doctor, Client, Slot, Appointment, User)
class WithIdAndVersion:
# der Primärschlüssel, von der Datenbank erzeugt (Spalte AUTO_INCREMENT):
# SQLAlchemy liest seinen Wert nach jedem INSERT zurück. Eine noch nicht
# gespeicherte Entität hat die id None.
id: Mapped[int] = mapped_column(primary_key=True)
# das optimistische Sperren. Jedes von SQLAlchemy gesendete UPDATE trägt die
# Bedingung "WHERE id = ... AND version = <gelesener Wert>" und schreibt die
# um 1 erhöhte Version. Hat jemand die Zeile in der Zwischenzeit geändert,
# wird keine Zeile aktualisiert: SQLAlchemy löst einen StaleDataError aus
# (siehe business/service.py).
version: Mapped[int] = mapped_column()
# @declared_attr: ein Attribut, das für JEDE Kindklasse berechnet wird;
# version_id_col: die Spalte, die als optimistische Sperre dient
@declared_attr.directive
def __mapper_args__(cls):
return {"version_id_col": cls.version}
|
- Zeilen 15–16: die Elternklasse aller Entitäten (Beispiel 28);
- Zeilen 21–39: die beiden allen Tabellen gemeinsamen Spalten, [id] und [version], nur einmal definiert. [WithIdAndVersion] ist ein Mixin: eine Klasse, die keine Tabelle hat und nie für sich allein erzeugt wird, von der aber Kindklassen Spalten erben. Eine Entität erbt somit von zwei Klassen: [class User(WithIdAndVersion, Base)] (Mehrfachvererbung in [Python]);
- Zeilen 37–39: das optimistische Sperren (Beispiel 28). [__mapper_args__] muss auf die Spalte [version] jeder Kindklasse verweisen, nicht auf die des Mixins: Der Dekorator [@declared_attr.directive] macht diese Methode zu einem berechneten Attribut für jede Klasse, die vom Mixin erbt. [SQLAlchemy] ruft sie beim Parsen der Kindklasse auf und übergibt die Kindklasse als Parameter ([cls]).
11.8.2. entities/role.py
| # =========================================================================
# entities/role.py
# -------------------------------------------------------------------------
# Die drei Rollen eines Benutzers (Spalte users.role):
# - ADMIN : der Administrator - Termine + Verwaltung von Ärzten und Clients;
# - DOCTOR : ein Arzt - bucht und storniert Termine;
# - USER : ein Client (Patient) - bucht für sich selbst, verwaltet sein Konto.
#
# Eine Aufzählung (Enum): kein anderer Wert ist möglich. StrEnum: ihre
# Werte sind zugleich Strings ("ADMIN"), unverändert in der Datenbank gespeichert,
# so wie es das SQL-Skript tut (siehe user.py).
# =========================================================================
from enum import StrEnum
class Role(StrEnum):
ADMIN = "ADMIN"
DOCTOR = "DOCTOR"
USER = "USER"
|
Eine Aufzählung: ein Typ, dessen mögliche Werte ein für alle Mal feststehen ([Role.ADMIN], [Role.DOCTOR], [Role.USER]). [StrEnum] (Standardmodul [enum], [Python] 3.11): Jeder Wert ist zugleich eine Zeichenkette, gleich ["ADMIN"] usw. Er kann daher mit einer Zeichenkette verglichen, in ein JWT-Token geschrieben oder ohne Umwandlung in eine Seite eingefügt werden.
11.8.3. entities/user.py
| # =========================================================================
# entities/user.py
# -------------------------------------------------------------------------
# Ein Benutzer, der sich an der Anwendung anmelden darf (Tabelle [users]).
# Jeder Arzt und jeder Client hat SEIN Benutzerkonto (Spalte
# [user] der Tabellen [doctors] und [clients], siehe person.py).
#
# SQL-Eindeutigkeitsbedingung: unq_users_login (ein Login gehört nur zu einem
# Konto). Sie wird vom Skript database/dbrdvmedecins2.sql angelegt;
# die Geschäftsschicht erkennt sie an ihrem NAMEN (siehe business/service.py).
# =========================================================================
from sqlalchemy import Enum, String
from sqlalchemy.orm import Mapped, mapped_column
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.role import Role
class User(WithIdAndVersion, Base):
__tablename__ = "users"
login: Mapped[str] = mapped_column(String(30))
# das GEHASHTE Passwort (bcrypt) - niemals im Klartext
password: Mapped[str] = mapped_column(String(100))
# der nach der Anmeldung angezeigte Name - bei einem Arzt oder einem Client:
# "Vorname NACHNAME" (z. B.: "Marie PELISSIER")
name: Mapped[str] = mapped_column(String(40))
# ADMIN, DOCTOR oder USER, in der Datenbank als Text gespeichert.
# native_enum=False: eine einfache VARCHAR-Spalte (und nicht der MySQL-Typ ENUM)
role: Mapped[Role] = mapped_column(Enum(Role, native_enum=False, length=10))
|
- Zeile 19: Die Entität erbt ID und Version vom Mixin sowie von [Base];
- Zeile 24: das Passwort als Hash;
- Zeile 30: ein Attribut vom Typ [Role]. Der Typ [Enum] von [SQLAlchemy] wandelt die Aufzählung beim Schreiben in Text um (["ADMIN"]) und beim Lesen den Text in eine Aufzählung. [native_enum=False]: Die Spalte ist ein einfaches [VARCHAR], wie im SQL-Skript, und nicht der für [ENUM]-Typ spezifische [MySQL].
11.8.4. entities/person.py
| # =========================================================================
# entities/person.py
# -------------------------------------------------------------------------
# Die Ärzte (Tabelle [doctors]) und die Clients (Tabelle [clients]): eine
# Anrede, ein Nachname, ein Vorname - und das zugehörige Benutzerkonto (Spalte [user]).
#
# Die beiden Tabellen haben genau dieselben Spalten: sie werden
# EINMAL im Mixin Person beschrieben, von dem Doctor und Client erben. Eine
# in einem Mixin deklarierte Relationship muss durch eine Methode mit @declared_attr deklariert werden:
# SQLAlchemy ruft sie für jede Kindklasse auf, die so IHRE Relationship erhält.
#
# Achtung: [Client] bezeichnet hier einen PATIENTEN der Arztpraxis, keinen
# HTTP-Client! Es ist das Vokabular der ursprünglichen Fachdomäne, unverändert
# beibehalten (Tabelle [clients]).
#
# SQL-Eindeutigkeitsbedingungen: unq_doctors_first_name_last_name, unq_clients_first_name_last_name
# (zwei Ärzte oder zwei Clients dürfen nicht denselben Vor- und
# Nachnamen haben) - vom SQL-Skript angelegt, in der Geschäftsschicht an ihrem Namen erkannt.
# =========================================================================
from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import Mapped, declared_attr, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.user import User
class Person(WithIdAndVersion):
title: Mapped[str] = mapped_column(String(5)) # Melle, Mme, Mr
last_name: Mapped[str] = mapped_column(String(20))
first_name: Mapped[str] = mapped_column(String(20))
# der Fremdschlüssel auf users(id), als einfache Zahl gelesen: so kennen wir
# die id des Kontos, ohne den User zu laden. "user" ist der Name der
# Spalte (ein SQL-Schlüsselwort, das SQLAlchemy selbst in
# Backticks `user` einfasst, wenn das DBMS es verlangt); user_id der des Python-Attributs
@declared_attr
def user_id(cls) -> Mapped[int]:
return mapped_column("user", ForeignKey("users.id"))
# -----------------------------------------------------------------------
# Die Relationship zum Benutzerkonto: ein Arzt (ein Client) hat EIN
# Konto. relationship: das Attribut [user] ist ein User-Objekt und keine
# Zahl. SQLAlchemy liest es nur dann aus der Datenbank, wenn man es verlangt: in der
# Abfrage (Optionen joinedload, siehe repositories/) oder beim ersten Zugriff auf
# das Attribut, solange die Session offen ist.
# -----------------------------------------------------------------------
@declared_attr
def user(cls) -> Mapped[User]:
return relationship()
class Doctor(Person, Base):
__tablename__ = "doctors"
class Client(Person, Base):
__tablename__ = "clients"
|
- Zeile 27: Da die Tabellen [doctors] und [clients] exakt dieselben Spalten haben, werden sie einmal im Mixin [Person] beschrieben, das seinerseits vom Mixin [WithIdAndVersion] erbt;
- Zeilen 29–31: die regulären Spalten, deklariert wie in Beispiel 28;
- Zeilen 9–39: der Fremdschlüssel auf das Benutzerkonto. In einem Mixin muss eine Spalte, die als Fremdschlüssel dient, mit der Methode [@declared_attr] deklariert werden: So erhält jede Kindklasse ihre eigene Spalte. [ForeignKey("users.id")] gibt die referenzierte Spalte an; der erste Parameter von [mapped_column] ist der Name der Spalte in der Tabelle ([user]), der sich vom Namen des [Python]-Attributs ([user_id]) unterscheidet;
- Zeilen 37–50: die Relation zum Konto: Das Attribut [user] ist ein Objekt [User], keine Zahl. [SQLAlchemy] leitet den Join über den Fremdschlüssel ab. Eine Relation ist keine Spalte: Sie ist ein Mittel, um das verknüpfte Objekt zu erhalten. Standardmäßig liest [SQLAlchemy] sie erst beim ersten Zugriff auf das Attribut aus der Datenbank (Lazy Loading), was voraussetzt, dass die Session noch geöffnet ist;
- Zeilen 53–58: zwei Entitäten, die sich nur in ihrer Tabelle unterscheiden.
Beachten Sie die Terminologie: Ein [Client] bezeichnet hier einen Patienten der Arztpraxis, nicht einen HTTP-Client. Dies ist die Terminologie der ursprünglichen Anwendung, unverändert übernommen.
11.8.5. entities/slot.py
| # =========================================================================
# entities/slot.py
# -------------------------------------------------------------------------
# Ein Zeitfenster eines Arztes (Tabelle [slots]): 8:00 - 8:20 usw.
# =========================================================================
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.person import Doctor
class Slot(WithIdAndVersion, Base):
__tablename__ = "slots"
start_hour: Mapped[int] # Startstunde des Zeitfensters
start_minute: Mapped[int] # Startminute des Zeitfensters
end_hour: Mapped[int] # Endstunde des Zeitfensters
end_minute: Mapped[int] # Endminute des Zeitfensters
# mehrere Zeitfenster für denselben Arzt: der Fremdschlüssel [doctor_id]
# (eine Zahl) und die Relationship [doctor] (das Doctor-Objekt)
doctor_id: Mapped[int] = mapped_column(ForeignKey("doctors.id"))
doctor: Mapped[Doctor] = relationship()
|
Ein Terminzeitfenster und sein Arzt: der Fremdschlüssel [doctor_id] (eine Zahl) und die Relation [doctor] (das Objekt). Ohne Mixin wird die Relation direkt als Attribut deklariert.
11.8.6. entities/appointment.py
| # =========================================================================
# entities/appointment.py
# -------------------------------------------------------------------------
# Ein Termin (Tabelle [appointments]): ein Client, in einem Zeitfenster, an einem bestimmten Tag.
#
# SQL-Eindeutigkeitsbedingung: unq1_appointments (day, slot_id) - ein Zeitfenster wird
# pro Tag nur einmal gebucht. Vom SQL-Skript angelegt, in der Geschäftsschicht an seinem
# Namen erkannt.
# =========================================================================
from datetime import date
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client
class Appointment(WithIdAndVersion, Base):
__tablename__ = "appointments"
# date: ein Datum OHNE Uhrzeit, das genau dem SQL-Typ DATE
# der Spalte [day] entspricht
day: Mapped[date]
client_id: Mapped[int] = mapped_column(ForeignKey("clients.id"))
client: Mapped[Client] = relationship()
slot_id: Mapped[int] = mapped_column(ForeignKey("slots.id"))
slot: Mapped[Slot] = relationship()
|
- Zeile 25: Der Typ [date] von [Python], ein Datum ohne Uhrzeit, entspricht exakt dem SQL-Typ [DATE];
- Zeilen 27–31: die beiden Fremdschlüssel und ihre Relationen.
11.8.7. entities/__init__.py
| # =========================================================================
# entities/ - die ENTITÄTEN: eine Klasse pro Tabelle der Datenbank dbrdvmedecins2.
# Diese Datei bündelt die Importe: "from rdvmedecins.entities import
# Doctor" genügt an allen anderen Stellen der Anwendung.
# =========================================================================
from rdvmedecins.entities.base import Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client, Doctor, Person
from rdvmedecins.entities.role import Role
from rdvmedecins.entities.appointment import Appointment
from rdvmedecins.entities.user import User
__all__ = ["Base", "Client", "Slot", "Doctor", "Person", "Role", "Appointment", "User"]
|
Die Datei [__init__.py] eines Pakets wird ausgeführt, wenn das Paket importiert wird. Diese Datei importiert die Entitäten aus ihren jeweiligen Modulen; anderswo genügt [from rdvmedecins.entities import Doctor] , ohne wissen zu müssen, in welchem Modul die Klasse definiert ist. Die Liste [__all__] deklariert die vom Paket bereitgestellten Namen.
11.9. SQLAlchemy: Sessions und das Laden von Relationen
Beispiel 28 hat die Grundlagen von [SQLAlchemy] behandelt. Die Fallstudie verwendet zwei weitere, miteinander verbundene Aspekte.
Die Lebensdauer gelesener Objekte. Jede Methode der Geschäftsschicht öffnet eine Session und eine Transaktion und schließt sie beim Verlassen. Die von ihr zurückgegebenen Entitäten sind dann losgelöst (detached): Sie sind keiner Session mehr zugeordnet. Dank der Einstellung [expire_on_commit=False] bleiben ihre regulären Attribute lesbar. Eine Relation, die nicht geladen wurde, kann jedoch nicht mehr geladen werden: Dazu wäre eine Datenbankabfrage nötig, und es gibt keine Session mehr. Der Zugriff auf das Attribut löst dann eine [DetachedInstanceError]-Ausnahme aus. Dieses Problem löst [Spring Boot] zusammen mit [Hibernate] über die Einstellung [open-in-view] (eine Session, die für die Dauer der Anfrage offen ist), die die [Spring MVC]-Version der Fallstudie aus demselben Grund wie wir deaktiviert hat: Eine View sollte keine SQL-Anfragen auslösen. Die Regel lautet daher: Jede Methode der DAO-Schicht lädt explizit die Relationen, die der Aufrufer benötigt.
Ladeoptionen. [SQLAlchemy] bietet mehrere Möglichkeiten, eine Relation zusammen mit der Entität zu laden:
- [joinedload(Doctor.user)]: Fügt der Abfrage einen Join ([LEFT OUTER JOIN users ...]) hinzu, dessen Spalten zum Erstellen der [User]-Objekte verwendet werden. Eine einzige Abfrage liefert die Ärzte und ihre Konten;
- [contains_eager(Appointment.slot)]: Wenn die Abfrage bereits einen Join enthält ([select(Appointment).join(Appointment.slot)], geschrieben, um nach einer Spalte der verknüpften Tabelle zu filtern), weist diese Option [SQLAlchemy] an, die Spalten dieses Joins zum Befüllen der Relation zu verwenden, statt einen zweiten hinzuzufügen;
- Die Optionen werden verkettet, um eine Relation von einer anderen Relation aus zu laden: [contains_eager(Appointment.slot).joinedload(Slot.doctor)] lädt das Zeitfenster jedes Termins und dann den Arzt jedes Zeitfensters.
Dies sind die Entsprechungen von [JOIN FETCH] bei [JPA] und von [Include] bei [Entity Framework Core].
11.10. Die Domäne: der Kalender
11.10.1. domain/schedule.py
| # =========================================================================
# domain/schedule.py
# -------------------------------------------------------------------------
# Berechnete "fachliche" Objekte, die keiner Tabelle entsprechen:
# - DoctorDaySlot: ein Zeitfenster und der Termin, der an einem bestimmten Tag
# möglicherweise in diesem Zeitfenster gebucht ist (None, wenn das Zeitfenster frei ist);
# - DoctorDaySchedule: der vollständige Terminkalender eines Arztes für einen bestimmten Tag,
# die Liste seiner Zeitfenster, jedes frei oder gebucht. Berechnet von
# BusinessService.get_doctor_day_schedule, von
# controllers/schedule.py in eine HTML-Tabelle umgewandelt.
#
# frozen=True: unveränderliche Objekte, deren Felder ein für alle Mal
# vom Konstruktor gesetzt werden - genau das, was für ein
# berechnetes Objekt nötig ist, das danach niemand mehr ändert.
# =========================================================================
from dataclasses import dataclass
from datetime import date
from rdvmedecins.entities import Slot, Doctor, Appointment
@dataclass(frozen=True)
class DoctorDaySlot:
slot: Slot
appointment: Appointment | None
@dataclass(frozen=True)
class DoctorDaySchedule:
doctor: Doctor
day: date
doctor_day_slots: list[DoctorDaySlot]
|
Zwei Klassen, die keiner Tabelle entsprechen: der Terminkalender eines Arztes für einen einzelnen Tag, berechnet von der Geschäftsschicht. [DoctorDaySlot] ordnet einem Zeitfenster den für dieses Zeitfenster an diesem Tag gebuchten Termin zu, oder [None] , wenn es frei ist; [DoctorDaySchedule] vereint den Arzt, den Tag und die Liste der Zeitfenster des Arztes. Dies sind unveränderliche [dataclass]-Objekte ([frozen=True]): ein berechnetes Objekt, das danach niemand mehr ändert.
11.11. Die DAO-Schicht
Der Ordner [repositories] (die im Englischen übliche Bezeichnung für DAO-Klassen, „Repositories“) enthält eine Klasse pro Entität. Wie in Beispiel 28 erhält jede Methode die von der Geschäftsschicht geöffnete Session und enthält keine Geschäftslogik.
11.11.1. repositories/person_repository.py
| # =========================================================================
# repositories/person_repository.py
# -------------------------------------------------------------------------
# Die DAO-Schicht, die Ärzte und Clients gemeinsam haben.
#
# Jede Methode erhält die SQLAlchemy-SESSION, die von der Geschäfts-
# schicht geöffnet wurde (siehe business/service.py): alle Abfragen derselben Operation
# verwenden so dieselbe Verbindung und dieselbe TRANSAKTION.
#
# Die Abfragen werden mit den SQLAlchemy-Objekten geschrieben (select, where,
# order_by ...), die auf die KLASSEN und ihre Attribute angewendet werden; SQLAlchemy
# übersetzt sie in SQL. Die Werte (first_name, last_name ...) werden zu PARAMETERN
# der Abfrage: keine String-Verkettung, also keine SQL-Injection.
#
# Die DAOs der Ärzte und der Clients wären identisch: diese
# GENERISCHE Klasse schreibt sie nur einmal. [T: Person]: ein Typparameter,
# der Doctor oder Client ist; self.entity ist die entsprechende Klasse.
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Person
class PersonRepository[T: Person]:
def __init__(self, entity: type[T]):
self.entity = entity
# nach Nachname, dann Vorname sortierte Liste, Benutzerkonto eingeschlossen.
# joinedload(user): bringt AUCH das Konto mit, über einen Join
# (SELECT ... FROM doctors LEFT OUTER JOIN users ...). Ohne ihn würde das
# Konto erst beim ersten Zugriff gelesen - unmöglich, sobald die Session
# geschlossen ist: diese Listen werden vom Cache im Speicher gehalten
# (web/application_model.py), lange nach dem Ende der Anfrage.
def list(self, session: Session) -> list[T]:
e = self.entity
query = select(e).options(joinedload(e.user)).order_by(e.last_name, e.first_name)
return list(session.scalars(query))
# eine Person und ihr Konto; None, wenn sie nicht existiert
def read(self, session: Session, id: int) -> T | None:
return session.get(self.entity, id, options=[joinedload(self.entity.user)])
# die Person, deren Benutzerkonto [user_id] ist
def read_by_user(self, session: Session, user_id: int) -> T | None:
e = self.entity
query = select(e).options(joinedload(e.user)).where(e.user_id == user_id)
return session.scalars(query).first()
# die Person mit diesem Vor- und Nachnamen, falls es eine gibt. Der Vergleich
# wird von MySQL durchgeführt, also mit der Kollation der Datenbank
# (utf8mb4_unicode_ci: ohne Beachtung von Groß-/Kleinschreibung und Akzenten) -
# genau dieselbe Regel wie die der SQL-Eindeutigkeitsbedingung.
def namesake(self, session: Session, first_name: str, last_name: str) -> T | None:
e = self.entity
return session.scalars(select(e).where(e.first_name == first_name, e.last_name == last_name).limit(1)).first()
def add(self, session: Session, person: T) -> T:
session.add(person)
return person
# ein direkt an die Datenbank gesendetes DELETE, ohne die Person vorher zu lesen
def remove(self, session: Session, id: int):
session.execute(delete(self.entity).where(self.entity.id == id))
|
- Zeile 25: eine generische Klasse, geschrieben in der [Python]-3.12-Syntax (PEP 695). [T] ist ein Typparameter: Die Klasse wird als [PersonRepository[Doctor]] oder [PersonRepository[Client]] verwendet. [T: Person] beschränkt [T] auf Klassen, die von [Person] erben. Typen werden von [Python] zur Laufzeit nicht geprüft (Beispiel 06): Sie dokumentieren den Code und lassen den Editor wissen, dass [list()] beim DAO der Ärzte eine Liste von [Doctor] zurückgibt. Vor [Python] 3.12 hätte man [T = TypeVar("T", bound=Person)] gefolgt von [class PersonRepository(Generic[T])] geschrieben;
- Zeilen 27–28: Der Typparameter existiert zur Laufzeit nicht: Die tatsächliche Klasse ([Doctor] oder [Client]) wird daher dem Konstruktor übergeben und in [self.entity] gespeichert. [type[T]] ist der Typ einer Klasse (nicht eines Objekts);
- Zeilen 36–39: die sortierte Liste mit der Anzahl für jede Person, über einen Join geladen ([joinedload]). Das ist hier unverzichtbar: Diese Listen werden vom Cache [ApplicationModel]lange nach dem Ende der Session im Arbeitsspeicher gehalten;
- Zeilen 42–43: Das Lesen über den Primärschlüssel akzeptiert ebenfalls Ladeoptionen;
- Zeilen 46–49: die einem Konto zugeordnete Person – so identifizieren wir den angemeldeten Client;
- Zeilen 55–57: die Suche nach einem Namensvetter. Der Vergleich wird von [MySQL] mit der Kollation der Datenbank durchgeführt: Das ist exakt die Regel der Eindeutigkeitsbedingung;
- Zeilen 59–61: das Hinzufügen, ohne [flush]: Die Geschäftsschicht entscheidet, wann die SQL-Befehle gesendet werden;
- Zeilen 64–65: ein direkt an die Datenbank gesendetes [DELETE].
11.11.2. repositories/doctor_repository.py
| # =========================================================================
# repositories/doctor_repository.py
# -------------------------------------------------------------------------
# Das DAO der Ärzte: alles wird von PersonRepository geerbt.
# =========================================================================
from rdvmedecins.entities import Doctor
from rdvmedecins.repositories.person_repository import PersonRepository
class DoctorRepository(PersonRepository[Doctor]):
def __init__(self):
super().__init__(Doctor)
|
Die DAO-Klasse für Ärzte erbt von [PersonRepository[Doctor]] und übergibt die Klasse [Doctor] an den Konstruktor ihrer Elternklasse; alles Übrige wird geerbt.
11.11.3. repositories/client_repository.py
| # =========================================================================
# repositories/client_repository.py
# -------------------------------------------------------------------------
# Das DAO der Clients: das der Personen, plus eine Sperrmethode.
# =========================================================================
from sqlalchemy import select
from sqlalchemy.orm import Session
from rdvmedecins.entities import Client
from rdvmedecins.repositories.person_repository import PersonRepository
class ClientRepository(PersonRepository[Client]):
def __init__(self):
super().__init__(Client)
# -----------------------------------------------------------------------
# setzt einen LOCK auf die Zeile eines Clients bis zum Ende der
# aktuellen Transaktion (SELECT ... FOR UPDATE) und gibt seine id zurück (None,
# wenn der Client nicht existiert). Eine zweite Transaktion, die denselben
# Lock verlangt, WARTET, bis die erste beendet ist.
# Wird für die Buchung eines Termins verwendet (siehe BusinessService.add_appointment):
# zwei gleichzeitige Buchungen für denselben Patienten werden so
# nacheinander verarbeitet, und die zweite sieht den von der ersten angelegten Termin.
# with_for_update: fügt der Abfrage "FOR UPDATE" hinzu.
# -----------------------------------------------------------------------
def lock(self, session: Session, id: int) -> int | None:
return session.scalars(select(Client.id).where(Client.id == id).with_for_update()).first()
|
- Zeilen 28–29: eine weitere Methode, die eine Sperre auf den Datensatz eines Clients setzt: [with_for_update()] fügt der Abfrage [FOR UPDATE] hinzu ([SELECT clients.id FROM clients WHERE clients.id = ? FOR UPDATE]). Bis zum Ende der Transaktion wartet jede andere Transaktion, die dieselbe Sperre anfordert. Die Geschäftsschicht nutzt dies für die Terminvergabe: Zwei gleichzeitige Termine für denselben Patienten werden so nacheinander verarbeitet, und der zweite Termin sieht den vom ersten erstellten Termin (Regel: nur ein künftiger Termin pro Patient). Dieses pessimistische Sperren ergänzt das optimistische: Das optimistische Sperren erkennt eine gleichzeitige Änderung einer Zeile, während das pessimistische verhindert, dass zwei Transaktionen gleichzeitig eine Entscheidung auf Grundlage derselben Daten treffen.
11.11.4. repositories/slot_repository.py
| # =========================================================================
# repositories/slot_repository.py
# -------------------------------------------------------------------------
# DAO-Schicht der Entität [Slot].
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Slot
class SlotRepository:
# ein Zeitfenster und sein Arzt
def read(self, session: Session, id: int) -> Slot | None:
return session.get(Slot, id, options=[joinedload(Slot.doctor)])
# die Zeitfenster eines Arztes in chronologischer Reihenfolge
def list_by_doctor(self, session: Session, doctor_id: int) -> list[Slot]:
query = (select(Slot).where(Slot.doctor_id == doctor_id)
.order_by(Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# löscht alle Zeitfenster eines Arztes (Löschen eines Arztes):
# DELETE FROM slots WHERE doctor_id = ?
def delete_by_doctor(self, session: Session, doctor_id: int):
session.execute(delete(Slot).where(Slot.doctor_id == doctor_id))
|
Ein Terminzeitfenster (mit einem Arzt), die Zeitfenster eines Arztes in chronologischer Reihenfolge und das Löschen der Zeitfenster eines Arztes (wenn der Arzt entfernt wird).
11.11.5. repositories/appointment_repository.py
| # =========================================================================
# repositories/appointment_repository.py
# -------------------------------------------------------------------------
# DAO-Schicht der Entität [Appointment].
#
# join(Appointment.slot): ein SQL-Join, geschrieben aus der RELATIONSHIP zwischen
# den beiden Klassen (SQLAlchemy kennt den Fremdschlüssel). contains_eager:
# die Spalten der verknüpften Tabelle dienen AUCH dazu, die Relationship zu füllen
# (appointment.slot), ohne neue Abfrage.
# =========================================================================
from datetime import date
from sqlalchemy import delete, func, select
from sqlalchemy.orm import Session, contains_eager, joinedload
from rdvmedecins.entities import Slot, Appointment
class AppointmentRepository:
# ein Termin, sein Client und sein Zeitfenster
def read(self, session: Session, id: int) -> Appointment | None:
return session.get(Appointment, id, options=[joinedload(Appointment.client), joinedload(Appointment.slot)])
# die Termine eines Arztes an einem bestimmten Tag, Client und Zeitfenster eingeschlossen.
# Die Tabelle [appointments] verweist nicht direkt auf den Arzt: wir gehen über das Zeitfenster.
def doctor_day_appointments(self, session: Session, doctor_id: int, day: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot), joinedload(Appointment.client))
.where(Slot.doctor_id == doctor_id, Appointment.day == day))
return list(session.scalars(query))
# die Termine eines Clients ab dem Tag [since] (eingeschlossen), in
# chronologischer Reihenfolge, mit dem Zeitfenster UND dem Arzt dieses Zeitfensters
def client_upcoming_appointments(self, session: Session, client_id: int, since: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot).joinedload(Slot.doctor))
.where(Appointment.client_id == client_id, Appointment.day >= since)
.order_by(Appointment.day, Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# Anzahl der Termine eines Clients ab dem Tag [since] (eingeschlossen)
def count_client_upcoming(self, session: Session, client_id: int, since: date) -> int:
query = select(func.count(Appointment.id)).where(Appointment.client_id == client_id, Appointment.day >= since)
return session.scalar(query)
# Anzahl der (vergangenen oder künftigen) Termine eines Arztes
def count_by_doctor(self, session: Session, doctor_id: int) -> int:
query = select(func.count(Appointment.id)).join(Appointment.slot).where(Slot.doctor_id == doctor_id)
return session.scalar(query)
def add(self, session: Session, appointment: Appointment) -> Appointment:
session.add(appointment)
return appointment
# löscht einen Termin: DELETE FROM appointments WHERE id = ?
def remove(self, session: Session, id: int):
session.execute(delete(Appointment).where(Appointment.id == id))
# löscht ALLE Termine (vergangene und künftige) eines Clients
def delete_by_client(self, session: Session, client_id: int):
session.execute(delete(Appointment).where(Appointment.client_id == client_id))
|
- Zeilen 27–31: die Termine eines Arztes an einem bestimmten Tag. Die Tabelle [appointments] verweist nicht direkt auf den Arzt: Sie läuft über das Terminzeitfenster. [join(Appointment.slot)] schreibt den Join auf Grundlage der Relation; der Filter bezieht sich auf eine Spalte der verknüpften Tabelle ([Slot.doctor_id]). [contains_eager] verwendet den Join wieder, um [appointment.slot] zu befüllen; [joinedload] lädt den Client: Der Terminkalender wird in einer einzigen SQL-Abfrage aufgebaut;
- Zeilen 35–39: die künftigen Termine eines Clients mit ihren Zeitfenstern und dem jedem Zeitfenster zugeordneten Arzt;
- Zeilen 43–45: [func.count] erzeugt die SQL-Funktion [COUNT], und [session.scalar] (im Singular); [session.scalar] gibt die erste Spalte der ersten Zeile zurück: die Anzahl;
- Zeilen 48–50: die Anzahl der Termine eines Arztes, um festzustellen, ob der Arzt gelöscht werden kann;
- Zeilen 61–62: das Löschen der Termine eines Clients (wenn der Client gelöscht wird).
11.11.6. repositories/user_repository.py
| # =========================================================================
# repositories/user_repository.py
# -------------------------------------------------------------------------
# DAO-Schicht der Entität [User]. Das Anlegen (oder Löschen) eines Arztes oder eines
# Clients legt auch sein Konto an (oder löscht es) - siehe business/service.py.
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session
from rdvmedecins.entities import User
class UserRepository:
# None, wenn kein Benutzer diesen Login hat
def read_by_login(self, session: Session, login: str) -> User | None:
return session.scalars(select(User).where(User.login == login)).first()
def add(self, session: Session, user: User) -> User:
session.add(user)
return user
def remove(self, session: Session, id: int):
session.execute(delete(User).where(User.id == id))
|
Das Lesen eines Benutzers über sein Login (für die Anmeldung), das Hinzufügen und Löschen eines Kontos.
11.12. Die Geschäftsschicht
Der Ordner [business] enthält die Geschäftsregeln, und nur diese. Er kennt weder [Flask], HTML noch die HTTP-Anfrage: Er könnte unverändert in einer Befehlszeilenanwendung oder in einer API verwendet werden.
11.12.1. business/dates.py
| # =========================================================================
# business/dates.py
# -------------------------------------------------------------------------
# Das heutige Datum. Es wird von GESCHÄFTSREGELN verwendet (keine Buchung
# in der Vergangenheit, nur ein ANSTEHENDER Termin pro Patient): es gehört daher
# in die Geschäftsschicht. Die Web-Schicht verwendet es wieder.
# =========================================================================
from datetime import date
# das heutige Datum, in der Zeitzone des Servers
def today() -> date:
return date.today()
|
Das aktuelle Datum wird für zwei Geschäftsregeln benötigt (keine Termine in der Vergangenheit, nur ein künftiger Termin pro Patient): Es gehört in die Geschäftsschicht. Es in einer Funktion zu isolieren, hat einen weiteren Vorteil: Ein automatisierter Test könnte sie durch ein festes Datum ersetzen.
11.12.2. business/exception.py
| # =========================================================================
# business/exception.py
# -------------------------------------------------------------------------
# Die Exception, die die Geschäftsschicht auslöst, wenn eine GESCHÄFTSREGEL
# verletzt wird (Login bereits vergeben, Arzt, der noch Termine hat, Zeitfenster
# bereits gebucht ...). Sie trägt keinen Text, sondern einen Übersetzungs-
# SCHLÜSSEL (z. B.: "ERRORS.LOGIN_TAKEN"): die Web-Schicht übersetzt ihn
# bei der Anzeige der Seite ins Französische oder Englische
# (siehe i18n/fr.json, i18n/en.json).
#
# Eine BusinessException ist keine Anomalie: sie ist eine normale Antwort
# ("dieser Login ist bereits vergeben"), die dem Benutzer angezeigt wird. Jede andere
# Exception ist eine echte Anomalie, die auf der Fehlerseite 500 landet.
# =========================================================================
class BusinessException(Exception):
def __init__(self, key: str, params: dict[str, str] | None = None):
super().__init__(key)
# Übersetzungsschlüssel der Meldung
self.key = key
# mögliche Parameter der Meldung ({minutes} ...)
self.params = params or {}
|
Die Ausnahme der Geschäftsschicht trägt keinen Text, wie in Beispiel 28, sondern einen Übersetzungsschlüssel ([ERRORS.LOGIN_TAKEN]) und gegebenenfalls Parameter: Die Geschäftsschicht weiß nicht, in welcher Sprache der Benutzer die Seite betrachtet. Die Web-Schicht übersetzt den Schlüssel. [super().__init__(key)] übergibt den Schlüssel an den Konstruktor der Klasse [Exception]: Das ist der Wert, der angezeigt wird, wenn die Ausnahme protokolliert wird.
Eine [BusinessException] ist kein Fehler: Sie ist eine normale Antwort („dieser Benutzername ist bereits vergeben“), die dem Benutzer angezeigt wird. Jede andere Ausnahme ist ein echter Fehler, der zu einer Fehlerseite 500 führt.
11.12.3. business/person_data.py
| # =========================================================================
# business/person_data.py
# -------------------------------------------------------------------------
# Die im Formular "Arzt" oder "Client" eingegebenen Daten, so wie
# die Web-Schicht sie an die Geschäftsschicht übergibt.
# =========================================================================
from dataclasses import dataclass
@dataclass(frozen=True)
class PersonData:
title: str # Mr, Mme, Melle
last_name: str
first_name: str
# Anlegen: optional (None), standardmäßig der Nachname in Kleinbuchstaben
# Bearbeiten: optional, der Login bleibt unverändert, wenn er fehlt
login: str | None = None
# Anlegen: optional, standardmäßig der Login
# Bearbeiten: optional, das Passwort bleibt unverändert, wenn es fehlt
password: str | None = None
# Bearbeiten: die Version des Datensatzes zu dem Zeitpunkt, als das Formular
# angezeigt wurde (optimistisches Sperren, siehe entities/base.py)
version: int | None = None
|
Die Daten eines Formulars „Arzt“ oder „Client“, von der Web-Schicht übergeben (Beispiel 28). Login, Passwort und Version sind optional: Die Kommentare erklären, was ihr Fehlen bei der Erstellung und bei der Änderung bedeutet.
11.12.4. business/business.py
| # =========================================================================
# business/business.py
# -------------------------------------------------------------------------
# Der VERTRAG der Geschäftsschicht: Lesezugriffe, Terminkalender, Termine, Verwaltung
# der Ärzte und der Clients.
#
# Ein Protocol beschreibt die Methoden, die ein Objekt haben muss, ohne zu sagen, wie
# sie geschrieben sind (das Äquivalent einer Schnittstelle). BusinessService (die
# Geschäftsschicht) und ApplicationModel (der Cache der Web-Schicht) erfüllen
# ihn beide. Python prüft zur Laufzeit nichts: es sind
# die Analysewerkzeuge (zum Beispiel das von VS Code), die eine Abweichung melden.
#
# T | None: ein Ergebnis, das fehlen kann (ein Arzt, der nicht existiert ...).
# =========================================================================
from datetime import date
from typing import Protocol
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
class Business(Protocol):
# ------------------------------------------------ Lesezugriffe
def get_all_clients(self) -> list[Client]: ...
def get_all_doctors(self) -> list[Doctor]: ...
def get_all_slots(self, doctor_id: int) -> list[Slot]: ...
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]: ...
def get_client_by_id(self, id: int) -> Client | None: ...
def get_doctor_by_id(self, id: int) -> Doctor | None: ...
def get_appointment_by_id(self, id: int) -> Appointment | None: ...
def get_slot_by_id(self, id: int) -> Slot | None: ...
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None: ...
# der Client (Patient), dessen Benutzerkonto [user_id] ist
def get_client_by_user_id(self, user_id: int) -> Client | None: ...
# die Termine eines Clients, von heute oder künftig, mit Zeitfenster und Arzt
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]: ...
# ------------------------------------------------ Termine (ADMIN, DOCTOR, USER)
# löst eine BusinessException aus, wenn:
# - der Tag in der Vergangenheit liegt ("ERRORS.PAST_DATE");
# - der Patient bereits einen anstehenden Termin hat ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
# - das Zeitfenster an diesem Tag bereits belegt ist ("ERRORS.SLOT_ALREADY_BOOKED").
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment: ...
def delete_appointment(self, appointment: Appointment) -> None: ...
# ------------------------------------------------ Ärzte (ADMIN)
# legt den Arzt UND sein Benutzerkonto an (Rolle DOCTOR)
def add_doctor(self, data: PersonData) -> Doctor: ...
# bearbeitet den Arzt UND sein Benutzerkonto
def edit_doctor(self, id: int, data: PersonData) -> Doctor: ...
# löscht den Arzt, seine Zeitfenster UND sein Konto - abgelehnt, wenn er Termine hat
def delete_doctor(self, id: int) -> None: ...
# ------------------------------------------------ Clients
# (der ADMIN; add_client wird auch für die Registrierung eines Patienten verwendet,
# edit_client und delete_client vom Patienten für sein eigenes Konto)
# legt den Client UND sein Benutzerkonto an (Rolle USER)
def add_client(self, data: PersonData) -> Client: ...
def edit_client(self, id: int, data: PersonData) -> Client: ...
# löscht den Client, sein Konto UND alle seine Termine (vergangene und künftige)
def delete_client(self, id: int) -> None: ...
|
- Zeile 23: der Vertrag der Geschäftsschicht: eine Liste ihrer Methoden samt Parametern und Rückgabewerten. Ein [Protocol] (Standardmodul [typing]) ist das [Python]-Äquivalent einer Schnittstelle: Es beschreibt die Methoden, die ein Objekt haben muss, ohne festzulegen, wie sie implementiert sind. Eine Klasse genügt ihm, sofern sie diese Methoden besitzt, ohne dies deklarieren zu müssen (man spricht von struktureller Typisierung, oder *Duck Typing*: „Wenn es wie eine Ente läuft ...“). Zwei Klassen genügen ihm: [BusinessService], die Geschäftsschicht, und [ApplicationModel], der Cache der Web-Schicht (später besprochen). [Python] prüft zur Laufzeit nichts: Es sind die Analysewerkzeuge, etwa das in [Visual Studio Code], die eine Abweichung melden;
- Zeile 26: Der Rumpf einer Protokollmethode wird reduziert auf [...] (das [Ellipsis]-Objekt von [Python], das nichts tut);
- Zeilen 55–78: Die Kommentare dokumentieren die Geschäftslogik und die Fehlercodes jeder Methode.
11.12.5. business/service.py
Die Implementierung der Geschäftsschicht. Dies ist die wichtigste Datei der Anwendung.
| # =========================================================================
# business/service.py
# -------------------------------------------------------------------------
# Implementierung der Geschäftsschicht.
#
# Die Verwaltung der Ärzte und der Clients folgt drei Geschäftsregeln:
#
# 1. eine Person (Arzt oder Client) und ihr Benutzerkonto gehören IMMER
# zusammen: sie werden gemeinsam angelegt, bearbeitet und gelöscht, in
# derselben TRANSAKTION - entweder gelingt alles, oder nichts wird geschrieben;
# 2. der Login ist in der gesamten Anwendung eindeutig, und zwei Ärzte (oder
# zwei Clients) dürfen nicht denselben Vor- und Nachnamen haben;
# 3. Löschen:
# - ein ARZT, der Termine hat, kann nicht gelöscht werden (seine
# Patienten würden ihren Termin verlieren, ohne gewarnt zu werden): sie müssen
# zuerst storniert werden. Seine Zeitfenster verschwinden mit ihm;
# - ein CLIENT dagegen verschwindet mit ALLEN seinen Terminen (vergangenen und
# künftigen) - ob das Löschen vom ADMIN oder vom Patienten
# selbst kommt.
#
# Und zwei Regeln für die Buchung von Terminen, unabhängig von der Rolle
# desjenigen, der bucht (ADMIN, DOCTOR oder der Patient selbst):
# 4. kein Termin in der Vergangenheit;
# 5. ein Patient hat jeweils nur EINEN anstehenden Termin.
#
# Ärzte und Clients folgen genau denselben Regeln: der gemeinsame Code
# wird EINMAL geschrieben (private Methoden _xxx_person) und durch einen
# kleinen "Deskriptor" parametrisiert, der angibt, mit welcher Art von Person wir es zu tun haben.
#
# Die TRANSAKTIONEN werden von der Methode _transaction geöffnet (am Ende der
# Datei), die außerdem die Fehler, die die Datenbank beim Senden der SQL-Anweisungen
# meldet, in BusinessException übersetzt.
# =========================================================================
import re
from collections.abc import Callable
from dataclasses import dataclass
from datetime import date
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session, sessionmaker
from sqlalchemy.orm.exc import StaleDataError
from rdvmedecins.auth.passwords import hash_password
from rdvmedecins.domain.schedule import DoctorDaySchedule, DoctorDaySlot
from rdvmedecins.entities import Client, Slot, Doctor, Person, Role, Appointment, User
from rdvmedecins.business import dates
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.person_repository import PersonRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
# alles, was für die Geschäftsregeln einen Arzt von einem Client unterscheidet
@dataclass(frozen=True)
class Descriptor:
dao: PersonRepository
factory: type[Person] # Arzt oder Client
role: Role # DOCTOR oder USER
not_found_key: str # Meldung, falls die Person nicht existiert
already_exists_key: str # Meldung, falls dieselben Vor- und Nachnamen bereits existieren
# optional (None): falls vorhanden, wird das Löschen ABGELEHNT, solange die
# Person Termine hat (count_appointments > 0), mit der Meldung has_appointments_key
count_appointments: Callable[[Session, int], int] | None
has_appointments_key: str | None
# optional: was VOR der Person gelöscht werden muss (die Zeilen, die
# sie über einen Fremdschlüssel referenzieren)
before_delete: Callable[[Session, int], None] | None
# -----------------------------------------------------------------------
# Datenbankfehler -> BusinessException
#
# Wenn eine UNIQUE-Bedingung einen Schreibvorgang ablehnt, löst SQLAlchemy einen
# IntegrityError aus, dessen Attribut [orig] der ursprüngliche Fehler ist, der des
# Treibers PyMySQL. Seine Meldung zitiert den NAMEN der Bedingung:
# Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
# (MySQL 8 stellt dem Namen den der Tabelle voran, MariaDB nicht). Deshalb
# VERGIBT das SQL-Skript für alle seine Bedingungen NAMEN.
# -----------------------------------------------------------------------
CONSTRAINT_MESSAGES = {
"unq_users_login": "ERRORS.LOGIN_TAKEN",
"unq_doctors_first_name_last_name": "ERRORS.DOCTOR_ALREADY_EXISTS",
"unq_clients_first_name_last_name": "ERRORS.PATIENT_ALREADY_EXISTS",
"unq1_appointments": "ERRORS.SLOT_ALREADY_BOOKED",
}
CONSTRAINT = re.compile(r"for key '(?:[^'.]*\.)?([^']+)'")
class BusinessService:
# alle Abhängigkeiten werden von der Anwendungs-Factory bereitgestellt
# (siehe rdvmedecins/__init__.py): das ist Dependency Injection "von
# Hand". sessions: die Factory der SQLAlchemy-Sessions.
def __init__(self, sessions: sessionmaker, doctors: DoctorRepository,
clients: ClientRepository, slots: SlotRepository, appointments: AppointmentRepository,
users: UserRepository):
self._sessions = sessions
self._doctors = doctors
self._clients = clients
self._slots = slots
self._appointments = appointments
self._users = users
self._doctor = Descriptor(
dao=doctors, factory=Doctor, role=Role.DOCTOR,
not_found_key="ERRORS.DOCTOR_NOT_FOUND",
already_exists_key="ERRORS.DOCTOR_ALREADY_EXISTS",
count_appointments=appointments.count_by_doctor,
has_appointments_key="ERRORS.DOCTOR_HAS_APPOINTMENTS",
# ein Arzt ohne Termine kann noch Zeitfenster haben:
# sie ergeben ohne ihn keinen Sinn und werden mit ihm gelöscht (andernfalls
# würde der Fremdschlüssel slots.doctor_id das Löschen verbieten)
before_delete=slots.delete_by_doctor)
self._client = Descriptor(
dao=clients, factory=Client, role=Role.USER,
not_found_key="ERRORS.PATIENT_NOT_FOUND",
already_exists_key="ERRORS.PATIENT_ALREADY_EXISTS",
# kein count_appointments: das Löschen eines Clients wird nie abgelehnt;
# seine Termine (vergangene und künftige) werden mit ihm gelöscht (andernfalls
# würde der Fremdschlüssel appointments.client_id das Löschen verbieten)
count_appointments=None, has_appointments_key=None,
before_delete=appointments.delete_by_client)
# =======================================================================
# Lesezugriffe: eine Session für die Dauer des Lesens; die gelesenen Objekte bleiben
# danach verwendbar (expire_on_commit=False, siehe rdvmedecins/__init__.py)
# =======================================================================
def _read[R](self, work: Callable[[Session], R]) -> R:
with self._sessions() as session:
return work(session)
def get_all_clients(self) -> list[Client]:
return self._read(self._clients.list)
def get_all_doctors(self) -> list[Doctor]:
return self._read(self._doctors.list)
def get_all_slots(self, doctor_id: int) -> list[Slot]:
return self._read(lambda s: self._slots.list_by_doctor(s, doctor_id))
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
return self._read(lambda s: self._appointments.doctor_day_appointments(s, doctor_id, day))
def get_client_by_id(self, id: int) -> Client | None:
return self._read(lambda s: self._clients.read(s, id))
def get_doctor_by_id(self, id: int) -> Doctor | None:
return self._read(lambda s: self._doctors.read(s, id))
def get_appointment_by_id(self, id: int) -> Appointment | None:
return self._read(lambda s: self._appointments.read(s, id))
def get_slot_by_id(self, id: int) -> Slot | None:
return self._read(lambda s: self._slots.read(s, id))
def get_client_by_user_id(self, user_id: int) -> Client | None:
return self._read(lambda s: self._clients.read_by_user(s, user_id))
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
return self._read(lambda s: self._appointments.client_upcoming_appointments(s, client_id, dates.today()))
# der Terminkalender eines Arztes an einem bestimmten Tag: seine Zeitfenster und für jedes der
# an diesem Tag gebuchte Termin (None, wenn es frei ist)
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
doctor = self.get_doctor_by_id(doctor_id)
if doctor is None:
return None
time_slots = self.get_all_slots(doctor_id)
# Nr. des Zeitfensters -> an diesem Zeitfenster gebuchter Termin (eine Dictionary-"Comprehension")
bookings = {a.slot_id: a for a in self.get_doctor_day_appointments(doctor_id, day)}
doctor_day_slots = [DoctorDaySlot(slot, bookings.get(slot.id))
for slot in time_slots]
return DoctorDaySchedule(doctor, day, doctor_day_slots)
# =======================================================================
# Termine
# =======================================================================
# -----------------------------------------------------------------------
# Buchung eines Termins, in einer Transaktion:
# 1. kein Termin in der Vergangenheit;
# 2. die Zeile des Patienten wird GESPERRT (SELECT ... FOR UPDATE): bucht
# derselbe Patient im selben Moment zwei Zeitfenster (zwei Tabs,
# Doppelklick ...), wartet die zweite Transaktion auf das Ende der
# ersten - und sieht dann den Termin, den sie gerade angelegt hat;
# 3. nur ein anstehender Termin pro Patient;
# 4. schließlich das Einfügen. Wurde das Zeitfenster gerade von einem ANDEREN
# Patienten belegt, lehnt die SQL-Bedingung unq1_appointments (day, slot_id) das
# Einfügen ab - von _transaction in BusinessException übersetzt.
# -----------------------------------------------------------------------
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
def work(session: Session) -> Appointment:
today = dates.today()
if day < today:
raise BusinessException("ERRORS.PAST_DATE")
patient_id = self._clients.lock(session, client.id)
if patient_id is None:
raise BusinessException("ERRORS.PATIENT_NOT_FOUND")
if self._appointments.count_client_upcoming(session, patient_id, today) > 0:
raise BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT")
# die ids des Zeitfensters und des Patienten zu kennen, genügt, um
# die Fremdschlüssel zu schreiben: diese Objekte müssen nicht erneut in der Session gelesen werden
return self._appointments.add(session, Appointment(day=day, slot_id=slot.id,
client_id=patient_id))
return self._transaction(work)
def delete_appointment(self, appointment: Appointment) -> None:
self._transaction(lambda session: self._appointments.remove(session, appointment.id))
# =======================================================================
# Ärzte und Clients - die öffentlichen Methoden delegieren an die gemeinsamen
# privaten Methoden, mit dem passenden Deskriptor
# =======================================================================
def add_doctor(self, data: PersonData) -> Doctor:
return self._add_person(self._doctor, data)
def edit_doctor(self, id: int, data: PersonData) -> Doctor:
return self._edit_person(self._doctor, id, data)
def delete_doctor(self, id: int) -> None:
self._delete_person(self._doctor, id)
def add_client(self, data: PersonData) -> Client:
return self._add_person(self._client, data)
def edit_client(self, id: int, data: PersonData) -> Client:
return self._edit_person(self._client, id, data)
# der Client, sein Konto UND alle seine Termine (ADMIN oder der Patient
# selbst über "Mein Konto verwalten": dieselbe Methode, dieselbe Regel)
def delete_client(self, id: int) -> None:
self._delete_person(self._client, id)
# -----------------------------------------------------------------------
# Anlegen: das Benutzerkonto UND die Person, in EINER Transaktion.
# -----------------------------------------------------------------------
def _add_person(self, d: Descriptor, data: PersonData):
last_name = data.last_name.strip().upper()
first_name = data.first_name.strip()
# die Regeln der Datenbank dbrdvmedecins2: Login = Nachname in Kleinbuchstaben,
# Passwort = Login - es sei denn, der ADMIN hat andere eingegeben
login = (data.login or last_name).lower()
password = data.password or login
def work(session: Session):
self._check_person_unique(session, d, first_name, last_name, None)
self._check_login_free(session, login)
user = User(login=login, password=hash_password(password), name=f"{first_name} {last_name}", role=d.role)
person = d.factory(title=data.title, last_name=last_name, first_name=first_name, user=user)
# die Person verweist auf ihr Konto: SQLAlchemy fügt zuerst das
# Konto ein (um seine id zu kennen), dann die Person
d.dao.add(session, person)
# flush: die INSERTs gehen sofort hinaus (und nicht erst beim COMMIT); eine
# verletzte Bedingung löst ihren Fehler daher HIER aus
session.flush()
return person
return self._transaction(work)
# -----------------------------------------------------------------------
# Bearbeiten: die Person UND ihr Konto (der angezeigte Name "Vorname NACHNAME"
# muss mitgeführt werden; der Login und das Passwort ändern sich nur, wenn sie
# eingegeben wurden).
# -----------------------------------------------------------------------
def _edit_person(self, d: Descriptor, id: int, data: PersonData):
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
# optimistisches Sperren: entspricht die Version in der Datenbank nicht mehr der des
# Formulars, hat jemand diesen Datensatz in der Zwischenzeit bearbeitet - wir lehnen ab,
# statt seine Änderungen stillschweigend zu überschreiben.
# (Erfolgt die gleichzeitige Bearbeitung NACH diesem Lesen, erkennt sie
# die Klausel "WHERE version = ..." des UPDATE.)
if data.version is not None and data.version != person.version:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
last_name = data.last_name.strip().upper()
first_name = data.first_name.strip()
self._check_person_unique(session, d, first_name, last_name, id)
# wir ändern lediglich die Objekte: sie werden von der
# Session "verfolgt", die die nötigen UPDATEs selbst sendet
person.title = data.title
person.last_name = last_name
person.first_name = first_name
user = person.user
user.name = f"{first_name} {last_name}"
if data.login and data.login.lower() != user.login:
login = data.login.lower()
self._check_login_free(session, login)
user.login = login
if data.password:
user.password = hash_password(data.password)
session.flush()
return person
return self._transaction(work)
# -----------------------------------------------------------------------
# Löschen, in EINER Transaktion, in der von den Fremd-
# schlüsseln vorgegebenen Reihenfolge:
# 1. mögliche Ablehnung, wenn noch Termine vorhanden sind (Arzt);
# 2. was auf die Person verweist (Zeitfenster eines Arztes, Termine
# eines Clients);
# 3. die Person (sie verweist auf ihr Konto);
# 4. ihr Konto.
# -----------------------------------------------------------------------
def _delete_person(self, d: Descriptor, id: int) -> None:
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
if d.count_appointments is not None and d.count_appointments(session, id) > 0:
raise BusinessException(d.has_appointments_key)
if d.before_delete is not None:
d.before_delete(session, id)
d.dao.remove(session, id)
self._users.remove(session, person.user_id)
self._transaction(work)
# lehnt Vor- und Nachnamen ab, die bereits von einer ANDEREN Person desselben Typs verwendet werden
# (current_id: die Person, die gerade bearbeitet wird und die selbstverständlich das
# Recht hat, ihren eigenen Vor- und Nachnamen zu behalten; None beim Anlegen)
@staticmethod
def _check_person_unique(session: Session, d: Descriptor, first_name: str, last_name: str,
current_id: int | None):
namesake = d.dao.namesake(session, first_name, last_name)
if namesake is not None and namesake.id != current_id:
raise BusinessException(d.already_exists_key)
def _check_login_free(self, session: Session, login: str):
if self._users.read_by_login(session, login) is not None:
raise BusinessException("ERRORS.LOGIN_TAKEN")
# -----------------------------------------------------------------------
# führt [work] in einer Transaktion aus:
# sessions.begin() -> eine Session und ihre Transaktion (START TRANSACTION);
# beim Verlassen des with-Blocks: COMMIT, wenn alles gut gegangen ist; verlässt eine
# Exception ihn (BusinessException eingeschlossen), ROLLBACK: nichts wird geschrieben.
#
# Die Prüfungen "Login frei" und "Vor- + Nachname eindeutig" erfolgen VOR
# dem Schreiben, um eine klare Meldung zu geben. Zwei ADMINs könnten aber
# im selben Moment denselben Login (oder denselben Arzt) speichern: in diesem
# seltenen Fall lehnt eine SQL-Eindeutigkeitsbedingung den zweiten
# Schreibvorgang ab. Die Datenbankfehler werden daher UM die
# Transaktion herum abgefangen, um sie in dieselbe BusinessException zu übersetzen:
# - StaleDataError: das UPDATE "WHERE id = ... AND version = ..." hat
# keine Zeile geändert (optimistisches Sperren);
# - IntegrityError: eine Bedingung der Datenbank hat den Schreibvorgang abgelehnt.
# Jeder andere Fehler ist eine echte Anomalie: er wird durchgelassen.
# -----------------------------------------------------------------------
def _transaction[R](self, work: Callable[[Session], R]) -> R:
try:
with self._sessions.begin() as session:
return work(session)
except StaleDataError:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
except IntegrityError as e:
match = CONSTRAINT.search(str(e.orig))
if match and match.group(1) in CONSTRAINT_MESSAGES:
raise BusinessException(CONSTRAINT_MESSAGES[match.group(1)])
raise
|
11.12.5.1. Die Deskriptoren
Ärzte und Clients folgen exakt denselben Geschäftsregeln, mit einigen kleinen Unterschieden: ein anderes DAO, eine andere Rolle für ihr Konto, andere Fehlermeldungen und eine andere Löschregel. Statt jede Methode doppelt zu schreiben, wird der gemeinsame Code nur einmal geschrieben (die Methoden [_add_person], [_edit_person], [_delete_person]) und über einen Deskriptor konfiguriert, der angibt, welche Art von Person behandelt wird:
- Zeilen 59–71: Der Deskriptor ist eine unveränderliche [dataclass]. Drei seiner Felder sind Funktionen: [Callable[[Session, int], int]] ist der Typ einer Funktion, die eine Session und eine Ganzzahl entgegennimmt und eine Ganzzahl zurückgibt. [count_appointments] zählt die Termine einer Person (um das Löschen eines Arztes zu verhindern, der noch Termine hat); [before_delete] löscht die Verweise auf die Person (die Zeitfenster eines Arztes, die Termine eines Clients);
- Zeilen 109–118: der Deskriptor der Ärzte. [appointments.count_by_doctor] ist eine Methode, die dem Objekt [appointments] zugeordnet ist (Beispiel 22): eine Funktion, die die Session und die ID erhält;
- Zeilen 120–128: der Deskriptor der Clients: keine Löschverweigerung ([count_appointments=None]), dafür aber das vorherige Löschen aller ihrer Termine.
11.12.5.2. Lesevorgänge und der Kalender
- Zeilen 135–137: Die Lesevorgänge werden von einer kleinen generischen Methode abgewickelt: [R] ist der Ergebnistyp, der mit dem der Funktion [work] übereinstimmt. Die Session wird von [self._sessions()] (ohne [begin]) geöffnet, solange die Funktion ausgeführt wird, und anschließend vom [with]-Block geschlossen. [SQLAlchemy] startet bei der ersten Abfrage dennoch eine Transaktion ([BEGIN (implicit)] in der Konsole); da nichts geschrieben wurde, bricht das Schließen der Session sie ab ([ROLLBACK]): Dies sind die Zeilen, die die Konsole beim Start der Anwendung anzeigt;
- Zeilen 139–167: Jeder Lesevorgang weist [_read] an, die DAO-Methode aufzurufen. Hat die DAO-Methode andere Parameter als die Session, liefert sie eine anonyme Funktion ([lambda s: ...]);
- Zeilen 171–180: Der Terminkalender eines Arztes für einen einzelnen Tag. Die Termine des Tages werden in einem Dictionary ([{key: value for ...}]) abgelegt, das jeder Zeitfensternummer den zugehörigen Termin zuordnet; jedes Zeitfenster wird dann seinem Termin zugeordnet oder [None] ([bookings.get(slot.id)]). Drei Lesevorgänge in drei Sessions: Eine Inkonsistenz zwischen ihnen (ein zwischen zwei Lesevorgängen vereinbarter Termin) wäre folgenlos, da der Terminkalender lediglich eine Anzeige ist.
11.12.5.3. Einen Termin vereinbaren
- Zeilen 198–213: Die Methode definiert eine interne Funktion [work], die die in der Transaktion auszuführenden Operationen enthält, und übergibt sie an die Methode [_transaction] (siehe unten). Die Regeln in der Reihenfolge ihrer Prüfung: - keine Termine in der Vergangenheit ([day < today]: Datumswerte werden in [Python] mit den üblichen Operatoren verglichen); - der Datensatz des Patienten wird gesperrt ([lock], siehe [ClientRepository]): Wenn derselbe Patient zwei Zeitfenster gleichzeitig bucht (zwei Tabs, ein Doppelklick), wartet die zweite Transaktion, bis die erste abgeschlossen ist, und sieht dann den Termin, den diese angelegt hat; - nur ein bevorstehender Termin pro Patient; - zuletzt das Einfügen. Der Termin wird anhand der ID des Zeitfensters und der Patienten-ID angelegt: Die Werte der Fremdschlüssel zu kennen genügt, die Objekte müssen nicht erneut gelesen werden. Die benannten Parameter des Konstruktors ([Appointment(day=..., slot_id=...)]) stellt [SQLAlchemy] jeder Entität bereit, die keinen eigenen Konstruktor hat.
- Ein Szenario bleibt übrig: Das Zeitfenster wurde zwischen der Anzeige des Kalenders und der Buchung von einem anderen Patienten belegt. In diesem Fall verhindert die Datenbankconstraint [unq1_appointments] das Einfügen beim [COMMIT]. Die Methode [_transaction] übersetzt diesen Fehler in eine [BusinessException];
- Zeilen 215–216: Stornierung eines Termins. Die Berechtigungsprüfungen (ein Patient darf nur seine eigenen Termine stornieren) übernimmt die Web-Schicht, die den Benutzer kennt.
11.12.5.4. Verwaltung der Ärzte und Clients
- Zeilen 223–241: Die öffentlichen Methoden delegieren an die gemeinsamen Methoden und verwenden dabei den passenden Deskriptor;
- Zeilen 246–267: Anlegen. Der Nachname wird großgeschrieben und aus dem Vornamen werden die Leerzeichen entfernt; der Standardbenutzername ist der Nachname in Kleinbuchstaben, und das Passwort entspricht dem Benutzernamen (die Regel für die Demo-Konten im SQL-Skript). In der Transaktion: Validierungen (keine Namensgleichen, freier Login), gefolgt vom Anlegen des Kontos und der Person. Die Person erhält ihr Konto über ihre Beziehung ([user=user]): [SQLAlchemy] weiß, dass es zuerst das Konto einfügen muss, um dessen ID zu erhalten, und danach die Person. [session.flush()] sendet [INSERT] sofort: Eine verletzte Constraint löst in der Transaktion einen Fehler aus, und die zurückgegebene Person hat ihre ID;
- Zeilen 274–309: die Aktualisierung. Die Version des Formulars wird mit der Version in der Datenbank verglichen (optimistisches Sperren, Beispiel 28); danach aktualisieren wir die gelesenen Objekte einfach: Sie werden von der Session verfolgt, die die nötigen [UPDATE]-Anweisungen selbst sendet. Der angezeigte Kontoname folgt dem Vor- und Nachnamen; Login und Passwort ändern sich nur, wenn sie eingegeben wurden;
- Zeilen 320–332: Löschen, in der von den Fremdschlüsseln vorgegebenen Reihenfolge: mögliche Ablehnung (ein Arzt, der Termine hat), Löschen der Verweise auf die Person, der Person selbst und danach ihres Kontos. In umgekehrter Reihenfolge würde die Datenbank jedes [DELETE] ablehnen. Das alles geschieht in einer einzigen Transaktion: Schlägt ein Schritt fehl, wird keiner der Schritte ausgeführt;
- Zeilen 337–342: Ein Namensgleicher wird abgelehnt, es sei denn, es handelt sich um die Person, die gerade bearbeitet wird und die das Recht hat, ihren eigenen Vor- und Nachnamen zu behalten;
- Zeilen 344–346: Ein Benutzername kann nur zu einem einzigen Konto gehören.
11.12.5.5. Transaktionen und Eindeutigkeitsconstraints
- Zeilen 365–375: Alle Aktualisierungen laufen über diese Methode. [sessions.begin()] öffnet eine Session und ihre Transaktion; beim Verlassen des [with]-Blocks wird die Transaktion bestätigt ([COMMIT]), wenn alles gut gegangen ist, oder zurückgerollt ([ROLLBACK]), wenn eine Ausnahme auftritt, einschließlich [BusinessException];
- Zeilen 369–370: Das optimistische Sperren hat eine gleichzeitige Änderung erkannt (Beispiel 28);
- Zeilen 371–374: Eine Datenbankconstraint hat den Schreibvorgang abgelehnt. Die vor dem Schreiben durchgeführten Prüfungen (eindeutiger Benutzername, keine Namensgleichen) liefern in den allermeisten Fällen eine klare Meldung; zwei Administratoren könnten jedoch gleichzeitig denselben Benutzernamen registrieren, oder zwei Patienten könnten dasselbe Zeitfenster buchen. Die Eindeutigkeitsconstraint lehnt dann den zweiten Schreibvorgang ab, und [SQLAlchemy] löst eine [IntegrityError] aus. Ihre ursprüngliche Meldung ([e.orig], der Fehler von [PyMySQL]) nennt den Namen der Constraint (hier mit [MariaDB], für das zweite am selben Tag doppelt gebuchte Zeitfenster):
| (1062, "Duplicate entry '2026-09-26-2' for key 'unq1_appointments'")
|
- Der reguläre Ausdruck [CONSTRAINT] (Zeile 91) extrahiert diesen Namen. [MySQL] 8 fügt das Präfix mit dem Tabellennamen hinzu (['appointments.unq1_appointments']), [MariaDB] nicht: der Teil [(?:[^'.]*\.)?] akzeptiert dieses optionale Präfix ([(?:...)] ist eine nicht erfassende Gruppe, [?] macht sie optional). Das Dictionary [CONSTRAINT_MESSAGES] (Zeilen 84–88) ordnet jeder bekannten Constraint den Schlüssel ihrer Meldung zu. Deshalb benennt das SQL-Skript alle seine Constraints;
- Zeile 375: Jeder andere Fehler ist eine echte Anomalie: [raise] ohne Parameter wirft die aktuelle Ausnahme erneut, was zu einer 500-Fehlerseite führt.
Beachten Sie die Struktur aller schreibenden Methoden: Eine interne Funktion [work], die die Operationen enthält, wird an [_transaction] übergeben, das sie in einer Transaktion ausführt und die Fehler übersetzt. Das entspricht der Annotation ***[@Transactional]*** von *[Spring]*, in nur wenigen Zeilen geschrieben: Eine Funktion ist ein Objekt wie jedes andere und kann als Parameter übergeben werden.
11.13. Authentifizierung
Der Ordner [auth] enthält die Mechanismen aus den Beispielen 25 bis 27, mit drei Unterschieden: Die Zugriffsregel ist umgekehrt (alles ist verboten, außer dem, was als öffentlich deklariert ist), die Benutzer werden aus der Datenbank gelesen, und das Anlegen eines Client-Kontos ist durch einen „Pass“ geschützt.
11.13.1. auth/passwords.py
| # =========================================================================
# auth/passwords.py
# -------------------------------------------------------------------------
# Passwort-Hashing: bcrypt, 10 Runden, Version $2b$ - wie die
# Hashes des SQL-Skripts.
#
# bcrypt berücksichtigt nur die ersten 72 BYTES eines Passworts (ein
# Zeichen mit Akzent belegt davon zwei, in UTF-8); die Bibliothek bcrypt
# lehnt ein längeres Passwort sogar ab. Wir übergeben ihr daher nur diese
# 72 Bytes, beim Anlegen wie bei der Überprüfung.
# =========================================================================
import bcrypt
def _bytes(password: str) -> bytes:
return password.encode("utf-8")[:72]
# der in der Datenbank zu speichernde Hash: "$2b$10$" + der Salt + das Ergebnis
def hash_password(password: str) -> str:
return bcrypt.hashpw(_bytes(password), bcrypt.gensalt(rounds=10)).decode("ascii")
# checkpw hasht das eingegebene Passwort mit dem im gespeicherten
# Hash enthaltenen "Salt" und vergleicht dann die beiden Ergebnisse
def verify(password: str, hashed: str) -> bool:
return bcrypt.checkpw(_bytes(password), hashed.encode("ascii"))
|
- Zeilen 15–16: [bcrypt] berücksichtigt nur die ersten 72 Bytes eines Passworts, und Version 5 der Bibliothek lehnt längere Passwörter ab (Beispiel 25). Daher werden nur diese 72 Bytes übergeben, sowohl beim Erstellen als auch beim Überprüfen: Ein längeres Passwort wird akzeptiert, aber Zeichen jenseits des 72. Bytes werden ignoriert. Ein Zeichen mit Akzent belegt in [UTF-8] zwei Bytes;
- Zeilen 20–21: Der Hash wird in Textform gespeichert: [decode("ascii")] wandelt die von [bcrypt] zurückgegebenen Bytes in eine Zeichenkette um;
- Zeilen 26–27: Überprüfung (Beispiel 25). Dieses Modul wird von der Authentifizierung und von der Geschäftsschicht verwendet (Kontoerstellung, Passwortänderung).
11.13.2. auth/connected_user.py
| # =========================================================================
# auth/connected_user.py
# -------------------------------------------------------------------------
# Was das JWT-Token enthält und wie man es wieder ausliest.
#
# Die Claims unserer Tokens (siehe AuthService.set_token):
# sub : die id des Benutzerkontos (JWT-Konvention: "subject"), als Text
# login : der Login
# name : der angezeigte Name ("Marie PELISSIER"), für die Navigationsleiste
# role : ADMIN, DOCTOR oder USER
# iat, exp: Erstellungs- und Ablaufdatum des Tokens
# =========================================================================
from dataclasses import dataclass
from rdvmedecins.entities import Role
# der angemeldete Benutzer in typisierter Form
@dataclass(frozen=True)
class ConnectedUser:
user_id: int
login: str
name: str
role: Role
# der durch die Claims eines bereits geprüften Tokens beschriebene Benutzer; None, wenn
# ein Claim fehlt oder nicht die erwartete Form hat
@staticmethod
def of(claims: dict) -> "ConnectedUser | None":
try:
return ConnectedUser(int(claims["sub"]), claims["login"], claims["name"],
Role(claims["role"]))
except (KeyError, ValueError, TypeError):
return None
@property
def is_admin(self) -> bool:
return self.role == Role.ADMIN
@property
def is_patient(self) -> bool:
return self.role == Role.USER
|
- Zeilen 20–24: der angemeldete Benutzer in typisierter Form: Beispiel 25 speicherte das Dictionary mit den Assertions des Tokens in [g.user]; die Anwendung speichert dieses Objekt, dessen Attribute dem Editor bekannt sind ([g.user.role]) und dessen Rolle ein Wert der Enumeration [Role] ist;
- Zeilen 29–34: Konstruktion auf Grundlage der Assertions eines bereits verifizierten Tokens. Der Ergebnistyp steht in Anführungszeichen (["ConnectedUser | None"]): Wenn [Python] die Methodendefinition liest, ist die Klasse [ConnectedUser] noch nicht vollständig definiert, und ihr Name kann nicht direkt verwendet werden. Ein Token mit fehlender Assertion ([KeyError]) oder unerwartetem Wert ([ValueError]: eine unbekannte Rolle, ein [sub] , das keine Zahl ist) ergibt [None]: Der Benutzer ist nicht authentifiziert;
- Zeilen 36–42: zwei Eigenschaften: Der Dekorator [@property] verwandelt eine Methode in eine berechnete Eigenschaft, die ohne Klammern verwendet wird: [g.user.is_admin].
Das Token enthält die Konto-ID ([sub], in Textform, wie vom JWT-Standard verlangt), den Login, den Anzeigenamen und die Rolle: alles, was die Navigationsleiste und die Zugriffsregeln benötigen, ohne bei jeder Anfrage die Datenbank abfragen zu müssen.
11.13.3. auth/auth_service.py
| # =========================================================================
# auth/auth_service.py
# -------------------------------------------------------------------------
# Die Authentifizierungslogik:
# - validate_user(): prüft ein Login-/Passwort-Paar;
# - set_token() : erstellt das JWT-Token eines validierten Benutzers
# und legt es in einem Cookie der Antwort ab;
# - clear_token() : löscht dieses Cookie;
# - current_user() : der durch das Cookie der Anfrage beschriebene Benutzer.
#
# Wie wird das JWT-Token übertragen?
# Bei einem JavaScript-Client verwaltete der Client-Code das Token selbst
# und fügte es jeder Anfrage selbst hinzu (Header "Authorization: Bearer
# ..."). Ein Browser, der gewöhnliche HTML-Seiten anzeigt, kann das nicht:
# Damit er das Token bei jeder Anfrage von sich aus mitsendet, muss es
# in einem COOKIE gespeichert werden. Die Optionen dieses Cookies sind für die
# Sicherheit wichtig:
# - HttpOnly: Das JavaScript der Seite kann das Cookie nicht lesen (ein
# eingeschleustes Skript könnte das Token somit nicht stehlen);
# - SameSite=Lax: Der Browser sendet das Cookie NICHT bei einem POST von
# einer anderen Website mit (erster Schutz gegen den sogenannten CSRF-Angriff; der
# zweite ist das Anti-CSRF-Token der Formulare, siehe rdvmedecins/__init__.py);
# - Secure: In der Produktion (HTTPS) wird das Cookie nie im Klartext übertragen;
# - Max-Age: Das Cookie verschwindet gleichzeitig mit dem Ablauf des Tokens.
# =========================================================================
from datetime import datetime, timedelta, timezone
import jwt
from flask import Request, Response
from rdvmedecins.auth.passwords import verify
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import User
from rdvmedecins.repositories.user_repository import UserRepository
# der Name des Cookies, das das Token trägt
JWT_COOKIE = "rdvmedecins_jwt"
class AuthService:
def __init__(self, sessions, users: UserRepository, secret: str, duration_seconds: int,
cookie_secure: bool):
# HMAC-SHA256 erfordert einen Schlüssel von mindestens 256 Bit: Wir melden dies
# beim Start deutlich, statt erst bei der ersten Anmeldung
if len(secret.encode("utf-8")) < 32:
raise RuntimeError("JWT_SECRET must be at least 32 characters long (see config.py).")
self._sessions = sessions
self._users = users
self._secret = secret
self._duration = timedelta(seconds=duration_seconds)
self._cookie_secure = cookie_secure
# None, wenn das Login nicht existiert oder das Passwort falsch ist
def validate_user(self, login: str, password: str) -> User | None:
with self._sessions() as session:
user = self._users.read_by_login(session, login)
if user is None or not verify(password, user.password):
return None
return user
# -----------------------------------------------------------------------
# erstellt das JWT-Token von [user] und legt es in einem Cookie ab.
# Das Token wird mit dem geheimen Schlüssel SIGNIERT (HMAC-SHA256): Der Browser
# kann es lesen (es ist nicht verschlüsselt), aber nicht ändern - jede
# Änderung würde die Signatur ungültig machen.
# -----------------------------------------------------------------------
def set_token(self, response: Response, user: User):
now = datetime.now(timezone.utc)
claims = {
"sub": str(user.id),
"login": user.login,
"name": user.name,
"role": user.role.value,
"iat": now,
"exp": now + self._duration,
}
token = jwt.encode(claims, self._secret, algorithm="HS256")
response.set_cookie(JWT_COOKIE, token, max_age=self._duration, path="/", httponly=True,
samesite="Lax", secure=self._cookie_secure)
# löscht das Cookie: Es wird erneut leer und mit der Lebensdauer null gesetzt
@staticmethod
def clear_token(response: Response):
response.delete_cookie(JWT_COOKIE, path="/")
# das in der Anfrage vorhandene Token, ob gültig oder nicht
@staticmethod
def token_of(request: Request) -> str | None:
return request.cookies.get(JWT_COOKIE)
# -----------------------------------------------------------------------
# der durch das Cookie der Anfrage beschriebene Benutzer; None, wenn kein
# Token vorhanden ist oder wenn das Token abgelaufen, gefälscht oder fehlerhaft ist.
# jwt.decode prüft die Signatur UND das Ablaufdatum (Claim exp).
# -----------------------------------------------------------------------
def current_user(self, request: Request) -> ConnectedUser | None:
token = self.token_of(request)
if not token:
return None
try:
claims = jwt.decode(token, self._secret, algorithms=["HS256"])
except jwt.InvalidTokenError:
return None
return ConnectedUser.of(claims)
|
- Zeilen 46–47: Ein zu kurzer Signaturschlüssel wird beim Start der Anwendung gemeldet und nicht erst beim ersten Login: [create_app] erstellt den Service, und die Ausnahme beendet die Anwendung mit dieser Meldung;
- Zeilen 55–60: Überprüfung von Benutzername und Passwort. Der Service liest den Benutzer über das DAO in einer Session, die nur für die Dauer dieses Lesevorgangs geöffnet bleibt; die Passwortprüfung ([bcrypt], das langsam ist) erfolgt nach dem Schließen der Session, um keine unnötige Verbindung zur Datenbank aufrechtzuerhalten;
- Zeilen 68–80: das Token (Beispiel 25) und sein Cookie [rdvmedecins_jwt]. [user.role.value]: der Wert der Enumeration, die Zeichenkette ["USER"]. Dem Cookie wird in der Produktion das Attribut [Secure] zugewiesen ([COOKIE_SECURE]);
- Zeilen 84–85: Löschen des Cookies. Dies ist eine statische Methode: Sie benötigt kein Objekt und wird auf der Klasse aufgerufen ([AuthService.clear_token(response)]);
- Zeilen 97–105: der durch das Cookie der Anfrage identifizierte Benutzer oder [None].
11.13.4. auth/security.py
Das Herzstück der Sicherheit: die Authentifizierung jeder Anfrage und die Zugriffsregel.
| # =========================================================================
# auth/security.py
# -------------------------------------------------------------------------
# Wer auf was zugreifen darf und wie der Benutzer bei jeder
# Anfrage erkannt wird (siehe Beispiele 25 und 26).
#
# Bei jeder Anfrage führt die Funktion authenticate (ein before_request der
# Anwendung) Folgendes aus:
# 1. Sie liest das Token aus dem Cookie, prüft Signatur und Ablaufdatum
# und speichert den Benutzer in g.user (None, falls keiner vorhanden);
# 2. Sie wendet die Zugriffsregel an: ALLE Aktionen erfordern einen authentifizierten
# Benutzer, außer den mit @public markierten (Login,
# Kontoerstellung, Sprachwahl) und den statischen Dateien.
# Es gilt die Regel „alles ist verboten, außer was erlaubt ist": Eine später
# hinzugefügte Aktion, deren Schutz man vergessen hätte, ist standardmäßig geschützt.
# Erst danach ruft Flask die Aktion auf, deren Dekorator
# @roles_required(...) die Rolle prüft.
#
# Zwei Fehlerfälle, zwei für eine HTML-Anwendung passende Antworten:
# - kein authentifizierter Benutzer (kein Token, abgelaufenes oder gefälschtes Token)
# -> Weiterleitung zur Login-Seite;
# - unzureichende Rolle -> Antwort 403, die web/errors.py in eine Seite umwandelt.
# =========================================================================
from functools import wraps
from flask import abort, current_app, g, redirect, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.entities import Role
from rdvmedecins.web.flash import flash_error
# Das Token ist gültig, aber das darin bezeichnete Konto existiert nicht mehr: Es wurde
# seit der Anmeldung gelöscht (vom Patienten selbst in einem anderen
# Tab oder vom ADMIN). Dieser Fall wird wie eine abgelaufene Sitzung behandelt:
# web/errors.py löscht das Cookie und leitet zur Login-Seite weiter.
class InvalidSession(Exception):
pass
# ein Dekorator, der eine Aktion als öffentlich MARKIERT (siehe Beispiel 24)
def public(action):
action.public = True
return action
def register(app, auth_service: AuthService):
@app.before_request
def authenticate():
g.user = auth_service.current_user(request)
# keine Route passt (die 404-Seite folgt) oder eine statische Datei
if request.endpoint is None or request.endpoint == "static":
return None
action = current_app.view_functions[request.endpoint]
if getattr(action, "public", False) or g.user is not None:
return None
# Eine von einem before_request zurückgegebene Antwort beendet die Verarbeitung:
# Die Aktion wird nicht aufgerufen
return to_login()
# -----------------------------------------------------------------------
# kein authentifizierter Benutzer -> Login-Seite. War ein Cookie
# vorhanden, ist dessen Token nicht mehr gültig: Die Sitzung ist abgelaufen.
# Das Cookie wird dann gelöscht und der Benutzer durch eine Flash-Nachricht gewarnt.
# -----------------------------------------------------------------------
def to_login():
response = redirect(url_for("auth.show_login"))
if AuthService.token_of(request):
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
# -----------------------------------------------------------------------
# Die Rolle des Benutzers muss eine der [roles] sein; andernfalls Antwort 403.
# require_roles wird aus einem before_request eines Blueprints aufgerufen (alle
# Aktionen des Blueprints, siehe controllers/persons.py); roles_required ist
# der Dekorator einer Aktion (siehe Beispiel 26).
# -----------------------------------------------------------------------
def require_roles(*roles: Role):
if g.user is None:
raise InvalidSession()
if g.user.role not in roles:
abort(403)
def roles_required(*roles: Role):
def decorator(action):
@wraps(action)
def protected_action(*args, **kwargs):
require_roles(*roles)
return action(*args, **kwargs)
return protected_action
return decorator
|
- Zeilen 37–38: eine Ausnahme für einen Sonderfall: Das Token ist gültig, aber das Konto, auf das es verweist, existiert nicht mehr (der Patient hat es in einem anderen Tab gelöscht, oder der Administrator hat es gelöscht). Aktionen, die das Konto benötigen, lösen diese Ausnahme aus; der Fehler-Handler behandelt sie wie eine abgelaufene Sitzung (siehe [web/errors.py]);
- Zeilen 42–44: der Dekorator, der eine Aktion als öffentlich kennzeichnet (Beispiel 24);
- Zeilen 50–60: die Funktion [before_request] der Anwendung. Zuerst wird der Benutzer bei allen Anfragen authentifiziert, auch bei öffentlichen: Die Login-Seite muss wissen, ob der Benutzer bereits angemeldet ist. Danach die Zugriffsregel: Eine Anfrage, die zu keiner Route passt ([request.endpoint is None]: darauf folgt die 404-Seite) oder eine statische Datei anfordert, ist erlaubt; eine als öffentlich gekennzeichnete Aktion ist erlaubt; ein authentifizierter Benutzer ist erlaubt. Andernfalls gibt die Funktion eine Antwort zurück (Weiterleitung auf die Login-Seite), die die Verarbeitung beendet: Die Aktion wird nicht aufgerufen.
Dies ist die Regel „Alles ist verboten, außer es ist ausdrücklich erlaubt“: Eine später hinzugefügte Aktion ist automatisch gesichert, auch wenn Sie vergessen haben, sie abzusichern. Fehlt [@public] an einer öffentlichen Aktion, fällt das sofort auf (die Seite leitet auf die Login-Seite um); der fehlende Schutz einer privaten Aktion fällt dagegen nicht sofort auf: Die Standardregel muss die sicherste sein. Das ist auch die Regel in [Spring MVC] ([anyRequest().authenticated()]);
- Zeilen 68–73: die Weiterleitung auf die Login-Seite. Enthielt die Anfrage ein Token-Cookie, bedeutet das, dass dieses Token nicht mehr gültig ist (abgelaufen oder manipuliert): Das Cookie wird gelöscht, und eine Pop-up-Meldung erklärt dem Benutzer, dass seine Sitzung abgelaufen ist (der oben gezeigte Screenshot der Meldung zum Sitzungsende);
- Zeilen 82–86: Autorisierung. Der Parameter [*roles] nimmt beliebig viele Rollen in einem Tupel entgegen: [require_roles(Role.ADMIN, Role.DOCTOR)]. Eine in der Liste fehlende Rolle führt zu einem 403-Fehler. Der Test [g.user is None] dürfte nie wahr sein (die Zugriffsregel hat anonyme Besucher bereits herausgefiltert), es sei denn, [require_roles] würde von einer öffentlichen Aktion aufgerufen: Das bietet eine zusätzliche Sicherheitsebene;
- Zeilen 89–98: der parametrisierte Dekorator aus Beispiel 26, der [require_roles] aufruft. [require_roles] kann auch allein im [before_request] eines Blueprints verwendet werden, um alle seine Aktionen auf einmal zu schützen (siehe [controllers/persons.py]).
11.13.5. auth/captcha_drawing.py
Die Bilddarstellung ist dieselbe wie in Beispiel 27 und wird exakt so übernommen. Der Kommentar im Kopf hebt einen wichtigen Punkt hervor: Jedes Zeichen wird mit Linien ([<path>]-Elemente) gezeichnet und niemals als Text geschrieben (ein [<text>]-Element); andernfalls müsste ein Bot nur den Quellcode des Bildes lesen.
11.13.6. auth/captcha.py
| # =========================================================================
# auth/captcha.py
# -------------------------------------------------------------------------
# Ein CAPTCHA („Test zur Unterscheidung von Mensch und Roboter"), das vom
# Server selbst ohne externen Dienst erzeugt wird: einige verzerrte Zeichen,
# durch Linien verwirrt, in einem SVG-Bild (siehe captcha_drawing.py). Ein
# Mensch liest sie leicht; ein Roboter, der lediglich in einer Schleife
# Formulare sendet, schafft das nicht.
#
# Funktionsweise:
# 1. generate() zeichnet einen zufälligen Text, erstellt daraus ein Bild und speichert die
# richtige Antwort IM SPEICHER DES SERVERS unter einer zufälligen Kennung;
# 2. Die Seite zeigt das Bild an und legt die Kennung in einem versteckten Feld des
# Formulars ab (die Antwort selbst verlässt den Server nie);
# 3. verify(id, typed) vergleicht die Eingabe mit der erwarteten Antwort und
# VERGISST dann dieses Captcha: Jedes Bild wird nur einmal verwendet, ein Roboter kann
# eine bereits gefundene Antwort nicht wiederverwenden.
#
# Ein einziges CaptchaService-Objekt für den gesamten Server, das von mehreren
# Anfragen PARALLEL verwendet wird (der Server verarbeitet sie in mehreren Threads): Ein
# Lock (Sperre) stellt sicher, dass immer nur ein Thread das
# Dictionary der ausstehenden Captchas liest oder ändert.
#
# Akzeptierte Einschränkung: der Speicher eines einzelnen Prozesses. Bei mehreren Prozessen
# oder mehreren Servern wäre ein gemeinsamer Speicher nötig.
# =========================================================================
import secrets
from dataclasses import dataclass
from datetime import datetime, timedelta
from threading import Lock
from rdvmedecins.auth import captcha_drawing
# Gültigkeitsdauer eines Bildes: Man hat 10 Minuten Zeit, das Formular auszufüllen
LIFETIME = timedelta(minutes=10)
# Speicherschutz: Darüber hinaus werden alle ausstehenden Captchas vergessen
MAX_CAPTCHAS = 10_000
# ein Captcha: id, die in das versteckte Feld "captchaId" des Formulars zu legen ist;
# svg, das Bild, das unverändert in die Seite eingefügt wird
@dataclass(frozen=True)
class Captcha:
id: str
svg: str
class CaptchaService:
def __init__(self):
# id -> (erwartete Antwort, Ablaufdatum)
self._pending: dict[str, tuple[str, datetime]] = {}
self._lock = Lock()
def generate(self) -> Captcha:
text = captcha_drawing.random_text(5) # 5 Zeichen
id = secrets.token_urlsafe(16) # ein zufälliger Bezeichner, nicht zu erraten
with self._lock:
self._purge()
self._pending[id] = (text, datetime.now() + LIFETIME)
return Captcha(id, captcha_drawing.svg(text))
# true, wenn [typed] die richtige Antwort auf das Captcha [id] ist (unabhängig von der
# Groß-/Kleinschreibung). Das Captcha wird in jedem Fall verbraucht: Legen zwei
# Anfragen gleichzeitig dasselbe Captcha vor, entfernt es nur eine
# (pop, unter dem Lock) - die andere schlägt fehl.
def verify(self, id: str | None, typed: str | None) -> bool:
with self._lock:
expected = self._pending.pop(id, None) if id else None
if expected is None or typed is None:
return False
text, expires = expected
return expires > datetime.now() and text.lower() == typed.strip().lower()
# (unter dem Lock aufgerufen)
def _purge(self):
now = datetime.now()
for id in [id for id, (_, expires) in self._pending.items() if expires <= now]:
del self._pending[id]
if len(self._pending) >= MAX_CAPTCHAS:
self._pending.clear()
|
Der Service aus Beispiel 27, mit einer Ergänzung: Die Methode [_purge] (Zeilen 77–82), die bei jeder Erstellung eines CAPTCHA aufgerufen wird, verwirft abgelaufene CAPTCHAs. Ohne sie würden sich angezeigte, aber nie verwendete CAPTCHAs (etwa wenn eine Login-Seite geöffnet und dann verlassen wird) im Speicher ansammeln. [MAX_CAPTCHAS] dient als Sicherung: Ein Bot, der Millionen von Login-Seiten anfordert, könnte den Speicher des Servers nicht erschöpfen. Die Zahl [10_000] ist mit einem Unterstrich geschrieben, der die Tausender zur besseren Lesbarkeit trennt ([Python] ignoriert ihn). Die Liste der zu löschenden Bezeichner wird vor der Löschschleife erstellt: Man kann keine Schlüssel aus einem Dictionary löschen, während man darüber iteriert.
11.13.7. auth/limiter.py
| # =========================================================================
# auth/limiter.py
# -------------------------------------------------------------------------
# Zweite Verteidigungslinie gegen Roboter (die erste ist das Captcha): Wir ZÄHLEN
# die Versuche und SPERREN ab einem Schwellenwert für eine gewisse Zeit.
#
# - Login: Nach LOGIN_MAX_FAILURES Fehlversuchen (falsches Captcha oder falsches
# Passwort) für dasselbe Login von derselben IP-Adresse wird dieses Paar
# LOGIN_BLOCK_MINUTES Minuten lang gesperrt. Dieselbe IP-Adresse wird ebenfalls
# gesperrt, wenn sie 5-mal mehr Fehlversuche ansammelt, alle Logins zusammen (ein
# Roboter, der Tausende verschiedener Logins ausprobiert);
# - Kontoerstellung: höchstens REGISTRATION_MAX_PER_HOUR erstellte Konten
# pro Stunde von derselben IP-Adresse.
#
# Vorsicht im Unterrichtsraum: Alle Rechner gehen oft über dieselbe
# IP-Adresse ins Internet. Deshalb gilt die Login-Sperre
# zunächst für das Paar (IP, Login) - ein Student, der sich bei seinem
# Passwort vertippt, sperrt nicht seine Nachbarn - und deshalb lassen sich die Schwellenwerte
# in config.py einstellen.
#
# Ein einziges Objekt für den gesamten Server, das von parallelen Anfragen aufgerufen wird:
# Alle öffentlichen Methoden nehmen den Lock - immer nur ein Thread
# liest UND ändert die Zähler.
# =========================================================================
import math
from datetime import datetime, timedelta
from threading import Lock
ONE_HOUR = timedelta(hours=1)
class Counter:
def __init__(self, start: datetime):
self.number = 0 # im aktuellen Fenster gezählte Versuche
self.start = start # Beginn des Zählfensters
self.blocked_until = datetime.min # datetime.min, falls nicht gesperrt
class AttemptLimiter:
def __init__(self, login_max_failures: int, login_block_minutes: int,
registration_max_per_hour: int):
self._counters: dict[str, Counter] = {}
self._lock = Lock()
self._max_login_failures = login_max_failures
self._login_block_duration = timedelta(minutes=login_block_minutes)
self._max_registrations = registration_max_per_hour
# Anmeldung
# Anzahl der verbleibenden Sperrminuten (0 = der Versuch ist erlaubt)
def login_block_minutes(self, ip: str, login: str) -> int:
with self._lock:
return max(self._remaining_minutes(self._login_key(ip, login)),
self._remaining_minutes(self._ip_key(ip)))
def login_failure(self, ip: str, login: str):
with self._lock:
self._count(self._login_key(ip, login), self._max_login_failures,
self._login_block_duration, self._login_block_duration)
self._count(self._ip_key(ip), self._max_login_failures * 5,
self._login_block_duration, self._login_block_duration)
# eine erfolgreiche Anmeldung setzt den Zähler DIESES Logins zurück
def login_success(self, ip: str, login: str):
with self._lock:
self._counters.pop(self._login_key(ip, login), None)
# Registrierung
def registration_block_minutes(self, ip: str) -> int:
with self._lock:
return self._remaining_minutes(f"registration|{ip}")
# Fenster von einer Stunde; ist das Kontingent erreicht, wird bis zum Ende der Stunde gesperrt
def registration_success(self, ip: str):
with self._lock:
self._count(f"registration|{ip}", self._max_registrations, ONE_HOUR, ONE_HOUR)
# gemeinsame Mechanik
# (die privaten Methoden werden immer unter dem Lock aufgerufen)
def _remaining_minutes(self, key: str) -> int:
counter = self._counters.get(key)
if counter is None:
return 0
remaining = (counter.blocked_until - datetime.now()).total_seconds()
# auf die Minute AUFGERUNDET: 30 s verbleibende Sperre -> "1 minute"
return max(0, math.ceil(remaining / 60))
# zählt einen Versuch; wird der Schwellenwert innerhalb des Fensters erreicht, wird gesperrt
def _count(self, key: str, maximum: int, window: timedelta, block: timedelta):
now = datetime.now()
self._purge(now)
counter = self._counters.get(key)
if counter is None or now - counter.start > window:
counter = Counter(now)
self._counters[key] = counter
counter.number += 1
if counter.number >= maximum:
counter.blocked_until = now + block
counter.number = 0 # nach der Sperre beginnen wir wieder bei null
counter.start = counter.blocked_until
# Wir vergessen die nicht mehr nützlichen Zähler (weder gesperrt noch aktuell)
def _purge(self, now: datetime):
if len(self._counters) < 1000:
return
for key in [key for key, c in self._counters.items()
if c.blocked_until < now and now - c.start > ONE_HOUR]:
del self._counters[key]
@staticmethod
def _login_key(ip: str, login: str) -> str:
return f"login|{ip}|{login.strip().lower()}"
@staticmethod
def _ip_key(ip: str) -> str:
return f"ip|{ip}"
|
Eine vollständigere Version des Limiters aus Beispiel 27:
- Der Login-Block zielt zunächst auf das Paar (IP-Adresse, Login): In einem Klassenraum greifen oft alle Rechner über dieselbe IP-Adresse auf das Internet zu, und ein Schüler, der das falsche Passwort eingibt, soll seine Nachbarn nicht blockieren. Eine Adresse wird jedoch auch dann blockiert, wenn sie über alle Logins hinweg fünfmal so viele Fehlversuche ansammelt: Das ist bei einem Bot der Fall, der Tausende verschiedener Logins ausprobiert (Zeilen 57–61);
- Die Kontoerstellung ist auf eine bestimmte Anzahl von Konten pro Stunde und IP-Adresse begrenzt (Zeilen 71–78);
- Die Zähler werden in einem einzigen Dictionary gespeichert, unter Schlüsseln, denen ihr Verwendungszweck vorangestellt ist ([login|...], [ip|...], [registration|...]);
- Zeilen 92–103: Ein Zähler erfasst Versuche innerhalb eines Zeitfensters; ein Versuch nach Ablauf des Zeitfensters startet ein neues. Wird der Schwellenwert erreicht, wird der Schlüssel gesperrt und der Zähler auf null zurückgesetzt;
- Zeilen 106–111: Sobald der Zähler mehr als 1.000 Einträge enthält, werden die nicht mehr verwendeten (weder gesperrt noch aktuell) verworfen.
Wie das CAPTCHA speichert der Limiter seine Daten im Speicher des Prozesses: Das ist für eine Anwendung akzeptabel, die von einem einzigen Prozess bedient wird (der Entwicklungsserver, [Waitress]), nicht aber für mehrere Prozesse oder mehrere Server, die ihre Zähler nicht teilen würden (dann wäre ein gemeinsamer Speicher erforderlich, etwa [Redis]).
11.13.8. auth/registration_pass.py
| # =========================================================================
# auth/registration_pass.py
# -------------------------------------------------------------------------
# Der „Pass" für die Kontoerstellung.
#
# Um die Seite "Create a patient account" zu öffnen, muss man zuvor das Captcha
# der Authentifizierungsseite eingegeben haben (siehe
# controllers/registration.py, POST /register/access). Der Server stellt dann
# einen Pass aus:
# - eine zufällige Kennung, gespeichert in einem HttpOnly-Cookie;
# - 15 Minuten gültig (die Zeit zum Ausfüllen des Formulars, auch bei mehreren
# Versuchen nach Eingabefehlern);
# - verbraucht, sobald ein Konto erstellt wird: EIN gelöstes Captcha = höchstens EIN Konto.
# Ein Roboter kann keine Konten in Serie erstellen.
#
# Ohne gültigen Pass leiten GET und POST /register zur
# Authentifizierungsseite weiter: Die direkte Eingabe der URL /register erlaubt es nicht,
# das Captcha zu umgehen.
#
# Wie die Captchas leben die Pässe im Speicher des Prozesses.
# =========================================================================
import secrets
from datetime import datetime, timedelta
from threading import Lock
from flask import Response
COOKIE = "rdvmedecins_registration"
LIFETIME = timedelta(minutes=15)
MAX_PASSES = 10_000
class RegistrationPass:
def __init__(self):
# id -> Ablaufdatum
self._passes: dict[str, datetime] = {}
self._lock = Lock()
# stellt einen neuen Pass aus; gibt seine Kennung zurück
def issue(self) -> str:
id = secrets.token_urlsafe(16)
with self._lock:
self._purge()
self._passes[id] = datetime.now() + LIFETIME
return id
# true, wenn [id] ein vorhandener, nicht abgelaufener Pass ist
def is_valid(self, id: str | None) -> bool:
with self._lock:
expires = self._passes.get(id) if id else None
return expires is not None and expires > datetime.now()
# der Pass wurde verwendet: Er wird vergessen
def consume(self, id: str | None):
with self._lock:
self._passes.pop(id, None)
# (unter dem Lock aufgerufen)
def _purge(self):
now = datetime.now()
for id in [id for id, expires in self._passes.items() if expires <= now]:
del self._passes[id]
if len(self._passes) >= MAX_PASSES:
self._passes.clear()
# Das Cookie wird vom Browser nur an die /register-Adressen gesendet...
def set_cookie(response: Response, id: str, secure: bool):
response.set_cookie(COOKIE, id, max_age=LIFETIME, path="/register", httponly=True,
samesite="Lax", secure=secure)
# ... und es wird gelöscht, indem es erneut leer und mit der Lebensdauer null gesetzt wird
def clear_cookie(response: Response):
response.delete_cookie(COOKIE, path="/register")
|
Das Anlegen eines Patientenkontos ist eine öffentliche Seite: Ein Bot könnte massenhaft Konten erstellen. Sie ist daher durch das CAPTCHA der Login-Seite geschützt: Die Schaltfläche „Patientenkonto erstellen“ sendet dieses CAPTCHA an den Server, der bei korrekter Lösung ein Token ausstellt:
- Zeilen 42–47: ein zufälliger Bezeichner, 15 Minuten gültig, wie die CAPTCHAs im Speicher abgelegt;
- Zeilen 50–53: Die Registrierungsseite überprüft den Pass bei jeder Anfrage – GET wird genauso behandelt wie POST;
- Zeilen 56–58: Das Anlegen eines Kontos verbraucht den Pass: ein gelöstes CAPTCHA, höchstens ein Konto;
- Zeilen 70–72: Der Pass wird in einem Cookie gespeichert. Sein Attribut [path="/register"], begrenzt die Anfragen, an die der Browser es anhängt: nur Adressen, die mit [/register] beginnen;
- Zeilen 76–77: Um ein Cookie zu löschen, müssen Sie denselben Pfad angeben wie beim Setzen.
11.13.9. controllers/auth.py
Der Login-Controller, der alle diese Services verwendet.
| # =========================================================================
# controllers/auth.py
# -------------------------------------------------------------------------
# Die ÖFFENTLICHEN Routen der Anmeldung:
# GET / leitet zur Startseite der Rolle weiter (oder zu /login)
# GET /login zeigt das Login-Formular an (mit seinem Captcha)
# POST /login prüft Versuchsgrenze, Captcha, Login/Passwort
# POST /logout die Abmeldung
#
# Schutz gegen Roboter, in dieser Reihenfolge:
# 1. zu viele aktuelle Fehlversuche für dieses Login von dieser IP-Adresse?
# -> sofortige Ablehnung, ohne das Passwort überhaupt anzusehen;
# 2. falsche Antwort auf das Captcha? -> Ablehnung (als Fehlversuch gezählt);
# 3. erst dann die Überprüfung des Passworts.
# Das Passwort eines in Schritt 1 oder 2 abgelehnten Versuchs wird NIE
# geprüft: Ein Roboter kann daher durch Beharren nichts lernen.
# =========================================================================
from flask import Blueprint, g, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import public
from rdvmedecins.entities import Role
from rdvmedecins.models.view_models import LoginModel, Message
from rdvmedecins.web.services import auth_service, captchas, limiter
auth = Blueprint("auth", __name__)
# die Startseite jeder Rolle direkt nach der Anmeldung
def home_page(role: Role) -> str:
return url_for("area.patient_area") if role == Role.USER else url_for("schedule.show")
# die IP-Adresse des Besuchers. Hinter einem Reverse-Proxy (nginx ...) wäre es
# die des Proxys: Die Anwendung müsste dann in die
# ProxyFix-Middleware von Werkzeug eingebettet werden, die den Header X-Forwarded-For liest.
def ip_address() -> str:
return request.remote_addr or ""
# -----------------------------------------------------------------------
# GET /
# Die Route ist öffentlich: Der Benutzer wurde, falls vorhanden, durch
# auth/security.py ermittelt (g.user), aber es wird nichts verlangt.
# -----------------------------------------------------------------------
@auth.get("/")
@public
def home():
return redirect(home_page(g.user.role) if g.user else url_for("auth.show_login"))
# -----------------------------------------------------------------------
# GET /login[?login=xxx]: Der optionale Parameter füllt das Login-Feld
# vor (wird direkt nach der Erstellung eines Kontos verwendet, siehe controllers/registration.py)
# -----------------------------------------------------------------------
@auth.get("/login")
@public
def show_login():
# bereits angemeldet (Token noch gültig): direkt zur Startseite
if g.user:
return redirect(home_page(g.user.role))
return form(request.args.get("login", "")[:30], None)
# -----------------------------------------------------------------------
# POST /login
# request.form.get: Ein fehlendes Feld ergibt None (und keinen 400-Fehler) -
# der Code entscheidet, was damit geschieht.
# -----------------------------------------------------------------------
@auth.post("/login")
@public
def log_in():
login = (request.form.get("login") or "").strip()
password = request.form.get("password") or ""
ip = ip_address()
# 1. zu viele aktuelle Fehlversuche?
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return form(login, Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)}))
# 2. das Captcha
if not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, login)
return form(login, Message("ERRORS.WRONG_CAPTCHA"))
# 3. das Passwort
user = auth_service().validate_user(login, password) if login and password else None
if user is None:
limiter().login_failure(ip, login)
return form(login, Message("LOGIN.ERROR"))
limiter().login_success(ip, login)
response = redirect(home_page(user.role))
auth_service().set_token(response, user)
return response
# -----------------------------------------------------------------------
# POST /logout: das Cookie des Tokens löschen, dann zur Login-
# Seite gehen. Nur POST: Ein einfacher Link (GET) auf einer anderen Website
# kann den Benutzer nicht ohne sein Wissen abmelden.
# -----------------------------------------------------------------------
@auth.post("/logout")
@public
def log_out():
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# das Formular, immer mit einem NEUEN Captcha (jedes Bild wird nur einmal
# verwendet); das eingegebene Login wird erneut angezeigt, nie das Passwort
def form(login: str, error: Message | None):
model = LoginModel("LOGIN.TITLE", error, login, captchas().generate())
return render_template("login.html", model=model)
|
- Zeile 24: Gemeinsame Services werden über kleine Funktionen im Modul [web/services.py] (später behandelt) bezogen, die sie aus [app.extensions] abrufen;
- Zeilen 30–31: Jede Rolle hat ihre eigene Startseite: ein Patientenportal für Patienten und den Terminkalender für alle anderen;
- Zeilen 37–38: die IP-Adresse des Besuchers. Hinter einem Reverse-Proxy ([nginx], [Apache]) wäre dies die Adresse des Proxys, die für alle Besucher gleich ist: Die Anwendung müsste dann in die [ProxyFix]-Middleware von [Werkzeug] eingebettet werden (siehe das Kapitel zum Lebenszyklus), die die ursprüngliche Adresse aus dem vom Proxy hinzugefügten Header [X-Forwarded-For] liest;
- Zeilen 46–49: die öffentliche Wurzel der Site: Sie leitet auf die Startseite des Benutzers oder auf die Login-Seite weiter;
- Zeilen 56–62: die Login-Seite. Ein bereits angemeldeter Benutzer (dessen Token noch gültig ist) wird direkt auf seine Startseite geleitet. Der optionale Parameter [login] füllt das Feld vor (nach dem Anlegen eines Kontos); [[:30]] begrenzt seine Länge auf die eines Benutzernamens;
- Zeilen 70–96: der Login-Vorgang in drei Schritten, in dieser Reihenfolge: mögliche Sperre, das CAPTCHA und erst dann das Passwort. Ein in den ersten beiden Schritten abgelehnter Versuch prüft nie das Passwort: Ein Bot kann durch Beharrlichkeit nichts lernen. [request.form.get(...) or ""]: Ein leeres Feld liefert eine leere Zeichenkette. Die Fehlermeldung ist ein Objekt [Message]: ein Übersetzungsschlüssel und seine Parameter (später behandelt);
- Zeilen 104–109: Logout per POST (Beispiel 25). Er ist öffentlich: Ein Benutzer, dessen Sitzung abgelaufen ist, muss auf „Abmelden“ klicken können, ohne zuvor umgeleitet zu werden;
- Zeilen 114–116: die Login-Seite, weiterhin mit einem neuen CAPTCHA. Ihr Template ist ein Objekt [LoginModel] (siehe [models/view_models.py]).
Beachten Sie, dass das Login-Formular [WTForms] nicht verwendet: Seine drei Felder haben keine Validierungsregeln (ein leerer Benutzername führt einfach zu einem fehlgeschlagenen Login), und das Formular ist wie alle Formulare der Anwendung durch [CSRFProtect] gegen CSRF-Angriffe geschützt.
11.14. Die Web-Schicht: gemeinsame Services
Der Ordner [web] enthält, was den Controllern gemeinsam ist. Jedes Modul darin beantwortet eine Frage, die sich alle Controller stellen: wie man einen Service erhält, einen Text übersetzt, nach einer Weiterleitung eine Meldung anzeigt, ein abgelehntes Formular erneut anzeigt oder einen Fehler in eine Seite umwandelt.
11.14.1. web/services.py
| # =========================================================================
# web/services.py
# -------------------------------------------------------------------------
# Die gemeinsamen Objekte der Anwendung (siehe Beispiel 06): Sie werden EINMAL
# von der Application Factory (rdvmedecins/__init__.py) erstellt und
# im Dictionary app.extensions abgelegt. Diese kleinen Funktionen finden
# sie dort für die Anwendung, die die aktuelle Anfrage verarbeitet
# (current_app); sie geben außerdem den Analysewerkzeugen ihren TYP an.
# =========================================================================
from flask import current_app
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.web.application_model import ApplicationModel
def application() -> ApplicationModel:
return current_app.extensions["rdvmedecins.application"]
def auth_service() -> AuthService:
return current_app.extensions["rdvmedecins.auth"]
def captchas() -> CaptchaService:
return current_app.extensions["rdvmedecins.captchas"]
def limiter() -> AttemptLimiter:
return current_app.extensions["rdvmedecins.limiter"]
def passes() -> RegistrationPass:
return current_app.extensions["rdvmedecins.passes"]
|
Die gemeinsamen Objekte, die von der Factory erstellt und in [app.extensions] abgelegt werden, werden über diese kleinen Funktionen abgerufen (Beispiel 06). Sie ersparen es, den Dictionary-Schlüssel in jedem Controller zu wiederholen, und liefern Analysewerkzeugen ihren Typ : In einem Controller weiß der Editor, dass [application()] ein [ApplicationModel] ist, und bietet dessen Methoden an.
11.14.2. web/translator.py
| # =========================================================================
# web/translator.py
# -------------------------------------------------------------------------
# Französisch-/Englisch-Übersetzung der Oberfläche (siehe Beispiel 22).
#
# Die Wörterbücher sind DIESELBEN Dateien wie bei den Versionen der Anwendung mit NestJS,
# ASP.NET Core und Spring MVC (i18n/fr.json, i18n/en.json),
# die nur einmal beim Start gelesen werden.
#
# In den Views die Funktion t (siehe web/common_model.py):
# {{ t("LOGIN.TITLE") }} ohne Parameter;
# {{ t("AREA.HELLO", name=model.patient) }} benannte Parameter;
# {{ t(message.key, message.params) }} ein Dictionary von Parametern.
#
# DIE AKTUELLE SPRACHE: g.language, bei jeder Anfrage aus einem Cookie gesetzt
# (siehe rdvmedecins/__init__.py, Funktion set_language).
# =========================================================================
import json
import re
from pathlib import Path
from flask import g
LANGUAGES = ("fr", "en")
DEFAULT_LANGUAGE = "en"
# das Cookie, das die gewählte Sprache speichert (siehe controllers/language.py)
LANGUAGE_COOKIE = "rdvmedecins_language"
# {name}: ein Parameter in einem Text
PARAMETER = re.compile(r"\{(\w+)\}")
# die unterstützte Sprache, die zu [code] passt: "fr" -> "fr"; "de" oder None -> "en"
def language(code: str | None) -> str:
return code if code in LANGUAGES else DEFAULT_LANGUAGE
class Translator:
def __init__(self, folder: Path):
# Sprache -> (vollständiger Schlüssel "LOGIN.TITLE" -> Text)
self._dictionaries: dict[str, dict[str, str]] = {}
for code in LANGUAGES:
with open(folder / f"{code}.json", encoding="utf-8") as file:
self._dictionaries[code] = self._flatten(json.load(file))
# -----------------------------------------------------------------------
# translate("DOCTORS.ADDED", {"name": "Marie PELISSIER"})
# -> sucht "DOCTORS.ADDED" im Wörterbuch der Sprache und
# ersetzt {name} durch seinen Wert. Ein in der angeforderten Sprache fehlender Schlüssel
# wird auf Englisch gesucht; fehlt er überall, wird der Schlüssel selbst
# angezeigt (ein Fehler fällt so sofort auf).
# Die Parameter: ein Dictionary und/oder benannte Parameter.
# -----------------------------------------------------------------------
def translate(self, key: str | None, params: dict | None = None, **others) -> str:
if not key:
return ""
text = self._dictionaries[language(g.get("language"))].get(key)
if text is None:
text = self._dictionaries[DEFAULT_LANGUAGE].get(key, key)
values = {**(params or {}), **others}
if not values:
return text
return PARAMETER.sub(lambda m: str(values.get(m.group(1), m.group(0))), text)
# { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
@classmethod
def _flatten(cls, node: dict, prefix: str = "") -> dict[str, str]:
result = {}
for key, value in node.items():
full_key = f"{prefix}.{key}" if prefix else key
if isinstance(value, dict):
result.update(cls._flatten(value, full_key))
else:
result[full_key] = value
return result
|
Der Translator aus Beispiel 22, mit drei Ergänzungen:
- Zeilen 56–65: Die Parameter eines Textes können über ein Dictionary (den zweiten Parameter [params]), über benannte Parameter ([**others]) oder über beides geliefert werden. Meldungen der Anwendung (die Klasse [Message], später behandelt) tragen ihre Parameter in einem Dictionary; Views bevorzugen dagegen benannte Parameter. [{**a, **b}] erzeugt ein Dictionary, das die von [a] und [b] vereint;
- Zeile 61: Ein in der angeforderten Sprache fehlender Schlüssel wird zunächst auf Englisch nachgeschlagen, bevor er unverändert angezeigt wird;
- Zeile 59: [g.get("language")] liefert [None] , wenn [g] das Attribut [language] nicht besitzt, anstatt eine Ausnahme auszulösen: Der Translator funktioniert auch dann, wenn ein Fehler vor der Funktion [before_request] auftritt, die die Sprache festlegt.
Dem Namen des Sprach-Cookies ist der Name der Anwendung vorangestellt ([rdvmedecins_language]), genau wie bei Token und Pass: Cookies sind einem Domainnamen ([localhost]) zugeordnet, nicht einem Port. Die Beispiele, die ebenfalls über [localhost] bereitgestellt werden, könnten sonst die Cookies der Anwendung lesen.
11.14.3. web/common_model.py
| # =========================================================================
# web/common_model.py
# -------------------------------------------------------------------------
# Was ALLE Views benötigen, unabhängig von der Seite (siehe Beispiel
# 15): Ein „Context Processor", der vor dem Erstellen jeder View
# ausgeführt wird, fügt seine Variablen dem Modell aller Views hinzu:
# - user : der angemeldete Benutzer (oder None) für die Navigationsleiste;
# - language : "fr" oder "en";
# - path : die angeforderte URL (aktives Menü der Navigationsleiste,
# Link "Another image" des Captchas);
# - t : die Übersetzungsfunktion (siehe web/translator.py).
# Die Flash-Nachrichten werden vom Layout gelesen (get_flashed_messages).
# =========================================================================
from flask import g, request
from rdvmedecins.web.translator import Translator
def register(app, translator: Translator):
@app.context_processor
def common_model():
return {
"user": g.get("user"),
"language": g.get("language", "en"),
"path": request.path,
"t": translator.translate,
}
|
Der Context Processor aus Beispiel 15: vier Variablen, die in allen Views verfügbar sind, ohne dass die Aktionen sie liefern müssen: der angemeldete Benutzer (für die Navigationsleiste), die Sprache (für das Attribut [lang] der Seite und die Schaltflächen FR / EN), der Pfad der angeforderten URL (für das aktive Menü und den Link „Anderes Bild“ im CAPTCHA) und die Übersetzungsfunktion [t]. [g.get("user")] liefert [None] , wenn das Attribut nicht existiert (zum Beispiel bei einer vor der Authentifizierung erzeugten Fehlerseite).
11.14.4. web/flash.py
| # =========================================================================
# web/flash.py
# -------------------------------------------------------------------------
# Die „Flash"-Nachrichten: eine Nachricht, die EINMAL auf der NÄCHSTEN
# Seite angezeigt wird (siehe Beispiel 20). Sie ist die natürliche Ergänzung des
# Musters „Post / Redirect / Get", das alle Formulare der Anwendung nutzen:
# Ein erfolgreicher POST erstellt keine Seite, sondern leitet (302) auf eine
# GET-Seite um; die Nachricht muss die Umleitung jedoch überstehen.
#
# Flask speichert sie in der SESSION, also in einem durch den
# geheimen Schlüssel (SECRET_KEY) SIGNIERTEN Cookie: Der Server bleibt ZUSTANDSLOS, er behält zwischen zwei Anfragen nichts im
# Speicher. Der Browser kann dieses Cookie lesen (es ist
# nicht verschlüsselt), aber nicht ändern, ohne dass die Signatur ihn verrät.
#
# Eine Nachricht enthält keinen Text, sondern einen Übersetzungsschlüssel (KEY) und seine
# Parameter: Sie wird bei der Anzeige in der Sprache
# der Seite übersetzt (siehe templates/layout.html). Ihre Kategorie: "success" (oben auf der
# Seite angezeigt) oder "danger" (ein Fehler, unten angezeigt).
# =========================================================================
from flask import flash
def flash_success(key: str, **params):
flash({"key": key, "params": params}, "success")
def flash_error(key: str, **params):
flash({"key": key, "params": params}, "danger")
|
Die Flash-Meldungen aus Beispiel 20. Eine Meldung ist kein Text, sondern ein Dictionary: der Übersetzungsschlüssel und seine Parameter. Sie wird erst bei der Anzeige durch das Template in die Sprache der Seite übersetzt. [Flask] speichert die Meldungen in der Session, die ein Cookie ist: Dazu wandelt es sie in JSON um, das ein Dictionary aus Zeichenketten akzeptiert. Die Kategorie der Meldung ([success] oder [danger], die Farbnamen von [Bootstrap]) bestimmt ihre Position: bei einem Erfolg am oberen Seitenrand, bei einem Fehler am unteren.
11.14.5. web/errors.py
| # =========================================================================
# web/errors.py
# -------------------------------------------------------------------------
# Wie aus den Fehlern HTML-Seiten werden. Drei Handler teilen sich
# die Arbeit (siehe Beispiel 24):
#
# 1. eine InvalidSession (seit der Anmeldung gelöschtes Konto) -> zurück zur
# Login-Seite, wie bei einer abgelaufenen Sitzung;
# 2. ein HTTP-Fehler: abort(400), abort(403) (unzureichende Rolle), unbekannte
# Seite (404), nicht unterstützte Methode (405), fehlendes oder falsches Anti-CSRF-Token
# (400) ... -> die Fehlerseite mit dem ursprünglichen Code;
# 3. jede andere Ausnahme (eine echte Anomalie) -> wird mit ihrem Stacktrace in das Log
# des Servers geschrieben; der Benutzer sieht die
# 500-Fehlerseite - nie den Stacktrace.
# =========================================================================
from flask import current_app, redirect, render_template, url_for
from werkzeug.exceptions import HTTPException
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.models.view_models import ErrorModel
from rdvmedecins.web.flash import flash_error
MESSAGES = {
400: "ERRORS.BAD_REQUEST",
403: "ERRORS.FORBIDDEN",
404: "ERRORS.NOT_FOUND",
}
def error_page(code: int):
model = ErrorModel("ERROR_PAGE.TITLE", None, code, MESSAGES.get(code, "ERRORS.SERVER_ERROR"))
# die Seite behält den Fehlercode (404 bleibt 404 ...)
return render_template("error.html", model=model), code
def register(app):
@app.errorhandler(InvalidSession)
def invalid_session(e):
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
@app.errorhandler(HTTPException)
def http_error(e: HTTPException):
return error_page(e.code or 500)
# Exception: die Elternklasse aller Ausnahmen; dieser Handler
# erhält nur diejenigen, die kein spezifischerer Handler verarbeitet hat
@app.errorhandler(Exception)
def anomaly(e: Exception):
current_app.logger.exception("unexpected error")
return error_page(500)
|
Die Fehler-Handler aus Beispiel 24:
- Zeilen 31–34: die Fehlerseite mit dem ursprünglichen Fehlercode (eine 404-Seite bleibt eine 404-Antwort) und einer übersetzten Meldung, die anhand des Codes ausgewählt wird;
- Zeilen 39–44: ein seit dem Login gelöschtes Konto: Weiterleitung auf die Login-Seite, wie bei einer abgelaufenen Sitzung;
- Zeilen 46–48: alle HTTP-Fehler: [abort(403)], eine unbekannte Seite (404), eine verbotene Methode (405), ein fehlendes oder ungültiges Anti-CSRF-Token (400, behandelt von [CSRFProtect]) ...;
- Zeilen 52–55: jede andere Ausnahme, also eine echte Anomalie (ein Programmierfehler, eine unerreichbar gewordene Datenbank). [current_app.logger] ist das Log der Anwendung (ein Objekt des Standardmoduls [logging]); seine Methode [exception] schreibt die Meldung dorthin, gefolgt vom Aufrufstapel der aktuellen Ausnahme. Der Benutzer sieht jedoch nur die 500-Fehlerseite: niemals den Aufrufstapel, der interne Details der Anwendung preisgeben würde. [Flask] wählt immer den spezifischsten Handler: Ein HTTP-Fehler wird vom zweiten Handler behandelt, nicht von diesem.
11.14.6. web/application_model.py
| # =========================================================================
# web/application_model.py
# -------------------------------------------------------------------------
# Der Cache / die Fassade der Geschäftsschicht (das Äquivalent der Klasse
# [ApplicationModel] der vorherigen Versionen der Anwendung): Die
# Listen der Ärzte und der Clients werden einmal beim Start gelesen und dann
# aus dem Speicher geliefert.
#
# Diese Listen können sich ÄNDERN (der ADMIN fügt Ärzte und Clients hinzu, bearbeitet und
# löscht sie): Jeder Schreibvorgang läuft daher über diese Fassade,
# die die betroffene Liste anschließend neu lädt. Das ist der ganze Sinn eines
# EINZIGEN Einstiegspunkts in die Geschäftsschicht: Die Regel „Schreiben =>
# Cache neu laden" steht nur hier.
#
# Ein einziges Objekt für die gesamte Anwendung, das von
# parallel verarbeiteten Anfragen in mehreren Threads verwendet wird. Eine Liste wird daher nie an Ort und Stelle geändert:
# Sie wird vollständig durch eine neue ERSETZT. In Python
# ist die Zuweisung eines Attributs atomar: Ein Thread, der die Liste liest, sieht
# die alte oder die neue, nie eine halb aufgebaute Liste.
# =========================================================================
from datetime import date
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.business import Business
# derselbe Vertrag wie die Geschäftsschicht (Business)
class ApplicationModel:
def __init__(self, business: Business):
self._business = business
# anfängliches Laden der beiden Listen beim Start der Anwendung.
# Ein Lesefehler (nicht erreichbare Datenbank ...) wird nicht abgefangen:
# Er stoppt den Server, statt ihn „leer" starten zu lassen
self._doctors: list[Doctor] = []
self._clients: list[Client] = []
self._reload_doctors()
self._reload_clients()
def _reload_doctors(self):
self._doctors = list(self._business.get_all_doctors())
def _reload_clients(self):
self._clients = list(self._business.get_all_clients())
# Lesezugriffe auf den Cache
def get_all_doctors(self) -> list[Doctor]:
return self._doctors
def get_all_clients(self) -> list[Client]:
return self._clients
# der Arzt, dessen Benutzerkonto [user_id] ist - dient dazu, bei einem
# angemeldeten Arzt dessen eigenen Terminkalender vorzuwählen
def get_doctor_by_user_id(self, user_id: int) -> Doctor | None:
return next((d for d in self._doctors if d.user_id == user_id), None)
# einfache Delegationen
def get_all_slots(self, doctor_id: int) -> list[Slot]:
return self._business.get_all_slots(doctor_id)
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
return self._business.get_doctor_day_appointments(doctor_id, day)
def get_client_by_id(self, id: int) -> Client | None:
return self._business.get_client_by_id(id)
def get_doctor_by_id(self, id: int) -> Doctor | None:
return self._business.get_doctor_by_id(id)
def get_appointment_by_id(self, id: int) -> Appointment | None:
return self._business.get_appointment_by_id(id)
def get_slot_by_id(self, id: int) -> Slot | None:
return self._business.get_slot_by_id(id)
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
return self._business.get_doctor_day_schedule(doctor_id, day)
# hier kein Cache: Es kommt auf die aktuellsten Daten an (ein Patient,
# der gerade sein Konto bearbeitet oder gelöscht hat)
def get_client_by_user_id(self, user_id: int) -> Client | None:
return self._business.get_client_by_user_id(user_id)
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
return self._business.get_client_upcoming_appointments(client_id)
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
return self._business.add_appointment(day, slot, client)
def delete_appointment(self, appointment: Appointment) -> None:
self._business.delete_appointment(appointment)
# Schreibzugriffe => Neuladen
def add_doctor(self, data: PersonData) -> Doctor:
doctor = self._business.add_doctor(data)
self._reload_doctors()
return doctor
def edit_doctor(self, id: int, data: PersonData) -> Doctor:
doctor = self._business.edit_doctor(id, data)
self._reload_doctors()
return doctor
def delete_doctor(self, id: int) -> None:
self._business.delete_doctor(id)
self._reload_doctors()
def add_client(self, data: PersonData) -> Client:
client = self._business.add_client(data)
self._reload_clients()
return client
def edit_client(self, id: int, data: PersonData) -> Client:
client = self._business.edit_client(id, data)
self._reload_clients()
return client
def delete_client(self, id: int) -> None:
self._business.delete_client(id)
self._reload_clients()
|
Der Cache der Web-Schicht und seine Schnittstelle zur Geschäftsschicht:
- Zeilen 32–40: Die Listen der Ärzte und Patienten werden einmalig beim Start gelesen. Sie werden bei jeder Anzeige des Kalenders verwendet (die Dropdown-Liste der Ärzte, die Liste der Patienten): Sie im Speicher zu halten erspart zwei SQL-Anfragen pro Seite. Ein Lesefehler wird nicht abgefangen: Er lässt die Anwendung beim Start abstürzen (siehe „Häufige Probleme“);
- Zeilen 50–59: aus dem Cache abgerufene Daten. [get_doctor_by_user_id] identifiziert den angemeldeten Arzt, um dessen eigenen Kalender vorauszuwählen;
- Zeilen 63–96: Die übrigen Lesevorgänge und die Termine werden einfach an die Geschäftsschicht weitergereicht. [get_client_by_user_id] verwendet den Cache nicht: Ein Patient, der sein Konto gerade geändert oder gelöscht hat, muss die aktuellsten Daten sehen;
- Zeilen 100–126: Jede Aktualisierung bei Ärzten oder Clients aktualisiert die betreffende Liste. Das ist der Vorteil eines einzigen Einstiegspunkts zur Geschäftsschicht: Die Regel „aktualisieren, dann den Cache auffrischen“ ist nur hier implementiert.
Dieses eindeutige Objekt wird von Anfragen verwendet, die parallel in mehreren Threads verarbeitet werden: Daher wird eine Liste niemals an Ort und Stelle geändert (mit [append] oder [remove]); stattdessen wird sie vollständig durch eine neue ersetzt. In [Python] ist die Zuweisung eines Attributs atomar: Ein Thread, der die Liste liest, sieht entweder die alte oder die neue Version, nie eine nur teilweise aufgebaute Liste. Deshalb ist keine Sperre nötig.
[ApplicationModel] hält den Vertrag [Business] ein (es hat dieselben Methoden wie [BusinessService]): Für die Controller ist es die Geschäftsschicht. Wir könnten den Cache entfernen, ohne die Controller anzufassen, indem wir [BusinessService] direkt in [app.extensions] ablegen.
11.14.7. web/validation.py
| # =========================================================================
# web/validation.py
# -------------------------------------------------------------------------
# Was nötig ist, um ein abgelehntes Formular ERNEUT anzuzeigen: die Eingabefehler
# Feld für Feld und die rot umrandeten Felder.
# =========================================================================
from flask_wtf import FlaskForm
from rdvmedecins.models.view_models import FormState, Message
# -----------------------------------------------------------------------
# das validierte Formular (siehe forms/forms.py) -> das Dictionary
# Feld -> Schlüssel der Nachricht, wobei nur die erste Nachricht jedes
# Feldes behalten wird: { "last_name": "ERRORS.LASTNAME_REQUIRED", ... }
#
# Unsere Nachrichten sind Übersetzungsschlüssel ("ERRORS...."). Eine Nachricht, die
# WTForms selbst (auf Englisch) verfasst hat, wird durch den Schlüssel
# ERRORS.INVALID_FORM ersetzt.
# -----------------------------------------------------------------------
def errors_of(form: FlaskForm) -> dict[str, str]:
errors = {}
for field, messages in form.errors.items():
message = str(messages[0])
errors[field] = message if message.startswith("ERRORS.") else "ERRORS.INVALID_FORM"
return errors
# -----------------------------------------------------------------------
# die von jedem „Eingabe"-Geschäftsfehler betroffenen Formularfelder
# (ein Duplikat): Sie werden rot umrandet, die Nachricht steht unten auf der Seite
# -----------------------------------------------------------------------
BUSINESS_ERROR_FIELDS = {
"ERRORS.LOGIN_TAKEN": ["login"],
"ERRORS.DOCTOR_ALREADY_EXISTS": ["first_name", "last_name"],
"ERRORS.PATIENT_ALREADY_EXISTS": ["first_name", "last_name"],
}
# der Zustand eines (erneut) anzuzeigenden Formulars: eine Nachricht unter jedem
# von der Validierung abgelehnten Feld (errors) und die rot zu umrandenden Felder,
# diese plus eventuell weitere (other_fields)
def state(errors: dict[str, str], other_fields: list[str] | None = None) -> FormState:
return FormState(dict(errors), set(errors) | set(other_fields or []))
# DIE Fehlermeldung der Seite, unten auf der Seite angezeigt: [error], falls
# vorhanden, sonst "The form contains errors.", falls es
# Feldfehler gibt, sonst nichts
def page_message(errors: dict[str, str], error: Message | None) -> Message | None:
if error is not None:
return error
return Message("ERRORS.INVALID_FORM") if errors else None
|
Was zum erneuten Anzeigen eines abgelehnten Formulars nötig ist:
- Zeilen 21–26: die Fehler eines [WTForms]-Formulars (Beispiel 19) in Form eines Dictionarys „Feld → Meldungsschlüssel“, wobei für jedes Feld nur die erste Meldung behalten wird. Die Meldungen unserer Validatoren sind Übersetzungsschlüssel ([ERRORS.LASTNAME_REQUIRED], siehe [forms/forms.py]); eine Meldung, die [WTForms] selbst auf Englisch erzeugt hätte, wird durch einen generischen Schlüssel ersetzt;
- Zeilen 33–36: Einige Fehler der Geschäftslogik betreffen bestimmte Felder, etwa einen bereits vergebenen Benutzernamen oder einen gleich geschriebenen Namen. Ihre Fehlermeldungen erscheinen am Seitenende, aber die betroffenen Felder werden rot hervorgehoben, damit der Benutzer sofort sieht, was zu korrigieren ist (siehe den Screenshot zum gleich geschriebenen Namen oben);
- Zeilen 43–44: der Zustand eines erneut anzuzeigenden Formulars: die Meldungen unter den Feldern und alle rot hervorzuhebenden Felder. [set(errors)] ist die Menge der Schlüssel des Dictionarys; der Operator [|] bildet die Vereinigung zweier Mengen;
- Zeilen 50–53: die allgemeine Meldung im Fußbereich.
11.14.8. web/utils.py
| # =========================================================================
# web/utils.py
# -------------------------------------------------------------------------
# Kleine Hilfsfunktionen der Web-Schicht:
# - Bezeichnungen: "Mme Alice DURAND";
# - Datumsangaben: "yyyy-mm-dd", Uhrzeiten "8:05", Tage "Wednesday 23 September 2026";
# - Eingabe: Lesen einer positiven ganzen Zahl, die vom Browser gesendet wird;
# - Benutzer: der angemeldete Benutzer und sein Patient (Entität Client).
# =========================================================================
import re
from datetime import date, datetime
from babel.dates import format_date
from flask import g
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import Client, Slot, Person
# Bezeichnungen
# "Mme Alice DURAND"
def label(p: Person) -> str:
return f"{p.title} {p.first_name} {p.last_name}"
# Datumsangaben
# das Format der Datumsangaben in den URLs und im Feld <input type="date">
ISO_FORMAT = re.compile(r"\d{4}-\d{2}-\d{2}")
# das Datum, wenn [text] ein existierendes Datum im Format yyyy-mm-dd ist; sonst None.
# strptime prüft, ob das Datum existiert: "2026-02-30" wird abgelehnt
def valid_date(text: str | None) -> date | None:
if text is None or not ISO_FORMAT.fullmatch(text):
return None
try:
return datetime.strptime(text, "%Y-%m-%d").date()
except ValueError:
return None
def iso(day: date) -> str:
return day.isoformat()
# "8:05" statt "8:5"
def format_time(h: int, m: int) -> str:
return f"{h}:{m:02d}"
def time(s: Slot) -> str:
return f"{format_time(s.start_hour, s.start_minute)} - {format_time(s.end_hour, s.end_minute)}"
# "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", je nach
# Sprache der Anfrage (g.language). Das Babel-Format: EEEE der ausgeschriebene Wochentag,
# d der Tag, MMMM der ausgeschriebene Monat, y das Jahr
def format_day(day: date) -> str:
return format_date(day, "EEEE d MMMM y", locale=g.language)
# Eingabe
# "3" -> 3 ; "", "abc", "-2", "+2", None -> None
def positive_integer(value: str | None) -> int | None:
if value is None or not re.fullmatch(r"\d{1,9}", value):
return None
n = int(value)
return n if n > 0 else None
# Benutzer
# der angemeldete Benutzer (siehe auth/security.py). Die geschützten Aktionen werden
# nur aufgerufen, wenn er existiert; vorsichtshalber wird sein Fehlen
# wie eine abgelaufene Sitzung behandelt.
def user() -> ConnectedUser:
if g.user is None:
raise InvalidSession()
return g.user
# -----------------------------------------------------------------------
# Der Patient (Entität Client), der dem angemeldeten Benutzer entspricht.
#
# Das JWT-Token enthält nur die ID des KONTOS (users.id). Für eine Rolle USER
# wird der zugehörige Client über die Spalte clients.user gefunden.
#
# Gibt es keinen, wurde das Konto seit der
# Anmeldung gelöscht, während sein Token noch gültig ist: Es wird wie eine abgelaufene
# Sitzung behandelt (siehe InvalidSession).
# -----------------------------------------------------------------------
def connected_patient(application) -> Client:
patient = application.get_client_by_user_id(user().user_id)
if patient is None:
raise InvalidSession()
return patient
|
Hilfsfunktionen, die von mehreren Controllern verwendet werden:
- Zeile 24: die Anrede einer Person, „Mme Alice DURAND“;
- Zeilen 31–42: Parsen eines Datums im Format [yyyy-mm-dd], das dem Format der URL-Eingaben im Kalender ([day=2026-09-26]) und des Felds [<input type="date">] entspricht. Der reguläre Ausdruck prüft das Format ([fullmatch]: die gesamte Zeichenkette muss passen), während [strptime] die Existenz des Datums prüft. Ein ungültiges Datum ergibt [None]: Die Aktion entscheidet über das weitere Vorgehen;
- Zeilen 50–51: Das Format [02d] gibt eine zweistellige, mit Nullen aufgefüllte Ganzzahl aus: [8:05];
- Zeilen 61–62: ein ausgeschriebenes Datum in der Sprache der Anfrage, mit [Babel] (Beispiel 16). Das Format wird hier ausdrücklich angegeben: [EEEE], der ausgeschriebene Wochentag; [d], der Tag; [MMMM], der ausgeschriebene Monat; [y], das Jahr;
- Zeilen 69–73: Lesen eines vom Browser gesendeten Bezeichners (ein URL-Parameter, ein verstecktes Feld). [\d{1,9}]: eine bis neun Ziffern, was Buchstaben, Leerzeichen und für eine [INT]-Spalte zu große Zahlen ausschließt. Alles, was vom Browser kommt, kann verändert worden sein: Es muss vor der Verwendung überprüft werden;
- Zeilen 82–85: der angemeldete Benutzer; sein Fehlen (das in einer geschützten Aktion nicht vorkommen dürfte) wird wie eine abgelaufene Sitzung behandelt;
- Zeilen 98–102: der Patient (die Entität [Client]), der dem angemeldeten Benutzer entspricht. Das Token enthält nur die ID des Kontos: Der Patient wird über die Spalte [clients.user] identifiziert. Existiert er nicht, bedeutet das, dass das Konto seit dem Login des Benutzers gelöscht wurde.
| # =========================================================================
# forms/rules.py
# -------------------------------------------------------------------------
# Die gemeinsamen Eingaberegeln der „Personen"-Formulare und die FILTER
# von WTForms (siehe Beispiel 19): Funktionen, die den empfangenen Wert
# VOR der Validierung umwandeln.
# =========================================================================
TITLES = ("Mr", "Mme", "Melle")
# Login: Kleinbuchstaben, Ziffern, Punkt, Bindestrich, Unterstrich - höchstens 30 Zeichen
LOGIN_FORMAT = r"^[a-z0-9._-]{1,30}$"
# Mindestlänge eines von einem Patienten GEWÄHLTEN Passworts
PASSWORD_MIN = 6
# " dupont " -> "dupont" ; " " -> None
def clean(value):
if not isinstance(value, str):
return value
return value.strip() or None
# " Dupont " -> "dupont": Ein Login ist immer kleingeschrieben
def login(value):
value = clean(value)
return value.lower() if isinstance(value, str) else value
# ein leeres Feld -> None; bei einem Passwort werden die Leerzeichen NICHT entfernt
# (sie können Teil davon sein)
def empty_to_none(value):
return value if value else None
# das versteckte Feld [version]: eine ganze Zahl oder None, falls es fehlt oder leer ist.
# Ein Text, der keine Zahl ist: ein ValueError, den WTForms in einen
# Feldfehler mit dieser Nachricht (einem Übersetzungsschlüssel) umwandelt
def version(value):
if value in (None, ""):
return None
try:
return int(value)
except (TypeError, ValueError):
raise ValueError("ERRORS.INVALID_FORM")
|
Eingaberegeln, die allen Formularen gemeinsam sind, und die [WTForms]-Filter (Beispiel 19):
- Zeilen 8–14: erlaubte Anreden, das Format eines Benutzernamens (Kleinbuchstaben, Ziffern, Punkt, Bindestrich, Unterstrich, bis zu 30 Zeichen) und die Mindestlänge eines von einem Patienten gewählten Passworts;
- Zeilen 18–21: Die Leerzeichen um eine Eingabe werden entfernt; eine leere Eingabe wird zu [None]. [a or b] entspricht [b] , wenn [a] „falsch“ ist (hier eine leere Zeichenkette);
- Zeilen 25–27: Ein Benutzername steht immer in Kleinbuchstaben;
- Zeilen 32–33: Bei einem Passwort werden Leerzeichen nicht entfernt, da sie Teil des Passworts sein können;
- Zeilen 39–45: das versteckte Versionsfeld (das optimistische Sperren): eine Ganzzahl oder [None]. Ein Filter, der einen Wert wie [ValueError] auslöst, führt zu einem Feldfehler, wobei die Fehlermeldung der der Ausnahme entspricht: Ein Browser, der etwas anderes als eine Zahl sendet, erhielte den Fehler „ungültiges Formular“.
| # =========================================================================
# forms/forms.py
# -------------------------------------------------------------------------
# Die Felder der „Personen"-Formulare und ihre Einschränkungen (siehe Beispiele
# 19 und 28). Drei Formulare teilen sich dieselben Identitätsfelder
# (Anrede, Vorname, Nachname):
#
# PersonFields Anrede, Vorname, Nachname
# ├─ PersonForm + OPTIONALES Login / Passwort, Version
# │ (der ADMIN fügt einen Arzt / Client hinzu oder bearbeitet ihn)
# ├─ RegistrationForm + OBLIGATORISCHES Login / Passwort / Bestätigung
# │ (ein Patient erstellt sein Konto)
# └─ MyAccountForm + Login, optionales neues Passwort,
# obligatorisches AKTUELLES Passwort, Version
# (ein Patient bearbeitet sein Konto)
#
# Eine WTForms-Klasse, die von einer anderen erbt, erbt auch deren Felder.
#
# BINDING: PersonForm() liest selbst die gleichnamigen Felder der
# aktuellen POST-Anfrage (request.form) und wendet seine Filter darauf an
# (überflüssige Leerzeichen entfernt, Login in Kleinbuchstaben ...).
# VALIDIERUNG: form.validate() prüft dann die Einschränkungen jedes
# Feldes der Reihe nach; die erste, die fehlschlägt, speichert ihre Nachricht in
# form.<field>.errors. Diese Meldungen sind Übersetzungs-SCHLÜSSEL (siehe i18n/*.json).
#
# Die Formulare dienen hier nur dazu, die Eingabe zu lesen und zu validieren: Die Views
# schreiben ihre <input>-Tags selbst, ausgehend von den View-Modellen
# (siehe models/view_models.py).
# =========================================================================
from flask_wtf import FlaskForm
from wtforms import PasswordField, StringField
from wtforms.validators import AnyOf, DataRequired, InputRequired, Length, Optional, Regexp
from rdvmedecins.forms import rules
# gemeinsame Basis
class PersonFields(FlaskForm):
title = StringField(validators=[AnyOf(rules.TITLES, message="ERRORS.INVALID_TITLE")])
# Maximallängen = die der SQL-Spalten (VARCHAR(20)).
# DataRequired beendet die Validierung des Feldes, wenn es leer ist: Die Nachricht
# von Length wird diesem Feld daher nie hinzugefügt
first_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.FIRSTNAME_REQUIRED"),
Length(max=20, message="ERRORS.FIRSTNAME_TOO_LONG")])
last_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.LASTNAME_REQUIRED"),
Length(max=20, message="ERRORS.LASTNAME_TOO_LONG")])
# ADMIN
class PersonForm(PersonFields):
# optional (siehe business/person_data.py): Optional beendet die Validierung eines
# leeren Feldes ohne Fehler
login = StringField(filters=[rules.login], validators=[
Optional(), Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# optional; höchstens 72 Zeichen (darüber hinaus ignoriert bcrypt den Rest)
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False), Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
# verstecktes Feld des Bearbeitungsformulars (optimistisches Sperren)
version = StringField(filters=[rules.version])
# Registrierung eines Patienten
class RegistrationForm(PersonFields):
# InputRequired: Die Eingabe darf nicht leer sein
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# zwei Length-Einschränkungen, jede mit ihrer Nachricht
password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.PASSWORD_REQUIRED"),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CONFIRMATION_REQUIRED")])
# „Mein Konto verwalten"
class MyAccountForm(PersonFields):
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# optional: leer = Passwort unverändert
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none])
# das AKTUELLE Passwort, für jede Änderung des Kontos erforderlich
current_password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CURRENT_PASSWORD_REQUIRED")])
version = StringField(filters=[rules.version])
|
- Zeilen 38–51: die Felder, die allen drei Formularen gemeinsam sind: Anrede, Vorname, Nachname. Die Meldungen der Validatoren sind Übersetzungsschlüssel: Die View übersetzt sie in die Sprache der Seite. Der Validator [AnyOf] akzeptiert einen Wert aus einer Liste. Die maximalen Längen entsprechen denen der SQL-Spalten: Eine längere Eingabe würde von der Datenbank abgelehnt;
- Zeilen 55–67: das Administratorformular: ein Login und ein optionales Passwort (der Validator [Optional] beendet die Validierung eines leeren Feldes, ohne einen Fehler zu melden; [strip_whitespace=False]: Ein Passwort aus Leerzeichen gilt nicht als leer) sowie die Version;
- Zeilen 71–85: das Registrierungsformular für Patienten: Benutzername, Passwort und Bestätigung sind Pflichtfelder. Zwei Validatoren [Length], jeder mit eigener Meldung: zu kurz, zu lang;
- Zeilen 89–107: „Mein Konto verwalten“: ein optionales neues Passwort und das aktuelle Passwort, das für jede Änderung erforderlich ist.
Eine [WTForms]-Klasse, die von einer anderen Klasse erbt, erbt deren Felder: Die drei Formulare teilen sich die Felder von [PersonFields]. Der Vergleich des Passworts mit seiner Bestätigung wird nicht vom Validator [EqualTo] übernommen (Beispiel 19), sondern von der Aktion durchgeführt, die so die Meldung und das betreffende Feld auswählt.
Beachten Sie, dass diese Formulare nur dazu dienen, die Eingaben des Benutzers zu lesen und zu validieren: Die Views rufen die [WTForms]-Felder nicht auf, um sie darzustellen (Beispiel 18); stattdessen schreiben sie ihre eigenen [<input>]-Tags auf Grundlage der View-Templates. Dieser Ansatz hält die Views für alle drei Formulare identisch und gibt der Aktion die volle Kontrolle darüber, was angezeigt wird (zum Beispiel nie ein Passwort). Dies ist auch der Ansatz der früheren Versionen der Anwendung.
11.15.3. models/view_models.py
| # =========================================================================
# models/view_models.py
# -------------------------------------------------------------------------
# Die „View-Modelle": das, was jede Aktion ihrer
# View unter dem Namen [model] übergibt. Es sind Dataclasses: Objekte, die von der Aktion
# in einem Zug erstellt werden und die die View nur liest
# ({{ model.schedule.rows }} ...).
#
# Regel, der alle Seiten folgen: keine Logik in den Views. Die
# Aktionen bereiten BEREITS formatierte Daten vor ("Mme Marie
# PELISSIER", "8:00 - 8:20", selected = True ...), die außerdem bereits nach
# der Rolle des Benutzers gefiltert sind; die Views platzieren sie lediglich im HTML.
#
# Jedes Seitenmodell hat zwei Felder, die vom Layout (templates/layout.html) gelesen werden:
# page_title, der Schlüssel des Seitentitels, und error, DIE Fehlermeldung der
# Seite, unten auf der Seite angezeigt (None: kein Fehler).
# =========================================================================
from dataclasses import dataclass, field
from rdvmedecins.auth.captcha import Captcha
from rdvmedecins.forms import rules
# eine zu übersetzende Nachricht: ihr Schlüssel und ihre Parameter
@dataclass(frozen=True)
class Message:
key: str
params: dict[str, str] = field(default_factory=dict)
# eine Option einer Dropdown-Liste (Arzt, Patient)
@dataclass(frozen=True)
class OptionView:
id: int
label: str
selected: bool
# Anmeldung
@dataclass
class LoginModel:
page_title: str
error: Message | None
login: str
captcha: Captcha
# Terminkalender
@dataclass(frozen=True)
class ScheduleRowView:
slot_id: int
time: str # "8:00 - 8:20"
free: bool
patient: str | None # angezeigter Name für ein gebuchtes Zeitfenster; None = "Booked"
mine: bool # der Termin des angemeldeten Patienten
bookable: bool # Button "Book" anzeigen?
book_url: str
appointment_id: int | None # nur gefüllt, wenn der Button "Cancel" angezeigt wird
@dataclass(frozen=True)
class ScheduleView:
doctor: str
day: str
rows: list[ScheduleRowView]
@dataclass(frozen=True)
class BookingView:
slot_id: int
time: str
clients: list[OptionView] # ADMIN / DOCTOR: die zur Auswahl stehenden Patienten
patient: str | None # USER: der Patient ist die Person selbst
@dataclass
class ScheduleModel:
page_title: str
error: Message | None
doctors: list[OptionView]
doctor_id: int | None
day: str # "yyyy-mm-dd"
schedule: ScheduleView | None
booking: BookingView | None
back_url: str # der angezeigte Terminkalender, ohne Buchungsdialog
# Patient, der bereits einen bevorstehenden Termin hat: die Nachricht, die erklärt,
# warum es keinen Button "Book" gibt
info: str | None
# „Personen"-Formulare
# die in den Feldern des Formulars angezeigten Werte (nie das Passwort)
@dataclass(frozen=True)
class PersonValues:
title: str = "Mr"
first_name: str = ""
last_name: str = ""
login: str = ""
version: int | None = None
# der Zustand eines abgelehnten Formulars: die UNTER jedem Feld angezeigte Nachricht
# (Feld -> Schlüssel der Nachricht) und die rot zu umrandenden Felder (Bootstrap-
# Klasse is-invalid): die mit einer Nachricht plus eventuell weitere
# (doppelter Vor- + Nachname, vergebenes Login ...)
@dataclass(frozen=True)
class FormState:
errors: dict[str, str] = field(default_factory=dict)
invalid_fields: set[str] = field(default_factory=set)
def error_of(self, field: str) -> str | None:
return self.errors.get(field)
def invalid_class(self, field: str) -> str:
return "is-invalid" if field in self.invalid_fields else ""
# eine Option der Liste der Anreden
@dataclass(frozen=True)
class TitleOption:
value: str
selected: bool
# was das gemeinsame Fragment person_fields.html verwendet (Anrede, Vorname, Nachname):
# eine Basisklasse, von der die drei Formularmodelle erben
@dataclass
class FormView:
page_title: str
error: Message | None
values: PersonValues
state: FormState
# eine Property: Sie wird wie ein Attribut gelesen (model.titles), aber berechnet
@property
def titles(self) -> list[TitleOption]:
return [TitleOption(t, t == self.values.title) for t in rules.TITLES]
@property
def password_min(self) -> int:
return rules.PASSWORD_MIN
@dataclass
class PersonFormModel(FormView):
creating: bool # True: hinzufügen; False: bearbeiten
action: str # URL des POST
list_url: str
@dataclass
class RegistrationModel(FormView):
pass
@dataclass
class MyAccountModel(FormView):
pass
# Listen der Ärzte / Clients
# die für jeden Personentyp spezifischen Übersetzungsschlüssel
@dataclass(frozen=True)
class PersonKeys:
title: str # "Doctors"
add: str # "Add a doctor"
edit: str # "Edit a doctor"
empty: str # "No doctors."
confirm_delete: str # "Delete this doctor and their account?"
added: str # "Doctor {name} has been added (login: {login})."
edited: str
deleted: str
@dataclass(frozen=True)
class PersonView:
title: str
first_name: str
last_name: str
login: str
edit_url: str
delete_url: str
@dataclass
class PersonListModel:
page_title: str
error: Message | None
keys: PersonKeys
add_url: str
persons: list[PersonView]
# Bereich des Patienten
@dataclass(frozen=True)
class AppointmentView:
id: int
day: str
time: str
doctor: str
schedule_url: str
@dataclass
class AreaModel:
page_title: str
error: Message | None
patient: str
appointments: list[AppointmentView]
# Fehlerseite
@dataclass
class ErrorModel:
page_title: str
error: Message | None
code: int
message: str
|
View-Modelle (*View Models*): was jede Aktion ihrer View übergibt, unter dem Namen [model]. Die Regel für alle Seiten: keine Logik in den Views. Aktionen bereiten bereits formatierte Daten („Mme Marie PELISSIER“, „8:00 – 8:20“) vor, die bereits nach der Rolle des Benutzers gefiltert sind; die Views setzen diese Daten lediglich in das HTML ein.
- Zeilen 26–28: eine zu übersetzende Meldung: ein Schlüssel und seine Parameter. [field(default_factory=dict)]: Der Standardwert ist für jedes Objekt ein neues, leeres Dictionary. Man kann nicht [= {}] schreiben: Dieses Dictionary würde nur einmal erzeugt und von allen Objekten geteilt;
- Zeilen 33–36: eine Option einer Dropdown-Liste;
- Zeilen 41–45: das Template der Login-Seite. Jedes Seiten-Template hat zwei Felder, die vom Template gelesen werden: [page_title], der Schlüssel des Seitentitels, und [error], die am Seitenende angezeigte Fehlermeldung;
- Zeilen 50–58: eine Zeile im Kalender, bereits für den angemeldeten Benutzer befüllt: [patient] ist gleich [None] bei einem Zeitfenster, das von einem anderen Patienten belegt ist, wenn der Benutzer ein Patient ist (die View zeigt „Belegt“ an); [bookable] gibt an, ob die Schaltfläche „Buchen“ angezeigt werden soll; [appointment_id] wird nur befüllt, wenn die Schaltfläche „Stornieren“ angezeigt werden soll. Alle diese Entscheidungen trifft die Aktion;
- Zeilen 69–73: das Buchungsfenster: die Liste der Patienten für einen Administrator oder Arzt, der Name des Patienten für einen Patienten;
- Zeilen 77–88: das Template der Kalenderseite;
- Zeilen 108–116: der Zustand eines abgelehnten Formulars, mit zwei von den Views aufgerufenen Methoden: die Meldung für ein Feld und die CSS-Klasse, die es rot hervorhebt;
- Zeilen 129–142: die Basisklasse der drei Formular-Templates, die vom gemeinsamen Fragment [person_fields.html] verwendet wird. Ihre beiden Eigenschaften berechnen die Liste der Anreden (einschließlich der ausgewählten Anrede) und die Mindestlänge eines Passworts;
- Zeilen 146–158: Die drei Formular-Templates erben von [FormView]. Eine [dataclass] , die von einer anderen erbt, fügt ihre Felder denen ihrer Elternklasse hinzu;
- Zeilen 166–174: Übersetzungsschlüssel speziell für Ärzte oder Clients: Dieselbe View zeigt beide Listen an;
- Zeilen 198–211: der Patientenbereich;
- Zeilen 216–220: die Fehlerseite.
11.16. Die Web-Schicht: Controller
Der Ordner [controllers] enthält einen Blueprint pro Teil der Anwendung (der Login-Controller [controllers/auth.py] wurde bei der Authentifizierung vorgestellt):
Blueprint | Adressen |
[language] | [GET /language/<code>] |
[schedule] | [GET /schedule], [POST /schedule/book], [POST /schedule/cancel] |
[doctors], [clients] | [/doctors/...], [/clients/...]: auflisten, hinzufügen, bearbeiten, löschen |
[registration] | [POST /register/access], [GET] und [POST /register] |
[area] | [/my-area], [/my-area/cancel], [/my-account], [/my-account/delete] |
Alle Aktionen folgen demselben Muster: die Anfrage lesen und validieren, die Geschäftsschicht aufrufen (über [ApplicationModel]) und das View-Modell erstellen; oder, bei einer Aktion wie POST, eine Flash-Meldung ablegen und weiterleiten (PRG-Ablauf, Beispiel 20).
11.16.1. controllers/language.py
| # =========================================================================
# controllers/language.py
# -------------------------------------------------------------------------
# GET /language/fr, GET /language/en: die beiden Buttons FR / EN der
# Navigationsleiste. Öffentliche Route: Man muss die Sprache wechseln können, bevor man sich
# anmeldet.
#
# Die Wahl wird in einem Cookie gespeichert: Bei jeder folgenden Anfrage liest die
# Funktion set_language (siehe rdvmedecins/__init__.py) es erneut und setzt die
# Sprache der Anfrage (g.language). Dann gehen wir zur Seite zurück, von der wir kamen.
# =========================================================================
from datetime import timedelta
from urllib.parse import urlsplit
from flask import Blueprint, abort, current_app, redirect, request
from rdvmedecins.auth.security import public
from rdvmedecins.web.translator import LANGUAGE_COOKIE, LANGUAGES
language = Blueprint("language", __name__)
@language.get("/language/<code>")
@public
def change(code: str):
if code not in LANGUAGES:
abort(404) # -> 404-Fehlerseite (siehe web/errors.py)
response = redirect(origin_page())
response.set_cookie(LANGUAGE_COOKIE, code, max_age=timedelta(days=365), path="/",
httponly=True, samesite="Lax", secure=current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# die vorherige Seite gemäß dem HTTP-Header "Referer", den der
# Browser sendet. Nur ihr Pfad (/schedule?...) wird behalten: Eine Weiterleitung auf
# eine vollständige, von der Anfrage gelieferte Adresse würde es ermöglichen, den
# Benutzer auf eine andere Website zu schicken (sogenannte „Open-Redirect"-Schwachstelle).
# -----------------------------------------------------------------------
def origin_page() -> str:
referer = request.headers.get("Referer")
if not referer:
return "/"
url = urlsplit(referer)
path = url.path
# "//site.com/..." würde vom Browser als Adresse
# auf einer ANDEREN Website: ebenfalls abgelehnt
if not url.scheme or not path.startswith("/") or path.startswith("//") \
or path.startswith("/language/"):
return "/"
return f"{path}?{url.query}" if url.query else path
|
Die Sprachauswahl aus Beispiel 22, mit zwei zusätzlichen Vorsichtsmaßnahmen in [origin_page] (Zeilen 40–51): Ein [Referer] ohne Schema ([http], [https]) ist keine vollständige Adresse, und ein [Referer], der selbst eine Adresse [/language/...] wäre, würde auf diese Aktion weiterleiten und eine Schleife erzeugen. In beiden Fällen wird der Benutzer zurück zur Wurzel der Site geleitet. Die Lebensdauer des Cookies wird durch einen [timedelta] angegeben: [set_cookie] akzeptiert diesen ebenso wie eine Anzahl von Sekunden.
Die Hauptseite der Anwendung, für alle Rollen.
| # =========================================================================
# controllers/schedule.py
# -------------------------------------------------------------------------
# Die Terminkalender-Seite: Wahl eines Arztes und eines Tages, Terminkalender dieses
# Arztes an diesem Tag, Buchen und Stornieren von Terminen.
#
# GET /schedule?doctorId=1&day=2026-09-23 die Seite
# GET /schedule?doctorId=1&day=2026-09-23&book=7 dieselbe Seite, mit
# geöffnetem Buchungsdialog
# für den Slot 7
# POST /schedule/book erstellt einen Termin
# POST /schedule/cancel storniert einen Termin
#
# Die gesamte Seite wird durch ihre URL beschrieben: Sie kann neu geladen und mit einem Lesezeichen versehen werden,
# der Button „Zurück" des Browsers ist nutzbar - ohne eine einzige Zeile
# JavaScript.
#
# Was jeder sieht und tun kann:
#
# | Rolle | angezeigter gebuchter Slot | Buchen | Stornieren |
# |---------------|-----------------------------------|--------------------|---------|
# | ADMIN, DOCTOR | Name des Patienten | für einen Patienten | ja |
# | | | aus einer Liste | |
# | USER (Patient)| "Booked" oder IHR Name, falls es | für sich selbst, | nein (*) |
# | | ihr eigener Termin ist | falls kein | |
# | | | bevorstehender Termin | |
#
# (*) Der Patient storniert seinen Termin auf seiner Seite "My area".
#
# VERTRAULICHKEIT: Bei einem Patienten wird der Name der ANDEREN Patienten nicht
# einfach von der View ausgeblendet - er wird nie in das der View
# übergebene Modell aufgenommen. Das an den Browser gesendete HTML enthält ihn daher nicht,
# nicht einmal versteckt (sonst würde ihn ein einfaches „Seitenquelltext anzeigen" verraten).
#
# Keine Buchung in der Vergangenheit: Der Button "Book" erscheint nur
# für heute und die folgenden Tage (und die Geschäftsschicht würde sie
# ohnehin ablehnen).
#
# Sicherheit: Alle /schedule-URLs erfordern einen authentifizierten Benutzer
# (siehe auth/security.py: alles, was nicht @public ist). @roles_required
# bei einer Aktion verlangt zusätzlich eine der aufgeführten Rollen. Ohne gültiges Token:
# zurück zu /login; unzureichende Rolle: 403-Seite.
# =========================================================================
from dataclasses import dataclass
from datetime import date
from flask import Blueprint, abort, redirect, render_template, request, url_for
from rdvmedecins.auth.security import roles_required
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Person, Role
from rdvmedecins.business import dates
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (ScheduleModel, ScheduleView, ScheduleRowView, Message,
OptionView, BookingView)
from rdvmedecins.web import utils
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application
schedule = Blueprint("schedule", __name__, url_prefix="/schedule")
# was der Controller über den Benutzer weiß, um zu entscheiden, was angezeigt wird
@dataclass(frozen=True)
class Rights:
manager: bool # ADMIN oder DOCTOR
patient: Client | None # der angemeldete Client (Rolle USER), sonst None
patient_can_book: bool # USER ohne bevorstehenden Termin
# -----------------------------------------------------------------------
# GET /schedule
# Die URL-Parameter werden unverarbeitet gelesen (request.args.get), um
# einen FEHLENDEN Parameter (None) von einem LEEREN Parameter (?doctorId=) zu unterscheiden.
# -----------------------------------------------------------------------
@schedule.get("")
def show():
error = None
user = utils.user()
rights = compute_rights()
# der Tag: der aus der URL, wenn er gültig ist, sonst heute
day = dates.today()
raw_day = request.args.get("day")
if raw_day is not None:
requested_day = utils.valid_date(raw_day)
if requested_day is not None:
day = requested_day
else:
error = "ERRORS.INVALID_DATE"
day_bookable = day >= dates.today()
# der Arzt: der aus der URL; ersatzweise bei einem angemeldeten Arzt er selbst
raw_doctor_id = request.args.get("doctorId")
doctor_id = utils.positive_integer(raw_doctor_id)
if raw_doctor_id is None and user.role == Role.DOCTOR:
doctor = application().get_doctor_by_user_id(user.user_id)
doctor_id = doctor.id if doctor else None
# die Dropdown-Liste der Ärzte
doctors = [option(d, d.id == doctor_id) for d in application().get_all_doctors()]
# der Terminkalender, falls ein Arzt gewählt ist (und das Datum gültig)
view = None
if doctor_id is not None and error is None:
doctor_schedule = application().get_doctor_day_schedule(doctor_id, day)
if doctor_schedule is None:
error = "ERRORS.DOCTOR_NOT_FOUND"
else:
view = schedule_view(doctor_schedule, rights, day_bookable)
# der Buchungsdialog: nur, wenn der angeforderte Slot von diesem Benutzer
# gebucht werden kann
booking = None
slot_id = utils.positive_integer(request.args.get("book"))
if view is not None and slot_id is not None:
row = next((r for r in view.rows if r.slot_id == slot_id and r.bookable),
None)
if row is not None:
booking = BookingView(
row.slot_id,
row.time,
[option(c, False) for c in application().get_all_clients()]
if rights.manager else [],
utils.label(rights.patient) if rights.patient else None)
model = ScheduleModel(
page_title="SCHEDULE.PAGE_TITLE",
error=Message(error) if error else None,
doctors=doctors,
doctor_id=doctor_id,
day=utils.iso(day),
schedule=view,
booking=booking,
back_url=schedule_url(doctor_id, day) if doctor_id is not None else url_for("schedule.show"),
info=patient_info(rights, view))
return render_template("schedule.html", model=model)
# -----------------------------------------------------------------------
# POST /schedule/book Felder: doctorId, day, slotId, clientId
#
# Bei einem Patienten (USER) wird das Feld clientId IGNORIERT: Er bucht immer
# für sich selbst. Einem vom Browser gesendeten Feld zu vertrauen,
# würde einem findigen Patienten erlauben, im Namen eines anderen zu buchen.
#
# Muster „Post / Redirect / Get": Unabhängig vom Ergebnis wird hier keine Seite
# erstellt - eine Flash-Nachricht wird gesetzt und wir leiten auf
# den Terminkalender um (siehe Beispiel 20).
# -----------------------------------------------------------------------
@schedule.post("/book")
@roles_required(Role.ADMIN, Role.DOCTOR, Role.USER)
def book():
doctor_id, day = read_schedule_request()
slot_id = utils.positive_integer(request.form.get("slotId"))
if doctor_id is None or slot_id is None:
abort(400) # -> Seite "invalid request" (siehe web/errors.py)
user = utils.user()
if user.is_patient:
client = utils.connected_patient(application())
else:
client_id = utils.positive_integer(request.form.get("clientId"))
if client_id is None:
# kein Patient gewählt: Der Buchungsdialog wird erneut geöffnet
flash_error("ERRORS.CHOOSE_PATIENT")
return redirect(schedule_url(doctor_id, day, slot_id))
client = application().get_client_by_id(client_id)
slot = application().get_slot_by_id(slot_id)
if client is None:
flash_error("ERRORS.PATIENT_NOT_FOUND")
elif slot is None or slot.doctor_id != doctor_id:
flash_error("ERRORS.SLOT_NOT_FOUND")
else:
try:
# die Regeln (nicht in der Vergangenheit, nur ein bevorstehender Termin pro
# Patient, freier Slot) werden von der Geschäftsschicht geprüft
application().add_appointment(day, slot, client)
flash_success("SCHEDULE.BOOKED")
except BusinessException as e:
# dieselbe Regel, aber eine Nachricht in der 2. Person, wenn der
# Patient selbst bucht („You already have ..." statt
# „This patient ..."). Die anderen Ausnahmen (echte
# Anomalien) werden nicht abgefangen: 500-Seite.
if e.key == "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT" and user.is_patient:
flash_error("SCHEDULE.ALREADY_BOOKED_INFO")
else:
flash_error(e.key, **e.params)
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# POST /schedule/cancel Felder: appointmentId, doctorId, day
# (ein Patient storniert SEINEN Termin auf "My area", nicht hier)
# -----------------------------------------------------------------------
@schedule.post("/cancel")
@roles_required(Role.ADMIN, Role.DOCTOR)
def cancel():
doctor_id, day = read_schedule_request()
appointment_id = utils.positive_integer(request.form.get("appointmentId"))
if doctor_id is None or appointment_id is None:
abort(400)
appointment = application().get_appointment_by_id(appointment_id)
if appointment is None:
# bereits storniert (von jemand anderem oder durch Doppelklick)
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# wer ist angemeldet und was darf er auf dieser Seite tun?
# -----------------------------------------------------------------------
def compute_rights() -> Rights:
if not utils.user().is_patient:
return Rights(True, None, False)
patient = utils.connected_patient(application())
upcoming = application().get_client_upcoming_appointments(patient.id)
return Rights(False, patient, not upcoming)
# -----------------------------------------------------------------------
# der Terminkalender des Arztes, für die View formatiert - und nach den Rechten gefiltert
# -----------------------------------------------------------------------
def schedule_view(doctor_schedule: DoctorDaySchedule, rights: Rights, day_bookable: bool) -> ScheduleView:
doctor_id = doctor_schedule.doctor.id
day = doctor_schedule.day
rows = []
for dds in doctor_schedule.doctor_day_slots:
slot, appointment = dds.slot, dds.appointment
free = appointment is None
# der Termin des angemeldeten Patienten?
mine = appointment is not None and rights.patient is not None and appointment.client_id == rights.patient.id
rows.append(ScheduleRowView(
slot_id=slot.id,
time=utils.time(slot),
free=free,
# DER Vertraulichkeitspunkt: Ein Patient erhält nur den Namen
# SEINES Termins; für die anderen None (die View zeigt "Booked" an)
patient=utils.label(appointment.client) if appointment is not None and (rights.manager or mine) else None,
mine=mine,
bookable=free and day_bookable and (rights.manager or rights.patient_can_book),
book_url=schedule_url(doctor_id, day, slot.id),
appointment_id=appointment.id if appointment is not None and rights.manager else None))
return ScheduleView(utils.label(doctor_schedule.doctor), utils.format_day(day), rows)
# Hilfsfunktionen
# die versteckten Felder doctorId / day der POST-Formulare; (None, None), wenn sie ungültig sind
def read_schedule_request() -> tuple[int | None, date | None]:
doctor_id = utils.positive_integer(request.form.get("doctorId"))
day = utils.valid_date(request.form.get("day"))
return (None, None) if doctor_id is None or day is None else (doctor_id, day)
# /schedule?doctorId=1&day=2026-09-23[&book=7]: url_for fügt am Ende der
# URL die Parameter hinzu, die keine Variablen des Pfads sind
def schedule_url(doctor_id: int, day: date, book: int | None = None) -> str:
if book is None:
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day))
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day), book=book)
def option(p: Person, selected: bool) -> OptionView:
return OptionView(p.id, utils.label(p), selected)
# -----------------------------------------------------------------------
# die Informationsmeldung eines Patienten, der bereits einen bevorstehenden Termin hat
# (warum es keinen Button "Book" gibt), oder None. Überflüssig, wenn SEIN
# Termin im angezeigten Terminkalender erscheint (in Blau): Das ist kurz
# nach der Buchung der Fall, wenn die Meldung unpassend wäre.
# -----------------------------------------------------------------------
def patient_info(rights: Rights, view: ScheduleView | None) -> str | None:
if rights.patient is None or rights.patient_can_book:
return None
appointment_shown = view is not None and any(row.mine for row in view.rows)
return None if appointment_shown else "SCHEDULE.ALREADY_BOOKED_INFO"
|
11.16.2.1. Die URL der Seite
Die gesamte Seite wird durch ihre URL beschrieben: [/schedule?doctorId=1&day=2026-09-26] zeigt den Terminkalender von Arzt Nr. 1 für diesen Tag an; [&book=4] öffnet zusätzlich das Buchungsfenster für das Zeitfenster Nr. 4. Das Fenster zur Terminbuchung wird also nicht von [JavaScript] geöffnet: Der Server erzeugt eine Seite, die das Fenster enthält. Das bedeutet, dass Sie die Seite neu laden, als Lesezeichen speichern und die Schaltfläche „Zurück“ des Browsers verwenden können, und die Anwendung funktioniert ohne [JavaScript] (das einzige Skript der Anwendung dient den Bestätigungsfenstern und funktioniert ebenfalls ohne es; siehe Beispiel 21).
11.16.2.2. GET /schedule
- Zeilen 65–68: was die Aktion über den Benutzer weiß, um die Anzeige zu bestimmen: ein „Verwalter“ (ADMIN oder DOCTOR) oder ein Patient, der eine Buchung vornehmen darf oder nicht;
- Zeilen 83–91: der Tag: der per URL angegebene Tag, wenn er gültig ist; andernfalls heute. Die Parameter werden im Rohformat gelesen ([request.args.get]), um zwischen einem fehlenden Parameter ([None]: Der Standardwert wird ohne Fehler verwendet) und einem ungültigen Parameter (ein Fehler wird gemeldet) zu unterscheiden. Nur der heutige und die folgenden Tage sind buchbar;
- Zeilen 94–98: der Arzt: der per URL angegebene; andernfalls bei einem angemeldeten Arzt der Arzt selbst: Ein Arzt kann seinen Tageskalender direkt nach dem Login ansehen;
- Zeile 101: die Dropdown-Liste der Ärzte, aus dem Cache gelesen, wobei der ausgewählte Arzt hervorgehoben ist;
- Zeilen 104–110: der Terminkalender, wenn ein Arzt ausgewählt und das Datum gültig ist. Ein nicht existierender Arzt (eine per Hand geänderte ID in der URL) löst eine Fehlermeldung aus, keine Fehlerseite;
- Zeilen 114–125: das Buchungsfenster, nur wenn das angeforderte Zeitfenster existiert und von diesem Benutzer buchbar ist: Ein Patient, der [&book=2] an die URL eines bereits gebuchten Zeitfensters anhängt, sieht nichts. [next(...)] sucht den entsprechenden Eintrag des Kalenders (Beispiel 21). Das Fenster zeigt einem Administrator eine Liste der Patienten an; für einen Patienten zeigt es dessen eigenen Namen an;
- Zeilen 127–137: das Seiten-Template. [back_url] ist die URL des Kalenders ohne Buchungsfenster; die Schaltfläche „Abbrechen“ im Fenster führt dorthin.
11.16.2.3. POST /schedule/book
- Zeile 152: Alle Rollen können Buchungen vornehmen. Der Dekorator dokumentiert die Regel und schützt sie für den Fall, dass künftig eine vierte Rolle hinzukommt;
- Zeilen 154–157: die versteckten Felder des Formulars. Ungültige Felder können nur von einer manuell erstellten Anfrage stammen: Fehler 400;
- Zeilen 160–168: der Patient für den Termin. Für einen Patienten ist es immer der Patient selbst: Das Feld [clientId] wird ignoriert. Einem vom Browser gesendeten Feld zu vertrauen, würde es einem Patienten erlauben, für einen anderen zu buchen. Hat ein Administrator keinen Patienten ausgewählt, wird das Buchungsfenster mit einer Meldung erneut geöffnet;
- Zeilen 170–189: Validierungen (der Patient existiert, das Zeitfenster existiert und gehört zum Arzt im Kalender), gefolgt von der Buchung. Die Geschäftsregeln werden von der Geschäftslogikschicht geprüft; eine [BusinessException] wird zu einer Flash-Fehlermeldung. Die Meldung „nur ein bevorstehender Termin“ wird angepasst, wenn der Patient selbst bucht („Sie haben bereits ...“ statt „Dieser Patient hat bereits ...“);
- Zeile 190: in allen Fällen Rückkehr zum Kalender (PRG-Schema).
11.16.2.4. POST /schedule/cancel
- Zeilen 197–211: Die Stornierung eines Termins ist Administratoren vorbehalten (ein Patient storniert seinen Termin über sein Konto). Bei einem bereits stornierten Termin (durch jemand anderen oder durch einen Doppelklick) wird eine Meldung angezeigt, kein Fehler.
- Zeilen 217–222: die Berechtigungen des Benutzers. Bei einem Patienten müssen dessen bevorstehende Termine angesehen werden: Eine leere Liste ist „falsch“, daher [not upcoming];
- Zeilen 228–248: der Kalender der Domäne, für die Anzeige formatiert und nach Berechtigungen gefiltert. Hier kommt die Vertraulichkeit der Patientendaten ins Spiel (Zeile 243): Bei einem Patienten sind die Namen anderer Patienten nicht bloß ausgeblendet; sie gelangen nie in das Template. Das an den Browser gesendete HTML enthält sie daher nicht, auch nicht versteckt (sonst würde ein einfaches „Quelltext anzeigen“ sie offenlegen). Die Schaltfläche „Buchen“ erscheint nur, wenn ein freies Zeitfenster, ein buchbarer Tag und ein Benutzer mit Buchungsrecht vorhanden sind; die Schaltfläche „Stornieren“ erscheint nur für einen Administrator;
- Zeilen 254–257: die versteckten Felder [doctorId] and [day] in den POST-Formularen, validiert;
- Zeilen 262–265: die URL des Kalenders. [url_for] hängt die benannten Parameter, die keine Pfadvariablen sind, als Parameter an die URL an (Beispiel 16);
- Zeilen 278–282: die Informationsmeldung für einen Patienten, der bereits einen bevorstehenden Termin hat: Sie erklärt, warum die Schaltflächen „Buchen“ fehlen. Sie wird nicht angezeigt, wenn der eigene Termin des Patienten im Kalender erscheint (in Blau), was unmittelbar nach der Buchung der Fall ist. [any(...)] liefert [True] , wenn eine der beiden Bedingungen zutrifft.
11.16.3. controllers/persons.py
Die Verwaltung von Ärzten und Clients, dem Administrator vorbehalten, ist identisch: dieselbe Liste, dasselbe Formular, dieselben Regeln. Statt dieselben Aktionen zweimal zu schreiben, schreiben wir sie einmal, in einer Blueprint-Factory.
| # =========================================================================
# controllers/persons.py
# -------------------------------------------------------------------------
# Die Verwaltung der Ärzte und die der Clients (dem ADMIN vorbehalten) sind
# IDENTISCH: gleiche Liste, gleiches Formular, gleiche Regeln. Statt
# dieselben Aktionen zweimal zu schreiben, werden sie einmal in einer
# BLUEPRINT-FACTORY geschrieben: Die Funktion create_blueprint baut einen
# vollständigen Blueprint aus einer „Konfiguration", die angibt, WAS aufzurufen ist und
# WELCHE Beschriftungen anzuzeigen sind. controllers/doctors.py und controllers/clients.py
# rufen sie jeweils mit ihrer eigenen auf. So erhalten wir für jeden von ihnen:
#
# GET /doctors Liste
# GET /doctors/add leeres Formular
# POST /doctors/add Erstellung
# GET /doctors/<id>/edit vorausgefülltes Formular
# POST /doctors/<id>/edit Bearbeitung
# POST /doctors/<id>/delete Löschung
#
# (und dieselben URLs unter /clients). Auch die Views sind gemeinsam:
# templates/persons/list.html und templates/persons/form.html.
#
# SICHERHEIT: Ein before_request DES BLUEPRINTS verlangt die Rolle ADMIN. Er
# läuft vor JEDER Aktion des Blueprints - auch vor solchen, die ihm
# später hinzugefügt würden: Die Regel wird ein für alle Mal geschrieben.
# =========================================================================
from collections.abc import Callable
from dataclasses import dataclass
from flask import Blueprint, abort, redirect, render_template, url_for
from rdvmedecins.auth.security import require_roles
from rdvmedecins.entities import Person, Role
from rdvmedecins.forms.forms import PersonForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (PersonKeys, FormState, PersonFormModel,
PersonListModel, Message, PersonView,
PersonValues)
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
# -----------------------------------------------------------------------
# was jeder Personentyp liefern muss. Die letzten fünf Felder
# sind FUNKTIONEN: doctors.py und clients.py legen dort Lambdas ab, die
# die Methoden des ApplicationModel aufrufen (get_all_doctors ...).
# -----------------------------------------------------------------------
@dataclass(frozen=True)
class PersonsConfig:
name: str # "doctors" oder "clients": der Name des Blueprints und der Beginn der URLs
keys: PersonKeys
list: Callable[[], list[Person]] # () -> Liste
find: Callable[[int], Person | None] # id -> Person
add: Callable[[PersonData], Person] # data -> erstellte Person
edit: Callable[[int, PersonData], Person] # (id, data) -> bearbeitete Person
delete: Callable[[int], None] # id -> nichts
def create_blueprint(config: PersonsConfig) -> Blueprint:
bp = Blueprint(config.name, __name__, url_prefix=f"/{config.name}")
# die URL einer Aktion DIESES Blueprints: url("list_persons") -> "/doctors"
def url(action: str, **params) -> str:
return url_for(f"{config.name}.{action}", **params)
# alle Aktionen des Blueprints sind dem ADMIN vorbehalten
@bp.before_request
def admin_only():
require_roles(Role.ADMIN)
# -------------------------------------------------------------------
# GET /doctors (oder /clients)
# -------------------------------------------------------------------
@bp.get("")
def list_persons():
persons = [PersonView(p.title, p.first_name, p.last_name, login(p),
url("edit_form", id=p.id),
url("delete", id=p.id))
for p in config.list()]
model = PersonListModel(config.keys.title, None, config.keys, url("add_form"),
persons)
return render_template("persons/list.html", model=model)
# -------------------------------------------------------------------
# GET /doctors/add
# -------------------------------------------------------------------
@bp.get("/add")
def add_form():
return show_form(None, PersonValues(), {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/add
# PersonForm() liest die Eingabe; validate() prüft sie.
# -------------------------------------------------------------------
@bp.post("/add")
def add():
form = PersonForm()
if not form.validate():
return show_form(None, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.add(data(form))
except BusinessException as e:
return show_business_error(None, entered_values(form), e)
flash_success(config.keys.added, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# GET /doctors/<id>/edit
# <int:id>: Die id muss aus Ziffern bestehen - /doctors/abc/edit
# passt auf keine Route (404-Seite)
# -------------------------------------------------------------------
@bp.get("/<int:id>/edit")
def edit_form(id: int):
person = config.find(id)
if person is None:
abort(404)
values = PersonValues(person.title, person.first_name, person.last_name, login(person),
person.version)
return show_form(id, values, {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/<id>/edit
# -------------------------------------------------------------------
@bp.post("/<int:id>/edit")
def edit(id: int):
form = PersonForm()
if not form.validate():
return show_form(id, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.edit(id, data(form))
except BusinessException as e:
return show_business_error(id, entered_values(form), e)
flash_success(config.keys.edited, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# POST /doctors/<id>/delete
# (die Bestätigung "Are you sure?" wird vor dem Senden des Formulars
# angefordert, siehe static/js/app.js)
# -------------------------------------------------------------------
@bp.post("/<int:id>/delete")
def delete(id: int):
person = config.find(id)
try:
config.delete(id)
flash_success(config.keys.deleted, **params(person))
except BusinessException as e:
flash_error(e.key, **e.params)
return redirect(url("list_persons"))
# interne Funktionen
# id None: Erstellungsformular; sonst: Bearbeitungsformular.
# errors: Feld -> Schlüssel der Nachricht; error: der Schlüssel der Nachricht unten
# auf der Seite; other_fields: zusätzliche rot zu umrandende Felder
def show_form(id: int | None, values: PersonValues, errors: dict[str, str],
error: str | None, other_fields: list[str] | None):
creating = id is None
state: FormState = validation.state(errors, other_fields)
model = PersonFormModel(
page_title=config.keys.add if creating else config.keys.edit,
error=validation.page_message(errors, Message(error) if error else None),
values=values,
state=state,
creating=creating,
action=url("add") if creating else url("edit", id=id),
list_url=url("list_persons"))
return render_template("persons/form.html", model=model)
# eine Geschäftsregel hat den Schreibvorgang abgelehnt: Das Formular wird erneut angezeigt,
# mit der Eingabe des Benutzers und der Nachricht der Geschäftsschicht
def show_business_error(id: int | None, values: PersonValues, e: BusinessException):
if e.key in ("ERRORS.DOCTOR_NOT_FOUND", "ERRORS.PATIENT_NOT_FOUND"):
# zwischenzeitlich von einem anderen ADMIN gelöscht: zurück zur Liste
flash_error(e.key)
return redirect(url("list_persons"))
# die Nachricht steht unten auf der Seite; die betroffenen Felder, falls vorhanden, werden
# rot umrandet, damit der Benutzer sofort sieht, was zu korrigieren ist
return show_form(id, values, {}, e.key, validation.BUSINESS_ERROR_FIELDS.get(e.key))
return bp
# was der Benutzer eingegeben hat (Passwort ausgenommen: Es wird nie an den
# Browser zurückgesendet). form.<field>.data: der Wert nach den Filtern
def entered_values(form: PersonForm) -> PersonValues:
return PersonValues(form.title.data or "", form.first_name.data or "", form.last_name.data or "",
form.login.data or "", form.version.data)
# das validierte Formular -> die von der Geschäftsschicht erwarteten Daten
def data(form: PersonForm) -> PersonData:
return PersonData(form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, form.version.data)
# {name} und {login} der Nachrichten „hinzugefügt / bearbeitet / gelöscht"
def params(person: Person | None) -> dict[str, str]:
if person is None:
return {"name": "", "login": ""}
return {"name": f"{person.first_name} {person.last_name}", "login": login(person)}
def login(person: Person) -> str:
return person.user.login if person.user else ""
|
- Zeilen 49–56: was jeder Entitätstyp bereitstellen muss: den Namen des Blueprints (der zugleich der Anfang der URL ist), die Übersetzungsschlüssel und fünf Funktionen: auflisten, suchen, hinzufügen, bearbeiten und löschen. Das ist dasselbe Verfahren wie bei den Deskriptoren der Geschäftsschicht;
- Zeilen 59–60: Die Factory erstellt einen Blueprint, dessen Name und URL-Präfix aus der Konfiguration stammen. Die Aktionen sind interne Funktionen von [create_blueprint]: Sie haben Zugriff auf die Variable [config] der Factory. Jeder Aufruf von [create_blueprint] erstellt einen neuen Blueprint mit eigenen Aktionen;
- Zeilen 63–64: die URL einer Aktion dieses Blueprints: [url("list_persons")] liefert [/doctors] für den Blueprint der Ärzte und [/clients] für den Blueprint der Clients;
- Zeilen 67–69: ein Blueprint-[before_request]: Er wird vor jeder Aktion des Blueprints (und nur dieses Blueprints) ausgeführt, nach denen der Anwendung. Alle Aktionen sind so dem Administrator vorbehalten, auch später hinzugefügte: Die Regel wird einmal geschrieben und gilt für alle;
- Zeilen 74–82: die Liste. [@bp.get("")]: Die Route ist das Präfix des Blueprints selbst ([/doctors]);
- Zeilen 95–106: der Hinzufügen-Vorgang: Formularvalidierung (Eingabefehler, unter den Feldern angezeigt), Aufruf der Geschäftsschicht (Geschäftsfehler, am Seitenende angezeigt), gefolgt von einer Flash-Meldung und der Weiterleitung auf die Liste. Die Flash-Meldungen erhalten Parameter: den Namen und den Login der Person;
- Zeilen 113–120: das Bearbeitungsformular, vorbefüllt mit der Version des Datensatzes (optimistisches Sperren). Eine nicht existierende Person führt zu einer 404-Seite;
- Zeilen 125–136: die Aktualisierung, dem Hinzufügen nachempfunden;
- Zeilen 143–151: der Löschvorgang, zuvor durch das Bestätigungsfenster bestätigt (Beispiel 21). Eine Ablehnung durch die Geschäftsschicht (ein Arzt mit Terminen) führt zu einer Flash-Fehlermeldung;
- Zeilen 158–170: das Formular zum Hinzufügen ([id] ist gleich [None]) oder Bearbeiten samt seinem Zustand (Werte, Fehler, rot hervorgehobene Felder);
- Zeilen 174–181: ein Geschäftsfehler: Eine Person, die inzwischen von einem anderen Administrator gelöscht wurde, wird zur Liste zurückgeleitet; in den anderen Fällen wird das Formular erneut angezeigt, wobei die betreffenden Felder rot hervorgehoben sind;
- Zeilen 188–190: die erneut anzuzeigenden Werte: was der Benutzer eingegeben hat, niemals das Passwort;
- Zeilen 194–196: das validierte Formular, in Daten für die Geschäftsschicht umgewandelt;
- Zeilen 200–203: die Parameter für die Meldungen „hinzugefügt/geändert/gelöscht“.
11.16.4. controllers/doctors.py und controllers/clients.py
| # =========================================================================
# controllers/doctors.py
# -------------------------------------------------------------------------
# Verwaltung der Ärzte (nur Rolle ADMIN). Alle Aktionen werden
# von controllers/persons.py erstellt: Hier bleibt nur noch anzugeben, WAS
# aufzurufen ist und WELCHE Beschriftungen anzuzeigen sind.
#
# Die Funktionen der Konfiguration sind LAMBDAS (Funktionen ohne
# Namen, an Ort und Stelle geschrieben): application() wird erst aufgerufen, wenn
# die Aktion läuft, während einer Anfrage - das ApplicationModel existiert
# noch nicht, wenn dieses Modul importiert wird.
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
doctors = create_blueprint(PersonsConfig(
name="doctors",
keys=PersonKeys(
title="DOCTORS.TITLE",
add="DOCTORS.ADD",
edit="DOCTORS.EDIT",
empty="DOCTORS.EMPTY",
confirm_delete="DOCTORS.DELETE_CONFIRM",
added="DOCTORS.ADDED",
edited="DOCTORS.UPDATED",
deleted="DOCTORS.DELETED"),
list=lambda: application().get_all_doctors(),
find=lambda id: application().get_doctor_by_id(id),
add=lambda data: application().add_doctor(data),
edit=lambda id, data: application().edit_doctor(id, data),
delete=lambda id: application().delete_doctor(id)))
|
Der Blueprint der Ärzte, von [create_blueprint] samt seiner Konfiguration erzeugt. Die Konfigurationsfunktionen sind anonyme Funktionen ([lambda]), die [ApplicationModel] aufrufen. Warum nicht direkt [list=application().get_all_doctors] schreiben? Weil dieses Modul beim Import, also beim Start, ausgeführt wird, bevor die Anwendung erstellt ist: [application()], das [current_app] benötigt, würde fehlschlagen. Die anonyme Funktion verschiebt den Aufruf auf die Ausführung der Aktion während einer Anfrage.
| # =========================================================================
# controllers/clients.py
# -------------------------------------------------------------------------
# Verwaltung der Clients (der PATIENTEN der Praxis), nur Rolle ADMIN.
# Gleiches Prinzip wie controllers/doctors.py (siehe dessen Kommentare).
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
clients = create_blueprint(PersonsConfig(
name="clients",
keys=PersonKeys(
title="CLIENTS.TITLE",
add="CLIENTS.ADD",
edit="CLIENTS.EDIT",
empty="CLIENTS.EMPTY",
confirm_delete="CLIENTS.DELETE_CONFIRM",
added="CLIENTS.ADDED",
edited="CLIENTS.UPDATED",
deleted="CLIENTS.DELETED"),
list=lambda: application().get_all_clients(),
find=lambda id: application().get_client_by_id(id),
add=lambda data: application().add_client(data),
edit=lambda id, data: application().edit_client(id, data),
delete=lambda id: application().delete_client(id)))
|
Der Blueprint der Clients folgt demselben Muster.
11.16.5. controllers/registration.py
| # =========================================================================
# controllers/registration.py
# -------------------------------------------------------------------------
# „Patientenkonto erstellen": Ein Patient, der noch kein Konto hat,
# erstellt es selbst. ÖFFENTLICHE Routen (man hat per Definition noch
# kein Konto):
#
# POST /register/access Button "Create a patient account" der
# Authentifizierungsseite: prüft das Captcha
# DIESER Seite und öffnet dann das Formular
# GET /register das Formular
# POST /register die Erstellung, dann zurück zur Login-Seite
#
# Der Ablauf ist durch EIN Captcha gegen Roboter geschützt, das der
# Authentifizierungsseite:
# 1. Der Button "Create a patient account" sendet das Login-Formular
# an /register/access; wird das Captcha korrekt eingegeben, stellt der Server
# einen Pass aus (siehe auth/registration_pass.py);
# 2. ohne gültigen Pass leitet /register zur
# Authentifizierungsseite zurück - die direkte Eingabe der URL nützt nichts;
# 3. Der Pass wird bei der Erstellung verbraucht: Ein gelöstes Captcha
# erlaubt die Erstellung EINES Kontos;
# 4. zusätzlich ist die Anzahl der pro Stunde und pro IP-Adresse erstellten Konten
# begrenzt (siehe auth/limiter.py).
#
# Das erstellte Konto ist genau das, das der ADMIN auf der Seite
# "Patients" erstellen würde (gleiche Methode der Geschäftsschicht: add_client), außer
# dass der Patient sein Login und sein Passwort WÄHLT (obligatorisch,
# mit Bestätigung).
# =========================================================================
from flask import Blueprint, current_app, redirect, render_template, request, url_for
from rdvmedecins.auth import registration_pass
from rdvmedecins.auth.security import public
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.forms.forms import RegistrationForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import RegistrationModel, Message, PersonValues
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, captchas, limiter, passes
registration = Blueprint("registration", __name__, url_prefix="/register")
# -----------------------------------------------------------------------
# POST /register/access Felder: captchaId, captcha (die der
# Authentifizierungsseite; login und password, ebenfalls gesendet, werden ignoriert)
# -----------------------------------------------------------------------
@registration.post("/access")
@public
def access():
ip = ip_address()
# zu viele kürzlich von dieser Adresse erstellte Konten: kein Grund, weiterzugehen
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
flash_error("ERRORS.TOO_MANY_ACCOUNTS", minutes=str(minutes))
return redirect(url_for("auth.show_login"))
# Captcha fehlt oder ist falsch: zurück zur Authentifizierungsseite mit
# einem neuen Bild (ein Fehlversuch zählt als Login-Fehlversuch)
if not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, "")
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# korrektes Captcha: Der Pass wird ausgestellt und das Formular geöffnet
response = redirect(url_for("registration.form"))
registration_pass.set_cookie(response, passes().issue(), current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# GET /register
# -----------------------------------------------------------------------
@registration.get("")
@public
def form():
if not passes().is_valid(request.cookies.get(registration_pass.COOKIE)):
return back_to_login()
return show(PersonValues(), {}, None, None)
# -----------------------------------------------------------------------
# POST /register
# -----------------------------------------------------------------------
@registration.post("")
@public
def create():
pass_id = request.cookies.get(registration_pass.COOKIE)
if not passes().is_valid(pass_id):
return back_to_login()
ip = ip_address()
form = RegistrationForm()
form.validate()
values = PersonValues(form.title.data or "Mr", form.first_name.data or "",
form.last_name.data or "", form.login.data or "", None)
# 1. zu viele kürzlich von dieser Adresse erstellte Konten?
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
return show(values, {}, Message("ERRORS.TOO_MANY_ACCOUNTS", {"minutes": str(minutes)}),
None)
# 2. alle Eingabefehler auf einmal (Felder + Bestätigung):
# Der Benutzer korrigiert sie alle in einem Zug
errors = validation.errors_of(form)
if "password" not in errors and "confirmation" not in errors \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# 3. die Erstellung (Client + USER-Konto, in einer Transaktion)
try:
application().add_client(PersonData(form.title.data, form.last_name.data,
form.first_name.data, form.login.data,
form.password.data))
except BusinessException as e:
# Login oder Vorname + Nachname bereits vergeben: Der Pass bleibt gültig
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# 4. Der Pass wurde verwendet: Er erlaubt nicht, ein 2. Konto zu erstellen
passes().consume(pass_id)
limiter().registration_success(ip)
# 5. zurück zur Login-Seite, Login vorausgefüllt
flash_success("REGISTRATION.DONE", login=form.login.data)
response = redirect(url_for("auth.show_login", login=form.login.data))
registration_pass.clear_cookie(response)
return response
# interne Funktionen
# kein gültiger Pass: zurück zur Authentifizierungsseite
def back_to_login():
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# das Formular; nie ein Passwort, das an den Browser zurückgesendet wird
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = RegistrationModel("REGISTRATION.TITLE", validation.page_message(errors, error),
values, validation.state(errors, other_fields))
return render_template("registration.html", model=model)
|
- Zeilen 51–72: Die Schaltfläche „Patientenkonto erstellen“ auf der Login-Seite sendet das Login-Formular an diese Aktion (über das Attribut [formaction], Beispiel 20). Sie prüft die Begrenzung der Kontoerstellungen und dann das CAPTCHA der Login-Seite; ist es korrekt, stellt sie ein Token aus ([auth/registration_pass.py]) und leitet auf das Registrierungsformular weiter. Ein Fehlschlag wird als fehlgeschlagener Login-Versuch gezählt (mit einem leeren Benutzernamen);
- Zeilen 78–83: das Formular, nur mit einem gültigen Pass: Wer die Adresse [/register] direkt eingibt, wird auf die Login-Seite weitergeleitet;
- Zeilen 89–133: Kontoerstellung: - der Pass, erneut; - [form.validate()] wird aufgerufen, sein Ergebnis aber ignoriert: Wir wollen alle Eingabefehler auf einmal, einschließlich einer etwaigen Abweichung zwischen Passwort und Bestätigung, die dann von der Aktion geprüft wird (sofern beide Felder ansonsten gültig sind). Der Benutzer korrigiert sie alle auf einmal; - der Client und sein Konto werden mit derselben Methode der Geschäftslogik angelegt wie beim Administrator; - der Pass wird verbraucht, und die Erstellung wird vom Limiter gezählt; - Rückkehr zur Login-Seite, mit einer Meldung und vorbefülltem Login (Parameter [login] aus der URL). Das Pass-Cookie wird gelöscht.
11.16.6. controllers/area.py
Die persönlichen Seiten des Patienten.
| # =========================================================================
# controllers/area.py
# -------------------------------------------------------------------------
# Die PERSÖNLICHEN Seiten des Patienten (Rolle USER), die er direkt
# nach der Anmeldung sieht:
#
# GET /my-area Startseite: [Manage my account],
# [View a schedule] und sein bevorstehender Termin
# POST /my-area/cancel storniert SEINEN Termin
# GET /my-account Formular zur Bearbeitung seines Kontos
# POST /my-account Bearbeitung
# POST /my-account/delete Löschung des Kontos (und seiner Termine)
#
# Goldene Regel dieses Controllers: Der betroffene Patient ist IMMER der aus dem
# Token (utils.connected_patient), nie eine vom Browser gesendete Kennung. Ein Patient kann daher
# weder sehen noch bearbeiten noch stornieren, was einem anderen Patienten
# gehört, selbst wenn er seine Anfragen selbst manipuliert.
#
# Jede Bearbeitung oder Löschung des Kontos erfordert das AKTUELLE
# Passwort: Jemand, der eine offen gelassene Sitzung gefunden hat, könnte
# weder das Passwort ändern noch das Konto löschen. Fehler beim aktuellen
# Passwort werden als Login-Fehlversuche gezählt (gleiche Grenze).
# =========================================================================
from flask import Blueprint, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import require_roles
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.entities import Client, Role
from rdvmedecins.forms.forms import MyAccountForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (AreaModel, Message, MyAccountModel, AppointmentView,
PersonValues)
from rdvmedecins.web import utils, validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, auth_service, limiter
area = Blueprint("area", __name__)
# alle Aktionen dieses Blueprints sind der Rolle USER vorbehalten
@area.before_request
def patient_only():
require_roles(Role.USER)
# -----------------------------------------------------------------------
# GET /my-area
# -----------------------------------------------------------------------
@area.get("/my-area")
def patient_area():
patient = utils.connected_patient(application())
appointments = [AppointmentView(
a.id,
utils.format_day(a.day),
utils.time(a.slot),
utils.label(a.slot.doctor),
# Link zum Terminkalender des Arztes an diesem Tag: Der Patient sieht dort seinen Namen
url_for("schedule.show", doctorId=a.slot.doctor_id, day=utils.iso(a.day)))
for a in application().get_client_upcoming_appointments(patient.id)]
model = AreaModel("AREA.TITLE", None, utils.label(patient), appointments)
return render_template("area.html", model=model)
# -----------------------------------------------------------------------
# POST /my-area/cancel Feld: appointmentId
# -----------------------------------------------------------------------
@area.post("/my-area/cancel")
def cancel_appointment():
patient = utils.connected_patient(application())
appointment_id = utils.positive_integer(request.form.get("appointmentId"))
appointment = application().get_appointment_by_id(appointment_id) if appointment_id is not None else None
# ein Termin, der nicht existiert, und der eines ANDEREN Patienten erhalten
# dieselbe Antwort: Über die Termine anderer wird nichts verraten
if appointment is None or appointment.client_id != patient.id:
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(url_for("area.patient_area"))
# -----------------------------------------------------------------------
# GET /my-account
# -----------------------------------------------------------------------
@area.get("/my-account")
def account_form():
patient = utils.connected_patient(application())
values = PersonValues(patient.title, patient.first_name, patient.last_name, patient.user.login,
patient.version)
return show(values, {}, None, None)
# -----------------------------------------------------------------------
# POST /my-account
# -----------------------------------------------------------------------
@area.post("/my-account")
def edit_account():
patient = utils.connected_patient(application())
form = MyAccountForm()
form.validate()
values = PersonValues(form.title.data or patient.title, form.first_name.data or "",
form.last_name.data or "", form.login.data or "", form.version.data)
errors = validation.errors_of(form)
if "password" not in errors and form.password.data is not None \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# das aktuelle Passwort
password_error = check_current_password(patient, form.current_password.data)
if password_error is not None:
# falsches Passwort: Die Nachricht steht auch UNTER dem Feld
field_errors = ({"current_password": password_error.key}
if password_error.key == "ERRORS.WRONG_CURRENT_PASSWORD" else {})
return show(values, field_errors, password_error, None)
try:
client = application().edit_client(patient.id, PersonData(
form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, # None = unverändert
form.version.data))
except BusinessException as e:
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# das Login und der angezeigte Name stehen IM Token: Es wird ein neues
# ausgestellt, sonst würde die Navigationsleiste den alten Namen behalten
flash_success("MY_ACCOUNT.UPDATED")
response = redirect(url_for("area.patient_area"))
auth_service().set_token(response, client.user)
return response
# -----------------------------------------------------------------------
# POST /my-account/delete Feld: delete_password
# Das Konto, der Client und ALLE seine Termine verschwinden zusammen,
# dann wird der Patient abgemeldet.
# -----------------------------------------------------------------------
@area.post("/my-account/delete")
def delete_account():
patient = utils.connected_patient(application())
password_error = check_current_password(
patient, request.form.get("delete_password"))
if password_error is not None:
flash_error(password_error.key, **password_error.params)
return redirect(url_for("area.account_form"))
application().delete_client(patient.id)
flash_success("MY_ACCOUNT.DELETED")
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# interne Funktionen
# None, wenn das aktuelle Passwort korrekt ist; sonst die Fehlermeldung
def check_current_password(patient: Client, password: str | None) -> Message | None:
ip = ip_address()
login = patient.user.login
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)})
ok = bool(password) and auth_service().validate_user(login, password) is not None
if not ok:
limiter().login_failure(ip, login)
return Message("ERRORS.WRONG_CURRENT_PASSWORD")
return None
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = MyAccountModel("MY_ACCOUNT.TITLE", validation.page_message(errors, error), values,
validation.state(errors, other_fields))
return render_template("account.html", model=model)
|
- Zeilen 43–45: Alle Aktionen des Blueprints sind der Rolle USER vorbehalten;
- Zeilen 51–63: das Dashboard des Patienten: seine bevorstehenden Termine, formatiert, jeweils mit einem Link zum Terminkalender des Arztes für diesen Tag. Der Patient ist immer der dem Token zugeordnete ([utils.connected_patient]), niemals ein vom Browser gesendeter Bezeichner: Ein Patient kann die Daten eines anderen Patienten weder einsehen noch ändern oder stornieren;
- Zeilen 69–81: Stornierung des Termins des Patienten. Ein nicht existierender Termin und der Termin eines anderen Patienten erhalten die gleiche Antwort: Es werden keine Informationen über die Termine anderer Patienten preisgegeben (andernfalls könnte ein Patient herausfinden, welche Terminnummern existieren);
- Zeilen 87–92: das Kontoformular des Benutzers, vorbefüllt;
- Zeilen 98–133: die Bearbeitung: Validierung der Felder und der Bestätigung, Überprüfung des aktuellen Passworts, dann ein Aufruf der Geschäftsschicht. Der Login und der angezeigte Name stehen im Token: Die Aktion stellt ein neues aus; andernfalls würde die Navigationsleiste bis zum nächsten Login den alten Namen behalten;
- Zeilen 141–153: Kontolöschung, die ebenfalls durch das aktuelle Passwort geschützt ist. Das Konto, der Client und alle seine Termine werden gemeinsam gelöscht; der Patient wird abgemeldet;
- Zeilen 159–169: Das aktuelle Passwort schützt das Konto vor jedem, der eine offen gebliebene Sitzung findet. Fehleingaben werden als Login-Fehlschläge mit derselben Begrenzung gezählt: Mit ihnen lässt sich das Passwort nicht erraten.
11.17. Die Views
Der Ordner [templates] enthält die [Jinja2]-Views der Anwendung: ein Template, sieben Fragmente und acht Seiten. Alle folgen derselben Regel: keine Logik in den Views. Aktionen übergeben ihnen vorbereitete Modelle ([models/view_models.py]); die Views setzen die Daten lediglich in HTML ein und übersetzen die Texte mit der Funktion [t]. Sie enthalten keine fest codierten Texte: Alles läuft über die Wörterbücher.
11.17.1. Das Template und die Fragmente
11.17.1.1. templates/layout.html
| <!doctype html>
{# =========================================================================
templates/layout.html
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Das für alle Seiten GEMEINSAME Layout (siehe Beispiel 15): jede Seite
(schedule.html, login.html...) ERWEITERT es ({% extends %}) und füllt ihren Block
[content].
Jinja2 MASKIERT alles, was es mit {{ ... }} ausgibt (die Zeichen
< > & " ' werden zu < >...): Schutz vor HTML-Injection
zum Beispiel über einen eingegebenen Namen. Um HTML unverändert einzufügen, muss das
ausdrücklich verlangt werden (Filter safe, siehe fragments/captcha.html).
Meldungen: ein Erfolg wird OBEN auf der Seite angezeigt, ein Fehler UNTEN, auf
hellrosa Hintergrund (Fragment errors.html).
Das Layout teilt die Variablen der Seite: [model] (das von der Action übergebene
View-Modell, siehe models/view_models.py), aus dem es den Schlüssel des
Seitentitels liest; [language], [user], [path], [t], allen Views
von web/common_model.py hinzugefügt.
========================================================================= #}
<html lang="{{ language }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# t(key): die Übersetzung eines Schlüssels; hier ist der Schlüssel eine VARIABLE (model.page_title) #}
<title>{{ t(model.page_title) }} - {{ t("APP.TITLE") }}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='lib/bootstrap/css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
{# die Flash-Meldungen der vorherigen Anfrage: EINMAL gelesen
(get_flashed_messages vergisst sie sofort), dann aufgeteilt: die Erfolge
oben, die Fehler unten #}
{% set flashes = get_flashed_messages(with_categories=true) %}
<div class="container py-4">
{% include "fragments/navbar.html" %}
{% include "fragments/flash.html" %}
<main>
{% block content %}{% endblock %}
</main>
{% include "fragments/errors.html" %}
</div>
{# der Dialog "Are you sure?", versteckt, bis er gebraucht wird #}
{% include "fragments/confirmation.html" %}
<script src="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
|
- Zeile 22: die Sprache der Seite, vom Context Processor geliefert;
- Zeile 27: der Seitentitel. Der Titelschlüssel ist eine Variable ([model.page_title]): Jedes Seiten-Template liefert eine (das Verfahren aus Beispiel 22, wobei das View-Template statt einer [{% set %}]-Variable verwendet wird);
- Zeile 28: [Bootstrap] ist Teil der Anwendung und liegt in deren Ordner [static];
- Zeile 35: Flash-Meldungen werden vom Template nur einmal gelesen; [get_flashed_messages] vergisst sie sofort, und ein zweiter Aufruf würde eine leere Liste liefern. Mit [with_categories=true] liefert die Funktion Tupel (Kategorie, Meldung). Die Variable [flashes] wird dann von den beiden Fragmenten gelesen, die sie anzeigen: Erfolgsmeldungen oben, Fehlermeldungen unten. Eine mit [{% set %}] definierte Variable ist in den mit [{% include %}] eingebundenen Fragmenten sichtbar;
- Zeilen 37–42: die Navigationsleiste, die Erfolgsmeldungen, der Seiteninhalt und der Fehlerbereich;
- Zeilen 45–46: das Bestätigungsfenster und das Skript, das es verwaltet (Beispiel 21).
11.17.1.2. templates/fragments/navbar.html
| {# =========================================================================
templates/fragments/navbar.html - die Navigationsleiste.
Titel, FR/EN, Rolle, Name, Abmelden - und ein Menü, dessen Einträge
von der Rolle abhängen: "Doctors" und "Patients" erscheinen nur für
den ADMIN. Das ist nur eine Anzeigehilfe: der echte Schutz sind
die Rollenprüfungen der Actions (ein USER, der /doctors von Hand
eingibt, erhält eine 403-Seite). Ein Patient (USER) hat zusätzlich sein Menü "My area".
Das Menü der aktuellen Seite wird hervorgehoben (Klasse "active"):
[path] ist die angeforderte URL (siehe web/common_model.py). Ein Makro schreibt
einmal das HTML eines Menüeintrags; sein optionaler Parameter [prefix]
(standardmäßig href) ist der Anfang der Pfade, für die der Eintrag aktiv ist.
========================================================================= #}
{% macro entry(href, key, prefix=none) %}
<li class="nav-item">
<a class="nav-link{{ ' active' if path.startswith(prefix or href) }}" href="{{ href }}">{{ t(key) }}</a>
</li>
{% endmacro %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ t("APP.TITLE") }}</span>
{% if user %}
<ul class="navbar-nav me-auto">
{% if user.is_patient %}
{# aktiv für /my-area UND /my-account #}
{{ entry("/my-area", "APP.MENU_MY_AREA", "/my-") }}
{% endif %}
{{ entry("/schedule", "APP.MENU_SCHEDULE") }}
{% if user.is_admin %}
{{ entry("/doctors", "APP.MENU_DOCTORS") }}
{{ entry("/clients", "APP.MENU_PATIENTS") }}
{% endif %}
</ul>
{% else %}
<div class="me-auto"></div>
{% endif %}
<div class="d-flex align-items-center gap-2">
{# FR / EN: einfache Links (GET /language/fr), die aktive Sprache hervorgehoben #}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
{% for code in ["fr", "en"] %}
<a class="btn {{ 'btn-light' if language == code else 'btn-outline-light' }}" href="/language/{{ code }}">{{ code | upper }}</a>
{% endfor %}
</div>
{% if user %}
<span class="badge text-bg-light text-primary">{{ user.role }}</span>
<span class="text-white">{{ user.name }}</span>
{# das Abmelden ist ein POST: ein Formular, reduziert auf seinen Button (und das Anti-CSRF-Token) #}
<form method="post" action="/logout" class="m-0">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-light">{{ t("APP.LOGOUT") }}</button>
</form>
{% endif %}
</div>
</nav>
|
- Zeilen 15–19: ein Menüeintrag, hervorgehoben (Klasse [active]), wenn der Pfad der aktuellen Seite mit seinem Präfix beginnt. Der Parameter [prefix] ist optional ([none] für [Jinja2], so wie [None] für [Python]); andernfalls ist es die Adresse des Eintrags ([prefix or href]). Der Eintrag „Mein Bereich“ hat das Präfix [/my-]: Er ist sowohl für [/my-area] als auch für [/my-account] aktiv;
- Zeilen 23–37: Das Menü hängt von der Rolle ab: „Mein Bereich“ für einen Patienten, „Ärzte“ und „Patienten“ für den Administrator. Das ist lediglich eine Anzeigeerleichterung; die echte Sicherheit stammt aus den rollenbasierten Kontrollen der Aktionen. Ein Patient, der [/doctors] manuell eingibt, erhält eine 403-Fehlerseite;
- Zeilen 42–44: Die Schaltflächen FR und EN sind einfach Links auf [/language/fr] und [/language/en];
- Zeilen 48–54: Rolle, Benutzername und Logout: ein auf seine Schaltfläche reduziertes POST-Formular mit dem Anti-CSRF-Token.
11.17.1.3. templates/fragments/flash.html
| {# =========================================================================
templates/fragments/flash.html - die ERFOLGSMELDUNGEN, von
der vorherigen Action hinterlegt (Termin gespeichert, Arzt hinzugefügt...),
nur einmal angezeigt, oben auf der Seite (siehe web/flash.py).
Eine FEHLER-Flash-Meldung wird unten auf der Seite angezeigt, von
fragments/errors.html angezeigt.
[flashes]: die Liste der Paare (category, message), vom Layout gelesen.
t(message.key, message.params): die Meldung, deren Schlüssel
message.key ist, mit dem Dictionary der Werte von {name},
{login}... als Parameter (siehe web/translator.py).
========================================================================= #}
{% for category, message in flashes if category == "success" %}
<div class="alert alert-success" role="status">{{ t(message.key, message.params) }}</div>
{% endfor %}
|
- Zeile 13: Eine [for]-Schleife von [Jinja2] kann ihre Elemente filtern: [for ... in ... if condition] durchläuft nur die Elemente, die die Bedingung erfüllen. Jedes Element ist ein Paar, dessen beide Teile in zwei Variablen gespeichert werden;
- Zeile 14: Die Meldung ist ein Dictionary (siehe [web/flash.py]): sein Schlüssel und seine Parameter. Die Punktnotation in [Jinja2] liest auch die Schlüssel eines Dictionarys (Beispiel 13).
11.17.1.4. templates/fragments/errors.html
| {# =========================================================================
templates/fragments/errors.html - die Fehlerzone, UNTEN auf jeder
Seite, auf hellrosa Hintergrund (Klasse .error-zone, siehe static/css/styles.css).
Sie fasst die beiden möglichen Fehlerquellen zusammen:
- model.error: der Fehler der angezeigten Seite (abgelehntes Formular, Login
oder Vor- + Nachname bereits verwendet, ungültiges Datum, falsches Passwort...);
- die Fehler-Flash-Meldungen, von der vorherigen Action vor einer
Weiterleitung hinterlegt (Zeitfenster bereits gebucht, Löschen abgelehnt...).
Eine for-Schleife kann ihre Elemente filtern: "for ... in ... if condition".
role="alert": ein Screenreader liest die Meldung vor, sobald die Seite
angezeigt wird, auch wenn sie unten steht.
========================================================================= #}
{% set flash_errors = flashes | selectattr(0, "equalto", "danger") | list %}
{% if model.error or flash_errors %}
<div class="error-zone" role="alert">
{% if model.error %}
<div>{{ t(model.error.key, model.error.params) }}</div>
{% endif %}
{% for category, message in flash_errors %}
<div>{{ t(message.key, message.params) }}</div>
{% endfor %}
</div>
{% endif %}
|
- Zeile 15: Fehler-Flash-Meldungen, von zwei Filtern extrahiert: [selectattr(0, "equalto", "danger")] behält nur die Elemente, deren Attribut [0] (das erste Element des Paares, die Kategorie) gleich ["danger"] ist; [list] wandelt das Ergebnis in eine Liste um (Filter dieser Art liefern einen Iterator, der nur einmal durchlaufen werden kann und dessen Leere sich nicht prüfen lässt);
- Zeilen 16–25: Der Fehlerbereich vereint die beiden Fehlerquellen: Fehler der angezeigten Seite (ein abgelehntes Formular, ein ungültiges Datum) und Fehler, die von der vorherigen Aktion vor einer Weiterleitung erzeugt wurden (ein bereits belegtes Zeitfenster, eine abgelehnte Löschung). Der Bereich existiert nur, wenn es mindestens einen Fehler gibt.
11.17.1.5. templates/fragments/confirmation.html
| {# =========================================================================
templates/fragments/confirmation.html - der modale Dialog "Are you sure?".
Er ersetzt die Box window.confirm() des Browsers, das sich weder
gestalten noch übersetzen lässt (seine Buttons bleiben in der Sprache des
Browsers, nicht in der der Seite).
EIN EINZIGER Dialog für die ganze Seite, zunächst versteckt (d-none). Seine
Beschriftungen werden hier vom Server übersetzt, wie der Rest der Seite;
das kleine Skript static/js/app.js zeigt ihn lediglich an, setzt die
für das Formular spezifische Meldung ein (Attribut data-confirmation) und sendet
das Formular ab, wenn der Benutzer bestätigt.
Dieselben Bootstrap-Klassen wie der Buchungsdialog (fragments/booking.html).
========================================================================= #}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="confirmation-modal-title">{{ t("CONFIRMATION.TITLE") }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ t('BOOKING_DIALOG.CLOSE_ARIA') }}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
{# "No, go back" statt "Cancel": die Frage lautet manchmal
"Cancel this appointment?", und ein Button "Cancel" wäre dort mehrdeutig #}
<button type="button" class="btn btn-secondary" data-action="no">{{ t("CONFIRMATION.NO") }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ t("CONFIRMATION.YES") }}</button>
</div>
</div>
</div>
</div>
</div>
|
Das Bestätigungsfenster aus Beispiel 21, mit vom Server übersetzten Beschriftungen (das Feld [window.confirm()] des Browsers zeigt seine Schaltflächen in der Sprache des Browsers an, nicht in der Sprache der Seite), einer Schließen-Schaltfläche und Barrierefreiheitsattributen: [aria-labelledby] und [aria-describedby] verweisen auf den Titel und die Meldung des Fensters, die Screenreader beim Öffnen des Fensters vorlesen. Die Schaltfläche „Nein, zurück“ wird gegenüber „Abbrechen“ bevorzugt: Die Frage lautet manchmal „Diesen Termin stornieren?“, und eine Schaltfläche „Abbrechen“ wäre in diesem Zusammenhang mehrdeutig.
11.17.1.6. templates/fragments/captcha.html
| {# =========================================================================
templates/fragments/captcha.html - das CAPTCHA der Authentifizierungsseite
(siehe auth/captcha.py). Es schützt sowohl das Login als auch den Zugang zur
Kontoerstellung (Button "Create a patient account").
Ein Makro, dessen Parameter ein Captcha-Objekt ist (id, svg).
Der Filter safe: das SVG-Bild wird UNVERÄNDERT in die Seite eingefügt, ohne
Maskierung. Das ist hier harmlos, weil dieses SVG vom Server selbst erzeugt wird
und nichts vom Benutzer Eingegebenes enthält - bei einer Eingabe würde man das
NIEMALS tun.
Das versteckte Feld captchaId teilt dem Server mit, WELCHES CAPTCHA zu prüfen ist; die
richtige Antwort selbst wird nie an den Browser gesendet.
"Another image" lädt einfach die Seite neu ([path] = die aktuelle URL).
Ein Makro sieht die Variablen der aufrufenden Seite nicht ("with
context": bei login.html sieht es sie beim Import): hier t und path.
========================================================================= #}
{% macro captcha(captcha) %}
<div class="mb-3">
<label class="form-label" for="captcha">{{ t("CAPTCHA.LABEL") }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ t('CAPTCHA.IMAGE_ALT') }}">{{ captcha.svg | safe }}</div>
<a class="small" href="{{ path }}">{{ t("CAPTCHA.NEW_IMAGE") }}</a>
</div>
<input type="hidden" name="captchaId" value="{{ captcha.id }}">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
spellcheck="false" required class="form-control">
<div class="form-text">{{ t("CAPTCHA.HELP") }}</div>
</div>
{% endmacro %}
|
- Zeile 18: ein Makro, das ein Objekt [Captcha] erhält;
- Zeile 22: das SVG-Bild, unverändert eingefügt (Beispiel 27). Das Attribut [role="img"] und sein [aria-label] beschreiben das Bild für Screenreader;
- Zeile 23: Der Link „Anderes Bild“ lädt die Seite einfach neu: Jede View erzeugt ein neues CAPTCHA;
- Zeilen 25–27: die CAPTCHA-ID und das Eingabefeld. [autocapitalize="off"] und [spellcheck="false"] verhindern, dass Smartphones die Eingabe verändern (Großbuchstabe am Anfang, Rechtschreibprüfung).
Standardmäßig kann ein importiertes Makro nicht auf die Variablen der importierenden Seite zugreifen: Die Funktion [t] und die vom Context Processor gelieferte Variable [path]wären ihm unbekannt. Deshalb importiert [login.html] es mit dem Zusatz [with context].
11.17.1.7. templates/fragments/person_fields.html
| {# =========================================================================
templates/fragments/person_fields.html - die Identitätsfelder (Anrede,
Vorname, Nachname), gemeinsam für drei Formulare: Arzt/Client des ADMIN,
"Create a patient account" und "Manage my account".
Das mit {% include %} eingefügte Fragment liest die Variable [model] der
einfügenden Seite (eine FormView, siehe models/view_models.py):
Werte, Meldung unter jedem Feld, rot umrandete Felder.
selected: ein boolesches Attribut, geschrieben, wenn die Option gewählt ist, sonst
weggelassen. state.invalid_class(field): "is-invalid" (rote Umrandung von Bootstrap)
für ein abgelehntes Feld, sonst "".
========================================================================= #}
{% set state = model.state %}
<div class="mb-3">
<label class="form-label" for="title">{{ t("PERSONS.TITLE_LABEL") }}</label>
<select id="title" name="title" class="form-select {{ state.invalid_class('title') }}">
{% for title in model.titles %}
<option value="{{ title.value }}"{{ " selected" if title.selected }}>{{ title.value }}</option>
{% endfor %}
</select>
{% if state.error_of("title") %}
<div class="invalid-feedback">{{ t(state.error_of("title")) }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="first_name">{{ t("PERSONS.FIRSTNAME_LABEL") }}</label>
<input id="first_name" name="first_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('first_name') }}" value="{{ model.values.first_name }}">
{% if state.error_of("first_name") %}
<div class="invalid-feedback">{{ t(state.error_of("first_name")) }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="last_name">{{ t("PERSONS.LASTNAME_LABEL") }}</label>
<input id="last_name" name="last_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('last_name') }}" value="{{ model.values.last_name }}">
{% if state.error_of("last_name") %}
<div class="invalid-feedback">{{ t(state.error_of("last_name")) }}</div>
{% endif %}
</div>
</div>
|
Die Identitätsfelder (Anrede, Vorname, Nachname), die allen drei Formularen der Anwendung gemeinsam sind. Das mit [{% include %}] eingefügte Fragment liest die Variable [model] der Seite, die es einfügt: ein Template, das von [FormView] erbt.
- Zeilen 16–20: die Liste der Anreden, berechnet von der Eigenschaft [titles] des Templates, wobei die ausgewählte Anrede hervorgehoben ist;
- Zeilen 29–30: das Eingabefeld für den Vornamen, mit dem erneut anzuzeigenden Wert und der Klasse [is-invalid] , wenn das Feld abgelehnt wird ([state.invalid_class('first_name')]);
- Zeilen 31–33: die Meldung unter dem Feld, übersetzt.
Die Attribute [maxlength] und [required] sind Kontrollen des Browsers. Die Formulare der Anwendung enthalten das Attribut [novalidate] (Beispiel 19): Diese Prüfungen werden vor dem Absenden nicht durchgeführt; die Validierung übernimmt der Server. [maxlength] hindert Benutzer dagegen immer daran, mehr Zeichen einzugeben, als eine Spalte aufnehmen kann.
11.17.1.8. templates/fragments/booking.html
| {# =========================================================================
templates/fragments/booking.html - der Buchungsdialog des
Terminkalenders.
Die ECHTEN Bootstrap-Klassen eines modalen Dialogs (.modal,
.modal-backdrop...), fest codiert sichtbar gemacht (show d-block) statt
durch das JavaScript von Bootstrap. Der SERVER entscheidet, ihn anzuzeigen
(URL-Parameter &book=...), und ihn zu schließen bedeutet, einem Link
auf dieselbe Seite ohne diesen Parameter zu folgen.
Das Fragment liest direkt die Variable [model] der Seite, die es einfügt
(ein ScheduleModel).
========================================================================= #}
{% set booking = model.booking %}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
<div class="modal-dialog modal-dialog-centered">
<form method="post" action="/schedule/book" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ t("BOOKING_DIALOG.TITLE") }}</h5>
<a class="btn-close" href="{{ model.back_url }}" aria-label="{{ t('BOOKING_DIALOG.CLOSE_ARIA') }}"></a>
</div>
<div class="modal-body">
<p>{{ t("BOOKING_DIALOG.SLOT", time=booking.time) }}</p>
{# was der Server zusätzlich zum gewählten Patienten wissen muss #}
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.day }}">
<input type="hidden" name="slotId" value="{{ booking.slot_id }}">
{# ein Patient bucht für sich selbst: keine Auswahlliste
(und der Server ignoriert eine eventuelle clientId ohnehin) #}
{% if booking.patient %}
<p class="mb-0">
<span>{{ t("BOOKING_DIALOG.PATIENT_LABEL") }}</span>:
<strong>{{ booking.patient }}</strong>
</p>
{% else %}
<label class="form-label" for="clientId">{{ t("BOOKING_DIALOG.PATIENT_LABEL") }}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{ t("BOOKING_DIALOG.CHOOSE_PATIENT") }}</option>
{% for client in booking.clients %}
<option value="{{ client.id }}">{{ client.label }}</option>
{% endfor %}
</select>
{% endif %}
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{ model.back_url }}">{{ t("BOOKING_DIALOG.CANCEL") }}</a>
<button type="submit" class="btn btn-primary">{{ t("BOOKING_DIALOG.CONFIRM") }}</button>
</div>
</form>
</div>
</div>
|
Das Reservierungsfenster. Es verwendet die tatsächlichen Klassen eines modalen Fensters von [Bootstrap] ([modal], [modal-backdrop] ...), die „fest codiert“ sichtbar gemacht werden ([show d-block]), statt über das [JavaScript] von [Bootstrap]: Der Server entscheidet, ob es angezeigt wird (der Parameter [book] der URL), und sein Schließen entspricht dem Aufruf eines Links auf dieselbe Seite ohne diesen Parameter ([model.back_url]).
- Zeilen 29–31: Versteckte Felder: Informationen, die der Server zusätzlich zum ausgewählten Patienten kennen muss;
- Zeilen 35–48: Ein Patient bucht für sich selbst: Sein Name wird angezeigt, ohne Auswahlliste (und der Server würde ein Feld [clientId] ohnehin ignorieren). Für einen Administrator wird die Liste der Patienten angezeigt, deren erste Option mit leerem Wert zur Auswahl auffordert.
11.17.2. Die Seiten
11.17.2.1. templates/login.html
| {# =========================================================================
templates/login.html - das Login-Formular (siehe controllers/auth.py).
Ein gewöhnliches HTML-<form>: der Browser selbst sendet Login,
Passwort und CAPTCHA-Antwort per POST /login, ohne JavaScript. Bei
Fehlschlag sendet der Server DIESE Seite zurück, mit dem bereits eingegebenen Login, einem
NEUEN CAPTCHA und dem Fehler, der vom Layout unten auf der Seite angezeigt wird.
========================================================================= #}
{% extends "layout.html" %}
{# with context: das Makro sieht die Variablen dieser Seite (t, path) #}
{% from "fragments/captcha.html" import captcha with context %}
{% block content %}
{% set login_typed = model.login != "" %}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t("LOGIN.TITLE") }}</h5>
<form method="post" action="/login">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="mb-3">
<label class="form-label" for="login">{{ t("LOGIN.LOGIN_LABEL") }}</label>
{# autofocus: ein boolesches Attribut, geschrieben, wenn die Bedingung wahr ist, sonst weggelassen #}
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{ model.login }}" required{{ " autofocus" if not login_typed }}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ t("LOGIN.PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required{{ " autofocus" if login_typed }}>
</div>
{{ captcha(model.captcha) }}
<button type="submit" class="btn btn-primary w-100">{{ t("LOGIN.SUBMIT") }}</button>
{# noch kein Konto: ein Patient kann selbst eines anlegen.
Es ist KEIN einfacher Link: es ist ein zweiter Submit-Button
DIESES Formulars, der an eine andere Adresse geht (formaction). Der
Server prüft dort das obige CAPTCHA, bevor er die Seite zur
Kontoerstellung öffnet (siehe controllers/registration.py).
formnovalidate: der Browser verlangt Login und Passwort nicht
(für die Kontoerstellung unnötig); der Server prüft
das CAPTCHA. Enter in einem Feld löst immer den ERSTEN
Button des Formulars aus, "Log in". #}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="/register/access" formnovalidate>{{ t("LOGIN.CREATE_ACCOUNT") }}</button>
<div class="form-text text-center">{{ t("LOGIN.CREATE_ACCOUNT_HELP") }}</div>
</form>
<div class="text-muted small mt-3">
<span>{{ t("LOGIN.DEMO_ACCOUNTS") }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ t("LOGIN.DEMO_ADMIN") }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ t("LOGIN.DEMO_DOCTOR") }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ t("LOGIN.DEMO_USER") }}</span></li>
</ul>
</div>
</div>
</div>
</div>
{% endblock %}
|
- Zeile 10: Das Makro wird zusammen mit dem Kontext der Seite importiert;
- Zeile 13: Der Cursor wird in das Login-Feld gesetzt, wenn es leer ist, andernfalls in das Passwortfeld (nach einem fehlgeschlagenen Login-Versuch oder nach dem Erstellen eines Kontos): Das boolesche Attribut [autofocus] wird beim einen oder beim anderen gesetzt;
- Zeilen 24–30: Die Werte des Attributs [autocomplete] helfen den Passwortmanagern der Browser, das Formular auszufüllen;
- Zeilen 46–47: Die Schaltfläche „Patientenkonto erstellen“ ist kein Link, sondern eine zweite Schaltfläche zum Absenden dieses Formulars, die es an eine andere Adresse sendet ([formaction], Beispiel 20). Dort prüft der Server das CAPTCHA, bevor er die Seite zur Kontoerstellung öffnet. [formnovalidate]: Der Browser verlangt Benutzername und Passwort nicht, die als [required] markiert sind und für die Kontoerstellung nicht nötig sind. Das Drücken der Eingabetaste in einem Feld löst immer die erste Schaltfläche des Formulars aus, „Anmelden“.
11.17.2.2. templates/schedule.html
| {# =========================================================================
templates/schedule.html - die Hauptseite (siehe controllers/schedule.py).
Drei Blöcke:
1. die Wahl des Arztes und des Tages;
2. der Terminkalender;
3. der Buchungsdialog (fragments/booking.html).
Ein möglicher Fehler (ungültiges Datum, unbekannter Arzt) wird unten
auf der Seite vom Layout angezeigt (siehe fragments/errors.html).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{# 1. Wahl des Arztes und des Tages: ein GET-Formular, das diese Seite
einfach mit ?doctorId=...&day=... in der URL neu lädt #}
<form method="get" action="/schedule" class="card p-3 mb-3">
<div class="row g-2 align-items-end">
<div class="col-sm-5">
<label class="form-label" for="doctorId">{{ t("DOCTOR_DAY_PICKER.DOCTOR_LABEL") }}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{ t("DOCTOR_DAY_PICKER.CHOOSE_DOCTOR") }}</option>
{% for doctor in model.doctors %}
<option value="{{ doctor.id }}"{{ " selected" if doctor.selected }}>{{ doctor.label }}</option>
{% endfor %}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ t("DOCTOR_DAY_PICKER.DAY_LABEL") }}</label>
<input id="day" name="day" type="date" class="form-control" value="{{ model.day }}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{ t("DOCTOR_DAY_PICKER.VIEW_SCHEDULE") }}</button>
</div>
</div>
</form>
{# Patient, der bereits einen bevorstehenden Termin hat: deshalb gibt es keinen Button "Book" #}
{% if model.info %}
<div class="alert alert-info">
<span>{{ t(model.info) }}</span>
<a href="/my-area" class="alert-link">{{ t("APP.MENU_MY_AREA") }}</a>
</div>
{% endif %}
{# 2. der Terminkalender #}
{% set schedule = model.schedule %}
{% if schedule %}
<div class="card p-3">
<h5>{{ t("SCHEDULE.TITLE_PREFIX") }} {{ schedule.day }} - {{ schedule.doctor }}</h5>
{% if schedule.rows %}
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{ t("SCHEDULE.COLUMN_SLOT") }}</th>
<th>{{ t("SCHEDULE.COLUMN_STATUS") }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for row in schedule.rows %}
<tr class="{{ 'free-slot' if row.bookable }}">
<td>{{ row.time }}</td>
<td>
{# [patient] ist nur gefüllt, wenn der Benutzer diesen Namen
sehen darf (ADMIN, DOCTOR oder der Patient für SEINEN
Termin) - andernfalls einfach "Booked" #}
{% if row.free %}
<span class="badge text-bg-success">{{ t("SCHEDULE.FREE") }}</span>
{% elif row.patient %}
<span class="badge {{ 'text-bg-primary' if row.mine else 'text-bg-secondary' }}">{{ row.patient }}</span>
{% else %}
<span class="badge text-bg-secondary">{{ t("SCHEDULE.BOOKED_BY_OTHER") }}</span>
{% endif %}
</td>
<td>
{# die angezeigten Buttons wurden vom Controller entschieden
(bookable, appointment_id) je nach Rolle des Benutzers.
"Book" ist ein einfacher Link: er öffnet diese Seite erneut
mit dem Buchungsdialog dieses Zeitfensters #}
{% if row.bookable %}
<a class="btn btn-sm btn-outline-success" href="{{ row.book_url }}">{{ t("SCHEDULE.BOOK") }}</a>
{% endif %}
{# "Cancel" ÄNDERT Daten: es ist daher ein POST #}
{% if row.appointment_id %}
<form method="post" action="/schedule/cancel" class="m-0"
data-confirmation="{{ t('SCHEDULE.CANCEL_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ row.appointment_id }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.day }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("SCHEDULE.CANCEL_APPOINTMENT") }}</button>
</form>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t("SCHEDULE.NO_SLOTS") }}</p>
{% endif %}
</div>
{% else %}
<p class="text-muted">{{ t("SCHEDULE.EMPTY_STATE") }}</p>
{% endif %}
{# 3. der Buchungsdialog, nur wenn die URL &book=... enthält #}
{% if model.booking %}
{% include "fragments/booking.html" %}
{% endif %}
{% endblock %}
|
- Zeilen 15–34: Auswahl eines Arztes und eines Tages: ein GET-Formular (Beispiel 17), das die Seite einfach mit den Parametern [doctorId] and [day] in der URL neu lädt. Das Feld [<input type="date">] zeigt seine Werte im Format [yyyy-mm-dd] an, unabhängig von der Sprache, in der der Browser es darstellt;
- Zeilen 37–42: die Informationsmeldung für einen Patienten, der bereits einen bevorstehenden Termin hat;
- Zeilen 61–95: ein Eintrag im Terminkalender. Es gibt drei mögliche Zustände: frei, gebucht mit dem Namen des Patienten (in Blau, wenn es der Termin des angemeldeten Patienten ist) oder gebucht ohne Namen („Belegt“). Die angezeigten Schaltflächen bestimmt die Aktion. „Buchen“ ist ein einfacher Link: Er öffnet diese Seite erneut mit dem Reservierungsfenster für dieses Zeitfenster. „Stornieren“ ändert Daten: Es ist ein POST-Formular mit seiner Bestätigungsabfrage (Beispiel 21);
- Zeilen 108–110: das Buchungsfenster, nur wenn die Aktion es vorbereitet hat.
11.17.2.3. templates/persons/list.html
| {# =========================================================================
templates/persons/list.html - die Liste der Ärzte ODER der Clients (ADMIN).
Eine einzige View für beide: die jeweils spezifischen Beschriftungen kommen in
model.keys an (siehe controllers/doctors.py / controllers/clients.py).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ t(model.keys.title) }}</h4>
<a class="btn btn-primary" href="{{ model.add_url }}">{{ t(model.keys.add) }}</a>
</div>
<div class="card p-3">
{% if model.persons %}
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{ t("PERSONS.COLUMN_TITLE") }}</th>
<th>{{ t("PERSONS.COLUMN_FIRSTNAME") }}</th>
<th>{{ t("PERSONS.COLUMN_LASTNAME") }}</th>
<th>{{ t("PERSONS.COLUMN_LOGIN") }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for person in model.persons %}
<tr>
<td>{{ person.title }}</td>
<td>{{ person.first_name }}</td>
<td>{{ person.last_name }}</td>
<td><code>{{ person.login }}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary" href="{{ person.edit_url }}">{{ t("PERSONS.EDIT") }}</a>
{# data-confirmation: ein Bestätigungsdialog öffnet sich,
bevor das Formular gesendet wird (siehe static/js/app.js) #}
<form method="post" action="{{ person.delete_url }}" class="m-0"
data-confirmation="{{ t(model.keys.confirm_delete) }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("PERSONS.DELETE") }}</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t(model.keys.empty) }}</p>
{% endif %}
</div>
{% endblock %}
|
Eine einzige View für beide Listen, Ärzte und Clients: Die jeweils spezifischen Beschriftungen stehen in [model.keys]; [t(model.keys.title)] stellt einen Schlüssel dar, der selbst eine Variable ist. Jede Zeile hat einen Link „Bearbeiten“ und ein Formular „Löschen“, das eine Bestätigung erfordert.
| {# =========================================================================
templates/persons/form.html - Erstellen ODER Bearbeiten eines
Arztes oder eines Clients (ADMIN). model.creating unterscheidet die beiden Fälle.
Wenn die Eingabe abgelehnt wird (leeres Feld, Login bereits vergeben...), sendet die Action
DIESE View zurück mit:
- den bereits eingegebenen Werten (model.values);
- den fehlerhaften Feldern, rot umrandet (Bootstrap-Klasse "is-invalid");
- unter einem von der Validierung abgelehnten Feld seiner Meldung;
- der Fehlermeldung der Seite, die vom Layout UNTEN auf der Seite angezeigt wird
(siehe fragments/errors.html).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t(model.page_title) }}</h5>
{# novalidate: wir lassen den SERVER validieren (er ist die maßgebliche Instanz);
die Prüfungen des Browsers (required...) sind nur eine Hilfe,
die ein Benutzer immer umgehen kann #}
<form method="post" action="{{ model.action }}" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% if not model.creating %}
<input type="hidden" name="version" value="{{ model.values.version }}">
{% endif %}
{# Anrede, Vorname, Nachname: gemeinsames Fragment für drei Formulare #}
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="off"
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.LOGIN_HELP_CREATE" if model.creating else "PERSONS.LOGIN_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="mb-4">
<label class="form-label" for="password">{{ t("PERSONS.PASSWORD_LABEL") }}</label>
{# nie vorausgefüllt: das Passwort geht nie zurück an den Browser #}
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_CREATE" if model.creating else "PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("PERSONS.SAVE") }}</button>
<a class="btn btn-secondary" href="{{ model.list_url }}">{{ t("PERSONS.BACK") }}</a>
</div>
</form>
</div>
</div>
</div>
{% endblock %}
|
- Zeile 25: Die Zieladresse wird von der Aktion geliefert: [/doctors/add], [/clients/3/edit] ...;
- Zeilen 27–29: Beim Aktualisieren wird die Version des Datensatzes in einem versteckten Feld gespeichert (optimistisches Sperren);
- Zeile 32: die Identitätsfelder;
- Zeilen 38–44: der Login, optional, mit einem Tooltip, der davon abhängt, ob der Datensatz angelegt oder bearbeitet wird ([t("..." if model.creating else "...")]);
- Zeilen 50-50: Das Passwort wird nie vorbefüllt; es wird nie an den Browser zurückgesendet. [autocomplete="new-password"] verhindert, dass der Browser hier das Passwort des Administrators vorschlägt.
11.17.2.5. templates/registration.html
| {# =========================================================================
templates/registration.html - "Create a patient account" (öffentliche Seite,
siehe controllers/registration.py). Dieselben Identitätsfelder wie im Formular
des ADMIN (Fragment person_fields.html), aber Login und
Passwort sind Pflicht, mit Bestätigung.
Hier KEIN CAPTCHA: man gelangt nur auf diese Seite, nachdem man das
der Authentifizierungsseite eingegeben hat (Button "Create a patient account").
t(key, min=...): die Meldung, deren Schlüssel der Wert von [key] ist, mit dem
Parameter {min} (siehe web/translator.py).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1">{{ t("REGISTRATION.TITLE") }}</h5>
<p class="text-muted small mb-3">{{ t("REGISTRATION.INTRO") }}</p>
<form method="post" action="/register" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.LOGIN_HELP") }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{ t("PERSONS.PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.PASSWORD_HELP", min=model.password_min) }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{ t("ACCOUNT.CONFIRMATION_LABEL") }}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("REGISTRATION.SUBMIT") }}</button>
<a class="btn btn-secondary" href="/login">{{ t("REGISTRATION.BACK_TO_LOGIN") }}</a>
</div>
</form>
</div>
</div>
</div>
{% endblock %}
|
Das Formular zur Erstellung eines Patientenkontos: die Felder für die persönlichen Angaben, gefolgt von Benutzername, Passwort und Passwortbestätigung, sind Pflichtfelder. Die Meldung, dass ein Passwort zu kurz ist, hat einen Parameter, der die Mindestlänge angibt: [t(state.error_of("password"), min=model.password_min)]. Hier gibt es kein CAPTCHA: Auf diese Seite gelangt man nur nach Eingabe des CAPTCHA auf der Login-Seite.
11.17.2.6. templates/area.html
| {# =========================================================================
templates/area.html - "My area": die Startseite des Patienten
(Rolle USER), direkt nach dem Login angezeigt.
- zwei Optionen: [Manage my account] und [View a schedule];
- sein bevorstehender Termin, falls vorhanden, mit der Möglichkeit, ihn abzusagen.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<h4 class="mb-3">{{ t("AREA.HELLO", name=model.patient) }}</h4>
<div class="row g-3 mb-4">
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
<h5 class="mb-1">{{ t("AREA.MANAGE_ACCOUNT") }}</h5>
<span class="text-muted">{{ t("AREA.MANAGE_ACCOUNT_HELP") }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
<h5 class="mb-1">{{ t("AREA.VIEW_SCHEDULE") }}</h5>
<span class="text-muted">{{ t("AREA.VIEW_SCHEDULE_HELP") }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ t("AREA.MY_APPOINTMENT") }}</h5>
{# normalerweise nur einer (Regel "ein bevorstehender Termin zur Zeit"),
aber die Seite kann mehrere anzeigen. loop.last: letztes Element?
Der else-Block einer for-Schleife: die Liste ist leer #}
{% for appointment in model.appointments %}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{{ '' if loop.last else ' border-bottom' }}">
<div>
<div class="fw-semibold">{{ appointment.day }}, {{ appointment.time }}</div>
<div class="text-muted">
<span>{{ appointment.doctor }}</span> -
<a href="{{ appointment.schedule_url }}">{{ t("AREA.SEE_IN_SCHEDULE") }}</a>
</div>
</div>
<form method="post" action="/my-area/cancel" class="m-0"
data-confirmation="{{ t('SCHEDULE.CANCEL_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ appointment.id }}">
<button type="submit" class="btn btn-outline-danger">{{ t("AREA.CANCEL_APPOINTMENT") }}</button>
</form>
</div>
{% else %}
<p class="text-muted mb-0">{{ t("AREA.NO_APPOINTMENT") }}</p>
{% endfor %}
</div>
{% endblock %}
|
Das Dashboard des Patienten: zwei große Reiter („Mein Konto verwalten“, „Einen Terminkalender ansehen“) und seine bevorstehenden Termine. Die [for ... else]-Schleife (Beispiel 14) zeigt eine Meldung an, wenn die Liste leer ist; [loop.last] entfernt den Rand unter dem letzten Termin. Die Seite kann mehrere Termine anzeigen, auch wenn die Verwaltungsregel nur einen erlaubt.
11.17.2.7. templates/account.html
| {# =========================================================================
templates/account.html - "Manage my account" (Rolle USER).
Zwei unabhängige Formulare auf derselben Seite:
1. das Bearbeiten (Identität, Login, optionales neues Passwort);
2. das Löschen des Kontos - das auch seine Termine absagt.
Beide verlangen das AKTUELLE Passwort.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{# 1. Bearbeiten #}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{ t("MY_ACCOUNT.TITLE") }}</h5>
<form method="post" action="/my-account" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="version" value="{{ model.values.version }}">
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{ t("MY_ACCOUNT.NEW_PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{ t("ACCOUNT.CONFIRMATION_LABEL") }}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</div>
</div>
<div class="mb-4">
<label class="form-label" for="current_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="current_password" name="current_password" type="password" maxlength="72"
autocomplete="current-password" required
class="form-control {{ state.invalid_class('current_password') }}">
{% if state.error_of("current_password") %}
<div class="invalid-feedback">{{ t(state.error_of("current_password")) }}</div>
{% else %}
<div class="form-text">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_HELP") }}</div>
{% endif %}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("PERSONS.SAVE") }}</button>
<a class="btn btn-secondary" href="/my-area">{{ t("MY_ACCOUNT.BACK") }}</a>
</div>
</form>
</div>
{# 2. Löschen #}
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1">{{ t("MY_ACCOUNT.DELETE_TITLE") }}</h5>
<p class="text-muted small">{{ t("MY_ACCOUNT.DELETE_HELP") }}</p>
<form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{ t('MY_ACCOUNT.DELETE_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="delete_password" name="delete_password" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger">{{ t("MY_ACCOUNT.DELETE_SUBMIT") }}</button>
</form>
</div>
</div>
</div>
{% endblock %}
|
Zwei unabhängige Formulare auf derselben Seite: Kontoänderung (Zeilen 19–73) und Kontolöschung (Zeilen 80–89), durch das Bestätigungsfenster bestätigt. Beide erfordern das aktuelle Passwort, das in zwei getrennten Feldern eingegeben wird (ein Formular sendet nur seine eigenen Felder).
11.17.2.8. templates/error.html
| {# =========================================================================
templates/error.html - die Fehlerseite (400, 403, 404, 500...),
erstellt von web/errors.py.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4 text-center">
<h1 class="display-4 text-danger">{{ model.code }}</h1>
<p class="lead">{{ t(model.message) }}</p>
<div><a class="btn btn-primary" href="/">{{ t("ERROR_PAGE.BACK") }}</a></div>
</div>
</div>
</div>
{% endblock %}
|
Die Fehlerseite: der Code, prominent dargestellt, und die übersetzte Meldung. Sie erweitert das Template: Auch im Fehlerfall behält der Benutzer seine Navigationsleiste und kann die Sprache wechseln.
11.18. Die Wörterbücher
Die Texte der Oberfläche stehen in zwei JSON-Wörterbüchern, [i18n/fr.json] und [i18n/en.json], die der Translator beim Start liest. Es sind dieselben Dateien wie in den Versionen der Anwendung mit [NestJS], [ASP.NET Core MVC] und [Spring MVC].
11.18.1. i18n/fr.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace"
},
"LOGIN": {
"TITLE": "Connexion",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"SUBMIT": "Se connecter",
"ERROR": "Login ou mot de passe incorrect.",
"DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
"DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
"DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
"DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
"CREATE_ACCOUNT": "Créer un compte client",
"CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Médecin",
"CHOOSE_DOCTOR": "-- choisir un médecin --",
"DAY_LABEL": "Jour",
"VIEW_SCHEDULE": "Voir l'agenda"
},
"SCHEDULE": {
"PAGE_TITLE": "Agenda",
"TITLE_PREFIX": "Agenda du",
"COLUMN_SLOT": "Créneau",
"COLUMN_STATUS": "Statut",
"FREE": "Libre",
"BOOK": "Réserver",
"CANCEL_APPOINTMENT": "Annuler",
"CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
"EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
"NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
"BOOKED": "Rendez-vous enregistré.",
"CANCELLED": "Rendez-vous annulé.",
"BOOKED_BY_OTHER": "Réservé",
"ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
},
"BOOKING_DIALOG": {
"TITLE": "Réserver ce créneau",
"CLOSE_ARIA": "Fermer",
"SLOT": "Créneau de {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choisir un patient --",
"CANCEL": "Annuler",
"CONFIRM": "Confirmer"
},
"PERSONS": {
"COLUMN_TITLE": "Titre",
"COLUMN_FIRSTNAME": "Prénom",
"COLUMN_LASTNAME": "Nom",
"COLUMN_LOGIN": "Login",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"SAVE": "Enregistrer",
"BACK": "Retour à la liste",
"TITLE_LABEL": "Titre",
"FIRSTNAME_LABEL": "Prénom",
"LASTNAME_LABEL": "Nom",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
"LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
"PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"ACCOUNT_SECTION": "Compte utilisateur"
},
"DOCTORS": {
"TITLE": "Médecins",
"ADD": "Ajouter un médecin",
"EDIT": "Modifier un médecin",
"EMPTY": "Aucun médecin.",
"DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
"ADDED": "Le médecin {name} a été ajouté (login : {login}).",
"UPDATED": "Le médecin {name} a été modifié.",
"DELETED": "Le médecin {name} a été supprimé."
},
"CLIENTS": {
"TITLE": "Clients",
"ADD": "Ajouter un client",
"EDIT": "Modifier un client",
"EMPTY": "Aucun client.",
"DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
"ADDED": "Le client {name} a été ajouté (login : {login}).",
"UPDATED": "Le client {name} a été modifié.",
"DELETED": "Le client {name} a été supprimé."
},
"ERROR_PAGE": {
"TITLE": "Erreur",
"BACK": "Retour à l'accueil"
},
"ERRORS": {
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
"SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
"DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
"APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
"INVALID_DATE": "La date demandée n'est pas valide.",
"CHOOSE_PATIENT": "Choisissez un patient.",
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"BAD_REQUEST": "La requête est invalide.",
"FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
"NOT_FOUND": "Cette page n'existe pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
"TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
"WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
"TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
"LOGIN_REQUIRED": "Le login est obligatoire.",
"PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
"PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
"CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
"PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
"CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
"WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
"PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
"CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
},
"CAPTCHA": {
"LABEL": "Recopiez les caractères de l'image",
"IMAGE_ALT": "Image de vérification anti-robots",
"NEW_IMAGE": "Autre image",
"HELP": "Majuscules ou minuscules, peu importe."
},
"REGISTRATION": {
"TITLE": "Créer un compte client",
"INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
"LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_HELP": "Au moins {min} caractères.",
"SUBMIT": "Créer mon compte",
"BACK_TO_LOGIN": "Retour à la connexion",
"DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirmation du mot de passe"
},
"AREA": {
"TITLE": "Mon espace",
"HELLO": "Bonjour {name}",
"MANAGE_ACCOUNT": "Gérer mon compte",
"MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
"VIEW_SCHEDULE": "Voir un agenda",
"VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
"MY_APPOINTMENT": "Mon rendez-vous",
"SEE_IN_SCHEDULE": "voir dans l'agenda",
"CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
"NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
},
"MY_ACCOUNT": {
"TITLE": "Gérer mon compte",
"NEW_PASSWORD_LABEL": "Nouveau mot de passe",
"CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
"CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
"BACK": "Retour à mon espace",
"DELETE_TITLE": "Supprimer mon compte",
"DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
"DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
"DELETE_SUBMIT": "Supprimer mon compte",
"UPDATED": "Votre compte a été modifié.",
"DELETED": "Votre compte a été supprimé."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "Non, revenir",
"YES": "Oui, confirmer"
}
}
|
Die Schlüssel sind nach Seite oder Thema gruppiert: [APP] (die Navigationsleiste), [LOGIN], [SCHEDULE], [BOOKING_DIALOG] (das Reservierungsfenster), [PERSONS], [DOCTORS], [CLIENTS], [ERRORS] (alle Fehlermeldungen, einschließlich der von Formularvalidatoren und der Geschäftsschicht) ... Die Parameter der Meldungen werden als [{name}], [{login}], [{minutes}], [{min}], [{time}] geschrieben.
11.18.2. i18n/en.json
Das englische Wörterbuch hat exakt dieselben Schlüssel. Hier einige Zeilen zum Vergleich:
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Log out",
"MENU_SCHEDULE": "Schedule",
"MENU_DOCTORS": "Doctors",
"MENU_PATIENTS": "Patients",
"MENU_MY_AREA": "My area"
},
"LOGIN": {
"TITLE": "Login",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"SUBMIT": "Log in",
"ERROR": "Incorrect login or password.",
"DEMO_ACCOUNTS": "Demo accounts (password = login):",
"DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
"DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
"DEMO_USER": "USER role (patients): booking for themselves, managing their account",
"CREATE_ACCOUNT": "Create a patient account",
"CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
|
Ein weiteres Wörterbuch würde für eine dritte Sprache genügen: Es müsste in die Liste des Translators ([LANGUAGES]) aufgenommen und der Navigationsleiste eine Schaltfläche hinzugefügt werden.
11.19. Statische Dateien
Der Ordner [static] enthält das Stylesheet der Anwendung, ihr Skript und [Bootstrap] (Ordner [lib/bootstrap]: das Stylesheet [bootstrap.min.css] aus der offiziellen Distribution und seine Lizenz; die Anwendung verwendet das [JavaScript] von [Bootstrap] nicht).
11.19.1. static/css/styles.css
| /* =========================================================================
static/css/styles.css - einige Einstellungen zusätzlich zu Bootstrap
(dieselben wie in den Versionen ASP.NET Core MVC und Spring MVC dieser Anwendung).
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* -------------------------------------------------------------------------
.error-zone: die Fehlermeldungen am Seitenende, auf hellrosa Hintergrund
(siehe templates/fragments/errors.html).
position: sticky + bottom: Wenn die Seite höher als das Fenster ist (ein
Terminkalender mit 12 Zeitfenstern zum Beispiel), bleibt die Zone am unteren
Fensterrand haften, statt unter dem sichtbaren Bereich zu verschwinden - ohne jemals
den Inhalt zu verdecken, wenn die Seite kurz ist.
z-index: über dem grauen Hintergrund des Buchungsdialogs (.modal-backdrop).
------------------------------------------------------------------------- */
.error-zone {
position: sticky;
bottom: 1rem;
z-index: 1060;
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef; /* hellrosa */
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
/* die zwei großen Optionen der Seite "My area" des Patienten */
.option-card {
transition: border-color 0.15s, box-shadow 0.15s;
}
.option-card:hover {
border-color: #0d6efd;
box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}
/* das Captcha-Bild (SVG von 150 x 50 Pixeln) */
.captcha-image svg {
display: block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
|
Einige zusätzliche Regeln für [Bootstrap], dieselben wie in den früheren Versionen der Anwendung. Der Fehlerbereich (Zeilen 23–32) ist „sticky“ ([position: sticky], [bottom: 1rem]): Ist die Seite höher als das Fenster (ein Kalender mit zwölf Zeitfenstern), bleibt er am unteren Fensterrand sichtbar, statt unterhalb des sichtbaren Bereichs zu verschwinden. [z-index: 1060] platziert ihn über dem grauen Hintergrund modaler Fenster.
11.19.2. static/js/app.js
| // =========================================================================
// static/js/app.js - das EINZIGE JavaScript der Anwendung.
// -------------------------------------------------------------------------
// Die gesamte Anwendung funktioniert ohne JavaScript. Dieses Skript fügt eine
// Komfortfunktion hinzu: Vor dem Senden eines Formulars mit dem Attribut
// data-confirmation="..." fragt ein modaler Dialog "Are you sure?"
// (der Dialog selbst befindet sich in der Seite: templates/fragments/confirmation.html).
// Ist JavaScript deaktiviert, wird das Formular einfach ohne
// Bestätigung gesendet - nichts geht kaputt (Prinzip der „Progressive Enhancement").
//
// Warum nicht window.confirm()? Seine Box lässt sich nicht gestalten, und seine
// Buttons bleiben in der Sprache des Browsers, nicht in der der Seite.
// =========================================================================
(() => {
const modal = document.getElementById('confirmation-modal');
if (!modal) {
return;
}
const message = document.getElementById('confirmation-modal-message');
const noButton = modal.querySelector('.modal-footer [data-action="no"]');
let pendingForm = null; // das Formular, das gesendet wird, wenn der Benutzer bestätigt
let previousFocus = null; // das Element, an das der Fokus beim Schließen zurückgegeben wird
function open(form) {
pendingForm = form;
previousFocus = document.activeElement;
// textContent (und nicht innerHTML): Die Nachricht wird als TEXT angezeigt,
// nie als HTML interpretiert
message.textContent = form.dataset.confirmation;
modal.classList.remove('d-none');
// der Fokus geht auf "No": Ein unbedachter Druck auf Enter löscht nichts
noButton.focus();
}
function close() {
modal.classList.add('d-none');
pendingForm = null;
if (previousFocus) {
previousFocus.focus();
}
}
// 1. Wir fangen das Senden der zu bestätigenden Formulare ab
document.querySelectorAll('form[data-confirmation]').forEach((form) => {
form.addEventListener('submit', (event) => {
event.preventDefault();
open(form);
});
});
// 2. die Buttons des Dialogs (Yes / No / Schließen-Kreuz)
modal.addEventListener('click', (event) => {
const action = event.target.closest('[data-action]')?.dataset.action;
if (action === 'yes') {
const form = pendingForm;
close();
// form.submit() sendet das Formular, OHNE das Ereignis
// 'submit' erneut auszulösen: keine neue Bestätigungsabfrage
form.submit();
} else if (action === 'no') {
close();
} else if (event.target.classList.contains('modal')) {
close(); // Klick auf den grauen Hintergrund, außerhalb des Dialogs
}
});
// 3. Tastatur: Escape schließt den Dialog; Tab bleibt INNERHALB des Dialogs
// (sonst würde der Fokus auf die ausgegraute Seite dahinter gehen)
modal.addEventListener('keydown', (event) => {
if (event.key === 'Escape') {
close();
} else if (event.key === 'Tab') {
const buttons = [...modal.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (event.shiftKey && document.activeElement === first) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault();
first.focus();
}
}
});
})();
|
Das Skript aus Beispiel 21, vervollständigt:
- Zeilen 16–18: Das Skript tut nichts, wenn die Seite kein Bestätigungsfenster hat;
- Zeilen 26–34: Beim Öffnen wird die Meldung mit [textContent] eingesetzt, nicht mit [innerHTML]: Sie wird als Text angezeigt und niemals als HTML interpretiert. Der Fokus wechselt auf die Schaltfläche „Nein“: Ein versehentliches Drücken der Eingabetaste löscht nichts;
- Zeilen 37–41: Beim Schließen kehrt der Fokus zu dem Element zurück, das ihn zuvor hatte (die Schaltfläche „Löschen“), was für die Tastaturnavigation wichtig ist;
- Zeilen 54–65: Klicks innerhalb des Fensters. [closest('[data-action]')] sucht das Element mit dem Attribut [data-action], ausgehend vom angeklickten Element und aufwärts durch dessen Elternelemente: Ein Klick auf ein Symbol innerhalb einer Schaltfläche wird so der Schaltfläche zugerechnet. Der Operator [?.] liefert [undefined] , anstatt einen Fehler auszulösen, wenn kein Element gefunden wird. Ein Klick auf den ausgegrauten Hintergrund schließt das Fenster;
- Zeilen 71–83: Tastaturverhalten: Esc schließt das Fenster; Tab und Umschalt-Tab wechseln den Fokus zwischen den Schaltflächen des Fensters, ohne auf die abgedunkelte Seite dahinter zu springen.