Skip to content

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). Es ist die exakte Portierung der [Django]-Version der [Symfony]-Anwendung aus der vorherigen Lektion (die ihrerseits aus den Versionen [Laravel], [Flask], [Spring MVC] und [ASP.NET Core MVC] portiert wurde): dieselbe Datenbank, dieselben Geschäftsregeln, dieselben Seiten, dieselben URLs, derselbe Text. Die HTML-Seiten werden vom Server mit den Templates von [Django] erzeugt; der Zugriff auf die Datenbank läuft über den ORM von [Django].

Drei Benutzerrollen teilen sich die Anwendung:

Rolle
Wer
Berechtigungen
ADMIN
Der Administrator ([admin])
Terminkalender einsehen, Termine für beliebige Patienten buchen und stornieren; Ärzte und Patienten verwalten (auflisten, hinzufügen, bearbeiten, löschen)
DOCTOR
Ärzte
Terminkalender einsehen, Termine buchen und Termine beliebiger 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 reserviert werden;
  • Ein Patient hat jeweils nur einen anstehenden Termin;
  • Zwei Ärzte (oder zwei Clients) dürfen nicht denselben Vor- und Nachnamen haben, und ein Login gehört zu nur einem Konto;
  • Ein Arzt mit Terminen kann nicht gelöscht werden; ein Client wird zusammen mit seinen Terminen gelöscht;
  • Die Login-Seite ist gegen Bots geschützt (CAPTCHA, begrenzte Versuche), und für die Erstellung eines Patientenkontos muss zuvor auf dieser Seite das CAPTCHA gelöst werden.

11.2. Die Anwendung verwenden

11.2.1. Die Login-Seite

Image

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:

Image

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

Image

11.2.2. Der Kalender aus Sicht des Administrators und der Ärzte

Nach dem Login gelangt der Administrator zur Kalenderseite. Er wählt einen Arzt und einen Tag aus:

Image

Image

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=5], die Nummer des ausgewählten Zeitfensters:

Image

Nach der Buchung bestätigt eine Meldung den Termin:

Image

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

Image

11.2.3. Das Patientenportal

Ein Patient (Rolle USER) gelangt zu „Mein Bereich“: seinem anstehenden Termin, den er stornieren kann, und Links zur Verwaltung seines Kontos und zur Ansicht seines Kalenders. Hier hat er noch keinen Termin:

Image

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

Image

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

Image

Image

Seine Übersicht zeigt nun seinen anstehenden Termin, den er stornieren kann:

Image

Da er einen anstehenden 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:

Image

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

Image

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

Image

11.2.4. Ärzte und Patienten verwalten

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

Image

Image

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

Image

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

Image

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

Image

11.2.5. Ein Patientenkonto erstellen

Auf der Login-Seite öffnet die Schaltfläche „Patientenkonto erstellen“ das Formular nur, wenn das CAPTCHA korrekt eingegeben wurde:

Image

Nach der Erstellung des Kontos wird der Benutzer auf die Login-Seite umgeleitet, wobei sein Benutzername bereits ausgefüllt ist:

Image

11.2.6. Abmelden

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 Login-Seite um:

Image

11.3. Installation und Ausführung

Die Anwendung befindet sich im Ordner [rdvmedecins2-django], neben dem Ordner [examples]. Es ist ein eigenständiges Projekt mit eigenen Dateien [requirements.txt] und [.env] und eigener virtueller Umgebung. Die Datei [README.md] im Ordner enthält alles Folgende. Die Einleitung dieses Dokuments hat die Installation bereits beschrieben; hier geben wir weitere Details.

11.3.1. Erforderliche Software

Zwei Softwarepakete genügen:

  • [Python] 3.12 oder höher ([Django] 6.1 erfordert [Python] 3.12). Prüfen Sie die Installation in einem Terminal:
python --version
  • Unter [Linux] und [macOS]lautet der Befehl oft [python3]. Unter [Linux]erfordert das Kompilieren von [mysqlclient] außerdem einige Systempakete (siehe Anhänge);
  • ein [MySQL]-Server in Version 8.4 oder höher, etwa der von [Laragon] unter [Windows] (siehe Anhänge). [MariaDB] 10.11 oder höher ist ebenfalls geeignet. Dies sind die Mindestversionen für [Django] 6.1: Mit [MySQL] 8.0 verweigert [Django] die Verbindung ([MySQL 8.4 or later is required]).

Als Editor wird [Visual Studio Code] mit den Erweiterungen [Python] und [Django] empfohlen (siehe Anhänge); alles lässt sich jedoch auch über die Befehlszeile erledigen.

11.3.2. Bibliotheken installieren

Die Bibliotheken werden nicht mitgeliefert: Erstellen Sie einmalig eine virtuelle Umgebung im Anwendungsordner und installieren Sie die Bibliotheken dort in einem Terminal, das im Ordner [rdvmedecins2-django] geöffnet ist (Sie müssen mit dem Internet verbunden sein):

1
2
3
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

(unter [Linux] und [macOS] lautet der zweite Befehl [source .venv/bin/activate]). [pip] liest die Datei [requirements.txt] (siehe unten), lädt [Django], [mysqlclient], [PyJWT], [bcrypt] und die Bibliotheken herunter, von denen diese abhängen, und installiert sie im Ordner [.venv]. Die Umgebung muss in jedem neuen Terminal aktiviert werden ([Visual Studio Code] erledigt das automatisch, sobald der Interpreter der Umgebung ausgewählt wurde; siehe die Einführung).

11.3.3. Datenbank erstellen

Die Datenbank [dbrdvmedecins2] wird durch das Skript [database/dbrdvmedecins2.sql] erstellt. Öffnen Sie mit [Laragon] das Werkzeug [HeidiSQL] (Schaltfläche Database) und führen Sie das Skript über das Menü File / Run SQL aus (siehe Einführung). In der Befehlszeile, im Anwendungsordner:

mysql -u root -p < database/dbrdvmedecins2.sql

Die Option [-p] fragt das Passwort des Benutzers [root] ab; lassen Sie sie weg, wenn das Konto kein Passwort hat (wie bei [Laragon]). Es handelt sich um dieselbe Datenbank wie in den anderen Versionen der Anwendung: Wenn sie bereits existiert, ist dieser Schritt optional. Das Skript kann jederzeit ausgeführt werden, um die ursprünglichen Daten wiederherzustellen.

11.3.4. Datenbankzugriff konfigurieren

Die gesamte Installationskonfiguration steht in der Datei [.env] (siehe weiter unten). Standardmäßig verbindet sich die Anwendung mit [MySQL] auf [127.0.0.1], Port 3306, mit dem Benutzer [root] ohne Passwort: Das sind die Standardeinstellungen von [Laragon]. Wenn Ihr Konto [root] ein Passwort hat, tragen Sie es in dieser Datei in der Zeile [DB_PASSWORD=] ein. Eine Systemumgebungsvariable hat Vorrang vor der Datei (Beispiel 25): So können Sie das Passwort angeben, ohne es in eine Projektdatei zu schreiben.

11.3.5. Anwendung starten

In einem Terminalfenster, das im Ordner [rdvmedecins2-django] geöffnet ist, mit aktivierter virtueller Umgebung:

python manage.py runserver 8081
1
2
3
4
5
6
7
8
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 27, 2026 - 19:30:12
Django version 6.1.1, using settings 'config.settings'
Starting WSGI development server at http://127.0.0.1:8081/
Quit the server with CONTROL-C.

Öffnen Sie anschließend die URL [http://localhost:8081] in einem Browser und beenden Sie die Anwendung mit [Ctrl-C]. Port 8081 erlaubt es, gleichzeitig ein Kursbeispiel (Port 8000) auszuführen; auch andere Versionen der Anwendung verwenden Port 8081: Führen Sie sie nicht gleichzeitig aus.

11.3.6. Demo-Konten

Das Passwort jedes Kontos ist sein Benutzername; außerdem müssen Sie die im Bild angezeigten Zeichen eingeben, in Groß- oder Kleinschreibung:

Benutzername
Rolle
[admin]
ADMIN (der Administrator)
[pelissier], [tatou], [dupont]
DOCTOR (die Ä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, für ihn einen zweiten Termin zu buchen (wird abgelehnt). Menüs Doctors und Patients: hinzufügen, ändern, löschen (Dr. PELISSIER, die Termine hat, kann nicht gelöscht werden);
  • [pelissier]: Der eigene Tageskalender wird direkt angezeigt; die manuell eingegebene Adresse [/doctors] liefert eine Fehlerseite 403;
  • [martin]: Mein Bereich, der eigene Termin, der Kalender, in dem andere Patienten als „Booked“ erscheinen (sehen Sie sich den Quellcode der Seite an: Ihre Namen kommen darin nicht vor); Mein Konto verwalten;
  • Anmeldeseite: Ein Patientenkonto erstellen und sich dann mit dem neuen Konto anmelden;
  • Schaltflächen FR / EN: Die gesamte Oberfläche wechselt die Sprache, einschließlich der Datumsangaben.

11.3.7. Entwicklungsmodus

Die mitgelieferte Datei [.env] konfiguriert die Anwendung für die Entwicklung ([DJANGO_DEBUG=1]):

  • Die Serverkonsole zeigt jede Anfrage und jeden an die Datenbank gesendeten SQL-Befehl an (Beispiel 28). Um beispielsweise einen Kalender anzuzeigen (nach den beiden Befehlen zum Öffnen der Verbindung, Beispiel 28; Zeilen gekürzt):
1
2
3
4
(0.000) SELECT `doctors`.`id`, ..., `users`.`role` FROM `doctors` INNER JOIN `users` ON (`doctors`.`user` = `users`.`id`) WHERE `doctors`.`id` = 1 ORDER BY `doctors`.`id` ASC LIMIT 1; args=(1,); alias=default
(0.003) SELECT `appointments`.`id`, ..., `clients`.`user` FROM `appointments` INNER JOIN `slots` ON (`appointments`.`slot_id` = `slots`.`id`) INNER JOIN `clients` ON (`appointments`.`client_id` = `clients`.`id`) WHERE (`appointments`.`day` = '2026-09-28' AND `slots`.`doctor_id` = 1); args=('2026-09-28', 1); alias=default
(0.000) SELECT `slots`.`id`, ..., `slots`.`end_minute` FROM `slots` WHERE `slots`.`doctor_id` = 1 ORDER BY `slots`.`start_hour` ASC, `slots`.`start_minute` ASC; args=(1,); alias=default
[27/Sep/2026 19:50:21] "GET /schedule?doctorId=1&day=2026-09-28 HTTP/1.1" 200 9186

Hier lassen sich drei Abfragen erkennen: der Arzt und sein Konto (ein Join), die heutigen Termine und ihre Patienten sowie die freien Zeitfenster des Arztes. Die Liste der Ärzte im Dropdown-Menü wird hingegen nicht abgerufen; sie stammt aus dem Cache (siehe unten). Der angemeldete Benutzer wird ebenfalls nicht abgerufen; er wird anhand seines Tokens identifiziert (Beispiel 25);

  • Eine unerwartete Ausnahme zeigt die [Django]-Debug-Seite (Beispiel 03) mit der Fehlermeldung und dem Aufrufstapel an. In der Produktion zeigt die Anwendung stattdessen ihre eigene Fehlerseite 500 an;
  • Nach einer Änderung muss nichts neu gestartet werden: Der Entwicklungsserver startet automatisch neu, wenn sich eine [Python]-Datei ändert (Beispiel 01), und ein geändertes Template wird bei der nächsten Anfrage neu gelesen.

Der Debugger der Erweiterung [Python] von [Visual Studio Code] erlaubt es außerdem, die Anwendung schrittweise auszuführen: Dazu genügt eine Startkonfiguration vom Typ „Django“ (Datei [.vscode/launch.json], die die Erweiterung zu erstellen anbietet) mit den Parametern [runserver 8081 --noreload]. Die Erweiterung [django-debug-toolbar] (die per [pip] installiert wird) zeigt neben jeder Seite die Details der Anfrage an: die SQL-Befehle und ihre Dauer, die verwendeten Templates, die Einstellungen, die Signale ...

11.3.8. Ein Produktionsserver

Der Entwicklungsserver von [Django] ist nicht für die Produktion gedacht. In der Produktion wird die Anwendung von einem WSGI-Server ausgeliefert (Beispiel 01): [gunicorn] unter [Linux] ([gunicorn config.wsgi:application --workers 4]), [waitress] unter [Windows] ([waitress-serve --port=8081 config.wsgi:application]), in der Regel hinter einem Webserver ([nginx], [Apache]), der die HTTPS-Verbindungen entgegennimmt, die statischen Dateien selbst ausliefert und den Rest an den WSGI-Server delegiert. In der Datei [.env] müssen Sie den Produktionsmodus festlegen, die geheimen Schlüssel ändern, den Namen der Website deklarieren und angeben, dass die Website über HTTPS ausgeliefert wird:

1
2
3
4
5
DJANGO_DEBUG=0
DJANGO_SECRET_KEY=a-long-random-string
DJANGO_ALLOWED_HOSTS=rdvmedecins.example.com
JWT_SECRET=another-long-random-string
COOKIE_SECURE=1

Eine geeignete Zufallszeichenfolge lässt sich mit [Python] selbst erzeugen: [python -c "import secrets; print(secrets.token_hex(32))"]. Die Anwendung wird anschließend mit zwei Befehlen vorbereitet:

python manage.py collectstatic
python manage.py check --deploy

Der erste Befehl kopiert alle statischen Dateien (die der Anwendung und die von [Django]) in den Ordner [var/static] (Einstellung [STATIC_ROOT]), den der Webserver ausliefert (Beispiel 15). Der zweite Befehl prüft die Sicherheitseinstellungen einer Bereitstellung und meldet fehlende (die HSTS-Header, die Weiterleitung auf HTTPS usw.). Um den Produktionsmodus mit dem Entwicklungsserver zu testen, der statische Dateien dann nicht mehr ausliefert: [python manage.py runserver 8081 --insecure].

11.3.9. Häufige Probleme

Mit [MySQL] verbindet sich der Befehl [runserver] schon beim Start mit der Datenbank: Seine Projektprüfungen (System Checks, Beispiel 01) benötigen die Version des Servers. Eine nicht erreichbare Datenbank verhindert daher den Start: Die Konsole zeigt einen langen Aufrufstapel an, der mit dem Fehler endet. Beispiel mit einer Datenbank, die nicht existiert:

django.db.utils.OperationalError: (1049, "Unknown database 'dbrdvmedecins2'")

Ein Produktionsserver ([gunicorn] ...) führt diese Prüfungen nicht durch: Der Fehler erscheint dann im Log bei der ersten Seite, die die Datenbank abfragt (die Anmeldeseite fragt die Datenbank nicht ab; der Anmeldevorgang selbst schon). Die häufigsten Meldungen:

Meldung
Ursache
[ModuleNotFoundError: No module named 'django']
Die virtuelle Umgebung ist nicht aktiviert, oder [pip install -r requirements.txt] wurde nicht ausgeführt
[Django 6.1 requires Python 3.12 or later] (bei der Installation)
Die Version von [Python] ist älter als 3.12
[OperationalError: (2002, "Can't connect to server on '127.0.0.1' ...")]
[MySQL] wurde nicht gestartet oder lauscht nicht auf [127.0.0.1:3306]
[OperationalError: (1045, "Access denied for user 'root'@'localhost' ...")]
Das Passwort von [MySQL] muss in [DB_PASSWORD] eingetragen werden (siehe „Datenbankzugriff konfigurieren“)
[OperationalError: (1049, "Unknown database 'dbrdvmedecins2'")]
Das Skript [database/dbrdvmedecins2.sql] wurde nicht ausgeführt
[NotSupportedError: MySQL 8.4 or later is required]
Der [MySQL]-Server ist zu alt: Aktualisieren Sie auf [MySQL] 8.4 oder [MariaDB] 10.11
[ImproperlyConfigured: JWT_SECRET must be at least 32 characters long (see .env).]
Der geheime Schlüssel für die Token ist in [.env] zu kurz
[Error: That port is already in use.]
Port 8081 ist bereits belegt (läuft eine andere Version der Anwendung?): Beenden Sie sie oder wählen Sie einen anderen Port

11.4. Architektur der Anwendung

Image

  • Der Browser sendet seine Anfragen an den Server ([runserver] oder [nginx] + [gunicorn]), der sie über die WSGI-Anwendung in der Datei [config/wsgi.py] an [Django] weiterleitet. Die Anfrage durchläuft die Middleware-Schichten (siehe das Kapitel zum Lebenszyklus): die Sprache der Anfrage ([SetLanguage]), den Anti-CSRF-Schutz, die Flash-Nachrichten und dann die Authentifizierung: Der Benutzer wird anhand des JWT-Tokens in seinem Cookie identifiziert ([Authentication]); nach dem Routing verweigert [AccessControl] nicht berechtigten Besuchern den Zugriff auf geschützte Seiten. Fehler werden durch HTML-Seiten behandelt ([ErrorPage] und die Fehler-Views);
  • [web]: die Web-Schicht. Views ([web/views]), eine Familie von Seiten pro Modul, und ihre Routen ([web/urls.py]); Formulare und ihre Einschränkungen ([web/forms.py]); die Template-Modelle ([web/view_models.py]). Alle laufen über ein einziges Objekt, [ApplicationModel] ([web/application.py]), das die Listen der Ärzte und Clients zwischenspeichert und die übrigen Anfragen an die Geschäftsschicht weiterleitet;
  • [security]: JWT-Token, Middleware für Authentifizierung und Zugriffskontrolle, CAPTCHA, Versuchsbegrenzungen und der Pass zur Kontoerstellung;
  • [business]: Geschäftsregeln und Transaktionen; [domain]: Kalenderobjekte, die von der Geschäftsschicht berechnet werden;
  • [dao]: die DAO-Schicht, ein Modul pro Tabelle (oder Tabellenfamilie);
  • [models]: die ORM-Modelle (Beispiel 28), die die DAO-Schicht aus der Datenbank liest und in sie schreibt;
  • [templates]: die Templates, die die HTML-Seiten erzeugen; [locale]: das französische Wörterbuch; [static]: das Stylesheet, das Seitenskript und [Bootstrap];
  • Der Ordner [config] und die Datei [.env]: die Konfiguration, die alles zusammenhält.

Der Anwendungsordner (ohne [.venv] und [var]):

rdvmedecins2-django/
├── business/
│   ├── README.md
│   ├── __init__.py
│   ├── business.py
│   ├── dates.py
│   ├── descriptor.py
│   ├── errors.py
│   ├── person_data.py
│   ├── provider.py
│   └── service.py
├── config/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── dao/
│   ├── README.md
│   ├── __init__.py
│   ├── appointments.py
│   ├── persons.py
│   ├── slots.py
│   └── users.py
├── database/
│   ├── README.md
│   └── dbrdvmedecins2.sql
├── domain/
│   ├── README.md
│   ├── __init__.py
│   └── schedule.py
├── locale/
│   └── fr/
│       └── LC_MESSAGES/
│           ├── django.mo
│           └── django.po
├── models/
│   ├── README.md
│   ├── __init__.py
│   ├── apps.py
│   └── models.py
├── security/
│   ├── README.md
│   ├── __init__.py
│   ├── access.py
│   ├── auth.py
│   ├── captcha_drawing.py
│   ├── captchas.py
│   ├── connected_user.py
│   ├── errors.py
│   ├── limiter.py
│   ├── middleware.py
│   ├── passwords.py
│   └── registration_pass.py
├── static/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── app.js
│   └── lib/
│       └── bootstrap/
├── templates/
│   ├── forms/
│   │   └── field.html
│   ├── fragments/
│   │   ├── booking.html
│   │   ├── captcha.html
│   │   ├── confirmation.html
│   │   ├── errors.html
│   │   ├── navbar.html
│   │   └── success.html
│   ├── persons/
│   │   ├── form.html
│   │   └── list.html
│   ├── README.md
│   ├── account.html
│   ├── area.html
│   ├── error.html
│   ├── layout.html
│   ├── login.html
│   ├── macros.html
│   ├── registration.html
│   └── schedule.html
├── web/
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── rdv.py
│   ├── views/
│   │   ├── README.md
│   │   ├── __init__.py
│   │   ├── area.py
│   │   ├── auth.py
│   │   ├── errors.py
│   │   ├── language.py
│   │   ├── persons.py
│   │   ├── registration.py
│   │   └── schedule.py
│   ├── README.md
│   ├── __init__.py
│   ├── application.py
│   ├── apps.py
│   ├── contexts.py
│   ├── forms.py
│   ├── middleware.py
│   ├── rendering.py
│   ├── urls.py
│   ├── utils.py
│   └── view_models.py
├── .env
├── .gitignore
├── README.md
├── manage.py
└── requirements.txt

Dies ist die Struktur eines typischen [Django]-Projekts (Beispiel 01): ein Konfigurationspaket ([config]), eine Datei [manage.py] und Code-Pakete. Nur zwei davon sind [Django]-Anwendungen, die in [INSTALLED_APPS] deklariert sind: [models], weil es ORM-Modelle enthält (die [Django] nur in Anwendungen sucht), und [web], weil es eine Tag-Bibliothek enthält ([templatetags], Beispiel 16). Die übrigen ([dao], [business], [security], [domain]) sind einfach [Python]-Pakete, die die anderen importieren: Sie haben [Django] nichts mitzuteilen. [Django] schreibt keinen dieser Ordner vor, und ein typisches Projekt hätte stattdessen eine Anwendung pro Fachgebiet (Kalender, Konten usw.), jeweils mit eigenen Modellen, Views und Templates; wir haben uns wie in den anderen Versionen der Fallstudie für eine Organisation nach Schichten entschieden, wie in Beispiel 28 dargestellt. [Bootstrap] ist diesmal Teil der Anwendung (Ordner [static/lib/bootstrap]): Die Fallstudie ist in sich geschlossen.

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 ihrem Benutzerkonto verknüpft;
  • [slots]: die freien 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 Kunde ist
--      nun auch ein Benutzer, der sich anmelden kann;
--   2. eine dritte Rolle erscheint: DOCTOR (zusätzlich zu ADMIN und USER);
--   3. das Skript erstellt eine Zeile in [users] für jeden Arzt (Rolle DOCTOR)
--      und für jeden Kunden (Rolle USER):
--        - login        = Nachname in Kleinbuchstaben
--        - password     = Nachname in Kleinbuchstaben, mit bcrypt gehasht (10 Runden)
--        - display name = Vorname + Nachname
--
--   4. Eindeutigkeitseinschränkungen, alle BENANNT (die Anwendung erkennt
--      den Namen der verletzten Einschränkung in der MySQL-Fehlermeldung):
--        - unq_users_login                   : ein Login gehört nur zu einem Konto;
--        - unq_doctors_first_name_last_name  : zwei Ärzte können nicht denselben
--                                              Vor- und Nachnamen haben;
--        - unq_clients_first_name_last_name  : dasselbe für die Kunden.
--      Achtung: die Kollation utf8mb4_unicode_ci vergleicht ohne Rücksicht auf
--      Groß- und Kleinschreibung und Akzente - "Hélène DUPONT" und "helene dupont"
--      gelten daher als identisch.
--
-- Die Tabelle [users] muss jetzt VOR [doctors] und [clients] erstellt werden
-- (diese referenzieren 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;

-- Reihenfolge des Löschens: 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 kann 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 können 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 Kunde und ein Kunde pro Konto
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- zwei Kunden können nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- Tabelle [slots]: die Zeitslots 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 Kunden 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),
  -- derselbe Zeitslot kann 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 Konto DOCTOR pro Arzt, ein Konto USER pro Kunde
--   (das Demokonto user/user gibt es nicht mehr: ein Konto USER ist
--   jetzt IMMER das Konto eines Kunden, der 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'));

-- Zeitslots von Arzt PELISSIER (doctor_id = 1): von 8:00 bis 12:00 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);

-- Zeitslots von Arzt TATOU (doctor_id = 2): von 14:00 bis 18:00 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 einen belegten Zeitslot 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 Zeichenfolgen 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 versetzt die Datenbank in ihren Anfangszustand 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–55: users: ein Login, ein von [bcrypt] gehashtes Passwort (Beispiel 25), der nach der Anmeldung angezeigte Name und die Rolle ([ADMIN], [DOCTOR], oder [USER]). Die Einschränkung [unq_users_login] stellt sicher, dass ein Benutzername zu nur einem Konto gehört;
  • Zeilen 60–72: Jede Tabelle hat einen Primärschlüssel [id], der von der Datenbank erzeugt wird, und eine Spalte [version], die das optimistische Sperren realisiert (Beispiel 28). Die Spalte [user] ist ein Fremdschlüssel auf [users(id)]: Die Datenbank weist jeden Wert zurück, der nicht die ID eines vorhandenen Benutzers ist. Da [user] in der Sprache SQL ein reserviertes Wort ist, wird es in Backticks gesetzt. Drei Einschränkungen: [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 Namensgleichheit). Alle Einschränkungen haben einen Namen: Die Anwendung erkennt eine verletzte Einschränkung an ihrem Namen;
  • Zeilen 77–89: Die Tabelle [clients] hat genau dieselben Spalten;
  • Zeilen 94–103: Ein Zeitfenster gehört zu einem Arzt; Beginn und Ende werden in Stunden und Minuten gespeichert;
  • Zeilen 108–118: Ein Termin besteht aus einem Tag (Typ [DATE], ohne Uhrzeit), einem Zeitfenster und einem Client. Die Einschränkung [unq1_appointments] verhindert, dass dasselbe Zeitfenster am selben Tag zweimal gebucht wird: Die Datenbank erzwingt diese Regel, auch wenn zwei Benutzer gleichzeitig versuchen, es zu buchen;
  • Zeilen 130–140: Demo-Benutzer, deren Passwort ihr Login ist. Die Hashes beginnen mit [$2b$10$]: der Algorithmus ([bcrypt], Variante [2b]) und der Kostenfaktor (10: 2^10 Berechnungsrunden). Es folgen das Salt (22 Zeichen) und der Hash. Diese Hashes wurden von der [Flask]-Version der Anwendung berechnet, mit der Bibliothek [bcrypt] von [Python], die auch diese Version verwendet;
  • Zeilen 144–147: Die Spalte [user] jedes Arztes wird über eine Unterabfrage anhand des Logins ermittelt, statt die Werte der Primärschlüssel vorauszusetzen;
  • Zeilen 170–171: Ein für heute ([CURDATE()]) bereits eingetragener Termin im zweiten Zeitfenster von Dr. PELISSIER für Frau BISTROU: Der Kalender zeigt damit sofort, dass das Zeitfenster gebucht ist.

Anders als bei [Django] üblich wird die Datenbank nicht durch die Migrationen von [Django] erstellt (Beispiel 28): Sie wird mit den anderen Versionen der Anwendung geteilt, und das SQL-Skript ist allen gemeinsam. Die Modelle werden daher mit [managed = False] deklariert, und der Befehl [python manage.py makemigrations] hat nichts zu tun. Mit dem Befehl [python manage.py inspectdb] lässt sich die Datenbank mit den Modellen vergleichen.

11.6. Projektkonfiguration

11.6.1. requirements.txt

1
2
3
4
5
# die Bibliotheken der Anwendung: pip install -r requirements.txt
Django==6.1.1
mysqlclient==2.3.0
PyJWT==2.15.0
bcrypt==5.0.0

Die vier von der Anwendung benötigten Bibliotheken mit ihren exakten Versionen (siehe Einführung): [Django], der Treiber [MySQL] ([mysqlclient], Beispiel 28), die JWT-Token ([PyJWT], Beispiel 25) und [bcrypt] für die Passwörter in der Datenbank (siehe unten). [pip] installiert außerdem die Bibliotheken, von denen sie abhängen ([asgiref] und [sqlparse], für [Django]). Der Befehl [pip freeze] gibt die exakte Liste dessen aus, was in der Umgebung installiert ist, einschließlich der Abhängigkeiten: So erhält man eine Datei, die alle Versionen festschreibt. Ein größeres Projekt würde ein Projektverwaltungswerkzeug wie [uv] oder [Poetry] verwenden, das die angeforderten Bibliotheken (Datei [pyproject.toml]) von den exakten installierten Versionen trennt (einer Lock-Datei, wie [composer.lock] für [PHP]).

11.6.2. .env

# =========================================================================
# .env: die für DIESE Installation spezifischen Einstellungen, beim Start von
# config/settings.py gelesen. Jede Zeile NAME=value wird zu einer Umgebungsvariable
# des Prozesses; eine echte Umgebungsvariable des Systems
# hat Vorrang vor dieser Datei.
# =========================================================================

# 1: Entwicklung (detaillierte Fehlerseiten); 0: Produktion (siehe README.md)
DJANGO_DEBUG=1
# der geheime Schlüssel von Django (Signaturen, Anti-CSRF-Token ...). In Produktion: ein anderer
# Wert, lang und zufällig
DJANGO_SECRET_KEY=Hayf1oPBd4cm9qXHUGusMtUqCFqEyyj1nnwGxKvuJKYI0EDjjn
# die Hostnamen, die die Anwendung bedient (durch Kommas getrennt)
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

# ---- die MySQL-Datenbank [dbrdvmedecins2] (Skript: database/dbrdvmedecins2.sql): der
# Server, sein Port, die Datenbank, der Benutzer und sein Passwort (die von Laragon:
# root, ohne Passwort)
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=dbrdvmedecins2
DB_USER=root
DB_PASSWORD=

# ---- Authentifizierung (siehe security/auth.py)
# geheimer Schlüssel der JWT-Tokens: mindestens 32 Zeichen (HMAC-SHA256)
JWT_SECRET=229b83fd9cc502aaebd911d2662753a8393b340edb296724
# Gültigkeitsdauer eines Tokens in Minuten (120 min = 2 h)
JWT_DURATION_MINUTES=120
# 1 in Produktion (Site über HTTPS ausgeliefert): Die Cookies reisen nie unverschlüsselt
COOKIE_SECURE=0

# ---- Schutz vor Robotern (siehe security/limiter.py)
# erlaubte Login-Fehlschläge für dasselbe Login von derselben IP-Adresse, dann
# Sperre für diese Dauer (in Minuten); eine IP-Adresse wird auch gesperrt, wenn sie
# LOGIN_MAX_FAILURES_IP Fehlschläge ansammelt, alle Logins zusammen (ein Roboter, der
# Tausende verschiedener Logins ausprobiert)
LOGIN_MAX_FAILURES=5
LOGIN_MAX_FAILURES_IP=25
LOGIN_BLOCK_MINUTES=15
# höchstens erstellte Kundenkonten pro Stunde und pro IP-Adresse. In einem Klassenraum gehen alle
# Rechner oft über dieselbe Adresse hinaus: bei Bedarf erhöhen
REGISTRATION_MAX_PER_HOUR=10

Die Datei mit den Einstellungen, die für diese Installation spezifisch sind (Beispiel 25): Sie ändern sich von Rechner zu Rechner (die Datenbank, ihre Zugangsdaten) oder sind Geheimnisse (die Schlüssel). In einem realen Projekt wird diese Datei nie zusammen mit dem Code veröffentlicht: Jede Installation hat ihre eigene, und Produktionsgeheimnisse werden oft über echte Umgebungsvariablen bereitgestellt. [Django] liest eine Datei [.env] nicht von selbst: Die Datei [config/settings.py] liest sie (siehe später). Die Bibliothek [python-dotenv] würde dasselbe tun, und [django-environ] würde zusätzlich die Konvertierung von Werten bieten.

  • Zeile 9: Debug-Modus (Beispiel 01): 1 während der Entwicklung (detaillierte Fehlerseiten, SQL-Befehle in der Konsole), 0 in der Produktion;
  • Zeile 12: der geheime Schlüssel von [Django], der für Anti-CSRF-Token (Beispiel 18) und alle Signaturen (signierte Cookies, Flash-Nachrichten, Beispiele 20 und 23) verwendet wird;
  • Zeile 14: akzeptierte Hostnamen (Beispiel 01);
  • Zeilen 19–23: die Datenbankverbindung (Beispiel 28);
  • Zeilen 25–43: anwendungsspezifische Einstellungen: die JWT-Token (Beispiel 25), das Setzen der Cookies im Modus [Secure] (siehe später) und der Schutz vor Bots (Beispiel 27).

11.6.3. config/settings.py

Die Einstellungsdatei enthält die gesamte Konfiguration, geschrieben in [Python] (Beispiel 01):

# =========================================================================
# config/settings.py: die Konfiguration der Anwendung RdvMedecins.
#
# Die für eine Installation spezifischen Einstellungen (Passwörter, geheime Schlüssel, Schwellenwerte)
# werden aus Umgebungsvariablen gelesen, die die Datei .env in der
# Entwicklung bereitstellt (siehe read_env). Alles andere steht hier.
# =========================================================================

import os
from pathlib import Path

# der Projektordner (derjenige, der manage.py enthält)
BASE_DIR = Path(__file__).resolve().parent.parent


# -------------------------------------------------------------------------
# liest die Datei .env: Jede Zeile NAME=value wird zu einer Umgebungs-
# variable, AUSSER wenn sie bereits existiert (setdefault): Eine echte Umgebungs-
# variable des Systems hat Vorrang vor der Datei. Leere Zeilen und
# Kommentare (#) werden ignoriert; Anführungszeichen um den Wert werden entfernt
# -------------------------------------------------------------------------
def read_env(file: Path) -> None:
    if not file.exists():
        return
    for line in file.read_text(encoding="utf-8").splitlines():
        line = line.strip()
        if line and not line.startswith("#") and "=" in line:
            name, value = line.split("=", 1)
            os.environ.setdefault(name.strip(), value.strip().strip('"'))


read_env(BASE_DIR / ".env")


# eine Umgebungsvariable: ein Text, eine ganze Zahl, ein Boolean (1/0)
def env(name: str, default: str = "") -> str:
    return os.environ.get(name, default)


def env_int(name: str, default: int) -> int:
    return int(env(name, str(default)))


def env_bool(name: str, default: bool) -> bool:
    return env(name, "1" if default else "0") == "1"


# ---- Debug-Modus und Sicherheit
DEBUG = env_bool("DJANGO_DEBUG", False)
SECRET_KEY = env("DJANGO_SECRET_KEY")
ALLOWED_HOSTS = [h.strip() for h in env("DJANGO_ALLOWED_HOSTS", "localhost").split(",")]

# ---- die Anwendungen: Django selbst (statische Dateien, Flash-Meldungen,
# Formulare) und unsere beiden Anwendungen: models (die Tabellen) und web (die
# Template-Tags). Die anderen Ordner (dao, business, security ...) sind
# einfache Python-Pakete: Sie haben weder Modelle noch Templates
INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "django.contrib.messages",
    "django.forms",
    "models",
    "web",
]

# ---- die Middlewares, in der Reihenfolge (siehe Beispiel 24):
#   - SetLanguage: die Sprache der Anfrage (Cookie rdvmedecins_language);
#   - CsrfViewMiddleware: das Anti-CSRF-Token jeder POST-Anfrage;
#   - MessageMiddleware: die Flash-Meldungen;
#   - Authentication: der Benutzer, aus dem JWT-Token seines Cookies;
#   - AccessControl: die Zugriffsregel jeder URL (nach dem Routing);
#   - ErrorPage: Fehler werden zu Seiten der Anwendung
MIDDLEWARE = [
    "web.middleware.SetLanguage",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "security.middleware.Authentication",
    "security.middleware.AccessControl",
    "web.middleware.ErrorPage",
]

ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

# ---- die Datenbank: MySQL (oder MariaDB), die Datenbank dbrdvmedecins2
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "HOST": env("DB_HOST", "127.0.0.1"),
        "PORT": env("DB_PORT", "3306"),
        "NAME": env("DB_NAME", "dbrdvmedecins2"),
        "USER": env("DB_USER", "root"),
        "PASSWORD": env("DB_PASSWORD"),
        "OPTIONS": {"charset": "utf8mb4"},
    },
}

# ---- der CACHE: Dateien des Ordners var/cache, von allen
# Prozessen des Servers GEMEINSAM genutzt (Captchas, Fehlschlagzähler, Pässe, Listen der
# Ärzte und Kunden). Ein Cache im Speicher (LocMemCache) wäre für
# jeden Prozess spezifisch: Ein Produktionsserver startet mehrere davon
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": BASE_DIR / "var" / "cache",
    },
}

# ---- die Templates (Ordner templates) und ihre Context-Prozessoren
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.template.context_processors.i18n",
                "django.contrib.messages.context_processors.messages",
                # der angemeldete Benutzer in allen Templates (siehe web/contexts.py)
                "web.contexts.user",
            ],
        },
    },
]

# die Formularfelder werden mit den Klassen von Bootstrap 5 gezeichnet (siehe
# Beispiel 18 und templates/forms/field.html)
FORM_RENDERER = "web.rendering.BootstrapRenderer"

# ---- die Sprachen (siehe Beispiel 22): standardmäßig Englisch, Französisch; die
# Wörterbücher liegen im Ordner locale
LANGUAGE_CODE = "en"
LANGUAGES = [("fr", "Français"), ("en", "English")]
LOCALE_PATHS = [BASE_DIR / "locale"]
# das Cookie, das sich die gewählte Sprache merkt (siehe web/views/language.py)
LANGUAGE_COOKIE_NAME = "rdvmedecins_language"

# ---- die Zeitzone: die der Arztpraxis. Sie legt das heutige Datum fest (kein
# Termin in der Vergangenheit, siehe business/dates.py)
TIME_ZONE = "Europe/Paris"
USE_TZ = True

# ---- die statischen Dateien (Ordner static): Bootstrap, das Stylesheet, das Skript
STATIC_URL = "static/"
STATICFILES_DIRS = [BASE_DIR / "static"]
# in Produktion sammelt collectstatic dort alle statischen Dateien (siehe README.md)
STATIC_ROOT = BASE_DIR / "var" / "static"

# ---- die Flash-Meldungen: in einem signierten Cookie (siehe Beispiel 20)
MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

# ---- die Cookies: nie vom JavaScript der Seite lesbar (HttpOnly, auch nicht das
# Anti-CSRF-Cookie, das Django standardmäßig lesbar lässt), nie mit einer
# POST-Anfrage von einer anderen Site gesendet (Lax), in Produktion nie unverschlüsselt (Secure)
COOKIE_SECURE = env_bool("COOKIE_SECURE", False)
CSRF_COOKIE_NAME = "rdvmedecins_csrf"
CSRF_COOKIE_SECURE = COOKIE_SECURE
CSRF_COOKIE_HTTPONLY = True
CSRF_COOKIE_SAMESITE = "Lax"
# ein fehlendes oder falsches Anti-CSRF-Token: unsere 419-Fehlerseite (siehe web/views/errors.py)
CSRF_FAILURE_VIEW = "web.views.errors.csrf_rejected"

# ---- unsere eigenen Einstellungen: Authentifizierung (siehe security/auth.py) ...
JWT_SECRET = env("JWT_SECRET")
JWT_DURATION_MINUTES = env_int("JWT_DURATION_MINUTES", 120)
# ... und Schutz vor Robotern (siehe security/limiter.py)
LOGIN_MAX_FAILURES = env_int("LOGIN_MAX_FAILURES", 5)
LOGIN_MAX_FAILURES_IP = env_int("LOGIN_MAX_FAILURES_IP", 25)
LOGIN_BLOCK_MINUTES = env_int("LOGIN_BLOCK_MINUTES", 15)
REGISTRATION_MAX_PER_HOUR = env_int("REGISTRATION_MAX_PER_HOUR", 10)

# ---- Logging: Im Debug-Modus werden die an die Datenbank gesendeten SQL-Anweisungen in die
# Konsole geschrieben (siehe Beispiel 28)
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "django.db.backends": {"handlers": ["console"], "level": "DEBUG"},
    },
}
  • Zeilen 22–32: Lesen der Datei [.env]. [read_text] liest die gesamte Datei, während [splitlines] sie in Zeilen aufteilt. Jede Zeile der Form [NAME=value], ausgenommen Kommentare, wird zu einer Umgebungsvariablen des Prozesses ([split("=", 1)]: nur beim ersten Vorkommen von [=] trennen, da ein Wert es enthalten kann). [setdefault] überschreibt eine vorhandene Variable nicht: Eine echte Umgebungsvariable hat Vorrang vor der Datei (Beispiel 25);
  • Zeilen 36–45: drei kleine Funktionen, die eine Umgebungsvariable lesen – mit einem Standardwert – und sie konvertieren (in eine ganze Zahl oder einen booleschen Wert 1 oder 0);
  • Zeilen 49–51: Debug-Modus, geheimer Schlüssel und Hostnamen, aus der Umgebung gelesen. Wenn [.env] nicht vorhanden ist, ist der Debug-Modus deaktiviert: Das ist die sichere Wahl. [ALLOWED_HOSTS] ist eine Liste, die aus einer Zeichenfolge von durch Kommas getrennten Namen aufgebaut wird;
  • Zeilen 57–63: die Anwendungen (siehe die Architektur): drei Anwendungen von [Django] (statische Dateien, Beispiel 15; Flash-Nachrichten, Beispiel 20; Formular-Templates, Beispiel 18) und unsere beiden;
  • Zeilen 72–79: die sechs Middleware-Komponenten in der Reihenfolge, in der die Anfrage sie durchläuft (Beispiel 24). Die Reihenfolge ist wichtig: Zuerst wird die Sprache festgelegt, damit alle Seiten – auch Fehlerseiten – in der richtigen Sprache erscheinen; der Anti-CSRF-Schutz kommt vor der Authentifizierung; die Authentifizierung (die den Benutzer identifiziert) kommt vor der Zugriffskontrolle (die den Benutzer bewertet); und [ErrorPage], die letzte, behandelt als erste die von den Views ausgelösten Ausnahmen ([process_exception] wird in umgekehrter Reihenfolge aufgerufen, Beispiel 24);
  • Zeilen 85–95: die Datenbank (Beispiel 28), deren Parameter aus der Umgebung stammen;
  • Zeilen 101–106: der Anwendungs-Cache (Beispiel 27). Er wird in Dateien ([FileBasedCache]) im Ordner [var/cache] gespeichert, den [Django] selbst anlegt: Anders als der Cache im Arbeitsspeicher in Beispiel 27 übersteht er Neustarts des Servers (auf einem Entwicklungsserver nach jeder Codeänderung) und wird auf einem Produktionsserver von allen Prozessen gemeinsam genutzt (siehe das Kapitel zu den Gültigkeitsbereichen). Die Anwendung legt in diesem Cache Listen von Ärzten und Clients, CAPTCHAs, Versuchszähler und Pässe ab. Bei mehreren Servern würde man einen gemeinsam genutzten Cache wählen, etwa [Redis];
  • Zeilen 109–124: die Templates (Beispiel 13) samt den Templates der Anwendungen ([APP_DIRS], für die in [django.forms], Beispiel 18) und vier Kontextprozessoren: die Anfrage, die Sprache (Beispiel 22), die Flash-Nachrichten (Beispiel 20) und unser eigener, der den angemeldeten Benutzer allen Templates zur Verfügung stellt (siehe unten);
  • Zeile 128: die Rendering-Engine für Formulare, mit den Klassen von [Bootstrap] (Beispiel 18);
  • Zeilen 132–136: die Sprachen und das Wörterbuch (Beispiel 22). Das Sprach-Cookie hat einen anwendungsspezifischen Namen;
  • Zeilen 140–141: die Zeitzone der Praxis. [USE_TZ = True] (der Standardwert) bewirkt, dass [Django] in koordinierter Weltzeit (UTC) arbeitet und Uhrzeiten für die Anzeige in diese Zeitzone umrechnet; [timezone.localdate()] liefert das aktuelle Datum in dieser Zeitzone. Das aktuelle Datum wird für eine Geschäftsregel verwendet (keine Termine in der Vergangenheit): In Paris ist während der Sommerzeit zwischen Mitternacht und 2:00 Uhr das Datum in koordinierter Weltzeit noch der Vortag; daher hat die Zeitzone der Praxis Vorrang;
  • Zeilen 144–147: statische Dateien (Beispiel 15): der Ordner [static] der Anwendung und der Ordner, in dem [collectstatic] sie für die Produktion sammelt;
  • Zeile 150: Flash-Nachrichten in einem signierten Cookie (Beispiel 20);
  • Zeilen 155–161: die Cookies von [Django]. [COOKIE_SECURE], aus [.env] gelesen, wird auch für unsere eigenen Cookies (das Token, die Sprache usw.) verwendet: In der Produktion wird über HTTPS kein Cookie im Klartext übertragen. Das Cookie des Anti-CSRF-Tokens erhält einen anwendungsspezifischen Namen; es wird als [HttpOnly] ausgeliefert (das [JavaScript] der Seite braucht es nicht: Es sendet selbst keine Anfragen) und mit [SameSite=Lax]. Ein fehlendes oder ungültiges Anti-CSRF-Token zeigt eine Seite der Anwendung an (siehe unten) statt der Seite 403 von [Django] (Beispiel 18);
  • Zeilen 164–170: anwendungsspezifische Einstellungen, aus der Umgebung gelesen: die JWT-Token (Beispiel 25) und der Bot-Schutz (Beispiel 27);
  • Zeilen 174–181: das Protokoll der SQL-Befehle im Debug-Modus (Beispiel 28).

Der Befehl [python manage.py diffsettings] zeigt alle Einstellungen an, die von den Standardwerten von [Django] abweichen.

11.6.4. config/urls.py

# config/urls.py: die Haupt-Routing-Tabelle

from django.urls import include, path

urlpatterns = [
    path("", include("web.urls")),
]

# die Views der Fehlerseiten, die Django selbst erzeugt (siehe web/views/errors.py):
# Im Debug-Modus ersetzt Django die der Fehler 400, 404 und 500 durch seine
# detaillierten Seiten
handler400 = "web.views.errors.error_400"
handler403 = "web.views.errors.error_403"
handler404 = "web.views.errors.error_404"
handler500 = "web.views.errors.error_500"

Alle Routen der Anwendung stehen in der Datei [web/urls.py] (die Web-Schicht, siehe später) und sind an der Wurzel der Website eingebunden (Beispiel 04). Die vier Views der Fehlerseiten, die [Django] selbst erzeugt (Beispiel 24), werden hier durch Zeichenfolgen bezeichnet (den vollständigen Pfad der Funktion): [Django] importiert sie selbst.

11.7. Start der Anwendung

11.7.1. manage.py und config/wsgi.py

Die Dateien [manage.py] und [config/wsgi.py] stammen aus Beispiel 01: das Befehlszeilenwerkzeug und die WSGI-Anwendung, die vom Entwicklungsserver und von den Produktionsservern gestartet wird. Beim Start liest [Django] die Einstellungen (die Datei [config/settings.py] liest dann die Datei [.env]), lädt die Anwendungen aus [INSTALLED_APPS] (ihre Modelle, ihre Konfiguration, Beispiel 24), erzeugt für jede Middleware-Komponente ein Objekt (Beispiel 03) und wartet dann auf Anfragen. Alles, was beim Start aufgebaut wird, wird von allen Anfragen gemeinsam genutzt, solange der Prozess läuft: Das gilt für die einmalig vorhandenen Anwendungsobjekte (die Geschäftsschicht, die Fassade [ApplicationModel]), die von ihren Providern bei der ersten Verwendung erzeugt werden (Beispiel 06).

Zwei Dinge werden beim Start geprüft, und ein Fehler beendet den Server, bevor Anfragen verarbeitet werden: der Schlüssel der JWT-Token (ist er zu kurz, wird er abgelehnt; siehe [security/auth.py]) und, mit [MySQL], die Datenbankverbindung (siehe „Häufige Probleme“).

11.8. Die Modelle

Die ORM-Modelle (Beispiel 28): eine Klasse pro Tabelle, in der Datei [models/models.py] der Anwendung [models].

11.8.1. models/apps.py

1
2
3
4
5
6
7
# models/apps.py: die Konfiguration der Anwendung models

from django.apps import AppConfig


class ModelsConfig(AppConfig):
    name = "models"

Die Anwendungskonfiguration (Beispiel 24), auf ihren Namen reduziert. Sie ist nicht erforderlich: [Django] würde eine erzeugen; wir schreiben sie, damit jede Anwendung ihre eigene hat.

11.8.2. models/models.py

# =========================================================================
# models/models.py: die Django-MODELLE, eine Klasse pro Tabelle der
# Datenbank dbrdvmedecins2 (siehe Beispiel 28).
#
# Die Tabellen existieren bereits: Sie werden vom Skript
# database/dbrdvmedecins2.sql angelegt, demselben wie bei den anderen Versionen der
# Anwendung. Jedes Modell teilt Django das mit managed = False mit: Django
# legt diese Tabellen nie an, ändert oder löscht sie nie (keine Migrationen).
#
# Die Fremdschlüssel (ForeignKey, OneToOneField) werden mit
# on_delete=DO_NOTHING deklariert: Wenn eine Zeile gelöscht wird, sucht Django nicht selbst nach
# den Zeilen, die auf sie verweisen. Es ist die Geschäftsschicht, die in der richtigen
# Reihenfolge löscht, was gelöscht werden muss (siehe business/service.py); die Constraints der Datenbank
# würden ein unvollständiges Löschen ohnehin ablehnen.
#
# Alle Tabellen haben eine Spalte [version]: das optimistische Sperren, das die DAO-
# Schicht für ihre UPDATEs verwendet (siehe dao/persons.py).
# =========================================================================

from django.db import models


# die drei Rollen eines Benutzers (Spalte users.role):
#   - ADMIN  : der Administrator - Termine + Verwaltung der Ärzte und Kunden;
#   - DOCTOR : ein Arzt - bucht und storniert Termine;
#   - USER   : ein Kunde (Patient) - bucht für sich selbst, verwaltet sein Konto.
# TextChoices: eine Django-AUFZÄHLUNG, deren Werte jeweils ein String sind (der in der
# Datenbank gespeicherte); Role("ADMIN") geht den umgekehrten Weg
class Role(models.TextChoices):
    ADMIN = "ADMIN"
    DOCTOR = "DOCTOR"
    USER = "USER"


# ein Benutzer, der sich anmelden darf (Tabelle [users]). Jeder Arzt und jeder
# Kunde besitzt SEIN Konto (Spalte [user] der Tabellen [doctors] und [clients]).
# SQL-Eindeutigkeitseinschränkung: unq_users_login (ein Login gehört nur zu einem
# Konto), in der Geschäftsschicht an ihrem NAMEN erkannt (siehe business/service.py)
class User(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    login = models.CharField(max_length=30)
    # das GEHASHTE Passwort (bcrypt), nie das Passwort selbst
    password = models.CharField(max_length=100)
    # der Name, der nach der Anmeldung angezeigt wird: "Marie PELISSIER"
    name = models.CharField(max_length=40)
    # choices: die möglichen Werte der Spalte
    role = models.CharField(max_length=10, choices=Role.choices)

    class Meta:
        db_table = "users"
        managed = False

    def __str__(self):
        return self.login


# -------------------------------------------------------------------------
# was Ärzte (Tabelle [doctors]) und Kunden (Tabelle
# [clients]) gemeinsam haben: eine Anrede, ein Nachname, ein Vorname - und das zugehörige
# Benutzerkonto (Spalte [user]).
#
# Die beiden Tabellen haben genau dieselben Spalten: Sie werden EINMAL beschrieben,
# in diesem ABSTRAKTEN Modell (abstract = True: Eine "Person" wird nie angelegt und
# hat keine eigene Tabelle), von dem Doctor und Client erben; jedes gibt nur
# den Namen seiner Tabelle an.
#
# Achtung: [Client] bedeutet hier einen PATIENTEN der Arztpraxis, nicht einen HTTP-
# Client! Es ist das Vokabular der ursprünglichen Fachdomäne, unverändert übernommen.
# -------------------------------------------------------------------------
class Person(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # "Mr, Mme, Melle"
    title = models.CharField(max_length=5)
    last_name = models.CharField(max_length=20)
    first_name = models.CharField(max_length=20)
    # die BEZIEHUNG zum Benutzerkonto: Eine Person hat EIN Konto, bezeichnet durch den
    # Fremdschlüssel [user] (db_column). OneToOneField: ein Konto pro Person,
    # eine Person pro Konto. person.account liefert ein User-Objekt, beim ersten
    # Zugriff aus der Datenbank gelesen - oder durch die Abfrage selbst, wenn sie es verlangt (select_related, siehe
    # dao/persons.py). related_name: der Name der umgekehrten Beziehung,
    # user.doctor oder user.client (%(class)s: der Name des Modells in Kleinbuchstaben)
    account = models.OneToOneField(User, db_column="user", on_delete=models.DO_NOTHING,
                                   related_name="%(class)s")

    class Meta:
        abstract = True

    # "Mme Alice DURAND"
    def label(self) -> str:
        return f"{self.title} {self.first_name} {self.last_name}"

    def __str__(self):
        return self.label()


# ein Arzt (Tabelle [doctors]). SQL-Eindeutigkeitseinschränkung: unq_doctors_first_name_last_name
# (zwei Ärzte können nicht denselben Vor- und Nachnamen haben)
class Doctor(Person):
    class Meta:
        db_table = "doctors"
        managed = False


# ein Kunde, also ein PATIENT (Tabelle [clients]). SQL-Eindeutigkeitseinschränkung:
# unq_clients_first_name_last_name
class Client(Person):
    class Meta:
        db_table = "clients"
        managed = False


# ein Zeitfenster eines Arztes (Tabelle [slots]): 8:00 - 8:20 usw. Die
# Zeitfenster werden vom SQL-Skript angelegt: Die Anwendung liest sie nur
class Slot(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # mehrere Zeitfenster desselben Arztes: ein Fremdschlüssel, [doctor_id]
    doctor = models.ForeignKey(Doctor, db_column="doctor_id", on_delete=models.DO_NOTHING,
                               related_name="slots")
    start_hour = models.IntegerField()
    start_minute = models.IntegerField()
    end_hour = models.IntegerField()
    end_minute = models.IntegerField()

    class Meta:
        db_table = "slots"
        managed = False

    # "8:00 - 8:20"; :02d: zweistellig, "8:05" statt "8:5"
    def time_range(self) -> str:
        return f"{self.start_hour}:{self.start_minute:02d} - {self.end_hour}:{self.end_minute:02d}"


# ein Termin (Tabelle [appointments]): ein Kunde, in einem Zeitfenster, an einem bestimmten Tag.
# SQL-Eindeutigkeitseinschränkung: unq1_appointments (day, slot_id) - ein Zeitfenster wird pro Tag nur
# einmal gebucht; in der Geschäftsschicht an seinem Namen erkannt
class Appointment(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # DateField: Die Spalte [day] (SQL-Typ DATE) wird zu einem Python-Datum-Objekt
    day = models.DateField()
    slot = models.ForeignKey(Slot, db_column="slot_id", on_delete=models.DO_NOTHING,
                             related_name="appointments")
    client = models.ForeignKey(Client, db_column="client_id", on_delete=models.DO_NOTHING,
                               related_name="appointments")

    class Meta:
        db_table = "appointments"
        managed = False
  • Zeilen 29–32: die drei Rollen in Form einer Enumeration von [Django] ([models.TextChoices]), die ihrerseits auf den Enumerationen von [Python] (dem Modul [enum]) aufbaut: ein Typ, dessen einzig mögliche Werte seine Mitglieder sind: [Role.ADMIN], [Role.DOCTOR], und [Role.USER]. Jedes Element hat einen Wert, hier die zugrunde liegende Zeichenfolge; ein Element von [TextChoices] ist selbst eine Zeichenfolge: [Role.ADMIN == "ADMIN"] ist wahr. [Role("ADMIN")] liefert das entsprechende Element (und löst bei einem unbekannten Wert [ValueError] aus). [Role.choices] liefert die Liste der Paare (Wert, Bezeichnung), die dem Parameter [choices] eines Feldes übergeben werden kann;
  • Zeilen 39–55: das Schema der Tabelle [users]: der Primärschlüssel, die Version (das optimistische Sperren, Beispiel 28), gefolgt von den Spalten. [choices] (Zeile 48) dokumentiert die möglichen Werte der Spalte; [Django] nutzt dies, um ein auf dem Schema basierendes Formular zu validieren, und für die Administrationsoberfläche; die Datenbank selbst führt keine Prüfung durch. [managed = False]: Die Tabelle wird vom SQL-Skript erstellt (Beispiel 28);
  • Zeilen 71–95: Die Tabellen [doctors] und [clients] haben dieselben Spalten. Ihre gemeinsame Beschreibung wird nur einmal in einem abstrakten Modell geschrieben ([abstract = True], Zeile 88): einem Modell, das keine eigene Tabelle hat und nur zum Vererben dient. Die Modelle [Doctor] und [Client] erben davon: Jedes hat die Felder von [Person] in seiner eigenen Tabelle. ([Django] unterstützt auch echte Modellhierarchien, bei denen jede Kindklasse eine mit der Tabelle der Elternklasse verknüpfte Tabelle hat; das ist hier nicht der Fall, die beiden Tabellen sind unabhängig);
  • Zeilen 84–85: die Beziehung zum Konto. [OneToOneField]: Eine Person hat ein Konto, und ein Konto gehört zu höchstens einer Person. [db_column] bezeichnet die Fremdschlüsselspalte [user] (ohne diesen Parameter würde [Django] sie [account_id] nennen, den Feldnamen gefolgt von [_id]). [on_delete] legt fest, was [Django] beim Löschen des Kontos tut: [DO_NOTHING], nichts (der Kommentar in den Zeilen 10–14 erklärt diese Wahl; [CASCADE] würde auch die Person löschen, während [PROTECT] das Löschen ablehnen würde). Das Attribut [account] ist ein Objekt [User], keine Zahl: Das ist der Zweck eines ORM. Wenn das ORM eine Person liest, liest es auch ihr Konto, falls die Abfrage es verlangt ([select_related]; siehe die DAO-Schicht); andernfalls ruft es das Konto beim ersten Zugriff auf [person.account] über eine zusätzliche Abfrage ab. Die Nummer selbst ist immer ohne Abfrage unter dem Namen [account_id] verfügbar. [related_name] bezeichnet die umgekehrte Beziehung: [user.doctor] oder [user.client], die einem Konto zugeordnete Person; [%(class)s] wird durch den Modellnamen in Kleinbuchstaben ersetzt, was jedem der beiden Modelle, die das Feld erben, einen eigenen Namen gibt;
  • Zeilen 91–95: der Name einer Person, „Frau Alice DURAND“, der von allen Seiten verwendet wird;
  • Zeilen 100–111: zwei Modelle, die nur ihre Tabelle angeben; alles andere wird geerbt. Ein [Client] ist ein Patient der Praxis, kein HTTP-Client: Das ist das Vokabular der ursprünglichen Fachdomäne, das in allen Versionen der Anwendung beibehalten wurde;
  • Zeilen 116–133: ein Zeitfenster. [ForeignKey] (Zeile 120): mehrere Zeitfenster für denselben Arzt über den Fremdschlüssel [doctor_id]; die umgekehrte Beziehung [doctor.slots] liefert die Zeitfenster eines Arztes. Die Methode [time_range] liefert „8:00 - 8:20“: In einem f-String schreibt [{self.start_minute:02d}] eine ganze Zahl mit mindestens zwei Ziffern, mit Nullen aufgefüllt ([8:05] statt [8:5]);
  • Zeilen 139–151: ein Termin. Die Spalte [day] (SQL-Typ [DATE]) wird zu einem Objekt [date] vom [Python]-Typ ([DateField]); die Objekte [date] sind unveränderlich ([day + timedelta(days=1)] liefert den nächsten Tag, [day] bleibt unverändert). Zwei Beziehungen: eine zum Zeitfenster und eine zum Client des Termins.

11.9. Die Domäne: der Kalender

11.9.1. domain/schedule.py

# =========================================================================
# domain/schedule.py: der Terminkalender eines Arztes für einen bestimmten Tag. "Fachliche"
# Objekte, von der Geschäftsschicht BERECHNET (BusinessService.get_doctor_day_schedule),
# die keiner Tabelle entsprechen und dann von der
# View schedule (web/views/schedule.py) für das Template formatiert werden.
#
# frozen=True: Die Attribute werden vom Konstruktor ein für alle Mal gesetzt -
# genau das, was für ein berechnetes Objekt nötig ist, das danach niemand ändert.
# =========================================================================

from dataclasses import dataclass
from datetime import date

from models.models import Appointment, Doctor, Slot


# ein Zeitfenster und der möglicherweise darin gebuchte Termin an einem bestimmten
# Tag (None, wenn das Zeitfenster frei ist)
@dataclass(frozen=True)
class DoctorDaySlot:
    slot: Slot
    appointment: Appointment | None


# der vollständige Terminkalender eines Arztes für einen bestimmten Tag: die Liste seiner Zeitfenster,
# jedes frei oder belegt
@dataclass(frozen=True)
class DoctorDaySchedule:
    doctor: Doctor
    day: date
    doctor_day_slots: list[DoctorDaySlot]

Zwei berechnete Objekte, die keiner Tabelle entsprechen: ein Zeitfenster mit seinem möglichen Termin an einem bestimmten Tag; der Terminkalender eines Arztes für einen einzelnen Tag, die Liste seiner Zeitfenster. Es sind unveränderliche Datenklassen (Beispiel 03), deren Attribute typisiert sind: [Appointment | None] (ein Termin oder [None] für ein freies Zeitfenster), [list[DoctorDaySlot]] (eine Liste von Zeitfenstern). [Python] validiert diese Typen zur Laufzeit nicht, aber die Editoren ([Pylance]) und Analysewerkzeuge ([mypy]) lesen sie.

11.10. Die DAO-Schicht

Die DAO-Schicht (Beispiel 28) bündelt die Abfragen: ein Modul pro Tabelle (Ärzte und Clients teilen sich eines), ohne Geschäftsregeln. Ihre Methoden starten keine Transaktion: Die Geschäftsschicht ruft sie innerhalb ihrer eigenen Transaktionen auf. Sie sind mit dem [QuerySet] des ORM (Beispiel 28) geschrieben; die Werte darin sind Abfrageparameter: SQL-Injection ist nicht möglich. Die DAO sind Klassen, von denen die Geschäftsschicht jeweils ein Objekt erzeugt; sie haben keinen Zustand: Sie sind Sammlungen von Funktionen.

11.10.1. dao/persons.py

# =========================================================================
# dao/persons.py: die gemeinsame DAO-Schicht für Ärzte und Kunden.
#
# Die DAOs der Ärzte und Kunden wären identisch: Die Klasse PersonDao
# schreibt sie nur einmal. self.model ist das betroffene Modell (Doctor oder
# Client): Die Abfragen gelten für SEINE Tabelle.
#
# Die Abfragen sind mit dem Django-ORM geschrieben (siehe Beispiel 28), das sie in
# SQL übersetzt. Die Werte (Vorname, Nachname ...) werden zu PARAMETERN der SQL-Anweisung:
# keine String-Verkettung, also keine SQL-Injection. Diese Methoden öffnen
# keine Transaktion: Die Geschäftsschicht ruft sie auf, innerhalb ihrer eigenen.
# =========================================================================

from django.db.models import F, QuerySet

from models.models import Client, Doctor, Person


class PersonDao:
    # model: die KLASSE des Modells, Doctor oder Client (in Python ist eine Klasse
    # ein Wert wie jeder andere, der in einer Variablen gespeichert werden kann)
    def __init__(self, model: type[Person]):
        self.model = model

    # -----------------------------------------------------------------------
    # eine Abfrage auf die Tabelle des Modells, Benutzerkonto eingeschlossen.
    # select_related("account"): der SQL-Join mit der Tabelle [users]
    #   SELECT doctors.*, users.* FROM doctors INNER JOIN users ON ...
    # die Konten werden von DERSELBEN Abfrage geladen. Ohne sie würde jeder Zugriff auf
    # person.account eine eigene Abfrage auslösen
    # -----------------------------------------------------------------------
    def _query(self) -> QuerySet:
        return self.model.objects.select_related("account")

    # nach Nachname, dann Vorname sortierte Liste
    def list(self) -> list[Person]:
        return list(self._query().order_by("last_name", "first_name"))

    # eine Person und ihr Konto; None, wenn sie nicht existiert
    def read(self, id: int) -> Person | None:
        return self._query().filter(id=id).first()

    # die Person, deren Benutzerkonto [user_id] ist; account_id: die
    # Spalte des Fremdschlüssels selbst, ohne Join
    def read_by_user(self, user_id: int) -> Person | None:
        return self._query().filter(account_id=user_id).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: unabhängig
    # von Groß-/Kleinschreibung und Akzenten) - genau dieselbe Regel wie
    # die der SQL-Eindeutigkeitseinschränkung
    def namesake(self, first_name: str, last_name: str) -> Person | None:
        return self._query().filter(first_name=first_name, last_name=last_name).first()

    # INSERT: Die Datenbank erzeugt die id, die Django im erzeugten Objekt speichert
    def add(self, title: str, last_name: str, first_name: str, account) -> Person:
        return self.model.objects.create(title=title, last_name=last_name, first_name=first_name, account=account)

    # -----------------------------------------------------------------------
    # UPDATE mit OPTIMISTISCHEM SPERREN (siehe Beispiel 28):
    #   UPDATE doctors SET title = ?, last_name = ?, first_name = ?, version = version + 1
    #   WHERE id = ? AND version = ?
    # liefert False, wenn keine Zeile geändert wurde: Der Datensatz hat sich geändert (oder ist verschwunden),
    # seit er gelesen wurde
    # -----------------------------------------------------------------------
    def update(self, id: int, version: int, title: str, last_name: str, first_name: str) -> bool:
        return self.model.objects.filter(id=id, version=version).update(
            title=title, last_name=last_name, first_name=first_name, version=F("version") + 1) == 1

    # DELETE FROM doctors WHERE id = ?
    def delete(self, id: int) -> None:
        self.model.objects.filter(id=id).delete()


# das DAO der Ärzte: Alles wird von PersonDao geerbt
class DoctorDao(PersonDao):
    def __init__(self):
        super().__init__(Doctor)


# das DAO der Kunden: das der Personen, plus eine Sperrmethode
class ClientDao(PersonDao):
    def __init__(self):
        super().__init__(Client)

    # -----------------------------------------------------------------------
    # setzt eine SPERRE auf die Zeile eines Kunden bis zum Ende der aktuellen
    # Transaktion (SELECT ... FOR UPDATE) und liefert seine id (None, wenn der Kunde nicht
    # existiert). Eine zweite Transaktion, die dieselbe Sperre anfordert, WARTET, bis die
    # erste beendet ist. select_for_update: die "pessimistische" Sperre von
    # Django, die eine offene Transaktion voraussetzt.
    # Verwendet für die Buchung eines Termins (siehe BusinessService.add_appointment): Zwei
    # gleichzeitige Buchungen für denselben Patienten werden so eine
    # NACH der anderen verarbeitet, und die zweite sieht den von der ersten angelegten Termin.
    # values_list("id", flat=True): die einzelne Spalte id, ohne Client-Objekt
    # -----------------------------------------------------------------------
    def lock(self, id: int) -> int | None:
        return Client.objects.select_for_update().filter(id=id).values_list("id", flat=True).first()
  • Zeilen 19–23: Die DAO-Objekte für Ärzte und Clients wären bis auf das Modell identisch: Die Klasse [PersonDao] erzeugt sie einmalig und erhält das Modell als Parameter ihres Konstruktors. [type[Person]] ist die Annotation einer Klasse (nicht eines Objekts): [Person] oder eine ihrer Kindklassen;
  • Zeilen 32–33: die Basisabfrage, allen Methoden gemeinsam. [select_related("account")] weist das ORM an, auch das Konto jeder Person über einen Join abzurufen ([INNER JOIN users]; siehe die Konsolenausgabe oben): eine einzige Abfrage statt einer zusätzlichen Abfrage pro Person. Ohne sie würde die Anzeige der Liste der Ärzte mit ihren Logins eine Abfrage für die Liste und dann eine pro Arzt erfordern: Das ist das sogenannte „N + 1-Abfragen“-Problem, die häufigste Falle von ORM. Der Unterstrich am Anfang des Methodennamens zeigt an, dass sie klassenintern ist (Beispiel 06);
  • Zeilen 36–46: die Lesezugriffe. [account_id] (Zeile 46) bezeichnet die Fremdschlüsselspalte selbst: Die Bedingung gilt für die Personentabelle, ohne Join;
  • Zeilen 52–53: die Suche nach einer Namensgleichheit. Der Vergleich wird von [MySQL] mit der Kollation der Datenbank durchgeführt: ohne Beachtung der Groß- und Kleinschreibung und ohne Akzente, genau wie die Eindeutigkeitseinschränkung (Beispiel 28);
  • Zeilen 56–57: das Einfügen; [account] ist eine Instanz von [User], die bereits eingefügt wurde;
  • Zeilen 66–68: die Änderung mit ihrem optimistischen Sperren (Beispiel 28): [update] liefert die Anzahl der geänderten Zeilen, 0, wenn sich die Version geändert hat;
  • Zeilen 71–72: das Löschen über ein [QuerySet]: [delete()] sendet ein [DELETE] für alle Zeilen, die es bezeichnet;
  • Zeilen 76–78: das DAO für Ärzte, das alles erbt. [super().__init__(Doctor)] ruft den Konstruktor der Elternklasse mit dem Modell auf;
  • Zeilen 82–98: das DAO für Clients, mit einer zusätzlichen Methode. [select_for_update()] fügt der Abfrage [FOR UPDATE] hinzu: [MySQL] setzt eine Sperre auf die gelesenen Zeilen bis zum Ende der aktuellen Transaktion. Eine zweite Transaktion, die dieselbe Sperre anfordert, wartet, bis die erste beendet ist. Das ist eine „pessimistische“ Sperre: Sie blockiert die Transaktion, statt wie das optimistische Sperren Konflikte erst im Nachhinein zu erkennen. Sie ist nur innerhalb einer Transaktion erlaubt (andernfalls löst das ORM eine Ausnahme aus). [values_list("id", flat=True)] liest nur die Spalte [id]: eine Liste von ganzen Zahlen, keine Objekte. Der Code-Kommentar erklärt den Zweck dieser Sperre; wir kommen darauf zurück, wenn wir die Geschäftsschicht besprechen.

11.10.2. dao/slots.py

# dao/slots.py: die DAO-Schicht der Zeitfenster

from models.models import Slot


class SlotDao:
    # ein Zeitfenster und sein Arzt (ein Join)
    def read(self, id: int) -> Slot | None:
        return Slot.objects.select_related("doctor").filter(id=id).first()

    # die Zeitfenster eines Arztes in chronologischer Reihenfolge. doctor_id: die Spalte
    # des Fremdschlüssels, mit einer id verglichen
    def list_by_doctor(self, doctor_id: int) -> list[Slot]:
        return list(Slot.objects.filter(doctor_id=doctor_id).order_by("start_hour", "start_minute"))

    # löscht alle Zeitfenster eines Arztes (Löschen eines Arztes):
    #   DELETE FROM slots WHERE doctor_id = ?
    def delete_by_doctor(self, doctor_id: int) -> None:
        Slot.objects.filter(doctor_id=doctor_id).delete()

Die Zeitfenster eines Arztes in chronologischer Reihenfolge; ein Zeitfenster und sein Arzt (ein Join); das Löschen der Zeitfenster eines Arztes (das wegen der Fremdschlüsseleinschränkung dem Löschen des Arztes vorausgeht).

11.10.3. dao/appointments.py

# =========================================================================
# dao/appointments.py: die DAO-Schicht der Termine.
#
# Die Tabelle [appointments] verweist nicht direkt auf den Arzt: Sie geht über das Zeitfenster.
# Das Django-ORM schreibt den Join selbst, wenn auf einen Filter eine Beziehung folgt:
# slot__doctor_id (zwei Unterstriche: "der Arzt des Zeitfensters").
# =========================================================================

from datetime import date

from models.models import Appointment, Client, Slot


class AppointmentDao:
    # ein Termin, sein Kunde und sein Zeitfenster
    def read(self, id: int) -> Appointment | None:
        return Appointment.objects.select_related("client", "slot").filter(id=id).first()

    # die Termine eines Arztes an einem bestimmten Tag, mit ihrem Kunden
    def doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return list(Appointment.objects.select_related("client")
                    .filter(day=day, slot__doctor_id=doctor_id))

    # -----------------------------------------------------------------------
    # die Termine eines Kunden ab dem Tag [since] (einschließlich), in chronologischer
    # Reihenfolge, mit dem Zeitfenster UND dem Arzt dieses Zeitfensters (zwei Joins:
    # select_related("slot__doctor")). day__gte: day >= since (gte:
    # "greater than or equal")
    # -----------------------------------------------------------------------
    def client_upcoming_appointments(self, client_id: int, since: date) -> list[Appointment]:
        return list(Appointment.objects.select_related("slot__doctor")
                    .filter(client_id=client_id, day__gte=since)
                    .order_by("day", "slot__start_hour", "slot__start_minute"))

    # Anzahl der Termine eines Kunden ab dem Tag [since] (einschließlich):
    # count() lässt die Datenbank zählen (SELECT COUNT(*) ...)
    def count_client_upcoming(self, client_id: int, since: date) -> int:
        return Appointment.objects.filter(client_id=client_id, day__gte=since).count()

    # Anzahl der Termine (vergangene oder zukünftige) eines Arztes
    def count_by_doctor(self, doctor_id: int) -> int:
        return Appointment.objects.filter(slot__doctor_id=doctor_id).count()

    # INSERT INTO appointments ...
    def add(self, day: date, slot: Slot, client: Client) -> Appointment:
        return Appointment.objects.create(day=day, slot=slot, client=client)

    def delete(self, id: int) -> None:
        Appointment.objects.filter(id=id).delete()

    # löscht ALLE Termine (vergangene und zukünftige) eines Kunden
    def delete_by_client(self, client_id: int) -> None:
        Appointment.objects.filter(client_id=client_id).delete()
  • Zeilen 20–22: die Termine eines Arztes an einem bestimmten Tag. Die Tabelle [appointments] referenziert den Arzt nicht direkt: [slot__doctor_id] (zwei Unterstriche) folgt der Beziehung zum Zeitfenster und vergleicht dann die Spalte [doctor_id] des Zeitfensters. Das ORM schreibt den Join selbst ([INNER JOIN slots]; siehe die Konsolenausgabe oben). Der Client jedes Termins wird mit derselben Abfrage abgerufen;
  • Zeilen 30–33: die kommenden Termine eines Clients. [select_related("slot__doctor")] verbindet zwei Tabellen: das Zeitfenster und dann den Arzt des Clients (zwei Joins). [day__gte]: Das Suffix [gte] („greater than or equal“, Beispiel 28) führt einen Vergleich mit [>=] durch. Auch die Sortierung folgt den Beziehungen;
  • Zeilen 37–42: [count()] zählt die Basis ([SELECT COUNT(*)]), ohne die Zeilen zu lesen;
  • Zeilen 45–53: Einfügungen und Löschungen.

11.10.4. dao/users.py

# dao/users.py: die DAO-Schicht der Benutzerkonten. Das Anlegen (oder Löschen) eines
# Arztes oder Kunden legt auch sein Konto an (oder löscht es) - siehe business/service.py

from django.db.models import F

from models.models import User


class UserDao:
    # None, wenn kein Benutzer dieses Login hat
    def read_by_login(self, login: str) -> User | None:
        return User.objects.filter(login=login).first()

    def add(self, login: str, hash: str, name: str, role: str) -> User:
        return User.objects.create(login=login, password=hash, name=name, role=role)

    # UPDATE mit optimistischem Sperren (siehe dao/persons.py); Hash None: das
    # Passwort bleibt unverändert. **fields: das Dictionary, in benannte Parameter „entpackt“
    def update(self, id: int, version: int, login: str, name: str, hash: str | None) -> bool:
        fields = {"login": login, "name": name, "version": F("version") + 1}
        if hash is not None:
            fields["password"] = hash
        return User.objects.filter(id=id, version=version).update(**fields) == 1

    def delete(self, id: int) -> None:
        User.objects.filter(id=id).delete()

Die Benutzerkonten. Die Änderung (Zeilen 19–23) hat einen optionalen Parameter: den Hash des neuen Passworts oder [None] , um das bestehende beizubehalten. Die zu ändernden Spalten werden in einem Dictionary zusammengefasst, das [**fields] als benannte Parameter an [update] übergibt (das „Entpacken“ eines Dictionarys, Beispiel 08).

11.11. Die Geschäftsschicht

Die Geschäftsschicht (Beispiel 28): Geschäftsregeln und Transaktionen. Sie weiß nichts vom Web: keine Anfragen, keine Antworten, keine Templates.

11.11.1. business/dates.py

# business/dates.py: das heutige Datum. Es wird von GESCHÄFTSREGELN verwendet (keine
# Buchung in der Vergangenheit, nur ein einziger ZUKÜNFTIGER Termin pro Patient): Es gehört daher
# in die Geschäftsschicht. Die Web-Schicht verwendet es wieder.

from datetime import date

from django.utils import timezone


# heute, in der Zeitzone der Anwendung (Einstellung TIME_ZONE)
def today() -> date:
    return timezone.localdate()

Das heutige Datum in der Zeitzone der Anwendung ([TIME_ZONE], siehe [config/settings.py]): [timezone.localdate()] rechnet die koordinierte Weltzeit in diese Zeitzone um und liefert dann das Datum. Das aktuelle Datum wird für zwei Geschäftsregeln verwendet (keine Termine in der Vergangenheit, nur ein kommender Termin): Es wird daher hier an einer einzigen Stelle berechnet.

11.11.2. business/errors.py

# =========================================================================
# business/errors.py: die Exception, die die Geschäftsschicht auslöst, wenn eine GESCHÄFTSREGEL
# verletzt wird (Login bereits vergeben, Arzt mit noch bestehenden Terminen,
# Zeitfenster bereits gebucht ...).
#
# Sie trägt einen CODE (LOGIN_TAKEN ...), den die Web-Schicht prüfen kann, und die Meldung
# für den Benutzer. Diese Meldung wird beim Anzeigen
# ins Französische oder Englische übersetzt, in der Sprache der Seite: gettext_lazy liefert eine
# „lazy“ Übersetzung, die erst berechnet wird, wenn ihr Text angefordert wird
# (str), und nicht beim Laden des Moduls (siehe Beispiel 22 und den Ordner locale).
#
# Ein BusinessError ist keine Störung: Er ist eine normale Antwort („dieses Login
# wird bereits verwendet"), die dem Benutzer angezeigt wird. Jede andere Exception ist eine echte
# Störung, die auf der Fehlerseite 500 endet.
# =========================================================================

from django.utils.translation import gettext_lazy as _

# die Codes der Geschäftsfehler
LOGIN_TAKEN = "LOGIN_TAKEN"
DOCTOR_ALREADY_EXISTS = "DOCTOR_ALREADY_EXISTS"
CLIENT_ALREADY_EXISTS = "CLIENT_ALREADY_EXISTS"
DOCTOR_HAS_APPOINTMENTS = "DOCTOR_HAS_APPOINTMENTS"
SLOT_ALREADY_BOOKED = "SLOT_ALREADY_BOOKED"
CONCURRENT_UPDATE = "CONCURRENT_UPDATE"
DOCTOR_NOT_FOUND = "DOCTOR_NOT_FOUND"
CLIENT_NOT_FOUND = "CLIENT_NOT_FOUND"
PAST_DATE = "PAST_DATE"
PATIENT_HAS_APPOINTMENT = "PATIENT_HAS_APPOINTMENT"

# die Meldung zu jedem Code
MESSAGES = {
    LOGIN_TAKEN: _("This login is already used by another account."),
    DOCTOR_ALREADY_EXISTS: _("A doctor with this first and last name already exists."),
    CLIENT_ALREADY_EXISTS: _("A patient with this first and last name already exists."),
    DOCTOR_HAS_APPOINTMENTS: _("This doctor has appointments: cancel them before deleting the doctor."),
    SLOT_ALREADY_BOOKED: _("This slot has just been booked by someone else."),
    CONCURRENT_UPDATE: _("This record was changed by another user in the meantime. "
                         "Go back to the list and reopen it before trying again."),
    DOCTOR_NOT_FOUND: _("This doctor does not exist (any more)."),
    CLIENT_NOT_FOUND: _("This patient does not exist (any more)."),
    PAST_DATE: _("Appointments cannot be booked for a past date."),
    PATIENT_HAS_APPOINTMENT: _("This patient already has an upcoming appointment: it must be cancelled "
                               "before booking another one."),
}


class BusinessError(Exception):
    def __init__(self, code: str):
        super().__init__(code)
        self.code = code

    # die Meldung, in der Sprache der aktuellen Anfrage; @property: man schreibt
    # error.message, ohne Klammern
    @property
    def message(self) -> str:
        return str(MESSAGES[self.code])
  • Zeilen 20–29: Fehlercodes und Konstanten der Geschäftsschicht (Beispiel 09). Die Web-Schicht kann einen Fehlercode prüfen, um ihn dem richtigen Feld eines Formulars zuzuordnen (siehe unten);
  • Zeilen 32–45: die Meldung zu jedem Code, als „zu übersetzen“ markiert. [gettext_lazy], unter dem Kurznamen [_] importiert (wie in Beispiel 22 verwendet), liefert eine verzögerte Übersetzung: ein Objekt, das seine Übersetzung erst abruft, wenn der Text angefordert wird. Eine normale Übersetzung ([gettext]) würde beim Laden des Moduls, also beim Start, einmalig in der Standardsprache durchgeführt; die verzögerte Übersetzung erfolgt bei jeder Anzeige des Inhalts in der Sprache der aktuellen Anfrage. Zwei nebeneinander geschriebene Zeichenfolgen werden von [Python] verkettet (Zeile 38);
  • Zeilen 48–57: die Ausnahme der Geschäftsschicht (Beispiel 28), die ihren eigenen Code mitführt. Die Eigenschaft [message] (Beispiel 14) gibt die Meldung in der Sprache der Anfrage aus; [str] erzwingt die verzögerte Übersetzung.

Ein [BusinessError] ist kein Fehler: Er ist eine normale Antwort („dieses Login wird bereits verwendet“), die dem Benutzer angezeigt wird. Jede andere Ausnahme ist ein echter Fehler, der zu einer Fehlerseite 500 führt.

11.11.3. business/person_data.py

# business/person_data.py: die in einem 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
    # Erstellung: optional (None), standardmäßig der Nachname in Kleinbuchstaben
    # Aktualisierung: optional, das Login bleibt unverändert, wenn es fehlt
    login: str | None = None
    # Erstellung: optional, standardmäßig das Login
    # Aktualisierung: optional, das Passwort bleibt unverändert, wenn es fehlt
    password: str | None = None
    # Aktualisierung: die Version des Datensatzes zum Zeitpunkt der Anzeige des
    # Formulars (optimistisches Sperren)
    version: int | None = None

Die Daten einer Person, wie sie von der Web-Schicht an die Geschäftsschicht übergeben werden (Beispiel 28). Die letzten drei Attribute haben einen Standardwert, [None]: Sie sind optional. Ein Kommentar nach einem Attribut (Zeile 9) ist erlaubt: Der Kommentar reicht von [#] bis zum Zeilenende.

11.11.4. business/business.py

# =========================================================================
# business/business.py: der VERTRAG der Geschäftsschicht: Lesezugriffe, Terminkalender,
# Termine, Verwaltung von Ärzten und Clients.
#
# Eine abstrakte Klasse (ABC, siehe Beispiel 06) beschreibt die Methoden, die eine Klasse
# haben muss, ohne zu sagen, wie sie geschrieben werden. BusinessService (die Geschäftsschicht) und
# ApplicationModel (der Cache der Web-Schicht) erben beide davon; Python
# weigert sich, ein Objekt einer Klasse zu erzeugen, der eine abstrakte Methode fehlt.
#
# X | None: ein Ergebnis, das fehlen kann (ein Arzt, der nicht existiert ...).
# =========================================================================

from abc import ABC, abstractmethod
from datetime import date

from domain.schedule import DoctorDaySchedule
from models.models import Appointment, Client, Doctor, Slot

from .person_data import PersonData


class Business(ABC):
    # ──────────────────────────────────────────────── Lesezugriffe
    @abstractmethod
    def get_all_clients(self) -> list[Client]: ...

    @abstractmethod
    def get_all_doctors(self) -> list[Doctor]: ...

    @abstractmethod
    def get_all_slots(self, doctor_id: int) -> list[Slot]: ...

    @abstractmethod
    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]: ...

    @abstractmethod
    def get_client_by_id(self, id: int) -> Client | None: ...

    @abstractmethod
    def get_doctor_by_id(self, id: int) -> Doctor | None: ...

    @abstractmethod
    def get_appointment_by_id(self, id: int) -> Appointment | None: ...

    @abstractmethod
    def get_slot_by_id(self, id: int) -> Slot | None: ...

    @abstractmethod
    def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None: ...

    # der Client (Patient), dessen Benutzerkonto [user_id] ist
    @abstractmethod
    def get_client_by_user_id(self, user_id: int) -> Client | None: ...

    # die Termine eines Clients, heute oder in der Zukunft, mit Zeitfenster und Arzt
    @abstractmethod
    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]: ...

    # ──────────────────────────────────────────────── Termine (ADMIN, DOCTOR, USER)
    # löst einen BusinessError aus, wenn:
    #  - der Tag in der Vergangenheit liegt (PAST_DATE);
    #  - der Patient bereits einen zukünftigen Termin hat (PATIENT_HAS_APPOINTMENT);
    #  - das Zeitfenster an diesem Tag bereits belegt ist (SLOT_ALREADY_BOOKED).
    @abstractmethod
    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment: ...

    @abstractmethod
    def delete_appointment(self, appointment: Appointment) -> None: ...

    # ──────────────────────────────────────────────── Ärzte (ADMIN)
    # erstellt den Arzt UND sein Benutzerkonto (Rolle DOCTOR)
    @abstractmethod
    def add_doctor(self, data: PersonData) -> Doctor: ...

    # aktualisiert den Arzt UND sein Benutzerkonto
    @abstractmethod
    def edit_doctor(self, id: int, data: PersonData) -> Doctor: ...

    # löscht den Arzt, seine Zeitfenster UND sein Konto - abgelehnt, wenn er Termine hat
    @abstractmethod
    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)
    # erstellt den Client UND sein Benutzerkonto (Rolle USER)
    @abstractmethod
    def add_client(self, data: PersonData) -> Client: ...

    @abstractmethod
    def edit_client(self, id: int, data: PersonData) -> Client: ...

    # löscht den Client, sein Konto UND alle seine Termine (vergangene und zukünftige)
    @abstractmethod
    def delete_client(self, id: int) -> None: ...

Der Vertrag der Geschäftsschicht, eine abstrakte Klasse (Beispiel 06): alle Methoden mit ihren Parametern und Typen und, in Kommentaren, den Regeln, die sie durchsetzen. Der Rumpf einer abstrakten Methode kann in derselben Zeile wie ihre Signatur stehen ([: ...]). Zwei Klassen erben von diesem Vertrag: [BusinessService], die Geschäftsschicht selbst, und [ApplicationModel], die Fassade der Web-Schicht (siehe später), die damit überall dort die Geschäftsschicht ersetzen kann, wo ein Objekt [Business] erwartet wird.

11.11.5. business/descriptor.py

# business/descriptor.py: alles, was einen Arzt von einem Client für die
# Geschäftsregeln unterscheidet (siehe business/service.py). Ärzte und Clients folgen denselben
# Regeln: Der gemeinsame Code wird EINMAL geschrieben und über einen Descriptor parametrisiert.

from collections.abc import Callable
from dataclasses import dataclass

from dao.persons import PersonDao


@dataclass(frozen=True)
class Descriptor:
    dao: PersonDao
    role: str                   # DOCTOR oder USER
    not_found_code: str         # Fehler, wenn die Person nicht existiert
    already_exists_code: str    # Fehler, wenn dieselben Vor- und Nachnamen bereits existieren
    # optional (None): falls vorhanden, wird das Löschen ABGELEHNT, solange die
    # Person Termine hat (count_appointments(id) > 0), mit dem Fehler has_appointments_code.
    # Callable[[int], int]: eine Funktion, die eine ganze Zahl erhält und eine ganze Zahl zurückgibt
    count_appointments: Callable[[int], int] | None
    has_appointments_code: str | None
    # optional: was VOR der Person gelöscht werden muss (die Zeilen, die
    # sie über einen Fremdschlüssel referenzieren); erhält deren id
    before_delete: Callable[[int], None] | None

Ärzte und Clients folgen denselben Verwaltungsregeln, mit einigen kleinen Unterschieden: ihre Kontorollen, ihre Fehlercodes und das, was ihr Löschen verhindert oder erleichtert. Ein Deskriptor fasst diese Einzelheiten zusammen; der gemeinsame Code in [BusinessService] wird einmal definiert und erhält den Deskriptor. Die letzten drei Attribute sind Funktionen: [Callable[[int], int]] deklariert eine Funktion, die eine ganze Zahl entgegennimmt und eine ganze Zahl zurückgibt (das Modul [collections.abc] stellt diese abstrakten Typen bereit); [| None]: oder nichts.

11.11.6. business/provider.py

# business/provider.py: der Provider der Geschäftsschicht (siehe Beispiel 06):
# EIN Objekt BusinessService, bei der ersten Anfrage erzeugt und dann von allen
# Anfragen gemeinsam genutzt, solange der Server läuft. Es hat keinen anfragespezifischen Zustand:
# die gemeinsame Nutzung ist sicher, auch zwischen mehreren Threads

from functools import cache

from .service import BusinessService


@cache
def business() -> BusinessService:
    return BusinessService()

Der Provider der Geschäftsschicht (Beispiel 06): ein einziges Objekt [BusinessService], bei der ersten Anfrage erzeugt und dann von allen Anfragen gemeinsam genutzt. Das ist sicher, auch bei mehreren Ausführungs-Threads (Beispiel 20): Das Objekt hat keinen anfragespezifischen Zustand (seine DAO-Objekte ebenfalls nicht), und jeder Thread hat seine eigene Verbindung zur Datenbank (das ORM von [Django] öffnet eine Verbindung pro Ausführungs-Thread).

11.11.7. business/service.py

# =========================================================================
# business/service.py: die Implementierung der Geschäftsschicht.
#
# Die Verwaltung von Ärzten und Clients folgt drei Geschäftsregeln:
#
#   1. eine Person (Arzt oder Client) und ihr Benutzerkonto gehören IMMER
#      zusammen: Sie werden gemeinsam erstellt, aktualisiert und gelöscht, in derselben
#      TRANSAKTION - entweder gelingt alles, oder es wird nichts geschrieben;
#   2. das 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): Diese müssen zuvor
#        storniert werden. Seine Zeitfenster verschwinden mit ihm;
#      - ein CLIENT verschwindet dagegen mit ALLEN seinen Terminen (vergangenen und zukünftigen) -
#        unabhängig davon, 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 dessen, der
# bucht (ADMIN, DOCTOR oder der Patient selbst):
#   4. kein Termin in der Vergangenheit;
#   5. ein Patient hat jeweils nur EINEN zukünftigen Termin.
#
# Ärzte und Clients folgen exakt denselben Regeln: Der gemeinsame Code wird
# EINMAL geschrieben (Methoden _xxx_person) und über einen Descriptor parametrisiert, der angibt,
# um welche Art von Person es sich handelt.
#
# Die TRANSAKTIONEN werden von der Methode _transaction geöffnet (am Ende der Datei),
# die außerdem die von der Datenbank gemeldeten Fehler in BusinessError übersetzt.
# =========================================================================

import re
from collections.abc import Callable
from datetime import date

from django.db import IntegrityError, transaction

from dao.slots import SlotDao
from dao.persons import ClientDao, DoctorDao
from dao.appointments import AppointmentDao
from dao.users import UserDao
from domain.schedule import DoctorDaySchedule, DoctorDaySlot
from models.models import Appointment, Client, Doctor, Person, Role, Slot
from security import passwords

from . import errors
from .dates import today
from .descriptor import Descriptor
from .person_data import PersonData
from .errors import BusinessError
from .business import Business

# -------------------------------------------------------------------------
# Datenbankfehler -> BusinessError
#
# Wenn eine UNIQUE-Einschränkung einen Schreibvorgang ablehnt, löst Django einen IntegrityError aus,
# dessen Meldung die von MySQL ist. Sie nennt den NAMEN der Einschränkung:
#   (1062, "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
# GIBT das SQL-Skript allen seinen Einschränkungen NAMEN. Der reguläre Ausdruck CONSTRAINT
# extrahiert diesen Namen: (?:[^'.]*\.)? überspringt das optionale Präfix, ([^']+) erfasst den Namen
# -------------------------------------------------------------------------
CONSTRAINT_ERRORS = {
    "unq_users_login": errors.LOGIN_TAKEN,
    "unq_doctors_first_name_last_name": errors.DOCTOR_ALREADY_EXISTS,
    "unq_clients_first_name_last_name": errors.CLIENT_ALREADY_EXISTS,
    "unq1_appointments": errors.SLOT_ALREADY_BOOKED,
}

CONSTRAINT = re.compile(r"for key '(?:[^'.]*\.)?([^']+)'")


# ein BusinessError CONCURRENT_UPDATE, INNERHALB einer Transaktion ausgelöst, damit diese
# zurückgerollt wird: Ein UPDATE hat keine Zeile geändert (optimistisches Sperren)
class _StaleVersion(Exception):
    pass


class BusinessService(Business):
    # die DAOs, einmalig erzeugt; sie haben keinen Zustand: Ein einziges Objekt
    # jedes DAO bedient alle Anfragen
    def __init__(self):
        self.doctors = DoctorDao()
        self.clients = ClientDao()
        self.slots = SlotDao()
        self.appointments = AppointmentDao()
        self.users = UserDao()

        self.doctor = Descriptor(
            dao=self.doctors,
            role=Role.DOCTOR,
            not_found_code=errors.DOCTOR_NOT_FOUND,
            already_exists_code=errors.DOCTOR_ALREADY_EXISTS,
            # self.appointments.count_by_doctor: die Methode selbst, ohne Aufruf (eine
            # „gebundene Methode“ des Objekts self.appointments, die später aufgerufen wird)
            count_appointments=self.appointments.count_by_doctor,
            has_appointments_code=errors.DOCTOR_HAS_APPOINTMENTS,
            # ein Arzt ohne Termine kann dennoch Zeitfenster haben:
            # sie ergeben ohne ihn keinen Sinn und werden mit ihm gelöscht (sonst würde der
            # Fremdschlüssel slots.doctor_id das Löschen verbieten)
            before_delete=self.slots.delete_by_doctor)

        self.client = Descriptor(
            dao=self.clients,
            role=Role.USER,
            not_found_code=errors.CLIENT_NOT_FOUND,
            already_exists_code=errors.CLIENT_ALREADY_EXISTS,
            # kein count_appointments: Das Löschen eines Clients wird nie abgelehnt;
            # seine Termine (vergangene und zukünftige) werden mit ihm gelöscht (sonst würde der
            # Fremdschlüssel appointments.client_id das Löschen verbieten)
            count_appointments=None,
            has_appointments_code=None,
            before_delete=self.appointments.delete_by_client)

    # =======================================================================
    # Lesezugriffe
    # =======================================================================

    def get_all_clients(self) -> list[Client]:
        return self.clients.list()

    def get_all_doctors(self) -> list[Doctor]:
        return self.doctors.list()

    def get_all_slots(self, doctor_id: int) -> list[Slot]:
        return self.slots.list_by_doctor(doctor_id)

    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return self.appointments.doctor_day_appointments(doctor_id, day)

    def get_client_by_id(self, id: int) -> Client | None:
        return self.clients.read(id)

    def get_doctor_by_id(self, id: int) -> Doctor | None:
        return self.doctors.read(id)

    def get_appointment_by_id(self, id: int) -> Appointment | None:
        return self.appointments.read(id)

    def get_slot_by_id(self, id: int) -> Slot | None:
        return self.slots.read(id)

    def get_client_by_user_id(self, user_id: int) -> Client | None:
        return self.clients.read_by_user(user_id)

    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
        return self.appointments.client_upcoming_appointments(client_id, 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
        # eine Dictionary-COMPREHENSION: Nr. des Zeitfensters -> für dieses Zeitfenster gebuchter Termin
        bookings = {a.slot_id: a for a in self.get_doctor_day_appointments(doctor_id, day)}
        # get(key): der Wert, oder None, wenn der Schlüssel fehlt
        doctor_day_slots = [DoctorDaySlot(slot, bookings.get(slot.id))
                            for slot in self.get_all_slots(doctor_id)]
        return DoctorDaySchedule(doctor, day, doctor_day_slots)

    # =======================================================================
    # Termine
    # =======================================================================

    # -----------------------------------------------------------------------
    # einen Termin buchen, in einer Transaktion:
    #   1. kein Termin in der Vergangenheit;
    #   2. die Zeile des Patienten wird GESPERRT (SELECT ... FOR UPDATE): Wenn derselbe
    #      Patient zwei Zeitfenster gleichzeitig bucht (zwei Tabs, Doppelklick
    #      ...), wartet die zweite Transaktion auf das Ende der ersten - und sieht dann den
    #      Termin, den diese gerade erstellt hat;
    #   3. nur ein zukünftiger Termin pro Patient;
    #   4. schließlich das Einfügen. Wurde das Zeitfenster gerade von einem ANDEREN Patienten belegt,
    #      lehnt die SQL-Einschränkung unq1_appointments (day, slot_id) das Einfügen ab -
    #      von _transaction in BusinessError übersetzt.
    # Eine INNERHALB einer Methode definierte Funktion (work) sieht die Variablen
    # dieser Methode (day, slot, client): Das ist eine „Closure“
    # -----------------------------------------------------------------------
    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
        def work():
            if day < today():
                raise BusinessError(errors.PAST_DATE)
            patient_id = self.clients.lock(client.id)
            if patient_id is None:
                raise BusinessError(errors.CLIENT_NOT_FOUND)
            if self.appointments.count_client_upcoming(patient_id, today()) > 0:
                raise BusinessError(errors.PATIENT_HAS_APPOINTMENT)
            return self.appointments.add(day, slot, client)
        return self._transaction(work)

    def delete_appointment(self, appointment: Appointment) -> None:
        # lambda: eine anonyme Funktion, beschränkt auf einen Ausdruck
        self._transaction(lambda: self.appointments.delete(appointment.id))

    # =======================================================================
    # Ärzte und Clients - die öffentlichen Methoden delegieren an die gemeinsamen
    # Methoden, mit dem passenden Descriptor
    # =======================================================================

    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)

    # -----------------------------------------------------------------------
    # Erstellung: das Benutzerkonto, DANN die Person (die es über ihren
    # Fremdschlüssel [user] referenziert), in EINER Transaktion
    # -----------------------------------------------------------------------
    def _add_person(self, d: Descriptor, data: PersonData) -> Person:
        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 (oder der Patient) hat andere eingegeben
        login = (data.login or last_name).lower()
        password = data.password or login

        def work():
            self._check_person_unique(d, first_name, last_name, None)
            self._check_login_free(login)
            account = self.users.add(login, passwords.hash_password(password), f"{first_name} {last_name}", d.role)
            return d.dao.add(data.title, last_name, first_name, account)
        return self._transaction(work)

    # -----------------------------------------------------------------------
    # Aktualisierung: die Person UND ihr Konto (der angezeigte Name „Vorname NACHNAME“ muss
    # mitziehen; Login und Passwort ändern sich nur, wenn sie eingegeben wurden).
    # -----------------------------------------------------------------------
    def _edit_person(self, d: Descriptor, id: int, data: PersonData) -> Person:
        def work():
            person = d.dao.read(id)
            if person is None:
                raise BusinessError(d.not_found_code)
            # optimistisches Sperren: Entspricht die Version in der Datenbank nicht mehr der des
            # Formulars, hat jemand diesen Datensatz in der Zwischenzeit geändert - wir lehnen ab,
            # anstatt seine Änderungen stillschweigend zu überschreiben
            if data.version is not None and data.version != person.version:
                raise BusinessError(errors.CONCURRENT_UPDATE)
            last_name = data.last_name.strip().upper()
            first_name = data.first_name.strip()
            self._check_person_unique(d, first_name, last_name, id)
            # sein Konto: der angezeigte Name und, falls eingegeben, das Login und das
            # Passwort
            account = person.account
            login = data.login.lower() if data.login else account.login
            if login != account.login:
                self._check_login_free(login)
            hash = passwords.hash_password(data.password) if data.password else None
            # die UPDATEs, mit ihrem optimistischen Sperren: Wurde der Datensatz (oder das Konto)
            # NACH dem obigen Lesen geändert, wird keine Zeile geändert
            if not d.dao.update(id, person.version, data.title, last_name, first_name):
                raise _StaleVersion()
            if not self.users.update(account.id, account.version, login, f"{first_name} {last_name}", hash):
                raise _StaleVersion()
            # die erneut gelesene Person, mit ihrem Konto: die gespeicherten Werte
            return d.dao.read(id)
        return self._transaction(work)

    # -----------------------------------------------------------------------
    # Löschen, in EINER Transaktion, in der durch die Fremdschlüssel
    # vorgegebenen Reihenfolge:
    #   1. mögliche Ablehnung, wenn noch Termine existieren (Arzt);
    #   2. was die Person referenziert (Zeitfenster eines Arztes, Termine eines
    #      Clients);
    #   3. die Person (die ihr Konto referenziert), dann ihr Konto.
    # -----------------------------------------------------------------------
    def _delete_person(self, d: Descriptor, id: int) -> None:
        def work():
            person = d.dao.read(id)
            if person is None:
                raise BusinessError(d.not_found_code)
            if d.count_appointments is not None and d.count_appointments(id) > 0:
                raise BusinessError(d.has_appointments_code)
            if d.before_delete is not None:
                d.before_delete(id)
            d.dao.delete(id)
            self.users.delete(person.account_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 aktualisiert wird und selbstverständlich das Recht hat,
    # ihren eigenen Vor- und Nachnamen zu behalten; None bei einer Erstellung)
    def _check_person_unique(self, d: Descriptor, first_name: str, last_name: str,
                             current_id: int | None) -> None:
        namesake = d.dao.namesake(first_name, last_name)
        if namesake is not None and namesake.id != current_id:
            raise BusinessError(d.already_exists_code)

    def _check_login_free(self, login: str) -> None:
        if self.users.read_by_login(login) is not None:
            raise BusinessError(errors.LOGIN_TAKEN)

    # -----------------------------------------------------------------------
    # führt [work] in einer Transaktion aus (transaction.atomic, siehe Beispiel 28):
    # Endet die Funktion normal, wird die Transaktion bestätigt (COMMIT);
    # kommt eine Exception heraus (auch BusinessError), wird sie zurückgerollt
    # (ROLLBACK): Es wird nichts geschrieben.
    #
    # Die Prüfungen „Login frei“ und „eindeutiger Vor- + Nachname“ erfolgen VOR
    # dem Schreiben, um eine klare Meldung zu geben. Aber zwei ADMINs könnten
    # im selben Moment dasselbe Login (oder denselben Arzt) speichern: In diesem
    # seltenen Fall lehnt eine SQL-Eindeutigkeitseinschränkung den zweiten Schreibvorgang ab.
    # Ebenso werden zwei gleichzeitige Aktualisierungen desselben Datensatzes durch das
    # optimistische Sperren geklärt. Diese Fehler werden daher UM die Transaktion herum abgefangen,
    # um sie in BusinessError zu übersetzen. Jeder andere Fehler ist eine echte Störung:
    # er wird weitergereicht.
    # -----------------------------------------------------------------------
    def _transaction(self, work: Callable):
        try:
            with transaction.atomic():
                return work()
        except IntegrityError as e:
            # str(e): die MySQL-Meldung
            found = CONSTRAINT.search(str(e))
            if found and found.group(1) in CONSTRAINT_ERRORS:
                # from e: die neue Exception behält die Spur der Exception, die sie verursacht hat
                raise BusinessError(CONSTRAINT_ERRORS[found.group(1)]) from e
            raise
        except _StaleVersion as e:
            raise BusinessError(errors.CONCURRENT_UPDATE) from e

11.11.7.1. Abhängigkeiten und Deskriptoren

  • Zeilen 62–69: Übersetzung von Datenbankfehlern in Geschäftsfehler (siehe „Transaktionen“ weiter unten);
  • Zeilen 74–75: eine interne Ausnahme, die ein [UPDATE] ohne Wirkung signalisiert (das optimistische Sperren);
  • Zeilen 81–86: die DAO-Objekte, einmalig vom Konstruktor erzeugt;
  • Zeilen 88–112: die beiden Deskriptoren. Die Funktionen sind Methoden der DAO, ohne Klammern übergeben (Zeile 95): Es sind gebundene Methoden – Funktionen, die einen Verweis auf ihr Objekt behalten – und sie werden später aufgerufen ([d.count_appointments(id)], Zeile 286). Ein Arzt mit Terminen kann nicht gelöscht werden; seine Zeitfenster werden mit ihm gelöscht. Ein Client wird zusammen mit seinen Terminen gelöscht. Die Parameter sind benannt: Man sieht sofort, wofür jeder Wert dient.

11.11.7.2. Lesevorgänge und der Kalender

  • Zeilen 118–146: die Lesezugriffe, an die DAO-Schicht delegiert. Das aktuelle Datum wird hier berechnet (Zeile 146), nicht vom DAO: Das ist eine Geschäftsregel („kommend“);
  • Zeilen 150–159: der Terminkalender eines Arztes für einen bestimmten Tag. Ein schreibgeschütztes Dictionary (Beispiel 18) ordnet jeder Nummer eines Zeitfensters den Termin zu, der für dieses Zeitfenster an diesem Tag gebucht ist ([a.slot_id]: der Fremdschlüssel, ohne Abfrage; siehe die Modelle); dann, für jedes Zeitfenster des Arztes, der entsprechende Termin oder [None]. Nur zwei Abfragen, unabhängig von der Anzahl der Zeitfenster: die Termine des Tages und die Zeitfenster (plus die Angaben zum Arzt), wie die Konsole zeigt („Entwicklungsmodus“).

11.11.7.3. Terminplanung

  • Zeilen 179–189: Einen Termin in einer Transaktion planen. Die Funktion [work], die in der Methode definiert ist, erhält ihre Parameter ([day], [slot], [client]): Das ist eine Closure (Beispiel 08). Sie wird an [_transaction] übergeben, das sie innerhalb einer Transaktion ausführt;
  • Zeilen 181–182: keine Termine in der Vergangenheit;
  • Zeilen 183–185: die „pessimistische“ Sperre auf den Datensatz des Patienten ([SELECT ... FOR UPDATE]; siehe DAO-Schicht). Der Grund: Die Regel „nur ein kommender Termin“ wird durch eine Zählung geprüft (Zeile 186), danach wird der Termin eingefügt (Zeile 188). Wenn derselbe Patient zwei Zeitfenster gleichzeitig bucht (zwei Tabs, ein Doppelklick), könnten zwei Transaktionen beide null Termine zählen und dann beide den Termin einfügen: Keine Datenbankeinschränkung würde dies verhindern, da die beiden Zeitfenster verschieden sind. Die Sperre auf die Zeile des Patienten bewirkt, dass die zweite Transaktion wartet, bis die erste beendet ist: Sie zählt dann einen Termin und schlägt fehl. Die Datenbank kann diese Regel nicht allein durchsetzen: Es ist die Geschäftsschicht, die sie mit Unterstützung der Datenbank durchsetzt;
  • Zeilen 186–187: nur ein kommender Termin pro Patient;
  • Zeile 188: das Einfügen. Wurde das Zeitfenster gerade von einem anderen Patienten belegt, so lehnt die Datenbankeinschränkung [unq1_appointments] das Einfügen ab, und [_transaction] übersetzt den Fehler (weiter unten);
  • Zeilen 191–193: einen Termin stornieren. [lambda: ...] ist eine anonyme Funktion, reduziert auf einen einzigen Ausdruck (hier einen Aufruf): das Äquivalent einer dreizeiligen Funktion [def].

11.11.7.4. Ärzte und Patienten verwalten

  • Zeilen 200–218: Die öffentlichen Methoden delegieren an gemeinsame Methoden, jeweils mit dem passenden Deskriptor;
  • Zeilen 224–237: eine Person anlegen. Der Nachname wird in Großbuchstaben geschrieben ([PELISSIER], die Konvention der Datenbank), und die Leerzeichen um die Eingabe werden entfernt. Die Regeln der Datenbank [dbrdvmedecins2]: Standardmäßig ist das Login der Nachname in Kleinbuchstaben, und das Passwort ist standardmäßig das Login ([a or b]: [a] wenn es „wahr“ ist (eine nicht leere Zeichenfolge), [b] andernfalls). In der Transaktion: die Validierungen (Prüfung auf Namensgleichheit, freies Login), dann das Konto (mit dem Passwort-Hash; siehe [security/passwords.py]), dann die Person, die das Konto über ihren Fremdschlüssel referenziert: Die Reihenfolge ist festgelegt;
  • Zeilen 243–271: eine Person und ihr Konto ändern. Die Version des Formulars wird mit der gelesenen Version verglichen (Zeile 251): Das ist die erste Stufe des optimistischen Sperrens, die eine verständliche Meldung liefert. Die zweite Stufe ist die des [UPDATE] (Zeilen 265–268): Wurde der Datensatz zwischen dem Lesevorgang (Zeile 245) und dem Schreibvorgang geändert, ändert [UPDATE] nichts, und die Ausnahme [_StaleVersion] macht die gesamte Transaktion rückgängig (das Konto wird also ebenfalls nicht geändert). Login und Passwort ändern sich nur, wenn sie eingegeben wurden; der angezeigte Kontoname folgt der Person;
  • Zeilen 281–292: das Löschen in der durch die Fremdschlüssel vorgegebenen Reihenfolge: das, was auf die Person verweist (ihre Zeitfenster oder Termine), die Person, dann ihr Konto. [person.account_id] ist der Fremdschlüssel, der ohne Abfrage gelesen wird;
  • Zeilen 297–305: die beiden Eindeutigkeitsprüfungen, die vor dem Schreibvorgang durchgeführt werden, um eine verständliche Meldung zu gewährleisten. Eine Person, die bearbeitet wird, darf ihren eigenen Vor- und Nachnamen behalten: [current_id] schließt dies aus.

11.11.7.5. Datenbanktransaktionen und -fehler

  • Zeilen 322–334: Jeder Schreibvorgang wird innerhalb einer Transaktion ausgeführt ([transaction.atomic], Beispiel 28): Wenn [work] normal endet, wird die Transaktion bestätigt ([COMMIT]); tritt eine Ausnahme auf (auch ein [BusinessError]), wird sie rückgängig gemacht ([ROLLBACK]): Es wird nichts geschrieben. Die Geschäftsschicht legt so den Umfang der Transaktionen fest: eine Geschäftsoperation, eine Transaktion;
  • Zeilen 326–332: Die vor dem Schreiben durchgeführten Prüfungen genügen nicht immer: Zwei Administratoren könnten gleichzeitig dasselbe Login speichern. In diesem Fall weist eine Eindeutigkeitseinschränkung der Datenbank den zweiten Schreibvorgang zurück, und das ORM löst eine [IntegrityError] aus, deren Meldung die von [MySQL] ist: [(1062, "Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'")]. Der reguläre Ausdruck [CONSTRAINT] (Zeile 69) extrahiert den Namen der Einschränkung ([search] sucht den Ausdruck in der Zeichenfolge; [group(1)] liefert, was die erste Gruppe in Klammern erfasst hat; [(?:...)] ist eine nicht erfassende Gruppe, und [?] macht sie optional: [MySQL] 8 stellt dem Namen den Tabellennamen voran, [MariaDB] nicht). Deshalb gibt das SQL-Skript allen seinen Einschränkungen einen Namen. Eine bekannte Einschränkung wird zum entsprechenden [BusinessError]; eine andere, [IntegrityError], wird unverändert erneut ausgelöst ([raise] ohne Parameter): Das ist eine echte Anomalie. [raise ... from e] hängt die ursprüngliche Ausnahme an die neue an (Beispiel 28);
  • Zeilen 333–334: Ein fehlgeschlagenes optimistisches Sperren führt zum Fehler [CONCURRENT_UPDATE]. Die Ausnahme [_StaleVersion] wird innerhalb des Blocks [atomic] ausgelöst, um die Transaktion rückgängig zu machen, und dann außerhalb des Blocks weitergereicht.

Ausnahmen werden außerhalb des Blocks [with transaction.atomic()] abgefangen, nicht innerhalb: Nach einem Datenbankfehler ist die Transaktion nicht mehr gültig und muss zuerst rückgängig gemacht werden, was das Verlassen des Blocks bewirkt (Beispiel 28).

11.12. Authentifizierung und Sicherheit

Das Paket [security] umfasst alles rund um die Authentifizierung (wer ist der Benutzer?), die Berechtigungen (hat der Benutzer Zugriff auf diese Seite?) und den Schutz vor Bots. Dies ist die vollständige Version der Beispiele 25 bis 27.

11.12.1. security/passwords.py

# =========================================================================
# security/passwords.py: das Hashen der Passwörter mit dem Algorithmus bcrypt
# (Bibliothek bcrypt), 10 Runden, wie die Hashes des SQL-Skripts.
#
# Ein HASH ist eine Einwegfunktion: Das Passwort lässt sich daraus nicht wiederherstellen.
# Um ein eingegebenes Passwort zu prüfen, wird es mit dem „Salt“ (einem
# Zufallswert) gehasht, der im gespeicherten Hash enthalten ist, und die beiden
# Ergebnisse werden verglichen: Das macht bcrypt.checkpw.
#
# Die Hashes des SQL-Skripts beginnen mit $2b$; die der anderen Versionen der
# Anwendung, die dieselbe Datenbank nutzen, mit $2y$ (PHP) oder $2a$ (Java):
# bcrypt prüft alle drei Formen.
#
# bcrypt berücksichtigt nur die ersten 72 BYTES des Passworts (und die
# Bibliothek weigert sich, mehr zu hashen): Die Formulare begrenzen daher die
# Länge der Passwörter (siehe web/forms.py).
# =========================================================================

import bcrypt

# die Anzahl der Runden: Der Hash kostet 2^10 elementare Berechnungen
ROUNDS = 10
MAX_BYTES = 72


def hash_password(password: str) -> str:
    # encode: den String in Bytes (UTF-8); decode: die Bytes in einen String
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt(ROUNDS)).decode()


def check_password(password: str, hash: str) -> bool:
    data = password.encode()
    if len(data) > MAX_BYTES:
        return False
    return bcrypt.checkpw(data, hash.encode())

Die Passwörter in der Datenbank werden von [bcrypt] gehasht (das oben erwähnte SQL-Skript), nicht von PBKDF2, dem Standardalgorithmus von [Django] (Beispiel 25). Die Bibliothek [bcrypt] überprüft sie direkt:

  • Zeilen 26–28: der Hash eines Passworts. [gensalt(10)] erzeugt ein zufälliges Salt mit dem Kostenfaktor 10; [hashpw] berechnet den Hash, der den Algorithmus, den Kostenfaktor und das Salt enthält (Beispiel 25). Die Bibliothek arbeitet mit Bytes: [encode()] wandelt die Zeichenfolge in Bytes um ([UTF-8]), und [decode()] führt die Umkehrung durch;
  • Zeilen 31–35: die Überprüfung. [checkpw] entnimmt Kostenfaktor und Salt dem gespeicherten Hash, hasht damit das eingegebene Passwort und vergleicht die Ergebnisse (in konstanter Zeit, Beispiel 23). [bcrypt] berücksichtigt nur die ersten 72 Bytes eines Passworts, und die Bibliothek weigert sich seit Version 5, mehr zu hashen (sie löst eine Ausnahme aus): Ein längeres Passwort wird daher von vornherein abgelehnt. Auch die Formulare begrenzen die Länge des Passworts (Web-Schicht, siehe später).

[Django] hätte diese Hashes selbst überprüfen können, mit seinem Algorithmus [BCryptPasswordHasher] (Einstellung [PASSWORD_HASHERS]): Er erwartet jedoch Hashes mit dem Präfix [bcrypt$], und die Datenbank wird mit anderen Versionen der Anwendung geteilt, die dieses Präfix nicht kennen.

11.12.2. security/connected_user.py

# =========================================================================
# security/connected_user.py: der angemeldete Benutzer, wie ihn sein JWT-Token beschreibt
# (siehe Beispiel 25).
#
# Die Claims unserer Token (siehe security/auth.py):
#   sub   : die id des Benutzerkontos (JWT-Konvention: „subject“), als Text
#   login : das Login
#   name  : der angezeigte Name („Marie PELISSIER“), für die Navigationsleiste
#   role  : ADMIN, DOCTOR oder USER
#   iat, exp : Erstellungs- und Ablaufdatum des Tokens
#
# Dieses Objekt stammt NICHT aus der Datenbank: Es wird bei jeder Anfrage aus
# dem Token neu aufgebaut, dessen Signatur den Inhalt garantiert.
# =========================================================================

from dataclasses import dataclass

from models.models import Role


@dataclass(frozen=True)
class ConnectedUser:
    user_id: int
    login: str
    name: str
    role: str

    # der Benutzer, wie ihn die Claims eines bereits geprüften Tokens beschreiben; None, wenn ein Claim
    # fehlt oder nicht die erwartete Form hat. @staticmethod: eine in der
    # Klasse abgelegte Funktion, die weder Objekt noch Klasse erhält
    @staticmethod
    def from_claims(claims: dict) -> "ConnectedUser | None":
        role = claims.get("role")
        sub = str(claims.get("sub", ""))
        # Role.values: die Werte der Enumeration; isdigit: nur Ziffern
        if role not in Role.values or not sub.isdigit() or "login" not in claims or "name" not in claims:
            return None
        return ConnectedUser(int(sub), str(claims["login"]), str(claims["name"]), role)

    @property
    def is_admin(self) -> bool:
        return self.role == Role.ADMIN

    @property
    def is_doctor(self) -> bool:
        return self.role == Role.DOCTOR

    @property
    def is_patient(self) -> bool:
        return self.role == Role.USER

Der angemeldete Benutzer, wie sein Token ihn beschreibt (Beispiel 25). Dieses Objekt stammt nicht aus der Datenbank: Es wird bei jeder Anfrage aus dem Token rekonstruiert, dessen Signatur seinen Inhalt garantiert.

  • Zeilen 31–38: eine statische Methode ([@staticmethod]): eine in der Klasse definierte Methode, die weder ein Objekt noch eine Klasse als Argument erhält und mit [ConnectedUser.from_claims(claims)] aufgerufen wird. Sie konstruiert das Benutzerobjekt anhand der Claims eines bereits überprüften Tokens. Auch wenn es von uns signiert wurde, wird ein Token sorgfältig überprüft: Eine unbekannte Rolle, eine Kennung, die keine Zahl ist, oder ein fehlender Claim führen dazu, dass dem Benutzer der Zugriff verweigert wird ([None]). [Role.values] ist die Liste der Werte der Enumeration; [isdigit] prüft, ob eine Zeichenfolge nur aus Ziffern besteht. Die Annotation des Rückgabetyps steht in Anführungszeichen: Die Klasse ist an dieser Stelle noch nicht vollständig definiert;
  • Zeilen 40–50: drei Eigenschaften für Templates (Beispiel 26).

11.12.3. security/auth.py

# =========================================================================
# security/auth.py: die Logik der Authentifizierung:
#   - validate()         : prüft ein Paar aus Login und Passwort;
#   - set_token()        : erstellt das JWT-Token eines validierten Benutzers und
#                          legt es in einem Cookie der Antwort ab;
#   - user()             : der Benutzer, wie ihn ein Token beschreibt.
#
# Wo wird das JWT-Token transportiert? In einem COOKIE (siehe Beispiel 25): Ein Browser, der
# gewöhnliche HTML-Seiten anzeigt, sendet es so bei jeder Anfrage von selbst mit.
# 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 also nicht stehlen);
#   - SameSite=Lax: Der Browser sendet das Cookie NICHT mit einem POST, der von einer anderen
#     Site kommt (erster Schutz gegen den sogenannten CSRF-Angriff; der zweite ist
#     das Anti-CSRF-Token der Formulare);
#   - Secure: In der Produktion (HTTPS) wird das Cookie nie unverschlüsselt übertragen;
#   - Lebensdauer: Das Cookie verschwindet zugleich mit dem Ablauf des Tokens.
# =========================================================================

import time

import jwt
from django.conf import settings
from django.core.exceptions import ImproperlyConfigured

from dao.users import UserDao
from models.models import User

from . import passwords
from .connected_user import ConnectedUser

# der Name des Cookies, das das Token trägt
COOKIE = "rdvmedecins_jwt"

# HMAC-SHA256 erfordert einen Schlüssel von mindestens 256 Bit: Wir sagen das klar, sobald das
# Modul geladen wird, anstatt die Bibliothek später fehlschlagen zu lassen
if len(settings.JWT_SECRET) < 32:
    raise ImproperlyConfigured("JWT_SECRET must be at least 32 characters long (see .env).")

_users = UserDao()


# None, wenn das Login nicht existiert oder das Passwort falsch ist
def validate(login: str, password: str) -> User | None:
    user = _users.read_by_login(login)
    if user is None or not passwords.check_password(password, user.password):
        return None
    return user


# -------------------------------------------------------------------------
# das JWT-Token von [user], abgelegt in dem Cookie, das es transportiert. 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(response, user: User):
    now = int(time.time())
    duration = settings.JWT_DURATION_MINUTES * 60
    claims = {
        "sub": str(user.id),
        "login": user.login,
        "name": user.name,
        "role": user.role,
        "iat": now,
        "exp": now + duration,
    }
    token = jwt.encode(claims, settings.JWT_SECRET, algorithm="HS256")
    response.set_cookie(COOKIE, token, max_age=duration, secure=settings.COOKIE_SECURE,
                        httponly=True, samesite="Lax")
    return response


# löscht das Token-Cookie: Die Antwort trägt ein Cookie gleichen Namens, leer, bereits abgelaufen
def clear_token(response):
    response.delete_cookie(COOKIE, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# der Benutzer, wie ihn ein Token beschreibt; None, wenn das Token abgelaufen, gefälscht oder
# fehlerhaft ist. jwt.decode prüft die Signatur UND das Ablaufdatum (Claim exp).
# -------------------------------------------------------------------------
def user(token: str) -> ConnectedUser | None:
    try:
        claims = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
    except jwt.InvalidTokenError:
        return None
    return ConnectedUser.from_claims(claims)

Der Authentifizierungsservice aus Beispiel 25, mit einigen Unterschieden:

  • Zeilen 37–38: Der Schlüssel der Token wird beim Laden des Moduls geprüft, also beim Start der Anwendung: Ist der Schlüssel zu kurz, wird der Prozess vollständig beendet, mit einer klaren Fehlermeldung ([ImproperlyConfigured] ist die Ausnahme von [Django] für eine fehlerhafte Konfiguration), statt einer einfachen Warnung wie bei [PyJWT] (Beispiel 25);
  • Zeilen 44–48: Überprüfung eines Benutzernamens und eines Passworts durch die DAO-Schicht (das Konto, aus der Datenbank abgerufen) und durch das Passwortmodul. Die Web-Schicht ruft dieses Modul direkt auf: Authentifizierung ist eine Sicherheitsangelegenheit, keine Geschäftsregel;
  • Zeilen 57–71: das Token erzeugen und in einem Cookie der Antwort ablegen (Beispiel 25). Die ID des Kontos ([sub]) wird im Klartext geschrieben: Der JWT-Standard verlangt dies. Das Cookie ist in der Produktion [Secure] ([COOKIE_SECURE], siehe [config/settings.py]);
  • Zeilen 75–77: Löschen des Cookies: ein Cookie mit demselben Namen, leer und bereits abgelaufen (Beispiel 25);
  • Zeilen 84–89: Der Benutzer wird anhand eines Tokens identifiziert, oder [None] (Beispiel 25).

11.12.4. security/access.py

# =========================================================================
# security/access.py: DIE ZUGRIFFSREGEL jeder URL.
#
# Die Regeln werden der Reihe nach geprüft; die erste, deren Muster (ein
# regulärer Ausdruck) auf den Pfad der URL passt, gilt:
#   - einige ÖFFENTLICHE URLs: die Startseite, die Anmeldung, die Sprachauswahl, die
#     Erstellung eines Kontos;
#   - URLs, die bestimmten Rollen vorbehalten sind (eine Menge von Rollen: EINE davon genügt);
#   - alle ANDEREN erfordern einen authentifizierten Benutzer (letzte Regel).
# Es ist die Regel „alles ist verboten, außer was erlaubt ist“: Eine später hinzugefügte URL,
# die man zu schützen vergessen hat, ist automatisch geschützt.
#
# Die Middleware AccessControl (siehe security/middleware.py) wendet diese Regeln an: Ein
# abgelehnter anonymer Besucher wird auf die Anmeldeseite geleitet; ein
# authentifizierter Benutzer ohne die erforderliche Rolle erhält eine Fehlerseite 403.
# =========================================================================

import re

from models.models import Role

# zwei besondere Werte anstelle einer Menge von Rollen
PUBLIC = "PUBLIC"
AUTHENTICATED = "AUTHENTICATED"

# re.compile: der reguläre Ausdruck, einmalig geparst
RULES = [
    (re.compile(r"^/$"), PUBLIC),
    (re.compile(r"^/(login|logout)$"), PUBLIC),
    (re.compile(r"^/language/"), PUBLIC),
    (re.compile(r"^/register"), PUBLIC),
    # ein Patient storniert SEINEN Termin über „Mein Bereich“, nicht über den Terminkalender
    (re.compile(r"^/schedule/cancel$"), {Role.ADMIN, Role.DOCTOR}),
    (re.compile(r"^/(doctors|clients)"), {Role.ADMIN}),
    (re.compile(r"^/my-"), {Role.USER}),
    (re.compile(r"^/"), AUTHENTICATED),
]


# die Regel des Pfads [path]: PUBLIC, AUTHENTICATED oder eine Menge von Rollen
def rule(path: str):
    for pattern, requirement in RULES:
        if pattern.match(path):
            return requirement
    return AUTHENTICATED

Die Zugriffsregeln der Anwendung, in einer einzigen Liste zusammengefasst. Beispiel 26 schützte jeden View mit einem Dekorator; hier ist der Schutz zentralisiert, wie es die Regeln [access_control] von [Symfony] taten:

  • Zeilen 27–37: Jede Regel ordnet einem Muster (einem regulären Ausdruck, einmalig von [re.compile] kompiliert) eine Anforderung zu: [PUBLIC], [AUTHENTICATED] oder eine Menge von Rollen, von denen eine beliebige genügt. [^] markiert den Anfang des Pfads, [$] markiert sein Ende; [(login|logout)]: das eine oder das andere. Die öffentlichen URLs sind die Startseite, die Anmeldung, die Sprachauswahl und die Kontoerstellung. Es folgen die URLs, die bestimmten Rollen vorbehalten sind: die Stornierung aus dem Kalender (ein Patient storniert über „Mein Bereich“), die Verwaltung der Ärzte und Clients und das Konto des Patienten. Die letzte Regel, [^/], gilt für alle übrigen URLs und verlangt einen authentifizierten Benutzer;
  • Zeilen 41–45: die Pfadregel: die erste, die zutrifft ([match]: der am Anfang der Zeichenfolge erkannte Ausdruck).

Dies ist die Regel „alles ist verboten, außer was erlaubt ist“: Eine später hinzugefügte URL – bei der man vergessen haben könnte, sie zu schützen – ist automatisch geschützt. Der umgekehrte Fehler (eine öffentliche URL, die man vergessen hat öffentlich zu machen) fällt sofort auf; der Fehler einer vergessenen geschützten Seite fällt viel weniger auf.

11.12.5. security/middleware.py

# =========================================================================
# security/middleware.py: die beiden Sicherheits-Middlewares (siehe Beispiele 24 bis 26).
#
#   1. Authentication, VOR dem Routing: Wer ist der Benutzer? Anhand des
#      JWT-Tokens seines Cookies. Sie lehnt selbst nichts ab: Ein fehlendes oder
#      ungültiges Token lässt den Besucher ANONYM (request.user ist None); das
#      Cookie eines ungültigen Tokens wird in der Antwort gelöscht;
#   2. AccessControl, NACH dem Routing (process_view): Darf der Benutzer
#      auf diese URL zugreifen? Die Regeln stehen in security/access.py. Eine URL,
#      die keine Route hat, kommt gar nicht so weit: Sie erhält eine Seite 404.
# =========================================================================

from django.contrib import messages
from django.core.exceptions import PermissionDenied
from django.shortcuts import redirect
from django.utils.translation import gettext as _

from . import access, auth


class Authentication:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        token = request.COOKIES.get(auth.COOKIE, "")
        request.user = auth.user(token) if token else None
        response = self.get_response(request)
        # ein ungültiges Token (abgelaufen, gefälscht): Das Cookie wird in der Antwort gelöscht
        # was auch immer es ist - es sei denn, die Anfrage hat gerade ein neues gesetzt (eine
        # erfolgreiche Anmeldung)
        if token and request.user is None and auth.COOKIE not in response.cookies:
            auth.clear_token(response)
        return response


class AccessControl:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    def process_view(self, request, view_func, view_args, view_kwargs):
        # path_info: der Pfad der URL, ohne ihre Parameter
        requirement = access.rule(request.path_info)
        if requirement == access.PUBLIC:
            return None
        user = request.user
        if user is None:
            # ein anonymer Besucher: ab zur Anmeldeseite. Hatte er ein
            # Token-Cookie, bedeutet das, dass sein Token nicht mehr gültig ist (abgelaufen,
            # gefälscht): Seine Sitzung ist abgelaufen, das teilen wir ihm mit
            if auth.COOKIE in request.COOKIES:
                messages.error(request, _("Your session has expired: please log in again."))
            return redirect("login")
        if requirement != access.AUTHENTICATED and user.role not in requirement:
            # authentifiziert, aber ohne die erforderliche Rolle: Fehler 403 (View handler403, siehe config/urls.py)
            raise PermissionDenied("insufficient role")
        return None

Die beiden Sicherheits-Middleware-Komponenten:

  • Zeilen 21–34: die Authentifizierung (Beispiel 25), vor dem Routing. Sie lehnt nichts ab: Ein fehlendes oder ungültiges Token lässt den Besucher anonym. Das zu einem ungültigen Token gehörende Cookie löscht sie in der Antwort, unabhängig davon, wie diese Antwort aussieht, es sei denn, die Antwort setzt ein neues (eine erfolgreiche Anmeldung): [response.cookies] ist das Dictionary der Cookies, die die Antwort setzt;
  • Zeilen 37–60: die Zugriffskontrolle, nach dem Routing (ihre Methode [process_view], Beispiel 24). Eine URL ohne Route kommt daher nicht bis hierher: Sie erhält direkt eine Seite 404, ohne dass der Besucher zur Anmeldung aufgefordert wird. [request.path_info] ist der Pfad der URL ohne ihre Parameter. Ein anonymer Besucher, dem der Zugriff verweigert wird, wird zur Anmeldeseite geleitet; hatte er ein Token-Cookie, bedeutet das, dass sein Token nicht mehr gültig ist: Eine Popup-Meldung informiert ihn, dass seine Sitzung abgelaufen ist (siehe den Screenshot mit dem Titel „Sitzungsende“). Ein authentifizierter Benutzer ohne die erforderliche Rolle löst [PermissionDenied] aus: Da die Ausnahme in [process_view] – nicht im View – ausgelöst wird, wandelt [Django] sie selbst über den View [handler403] der Anwendung in eine Antwort um (Beispiel 24), sowohl im Debug- als auch im Produktionsmodus.

Die Meldung wird von [gettext] (Zeile 16) übersetzt, nicht von [gettext_lazy]: Sie wird während der Anfrage in deren Sprache übersetzt; die verzögerte Übersetzung ist nur für Text nützlich, der beim Laden eines Moduls definiert wird.

11.12.6. security/errors.py

1
2
3
4
5
6
7
8
# security/errors.py: Das Token ist gültig, aber das Konto, das es bezeichnet, 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: Die
# Middleware ErrorPage löscht das Cookie und leitet auf die Anmeldeseite um.


class InvalidSession(Exception):
    pass

Ein 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). Views, die das Konto benötigen, lösen dann diese Ausnahme aus, die die Middleware [ErrorPage] wie eine abgelaufene Sitzung behandelt (siehe unten).

11.12.7. security/captchas.py und captcha_drawing.py

# =========================================================================
# security/captchas.py: ein CAPTCHA („Test zur Unterscheidung von Mensch und Roboter“),
# vom Server selbst erzeugt, ohne externen Dienst (siehe Beispiel 27).
#
# So funktioniert es:
#   1. generate() zieht einen zufälligen Text, erzeugt daraus ein Bild und speichert die richtige
#      Antwort IM CACHE 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, input) 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.
#
# Warum der Cache und nicht einfach eine Variable des Moduls? Weil ein Produktionsserver
# MEHRERE Prozesse startet (siehe README.md), die ihren Speicher nicht teilen: Die Anfrage,
# die das Captcha prüft, wird nicht unbedingt von dem Prozess bearbeitet, der es erzeugt hat.
# Prozess bearbeitet, der es erzeugt hat. Der Cache der Anwendung (Dateien, siehe
# config/settings.py) wird dagegen von allen Prozessen geteilt.
# =========================================================================

import secrets
from dataclasses import dataclass

from django.core.cache import cache

from . import captcha_drawing

# Gültigkeitsdauer eines Bildes in Sekunden: 10 Minuten zum Ausfüllen des Formulars
LIFETIME = 600


# ein Captcha: seine Kennung, die in das versteckte Feld [captcha_id] des
# Formulars gehört, und sein Bild (SVG), das unverändert in die Seite eingefügt wird
@dataclass(frozen=True)
class Captcha:
    id: str
    svg: str


def generate() -> Captcha:
    text = captcha_drawing.random_text(5)        # 5 Zeichen
    id = secrets.token_hex(12)                     # eine nicht erratbare Kennung
    # der Cache vergisst die Antwort nach 10 Minuten von selbst
    cache.set(f"captcha.{id}", text, LIFETIME)
    return Captcha(id, captcha_drawing.svg(text))


# true, wenn [answer] die richtige Antwort auf das Captcha [id] ist (unabhängig von
# Groß-/Kleinschreibung). Das Captcha wird in jedem Fall verbraucht.
def verify(id: str, answer: str) -> bool:
    # die Kennung stammt vom Browser: 24 Hexadezimalziffern oder nichts
    if len(id) != 24 or any(c not in "0123456789abcdef" for c in id) or not answer:
        return False
    expected = cache.get(f"captcha.{id}")
    # delete gibt True zurück, wenn das Element existierte: Reichen zwei Anfragen im selben
    # Moment dasselbe Captcha ein, löscht nur eine es wirklich - die andere scheitert
    if expected is None or not cache.delete(f"captcha.{id}"):
        return False
    return expected.casefold() == answer.strip().casefold()

Der CAPTCHA-Service aus Beispiel 27, mit zwei zusätzlichen Vorsichtsmaßnahmen:

  • Zeilen 51–52: Die Kennung stammt vom Browser; wir prüfen, ob sie aus 24 Hexadezimalziffern besteht (denen von [token_hex(12)]), bevor wir sie als Cache-Schlüssel verwenden. [any] liefert [True] , wenn eines der vom Generatorausdruck erzeugten Elemente wahr ist;
  • Zeilen 53–56: [cache.delete] liefert [True] , wenn das Element existierte. Legen zwei Anfragen gleichzeitig dasselbe CAPTCHA vor, entfernt es nur eine tatsächlich; die andere schlägt fehl. Ein Bild wird nur einmal verwendet.

Der Kommentar der Datei (Zeilen 17–22) erklärt, warum die CAPTCHAs im Cache (einer Menge von Dateien, die alle Serverprozesse gemeinsam nutzen) statt in einer Modulvariablen gespeichert werden. Die Datei [security/captcha_drawing.py] ist die aus Beispiel 27, mit einem längeren Kopfkommentar: Jedes Zeichen wird mit Linien gezeichnet, nie als Text geschrieben, da ein Bot sonst einfach den Quellcode des Bildes lesen müsste.

11.12.8. security/limiter.py

# =========================================================================
# security/limiter.py: zweite Hürde gegen Roboter (die erste ist das
# Captcha): Versuche werden GEZÄHLT, und ab einem Schwellenwert werden sie eine
# Zeit lang BLOCKIERT (siehe Beispiel 27).
#
#   - Login: Nach LOGIN_MAX_FAILURES Fehlversuchen (falsches Captcha oder falsches
#     Passwort) für dasselbe Login von derselben IP-Adresse wird dieses Paar
#     bis zum Ende eines Zeitfensters von LOGIN_BLOCK_MINUTES Minuten blockiert, gerechnet ab
#     dem ersten Fehlversuch. Dieselbe IP-Adresse wird auch blockiert, wenn sie
#     LOGIN_MAX_FAILURES_IP 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 Anmeldesperre zuerst für das
# Paar (IP, Login) - ein Student, der sich beim Passwort vertippt, blockiert nicht seine
# Nachbarn - und deshalb sind die Schwellenwerte konfigurierbar (Datei .env).
#
# Jeder Zähler wird im Cache gespeichert (siehe security/captchas.py), zusammen mit dem Ende
# seines Zeitfensters: {"count": 3, "end": 1790531419.2}.
# =========================================================================

import hashlib
import math
import time

from django.conf import settings
from django.core.cache import cache


# ──────────────────────────────────────────────── Login
# Anzahl der verbleibenden Sperrminuten (0 = der Versuch ist erlaubt)
def login_block_minutes(ip: str, login: str) -> int:
    return max(_remaining_minutes(_login_key(ip, login), settings.LOGIN_MAX_FAILURES),
               _remaining_minutes(f"login_ip.{ip}", settings.LOGIN_MAX_FAILURES_IP))


# ein weiterer Fehlversuch; der erste öffnet ein Zeitfenster von LOGIN_BLOCK_MINUTES Minuten,
# an dessen Ende der Zähler wieder bei null beginnt
def login_failure(ip: str, login: str) -> None:
    duration = settings.LOGIN_BLOCK_MINUTES * 60
    _count(_login_key(ip, login), duration)
    _count(f"login_ip.{ip}", duration)


# eine erfolgreiche Anmeldung setzt den Zähler DIESES Logins zurück
def login_success(ip: str, login: str) -> None:
    cache.delete(_login_key(ip, login))


# ──────────────────────────────────────────────── Registrierung
def registration_block_minutes(ip: str) -> int:
    return _remaining_minutes(f"registration.{ip}", settings.REGISTRATION_MAX_PER_HOUR)


def registration_success(ip: str) -> None:
    _count(f"registration.{ip}", 3600)


# ──────────────────────────────────────────────── gemeinsame Mechanik
# der Schlüssel des Paars (IP, Login). Das Login kommt vom Browser: Es kann
# beliebige Zeichen enthalten (Leerzeichen ...). Sein SHA-256-Fingerabdruck aus 64 Hexadezimal-
# ziffern ergibt einen Cache-Schlüssel, der immer gültig ist
def _login_key(ip: str, login: str) -> str:
    fingerprint = hashlib.sha256(f"{ip}|{login.strip().lower()}".encode()).hexdigest()
    return f"login.{fingerprint}"


# die Minuten bis zum Ende des Zeitfensters, wenn der Zähler die
# Grenze erreicht hat, sonst 0; die Sekunden werden auf die Minute AUFGERUNDET (ceil):
# 30 s -> "1 minute"
def _remaining_minutes(key: str, limit: int) -> int:
    state = cache.get(key)
    if state is None or state["count"] < limit:
        return 0
    return max(1, math.ceil((state["end"] - time.time()) / 60))


# ein weiterer Versuch im aktuellen Zeitfenster (oder in einem neuen Zeitfenster von
# [duration] Sekunden). Der Cache vergisst den Zähler am Ende des Zeitfensters (timeout).
# Das Lesen und anschließende Schreiben sind nicht ATOMAR: Zwei gleichzeitige Versuche
# könnten nur als einer zählen. Bei einem Fehlversuchszähler spielt das keine Rolle
def _count(key: str, duration: int) -> None:
    state = cache.get(key) or {"count": 0, "end": time.time() + duration}
    state["count"] += 1
    cache.set(key, state, timeout=max(1, math.ceil(state["end"] - time.time())))

Die Versuchsbegrenzung aus Beispiel 27, verfeinert:

  • Zeilen 34–49: die Anmeldung. Fehlgeschlagene Versuche werden pro Paar (IP-Adresse, Benutzername) gezählt: Fünf fehlgeschlagene Versuche (Einstellung [LOGIN_MAX_FAILURES]) sperren diesen Benutzernamen von dieser Adresse aus für fünfzehn Minuten, ab dem ersten fehlgeschlagenen Versuch. In einem Klassenraum, in dem oft alle Computer über dieselbe IP-Adresse auf das Internet zugreifen, sperrt ein Schüler, der ein falsches Passwort eingibt, seine Nachbarn nicht. Dieselbe Adresse wird jedoch auch gesperrt, wenn sie über alle Logins hinweg 25 fehlgeschlagene Versuche ansammelt: So verhält sich ein Bot, der Tausende verschiedener Logins ausprobiert. Eine erfolgreiche Anmeldung löscht die fehlgeschlagenen Versuche für dieses Login;
  • Zeilen 53–58: die Kontoerstellung: höchstens zehn Konten pro Stunde und IP-Adresse;
  • Zeilen 65–67: der Schlüssel des Paares (IP, Login). Das Login stammt vom Browser: Es kann beliebigen Inhalt haben. Sein SHA-256-Fingerabdruck ([hashlib.sha256], aus der Standardbibliothek) aus 64 Hexadezimalziffern ergibt einen Cache-Schlüssel, der immer gültig ist und eine feste Länge hat;
  • Zeilen 73–77: die verbleibenden Minuten der Sperre, auf die nächste Minute aufgerundet ([math.ceil]: 30 Sekunden ergeben „1 Minute“);
  • Zeilen 84–87: der Zähler innerhalb eines festen Zeitfensters (Beispiel 27). [cache.get(key) or {...}]: der aktuelle Zustand oder ein neuer Zustand. Der Code-Kommentar räumt die Schwäche aus Beispiel 27 ein (zwei gleichzeitige Fehlschläge werden möglicherweise nur als einer gezählt); für einen Fehlerzähler ist das kein ernstes Problem.

11.12.9. security/registration_pass.py

# =========================================================================
# security/registration_pass.py: der „Pass“ für die Kontoerstellung.
#
# Um die Seite „Patientenkonto erstellen“ zu öffnen, muss zuvor das Captcha der Anmeldeseite
# eingegeben worden sein (siehe web/views/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 (Zeit zum Ausfüllen des Formulars, auch nach mehreren
#     Versuchen infolge von 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 auf die
# Anmeldeseite um (siehe den Dekorator @registration_pass_required): Die direkte Eingabe
# der URL /register umgeht das Captcha nicht.
#
# Wie die Captchas leben auch die Pässe im Cache.
# =========================================================================

import secrets
from functools import wraps

from django.conf import settings
from django.contrib import messages
from django.core.cache import cache
from django.shortcuts import redirect
from django.utils.translation import gettext as _

COOKIE = "rdvmedecins_registration"
# das Cookie wird vom Browser nur an die Adressen /register... gesendet
PATH = "/register"
# Lebensdauer eines Passes, in Minuten
LIFETIME = 15


# stellt einen neuen Pass aus, in einem Cookie der Antwort
def issue(response):
    id = secrets.token_hex(12)
    cache.set(f"pass.{id}", True, LIFETIME * 60)
    response.set_cookie(COOKIE, id, max_age=LIFETIME * 60, path=PATH,
                        secure=settings.COOKIE_SECURE, httponly=True, samesite="Lax")
    return response


# true, wenn [id] ein vorhandener, nicht abgelaufener Pass ist
def is_valid(id: str | None) -> bool:
    return bool(id) and id.isalnum() and cache.get(f"pass.{id}") is not None


# der Pass wurde verwendet: Er wird vergessen ...
def consume(id: str | None) -> None:
    if id and id.isalnum():
        cache.delete(f"pass.{id}")


# ... und sein Cookie wird durch ein Cookie gleichen Namens und gleichen Pfads, bereits abgelaufen, gelöscht
def clear_cookie(response):
    response.delete_cookie(COOKIE, path=PATH, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# @registration_pass_required: ein Dekorator (siehe Beispiel 26), der auf die Views gesetzt wird,
# die einen Pass erfordern (GET und POST /register). Ohne gültigen Pass
# wird die View nicht aufgerufen: Es geht zurück zur Anmeldeseite, mit einer Meldung
# -------------------------------------------------------------------------
def registration_pass_required(view):
    @wraps(view)
    def wrapper(request, *args, **kwargs):
        if not is_valid(request.COOKIES.get(COOKIE)):
            messages.error(request, _("To create an account, first type the characters shown in the image "
                                      "correctly, then click \"Create a patient account\"."))
            return redirect("login")
        return view(request, *args, **kwargs)
    return wrapper

Der Pass zur Kontoerstellung. Um ein Konto zu erstellen, müssen Sie zuerst das CAPTCHA der Anmeldeseite eingeben (die Schaltfläche „Ein Patientenkonto erstellen“): Der Server stellt dann einen Pass aus, eine zufällige Kennung, die im Cache und in einem Cookie gespeichert wird. Ohne Pass leitet die Seite zur Kontoerstellung auf die Anmeldeseite um: Die direkte Eingabe der URL [/register] umgeht das CAPTCHA nicht; und ein Pass dient nur zur Erstellung eines Kontos: Ein Bot kann keine Konten massenhaft erstellen.

  • Zeilen 29–33: Das Cookie wird vom Browser nur an Adressen gesendet, die mit [/register] beginnen (Cookie-Parameter [path]): Es wird bei anderen Anfragen nicht mitgesendet;
  • Zeilen 37–42: Das Cookie wird für fünfzehn Minuten ausgestellt – genug Zeit, um das Formular auszufüllen, selbst wenn man es nach Eingabefehlern mehrmals versuchen muss;
  • Zeilen 46–59: Überprüfung, Verwendung und Löschung des Cookies (das denselben Pfad haben muss wie das zu löschende Cookie). [isalnum] prüft, ob die Kennung nur aus Buchstaben und Ziffern besteht;
  • Zeilen 67–75: der Dekorator [@registration_pass_required] (Beispiel 26), angewendet auf den View zur Kontoerstellung.

11.13. Die Web-Schicht: gemeinsame Services

Der Ordner [web] enthält die [Django]-Anwendung der Web-Schicht (deklariert in [INSTALLED_APPS]; siehe [config/settings.py]; ihre Datei [web/apps.py] enthält nur ihren Namen). Sie vereint die Routen, Views, Formulare und das, was allen Views gemeinsam ist: Darauf konzentriert sich dieser Abschnitt.

11.13.1. web/application.py

# =========================================================================
# web/application.py: der Cache / die Fassade der Geschäftsschicht (das Äquivalent der
# Klasse [ApplicationModel] der anderen Versionen der Anwendung): Die Listen der
# Ärzte und Clients werden einmal aus der Datenbank gelesen und dann aus dem Cache bereitgestellt.
#
# Warum der Django-CACHE und nicht einfach ein Attribut dieses Objekts? Ein
# Python-Prozess behält seine Objekte von einer Anfrage zur nächsten (siehe Beispiel 20);
# aber ein Produktionsserver startet MEHRERE Prozesse, von denen jeder SEINE
# Kopie der Listen hätte: Der ADMIN, der einen Arzt hinzufügt, würde nur die Liste des
# Prozesses aktualisieren, der seine Anfrage bearbeitet hat. Der Cache der Anwendung (Dateien, siehe
# config/settings.py) wird dagegen von allen Prozessen geteilt.
#
# Diese Listen können sich ÄNDERN (der ADMIN fügt Ärzte und
# Clients hinzu, aktualisiert und löscht sie): Jeder Schreibvorgang läuft daher über diese Fassade, die die
# betroffene Liste direkt danach VERGISST; die nächste Anfrage, die sie braucht, liest sie erneut aus der Datenbank. Genau
# darin liegt der Sinn eines EINZIGEN Einstiegspunkts in die Geschäftsschicht: Die Regel
# „Schreiben => Cache aktualisieren“ steht nur hier.
# =========================================================================

from datetime import date
from functools import cache as once

from django.core.cache import cache

from domain.schedule import DoctorDaySchedule
from business.person_data import PersonData
from business.provider import business
from business.business import Business
from models.models import Appointment, Client, Doctor, Slot

DOCTORS = "rdvmedecins.doctors"
CLIENTS = "rdvmedecins.clients"


# derselbe Vertrag wie die Geschäftsschicht
class ApplicationModel(Business):
    def __init__(self):
        self.business = business()

    # ──────────────────────────────────────────────── Lesezugriffe aus dem Cache
    # get_or_set(key, function, timeout): der Wert aus dem Cache, wenn er existiert; andernfalls
    # wird die Funktion aufgerufen und ihr Ergebnis im Cache gespeichert (timeout=None:
    # ohne Zeitbegrenzung), bevor es zurückgegeben wird. Die Objekte werden dort serialisiert gespeichert
    # (Modul pickle): Jede Anfrage, die sie liest, erhält Kopien davon
    def get_all_doctors(self) -> list[Doctor]:
        return cache.get_or_set(DOCTORS, self.business.get_all_doctors, timeout=None)

    def get_all_clients(self) -> list[Client]:
        return cache.get_or_set(CLIENTS, self.business.get_all_clients, timeout=None)

    # der Arzt, dessen Benutzerkonto [user_id] ist - dient dazu, für einen angemeldeten Arzt
    # seinen eigenen Terminkalender vorauszuwählen
    def get_doctor_by_user_id(self, user_id: int) -> Doctor | None:
        return next((d for d in self.get_all_doctors() if d.account_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)

    # kein Cache hier: Es zählen die aktuellsten Daten (ein Patient, der
    # gerade sein Konto aktualisiert 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 => Cache vergessen
    # (delete: das Element wird aus dem Cache entfernt)
    def add_doctor(self, data: PersonData) -> Doctor:
        doctor = self.business.add_doctor(data)
        cache.delete(DOCTORS)
        return doctor

    def edit_doctor(self, id: int, data: PersonData) -> Doctor:
        doctor = self.business.edit_doctor(id, data)
        cache.delete(DOCTORS)
        return doctor

    def delete_doctor(self, id: int) -> None:
        self.business.delete_doctor(id)
        cache.delete(DOCTORS)

    def add_client(self, data: PersonData) -> Client:
        client = self.business.add_client(data)
        cache.delete(CLIENTS)
        return client

    def edit_client(self, id: int, data: PersonData) -> Client:
        client = self.business.edit_client(id, data)
        cache.delete(CLIENTS)
        return client

    def delete_client(self, id: int) -> None:
        self.business.delete_client(id)
        cache.delete(CLIENTS)


# der Provider der Fassade: ein einziges, gemeinsam genutztes Objekt (siehe business/provider.py)
@once
def application() -> ApplicationModel:
    return ApplicationModel()

Alle Versionen der Anwendung haben eine Klasse [ApplicationModel]: einen einzigen Einstiegspunkt von der Web-Schicht zur Geschäftsschicht, der die Listen der Ärzte und Clients im Speicher hält. Diese Listen werden von fast allen Seiten angefordert (die Dropdown-Liste der Ärzte im Kalender, die Liste der Patienten im Buchungsfenster, die Administrationsseiten) und ändern sich selten.

Ein [Python]-Prozess behält seine Objekte von einer Anfrage zur nächsten (Beispiel 20): Die [Flask]-Version speicherte diese Listen daher einfach in den Attributen eines einzigen Objekts. Der Kopfkommentar erklärt, warum diese Version sie stattdessen im Cache von [Django] ablegt (Beispiel 20): Ein Produktionsserver führt mehrere Prozesse aus, und jeder hätte seine eigene Kopie der Listen.

  • Zeile 36: Die Klasse erbt den Vertrag [Business], genau wie [BusinessService]: Die Views rufen dieselben Methoden auf, unabhängig davon, welche Klasse sie bedient;
  • Zeilen 45–49: [get_or_set(key, function, timeout)] liefert den unter diesem Schlüssel gespeicherten Wert; existiert er nicht, ruft es die Funktion auf (hier eine gebundene Methode der Geschäftsschicht, ohne Klammern übergeben, die die Liste aus der Datenbank liest), speichert ihr Ergebnis unbefristet im Cache ([timeout=None]) und gibt es zurück. Die erste Anfrage, die die Liste benötigt, liest sie aus der Datenbank; die folgenden Anfragen finden sie im Cache. Der Cache speichert die Liste, serialisiert vom Modul [pickle] (Beispiel 20), und rekonstruiert sie beim Abruf samt den bereits geladenen Beziehungen: dem Konto jeder Person, das über den Join [select_related("account")] aus der DAO-Schicht abgerufen wurde. Die rekonstruierten Objekte sind Kopien: Sie dienen der Anzeige, nie dem Schreiben (die Geschäftsschicht liest, was sie ändert, immer erneut aus der Datenbank);
  • Zeilen 53–54: der einem Konto zugeordnete Arzt, aus der Cache-Liste abgerufen. [next(generator, None)] liefert das erste vom Generatorausdruck erzeugte Element oder [None] , wenn es keines gibt (Beispiel 06);
  • Zeilen 57–90: Die übrigen Methoden des Vertrags delegieren einfach an die Geschäftsschicht. Der Client eines Kontos ([get_client_by_user_id]) wird immer aus der Datenbank abgerufen, nicht aus dem Cache: Es kommt auf die aktuellsten Daten an (ein Patient, der sein Konto gerade geändert oder gelöscht hat);
  • Zeilen 94–120: die Änderungen. Jeder Schreibvorgang für einen Arzt oder Client leert die betreffende Liste ([delete]): Die nächste Abfrage, die sie benötigt, liest sie erneut aus der Datenbank. Das ist der Sinn eines einzigen Einstiegspunkts: Die Regel „ein Schreibvorgang aktualisiert den Cache“ ist nur hier umgesetzt. Schlägt der Schreibvorgang fehl (ein [BusinessError]), verlässt die Ausnahme die Methode vor dem [delete]: Die Liste wird nicht überschrieben; sie hat sich nicht geändert. Eine Anwendung, die über einen anderen Weg in die Datenbank schreibt (ein anderes Programm, eine andere Version der Anwendung mit derselben Datenbank), würde den Cache veraltet zurücklassen: In diesem Fall würde es genügen, den Ordner [var/cache] zu leeren;
  • Zeilen 124–126: der Provider der Fassade, dem Provider der Geschäftsschicht nachempfunden: ein einziges Objekt, bei der ersten Anfrage erzeugt. [functools.cache], unter dem Namen [once] importiert, speichert das Ergebnis einer Funktion (Beispiel 06): Die Funktion [application()] wird nur einmal ausgeführt und gibt danach immer dasselbe Objekt zurück.

11.13.2. web/utils.py

# =========================================================================
# web/utils.py: kleine Hilfsfunktionen der Web-Schicht:
#   - Datumsangaben: „yyyy-mm-dd“, Tage wie „Wednesday 23 September 2026“;
#   - Eingabe: Lesen einer positiven ganzen Zahl und eines vom Browser gesendeten Datums;
#   - Benutzer: der angemeldete Benutzer und sein Patient (Modell Client).
# =========================================================================

import re
from datetime import date, datetime

from django.utils import dateformat

from models.models import Client
from security.errors import InvalidSession
from security.connected_user import ConnectedUser

from .application import application


# ──────────────────────────────────────────────── Datumsangaben
# das Datum, wenn [text] ein existierendes Datum im Format yyyy-mm-dd ist; sonst None.
# strptime lehnt nicht existierende Daten ab ("2026-02-30")
def valid_date(text: str | None) -> date | None:
    if text is None or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", text):
        return None
    try:
        return datetime.strptime(text, "%Y-%m-%d").date()
    except ValueError:
        return None


# "2026-09-23"
def iso(day: date) -> str:
    return day.isoformat()


# „Wednesday 23 September 2026“ / „mercredi 23 septembre 2026“, in der aktiven
# Sprache (siehe web/middleware.py). dateformat.format formatiert ein Datum wie der
# Filter date der Templates: l den Wochentag ausgeschrieben, j den Tag,
# F den Monat ausgeschrieben, Y das Jahr; die Namen werden von Django übersetzt
def format_day(day: date) -> str:
    return dateformat.format(day, "l j F Y")


# ──────────────────────────────────────────────── 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. Die geschützten Views werden nur aufgerufen, wenn er existiert (siehe
# security/middleware.py); vorsichtshalber wird sein Fehlen wie eine
# abgelaufene Sitzung behandelt
def user(request) -> ConnectedUser:
    if request.user is None:
        raise InvalidSession()
    return request.user


# -------------------------------------------------------------------------
# Der Patient (Modell Client), der dem angemeldeten Benutzer entspricht.
#
# Das JWT-Token enthält nur die id des KONTOS (users.id). Für die 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: Das wird wie eine abgelaufene Sitzung behandelt.
# -------------------------------------------------------------------------
def connected_patient(request) -> Client:
    client = application().get_client_by_user_id(user(request).user_id)
    if client is None:
        raise InvalidSession()
    return client


# die IP-Adresse des Clients
def ip(request) -> str:
    return request.META.get("REMOTE_ADDR", "")

Einige Hilfsfunktionen, die alle Views benötigen:

  • Zeilen 23–29: das Datum eines Parameters [yyyy-mm-dd] oder [None]. Zwei Prüfungen: das Format (ein regulärer Ausdruck; [fullmatch] verlangt, dass die gesamte Zeichenfolge passt), dann die Existenz des Datums: [strptime] löst für den 30. Februar eine [ValueError] aus;
  • Zeilen 41–42: „Wednesday 23 September 2026“ oder „mercredi 23 septembre 2026“, je nach Sprache der Anfrage. [dateformat.format] formatiert ein Datum wie der Filter [date] in den Templates (Beispiel 16) mit denselben Codes; die Namen der Tage und Monate werden von [Django] selbst in der aktiven Sprache übersetzt;
  • Zeilen 47–51: Ein Abfrageparameter ist eine Zeichenfolge oder [None]. Es werden nur Ziffern akzeptiert (bis zu neun: eine vernünftige Zahl, die die Datenbank akzeptiert), und die Zahl muss strikt positiv sein;
  • Zeilen 58–61: der angemeldete Benutzer, von der Middleware [Authentication] ermittelt. Geschützte Views werden nur für einen authentifizierten Benutzer aufgerufen (Zugriffskontrolle), aber das Fehlen eines Benutzers wird dennoch wie eine abgelaufene Sitzung behandelt;
  • Zeilen 73–77: der Patient ([Client]), der dem angemeldeten Benutzer zugeordnet ist. Das Token enthält nur die ID des Kontos; der Client wird über die Spalte [clients.user] identifiziert. Existiert er nicht, wurde das Konto seit der Anmeldung des Benutzers gelöscht: [InvalidSession] (die Middleware [ErrorPage], siehe später);
  • Zeilen 81–82: die Adresse (IP) des Clients für die Versuchsbegrenzung. [REMOTE_ADDR] ist die Adresse des Rechners, der die Verbindung hergestellt hat. Hinter einem Reverse-Proxy (siehe „Ein Produktionsserver“) wäre dies immer die Adresse des Proxys: Man müsste dann den Header lesen, den er hinzufügt ([X-Forwarded-For]), und zwar nur den, den er hinzufügt, da der Browser beliebige Header senden kann.

11.13.3. web/contexts.py

# =========================================================================
# web/contexts.py: ein Context Processor (siehe Beispiel 15): die Variablen, die
# ALLE Seiten brauchen:
#   - user: der angemeldete Benutzer (oder None), für die Navigationsleiste;
#   - menu: die Einträge des Menüs der Navigationsleiste, die von der Rolle abhängen.
#
# Das Menü wird HIER in Python berechnet und nicht im Template: „Ärzte“ und
# „Patienten“ erscheinen nur für den ADMIN. Das ist nur eine Anzeigeerleichterung: Der
# eigentliche Schutz sind die Zugriffsregeln (ein USER, der /doctors von
# Hand eintippt, erhält eine Seite 403).
# =========================================================================

from dataclasses import dataclass

from django.urls import reverse
from django.utils.translation import gettext_lazy as _

from security import auth


# ein Menüeintrag: seine URL, seine Beschriftung und ob es der Eintrag der aktuellen Seite ist
@dataclass(frozen=True)
class MenuEntry:
    url: str
    label: str
    active: bool


def user(request):
    # der von der Middleware Authentication ermittelte Benutzer. Vorsichtshalber wird er, falls er
    # fehlt (eine Fehlerseite aufgrund eines Fehlers, der vor dieser Middleware auftrat), direkt
    # aus dem Token gelesen, damit die Navigationsleiste vollständig ist
    connected = getattr(request, "user", None)
    if connected is None and request.COOKIES.get(auth.COOKIE):
        connected = auth.user(request.COOKIES[auth.COOKIE])
    return {"user": connected, "menu": menu(request, connected)}


# die Menüeinträge: (Name der Route, Beschriftung, Präfixe der Pfade, für
# die der Eintrag aktiv ist)
def menu(request, connected):
    if connected is None:
        return []
    entries = []
    if connected.is_patient:
        # aktiv für /my-area UND /my-account
        entries.append(("area", _("My area"), ["/my-"]))
    entries.append(("schedule", _("Schedule"), ["/schedule"]))
    if connected.is_admin:
        entries.append(("doctors_list", _("Doctors"), ["/doctors"]))
        entries.append(("clients_list", _("Patients"), ["/clients"]))
    # any: true, wenn eines der Präfixe passt
    return [MenuEntry(reverse(route), label, any(request.path.startswith(p) for p in prefixes))
            for route, label, prefixes in entries]

Ein Context-Prozessor (Beispiel 15), deklariert in [config/settings.py]: die Variablen, die alle Seiten benötigen, im Kontext aller Templates:

  • [user]: der angemeldete Benutzer oder [None] für die Navigationsleiste. Normalerweise stammt er aus der [Authentication]-Middleware; [getattr(object, name, default)] liest ein Attribut oder liefert den Standardwert, falls es nicht existiert. Vorsichtshalber wird der Benutzer, falls er fehlt, direkt aus dem Token gelesen (Zeilen 34–35);
  • [menu]: die Menüeinträge der Navigationsleiste, die von der Rolle abhängen (Zeilen 41–54). Jeder Eintrag ist ein Objekt [MenuEntry] (eine Datenklasse, Zeilen 22–26): die URL (erzeugt von [reverse], Beispiel 04), die übersetzte Beschriftung und die Kennzeichnung des aktiven Eintrags – desjenigen der aktuell angezeigten Seite –, den das Template hervorhebt. Der Eintrag [My area] ist für alle URLs aktiv, die mit [/my-] beginnen: [/my-area] und [/my-account].

Das Menü wird in [Python] berechnet, nicht im Template (in den Templates gibt es keine Logik; dazu später mehr). Das Ausblenden der Einträge „Ärzte“ und „Patienten“ ist lediglich eine Anzeigehilfe: Der eigentliche Schutz stammt aus den Zugriffsregeln.

11.13.4. web/templatetags/rdv.py

# =========================================================================
# web/templatetags/rdv.py: die Tags unserer Templates (siehe Beispiel 16), geladen
# durch {% load rdv %}.
#
#   {% success_zone %}: die Flash-Meldungen zum ERFOLG, oben auf der Seite;
#   {% error_zone %}: der Fehlerbereich, UNTEN auf jeder Seite, auf hellrosa
#   Hintergrund. Er sammelt die drei möglichen Fehlerquellen:
#     - [error]: der Fehler der angezeigten Seite (ungültiges Datum, falsch eingegebenes Captcha,
#       Login bereits vergeben ...), von der View weitergereicht;
#     - die Flash-Fehlermeldungen, die die vorherige View vor einer
#       Weiterleitung hinterlassen hat (Zeitfenster bereits gebucht, Löschen abgelehnt ...);
#     - die Eingabefehler eines ungültigen Formulars (siehe Beispiel 19): Ihre
#       Meldungen werden UNTER den Feldern angezeigt; hier steht, wenn es keine andere
#       Meldung gibt, ein einfacher Satz „The form contains errors.“.
# =========================================================================

from django import template
from django.contrib import messages as flash
from django.utils.translation import gettext as _

register = template.Library()


# takes_context: Die Funktion erhält den Kontext des Templates, das sie aufruft; messages:
# die Variable des Context Processors der Flash-Meldungen; level: die Stufe einer Meldung
@register.inclusion_tag("fragments/success.html", takes_context=True)
def success_zone(context):
    return {"texts": [m.message for m in context.get("messages", []) if m.level == flash.SUCCESS]}


@register.inclusion_tag("fragments/errors.html", takes_context=True)
def error_zone(context):
    texts = [m.message for m in context.get("messages", []) if m.level == flash.ERROR]
    if context.get("error"):
        texts.insert(0, context["error"])
    form = context.get("form")
    # ein GEBUNDENES (gesendetes) und ungültiges Formular, ohne weitere Meldung
    if not texts and form is not None and form.is_bound and form.errors:
        texts.append(_("The form contains errors."))
    return {"texts": texts}

Zwei Inclusion-Tags (Beispiel 16), die von [{% load rdv %}] in die Templates geladen werden. Jedes rendert ein kleines Template (ein Fragment, später beschrieben) mit den Variablen, die die Funktion zurückgibt:

  • Zeilen 26–28: [{% success_zone %}]: Flash-Erfolgsmeldungen (Beispiel 20), die am Seitenanfang angezeigt werden. [takes_context=True]: Die Funktion erhält den Kontext des aufrufenden Templates, in dem der Context-Prozessor der Meldungen die Variable [messages] abgelegt hat. [level] ist die Stufe einer Meldung ([flash.SUCCESS], [flash.ERROR] ...);
  • Zeilen 31–40: [{% error_zone %}]: der Fehlerbereich am Ende jeder Seite. Er fasst die drei möglichen Fehlerquellen zusammen: den Seitenfehler (die Variable [error], die von der View übergeben und von [insert(0, ...)] an den Anfang der Liste gestellt wird), Flash-Fehlermeldungen (von der vorherigen View vor einer Weiterleitung gesetzt) und Eingabefehler eines ungültigen Formulars, deren Meldungen unter den Feldern angezeigt werden: Der Fehlerbereich zeigt dann einfach den Satz „Das Formular enthält Fehler.“ an. [is_bound]: Das Formular hat eine Eingabe erhalten (Beispiel 19).

Beide Tags lesen dieselbe Liste und behalten jeweils nur eine Stufe. Eine gelesene Meldungsliste wird am Ende der Anfrage geleert (Beispiel 20): Jede Meldung wird nur einmal angezeigt.

11.13.5. web/middleware.py

# =========================================================================
# web/middleware.py: zwei Middlewares der Web-Schicht (siehe Beispiel 24).
# =========================================================================

from django.conf import settings
from django.contrib import messages
from django.core.exceptions import BadRequest, PermissionDenied
from django.http import Http404
from django.shortcuts import redirect
from django.utils import translation
from django.utils.translation import gettext as _

from security import auth
from security.errors import InvalidSession

from .views.errors import error_page


# -------------------------------------------------------------------------
# die Sprache der Anfrage (siehe Beispiel 22): die des Cookies [rdvmedecins_language],
# wenn es eine unterstützte Sprache ist, sonst Englisch. Ganz oben in der Liste der
# Middlewares platziert, wirkt sie für ALLE Anfragen, auch für solche, die auf
# keiner Route enden (Seite 404): Ihre Fehlerseite ist in der richtigen Sprache
# -------------------------------------------------------------------------
class SetLanguage:
    # die unterstützten Sprachen; die Standardsprache ist LANGUAGE_CODE
    LANGUAGES = [code for code, name in settings.LANGUAGES]

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        language = request.COOKIES.get(settings.LANGUAGE_COOKIE_NAME)
        if language not in self.LANGUAGES:
            language = settings.LANGUAGE_CODE
        translation.activate(language)
        # die Sprache der Anfrage, gespeichert wie es LocaleMiddleware tut (siehe Beispiel 22)
        request.LANGUAGE_CODE = language
        return self.get_response(request)


# -------------------------------------------------------------------------
# wie Fehler zu HTML-Seiten werden. Drei Fälle:
#   1. eine InvalidSession (seit der Anmeldung gelöschtes Konto) -> zurück zur
#      Anmeldeseite, wie bei einer abgelaufenen Sitzung;
#   2. ein von einer View ausgelöster HTTP-Fehler: ungültige Anfrage (BadRequest, 400),
#      unzureichende Rolle (PermissionDenied, 403), unbekanntes Objekt (Http404) -> die Fehler-
#      seite, mit dem ursprünglichen Code;
#   3. jede andere Exception (eine echte Störung): Django schreibt sie ins
#      Log, mit ihrem Stacktrace; in der Produktion (DEBUG false) sieht der Benutzer
#      die Fehlerseite 500 (handler500, siehe config/urls.py) - nie den Stack-
#      trace; in der Entwicklung die Debug-Seite von Django.
# Eine abgelehnte HTTP-Methode (405) ist keine Exception: Die Dekoratoren
# require_GET ... geben eine leere Antwort 405 zurück, die __call__ durch unsere Seite ersetzt.
# -------------------------------------------------------------------------
class ErrorPage:
    CODES = {BadRequest: 400, PermissionDenied: 403, Http404: 404}

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        if response.status_code == 405 and not response.content:
            page = error_page(request, 405)
            # der Header Allow: die akzeptierten Methoden
            page["Allow"] = response["Allow"]
            return page
        return response

    def process_exception(self, request, exception):
        if isinstance(exception, InvalidSession):
            messages.error(request, _("Your session has expired: please log in again."))
            return auth.clear_token(redirect("login"))
        for cls, code in self.CODES.items():
            if isinstance(exception, cls):
                return error_page(request, code)
        return None

Die beiden Middleware-Komponenten der Web-Schicht (Beispiel 24). Erinnern Sie sich an ihre Reihenfolge in der Liste [MIDDLEWARE] aus [config/settings.py]: [SetLanguage] zuerst, [ErrorPage] zuletzt.

  • Zeilen 25–39: die Sprache der Anfrage; entspricht sie der Sprache des Cookies [rdvmedecins_language], wird diese Sprache verwendet, andernfalls Englisch. Dies ist die Middleware [SetLanguage] aus Beispiel 16, nicht [LocaleMiddleware] (Beispiel 22): [LocaleMiddleware] würde ohne Cookie die bevorzugte Sprache des Browsers wählen; die anderen Versionen der Anwendung starten immer auf Englisch, und diese tut dasselbe. Die unterstützten Sprachen werden aus der Einstellung [LANGUAGES] gelesen (Zeile 27, eine schreibgeschützte Liste, die einmal beim Laden der Klasse ausgeführt wird). [translation.activate] (Zeile 36) legt die aktive Sprache fest (Beispiel 16): die Sprache für Übersetzungen, Datumsangaben und die Variable [LANGUAGE_CODE] in den Templates (Context-Prozessor [i18n], Beispiel 22). Die Sprache wird außerdem in [request.LANGUAGE_CODE] gespeichert (Zeile 38), wie es auch [LocaleMiddleware] tut, für Views, die darauf zugreifen müssen. Da diese Middleware ganz oben steht, gilt sie für alle Anfragen vor jeder anderen Verarbeitung: Alle Seiten, einschließlich der Fehlerseiten, erscheinen in der richtigen Sprache;
  • Zeilen 62–69: Eine abgelehnte HTTP-Methode (ein GET-Aufruf von [/logout], das nur POST akzeptiert) löst keine Exception aus: Die Dekoratoren [require_GET], [require_POST] ... liefern eine 405-Antwort ohne Inhalt. [__call__] ersetzt sie durch die Fehlerseite und behält den Header [Allow] (die akzeptierten Methoden) bei, der in einer 405-Antwort erforderlich ist;
  • Zeilen 71–78: Von Views ausgelöste Exceptions ([process_exception], Beispiel 24). Eine [InvalidSession] (das Konto wurde gelöscht): die Meldung „Sitzung abgelaufen“, das Löschen des Token-Cookies und die Anmeldeseite. Ein von einer View ausgelöster HTTP-Fehler ([BadRequest], [PermissionDenied], [Http404]): die Fehlerseite mit ihrem Code, sowohl in Produktion als auch in Entwicklung. Jede andere Exception ist eine echte Anomalie: Die Methode liefert [None], und [Django] behandelt sie selbst; es protokolliert sie samt Aufrufstack und zeigt dann in der Entwicklung seine Debug-Seite und in der Produktion die 500-Fehlerseite ([handler500]) an. Der Benutzer sieht in der Produktion nie den Aufrufstack einer Anwendung.
1
2
3
4
5
6
7
$ curl -si http://localhost:8081/logout
HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=utf-8
Allow: POST
...
<!doctype html>
...

Der Code 405 (Method Not Allowed) wird dem Benutzer als „Seite nicht gefunden“ präsentiert (die Meldung der Fehlerseite, weiter unten beschrieben). Eine URL, die zu keiner Route passt, durchläuft [ErrorPage] nicht: [Django] ruft in der Produktion direkt die View [handler404] auf und zeigt in der Entwicklung seine detaillierte 404-Seite an (Beispiel 24).

11.14. Wörterbücher

Die Texte der Oberfläche sind dieselben wie in den anderen Versionen der Anwendung, die sie in JSON-Dateien unter Schlüsseln ablegten ([LOGIN.TITLE] verwies auf den Text [Sign in]). [Django] arbeitet anders (Beispiel 22): Der englische Originaltext steht direkt im Code ([_("Sign in")]) und in den Templates ([{% translate "Sign in" %}]); er dient als Schlüssel im französischen Wörterbuch, der Datei [locale/fr/LC_MESSAGES/django.po]:

#: web/views/schedule.py:202 web/views/area.py:75
msgid "Appointment cancelled."
msgstr "Rendez-vous annulé."

#: web/views/auth.py:62 web/views/area.py:142
#, python-format
msgid "Too many failed attempts. Try again in %(minutes)d minute."
msgid_plural "Too many failed attempts. Try again in %(minutes)d minutes."
msgstr[0] "Trop de tentatives infructueuses. Réessayez dans %(minutes)d minute."
msgstr[1] ""
"Trop de tentatives infructueuses. Réessayez dans %(minutes)d minutes."

Diese Datei mit etwa 140 Texten wird hier nicht wiedergegeben. Sie wurde mit dem Befehl [python manage.py makemessages -l fr] erzeugt, der alle mit dem Code und den Templates markierten Texte einsammelt, anschließend von Hand ergänzt und mit [django.mo] durch [python manage.py compilemessages] kompiliert (Beispiel 22). Die kompilierte Datei [django.mo] wird mit dem Code ausgeliefert: Die Anwendung läuft ohne die Werkzeuge von [gettext]. Es gibt kein englisches Wörterbuch: Text ohne Übersetzung wird unverändert, also auf Englisch, angezeigt.

Die Zeilen [#:] geben an, wo jeder Text verwendet wird; [#, python-format] kennzeichnet einen Text mit Parametern ([%(minutes)d]), dessen Übersetzung [makemessages] überprüfen wird. [gettext] ermöglicht etwas, das die anderen Versionen nicht konnten: den Plural („1 Minute“, „15 Minuten“), mit [ngettext] im Code (siehe unten) und [msgid_plural] im Wörterbuch (Beispiel 22). Einige Texte wurden hinzugefügt: die Meldung auf Seite 419, die die anderen Versionen nicht haben.

Fehlermeldungen von Formularen werden auf dieselbe Weise übersetzt (siehe unten). Die Meldungen, die [Django] selbst erzeugt (Zahl zu groß, ungültige E-Mail-Adresse usw.), werden mithilfe der Wörterbücher von [Django] übersetzt.

11.15. Formulare

Die „Person“-Formulare sind [Django]-Formulare (Beispiele 18 und 19): Eine Klasse beschreibt die Felder und ihre Einschränkungen; die View erzeugt das Formular mit der Eingabe des Benutzers ([PersonForm(request.POST)]) und prüft dann, ob es gültig ist ([is_valid]). Ein ungültiges Formular wird erneut angezeigt, mit der Eingabe des Benutzers und den Fehlermeldungen unter den Feldern (außer bei Passwörtern: Ein Feld [PasswordInput] wird nie erneut angezeigt). Das Anti-CSRF-Token wird bei allen Formularen von der Middleware [CsrfViewMiddleware] überprüft.

11.15.1. web/forms.py

# =========================================================================
# web/forms.py: die „Personen“-Formulare und ihre Einschränkungen (siehe
# Beispiele 18 und 19). Drei Formulare teilen sich dieselben Identitätsfelder
# (Anrede, Vorname, Nachname):
#
#   PersonFieldsForm            Anrede, Vorname, Nachname
#    ├─ PersonForm              + OPTIONALES Login / Passwort, Version
#    │                            (der ADMIN fügt einen Arzt / Client hinzu oder aktualisiert ihn)
#    ├─ RegistrationForm        + ERFORDERLICHES Login / Passwort / Bestätigung
#    │                            (ein Patient erstellt sein Konto)
#    └─ MyAccountForm           + Login, optionales neues Passwort, ERFORDERLICHES
#                                 AKTUELLES Passwort, Version
#                                 (ein Patient aktualisiert sein Konto)
#
# Die Kindklassen ERBEN von PersonFieldsForm: Sie haben dessen Felder plus
# ihre eigenen. Die validierte Eingabe (cleaned_data) wird von der Methode person_data() in PersonData
# für die Geschäftsschicht umgewandelt.
#
# Die Beschriftungen, die Hilfetexte und die Fehlermeldungen werden übersetzt (gettext_lazy,
# siehe business/errors.py). Die Maximallängen sind die der SQL-Spalten.
# =========================================================================

from django import forms
from django.core.exceptions import ValidationError
from django.core.validators import RegexValidator
from django.utils.translation import gettext_lazy as _

from business.person_data import PersonData
from security import passwords

TITLES = ["Mr", "Mme", "Melle"]
# Mindestlänge eines von einem Patienten GEWÄHLTEN Passworts
PASSWORD_MIN = 6

# Login: Kleinbuchstaben, Ziffern, Punkt, Bindestrich, Unterstrich - höchstens 30 Zeichen
LOGIN_FORMAT = RegexValidator(r"^[a-z0-9._-]{1,30}$", message=_(
    "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore."))


# bcrypt berücksichtigt nur die ersten 72 Bytes eines Passworts (siehe
# security/passwords.py); ein Buchstabe mit Akzent belegt in UTF-8 zwei Bytes
def bcrypt_length(value: str) -> None:
    if len(value.encode()) > passwords.MAX_BYTES:
        raise ValidationError(_("The password must not exceed 72 characters."))


# -------------------------------------------------------------------------
# ein Login steht immer in Kleinbuchstaben: Das Feld wandelt die Eingabe VOR ihrer
# Validierung um (to_python wird vor den Validatoren aufgerufen)
# -------------------------------------------------------------------------
class LoginField(forms.CharField):
    def to_python(self, value):
        text = super().to_python(value)
        return text.lower() if text else text


# ein Passwortfeld: wird nie erneut angezeigt und entfernt keine Leerzeichen
# (strip=False: Ein Leerzeichen gehört zum Passwort)
def password_field(label, required, help_text="", min_length=None):
    messages = {
        "required": _("The password is required."),
        # %(limit_value)d: die Mindestlänge, die Django in die Meldung einsetzt
        "min_length": _("The password must be at least %(limit_value)d characters long."),
    }
    return forms.CharField(label=label, required=required, help_text=help_text, strip=False,
                           min_length=min_length, validators=[bcrypt_length],
                           error_messages=messages,
                           widget=forms.PasswordInput(attrs={"maxlength": 72,
                                                             "autocomplete": "new-password"}))


# -------------------------------------------------------------------------
# die Elternklasse unserer Formulare (siehe Beispiel 18): Jedes Eingabefeld erhält
# die passende Bootstrap-CSS-Klasse; flag() umrandet rot (Klasse
# is-invalid) die Felder mit einem Eingabefehler und die, die ein GESCHÄFTSFehler
# bezeichnet (ein bereits vergebenes Login ...), wobei die Meldung dann unten auf der Seite steht
# -------------------------------------------------------------------------
class BootstrapForm(forms.Form):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        for field in self.fields.values():
            css_class = "form-select" if isinstance(field.widget, forms.Select) else "form-control"
            field.widget.attrs["class"] = css_class

    def flag(self, fields=()):
        # errors: die Eingabefehler; |: die Vereinigung zweier Mengen
        for name in set(self.errors) | set(fields):
            if name in self.fields:
                self.fields[name].widget.attrs["class"] += " is-invalid"
        return self


class PersonFieldsForm(BootstrapForm):
    title = forms.ChoiceField(label=_("Title"), choices=[(t, t) for t in TITLES], error_messages={
        "required": _("Choose a title from the list."),
        "invalid_choice": _("Choose a title from the list.")})
    first_name = forms.CharField(label=_("First name"), max_length=20, error_messages={
        "required": _("The first name is required."),
        "max_length": _("The first name must not exceed 20 characters.")})
    last_name = forms.CharField(label=_("Last name"), max_length=20, error_messages={
        "required": _("The last name is required."),
        "max_length": _("The last name must not exceed 20 characters.")})

    # die validierte Eingabe -> die von der Geschäftsschicht erwarteten Daten. Ein leeres
    # Feld ist None (oder None: Ein leerer String ist „falsy“)
    def person_data(self) -> PersonData:
        d = self.cleaned_data
        return PersonData(d["title"], d["last_name"], d["first_name"], d.get("login") or None,
                          d.get("password") or None, d.get("version"))


# das Formular eines Arztes oder Clients (ADMIN): OPTIONALES Login und
# Passwort; creation=False: das Aktualisierungsformular, mit der Version
class PersonForm(PersonFieldsForm):
    def __init__(self, *args, creation=True, **kwargs):
        super().__init__(*args, **kwargs)
        # ein leeres Feld wird akzeptiert: Die Validatoren gelten nur für einen eingegebenen Wert
        self.fields["login"] = LoginField(
            label=_("Login"), required=False, max_length=30, validators=[LOGIN_FORMAT],
            help_text=_("Optional: defaults to the last name in lower case.") if creation
            else _("Leave empty to keep it unchanged."),
            widget=forms.TextInput(attrs={"class": "form-control", "autocomplete": "off"}))
        self.fields["password"] = password_field(
            _("Password"), False,
            _("Optional: defaults to the login.") if creation
            else _("Leave empty to keep it unchanged."))
        self.fields["password"].widget.attrs["class"] = "form-control"
        # Aktualisierung: die Version des angezeigten Datensatzes, in einem versteckten Feld (das
        # optimistische Sperren)
        if not creation:
            self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)


# -------------------------------------------------------------------------
# das Passwort und seine Bestätigung: zwei Felder, verglichen durch clean (siehe
# Beispiel 19). Gemeinsam für die Registrierung (erforderlich) und das Konto des Patienten
# (optional: leer = Passwort unverändert)
# -------------------------------------------------------------------------
class WithConfirmation(PersonFieldsForm):
    def add_passwords(self, required: bool):
        self.fields["login"] = LoginField(
            label=_("Login"), max_length=30, validators=[LOGIN_FORMAT],
            help_text=_("Unaccented lower-case letters, digits, dot, hyphen, underscore.")
            if required else "",
            error_messages={"required": _("The login is required.")},
            widget=forms.TextInput(attrs={"class": "form-control", "autocomplete": "username"}))
        self.fields["password"] = password_field(
            _("Password") if required else _("New password"), required,
            _("At least 6 characters.") if required else _("Leave empty to keep it unchanged."),
            min_length=PASSWORD_MIN)
        self.fields["confirmation"] = password_field(_("Confirm password"), required)
        self.fields["confirmation"].error_messages["required"] = _("Please confirm the password.")
        for name in ("password", "confirmation"):
            self.fields[name].widget.attrs["class"] = "form-control"

    # die Validierung des gesamten Formulars, nach der jedes einzelnen Feldes
    def clean(self):
        data = super().clean()
        password = data.get("password")
        confirmation = data.get("confirmation")
        if password and password != confirmation and "confirmation" not in self.errors:
            self.add_error("confirmation", _("The confirmation does not match the password."))
        return data


# „Patientenkonto erstellen“: ERFORDERLICHES Login, Passwort und Bestätigung
class RegistrationForm(WithConfirmation):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.add_passwords(required=True)


# „Mein Konto verwalten“ (ein Patient): erforderliches Login, optionales neues Passwort,
# ERFORDERLICHES AKTUELLES Passwort, Version
class MyAccountForm(WithConfirmation):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.add_passwords(required=False)
        # das AKTUELLE Passwort, erforderlich für jede Aktualisierung des Kontos
        self.fields["current_password"] = forms.CharField(
            label=_("Current password"), strip=False,
            help_text=_("Required to save any change."),
            error_messages={"required": _("Enter your current password.")},
            widget=forms.PasswordInput(attrs={"class": "form-control", "maxlength": 72,
                                              "autocomplete": "current-password"}))
        self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)

Drei Formulare teilen sich die Identitätsfelder (Anrede, Vorname, Nachname): das Administratorformular (für einen Arzt oder einen Client), das Formular zur Erstellung eines Patientenkontos und „Mein Konto verwalten“. Der Kommentar im Kopf skizziert ihre Vererbungshierarchie: Ihre gemeinsame Elternklasse [PersonFieldsForm] definiert die Identitätsfelder; jedes Kind fügt seine eigenen hinzu. Die Beschriftungen, Tooltips und Meldungen werden verzögert übersetzt ([gettext_lazy]): Sie werden beim Laden des Moduls definiert und bei jeder Anzeige der Seite in die Sprache der Anfrage übersetzt (die Geschäftsschicht, weiter oben erwähnt).

  • Zeilen 36–37: ein Anmeldeformular, ein Validator ([RegexValidator]), der einen regulären Ausdruck prüft. Ein Validator ist ein aufrufbares Objekt, das bei einem fehlerhaften Wert [ValidationError] auslöst (Beispiel 19); er wird einem Feld über dessen Parameter [validators] zugewiesen;
  • Zeilen 42–44: ein Validator, der als einfache Funktion geschrieben ist. [bcrypt] berücksichtigt nur die ersten 72 Bytes eines Passworts (die Sicherheitsschicht, weiter oben beschrieben): Die Grenze gilt für Bytes, nicht für Zeichen ([encode()]: Ein Buchstabe mit Akzent belegt in [UTF-8] zwei Bytes);
  • Zeilen 51–54: Ein Benutzername ist immer kleingeschrieben. Ein eigenes Feld, eine Unterklasse von [CharField], überschreibt [to_python], die Methode, die die Eingabe in einen Python-Wert umwandelt: Sie wird vor den Validatoren aufgerufen, die die Eingabe daher erst nach der Umwandlung prüfen. [super().to_python(value)] führt zuerst die Standardverarbeitung von [CharField] aus (Entfernen der Leerzeichen um die Eingabe);
  • Zeilen 59–69: eine Funktion, die ein Passwortfeld erzeugt. [strip=False]: Leerzeichen werden nicht entfernt; sie können Teil eines Passworts sein. [min_length]: die Mindestlänge, die [Django] selbst prüft; ihre Meldung enthält [%(limit_value)d], den Parameter, den [Django] dort einsetzt. Das Widget [PasswordInput] wird nie erneut gezeichnet; das HTML-Attribut [maxlength] verhindert, dass Benutzer mehr als 72 Zeichen eingeben; [autocomplete="new-password"] weist den Browser an, ein neues Passwort vorzuschlagen, anstatt das Feld mit dem gespeicherten Passwort zu füllen;
  • Zeilen 78–90: die Elternklasse unserer Formulare (Beispiel 18). Ihr Konstruktor weist jedem Eingabefeld die passende CSS-Klasse zu ([form-select] für eine Liste, [form-control] für die übrigen). Die Methode [flag] fügt die Klasse [is-invalid] (einen roten Rand) zu Feldern mit Eingabefehlern und zu solchen hinzu, die durch einen Fehler einer Geschäftsregel markiert sind (ein bereits verwendeter Benutzername): [set(a) | set(b)] ist die Vereinigung zweier Mengen. Sie gibt das Formular selbst zurück: Die Views rufen sie auf, wenn sie das Formular an das Template übergeben;
  • Zeilen 93–102: die Anrede, eine Liste ([ChoiceField], Beispiel 18); Vor- und Nachname, maximal 20 Zeichen, entsprechend den Spaltenbreiten in SQL (das Attribut [maxlength] im Eingabefeld fügt [Django] selbst hinzu). Jede Fehlermeldung wird durch eine eigene ersetzt ([error_messages], Beispiel 19). [invalid_choice] ist die Meldung für einen Wert, der nicht in der Liste enthalten ist (eine manuell erzeugte Anfrage). Die Leerzeichen um eine Eingabe werden von [CharField] entfernt;
  • Zeilen 106–109: die validierte Eingabe ([cleaned_data]), umgewandelt in [PersonData] für die Geschäftsschicht: Die Geschäftsschicht kennt keine Formulare. [d.get(key)] liefert [None] für ein Feld, das das Formular nicht besitzt; [x or None] wandelt eine leere Zeichenkette in [None] um (ansonsten unverändert, oder der Standardwert);
  • Zeilen 114–131: das Formular des Administrators. Der Parameter [creation], den wir selbst eingeführt haben, unterscheidet zwischen Erstellung und Änderung; er steht nach [*args]: Er ist ein Pflichtparameter ([PersonForm(request.POST, creation=False)]). Die für dieses Formular spezifischen Felder werden vom Konstruktor im Dictionary [self.fields] ergänzt: Ihre Optionen hängen von [creation] ab (die Tooltips unterscheiden sich: „Optional: standardmäßig der Nachname in Kleinbuchstaben.“, „Leer lassen, um den Wert unverändert zu lassen.“). Benutzername und Passwort sind optional ([required=False]): Ein Validator wird nur auf einen eingegebenen Wert angewendet, ein leeres Feld wird also akzeptiert. Nur das Formular zum Ändern besitzt das versteckte Feld „version“ (das optimistische Sperren, Geschäftsschicht);
  • Zeilen 139–163: das Passwort und seine Bestätigung, die der Registrierung und dem Konto des Patienten gemeinsam sind. Die beiden Felder werden mit der Methode [clean] des Formulars verglichen (Beispiel 19), die nach der Validierung jedes Felds aufgerufen wird. [add_error] hängt die Meldung an das Bestätigungsfeld an, es sei denn, dieses Feld enthält bereits einen Fehler („Bitte bestätigen Sie das Passwort.“): nur eine Meldung pro Feld. Die Mindestlänge gilt nur für ein Passwort, das ein Patient wählt (6 Zeichen);
  • Zeilen 167–170: Erstellung eines Patientenkontos: Benutzername, Passwort und Bestätigung sind Pflichtfelder;
  • Zeilen 175–186: „Mein Konto verwalten“: Das neue Passwort ist optional (leer: unverändert), das aktuelle Passwort ist erforderlich. Es wird nicht vom Formular, sondern von der View validiert: Ein falsches Passwort muss vom Versuchsbegrenzer als fehlgeschlagene Anmeldung gezählt werden. [autocomplete="current-password"]: Hier darf der Browser das gespeicherte Passwort vorschlagen.

11.15.2. web/rendering.py

1
2
3
4
5
6
7
8
9
# web/rendering.py: die Rendering-Engine der Formulare (siehe Beispiel 18): Ein vollständiges
# Feld (Beschriftung, Eingabebereich, Hilfe, Fehler) wird vom Template
# templates/forms/field.html mit den Klassen von Bootstrap 5 gezeichnet

from django.forms.renderers import TemplatesSetting


class BootstrapRenderer(TemplatesSetting):
    field_template_name = "forms/field.html"

Die Rendering-Engine für Formulare aus Beispiel 18, festgelegt durch die Einstellung [FORM_RENDERER] in [config/settings.py]: Jedes vollständige Feld (Beschriftung, Eingabefeld, Tooltip, Fehlermeldungen) wird mit dem Template [templates/forms/field.html] (später beschrieben) und mit Klassen von [Bootstrap] gerendert.

11.16. View-Modelle

# =========================================================================
# web/view_models.py: die „View-Modelle“: Objekte, die von einer View
# in einem Zug aufgebaut werden und die das Template nur liest. Regel, der alle
# Seiten folgen: keine Logik in den Templates. Die Views bereiten
# BEREITS formatierte Daten vor („Mme Marie PELISSIER“, „8:00 - 8:20“,
# selected = True ...), bereits nach der Rolle des Benutzers gefiltert; die
# Templates setzen sie nur noch in das HTML ein.
# =========================================================================

from dataclasses import dataclass


# eine Option einer Dropdown-Liste (Arzt, Patient)
@dataclass(frozen=True)
class OptionView:
    id: int
    label: str
    selected: bool


# eine Zeile des angezeigten Terminkalenders (ein Zeitfenster)
@dataclass(frozen=True)
class ScheduleRow:
    slot_id: int
    time_range: str         # "8:00 - 8:20"
    free: bool
    # angezeigter Name für ein belegtes Zeitfenster; None = „Booked“
    patient: str | None
    me: bool                # der Termin des angemeldeten Patienten
    bookable: bool          # den Button "Book" anzeigen?
    book_url: str
    # nur gesetzt, wenn die Schaltfläche „Cancel“ angezeigt wird
    appointment_id: int | None


# der angezeigte Terminkalender: der Arzt, der Tag, die Zeilen
@dataclass(frozen=True)
class ScheduleView:
    doctor: str             # "Mme Marie PELISSIER"
    day: str                # "Wednesday 23 September 2026"
    rows: list[ScheduleRow]


# der Buchungsdialog eines Zeitfensters
@dataclass(frozen=True)
class BookingView:
    slot_id: int
    time_range: str
    # ADMIN / DOCTOR: die Patienten zur Auswahl
    clients: list[OptionView]
    # USER: der Patient ist er selbst
    patient: str | None


# ein zukünftiger Termin, im Bereich des Patienten
@dataclass(frozen=True)
class AppointmentView:
    id: int
    day: str                # "Wednesday 23 September 2026"
    time_range: str         # "8:00 - 8:20"
    doctor: str             # "Mme Marie PELISSIER"
    schedule_url: str       # der Terminkalender des Arztes an diesem Tag

Die Datei [web/view_models.py] enthält die View-Modelle: von einer View aufgebaute Objekte, die das Template einfach nur liest. Die Regel, der alle Seiten folgen: keine Logik in den Templates. Die Views bereiten Daten vor, die bereits formatiert („Frau Marie PELISSIER“, „8:00 – 8:20“) und bereits nach der Rolle des Benutzers gefiltert sind; die Templates setzen sie in das HTML ein. Es handelt sich um unveränderliche Datenklassen ([frozen=True], Beispiel 08): Ein einmal erzeugtes View-Modell ändert sich nie.

  • Zeilen 14–18: eine Option einer Dropdown-Liste: die ID, die Beschriftung und die Angabe, ob die Option ausgewählt ist;
  • Zeilen 22–33: ein Kalendereintrag: ein Zeitfenster und das, was der angemeldete Benutzer dazu sehen und tun darf. [patient] wird nur gefüllt, wenn der Benutzer den Namen des Patienten sehen darf; [bookable] gibt an, ob die Schaltfläche „Buchen“ angezeigt wird; [appointment_id] gibt an, ob die Schaltfläche „Stornieren“ angezeigt wird;
  • Zeilen 37–52: der angezeigte Kalender und das Buchungsfenster: für den Administrator und die Ärzte die Liste der auswählbaren Patienten, für einen Patienten sein eigener Name;
  • Zeilen 56–62: ein bevorstehender Termin im Bereich des Patienten.

11.17. Die Web-Schicht: Routen und Views

11.17.1. Routen

# =========================================================================
# web/urls.py: die Routen der Anwendung. Ihr Schutz steht nicht hier,
# sondern in security/access.py (eine Regel pro URL-Präfix).
# =========================================================================

from django.urls import path, re_path

from .views import area, auth, language, registration, schedule
from .views.persons import clients, doctors

urlpatterns = [
    # Anmeldung
    path("", auth.home, name="home"),
    path("login", auth.login, name="login"),
    path("logout", auth.logout, name="logout"),
    # die Sprache: nur fr oder en
    re_path(r"^language/(?P<code>fr|en)$", language.change, name="language"),
    # der Terminkalender
    path("schedule", schedule.show, name="schedule"),
    path("schedule/book", schedule.book, name="schedule_book"),
    path("schedule/cancel", schedule.cancel, name="schedule_cancel"),
    # die Erstellung eines Client-Kontos
    path("register/access", registration.access, name="registration_access"),
    path("register", registration.registration, name="registration"),
    # der Bereich des Patienten
    path("my-area", area.area, name="area"),
    path("my-area/cancel", area.cancel_appointment, name="area_cancel"),
    path("my-account", area.account, name="account"),
    path("my-account/delete", area.delete_account, name="account_delete"),
    # die Verwaltung von Ärzten und Clients: die Routen, die von den beiden
    # Objekten PersonManagement erstellt werden; * „entpackt“ die Liste, die sie zurückgeben
    *doctors.urls(),
    *clients.urls(),
]

Die Routen der Anwendung, eingebunden an der Wurzel der Website durch [config/urls.py]. Die Routen zur Verwaltung von Ärzten und Clients werden von zwei Objekten erzeugt (später beschrieben); [*list] fügt die Elemente einer Liste in eine andere Liste ein (Zeilen 32–33). Der Befehl [show_urls] existiert in [Django] nicht (er stammt aus einer Erweiterung); ein kurzes Skript, gestartet mit [python manage.py shell], listet sie alle samt ihren Namen auf:

$ python manage.py shell -v 0 -c "from django.urls import get_resolver; [print(f'{str(p.pattern):32} {p.name}') for p in get_resolver().url_patterns[0].url_patterns]"
                                 home
login                            login
logout                           logout
^language/(?P<code>fr|en)$       language
schedule                         schedule
schedule/book                    schedule_book
schedule/cancel                  schedule_cancel
register/access                  registration_access
register                         registration
my-area                          area
my-area/cancel                   area_cancel
my-account                       account
my-account/delete                account_delete
doctors                          doctors_list
doctors/add                      doctors_add
doctors/<int:id>/edit            doctors_edit
doctors/<int:id>/delete          doctors_delete
clients                          clients_list
clients/add                      clients_add
clients/<int:id>/edit            clients_edit
clients/<int:id>/delete          clients_delete

Die URLs sind die der anderen Versionen der Anwendung: Sie haben keinen abschließenden Schrägstrich ([/schedule], nicht [/schedule/]), und das Bearbeiten und Löschen eines Arztes sind POST-Anfragen ([/doctors/{id}/edit], [/doctors/{id}/delete]), nicht PUT und DELETE wie in Beispiel 28. Der Code erzeugt die URLs immer anhand der Routennamen ([redirect("login")], [reverse("schedule")], [{% url 'schedule' %}] in den Templates, Beispiel 04): Um eine URL zu ändern, muss nur ihre Route angepasst werden.

Die von jeder Route akzeptierten Methoden werden in den Views durch die Dekoratoren [require_GET], [require_POST], und [require_http_methods] deklariert (Beispiel 02). Die Zugriffsregeln stehen nicht in den Views, sondern, wie oben gesehen, in der Datei [security/access.py]: eine Regel pro URL-Präfix ([^/(doctors|clients)] für den Administrator, [^/my-] für Patienten ...) und eine abschließende Regel, die für alle anderen URLs einen authentifizierten Benutzer verlangt. Die URLs der Anwendung wurden mit diesem Ziel gewählt: Alle Seiten derselben Rolle beginnen gleich.

11.17.2. web/views/errors.py

# =========================================================================
# web/views/errors.py: die Fehlerseite (400, 403, 404, 405, 419, 500) und die Views,
# die Django für die Fehler aufruft, die es selbst erkennt (siehe config/urls.py:
# handler400, handler403, handler404, handler500 und die Einstellung CSRF_FAILURE_VIEW).
# =========================================================================

from django.shortcuts import render
from django.utils.translation import gettext_lazy as _

# die Meldung zu jedem Code
MESSAGES = {
    400: _("The request is invalid."),
    403: _("Your role does not allow you to access this page."),
    404: _("This page does not exist."),
    405: _("This page does not exist."),
    419: _("The page has expired: reload it, then try again."),
    500: _("An unexpected error occurred. Please try again later."),
}


def error_page(request, code: int):
    return render(request, "error.html", {
        "page_title": _("Error"), "code": code, "message": MESSAGES.get(code, MESSAGES[500]),
    }, status=code)


# die Views der von Django erkannten Fehler (exception: die Exception, die den
# Fehler verursacht hat; die View 500 erhält sie nicht)
def error_400(request, exception):
    return error_page(request, 400)


def error_403(request, exception):
    return error_page(request, 403)


def error_404(request, exception):
    return error_page(request, 404)


def error_500(request):
    return error_page(request, 500)


# -------------------------------------------------------------------------
# ein fehlendes oder falsches Anti-CSRF-Token: Die Seite wurde wahrscheinlich vor
# langer Zeit angezeigt, in einem anderen Tab, vor einem Wechsel des Token-Cookies ... Fehler
# 419, der (inoffizielle, aber verbreitete) Code einer abgelaufenen Seite. reason: der Grund
# der Ablehnung, von CsrfViewMiddleware angegeben (auf Englisch)
# -------------------------------------------------------------------------
def csrf_rejected(request, reason=""):
    return error_page(request, 419)

Die Fehlerseite und die Fehler-Views, die [Django] selbst erkennt:

  • Zeilen 11–18: die Meldung für jeden Code. Der Code 405 wird als Fehler „Seite nicht gefunden“ angezeigt;
  • Zeilen 21–24: die Fehlerseite, Template [error.html], mit dem HTTP-Antwortcode ([status=code]). Ein unbekannter Code erhält die Fehlermeldung 500 ([dict.get(key, default)]);
  • Zeilen 29–42: die vier Views [handler400] ... [handler500], auf die in [config/urls.py] verwiesen wird (Beispiel 24). Ihre Signatur wird von [Django] vorgegeben: die Anfrage und die Exception, die den Fehler verursacht hat (außer beim Fehler 500);
  • Zeilen 51–52: ein fehlendes oder ungültiges Anti-CSRF-Token. Die Middleware [CsrfViewMiddleware] weist die Anfrage ab, bevor die View aufgerufen wird (Beispiel 21), und ruft stattdessen die View auf, die der Einstellung [CSRF_FAILURE_VIEW] zugeordnet ist (siehe [config/settings.py]): die Fehlerseite 419, der (inoffizielle, aber weit verbreitete) Code für eine abgelaufene Seite. Dies tritt auf, wenn eine Seite lange in einem Tab geöffnet blieb, obwohl sich das Token-Cookie inzwischen geändert hat. Die Seite zeigt dann an: „Die Seite ist abgelaufen: Laden Sie sie neu und versuchen Sie es dann erneut.“ Ihr Parameter [reason] ist der Grund der Ablehnung, auf Englisch, der für das Protokoll und nicht für den Benutzer bestimmt ist.

11.17.3. web/views/language.py

# =========================================================================
# web/views/language.py: GET /language/fr, GET /language/en: die beiden Schaltflächen FR / EN der
# Navigationsleiste. Öffentliche Route: Die Sprache muss vor der Anmeldung
# änderbar sein.
#
# Die Wahl wird in einem Cookie gespeichert: Bei jeder folgenden Anfrage liest die Middleware
# SetLanguage es erneut und setzt die Sprache der Anfrage. Dann geht es zurück zu der Seite,
# von der wir kamen (siehe Beispiel 22).
# =========================================================================

from urllib.parse import urlsplit

from django.conf import settings
from django.shortcuts import redirect
from django.views.decorators.http import require_GET


# code: fr oder en (siehe web/urls.py: /language/de ergibt eine Seite 404)
@require_GET
def change(request, code):
    response = redirect(origin_page(request))
    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, code, max_age=365 * 24 * 3600,
                        secure=settings.COOKIE_SECURE, httponly=True, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# die vorherige Seite, aus dem HTTP-Header „Referer“, den der Browser sendet. Nur
# ihr Pfad und ihre Parameter werden behalten (/schedule?...): Eine Weiterleitung auf eine
# vollständige, von der Anfrage gelieferte Adresse würde es erlauben, den Benutzer auf
# eine andere Site zu schicken (sogenannte „Open-Redirect“-Schwachstelle). urlsplit zerlegt eine URL in ihre
# Bestandteile: scheme (http), netloc (der Rechner), path, query ...
# -------------------------------------------------------------------------
def origin_page(request) -> str:
    referer = urlsplit(request.headers.get("Referer", ""))
    path = referer.path
    # „//site.com/...“ würde vom Browser als Adresse auf einer
    # ANDEREN Site verstanden: ebenfalls abgelehnt
    if not referer.scheme or not path.startswith("/") or path.startswith("//") \
            or path.startswith("/language/"):
        return "/"
    return f"{path}?{referer.query}" if referer.query else path

Die Schaltflächen FR / EN in der Navigationsleiste: Die Sprachauswahl wird ein Jahr lang in einem Cookie gespeichert (Beispiel 22), danach kehrt der Browser zu der Seite zurück, von der er kam. Das Cookie ist [HttpOnly]: Das [JavaScript] der Seite muss es nicht lesen. Es ist nicht signiert: Die Middleware [SetLanguage] überprüft seinen Wert, und ein unbekannter Wert führt zu Englisch (siehe das Kapitel über Gültigkeitsbereiche).

  • Zeile 20: [code] entspricht [fr] oder [en]: Die Route (ein regulärer Ausdruck, [re_path], Beispiel 02) akzeptiert nur diese beiden Werte. [/language/de] passt zu keiner Route (404-Seite);
  • Zeilen 34–42: Die vorherige Seite wird durch den HTTP-Header [Referer] angegeben, den der Browser mit der Anfrage sendet. Diese Angabe stammt vom Client und ist daher verdächtig: Eine Weiterleitung auf eine vollständige URL aus der Anfrage würde es einem Angreifer erlauben, den Benutzer über einen Link auf [/language/fr] mit einem gefälschten [Referer] auf seine eigene Website zu schicken (die sogenannte „Open-Redirect“-Schwachstelle). Deshalb behalten wir nur den Pfad und die Parameter ([/schedule?doctorId=1&...]), die von der Funktion [urlsplit] der Standardbibliothek extrahiert werden, die eine URL in ihre Bestandteile zerlegt ([scheme], [netloc], [path], [query] ...). Ein Pfad, der mit [//] beginnt, wird ebenfalls abgelehnt: Ein Browser interpretiert [//site.com/page] als Adresse auf einer anderen Website. Schließlich darf man nicht zu [/language/...] zurückkehren: eine Schleife. Ein Backslash ([\]) am Zeilenende ([Python]) setzt die Anweisung in der nächsten Zeile fort.
1
2
3
4
5
6
7
8
9
$ curl -si http://localhost:8081/language/fr -H "Referer: http://localhost:8081/schedule?doctorId=1&day=2026-09-30"
HTTP/1.1 302 Found
Location: /schedule?doctorId=1&day=2026-09-30
Set-Cookie: rdvmedecins_language=fr; expires=Mon, 27 Sep 2027 17:56:57 GMT; HttpOnly; Max-Age=31536000; Path=/; SameSite=Lax
...
$ curl -si http://localhost:8081/language/fr -H "Referer: https://pirate.com//page"
HTTP/1.1 302 Found
Location: /
...

11.17.4. web/views/auth.py

# =========================================================================
# web/views/auth.py: die ÖFFENTLICHEN Routen der Anmeldung:
#   GET  /        leitet auf die Startseite der Rolle (oder auf /login) um
#   GET  /login   zeigt das Anmeldeformular an (mit seinem Captcha)
#   POST /login   prüft Versuchsgrenze, Captcha, Login / Passwort
#   POST /logout  Abmeldung
#
# Schutz vor Robotern, in dieser Reihenfolge:
#   1. zu viele aktuelle Fehlversuche für dieses Login von dieser IP-Adresse?
#      -> sofortige Ablehnung, ohne das Passwort auch nur anzusehen;
#   2. falsche Antwort auf das Captcha? -> Ablehnung (zählt als Fehlversuch);
#   3. erst dann die Prüfung des Passworts.
# Das Passwort eines in Schritt 1 oder 2 abgelehnten Versuchs wird NIE geprüft:
# Ein Roboter kann daher nichts lernen, wenn er hartnäckig bleibt.
# =========================================================================

from django.shortcuts import redirect, render
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from models.models import Role
from security import auth, captchas, limiter

from .. import utils


# die Startseite jeder Rolle, direkt nach der Anmeldung: der Name ihrer Route
def home_page(role: str) -> str:
    return "area" if role == Role.USER else "schedule"


# GET /: Die Route ist öffentlich; der Benutzer, falls vorhanden, ist bekannt
@require_GET
def home(request):
    if request.user is not None:
        return redirect(home_page(request.user.role))
    return redirect("login")


# GET /login[?login=xxx]: das Formular; der optionale Parameter füllt das
# Feld Login vor (verwendet direkt nach der Erstellung eines Kontos, siehe views/registration.py).
# POST /login: Anmeldung
@require_http_methods(["GET", "POST"])
def login(request):
    if request.method == "POST":
        return log_in(request)
    # bereits angemeldet (Token noch gültig): direkt zur Startseite
    if request.user is not None:
        return redirect(home_page(request.user.role))
    # [:30]: höchstens 30 Zeichen
    return page(request, request.GET.get("login", "")[:30], None)


def log_in(request):
    login = request.POST.get("login", "")
    password = request.POST.get("password", "")
    ip = utils.ip(request)
    # 1. zu viele aktuelle Fehlversuche? ngettext: der Singular oder der Plural, je nach der Anzahl
    minutes = limiter.login_block_minutes(ip, login)
    if minutes > 0:
        return page(request, login, ngettext(
            "Too many failed attempts. Try again in %(minutes)d minute.",
            "Too many failed attempts. Try again in %(minutes)d minutes.",
            minutes) % {"minutes": minutes})
    # 2. das Captcha
    if not captchas.verify(request.POST.get("captcha_id", ""), request.POST.get("captcha", "")):
        limiter.login_failure(ip, login)
        return page(request, login, _("The characters you typed do not match the image. "
                                      "A new image is shown."))
    # 3. das Passwort
    user = auth.validate(login, password) if login and password else None
    if user is None:
        limiter.login_failure(ip, login)
        return page(request, login, _("Incorrect login or password."))
    limiter.login_success(ip, login)
    return auth.set_token(redirect(home_page(user.role)), user)


# POST /logout: das Token-Cookie löschen, dann zur Anmeldeseite gehen.
# Nur POST: Ein einfacher Link (GET), der auf einer anderen Site platziert ist, kann
# den Benutzer nicht ohne sein Wissen abmelden
@require_POST
def logout(request):
    return auth.clear_token(redirect("login"))


# das Formular, immer mit einem NEUEN Captcha (jedes Bild wird nur
# einmal verwendet); das eingegebene Login wird erneut angezeigt, nie das Passwort. Bei einem Fehler: der
# Code 422, wie bei einem ungültigen Formular (siehe Beispiel 19)
def page(request, login: str, error: str | None):
    return render(request, "login.html", {
        "page_title": _("Sign in"), "error": error, "login": login,
        "captcha": captchas.generate(),
    }, status=422 if error else 200)

Die Anmeldung, die Beispiel 27 folgt:

  • Zeilen 28–29: die Startseite jeder Rolle samt ihrem Routennamen: „Mein Bereich“ für einen Patienten und der Kalender für die anderen;
  • Zeilen 33–37: Die Adresse [/] leitet auf die Startseite der Rolle oder auf die Anmeldeseite weiter. Die Route ist öffentlich (security/access.py): [request.user] ist der von der Middleware [Authentication] ermittelte Benutzer, falls es einen gibt;
  • Zeilen 43–51: Ein bereits angemeldeter Benutzer wird direkt auf seine Startseite geleitet. Der optionale URL-Parameter [login] füllt das Feld vorab aus (nach der Erstellung eines Kontos); [[:30]] kürzt ihn auf 30 Zeichen;
  • Zeilen 54–76: der Anmeldevorgang in der Reihenfolge von Beispiel 27: mögliche Sperre, das CAPTCHA, das Passwort (das Anti-CSRF-Token wurde bereits von der Middleware überprüft). Ein Passwort wird bei einem vom Begrenzer oder vom CAPTCHA abgelehnten Versuch nie überprüft: Ein Bot erfährt nichts, wenn er hartnäckig bleibt. [ngettext(singular, plural, number)] (Zeilen 61–64) wählt das passende Format für die Zahl in der Sprache der Anfrage (Beispiel 22); der Parameter [%(minutes)d] wird nach der Übersetzung gesetzt. Schlägt der Versuch fehl, wird die Seite direkt gerendert (keine Weiterleitung): Das erneut angezeigte Formular hat immer ein neues CAPTCHA und den eingegebenen Benutzernamen. Bei Erfolg wird der Anmeldezähler auf null zurückgesetzt, und der Browser wird mit dem Token-Cookie auf die Startseite der Rolle weitergeleitet;
  • Zeilen 82–84: Das Abmelden löscht das Token-Cookie (Beispiel 25). Es akzeptiert nur POST, zusammen mit dem Anti-CSRF-Token: Ein einfacher Link auf einer anderen Website kann den Benutzer nicht ohne sein Wissen abmelden;
  • Zeilen 90–94: die Anmeldeseite. Ein Fehler, etwa ein ungültiges Formular, wird mit dem Code 422 (Unprocessable Content) zurückgegeben (Beispiel 19).

Die Anmeldeseite erhält die Variable [page_title], den bereits übersetzten Seitentitel: Alle Views stellen ihn ihrem Template für das Tag [<title>] und die Seitenüberschrift bereit (siehe unten).

11.17.5. web/views/schedule.py

# =========================================================================
# web/views/schedule.py: die Seite des Terminkalenders: Auswahl eines Arztes und eines Tages,
# Terminkalender dieses Arztes an diesem Tag, Buchung und Stornierung 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 Zeitfenster 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 als Lesezeichen gespeichert werden,
# die Schaltfläche „Zurück“ des Browsers ist verwendbar - ohne eine einzige Zeile
# JavaScript.
#
# Was jeder sieht und tun kann:
#
#   | Rolle         | belegtes Zeitfenster angezeigt    | Buchen             | Stornieren |
#   |─────────────|───────────────────────────────────|────────────────────|─────────|
#   | ADMIN, DOCTOR | Name des Patienten                | für einen Patienten | ja        |
#   |               |                                   | aus einer Liste    |           |
#   | USER (Patient)| „Booked“ oder IHR Name, wenn es   | für sich selbst,   | nein (*)  |
#   |               | ihr eigener Termin ist            | wenn sie keinen    |           |
#   |               |                                   | zukünftigen Termin |           |
#
#   (*) der Patient storniert seinen Termin über seine Seite „Mein Bereich“.
#
# VERTRAULICHKEIT: Für einen Patienten wird der Name der ANDEREN Patienten nicht
# einfach vom Template ausgeblendet - er wird dem Template nie übergeben. Das an den Browser
# gesendete HTML enthält ihn daher nicht, auch nicht versteckt (sonst würde ihn ein einfaches „Seitenquelltext
# anzeigen" verraten).
#
# Keine Buchung in der Vergangenheit: Die Schaltfläche „Book“ erscheint nur für
# heute und die folgenden Tage (und die Geschäftsschicht würde sie ohnehin
# ablehnen).
#
# Sicherheit: Alle URLs unter /schedule erfordern einen authentifizierten Benutzer, und
# /schedule/cancel die Rolle ADMIN oder DOCTOR (siehe security/access.py).
# =========================================================================

from dataclasses import dataclass
from datetime import date
from urllib.parse import urlencode

from django.contrib import messages
from django.core.exceptions import BadRequest
from django.shortcuts import redirect, render
from django.urls import reverse
from django.utils.translation import gettext as _
from django.views.decorators.http import require_GET, require_POST

from domain.schedule import DoctorDaySchedule
from business import errors
from business.dates import today
from business.errors import BusinessError
from models.models import Client, Person, Role

from .. import utils
from ..application import application
from ..view_models import BookingView, OptionView, ScheduleRow, ScheduleView


# wer ist angemeldet, und was darf er auf dieser Seite tun?
@dataclass(frozen=True)
class Rights:
    manager: bool                      # ADMIN oder DOCTOR
    patient: Client | None             # der angemeldete Client (Rolle USER), sonst None
    patient_can_book: bool             # ein USER ohne bevorstehenden Termin


# -------------------------------------------------------------------------
# GET /schedule
# Die URL-Parameter werden roh gelesen (request.GET), um einen
# FEHLENDEN Parameter (None) von einem LEEREN Parameter (?doctorId=) zu unterscheiden.
# -------------------------------------------------------------------------
@require_GET
def show(request):
    error = None
    user = utils.user(request)
    rights = compute_rights(request)
    app = application()
    # der Tag: der aus der URL, wenn er gültig ist, sonst heute
    day = today()
    raw_day = request.GET.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 = _("The requested date is not valid.")
    bookable_day = day >= today()
    # der Arzt: der aus der URL; ersatzweise bei einem angemeldeten Arzt er selbst
    raw_doctor_id = request.GET.get("doctorId")
    doctor_id = utils.positive_integer(raw_doctor_id)
    if raw_doctor_id is None and user.role == Role.DOCTOR:
        doctor = app.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 app.get_all_doctors()]
    # der Terminkalender, wenn ein Arzt gewählt ist (und das Datum gültig)
    schedule = None
    if doctor_id is not None and error is None:
        doctor_schedule = app.get_doctor_day_schedule(doctor_id, day)
        if doctor_schedule is None:
            error = _("This doctor does not exist (any more).")
        else:
            schedule = schedule_view(doctor_schedule, rights, bookable_day)
    # der Buchungsdialog: nur wenn das angeforderte Zeitfenster von
    # diesem Benutzer gebucht werden kann
    booking = None
    slot_id = utils.positive_integer(request.GET.get("book"))
    if schedule is not None and slot_id is not None:
        row = next((r for r in schedule.rows if r.slot_id == slot_id and r.bookable), None)
        if row is not None:
            booking = BookingView(
                row.slot_id,
                row.time_range,
                [option(c, False) for c in app.get_all_clients()] if rights.manager else [],
                rights.patient.label() if rights.patient else None)
    return render(request, "schedule.html", {
        "page_title": _("Schedule"),
        "error": error,
        "doctors": doctors,
        "doctor_id": doctor_id,
        "day": utils.iso(day),
        "schedule": schedule,
        "booking": booking,
        # der angezeigte Terminkalender, ohne Buchungsdialog
        "back_url": schedule_url(doctor_id, day) if doctor_id is not None else reverse("schedule"),
        "info": patient_info(rights, schedule),
    })


# -------------------------------------------------------------------------
# POST /schedule/book   Felder: doctorId, day, slotId, clientId
#
# Für einen Patienten (USER) wird das Feld clientId IGNORIERT: Er bucht immer für
# sich selbst. Einem vom Browser gesendeten Feld zu vertrauen, würde es einem
# schlauen Patienten erlauben, im Namen eines anderen zu buchen.
#
# Muster „Post / Redirect / Get“: Was auch immer das Ergebnis ist, hier wird keine Seite aufgebaut
# - eine Flash-Meldung wird hinterlassen und auf den Terminkalender umgeleitet (siehe Beispiel 20).
# -------------------------------------------------------------------------
@require_POST
def book(request):
    doctor_id, day = requested_schedule(request)
    slot_id = utils.positive_integer(request.POST.get("slotId"))
    if doctor_id is None or slot_id is None:
        # -> Seite „ungültige Anfrage“ (siehe web/middleware.py)
        raise BadRequest("invalid schedule or slot")
    app = application()
    user = utils.user(request)
    if user.is_patient:
        client = utils.connected_patient(request)
    else:
        client_id = utils.positive_integer(request.POST.get("clientId"))
        if client_id is None:
            # kein Patient gewählt: Der Buchungsdialog wird erneut geöffnet
            messages.error(request, _("Choose a patient."))
            return redirect(schedule_url(doctor_id, day, slot_id))
        client = app.get_client_by_id(client_id)
    slot = app.get_slot_by_id(slot_id)
    if client is None:
        messages.error(request, _("This patient does not exist (any more)."))
    elif slot is None or slot.doctor_id != doctor_id:
        messages.error(request, _("This slot does not exist (any more)."))
    else:
        try:
            # die Regeln (nicht in der Vergangenheit, nur ein zukünftiger Termin pro
            # Patient, freies Zeitfenster) werden von der Geschäftsschicht geprüft
            app.add_appointment(day, slot, client)
            messages.success(request, _("Appointment booked."))
        except BusinessError as e:
            # dieselbe Regel, aber eine Meldung in der 2. Person, wenn der Patient
            # selbst bucht („You already have ...“ statt „This patient ...“).
            # Die anderen Exceptions (echte Störungen) werden nicht abgefangen: Seite 500
            if e.code == errors.PATIENT_HAS_APPOINTMENT and user.is_patient:
                messages.error(request, _("You already have an upcoming appointment: "
                                          "cancel it to book another one."))
            else:
                messages.error(request, e.message)
    return redirect(schedule_url(doctor_id, day))


# -------------------------------------------------------------------------
# POST /schedule/cancel   Felder: appointmentId, doctorId, day
# (ein Patient storniert SEINEN Termin über „Mein Bereich“, nicht von hier aus)
# -------------------------------------------------------------------------
@require_POST
def cancel(request):
    doctor_id, day = requested_schedule(request)
    appointment_id = utils.positive_integer(request.POST.get("appointmentId"))
    if doctor_id is None or appointment_id is None:
        raise BadRequest("invalid schedule or appointment")
    app = application()
    appointment = app.get_appointment_by_id(appointment_id)
    if appointment is None:
        # bereits storniert (durch jemand anderen oder Doppelklick)
        messages.error(request, _("This appointment does not exist (any more)."))
    else:
        app.delete_appointment(appointment)
        messages.success(request, _("Appointment cancelled."))
    return redirect(schedule_url(doctor_id, day))


# -------------------------------------------------------------------------
# wer ist angemeldet, und was darf er auf dieser Seite tun?
# -------------------------------------------------------------------------
def compute_rights(request) -> Rights:
    if not utils.user(request).is_patient:
        return Rights(manager=True, patient=None, patient_can_book=False)
    patient = utils.connected_patient(request)
    upcoming = application().get_client_upcoming_appointments(patient.id)
    # not list: true für eine leere Liste
    return Rights(manager=False, patient=patient, patient_can_book=not upcoming)


# -------------------------------------------------------------------------
# der Terminkalender des Arztes, für das Template formatiert - und nach den Rechten gefiltert
# -------------------------------------------------------------------------
def schedule_view(doctor_schedule: DoctorDaySchedule, rights: Rights, bookable_day: bool) -> ScheduleView:
    doctor_id = doctor_schedule.doctor.id
    day = doctor_schedule.day
    rows = []
    for dds in doctor_schedule.doctor_day_slots:
        slot = dds.slot
        appointment = dds.appointment
        free = appointment is None
        # der Termin des angemeldeten Patienten?
        me = appointment is not None and rights.patient is not None and appointment.client_id == rights.patient.id
        rows.append(ScheduleRow(
            slot_id=slot.id,
            time_range=slot.time_range(),
            free=free,
            # DER Punkt der Vertraulichkeit: Ein Patient erhält nur den Namen SEINES
            # Termins; für die anderen None (das Template zeigt „Booked“ an)
            patient=appointment.client.label() if appointment is not None and (rights.manager or me) else None,
            me=me,
            bookable=free and bookable_day 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(doctor_schedule.doctor.label(), utils.format_day(day), rows)


# ──────────────────────────────────────────────── Hilfsfunktionen
# die versteckten Felder doctorId / day der POST-Formulare; (None, None), wenn sie
# ungültig sind
def requested_schedule(request) -> tuple[int | None, date | None]:
    doctor_id = utils.positive_integer(request.POST.get("doctorId"))
    day = utils.valid_date(request.POST.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]: reverse baut den Pfad der
# Route, urlencode die URL-Parameter, korrekt kodiert (siehe Beispiel 04)
def schedule_url(doctor_id: int, day: date, book: int | None = None) -> str:
    parameters = {"doctorId": doctor_id, "day": utils.iso(day)}
    if book is not None:
        parameters["book"] = book
    return f"{reverse('schedule')}?{urlencode(parameters)}"


def option(p: Person, selected: bool) -> OptionView:
    return OptionView(p.id, p.label(), selected)


# -------------------------------------------------------------------------
# die Informationsmeldung für einen Patienten, der bereits einen zukünftigen Termin hat (warum
# es keine Schaltfläche „Book“ gibt), oder None. Überflüssig, wenn SEIN Termin
# im angezeigten Terminkalender erscheint (in Blau): Das ist direkt nach der
# Buchung der Fall, wo die Meldung fehl am Platz wäre
# -------------------------------------------------------------------------
def patient_info(rights: Rights, schedule: ScheduleView | None) -> str | None:
    if rights.patient is None or rights.patient_can_book:
        return None
    appointment_shown = schedule is not None and any(r.me for r in schedule.rows)
    return None if appointment_shown else _("You already have an upcoming appointment: "
                                            "cancel it to book another one.")

Die Hauptseite der Anwendung. Der Kommentar im Kopf fasst zusammen, was jeder Benutzer sieht und tun kann.

11.17.5.1. Die URL-Elemente der Seite

Die gesamte Seite wird durch ihre URL beschrieben: [/schedule?doctorId=1&day=2026-09-30] zeigt den Terminkalender von Arzt 1 für diesen Tag an; [&book=4] öffnet zusätzlich das Fenster zur Buchung von Zeitfenster 4. Sie können die Seite neu laden, als Lesezeichen speichern oder die Zurück-Schaltfläche des Browsers verwenden, ohne eine einzige Zeile [JavaScript]. Das Formular am Seitenanfang (zur Auswahl von Arzt und Tag) ist ein GET-Formular (Beispiel 17): Es lädt die Seite mit neuen Parametern neu. Das Fenster zur Terminbuchung wird durch einen einfachen Link geöffnet und durch einen Link auf dieselbe Seite ohne den Parameter [book] geschlossen.

11.17.5.2. GET /schedule

Zeilen 76–131:

  • Die URL-Parameter werden als Rohdaten gelesen ([request.GET.get("day")]), ohne Formular: Ein fehlender Parameter ([None]) ist kein Fehler (es gilt standardmäßig der heutige Tag bzw. kein Arzt); ein ungültiges Datum ist ein Fehler, der am Seitenende angezeigt wird (die Auswahl von Arzt und Tag bleibt sichtbar, der Kalender jedoch nicht); eine Arzt- oder Zeitfensternummer, die keine positive ganze Zahl ist, wird einfach ignoriert;
  • Ein angemeldeter Benutzer, der keinen Arzt ausgewählt hat, sieht seinen eigenen Terminkalender: Das System sucht seinen Arzt anhand seines Kontos ([get_doctor_by_user_id]);
  • die Dropdown-Liste der Ärzte: Eine Listenkomprehension wandelt den Namen jedes Arztes in [OptionView] um;
  • der Kalender, formatiert und gefiltert nach den Berechtigungen des Benutzers ([schedule_view], weiter unten);
  • das Buchungsfenster, nur wenn das angeforderte Zeitfenster für diesen Benutzer buchbar ist: Ein Patient, der versucht, die URL [&book=2] für ein bereits gebuchtes Zeitfenster zu erzeugen, erhielte nichts. [next(...)] liefert die erste Zeile des passenden Kalenders oder [None]. Die Liste der Patienten wird nur dem Administrator und den Ärzten bereitgestellt; ein Patient sieht nur seinen eigenen Namen;
  • das Template erhält seine Variablen ([render], Beispiel 13), darunter [page_title] und [error], die vom Basis-Template gelesen werden.

11.17.5.3. POST /schedule/book

Zeilen 144–182:

  • die versteckten Felder des Terminformulars (Arzt, Tag, Zeitfenster). Ungültig: Das kann nur eine manuell erzeugte Anfrage sein: [BadRequest], die Seite „Ungültige Anfrage“ (400), über die Middleware [ErrorPage];
  • Bei einem Patienten wird das Feld [clientId] ignoriert: Der Patient bucht immer für sich selbst ([utils.connected_patient]). Einem vom Browser gesendeten Feld zu vertrauen, würde einem böswilligen Patienten erlauben, eine Reservierung im Namen eines anderen vorzunehmen. Beim Administrator und bei den Ärzten muss ein Patient ausgewählt worden sein; andernfalls öffnet sich das Buchungsfenster erneut mit einer Meldung;
  • das Zeitfenster muss zu dem Arzt auf der Seite gehören ([slot.doctor_id]: der Fremdschlüssel, ohne Abfrage);
  • die Geschäftsregeln (nicht in der Vergangenheit, nur ein bevorstehender Termin, verfügbares Zeitfenster) werden von der Geschäftsschicht überprüft. Ein [BusinessError] wird zu einer Flash-Fehlermeldung. Dieselbe Ablehnung, „ein bevorstehender Termin“, wird der zweiten Person im Namen des Patienten selbst angezeigt („Sie haben bereits ...“). Jede andere Exception wird nicht abgefangen: Das ist ein echter Fehler (500-Seite);
  • in jedem Fall greift das Muster Post/Redirect/Get (Beispiel 20): eine Flash-Meldung und eine Weiterleitung auf den Kalender.

11.17.5.4. POST /schedule/cancel

Zeilen 189–203: Stornierung eines Termins durch den Administrator oder einen Arzt (Regel [^/schedule/cancel$] abgeleitet aus [security/access.py]). Ein Termin, der nicht mehr existiert (bereits von jemand anderem storniert oder durch einen Doppelklick), ist kein Fehler: Es erscheint lediglich eine Meldung.

11.17.5.5. Berechtigungen, formatierter Kalender und Hilfsfunktionen

  • Zeilen 64–68 und 209–215: was der Benutzer auf der Seite tun darf, in einer Datenklasse: Ist der Benutzer ein Administrator (ADMIN oder DOCTOR)? Ein Patient (und welcher)? Kann dieser Patient eine Reservierung vornehmen (keine bevorstehenden Termine)? [not list] ist wahr für eine leere Liste;
  • Zeilen 221–242: der Terminkalender des Arztes, umgewandelt in Zeilen für das Template. Das Vertraulichkeitsproblem liegt in Zeile 237: Einem Patienten wird nur der Name seines eigenen Termins angezeigt. Bei den anderen wird das Attribut [patient] auf [None] gesetzt, und das Template zeigt „Gebucht“ an. Der Name wird nicht vom Template maskiert: Er wird nie an das Template übermittelt und erscheint daher nicht im Quelltext der Seite, wo er leicht zu lesen wäre. Die Schaltfläche „Buchen“ wird für ein freies Zeitfenster in der Zukunft einem Administrator oder einem Patienten angezeigt, der eine Reservierung vornehmen kann; die Schaltfläche „Stornieren“ wird nur Administratoren angezeigt. Die benannten Parameter ([slot_id=slot.id]) machen die Erzeugung eines Objekts mit acht Attributen lesbar;
  • Zeilen 248–251: die versteckten Felder der POST-Formulare. Die Funktion gibt ein Tupel zurück, das die View in zwei Variablen entpackt ([doctor_id, day = requested_schedule(request)], Zeilen 146 und 191);
  • Zeilen 256–260: die URL für den Terminkalender eines Arztes an einem bestimmten Tag. [reverse("schedule")] liefert den Pfad der Route; [urlencode] erzeugt die korrekt kodierten Parameter: [/schedule?doctorId=1&day=2026-09-30];
  • Zeilen 273–278: die Meldung, die einem Patienten erklärt, warum es keine Schaltfläche „Buchen“ gibt (er hat bereits einen bevorstehenden Termin), es sei denn, dieser Termin steht im angezeigten Kalender (unmittelbar nach der Buchung würde die Meldung sonst verschoben). [any(...)]: Erfüllt mindestens eine Zeile die Bedingung?

11.17.6. web/views/persons.py

# =========================================================================
# web/views/persons.py: Die Verwaltung der Ärzte und die der Clients (dem
# ADMIN vorbehalten) sind IDENTISCH: gleiche Liste, gleiches Formular, gleiche Regeln. Anstatt
# dieselben Views zweimal zu schreiben, werden sie einmal geschrieben, als die METHODEN
# einer Klasse, PersonManagement; zwei OBJEKTE dieser Klasse, doctors und
# clients, unterscheiden sich nur durch das, was sie voneinander trennt: den Namen des Abschnitts
# (doctors oder clients), die Texte und die aufzurufenden Methoden des ApplicationModel.
#
# Eine Methode eines Objekts wird mit dem Objekt (self) aufgerufen: Die View object.list(request)
# weiß so, um welchen Abschnitt es geht. Die Methode urls() baut die Routen des
# Abschnitts:
#
#   GET  /doctors                    Liste                     doctors_list
#   GET  /doctors/add                leeres Formular           doctors_add
#   POST /doctors/add                Erstellung                doctors_add
#   GET  /doctors/{id}/edit          vorausgefülltes Formular  doctors_edit
#   POST /doctors/{id}/edit          Aktualisierung            doctors_edit
#   POST /doctors/{id}/delete        Löschen                   doctors_delete
#
# (und dieselben URLs unter /clients). Auch die Templates sind gemeinsam:
# templates/persons/list.html und persons/form.html.
#
# SICHERHEIT: Die Regel ^/(doctors|clients) in security/access.py reserviert alle diese
# URLs für den ADMIN - auch die, die später hinzukämen.
# =========================================================================

from collections.abc import Callable
from dataclasses import dataclass

from django.contrib import messages
from django.http import Http404
from django.shortcuts import redirect, render
from django.urls import path, reverse
from django.utils.translation import gettext_lazy as _
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from business import errors
from business.errors import BusinessError
from models.models import Person

from ..application import application
from ..forms import PersonForm

# die von jedem „Eingabe“-Geschäftsfehler (ein
# Duplikat) betroffenen Formularfelder: Sie werden rot umrandet, die Meldung steht unten auf der Seite
BUSINESS_ERROR_FIELDS = {
    errors.LOGIN_TAKEN: ["login"],
    errors.DOCTOR_ALREADY_EXISTS: ["first_name", "last_name"],
    errors.CLIENT_ALREADY_EXISTS: ["first_name", "last_name"],
}


# die für jeden Personentyp spezifischen Texte; %(name)s, %(login)s: die
# Parameter der Meldungen
@dataclass(frozen=True)
class Texts:
    title: str                  # "Doctors"
    add: str                    # "Add a doctor"
    edit: str                   # "Edit a doctor"
    empty: str                  # "No doctors."
    confirm_delete: str         # "Delete this doctor... ?"
    added: str                  # "Doctor %(name)s has been added (login: %(login)s)."
    updated: str
    deleted: str


class PersonManagement:
    def __init__(self, section: str, texts: Texts, list_all: Callable, find: Callable,
                 create: Callable, update: Callable, remove: Callable):
        # „doctors“ oder „clients“: der Anfang des Pfads und des Namens der Routen
        self.section = section
        self.texts = texts
        # die aufzurufenden Methoden des ApplicationModel (Funktionen, siehe unten)
        self.list_all = list_all
        self.find = find
        self.create = create
        self.update = update
        self.remove = remove

    # die Routen des Abschnitts; self.list: die an DIESES Objekt gebundene Methode
    def urls(self):
        s = self.section
        return [
            path(f"{s}", require_GET(self.list), name=f"{s}_list"),
            path(f"{s}/add", require_http_methods(["GET", "POST"])(self.add), name=f"{s}_add"),
            path(f"{s}/<int:id>/edit", require_http_methods(["GET", "POST"])(self.edit),
                 name=f"{s}_edit"),
            path(f"{s}/<int:id>/delete", require_POST(self.delete), name=f"{s}_delete"),
        ]

    # -------------------------------------------------------------------
    # GET /doctors (oder /clients)
    # -------------------------------------------------------------------
    def list(self, request):
        return render(request, "persons/list.html", {
            "page_title": self.texts.title, "texts": self.texts, "section": self.section,
            "add_url": reverse(f"{self.section}_add"), "persons": self.list_all()})

    # -------------------------------------------------------------------
    # GET /doctors/add: das leere Formular; POST: die Erstellung
    # -------------------------------------------------------------------
    def add(self, request):
        if request.method == "GET":
            return self.page(request, PersonForm(initial={"title": "Mr"}), None)
        form = PersonForm(request.POST)
        if not form.is_valid():
            return self.page(request, form, None)
        try:
            person = self.create(form.person_data())
        except BusinessError as e:
            return self.business_error(request, e, form, None)
        messages.success(request, str(self.texts.added) % parameters(person))
        return redirect(f"{self.section}_list")

    # -------------------------------------------------------------------
    # GET /doctors/{id}/edit: das vorausgefüllte Formular; POST: die Aktualisierung.
    # <int:id>: ein Parameter aus Ziffern (siehe Beispiel 02):
    # /doctors/abc/edit passt auf keine Route (Seite 404)
    # -------------------------------------------------------------------
    def edit(self, request, id):
        person = self.find(id)
        if person is None:
            raise Http404("unknown person")
        if request.method == "GET":
            # das Formular, vorausgefüllt mit den Werten der Person (das
            # Passwort selbst wird nie angezeigt)
            form = PersonForm(creation=False, initial={
                "title": person.title, "first_name": person.first_name, "last_name": person.last_name,
                "login": person.account.login, "version": person.version})
            return self.page(request, form, person)
        form = PersonForm(request.POST, creation=False)
        if not form.is_valid():
            return self.page(request, form, person)
        try:
            person = self.update(id, form.person_data())
        except BusinessError as e:
            return self.business_error(request, e, form, person)
        messages.success(request, str(self.texts.updated) % parameters(person))
        return redirect(f"{self.section}_list")

    # -------------------------------------------------------------------
    # POST /doctors/{id}/delete (die Bestätigung „Sind Sie sicher?“ wird abgefragt,
    # bevor das Formular gesendet wird, siehe static/js/app.js)
    # -------------------------------------------------------------------
    def delete(self, request, id):
        person = self.find(id)
        try:
            self.remove(id)
            messages.success(request, str(self.texts.deleted) % parameters(person))
        except BusinessError as e:
            messages.error(request, e.message)
        return redirect(f"{self.section}_list")

    # ──────────────────────────────────────────────── interne Funktionen
    # person None: Erstellungsformular; sonst: Aktualisierungsformular.
    # Ein abgelehntes Formular (ungültige Eingabe oder Geschäftsregel): der Code 422
    def page(self, request, form, person, error=None, invalid_fields=()):
        refused = error is not None or (form.is_bound and bool(form.errors))
        title = self.texts.add if person is None else self.texts.edit
        return render(request, "persons/form.html", {
            "page_title": title,
            "form": form.flag(invalid_fields),
            "error": error,
            "list_url": reverse(f"{self.section}_list"),
        }, status=422 if refused else 200)

    # eine Geschäftsregel hat den Schreibvorgang abgelehnt: Das Formular wird erneut angezeigt, mit
    # der Eingabe des Benutzers (ohne das Passwort), der Meldung der
    # Geschäftsschicht (unten auf der Seite) und den betroffenen Feldern, falls vorhanden, rot
    # umrandet, damit der Benutzer sofort sieht, was zu korrigieren ist
    def business_error(self, request, e: BusinessError, form, person):
        if e.code in (errors.DOCTOR_NOT_FOUND, errors.CLIENT_NOT_FOUND):
            # in der Zwischenzeit von einem anderen ADMIN gelöscht: zurück zur Liste
            messages.error(request, e.message)
            return redirect(f"{self.section}_list")
        return self.page(request, form, person, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))


# die Parameter %(name)s und %(login)s der Meldungen „hinzugefügt / aktualisiert / gelöscht“
def parameters(person: Person | None) -> dict:
    if person is None:
        return {"name": "", "login": ""}
    return {"name": f"{person.first_name} {person.last_name}", "login": person.account.login}


# -------------------------------------------------------------------------
# die beiden Objekte. lambda: eine kleine anonyme Funktion, die zum Zeitpunkt der Anfrage die richtige
# Methode des ApplicationModel aufruft. Die Texte werden „lazy“ übersetzt
# (gettext_lazy): zum Zeitpunkt ihrer Anzeige, in der
# Sprache der Anfrage, und nicht beim Laden des Moduls
# -------------------------------------------------------------------------

doctors = PersonManagement(
    "doctors",
    Texts(_("Doctors"), _("Add a doctor"), _("Edit a doctor"), _("No doctors."),
          _("Delete this doctor, their time slots and their user account?"),
          _("Doctor %(name)s has been added (login: %(login)s)."),
          _("Doctor %(name)s has been updated."), _("Doctor %(name)s has been deleted.")),
    list_all=lambda: application().get_all_doctors(),
    find=lambda id: application().get_doctor_by_id(id),
    create=lambda data: application().add_doctor(data),
    update=lambda id, data: application().edit_doctor(id, data),
    remove=lambda id: application().delete_doctor(id))

clients = PersonManagement(
    "clients",
    Texts(_("Patients"), _("Add a patient"), _("Edit a patient"), _("No patients."),
          _("Delete this patient, their user account and all their appointments?"),
          _("Patient %(name)s has been added (login: %(login)s)."),
          _("Patient %(name)s has been updated."), _("Patient %(name)s has been deleted.")),
    list_all=lambda: application().get_all_clients(),
    find=lambda id: application().get_client_by_id(id),
    create=lambda data: application().add_client(data),
    update=lambda id, data: application().edit_client(id, data),
    remove=lambda id: application().delete_client(id))

Die Verwaltung von Ärzten und Clients ist identisch: dieselbe Liste, dasselbe Formular, dieselben Regeln. Die Views werden einmal geschrieben, wie die Methoden einer Klasse [PersonManagement]; zwei Objekte dieser Klasse, [doctors] und [clients], unterscheiden sich nur in dem, was sie voneinander abhebt: dem Namen des Abschnitts, dem Text und den Methoden von [ApplicationModel] , die aufgerufen werden sollen. Eine View muss keine Funktion sein: Sie ist jedes aufrufbare Objekt, das eine Anfrage erhält und eine Antwort zurückgibt. [self.list], eine an ein Objekt gebundene Methode, ist eine solche View: [Django] ruft sie mit der Anfrage auf, und die Methode erhält zusätzlich ihr Objekt ([self]), das ihr Abschnitt ist. Um der Arzt- und der Client-Verwaltung eine View hinzuzufügen, genügt es, sie hier zu schreiben.

  • Zeilen 46–50: die Felder, die von jedem Eingabefehler der Geschäftslogik betroffen sind: Ein doppelter Benutzername betrifft das Feld „Login“; ein Namenskonflikt betrifft die Felder „Vorname“ und „Nachname“. Diese Felder werden rot hervorgehoben;
  • Zeilen 55–64: die für jeden Abschnitt spezifischen Texte in einer Datenklasse;
  • Zeilen 68–78: der Konstruktor. Die letzten fünf Parameter sind Funktionen ([Callable]): eine Person lesen (Liste), suchen, erstellen, ändern oder löschen;
  • Zeilen 81–89: die Routen des Abschnitts. Dekoratoren werden hier als Funktionen aufgerufen ([require_GET(self.list)]: die dekorierte View [self.list]): Genau das bewirkt die Syntax [@require_GET], wenn sie über einer Funktion steht (Beispiel 02). Das Präfix für den Pfad und die Routennamen ist der Abschnitt: Aus der View [list] werden die Routen [doctors_list] ([/doctors]) und [clients_list] ([/clients]);
  • Zeilen 94–97: die Liste. Das Template wird von beiden Abschnitten gemeinsam genutzt: Es erhält den Text des Abschnitts und die URL der Schaltfläche „Hinzufügen“;
  • Zeilen 102–113: die Funktion zum Hinzufügen. Eine einzige View für GET (das leere Formular, mit der über [Mr] ausgewählten Anrede [initial], Beispiel 18) und POST (Erstellung), wie in Beispiel 19 gezeigt. Eine ungültige Eingabe zeigt das Formular erneut an. Eine gültige Eingabe geht an die Geschäftsschicht, die den Schreibvorgang ablehnen kann (wegen eines Homonyms oder eines bereits verwendeten Logins); andernfalls erscheint eine Erfolgsmeldung als Flash-Nachricht, und der Benutzer kehrt zur Liste zurück (Schema PRG). Der Text der Meldung ist eine verzögerte Übersetzung: [str(...)] übersetzt ihn, bevor der Operator [%] seine Parameter einsetzt;
  • Zeilen 120–139: die Änderung, für eine Person, die existiert; andernfalls liefert [Http404] eine 404-Seite. [<int:id>] akzeptiert für den Parameter [id] nur Zahlen (z. B. 02) und wandelt sie in eine ganze Zahl um. Das GET-Formular wird mit den Werten der Person und ihrer Version vorausgefüllt; ein POST-Formular erhält die Eingabe;
  • Zeilen 145–152: das Löschen. Das Formular hat im Browser eine Bestätigung angefordert (Beispiel 21). Die Person wird vor dem Löschen für die Erfolgsmeldung abgerufen („Arzt Paul TATOU wurde gelöscht.“);
  • Zeilen 157–165: das Formular, für die Erstellung ([person] ist gleich [None]) oder die Änderung. Ein abgelehntes Formular (ungültige Eingabe oder Verstoß gegen eine Geschäftsregel) wird mit dem Statuscode 422 zurückgegeben (Beispiel 19). Hier hebt [flag] die Felder mit Fehlern rot hervor;
  • Zeilen 171–176: Die Geschäftsschicht hat den Schreibvorgang abgelehnt. Wurde eine Person in der Zwischenzeit gelöscht (von einem anderen Administrator): Rückkehr zur Liste. Andernfalls wird das Formular wie bei einem Eingabefehler direkt (ohne Weiterleitung) erneut angezeigt: Es enthält bereits die Eingabe des Benutzers. Hinzu kommen die Meldung der Geschäftsschicht (am Seitenende im Fehlerbereich angezeigt) und die rot hervorzuhebenden Felder;
  • Zeilen 180–183: die Parameter [%(name)s] und [%(login)s] für die Erfolgsmeldungen;
  • Zeilen 193–215: die beiden Objekte. Jedes [lambda] ruft bei Eintreffen der Anfrage die passende Methode von [ApplicationModel] auf: Die Fassade wird nicht beim Laden des Moduls erzeugt, sondern bei ihrer ersten Verwendung.

11.17.7. web/views/registration.py

# =========================================================================
# web/views/registration.py: „Patientenkonto erstellen“: Ein Patient, der noch
# kein Konto hat, erstellt es selbst. ÖFFENTLICHE Routen (man hat noch kein Konto,
# per Definition):
#
#   POST /register/access     Schaltfläche „Patientenkonto erstellen“ der
#                             Anmeldeseite: prüft das Captcha DIESER
#                             Seite und öffnet dann das Formular
#   GET  /register            das Formular
#   POST /register            die Erstellung, dann zurück zur Anmeldeseite
#
# Der Weg wird durch EIN Captcha gegen Roboter geschützt, das der
# Anmeldeseite:
#   1. die Schaltfläche „Patientenkonto erstellen“ sendet das Anmeldeformular an
#      /register/access; wird das Captcha korrekt eingegeben, stellt der Server einen
#      Pass aus (siehe security/registration_pass.py);
#   2. ohne gültigen Pass verweist /register zurück auf die
#      Anmeldeseite (Dekorator @registration_pass_required);
#   3. der Pass wird bei der Erstellung verbraucht: Ein gelöstes Captcha erlaubt die Erstellung
#      EINES Kontos;
#   4. außerdem ist die Anzahl der Konten pro Stunde und pro IP-Adresse begrenzt
#      (siehe security/limiter.py).
#
# Das erstellte Konto ist genau das, das der ADMIN über die Seite „Patienten“ erstellen würde
# (dieselbe Methode der Geschäftsschicht: add_client), nur dass der Patient
# sein Login und sein Passwort WÄHLT (erforderlich, mit Bestätigung).
# =========================================================================

from urllib.parse import urlencode

from django.contrib import messages
from django.shortcuts import redirect, render
from django.urls import reverse
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_http_methods, require_POST

from business.errors import BusinessError
from security import captchas, limiter, registration_pass
from security.registration_pass import registration_pass_required

from .. import utils
from ..application import application
from ..forms import RegistrationForm
from .persons import BUSINESS_ERROR_FIELDS


# die Meldung „zu viele erstellte Konten“, im Singular oder im Plural
def too_many_accounts(minutes: int) -> str:
    return ngettext(
        "Too many accounts have been created from your connection. Try again in %(minutes)d minute.",
        "Too many accounts have been created from your connection. Try again in %(minutes)d minutes.",
        minutes) % {"minutes": minutes}


# -------------------------------------------------------------------------
# POST /register/access   Felder: captcha_id, captcha (die der
# Anmeldeseite; login und password, ebenfalls gesendet, werden ignoriert)
# -------------------------------------------------------------------------
@require_POST
def access(request):
    ip = utils.ip(request)
    # zu viele in letzter Zeit von dieser Adresse erstellte Konten: Weitermachen ist sinnlos
    minutes = limiter.registration_block_minutes(ip)
    if minutes > 0:
        messages.error(request, too_many_accounts(minutes))
        return redirect("login")
    # fehlendes oder falsches Captcha: zurück zur Anmeldeseite, mit einem
    # neuen Bild (ein Fehlversuch zählt als Anmeldefehlversuch)
    if not captchas.verify(request.POST.get("captcha_id", ""), request.POST.get("captcha", "")):
        limiter.login_failure(ip, "")
        messages.error(request, _("To create an account, first type the characters shown in the image "
                                  "correctly, then click \"Create a patient account\"."))
        return redirect("login")
    # richtiges Captcha: Der Pass wird ausgestellt und das Formular geöffnet
    return registration_pass.issue(redirect("registration"))


# -------------------------------------------------------------------------
# GET /register: das Formular; POST /register: die Erstellung. Der
# Pass wurde VOR dem Aufruf der View geprüft (@registration_pass_required).
# Das Formular validiert ALLE Eingaben (Felder und Passwortbestätigung):
# Der Benutzer korrigiert alle seine Fehler in einem Zug
# -------------------------------------------------------------------------
@require_http_methods(["GET", "POST"])
@registration_pass_required
def registration(request):
    if request.method == "GET":
        return page(request, RegistrationForm(initial={"title": "Mr"}))
    form = RegistrationForm(request.POST)
    if not form.is_valid():
        return page(request, form)
    ip = utils.ip(request)
    # 1. zu viele in letzter Zeit von dieser Adresse erstellte Konten?
    minutes = limiter.registration_block_minutes(ip)
    if minutes > 0:
        return page(request, form, too_many_accounts(minutes))
    # 2. die Erstellung (Client + USER-Konto, in einer Transaktion)
    data = form.person_data()
    try:
        application().add_client(data)
    except BusinessError as e:
        # Login oder Vor- + Nachname bereits vergeben: Der Pass bleibt gültig
        return page(request, form, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))
    # 3. der Pass wurde verwendet: Er erlaubt nicht die Erstellung eines 2. Kontos
    registration_pass.consume(request.COOKIES.get(registration_pass.COOKIE))
    limiter.registration_success(ip)
    # 4. zurück zur Anmeldeseite, Login vorausgefüllt
    messages.success(request, _("Your account has been created. You can now log in with "
                                "the login %(login)s.") % {"login": data.login})
    url = f"{reverse('login')}?{urlencode({'login': data.login})}"
    return registration_pass.clear_cookie(redirect(url))


# das Formular; ein abgelehntes Formular: der Code 422
def page(request, form, error=None, invalid_fields=()):
    refused = error is not None or (form.is_bound and bool(form.errors))
    return render(request, "registration.html", {
        "page_title": _("Create a patient account"),
        "form": form.flag(invalid_fields), "error": error,
    }, status=422 if refused else 200)

Der Patient legt sein Patientenkonto selbst an. Der Ablauf ist durch ein CAPTCHA geschützt, dasselbe wie auf der Anmeldeseite.

  • Zeilen 59–75: Die Schaltfläche „Patientenkonto erstellen“ auf der Anmeldeseite sendet das Anmeldeformular an diese Adresse (die später zum Template [login.html] wird). Wurden von dieser Adresse (IP) zuletzt zu viele Konten erstellt, wird nicht weiter fortgefahren. Fehlt das CAPTCHA oder ist es falsch: Rückkehr zur Anmeldeseite mit einem neuen Bild und einer Meldung; der Fehlschlag zählt als fehlgeschlagener Anmeldeversuch (mit leerem Benutzernamen). Ist das CAPTCHA korrekt: Ein Token wird in einem Cookie gespeichert, und der Benutzer wird zum Formular weitergeleitet;
  • Zeilen 84–91: das Formular. Der Dekorator [@registration_pass_required] (Zeile 85) prüft das Token, bevor die View aufgerufen wird. Die Reihenfolge der Dekoratoren ist wichtig: Der, der der Funktion am nächsten steht, wird zuerst angewendet; [require_http_methods], das darüber steht, lehnt daher eine unzulässige Methode vor allen anderen Prüfungen ab. Das Formular validiert die gesamte Eingabe, einschließlich der Passwortbestätigung: Der Benutzer sieht alle seine Fehler auf einmal;
  • Zeilen 92–111: die Kontoerstellung. Der Client und sein Konto werden mit derselben Methode der Geschäftslogik erstellt wie beim Administrator ([add_client]); nur Benutzername und Passwort werden vom Patienten gewählt. Ist ein Benutzername oder ein Homonym bereits vergeben: Rückkehr zum Formular, ohne das Token zu verbrauchen. Die Erstellung eines Kontos verbraucht das Token (ein gelöstes CAPTCHA entspricht einem Konto), zählt für die stündliche Begrenzung und leitet mit vorausgefülltem Benutzernamen (Parameter [?login=...], erzeugt von [urlencode]) und einer Erfolgsmeldung auf die Anmeldeseite weiter. Das Pass-Cookie wird gelöscht.

11.17.8. web/views/area.py

# =========================================================================
# web/views/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 zukünftiger Termin
#   POST /my-area/cancel           storniert SEINEN Termin
#   GET  /my-account               Aktualisierungsformular seines Kontos
#   POST /my-account               Aktualisierung
#   POST /my-account/delete        Löschen des Kontos (und seiner Termine)
#
# Goldene Regel dieses Moduls: 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 ändern noch stornieren, was einem anderen
# Patienten gehört, auch nicht, indem er seine Anfragen selbst zusammenbaut.
#
# Jede Aktualisierung oder jedes Löschen 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. Die Fehler beim aktuellen Passwort werden
# als Anmeldefehlversuche gezählt (gleiche Grenze).
#
# Sicherheit: Alle diese URLs sind der Rolle USER vorbehalten (Regel ^/my- in
# security/access.py).
# =========================================================================

from django.contrib import messages
from django.shortcuts import redirect, render
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from business.errors import BusinessError
from models.models import Client
from security import auth, limiter

from .. import utils
from ..application import application
from ..forms import MyAccountForm
from ..view_models import AppointmentView
from .schedule import schedule_url
from .persons import BUSINESS_ERROR_FIELDS


# -------------------------------------------------------------------------
# GET /my-area
# -------------------------------------------------------------------------
@require_GET
def area(request):
    patient = utils.connected_patient(request)
    appointments = [AppointmentView(
        a.id,
        utils.format_day(a.day),
        a.slot.time_range(),
        a.slot.doctor.label(),
        # Link zum Terminkalender des Arztes an diesem Tag: Der Patient sieht dort seinen Namen
        schedule_url(a.slot.doctor_id, a.day))
        for a in application().get_client_upcoming_appointments(patient.id)]
    return render(request, "area.html", {"page_title": _("My area"),
                                         "patient": patient.label(), "appointments": appointments})


# -------------------------------------------------------------------------
# POST /my-area/cancel   Feld: appointmentId
# -------------------------------------------------------------------------
@require_POST
def cancel_appointment(request):
    patient = utils.connected_patient(request)
    appointment_id = utils.positive_integer(request.POST.get("appointmentId"))
    appointment = application().get_appointment_by_id(appointment_id) if appointment_id is not None else None
    # Ein nicht existierender Termin und der eines ANDEREN Patienten erhalten dieselbe
    # Antwort: Über die Termine der anderen wird nichts verraten
    if appointment is None or appointment.client_id != patient.id:
        messages.error(request, _("This appointment does not exist (any more)."))
    else:
        application().delete_appointment(appointment)
        messages.success(request, _("Appointment cancelled."))
    return redirect("area")


# -------------------------------------------------------------------------
# GET /my-account: das Formular, vorausgefüllt mit den Werten des Patienten;
# POST /my-account: die Aktualisierung
# -------------------------------------------------------------------------
@require_http_methods(["GET", "POST"])
def account(request):
    patient = utils.connected_patient(request)
    if request.method == "GET":
        return page(request, MyAccountForm(initial={
            "title": patient.title, "first_name": patient.first_name, "last_name": patient.last_name,
            "login": patient.account.login, "version": patient.version}))
    form = MyAccountForm(request.POST)
    if not form.is_valid():
        return page(request, form)
    # das aktuelle Passwort; falsch: Die Meldung steht UNTER dem Feld (ein per add_error dem
    # Feld hinzugefügter Fehler) und unten auf der Seite
    error = check_current_password(request, patient, form.cleaned_data["current_password"])
    if error is not None:
        form.add_error("current_password", error)
        return page(request, form, error)
    try:
        client = application().edit_client(patient.id, form.person_data())
    except BusinessError as e:
        return page(request, form, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))
    # das Login und der angezeigte Name stehen IM Token: Ein neues wird ausgestellt, sonst
    # würde die Navigationsleiste den alten Namen behalten
    messages.success(request, _("Your account has been updated."))
    return auth.set_token(redirect("area"), client.account)


# -------------------------------------------------------------------------
# POST /my-account/delete   Feld: current_password
# Das Konto, der Client und ALLE seine Termine verschwinden gemeinsam, dann wird der
# Patient abgemeldet.
# -------------------------------------------------------------------------
@require_POST
def delete_account(request):
    patient = utils.connected_patient(request)
    error = check_current_password(request, patient, request.POST.get("current_password", ""))
    if error is not None:
        messages.error(request, error)
        return redirect("account")
    application().delete_client(patient.id)
    messages.success(request, _("Your account has been deleted."))
    return auth.clear_token(redirect("login"))


# ──────────────────────────────────────────────── interne Funktionen
# die Kontoseite; ein abgelehntes Formular: der Code 422
def page(request, form, error=None, invalid_fields=()):
    refused = error is not None or (form.is_bound and bool(form.errors))
    return render(request, "account.html", {
        "page_title": _("Manage my account"),
        "form": form.flag(invalid_fields), "error": error,
    }, status=422 if refused else 200)


# None, wenn das aktuelle Passwort korrekt ist; andernfalls die Fehlermeldung
def check_current_password(request, patient: Client, password: str) -> str | None:
    ip = utils.ip(request)
    login = patient.account.login
    minutes = limiter.login_block_minutes(ip, login)
    if minutes > 0:
        return ngettext("Too many failed attempts. Try again in %(minutes)d minute.",
                        "Too many failed attempts. Try again in %(minutes)d minutes.",
                        minutes) % {"minutes": minutes}
    if not password or auth.validate(login, password) is None:
        limiter.login_failure(ip, login)
        return _("Incorrect current password.")
    return None

Die persönlichen Seiten des Patienten. Die goldene Regel dieses Moduls: Der betreffende Patient ist immer derjenige, der dem Token zugeordnet ist ([utils.connected_patient]), nie eine vom Browser gesendete Kennung. Ein Patient kann daher Informationen eines anderen Patienten weder einsehen noch ändern noch stornieren, selbst wenn er eigene Anfragen erzeugt.

  • Zeilen 46–58: Mein Bereich: der Name des Patienten und seine bevorstehenden Termine, formatiert ([AppointmentView]), jeweils mit einem Link auf den Terminkalender des Arztes für diesen Tag. Die Funktion [schedule_url] gehört zum Kalendermodul (Zeile 39, [from .schedule import schedule_url]);
  • Zeilen 64–76: die Stornierung seines Termins. Sowohl ein nicht existierender Termin als auch der Termin eines anderen Patienten erhalten dieselbe Antwort: Über die Termine anderer Patienten wird keine Information preisgegeben (nicht einmal ihre Existenz);
  • Zeilen 83–92: das Formular „Mein Konto verwalten“, mit den Angaben des Patienten vorausgefüllt, und seine Übermittlung;
  • Zeilen 95–106: die Änderung. Jede Änderung erfordert das aktuelle Passwort: Wer eine offen gebliebene Sitzung gefunden hat, kann weder das Passwort noch sonst etwas ändern. Ist das aktuelle Passwort falsch, wird das Formular erneut angezeigt, mit der Meldung unter dem Feld und am Seitenende. [add_error(field, message)] fügt einem Feld einen Fehler hinzu, als hätte die Validierung ihn erkannt (Beispiel 19). Nach der Änderung wird ein neues Token erzeugt: Der Login und der angezeigte Name sind im Token enthalten, und die Navigationsleiste würde andernfalls bis zur nächsten Anmeldung den alten Namen behalten;
  • Zeilen 114–123: das Löschen des Kontos, des Clients und aller seiner Termine, mit derselben Methode der Geschäftslogik wie beim Administrator. Dieses zweite Formular auf der Seite ist von Hand geschrieben (ein einziges Feld: das aktuelle Passwort). Der Patient wird anschließend abgemeldet (das Token-Cookie wird gelöscht);
  • Zeilen 137–148: die Überprüfung des aktuellen Passworts. Sie unterliegt dem Versuchsbegrenzer, genau wie eine Anmeldung: Ohne ihn könnte jemand mit einer offenen Sitzung über das Formular „Mein Konto verwalten“ Tausende von Passwörtern ausprobieren und das richtige herausfinden.

11.18. Die Templates

Die Templates im Ordner [templates] (Konfiguration [TEMPLATES] aus [config/settings.py]): ein Eltern-Template, Fragmente, benannte Formularfragmente und Seiten.

11.18.1. Das Eltern-Template und die Fragmente

11.18.1.1. templates/layout.html

<!doctype html>
{% comment %}
  =========================================================================
  templates/layout.html
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  Das ELTERN-Template aller Seiten (siehe Beispiel 15): jede Seite
  (schedule.html, login.html...) ERWEITERT es ({% extends %}) und füllt seinen
  Block [content].

  Django MASKIERT alles, was es mit {{ ... }} anzeigt (die Zeichen < > & " '
  werden zu &lt; &gt;...): Schutz vor HTML-Injection, zum Beispiel durch einen eingegebenen
  Namen. Um HTML unverändert einzufügen, muss dies ausdrücklich
  angefordert werden (Filter safe, siehe fragments/captcha.html).

  Nachrichten: Ein Erfolg wird OBEN auf der Seite angezeigt, ein Fehler UNTEN, auf hellrosa
  Hintergrund (Tags success_zone und error_zone, siehe web/templatetags/rdv.py).

  Das Template teilt die Variablen der Seite: [page_title] (der Titel der
  Seite, von der View übergeben, bereits übersetzt). LANGUAGE_CODE: die Sprache der
  Anfrage (siehe web/middleware.py).
  =========================================================================
{% endcomment %}
{% load static i18n rdv %}
<html lang="{{ LANGUAGE_CODE }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ page_title }} - RdvMedecins</title>
  {# static: die URL einer Datei im Ordner static #}
  <link rel="stylesheet" href="{% static 'lib/bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-4">
    {% include "fragments/navbar.html" %}
    {% success_zone %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {% error_zone %}
  </div>
  {# der Dialog "Are you sure?", versteckt, solange er nicht benötigt wird #}
  {% include "fragments/confirmation.html" %}
  <script src="{% static 'js/app.js' %}"></script>
</body>
</html>

Das Eltern-Template aller Seiten (Beispiel 15): Jede Seite erweitert es ([{% extends "layout.html" %}]) und füllt ihren Block [content] (Zeile 38).

  • Zeile 23: die verwendeten Tag-Bibliotheken: [static] (statische Dateien), [i18n] (Übersetzungen, Beispiel 22) und [rdv], unsere eigene (Web-Schicht, weiter oben). Ein Eltern-Template gibt seine Bibliotheken nicht an die Templates weiter, die es erweitern: Jede Seite lädt die, die sie benötigt;
  • Zeile 24: die Sprache der Seite, [fr] oder [en]: die aktive Sprache der Anfrage, festgelegt von der Middleware [SetLanguage];
  • Zeile 28: der Seitentitel, bereits von der View übersetzt, die ihn in der Variablen [page_title] übergibt;
  • Zeilen 30–31: Das Tag [{% static %}] erzeugt die URL einer Datei im Ordner [static] (Beispiel 15);
  • Zeilen 35–40: die Navigationsleiste, die Erfolgsmeldungen am Seitenanfang, der Seiteninhalt und der Fehlerbereich am Seitenende. Das Fragment der Navigationsleiste wird von [{% include %}] eingefügt (Beispiel 15): Es greift auf die Variablen der Seite zu. Die beiden Meldungsbereiche sind die Inclusion-Tags aus [web/templatetags/rdv.py];
  • Zeilen 43–44: das Fenster „Sind Sie sicher?“, bis zum Bedarfsfall verborgen, und das Skript, das es anzeigt.

Der Kommentar im Kopf (Zeilen 2–22) ist ein Tag [{% comment %}]: ein Template-Kommentar, der sich über mehrere Zeilen erstrecken kann ([{# ... #}] passt in eine einzige Zeile, Beispiel 14). Er steht nach [<!doctype html>]: Die erste Zeile der gesendeten Seite muss die Dokumenttyp-Deklaration sein. Die DTL maskiert alles, was sie mit [{{ ... }}] ausgibt (Beispiel 14): Ein vom Benutzer eingegebener Name, der HTML enthält ([<script>]), wird unverändert angezeigt, ohne interpretiert zu werden. Das verhindert, dass mühelos HTML (XSS) in alle Seiten eingeschleust wird.

11.18.1.2. templates/fragments/navbar.html

{% comment %}
  =========================================================================
  templates/fragments/navbar.html: die Navigationsleiste.

  Titel, FR/EN, Rolle, Name, Abmelden - und das Menü, dessen Einträge von der Rolle
  abhängen: sie werden vom Context Processor web/contexts.py berechnet
  (Variable menu), jeweils mit ihrer URL, ihrem Label und der Angabe, ob es der Eintrag
  der aktuellen Seite ist (Klasse "active").

  user: der angemeldete Benutzer oder None (siehe web/contexts.py).
  =========================================================================
{% endcomment %}
{% load i18n %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">RdvMedecins</span>

  <ul class="navbar-nav me-auto">
    {% for entry in menu %}
    <li class="nav-item">
      <a class="nav-link{% if entry.active %} active{% endif %}" href="{{ entry.url }}">{{ entry.label }}</a>
    </li>
    {% endfor %}
  </ul>

  <div class="d-flex align-items-center gap-2">
    {# FR / EN: einfache Links (GET /language/fr), die aktive Sprache hervorgehoben #}
    {% get_available_languages as languages %}
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      {% for code, name in languages %}
      <a class="btn {% if code == LANGUAGE_CODE %}btn-light{% else %}btn-outline-light{% endif %}"
         href="{% url '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>
    {# logout ist ein POST: ein Formular, reduziert auf seinen Button (und auf das Anti-CSRF-Token) #}
    <form method="post" action="{% url 'logout' %}" class="m-0">
      {% csrf_token %}
      <button type="submit" class="btn btn-sm btn-outline-light">{% translate "Log out" %}</button>
    </form>
    {% endif %}
  </div>
</nav>

Die Navigationsleiste. Sie zeigt einfach das an, was der Context-Prozessor [web/contexts.py] vorbereitet hat: den angemeldeten Benutzer ([user]) und die Menüeinträge ([menu]), die von der Rolle abhängen.

  • Zeilen 17–23: das Menü, wobei jeder Eintrag seine eigene URL und Beschriftung hat; die Klasse [active] von [Bootstrap] hebt den Eintrag der aktuell angezeigten Seite hervor;
  • Zeilen 27–32: die Schaltflächen FR / EN, einfache Links ([/language/fr]), wobei die aktive Sprache hervorgehoben wird. [{% get_available_languages as languages %}] (Bibliothek [i18n]) speichert die Einstellung [LANGUAGES] – eine Liste von Paaren (Code, Name) – in der Variablen [languages], die die Schleife entpackt ([{% for code, name in languages %}]); der Filter [upper] schreibt den Code in Großbuchstaben. [{% url 'language' code %}] erzeugt die URL für eine Route mit einem Parameter (Beispiel 15);
  • Zeilen 35–43: Für einen angemeldeten Benutzer seine Rolle, sein Name und die Schaltfläche zum Abmelden. Das Abmelden ist eine POST-Anfrage: ein auf seine Schaltfläche reduziertes Formular mit seinem Anti-CSRF-Token ([{% csrf_token %}], Beispiel 21).

11.18.1.3. templates/fragments/success.html und errors.html

1
2
3
4
{# templates/fragments/success.html: die ERFOLGSMELDUNGEN (Tag success_zone, siehe web/templatetags/rdv.py) #}
{% for text in texts %}
<div class="alert alert-success" role="status">{{ text }}</div>
{% endfor %}
{% comment %}
  templates/fragments/errors.html: der Fehlerbereich, UNTEN auf jeder Seite, auf
  hellrosa Hintergrund (Klasse .error-zone, siehe static/css/styles.css). Die Meldungen
  werden vom Tag error_zone gesammelt (siehe web/templatetags/rdv.py).
  role="alert": ein Screenreader kündigt die Meldung an, sobald die Seite angezeigt wird,
  auch wenn sie unten steht.
{% endcomment %}
{% if texts %}
<div class="error-zone" role="alert">
  {% for text in texts %}
  <div>{{ text }}</div>
  {% endfor %}
</div>
{% endif %}

Die beiden Inclusion-Tag-Templates [success_zone] und [error_zone] (Web-Schicht, weiter oben): Sie erhalten die vom Tag vorbereitete Liste [texts] und zeigen sie an. [role="status"]: Ein Screenreader kündigt die Erfolgsmeldung an. [role="alert"]: Er kündigt den Fehlerbereich an, sobald die Seite angezeigt wird, auch wenn dieser am Seitenende liegt. Der Fehlerbereich bleibt am unteren Fensterrand verankert, wenn die Seite lang ist (siehe das Stylesheet weiter unten).

11.18.1.4. templates/fragments/confirmation.html

{% comment %}
  =========================================================================
  templates/fragments/confirmation.html: der modale Dialog "Are you sure?"
  (siehe Beispiel 21).

  Er ersetzt das Fenster 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 Nachricht
  ein (Attribut data-confirmation) und sendet das Formular, wenn
  der Benutzer bestätigt.
  =========================================================================
{% endcomment %}
{% load i18n %}
<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">{% translate "Confirmation" %}</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="{% translate 'Close' %}"></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?" #}
          <button type="button" class="btn btn-secondary" data-action="no">{% translate "No, go back" %}</button>
          <button type="button" class="btn btn-danger" data-action="yes">{% translate "Yes, confirm" %}</button>
        </div>
      </div>
    </div>
  </div>
</div>

Das modale Fenster „Sind Sie sicher?“ aus Beispiel 21, das das Dialogfeld [window.confirm()] des Browsers ersetzt: Dieses Dialogfeld lässt sich nicht richtig formatieren, und seine Schaltflächen bleiben in der Sprache des Browsers statt in der der Seite. Ein einziges Fenster für die gesamte Seite, anfangs verborgen (Klasse [d-none] aus [Bootstrap]); seine Beschriftungen werden wie der Rest der Seite vom Server übersetzt. Das Skript [static/js/app.js] zeigt es an, setzt die Meldung des zu bestätigenden Formulars hinein (dessen Attribut [data-confirmation]) und sendet das Formular ab, wenn der Benutzer bestätigt. Die Schaltfläche „Abbrechen“ ist mit „Nein, zurück“ statt mit „Abbrechen“ beschriftet: Die Frage lautet manchmal „Diesen Termin stornieren?“, und eine Schaltfläche „Abbrechen“ wäre in diesem Zusammenhang mehrdeutig. Die Attribute [role="alertdialog"], [aria-modal], [aria-labelledby] und [aria-describedby] beschreiben das Fenster für Screenreader: ein Dialogfeld, das auf eine Antwort wartet, sein Titel und seine Meldung.

11.18.1.5. templates/fragments/booking.html

{% comment %}
  =========================================================================
  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 über seine Anzeige (Parameter &book=... der
  URL), und das Schließen bedeutet, einem Link zur selben Seite ohne diesen
  Parameter zu folgen.

  Das Fragment liest direkt die Variablen der Seite, die es einbindet
  (booking, doctor_id, day, back_url).
  =========================================================================
{% endcomment %}
{% load i18n %}
<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="{% url 'schedule_book' %}" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">{% translate "Book this slot" %}</h5>
        <a class="btn-close" href="{{ back_url }}" aria-label="{% translate 'Close' %}"></a>
      </div>

      <div class="modal-body">
        <p>{% blocktranslate with time_range=booking.time_range %}Slot {{ time_range }}{% endblocktranslate %}</p>

        {# was der Server zusätzlich zum gewählten Patienten wissen muss #}
        {% csrf_token %}
        <input type="hidden" name="doctorId" value="{{ doctor_id }}">
        <input type="hidden" name="day" value="{{ day }}">
        <input type="hidden" name="slotId" value="{{ booking.slot_id }}">

        {# ein Patient bucht für sich selbst: keine Auswahlliste (und der Server ignoriert ein etwaiges clientId ohnehin) #}
        {% if booking.patient %}
        <p class="mb-0">
          <span>{% translate "Patient" %}</span>:
          <strong>{{ booking.patient }}</strong>
        </p>
        {% else %}
        <label class="form-label" for="clientId">{% translate "Patient" %}</label>
        <select id="clientId" name="clientId" class="form-select" required autofocus>
          <option value="">{% translate "-- choose a 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="{{ back_url }}">{% translate "Cancel" %}</a>
        <button type="submit" class="btn btn-primary">{% translate "Confirm" %}</button>
      </div>
    </form>
  </div>
</div>

Das Buchungsfenster des Kalenders. Es verwendet die tatsächlichen Klassen eines modalen Fensters von [Bootstrap] ([modal], [modal-backdrop] ...), wird aber „fest verdrahtet“ sichtbar gemacht ([show d-block]) statt über das [JavaScript] von [Bootstrap]: Der Server entscheidet, es anzuzeigen, wenn die URL [&book=...] enthält. Das Schließen (mit dem X oder der Schaltfläche „Abbrechen“) entspricht dem Aufruf eines Links auf dieselbe Seite ohne diesen Parameter ([back_url]).

  • Zeile 26: [{% blocktranslate with time_range=booking.time_range %}]: ein übersetzter Text, der eine Variable enthält (Beispiel 22). In einem [blocktranslate] sind nur einfache Variablen erlaubt ([{{ time_range }}], nicht [{{ booking.time_range }}]): Die Klausel [with] erzeugt eine solche;
  • Zeilen 29–32: das Anti-CSRF-Token und das, was der Server wissen muss: der Arzt, der Tag und das Zeitfenster;
  • Zeilen 35–48: Ein Patient reserviert für sich selbst: sein Name, ohne Auswahlliste (und der Server ignoriert ein eventuelles Feld [clientId] ohnehin). Der Administrator und die Ärzte wählen den Patienten aus einer Liste; [required] und [autofocus]: Der Browser verlangt eine Auswahl und setzt den Cursor in die Liste.

11.18.1.6. templates/fragments/captcha.html

{% comment %}
  =========================================================================
  templates/fragments/captcha.html: das CAPTCHA der Authentifizierungsseite
  (siehe security/captchas.py). Es schützt sowohl die Anmeldung als auch den Zugang zur
  Kontoerstellung (Button "Create a patient account"). Es liest die Variable
  [captcha] der Seite.

  captcha.svg|safe: das SVG-Bild wird UNVERÄNDERT in die Seite eingefügt, ohne
  Maskierung. Das ist hier unbedenklich, weil dieses SVG vom Server selbst erzeugt wird
  und nichts vom Benutzer Stammendes enthält: bei Benutzereingaben würde man das NIEMALS
  tun.

  Das versteckte Feld captcha_id teilt dem Server mit, WELCHES CAPTCHA zu prüfen ist; die richtige
  Antwort wird dagegen nie an den Browser gesendet. "Another image" lädt einfach
  die Seite neu ({% url 'login' %}: die URL der Seite ohne ihre Parameter).
  =========================================================================
{% endcomment %}
{% load i18n %}
<div class="mb-3">
  <label class="form-label" for="captcha">{% translate "Type the characters shown in the image" %}</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="{% translate 'Anti-robot verification image' %}">{{ captcha.svg|safe }}</div>
    <a class="small" href="{% url 'login' %}">{% translate "Another image" %}</a>
  </div>
  <input type="hidden" name="captcha_id" 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">{% translate "Upper or lower case, it does not matter." %}</div>
</div>

Das CAPTCHA (Beispiel 27). [captcha.svg|safe] fügt das SVG-Bild unverändert ein, ohne es zu maskieren: Andernfalls würde der Browser seinen XML-Code anzeigen. Das ist hier unbedenklich, weil dieses SVG vom Server erzeugt wird und nichts vom Benutzer Geliefertes enthält: Bei Benutzereingaben würden wir das nie tun. Das versteckte Feld [captcha_id] teilt dem Server mit, welches CAPTCHA zu überprüfen ist; die Antwort selbst wird nie an den Browser gesendet. Der Link „Anderes Bild“ lädt die Anmeldeseite – und damit das CAPTCHA – neu. Die Attribute der Eingabefelder ([autocomplete="off"], [autocapitalize="off"], [spellcheck="false"]) verhindern, dass der Browser eine frühere Eingabe vorschlägt und dass die Tastatur des Telefons Buchstaben großschreibt oder die Rechtschreibung korrigiert.

11.18.2. Die Formularfelder

11.18.2.1. templates/forms/field.html

{% comment %}
  templates/forms/field.html: ein vollständiges Feld eines Formulars: Label,
  Eingabebereich, dann seine Fehlermeldung oder seine Hilfe (siehe Beispiel 18 und die
  Einstellung FORM_RENDERER). Der Eingabebereich wird durch die Methode flag des Formulars rot umrahmt (Klasse
  is-invalid) (siehe web/forms.py).
{% endcomment %}
<div class="mb-3">
  <label class="form-label" for="{{ field.id_for_label }}">{{ field.label }}</label>
  {{ field }}
  {% if field.errors %}<div class="invalid-feedback d-block" id="{{ field.auto_id }}_error">{% for error in field.errors %}{{ error }}{% if not forloop.last %}<br>{% endif %}{% endfor %}</div>{% endif %}
  {% if field.help_text and not field.errors %}<div class="form-text" id="{{ field.auto_id }}_helptext">{{ field.help_text }}</div>{% endif %}
</div>

Das Template für ein vollständiges Feld – das der Rendering-Engine [BootstrapRenderer] (Web-Schicht, weiter oben) – wie in Beispiel 18: die Beschriftung, das Eingabefeld ([{{ field }}], mit den vom Formular bereitgestellten CSS-Klassen), gefolgt von der Fehlermeldung oder, falls keine vorhanden ist, dem Hilfetext. Die Klassen [invalid-feedback] (die Meldung in Rot) und [form-text] (der Hilfetext in Grau) stammen aus [Bootstrap]; [d-block] zeigt die Meldung auch dann an, wenn das Eingabefeld ihr nicht unmittelbar vorausgeht. Ein Feld kann mehrere Fehler haben: Sie werden durch einen Zeilenumbruch getrennt ([forloop.last], Beispiel 14).

Die Bezeichner [..._error] und [..._helptext] sind nicht zufällig gewählt: Es sind die, auf die [Django] in den Attributen [aria-describedby] des Eingabefelds verweist, zusammen mit [aria-invalid] bei einem Feld mit Fehler. Ein Screenreader liest so die Fehlermeldung oder den Hilfetext zusammen mit dem Feld vor:

1
2
3
4
5
<div class="mb-3">
  <label class="form-label" for="id_first_name">First name</label>
  <input type="text" name="first_name" maxlength="20" class="form-control is-invalid" required aria-invalid="true" aria-describedby="id_first_name_error" id="id_first_name">
  <div class="invalid-feedback d-block" id="id_first_name_error">The first name is required.</div>
</div>

Der rote Rand ([is-invalid]) wurde von der Methode [flag] des Formulars hinzugefügt; [maxlength] und [required] von [Django], abhängig von den Optionen des Felds. Das Attribut [required] verhindert nicht, dass ein leeres Formular abgesendet wird: Die Formulare der Anwendung tragen das Attribut [novalidate] (siehe unten); die Validierung erfolgt durch den Server.

11.18.2.2. templates/macros.html

{% comment %}
  templates/macros.html: die benannten Fragmente der Formulare (siehe Beispiel 15).

  identity: die Identitätsfelder (Anrede, Vorname, Nachname), gemeinsam für drei
  Formulare: Arzt/Client des ADMIN, "Create a patient account" und "Manage my
  account". Es liest die Variable [form] der Seite, die es einbindet:
  {% include "macros.html#identity" %}.
{% endcomment %}
{% partialdef identity %}
  {{ form.title.as_field_group }}
  <div class="row g-3">
    <div class="col-sm-6">{{ form.first_name.as_field_group }}</div>
    <div class="col-sm-6">{{ form.last_name.as_field_group }}</div>
  </div>
{% endpartialdef %}

Ein benanntes Fragment ([{% partialdef %}], Beispiel 15), das von den drei Seiten verwendet wird, die ein „Person“-Formular anzeigen: die Identifikationsfelder, die Anrede, dann Vorname und Nachname nebeneinander (das Raster von [Bootstrap]: [row], [col-sm-6]). Jedes Feld wird von [as_field_group] (Beispiel 18) gerendert, das heißt vom Template [field.html]. Eine Seite fügt es mit [{% include "macros.html#identity" %}] ein: Das Fragment liest die Variable [form] von der Seite.

11.18.3. Die Seiten

11.18.3.1. templates/login.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/login.html: das Anmeldeformular (siehe web/views/auth.py).
  Ein gewöhnliches, von Hand geschriebenes HTML-<form>: der Browser selbst sendet Login,
  Passwort und CAPTCHA-Antwort per POST /login, ohne JavaScript. Bei einem
  Fehlschlag sendet der Server DIESE Seite zurück, mit dem bereits eingegebenen Login, einem NEUEN
  CAPTCHA und dem Fehler, den das Eltern-Template unten auf der Seite anzeigt.
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{% translate "Sign in" %}</h5>

      <form method="post" action="{% url 'login' %}">
        {% csrf_token %}
        <div class="mb-3">
          <label class="form-label" for="login">{% translate "Login" %}</label>
          {# autofocus: ein boolesches Attribut, geschrieben, wenn die Bedingung wahr ist. Der Cursor springt in das erste auszufüllende Feld #}
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="{{ login }}" required{% if not login %} autofocus{% endif %}>
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">{% translate "Password" %}</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required{% if login %} autofocus{% endif %}>
        </div>

        {% include "fragments/captcha.html" %}

        <button type="submit" class="btn btn-primary w-100">{% translate "Log in" %}</button>

        {% comment %}
          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 sendet (formaction). Der Server prüft dort das CAPTCHA
          oben, bevor er die Seite zur Kontoerstellung öffnet (siehe
          web/views/registration.py). formnovalidate: der Browser verlangt
          Login und Passwort nicht (für die Kontoerstellung unnötig). Enter in einem
          Feld löst immer den ERSTEN Button des Formulars aus, "Log in".
        {% endcomment %}
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="{% url 'registration_access' %}" formnovalidate>{% translate "Create a patient account" %}</button>
        <div class="form-text text-center">{% translate "To create an account, first type the characters shown in the image." %}</div>
      </form>

      <div class="text-muted small mt-3">
        <span>{% translate "Demo accounts (password = login):" %}</span>
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - <span>{% translate "ADMIN role: appointments + doctor and patient management" %}</span></li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{% translate "DOCTOR role: booking and cancelling appointments" %}</span></li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{% translate "USER role (patients): booking for themselves, managing their account" %}</span></li>
        </ul>
      </div>
    </div>
  </div>
</div>
{% endblock %}

Das Anmeldeformular, ein von Hand geschriebenes [<form>], wird per POST an [/login] gesendet. Das Tag [{% extends %}] steht, wie von der DTL verlangt, an erster Stelle im Template (Zeile 1); danach folgt der Kommentar.

  • Zeilen 24–30: Der eingegebene Login wird nach einem fehlgeschlagenen Versuch erneut angezeigt ([login]). Das Attribut [autofocus] setzt den Cursor in das erste auszufüllende Feld: den Benutzernamen, wenn er leer ist, andernfalls das Passwort (nach einem fehlgeschlagenen Anmeldeversuch oder nach der Erstellung eines Kontos). Ein boolesches Attribut ist entweder vorhanden oder nicht: [{% if not login %} autofocus{% endif %}];
  • Zeile 33: das CAPTCHA;
  • Zeilen 46–47: Die Schaltfläche „Patientenkonto erstellen“ ist kein Link, sondern eine zweite Schaltfläche, die dasselbe Formular an eine andere Adresse sendet (Schaltflächenattribut [formaction]). Der Server überprüft dort das CAPTCHA, bevor er die Seite zur Kontoerstellung öffnet ([registration.access]). [formnovalidate]: Der Browser verlangt keinen Benutzernamen und kein Passwort (Attribute [required]), da sie zum Erstellen eines Kontos nicht benötigt werden. Das Drücken der Eingabetaste in einem Feld löst immer die erste Schaltfläche zum Absenden des Formulars aus: Anmelden;
  • Zeilen 51–58: Demo-Konten zum Testen.

11.18.3.2. templates/schedule.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/schedule.html: die Hauptseite (siehe web/views/schedule.py).
  Drei Blöcke:
    1. die Auswahl des Arztes und des Tages;
    2. der Terminkalender;
    3. der Buchungsdialog (Fragment booking).
  Ein möglicher Fehler (ungültiges Datum, unbekannter Arzt) wird unten auf
  der Seite vom Eltern-Template angezeigt (Tag error_zone).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  {# 1. Auswahl des Arztes und des Tages: ein GET-Formular, das diese Seite einfach mit ?doctorId=...&day=... neu lädt #}
  <form method="get" action="{% url '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">{% translate "Doctor" %}</label>
        <select id="doctorId" name="doctorId" class="form-select" required>
          <option value="">{% translate "-- choose a doctor --" %}</option>
          {% for doctor in doctors %}
          <option value="{{ doctor.id }}"{% if doctor.selected %} selected{% endif %}>{{ doctor.label }}</option>
          {% endfor %}
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day">{% translate "Day" %}</label>
        <input id="day" name="day" type="date" class="form-control" value="{{ day }}" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100">{% translate "View schedule" %}</button>
      </div>
    </div>
  </form>

  {# Patient, der bereits einen bevorstehenden Termin hat: deshalb gibt es keinen Button "Book" #}
  {% if info %}
  <div class="alert alert-info">
    <span>{{ info }}</span>
    <a href="{% url 'area' %}" class="alert-link">{% translate "My area" %}</a>
  </div>
  {% endif %}

  {# 2. der Terminkalender #}
  {% if schedule %}
  <div class="card p-3">
    <h5>{% translate "Schedule for" %} {{ schedule.day }} - {{ schedule.doctor }}</h5>

    {% if schedule.rows %}
    <table class="table table-hover align-middle">
      <thead>
        <tr>
          <th>{% translate "Slot" %}</th>
          <th>{% translate "Status" %}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {% for row in schedule.rows %}
        <tr{% if row.bookable %} class="free-slot"{% endif %}>
          <td>{{ row.time_range }}</td>
          <td>
            {% comment %}
              [patient] ist nur gesetzt, wenn der Benutzer diesen Namen sehen darf
              (ADMIN, DOCTOR oder der Patient für SEINEN Termin) - andernfalls
              einfach "Booked"
            {% endcomment %}
            {% if row.free %}
            <span class="badge text-bg-success">{% translate "Free" %}</span>
            {% elif row.patient %}
            <span class="badge {% if row.me %}text-bg-primary{% else %}text-bg-secondary{% endif %}">{{ row.patient }}</span>
            {% else %}
            <span class="badge text-bg-secondary">{% translate "Booked" %}</span>
            {% endif %}
          </td>
          <td>
            {% comment %}
              die angezeigten Buttons wurden von der View festgelegt (bookable, appointment_id)
              gemäß der Rolle des Benutzers. "Book" ist ein einfacher Link: er
              öffnet diese Seite erneut mit dem Buchungsdialog dieses Zeitfensters
            {% endcomment %}
            {% if row.bookable %}
            <a class="btn btn-sm btn-outline-success" href="{{ row.book_url }}">{% translate "Book" %}</a>
            {% endif %}
            {# "Cancel" ÄNDERT Daten: es ist daher ein POST #}
            {% if row.appointment_id %}
            <form method="post" action="{% url 'schedule_cancel' %}" class="m-0"
                  data-confirmation="{% translate 'Cancel this appointment?' %}">
              {% csrf_token %}
              <input type="hidden" name="appointmentId" value="{{ row.appointment_id }}">
              <input type="hidden" name="doctorId" value="{{ doctor_id }}">
              <input type="hidden" name="day" value="{{ day }}">
              <button type="submit" class="btn btn-sm btn-outline-danger">{% translate "Cancel" %}</button>
            </form>
            {% endif %}
          </td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
    {% else %}
    <p class="text-muted mb-0">{% translate "This doctor has no time slots." %}</p>
    {% endif %}
  </div>
  {% else %}
  <p class="text-muted">{% translate 'Choose a doctor and a day, then click "View schedule".' %}</p>
  {% endif %}

  {# 3. der Buchungsdialog, nur wenn die URL &book=... enthält #}
  {% if booking %}
  {% include "fragments/booking.html" %}
  {% endif %}
{% endblock %}

Die Hauptseite. Drei Bereiche: die Auswahl eines Arztes und eines Tages, der Kalender und das Buchungsfenster.

  • Zeilen 17–36: Auswahl eines Arztes und eines Tages: ein GET-Formular (Beispiel 17), das die Seite mit [?doctorId=...&day=...] in der URL neu lädt. Der Tag ist ein Feld [type="date"]: Der Browser zeigt einen Kalender an und sendet das Datum im Format [yyyy-mm-dd], unabhängig davon, wie er es darstellt ([30/09/2026] auf Französisch); der Anfangswert ([value]) wird in demselben Format geschrieben;
  • Zeilen 39–44: für einen Patienten, der bereits einen bevorstehenden Termin hat, die Erklärung, warum es keine Schaltfläche „Buchen“ gibt, mit einem Link auf „Mein Bereich“;
  • Zeilen 70–76: der Status des Zeitfensters: Frei (in Grün), der Name des Patienten (in Blau bei einem vom angemeldeten Patienten gebuchten Termin, sonst in Grau) oder „Gebucht“. Das Template bestimmt nichts: [row.patient] wird nur angezeigt, wenn der Benutzer die Berechtigung hat, diesen Namen einzusehen;
  • Zeilen 84–86: „Buchen“ ist ein einfacher Link: Er öffnet die Seite erneut mit dem Buchungsfenster für dieses Zeitfenster ([row.book_url]). Er ändert nichts: Ein GET genügt;
  • Zeilen 88–97: „Stornieren“ ändert Daten: Es ist ein POST-Formular (Beispiel 21), mit seinem Anti-CSRF-Token, dem zu stornierenden Termin und den Angaben, um zur selben Seite zurückzukehren (der Arzt, der Tag). Das Attribut [data-confirmation] veranlasst das Skript der Seite, eine Bestätigung anzufordern; sein Text wird durch [{% translate %}] dargestellt, in einfache Anführungszeichen innerhalb des Attributs gesetzt, das seinerseits in doppelte Anführungszeichen eingeschlossen ist;
  • Zeilen 112–114: das Buchungsfenster, wenn die URL es verlangt (und wenn das Zeitfenster buchbar ist).

11.18.3.3. templates/persons/list.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/persons/list.html: die Liste der Ärzte ODER der Clients (ADMIN).
  Ein einziges Template für beide: die jeweils spezifischen Texte kommen in
  [texts] an, und [section] ("doctors" oder "clients") liefert den Anfang der Namen
  der Routen (siehe web/views/persons.py).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0">{{ texts.title }}</h4>
    <a class="btn btn-primary" href="{{ add_url }}">{{ texts.add }}</a>
  </div>

  <div class="card p-3">
    {% if persons %}
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{% translate "Title" %}</th>
          <th>{% translate "First name" %}</th>
          <th>{% translate "Last name" %}</th>
          <th>{% translate "Login" %}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {# person.account.login: das Konto, mit derselben Abfrage geladen (select_related) #}
        {% for person in persons %}
        <tr>
          <td>{{ person.title }}</td>
          <td>{{ person.first_name }}</td>
          <td>{{ person.last_name }}</td>
          <td><code>{{ person.account.login }}</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              {# section|add:"_edit": "doctors_edit", der Name der Route #}
              <a class="btn btn-sm btn-outline-primary"
                 href="{% url section|add:'_edit' person.id %}">{% translate "Edit" %}</a>
              {# data-confirmation: vor dem Absenden des Formulars öffnet sich ein Bestätigungsdialog (siehe static/js/app.js) #}
              <form method="post" action="{% url section|add:'_delete' person.id %}" class="m-0"
                    data-confirmation="{{ texts.confirm_delete }}">
                {% csrf_token %}
                <button type="submit" class="btn btn-sm btn-outline-danger">{% translate "Delete" %}</button>
              </form>
            </div>
          </td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
    {% else %}
    <p class="text-muted mb-0">{{ texts.empty }}</p>
    {% endif %}
  </div>
{% endblock %}

Die Liste der Ärzte oder Clients: Der jeweils spezifische Text steht in der Variablen [texts], und die Routennamen werden aus dem Namen des Abschnitts erzeugt: [section|add:'_edit'] ergibt [doctors_edit] oder [clients_edit] (der Filter [add] addiert zwei Zahlen oder, wie hier, verkettet zwei Zeichenketten). [{% url %}] akzeptiert somit als Routennamen einen berechneten Ausdruck, gefolgt von den Parametern der Route ([person.id]). [person.account.login]: der Login des Kontos, zusammen mit der Liste geladen (DAO-Schicht) und mit ihr im Cache abgelegt. Die Schaltfläche „Löschen“ ist ein POST-Formular mit Bestätigung.

11.18.3.4. templates/persons/form.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/persons/form.html: Erstellen ODER Aktualisieren eines Arztes oder
  eines Clients (ADMIN), mit dem Formular PersonForm.

  Wird die Eingabe abgelehnt (leeres Feld, Login bereits vergeben...), zeigt die View
  DIESE Seite erneut an, und das Template zeigt:
    - die bereits eingegebenen Werte (außer dem Passwort);
    - die fehlerhaften Felder rot umrahmt (Bootstrap-Klasse "is-invalid");
    - unter einem von der Validierung abgelehnten Feld seine Meldung;
    - die Fehlermeldung der Seite, UNTEN auf der Seite (Tag error_zone).
  Das Formular wird an die URL der Seite selbst gesendet (kein Attribut action).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{{ page_title }}</h5>

      <form method="post" novalidate>
        {% csrf_token %}
        {# Anrede, Vorname, Nachname: ein Fragment, das drei Formularen gemeinsam ist #}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        {# nie vorausgefüllt: das Passwort geht nie an den Browser zurück #}
        {{ form.password.as_field_group }}
        {# nur im Aktualisierungsmodus: die Version des Datensatzes in einem versteckten Feld (die optimistische Sperre) #}
        {% if form.version %}{{ form.version }}{% endif %}

        <div class="d-flex gap-2 mt-4">
          <button type="submit" class="btn btn-primary">{% translate "Save" %}</button>
          <a class="btn btn-secondary" href="{{ list_url }}">{% translate "Back to the list" %}</a>
        </div>
      </form>
    </div>
  </div>
</div>
{% endblock %}

Erstellung oder Änderung eines Arztes oder eines Clients mit dem Formular [PersonForm].

  • Zeile 24: ein POST-Formular ohne das Attribut [action]: Es wird an die URL der Seite selbst gesendet ([/doctors/add] oder [/doctors/3/edit]). [novalidate] deaktiviert beim Absenden des Formulars die Validierung des Browsers ([required], [maxlength] ...): Der Server führt die Validierung durch, und sein Ergebnis ist maßgeblich (Beispiel 19);
  • Zeile 27: Anrede, Vorname und Nachname über das Fragment [identity];
  • Zeilen 30–32: Benutzername und Passwort, die nie vorausgefüllt werden. Ihre Tooltips unterscheiden sich zwischen Erstellung und Änderung (abhängig vom Konstruktor des Formulars);
  • Zeile 34: nur für die Bearbeitung das versteckte Feld „version“ (das optimistische Sperren). [{{ form.version }}] erzeugt allein das Eingabefeld, ohne Beschriftung: [<input type="hidden" name="version" value="1" id="id_version">]. Bei der Erstellung hat das Formular kein Feld [version]: Die Variable ist leer, und der Test ergibt „falsch“.

Fehler des Formulars selbst, die kein Feld betreffen ([non_field_errors], Beispiel 19), müssen nicht angezeigt werden: Das Formular erzeugt keine, und ein ungültiges Anti-CSRF-Token wird vor der View abgewiesen (die 419-Seite).

11.18.3.5. templates/registration.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/registration.html: "Create a patient account" (öffentliche Seite, siehe
  web/views/registration.py), mit dem Formular RegistrationForm. Dieselben Identitäts-
  felder wie im ADMIN-Formular (Fragment identity), aber Login und
  Passwort sind erforderlich, mit Bestätigung. Hier KEIN CAPTCHA: diese Seite
  wird erst erreicht, nachdem das CAPTCHA der Authentifizierungsseite eingegeben wurde
  (Button "Create a patient account").
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{% translate "Create a patient account" %}</h5>
      <p class="text-muted small mb-3">{% translate "With this account you can book your own appointments." %}</p>

      <form method="post" action="{% url 'registration' %}" novalidate>
        {% csrf_token %}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        {# das Passwort und seine Bestätigung, nebeneinander #}
        <div class="row g-3">
          <div class="col-sm-6">{{ form.password.as_field_group }}</div>
          <div class="col-sm-6">{{ form.confirmation.as_field_group }}</div>
        </div>

        <div class="d-flex gap-2 mt-3">
          <button type="submit" class="btn btn-primary">{% translate "Create my account" %}</button>
          <a class="btn btn-secondary" href="{% url 'login' %}">{% translate "Back to login" %}</a>
        </div>
      </form>
    </div>
  </div>
</div>
{% endblock %}

Erstellung eines Patientenkontos: die Identitätsfelder, gefolgt von Benutzername, Passwort und Passwortbestätigung – allesamt Pflichtfelder – nebeneinander (Zeilen 28–31). Der Hilfetext zum Passwort nennt die Mindestlänge: „Mindestens 6 Zeichen.“ Hier gibt es kein CAPTCHA: Diese Seite ist nur erreichbar, nachdem das CAPTCHA der Anmeldeseite eingegeben wurde.

11.18.3.6. templates/area.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/area.html: "My area": die Startseite des Patienten (Rolle USER),
  die direkt nach der Anmeldung angezeigt wird.
    - zwei Optionen: [Manage my account] und [View a schedule];
    - sein bevorstehender Termin, falls vorhanden, mit der Möglichkeit, ihn zu stornieren.
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  <h4 class="mb-3">{% blocktranslate %}Hello {{ patient }}{% endblocktranslate %}</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="{% url 'account' %}">
        <h5 class="mb-1">{% translate "Manage my account" %}</h5>
        <span class="text-muted">{% translate "Change my details or password, or delete my account." %}</span>
      </a>
    </div>
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="{% url 'schedule' %}">
        <h5 class="mb-1">{% translate "View a schedule" %}</h5>
        <span class="text-muted">{% translate "See a doctor's schedule and book a slot." %}</span>
      </a>
    </div>
  </div>

  <div class="card p-3">
    <h5>{% translate "My appointment" %}</h5>
    {% comment %}
      normalerweise nur einer (Regel „ein bevorstehender Termin zur Zeit"), die Seite
      kann aber mehrere anzeigen. {% for %} ... {% empty %}: eine Schleife und das, was
      angezeigt wird, wenn die Liste leer ist; forloop.last: letztes Element?
    {% endcomment %}
    {% for appointment in appointments %}
    <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{% if not forloop.last %} border-bottom{% endif %}">
      <div>
        <div class="fw-semibold">{{ appointment.day }}, {{ appointment.time_range }}</div>
        <div class="text-muted">
          <span>{{ appointment.doctor }}</span> -
          <a href="{{ appointment.schedule_url }}">{% translate "see in the schedule" %}</a>
        </div>
      </div>
      <form method="post" action="{% url 'area_cancel' %}" class="m-0"
            data-confirmation="{% translate 'Cancel this appointment?' %}">
        {% csrf_token %}
        <input type="hidden" name="appointmentId" value="{{ appointment.id }}">
        <button type="submit" class="btn btn-outline-danger">{% translate "Cancel this appointment" %}</button>
      </form>
    </div>
    {% empty %}
    <p class="text-muted mb-0">{% translate "You have no upcoming appointment." %}</p>
    {% endfor %}
  </div>
{% endblock %}

„Mein Bereich“, die Startseite des Patienten: zwei große Karten („Mein Konto verwalten“, „Einen Terminkalender ansehen“) und sein bevorstehender Termin.

  • Zeile 13: [{% blocktranslate %}Hello {{ patient }}{% endblocktranslate %}]: ein übersetzter Text, der eine Variable enthält ([Bonjour %(patient)s] im französischen Wörterbuch);
  • Zeilen 37–55: [{% for %}] ... [{% empty %}] (Beispiel 14) ist eine Schleife, gefolgt von dem, was bei einer leeren Liste angezeigt wird. Normalerweise hat ein Patient höchstens einen bevorstehenden Termin; die Seite kann jedoch mehrere Termine anzeigen. [forloop.last] (Beispiel 14): Das letzte Element hat kein Trennzeichen;
  • Zeilen 46–51: Jeder Termin hat ein Stornierungsformular (POST, mit Bestätigung), das nur seine ID sendet: Der Server überprüft, ob er dem angemeldeten Patienten gehört.

11.18.3.7. templates/account.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/account.html: "Manage my account" (Rolle USER). Zwei unabhängige
  Formulare auf derselben Seite:
    1. die Aktualisierung (Identität, Login, optionales neues Passwort), mit
       dem Formular MyAccountForm;
    2. das Löschen des Kontos, das auch seine Termine storniert: ein
       von Hand geschriebenes Formular.
  Beide verlangen das AKTUELLE Passwort (Feld current_password).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    {# 1. Aktualisierung; novalidate: der SERVER validiert (siehe Beispiel 19) #}
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3">{% translate "Manage my account" %}</h5>

      <form method="post" action="{% url 'account' %}" novalidate>
        {% csrf_token %}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        <div class="row g-3">
          <div class="col-sm-6">{{ form.password.as_field_group }}</div>
          <div class="col-sm-6">{{ form.confirmation.as_field_group }}</div>
        </div>
        {{ form.current_password.as_field_group }}
        {# die Version des Datensatzes: ein verstecktes Feld (die optimistische Sperre) #}
        {{ form.version }}

        <div class="d-flex gap-2 mt-4">
          <button type="submit" class="btn btn-primary">{% translate "Save" %}</button>
          <a class="btn btn-secondary" href="{% url 'area' %}">{% translate "Back to my area" %}</a>
        </div>
      </form>
    </div>

    {% comment %}
      2. Löschen. Das Passwortfeld hat denselben NAMEN wie das des ersten
      Formulars (current_password), aber eine andere id: zwei Elemente derselben
      Seite dürfen nicht dieselbe id haben
    {% endcomment %}
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">{% translate "Delete my account" %}</h5>
      <p class="text-muted small">{% translate "Your account will be permanently deleted, together with all your appointments." %}</p>
      <form method="post" action="{% url 'account_delete' %}" class="d-flex flex-wrap gap-2 align-items-end"
            data-confirmation="{% translate 'Permanently delete your account? Any appointment you have will be cancelled.' %}">
        {% csrf_token %}
        <div class="flex-grow-1">
          <label class="form-label" for="delete_password">{% translate "Current password" %}</label>
          <input id="delete_password" name="current_password" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger">{% translate "Delete my account" %}</button>
      </form>
    </div>

  </div>
</div>
{% endblock %}

„Mein Konto verwalten“: zwei voneinander unabhängige Formulare auf derselben Seite.

  • Zeilen 20–42: die Änderung mit dem Formular [MyAccountForm]: die Identitätsfelder, der Login, das neue Passwort und seine Bestätigung (optional), das aktuelle Passwort (erforderlich) und das versteckte Feld „version“;
  • Zeilen 49–62: das Löschen des Kontos, ein von Hand geschriebenes Formular mit einem eigenen Feld für das aktuelle Passwort und einem Bestätigungsfeld. Das Feld hat denselben Namen wie das im ersten Formular ([current_password]), aber eine andere ID: Zwei Elemente einer Seite dürfen nicht dieselbe ID haben, wie das Attribut [for] eines Labels vorgibt. Die beiden Formulare sind unabhängig: Der Browser sendet nur die Felder des Formulars, dessen Schaltfläche angeklickt wurde.

11.18.3.8. templates/error.html

{% extends "layout.html" %}
{% comment %}
  templates/error.html: die Fehlerseite (400, 403, 404, 405, 419, 500...),
  erstellt von web/views/errors.py.
{% endcomment %}
{% load i18n %}

{% 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">{{ code }}</h1>
      <p class="lead">{{ message }}</p>
      <div><a class="btn btn-primary" href="{% url 'home' %}">{% translate "Back to the home page" %}</a></div>
    </div>
  </div>
</div>
{% endblock %}

Die Fehlerseite, erzeugt von [web/views/errors.py]: der HTTP-Code, die Meldung und ein Link auf die Startseite ([/], die auf die Startseite der Rolle oder auf die Anmeldeseite weiterleitet). Sie erweitert wie die anderen Seiten das Eltern-Template: Die Navigationsleiste, einschließlich des Benutzermenüs, ist ebenfalls enthalten.

11.19. Statische Dateien

Der Ordner [static] enthält die Dateien, die der Server unverändert sendet (Beispiel 15): [Bootstrap] ([lib/bootstrap], nur das Stylesheet und seine Lizenz), ein Stylesheet und ein Skript. In der Entwicklung liefert der [Django]-Server sie selbst aus (Anwendung [django.contrib.staticfiles]); in der Produktion werden sie nach [var/static] durch den Befehl [collectstatic] kopiert und vom Webserver ausgeliefert („Ein Produktionsserver“).

11.19.1. static/css/styles.css

/* =========================================================================
   static/css/styles.css - ein paar Einstellungen auf Basis von Bootstrap
   (dieselben wie in den anderen Versionen 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: ist die Seite höher als das Fenster (ein
   Terminkalender mit 12 Zeitfenstern zum Beispiel), bleibt der Bereich am unteren Rand des
   Fensters haften, statt unterhalb des sichtbaren Bereichs zu verschwinden - ohne je
   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 beiden großen Optionen der Seite „Mein Bereich“ 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, 150 x 50 Pixel) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}

Einige zusätzliche Einstellungen für [Bootstrap], dieselben wie in den anderen Versionen der Anwendung.

  • Zeilen 10–12: Ein buchbares Zeitfenster im Kalender wird beim Überfahren mit der Maus grün;
  • Zeilen 23–33: Der Fehlerbereich am Seitenende hat einen hellrosa Hintergrund. [position: sticky] mit [bottom: 1rem]: Ist die Seite höher als das Fenster (ein Kalender mit 12 Zeitfenstern), bleibt der Bereich am unteren Fensterrand verankert, statt unter dem Scrollbalken zu verschwinden; ist die Seite kurz, bleibt er an seinem Platz, ohne etwas zu verdecken. [z-index]: Er erscheint über dem grauen Hintergrund des Buchungsfensters;
  • Zeilen 36–43: die beiden großen Karten von „Mein Bereich“, die aufleuchten, wenn die Maus darüberfährt;
  • Zeilen 46–50: das CAPTCHA-Bild, mit einem Rand.

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 „Sind Sie sicher?“
// (der Dialog selbst steht in der Seite: templates/fragments/confirmation.html).
// Ist JavaScript deaktiviert, wird das Formular einfach ohne
// Bestätigung gesendet - nichts geht kaputt (Prinzip „Progressive Enhancement“).
//
// Warum nicht window.confirm()? Seine Box lässt sich nicht gestalten, und seine
// Schaltflächen 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, dem beim Schließen der Fokus zurückgegeben wird

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (und nicht innerHTML): Die Meldung wird als TEXT angezeigt,
    // nie als HTML interpretiert
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // der Fokus geht auf „No“: Ein unbedachtes Drücken der Eingabetaste 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 Schaltflächen 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ätigungsanfrage
      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 einzige [JavaScript] der Anwendung – das aus Beispiel 21 – mit einigen Ergänzungen. Die gesamte Anwendung funktioniert ohne [JavaScript]: Dieses Skript bietet zusätzlichen Komfort, indem es vor dem Absenden eines Formulars mit dem Attribut [data-confirmation] eine Bestätigung einholt. Ist [JavaScript] deaktiviert, wird das Formular ohne Bestätigung abgesendet: Nichts geht kaputt (Prinzip der progressiven Verbesserung).

  • Zeilen 15–19: Das Skript ist eine Funktion, die sofort nach ihrer Definition aufgerufen wird ([(() => { ... })()]); ihre Variablen sind für den Rest der Seite nicht sichtbar. Ohne Bestätigungsfenster auf der Seite tut es nichts;
  • Zeilen 26–35: Öffnen des Fensters: Das Formular, das bei Bestätigung durch den Benutzer abgesendet wird, wird gespeichert, und die Meldung des Formulars wird im Fenster angezeigt. [textContent], nicht [innerHTML]: Die Meldung wird als Text angezeigt und nie als HTML interpretiert. Der Fokus wechselt auf die Schaltfläche „Nein“: Versehentliches Drücken der Eingabetaste löscht nichts;
  • Zeilen 37–43: Schließen des Fensters; der Fokus kehrt zu dem Element zurück, das ihn zuvor hatte;
  • Zeilen 46–51: Das Absenden jedes zu bestätigenden Formulars wird abgefangen ([preventDefault] verhindert es), und das Fenster öffnet sich. Das Ereignis [submit] tritt erst nach den Validierungen des Browsers auf: Das aktuelle Passwort, das im Formular zum Löschen des Kontos erforderlich ist ([required]), wird vor der Rückfrage verlangt;
  • Zeilen 54–67: die Schaltflächen im Fenster. Ein einziger Handler für das gesamte Fenster: [closest('[data-action]')] findet die angeklickte Schaltfläche oder das Element, das sie enthält; [?.] sorgt dafür, dass [undefined] keinen Fehler verursacht, wenn keines passt. „Ja“ sendet das Formular über [form.submit()] ab, was das Ereignis [submit] nicht auslöst: Es erscheint keine neue Bestätigungsabfrage. Ein Klick auf den ausgegrauten Hintergrund außerhalb des Fensters schließt es;
  • Zeilen 71–86: die Tastatur. Esc schließt das Fenster; die Tabulatortaste bewegt den Fokus von einer Schaltfläche zur anderen, ohne das Fenster zu verlassen (andernfalls würde er auf die ausgegraute Seite dahinter wechseln): Das erwarten Benutzer, die mit der Tastatur und mit Screenreadern navigieren.