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 im 20-Minuten-Takt); ein Termin besteht aus einem Tag, einem Zeitfenster und einem Client (einem Patienten). Sie verwendet die Datenbank- und Geschäftsschichten des [NestJS]-Servers aus den Kursen „Ein Client-Server-Beispiel mit Flutter / NestJS“ und „Ein Client-Server-Beispiel mit Angular/NestJS“ und zeigt dieselben Seiten wie der [Angular]-Client; statt jedoch JSON an einen [JavaScript]- oder [Flutter]-Client auszuliefern, erzeugt sie ihre eigenen HTML-Seiten.

Drei Benutzer-Rollen teilen sich die Anwendung:

Rolle
Wer
Was sie tun können
ADMIN
Der Administrator ([admin])
Terminkalender einsehen, Termine für jeden Patienten vereinbaren und stornieren; Ärzte und Clients verwalten (auflisten, hinzufügen, ändern, löschen)
DOCTOR
Ärzte
Terminkalender einsehen, Termine für jeden Patienten vereinbaren und stornieren
USER
Clients (Patienten)
Terminkalender einsehen, ohne die Namen anderer Patienten zu sehen; einen Termin für sich selbst vereinbaren; ihren Termin stornieren; ihr Konto verwalten; ein Konto erstellen

Wichtige Verwaltungsregeln:

  • Keine Termine in der Vergangenheit;
  • ein Zeitfenster kann pro Tag nur einmal gebucht werden;
  • ein Patient darf jeweils nur einen bevorstehenden Termin haben;
  • Zwei Ärzte (oder zwei Clients) dürfen nicht denselben Vor- und Nachnamen haben, und ein Benutzername gehört zu genau einem Konto;
  • Ein Arzt mit Terminen kann nicht gelöscht werden; ein Client wird zusammen mit seinen Terminen gelöscht;
  • Die Anmeldeseite ist gegen Bots geschützt (CAPTCHA, begrenzte Versuche), und für das Erstellen eines Client-Kontos muss zuvor auf dieser Seite das CAPTCHA gelöst werden.

11.2. Verwendung der Anwendung

11.2.1. Die Anmeldeseite

Image

Die Seite enthält zwei Schaltflächen: Anmelden und Patientenkonto erstellen. Bei beiden müssen die im Bild gezeigten Zeichen eingegeben werden. Die Schaltflächen FR / EN wechseln die Sprache:

Image

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

Image

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

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

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 des Patienten fragt:

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 Dashboard des Patienten

Ein Patient (Rolle USER) gelangt zu Mein Bereich: seinem bevorstehenden Termin, den er stornieren kann, sowie Links zur Verwaltung seines Kontos und zum Kalender:

Image

Im Kalender sieht er seinen eigenen Termin, aber nicht die Namen anderer Patienten (Gebucht). Da er bereits einen bevorstehenden Termin hat, kann er keinen weiteren vereinbaren:

Image

Ein Patient ohne Termin kann ein freies Zeitfenster für sich selbst buchen:

Image

Kontoverwaltung: seine Angaben ändern, 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, erhält eine Fehlerseite:

Image

11.2.4. Verwaltung von Ärzten und Clients

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 vorhandenen Arztes übereinstimmt, wird abgelehnt:

Image

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

Image

11.2.5. Erstellen eines Patientenkontos

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

Image

Image

11.3. Installation und Ausführung

Der Anwendungsordner:

rdvmedecins-nestjs-html/
├── database/
│   ├── README.md
│   └── dbrdvmedecins2.sql
├── i18n/
│   ├── en.json
│   └── fr.json
├── public/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── src/
│   ├── auth/
│   │   ├── README.md
│   │   ├── attempt-limiter.service.ts
│   │   ├── auth.constants.ts
│   │   ├── auth.controller.ts
│   │   ├── auth.module.ts
│   │   ├── auth.service.ts
│   │   ├── captcha.service.ts
│   │   ├── jwt-auth.guard.ts
│   │   ├── jwt.strategy.ts
│   │   ├── registration-pass.service.ts
│   │   ├── roles.decorator.ts
│   │   └── roles.guard.ts
│   ├── business/
│   │   ├── README.md
│   │   ├── business.exception.ts
│   │   ├── business.interface.ts
│   │   ├── business.service.ts
│   │   └── dates.ts
│   ├── config/
│   │   ├── README.md
│   │   ├── database.config.ts
│   │   └── paths.ts
│   ├── domain/
│   │   ├── README.md
│   │   ├── doctor-day-schedule.ts
│   │   └── doctor-day-slot.ts
│   ├── entities/
│   │   ├── README.md
│   │   ├── abstract.entity.ts
│   │   ├── appointment.entity.ts
│   │   ├── client.entity.ts
│   │   ├── doctor.entity.ts
│   │   ├── person.entity.ts
│   │   ├── slot.entity.ts
│   │   └── user.entity.ts
│   ├── repositories/
│   │   ├── README.md
│   │   ├── appointment.repository.ts
│   │   ├── client.repository.ts
│   │   ├── doctor.repository.ts
│   │   ├── slot.repository.ts
│   │   └── user.repository.ts
│   ├── web/
│   │   ├── controllers/
│   │   │   ├── clients.controller.ts
│   │   │   ├── doctors.controller.ts
│   │   │   ├── language.controller.ts
│   │   │   ├── patient-area.controller.ts
│   │   │   ├── persons.controller.ts
│   │   │   ├── registration.controller.ts
│   │   │   └── schedule.controller.ts
│   │   ├── helpers/
│   │   │   ├── dates.helper.ts
│   │   │   ├── form.helper.ts
│   │   │   └── patient.helper.ts
│   │   ├── models/
│   │   │   └── person-form.dto.ts
│   │   ├── views/
│   │   │   └── handlebars-helpers.ts
│   │   ├── README.md
│   │   ├── application-model.service.ts
│   │   ├── html-exception.filter.ts
│   │   ├── i18n.ts
│   │   ├── view-context.ts
│   │   └── view-user.interceptor.ts
│   ├── README.md
│   ├── app.module.ts
│   └── main.ts
├── views/
│   ├── account/
│   │   └── registration.hbs
│   ├── partials/
│   │   ├── booking.hbs
│   │   ├── captcha.hbs
│   │   ├── confirmation.hbs
│   │   ├── errors.hbs
│   │   ├── flash.hbs
│   │   ├── navbar.hbs
│   │   └── personFields.hbs
│   ├── patient/
│   │   ├── account.hbs
│   │   └── area.hbs
│   ├── persons/
│   │   ├── form.hbs
│   │   └── list.hbs
│   ├── README.md
│   ├── error.hbs
│   ├── layout.hbs
│   ├── login.hbs
│   └── schedule.hbs
├── .env.example
├── README.md
├── nest-cli.json
├── package-lock.json
├── package.json
└── tsconfig.json

Die Dateien [README.md] beschreiben den Zweck der einzelnen Ordner; sie werden hier nicht wiedergegeben. So installieren und starten Sie die Anwendung:

  • Erstellen Sie die Datenbank [dbrdvmedecins2], indem Sie das Skript [database/dbrdvmedecins2.sql] ausführen (siehe Anhänge);
  • installieren Sie in einem Konsolenfenster, das im Anwendungsordner geöffnet ist, die Abhängigkeiten: [npm install];
  • benennen Sie die Datei [.env.example] in [.env] um und passen Sie darin die Verbindungseinstellungen an die von [MySQL] an;
  • starten Sie die Anwendung: [npm run start:dev], und öffnen Sie dann [http://localhost:8081].

Die Passwörter der Demokonten entsprechen ihren Benutzernamen: [admin] (ADMIN), [pelissier], [tatou], [dupont] (DOCTOR), [martin], [durand], [bistrou], [german] (USER). Beim Start:

[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [NestFactory] Starting Nest application...
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] TypeOrmModule dependencies initialized +84ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] PassportModule dependencies initialized +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] JwtModule dependencies initialized +1ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] TypeOrmCoreModule dependencies initialized +58ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] TypeOrmModule dependencies initialized +1ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] TypeOrmModule dependencies initialized +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] AuthModule dependencies initialized +1ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [InstanceLoader] AppModule dependencies initialized +3ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RoutesResolver] ScheduleController {/schedule}: +15ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/schedule, GET} route +3ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/schedule/book, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/schedule/cancel, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RoutesResolver] DoctorsController {/doctors}: +1ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/doctors, GET} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/doctors/add, GET} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/doctors/add, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/doctors/:id/edit, GET} route +1ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/doctors/:id/edit, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/doctors/:id/delete, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RoutesResolver] ClientsController {/clients}: +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/clients, GET} route +1ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/clients/add, GET} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/clients/add, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/clients/:id/edit, GET} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/clients/:id/edit, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RouterExplorer] Mapped {/clients/:id/delete, POST} route +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LOG [RoutesResolver] LanguageController {/language}: +0ms
[Nest] 14248  - 09/23/2026, 4:23:55 PM     LO

(die von [TypeORM] angezeigten SQL-Befehle wurden entfernt)

11.4. Architektur der Anwendung

Image

  • [src/main.ts] konfiguriert die Anwendung: View-Engine, statische Dateien, Cookies, Exception-Filter;
  • [src/auth]: Authentifizierung, Token (JWT), Rollen, CAPTCHA und Begrenzung der Versuche;
  • [src/web]: die Web-Schicht. Ihre Controller ([src/web/controllers]) laufen alle über einen einzigen Service, [ApplicationModelService], der die Listen der Ärzte und Clients im Speicher hält und die übrigen Anfragen an die Geschäftsschicht weiterleitet;
  • [src/business]: die Geschäftsregeln;
  • [src/repositories]: die DAO-Schicht, eine Klasse pro Tabelle;
  • [src/entities]: die [TypeORM]-Entitäten; [src/domain]: die Kalenderobjekte, die von der Geschäftsschicht berechnet werden;
  • [views]: die [Handlebars]-Views; [i18n]: die Wörterbücher; [public]: das Stylesheet und das Seitenskript.

Der weitere Text kommentiert alle Dateien, von den unteren Schichten (Datenbank) bis zu den oberen Schichten (Views).

11.5. Die Datenbank

Die Datei [database/dbrdvmedecins2.sql]:

-- =========================================================================
-- Datenbank [dbrdvmedecins2] - MySQL 8
--
-- Weiterentwicklung von [dbrdvmedecins]:
--   1. die Tabellen [doctors] und [clients] erhalten eine Spalte [user],
--      Fremdschlüssel auf users(id): jeder Arzt und jeder Client ist
--      nun auch ein Benutzer, der sich anmelden kann;
--   2. eine dritte Rolle kommt hinzu: DOCTOR (zusätzlich zu ADMIN und USER);
--   3. das Skript legt für jeden Arzt (Rolle DOCTOR)
--      und für jeden Client (Rolle USER) eine Zeile in [users] an:
--        - login        = Nachname in Kleinbuchstaben
--        - password     = Nachname in Kleinbuchstaben, mit bcrypt gehasht (10 Runden)
--        - Anzeigename  = Vorname + Nachname
--
--   4. Eindeutigkeitsbedingungen, alle BENANNT (die NestJS-Anwendung erkennt
--      den Namen der verletzten Bedingung in der MySQL-Fehlermeldung):
--        - unq_users_login                   : ein Login gehört zu nur einem Konto;
--        - unq_doctors_first_name_last_name  : zwei Ärzte dürfen nicht denselben
--                                              Vor- und Nachnamen haben;
--        - unq_clients_first_name_last_name  : dasselbe für die Clients.
--      Achtung: Die Kollation utf8mb4_unicode_ci vergleicht ohne Rücksicht auf
--      Groß-/Kleinschreibung und Akzente - "Hélène DUPONT" und "helene dupont"
--      gelten daher als identisch.
--
-- Die Tabelle [users] muss nun VOR [doctors] und [clients] angelegt
-- (diese verweisen auf sie) und NACH ihnen gelöscht werden.
-- =========================================================================

-- bei jedem Lauf 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 beim Löschen: von den „Kind“-Tabellen zu den „Eltern“-Tabellen
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;

-- -------------------------------------------------------------------------
-- Tabelle [users]: die Benutzer, die sich an der Anwendung anmelden dürfen
-- -------------------------------------------------------------------------
CREATE TABLE users (
  id       INT AUTO_INCREMENT PRIMARY KEY,
  version  INT NOT NULL DEFAULT 0,
  login    VARCHAR(30) NOT NULL,                 -- login identifier
  password VARCHAR(100) NOT NULL,                -- HASHED password (bcrypt) - never in clear
  name     VARCHAR(40) NOT NULL,                 -- name displayed once logged in
  role     VARCHAR(10) NOT NULL,                 -- 'ADMIN', 'DOCTOR' or 'USER'
  -- ein Login darf nur zu einem Konto gehören
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- Tabelle [doctors]: die Ärzte der Praxis
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
  id         INT AUTO_INCREMENT PRIMARY KEY,   -- primary key (technical identifier)
  version    INT NOT NULL DEFAULT 0,            -- row version number (optimistic lock)
  title      VARCHAR(5)  NOT NULL,              -- Melle, Mme, Mr
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- ein Konto pro Arzt und ein Arzt pro Konto
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- zwei Ärzte dürfen nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- Tabelle [clients]: die Patienten der Ärzte
-- -------------------------------------------------------------------------
CREATE TABLE clients (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  title      VARCHAR(5)  NOT NULL,
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- ein Konto pro Client und ein Client pro Konto
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- zwei Clients dürfen nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- Tabelle [slots]: die Zeitfenster jedes Arztes
-- -------------------------------------------------------------------------
CREATE TABLE slots (
  id           INT AUTO_INCREMENT PRIMARY KEY,
  version      INT NOT NULL DEFAULT 0,
  doctor_id    INT NOT NULL,                     -- foreign key -> doctors(id)
  start_hour   INT NOT NULL,                     -- start hour of the slot
  start_minute INT NOT NULL,                     -- start minute of the slot
  end_hour     INT NOT NULL,                     -- end hour of the slot
  end_minute   INT NOT NULL,                     -- end minute of the slot
  CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);

-- -------------------------------------------------------------------------
-- Tabelle [appointments]: die von den Clients gebuchten Termine
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  day        DATE NOT NULL,                      -- day of the appointment
  slot_id    INT NOT NULL,                       -- foreign key -> slots(id)
  client_id  INT NOT NULL,                       -- foreign key -> clients(id)
  CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
  CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
  -- dasselbe Zeitfenster 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 DOCTOR-Konto pro Arzt, ein USER-Konto pro Client
--   (das Demokonto user/user gibt es nicht mehr: ein USER-Konto ist
--   jetzt IMMER das Konto eines Clients, 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'));

-- Zeitfenster von Arzt PELISSIER (doctor_id = 1): von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- Zeitfenster von Arzt TATOU (doctor_id = 2): von 14:00 bis 18:00 Uhr in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- ein bereits gebuchter Termin, um ein belegtes Zeitfenster gleich im Terminkalender zu sehen
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);

Kommentieren wir dieses Skript:

  • Zeile 30: Wie in Beispiel 28 ignoriert die Kollation [utf8mb4_unicode_ci] bei Vergleichen Groß- und Kleinschreibung sowie Akzente;
  • Zeilen 34–38: Die Tabellen werden von den „untergeordneten“ Tabellen zu den „übergeordneten“ Tabellen gelöscht: Eine Tabelle, auf die ein Fremdschlüssel verweist, kann nicht vor den Tabellen gelöscht werden, die auf sie verweisen;
  • Zeilen 43–52: Benutzerkonten. [password] enthält den bcrypt-Hash des Passworts (siehe Beispiel 25). Zeile 51: Ein Benutzername ist eindeutig;
  • Zeilen 57–69: Ärzte. Jeder hat ein Konto (Spalte [user], Fremdschlüssel auf [users], Zeile 64). Der Name [user] ist ein reserviertes Wort in [MySQL]: Er steht in Backticks. Zeile 66: Ein Konto gehört zu genau einem Arzt; Zeile 68: Keine zwei Ärzte dürfen denselben Vor- und Nachnamen haben;
  • Zeilen 74–86: die Clients, nach demselben Schema;
  • Zeilen 91–100: die Zeitfenster jedes Arztes (Beginn und Ende in Stunden und Minuten);
  • Zeilen 105–115: die Termine: ein Tag, ein Zeitfenster, ein Client. Zeile 114: Ein Zeitfenster wird pro Tag nur einmal reserviert;
  • Zeilen 127–137: die Demokonten; das Passwort jedes Kontos ist sein Benutzername;
  • Zeilen 141–144: Die Spalte [user] jedes Arztes wird über eine Unterabfrage auf den Benutzernamen ermittelt, statt die erzeugten Kennungen vorauszusetzen;
  • Zeilen 167–168: ein Termin am selben Tag ([CURDATE()]), um sofort ein gebuchtes Zeitfenster zu zeigen.

11.6. Projektkonfiguration

Die Datei [package.json]:

{
  "name": "rdvmedecins-nestjs-html",
  "version": "1.0.0",
  "description": "NestJS web application (HTML pages generated server-side) for booking medical appointments [RdvMedecins] - database [dbrdvmedecins2], roles ADMIN / DOCTOR / USER",
  "private": true,
  "license": "UNLICENSED",
  "scripts": {
    "build": "nest build",
    "start": "nest start",
    "start:dev": "nest start --watch --watchAssets",
    "start:debug": "nest start --debug --watch --watchAssets",
    "start:prod": "node dist/main"
  },
  "dependencies": {
    "@nestjs/common": "^10.4.0",
    "@nestjs/core": "^10.4.0",
    "@nestjs/jwt": "^10.2.0",
    "@nestjs/passport": "^10.0.3",
    "@nestjs/platform-express": "^10.4.0",
    "@nestjs/typeorm": "^10.0.2",
    "bcryptjs": "^3.0.3",
    "bootstrap": "^5.3.3",
    "class-transformer": "^0.5.1",
    "class-validator": "^0.14.1",
    "cookie-parser": "^1.4.7",
    "dotenv": "^17.4.2",
    "hbs": "^4.2.0",
    "mysql2": "^3.11.0",
    "passport-jwt": "^4.0.1",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.1",
    "svg-captcha": "^1.4.0",
    "typeorm": "^0.3.20"
  },
  "devDependencies": {
    "@nestjs/cli": "^10.4.5",
    "@types/bcryptjs": "^2.4.6",
    "@types/cookie-parser": "^1.4.7",
    "@types/express": "^4.17.21",
    "@types/node": "^20.14.0",
    "@types/passport-jwt": "^4.0.1",
    "typescript": "^5.5.0"
  }
}
  • Zeilen 7–13: die [npm run ...]-Befehle. [start:dev] startet die Anwendung im „Watch“-Modus: Bei jeder Änderung wird der Code neu kompiliert und der Server neu gestartet; die Option [--watchAssets] überwacht auch Dateien, die kein Code sind;
  • Zeilen 14–34: die Bibliotheken der Anwendung, die allesamt in den Beispielen behandelt werden. [dotenv] liest die Datei [.env]; [mysql2] ist der [MySQL]-Treiber, den [TypeORM] verwendet; [reflect-metadata] und [rxjs] werden von [NestJS] benötigt;
  • Zeilen 35–43: Entwicklungswerkzeuge: das Werkzeug [nest], der [TypeScript]-Compiler und die Typdeklarationen ([@types/...]) für in [JavaScript] geschriebene Bibliotheken.

Die Datei [tsconfig.json]:

{
  "compilerOptions": {
    "module": "commonjs",
    "declaration": false,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "target": "ES2022",
    "lib": ["ES2022"],
    "sourceMap": true,
    "outDir": "./dist",
    "baseUrl": "./",
    "incremental": true,
    "skipLibCheck": true,
    "strictNullChecks": true,
    "noImplicitAny": false,
    "strictBindCallApply": false,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": false
  }
}

Diese Datei wird vom Werkzeug [nest] für ein neues Projekt erzeugt. Im Vergleich zu den Beispielen: Zeile 5: Kommentare werden nicht in den kompilierten Code übernommen; Zeile 14: Es werden nur geänderte Dateien neu kompiliert; Zeile 17: Eine Variable ohne expliziten oder ableitbaren Typ wird akzeptiert (sie hat dann den Typ [any]) – dadurch lässt sich das Paket [hbs] importieren, das keine Typdeklarationen hat.

Die Datei [nest-cli.json]:

1
2
3
4
5
6
7
8
{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true
  }
}

Identisch mit der aus den Beispielen.

Die Datei [.env.example]:

# -----------------------------------------------------------------------
# Beispiel-Konfigurationsdatei.
# Kopieren Sie diese Datei nach [.env] und passen Sie dann die Werte an Ihren Rechner an.
# Die Datei [.env] darf nie weitergegeben oder committet werden (Passwörter).
# -----------------------------------------------------------------------

# Listening-Port des NestJS-Servers. Der JSON-Server lauscht bereits auf 8080:
# wir wählen einen anderen Port, damit beide gleichzeitig laufen können.
PORT=8081

# Verbindungsparameter zur MySQL-Datenbank [dbrdvmedecins2]
# (Skript: database/dbrdvmedecins2.sql)
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=dbrdvmedecins2

# -----------------------------------------------------------------------
# Authentifizierung (siehe src/auth/)
# -----------------------------------------------------------------------
# geheimer Schlüssel zum Signieren/Prüfen der JWT-Token - MUSS geändert werden
# in Produktion (ein langer Zufallsstring, niemals committet).
JWT_SECRET=change-me-to-a-long-random-string
# Gültigkeitsdauer eines JWT-Tokens in Sekunden (7200 s = 2 h). Das Cookie,
# das das Token trägt, hat dieselbe Lebensdauer.
JWT_EXPIRES_IN_SECONDS=7200
# in Produktion auf true setzen (über HTTPS ausgelieferte Website): das Authentifizierungs-
# Cookie wird dann nie über eine unverschlüsselte Verbindung gesendet.
COOKIE_SECURE=false

# -----------------------------------------------------------------------
# Schutz vor Bots (siehe src/auth/attempt-limiter.service.ts)
# -----------------------------------------------------------------------
# Login: Anzahl der Fehlversuche (falsches Captcha oder Passwort), die für
# dasselbe Login von derselben IP-Adresse erlaubt sind, bevor dieses Paar gesperrt wird ...
LOGIN_MAX_FAILURES=5
# ... für diese Dauer (eine IP-Adresse wird auch gesperrt, wenn sie
# 5-mal mehr Fehlversuche ansammelt, alle Logins zusammengenommen)
LOGIN_BLOCK_MINUTES=15
# Erstellung von Kundenkonten: maximale Anzahl der pro Stunde erstellten Konten
# von derselben IP-Adresse. In einem Klassenraum gehen oft alle Rechner
# über dieselbe Adresse ins Netz: bei Bedarf erhöhen.
REGISTRATION_MAX_PER_HOUR=10
  • Eine Datei namens [.env] enthält rechnerspezifische Konfigurationseinstellungen: Sie wird niemals weitergegeben (sie enthält Passwörter). Die Datei [.env.example] dient als Vorlage, die zu kopieren ist;
  • Zeile 9: der Port der Anwendung;
  • Zeilen 13–17: die Datenbankverbindung;
  • Zeilen 24–30: der Token-Schlüssel, seine Gültigkeitsdauer (zwei Stunden) und die Cookie-Option [secure] (in der Produktion wird die Website über HTTPS ausgeliefert, und das Cookie darf niemals über eine unverschlüsselte Verbindung übertragen werden);
  • Zeilen 37–44: die Schwellenwerte für den Bot-Schutz.

Die Datei [src/config/database.config.ts]:

// =========================================================================
// config/database.config.ts
// -------------------------------------------------------------------------
// Konfiguration der Verbindung zur MySQL-Datenbank, verwendet von
// TypeORM. Sie entspricht der Klasse [DomainAndPersitenceConfig] des
// ursprünglichen Spring-Projekts, die eine [DataSource] definierte (@Bean-Block).
//
// Hier keine Klasse: NestJS/TypeORM bevorzugt eine einfache Funktion, die
// ein Konfigurationsobjekt zurückgibt, das aus den Umgebungsvariablen gelesen wird
// (Datei .env im Projektwurzelverzeichnis, von NestJS automatisch
// über das Modul @nestjs/config geladen, falls installiert - hier lesen wir
// process.env direkt, um es einfach und lehrreich zu halten).
// =========================================================================

import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { Doctor } from '../entities/doctor.entity';
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
import { User } from '../entities/user.entity';

export function getDatabaseConfig(): TypeOrmModuleOptions {
  return {
    // 'mysql': wir verwenden den MySQL-Treiber wie das ursprüngliche Projekt (MySQL5 -> hier MySQL8).
    type: 'mysql',
    host: process.env.DB_HOST ?? 'localhost',
    port: process.env.DB_PORT ? parseInt(process.env.DB_PORT, 10) : 3306,
    username: process.env.DB_USERNAME ?? 'root',
    password: process.env.DB_PASSWORD ?? '',
    database: process.env.DB_DATABASE ?? 'dbrdvmedecins2',

    // die Liste der Entitäten (@Entity-Klassen), die TypeORM verwalten muss.
    // Sie entspricht dem automatischen "Scan" der @Entity-Klassen durch Spring Boot.
    entities: [Doctor, Client, Slot, Appointment, User],

    // WICHTIG: synchronize=false, in diesem Kurs immer.
    // Wäre synchronize true, würde TypeORM das Datenbankschema von sich aus
    // anhand der Entitäten ändern: praktisch für einen Wegwerf-Prototyp, gefährlich, sobald
    // echte Daten vorliegen (Gefahr von Datenverlust). Wie ein echtes Team ziehen wir es vor,
    // die Kontrolle über das Schema über das Skript database/dbrdvmedecins2.sql zu behalten.
    synchronize: false,

    // zeigt die von TypeORM erzeugten SQL-Abfragen in der Konsole an: sehr nützlich, um
    // zu verstehen, was das ORM für Sie tut, genau wie die Hibernate-Logs
    // des ursprünglichen Spring-Projekts.
    logging: process.env.NODE_ENV !== 'production',
  };
}

Die Verbindung zur Datenbank (siehe Beispiel 28). Zeile 46: SQL-Befehle werden angezeigt, außer in der Produktion.

Die Datei [src/config/paths.ts]:

// =========================================================================
// config/paths.ts
// -------------------------------------------------------------------------
// Die NICHT kompilierten Ordner des Projekts (Handlebars-Views, statische Dateien,
// Übersetzungswörterbücher) liegen im Wurzelverzeichnis des Projekts, neben
// src/ und dist/. Nach der Kompilierung liegt diese Datei in
// dist/config/: das Projektwurzelverzeichnis liegt daher zwei Ebenen darüber.
// =========================================================================

import { join, resolve } from 'path';

export const PROJECT_ROOT = resolve(__dirname, '..', '..');

export const VIEWS_DIR = join(PROJECT_ROOT, 'views'); // Seiten-Templates (.hbs)
export const PARTIALS_DIR = join(VIEWS_DIR, 'partials'); // wiederverwendbare Seitenteile
export const PUBLIC_DIR = join(PROJECT_ROOT, 'public'); // CSS, JS, Bilder
export const I18N_DIR = join(PROJECT_ROOT, 'i18n'); // fr.json, en.json
export const BOOTSTRAP_DIR = join(PROJECT_ROOT, 'node_modules', 'bootstrap', 'dist');
  • Zeile 12: Nach dem Kompilieren befindet sich diese Datei in [dist/config]: Das Projektstammverzeichnis liegt zwei Ebenen darüber;
  • Zeilen 14–18: die nicht kompilierten Ordner (Views, statische Dateien, Wörterbücher) sowie der Ordner von [Bootstrap].

11.7. Start der Anwendung

Die Datei [src/main.ts]:

// =========================================================================
// main.ts
// -------------------------------------------------------------------------
// Einstiegspunkt der Anwendung. Im Vergleich zum JSON-Server konfiguriert der
// Start zusätzlich alles, was nötig ist, um HTML-SEITEN
// serverseitig ZU ERSTELLEN:
//   - eine View-Engine (Handlebars, Dateien views/*.hbs);
//   - die statischen Dateien (Bootstrap, CSS, ein wenig JavaScript);
//   - das Parsen von Cookies (JWT-Token, Sprache, Flash-Meldungen);
//   - einen Filter, der Fehler in HTML-Seiten umwandelt.
// CORS muss nicht mehr erlaubt werden: Seiten und Daten kommen jetzt vom
// SELBEN Server.
// =========================================================================

import 'dotenv/config'; // MUSS der allererste Import bleiben (siehe JSON-Server)
import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import * as cookieParser from 'cookie-parser';
import * as hbs from 'hbs';
import { AppModule } from './app.module';
import { BOOTSTRAP_DIR, PARTIALS_DIR, PUBLIC_DIR, VIEWS_DIR } from './config/paths';
import { registerHelpers } from './web/views/handlebars-helpers';
import { viewContextMiddleware } from './web/view-context';
import { HtmlExceptionFilter } from './web/html-exception.filter';
import { ViewUserInterceptor } from './web/view-user.interceptor';

async function bootstrap() {
  // NestExpressApplication: wir legen fest, dass die zugrunde liegende Plattform
  // Express ist, um Zugriff auf deren eigene Methoden zu erhalten (setViewEngine,
  // useStaticAssets ...) - sie existieren für die Plattform Fastify nicht.
  const app = await NestFactory.create<NestExpressApplication>(AppModule);

  // 1. statische Dateien: /css/..., /js/... (Ordner public/) und
  //    /bootstrap/css/bootstrap.min.css (direkt aus node_modules:
  //    Bootstrap muss nicht ins Projekt kopiert werden)
  app.useStaticAssets(PUBLIC_DIR);
  app.useStaticAssets(BOOTSTRAP_DIR, { prefix: '/bootstrap/' });

  // 2. die View-Engine. Die Datei views/layout.hbs wird von hbs
  //    AUTOMATISCH als gemeinsames Template aller Seiten verwendet:
  //    jede View wird an der Stelle {{{body}}} dieses Templates eingefügt.
  app.setBaseViewsDir(VIEWS_DIR);
  app.setViewEngine('hbs');
  registerHelpers(hbs);
  // die "Partials" (views/partials/*.hbs): wiederverwendbare Seitenteile,
  // eingefügt mit {{> name}}. registerPartials liest den Ordner
  // asynchron: wir warten, bis es fertig ist, bevor wir Anfragen annehmen.
  await new Promise<void>((done) => hbs.registerPartials(PARTIALS_DIR, () => done()));

  // 3. cookie-parser füllt req.cookies; danach bereitet unsere Middleware die
  //    Sprache und die Flash-Meldung jeder Seite vor (siehe web/view-context.ts)
  app.use(cookieParser());
  app.use(viewContextMiddleware);

  // 4. der angemeldete Benutzer, für alle Views sichtbar; und die Fehler,
  //    umgewandelt in HTML-Seiten (oder in eine Weiterleitung auf /login)
  app.useGlobalInterceptors(new ViewUserInterceptor());
  app.useGlobalFilters(new HtmlExceptionFilter());

  const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 8081;
  await app.listen(port);
  // eslint-disable-next-line no-console
  console.log(`[RdvMedecins] web application started on http://localhost:${port}`);
}

bootstrap();

Gehen wir diesen Code im Einzelnen durch:

  • Zeile 15: [dotenv/config] liest die Datei [.env] und legt ihre Werte in [process.env] ab. Dieser Import muss der erste sein: Die anderen Module lesen [process.env] , sobald sie geladen werden (zum Beispiel [JWT_SECRET]);
  • Zeilen 37–38: statische Dateien (siehe Beispiel 15);
  • Zeilen 43–49: die View-Engine, die Helfer und die Partial Views (siehe Beispiele 15 und 16);
  • Zeilen 53–54: das Lesen der Cookies, gefolgt von der Middleware, die für jede Seite die Sprache und die Flash-Nachricht vorbereitet (siehe [web/view-context.ts]);
  • Zeilen 58–59: Ein globaler Interceptor stellt den angemeldeten Benutzer den Views zur Verfügung, und ein globaler Filter wandelt Exceptions in HTML-Seiten um (siehe Kapitel 7);
  • Zeile 61: der Port, gelesen aus [.env] (standardmäßig 8081).

Die Datei [src/app.module.ts]:

// =========================================================================
// app.module.ts
// -------------------------------------------------------------------------
// Das Wurzelmodul. Dieselben Schichten wie beim JSON-Server (DAO, Geschäft,
// Cache/Fassade); nur die Controller ändern sich: sie erzeugen jetzt
// HTML-Seiten statt JSON-Antworten.
// =========================================================================

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { getDatabaseConfig } from './config/database.config';

import { Doctor } from './entities/doctor.entity';
import { Client } from './entities/client.entity';
import { Slot } from './entities/slot.entity';
import { Appointment } from './entities/appointment.entity';

import { DoctorRepository } from './repositories/doctor.repository';
import { ClientRepository } from './repositories/client.repository';
import { SlotRepository } from './repositories/slot.repository';
import { AppointmentRepository } from './repositories/appointment.repository';

import { BUSINESS_TOKEN } from './business/business.interface';
import { BusinessService } from './business/business.service';

import { ApplicationModelService } from './web/application-model.service';
import { ScheduleController } from './web/controllers/schedule.controller';
import { DoctorsController } from './web/controllers/doctors.controller';
import { ClientsController } from './web/controllers/clients.controller';
import { LanguageController } from './web/controllers/language.controller';
import { RegistrationController } from './web/controllers/registration.controller';
import { PatientAreaController } from './web/controllers/patient-area.controller';

import { AuthModule } from './auth/auth.module';

@Module({
  imports: [
    TypeOrmModule.forRoot(getDatabaseConfig()),
    TypeOrmModule.forFeature([Doctor, Client, Slot, Appointment]),
    // AuthModule stellt /login und /logout bereit; es exportiert UserRepository
    // (in BusinessService injiziert), AuthService, CaptchaService und
    // AttemptLimiterService (in die Controller von src/web/ injiziert)
    AuthModule,
  ],
  controllers: [
    ScheduleController,
    DoctorsController,
    ClientsController,
    LanguageController,
    RegistrationController, // "Create a patient account" (public)
    PatientAreaController, // "My area", "Manage my account" (USER)
  ],
  providers: [
    DoctorRepository,
    ClientRepository,
    SlotRepository,
    AppointmentRepository,
    { provide: BUSINESS_TOKEN, useClass: BusinessService },
    ApplicationModelService,
  ],
})
export class AppModule {}
  • Zeile 38: die Datenbankverbindung;
  • Zeile 39: die Repositories der vier von diesem Modul verwalteten Entitäten (das für [User] wird von [AuthModule] deklariert);
  • Zeile 43: das Authentifizierungsmodul mit eigenem Controller und eigenen Services;
  • Zeilen 45–52: die Controller der Web-Schicht;
  • Zeilen 53–60: die Services: die DAO-Schicht (die vier Repositories), die Geschäftsschicht und der Cache der Web-Schicht. Zeile 58: Die Geschäftsschicht wird unter einem Token ([BUSINESS_TOKEN]) registriert und nicht unter dem Namen ihrer Klasse: Wer sie verwendet, hängt von der Schnittstelle [IBusiness] ab, nicht von der Klasse [BusinessService]. Die Implementierung ließe sich (zum Beispiel durch eine Testversion) ersetzen, indem nur diese Zeile geändert wird.

11.8. Die Entitäten

Die [TypeORM]-Entitäten werden auf die Datenbanktabellen und auf Klassen in [TypeScript] abgebildet (siehe Beispiel 28). Ihre Kommentare verweisen häufig auf das [Java] / [Spring] -Projekt, von dem die Anwendung ein entfernter Nachkomme ist, und auf den „JSON-Server“: den [NestJS]-Server aus den Client-Server-Kursen, dessen Fallstudie die DAO- und die Geschäftsschicht übernimmt.

11.8.1. src/entities/abstract.entity.ts

// =========================================================================
// entities/abstract.entity.ts
// -------------------------------------------------------------------------
// Entspricht der Klasse [AbstractEntity] des ursprünglichen Spring-Projekts,
// die mit @MappedSuperclass annotiert war. Sie fasst die zwei Felder
// zusammen, die allen unseren persistenten Entitäten gemeinsam sind: die Kennung [id] und die
// Versionsnummer [version], mit der nebenläufige Zugriffe verwaltet werden.
//
// In JPA bedeutet @MappedSuperclass "diese Klasse ist keine Tabelle,
// aber ihre Felder müssen den Tabellen der Kindklassen hinzugefügt werden".
// TypeORM bietet genau denselben Mechanismus: es genügt, dass eine abstrakte
// Klasse (nicht mit @Entity dekoriert) von einer Klasse geerbt wird, die
// ihrerseits die Annotation @Entity trägt. TypeORM fügt dann automatisch
// die geerbten Spalten zur Tabelle der Kindklasse hinzu.
// =========================================================================

import { PrimaryGeneratedColumn, VersionColumn } from 'typeorm';

export abstract class AbstractEntity {
  // entspricht:
  //   @Id
  //   @GeneratedValue(strategy = GenerationType.AUTO)
  //   protected Long id;
  //
  // @PrimaryGeneratedColumn() deklariert einen vom DBMS automatisch hochgezählten Primärschlüssel,
  // genau wie GenerationType.AUTO dies dem DBMS überließ.
  @PrimaryGeneratedColumn()
  id: number;

  // entspricht:
  //   @Version
  //   protected Long version;
  //
  // @VersionColumn() ist DER native TypeORM-Mechanismus für optimistisches Sperren:
  // TypeORM erhöht diese Spalte bei jedem UPDATE automatisch und wirft einen Fehler,
  // wenn versucht wird, eine Entität zu speichern, deren Version nicht mehr mit der in der
  // Datenbank übereinstimmt (jemand anderes hat sie in der Zwischenzeit geändert). Es entspricht direkt der
  // Rolle von @Version in JPA/Hibernate.
  @VersionColumn()
  version: number;
}
  • Zeile 19: eine abstrakte Klasse ohne den Dekorator [@Entity]: Sie entspricht keiner Tabelle, aber ihre Spalten werden zu denen der abgeleiteten Klassen hinzugefügt;
  • Zeilen 27–28: der von der Datenbank erzeugte Primärschlüssel;
  • Zeilen 39–40: die Zeilenversion, die [TypeORM] bei jeder Änderung erhöht (optimistisches Sperren; siehe Beispiel 28).

11.8.2. src/entities/person.entity.ts

// =========================================================================
// entities/person.entity.ts
// -------------------------------------------------------------------------
// Elternklasse (selbst nicht persistiert) der Entitäten [Doctor] und
// [Client]: ein Titel, ein Nachname, ein Vorname - und, neu in der
// Datenbank [dbrdvmedecins2], das zugehörige Benutzerkonto (Spalte [user]).
//
// Eine in einer abstrakten Klasse deklarierte Relation wird von den
// Kindklassen genau wie die Spalten geerbt: TypeORM fügt die Relation
// [user] daher sowohl der Tabelle [doctors] ALS AUCH der Tabelle [clients] hinzu.
// =========================================================================

import { Column, JoinColumn, OneToOne, RelationId } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { User } from './user.entity';

export abstract class Person extends AbstractEntity {
  @Column({ length: 5 })
  title: string; // Melle, Mme, Mr

  @Column({ name: 'last_name', length: 20 })
  lastName: string;

  @Column({ name: 'first_name', length: 20 })
  firstName: string;

  // @OneToOne: ein Arzt (oder ein Client) hat EIN Benutzerkonto, und ein
  // Benutzerkonto gehört höchstens EINER Person (die Spalte [user]
  // ist im SQL-Skript als UNIQUE deklariert).
  // @JoinColumn({ name: 'user' }): DIESE Tabelle (doctors / clients)
  // trägt den Fremdschlüssel, in der Spalte namens [user].
  // Wie bei den anderen Relationen wird [user] nur auf Anforderung geladen
  // (Option `relations`) - siehe doctor.repository.ts.
  @OneToOne(() => User)
  @JoinColumn({ name: 'user' })
  user: User;

  // der Rohwert des Fremdschlüssels, ohne den vollständigen User zu laden
  // (dieselbe Technik wie Slot.doctorId, siehe slot.entity.ts)
  @RelationId((person: Person) => person.user)
  userId: number;
}
  • Zeile 17: die Elternklasse von [Doctor] und [Client], die selbst von [AbstractEntity] erbt;
  • Zeilen 18–25: Anrede, Nachname, Vorname;
  • Zeilen 34–36: eine Eins-zu-eins-Beziehung zum Benutzerkonto. [@JoinColumn] gibt an, dass diese Tabelle den Fremdschlüssel enthält, und zwar in der Spalte [user]. Die Beziehung wird nur geladen, wenn sie angefordert wird (Option [relations] in Abfragen);
  • Zeilen 40–41: [@RelationId] stellt den Wert des Fremdschlüssels (die Konto-ID) bereit, ohne das Konto selbst zu laden.

11.8.3. src/entities/doctor.entity.ts

// =========================================================================
// entities/doctor.entity.ts
// -------------------------------------------------------------------------
// Entspricht der JPA-Entität [Medecin] (ein Arzt):
//
//   @Entity
//   @Table(name = "medecins")
//   public class Medecin extends Personne { ... }
// =========================================================================

import { Entity, OneToMany, Unique } from 'typeorm';
import { Person } from './person.entity';
import { Slot } from './slot.entity';

// @Entity({ name: 'doctors' }): deklariert die Klasse als TypeORM-Entität,
// persistiert in der Tabelle [doctors]. Das ist das genaue Äquivalent zu
// @Entity + @Table(name = "doctors") in JPA.
@Entity({ name: 'doctors' })
// Erinnerung an die SQL-Bedingung des Skripts database/dbrdvmedecins2.sql: zwei
// Ärzte dürfen nicht denselben Vor- und Nachnamen haben. Wie bei unq1_appointments
// (siehe appointment.entity.ts) dient dies der Dokumentation: synchronize=false, das
// SQL-Skript erstellt die Bedingung tatsächlich - mit DIESEM Namen, den die
// Geschäftsschicht in den MySQL-Fehlermeldungen wiedererkennt (siehe business.service.ts).
@Unique('unq_doctors_first_name_last_name', ['firstName', 'lastName'])
export class Doctor extends Person {
  // inverse Relation (optional, praktisch, um von einem Arzt zu den Slots des Arztes zu navigieren).
  // Das ursprüngliche Projekt definierte sie nicht auf der Seite von [Medecin] (nur auf der Seite von [Creneau]),
  // aber mit TypeORM ist sie fast kostenlos hinzuzufügen und didaktisch nützlich:
  // sie zeigt die Relation "1 Arzt -> mehrere Slots" in beiden Richtungen.
  @OneToMany(() => Slot, (slot) => slot.doctor)
  slots: Slot[];
}
  • Zeile 18: Die Klasse entspricht der Tabelle [doctors];
  • Zeile 24: die Eindeutigkeitsbedingung, hier zu Dokumentationszwecken aufgeführt; tatsächlich wird sie vom SQL-Skript erstellt ([synchronize: false]);
  • Zeilen 30–31: die Eins-zu-viele-Beziehung zu den Zeitfenstern des Arztes, die Umkehrung der Beziehung [@ManyToOne] von [Slot].

11.8.4. src/entities/client.entity.ts

// =========================================================================
// entities/client.entity.ts
// -------------------------------------------------------------------------
// Entspricht der JPA-Entität [Client]:
//
//   @Entity
//   @Table(name = "clients")
//   public class Client extends Personne { ... }
//
// Achtung: [Client] bedeutet hier einen PATIENTEN der Arztpraxis, keinen
// HTTP-Client! Es ist das Vokabular der ursprünglichen Fachdomäne, unverändert
// beibehalten, um dem Ausgangsdokument treu zu bleiben.
// =========================================================================

import { Entity, Unique } from 'typeorm';
import { Person } from './person.entity';

@Entity({ name: 'clients' })
// zwei Clients dürfen nicht denselben Vor- und Nachnamen haben
// (siehe dieselbe Bedingung bei Doctor, doctor.entity.ts)
@Unique('unq_clients_first_name_last_name', ['firstName', 'lastName'])
export class Client extends Person {}

Ein Client (ein Patient): eine [Person] aus der Tabelle [clients], ohne zusätzliche Felder.

11.8.5. src/entities/slot.entity.ts

// =========================================================================
// entities/slot.entity.ts
// -------------------------------------------------------------------------
// Entspricht der JPA-Entität [Creneau] (ein Zeitslot):
//
//   @Entity
//   @Table(name = "creneaux")
//   public class Creneau extends AbstractEntity {
//       private int hdebut, mdebut, hfin, mfin;
//       @ManyToOne(fetch = FetchType.LAZY)
//       @JoinColumn(name = "id_medecin")
//       private Medecin medecin;
//       @Column(name = "id_medecin", insertable = false, updatable = false)
//       private long idMedecin;
//   }
// =========================================================================

import { Column, Entity, JoinColumn, ManyToOne, RelationId } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { Doctor } from './doctor.entity';

@Entity({ name: 'slots' })
export class Slot extends AbstractEntity {
  @Column({ name: 'start_hour' }) startHour: number; // Startstunde des Slots
  @Column({ name: 'start_minute' }) startMinute: number; // Startminute des Slots
  @Column({ name: 'end_hour' }) endHour: number; // Endstunde des Slots
  @Column({ name: 'end_minute' }) endMinute: number; // Endminute des Slots

  // entspricht:
  //   @ManyToOne(fetch = FetchType.LAZY)
  //   @JoinColumn(name = "id_medecin")
  //   private Medecin medecin;
  //
  // @ManyToOne: mehrere Slots für denselben Arzt.
  // Standardmäßig lädt TypeORM die Relation [doctor] beim Lesen eines Slots NICHT
  // (standardmäßig "lazy"-Verhalten): sie muss ausdrücklich über die Option
  // `relations: ['doctor']` einer Abfrage angefordert werden - genau wie FetchType.LAZY in JPA
  // ein ausdrückliches `left join fetch` in der JPQL-Abfrage erforderte, um den Arzt zu laden.
  @ManyToOne(() => Doctor, (doctor) => doctor.slots)
  @JoinColumn({ name: 'doctor_id' })
  doctor: Doctor;

  // entspricht:
  //   @Column(name = "id_medecin", insertable = false, updatable = false)
  //   private long idMedecin;
  //
  // @RelationId: es ist das EXAKTE und idiomatische TypeORM-Äquivalent des schreibgeschützten
  // Feldes "idMedecin" des ursprünglichen Projekts. Es stellt direkt den Wert
  // des Fremdschlüssels bereit, OHNE die vollständige Entität [Doctor] laden zu müssen.
  // Sehr nützlich, um Kennungen zu vergleichen, ohne die verknüpften Entitäten zu laden.
  @RelationId((slot: Slot) => slot.doctor)
  doctorId: number;
}
  • Zeilen 24–27: die Stunden und Minuten von Beginn und Ende;
  • Zeilen 39–41: die Viele-zu-eins-Beziehung zum Arzt: mehrere Zeitfenster für einen Arzt. Der Fremdschlüssel ist die Spalte [doctor_id];
  • Zeilen 51–52: die ID des Arztes, ohne den Arzt zu laden.

11.8.6. src/entities/appointment.entity.ts

// =========================================================================
// entities/appointment.entity.ts
// -------------------------------------------------------------------------
// Entspricht der JPA-Entität [Rv] (ein Termin):
//
//   @Entity
//   @Table(name = "rv")
//   public class Rv extends AbstractEntity {
//       @Temporal(TemporalType.DATE) private Date jour;
//       @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "id_client") private Client client;
//       @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "id_creneau") private Creneau creneau;
//       @Column(name = "id_client", insertable = false, updatable = false) private long idClient;
//       @Column(name = "id_creneau", insertable = false, updatable = false) private long idCreneau;
//   }
//
// Die SQL-Eindeutigkeitsbedingung auf (day, slot_id) - die verhindert, dass zwei
// Termine am selben Tag im selben Slot liegen - ist direkt
// im Skript database/dbrdvmedecins2.sql definiert (CONSTRAINT unq1_appointments UNIQUE).
// =========================================================================

import { Column, Entity, JoinColumn, ManyToOne, RelationId, Unique } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { Client } from './client.entity';
import { Slot } from './slot.entity';

@Entity({ name: 'appointments' })
// erinnert auf der TypeORM-Seite an die SQL-Bedingung des DB-Skripts. Achtung: wir verweisen hier auf
// den Namen der RELATION ('slot'), nicht auf das @RelationId-Feld ('slotId') - Letzteres ist
// eine "virtuelle" (berechnete) Spalte, die TypeORM in einer @Unique-Bedingung nicht akzeptiert.
// TypeORM übersetzt 'slot' selbst in die echte Fremdschlüsselspalte (slot_id).
@Unique('unq1_appointments', ['day', 'slot'])
export class Appointment extends AbstractEntity {
  // entspricht: @Temporal(TemporalType.DATE) private Date jour;
  // Typ 'date' (und nicht 'datetime'): nur der Tag wird gespeichert, nicht die Uhrzeit,
  // genau wie TemporalType.DATE es auf der JPA-Seite festlegte.
  @Column({ type: 'date' })
  day: string; // Format "yyyy-MM-dd", z. B. "2026-09-13"

  @ManyToOne(() => Client)
  @JoinColumn({ name: 'client_id' })
  client: Client;

  @ManyToOne(() => Slot)
  @JoinColumn({ name: 'slot_id' })
  slot: Slot;

  // Äquivalente der schreibgeschützten Felder idClient / idCreneau des ursprünglichen Projekts
  // (siehe die ausführliche Erklärung zu @RelationId in slot.entity.ts)
  @RelationId((appointment: Appointment) => appointment.client)
  clientId: number;

  @RelationId((appointment: Appointment) => appointment.slot)
  slotId: number;
}
  • Zeile 31: Ein Terminfenster wird pro Tag nur einmal reserviert;
  • Zeilen 36–37: eine Spalte vom Typ [DATE], die als Zeichenfolge [yyyy-mm-dd] behandelt wird: keine Zeitzonenprobleme, und zwei Datumsangaben werden als Zeichenfolgen verglichen;
  • Zeilen 39–45: der Client und das Zeitfenster des Termins;
  • Zeilen 49–53: ihre IDs.

11.8.7. src/entities/user.entity.ts

// =========================================================================
// entities/user.entity.ts
// -------------------------------------------------------------------------
// Ein Benutzer, der sich an der Anwendung anmelden darf (Tabelle [users]).
//
// Neu in der Datenbank [dbrdvmedecins2]: Jeder Arzt und jeder Client hat
// nun EIN EIGENES Benutzerkonto (Spalte [user] der Tabellen
// [doctors] und [clients], siehe person.entity.ts). Daher eine dritte Rolle:
//   - ADMIN  : der Administrator - Termine + Verwaltung von Ärzten und Clients;
//   - DOCTOR : ein Arzt - bucht und storniert Termine;
//   - USER   : ein Client (Patient) - bucht für sich selbst, verwaltet sein Konto.
//
// Die Rollen bleiben sich gegenseitig ausschließend: eine einfache Spalte [role]
// genügt weiterhin (keine Tabelle [roles] / [users_roles] wie im
// ursprünglichen Spring-Projekt).
// =========================================================================

import { Column, Entity, Unique } from 'typeorm';
import { AbstractEntity } from './abstract.entity';

export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

@Entity({ name: 'users' })
// ein Login gehört nur zu einem Konto (SQL-Bedingung unq_users_login)
@Unique('unq_users_login', ['login'])
export class User extends AbstractEntity {
  @Column({ length: 30 })
  login: string;

  // das GEHASHTE Passwort (bcrypt) - niemals im Klartext
  @Column({ length: 100 })
  password: string;

  // der nach der Anmeldung angezeigte Name - bei einem Arzt oder einem Client:
  // "firstName LASTNAME" (z. B. "Marie PELISSIER")
  @Column({ length: 40 })
  name: string;

  @Column({ type: 'varchar', length: 10 })
  role: Role;
}
  • Zeile 21: ein Union-Typ aus Zeichenfolgen: Eine Variable vom Typ [Role] kann nur eine dieser drei Zeichenfolgen sein;
  • Zeilen 31–32: der Hash des Passworts;
  • Zeilen 36–37: der in der Navigationsleiste angezeigte Name („Marie PELISSIER“);
  • Zeilen 39–40: die Rolle. Der Spaltentyp wird angegeben: [TypeORM] kann aus einem Union-Typ keinen SQL-Typ ableiten.

11.9. Die Domäne: der Kalender

Der Ordner [domain] enthält zwei Klassen, die keiner Tabelle entsprechen: Sie beschreiben den Terminkalender eines Arztes für einen einzelnen Tag, wie er von der Geschäftsschicht berechnet wird.

11.9.1. src/domain/doctor-day-slot.ts

// =========================================================================
// domain/doctor-day-slot.ts
// -------------------------------------------------------------------------
// Entspricht der Klasse [CreneauMedecinJour] des ursprünglichen Spring-Projekts:
// eine "fachliche" Entität (nicht in der Datenbank persistiert), die einen
// Zeitslot mit dem Termin verknüpft, der möglicherweise in diesem Slot gebucht ist.
//
//   public class CreneauMedecinJour implements Serializable {
//       private Creneau creneau;
//       private Rv rv; // null if the slot is free
//   }
//
// Diese Art von Klasse hat keine Tabelle in der Datenbank: sie existiert nur während
// der Berechnung des Terminkalenders eines Arztes, den die Web-Schicht dann in
// Zeilen der HTML-Terminkalender-Tabelle umwandelt (siehe schedule.controller.ts).
// =========================================================================

import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';

export class DoctorDaySlot {
  constructor(
    public slot: Slot,
    public appointment: Appointment | null, // null, wenn der Slot an diesem Tag frei ist
  ) {}
}

Zeilen 22–25: ein Zeitfenster und der für dieses Zeitfenster an diesem Tag vereinbarte Termin ([null] , wenn das Zeitfenster frei ist). Die Syntax [public slot: Slot] in den Parametern eines Konstruktors deklariert und initialisiert das Feld in einem einzigen Schritt.

11.9.2. src/domain/doctor-day-schedule.ts

// =========================================================================
// domain/doctor-day-schedule.ts
// -------------------------------------------------------------------------
// Entspricht der Klasse [AgendaMedecinJour] des ursprünglichen Spring-Projekts:
// der vollständige Terminkalender eines Arztes für einen bestimmten Tag, d. h. die Liste der
// Zeitslots des Arztes, von denen jeder frei oder durch einen Termin belegt ist.
//
//   public class AgendaMedecinJour implements Serializable {
//       private Medecin medecin;
//       private Date jour;
//       private CreneauMedecinJour[] creneauxMedecinJour;
//   }
// =========================================================================

import { Doctor } from '../entities/doctor.entity';
import { DoctorDaySlot } from './doctor-day-slot';

export class DoctorDaySchedule {
  constructor(
    public doctor: Doctor,
    public day: string, // Format "yyyy-MM-dd"
    public doctorDaySlots: DoctorDaySlot[],
  ) {}
}

Der Terminkalender: ein Arzt, ein Tag und die Liste seiner Zeitfenster, ob frei oder gebucht.

11.10. Die DAO-Schicht

Eine Klasse pro Tabelle. Alle folgen dem Muster aus Beispiel 28: ein injiziertes [Repository] [TypeORM], eine Methode [repo(manager)], die das Repository der aktuellen Transaktion auswählt, und kurze Methoden ohne Geschäftslogik.

11.10.1. src/repositories/doctor.repository.ts

// =========================================================================
// repositories/doctor.repository.ts
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Doctor]. Im Vergleich zum JSON-Server drei
// Neuerungen, alle im Zusammenhang mit der Verwaltung der Ärzte durch den ADMIN:
//   - die Lesezugriffe liefern auch das zugehörige Benutzerkonto (Relation
//     [user]), um das Login in der Liste der Ärzte anzuzeigen;
//   - save() / deleteById(): Erstellen, Aktualisieren, Löschen;
//   - jede schreibende Methode akzeptiert einen OPTIONALEN EntityManager: wenn
//     die Geschäftsschicht ihn übergibt, läuft die Operation INNERHALB der Transaktion
//     dieser Schicht (siehe business.service.ts, dataSource.transaction(...)).
// =========================================================================

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Doctor } from '../entities/doctor.entity';

@Injectable()
export class DoctorRepository {
  constructor(
    @InjectRepository(Doctor)
    private readonly repository: Repository<Doctor>,
  ) {}

  // das zu verwendende Repository: das der aktuellen Transaktion, falls es
  // eine gibt, andernfalls das "gewöhnliche" Repository.
  private repo(manager?: EntityManager): Repository<Doctor> {
    return manager ? manager.getRepository(Doctor) : this.repository;
  }

  // Liste, sortiert nach Nachname, dann Vorname, einschließlich Benutzerkonto
  findAll(): Promise<Doctor[]> {
    return this.repository.find({ relations: { user: true }, order: { lastName: 'ASC', firstName: 'ASC' } });
  }

  findById(id: number, manager?: EntityManager): Promise<Doctor | null> {
    return this.repo(manager).findOne({ where: { id }, relations: { user: true } });
  }

  // die Person mit diesem Vor- und Nachnamen, falls es eine gibt. Der Vergleich
  // erfolgt durch MySQL, also mit der Collation der Datenbank (utf8mb4_unicode_ci:
  // unabhängig von Groß-/Kleinschreibung und Akzenten) - exakt dieselbe
  // Regel wie die der SQL-Eindeutigkeitsbedingung.
  findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<Doctor | null> {
    return this.repo(manager).findOneBy({ firstName, lastName });
  }

  save(doctor: Doctor, manager?: EntityManager): Promise<Doctor> {
    return this.repo(manager).save(doctor);
  }

  async deleteById(id: number, manager?: EntityManager): Promise<void> {
    await this.repo(manager).delete(id);
  }
}
  • Zeilen 28–30: innerhalb einer Transaktion das Repository der aktuellen Transaktion ([manager]);
  • Zeilen 33–35: alle Ärzte samt ihrem Konto ([relations: { user: true }]), sortiert nach Nachname und dann nach Vorname. Das Konto wird verwendet, um den Benutzernamen in der Ärzteliste anzuzeigen;
  • Zeilen 45–47: mögliche Namensvettern. Der Vergleich wird von [MySQL] gemäß der Kollation der Datenbank durchgeführt;
  • Zeilen 49–51 und 53–55: Schreib- und Löschoperationen.

11.10.2. src/repositories/client.repository.ts

// =========================================================================
// repositories/client.repository.ts
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Client] (ein PATIENT der Praxis). Streng dasselbe
// Prinzip wie in doctor.repository.ts (siehe dortige Kommentare).
// =========================================================================

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Client } from '../entities/client.entity';

@Injectable()
export class ClientRepository {
  constructor(
    @InjectRepository(Client)
    private readonly repository: Repository<Client>,
  ) {}

  private repo(manager?: EntityManager): Repository<Client> {
    return manager ? manager.getRepository(Client) : this.repository;
  }

  findAll(): Promise<Client[]> {
    return this.repository.find({ relations: { user: true }, order: { lastName: 'ASC', firstName: 'ASC' } });
  }

  findById(id: number, manager?: EntityManager): Promise<Client | null> {
    return this.repo(manager).findOne({ where: { id }, relations: { user: true } });
  }

  // der Client (Patient), dessen Benutzerkonto [userId] ist, oder null.
  // where: { user: { id } }: TypeORM übersetzt diesen Filter auf der Relation in
  // ein einfaches "WHERE clients.user = ?" (kein Join nötig)
  findByUserId(userId: number): Promise<Client | null> {
    return this.repository.findOne({ where: { user: { id: userId } }, relations: { user: true } });
  }

  // liest einen Client und setzt dabei eine SPERRE auf dessen Zeile bis zum Ende der
  // aktuellen Transaktion (SELECT ... FOR UPDATE). Eine zweite Transaktion, die
  // dieselbe Sperre anfordert, WARTET, bis die erste beendet ist.
  // Verwendet beim Buchen eines Termins (siehe BusinessService.addAppointment): zwei
  // gleichzeitige Buchungen für denselben Patienten werden so
  // nacheinander abgearbeitet, und die zweite sieht den von der ersten erstellten Termin.
  lock(id: number, manager: EntityManager): Promise<Client | null> {
    return manager.getRepository(Client).findOne({ where: { id }, lock: { mode: 'pessimistic_write' } });
  }

  // die Person mit diesem Vor- und Nachnamen, falls es eine gibt. Der Vergleich
  // erfolgt durch MySQL, also mit der Collation der Datenbank (utf8mb4_unicode_ci:
  // unabhängig von Groß-/Kleinschreibung und Akzenten) - exakt dieselbe
  // Regel wie die der SQL-Eindeutigkeitsbedingung.
  findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<Client | null> {
    return this.repo(manager).findOneBy({ firstName, lastName });
  }

  save(client: Client, manager?: EntityManager): Promise<Client> {
    return this.repo(manager).save(client);
  }

  async deleteById(id: number, manager?: EntityManager): Promise<void> {
    await this.repo(manager).delete(id);
  }
}

Dieselben Methoden wie bei den Ärzten, plus zwei weitere:

  • Zeilen 35–37: der Client mit dem angegebenen Konto – so ruft ein angemeldeter Patient (dessen Token die Konto-ID enthält) seinen Client-Datensatz ab. [TypeORM] übersetzt den Filter [where: { user: { id: userId } }] in [WHERE clients.user = ?];
  • Zeilen 45–47: ein Lesevorgang mit einer Sperre ([lock: { mode: 'pessimistic_write' }], d. h. [SELECT ... FOR UPDATE] in SQL). Bis zum Ende der Transaktion wartet jede andere Transaktion, die dieselbe Sperre anfordert. Das Modul zur Terminvergabe nutzt dies, um zwei gleichzeitige Reservierungen für denselben Patienten nacheinander abzuarbeiten.

11.10.3. src/repositories/slot.repository.ts

// =========================================================================
// repositories/slot.repository.ts
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Slot]. Neu: deleteByDoctor(), verwendet,
// wenn ein Arzt gelöscht wird (die Zeitslots des Arztes verschwinden
// zusammen mit dem Arzt - siehe BusinessService.deleteDoctor).
// =========================================================================

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Slot } from '../entities/slot.entity';

@Injectable()
export class SlotRepository {
  constructor(
    @InjectRepository(Slot)
    private readonly repository: Repository<Slot>,
  ) {}

  findById(id: number): Promise<Slot | null> {
    return this.repository.findOne({ where: { id }, relations: { doctor: true } });
  }

  // die Slots eines Arztes in chronologischer Reihenfolge
  // (dieselbe Abfrage wie im JSON-Server - siehe dessen Kommentare)
  getAllSlots(doctorId: number): Promise<Slot[]> {
    return this.repository
      .createQueryBuilder('s')
      .where('s.doctor = :doctorId', { doctorId })
      .orderBy('s.startHour', 'ASC')
      .addOrderBy('s.startMinute', 'ASC')
      .getMany();
  }

  // löscht alle Slots eines Arztes. delete({ doctor: { id } })
  // erzeugt: DELETE FROM slots WHERE doctor_id = ?
  async deleteByDoctor(doctorId: number, manager?: EntityManager): Promise<void> {
    const repo = manager ? manager.getRepository(Slot) : this.repository;
    await repo.delete({ doctor: { id: doctorId } });
  }
}
  • Zeilen 27–34: die Zeitfenster eines Arztes in chronologischer Reihenfolge. Die Abfrage wird mit dem QueryBuilder von [TypeORM] geschrieben, der eine SQL-Abfrage Methode für Methode aufbaut: [createQueryBuilder('s')] (die Tabelle, mit dem Alias [s]), [where] (mit einem Parameter namens [:doctorId] – niemals mit Zeichenkettenverkettung, die SQL-Injections Tür und Tor öffnen würde), [orderBy], dann [getMany], das die Abfrage ausführt;
  • Zeilen 38–41: das Löschen der Zeitfenster eines Arztes, verwendet, wenn dieser Arzt entfernt wird.

11.10.4. src/repositories/appointment.repository.ts

// =========================================================================
// repositories/appointment.repository.ts
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Appointment]. Neuerungen:
//   - die Anzahl der Termine eines Arztes, um das Löschen
//     eines Arztes, der noch Termine hat, ABZULEHNEN (siehe BusinessService);
//   - die ANSTEHENDEN Termine eines Clients (Seite "My area" des Patienten und
//     Regel "nur ein anstehender Termin pro Patient");
//   - das Löschen aller Termine eines Clients (ein Client wird
//     zusammen mit seinen Terminen gelöscht, durch den ADMIN oder durch ihn selbst).
// =========================================================================

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Appointment } from '../entities/appointment.entity';

@Injectable()
export class AppointmentRepository {
  constructor(
    @InjectRepository(Appointment)
    private readonly repository: Repository<Appointment>,
  ) {}

  private repo(manager?: EntityManager): Repository<Appointment> {
    return manager ? manager.getRepository(Appointment) : this.repository;
  }

  findById(id: number): Promise<Appointment | null> {
    return this.repository.findOne({ where: { id }, relations: { client: true, slot: true } });
  }

  save(appointment: Appointment, manager?: EntityManager): Promise<Appointment> {
    return this.repo(manager).save(appointment);
  }

  async deleteById(id: number): Promise<void> {
    await this.repository.delete(id);
  }

  // die Termine eines Arztes an einem bestimmten Tag, einschließlich Client und Slot
  // (dieselbe Abfrage wie im JSON-Server - siehe dessen Kommentare)
  getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
    return this.repository
      .createQueryBuilder('appointment')
      .leftJoinAndSelect('appointment.client', 'client')
      .leftJoinAndSelect('appointment.slot', 'slot')
      .where('slot.doctor = :doctorId', { doctorId })
      .andWhere('appointment.day = :day', { day })
      .getMany();
  }

  // die Termine eines Clients ab dem Tag [from] (einschließlich), in
  // chronologischer Reihenfolge, mit dem Slot UND dem Arzt dieses Slots
  // (verkettetes innerJoinAndSelect: appointment -> slot -> doctor)
  findUpcomingByClient(clientId: number, from: string): Promise<Appointment[]> {
    return this.repository
      .createQueryBuilder('appointment')
      .innerJoinAndSelect('appointment.slot', 'slot')
      .innerJoinAndSelect('slot.doctor', 'doctor')
      .where('appointment.client = :clientId', { clientId })
      .andWhere('appointment.day >= :from', { from })
      .orderBy('appointment.day', 'ASC')
      .addOrderBy('slot.startHour', 'ASC')
      .addOrderBy('slot.startMinute', 'ASC')
      .getMany();
  }

  // Anzahl der Termine eines Clients ab dem Tag [from] (einschließlich)
  countUpcomingByClient(clientId: number, from: string, manager?: EntityManager): Promise<number> {
    return this.repo(manager)
      .createQueryBuilder('appointment')
      .where('appointment.client = :clientId', { clientId })
      .andWhere('appointment.day >= :from', { from })
      .getCount();
  }

  // löscht ALLE Termine (vergangene und zukünftige) eines Clients:
  //   DELETE FROM appointments WHERE client_id = ?
  async deleteByClient(clientId: number, manager?: EntityManager): Promise<void> {
    await this.repo(manager).delete({ client: { id: clientId } });
  }

  // Anzahl der Termine (vergangene oder zukünftige) eines Arztes - wir müssen über
  // die Slots des Arztes gehen, da [appointments] nicht direkt auf [doctors] verweist:
  //   SELECT COUNT(*) FROM appointments INNER JOIN slots s ON ... WHERE s.doctor_id = ?
  countByDoctor(doctorId: number, manager?: EntityManager): Promise<number> {
    return this.repo(manager)
      .createQueryBuilder('appointment')
      .innerJoin('appointment.slot', 'slot')
      .where('slot.doctor = :doctorId', { doctorId })
      .getCount();
  }
}
  • Zeilen 43–51: die Termine eines Arztes an einem bestimmten Tag. [leftJoinAndSelect] führt einen Join aus und lädt die verknüpfte Entität: Jeder Termin wird samt seinem Patienten und seinem Zeitfenster abgerufen;
  • Zeilen 56–67: die Termine eines Clients ab einem bestimmten Tag, mit ihrem Zeitfenster und dem diesem Zeitfenster zugeordneten Arzt (zwei kaskadierte Joins): Das wird unter „Mein Bereich“ angezeigt;
  • Zeilen 70–76: ihre Anzahl, für die Regel „nur ein bevorstehender Termin“;
  • Zeilen 80–82: das Löschen aller Termine eines Clients;
  • Zeilen 87–93: die Anzahl der Termine eines Arztes. Die Tabelle [appointments] verweist nicht direkt auf Ärzte: Man muss den Weg über die Zeitfenster nehmen ([innerJoin], ein Join ohne Laden).

11.10.5. src/repositories/user.repository.ts

// =========================================================================
// repositories/user.repository.ts
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [User]. Neu: save() / deleteById(), denn das
// Erstellen (oder Löschen) eines Arztes oder eines Clients erstellt (oder löscht) auch das
// Benutzerkonto - siehe BusinessService.
// =========================================================================

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { User } from '../entities/user.entity';

@Injectable()
export class UserRepository {
  constructor(
    @InjectRepository(User)
    private readonly repository: Repository<User>,
  ) {}

  private repo(manager?: EntityManager): Repository<User> {
    return manager ? manager.getRepository(User) : this.repository;
  }

  // gibt null zurück, wenn kein Benutzer dieses Login hat
  findByLogin(login: string, manager?: EntityManager): Promise<User | null> {
    return this.repo(manager).findOneBy({ login });
  }

  save(user: User, manager?: EntityManager): Promise<User> {
    return this.repo(manager).save(user);
  }

  async deleteById(id: number, manager?: EntityManager): Promise<void> {
    await this.repo(manager).delete(id);
  }
}

Zeilen 26–28: das Konto zu einem Benutzernamen, verwendet für die Anmeldung und um zu prüfen, ob ein Benutzername verfügbar ist.

11.11. Die Geschäftsschicht

11.11.1. src/business/dates.ts

// =========================================================================
// business/dates.ts
// -------------------------------------------------------------------------
// Heutiges Datum im Format "yyyy-MM-dd" (das der Spalte appointments.day).
// Es wird von GESCHÄFTSREGELN verwendet (keine Buchung in der Vergangenheit, nur ein
// ANSTEHENDER Termin pro Patient): es gehört daher in die
// Geschäftsschicht. Die Web-Schicht verwendet es wieder (siehe web/helpers/dates.helper.ts).
//
// Zwei Daten im Format "yyyy-MM-dd" können direkt als Strings verglichen werden:
// "2026-09-23" < "2026-10-01" - die alphabetische Reihenfolge ist die chronologische.
// =========================================================================

// heutiges Datum, in der Zeitzone des Servers
export function today(): string {
  const d = new Date();
  const twoDigits = (n: number) => n.toString().padStart(2, '0');
  return `${d.getFullYear()}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
}

Zeilen 14–18: das heutige Datum im Format [yyyy-mm-dd]; das Datum in der Spalte [appointments.day]. [padStart(2, '0')] dient dazu, eine einstellige Zahl auf zwei Stellen aufzufüllen (aus 9 wird [09]). In diesem Format entspricht die alphabetische Reihenfolge der chronologischen: Zwei Datumsangaben werden mit [<] verglichen.

11.11.2. src/business/business.exception.ts

// =========================================================================
// business/business.exception.ts
// -------------------------------------------------------------------------
// Die Exception, die die Geschäftsschicht wirft, wenn eine GESCHÄFTSREGEL
// verletzt wird (Login bereits vergeben, Arzt, der noch Termine hat, Slot
// bereits gebucht ...). Sie trägt keinen Text, sondern einen
// Übersetzungsschlüssel (z. B. 'ERRORS.LOGIN_TAKEN'): die Web-Schicht übersetzt ihn
// beim Anzeigen der Seite ins Französische oder Englische
// (siehe i18n/fr.json, i18n/en.json).
//
// Die Geschäftsschicht bleibt so unabhängig von der Sprache der Oberfläche -
// so wie sie bereits vom Ausgabeformat (JSON oder HTML) unabhängig war.
// =========================================================================

export class BusinessException extends Error {
  constructor(
    public readonly key: string, // Übersetzungsschlüssel der Meldung
    public readonly params: Record<string, string> = {}, // optionale Parameter der Meldung
  ) {
    super(key);
    this.name = 'BusinessException';
  }
}
  • Zeile 17: Eine [BusinessException] trägt keine Meldung, sondern einen Übersetzungsschlüssel ([ERRORS.LOGIN_TAKEN]). Die Geschäftsschicht kennt somit die Sprache der Oberfläche nicht: Die View übersetzt den Schlüssel (siehe Kapitel 5);
  • Zeile 18: eventuelle Parameter der Meldung;
  • Zeile 21: der Name der Exception, der in den Fehlerprotokollen angezeigt wird.

11.11.3. src/business/business.interface.ts

// =========================================================================
// business/business.interface.ts
// -------------------------------------------------------------------------
// Der Vertrag der Geschäftsschicht. Zu den 11 Methoden des JSON-Servers (Lesen von
// Listen, Terminkalender, Hinzufügen/Löschen eines Termins) kommen 2
// Methoden für den Patientenbereich und 6 Methoden zur Verwaltung von Ärzten
// und Clients hinzu.
// =========================================================================

import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Doctor } from '../entities/doctor.entity';
import { Appointment } from '../entities/appointment.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';

// die in das Formular "doctor" oder "client" eingegebenen Daten
export interface PersonData {
  title: string; // Mr, Mme, Melle
  lastName: string;
  firstName: string;
  // Erstellung: optional, standardmäßig der Nachname in Kleinbuchstaben
  // Aktualisierung: optional, das Login bleibt unverändert, wenn es fehlt
  login?: string;
  // Erstellung: optional, standardmäßig das Login
  // Aktualisierung: optional, das Passwort bleibt unverändert, wenn es fehlt
  password?: string;
  // Aktualisierung: die Version des Datensatzes, als das Formular
  // angezeigt wurde (optimistisches Sperren, siehe AbstractEntity.version)
  version?: number;
}

export interface IBusiness {
  // Lesezugriffe (unverändert)
  getAllClients(): Promise<Client[]>;
  getAllDoctors(): Promise<Doctor[]>;
  getAllSlots(doctorId: number): Promise<Slot[]>;
  getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]>;
  getClientById(id: number): Promise<Client | null>;
  getDoctorById(id: number): Promise<Doctor | null>;
  getAppointmentById(id: number): Promise<Appointment | null>;
  getSlotById(id: number): Promise<Slot | null>;
  getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null>;
  /** der Client (Patient), dessen Benutzerkonto [userId] ist, oder null */
  getClientByUserId(userId: number): Promise<Client | null>;
  /** die Termine eines Clients, heute oder in der Zukunft, mit Slot und Arzt */
  getClientUpcomingAppointments(clientId: number): Promise<Appointment[]>;

  // Termine (ADMIN, DOCTOR, USER)
  /**
   * wirft eine BusinessException, wenn:
   *  - der Tag in der Vergangenheit liegt ('ERRORS.PAST_DATE');
   *  - der Patient bereits einen bevorstehenden Termin hat ('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
   *  - das Zeitfenster an diesem Tag bereits belegt ist ('ERRORS.SLOT_ALREADY_BOOKED').
   */
  addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment>;
  deleteAppointment(appointment: Appointment): Promise<void>;

  // Ärzte (ADMIN)
  /** erstellt den Arzt UND dessen Benutzerkonto (Rolle DOCTOR) */
  addDoctor(data: PersonData): Promise<Doctor>;
  /** aktualisiert den Arzt UND dessen Benutzerkonto */
  editDoctor(id: number, data: PersonData): Promise<Doctor>;
  /** löscht den Arzt, die Slots UND das Konto - abgelehnt, wenn Termine vorhanden sind */
  deleteDoctor(id: number): Promise<void>;

  // Clients
  // (der ADMIN; addClient wird auch für die Registrierung eines Patienten verwendet,
  // editClient und deleteClient durch den Patienten für sein eigenes Konto)
  /** erstellt den Client UND dessen Benutzerkonto (Rolle USER) */
  addClient(data: PersonData): Promise<Client>;
  editClient(id: number, data: PersonData): Promise<Client>;
  /**
   * löscht den Client, das Konto UND alle Termine (vergangene und künftige).
   * Verwendet vom ADMIN (Seite "Clients") und vom Patienten
   * selbst ("Manage my account").
   */
  deleteClient(id: number): Promise<void>;
}

export const BUSINESS_TOKEN = 'IBusiness';
  • Zeilen 17–30: die Daten eines Arztes oder Clients, der erstellt oder geändert werden soll. Benutzername und Passwort sind optional: Beim Erstellen entsprechen sie standardmäßig dem Namen in Kleinbuchstaben; beim Ändern ändern sie sich nur, wenn sie eingegeben wurden;
  • Zeilen 32–78: der Vertrag der Geschäftsschicht – was andere Schichten von ihr anfordern können. Die Kommentare [/** ... */] sind Dokumentationskommentare, die [VS Code] anzeigt, wenn man mit der Maus über die Methode fährt;
  • Zeile 80: das Token, unter dem die Implementierung in [app.module.ts] registriert wird. Eine [TypeScript]-Schnittstelle verschwindet beim Kompilieren: Sie kann nicht für die Dependency Injection verwendet werden. Die Injektion erfolgt daher über dieses Token: [@Inject(BUSINESS_TOKEN)].

11.11.4. src/business/business.service.ts

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
// =========================================================================
// business/business.service.ts
// -------------------------------------------------------------------------
// Implementierung der Geschäftsschicht.
//
// Die Lesezugriffe und der Terminkalender werden unverändert aus dem JSON-Server übernommen. Neu
// ist die Verwaltung von Ärzten und Clients, die drei
// Geschäftsregeln befolgt:
//
//   1. eine Person (Arzt oder Client) und ihr Benutzerkonto gehören IMMER
//      zusammen: sie werden zusammen erstellt, aktualisiert und gelöscht, in
//      einer einzigen TRANSAKTION - entweder gelingt alles, oder nichts wird 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 (die
//        Patienten des Arztes würden ihren Termin verlieren, ohne es zu erfahren): diese
//        müssen zuerst storniert werden. Die Zeitslots des Arztes verschwinden ebenfalls;
//      - ein CLIENT hingegen verschwindet mit ALLEN seinen Terminen (vergangenen und
//        zukünftigen) - ganz gleich, ob das Löschen vom ADMIN oder vom Patienten
//        selbst ausgeht.
//
// Und zwei Regeln für das Buchen von Terminen, unabhängig von der Rolle
// der buchenden Person (ADMIN, DOCTOR oder der Patient selbst):
//   4. kein Termin in der Vergangenheit;
//   5. ein Patient hat jeweils nur EINEN anstehenden Termin.
//
// Ärzte und Clients folgen exakt denselben Regeln: der gemeinsame Code
// wird nur EINMAL geschrieben (private xxxPerson-Methoden) und durch einen
// kleinen "Deskriptor" parametrisiert, der angibt, mit welchem Personentyp wir es zu tun haben.
// =========================================================================

import { Injectable } from '@nestjs/common';
import { DataSource, EntityManager, QueryFailedError } from 'typeorm';
import * as bcrypt from 'bcryptjs';
import { PersonData, IBusiness } from './business.interface';
import { BusinessException } from './business.exception';
import { DoctorRepository } from '../repositories/doctor.repository';
import { ClientRepository } from '../repositories/client.repository';
import { SlotRepository } from '../repositories/slot.repository';
import { AppointmentRepository } from '../repositories/appointment.repository';
import { UserRepository } from '../repositories/user.repository';
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Doctor } from '../entities/doctor.entity';
import { Person } from '../entities/person.entity';
import { Appointment } from '../entities/appointment.entity';
import { Role, User } from '../entities/user.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';
import { DoctorDaySlot } from '../domain/doctor-day-slot';
import { today } from './dates';

// Anzahl der bcrypt-Salt-Runden - dieselbe wie im SQL-Skript ($2b$10$...)
const BCRYPT_ROUNDS = 10;

// was die beiden DAOs DoctorRepository und ClientRepository gemeinsam haben
// (TypeScript prüft die Kompatibilität anhand der FORM von Objekten: beide
// Klassen erfüllen dieses Interface, ohne es deklarieren zu müssen)
interface PersonDao<T extends Person> {
  findById(id: number, manager?: EntityManager): Promise<T | null>;
  findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<T | null>;
  save(person: T, manager?: EntityManager): Promise<T>;
  deleteById(id: number, manager?: EntityManager): Promise<void>;
}

// alles, was einen Arzt von einem Client für die Geschäftsregeln unterscheidet
interface PersonDescriptor<T extends Person> {
  dao: PersonDao<T>;
  create: () => T; // new Doctor() oder new Client()
  role: Role; // DOCTOR oder USER
  notFoundKey: string; // Meldung, wenn die Person nicht existiert
  alreadyExistsKey: string; // Meldung, wenn derselbe Vor- und Nachname bereits existiert
  // optional: falls vorhanden, wird das Löschen ABGELEHNT, solange die Person
  // Termine hat (countAppointments > 0), mit der Meldung hasAppointmentsKey
  countAppointments?: (id: number, manager: EntityManager) => Promise<number>;
  hasAppointmentsKey?: string;
  // optional: was VOR der Person gelöscht werden muss (die Zeilen, die
  // über einen Fremdschlüssel auf die Person verweisen)
  beforeDelete?: (id: number, manager: EntityManager) => Promise<void>;
}

@Injectable()
export class BusinessService implements IBusiness {
  private readonly doctorDescriptor: PersonDescriptor<Doctor>;
  private readonly clientDescriptor: PersonDescriptor<Client>;

  constructor(
    // DataSource: die TypeORM-Verbindung selbst, bereitgestellt von
    // TypeOrmModule.forRoot(...). Wir verwenden sie NUR, um
    // Transaktionen zu öffnen (dataSource.transaction(...)) - die Abfragen
    // bleiben dagegen in der DAO-Schicht.
    private readonly dataSource: DataSource,
    private readonly doctorRepository: DoctorRepository,
    private readonly clientRepository: ClientRepository,
    private readonly slotRepository: SlotRepository,
    private readonly appointmentRepository: AppointmentRepository,
    private readonly userRepository: UserRepository,
  ) {
    this.doctorDescriptor = {
      dao: doctorRepository,
      create: () => new Doctor(),
      role: 'DOCTOR',
      notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
      alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
      countAppointments: (id, manager) => appointmentRepository.countByDoctor(id, manager),
      hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
      // ein Arzt ohne Termine kann dennoch Zeitslots haben:
      // sie ergeben ohne den Arzt keinen Sinn, sie werden ebenfalls gelöscht (andernfalls
      // würde der Fremdschlüssel slots.doctor_id das Löschen verbieten).
      beforeDelete: (id, manager) => slotRepository.deleteByDoctor(id, manager),
    };
    this.clientDescriptor = {
      dao: clientRepository,
      create: () => new Client(),
      role: 'USER',
      notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
      alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
      // kein countAppointments: das Löschen eines Clients wird nie abgelehnt;
      // seine Termine (vergangene und zukünftige) werden mit ihm gelöscht (andernfalls
      // würde der Fremdschlüssel appointments.client_id das Löschen verbieten)
      beforeDelete: (id, manager) => appointmentRepository.deleteByClient(id, manager),
    };
  }

  // =======================================================================
  // Lesezugriffe - unverändert gegenüber dem JSON-Server
  // =======================================================================

  getAllClients(): Promise<Client[]> {
    return this.clientRepository.findAll();
  }

  getAllDoctors(): Promise<Doctor[]> {
    return this.doctorRepository.findAll();
  }

  getAllSlots(doctorId: number): Promise<Slot[]> {
    return this.slotRepository.getAllSlots(doctorId);
  }

  getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
    return this.appointmentRepository.getDoctorDayAppointments(doctorId, day);
  }

  getClientById(id: number): Promise<Client | null> {
    return this.clientRepository.findById(id);
  }

  getDoctorById(id: number): Promise<Doctor | null> {
    return this.doctorRepository.findById(id);
  }

  getAppointmentById(id: number): Promise<Appointment | null> {
    return this.appointmentRepository.findById(id);
  }

  getSlotById(id: number): Promise<Slot | null> {
    return this.slotRepository.findById(id);
  }

  getClientByUserId(userId: number): Promise<Client | null> {
    return this.clientRepository.findByUserId(userId);
  }

  getClientUpcomingAppointments(clientId: number): Promise<Appointment[]> {
    return this.appointmentRepository.findUpcomingByClient(clientId, today());
  }

  // derselbe Algorithmus wie im JSON-Server (und im ursprünglichen Spring-Projekt)
  async getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null> {
    const doctor = await this.getDoctorById(doctorId);
    if (doctor === null) {
      return null;
    }
    const timeSlots = await this.getAllSlots(doctorId);
    const bookings = await this.getDoctorDayAppointments(doctorId, day);
    const bookingsBySlot = new Map<number, Appointment>();
    for (const booking of bookings) {
      bookingsBySlot.set(booking.slotId, booking);
    }
    const doctorDaySlots = timeSlots.map(
      (slot) => new DoctorDaySlot(slot, bookingsBySlot.get(slot.id) ?? null),
    );
    return new DoctorDaySchedule(doctor, day, doctorDaySlots);
  }

  // =======================================================================
  // Termine
  // =======================================================================

  // -----------------------------------------------------------------------
  // Buchen eines Termins, in einer Transaktion:
  //   1. kein Termin in der Vergangenheit;
  //   2. wir SPERREN die Zeile des Patienten (SELECT ... FOR UPDATE): wenn
  //      derselbe Patient zwei Slots im selben Moment 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 anstehender Termin pro Patient;
  //   4. schließlich das Einfügen. Wenn der Slot gerade von einem ANDEREN
  //      Patienten belegt wurde, ist es die SQL-Bedingung unq1_appointments (day, slot_id), die
  //      das Einfügen ablehnt - von transaction() in eine BusinessException übersetzt.
  // -----------------------------------------------------------------------
  addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment> {
    return this.transaction(async (manager) => {
      const todayDate = today();
      if (day < todayDate) {
        throw new BusinessException('ERRORS.PAST_DATE');
      }
      if ((await this.clientRepository.lock(client.id, manager)) === null) {
        throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
      }
      if ((await this.appointmentRepository.countUpcomingByClient(client.id, todayDate, manager)) > 0) {
        throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
      }
      const appointment = new Appointment();
      appointment.day = day;
      appointment.slot = slot;
      appointment.client = client;
      return this.appointmentRepository.save(appointment, manager);
    });
  }

  async deleteAppointment(appointment: Appointment): Promise<void> {
    await this.appointmentRepository.deleteById(appointment.id);
  }

  // =======================================================================
  // Ärzte und Clients - die öffentlichen Methoden delegieren an die gemeinsamen
  // privaten Methoden, mit dem passenden Deskriptor
  // =======================================================================

  addDoctor(data: PersonData): Promise<Doctor> {
    return this.addPerson(this.doctorDescriptor, data);
  }

  editDoctor(id: number, data: PersonData): Promise<Doctor> {
    return this.editPerson(this.doctorDescriptor, id, data);
  }

  deleteDoctor(id: number): Promise<void> {
    return this.deletePerson(this.doctorDescriptor, id);
  }

  addClient(data: PersonData): Promise<Client> {
    return this.addPerson(this.clientDescriptor, data);
  }

  editClient(id: number, data: PersonData): Promise<Client> {
    return this.editPerson(this.clientDescriptor, id, data);
  }

  // der Client, das Konto UND alle Termine (ADMIN oder der Patient
  // selbst über "Manage my account": dieselbe Methode, dieselbe Regel)
  deleteClient(id: number): Promise<void> {
    return this.deletePerson(this.clientDescriptor, id);
  }

  // -----------------------------------------------------------------------
  // Erstellung: zuerst das Benutzerkonto (die Person verweist darauf),
  // dann die Person - alles in EINER Transaktion.
  // -----------------------------------------------------------------------
  private addPerson<T extends Person>(d: PersonDescriptor<T>, data: PersonData): Promise<T> {
    const lastName = data.lastName.trim().toUpperCase();
    const firstName = data.firstName.trim();
    // die Regeln der Datenbank dbrdvmedecins2: Login = Nachname in Kleinbuchstaben,
    // Passwort = Login - es sei denn, der ADMIN hat andere Werte eingegeben
    const login = (data.login || lastName).toLowerCase();
    const password = data.password || login;

    return this.transaction(async (manager) => {
      await this.checkPersonUnique(d, firstName, lastName, null, manager);
      await this.checkLoginFree(login, manager);

      const user = new User();
      user.login = login;
      user.password = await bcrypt.hash(password, BCRYPT_ROUNDS);
      user.name = `${firstName} ${lastName}`;
      user.role = d.role;
      await this.userRepository.save(user, manager);

      const person = d.create();
      person.title = data.title;
      person.lastName = lastName;
      person.firstName = firstName;
      person.user = user;
      return d.dao.save(person, manager);
    });
  }

  // -----------------------------------------------------------------------
  // Aktualisierung: die Person UND das Konto (der Anzeigename "firstName LASTNAME"
  // muss mitziehen; Login und Passwort ändern sich nur, wenn sie
  // eingegeben wurden).
  // -----------------------------------------------------------------------
  private editPerson<T extends Person>(
    d: PersonDescriptor<T>,
    id: number,
    data: PersonData,
  ): Promise<T> {
    return this.transaction(async (manager) => {
      const person = await d.dao.findById(id, manager);
      if (person === null) {
        throw new BusinessException(d.notFoundKey);
      }
      // optimistisches Sperren: wenn die Version in der Datenbank nicht mehr die des
      // Formulars ist, hat jemand diesen Datensatz in der Zwischenzeit geändert - wir lehnen ab,
      // statt seine Änderungen stillschweigend zu überschreiben.
      if (data.version !== undefined && data.version !== person.version) {
        throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
      }

      person.title = data.title;
      person.lastName = data.lastName.trim().toUpperCase();
      person.firstName = data.firstName.trim();
      await this.checkPersonUnique(d, person.firstName, person.lastName, id, manager);

      const user = person.user;
      user.name = `${person.firstName} ${person.lastName}`;
      if (data.login && data.login.toLowerCase() !== user.login) {
        const login = data.login.toLowerCase();
        await this.checkLoginFree(login, manager);
        user.login = login;
      }
      if (data.password) {
        user.password = await bcrypt.hash(data.password, BCRYPT_ROUNDS);
      }
      await this.userRepository.save(user, manager);
      return d.dao.save(person, manager);
    });
  }

  // -----------------------------------------------------------------------
  // Löschen, in EINER Transaktion, in der durch die Fremdschlüssel
  // vorgegebenen Reihenfolge:
  //   1. mögliche Ablehnung, wenn noch Termine vorhanden sind (Arzt);
  //   2. was auf die Person verweist (Slots eines Arztes, Termine
  //      eines Clients);
  //   3. die Person (sie verweist auf das Konto);
  //   4. das Konto.
  // -----------------------------------------------------------------------
  private deletePerson<T extends Person>(d: PersonDescriptor<T>, id: number): Promise<void> {
    return this.transaction(async (manager) => {
      const person = await d.dao.findById(id, manager);
      if (person === null) {
        throw new BusinessException(d.notFoundKey);
      }
      if (d.countAppointments && (await d.countAppointments(id, manager)) > 0) {
        throw new BusinessException(d.hasAppointmentsKey ?? 'ERRORS.INVALID_FORM');
      }
      if (d.beforeDelete) {
        await d.beforeDelete(id, manager);
      }
      await d.dao.deleteById(id, manager);
      await this.userRepository.deleteById(person.userId, manager);
    });
  }

  // lehnt einen Vor- und Nachnamen ab, der von einer ANDEREN Person desselben Typs verwendet wird
  // (currentId: die zu aktualisierende Person, die selbstverständlich das
  // Recht hat, ihren eigenen Vor- und Nachnamen zu behalten; null bei einer Erstellung)
  private async checkPersonUnique<T extends Person>(
    d: PersonDescriptor<T>,
    firstName: string,
    lastName: string,
    currentId: number | null,
    manager: EntityManager,
  ): Promise<void> {
    const namesake = await d.dao.findByFirstNameLastName(firstName, lastName, manager);
    if (namesake !== null && namesake.id !== currentId) {
      throw new BusinessException(d.alreadyExistsKey);
    }
  }

  private async checkLoginFree(login: string, manager: EntityManager): Promise<void> {
    if ((await this.userRepository.findByLogin(login, manager)) !== null) {
      throw new BusinessException('ERRORS.LOGIN_TAKEN');
    }
  }

  // -----------------------------------------------------------------------
  // führt [work] in einer Transaktion aus: dataSource.transaction() führt
  // START TRANSACTION aus, ruft [work] mit einem an diese Transaktion gebundenen EntityManager auf,
  // dann COMMIT, wenn alles gut ging - oder ROLLBACK, wenn eine
  // Exception geworfen wurde (BusinessException eingeschlossen).
  //
  // Die Prüfungen "Login frei" und "eindeutiger Vor- + Nachname" erfolgen VOR
  // dem Schreiben, um eine klare Meldung zu liefern. Aber zwei ADMINs könnten
  // im selben Moment dasselbe Login (oder denselben Arzt) speichern: in diesem
  // seltenen Fall lehnt eine SQL-Eindeutigkeitsbedingung das zweite
  // Schreiben ab - diesen SQL-Fehler übersetzen wir dann in dieselbe BusinessException.
  // -----------------------------------------------------------------------
  private async transaction<R>(work: (manager: EntityManager) => Promise<R>): Promise<R> {
    try {
      return await this.dataSource.transaction(work);
    } catch (e) {
      throw translateDuplicate(e);
    }
  }
}

// -------------------------------------------------------------------------
// Verletzungen von Eindeutigkeitsbedingungen -> BusinessException
//
// Wenn eine UNIQUE-Bedingung einen Schreibvorgang ablehnt, liefert MySQL den Fehler
// ER_DUP_ENTRY (Nr. 1062), dessen Meldung den NAMEN der Bedingung zitiert:
//   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
// BENENNT das SQL-Skript alle seine Bedingungen: jede kann so
// in eine eigene Meldung übersetzt werden.
// -------------------------------------------------------------------------
const CONSTRAINT_MESSAGES: Record<string, string> = {
  unq_users_login: 'ERRORS.LOGIN_TAKEN',
  unq_doctors_first_name_last_name: 'ERRORS.DOCTOR_ALREADY_EXISTS',
  unq_clients_first_name_last_name: 'ERRORS.PATIENT_ALREADY_EXISTS',
  unq1_appointments: 'ERRORS.SLOT_ALREADY_BOOKED',
};

// gibt die BusinessException zurück, die zur verletzten Bedingung passt, oder
// den ursprünglichen Fehler unverändert, wenn es sich nicht um eine bekannte Verletzung handelt
function translateDuplicate(e: unknown): unknown {
  if (!(e instanceof QueryFailedError)) {
    return e;
  }
  const sqlError = e.driverError as { code?: string; sqlMessage?: string };
  if (sqlError?.code !== 'ER_DUP_ENTRY') {
    return e;
  }
  // "... for key 'doctors.unq_doctors_first_name_last_name'" -> "unq_doctors_first_name_last_name"
  const constraint = /for key '(?:[^'.]*\.)?([^']+)'/.exec(sqlError.sqlMessage ?? e.message)?.[1];
  const key = constraint ? CONSTRAINT_MESSAGES[constraint] : undefined;
  return key ? new BusinessException(key) : e;
}

Dies ist die umfangreichste Datei der Anwendung. Gehen wir sie Abschnitt für Abschnitt durch.

11.11.4.1. Die Deskriptoren

  • Zeile 54: die Kosten von bcrypt, dieselben wie im SQL-Skript;
  • Zeilen 59–64: was die DAO-Klassen für Ärzte und Clients gemeinsam haben. [TypeScript] vergleicht Typen anhand ihrer Form: [DoctorRepository] und [ClientRepository] erfüllen diese Schnittstelle, ohne sie zu deklarieren ([implements]);
  • Zeilen 67–80: alles, was in der Geschäftslogik einen Arzt von einem Client unterscheidet: sein DAO, wie eine Instanz erzeugt wird, die Rolle seines Kontos, seine Fehlermeldungen und was beim Löschen geschieht. Da Ärzte und Clients denselben Regeln folgen, wird der Code für diese Regeln nur einmal geschrieben, in generischen Methoden, die durch einen Deskriptor parametrisiert werden;
  • Zeilen 87–98: Der Konstruktor erhält die [DataSource] (zum Öffnen von Transaktionen) und die fünf DAO. Er konstruiert die beiden Deskriptoren. Der für Ärzte (Zeilen 99–111) verhindert das Löschen eines Arztes mit Terminen ([countAppointments]) und löscht dessen Zeitfenster, bevor der Arzt gelöscht wird ([beforeDelete]). Der für Clients (Zeilen 112–122) hat kein [countAppointments]: Ein Client wird zusammen mit seinen Terminen gelöscht.

11.11.4.2. Leseoperationen und der Kalender

  • Zeilen 129–167: Die Abfragen delegieren an die DAO-Schicht;
  • Zeilen 170–185: die Kalenderberechnung. Die Zeitfenster des Arztes und die heutigen Termine werden gelesen; die Termine werden in einer [Map] gespeichert, die nach der ID ihres Zeitfensters indiziert ist; dann wird jedem Zeitfenster sein Termin zugeordnet oder [null]. Die [Map] erspart es, für jedes Zeitfenster die Terminliste zu durchsuchen.

11.11.4.3. Einen Termin vereinbaren

  • Zeilen 203–221: Alles geschieht innerhalb einer einzigen Transaktion;
  • Zeilen 206–208: keine Termine in der Vergangenheit;
  • Zeilen 209–211: Der Datensatz des Patienten wird gesperrt. Ohne diese Sperre könnten zwei gleichzeitig abgesendete Termine für denselben Patienten (zwei Tabs, ein Doppelklick) beide den folgenden Test bestehen, bevor einer von ihnen seinen Termin in die Datenbank geschrieben hat. Mit der Sperre wartet die zweite Transaktion, bis die erste abgeschlossen ist, und sieht dann den Termin, den diese angelegt hat;
  • Zeilen 212–214: nur ein bevorstehender Termin pro Patient;
  • Zeilen 215–219: das Einfügen. Hat ein anderer Patient soeben dasselbe Zeitfenster gebucht, weist die Bedingung [unq1_appointments] das Einfügen zurück, und die Methode [transaction] behandelt den Fehler (siehe unten);
  • Zeilen 223–225: das Löschen eines Termins.

11.11.4.4. Verwaltung von Ärzten und Clients

  • Zeilen 232–256: Die sechs öffentlichen Methoden delegieren an die drei generischen Methoden und verwenden dabei den passenden Deskriptor;
  • Zeilen 262–288: das Erstellen. Der Name wird großgeschrieben; standardmäßig ist der Benutzername der Name in Kleinbuchstaben und das Passwort der Benutzername (Zeilen 267–268). Innerhalb der Transaktion werden die Eindeutigkeitsregeln geprüft, das Konto wird erstellt (das Passwort wird gehasht), gefolgt von der Person, die mit dem Konto verknüpft wird. Schlägt die zweite Schreiboperation fehl, wird die erste rückgängig gemacht: Ein Konto wird niemals ohne Person erstellt;
  • Zeilen 295–299: die Änderung. Das optimistische Sperren (Zeilen 308–310) weist einen Datensatz zurück, der in der Zwischenzeit geändert wurde. Der angezeigte Name des Kontos folgt dem Vor- und Nachnamen; Benutzername und Passwort ändern sich nur, wenn sie eingegeben wurden;
  • Zeilen 341–356: das Löschen, in der durch die Fremdschlüssel vorgegebenen Reihenfolge: mögliche Ablehnung (ein Arzt mit Terminen), Löschen der Verweise auf die Person (die Zeitfenster eines Arztes, die Termine eines Clients), Löschen der Person und schließlich Löschen ihres Kontos;
  • Zeilen 361–367: Eine Person mit demselben Namen wird abgelehnt, es sei denn, es handelt sich um die Person selbst (Änderung);
  • Zeilen 374–378: Ein bereits vergebener Benutzername wird abgelehnt.

11.11.4.5. Transaktionen und Eindeutigkeitsbedingungen

  • Zeilen 392–398: Alle Schreibvorgänge laufen über diese Methode: [dataSource.transaction] bestätigt oder verwirft die Transaktion (siehe Beispiel 28), und ein Fehler wird von [translateDuplicate] übersetzt;
  • Zeilen 411–416: Jede benannte Eindeutigkeitsbedingung im SQL-Skript hat ihre eigene Fehlermeldung;
  • Zeilen 420–432: Ein SQL-Fehler ([QueryFailedError]) mit dem Code [ER_DUP_ENTRY] ist eine Verletzung einer Eindeutigkeitsbedingung. Seine Meldung enthält den Namen der Bedingung (bei [MySQL] 8 mit dem Tabellennamen als Präfix, bei [MariaDB] ohne Präfix): Der reguläre Ausdruck in Zeile 429 extrahiert ihn. Eine bekannte Bedingung wird zur [BusinessException]; jeder andere Fehler wird unverändert weitergegeben: Das ist eine echte Anomalie.

11.12. Authentifizierung

Der Ordner [auth] enthält in ausführlicherer Form die Beispiele 25 bis 27: das JWT-Token in einem Cookie, Rollen, CAPTCHA und Begrenzung der Versuche. Außerdem enthält er einen „Pass“ für die Kontoerstellung.

11.12.1. src/auth/auth.constants.ts

// =========================================================================
// auth/auth.constants.ts
// -------------------------------------------------------------------------
// Wo wird das JWT-Token übertragen?
//
// Beim Angular-Client war es der JavaScript-Code des Clients, der das Token
// aufbewahrte (localStorage) und es selbst jeder Anfrage hinzufügte (Header
// "Authorization: Bearer ..."). Ein Browser, der gewöhnliche HTML-Seiten
// anzeigt, kann das nicht: damit er das Token von
// allein bei jeder Anfrage vorlegt, muss das Token in einem COOKIE gespeichert sein.
//
// Die Optionen dieses Cookies sind für die Sicherheit wichtig:
//   - httpOnly: das JavaScript der Seite kann das Cookie nicht lesen (ein
//     eingeschleustes Skript könnte das Token somit nicht stehlen);
//   - sameSite 'lax': der Browser sendet das Cookie NICHT bei einem POST,
//     der von einer anderen Website kommt. Da alle Actions, die
//     Daten ändern, POSTs sind, kann eine präparierte Seite auf einer anderen Website nichts
//     buchen oder löschen, indem sie sich als
//     der Benutzer ausgibt (sogenannter CSRF-Angriff);
//   - secure: in Produktion (HTTPS) wird das Cookie nie im Klartext übertragen;
//   - maxAge: das Cookie verschwindet zugleich mit dem Ablauf des Tokens.
// =========================================================================

import { CookieOptions } from 'express';

export const COOKIE_JWT = 'rdvmedecins_jwt';

export const JWT_SECRET = process.env.JWT_SECRET ?? 'dev-secret-change-in-production';

export const JWT_EXPIRES_IN_SECONDS = process.env.JWT_EXPIRES_IN_SECONDS
  ? parseInt(process.env.JWT_EXPIRES_IN_SECONDS, 10)
  : 7200;

export function jwtCookieOptions(): CookieOptions {
  return {
    httpOnly: true,
    sameSite: 'lax',
    secure: process.env.COOKIE_SECURE === 'true',
    maxAge: JWT_EXPIRES_IN_SECONDS * 1000, // in Millisekunden für Express
    path: '/',
  };
}
  • Zeilen 4–21: Der Kommentar erklärt, warum das Token in einem Cookie gespeichert wird und wozu jede seiner Optionen dient (siehe Beispiel 25);
  • Zeile 28: der Schlüssel, gelesen aus [.env]. Der Standardwert sollte nur während der Entwicklung verwendet werden;
  • Zeilen 30–32: die Gültigkeitsdauer des Tokens: standardmäßig zwei Stunden;
  • Zeilen 34–42: die Cookie-Optionen, an einer Stelle zusammengefasst (sie werden bei der Anmeldung und beim Ändern des Kontos eines Patienten verwendet). [secure] ist nur in der Produktion aktiviert, wo die Website über HTTPS ausgeliefert wird; [maxAge] wird in Millisekunden angegeben.

11.12.2. src/auth/auth.service.ts

// =========================================================================
// auth/auth.service.ts
// -------------------------------------------------------------------------
// Die Authentifizierungslogik:
//   - validateUser() : prüft ein Paar aus Login und Passwort;
//   - createToken()  : erzeugt das JWT-Token eines validierten Benutzers;
//   - readToken()    : prüft ein Token (Login-Seite: wenn der
//                      Benutzer bereits angemeldet ist, muss das Passwort nicht
//                      erneut abgefragt werden).
// =========================================================================

import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcryptjs';
import { UserRepository } from '../repositories/user.repository';
import { User } from '../entities/user.entity';
import { JwtPayload } from './jwt.strategy';

@Injectable()
export class AuthService {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly jwtService: JwtService,
  ) {}

  async validateUser(login: string, password: string): Promise<User | null> {
    const user = await this.userRepository.findByLogin(login);
    if (user === null) {
      return null;
    }
    return (await bcrypt.compare(password, user.password)) ? user : null;
  }

  createToken(user: User): string {
    const payload: JwtPayload = { sub: user.id, login: user.login, name: user.name, role: user.role };
    return this.jwtService.sign(payload);
  }

  // gibt den Inhalt des Tokens zurück, wenn es gültig ist (korrekte Signatur, nicht
  // abgelaufen), andernfalls null
  readToken(token: string | undefined): JwtPayload | null {
    if (!token) {
      return null;
    }
    try {
      return this.jwtService.verify<JwtPayload>(token);
    } catch {
      return null;
    }
  }
}
  • Zeilen 26–32: das Konto, wenn Benutzername und Passwort korrekt sind ([bcrypt.compare]), andernfalls [null];
  • Zeilen 34–37: das Token, das die ID, den Benutzernamen, den Anzeigenamen und die Rolle enthält;
  • Zeilen 41–50: [jwtService.verify] überprüft die Signatur und das Ablaufdatum eines Tokens und löst eine Exception aus, wenn es ungültig ist. Diese Methode wird von ungeschützten Seiten (der Anmeldeseite) verwendet, die feststellen wollen, ob der Benutzer bereits angemeldet ist.

11.12.3. src/auth/jwt.strategy.ts

// =========================================================================
// auth/jwt.strategy.ts
// -------------------------------------------------------------------------
// Die Passport-Strategie, die JEDE geschützte Anfrage anhand des
// JWT-Tokens authentifiziert. Einziger Unterschied zum JSON-Server: das Token wird aus dem
// Cookie [rdvmedecins_jwt] gelesen (siehe auth.constants.ts) statt aus dem
// Header "Authorization: Bearer ...".
// =========================================================================

import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { Request } from 'express';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { Role } from '../entities/user.entity';
import { COOKIE_JWT, JWT_SECRET } from './auth.constants';

// was IM Token gespeichert wird, wenn es erzeugt wird (siehe AuthService).
// Der Anzeigename ist ebenfalls enthalten, damit die Navigationsleiste
// ihn anzeigen kann, ohne bei jeder Seite die Datenbank abzufragen.
export interface JwtPayload {
  sub: number; // die id des Benutzers (JWT-Konvention)
  login: string;
  name: string;
  role: Role;
}

// was request.user enthalten wird, sobald das Token verifiziert ist
export interface ConnectedUser {
  userId: number;
  login: string;
  name: string;
  role: Role;
}

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
  constructor() {
    super({
      // fromExtractors([...]): wir stellen UNSERE eigene Funktion zum Extrahieren des Tokens bereit -
      // hier das Lesen eines Cookies (req.cookies wird von der Middleware
      // cookie-parser gefüllt, siehe main.ts).
      jwtFromRequest: ExtractJwt.fromExtractors([(req: Request) => req?.cookies?.[COOKIE_JWT] ?? null]),
      ignoreExpiration: false,
      secretOrKey: JWT_SECRET,
    });
  }

  validate(payload: JwtPayload): ConnectedUser {
    return { userId: payload.sub, login: payload.login, name: payload.name, role: payload.role };
  }
}
  • Zeilen 20–25: der Inhalt des Tokens;
  • Zeilen 28–33: was [req.user] enthalten wird;
  • Zeilen 38–45: Das Token wird aus dem Cookie gelesen; ist es abgelaufen oder falsch signiert, wird es abgelehnt;
  • Zeilen 48–50: Der Inhalt des Tokens wird zu [req.user].

11.12.4. src/auth/jwt-auth.guard.ts

// =========================================================================
// auth/jwt-auth.guard.ts
// -------------------------------------------------------------------------
// Der Guard, der alle Seiten der Anwendung schützt (außer /login): er
// verlangt ein gültiges JWT-Token (siehe jwt.strategy.ts, registriert unter dem Namen
// 'jwt'). Ohne Token oder mit einem ungültigen/abgelaufenen Token wirft er eine
// UnauthorizedException - die HtmlExceptionFilter in eine Weiterleitung
// auf die Login-Seite umwandelt (siehe web/html-exception.filter.ts).
// =========================================================================

import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}

Der Guard, der ein gültiges Token verlangt (siehe Beispiel 25). Ohne Token löst er eine [UnauthorizedException] aus, die der Exception-Filter in eine Weiterleitung auf [/login] umwandelt.

11.12.5. src/auth/roles.decorator.ts

// =========================================================================
// auth/roles.decorator.ts
// -------------------------------------------------------------------------
// @Roles('ADMIN') ist ein SELBSTGEBAUTER Dekorator (wir schreiben ihn selbst,
// anders als @Get/@Post/@Injectable, die NestJS bereitstellt): er hängt lediglich
// eine Metadatenangabe ("diese Methode erfordert eine bestimmte Rolle") an
// die Methode an, die er dekoriert, ohne selbst etwas zu prüfen - RolesGuard
// (siehe roles.guard.ts) liest diese Metadaten und führt die Prüfung durch.
//
// SetMetadata(key, value) ist die NestJS-Low-Level-Funktion, mit der
// sich diese Art von "eigenem" Dekorator schreiben lässt: wir verwenden sie hier, um den
// String 'roles' nicht überall im Code wiederholen zu müssen.
// =========================================================================

import { SetMetadata } from '@nestjs/common';
import { Role } from '../entities/user.entity';

export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

Zeile 19: der Dekorator [@Roles(...)] (siehe Beispiel 26). Seine Parameter sind vom Typ [Role]: [@Roles('ADMIM')] (Tippfehler) wird vom Compiler abgelehnt.

11.12.6. src/auth/roles.guard.ts

// =========================================================================
// auth/roles.guard.ts
// -------------------------------------------------------------------------
// Zweite Kontrollebene, NACH JwtAuthGuard: dieser prüft nur,
// dass wir tatsächlich authentifiziert sind (ein gültiges JWT-Token); RolesGuard
// prüft zusätzlich, ob die Rolle des angemeldeten Benutzers (request.user.role,
// von JwtStrategy gesetzt) zu den von @Roles(...) verlangten gehört,
// die an der anvisierten Methode stehen.
//
// Unverändert gegenüber dem JSON-Server, außer dem Ziel des Fehlers:
// die hier geworfene ForbiddenException wird von HtmlExceptionFilter in eine
// SEITE "403 - access forbidden" umgewandelt (siehe web/html-exception.filter.ts).
//
// Es ist sinngemäß das Äquivalent der Spring-Security-Regel:
//   http.authorizeRequests().antMatchers(...).hasRole("ADMIN")
// hier aber Methode für Methode statt URL für URL angewendet, dank des
// Paares aus Dekorator (@Roles) + Reflector (der die von einem Dekorator
// gesetzten Metadaten zurücklesen kann).
// =========================================================================

import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from './roles.decorator';
import { Role } from '../entities/user.entity';
import { ConnectedUser } from './jwt.strategy';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    // wir lesen die von @Roles(...) an der anvisierten Methode gesetzten Metadaten zurück -
    // getAllAndOverride schaut zuerst an der Methode, dann an der Klasse.
    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [context.getHandler(), context.getClass()]);

    // keine @Roles(...)-Metadaten an dieser Methode: keine zusätzliche Rollenbeschränkung
    // (JwtAuthGuard wird bereits eine gültige
    // Authentifizierung verlangt haben, gleich welche Rolle).
    if (!requiredRoles || requiredRoles.length === 0) {
      return true;
    }

    // request.user wurde von JwtStrategy.validate() gesetzt (siehe jwt.strategy.ts) -
    // RolesGuard läuft daher IMMER nach JwtAuthGuard (siehe ihre Reihenfolge
    // in @UseGuards(JwtAuthGuard, RolesGuard), siehe src/web/controllers/).
    const request = context.switchToHttp().getRequest<{ user: ConnectedUser }>();
    const user = request.user;

    if (!requiredRoles.includes(user.role)) {
      throw new ForbiddenException(
        `role [${user.role}] does not allow this action (required role: ${requiredRoles.join(', ')})`,
      );
    }
    return true;
  }
}

Die Zuordnung der Rollen ist identisch mit der in Beispiel 26.

11.12.7. src/auth/captcha.service.ts

// =========================================================================
// auth/captcha.service.ts
// -------------------------------------------------------------------------
// Ein CAPTCHA ("test to tell a human from a robot"), das vom
// Server selbst erzeugt wird, ohne externen Dienst: die Bibliothek svg-captcha
// zeichnet einige verzerrte Zeichen, durch Linien verwischt, in ein
// SVG-Bild. Ein Mensch liest sie mühelos; ein Roboter, der
// Formulare nur in einer Schleife sendet, kann es nicht.
//
// So funktioniert es:
//   1. generate() zeichnet einen zufälligen Text, wandelt ihn in ein Bild um und speichert die
//      richtige Antwort IM SPEICHER DES SERVERS unter einer zufälligen Kennung;
//   2. die Seite zeigt das Bild an und legt die Kennung in einem versteckten Feld
//      des Formulars ab (die Antwort selbst verlässt den Server nie);
//   3. verify(id, 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.
//
// Akzeptierte Einschränkung: der Speicher eines einzelnen Node-Prozesses. Bei mehreren
// Servern hinter einem Load Balancer wäre ein gemeinsamer Speicher
// nötig (Redis, Datenbank ...).
// =========================================================================

import { Injectable } from '@nestjs/common';
import { randomUUID } from 'crypto';
import * as svgCaptcha from 'svg-captcha';

// Gültigkeit eines Bildes: Sie haben 10 Minuten, um das Formular auszufüllen
const LIFETIME_MS = 10 * 60 * 1000;
// Speicherschutz: darüber hinaus werden die ältesten Captchas vergessen
const MAX_CAPTCHAS = 10_000;

export interface Captcha {
  id: string; // in das versteckte Feld "captchaId" des Formulars einzutragen
  svg: string; // das Bild, unverändert in die Seite einzufügen
}

@Injectable()
export class CaptchaService {
  // id -> { erwartete Antwort, Ablaufdatum }. Eine Map behält die Einfügereihenfolge
  // bei: ihre ersten Einträge sind die ältesten.
  private readonly pending = new Map<string, { text: string; expires: number }>();

  generate(): Captcha {
    this.purge();
    const { text, data } = svgCaptcha.create({
      size: 5, // 5 Zeichen
      noise: 3, // 3 Störlinien
      color: true,
      background: '#f5f7fa',
      // Zeichen, die zu leicht miteinander zu verwechseln sind: ausgeschlossen
      ignoreChars: '0oO1iIlL',
    });
    const id = randomUUID();
    this.pending.set(id, { text: text.toLowerCase(), expires: Date.now() + LIFETIME_MS });
    return { id, svg: data };
  }

  // true, wenn [input] die richtige Antwort auf das Captcha [id] ist (unabhängig
  // von Groß-/Kleinschreibung). Das Captcha wird in jedem Fall verbraucht.
  verify(id: unknown, input: unknown): boolean {
    if (typeof id !== 'string' || typeof input !== 'string') {
      return false;
    }
    const expected = this.pending.get(id);
    this.pending.delete(id);
    return expected !== undefined && expected.expires > Date.now() && expected.text === input.trim().toLowerCase();
  }

  private purge(): void {
    const now = Date.now();
    for (const [id, { expires }] of this.pending) {
      if (expires <= now || this.pending.size >= MAX_CAPTCHAS) {
        this.pending.delete(id);
      }
    }
  }
}
  • Zeilen 29–31: Im Vergleich zu Beispiel 27 hat ein CAPTCHA eine Lebensdauer (zehn Minuten), und die Anzahl der CAPTCHAs im Speicher ist begrenzt: Ein Bot, der die Anmeldeseite millionenfach aufruft, könnte den Speicher des Servers nicht erschöpfen;
  • Zeile 42: eine [Map] behält die Einfügereihenfolge bei: ihre ältesten Einträge stehen vorn;
  • Zeilen 44–57: das Bild, die erwartete Antwort (in Kleinbuchstaben) und das Ablaufdatum;
  • Zeilen 61–68: Die Antwort wird ohne Beachtung der Groß- und Kleinschreibung verglichen; das CAPTCHA wird in jedem Fall verbraucht;
  • Zeilen 70–77: Abgelaufene CAPTCHAs werden verworfen, ebenso die ältesten, wenn die Obergrenze erreicht ist.

11.12.8. src/auth/attempt-limiter.service.ts

// =========================================================================
// auth/attempt-limiter.service.ts
// -------------------------------------------------------------------------
// Zweite Verteidigungslinie gegen Bots (die erste ist das Captcha): wir ZÄHLEN die
// Versuche, und ab einem Schwellenwert SPERREN wir für eine gewisse Zeit.
//
//   - Login: nach LOGIN_MAX_FAILURES Fehlversuchen (falsches Captcha oder falsches
//     Passwort) für dasselbe Login von derselben IP-Adresse wird dieses Paar
//     für LOGIN_BLOCK_MINUTES Minuten gesperrt. Dieselbe IP-Adresse wird auch
//     gesperrt, wenn sie 5-mal mehr Fehlversuche ansammelt, alle Logins zusammengenommen (ein
//     Bot, der Tausende verschiedener Logins ausprobiert);
//   - Kontoerstellung: höchstens REGISTRATION_MAX_PER_HOUR Konten pro
//     Stunde von derselben IP-Adresse.
//
// Vorsicht in einem Klassenraum: alle Rechner gehen oft über dieselbe IP-Adresse
// ins Internet.
// Deshalb gilt die Login-Sperre zuerst für das Paar (IP, Login) -
// ein Schüler, der sich bei seinem Passwort vertippt, sperrt seine Nachbarn nicht -
// und deshalb lassen sich die Schwellenwerte in der Datei .env festlegen.
//
// Wie beim Captcha liegen die Zähler im Speicher des Prozesses.
// =========================================================================

import { Injectable } from '@nestjs/common';

interface Counter {
  count: number; // im aktuellen Zeitfenster gezählte Versuche
  start: number; // Beginn des Zählfensters (ms)
  blockedUntil: number; // 0, wenn nicht gesperrt
}

const MINUTE = 60 * 1000;

function envInteger(name: string, fallback: number): number {
  const value = parseInt(process.env[name] ?? '', 10);
  return Number.isInteger(value) && value > 0 ? value : fallback;
}

@Injectable()
export class AttemptLimiterService {
  private readonly counters = new Map<string, Counter>();

  private readonly maxLoginFailures = envInteger('LOGIN_MAX_FAILURES', 5);
  private readonly loginBlockDuration = envInteger('LOGIN_BLOCK_MINUTES', 15) * MINUTE;
  private readonly maxRegistrations = envInteger('REGISTRATION_MAX_PER_HOUR', 10);

  // Login

  // Anzahl der verbleibenden Minuten der Sperre (0 = der Versuch ist erlaubt)
  loginBlockMinutes(ip: string, login: string): number {
    return Math.max(this.remainingMinutes(loginKey(ip, login)), this.remainingMinutes(ipKey(ip)));
  }

  loginFailure(ip: string, login: string): void {
    this.count(loginKey(ip, login), this.maxLoginFailures, this.loginBlockDuration, this.loginBlockDuration);
    this.count(ipKey(ip), this.maxLoginFailures * 5, this.loginBlockDuration, this.loginBlockDuration);
  }

  // eine erfolgreiche Anmeldung setzt den Zähler DIESES Logins zurück
  loginSuccess(ip: string, login: string): void {
    this.counters.delete(loginKey(ip, login));
  }

  // Registrierung

  registrationBlockMinutes(ip: string): number {
    return this.remainingMinutes(`registration|${ip}`);
  }

  registrationSuccess(ip: string): void {
    // Zeitfenster von einer Stunde; sobald das Kontingent erreicht ist, gesperrt bis zum Ende der Stunde
    this.count(`registration|${ip}`, this.maxRegistrations, 60 * MINUTE, 60 * MINUTE);
  }

  // gemeinsame Mechanik

  private remainingMinutes(key: string): number {
    const c = this.counters.get(key);
    const remaining = c ? c.blockedUntil - Date.now() : 0;
    return remaining > 0 ? Math.ceil(remaining / MINUTE) : 0;
  }

  // zählt einen Versuch; wird der Schwellenwert innerhalb des Fensters erreicht, wird gesperrt
  private count(key: string, max: number, window: number, block: number): void {
    const now = Date.now();
    this.purge(now);
    let c = this.counters.get(key);
    if (!c || now - c.start > window) {
      c = { count: 0, start: now, blockedUntil: 0 };
      this.counters.set(key, c);
    }
    c.count++;
    if (c.count >= max) {
      c.blockedUntil = now + block;
      c.count = 0; // nach der Sperre beginnen wir wieder bei null
      c.start = c.blockedUntil;
    }
  }

  // wir vergessen die nicht mehr benötigten Zähler (weder gesperrt noch aktuell)
  private purge(now: number): void {
    if (this.counters.size < 1000) {
      return;
    }
    for (const [key, c] of this.counters) {
      if (c.blockedUntil < now && now - c.start > 60 * MINUTE) {
        this.counters.delete(key);
      }
    }
  }
}

function loginKey(ip: string, login: string): string {
  return `login|${ip}|${login.trim().toLowerCase()}`;
}

function ipKey(ip: string): string {
  return `ip|${ip}`;
}
  • Zeilen 26–30: ein Versuchszähler mit dem Beginn seines Zählzeitfensters und dem Ende der Sperre;
  • Zeilen 34–37: ein aus [.env] gelesener Schwellenwert, mit einem Standardwert;
  • Zeilen 50–52: Die Sperre gilt für das Paar (IP-Adresse, Login) und allein für die IP-Adresse, wenn sich über alle Logins hinweg viele fehlgeschlagene Versuche ansammeln. In einem Unterrichtsraum verbinden sich alle Arbeitsplätze oft über dieselbe IP-Adresse: Ein Student, der ein falsches Passwort eingibt, soll seine Nachbarn nicht aussperren;
  • Zeilen 54–57: Ein fehlgeschlagener Versuch zählt für beide Schlüssel;
  • Zeilen 66–68 und 70–73: Die Anzahl der pro Stunde von derselben IP-Adresse aus angelegten Konten ist begrenzt;
  • Zeilen 84–98: das Zählen. Ein abgelaufenes Zeitfenster wird auf null zurückgesetzt; wenn der Schwellenwert erreicht ist, wird der Schlüssel gesperrt;
  • Zeilen 101–110: Alte Zähler werden gelöscht, damit sich nicht unbegrenzt Schlüssel im Speicher ansammeln;
  • Zeilen 113–118: Erzeugung der Schlüssel für [Map].

11.12.9. src/auth/registration-pass.service.ts

// =========================================================================
// auth/registration-pass.service.ts
// -------------------------------------------------------------------------
// Der "Pass" für die Kontoerstellung.
//
// Um die Seite "Create a patient account" zu öffnen, muss man zuvor das Captcha
// der Authentifizierungsseite eingegeben haben (siehe
// RegistrationController, POST /register/access). Der Server stellt dann
// einen Pass aus:
//   - eine zufällige Kennung, in einem httpOnly-Cookie gespeichert;
//   - 15 Minuten gültig (Zeit zum Ausfüllen des Formulars, auch bei
//     mehreren Versuchen nach Eingabefehlern);
//   - verbraucht, sobald ein Konto erstellt wird: EIN gelöstes Captcha = höchstens EIN
//     Konto. Ein Bot kann keine Konten in großer Zahl erstellen.
//
// Ohne gültigen Pass verweisen GET und POST /register zurück auf die
// Authentifizierungsseite: die direkte Eingabe der URL /register
// umgeht das Captcha nicht.
//
// Wie das Captcha liegen die Pässe im Speicher des Prozesses.
// =========================================================================

import { Injectable } from '@nestjs/common';
import { randomUUID } from 'crypto';
import { CookieOptions } from 'express';

export const COOKIE_REGISTRATION_PASS = 'rdvmedecins_registration';

const LIFETIME_MS = 15 * 60 * 1000;
const MAX_PASSES = 10_000;

@Injectable()
export class RegistrationPassService {
  // id -> Ablaufdatum
  private readonly passes = new Map<string, number>();

  // stellt einen neuen Pass aus; gibt dessen Kennung zurück
  issue(): string {
    this.purge();
    const id = randomUUID();
    this.passes.set(id, Date.now() + LIFETIME_MS);
    return id;
  }

  // true, wenn [id] ein vorhandener, nicht abgelaufener Pass ist
  isValid(id: unknown): boolean {
    if (typeof id !== 'string') {
      return false;
    }
    const expires = this.passes.get(id);
    return expires !== undefined && expires > Date.now();
  }

  // der Pass wurde verwendet: wir vergessen ihn
  consume(id: unknown): void {
    if (typeof id === 'string') {
      this.passes.delete(id);
    }
  }

  cookieOptions(): CookieOptions {
    return { httpOnly: true, sameSite: 'lax', maxAge: LIFETIME_MS, path: '/register' };
  }

  private purge(): void {
    const now = Date.now();
    for (const [id, expires] of this.passes) {
      if (expires <= now || this.passes.size >= MAX_PASSES) {
        this.passes.delete(id);
      }
    }
  }
}

Das Anlegen eines Patientenkontos ist von der Anmeldeseite aus möglich, sofern das CAPTCHA gelöst wurde. Daher muss eine Anfrage (das Registrierungsformular) wissen, dass eine vorherige Anfrage das CAPTCHA gelöst hat. Dies ist die Aufgabe des Passes:

  • Zeilen 38–43: ein zufälliger Bezeichner, 15 Minuten gültig, im Speicher abgelegt; er wird in einem Cookie gespeichert;
  • Zeilen 46–52: Das Registrierungsformular wird nur mit einem gültigen Pass angezeigt und akzeptiert;
  • Zeilen 55–59: Das Anlegen eines Kontos verbraucht den Pass: Ein gelöstes CAPTCHA berechtigt zu einem Konto und nicht zu mehr;
  • Zeilen 61–63: Die Option [path: '/register'] beschränkt das Senden des Cookies auf URLs, die mit [/register] beginnen.

11.12.10. src/auth/auth.controller.ts

// =========================================================================
// auth/auth.controller.ts
// -------------------------------------------------------------------------
// Die NICHT geschützten Login-Routen:
//   GET  /        leitet auf die Startseite der Rolle (oder auf /login) weiter
//   GET  /login   zeigt das Login-Formular an (mit seinem Captcha)
//   POST /login   prüft Versuchsgrenze, Captcha, Login / Passwort
//   POST /logout  löscht das Token-Cookie
//
// Der JSON-Server verwendete einen Passport-Guard "local" für POST /login:
// bei einem Fehler antwortete er direkt mit 401, was zu einem
// JavaScript-Client passt. Eine HTML-Seite muss dagegen das Formular ERNEUT
// mit einer Fehlermeldung ANZEIGEN: deshalb rufen wir AuthService selbst auf.
//
// Schutz vor Bots, in dieser Reihenfolge (siehe captcha.service.ts und
// attempt-limiter.service.ts):
//   1. zu viele jüngste Fehlversuche für dieses Login von dieser IP-Adresse?
//      -> sofortige Ablehnung, ohne das Passwort auch nur anzusehen;
//   2. falsche Antwort auf das Captcha? -> Ablehnung (als Fehlversuch gezählt);
//   3. erst dann wird das Passwort geprüft.
// Das Passwort eines in Schritt 1 oder 2 abgelehnten Versuchs wird NIE geprüft:
// ein Bot kann durch hartnäckiges Probieren also nichts lernen.
// =========================================================================

import { Body, Controller, Get, HttpCode, Post, Query, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { AuthService } from './auth.service';
import { CaptchaService } from './captcha.service';
import { AttemptLimiterService } from './attempt-limiter.service';
import { COOKIE_JWT, jwtCookieOptions } from './auth.constants';
import { Role } from '../entities/user.entity';

// die Startseite jeder Rolle, direkt nach der Anmeldung
export function homePage(role: Role): string {
  return role === 'USER' ? '/my-area' : '/schedule';
}

@Controller()
export class AuthController {
  constructor(
    private readonly authService: AuthService,
    private readonly captchaService: CaptchaService,
    private readonly limiter: AttemptLimiterService,
  ) {}

  @Get()
  home(@Req() req: Request, @Res() res: Response): void {
    const token = this.authService.readToken(req.cookies?.[COOKIE_JWT]);
    res.redirect(token ? homePage(token.role) : '/login');
  }

  // GET /login[?login=xxx]: der optionale Parameter füllt das Feld Login
  // vor (wird direkt nach der Erstellung eines Kontos verwendet, siehe RegistrationController)
  @Get('login')
  showLogin(@Req() req: Request, @Res() res: Response, @Query('login') login?: string): void {
    // bereits angemeldet (Token noch gültig): direkt zur Startseite
    const token = this.authService.readToken(req.cookies?.[COOKIE_JWT]);
    if (token !== null) {
      return res.redirect(homePage(token.role));
    }
    this.showForm(res, typeof login === 'string' ? login.slice(0, 30) : '');
  }

  // @HttpCode(200): standardmäßig antwortet NestJS auf einen POST mit 201 (Created) - was
  // keinen Sinn ergibt, wenn das Formular ERNEUT ANGEZEIGT wird (eine Weiterleitung
  // erzwingt ohnehin ihren eigenen Code, 302).
  @Post('login')
  @HttpCode(200)
  async logIn(
    @Body() body: { login?: string; password?: string; captchaId?: string; captcha?: string },
    @Req() req: Request,
    @Res() res: Response,
  ): Promise<void> {
    const login = (body.login ?? '').trim();
    const password = body.password ?? '';
    const ip = req.ip ?? 'unknown';

    // 1. zu viele jüngste Fehlversuche?
    const minutes = this.limiter.loginBlockMinutes(ip, login);
    if (minutes > 0) {
      return this.showForm(res, login, 'ERRORS.TOO_MANY_ATTEMPTS', { minutes: String(minutes) });
    }

    // 2. das Captcha
    if (!this.captchaService.verify(body.captchaId, body.captcha)) {
      this.limiter.loginFailure(ip, login);
      return this.showForm(res, login, 'ERRORS.WRONG_CAPTCHA');
    }

    // 3. das Passwort
    const user = login && password ? await this.authService.validateUser(login, password) : null;
    if (user === null) {
      this.limiter.loginFailure(ip, login);
      return this.showForm(res, login, 'LOGIN.ERROR');
    }

    this.limiter.loginSuccess(ip, login);
    res.cookie(COOKIE_JWT, this.authService.createToken(user), jwtCookieOptions());
    res.redirect(homePage(user.role));
  }

  // Abmelden mit einem POST (und nicht mit einem einfachen GET-Link): eine fremde Website
  // kann den Benutzer nicht ohne sein Wissen abmelden (siehe sameSite, auth.constants.ts)
  @Post('logout')
  logOut(@Res() res: Response): void {
    res.clearCookie(COOKIE_JWT, { path: '/' });
    res.redirect('/login');
  }

  // das Formular, immer mit einem NEUEN Captcha (jedes Bild wird nur einmal verwendet)
  private showForm(
    res: Response,
    login: string,
    error?: string,
    errorParams?: Record<string, string>,
  ): void {
    res.render('login', {
      pageTitle: 'LOGIN.TITLE',
      login, // das eingegebene Login wird erneut angezeigt, niemals das Passwort
      captcha: this.captchaService.generate(),
      error,
      errorParams,
    });
  }
}

Kommentieren wir diesen Code:

  • Zeilen 34–36: Die Startseite hängt von der Rolle des Benutzers ab: „Mein Bereich“ für Patienten, der Terminkalender für alle anderen;
  • Zeilen 46–50: Die Wurzel der Website leitet weiter, je nachdem, ob der Benutzer angemeldet ist oder nicht. Da die Route nicht durch den Guard geschützt ist, wird das Token von [readToken] überprüft;
  • Zeilen 54–62: Ein bereits angemeldeter Benutzer wird auf seine Startseite geleitet. Der Parameter [login] füllt das Feld vorab aus (nachdem ein Konto angelegt wurde). [slice(0, 30)] begrenzt seine Länge: Daten aus der Anfrage werden nie ohne Vorsichtsmaßnahmen verwendet;
  • Zeilen 69–73: der Anmeldevorgang in dieser Reihenfolge: mögliche Sperre, CAPTCHA, dann Passwort (siehe Beispiel 27). [req.ip] ist die IP-Adresse des Clients. Bei Erfolg: Zähler auf null zurückgesetzt, Cookie gesetzt, Weiterleitung auf die Startseite der Rolle;
  • Zeilen 104–108: die Abmeldung;
  • Zeilen 111–116: die Anmeldeseite, immer mit einem neuen CAPTCHA. Der Fehler ist ein Übersetzungsschlüssel samt seinen Parametern (die Anzahl der Minuten der Sperre).

11.12.11. src/auth/auth.module.ts

// =========================================================================
// auth/auth.module.ts
// -------------------------------------------------------------------------
// Das Authentifizierungsmodul. Es EXPORTIERT:
//   - UserRepository, das die Geschäftsschicht benötigt (Erstellen, Aktualisieren,
//     Löschen des Kontos eines Arztes oder eines Clients - siehe business.service.ts);
//   - AuthService, CaptchaService, AttemptLimiterService und
//     RegistrationPassService, die auch von den Seiten "Create an account"
//     und "Manage my account" (src/web/) verwendet werden.
// =========================================================================

import { Module } from '@nestjs/common';
import { JwtModule } from '@nestjs/jwt';
import { PassportModule } from '@nestjs/passport';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from '../entities/user.entity';
import { UserRepository } from '../repositories/user.repository';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { JwtStrategy } from './jwt.strategy';
import { CaptchaService } from './captcha.service';
import { AttemptLimiterService } from './attempt-limiter.service';
import { RegistrationPassService } from './registration-pass.service';
import { JWT_EXPIRES_IN_SECONDS, JWT_SECRET } from './auth.constants';

@Module({
  imports: [
    TypeOrmModule.forFeature([User]),
    PassportModule,
    JwtModule.register({
      secret: JWT_SECRET,
      signOptions: { expiresIn: JWT_EXPIRES_IN_SECONDS },
    }),
  ],
  controllers: [AuthController],
  providers: [
    AuthService,
    UserRepository,
    JwtStrategy,
    CaptchaService,
    AttemptLimiterService,
    RegistrationPassService,
  ],
  exports: [UserRepository, AuthService, CaptchaService, AttemptLimiterService, RegistrationPassService],
})
export class AuthModule {}
  • Zeile 28: das Repository für die Entität [User];
  • Zeilen 30–33: die Konfiguration für [JwtService];
  • Zeile 44: die Services, die exportiert werden an das Wurzelmodul (siehe Beispiel 06): [UserRepository] für die Geschäftsschicht (Anlegen eines Arzt- oder Kundenkontos), die übrigen für die Controller der Web-Schicht (Kontoerstellung, Kontoverwaltung durch den Patienten).

11.13. Die Web-Schicht: gemeinsame Services

Bevor wir uns die Controller ansehen, folgt, was ihnen gemeinsam ist: die Übersetzung, der Kontext jeder Seite, der Interceptor, der Exception-Filter, der Listen-Cache und die Helfer.

11.13.1. src/web/i18n.ts

// =========================================================================
// web/i18n.ts
// -------------------------------------------------------------------------
// Französische / englische Übersetzung der Oberfläche.
//
// Der Angular-Client lud seine Wörterbücher (public/i18n/fr.json und
// en.json) im BROWSER mit @ngx-translate. Hier werden die Seiten
// auf dem SERVER erzeugt: es sind daher dieselben Wörterbücher (dieselben
// Schlüssel, ergänzt), aber nur einmal beim Start vom Server gelesen.
// Eine Handlebars-View übersetzt einen Schlüssel mit dem Helper {{t 'KEY'}}
// (siehe views/handlebars-helpers.ts), dem Äquivalent der Pipe `| translate`.
// =========================================================================

import { readFileSync } from 'fs';
import { join } from 'path';
import { I18N_DIR } from '../config/paths';

export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const DEFAULT_LANGUAGE: Language = 'en';

// ein Wörterbuch ist ein verschachteltes JSON-Objekt: { "LOGIN": { "TITLE": "Login" } }
type Dictionary = { [key: string]: string | Dictionary };

const dictionaries: Record<Language, Dictionary> = {
  fr: JSON.parse(readFileSync(join(I18N_DIR, 'fr.json'), 'utf-8')),
  en: JSON.parse(readFileSync(join(I18N_DIR, 'en.json'), 'utf-8')),
};

export function isLanguage(value: unknown): value is Language {
  return typeof value === 'string' && (LANGUAGES as string[]).includes(value);
}

// -------------------------------------------------------------------------
// translate('en', 'DOCTORS.ADDED', { name: 'Marie PELISSIER' })
//   -> sucht DOCTORS, dann ADDED im englischen Wörterbuch und ersetzt
//      {name} durch seinen Wert. Ein in der angeforderten Sprache fehlender Schlüssel wird
//      in der Standardsprache gesucht; fehlt er überall, wird der Schlüssel selbst angezeigt
//      (ein Versäumnis in den Wörterbüchern fällt so sofort auf).
// -------------------------------------------------------------------------
export function translate(language: Language, key: string, params: Record<string, unknown> = {}): string {
  const text = lookup(dictionaries[language], key) ?? lookup(dictionaries[DEFAULT_LANGUAGE], key) ?? key;
  return text.replace(/\{(\w+)\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
}

function lookup(dictionary: Dictionary, key: string): string | null {
  let node: string | Dictionary | undefined = dictionary;
  for (const part of key.split('.')) {
    if (typeof node !== 'object' || node === null) {
      return null;
    }
    node = node[part];
  }
  return typeof node === 'string' ? node : null;
}

Das Übersetzungsmodul aus Beispiel 22, mit einer Präzisierung (Zeile 42): Fehlt ein Schlüssel im französischen Wörterbuch, wird er im englischen Wörterbuch (der Standardsprache) gesucht; fehlt er in beiden, wird der Schlüssel selbst angezeigt.

11.13.2. src/web/view-context.ts

// =========================================================================
// web/view-context.ts
// -------------------------------------------------------------------------
// Was ALLE Seiten wissen müssen, gleich welche Route sie
// anzeigt: die Sprache der Oberfläche, die mögliche "Flash"-Meldung, die
// anzuzeigen ist, und der angemeldete Benutzer (für die Navigationsleiste).
//
// Express bietet dafür [res.locals]: ein an die Antwort angehängtes Objekt, dessen
// Inhalt im Moment von res.render(...) AUTOMATISCH mit dem Modell jeder View
// zusammengeführt wird. Die Controller müssen diese
// Informationen daher nicht in jedem ihrer Modelle wiederholen.
//
// Zur Erinnerung: der Angular-Client hielt diese Informationen im Browser
// (Signals + localStorage). Ein HTML-Server muss sie dagegen bei
// JEDER Anfrage wiederfinden - hier in Cookies.
// =========================================================================

import { NextFunction, Request, Response } from 'express';
import { Language, DEFAULT_LANGUAGE, isLanguage } from './i18n';
import { ConnectedUser } from '../auth/jwt.strategy';

export const COOKIE_LANGUAGE = 'rdvmedecins_language';
export const COOKIE_FLASH = 'rdvmedecins_flash';

// eine Meldung, die EINMAL auf der nächsten Seite angezeigt wird
export interface FlashMessage {
  type: 'success' | 'danger'; // Bootstrap-Klassen alert-success / alert-danger
  key: string; // Übersetzungsschlüssel
  params?: Record<string, string>;
}

// der angemeldete Benutzer, wie ihn die Views sehen
export interface ViewUser {
  login: string;
  name: string;
  role: string;
  isAdmin: boolean; // ADMIN: Menüs Doctors / Clients
  isPatient: boolean; // USER: Menü My area
}

// -------------------------------------------------------------------------
// Express-Middleware, VOR jeder Route ausgeführt (siehe main.ts):
//   - res.locals.lang  : gewählte Sprache (Cookie), standardmäßig Englisch;
//   - res.locals.flash : die mögliche Flash-Meldung, die sofort gelöscht wird
//                        (sie darf nur einmal angezeigt werden);
//   - res.locals.currentPath: die angeforderte URL (aktives Menü der Navigationsleiste).
// -------------------------------------------------------------------------
export function viewContextMiddleware(req: Request, res: Response, next: NextFunction): void {
  res.locals.lang = languageOf(req);
  res.locals.currentPath = req.path;
  res.locals.flash = null;
  res.locals.currentUser = null;

  const raw = req.cookies?.[COOKIE_FLASH];
  if (raw) {
    try {
      res.locals.flash = JSON.parse(raw) as FlashMessage;
    } catch {
      // nicht lesbares Cookie: wird ignoriert
    }
    res.clearCookie(COOKIE_FLASH);
  }
  next();
}

export function languageOf(req: Request): Language {
  const value = req.cookies?.[COOKIE_LANGUAGE];
  return isLanguage(value) ? value : DEFAULT_LANGUAGE;
}

// -------------------------------------------------------------------------
// setzt eine Flash-Meldung, die von der NÄCHSTEN Seite angezeigt wird. Sie ist die
// natürliche Ergänzung zum Muster "Post / Redirect / Get", das alle
// Formulare der Anwendung verwenden: ein erfolgreicher POST erzeugt keine Seite, er
// leitet (302) auf eine GET-Seite weiter - lädt der Benutzer diese
// Seite dann neu (F5), sendet der Browser das Formular nicht ein zweites Mal.
// Die Meldung muss die Weiterleitung jedoch überleben: ein kurzlebiges
// Cookie erledigt das.
// -------------------------------------------------------------------------
export function flash(res: Response, message: FlashMessage): void {
  res.cookie(COOKIE_FLASH, JSON.stringify(message), { httpOnly: true, sameSite: 'lax', maxAge: 60_000 });
}

// -------------------------------------------------------------------------
// stellt den angemeldeten Benutzer (request.user, von JwtStrategy gesetzt) den
// Views bereit. Aufgerufen von ViewUserInterceptor (normale Routen) und von
// HtmlExceptionFilter (Fehlerseiten).
// -------------------------------------------------------------------------
export function exposeUser(req: Request, res: Response): void {
  const user = (req as Request & { user?: ConnectedUser }).user;
  if (!user) {
    return;
  }
  const currentUser: ViewUser = {
    login: user.login,
    name: user.name,
    role: user.role,
    isAdmin: user.role === 'ADMIN',
    isPatient: user.role === 'USER',
  };
  res.locals.currentUser = currentUser;
}

Kommentieren wir diesen Code:

  • Zeilen 22–23: die Namen der Cookies für die Sprache und die Flash-Nachricht;
  • Zeilen 26–30: eine Flash-Nachricht: ein Typ (Erfolg oder Fehler), ein Übersetzungsschlüssel und seine Parameter. Sie wird als JSON im Cookie gespeichert;
  • Zeilen 33–39: der angemeldete Benutzer, wie ihn die Views sehen. Die booleschen Werte [isAdmin] und [isPatient] ersparen den Views Zeichenkettenvergleiche;
  • Zeilen 48–64: die Middleware, die vor jeder Route ausgeführt wird (siehe Beispiele 20 und 22): die Sprache, der Pfad (für das aktive Menü) und die Flash-Nachricht, die gelesen und dann gelöscht wird. [JSON.parse] ist durch ein [try] geschützt: Ein manuell verändertes Cookie soll nicht dazu führen, dass die Seite fehlschlägt;
  • Zeilen 66–69: die Sprache, abgeleitet aus ihrem Cookie;
  • Zeilen 80–82: zeigt eine Flash-Nachricht an (siehe Beispiel 20);
  • Zeilen 89–102: Kopiert den angemeldeten Benutzer ([req.user]) nach [res.locals] für die Navigationsleiste. Diese Funktion wird nicht von der Middleware aufgerufen: Die Middleware läuft vor den Guards und damit, bevor [req.user] existiert (siehe Kapitel 7). Sie wird vom folgenden Interceptor und vom Exception-Filter aufgerufen.

11.13.3. src/web/view-user.interceptor.ts

// =========================================================================
// web/view-user.interceptor.ts
// -------------------------------------------------------------------------
// Warum ein Interceptor und nicht einfach die Middleware aus
// view-context.ts? Weil die Ausführungs-REIHENFOLGE wichtig ist:
//
//     Middlewares -> Guards (JwtAuthGuard ...) -> Interceptors -> Controller
//
// Der Guard JwtAuthGuard setzt request.user: eine Middleware läuft
// zu früh, um ihn zu sehen. Ein Interceptor läuft dagegen NACH den Guards und
// VOR dem Controller - der richtige Moment, um den angemeldeten Benutzer
// in res.locals zu kopieren, wo alle Views ihn finden.
// =========================================================================

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Request, Response } from 'express';
import { Observable } from 'rxjs';
import { exposeUser } from './view-context';

@Injectable()
export class ViewUserInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const http = context.switchToHttp();
    exposeUser(http.getRequest<Request>(), http.getResponse<Response>());
    return next.handle();
  }
}

Zeilen 22–26: Ein Interceptor läuft nach den Guards und vor der Aktion: Dies ist der richtige Zeitpunkt, um den von [JwtAuthGuard] übergebenen Benutzer bereitzustellen. Nach der Aktion hat er nichts zu tun: Er gibt direkt [next.handle()] zurück.

11.13.4. src/web/html-exception.filter.ts

// =========================================================================
// web/html-exception.filter.ts
// -------------------------------------------------------------------------
// Ein NestJS-"Exception-Filter" empfängt jede Exception, die vom Code der Controller
// nicht behandelt wurde. Standardmäßig antwortet NestJS in JSON
// ({"statusCode":403,"message":...}) - perfekt für den JSON-Server, aber
// in einem Browser unlesbar. Stattdessen erzeugt dieser Filter eine für eine
// HTML-Anwendung geeignete Antwort:
//
//   401 (nicht angemeldet oder Token abgelaufen) -> Weiterleitung auf /login
//   403 (unzureichende Rolle)                   -> Fehlerseite "access forbidden"
//   404 (unbekannte Seite)                       -> Fehlerseite "page not found"
//   400 (ungültiger Parameter)                    -> Fehlerseite "invalid request"
//   alles andere                                   -> Fehlerseite 500
//
// @Catch() ohne Argument: der Filter fängt ALLE Exceptions ab. Er wird
// einmal für die gesamte Anwendung in main.ts registriert.
// =========================================================================

import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus, Logger } from '@nestjs/common';
import { Request, Response } from 'express';
import { COOKIE_JWT } from '../auth/auth.constants';
import { exposeUser, flash } from './view-context';

const MESSAGES: Record<number, string> = {
  [HttpStatus.BAD_REQUEST]: 'ERRORS.BAD_REQUEST',
  [HttpStatus.FORBIDDEN]: 'ERRORS.FORBIDDEN',
  [HttpStatus.NOT_FOUND]: 'ERRORS.NOT_FOUND',
};

@Catch()
export class HtmlExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(HtmlExceptionFilter.name);

  catch(exception: unknown, host: ArgumentsHost): void {
    const http = host.switchToHttp();
    const req = http.getRequest<Request>();
    const res = http.getResponse<Response>();

    const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;

    if (status === HttpStatus.UNAUTHORIZED) {
      // ein Cookie war vorhanden, ist aber nicht mehr gültig: die Sitzung ist abgelaufen
      if (req.cookies?.[COOKIE_JWT]) {
        res.clearCookie(COOKIE_JWT, { path: '/' });
        flash(res, { type: 'danger', key: 'ERRORS.SESSION_EXPIRED' });
      }
      res.redirect('/login');
      return;
    }

    if (status >= 500) {
      // eine echte Anomalie: wir behalten den vollständigen Trace in der
      // Server-Konsole, ohne ihn dem Benutzer je anzuzeigen
      this.logger.error(exception instanceof Error ? exception.stack : String(exception));
    }

    // die Fehlerseite behält die Navigationsleiste des angemeldeten Benutzers
    // (falls vorhanden - ein 403 tritt NACH der Authentifizierung auf)
    exposeUser(req, res);
    res.status(status).render('error', {
      pageTitle: 'ERROR_PAGE.TITLE',
      code: status,
      message: MESSAGES[status] ?? 'ERRORS.SERVER_ERROR',
    });
  }
}
  • Zeilen 25–29: der Nachrichtenschlüssel für jeden Fehlercode;
  • Zeilen 42–50: Ein 401 leitet auf die Anmeldeseite weiter. War ein Token-Cookie vorhanden, ist es abgelaufen (oder das Konto wurde gelöscht): Es wird gelöscht, und der Benutzer wird über eine Popup-Nachricht benachrichtigt;
  • Zeilen 52–56: Ein echter Fehler wird zusammen mit seinem Aufrufstapel in der Server-Konsole protokolliert, dem Benutzer aber nie offengelegt: Diese Details würden einem Angreifer helfen;
  • Zeilen 60–65: die Fehlerseite, mit der Navigationsleiste des angemeldeten Benutzers.

11.13.5. src/web/application-model.service.ts

// =========================================================================
// web/application-model.service.ts
// -------------------------------------------------------------------------
// Der Cache / die Fassade, die bereits im JSON-Server vorhanden ist (Äquivalent der
// Klasse [ApplicationModel] des Spring-Projekts): die Listen der Ärzte und
// der Clients werden einmal beim Start gelesen und dann aus dem Speicher geliefert.
//
// Neu: diese Listen können sich jetzt ÄNDERN (der ADMIN fügt Ärzte und Clients hinzu,
// bearbeitet und löscht sie). Ein Cache, der
// nie aktualisiert würde, würde veraltete Daten anzeigen: jeder Schreibvorgang
// läuft daher über diesen Service, der die betroffene Liste unmittelbar danach neu lädt.
// Das ist der ganze Sinn eines EINZIGEN Einstiegspunkts in die
// Geschäftsschicht: die Regel "Schreiben => Cache neu laden" steht nur hier.
// =========================================================================

import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
import { PersonData, IBusiness, BUSINESS_TOKEN } from '../business/business.interface';
import { Client } from '../entities/client.entity';
import { Doctor } from '../entities/doctor.entity';
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';

@Injectable()
export class ApplicationModelService implements IBusiness, OnModuleInit {
  private doctors: Doctor[] = [];
  private clients: Client[] = [];

  constructor(@Inject(BUSINESS_TOKEN) private readonly business: IBusiness) {}

  // Wenn die Datenbank beim Start nicht erreichbar ist, stoppt die Exception den Server
  // mit einer expliziten Meldung - für eine HTML-Anwendung klarer, als
  // „leer“ zu starten und leere Listen anzuzeigen.
  async onModuleInit(): Promise<void> {
    await this.reloadDoctors();
    await this.reloadClients();
  }

  private async reloadDoctors(): Promise<void> {
    this.doctors = await this.business.getAllDoctors();
  }

  private async reloadClients(): Promise<void> {
    this.clients = await this.business.getAllClients();
  }

  // ──────────────────────────────────────────────── Lesezugriffe aus dem Cache

  async getAllDoctors(): Promise<Doctor[]> {
    return this.doctors;
  }

  async getAllClients(): Promise<Client[]> {
    return this.clients;
  }

  // der Arzt, dessen Benutzerkonto [userId] ist - dient dazu, bei einem angemeldeten Arzt
  // dessen eigenen Terminkalender vorauszuwählen
  getDoctorByUserId(userId: number): Doctor | null {
    return this.doctors.find((d) => d.userId === userId) ?? null;
  }

  // ──────────────────────────────────────────────── einfache Delegationen

  getAllSlots(doctorId: number): Promise<Slot[]> {
    return this.business.getAllSlots(doctorId);
  }

  getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
    return this.business.getDoctorDayAppointments(doctorId, day);
  }

  getClientById(id: number): Promise<Client | null> {
    return this.business.getClientById(id);
  }

  getDoctorById(id: number): Promise<Doctor | null> {
    return this.business.getDoctorById(id);
  }

  getAppointmentById(id: number): Promise<Appointment | null> {
    return this.business.getAppointmentById(id);
  }

  getSlotById(id: number): Promise<Slot | null> {
    return this.business.getSlotById(id);
  }

  getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null> {
    return this.business.getDoctorDaySchedule(doctorId, day);
  }

  // kein Cache hier: Es kommt auf die aktuellsten Daten an (ein Patient,
  // der gerade sein Konto geändert oder gelöscht hat)
  getClientByUserId(userId: number): Promise<Client | null> {
    return this.business.getClientByUserId(userId);
  }

  getClientUpcomingAppointments(clientId: number): Promise<Appointment[]> {
    return this.business.getClientUpcomingAppointments(clientId);
  }

  addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment> {
    return this.business.addAppointment(day, slot, client);
  }

  deleteAppointment(appointment: Appointment): Promise<void> {
    return this.business.deleteAppointment(appointment);
  }

  // ──────────────────────────────────────────────── Schreibzugriffe => neu laden

  async addDoctor(data: PersonData): Promise<Doctor> {
    const doctor = await this.business.addDoctor(data);
    await this.reloadDoctors();
    return doctor;
  }

  async editDoctor(id: number, data: PersonData): Promise<Doctor> {
    const doctor = await this.business.editDoctor(id, data);
    await this.reloadDoctors();
    return doctor;
  }

  async deleteDoctor(id: number): Promise<void> {
    await this.business.deleteDoctor(id);
    await this.reloadDoctors();
  }

  async addClient(data: PersonData): Promise<Client> {
    const client = await this.business.addClient(data);
    await this.reloadClients();
    return client;
  }

  async editClient(id: number, data: PersonData): Promise<Client> {
    const client = await this.business.editClient(id, data);
    await this.reloadClients();
    return client;
  }

  async deleteClient(id: number): Promise<void> {
    await this.business.deleteClient(id);
    await this.reloadClients();
  }
}

Kommentieren wir diesen Code:

  • Zeile 25: Der Service hat dieselbe Schnittstelle wie die Geschäftsschicht: Für die Controller ist er die Geschäftsschicht. Er sitzt zwischen beiden, um die Listen der Ärzte und Kunden, die auf fast jeder Seite angezeigt werden, im Speicher zu halten (Anwendungsbereich, siehe Kapitel 6);
  • Zeile 29: Die Geschäftsschicht wird über ihr Token injiziert;
  • Zeilen 34–37: [onModuleInit] wird von [NestJS] aufgerufen, sobald das Modul aufgebaut ist und bevor der Server startet: Die Listen werden beim Start gelesen. Ist die Datenbank nicht erreichbar, beendet sich die Anwendung mit einer klaren Meldung;
  • Zeilen 49–55: Die Listen werden aus dem Speicher bereitgestellt;
  • Zeilen 59–61: das Konto eines Arztes: Ein angemeldeter Arzt sieht sofort seinen eigenen Terminkalender;
  • Zeilen 65–109: Die übrigen Anfragen werden unverändert weitergeleitet;
  • Zeilen 113–145: Jede Schreiboperation, die Ärzte oder Kunden betrifft, aktualisiert die betreffende Liste. Da dieser Service der einzige Zugang zur Geschäftsschicht ist, wird die Regel „Schreiben = Cache aktualisieren“ nur hier umgesetzt, und der Cache kann nicht veralten.

11.13.6. src/web/views/handlebars-helpers.ts

// =========================================================================
// web/views/handlebars-helpers.ts
// -------------------------------------------------------------------------
// Handlebars ist bewusst eine LOGIKLOSE Template-Sprache: keine
// JavaScript-Ausdrücke in den Views, nur {{variables}},
// {{#if}} / {{#each}}-Blöcke ... Braucht ein View etwas mehr,
// geben wir ihm einen „Helper“: eine TypeScript-Funktion, die aus dem View aufrufbar ist.
//
// Die Anwendung benötigt nur vier Helper:
//   {{t 'KEY'}}                      Übersetzung (Entsprechung der Pipe `| translate`)
//   {{t 'KEY' name=person.lastName}} Übersetzung mit Parameter(n)
//   {{#if (eq a b)}}                 Gleichheitsvergleich
//   {{#if (or a b)}}                 true, wenn mindestens eines der Argumente true ist
//   {{active currentPath '/doctors'}} "active", wenn die aktuelle Seite unter diesem Pfad liegt
// =========================================================================

import { HelperOptions } from 'handlebars';
import { Language, DEFAULT_LANGUAGE, isLanguage, translate } from '../i18n';

// das Modul 'hbs' hat keine Typdeklarationen: Wir beschreiben hier den kleinen
// Teil, den wir davon verwenden
interface Hbs {
  registerHelper(name: string, fn: (...args: any[]) => unknown): void;
}

export function registerHelpers(hbs: Hbs): void {
  // Das letzte Argument, das ein Helper erhält, ist immer das Handlebars-Objekt [options]:
  // options.hash enthält die benannten Parameter (name=...), und
  // options.data.root das VOLLSTÄNDIGE Modell der Seite - also auch res.locals.lang,
  // die gewählte Sprache (siehe view-context.ts), selbst innerhalb eines {{#each}}.
  hbs.registerHelper('t', (key: unknown, options: HelperOptions) => {
    const lang = options.data?.root?.lang;
    const language: Language = isLanguage(lang) ? lang : DEFAULT_LANGUAGE;
    // der zurückgegebene Text wird anschließend von Handlebars maskiert ({{ }} und nicht {{{ }}}):
    // ein vom Benutzer eingegebener Name kann daher kein HTML einschleusen
    return typeof key === 'string' ? translate(language, key, options.hash) : '';
  });

  hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);

  // ...args: alle Argumente; das letzte ist das Handlebars-Objekt [options]
  // (siehe oben), das wir beiseitelegen, bevor wir die anderen prüfen
  hbs.registerHelper('or', (...args: unknown[]) => args.slice(0, -1).some(Boolean));

  hbs.registerHelper('active', (path: unknown, prefix: unknown) =>
    typeof path === 'string' && typeof prefix === 'string' && path.startsWith(prefix) ? 'active' : '',
  );
}
  • Zeilen 31–37: der Übersetzungshelfer (siehe Beispiel 22);
  • Zeile 39: der Gleichheitstest (siehe Beispiel 16);
  • Zeile 43: wahr, wenn eines der Argumente wahr ist. [...args] nimmt alle Argumente entgegen; das letzte ist das [options]-Objekt von [Handlebars], das verworfen wird;
  • Zeilen 45–47: die Klasse [active] des aktuellen Menüs (siehe Beispiel 16).

11.13.7. src/web/models/person-form.dto.ts

// =========================================================================
// web/models/person-form.dto.ts
// -------------------------------------------------------------------------
// Die Felder der „Personen“-Formulare und ihre Constraints. Drei
// Formulare teilen sich dieselben Identitätsfelder (Anrede, Vorname, Nachname):
//
//   PersonFieldsDto                 title, firstName, lastName
//    ├─ PersonFormDto               + OPTIONALES login / password, version
//    │                                (der ADMIN legt einen Arzt / Client an oder bearbeitet ihn)
//    ├─ RegistrationFormDto         + ERFORDERLICHES login / password / Bestätigung
//    │                                (ein Patient legt sein Konto an)
//    └─ MyAccountFormDto            + login, optionales neues Passwort,
//                                     AKTUELLES Passwort erforderlich, version
//                                     (ein Patient bearbeitet sein Konto)
//
// Die Klassenvererbung gilt auch für class-validator-Dekoratoren:
// eine Kindklasse erbt die Constraints der Felder ihrer Elternklasse.
//
// Die Fehlermeldungen sind Übersetzungs-SCHLÜSSEL (siehe i18n/*.json).
// @Transform(...) (class-transformer) bereinigt die Eingabe VOR der
// Validierung: überflüssige Leerzeichen entfernt, leer gelassene optionale Felder
// in `undefined` umgewandelt, Login in Kleinbuchstaben, version in eine Zahl umgewandelt
// (alles, was aus einem HTML-Formular kommt, ist eine Zeichenkette).
//
// Die Prüfung „Passwort = Bestätigung“ betrifft ZWEI Felder:
// Sie erfolgt im Controller, nach der Validierung jedes einzelnen Feldes.
// =========================================================================

import { Transform } from 'class-transformer';
import { IsIn, IsInt, IsNotEmpty, IsOptional, Matches, MaxLength, MinLength } from 'class-validator';

export const TITLES = ['Mr', 'Mme', 'Melle'];

const clean = ({ value }: { value: unknown }) => (typeof value === 'string' ? value.trim() : value);
const emptyToUndefined = ({ value }: { value: unknown }) =>
  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
const cleanLogin = ({ value }: { value: unknown }) => emptyToUndefined({ value })?.toLowerCase();
// ein Passwort wird nicht „bereinigt“ (Leerzeichen können Teil davon sein)
const passwordOrUndefined = ({ value }: { value: unknown }) =>
  typeof value === 'string' && value !== '' ? value : undefined;
const numberOrUndefined = ({ value }: { value: unknown }) =>
  value === undefined || value === '' ? undefined : Number(value);

// login: Kleinbuchstaben, Ziffern, Punkt, Bindestrich, Unterstrich - höchstens 30 Zeichen
const LOGIN_FORMAT = /^[a-z0-9._-]{1,30}$/;
// Mindestlänge eines von einem Patienten GEWÄHLTEN Passworts
export const PASSWORD_MIN = 6;

// ────────────────────────────────────────────────────────────────── gemeinsame Basis
export class PersonFieldsDto {
  @IsIn(TITLES, { message: 'ERRORS.INVALID_TITLE' })
  title: string;

  // maximale Längen = die der SQL-Spalten (VARCHAR(20))
  @Transform(clean)
  @IsNotEmpty({ message: 'ERRORS.FIRSTNAME_REQUIRED' })
  @MaxLength(20, { message: 'ERRORS.FIRSTNAME_TOO_LONG' })
  firstName: string;

  @Transform(clean)
  @IsNotEmpty({ message: 'ERRORS.LASTNAME_REQUIRED' })
  @MaxLength(20, { message: 'ERRORS.LASTNAME_TOO_LONG' })
  lastName: string;
}

// ────────────────────────────────────────────────────────────────── ADMIN
export class PersonFormDto extends PersonFieldsDto {
  // optional (siehe PersonData, business.interface.ts)
  @Transform(cleanLogin)
  @IsOptional()
  @Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
  login?: string;

  // optional; höchstens 72 Zeichen (darüber hinaus ignoriert bcrypt den Rest)
  @Transform(passwordOrUndefined)
  @IsOptional()
  @MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
  password?: string;

  // verstecktes Feld des Bearbeitungsformulars (optimistisches Sperren)
  @Transform(numberOrUndefined)
  @IsOptional()
  @IsInt({ message: 'ERRORS.INVALID_FORM' })
  version?: number;
}

// ────────────────────────────────────────────────────────────────── Registrierung eines Patienten
export class RegistrationFormDto extends PersonFieldsDto {
  @Transform(cleanLogin)
  @IsNotEmpty({ message: 'ERRORS.LOGIN_REQUIRED' })
  @Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
  login: string;

  @Transform(passwordOrUndefined)
  @IsNotEmpty({ message: 'ERRORS.PASSWORD_REQUIRED' })
  @MinLength(PASSWORD_MIN, { message: 'ERRORS.PASSWORD_TOO_SHORT' })
  @MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
  password: string;

  @Transform(passwordOrUndefined)
  @IsNotEmpty({ message: 'ERRORS.CONFIRMATION_REQUIRED' })
  confirmation: string;
}

// ────────────────────────────────────────────────────────────────── „Mein Konto verwalten“
export class MyAccountFormDto extends PersonFieldsDto {
  @Transform(cleanLogin)
  @IsNotEmpty({ message: 'ERRORS.LOGIN_REQUIRED' })
  @Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
  login: string;

  // optional: leer = Passwort unverändert
  @Transform(passwordOrUndefined)
  @IsOptional()
  @MinLength(PASSWORD_MIN, { message: 'ERRORS.PASSWORD_TOO_SHORT' })
  @MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
  password?: string;

  @Transform(passwordOrUndefined)
  @IsOptional()
  confirmation?: string;

  // das AKTUELLE Passwort, erforderlich für jede Änderung am Konto
  @Transform(passwordOrUndefined)
  @IsNotEmpty({ message: 'ERRORS.CURRENT_PASSWORD_REQUIRED' })
  currentPassword: string;

  @Transform(numberOrUndefined)
  @IsOptional()
  @IsInt({ message: 'ERRORS.INVALID_FORM' })
  version?: number;
}

Kommentieren wir diesen Code:

  • Zeile 32: mögliche Anreden;
  • Zeilen 34–42: die Bereinigungsfunktionen, die [@Transform] vor der Validierung anwendet: Entfernen von Leerzeichen, leere Felder auf [undefined] reduziert (damit [@IsOptional] sie akzeptiert), Login in Kleinbuchstaben, Version in eine Zahl umgewandelt. Ein Passwort wird nicht bereinigt: Seine Leerzeichen gehören dazu;
  • Zeile 45: das Format eines Benutzernamens, beschrieben durch einen regulären Ausdruck;
  • Zeilen 50–64: die Identitätsfelder, die drei Formularen gemeinsam sind. Die Maximallängen entsprechen denen der SQL-Spalten. Die Meldungen sind Übersetzungsschlüssel;
  • Zeilen 67–85: das ADMIN-Formular (Arzt oder Kunde): optionaler Benutzername und optionales Passwort sowie die Version für das optimistische Sperren. [extends]: Die Klasse erbt die Felder und Dekoratoren von ihrer Elternklasse. Ein Passwort darf höchstens 72 Zeichen lang sein; bcrypt ignoriert alle Zeichen jenseits dieser Grenze;
  • Zeilen 88–103: Ein Patient legt ein Konto an: Benutzername und Passwort erforderlich, mindestens sechs Zeichen, sowie Bestätigung;
  • Zeilen 106–132: Ein Patient ändert sein Konto: neues Passwort optional, aktuelles Passwort erforderlich.

11.13.8. src/web/helpers/form.helper.ts

// =========================================================================
// web/helpers/form.helper.ts
// -------------------------------------------------------------------------
// Validierung eines HTML-Formulars mit class-validator.
//
// Der JSON-Server überließ die Validierung der globalen ValidationPipe: Bei
// einem Fehler antwortete sie selbst mit 400 Bad Request - was zu einem
// JavaScript-Client passt, der den Fehler dann auf seine Weise anzeigt. Bei einer HTML-Seite dagegen
// wollen wir das Formular ERNEUT ANZEIGEN, mit den bereits
// eingegebenen Werten und einer Meldung unter jedem ungültigen Feld. Daher rufen wir
// class-validator selbst auf, um die Kontrolle über den weiteren Ablauf zu behalten.
// =========================================================================

import { ClassConstructor, plainToInstance } from 'class-transformer';
import { validate } from 'class-validator';
import { TITLES } from '../models/person-form.dto';

// Fehler pro Feld: { lastName: 'ERRORS.LASTNAME_REQUIRED', ... } - jede
// Meldung ist ein Übersetzungs-SCHLÜSSEL (siehe die Dekoratoren der DTOs)
export type FormErrors = Record<string, string>;

export interface ValidationResult<T> {
  dto: T; // die konvertierten und bereinigten Daten (siehe die @Transform der DTOs)
  errors: FormErrors | null; // null = gültiges Formular
}

export async function validateForm<T extends object>(
  cls: ClassConstructor<T>,
  body: Record<string, unknown>,
): Promise<ValidationResult<T>> {
  // plainToInstance: wandelt das empfangene einfache Objekt ({ lastName: ' dupont ' })
  // in eine Instanz der DTO-Klasse um und wendet dabei deren @Transform(...) an
  const dto = plainToInstance(cls, body);
  // validate: prüft alle Constraints (@IsNotEmpty, @MaxLength...);
  // forbidUnknownValues:false, weil wir ein selbst erstelltes Objekt validieren
  const violations = await validate(dto, { forbidUnknownValues: false });
  if (violations.length === 0) {
    return { dto, errors: null };
  }
  const errors: FormErrors = {};
  for (const violation of violations) {
    // wir behalten nur die erste Meldung jedes Feldes
    errors[violation.property] = Object.values(violation.constraints ?? {})[0] ?? 'ERRORS.INVALID_FORM';
  }
  return { dto, errors };
}

// -------------------------------------------------------------------------
// die von jedem fachlichen „input“-Fehler betroffenen Formularfelder
// (ein Duplikat): Sie werden rot umrandet, die Meldung steht unten auf der Seite
// -------------------------------------------------------------------------
export const BUSINESS_ERROR_FIELDS: Record<string, string[]> = {
  'ERRORS.LOGIN_TAKEN': ['login'],
  'ERRORS.DOCTOR_ALREADY_EXISTS': ['firstName', 'lastName'],
  'ERRORS.PATIENT_ALREADY_EXISTS': ['firstName', 'lastName'],
};

// { firstName: true, lastName: true }: die rot zu umrandenden Felder (is-invalid) -
// diejenigen mit einer Validierungsmeldung, plus eventuelle weitere
export function invalidFields(errors: FormErrors, others: string[] = []): Record<string, boolean> {
  const fields: Record<string, boolean> = {};
  for (const field of [...Object.keys(errors), ...others]) {
    fields[field] = true;
  }
  return fields;
}

// die Optionen der Dropdown-Liste „Title“, wobei die zu [value] gehörende ausgewählt ist
export function titleOptions(value: string): { value: string; selected: boolean }[] {
  return TITLES.map((t) => ({ value: t, selected: t === value }));
}
  • Zeilen 27–30: Formularvalidierung wie in Beispiel 19. Die Option [forbidUnknownValues: false] ist erforderlich, weil wir ein von [plainToInstance] erzeugtes Objekt validieren und kein von [ValidationPipe] empfangenes;
  • Zeilen 52–56: Bestimmte Geschäftsfehler beziehen sich auf bestimmte Felder (z. B. einen bereits vergebenen Benutzernamen): Diese Felder werden rot hervorgehoben, die Meldung erscheint am unteren Seitenrand;
  • Zeilen 60–66: die rot hervorzuhebenden Felder;
  • Zeilen 69–71: die Optionen der Anredeliste, wobei die ausgewählte hervorgehoben ist (siehe Beispiel 18).

11.13.9. src/web/helpers/dates.helper.ts

// =========================================================================
// web/helpers/dates.helper.ts
// -------------------------------------------------------------------------
// Kleine Funktionen für Datumsangaben im Format "yyyy-MM-dd" (das der Spalte
// appointments.day und des Feldes <input type="date"> der Formulare).
// =========================================================================

// heutiges Datum: in der Geschäftsschicht definiert, die es für
// ihre Geschäftsregeln benötigt - wir exportieren es hier einfach erneut
export { today } from '../../business/dates';

// true, wenn [day] ein existierendes Datum im Format yyyy-MM-dd ist
// (gleiche Prüfung wie beim JSON-Server: "2026-02-30" wird abgelehnt)
export function isValidDate(day: unknown): day is string {
  if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
    return false;
  }
  const date = new Date(`${day}T00:00:00Z`);
  return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}

// "8:05" statt "8:5"
export function formatTime(h: number, m: number): string {
  return `${h}:${twoDigits(m)}`;
}

// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", je nach Sprache
// (Intl.DateTimeFormat: die in JavaScript integrierte API zur Datumsformatierung)
export function formatDay(day: string, language: string): string {
  return new Intl.DateTimeFormat(language === 'en' ? 'en-GB' : 'fr-FR', {
    dateStyle: 'full',
    timeZone: 'UTC', // "2026-09-23T00:00:00Z" muss der 23. bleiben, unabhängig von der Zeitzone des Servers
  }).format(new Date(`${day}T00:00:00Z`));
}

function twoDigits(n: number): string {
  return n.toString().padStart(2, '0');
}
  • Zeile 10: Das aktuelle Datum wird in der Geschäftsschicht festgelegt; dieses Modul exportiert es erneut: Die Controller importieren alle Datumsfunktionen aus einer einzigen Quelle;
  • Zeilen 14–20: ein existierendes Datum im Format [yyyy-mm-dd] (siehe Beispiel 12);
  • Zeilen 29–34: ein ausgeschriebenes Datum, abhängig von der Sprache. Die Option [timeZone: 'UTC'] verhindert eine Verschiebung um einen Tag, wenn der Server nicht auf die mittlere Greenwich-Zeit eingestellt ist.

11.13.10. src/web/helpers/patient.helper.ts

// =========================================================================
// web/helpers/patient.helper.ts
// -------------------------------------------------------------------------
// Der zum angemeldeten Benutzer gehörende Patient (Entität Client).
//
// Das JWT-Token enthält nur die ID des KONTOS (users.id). Bei der Rolle USER wird
// der zugehörige Client über die Spalte clients.user gefunden.
//
// Gibt es keinen, wurde das Konto seit der Anmeldung gelöscht
// (vom Patienten selbst in einem anderen Tab oder vom ADMIN), während
// das Token noch gültig ist: Wir behandeln das wie eine abgelaufene Sitzung
// (UnauthorizedException -> zurück zur Anmeldeseite, siehe
// HtmlExceptionFilter).
// =========================================================================

import { UnauthorizedException } from '@nestjs/common';
import { ApplicationModelService } from '../application-model.service';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { Client } from '../../entities/client.entity';
import { Person } from '../../entities/person.entity';

// "Mme Alice DURAND"
export function label(p: Person): string {
  return `${p.title} ${p.firstName} ${p.lastName}`;
}

export async function connectedPatient(
  application: ApplicationModelService,
  user: ConnectedUser,
): Promise<Client> {
  const client = await application.getClientByUserId(user.userId);
  if (client === null) {
    throw new UnauthorizedException();
  }
  return client;
}
  • Zeilen 23–25: „Mme Alice DURAND“;
  • Zeilen 27–30: die Akte des angemeldeten Patienten, abgerufen anhand seines Kontos. Existiert sie nicht mehr (Konto in einem anderen Tab oder vom ADMIN gelöscht, obwohl das Token noch gültig ist), wird ein 401-Fehler zurückgegeben: Weiterleitung auf die Anmeldeseite.

11.14. Die Web-Schicht: die Controller

11.14.1. src/web/controllers/language.controller.ts

// =========================================================================
// web/controllers/language.controller.ts
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: die beiden Schaltflächen FR / EN der
// Navigationsleiste. Die Auswahl wird in einem Cookie gespeichert (der Angular-Client
// legte sie im localStorage ab), anschließend geht es zurück zur Seite, von der wir kamen.
// Ungeschützte Route: Die Sprache muss vor der Anmeldung änderbar sein.
// =========================================================================

import { Controller, Get, NotFoundException, Param, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { isLanguage } from '../i18n';
import { COOKIE_LANGUAGE } from '../view-context';

const ONE_YEAR = 365 * 24 * 3600 * 1000;

@Controller('language')
export class LanguageController {
  @Get(':language')
  change(@Param('language') language: string, @Req() req: Request, @Res() res: Response): void {
    if (!isLanguage(language)) {
      throw new NotFoundException();
    }
    res.cookie(COOKIE_LANGUAGE, language, { maxAge: ONE_YEAR, sameSite: 'lax', httpOnly: true });
    res.redirect(originPage(req));
  }
}

// die vorherige Seite gemäß dem HTTP-Header "Referer", den der
// Browser sendet. Nur ihr Pfad wird behalten (/schedule?...): Eine Weiterleitung auf
// eine vollständige, von der Anfrage gelieferte Adresse würde es erlauben,
// den Benutzer auf eine andere Website zu schicken (sogenannte „Open-Redirect“-Schwachstelle).
function originPage(req: Request): string {
  const referer = req.get('referer');
  if (!referer) {
    return '/';
  }
  try {
    const url = new URL(referer);
    return url.pathname.startsWith('/language/') ? '/' : url.pathname + url.search;
  } catch {
    return '/';
  }
}

Der Controller aus Beispiel 22. Beachten Sie: Ist die ursprüngliche Seite selbst eine [/language/...]-Seite (Zeile 40), wird die Anfrage auf die Wurzel der Website umgeleitet, um eine Endlosschleife zu vermeiden.

11.14.2. src/web/controllers/schedule.controller.ts

// =========================================================================
// web/controllers/schedule.controller.ts
// -------------------------------------------------------------------------
// Die Terminkalender-Seite: Auswahl eines Arztes und eines Tages, Terminkalender dieses
// Arztes an diesem Tag, Buchen und Stornieren von Terminen.
// Sie ist das serverseitige Gegenstück zu den Angular-Komponenten
// <app-doctor-day-picker>, <app-agenda> und <app-booking-dialog>.
//
//   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 Slot 7
//   POST /schedule/book                                     legt einen Termin an
//   POST /schedule/cancel                                   storniert einen Termin
//
// Die ganze Seite wird durch ihre URL beschrieben: Sie können sie neu laden,
// als Lesezeichen speichern, die „Zurück“-Schaltfläche des Browsers verwenden - ohne eine einzige Zeile
// JavaScript.
//
// Was jeder Benutzer sieht und tun kann:
//
//   | Rolle         | angezeigter belegter Slot         | Buchen             | Stornieren |
//   |───────────────|───────────────────────────────────|────────────────────|────────────|
//   | ADMIN, DOCTOR | Name des Patienten                | für einen Patienten| ja         |
//   |               |                                   | aus Liste gewählt  |            |
//   | USER (Patient)| "Booked" oder IHR Name, wenn es   | für sich selbst,   | nein (*)   |
//   |               | ihr eigener Termin ist            | wenn sie keinen    |            |
//   |               |                                   | bevorstehenden hat |            |
//
//   (*) der Patient storniert seinen Termin auf seiner Seite „My area“.
//
// VERTRAULICHKEIT: Für einen Patienten wird der Name der ANDEREN Patienten nicht
// einfach vom View ausgeblendet - er wird gar nicht erst in das an den View
// übergebene Modell aufgenommen. 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).
// =========================================================================

import { BadRequestException, Body, Controller, Get, Post, Query, Render, Req, Res, UseGuards } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { BusinessException } from '../../business/business.exception';
import { flash } from '../view-context';
import { today, isValidDate, formatTime } from '../helpers/dates.helper';
import { label, connectedPatient } from '../helpers/patient.helper';
import { Client } from '../../entities/client.entity';
import { Person } from '../../entities/person.entity';

type AuthenticatedRequest = Request & { user: ConnectedUser };

// ───────────────────────────────────────────────────────────────── View-Modell
// (was views/schedule.hbs anzeigt - nur bereits formatierte Daten
// UND bereits nach Rolle gefilterte: Der View entscheidet nichts)

interface OptionView {
  id: number;
  label: string; // "Mme Marie PELISSIER"
  selected: boolean;
}

interface ScheduleRowView {
  slotId: number;
  time: string; // "8:00 - 8:20"
  free: boolean;
  patient: string | null; // für einen belegten Slot angezeigter Name; null = "Booked"
  mine: boolean; // der Termin des angemeldeten Patienten
  bookable: boolean; // die Schaltfläche "Book" anzeigen?
  bookUrl: string;
  appointmentId: number | null; // nur gesetzt, wenn die Schaltfläche "Cancel" angezeigt wird
}

interface ScheduleView {
  doctor: string;
  day: string;
  rows: ScheduleRowView[];
}

interface BookingView {
  slotId: number;
  time: string;
  // ADMIN / DOCTOR: die Liste der auswählbaren Patienten
  clients: OptionView[];
  // USER: Der Patient ist der Benutzer selbst
  patient: string | null;
}

export interface ScheduleModel {
  pageTitle: string;
  doctors: OptionView[];
  doctorId: number | null;
  day: string;
  schedule: ScheduleView | null;
  booking: BookingView | null;
  backUrl: string; // der angezeigte Terminkalender, ohne Buchungsdialog
  // Patient, der bereits einen bevorstehenden Termin hat: die Meldung, die erklärt,
  // warum es keine Schaltfläche "Book" gibt
  info: string | null;
  error: string | null;
}

// was der Controller über den Benutzer weiß, um zu entscheiden, was angezeigt wird
interface Rights {
  manager: boolean; // ADMIN oder DOCTOR
  patient: Client | null; // der angemeldete Client (Rolle USER), sonst null
  patientCanBook: boolean; // USER ohne bevorstehenden Termin
}

@UseGuards(JwtAuthGuard, RolesGuard)
@Controller('schedule')
export class ScheduleController {
  constructor(private readonly application: ApplicationModelService) {}

  // -----------------------------------------------------------------------
  // GET /schedule
  // @Render('schedule'): Das von der Methode zurückgegebene Objekt wird zum Modell
  // des Views views/schedule.hbs (+ dem Inhalt von res.locals, siehe view-context.ts).
  // -----------------------------------------------------------------------
  @Get()
  @Render('schedule')
  async show(
    @Req() req: AuthenticatedRequest,
    @Query('doctorId') rawDoctorId?: string,
    @Query('day') rawDay?: string,
    @Query('book') rawBook?: string,
  ): Promise<ScheduleModel> {
    let error: string | null = null;
    const rights = await this.rights(req.user);

    // der Tag: der in der URL, wenn er gültig ist, sonst heute
    let day = today();
    if (rawDay !== undefined) {
      if (isValidDate(rawDay)) {
        day = rawDay;
      } else {
        error = 'ERRORS.INVALID_DATE';
      }
    }
    const dayBookable = day >= today();

    // der Arzt: der in der URL; fehlt er, bei einem angemeldeten Arzt der Arzt selbst
    let doctorId = positiveInteger(rawDoctorId);
    if (rawDoctorId === undefined && req.user.role === 'DOCTOR') {
      doctorId = this.application.getDoctorByUserId(req.user.userId)?.id ?? null;
    }

    const doctors = (await this.application.getAllDoctors()).map((d) => option(d, d.id === doctorId));

    // der Terminkalender, wenn ein Arzt gewählt ist (und das Datum gültig ist)
    let schedule: ScheduleView | null = null;
    if (doctorId !== null && error === null) {
      const doctorSchedule = await this.application.getDoctorDaySchedule(doctorId, day);
      if (doctorSchedule === null) {
        error = 'ERRORS.DOCTOR_NOT_FOUND';
      } else {
        schedule = {
          doctor: label(doctorSchedule.doctor),
          day,
          rows: doctorSchedule.doctorDaySlots.map(({ slot, appointment }) => {
            const free = appointment === null;
            // der Termin des angemeldeten Patienten?
            const mine = !free && rights.patient !== null && appointment.clientId === rights.patient.id;
            return {
              slotId: slot.id,
              time: `${formatTime(slot.startHour, slot.startMinute)} - ${formatTime(slot.endHour, slot.endMinute)}`,
              free,
              // DER Vertraulichkeitspunkt: Ein Patient erhält den Namen nur
              // SEINES Termins; für die anderen null (der View zeigt "Booked")
              patient: free ? null : rights.manager || mine ? label(appointment.client) : null,
              mine,
              bookable: free && dayBookable && (rights.manager || rights.patientCanBook),
              bookUrl: scheduleUrl(doctorId as number, day, slot.id),
              appointmentId: !free && rights.manager ? appointment.id : null,
            };
          }),
        };
      }
    }

    // der Buchungsdialog: nur, wenn der angeforderte Slot
    // von diesem Benutzer gebucht werden kann
    let booking: BookingView | null = null;
    const slotId = positiveInteger(rawBook);
    const row = schedule?.rows.find((r) => r.slotId === slotId && r.bookable);
    if (row) {
      booking = {
        slotId: row.slotId,
        time: row.time,
        clients: rights.manager ? (await this.application.getAllClients()).map((c) => option(c, false)) : [],
        patient: rights.patient ? label(rights.patient) : null,
      };
    }

    return {
      pageTitle: 'SCHEDULE.PAGE_TITLE',
      doctors,
      doctorId,
      day,
      schedule,
      booking,
      backUrl: doctorId !== null ? scheduleUrl(doctorId, day) : '/schedule',
      info: rights.patient !== null && !rights.patientCanBook ? 'SCHEDULE.ALREADY_BOOKED_INFO' : null,
      error,
    };
  }

  // -----------------------------------------------------------------------
  // POST /schedule/book   Felder: doctorId, day, slotId, clientId
  //
  // Bei einem Patienten (USER) wird das Feld clientId IGNORIERT: Er bucht immer
  // für sich selbst. Einem vom Browser gesendeten Feld zu vertrauen,
  // würde einem findigen Patienten erlauben, im Namen eines anderen zu buchen.
  //
  // Muster „Post / Redirect / Get“: Egal, wie das Ergebnis ausfällt, wir
  // erstellen hier keine Seite - wir setzen eine Flash-Meldung und leiten
  // zum Terminkalender weiter (siehe flash(), view-context.ts).
  // -----------------------------------------------------------------------
  @Post('book')
  @Roles('ADMIN', 'DOCTOR', 'USER')
  async book(
    @Body() body: Record<string, string>,
    @Req() req: AuthenticatedRequest,
    @Res() res: Response,
  ): Promise<void> {
    const { doctorId, day } = readScheduleRequest(body);
    const slotId = positiveInteger(body.slotId);
    if (slotId === null) {
      throw new BadRequestException();
    }

    let client: Client | null;
    if (req.user.role === 'USER') {
      client = await connectedPatient(this.application, req.user);
    } else {
      const clientId = positiveInteger(body.clientId);
      if (clientId === null) {
        // kein Patient gewählt: Der Buchungsdialog wird erneut geöffnet
        flash(res, { type: 'danger', key: 'ERRORS.CHOOSE_PATIENT' });
        return res.redirect(scheduleUrl(doctorId, day, slotId));
      }
      client = await this.application.getClientById(clientId);
    }

    const slot = await this.application.getSlotById(slotId);
    if (client === null) {
      flash(res, { type: 'danger', key: 'ERRORS.PATIENT_NOT_FOUND' });
    } else if (slot === null || slot.doctorId !== doctorId) {
      flash(res, { type: 'danger', key: 'ERRORS.SLOT_NOT_FOUND' });
    } else {
      try {
        // die Regeln (nicht in der Vergangenheit, nur ein bevorstehender Termin pro
        // Patient, freier Slot) werden von der Geschäftsschicht geprüft
        await this.application.addAppointment(day, slot, client);
        flash(res, { type: 'success', key: 'SCHEDULE.BOOKED' });
      } catch (e) {
        // dieselbe Regel, aber eine Meldung in der 2. Person, wenn der Patient
        // selbst bucht („Sie haben bereits ...“ statt „Dieser Patient ...“)
        if (
          req.user.role === 'USER' &&
          e instanceof BusinessException &&
          e.key === 'ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT'
        ) {
          flash(res, { type: 'danger', key: 'SCHEDULE.ALREADY_BOOKED_INFO' });
        } else {
          flashBusinessError(res, e);
        }
      }
    }
    res.redirect(scheduleUrl(doctorId, day));
  }

  // -----------------------------------------------------------------------
  // POST /schedule/cancel   Felder: appointmentId, doctorId, day
  // (ein Patient storniert SEINEN Termin von "My area" aus, nicht von hier)
  // -----------------------------------------------------------------------
  @Post('cancel')
  @Roles('ADMIN', 'DOCTOR')
  async cancel(@Body() body: Record<string, string>, @Res() res: Response): Promise<void> {
    const { doctorId, day } = readScheduleRequest(body);
    const appointmentId = positiveInteger(body.appointmentId);
    if (appointmentId === null) {
      throw new BadRequestException();
    }
    const appointment = await this.application.getAppointmentById(appointmentId);
    if (appointment === null) {
      // bereits storniert (von jemand anderem oder durch Doppelklick)
      flash(res, { type: 'danger', key: 'ERRORS.APPOINTMENT_NOT_FOUND' });
    } else {
      await this.application.deleteAppointment(appointment);
      flash(res, { type: 'success', key: 'SCHEDULE.CANCELLED' });
    }
    res.redirect(scheduleUrl(doctorId, day));
  }

  // -----------------------------------------------------------------------
  // wer ist angemeldet, und was darf er auf dieser Seite tun?
  // -----------------------------------------------------------------------
  private async rights(user: ConnectedUser): Promise<Rights> {
    if (user.role !== 'USER') {
      return { manager: true, patient: null, patientCanBook: false };
    }
    const patient = await connectedPatient(this.application, user);
    const upcoming = await this.application.getClientUpcomingAppointments(patient.id);
    return { manager: false, patient, patientCanBook: upcoming.length === 0 };
  }
}

// ───────────────────────────────────────────────────────────────── Hilfsfunktionen

// "3" -> 3 ; "", "abc", "-2", undefined -> null
function positiveInteger(value: unknown): number | null {
  const n = Number(value);
  return typeof value === 'string' && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}

// die versteckten Felder doctorId / day, gemeinsam für beide POST-Formulare
function readScheduleRequest(body: Record<string, string>): { doctorId: number; day: string } {
  const doctorId = positiveInteger(body.doctorId);
  if (doctorId === null || !isValidDate(body.day)) {
    throw new BadRequestException(); // -> Seite "invalid request" (siehe HtmlExceptionFilter)
  }
  return { doctorId, day: body.day };
}

function scheduleUrl(doctorId: number, day: string, book?: number): string {
  const params = new URLSearchParams({ doctorId: String(doctorId), day });
  if (book !== undefined) {
    params.set('book', String(book));
  }
  return `/schedule?${params.toString()}`;
}

function option(p: Person, selected: boolean): OptionView {
  return { id: p.id, label: label(p), selected };
}

// eine BusinessException wird zu einer Flash-Meldung; jeder andere Fehler ist eine
// echte Anomalie, die wir bis zum HtmlExceptionFilter durchlaufen lassen
function flashBusinessError(res: Response, e: unknown): void {
  if (e instanceof BusinessException) {
    flash(res, { type: 'danger', key: e.key, params: e.params });
    return;
  }
  throw e;
}

Die Hauptseite der Anwendung. Gehen wir diesen Code Abschnitt für Abschnitt durch.

11.14.2.1. Der URL-Abschnitt der Seite

Die Kommentare in den Zeilen 9–14 beschreiben die Routen. Beachten Sie, dass das Buchungsfenster nicht von [JavaScript] geöffnet wird: Es ist ein URL-Parameter ([book=7]), der den Server anweist, die Seite mit geöffnetem Fenster anzuzeigen. Die Schaltfläche „Buchen“ ist daher einfach ein Link. Die gesamte Seite wird durch ihre URL beschrieben: Sie können sie neu laden, als Lesezeichen speichern oder die Schaltfläche „Zurück“ des Browsers verwenden.

11.14.2.2. Das View-Template

  • Zeile 56: der Typ der Anfrage für eine geschützte Route: eine [Express]-Anfrage, deren Feld [user] von [JwtAuthGuard] gesetzt wurde;
  • Zeilen 62–106: Das View-Template ist typisiert. Die View erhält nur bereits formatierte ([time: "8:00 - 8:20"]) und nach der Rolle des Benutzers gefilterte Daten; sie trifft keine Entscheidungen. In [ScheduleRowView] (Zeilen 68–77) ist [patient] gleich [null] , wenn der Benutzer nicht berechtigt ist, den Namen des Patienten zu sehen; [bookable] und [appointmentId] bestimmen, ob die Schaltflächen „Buchen“ und „Stornieren“ angezeigt werden sollen;
  • Zeilen 109–113: was der Controller über den angemeldeten Benutzer weiß.

11.14.2.3. GET /schedule

  • Zeilen 115–116: Alle Routen erfordern einen angemeldeten Benutzer. Ohne [@Roles] an der Klasse haben alle Rollen Zugriff auf die Seite;
  • Zeilen 127–132: die drei URL-Parameter, alle optional, als Zeichenketten empfangen und später umgewandelt;
  • Zeilen 137–145: das angeforderte Datum, wenn es gültig ist; andernfalls heute. Termine können erst ab heute gebucht werden;
  • Zeilen 148–151: der angeforderte Arzt; andernfalls sieht ein angemeldeter Arzt seinen eigenen Terminkalender;
  • Zeile 153: die Dropdown-Liste der Ärzte, aus dem Cache abgerufen;
  • Zeilen 157–184: der von der Geschäftsschicht berechnete Kalender, in Tabellenzeilen umgewandelt. Zeile 175 ist der Datenschutz-Kontrollpunkt der Anwendung: Ein Patient erhält nur den Namen seines eigenen Termins. Für andere enthält das Modell [null], und die View zeigt „Belegt“ an. Der Name wird nicht einfach von der View ausgeblendet: Er wird nie an den Browser gesendet;
  • Zeilen 188–198: Das Buchungsfenster wird nur geöffnet, wenn der angeforderte Zeitraum von diesem Benutzer buchbar ist. Ein Administrator wählt den Patienten aus einer Liste aus; ein Patient bucht für sich selbst;
  • Zeilen 200–210: Das Template [info] erklärt einem Patienten, der bereits einen Termin hat, warum er keine Schaltfläche „Buchen“ sieht.

11.14.2.4. POST /schedule/book

  • Zeile 225: Alle drei Rollen können eine Reservierung vornehmen;
  • Zeile 231: Die Felder [doctorId] und [day], die im Formular verborgen sind, ermöglichen es dem Benutzer, zum angezeigten Kalender zurückzukehren;
  • Zeilen 238–239: Bei einem Patienten: Das Feld [clientId] wird ignoriert: Der Patient bucht immer für sich selbst. Sich auf dieses vom Browser gesendete Feld zu verlassen, würde einem raffinierten Patienten erlauben, im Namen eines anderen zu buchen;
  • Zeilen 242–246: Ein Administrator, der keinen Patienten ausgewählt hat, wird zusammen mit einer Meldung zum Buchungsfenster zurückgeleitet;
  • Zeilen 251–254: Der Zeitraum muss existieren und zum Arzt im Kalender gehören;
  • Zeilen 256–261: Die Regeln der Geschäftslogik werden von der Geschäftsschicht geprüft. Für einen Patienten wird die Meldung „Dieser Patient hat bereits einen bevorstehenden Termin“ durch eine direkt an den Patienten gerichtete Meldung ersetzt;
  • Zeile 275: PRG-Muster: Unabhängig vom Ergebnis wird eine Popup-Nachricht angezeigt und auf den Kalender weitergeleitet.

11.14.2.5. POST /schedule/cancel

Zeilen 282–299: Administratoren vorbehalten; ein Patient storniert seinen Termin über „Mein Bereich“. Ein bereits stornierter Termin (durch Doppelklick oder durch einen anderen Administrator) führt zu einer Fehlermeldung, nicht zu einer Fehlerseite.

11.14.2.6. Berechtigungen und Hilfsfunktionen

  • Zeilen 304–311: Ein Administrator hat alle Berechtigungen; ein Patient kann eine Reservierung vornehmen, wenn er keinen bevorstehenden Termin hat;
  • Zeilen 317–320: sichere Umwandlung eines Parameters in einen Bezeichner;
  • Zeilen 323–329: Ungültige verborgene Felder können nur von einer manuell erstellten Anfrage stammen: Fehler 400;
  • Zeilen 331–337: [URLSearchParams] erstellt eine korrekt kodierte Abfragezeichenfolge;
  • Zeilen 345–351: Eine [BusinessException] wird zu einer Flash-Nachricht; jede andere Ausnahme wird bis zum Exception-Filter weitergereicht.

11.14.3. src/web/controllers/persons.controller.ts

// =========================================================================
// web/controllers/persons.controller.ts
// -------------------------------------------------------------------------
// Die Verwaltung der Ärzte und die der Clients (dem ADMIN vorbehalten) sind
// IDENTISCH: gleiche Liste, gleiches Formular, gleiche Regeln. Statt
// dieselben Routen zweimal zu schreiben, schreiben wir sie einmal in dieser
// ABSTRAKTEN Klasse, von der DoctorsController (@Controller('doctors'))
// und ClientsController (@Controller('clients')) erben. Jede Unterklasse muss nur
// ihre „Konfiguration“ liefern: welche Methoden aufzurufen und welche
// Beschriftungen anzuzeigen sind.
//
// Die HIER gesetzten Routen-Dekoratoren (@Get, @Post...) werden vererbt: NestJS
// durchläuft die gesamte Prototypenkette der Controller-Klasse. Wir
// erhalten daher für jede der beiden Unterklassen:
//
//   GET  /doctors                    Liste
//   GET  /doctors/add                leeres Formular
//   POST /doctors/add                Anlegen
//   GET  /doctors/:id/edit           vorausgefülltes Formular
//   POST /doctors/:id/edit           Aktualisieren
//   POST /doctors/:id/delete         Löschen
//
// (und dieselben URLs unter /clients). Auch die Views werden geteilt:
// views/persons/list.hbs und views/persons/form.hbs.
// =========================================================================

import { Body, Get, HttpCode, NotFoundException, Param, ParseIntPipe, Post, Render, Res } from '@nestjs/common';
import { Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { PersonData } from '../../business/business.interface';
import { BusinessException } from '../../business/business.exception';
import { Person } from '../../entities/person.entity';
import { flash } from '../view-context';
import {
  BUSINESS_ERROR_FIELDS,
  FormErrors,
  invalidFields,
  titleOptions,
  validateForm,
} from '../helpers/form.helper';
import { PersonFormDto } from '../models/person-form.dto';

// die für jeden Personentyp spezifischen Übersetzungsschlüssel
export interface PersonKeys {
  title: string; // "Doctors"
  add: string; // "Add a doctor"
  edit: string; // "Edit a doctor"
  empty: string; // "No doctors."
  confirmDelete: string; // "Delete this doctor and their account?"
  added: string; // "Doctor {name} has been added (login: {login})."
  edited: string;
  deleted: string;
}

export interface PersonsConfig<T extends Person> {
  url: string; // '/doctors' oder '/clients'
  keys: PersonKeys;
  list(): Promise<T[]>;
  find(id: number): Promise<T | null>;
  add(data: PersonData): Promise<T>;
  edit(id: number, data: PersonData): Promise<T>;
  delete(id: number): Promise<void>;
}

// die in den Feldern des Formulars angezeigten Werte
interface FormValues {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  version: number | null;
}

export abstract class PersonsController<T extends Person> {
  protected abstract readonly config: PersonsConfig<T>;

  constructor(protected readonly application: ApplicationModelService) {}

  // -----------------------------------------------------------------------
  // GET /doctors (oder /clients)
  // -----------------------------------------------------------------------
  @Get()
  @Render('persons/list')
  async list() {
    const persons = await this.config.list();
    return {
      pageTitle: this.config.keys.title,
      keys: this.config.keys,
      addUrl: `${this.config.url}/add`,
      persons: persons.map((p) => ({
        title: p.title,
        firstName: p.firstName,
        lastName: p.lastName,
        login: p.user?.login ?? '',
        editUrl: `${this.config.url}/${p.id}/edit`,
        deleteUrl: `${this.config.url}/${p.id}/delete`,
      })),
    };
  }

  // -----------------------------------------------------------------------
  // GET /doctors/add
  // -----------------------------------------------------------------------
  @Get('add')
  addForm(@Res() res: Response): void {
    this.showForm(res, null, { title: 'Mr', firstName: '', lastName: '', login: '', version: null });
  }

  // -----------------------------------------------------------------------
  // POST /doctors/add
  // -----------------------------------------------------------------------
  @Post('add')
  @HttpCode(200) // wenn das Formular erneut angezeigt wird (siehe auth.controller.ts)
  async add(@Body() body: Record<string, unknown>, @Res() res: Response): Promise<void> {
    const { dto, errors } = await validateForm(PersonFormDto, body);
    if (errors !== null) {
      return this.showForm(res, null, enteredValues(dto), errors);
    }
    try {
      const person = await this.config.add(dto);
      flash(res, { type: 'success', key: this.config.keys.added, params: messageParams(person) });
      res.redirect(this.config.url);
    } catch (e) {
      this.showBusinessError(res, null, enteredValues(dto), e);
    }
  }

  // -----------------------------------------------------------------------
  // GET /doctors/:id/edit
  // ParseIntPipe: Wenn :id keine ganze Zahl ist, wirft NestJS eine
  // BadRequestException (Seite "invalid request", siehe HtmlExceptionFilter)
  // -----------------------------------------------------------------------
  @Get(':id/edit')
  async editForm(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
    const person = await this.config.find(id);
    if (person === null) {
      throw new NotFoundException();
    }
    this.showForm(res, id, {
      title: person.title,
      firstName: person.firstName,
      lastName: person.lastName,
      login: person.user?.login ?? '',
      version: person.version,
    });
  }

  // -----------------------------------------------------------------------
  // POST /doctors/:id/edit
  // -----------------------------------------------------------------------
  @Post(':id/edit')
  @HttpCode(200)
  async edit(
    @Param('id', ParseIntPipe) id: number,
    @Body() body: Record<string, unknown>,
    @Res() res: Response,
  ): Promise<void> {
    const { dto, errors } = await validateForm(PersonFormDto, body);
    if (errors !== null) {
      return this.showForm(res, id, enteredValues(dto), errors);
    }
    try {
      const person = await this.config.edit(id, dto);
      flash(res, { type: 'success', key: this.config.keys.edited, params: messageParams(person) });
      res.redirect(this.config.url);
    } catch (e) {
      this.showBusinessError(res, id, enteredValues(dto), e);
    }
  }

  // -----------------------------------------------------------------------
  // POST /doctors/:id/delete
  // (die Rückfrage "Are you sure?" wird vom Browser angefordert, bevor
  // das Formular gesendet wird, siehe public/js/app.js)
  // -----------------------------------------------------------------------
  @Post(':id/delete')
  async delete(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
    const person = await this.config.find(id);
    try {
      await this.config.delete(id);
      flash(res, { type: 'success', key: this.config.keys.deleted, params: messageParams(person) });
    } catch (e) {
      if (!(e instanceof BusinessException)) {
        throw e;
      }
      flash(res, { type: 'danger', key: e.key, params: e.params });
    }
    res.redirect(this.config.url);
  }

  // ───────────────────────────────────────────────────────────────── private Methoden

  // id === null: Anlegeformular; andernfalls: Bearbeitungsformular
  //   errors          : Meldung unter jedem von der Validierung abgelehnten Feld
  //   error           : DIE Fehlermeldung der Seite, unten auf der Seite angezeigt
  //                     (siehe views/partials/errors.hbs)
  //   otherFields     : rot zu umrandende Felder OHNE eigene Meldung (z. B.:
  //                     Vor- + Nachname eines Namensvetters - die Meldung steht unten)
  private showForm(
    res: Response,
    id: number | null,
    values: FormValues,
    errors: FormErrors = {},
    error: string | null = null,
    otherFields: string[] = [],
  ): void {
    const creating = id === null;
    res.render('persons/form', {
      pageTitle: creating ? this.config.keys.add : this.config.keys.edit,
      creating,
      action: creating ? `${this.config.url}/add` : `${this.config.url}/${id}/edit`,
      listUrl: this.config.url,
      values,
      titles: titleOptions(values.title),
      errors,
      invalidFields: invalidFields(errors, otherFields),
      error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
    });
  }

  // eine Geschäftsregel hat den Schreibvorgang abgelehnt: Das Formular wird erneut angezeigt,
  // mit der Eingabe des Benutzers und der Meldung der Geschäftsschicht
  private showBusinessError(res: Response, id: number | null, values: FormValues, e: unknown): void {
    if (!(e instanceof BusinessException)) {
      throw e; // echte Anomalie -> HtmlExceptionFilter (Seite 500)
    }
    if (e.key === 'ERRORS.DOCTOR_NOT_FOUND' || e.key === 'ERRORS.PATIENT_NOT_FOUND') {
      // in der Zwischenzeit von einem anderen ADMIN gelöscht: zurück zur Liste
      flash(res, { type: 'danger', key: e.key });
      return res.redirect(this.config.url);
    }
    // die Meldung steht unten auf der Seite; die betroffenen Felder, falls vorhanden, werden
    // rot umrandet, damit der Benutzer sofort sieht, was zu korrigieren ist
    this.showForm(res, id, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
  }
}

// was der Benutzer eingegeben hat (Passwort ausgenommen: Es wird nie an den Browser zurückgesendet)
function enteredValues(dto: PersonFormDto): FormValues {
  return {
    title: dto.title ?? '',
    firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
    lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
    login: dto.login ?? '',
    version: dto.version ?? null,
  };
}

// {name} und {login} der Meldungen „hinzugefügt / aktualisiert / gelöscht“
function messageParams(person: Person | null): Record<string, string> {
  if (person === null) {
    return { name: '', login: '' };
  }
  return { name: `${person.firstName} ${person.lastName}`, login: person.user?.login ?? '' };
}

Die Verwaltung von Ärzten und Kunden ist identisch. Statt zwei ähnliche Controller zu schreiben, erstellen wir eine abstrakte Klasse, von der beide Controller erben.

  • Zeilen 44–53: die für jede Personenart spezifischen Texte (Übersetzungsschlüssel);
  • Zeilen 55–63: die von jeder Unterklasse bereitgestellte Konfiguration: die Basis-URL, die Texte und die Funktionen, die zum Auflisten, Suchen, Hinzufügen, Ändern und Löschen aufzurufen sind;
  • Zeile 75: ein abstraktes Feld: Jede Unterklasse muss es definieren;
  • Zeilen 82–99: die Liste. Auf eine Elternklasse angewandte Route-Dekoratoren werden vererbt: [NestJS] findet sie, indem es die Prototypenkette durchläuft. Das Modell enthält für jede Person die URL für ihre Schaltflächen;
  • Zeilen 104–107 und 112–126: das Hinzufügen in drei Schritten wie in Beispiel 28: Validierung, Geschäftsschicht, PRG;
  • Zeilen 133–146 und 151–157: die Änderung. [ParseIntPipe] lehnt einen nicht numerischen Bezeichner ab (Fehler 400);
  • Zeilen 176–189: das Löschen. Die Person wird vorher abgerufen, um ihren Namen in der Bestätigungsmeldung anzuzeigen;
  • Zeilen 199–206: das Formular, sowohl für das Anlegen ([id === null]) als auch für die Änderung;
  • Zeilen 223–235: Eine Person, die in der Zwischenzeit gelöscht wurde, wird zur Liste zurückgeleitet; andere Geschäftsfehler zeigen das Formular erneut an, wobei die betreffenden Felder rot hervorgehoben sind;
  • Zeilen 239–247: die erneut anzuzeigenden Werte (nie das Passwort).

11.14.4. src/web/controllers/doctors.controller.ts

// =========================================================================
// web/controllers/doctors.controller.ts
// -------------------------------------------------------------------------
// Verwaltung der Ärzte (nur Rolle ADMIN). Alle Routen werden von
// PersonsController geerbt (siehe persons.controller.ts): Hier bleibt nur noch
// zu sagen, WAS aufzurufen ist und WELCHE Beschriftungen anzuzeigen sind.
//
// @Roles('ADMIN') auf der KLASSE gesetzt gilt für alle ihre Routen,
// auch für die geerbten (RolesGuard sucht die Metadaten an der Methode,
// dann an der Klasse - siehe auth/roles.guard.ts).
// =========================================================================

import { Controller, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ApplicationModelService } from '../application-model.service';
import { Doctor } from '../../entities/doctor.entity';
import { PersonsConfig, PersonsController } from './persons.controller';

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Controller('doctors')
export class DoctorsController extends PersonsController<Doctor> {
  protected readonly config: PersonsConfig<Doctor> = {
    url: '/doctors',
    keys: {
      title: 'DOCTORS.TITLE',
      add: 'DOCTORS.ADD',
      edit: 'DOCTORS.EDIT',
      empty: 'DOCTORS.EMPTY',
      confirmDelete: 'DOCTORS.DELETE_CONFIRM',
      added: 'DOCTORS.ADDED',
      edited: 'DOCTORS.UPDATED',
      deleted: 'DOCTORS.DELETED',
    },
    list: () => this.application.getAllDoctors(),
    find: (id) => this.application.getDoctorById(id),
    add: (data) => this.application.addDoctor(data),
    edit: (id, data) => this.application.editDoctor(id, data),
    delete: (id) => this.application.deleteDoctor(id),
  };

  // ein expliziter Konstruktor, damit TypeScript für DIESE Klasse die
  // Typmetadaten der Parameter erzeugt, die NestJS benötigt, um
  // zu wissen, was injiziert werden soll (die abstrakte Elternklasse ohne Dekorator hat
  // keine)
  constructor(application: ApplicationModelService) {
    super(application);
  }
}
  • Zeilen 21–22: ADMIN vorbehalten. [@Roles] an der Klasse gilt für alle ihre Routen, einschließlich der vererbten;
  • Zeilen 25–42: die Konfiguration: die Übersetzungsschlüssel für Ärzte und die aufzurufenden Cache-Methoden;
  • Zeilen 48–50: ein expliziter Konstruktor, obwohl er lediglich den Konstruktor der Elternklasse aufruft; dadurch kann der Compiler für diese Klasse die Typmetadaten erzeugen, die [NestJS] braucht, um zu wissen, was injiziert werden soll.

11.14.5. src/web/controllers/clients.controller.ts

// =========================================================================
// web/controllers/clients.controller.ts
// -------------------------------------------------------------------------
// Verwaltung der Clients (der PATIENTEN der Praxis), nur Rolle ADMIN.
// Gleiches Prinzip wie bei DoctorsController (siehe dessen Kommentare).
// =========================================================================

import { Controller, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ApplicationModelService } from '../application-model.service';
import { Client } from '../../entities/client.entity';
import { PersonsConfig, PersonsController } from './persons.controller';

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Controller('clients')
export class ClientsController extends PersonsController<Client> {
  protected readonly config: PersonsConfig<Client> = {
    url: '/clients',
    keys: {
      title: 'CLIENTS.TITLE',
      add: 'CLIENTS.ADD',
      edit: 'CLIENTS.EDIT',
      empty: 'CLIENTS.EMPTY',
      confirmDelete: 'CLIENTS.DELETE_CONFIRM',
      added: 'CLIENTS.ADDED',
      edited: 'CLIENTS.UPDATED',
      deleted: 'CLIENTS.DELETED',
    },
    list: () => this.application.getAllClients(),
    find: (id) => this.application.getClientById(id),
    add: (data) => this.application.addClient(data),
    edit: (id, data) => this.application.editClient(id, data),
    delete: (id) => this.application.deleteClient(id),
  };

  constructor(application: ApplicationModelService) {
    super(application);
  }
}

Derselbe Controller, für Kunden.

11.14.6. src/web/controllers/registration.controller.ts

// =========================================================================
// web/controllers/registration.controller.ts
// -------------------------------------------------------------------------
// „Patientenkonto anlegen“: Ein Patient, der noch kein Konto hat,
// legt es selbst an. UNGESCHÜTZTE Routen (per Definition hat man noch
// kein Konto):
//
//   POST /register/access     Schaltfläche "Create a patient account" der
//                             Authentifizierungsseite: prüft das CAPTCHA
//                             DIESER Seite und öffnet dann das Formular
//   GET  /register            das Formular
//   POST /register            das Anlegen, danach zurück zur Anmeldeseite
//
// Der Ablauf ist durch EIN CAPTCHA gegen Bots geschützt, das der
// Authentifizierungsseite:
//   1. Die Schaltfläche "Create a patient account" sendet das Anmeldeformular
//      an /register/access; wird das CAPTCHA korrekt eingegeben, stellt der Server
//      einen Pass aus (siehe auth/registration-pass.service.ts);
//   2. Ohne gültigen Pass leitet /register zur
//      Authentifizierungsseite zurück - die direkte Eingabe der URL nützt nichts;
//   3. Der Pass wird beim Anlegen verbraucht: Ein gelöstes CAPTCHA
//      erlaubt das Anlegen EINES Kontos;
//   4. Zusätzlich ist die Anzahl der pro Stunde und IP-Adresse angelegten Konten
//      begrenzt (siehe auth/attempt-limiter.service.ts).
//
// Das angelegte Konto ist genau das, das der ADMIN auf der Seite
// "Clients" anlegen würde (dieselbe Methode der Geschäftsschicht: addClient), außer
// dass der Patient Login und Passwort SELBST WÄHLT (erforderlich, mit
// Bestätigung).
// =========================================================================

import { Body, Controller, Get, HttpCode, Post, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { CaptchaService } from '../../auth/captcha.service';
import { AttemptLimiterService } from '../../auth/attempt-limiter.service';
import { COOKIE_REGISTRATION_PASS, RegistrationPassService } from '../../auth/registration-pass.service';
import { BusinessException } from '../../business/business.exception';
import { flash } from '../view-context';
import {
  BUSINESS_ERROR_FIELDS,
  FormErrors,
  invalidFields,
  titleOptions,
  validateForm,
} from '../helpers/form.helper';
import { RegistrationFormDto, PASSWORD_MIN } from '../models/person-form.dto';

interface RegistrationValues {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
}

@Controller('register')
export class RegistrationController {
  constructor(
    private readonly application: ApplicationModelService,
    private readonly captchaService: CaptchaService,
    private readonly limiter: AttemptLimiterService,
    private readonly passes: RegistrationPassService,
  ) {}

  // -----------------------------------------------------------------------
  // POST /register/access   Felder: captchaId, captcha (die der
  // Authentifizierungsseite; login und password, ebenfalls gesendet, werden ignoriert)
  // -----------------------------------------------------------------------
  @Post('access')
  access(@Body() body: Record<string, unknown>, @Req() req: Request, @Res() res: Response): void {
    const ip = req.ip ?? 'unknown';

    // zu viele kürzlich von dieser Adresse angelegte Konten: Weitermachen ist zwecklos
    const minutes = this.limiter.registrationBlockMinutes(ip);
    if (minutes > 0) {
      flash(res, { type: 'danger', key: 'ERRORS.TOO_MANY_ACCOUNTS', params: { minutes: String(minutes) } });
      return res.redirect('/login');
    }

    // CAPTCHA fehlt oder ist falsch: zurück zur Authentifizierungsseite, mit
    // einem neuen Bild (ein Fehlschlag zählt als fehlgeschlagene Anmeldung)
    if (!this.captchaService.verify(body.captchaId, body.captcha)) {
      this.limiter.loginFailure(ip, '');
      flash(res, { type: 'danger', key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
      return res.redirect('/login');
    }

    // korrektes CAPTCHA: Wir stellen den Pass aus und öffnen das Formular
    res.cookie(COOKIE_REGISTRATION_PASS, this.passes.issue(), this.passes.cookieOptions());
    res.redirect('/register');
  }

  // -----------------------------------------------------------------------
  // GET /register
  // -----------------------------------------------------------------------
  @Get()
  form(@Req() req: Request, @Res() res: Response): void {
    if (!this.hasPass(req, res)) {
      return;
    }
    this.show(res, { title: 'Mr', firstName: '', lastName: '', login: '' });
  }

  // -----------------------------------------------------------------------
  // POST /register
  // -----------------------------------------------------------------------
  @Post()
  @HttpCode(200) // wenn das Formular erneut angezeigt wird (siehe auth.controller.ts)
  async create(@Body() body: Record<string, unknown>, @Req() req: Request, @Res() res: Response): Promise<void> {
    if (!this.hasPass(req, res)) {
      return;
    }
    const ip = req.ip ?? 'unknown';
    const { dto, errors } = await validateForm(RegistrationFormDto, body);
    const values: RegistrationValues = {
      title: dto.title ?? 'Mr',
      firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
      lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
      login: dto.login ?? '',
    };

    // 1. zu viele kürzlich von dieser Adresse angelegte Konten?
    const minutes = this.limiter.registrationBlockMinutes(ip);
    if (minutes > 0) {
      return this.show(res, values, {}, 'ERRORS.TOO_MANY_ACCOUNTS', [], { minutes: String(minutes) });
    }

    // 2. alle Eingabefehler auf einmal (Felder + Bestätigung):
    //    Der Benutzer korrigiert sie alle in einem Zug
    const allErrors: FormErrors = { ...(errors ?? {}) };
    if (!allErrors.password && !allErrors.confirmation && dto.password !== dto.confirmation) {
      allErrors.confirmation = 'ERRORS.PASSWORDS_DIFFER';
    }
    if (Object.keys(allErrors).length > 0) {
      return this.show(res, values, allErrors);
    }

    // 3. das Anlegen (Client + USER-Konto, in einer Transaktion)
    try {
      await this.application.addClient({
        title: dto.title,
        lastName: dto.lastName,
        firstName: dto.firstName,
        login: dto.login,
        password: dto.password,
      });
    } catch (e) {
      if (!(e instanceof BusinessException)) {
        throw e;
      }
      // Login oder Vor- + Nachname bereits vergeben: Der Pass bleibt gültig
      return this.show(res, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
    }

    // 4. Der Pass wurde verwendet: Er erlaubt nicht das Anlegen eines 2. Kontos
    this.passes.consume(req.cookies?.[COOKIE_REGISTRATION_PASS]);
    res.clearCookie(COOKIE_REGISTRATION_PASS, { path: '/register' });
    this.limiter.registrationSuccess(ip);

    // 5. zurück zur Anmeldeseite, Login vorausgefüllt
    flash(res, { type: 'success', key: 'REGISTRATION.DONE', params: { login: dto.login } });
    res.redirect(`/login?${new URLSearchParams({ login: dto.login }).toString()}`);
  }

  // ───────────────────────────────────────────────────────────────── private Methoden

  // kein gültiger Pass: zurück zur Authentifizierungsseite
  private hasPass(req: Request, res: Response): boolean {
    if (this.passes.isValid(req.cookies?.[COOKIE_REGISTRATION_PASS])) {
      return true;
    }
    flash(res, { type: 'danger', key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
    res.redirect('/login');
    return false;
  }

  // das Formular; es wird nie ein Passwort an den Browser zurückgesendet
  private show(
    res: Response,
    values: RegistrationValues,
    errors: FormErrors = {},
    error: string | null = null,
    otherFields: string[] = [],
    errorParams?: Record<string, string>,
  ): void {
    res.render('account/registration', {
      pageTitle: 'REGISTRATION.TITLE',
      values,
      titles: titleOptions(values.title),
      errors,
      invalidFields: invalidFields(errors, otherFields),
      error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
      errorParams,
      passwordMin: PASSWORD_MIN,
    });
  }
}

Kommentieren wir diesen Code:

  • Zeilen 69–91: Die Schaltfläche „Patientenkonto anlegen“ auf der Anmeldeseite sendet das Anmeldeformular an diese Adresse (Attribut [formaction]; siehe Beispiel 20). Das CAPTCHA der Seite wird geprüft; ist es korrekt, wird ein Pass in einem Cookie gespeichert und der Browser auf das Formular weitergeleitet;
  • Zeilen 96–102: das Formular, aber nur mit einem gültigen Pass;
  • Zeilen 109–163: Kontoerstellung: Pass, Zeitlimit, Validierung (einschließlich der Prüfung, ob das Passwort mit seiner Bestätigung übereinstimmt), Erstellung durch die Geschäftsschicht. Der Pass wird anschließend verbraucht, und der Patient wird mit vorausgefülltem Benutzernamen auf die Anmeldeseite weitergeleitet;
  • Zeilen 168–175: Ohne Pass erfolgt die Rückkehr zur Anmeldeseite mit einer Meldung;
  • Zeilen 178–185: das Formular. [passwordMin] wird für den Hilfetext verwendet („Mindestens 6 Zeichen“).

11.14.7. src/web/controllers/patient-area.controller.ts

// =========================================================================
// web/controllers/patient-area.controller.ts
// -------------------------------------------------------------------------
// 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 der bevorstehende Termin
//   POST /my-area/cancel           storniert SEINEN Termin
//   GET  /my-account               Formular zum Bearbeiten seines Kontos
//   POST /my-account               Aktualisierung
//   POST /my-account/delete        Löschen des Kontos (und seiner Termine)
//
// Goldene Regel dieses Controllers: Der betroffene Patient ist IMMER der aus dem
// Token (connectedPatient), niemals ein vom Browser gesendeter Bezeichner.
// Ein Patient kann daher weder sehen noch bearbeiten noch stornieren, was einem
// anderen Patienten gehört, selbst mit selbst gebauten Anfragen.
//
// Jede Aktualisierung oder Löschung des Kontos erfordert das AKTUELLE
// Passwort: Wer eine offen gebliebene Sitzung gefunden hat, kann
// weder das Passwort ändern noch das Konto löschen. Fehler beim aktuellen
// Passwort werden als fehlgeschlagene Anmeldungen gezählt (gleiches Limit).
// =========================================================================

import { Body, Controller, Get, HttpCode, Post, Render, Req, Res, UseGuards } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { AuthService } from '../../auth/auth.service';
import { AttemptLimiterService } from '../../auth/attempt-limiter.service';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { COOKIE_JWT, jwtCookieOptions } from '../../auth/auth.constants';
import { BusinessException } from '../../business/business.exception';
import { Client } from '../../entities/client.entity';
import { flash } from '../view-context';
import { formatTime, formatDay } from '../helpers/dates.helper';
import { label, connectedPatient } from '../helpers/patient.helper';
import {
  BUSINESS_ERROR_FIELDS,
  FormErrors,
  invalidFields,
  titleOptions,
  validateForm,
} from '../helpers/form.helper';
import { MyAccountFormDto, PASSWORD_MIN } from '../models/person-form.dto';

type AuthenticatedRequest = Request & { user: ConnectedUser };

interface MyAccountValues {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  version: number | null;
}

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('USER')
@Controller()
export class PatientAreaController {
  constructor(
    private readonly application: ApplicationModelService,
    private readonly authService: AuthService,
    private readonly limiter: AttemptLimiterService,
  ) {}

  // -----------------------------------------------------------------------
  // GET /my-area
  // @Res({ passthrough: true }): Wir greifen auf die Response zu (um die Sprache
  // in res.locals zu lesen), OHNE auf die normale Funktionsweise von @Render zu verzichten.
  // -----------------------------------------------------------------------
  @Get('my-area')
  @Render('patient/area')
  async area(@Req() req: AuthenticatedRequest, @Res({ passthrough: true }) res: Response) {
    const patient = await connectedPatient(this.application, req.user);
    const appointments = await this.application.getClientUpcomingAppointments(patient.id);
    return {
      pageTitle: 'AREA.TITLE',
      patient: label(patient),
      appointments: appointments.map((appointment) => ({
        id: appointment.id,
        day: formatDay(appointment.day, res.locals.lang),
        time: `${formatTime(appointment.slot.startHour, appointment.slot.startMinute)} - ${formatTime(appointment.slot.endHour, appointment.slot.endMinute)}`,
        doctor: label(appointment.slot.doctor),
        // Link zum Terminkalender des Arztes an diesem Tag: Dort sieht der Patient seinen Namen
        scheduleUrl: `/schedule?${new URLSearchParams({ doctorId: String(appointment.slot.doctor.id), day: appointment.day })}`,
      })),
    };
  }

  // -----------------------------------------------------------------------
  // POST /my-area/cancel   Feld: appointmentId
  // -----------------------------------------------------------------------
  @Post('my-area/cancel')
  async cancelAppointment(
    @Body() body: Record<string, string>,
    @Req() req: AuthenticatedRequest,
    @Res() res: Response,
  ): Promise<void> {
    const patient = await connectedPatient(this.application, req.user);
    const appointment = await this.application.getAppointmentById(Number(body.appointmentId) || 0);
    // ein nicht existierender Termin und der eines ANDEREN Patienten erhalten
    // dieselbe Antwort: Über die Termine anderer Personen wird nichts verraten
    if (appointment === null || appointment.clientId !== patient.id) {
      flash(res, { type: 'danger', key: 'ERRORS.APPOINTMENT_NOT_FOUND' });
    } else {
      await this.application.deleteAppointment(appointment);
      flash(res, { type: 'success', key: 'SCHEDULE.CANCELLED' });
    }
    res.redirect('/my-area');
  }

  // -----------------------------------------------------------------------
  // GET /my-account
  // -----------------------------------------------------------------------
  @Get('my-account')
  async accountForm(@Req() req: AuthenticatedRequest, @Res() res: Response): Promise<void> {
    const patient = await connectedPatient(this.application, req.user);
    this.show(res, {
      title: patient.title,
      firstName: patient.firstName,
      lastName: patient.lastName,
      login: patient.user.login,
      version: patient.version,
    });
  }

  // -----------------------------------------------------------------------
  // POST /my-account
  // -----------------------------------------------------------------------
  @Post('my-account')
  @HttpCode(200) // wenn das Formular erneut angezeigt wird (siehe auth.controller.ts)
  async editAccount(
    @Body() body: Record<string, unknown>,
    @Req() req: AuthenticatedRequest,
    @Res() res: Response,
  ): Promise<void> {
    const patient = await connectedPatient(this.application, req.user);
    const { dto, errors } = await validateForm(MyAccountFormDto, body);
    const values: MyAccountValues = {
      title: dto.title ?? patient.title,
      firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
      lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
      login: dto.login ?? '',
      version: dto.version ?? null,
    };

    const allErrors: FormErrors = { ...(errors ?? {}) };
    if (!allErrors.password && dto.password !== undefined && dto.password !== dto.confirmation) {
      allErrors.confirmation = 'ERRORS.PASSWORDS_DIFFER';
    }
    if (Object.keys(allErrors).length > 0) {
      return this.show(res, values, allErrors);
    }

    // das aktuelle Passwort
    const passwordError = await this.checkCurrentPassword(req, patient, dto.currentPassword);
    if (passwordError !== null) {
      return this.show(
        res,
        values,
        passwordError.key === 'ERRORS.WRONG_CURRENT_PASSWORD' ? { currentPassword: passwordError.key } : {},
        passwordError.key,
        [],
        passwordError.params,
      );
    }

    try {
      const client = await this.application.editClient(patient.id, {
        title: dto.title,
        lastName: dto.lastName,
        firstName: dto.firstName,
        login: dto.login,
        password: dto.password, // undefined = unverändert
        version: dto.version,
      });
      // Login und Anzeigename stehen IM Token: Wir stellen ein
      // neues aus, sonst würde die Navigationsleiste den alten Namen behalten
      res.cookie(COOKIE_JWT, this.authService.createToken(client.user), jwtCookieOptions());
      flash(res, { type: 'success', key: 'MY_ACCOUNT.UPDATED' });
      res.redirect('/my-area');
    } catch (e) {
      if (!(e instanceof BusinessException)) {
        throw e;
      }
      this.show(res, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
    }
  }

  // -----------------------------------------------------------------------
  // POST /my-account/delete   Feld: deletePassword
  // Das Konto, der Client und ALLE seine Termine verschwinden gemeinsam,
  // danach wird der Patient abgemeldet.
  // -----------------------------------------------------------------------
  @Post('my-account/delete')
  async deleteAccount(
    @Body() body: Record<string, string>,
    @Req() req: AuthenticatedRequest,
    @Res() res: Response,
  ): Promise<void> {
    const patient = await connectedPatient(this.application, req.user);
    const passwordError = await this.checkCurrentPassword(req, patient, body.deletePassword);
    if (passwordError !== null) {
      flash(res, { type: 'danger', key: passwordError.key, params: passwordError.params });
      return res.redirect('/my-account');
    }
    await this.application.deleteClient(patient.id);
    res.clearCookie(COOKIE_JWT, { path: '/' });
    flash(res, { type: 'success', key: 'MY_ACCOUNT.DELETED' });
    res.redirect('/login');
  }

  // ───────────────────────────────────────────────────────────────── private Methoden

  // null, wenn das aktuelle Passwort korrekt ist; andernfalls der Schlüssel der Meldung
  private async checkCurrentPassword(
    req: Request,
    patient: Client,
    password: unknown,
  ): Promise<{ key: string; params?: Record<string, string> } | null> {
    const ip = req.ip ?? 'unknown';
    const login = patient.user.login;
    const minutes = this.limiter.loginBlockMinutes(ip, login);
    if (minutes > 0) {
      return { key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: String(minutes) } };
    }
    const ok =
      typeof password === 'string' &&
      password !== '' &&
      (await this.authService.validateUser(login, password)) !== null;
    if (!ok) {
      this.limiter.loginFailure(ip, login);
      return { key: 'ERRORS.WRONG_CURRENT_PASSWORD' };
    }
    return null;
  }

  private show(
    res: Response,
    values: MyAccountValues,
    errors: FormErrors = {},
    error: string | null = null,
    otherFields: string[] = [],
    errorParams?: Record<string, string>,
  ): void {
    res.render('patient/account', {
      pageTitle: 'MY_ACCOUNT.TITLE',
      values,
      titles: titleOptions(values.title),
      errors,
      invalidFields: invalidFields(errors, otherFields),
      error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
      errorParams,
      passwordMin: PASSWORD_MIN,
    });
  }
}

Kommentieren wir diesen Code:

  • Zeilen 59–60: Patienten vorbehalten;
  • Zeilen 14–17: die goldene Regel dieses Controllers: Der betreffende Patient ist immer derjenige, der dem Token zugeordnet ist, nie ein vom Browser gesendeter Bezeichner;
  • Zeilen 74–91: die Seite „Mein Bereich“. [@Res({ passthrough: true })] ermöglicht den Zugriff auf die Antwort (um die Sprache in [res.locals] zu lesen und das Datum zu formatieren), ohne auf [@Render] zu verzichten (siehe Beispiel 05);
  • Zeilen 96–101: das Stornieren eines Termins. Ein nicht existierender Termin und der Termin eines anderen Patienten erhalten die gleiche Antwort: Es werden keine Informationen über die Termine anderer Patienten preisgegeben;
  • Zeilen 118–128: das Kontoformular, vorausgefüllt;
  • Zeilen 133–139: die Aktualisierung: Validierung, Überprüfung des aktuellen Passworts, dann die Geschäftslogikschicht. Das Token enthält den Login und den Anzeigenamen: Nach einer Aktualisierung wird ein neues Token ausgestellt (Zeile 182); andernfalls würde die Navigationsleiste den alten Namen behalten;
  • Zeilen 198–203: Das Konto, die Akte und alle Termine werden gelöscht (mit derselben Methode der Geschäftsschicht wie für ADMIN), dann erfolgt die Abmeldung;
  • Zeilen 219–223: Für jede Änderung ist das aktuelle Passwort erforderlich: Jemand, der eine offen gelassene Sitzung vorfindet, könnte weder das Passwort ändern noch das Konto löschen. Fehler zählen als fehlgeschlagene Anmeldungen;
  • Zeilen 241–248: das Formular.

11.15. Die Views

Die Views müssen kaum Entscheidungen treffen: Ihr Template wurde von den Controllern vorbereitet. Jede View beginnt mit einem [Handlebars] [{{!-- ... --}}] -Kommentar, der ihre Rolle beschreibt; diese Kommentare erscheinen nicht in den an den Browser gesendeten Seiten.

11.15.1. Die Template- und Partial-Dateien

11.15.1.1. views/layout.hbs

{{!--
  ==========================================================================
  views/layout.hbs
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  Das allen Seiten GEMEINSAME Template. hbs verwendet es automatisch
  (Datei namens "layout.hbs" im Wurzelverzeichnis des Ordners views): die vom
  Controller angeforderte Seite (schedule.hbs, login.hbs...) wird an der
  Stelle {{{body}}} eingefügt.

  Dreifache geschweifte Klammern {{{ }}}: der Inhalt wird UNVERÄNDERT eingefügt, ohne
  Maskierung - hier unerlässlich, da [body] bereits fertiges HTML ist.
  Überall sonst verwenden wir {{ }}, das die Zeichen < > & " ' maskiert
  (Schutz vor HTML-Injection, z. B. durch einen eingegebenen Namen).

  Meldungen: ein Erfolg wird am ANFANG der Seite angezeigt ({{> flash}}), ein
  Fehler am ENDE, auf hellrosa Hintergrund ({{> errors}}).

  Entspricht src/index.html + app.html des Angular-Clients.
  ==========================================================================
--}}
<!doctype html>
<html lang="{{lang}}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{t pageTitle}} - {{t 'APP.TITLE'}}</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-4">
    {{> navbar}}
    {{> flash}}
    {{{body}}}
    {{> errors}}
  </div>
  {{!-- der Dialog "Are you sure?", ausgeblendet, solange er nicht benötigt wird --}}
  {{> confirmation}}
  <script src="/js/app.js"></script>
</body>
</html>
  • Zeile 22: die Sprache der Seite (siehe Beispiel 22);
  • Zeile 26: der übersetzte Titel: Der Schlüssel [pageTitle] wird von jeder Aktion bereitgestellt;
  • Zeilen 32–35: die Navigationsleiste, die Erfolgsmeldung, die Seite und der Fehlerbereich;
  • Zeilen 38–39: das Bestätigungsfenster und sein Skript (siehe Beispiel 21).

11.15.1.2. views/partials/navbar.hbs

{{!--
  views/partials/navbar.hbs - die Navigationsleiste (eingefügt durch {{> navbar}}).

  Gleicher Inhalt wie beim Angular-Client (Titel, FR/EN, Rolle, Name,
  Abmelden), plus ein Menü, dessen Einträge von der Rolle abhängen:
  "Doctors" und "Clients" erscheinen nur für den ADMIN. Das ist nur eine
  Anzeigehilfe: der eigentliche Schutz sind die Guards der
  Controller (ein USER, der /doctors von Hand eingibt, erhält eine 403-Seite).
  Ein Patient (USER) hat außerdem sein Menü "My area".
--}}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">{{t 'APP.TITLE'}}</span>

  {{#if currentUser}}
    <ul class="navbar-nav me-auto">
      {{#if currentUser.isPatient}}
        <li class="nav-item"><a class="nav-link {{active currentPath '/my-'}}" href="/my-area">{{t 'APP.MENU_MY_AREA'}}</a></li>
      {{/if}}
      <li class="nav-item"><a class="nav-link {{active currentPath '/schedule'}}" href="/schedule">{{t 'APP.MENU_SCHEDULE'}}</a></li>
      {{#if currentUser.isAdmin}}
        <li class="nav-item"><a class="nav-link {{active currentPath '/doctors'}}" href="/doctors">{{t 'APP.MENU_DOCTORS'}}</a></li>
        <li class="nav-item"><a class="nav-link {{active currentPath '/clients'}}" href="/clients">{{t 'APP.MENU_PATIENTS'}}</a></li>
      {{/if}}
    </ul>
  {{else}}
    <div class="me-auto"></div>
  {{/if}}

  <div class="d-flex align-items-center gap-2">
    {{!-- FR / EN: einfache Links (GET /language/fr), die aktive Sprache wird hervorgehoben --}}
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      <a class="btn {{#if (eq lang 'fr')}}btn-light{{else}}btn-outline-light{{/if}}" href="/language/fr">FR</a>
      <a class="btn {{#if (eq lang 'en')}}btn-light{{else}}btn-outline-light{{/if}}" href="/language/en">EN</a>
    </div>

    {{#if currentUser}}
      <span class="badge text-bg-light text-primary">{{currentUser.role}}</span>
      <span class="text-white">{{currentUser.name}}</span>
      {{!-- logout ist ein POST: ein Formular, das auf seine Schaltfläche reduziert ist --}}
      <form method="post" action="/logout" class="m-0">
        <button type="submit" class="btn btn-sm btn-outline-light">{{t 'APP.LOGOUT'}}</button>
      </form>
    {{/if}}
  </div>
</nav>
  • Zeilen 14–25: Die Menüs hängen von der Rolle ab: „Mein Bereich“ für einen Patienten, „Ärzte“ und „Patienten“ für den ADMIN. Das dient lediglich dem Komfort; die Sicherheit wird durch die Guards der Controller gewährleistet;
  • Zeilen 31–34: die Links FR / EN;
  • Zeilen 36–43: die Rolle, der Name und die Abmeldeschaltfläche in einem POST-Formular.

11.15.1.3. views/partials/flash.hbs

{{!--
  views/partials/flash.hbs - die ERFOLGSMELDUNG, die von der vorherigen
  Action gesetzt wurde (Termin gebucht, Arzt hinzugefügt...) und nur
  einmal am Seitenanfang angezeigt wird (siehe src/web/view-context.ts).
  Eine FEHLER-Flash-Meldung wird dagegen am Seitenende angezeigt, durch
  views/partials/errors.hbs.
--}}
{{#if (eq flash.type 'success')}}
  <div class="alert alert-success" role="status">
    {{t flash.key name=flash.params.name login=flash.params.login minutes=flash.params.minutes}}
  </div>
{{/if}}

Zeile 10: Die Nachricht ist ein Schlüssel; ihre möglichen Parameter ([name], [login], [minutes]) werden an den Helfer [t] übergeben.

11.15.1.4. views/partials/errors.hbs

{{!--
  ==========================================================================
  views/partials/errors.hbs - der Fehlerbereich am ENDE jeder Seite auf
  hellrosa Hintergrund (Klasse .error-zone, siehe public/css/styles.css).

  Er fasst die beiden möglichen Fehlerquellen zusammen:
    - [error]: der Fehler der angezeigten Seite (Formular abgelehnt, Login oder
      Vor- + Nachname bereits vergeben, ungültiges Datum, falsches Passwort...);
    - eine Fehler-Flash-Meldung, die von der vorherigen Action vor einer
      Weiterleitung gesetzt wurde (Slot bereits gebucht, Löschen abgelehnt...).

  role="alert": ein Screenreader liest die Meldung vor, sobald
  die Seite angezeigt wird, auch wenn sie am Seitenende steht.
  ==========================================================================
--}}
{{#if (or error (eq flash.type 'danger'))}}
  <div class="error-zone" role="alert">
    {{#if error}}
      <div>{{t error minutes=errorParams.minutes}}</div>
    {{/if}}
    {{#if (eq flash.type 'danger')}}
      <div>{{t flash.key name=flash.params.name login=flash.params.login minutes=flash.params.minutes}}</div>
    {{/if}}
  </div>
{{/if}}

Zeile 16: Der Bereich wird angezeigt, wenn ein Seitenfehler oder eine Flash-Fehlermeldung vorliegt: Der Helfer [or] verknüpft beide Bedingungen, wobei [eq] als Unterausdruck verwendet wird.

11.15.1.5. views/partials/confirmation.hbs

{{!--
  ==========================================================================
  views/partials/confirmation.hbs - der modale Dialog "Are you sure?".

  Er ersetzt das Fenster window.confirm() des Browsers, das sich weder
  gestalten noch übersetzen lässt (seine Schaltflächen bleiben in der Sprache des
  Browsers, nicht in der der Seite).

  EIN Dialog für die gesamte Seite, zunächst ausgeblendet (d-none). Seine
  Beschriftungen werden hier vom Server übersetzt, wie der Rest der Seite;
  das kleine Skript public/js/app.js zeigt ihn lediglich an, trägt darin
  die für das Formular spezifische Meldung ein (Attribut data-confirmation) und sendet
  das Formular ab, wenn der Benutzer bestätigt.

  Gleiche Bootstrap-Klassen wie beim Buchungsdialog (partials/booking.hbs).
  ==========================================================================
--}}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title">{{t 'CONFIRMATION.TITLE'}}</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="{{t 'BOOKING_DIALOG.CLOSE_ARIA'}}"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          {{!-- "No, go back" statt "Cancel": die Frage lautet manchmal
               "Cancel this appointment?", und eine Schaltfläche "Cancel" wäre mehrdeutig --}}
          <button type="button" class="btn btn-secondary" data-action="no">{{t 'CONFIRMATION.NO'}}</button>
          <button type="button" class="btn btn-danger" data-action="yes">{{t 'CONFIRMATION.YES'}}</button>
        </div>
      </div>
    </div>
  </div>
</div>

Das Fenster aus Beispiel 21, mit übersetzten Beschriftungen und Barrierefreiheitsattributen: [role="alertdialog"] sowie [aria-labelledby] / [aria-describedby], die den von einem Screenreader vorgelesenen Titel und die Meldung festlegen.

11.15.1.6. views/partials/captcha.hbs

{{!--
  ==========================================================================
  views/partials/captcha.hbs - das Captcha der Authentifizierungsseite
  (siehe src/auth/captcha.service.ts). Es schützt sowohl den Login als auch
  den Zugang zur Kontoerstellung (Schaltfläche "Create a patient account").

  {{{captcha.svg}}}: dreifache geschweifte Klammern, das SVG-Bild wird UNVERÄNDERT
  in die Seite eingefügt. Das ist hier unbedenklich, da dieses SVG vom
  Server selbst erzeugt wird (Bibliothek svg-captcha) und nichts enthält,
  was vom Benutzer stammt - bei Benutzereingaben würden wir das NIEMALS tun.

  Das versteckte Feld captchaId 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 (Pfad = aktuelle URL).
  ==========================================================================
--}}
<div class="mb-3">
  <label class="form-label" for="captcha">{{t 'CAPTCHA.LABEL'}}</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="{{t 'CAPTCHA.IMAGE_ALT'}}">{{{captcha.svg}}}</div>
    <a class="small" href="{{currentPath}}">{{t 'CAPTCHA.NEW_IMAGE'}}</a>
  </div>
  <input type="hidden" name="captchaId" value="{{captcha.id}}">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false" required
         class="form-control {{#if invalidFields.captcha}}is-invalid{{/if}}">
  {{#if errors.captcha}}
    <div class="invalid-feedback">{{t errors.captcha}}</div>
  {{else}}
    <div class="form-text">{{t 'CAPTCHA.HELP'}}</div>
  {{/if}}
</div>
  • Zeile 20: das SVG-Bild, unverändert eingefügt (dreifache geschweifte Klammern): Es wird vom Server erzeugt, ohne Benutzereingaben;
  • Zeile 21: „Anderes Bild“ lädt die Seite einfach neu;
  • Zeile 23: die CAPTCHA-ID in einem verborgenen Feld.

11.15.1.7. views/partials/personFields.hbs

{{!--
  views/partials/personFields.hbs - die Identitätsfelder (Anrede, Vorname,
  Nachname), die drei Formularen gemeinsam sind: dem Arzt-/Client-Formular des ADMIN,
  "Create a patient account" und "Manage my account".
  Das Partial verwendet das Modell der Seite, die es einfügt: values, titles,
  errors (Meldung unter dem Feld) und invalidFields (roter Rahmen).
--}}
<div class="mb-3">
  <label class="form-label" for="title">{{t 'PERSONS.TITLE_LABEL'}}</label>
  <select id="title" name="title" class="form-select {{#if invalidFields.title}}is-invalid{{/if}}">
    {{#each titles}}
      <option value="{{value}}" {{#if selected}}selected{{/if}}>{{value}}</option>
    {{/each}}
  </select>
  {{#if errors.title}}<div class="invalid-feedback">{{t errors.title}}</div>{{/if}}
</div>

<div class="row g-3 mb-3">
  <div class="col-sm-6">
    <label class="form-label" for="firstName">{{t 'PERSONS.FIRSTNAME_LABEL'}}</label>
    <input id="firstName" name="firstName" type="text" maxlength="20" required
           class="form-control {{#if invalidFields.firstName}}is-invalid{{/if}}" value="{{values.firstName}}">
    {{#if errors.firstName}}<div class="invalid-feedback">{{t errors.firstName}}</div>{{/if}}
  </div>
  <div class="col-sm-6">
    <label class="form-label" for="lastName">{{t 'PERSONS.LASTNAME_LABEL'}}</label>
    <input id="lastName" name="lastName" type="text" maxlength="20" required
           class="form-control {{#if invalidFields.lastName}}is-invalid{{/if}}" value="{{values.lastName}}">
    {{#if errors.lastName}}<div class="invalid-feedback">{{t errors.lastName}}</div>{{/if}}
  </div>
</div>

Die Identitätsfelder, die drei Formularen gemeinsam sind (siehe Beispiel 19). Ein ohne Parameter eingefügtes Partial verwendet das Template der Seite, die es einfügt: [values], [titles], [errors], [invalidFields].

11.15.1.8. views/partials/booking.hbs

{{!--
  ==========================================================================
  views/partials/booking.hbs - der Buchungsdialog.

  Gleiche Technik wie beim Angular-Client (booking-dialog): die ECHTEN Bootstrap-Klassen
  eines modalen Dialogs (.modal, .modal-backdrop...), die "fest codiert"
  sichtbar gemacht werden (show d-block) statt durch das JavaScript von Bootstrap.
  Der Unterschied: Der SERVER entscheidet, ihn anzuzeigen
  (Parameter &book=... der URL), und das Schließen besteht darin, einem Link
  zur selben Seite ohne diesen Parameter zu folgen.
  ==========================================================================
--}}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="/schedule/book" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">{{t 'BOOKING_DIALOG.TITLE'}}</h5>
        <a class="btn-close" href="{{backUrl}}" aria-label="{{t 'BOOKING_DIALOG.CLOSE_ARIA'}}"></a>
      </div>

      <div class="modal-body">
        <p>{{t 'BOOKING_DIALOG.SLOT' time=booking.time}}</p>

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

        {{#if booking.patient}}
          {{!-- ein Patient bucht für sich selbst: keine Auswahlliste
               (und der Server ignoriert ohnehin jede clientId) --}}
          <p class="mb-0">{{t 'BOOKING_DIALOG.PATIENT_LABEL'}}: <strong>{{booking.patient}}</strong></p>
        {{else}}
          <label class="form-label" for="clientId">{{t 'BOOKING_DIALOG.PATIENT_LABEL'}}</label>
          <select id="clientId" name="clientId" class="form-select" required autofocus>
            <option value="">{{t 'BOOKING_DIALOG.CHOOSE_PATIENT'}}</option>
            {{#each booking.clients}}
              <option value="{{id}}">{{label}}</option>
            {{/each}}
          </select>
        {{/if}}
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" href="{{backUrl}}">{{t 'BOOKING_DIALOG.CANCEL'}}</a>
        <button type="submit" class="btn btn-primary">{{t 'BOOKING_DIALOG.CONFIRM'}}</button>
      </div>
    </form>
  </div>
</div>
  • Zeilen 13–14: die [Bootstrap]-Klassen eines modalen Fensters, das „fest codiert“ sichtbar gemacht wird: Der Server entscheidet, es anzuzeigen;
  • Zeile 19: Das Schließen des Fensters bedeutet, einem Link auf dieselbe Seite zu folgen, ohne den Parameter [book];
  • Zeilen 26–28: die verborgenen Felder des Formulars;
  • Zeilen 30–34: Ein Patient sieht seinen Namen; ein Administrator wählt den Patienten aus einer Liste aus.

11.15.2. Die Seiten

11.15.2.1. views/login.hbs

{{!--
  ==========================================================================
  views/login.hbs - das Login-Formular.
  Entspricht features/login/ des Angular-Clients. Ein gewöhnliches HTML-<form>:
  der Browser selbst sendet Login, Passwort und Captcha-Antwort mit
  POST /login, ohne JavaScript. Bei einem Fehler sendet der Server DIESE
  Seite zurück, mit dem bereits eingegebenen Login, einem NEUEN Captcha und [error],
  das vom Layout am Seitenende angezeigt wird.
  ==========================================================================
--}}
<div class="row justify-content-center">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3">{{t 'LOGIN.TITLE'}}</h5>

      <form method="post" action="/login">
        <div class="mb-3">
          <label class="form-label" for="login">{{t 'LOGIN.LOGIN_LABEL'}}</label>
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="{{login}}" required {{#unless login}}autofocus{{/unless}}>
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">{{t 'LOGIN.PASSWORD_LABEL'}}</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required {{#if login}}autofocus{{/if}}>
        </div>

        {{> captcha}}

        <button type="submit" class="btn btn-primary w-100">{{t 'LOGIN.SUBMIT'}}</button>

        {{!-- noch kein Konto: ein Patient kann selbst eines erstellen.
             Es ist KEIN einfacher Link: es ist eine zweite Submit-Schaltfläche
             DIESES Formulars, die an eine andere Adresse geht (formaction). Der
             Server prüft dort das obige Captcha, bevor er die Seite zur
             Kontoerstellung öffnet (siehe RegistrationController).
             formnovalidate: der Browser verlangt weder Login noch Passwort
             (nutzlos für die Kontoerstellung); der Server prüft das Captcha.
             Enter in einem Feld löst immer die ERSTE Schaltfläche des Formulars aus,
             "Log in". --}}
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="/register/access" formnovalidate>{{t 'LOGIN.CREATE_ACCOUNT'}}</button>
        <div class="form-text text-center">{{t 'LOGIN.CREATE_ACCOUNT_HELP'}}</div>
      </form>

      <div class="text-muted small mt-3">
        {{t 'LOGIN.DEMO_ACCOUNTS'}}
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - {{t 'LOGIN.DEMO_ADMIN'}}</li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {{t 'LOGIN.DEMO_DOCTOR'}}</li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {{t 'LOGIN.DEMO_USER'}}</li>
        </ul>
      </div>
    </div>
  </div>
</div>
  • Zeile 20: Der Cursor wird im Login-Feld platziert oder im Passwortfeld, wenn der Login bereits bekannt ist;
  • Zeile 28: das CAPTCHA;
  • Zeilen 41–42: Die zweite Schaltfläche sendet dasselbe Formular an [/register/access] ([formaction]). [formnovalidate]: Der Browser verlangt keinen Benutzernamen und kein Passwort, da sie zum Anlegen eines Kontos nicht benötigt werden.

11.15.2.2. views/schedule.hbs

{{!--
  ==========================================================================
  views/schedule.hbs - die Hauptseite (siehe ScheduleController).
  Drei Blöcke, wie die drei Komponenten des Angular-Clients:
    1. die Wahl des Arztes und des Tages   (<app-doctor-day-picker>)
    2. der Terminkalender                   (<app-agenda>)
    3. der Buchungsdialog                    (<app-booking-dialog>)
  ==========================================================================
--}}

{{!-- ein möglicher Fehler (ungültiges Datum, unbekannter Arzt) wird
     am Seitenende vom Layout angezeigt (siehe views/partials/errors.hbs) --}}

{{!-- 1. Wahl des Arztes und des Tages: ein GET-Formular, das diese Seite einfach
     mit ?doctorId=...&day=... in der URL neu lädt --}}
<form method="get" action="/schedule" class="card p-3 mb-3">
  <div class="row g-2 align-items-end">
    <div class="col-sm-5">
      <label class="form-label" for="doctorId">{{t 'DOCTOR_DAY_PICKER.DOCTOR_LABEL'}}</label>
      <select id="doctorId" name="doctorId" class="form-select" required>
        <option value="">{{t 'DOCTOR_DAY_PICKER.CHOOSE_DOCTOR'}}</option>
        {{#each doctors}}
          <option value="{{id}}" {{#if selected}}selected{{/if}}>{{label}}</option>
        {{/each}}
      </select>
    </div>
    <div class="col-sm-4">
      <label class="form-label" for="day">{{t 'DOCTOR_DAY_PICKER.DAY_LABEL'}}</label>
      <input id="day" name="day" type="date" class="form-control" value="{{day}}" required>
    </div>
    <div class="col-sm-3">
      <button type="submit" class="btn btn-primary w-100">{{t 'DOCTOR_DAY_PICKER.VIEW_SCHEDULE'}}</button>
    </div>
  </div>
</form>

{{!-- Patient, der bereits einen bevorstehenden Termin hat: deshalb gibt es keine Schaltfläche "Book" --}}
{{#if info}}
  <div class="alert alert-info">
    {{t info}} <a href="/my-area" class="alert-link">{{t 'APP.MENU_MY_AREA'}}</a>
  </div>
{{/if}}

{{!-- 2. der Terminkalender --}}
{{#if schedule}}
  <div class="card p-3">
    <h5>{{t 'SCHEDULE.TITLE_PREFIX'}} {{schedule.day}} - {{schedule.doctor}}</h5>

    {{#if schedule.rows.length}}
      <table class="table table-hover align-middle">
        <thead>
          <tr>
            <th>{{t 'SCHEDULE.COLUMN_SLOT'}}</th>
            <th>{{t 'SCHEDULE.COLUMN_STATUS'}}</th>
            <th></th>
          </tr>
        </thead>
        <tbody>
          {{#each schedule.rows}}
            <tr {{#if bookable}}class="free-slot"{{/if}}>
              <td>{{time}}</td>
              <td>
                {{!-- [patient] wird nur gesetzt, wenn der Benutzer diesen Namen
                     sehen darf (ADMIN, DOCTOR oder der Patient bei SEINEM
                     Termin) - andernfalls einfach "Booked" --}}
                {{#if free}}
                  <span class="badge text-bg-success">{{t 'SCHEDULE.FREE'}}</span>
                {{else if patient}}
                  <span class="badge {{#if mine}}text-bg-primary{{else}}text-bg-secondary{{/if}}">{{patient}}</span>
                {{else}}
                  <span class="badge text-bg-secondary">{{t 'SCHEDULE.BOOKED_BY_OTHER'}}</span>
                {{/if}}
              </td>
              <td>
                {{!-- die angezeigten Schaltflächen wurden vom Controller entschieden
                     (bookable, appointmentId), je nach Rolle des Benutzers --}}
                {{#if bookable}}
                  {{!-- "Book" ist ein einfacher Link: er öffnet diese Seite erneut
                       mit dem Buchungsdialog dieses Slots --}}
                  <a class="btn btn-sm btn-outline-success" href="{{bookUrl}}">{{t 'SCHEDULE.BOOK'}}</a>
                {{/if}}
                {{#if appointmentId}}
                  {{!-- "Cancel" ÄNDERT Daten: daher ein POST.
                       @root: das Modell der SEITE (innerhalb eines {{#each}} beziehen sich
                       einfache Namen auf die Felder der aktuellen Zeile) --}}
                  <form method="post" action="/schedule/cancel" class="m-0"
                        data-confirmation="{{t 'SCHEDULE.CANCEL_CONFIRM'}}">
                    <input type="hidden" name="appointmentId" value="{{appointmentId}}">
                    <input type="hidden" name="doctorId" value="{{@root.doctorId}}">
                    <input type="hidden" name="day" value="{{@root.day}}">
                    <button type="submit" class="btn btn-sm btn-outline-danger">{{t 'SCHEDULE.CANCEL_APPOINTMENT'}}</button>
                  </form>
                {{/if}}
              </td>
            </tr>
          {{/each}}
        </tbody>
      </table>
    {{else}}
      <p class="text-muted mb-0">{{t 'SCHEDULE.NO_SLOTS'}}</p>
    {{/if}}
  </div>
{{else}}
  <p class="text-muted">{{t 'SCHEDULE.EMPTY_STATE'}}</p>
{{/if}}

{{!-- 3. der Buchungsdialog, nur wenn die URL &book=... enthält --}}
{{#if booking}}
  {{> booking}}
{{/if}}
  • Zeilen 16–35: Auswahl eines Arztes und eines Datums: ein GET-Formular (siehe Beispiel 17). Ein Feld [type="date"] sendet das Datum im Format [yyyy-mm-dd];
  • Zeilen 38–42: eine Meldung für einen Patienten, der bereits einen Termin hat;
  • Zeilen 59–96: eine Zeile pro Zeitraum. [{{else if patient}}] listet die Zustände der Reihe nach auf: frei, gebucht mit sichtbarem Namen, gebucht ohne Namen („Belegt“);
  • Zeile 80: „Buchen“ ist ein Link;
  • Zeilen 86–92: „Stornieren“ ist ein POST-Formular mit Bestätigung. In der Schleife verweist [@root.doctorId] auf das Feld im Template der Seite, nicht auf das der Zeile;
  • Zeilen 108–110: das Reservierungsfenster, falls der Controller es vorbereitet hat.

11.15.2.3. views/persons/list.hbs

{{!--
  ==========================================================================
  views/persons/list.hbs - die Liste der Ärzte ODER der Clients (ADMIN).
  Eine einzige View für beide: die jeweils spezifischen Beschriftungen kommen in
  [keys] an (siehe DoctorsController / ClientsController).
  ==========================================================================
--}}
<div class="d-flex justify-content-between align-items-center mb-3">
  <h4 class="mb-0">{{t keys.title}}</h4>
  <a class="btn btn-primary" href="{{addUrl}}">{{t keys.add}}</a>
</div>

<div class="card p-3">
  {{#if persons.length}}
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{{t 'PERSONS.COLUMN_TITLE'}}</th>
          <th>{{t 'PERSONS.COLUMN_FIRSTNAME'}}</th>
          <th>{{t 'PERSONS.COLUMN_LASTNAME'}}</th>
          <th>{{t 'PERSONS.COLUMN_LOGIN'}}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {{#each persons}}
          <tr>
            <td>{{title}}</td>
            <td>{{firstName}}</td>
            <td>{{lastName}}</td>
            <td><code>{{login}}</code></td>
            <td class="text-end">
              <div class="d-inline-flex gap-2">
                <a class="btn btn-sm btn-outline-primary" href="{{editUrl}}">{{t 'PERSONS.EDIT'}}</a>
                {{!-- data-confirmation: ein Bestätigungsdialog wird sich öffnen,
                     bevor das Formular gesendet wird (siehe public/js/app.js) --}}
                <form method="post" action="{{deleteUrl}}" class="m-0"
                      data-confirmation="{{t @root.keys.confirmDelete}}">
                  <button type="submit" class="btn btn-sm btn-outline-danger">{{t 'PERSONS.DELETE'}}</button>
                </form>
              </div>
            </td>
          </tr>
        {{/each}}
      </tbody>
    </table>
  {{else}}
    <p class="text-muted mb-0">{{t keys.empty}}</p>
  {{/if}}
</div>

Eine einzige View für Ärzte und Kunden: Die Texte werden als Schlüssel bereitgestellt ([keys.title], [keys.add]...). Zeile 38: [@root.keys] ist in der Schleife erforderlich.

11.15.2.4. views/persons/form.hbs

{{!--
  ==========================================================================
  views/persons/form.hbs - Erstellung ODER Änderung eines Arztes
  oder eines Clients (ADMIN). [creating] unterscheidet die beiden Fälle.

  Wird die Eingabe abgelehnt (leeres Feld, Login bereits vergeben...), sendet
  der Controller DIESE View zurück mit:
    - den bereits eingegebenen Werten (values.xxx);
    - den fehlerhaften Feldern mit rotem Rahmen (invalidFields.xxx, Bootstrap-Klasse
      "is-invalid");
    - unter einem von der Validierung abgelehnten Feld seiner Meldung (errors.xxx);
    - der Fehlermeldung der Seite (error), die vom Layout AM ENDE der Seite
      angezeigt wird (siehe views/partials/errors.hbs).
  ==========================================================================
--}}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-3">{{t pageTitle}}</h5>

      {{!-- novalidate: wir überlassen die Validierung dem SERVER (er hat das
           letzte Wort); die Prüfungen des Browsers (required...) sind nur ein
           Komfort, den ein Benutzer immer umgehen kann --}}
      <form method="post" action="{{action}}" novalidate>
        {{#unless creating}}
          <input type="hidden" name="version" value="{{values.version}}">
        {{/unless}}

        {{!-- Anrede, Vorname, Nachname: Partial, das drei Formularen gemeinsam ist --}}
        {{> personFields}}

        <h6 class="mt-4 text-muted">{{t 'PERSONS.ACCOUNT_SECTION'}}</h6>

        <div class="mb-3">
          <label class="form-label" for="login">{{t 'PERSONS.LOGIN_LABEL'}}</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="off"
                 class="form-control {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
          {{#if errors.login}}
            <div class="invalid-feedback">{{t errors.login}}</div>
          {{else}}
            <div class="form-text">{{#if creating}}{{t 'PERSONS.LOGIN_HELP_CREATE'}}{{else}}{{t 'PERSONS.LOGIN_HELP_EDIT'}}{{/if}}</div>
          {{/if}}
        </div>

        <div class="mb-4">
          <label class="form-label" for="password">{{t 'PERSONS.PASSWORD_LABEL'}}</label>
          {{!-- nie vorausgefüllt: das Passwort geht nie an den Browser zurück --}}
          <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                 class="form-control {{#if invalidFields.password}}is-invalid{{/if}}">
          {{#if errors.password}}
            <div class="invalid-feedback">{{t errors.password}}</div>
          {{else}}
            <div class="form-text">{{#if creating}}{{t 'PERSONS.PASSWORD_HELP_CREATE'}}{{else}}{{t 'PERSONS.PASSWORD_HELP_EDIT'}}{{/if}}</div>
          {{/if}}
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">{{t 'PERSONS.SAVE'}}</button>
          <a class="btn btn-secondary" href="{{listUrl}}">{{t 'PERSONS.BACK'}}</a>
        </div>
      </form>
    </div>
  </div>
</div>
  • Zeile 24: Die Absendeadresse ([action]) wird vom Controller bereitgestellt. [novalidate]: Der Server übernimmt die Validierung.
  • Zeilen 25–27: die Versionsnummer, für eine Änderung;
  • Zeile 30: die Identitätsfelder;
  • Zeilen 35–42: der Login, mit einem Hilfetext oder einer Fehlermeldung;
  • Zeilen 46–54: das Passwort, das nie vorausgefüllt wird.

11.15.2.5. views/account/registration.hbs

{{!--
  ==========================================================================
  views/account/registration.hbs - "Create a patient account" (öffentliche Seite,
  siehe RegistrationController). Gleiche Identitätsfelder wie beim Formular
  des ADMIN (Partial personFields), aber Login und Passwort sind
  erforderlich, mit Bestätigung.
  Hier KEIN Captcha: diese Seite ist nur erreichbar, nachdem das
  der Authentifizierungsseite eingegeben wurde (Schaltfläche "Create a patient account").
  "Back to login" führt zur Authentifizierungsseite zurück.
  ==========================================================================
--}}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-1">{{t 'REGISTRATION.TITLE'}}</h5>
      <p class="text-muted small mb-3">{{t 'REGISTRATION.INTRO'}}</p>

      <form method="post" action="/register" novalidate>
        {{> personFields}}

        <h6 class="mt-4 text-muted">{{t 'PERSONS.ACCOUNT_SECTION'}}</h6>

        <div class="mb-3">
          <label class="form-label" for="login">{{t 'PERSONS.LOGIN_LABEL'}}</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
          {{#if errors.login}}
            <div class="invalid-feedback">{{t errors.login}}</div>
          {{else}}
            <div class="form-text">{{t 'REGISTRATION.LOGIN_HELP'}}</div>
          {{/if}}
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password">{{t 'PERSONS.PASSWORD_LABEL'}}</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control {{#if invalidFields.password}}is-invalid{{/if}}">
            {{#if errors.password}}
              <div class="invalid-feedback">{{t errors.password min=passwordMin}}</div>
            {{else}}
              <div class="form-text">{{t 'REGISTRATION.PASSWORD_HELP' min=passwordMin}}</div>
            {{/if}}
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation">{{t 'ACCOUNT.CONFIRMATION_LABEL'}}</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control {{#if invalidFields.confirmation}}is-invalid{{/if}}">
            {{#if errors.confirmation}}<div class="invalid-feedback">{{t errors.confirmation}}</div>{{/if}}
          </div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">{{t 'REGISTRATION.SUBMIT'}}</button>
          <a class="btn btn-secondary" href="/login">{{t 'REGISTRATION.BACK_TO_LOGIN'}}</a>
        </div>
      </form>
    </div>
  </div>
</div>

Kontoerstellung. Zeile 42: Der Hilfetext hat einen Parameter, die minimale Passwortlänge, der vom Controller bereitgestellt wird.

11.15.2.6. views/patient/area.hbs

{{!--
  ==========================================================================
  views/patient/area.hbs - "My area": die Startseite des Patienten
  (Rolle USER), die direkt nach dem Login angezeigt wird (siehe PatientAreaController).
    - zwei Optionen: [Manage my account] und [View a schedule];
    - sein bevorstehender Termin, falls vorhanden, mit der Möglichkeit, ihn zu stornieren.
  ==========================================================================
--}}
<h4 class="mb-3">{{t 'AREA.HELLO' name=patient}}</h4>

<div class="row g-3 mb-4">
  <div class="col-sm-6">
    <a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
      <h5 class="mb-1">{{t 'AREA.MANAGE_ACCOUNT'}}</h5>
      <span class="text-muted">{{t 'AREA.MANAGE_ACCOUNT_HELP'}}</span>
    </a>
  </div>
  <div class="col-sm-6">
    <a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
      <h5 class="mb-1">{{t 'AREA.VIEW_SCHEDULE'}}</h5>
      <span class="text-muted">{{t 'AREA.VIEW_SCHEDULE_HELP'}}</span>
    </a>
  </div>
</div>

<div class="card p-3">
  <h5>{{t 'AREA.MY_APPOINTMENT'}}</h5>
  {{#if appointments.length}}
    {{!-- normalerweise nur einer (Regel "ein bevorstehender Termin zur Zeit"),
         aber die Seite kann mehrere anzeigen --}}
    {{#each appointments}}
      <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 {{#unless @last}}border-bottom{{/unless}}">
        <div>
          <div class="fw-semibold">{{day}}, {{time}}</div>
          <div class="text-muted">{{doctor}} - <a href="{{scheduleUrl}}">{{t 'AREA.SEE_IN_SCHEDULE'}}</a></div>
        </div>
        <form method="post" action="/my-area/cancel" class="m-0"
              data-confirmation="{{t 'SCHEDULE.CANCEL_CONFIRM'}}">
          <input type="hidden" name="appointmentId" value="{{id}}">
          <button type="submit" class="btn btn-outline-danger">{{t 'AREA.CANCEL_APPOINTMENT'}}</button>
        </form>
      </div>
    {{/each}}
  {{else}}
    <p class="text-muted mb-0">{{t 'AREA.NO_APPOINTMENT'}}</p>
  {{/if}}
</div>
  • Zeile 9: „Hallo Herr Jean MARTIN“;
  • Zeilen 13–19: die beiden Optionen, Links;
  • Zeilen 31–43: der bevorstehende Termin. [{{#unless @last}}]: Ein Rahmen trennt die Termine, außer nach dem letzten.

11.15.2.7. views/patient/account.hbs

{{!--
  ==========================================================================
  views/patient/account.hbs - "Manage my account" (Rolle USER).
  Zwei unabhängige Formulare auf derselben Seite:
    1. die Änderung (Identität, Login, optionales neues Passwort);
    2. das Löschen des Kontos - wodurch auch seine Termine storniert werden.
  Beide erfordern das AKTUELLE Passwort.
  ==========================================================================
--}}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    {{!-- 1. Änderung --}}
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3">{{t 'MY_ACCOUNT.TITLE'}}</h5>

      <form method="post" action="/my-account" novalidate>
        <input type="hidden" name="version" value="{{values.version}}">

        {{> personFields}}

        <h6 class="mt-4 text-muted">{{t 'PERSONS.ACCOUNT_SECTION'}}</h6>

        <div class="mb-3">
          <label class="form-label" for="login">{{t 'PERSONS.LOGIN_LABEL'}}</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
          {{#if errors.login}}<div class="invalid-feedback">{{t errors.login}}</div>{{/if}}
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password">{{t 'MY_ACCOUNT.NEW_PASSWORD_LABEL'}}</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control {{#if invalidFields.password}}is-invalid{{/if}}">
            {{#if errors.password}}
              <div class="invalid-feedback">{{t errors.password min=passwordMin}}</div>
            {{else}}
              <div class="form-text">{{t 'PERSONS.PASSWORD_HELP_EDIT'}}</div>
            {{/if}}
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation">{{t 'ACCOUNT.CONFIRMATION_LABEL'}}</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control {{#if invalidFields.confirmation}}is-invalid{{/if}}">
            {{#if errors.confirmation}}<div class="invalid-feedback">{{t errors.confirmation}}</div>{{/if}}
          </div>
        </div>

        <div class="mb-4">
          <label class="form-label" for="currentPassword">{{t 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL'}}</label>
          <input id="currentPassword" name="currentPassword" type="password" maxlength="72" autocomplete="current-password" required
                 class="form-control {{#if invalidFields.currentPassword}}is-invalid{{/if}}">
          {{#if errors.currentPassword}}
            <div class="invalid-feedback">{{t errors.currentPassword}}</div>
          {{else}}
            <div class="form-text">{{t 'MY_ACCOUNT.CURRENT_PASSWORD_HELP'}}</div>
          {{/if}}
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">{{t 'PERSONS.SAVE'}}</button>
          <a class="btn btn-secondary" href="/my-area">{{t 'MY_ACCOUNT.BACK'}}</a>
        </div>
      </form>
    </div>

    {{!-- 2. Löschen --}}
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">{{t 'MY_ACCOUNT.DELETE_TITLE'}}</h5>
      <p class="text-muted small">{{t 'MY_ACCOUNT.DELETE_HELP'}}</p>
      <form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
            data-confirmation="{{t 'MY_ACCOUNT.DELETE_CONFIRM'}}">
        <div class="flex-grow-1">
          <label class="form-label" for="deletePassword">{{t 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL'}}</label>
          <input id="deletePassword" name="deletePassword" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger">{{t 'MY_ACCOUNT.DELETE_SUBMIT'}}</button>
      </form>
    </div>

  </div>
</div>
  • Zeilen 17–65: die Änderung des Kontos;
  • Zeilen 72–80: das Löschen, mit Bestätigung. Zwei voneinander unabhängige Formulare auf derselben Seite: Jedes sendet nur seine eigenen Felder.

11.15.2.8. views/error.hbs

{{!--
  views/error.hbs - die Fehlerseite (403, 404, 400, 500), erstellt durch
  HtmlExceptionFilter (src/web/html-exception.filter.ts).
--}}
<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">{{t message}}</p>
      <div><a class="btn btn-primary" href="/">{{t 'ERROR_PAGE.BACK'}}</a></div>
    </div>
  </div>
</div>

Die Fehlerseite des Exception-Filters: der HTTP-Code und die übersetzte Meldung.

11.16. Die Wörterbücher

11.16.1. i18n/fr.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {name} a été ajouté (login : {login}).",
    "UPDATED": "Le médecin {name} a été modifié.",
    "DELETED": "Le médecin {name} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {name} a été ajouté (login : {login}).",
    "UPDATED": "Le client {name} a été modifié.",
    "DELETED": "Le client {name} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {min} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {name}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
  • Die Abschnitte gruppieren die Texte nach Seiten ([LOGIN], [SCHEDULE], [AREA]...) oder nach Themen ([ERRORS], [CONFIRMATION]);
  • Zeile 80: ein Text mit zwei Parametern, [{name}] und [{login}];
  • Zeilen 98–137: Fehlermeldungen. Dies sind die Schlüssel, die von der [BusinessException] in der Geschäftsschicht, von den Validierungsdekoratoren der Formulare und vom Exception-Filter verwendet werden.

11.16.2. i18n/en.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {name} has been added (login: {login}).",
    "UPDATED": "Doctor {name} has been updated.",
    "DELETED": "Doctor {name} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {name} has been added (login: {login}).",
    "UPDATED": "Patient {name} has been updated.",
    "DELETED": "Patient {name} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_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).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\"."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {min} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {name}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

Das englische Wörterbuch hat exakt dieselben Schlüssel.

11.17. Statische Dateien

11.17.1. public/css/styles.css

/* =========================================================================
   public/css/styles.css - einige Einstellungen zusätzlich zu Bootstrap
   (übernommen aus src/styles.css des Angular-Clients).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-zone: die Fehlermeldungen, am Seitenende, auf hellrosa Hintergrund
   (siehe views/partials/errors.hbs).
   position: sticky + bottom: ist die Seite höher als das Fenster (ein
   Terminkalender mit 12 Zeitfenstern zum Beispiel), bleibt die Zone am unteren Rand des
   Fensters haften, statt unterhalb des sichtbaren Bereichs zu verschwinden - ohne jemals
   den Inhalt zu verdecken, wenn die Seite kurz ist.
   z-index: oberhalb des grauen Hintergrunds 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 „My area“ des Patienten */
.option-card {
  transition: border-color 0.15s, box-shadow 0.15s;
}

.option-card:hover {
  border-color: #0d6efd;
  box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}

/* das CAPTCHA-Bild (SVG mit 150 x 50 Pixeln) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • Zeilen 10–12: Ein buchbarer Zeitraum ändert beim Überfahren mit der Maus die Farbe;
  • Zeilen 23–33: der Fehlerbereich auf hellrosa Hintergrund. [position: sticky] und [bottom: 1rem]: Ist die Seite höher als das Fenster, bleibt der Bereich am unteren Rand des Fensters, statt vom Bildschirm zu verschwinden; [z-index] legt ihn über den grauen Hintergrund modaler Fenster;
  • Zeilen 36–43: Die beiden Optionen von „Mein Bereich“ reagieren auf das Überfahren mit der Maus;
  • Zeilen 46–50: der Rahmen des CAPTCHA-Bilds.

11.17.2. public/js/app.js

// =========================================================================
// public/js/app.js - das EINZIGE JavaScript der Anwendung.
// -------------------------------------------------------------------------
// Die ganze Anwendung funktioniert ohne JavaScript. Dieses Skript fügt eine
// Komfortfunktion hinzu: Vor dem Senden eines Formulars mit dem Attribut
// data-confirmation="..." fragt ein modaler Dialog „Are you sure?“
// (der Dialog selbst steht in der Seite: views/partials/confirmation.hbs).
// Ist JavaScript deaktiviert, wird das Formular einfach ohne
// Bestätigung gesendet - nichts geht kaputt (Prinzip „Progressive Enhancement“).
//
// Warum nicht window.confirm()? Sein Fenster 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, an das 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ätigungsabfrage
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // Klick auf den grauen Hintergrund, außerhalb des Dialogs
    }
  });

  // 3. Tastatur: Escape schließt den Dialog; Tab bleibt INNERHALB des Dialogs
  //    (sonst würde der Fokus auf die ausgegraute Seite dahinter gehen)
  modal.addEventListener('keydown', (event) => {
    if (event.key === 'Escape') {
      close();
    } else if (event.key === 'Tab') {
      const buttons = [...modal.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  });
})();

Das vollständige Skript für das Bestätigungsfenster aus Beispiel 21:

  • Zeilen 17–19: Eine Seite ohne Bestätigungsfenster hat nichts zu tun;
  • Zeile 24: das Element, das vor dem Öffnen des Fensters den Tastaturfokus hatte und auf das der Fokus beim Schließen des Fensters zurückgesetzt wird;
  • Zeilen 26–35: Der Fokus wird auf „Nein, zurück“ gesetzt; ein versehentliches Drücken der Eingabetaste löscht nichts;
  • Zeilen 37–43: Das Fenster wird ausgeblendet, und der Fokus wird wiederhergestellt;
  • Zeilen 54–67: „Ja“, „Nein“, die Schließen-Schaltfläche und der Klick außerhalb des Fensters. [closest('[data-action]')] findet das Element, das das Attribut enthält, auch wenn auf ein darin liegendes Element geklickt wurde;
  • Zeilen 71–86: Die Esc-Taste schließt das Fenster; die Tab-Taste lässt den Fokus innerhalb des Fensters kreisen, statt ihn auf die ausgegraute Seite dahinter wandern zu lassen.