Skip to content

11. Caso de estudio: la aplicación RdvMedecins

11.1. El problema

La aplicación RdvMedecins gestiona las citas de un consultorio médico. Cada médico tiene franjas horarias (de 8:00 a 12:00, por ejemplo, en intervalos de 20 minutos); una cita consta de un día, una franja horaria y un cliente (un paciente). Es la implementación exacta, en [ASP.NET Core MVC], de la aplicación [NestJS] de la lección anterior: la misma base de datos, las mismas reglas de negocio, las mismas páginas, los mismos diccionarios de traducción. El servidor genera las páginas HTML mediante vistas [Razor].

Tres roles de usuario comparten la aplicación:

Rol
Quién
Qué puede hacer
ADMIN
El administrador ([admin])
Ver las agendas, hacer y cancelar citas para cualquier paciente; gestionar (listar, agregar, editar, eliminar) médicos y clientes
DOCTOR
Médicos
Ver las agendas, hacer citas y cancelarlas para cualquier paciente
USER
Clientes (pacientes)
Ver las agendas sin ver los nombres de otros pacientes; reservar una cita para sí mismos; cancelar su cita; gestionar su cuenta; crear una cuenta

Principales reglas de gestión:

  • no se permiten citas en el pasado;
  • una franja horaria solo puede reservarse una vez por día;
  • un paciente solo puede tener una cita próxima a la vez;
  • dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido, y un login pertenece a una sola cuenta;
  • un médico con citas no puede eliminarse; un cliente se elimina junto con sus citas;
  • la página de inicio de sesión está protegida contra bots (CAPTCHA, intentos limitados) y la creación de una cuenta de cliente exige resolver primero el CAPTCHA de esa página.

11.2. Uso de la aplicación

11.2.1. La página de inicio de sesión

Image

La página presenta dos botones: Iniciar sesión y Crear una cuenta de paciente. Ambos exigen ingresar los caracteres que se muestran en la imagen. Los botones FR / EN cambian el idioma:

Image

Un error (en este caso, un CAPTCHA ingresado incorrectamente) se muestra al pie de la página sobre un fondo rosa claro:

Image

11.2.2. El calendario, visto por el administrador y los médicos

Una vez iniciada la sesión, el administrador llega a la página del calendario. Selecciona un médico y un día:

Image

Image

Cada franja horaria está disponible (botón Reservar) u ocupada (nombre del paciente, botón Cancelar). Al hacer clic en Reservar se abre una ventana que solicita los datos del paciente:

Image

Al hacer clic en “Cancelar” se solicita una confirmación (aquí, por parte del Dr. Pélissier, cuya barra de navegación no incluye los menús de administración):

Image

11.2.3. El panel del paciente

Un paciente (rol USER) llega a Mi área: su próxima cita, que puede cancelar, y enlaces a la gestión de su cuenta y al calendario:

Image

En el calendario ve su propia cita, pero no los nombres de los demás pacientes. Como ya tiene una cita próxima, no puede programar otra:

Image

Un paciente sin cita puede reservar para sí mismo una franja horaria disponible:

Image

Gestión de la cuenta: modificar los datos personales, cambiar la contraseña o eliminar la cuenta (y sus citas). Se requiere la contraseña actual para cualquier cambio:

Image

Un paciente que intenta abrir una página reservada para el administrador recibe una página de error:

Image

11.2.4. Gestión de médicos y clientes

El administrador tiene dos menús adicionales, “Médicos” y “Pacientes”:

Image

Image

El formulario para agregar un médico, enviado con errores:

Image

Un nombre que coincide con el de un médico existente se rechaza:

Image

La eliminación de un cliente requiere confirmación:

Image

11.2.5. Creación de una cuenta de cliente

Desde la página de inicio de sesión, el botón "Crear una cuenta de paciente" solo abre el formulario si el CAPTCHA se ha ingresado correctamente:

Image

Image

11.3. Instalación y ejecución

Los pasos de instalación se presentaron al comienzo de este documento (en la sección “Ejecución del caso de estudio” de la introducción): crear la base de datos mediante el script SQL, verificar la cadena de conexión en [appsettings.json] y luego ejecutar [dotnet run] en la carpeta de la aplicación. La carpeta de la aplicación:

rdvmedecins2-aspnetcore-mvc/
├── Auth/
│   ├── AttemptLimiterService.cs
│   ├── AuthService.cs
│   ├── CaptchaService.cs
│   ├── ConnectedUser.cs
│   ├── InvalidSessionException.cs
│   ├── JwtAuthentication.cs
│   ├── README.md
│   └── RegistrationPassService.cs
├── Business/
│   ├── BusinessException.cs
│   ├── BusinessService.cs
│   ├── Dates.cs
│   ├── IBusiness.cs
│   └── README.md
├── Config/
│   ├── AuthOptions.cs
│   ├── ProtectionOptions.cs
│   └── README.md
├── Controllers/
│   ├── AuthController.cs
│   ├── ClientsController.cs
│   ├── DoctorsController.cs
│   ├── ErrorController.cs
│   ├── LanguageController.cs
│   ├── PatientAreaController.cs
│   ├── PersonsControllerBase.cs
│   ├── README.md
│   ├── RegistrationController.cs
│   └── ScheduleController.cs
├── Data/
│   ├── RdvMedecinsDbContext.cs
│   └── README.md
├── database/
│   ├── dbrdvmedecins2.sql
│   └── README.md
├── Domain/
│   ├── DoctorDaySchedule.cs
│   ├── DoctorDaySlot.cs
│   └── README.md
├── Entities/
│   ├── AbstractEntity.cs
│   ├── Appointment.cs
│   ├── Client.cs
│   ├── Doctor.cs
│   ├── Person.cs
│   ├── README.md
│   ├── Role.cs
│   ├── Slot.cs
│   └── User.cs
├── i18n/
│   ├── en.json
│   └── fr.json
├── Models/
│   ├── Forms.cs
│   ├── README.md
│   └── ViewModels.cs
├── Properties/
│   └── launchSettings.json
├── Repositories/
│   ├── AppointmentRepository.cs
│   ├── PersonRepository.cs
│   ├── README.md
│   ├── SlotRepository.cs
│   └── UserRepository.cs
├── Views/
│   ├── Auth/
│   │   ├── _Captcha.cshtml
│   │   └── Login.cshtml
│   ├── PatientArea/
│   │   ├── Account.cshtml
│   │   └── Area.cshtml
│   ├── Persons/
│   │   ├── Form.cshtml
│   │   └── List.cshtml
│   ├── Registration/
│   │   └── Registration.cshtml
│   ├── Schedule/
│   │   ├── _Booking.cshtml
│   │   └── Schedule.cshtml
│   ├── Shared/
│   │   ├── _Confirmation.cshtml
│   │   ├── _Errors.cshtml
│   │   ├── _Flash.cshtml
│   │   ├── _Layout.cshtml
│   │   ├── _Navbar.cshtml
│   │   ├── _PersonFields.cshtml
│   │   └── Error.cshtml
│   ├── _ViewImports.cshtml
│   ├── _ViewStart.cshtml
│   └── README.md
├── Web/
│   ├── ApplicationModel.cs
│   ├── Flash.cs
│   ├── HtmlExceptionFilter.cs
│   ├── README.md
│   ├── Translator.cs
│   ├── Utils.cs
│   ├── Validation.cs
│   └── ViewPage.cs
├── wwwroot/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── app.js
│   └── lib/
│       └── bootstrap/
│           ├── css/
│           │   └── bootstrap.min.css
│           └── LICENSE
├── .gitignore
├── appsettings.Development.json
├── appsettings.json
├── Program.cs
├── RdvMedecins.csproj
└── README.md

Cada carpeta contiene un archivo llamado [README.md] que enumera sus archivos. La consola al iniciar:

dotnet run
Using launch settings from Properties/launchSettings.json...
Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:8081
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\course\rdvmedecins2-aspnetcore-mvc

En modo de desarrollo (vea [Properties/launchSettings.json]), la consola también muestra cada comando SQL que EF Core envía a la base de datos. También puede:

  • iniciar la aplicación con [dotnet watch]: se recompila y se reinicia cada vez que se modifica un archivo;
  • depurarla paso a paso en [Visual Studio Code]: con la extensión [C# Dev Kit], la tecla F5 inicia la aplicación bajo el control del depurador; se establece un punto de interrupción con un solo clic en el margen de una línea de código.

11.4. La arquitectura de la aplicación

Image

  • [Program.cs] configura la aplicación: servicios (inyección de dependencias), middleware (archivos estáticos, páginas de error, idioma, autenticación), controladores;
  • [Auth]: inicio de sesión, tokens JWT, roles, CAPTCHA y límite de intentos;
  • [Controllers]: controladores de la capa web. Todos pasan por un único servicio, [ApplicationModel] (carpeta [Web]), que almacena en memoria las listas de médicos y clientes y transmite las demás solicitudes a la capa de negocio;
  • [Web]: elementos comunes de la capa web: traducción, mensajes flash, validación, clase padre de las vistas, filtro de excepciones; [Models]: modelos de formularios y de vistas;
  • [Business]: reglas de negocio;
  • [Repositories]: la capa DAO, una clase por tabla; [Data]: la capa [DbContext] de EF Core;
  • [Entities]: las entidades de EF Core; [Domain]: los objetos del calendario, calculados por la capa de negocio;
  • [Views]: las vistas [Razor]; [i18n]: los diccionarios; [wwwroot]: la hoja de estilos, el script de la página y [Bootstrap].

A continuación se comentan todos los archivos, desde las capas inferiores (base de datos) hasta las superiores (vistas).

11.5. La base de datos

La base de datos [dbrdvmedecins2] se crea mediante el script [database/dbrdvmedecins2.sql], que se ejecuta del mismo modo que en el ejemplo 28 (la herramienta [HeidiSQL] de [Laragon], o el comando [mysql -u root < database/dbrdvmedecins2.sql]). Es, palabra por palabra, el script de la aplicación [NestJS]: ambas aplicaciones pueden trabajar sobre la misma base de datos y una puede reemplazar a la otra sin hacer ningún cambio.

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Base de datos [dbrdvmedecins2] - MySQL 8
--
-- Evolución de [dbrdvmedecins]:
--   1. las tablas [doctors] y [clients] reciben una columna [user],
--      clave externa hacia users(id): cada médico y cada cliente es
--      ahora también un usuario que puede iniciar sesión;
--   2. aparece un tercer rol: DOCTOR (además de ADMIN y USER);
--   3. el script crea una fila en [users] para cada médico (rol DOCTOR)
--      y para cada cliente (rol USER):
--        - login          = apellido en minúsculas
--        - contraseña     = apellido en minúsculas, con hash bcrypt (10 rondas)
--        - nombre mostrado = nombre + apellido
--
--   4. restricciones de unicidad, todas con NOMBRE (la aplicación reconoce
--      el nombre de la restricción violada en el mensaje de error de MySQL):
--        - unq_users_login                   : un login pertenece a una sola cuenta;
--        - unq_doctors_first_name_last_name  : dos médicos no pueden tener los
--                                              mismos nombres y apellidos;
--        - unq_clients_first_name_last_name  : lo mismo para los clientes.
--      Atención: la collation utf8mb4_unicode_ci compara sin distinguir
--      mayúsculas ni acentos - "Hélène DUPONT" y "helene dupont"
--      se consideran, por tanto, idénticos.
--
-- La tabla [users] ahora debe crearse ANTES que [doctors] y [clients]
-- (porque las referencian) y eliminarse DESPUÉS de ellas.
-- =========================================================================

-- partimos de una base de datos vacía en cada ejecución del script (práctico en desarrollo)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- orden de eliminación: de las tablas "hijas" a las tablas "padre"
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;

-- -------------------------------------------------------------------------
-- tabla [users]: los usuarios autorizados para iniciar sesión en la aplicación
-- -------------------------------------------------------------------------
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'
  -- un login solo puede pertenecer a una cuenta
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- tabla [doctors]: los médicos del consultorio
-- -------------------------------------------------------------------------
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),
  -- una cuenta por médico, y un médico por cuenta
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- dos médicos no pueden tener los mismos nombres y apellidos
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabla [clients]: los pacientes de los médicos
-- -------------------------------------------------------------------------
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),
  -- una cuenta por cliente, y un cliente por cuenta
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- dos clientes no pueden tener los mismos nombres y apellidos
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabla [slots]: los horarios de cada médico
-- -------------------------------------------------------------------------
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)
);

-- -------------------------------------------------------------------------
-- tabla [appointments]: las citas reservadas por los clientes
-- -------------------------------------------------------------------------
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),
  -- el mismo horario, en el mismo día, solo puede reservarse una vez
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

-- =========================================================================
-- Datos de demostración
-- =========================================================================

-- los usuarios: contraseñas con hash bcrypt (10 rondas de salt)
--   admin/admin (ADMIN)
--   una cuenta DOCTOR por médico, una cuenta USER por cliente
--   (la cuenta de demostración user/user ya no existe: una cuenta USER es
--   ahora SIEMPRE la cuenta de un cliente, que puede reservar y gestionar la cuenta)
--   (login = contraseña = apellido en minúsculas)
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');

-- los médicos: la columna [user] se busca a partir del login,
-- en lugar de suponer los valores de las claves primarias de [users]
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'));

-- horarios del médico PELISSIER (doctor_id = 1): de 8:00 a 12:00 en intervalos de 20 minutos
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);

-- horarios del médico TATOU (doctor_id = 2): de 14:00 a 18:00 en intervalos de 20 minutos
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);

-- una cita ya reservada, para ver de inmediato un horario ocupado en la agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);

Repasemos este script:

  • línea 30: la base de datos se crea si aún no existe, con el conjunto de caracteres [utf8mb4] y la intercalación [utf8mb4_unicode_ci], como en el ejemplo 28: las comparaciones de cadenas no distinguen mayúsculas ni acentos. Esto también se aplica a las restricciones de unicidad: [Hélène DUPONT] y [helene dupont] son, para [MySQL], dos instancias de la misma persona;
  • líneas 34–38: el script parte de una base de datos vacía en cada ejecución. Las tablas se eliminan de las tablas “hijas” a las tablas “padre”: una tabla referenciada por una clave externa ([users], por ejemplo, referenciada por [doctors] y [clients]) no puede eliminarse mientras otra tabla aún la referencie. Las tablas se crean en el orden inverso;
  • líneas 43–52: las cuentas de usuario. Cada tabla comienza con una clave primaria [id], asignada por la base de datos ([AUTO_INCREMENT]), y una columna [version], que vale 0 cuando se crea la fila;
  • líneas 46–49: el login, la contraseña, el nombre que se muestra tras iniciar sesión y el rol ([ADMIN], [DOCTOR] o [USER]). La columna [password] nunca contiene la contraseña en sí, sino su hash [bcrypt] (vea el ejemplo 25): 60 caracteres, de ahí el ancho de la columna;
  • línea 51: un login pertenece a una sola cuenta. Como en el ejemplo 28, la restricción tiene nombre: cuando [MySQL] rechaza una operación de escritura, su mensaje de error especifica el nombre de la restricción violada y la capa de negocio lo usa para elegir el mensaje que se muestra (vea [Business/BusinessService.cs]);
  • líneas 57–69: médicos: título, apellido, nombre;
  • línea 59: la columna [version] se usa para el bloqueo optimista (vea el ejemplo 28): se incrementa cada vez que se modifica la fila, lo que permite detectar si otro usuario ha modificado la fila entre el momento en que se leyó y el momento en que se escribió. Como en el ejemplo 28, la aplicación incrementa este valor (vea [DbContext], más adelante);
  • líneas 63–64: cada médico tiene una cuenta: la columna [user] es una clave externa que referencia a [users(id)]. La base de datos rechaza un valor que no se refiera a ninguna cuenta y se niega a eliminar una cuenta que aún esté referenciada por un médico. Como [user] es una palabra reservada en [MySQL], el nombre de la columna se encierra entre acentos graves;
  • línea 66: una cuenta pertenece a un solo médico: la relación entre [doctors] y [users] es una relación “uno a uno”;
  • línea 68: dos médicos no pueden tener el mismo nombre y apellido. La restricción se aplica al par de columnas: dos médicos pueden tener el mismo apellido si no tienen el mismo nombre;
  • líneas 74–86: los clientes (pacientes), con el mismo esquema: una cuenta por cliente (clave externa [fk_clients_user], restricción de unicidad [unq_clients_user]); no puede haber dos clientes con el mismo nombre y apellido;
  • líneas 91–100: las franjas horarias de cada médico (clave externa [doctor_id]): hora y minuto de inicio, hora y minuto de fin. Una franja horaria no tiene fecha; se repite todos los días;
  • líneas 105–115: las citas: una fecha (tipo [DATE], sin hora), una franja horaria y un cliente, identificados mediante dos claves externas;
  • línea 114: la misma franja horaria solo puede reservarse una vez por día. La propia base de datos impone esta regla: si dos usuarios reservan la misma franja horaria al mismo tiempo, el segundo [INSERT] se rechaza, sin importar lo que la aplicación haya verificado justo antes;
  • líneas 127–137: cuentas de demostración: el administrador, tres médicos (rol [DOCTOR]) y cuatro clientes (rol [USER]). La contraseña de cada usuario es su login ([admin] / [admin], [pelissier] / [pelissier]...). Los hashes comienzan con [$2b$10$]: el algoritmo [bcrypt], con un costo de 10 (vea el ejemplo 25); la biblioteca [BCrypt.Net-Next] de la aplicación sabe verificarlos;
  • líneas 141–144: la columna [user] de cada médico se obtiene mediante una subconsulta sobre el login, en lugar de suponer los identificadores que la base de datos asignó a las cuentas;
  • líneas 146–150: los clientes se tratan del mismo modo;
  • líneas 153–157: doce franjas horarias de 20 minutos, de 8:00 a 12:00, para el Dr. PELISSIER. Aquí el identificador del médico (1) está escrito directamente en el código: la tabla [doctors] acaba de crearse, por lo que sus identificadores comienzan en 1;
  • líneas 160–164: doce franjas horarias, de 14:00 a 18:00, para el Dr. TATOU. El Dr. DUPONT no tiene franjas horarias: su agenda está vacía;
  • líneas 167–168: ya se ha programado una cita para Brigitte BISTROU (cliente n.º 3) en la segunda franja horaria del Dr. PELISSIER (8:20). [CURDATE()] es la fecha en que se ejecuta el script: al primer inicio de sesión, el calendario de hoy muestra una franja ya reservada.

11.6. Configuración del proyecto

11.6.1. RdvMedecins.csproj

<!--
  =========================================================================
  RdvMedecins.csproj - el archivo de proyecto (el equivalente de package.json).

  Microsoft.NET.Sdk.Web: el SDK de las aplicaciones ASP.NET Core. Por sí solo
  incluye todo el framework web (MVC, vistas Razor, autenticación,
  localización, archivos estáticos...): abajo solo se listan las bibliotecas
  EXTERNAS al framework (PackageReference), que
  [dotnet restore] / [dotnet build] descargan de nuget.org.
  =========================================================================
-->
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <!-- .NET 10, versión LTS (soporte a largo plazo) -->
    <TargetFramework>net10.0</TargetFramework>
    <!-- tipos de referencia "nullable": el compilador advierte sobre los riesgos de
         NullReferenceException (el equivalente de strictNullChecks en TypeScript) -->
    <Nullable>enable</Nullable>
    <!-- usings implícitos: System, System.Linq, System.Threading.Tasks... -->
    <ImplicitUsings>enable</ImplicitUsings>
    <RootNamespace>RdvMedecins</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <!-- Entity Framework Core + su proveedor para MySQL / MariaDB.
         Pomelo mismo incorpora Microsoft.EntityFrameworkCore (y MySqlConnector,
         el controlador ADO.NET) en la versión que le corresponde. -->
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
    <!-- autenticación con token JWT (lectura y verificación del token) -->
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
    <!-- hash de contraseñas (bcrypt), compatible con los
         hashes $2b$ del script SQL -->
    <PackageReference Include="BCrypt.Net-Next" Version="4.0.3" />
  </ItemGroup>

  <ItemGroup>
    <!-- los diccionarios de traducción se leen al inicio. El SDK Web
         ya incluye todos los archivos .json entre los archivos por publicar (Content):
         solo especificamos que siempre se copien (dotnet publish) -->
    <Content Update="i18n\*.json" CopyToPublishDirectory="PreserveNewest" />
    <!-- el script SQL no necesita publicarse -->
    <Content Remove="database\**" />
    <None Include="database\**" />
  </ItemGroup>

</Project>

Repasemos este archivo:

  • línea 12: el SDK para aplicaciones web, como en todos los ejemplos (vea la introducción);
  • líneas 14–23: los ajustes que los ejemplos tomaban del archivo compartido [examples/Directory.Build.props]: [.NET] 10, tipos de referencia “anulables” (nullable), [using] implícitos. El caso de estudio es un proyecto independiente: escribe él mismo estos ajustes. [RootNamespace] es el espacio de nombres raíz del proyecto, el que [Visual Studio Code] propone para un archivo nuevo;
  • línea 29: el proveedor [MySQL] de EF Core, que incluye EF Core y el controlador [MySqlConnector] (vea el ejemplo 28);
  • líneas 31–34: los dos paquetes de autenticación, ya utilizados en el capítulo 8: verificación de tokens JWT y hash de contraseñas;
  • línea 41: los diccionarios de traducción [i18n/*.json] se leen del disco al iniciar. Al preparar la aplicación para un servidor de producción (comando [dotnet publish]), deben copiarse junto con ella: eso es lo que hace [CopyToPublishDirectory];
  • líneas 43–44: el script SQL no es un archivo de la aplicación; se excluye de los archivos publicados, como se vio en el ejemplo 28.

11.6.2. appsettings.json

El archivo [appsettings.json] cumple la misma función que el archivo [.env] de la aplicación [NestJS]. Una diferencia importante: el archivo [.env] nunca se compartía y un archivo llamado [.env.example] le servía de plantilla. Aquí, [appsettings.json] forma parte del proyecto; los valores específicos de cada máquina (como una contraseña) pueden proporcionarse de otra manera, sin modificarlo (vea más adelante).

// =========================================================================
// appsettings.json - la configuración de la aplicación (el equivalente del
// archivo .env del proyecto NestJS). ASP.NET Core acepta comentarios
// en este archivo JSON.
//
// Los valores sensibles (contraseña de MySQL, secreto JWT) pueden
// reemplazarse sin tocar este archivo: variables de entorno o
// "user secrets" (ver README.md, sección Configuration).
// =========================================================================
{
  // puerto de escucha. El servidor JSON ya escucha en el 8080: elegimos otro
  // puerto para poder ejecutar ambos al mismo tiempo.
  "Urls": "http://localhost:8081",

  // conexión a la base de datos MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql)
  "ConnectionStrings": {
    "RdvMedecins": "Server=localhost;Port=3306;Database=dbrdvmedecins2;User=root;Password=;"
  },
  "MySql": {
    // versión del servidor, para que EF Core genere el dialecto SQL correcto:
    // "8.0.0-mysql" para MySQL 8, "10.11.0-mariadb" para MariaDB 10.11...
    "ServerVersion": "8.0.0-mysql"
  },

  // autenticación (ver Auth/)
  "Auth": {
    // clave secreta de los tokens JWT: al menos 32 caracteres (HMAC-SHA256).
    // Se debe cambiar sin falta en producción (cadena aleatoria larga).
    "JwtSecret": "change-me-to-a-long-random-string",
    // duración de validez de un token, en segundos (7200 s = 2 h); la cookie
    // que lleva el token tiene la misma duración
    "JwtExpiresInSeconds": 7200,
    // true en producción (sitio servido por HTTPS): la cookie de autenticación
    // nunca se envía por una conexión sin cifrar
    "CookieSecure": false
  },

  // protección contra robots (ver Auth/AttemptLimiterService.cs)
  "Protection": {
    // inicio de sesión: fallos permitidos para un mismo login desde la misma dirección IP...
    "LoginMaxFailures": 5,
    // ... antes de un bloqueo de esta duración (toda la dirección IP también se
    // bloquea si acumula 5 veces más fallos, con todos los logins combinados)
    "LoginBlockMinutes": 15,
    // creación de cuentas de cliente: como máximo esta cantidad de cuentas creadas por hora y por
    // dirección IP. En un salón de clases, todas las computadoras suelen salir por la
    // misma dirección: aumente el valor si es necesario.
    "RegistrationMaxPerHour": 10
  },

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Repasemos este archivo:

  • líneas 1–9: a diferencia del JSON estándar, [ASP.NET Core] admite comentarios en sus archivos de configuración;
  • línea 13: la dirección y el puerto de escucha. Los ejemplos escuchaban en el puerto 5000, el puerto predeterminado; la aplicación escucha en el puerto 8081, igual que la versión [NestJS];
  • líneas 16–18: la cadena de conexión a la base de datos [dbrdvmedecins2], con los valores predeterminados de [Laragon] (usuario [root], sin contraseña); vea el ejemplo 28;
  • líneas 19–23: la versión del servidor, que le indica al proveedor [Pomelo] qué dialecto SQL generar (vea el ejemplo 28);
  • líneas 26–36: la sección de autenticación: la clave secreta que firma los tokens (de al menos 32 caracteres; debe reemplazarse en producción), la duración del token (dos horas) y la opción [Secure] de la cookie que lo transporta. En producción, el sitio se sirve mediante HTTPS y la cookie nunca debe viajar por una conexión sin cifrar: la opción se establece en [true];
  • líneas 39–49: umbrales de protección contra bots (vea el ejemplo 27): número de intentos fallidos de inicio de sesión permitidos y duración del bloqueo resultante; número de cuentas de cliente creadas por hora desde la misma dirección IP;
  • líneas 51–57: niveles de registro (vea la introducción). Los mensajes de EF Core solo se muestran a partir del nivel [Warning]: los comandos SQL, que están en el nivel [Information], no aparecen (vea el ejemplo 28);
  • línea 58: se aceptan todos los nombres de dominio.

Las secciones [Auth] y [Protection] se interpretan como clases tipadas (vea [Config/AuthOptions.cs], más adelante). Cada valor se designa por su ruta, con los niveles separados por [:]: [Auth:JwtSecret], [ConnectionStrings:RdvMedecins], [MySql:ServerVersion]. [ASP.NET Core] lee la configuración de varias fuentes sucesivas, cada una de las cuales puede reemplazar los valores de las anteriores: [appsettings.json], luego [appsettings.{environment}.json] (vea el archivo siguiente), luego, en desarrollo, los “secretos de usuario” (valores almacenados fuera del proyecto, en el perfil del usuario), luego las variables de entorno y, por último, los argumentos de la línea de comandos. Así, una contraseña puede proporcionarse mediante una variable de entorno, donde [:] se escribe [__]:

export ConnectionStrings__RdvMedecins="Server=localhost;Port=3306;Database=dbrdvmedecins2;User=root;Password=myPassword;"

El archivo [README.md] de la aplicación detalla estas opciones.

11.6.3. appsettings.Development.json

// Sobrescritura de appsettings.json en desarrollo (ASPNETCORE_ENVIRONMENT=
// Development, ver Properties/launchSettings.json): mostramos en la
// consola las consultas SQL generadas por EF Core, como lo hacía la
// opción logging: true de TypeORM.
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Information"
    }
  }
}
  • línea 10: [ASP.NET Core] conoce el entorno en el que se ejecuta la aplicación: [Development], [Production]... Lo lee de la variable de entorno [ASPNETCORE_ENVIRONMENT] (vea el archivo siguiente); si no existe, usa [Production]. Después de [appsettings.json], lee el archivo [appsettings.{environment}.json], si existe, y combina los dos: las claves presentes en el segundo archivo reemplazan a las del primero, mientras que las demás se conservan. Durante el desarrollo, agregamos entonces el nivel [Information] para la categoría [Microsoft.EntityFrameworkCore.Database.Command]: la regla más específica prevalece sobre la más general de [appsettings.json] ([Warning] para todo [Microsoft.EntityFrameworkCore]), y cada comando SQL enviado a la base de datos se muestra en la consola. Esto equivale a la opción [logging] de [TypeORM], que la versión [NestJS] activaba fuera de producción. Todos los demás valores (conexión, autenticación, etc.) permanecen iguales a los de [appsettings.json].

11.6.4. Properties/launchSettings.json

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:8081",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Este archivo solo lo usan, durante el desarrollo, [dotnet run], [dotnet watch] y [Visual Studio Code]; no se publica. Comentémoslo:

  • líneas 3–4: un perfil de inicio describe una forma de iniciar la aplicación. Aquí solo hay uno; [dotnet run] usa el primero;
  • línea 5: la aplicación se inicia directamente, con su propio servidor web;
  • líneas 6–7: [dotnet run] muestra sus mensajes de compilación y el navegador se abre en la aplicación cuando está lista;
  • línea 8: la dirección de escucha, la misma que la clave [Urls] de [appsettings.json]. Cuando se inicia mediante este perfil, la aplicación usa esta dirección; cuando se inicia fuera del perfil (por ejemplo, una vez publicada), usa la dirección de [appsettings.json];
  • líneas 9–10: las variables de entorno que se pasan a la aplicación. [ASPNETCORE_ENVIRONMENT=Development] establece el entorno: se lee [appsettings.Development.json] y se muestran los comandos SQL. En un servidor de producción, sin este archivo ni esta variable, el entorno es [Production].

11.6.5. Config/AuthOptions.cs

// =========================================================================
// Config/AuthOptions.cs
// -------------------------------------------------------------------------
// La sección "Auth" de appsettings.json, como una clase tipada.
//
// Es el "patrón de opciones" de ASP.NET Core: en
// Program.cs, builder.Services.Configure<AuthOptions>(...) enlaza la sección
// con la clase; una clase que la necesita recibe entonces IOptions<AuthOptions>
// por inyección de dependencias. Así evitamos leer cadenas de caracteres
// por todas partes, como hacía process.env.JWT_SECRET.
// =========================================================================

namespace RdvMedecins.Config;

public class AuthOptions
{
    public const string Section = "Auth";

    // clave secreta usada para firmar / verificar los tokens JWT. El algoritmo
    // HMAC-SHA256 exige una clave de al menos 256 bits, es decir, 32 bytes.
    public string JwtSecret { get; set; } = "";

    // duración de validez de un token, en segundos; la cookie que lo lleva
    // tiene la misma duración
    public int JwtExpiresInSeconds { get; set; } = 7200;

    // true en producción (HTTPS): la cookie de autenticación nunca se
    // envía por una conexión sin cifrar
    public bool CookieSecure { get; set; }
}

Comentemos este código:

  • línea 15: la sección [Auth] de [appsettings.json], en forma de una clase normal: una propiedad por clave, con el mismo nombre. Este es el patrón de opciones ([options pattern]) de [ASP.NET Core]. En [Program.cs], [Configure<AuthOptions>(...)] vincula la sección con la clase: el framework crea un objeto [AuthOptions] y rellena sus propiedades con los valores de la sección, convirtiéndolos al tipo correcto (["7200"] se convierte en el entero 7200, [false] se convierte en el booleano [false]). Una clase que lo necesita lo recibe mediante inyección de dependencias, en forma de un ***[IOptions<AuthOptions>], cuya propiedad ***[Value] es el objeto ya rellenado: es lo que hace [Auth/AuthService.cs], con su parámetro [IOptions<AuthOptions> options] y su campo [auth = options.Value]. Así se evita tener que leer cadenas de caracteres por todas partes, como hacía [process.env.JWT_SECRET] en la versión [NestJS]: el compilador verifica los nombres de las claves y los valores ya están convertidos;
  • línea 17: el nombre de la sección, escrito una sola vez;
  • líneas 21–29: los tres valores de esta sección. Los valores predeterminados ([7200], [false] para un booleano) son los que se usan si la clave no está en la configuración.

11.6.6. Config/ProtectionOptions.cs

// =========================================================================
// Config/ProtectionOptions.cs
// -------------------------------------------------------------------------
// La sección "Protection" de appsettings.json: los umbrales de la protección
// contra robots (ver Auth/AttemptLimiterService.cs).
// =========================================================================

namespace RdvMedecins.Config;

public class ProtectionOptions
{
    public const string Section = "Protection";

    // inicio de sesión: cantidad de fallos (captcha o contraseña incorrectos) permitidos
    // para un mismo login desde la misma dirección IP, antes de que este par se bloquee...
    public int LoginMaxFailures { get; set; } = 5;

    // ... durante esta duración (una dirección IP también se bloquea si acumula
    // 5 veces más fallos, con todos los logins combinados)
    public int LoginBlockMinutes { get; set; } = 15;

    // creación de cuentas de cliente: cantidad máxima de cuentas creadas por hora
    // desde la misma dirección IP. En un salón de clases, todas las computadoras suelen salir
    // por la misma dirección: aumente el valor si es necesario.
    public int RegistrationMaxPerHour { get; set; } = 10;
}
  • líneas 10–25: la sección [Protection] de [appsettings.json], con el mismo esquema. Se inyecta, en forma de un [IOptions<ProtectionOptions>], en [Auth/AttemptLimiterService.cs], que lee de ella sus umbrales.

11.7. Inicio de la aplicación

11.7.1. Program.cs

El archivo [Program.cs] cumple a la vez la función de [main.ts] (inicio, middleware) y la de [app.module.ts] (qué servicio proporciona qué) de la versión [NestJS]. Sigue la estructura de todos los ejemplos: primero se registran los servicios y luego se construye el pipeline de middleware. Lo desglosaremos por secciones.

11.7.1.1. La configuración

// =========================================================================
// Program.cs
// -------------------------------------------------------------------------
// El punto de entrada de la aplicación: el equivalente de main.ts
// (arranque, middlewares) y de app.module.ts (quién provee qué) a la vez.
//
// Dos etapas, siempre en este orden:
//
//   1. builder.Services... : REGISTRAMOS los servicios en el contenedor de inyección
//      de dependencias (el equivalente de los "providers" de los módulos de
//      NestJS). Cada servicio tiene un TIEMPO DE VIDA:
//        - Singleton : una única instancia para toda la aplicación;
//        - Scoped    : una instancia por solicitud HTTP (el DbContext y todo
//                      lo que lo usa);
//        - Transient : una instancia nueva cada vez que se solicita.
//
//   2. app.Use... : construimos el PIPELINE de middlewares, que toda
//      solicitud atraviesa en el orden en que se declaran.
// =========================================================================

using System.Globalization;
using System.Text.Encodings.Web;
using System.Text.Unicode;
using Microsoft.AspNetCore.Localization;
using Microsoft.EntityFrameworkCore;
using RdvMedecins.Auth;
using RdvMedecins.Config;
using RdvMedecins.Data;
using RdvMedecins.Business;
using RdvMedecins.Repositories;
using RdvMedecins.Web;

var builder = WebApplication.CreateBuilder(args);

// =========================================================================
// 1. los servicios
// =========================================================================

// ---- la configuración tipada (secciones de appsettings.json, ver Config/)
builder.Services.Configure<AuthOptions>(builder.Configuration.GetSection(AuthOptions.Section));
builder.Services.Configure<ProtectionOptions>(builder.Configuration.GetSection(ProtectionOptions.Section));
var authOptions = builder.Configuration.GetSection(AuthOptions.Section).Get<AuthOptions>() ?? new AuthOptions();
  • líneas 21–31: los espacios de nombres utilizados, además de los [using] implícitos: los del framework (localización, EF Core, codificación HTML) y los de la aplicación, uno por carpeta;
  • línea 33: el constructor de la aplicación, como en todos los ejemplos. Ya ha leído la configuración ([appsettings.json], [appsettings.Development.json], variables de entorno...), accesible mediante [builder.Configuration];
  • líneas 40–41: el patrón de opciones (vea [Config/AuthOptions.cs]): cada sección se vincula con su clase. [GetSection("Auth")] designa la sección; [Configure<T>] registra el servicio correspondiente [IOptions<T>], que los servicios de autenticación recibirán mediante inyección;
  • línea 42: la misma sección, leída esta vez directamente como un objeto ([Get<AuthOptions>()]), o un objeto con valores predeterminados si falta la sección. La configuración de [JwtBearer] (más adelante) necesita la clave secreta ahora mismo, durante el registro de servicios: en este momento, el contenedor de inyección de dependencias aún no se ha construido y no se puede inyectar ningún [IOptions<AuthOptions>] .

11.7.1.2. La base de datos y las capas DAO y de negocio

// ---- Entity Framework Core: el DbContext, uno por solicitud (Scoped).
// UseMySql: el proveedor Pomelo para MySQL / MariaDB. La versión del
// servidor le indica qué dialecto SQL generar.
var connectionString = builder.Configuration.GetConnectionString("RdvMedecins")
    ?? throw new InvalidOperationException("ConnectionStrings:RdvMedecins missing from appsettings.json");
var serverVersion = ServerVersion.Parse(builder.Configuration["MySql:ServerVersion"] ?? "8.0.0-mysql");
builder.Services.AddDbContext<RdvMedecinsDbContext>(options => options.UseMySql(connectionString, serverVersion));

// ---- capa DAO y capa de negocio: Scoped, como el DbContext del que
// dependen (un servicio nunca debe vivir MÁS que sus dependencias)
builder.Services.AddScoped<DoctorRepository>();
builder.Services.AddScoped<ClientRepository>();
builder.Services.AddScoped<SlotRepository>();
builder.Services.AddScoped<AppointmentRepository>();
builder.Services.AddScoped<UserRepository>();
// "cuando se solicite un IBusiness, proporcionar un BusinessService" (NestJS:
// { provide: BUSINESS_TOKEN, useClass: BusinessService }). En C#, la propia
// interfaz sirve como token de inyección.
builder.Services.AddScoped<IBusiness, BusinessService>();

// ---- el caché (singleton) y su fachada (scoped), ver Web/ApplicationModel.cs
builder.Services.AddSingleton<ListCache>();
builder.Services.AddScoped<ApplicationModel>();
  • líneas 4–5: la cadena de conexión, como en el ejemplo 28. El operador [??] devuelve el valor de la izquierda si no es [null]; en caso contrario, devuelve el de la derecha: si falta la clave, la aplicación se detiene de inmediato mostrando un mensaje que indica qué falta, en lugar de devolver un error críptico en la primera solicitud;
  • línea 6: la versión del servidor [MySQL], con un valor predeterminado si falta la clave;
  • línea 7: el [DbContext] de la aplicación (vea [Data/RdvMedecinsDbContext.cs]), uno por solicitud ([Scoped]), con el proveedor [MySQL] (vea el ejemplo 28);
  • líneas 11–15: la capa DAO: una clase por tabla (excepto [users], cuyo repositorio se usa para la autenticación). Es [Scoped], al igual que el [DbContext] que utiliza. Un servicio nunca debe sobrevivir a sus dependencias: un DAO [Singleton] conservaría indefinidamente el [DbContext] de la primera solicitud, aunque este se destruye al final de dicha solicitud (vea el capítulo 6);
  • línea 19: la capa de negocio. [AddScoped<IBusiness, BusinessService>()] se lee: “cuando un servicio solicite un [IBusiness], proporcione un [BusinessService]”. Quienes usan la capa de negocio dependen de la interfaz, no de la clase: podríamos reemplazar la implementación (por una versión de prueba, por ejemplo) modificando solo esta línea. La versión [NestJS] requería un token ([BUSINESS_TOKEN]) para esto, ya que las interfaces de [TypeScript] desaparecen en tiempo de compilación; en [C#], la propia interfaz hace de token;
  • líneas 22–23: la caché de la capa web (las listas de médicos y clientes) tiene alcance de aplicación: [Singleton], una única instancia compartida por todas las solicitudes (vea el ejemplo 23). Su fachada, [ApplicationModel], por la que pasan todos los controladores, usa la capa de negocio: por lo tanto es [Scoped]. La caché en sí, que es independiente de todo lo demás, puede sobrevivir a la fachada.

11.7.1.3. Autenticación, traducción y codificación HTML

// ---- autenticación
builder.Services.AddScoped<AuthService>();
builder.Services.AddSingleton<CaptchaService>(); // captchas pendientes: en memoria
builder.Services.AddSingleton<AttemptLimiterService>(); // contadores: en memoria
builder.Services.AddSingleton<RegistrationPassService>(); // pases: en memoria
builder.Services.AddJwtAuthentication(authOptions); // ver Auth/JwtAuthentication.cs
builder.Services.AddAuthorization();

// ---- traducción
builder.Services.AddSingleton<Translator>();

// ---- el codificador HTML de Razor. Por defecto, reemplaza todo carácter no ASCII
// por una entidad ("é" -> "&#xE9;"): la página se muestra correctamente,
// pero su código fuente se vuelve ilegible. Le permitimos escribir tal cual
// los caracteres de todos los idiomas; < > & " ' siguen escapándose siempre.
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
  • línea 2: el servicio de inicio de sesión (verifica el nombre de usuario y la contraseña, genera el token; vea el ejemplo 25). Usa el repositorio de cuentas: es [Scoped];
  • líneas 3–5: los CAPTCHA pendientes, los contadores de fallos y los códigos de acceso para la creación de cuentas (vea el ejemplo 27). Estos datos se mantienen en memoria y deben ser los mismos para todas las solicitudes: los tres servicios son [Singleton]. El inconveniente: se pierden cada vez que se reinicia el servidor;
  • línea 6: la configuración de [JwtBearer] (token leído de la cookie, redirección a la página de inicio de sesión...), como se vio en el ejemplo 25. Está encapsulada en un método de extensión de [IServiceCollection] (vea [Auth/JwtAuthentication.cs]), que se invoca como un método del framework y, de este modo, alivia la carga de [Program.cs];
  • línea 7: los servicios de autorización, utilizados por [[Authorize]] y por el middleware [UseAuthorization];
  • línea 10: el servicio de traducción, que lee los diccionarios una sola vez (vea el ejemplo 22);
  • línea 16: el codificador HTML de [Razor] deja pasar los caracteres de todos los idiomas, como en el ejemplo 15.

11.7.1.4. MVC y sus opciones

// ---- MVC: controladores + vistas Razor
builder.Services.AddControllersWithViews(options =>
{
    // InvalidSessionException -> de vuelta a la página de inicio de sesión
    options.Filters.Add<HtmlExceptionFilter>();

    // con los tipos "nullable" habilitados, MVC trata automáticamente una propiedad
    // string (no nula) como requerida. Preferimos decirlo nosotros mismos,
    // explícitamente, con [Required] (ver Models/Forms.cs).
    options.SuppressImplicitRequiredAttributeForNonNullableReferenceTypes = true;

    // los mensajes de los errores de ENLACE (un texto donde se espera un número:
    // version="abc"...) también son claves de traducción
    var messages = options.ModelBindingMessageProvider;
    messages.SetValueMustNotBeNullAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetAttemptedValueIsInvalidAccessor((_, _) => "ERRORS.INVALID_FORM");
    messages.SetValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetValueMustBeANumberAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetUnknownValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyAttemptedValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyUnknownValueIsInvalidAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyValueMustBeANumberAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetMissingBindRequiredValueAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetMissingKeyOrValueAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetMissingRequestBodyRequiredValueAccessor(() => "ERRORS.INVALID_FORM");
});
  • línea 2: los controladores y vistas [Razor]. La función pasada como parámetro establece las opciones de MVC;
  • línea 5: un filtro de excepciones global (vea el ejemplo 24), que se aplica a todas las acciones. Maneja un solo caso: una [InvalidSessionException] (el token es válido, pero la cuenta a la que se refiere ha sido eliminada) lleva a la página de inicio de sesión. Las demás excepciones siguen su camino hacia el middleware [UseExceptionHandler] (más adelante);
  • línea 10: una trampa de los tipos “anulables” (nullable). Cuando están habilitados, MVC trata una propiedad [string] (no anulable) de un modelo como obligatoria, exactamente como si tuviera el atributo [[Required]], con un mensaje de error en inglés que no entendemos. Esta opción elimina ese comportamiento predeterminado: un campo es obligatorio solo si tiene explícitamente el atributo [[Required]], con nuestro propio mensaje (vea [Models/Forms.cs]);
  • líneas 14–25: los mensajes de error de enlace (binding) (vea el ejemplo 19): texto donde se espera un número ([version=abc]), un valor ausente... El ejemplo 19 redefinía solo dos de ellos, en inglés; el caso de estudio los redefine todos y cada uno devuelve la misma clave de traducción, [ERRORS.INVALID_FORM], en lugar de un texto: el mensaje se traduce en el momento de mostrarlo, en el idioma del usuario. El carácter [_] designa un parámetro que no se usa (el nombre del campo, el valor ingresado): el mensaje es el mismo sea cual sea el campo. Estos errores nunca deberían producirse con los formularios de la aplicación: indican una solicitud construida manualmente.

11.7.1.5. Carga de la caché

var app = builder.Build();

// =========================================================================
// carga del caché (listas de médicos y clientes). Los servicios Scoped
// solo existen dentro de un "ámbito" (normalmente: una solicitud): creamos
// uno para el tiempo de esta carga. Base de datos inaccesible -> la aplicación
// se detiene aquí, con la excepción de EF Core en la consola.
// =========================================================================
using (var scope = app.Services.CreateScope())
{
    await scope.ServiceProvider.GetRequiredService<ApplicationModel>().LoadAsync();
}
  • línea 1: construcción de la aplicación. El contenedor de inyección de dependencias ya está creado: ya no se pueden registrar servicios, pero sí obtenerlos;
  • líneas 9–12: las listas de médicos y clientes se cargan en la caché antes de que el servidor comience a escuchar. [ApplicationModel] es un servicio [Scoped]: solo puede crearse dentro de un ámbito (scope) y, fuera de una solicitud, no hay ámbito. [CreateScope()] crea uno; [GetRequiredService<ApplicationModel>()] obtiene de él el servicio (junto con la capa de negocio, los repositorios y el [DbContext] de los que depende) y [LoadAsync()] rellena la caché, que es un [Singleton] y por lo tanto sobrevive al ámbito. La instrucción [using] destruye el ámbito —y con él el [DbContext]— al terminar el bloque. Si la base de datos no es accesible, la excepción de EF Core no se captura: la aplicación termina, con un mensaje de error en la consola. Es la primera señal de una cadena de conexión incorrecta o de un servidor [MySQL] detenido.

11.7.1.6. El pipeline de middleware

// =========================================================================
// 2. el pipeline de middlewares - el ORDEN importa
// =========================================================================

// ---- los errores se convierten en páginas HTML (ver Web/HtmlExceptionFilter.cs):
// excepción no controlada -> página 500 (la excepción se escribe en el log);
// respuesta 400 / 403 / 404 sin contenido -> página de error correspondiente
app.UseExceptionHandler("/error/500");
app.UseStatusCodePagesWithReExecute("/error/{0}");

// ---- archivos estáticos de la carpeta wwwroot/: /css/..., /js/..., /lib/bootstrap/...
app.UseStaticFiles();

// ---- el idioma de cada solicitud: leído de una cookie (ver LanguageController),
// inglés por defecto. Define CultureInfo.CurrentCulture (formatos de fecha)
// y CultureInfo.CurrentUICulture (idioma de los textos, ver Web/Translator.cs).
var cultures = Translator.Languages.Select(l => new CultureInfo(l)).ToList();
var localization = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture(Translator.DefaultLanguage),
    SupportedCultures = cultures,
    SupportedUICultures = cultures,
};
// solo decide la cookie (ni el idioma del navegador, ni un parámetro de URL)
localization.RequestCultureProviders = [new CookieRequestCultureProvider()];
app.UseRequestLocalization(localization);

// ---- enrutamiento, luego autenticación (¿quién es? -> HttpContext.User, a partir
// del token), luego autorización (¿está permitido? -> [Authorize])
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

// ---- los controladores, con sus rutas declaradas mediante atributos ([HttpGet("...")])
app.MapControllers();

app.Run();

Cada solicitud pasa por los componentes de middleware en el orden en que se declaran (vea el capítulo 7): este orden es, por lo tanto, importante.

  • línea 8: el primer middleware envuelve a todos los demás. Si una excepción no ha sido manejada por nadie (un error de programación, una base de datos que se volvió inaccesible, etc.), registra la excepción y vuelve a ejecutar la solicitud con la dirección [/error/500]: el usuario ve una página de error de la aplicación, no un mensaje técnico (vea el capítulo 7);
  • línea 9: una respuesta de error vacía (400, 403, 404) se convierte en una página del mismo modo, mediante la acción [/error/{code}] del controlador [ErrorController] (vea los ejemplos 24 y 26). La solicitud re-ejecutada vuelve a pasar por los middleware siguientes: la página de error se muestra, por lo tanto, y reconoce al usuario que ha iniciado sesión;
  • línea 12: los archivos estáticos de la carpeta [wwwroot] (vea el ejemplo 15): la hoja de estilos, el script de la página y [Bootstrap], almacenado aquí en [wwwroot/lib/bootstrap]. Al colocarse al principio del pipeline, este middleware responde a las solicitudes de archivos sin pasarlas por la localización ni la autenticación;
  • líneas 17–23: la configuración de localización, como en el ejemplo 22. Los idiomas admitidos y el idioma predeterminado son los del servicio de traducción ([Translator.Languages], [Translator.DefaultLanguage]): se definen en un solo lugar;
  • línea 25: solo la cookie establecida por [LanguageController] determina el idioma (vea el ejemplo 22). La sintaxis [[...]] es una expresión de colección: en este caso, una lista con un solo elemento;
  • línea 26: el middleware de localización, que establece el idioma de cada solicitud;
  • líneas 30–32: el enrutamiento, seguido de la autenticación y luego de la autorización. El enrutamiento selecciona la acción que atenderá la solicitud, según las rutas declaradas mediante atributos. Los ejemplos no lo invocaban: [WebApplication] lo agrega, por tanto, automáticamente al comienzo del pipeline. Invocarlo explícitamente hace visible el orden: la autorización debe ir después del enrutamiento, porque es la acción seleccionada la que lleva el atributo [[Authorize]] que se debe verificar; y después de la autenticación, que determina, a partir del token, quién es el usuario (vea el ejemplo 25);
  • línea 35: los controladores y sus rutas, declaradas mediante atributos ([[Route("schedule")]]...);
  • línea 37: el servidor se inicia y espera solicitudes en el puerto 8081.

11.8. Las entidades

Las entidades de EF Core corresponden a las tablas de la base de datos y a las clases [C#] (vea el ejemplo 28). Replican, una por una, las entidades de [TypeORM] de la versión [NestJS]: los atributos [[Table]], [[Column]], [[Key]], [[ForeignKey]] hacen las veces de los decoradores [@Entity], [@Column], [@PrimaryGeneratedColumn] y [@JoinColumn]. EF Core no crea la base de datos, sino el script SQL [database/dbrdvmedecins2.sql]: las entidades solo deben describir con exactitud las tablas que ya existen.

11.8.1. Entities/AbstractEntity.cs

// =========================================================================
// Entities/AbstractEntity.cs
// -------------------------------------------------------------------------
// Los dos campos comunes a todas las entidades: el identificador [id] y el
// número de versión [version] (bloqueo optimista).
//
// Como con TypeORM (y @MappedSuperclass en JPA), basta con que una clase
// ABSTRACTA sea la madre de las clases de entidad: EF Core no crea una tabla
// para ella, pero agrega sus propiedades a las tablas de las clases hijas.
//
// Los atributos [Key], [Column]... provienen del espacio de nombres estándar
// System.ComponentModel.DataAnnotations: EF Core los lee para construir
// su "modelo" (qué clase va en qué tabla, qué propiedad en
// qué columna). Cumplen el papel de los decoradores @PrimaryGeneratedColumn,
// @Column de TypeORM.
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

public abstract class AbstractEntity
{
    // [Key]: la clave primaria. Una clave entera es, por convención, generada
    // por la base de datos (columna AUTO_INCREMENT): EF Core lee su valor de vuelta
    // después de cada INSERT.
    [Key]
    [Column("id")]
    public int Id { get; set; }

    // [ConcurrencyCheck]: el bloqueo optimista. Cada UPDATE generado por EF
    // Core lleva la condición "WHERE id = ... AND version = <valor leído>".
    // Si alguien modificó la fila mientras tanto, no se actualiza ninguna fila
    // y EF Core lanza una DbUpdateConcurrencyException.
    //
    // Diferencia con @VersionColumn de TypeORM: EF Core NO INCREMENTA
    // por sí mismo un número de versión entero. Lo hace nuestro DbContext,
    // justo antes de cada guardado (ver Data/RdvMedecinsDbContext.cs).
    [Column("version")]
    [ConcurrencyCheck]
    public int Version { get; set; }
}
  • línea 23: una clase abstracta sin el atributo [[Table]]: no corresponde a ninguna tabla, pero sus propiedades se agregan a las de las tablas de sus clases hijas. Todas las entidades de la aplicación heredan de ella y, por lo tanto, tienen un identificador y una versión;
  • líneas 28–30: la clave primaria ([[Key]]), columna [id]. Por convención en EF Core, una clave entera es generada por la base de datos ([AUTO_INCREMENT]): EF Core vuelve a leer su valor después de cada [INSERT];
  • líneas 40–42: la versión de la fila para el bloqueo optimista (vea el ejemplo 28). [[ConcurrencyCheck]] agrega la condición [AND version = <value read>] a cada [UPDATE]. A diferencia de [@VersionColumn] de [TypeORM], EF Core no incrementa la versión por sí mismo: [DbContext] se encarga de ello (vea más adelante).

11.8.2. Entities/Person.cs

// =========================================================================
// Entities/Person.cs
// -------------------------------------------------------------------------
// Clase madre (sin tabla) de las entidades [Doctor] y [Client]: un título, un
// apellido, un nombre - y la cuenta de usuario asociada (columna [user]).
//
// Una relación declarada en una clase abstracta es heredada por las
// clases hijas exactamente como las columnas: EF Core agrega entonces la
// relación [User] a la tabla [doctors] Y a la tabla [clients].
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

public abstract class Person : AbstractEntity
{
    [Column("title")]
    [MaxLength(5)]
    public string Title { get; set; } = ""; // Melle, Mme, Mr

    [Column("last_name")]
    [MaxLength(20)]
    public string LastName { get; set; } = "";

    [Column("first_name")]
    [MaxLength(20)]
    public string FirstName { get; set; } = "";

    // -----------------------------------------------------------------------
    // La relación con la cuenta de usuario, en DOS propiedades - es la forma
    // habitual de hacerlo con EF Core:
    //   - UserId : la clave externa propiamente dicha (columna [user]). Se puede
    //     leer sin cargar el User completo (TypeORM: @RelationId);
    //   - User   : la "propiedad de navegación", el propio objeto User. Solo
    //     se llena si se pide en la consulta (.Include(...),
    //     ver Repositories/); de lo contrario es null.
    // [ForeignKey] vincula ambas. La naturaleza "uno a uno" de la relación
    // (columna [user] UNIQUE) se especifica en RdvMedecinsDbContext.
    // -----------------------------------------------------------------------
    [Column("user")]
    public int UserId { get; set; }

    // "= null!": le prometemos al compilador leer esta propiedad solo
    // cuando se haya cargado (Include) o asignado
    [ForeignKey(nameof(UserId))]
    public User User { get; set; } = null!;
}
  • línea 17: la clase padre —que también es abstracta— de [Doctor] y [Client], a su vez hija de [AbstractEntity]. Los médicos y los clientes tienen las mismas columnas: se definen una sola vez;
  • líneas 19–29: el título (Mme, Mr, Melle), el apellido y el nombre. [[MaxLength]] especifica el ancho de la columna. Estas propiedades son de tipo [string] (no [string?]): nunca deben asignarse a [null], y por ello el compilador exige un valor inicial, en este caso la cadena vacía [""];
  • líneas 42–43: la clave externa a la cuenta de usuario, columna [user]. El identificador de la cuenta puede leerse sin cargar la cuenta en sí: es lo que hacía [@RelationId] en la versión [NestJS];
  • líneas 47–48: la propiedad de navegación: el propio objeto [User]. [[ForeignKey(nameof(UserId))]] indica qué propiedad contiene la clave externa ([nameof(UserId)] es igual a la cadena ["UserId"], pero el compilador verifica que la propiedad exista). Una propiedad de navegación solo se rellena si la consulta lo solicita ([Include]; vea la capa DAO); de lo contrario, vale [null]. La notación [= null!] suprime la advertencia del compilador: garantiza que la propiedad solo se leerá después de haberse cargado. El carácter “uno a uno” de la relación se especifica en [DbContext]. Una relación declarada en una clase padre se hereda, igual que las columnas: las tablas [doctors] y [clients] tienen cada una su propia relación con [users].

11.8.3. Entities/Doctor.cs

// =========================================================================
// Entities/Doctor.cs
// -------------------------------------------------------------------------
// Un médico del consultorio (tabla [doctors]).
//
// Restricción SQL de unicidad: unq_doctors_first_name_last_name (dos médicos
// no pueden tener el mismo nombre y apellido) - creada por el script SQL,
// reconocida por su nombre en la capa de negocio.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("doctors")]
public class Doctor : Person
{
    // relación inversa (opcional): las franjas horarias de este médico.
    // Muestra la relación "1 médico -> varias franjas" en ambos
    // sentidos; como toda navegación, solo se llena a pedido.
    public List<Slot> Slots { get; set; } = [];
}
  • línea 15: la clase [Doctor] corresponde a la tabla [doctors]. Hereda todas sus propiedades de [Person]. La restricción de unicidad [unq_doctors_first_name_last_name], mencionada en el comentario, la crea el script SQL; la capa de negocio la reconoce por su nombre (vea el ejemplo 28);
  • línea 21: la relación inversa de la de [Slot] hacia su médico: las franjas horarias de este médico. EF Core asocia automáticamente las dos navegaciones ([Doctor.Slots] y [Slot.Doctor]), que describen la misma relación “un médico, varias franjas horarias” vista desde cada lado. Como toda navegación, solo se rellena a petición; en realidad la aplicación no la usa: lee las franjas horarias mediante la capa DAO. [[]] es una expresión de colección: en este caso, una lista vacía.

11.8.4. Entities/Client.cs

// =========================================================================
// Entities/Client.cs
// -------------------------------------------------------------------------
// Atención: [Client] designa aquí a un PACIENTE del consultorio médico,
// no a un cliente HTTP. Es el vocabulario del dominio de negocio original,
// conservado tal cual (tabla [clients]).
//
// Restricción SQL de unicidad: unq_clients_first_name_last_name (ver Doctor.cs).
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("clients")]
public class Client : Person
{
}

Un cliente, es decir, un paciente del consultorio (no un cliente HTTP): una [Person] de la tabla [clients] (línea 15), sin propiedades adicionales.

11.8.5. Entities/Slot.cs

// =========================================================================
// Entities/Slot.cs
// -------------------------------------------------------------------------
// Una franja horaria de un médico (tabla [slots]): 8:00 - 8:20, etc.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("slots")]
public class Slot : AbstractEntity
{
    [Column("start_hour")] public int StartHour { get; set; } // hora de inicio de la franja
    [Column("start_minute")] public int StartMinute { get; set; } // minuto de inicio de la franja
    [Column("end_hour")] public int EndHour { get; set; } // hora de fin de la franja
    [Column("end_minute")] public int EndMinute { get; set; } // minuto de fin de la franja

    // varias franjas para el mismo médico: clave externa [doctor_id]
    // + navegación [Doctor] (misma técnica que Person.UserId / User)
    [Column("doctor_id")]
    public int DoctorId { get; set; }

    [ForeignKey(nameof(DoctorId))]
    public Doctor Doctor { get; set; } = null!;
}
  • líneas 14–17: la hora y el minuto de inicio y de fin de la franja. El atributo y la propiedad se escriben en la misma línea: esto está permitido y es más compacto para estas cuatro columnas similares;
  • líneas 21–25: la relación “muchos a uno” con el médico: varias franjas horarias para un médico. La misma técnica que en [Person]: la clave externa [DoctorId] (columna [doctor_id]) y la propiedad de navegación [Doctor], vinculadas mediante [[ForeignKey]]. EF Core no requiere más aclaraciones: una referencia de un lado, una lista del otro: es una relación “uno a muchos”.

11.8.6. Entities/Appointment.cs

// =========================================================================
// Entities/Appointment.cs
// -------------------------------------------------------------------------
// Una cita (tabla [appointments]): un cliente, en una franja, en un día dado.
//
// Restricción SQL de unicidad: unq1_appointments (day, slot_id) - una franja solo se
// reserva una vez por día. Creada por el script SQL, reconocida por su
// nombre en la capa de negocio.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("appointments")]
public class Appointment : AbstractEntity
{
    // DateOnly: una fecha SIN hora, que corresponde exactamente al tipo SQL
    // DATE de la columna [day]. (El proyecto NestJS usaba una cadena
    // "yyyy-MM-dd": JavaScript no tiene un tipo "fecha sin hora".)
    // Dos valores DateOnly se comparan directamente: day < today...
    [Column("day")]
    public DateOnly Day { get; set; }

    [Column("client_id")]
    public int ClientId { get; set; }

    [ForeignKey(nameof(ClientId))]
    public Client Client { get; set; } = null!;

    [Column("slot_id")]
    public int SlotId { get; set; }

    [ForeignKey(nameof(SlotId))]
    public Slot Slot { get; set; } = null!;
}
  • línea 15: la tabla de citas. Su restricción de unicidad [unq1_appointments (day, slot_id)] garantiza que una franja horaria se reserve una sola vez por día;
  • líneas 22–23: el día de la cita. El tipo [DateOnly] (una fecha sin hora) corresponde exactamente al tipo SQL [DATE]: sin hora, por lo tanto sin problemas de zona horaria. La versión [NestJS] manejaba una cadena de tipo [yyyy-mm-dd], ya que no existía un tipo así en [JavaScript]. Dos valores [DateOnly] se comparan directamente con [<], [>=]..., tanto en [C#] como en las consultas [LINQ];
  • líneas 25–35: el cliente y la franja horaria de la cita: dos relaciones “muchos a uno”, cada una definida con una clave externa y una navegación. Para crear una cita basta rellenar las claves externas [ClientId] y [SlotId]: es lo que hace la capa de negocio.

11.8.7. Entities/Role.cs

// =========================================================================
// Entities/Role.cs
// -------------------------------------------------------------------------
// Los tres roles de un usuario (columna users.role):
//   - ADMIN  : el administrador - citas + gestión de médicos y clientes;
//   - DOCTOR : un médico - reserva y cancela citas;
//   - USER   : un cliente (paciente) - reserva para sí mismo, gestiona su cuenta.
//
// En C#, una enumeración (enum) en lugar de un tipo unión de cadenas
// ('ADMIN' | 'DOCTOR' | 'USER'): el compilador rechaza cualquier otro valor.
// EF Core la guarda en la base de datos como TEXT ('ADMIN'...), igual que
// el script SQL (ver HasConversion<string>() en RdvMedecinsDbContext).
// =========================================================================

namespace RdvMedecins.Entities;

public enum Role
{
    ADMIN,
    DOCTOR,
    USER,
}
  • líneas 17–21: los tres roles, en forma de una enumeración ([enum]): una variable de tipo [Role] solo puede tomar los valores [Role.ADMIN], [Role.DOCTOR] o [Role.USER], y el compilador rechaza cualquier otro valor. Equivale al tipo de unión de cadenas ['ADMIN' | 'DOCTOR' | 'USER'] de la versión [NestJS]. De forma predeterminada, EF Core almacenaría una enumeración como un número (0, 1, 2); la columna [role] contiene texto: la conversión se solicita en [DbContext].

11.8.8. Entities/User.cs

// =========================================================================
// Entities/User.cs
// -------------------------------------------------------------------------
// Un usuario autorizado a iniciar sesión en la aplicación (tabla [users]).
// Cada médico y cada cliente tiene SU propia cuenta de usuario (columna
// [user] de las tablas [doctors] y [clients], ver Person.cs).
//
// Restricción SQL de unicidad: unq_users_login (un login pertenece a una sola
// cuenta). La crea el script database/dbrdvmedecins2.sql;
// la capa de negocio la reconoce por su NOMBRE (ver Business/BusinessService.cs).
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("users")]
public class User : AbstractEntity
{
    [Column("login")]
    [MaxLength(30)]
    public string Login { get; set; } = "";

    // la contraseña con HASH (bcrypt) - nunca en claro
    [Column("password")]
    [MaxLength(100)]
    public string Password { get; set; } = "";

    // el nombre que se muestra una vez iniciada la sesión - para un médico o un cliente:
    // "firstName LASTNAME" (p. ej. "Marie PELISSIER")
    [Column("name")]
    [MaxLength(40)]
    public string Name { get; set; } = "";

    // ADMIN, DOCTOR o USER, guardado en la base de datos como texto
    [Column("role")]
    public Role Role { get; set; }
}
  • línea 18: las cuentas de los usuarios autorizados a iniciar sesión: el administrador, cada médico y cada cliente. La restricción [unq_users_login] prohíbe dos cuentas con el mismo login;
  • líneas 21–23: el nombre de usuario;
  • líneas 26–28: el hash [bcrypt] de la contraseña, nunca la contraseña en sí (vea el ejemplo 25);
  • líneas 32–34: el nombre que se muestra en la barra de navegación una vez iniciada la sesión (“Marie PELISSIER”);
  • líneas 37–38: el rol, de tipo [Role]. Como la clase [User] no declara una navegación hacia el médico o el cliente que la posee, la relación solo se conoce del lado de [Person].

11.9. El DbContext

El [DbContext] de la aplicación se basa en el del Ejemplo 28, con cinco tablas en lugar de una, y algunas precisiones sobre el modelo que los atributos no pueden expresar.

11.9.1. Data/RdvMedecinsDbContext.cs

// =========================================================================
// Data/RdvMedecinsDbContext.cs
// -------------------------------------------------------------------------
// El DbContext es la pieza central de Entity Framework Core. Cumple
// al mismo tiempo el papel:
//   - del DataSource de TypeORM: la conexión a la base de datos;
//   - del Repository<T> de TypeORM: un DbSet<T> por tabla, que se
//     consulta en LINQ (db.Doctors.Where(...)...);
//   - de una "unidad de trabajo": SEGUIMIENTO de las entidades que ha
//     cargado (change tracking). Cuando se modifica una propiedad, nada
//     va a la base de datos; es SaveChangesAsync() quien envía, de una sola vez, los
//     INSERT / UPDATE / DELETE necesarios.
//
// Tiempo de vida: un DbContext por solicitud HTTP (registro "scoped",
// ver Program.cs). Todos los repositorios de una misma solicitud comparten
// por lo tanto el MISMO DbContext - y en consecuencia la misma conexión y la misma
// transacción cuando la capa de negocio abre una.
//
// El mapeo clase <-> tabla se describe principalmente mediante los atributos
// de las entidades ([Table], [Column], [ForeignKey]...); OnModelCreating completa
// lo que los atributos no pueden expresar.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Entities;

namespace RdvMedecins.Data;

public class RdvMedecinsDbContext(DbContextOptions<RdvMedecinsDbContext> options) : DbContext(options)
{
    // una "tabla" por entidad. Set<T>() devuelve el DbSet que EF Core creó
    // para el tipo T.
    public DbSet<Doctor> Doctors => Set<Doctor>();
    public DbSet<Client> Clients => Set<Client>();
    public DbSet<Slot> Slots => Set<Slot>();
    public DbSet<Appointment> Appointments => Set<Appointment>();
    public DbSet<User> Users => Set<User>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // un médico (un cliente) tiene UNA cuenta, y una cuenta pertenece a lo sumo a
        // UNA persona (columna [user] UNIQUE en el script SQL): relación
        // "uno a uno", cuya clave externa lleva doctors.user
        // (clients.user). Sin esta precisión, EF Core supondría "varios
        // médicos para la misma cuenta" - lo cual también funcionaría, pero
        // describiría mal el modelo.
        modelBuilder.Entity<Doctor>().HasOne(d => d.User).WithOne().HasForeignKey<Doctor>(d => d.UserId);
        modelBuilder.Entity<Client>().HasOne(c => c.User).WithOne().HasForeignKey<Client>(c => c.UserId);

        // el rol es una enumeración de C#, guardada en la base de datos como texto
        // ('ADMIN', 'DOCTOR', 'USER') y no como número (0, 1, 2)
        modelBuilder.Entity<User>().Property(u => u.Role).HasConversion<string>();
    }

    // -----------------------------------------------------------------------
    // El bloqueo optimista (ver AbstractEntity.Version): justo antes de cada
    // guardado, incrementamos la versión de toda entidad MODIFICADA.
    // EF Core compara el valor ANTERIOR (el leído de la base de datos) en la
    // cláusula WHERE del UPDATE, y escribe el nuevo:
    //     UPDATE doctors SET last_name = ..., version = 4 WHERE id = 1 AND version = 3
    //
    // ChangeTracker: el "seguimiento de cambios" del DbContext. Sabe, para
    // cada entidad cargada, si fue agregada (Added), modificada
    // (Modified), eliminada (Deleted) o dejada como estaba (Unchanged).
    //
    // Todas las variantes de SaveChanges(Async) terminan en este método.
    // -----------------------------------------------------------------------
    public override Task<int> SaveChangesAsync(bool acceptAllChangesOnSuccess, CancellationToken cancellationToken = default)
    {
        foreach (var entry in ChangeTracker.Entries<AbstractEntity>())
        {
            if (entry.State == EntityState.Modified)
            {
                entry.Entity.Version++;
            }
        }
        return base.SaveChangesAsync(acceptAllChangesOnSuccess, cancellationToken);
    }
}

Comentemos este código:

  • línea 29: como en el Ejemplo 28, el [DbContext] recibe sus opciones (proveedor [MySQL], cadena de conexión) de [AddDbContext], dentro de [Program.cs]. Se registra con el ciclo de vida [Scoped]: un [DbContext] por solicitud, compartido por todos los repositorios de esa solicitud, es decir, una sola conexión y, en su caso, una sola transacción. Cumple así las funciones tanto del [DataSource] como del [Repository<T>] de [TypeORM];
  • líneas 33–37: un [DbSet] por tabla. No hay ninguno para [AbstractEntity] ni para [Person]: estas clases abstractas no tienen tablas. EF Core no las incluye en el modelo como entidades; simplemente agrega sus propiedades a las de las clases hijas;
  • línea 39: [OnModelCreating] se llama una sola vez, cuando EF Core construye su modelo (la descripción de las tablas y las relaciones). Complementa los atributos de las entidades con una API fluida: una cadena de llamadas a métodos;
  • líneas 47–48: la relación entre un médico (un cliente) y su cuenta es “uno a uno”: [HasOne(d => d.User)] (un médico tiene una cuenta), [WithOne()] (una cuenta tiene como máximo un médico; los paréntesis vacíos indican que [User] no tiene navegación inversa), [HasForeignKey<Doctor>(d => d.UserId)] (la clave externa está en la tabla [doctors]). Sin estas líneas, EF Core supondría una relación “muchos a uno” (varios médicos para una sola cuenta), que también funcionaría pero describiría de forma inexacta el modelo: en la base de datos, la columna [user] es única;
  • línea 52: [HasConversion<string>()] almacena el rol en la base de datos como texto (['ADMIN']...) y lo convierte de nuevo a [Role] al leerlo;
  • líneas 68–77: el número de versión de cada entidad modificada se incrementa justo antes de guardar, como en el Ejemplo 28. [ChangeTracker.Entries<AbstractEntity>()] recorre todas las entidades rastreadas cuya clase deriva de [AbstractEntity]: gracias a la clase padre común, este único bucle se aplica a las cinco tablas. La variante de [SaveChangesAsync] se redefine con dos parámetros, porque es esta variante la que, en última instancia, llama a [SaveChangesAsync()] sin parámetros. EF Core compara la versión anterior en la cláusula [WHERE] de [UPDATE] y escribe la nueva: si la fila ha cambiado entretanto, no se modifica ninguna fila y EF Core lanza una [DbUpdateConcurrencyException].

11.10. El dominio: el calendario

La carpeta [Domain] contiene dos clases que no corresponden a ninguna tabla: describen la agenda de un médico para un solo día, calculada por la capa de negocio ([BusinessService.GetDoctorDayScheduleAsync]) y mostrada por el controlador de la agenda.

11.10.1. Domain/DoctorDaySlot.cs

// =========================================================================
// Domain/DoctorDaySlot.cs
// -------------------------------------------------------------------------
// Un objeto "de negocio" (sin tabla) que asocia una franja horaria con la
// cita eventualmente reservada en esa franja, en un día dado.
//
// Un "record" de C# es una clase cuyas propiedades se asignan una vez
// por todas en el constructor (objeto inmutable): exactamente lo que se necesita
// para un objeto calculado, que nadie modifica después.
// =========================================================================

using RdvMedecins.Entities;

namespace RdvMedecins.Domain;

// Appointment? : null si la franja está libre ese día
public record DoctorDaySlot(Slot Slot, Appointment? Appointment);
  • Línea 17: una franja horaria y la cita programada en esa franja ese día, [null] si la franja está disponible (de ahí el tipo [Appointment?]). Un [record] escrito de esta manera, con sus parámetros entre paréntesis (record posicional), declara en una sola línea una clase, su constructor y sus propiedades [Slot] y [Appointment], que no se pueden modificar después de la construcción: esto equivale a la sintaxis [constructor(public slot: Slot, ...)] de la versión [NestJS]. Ya hemos visto los records de los datos transmitidos a la capa de negocio (véase el Ejemplo 28).

11.10.2. Domain/DoctorDaySchedule.cs

// =========================================================================
// Domain/DoctorDaySchedule.cs
// -------------------------------------------------------------------------
// La agenda completa de un médico para un día dado: la lista de sus
// franjas horarias, cada una libre u ocupada por una cita. Calculada por
// BusinessService.GetDoctorDayScheduleAsync, convertida en una tabla HTML por
// ScheduleController.
// =========================================================================

using RdvMedecins.Entities;

namespace RdvMedecins.Domain;

public record DoctorDaySchedule(Doctor Doctor, DateOnly Day, List<DoctorDaySlot> DoctorDaySlots);

La agenda (línea 14): un médico, un día y la lista de sus franjas horarias disponibles u ocupadas, en orden cronológico.

11.11. La capa DAO

Una clase por tabla, como en el Ejemplo 28: métodos cortos, sin lógica de negocio, que simplemente consultan o modifican la base de datos. Aquí se llaman “repositorios”, como en la versión [NestJS]. Dos diferencias con respecto a esa versión:

  • las consultas se escriben en [LINQ], que EF Core traduce a SQL: se navega de una entidad a otra mediante propiedades de navegación y EF Core escribe las uniones por sí mismo;
  • los métodos no tienen un parámetro [manager] para las transacciones: todos los repositorios de una solicitud comparten el mismo [DbContext], y una transacción abierta en este [DbContext] por la capa de negocio abarca automáticamente todas sus consultas.

Todos los métodos son asíncronos y devuelven una [Task]: quien llama la espera con [await]. Muchos se escriben en la forma [=> expression]: devuelven directamente la [Task] de la consulta, sin [async] ni [await], ya que no tienen nada más que hacer después.

11.11.1. Repositories/PersonRepository.cs

En la versión [NestJS], los repositorios de médicos y clientes eran idénticos, salvo por una sola línea. En [C#], una clase genérica los escribe una sola vez.

// =========================================================================
// Repositories/PersonRepository.cs
// -------------------------------------------------------------------------
// La capa DAO común a los médicos y a los clientes.
//
// Los dos DAO del proyecto NestJS (DoctorRepository, ClientRepository)
// eran idénticos salvo por una línea. En C#, una clase GENÉRICA los escribe
// una sola vez: PersonRepository<T>, donde T es Doctor o Client.
// "where T : Person" garantiza que T tiene LastName, FirstName, User...
//
// Transacciones: los métodos ya no necesitan el parámetro opcional EntityManager
// de TypeORM. Todos los repositorios de una solicitud comparten el
// MISMO DbContext (ver Data/RdvMedecinsDbContext.cs): cuando la capa de negocio
// abre una transacción sobre este DbContext, todas sus consultas forman
// parte de ella automáticamente.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public abstract class PersonRepository<T>(RdvMedecinsDbContext db) where T : Person
{
    protected readonly RdvMedecinsDbContext db = db;

    // la "tabla" de las personas de tipo T (db.Doctors o db.Clients)
    protected DbSet<T> Table => db.Set<T>();

    // lista ordenada por apellido y luego por nombre, con la cuenta de usuario incluida.
    // Include(p => p.User): TAMBIÉN trae la cuenta, mediante una unión (join)
    // (SELECT ... FROM doctors INNER JOIN users ...). Sin esto, p.User
    // sería null.
    // AsNoTracking(): estas listas las conserva en memoria el caché
    // (Web/ApplicationModel.cs), mucho más allá de la solicitud HTTP: es inútil
    // (y costoso) que el DbContext les haga seguimiento.
    public Task<List<T>> FindAllAsync() =>
        Table.AsNoTracking().Include(p => p.User).OrderBy(p => p.LastName).ThenBy(p => p.FirstName).ToListAsync();

    public Task<T?> FindByIdAsync(int id) =>
        Table.Include(p => p.User).FirstOrDefaultAsync(p => p.Id == id);

    // la persona cuya cuenta de usuario es [userId], o null
    public Task<T?> FindByUserIdAsync(int userId) =>
        Table.Include(p => p.User).FirstOrDefaultAsync(p => p.UserId == userId);

    // la persona que tiene este nombre y apellido, si existe. La comparación
    // la hace MySQL, por lo tanto con la collation de la base de datos
    // (utf8mb4_unicode_ci: sin distinguir mayúsculas ni acentos) -
    // exactamente la misma regla que la de la restricción SQL de unicidad.
    public Task<T?> FindByFirstNameLastNameAsync(string firstName, string lastName) =>
        Table.FirstOrDefaultAsync(p => p.FirstName == firstName && p.LastName == lastName);

    // creación (Id = 0: aún no está en la base de datos) o actualización (entidad ya
    // con seguimiento del DbContext: SaveChanges detecta por sí mismo lo que cambió)
    public async Task<T> SaveAsync(T person)
    {
        if (person.Id == 0)
        {
            Table.Add(person);
        }
        await db.SaveChangesAsync();
        return person;
    }

    // ExecuteDeleteAsync (EF Core 7+): un DELETE enviado directamente a la base de datos,
    // sin cargar antes las entidades:  DELETE FROM doctors WHERE id = ?
    public Task DeleteByIdAsync(int id) => Table.Where(p => p.Id == id).ExecuteDeleteAsync();
}

// los dos DAO concretos: todo se hereda
public class DoctorRepository(RdvMedecinsDbContext db) : PersonRepository<Doctor>(db);

public class ClientRepository(RdvMedecinsDbContext db) : PersonRepository<Client>(db)
{
    // -----------------------------------------------------------------------
    // lee un cliente poniendo un BLOQUEO sobre su fila hasta el final de la
    // transacción en curso (SELECT ... FOR UPDATE). Una segunda transacción
    // que solicite el mismo bloqueo ESPERA a que la primera termine.
    // Se usa para reservar citas (ver BusinessService.AddAppointmentAsync):
    // dos reservas simultáneas para el mismo paciente se procesan así
    // una DESPUÉS de la otra, y la segunda ve la cita creada por la primera.
    //
    // LINQ no puede expresar "FOR UPDATE": escribimos nosotros mismos la consulta SQL.
    // FromSqlInterpolated convierte {id} en un PARÁMETRO SQL (sin
    // concatenación de cadenas, por lo tanto sin posible inyección SQL).
    // -----------------------------------------------------------------------
    public async Task<Client?> LockAsync(int id)
    {
        var clients = await Table.FromSqlInterpolated($"SELECT * FROM clients WHERE id = {id} FOR UPDATE").ToListAsync();
        return clients.FirstOrDefault();
    }
}

Comentemos este código:

  • Línea 24: [PersonRepository<T>] es una clase genérica; [T] es un parámetro de tipo, sustituido por un tipo concreto ([Doctor] o [Client]) cuando se usa la clase, como [T] en [List<T>]. La restricción [where T : Person] solo acepta [Person] o sus clases hijas para [T]: el compilador sabe entonces que un [T] contiene [Id], [LastName], [FirstName], [UserId], [User]... y acepta [p.LastName] en las consultas. La clase es abstracta: solo se usan sus dos clases hijas, que se listan más abajo;
  • línea 26: el parámetro [db] del constructor principal solo es visible dentro de esta clase. Se copia en un campo [protected] para que las clases hijas ([ClientRepository]) puedan acceder a él;
  • línea 29: la tabla de personas de tipo [T]. [db.Set<T>()] asocia [DbSet] a este tipo: [db.Doctors] for [T = Doctor], [db.Clients] para [T = Client];
  • líneas 38–39: todas las personas, ordenadas por apellido y luego por nombre ([OrderBy], luego [ThenBy] para desempatar apellidos idénticos). [Include(p => p.User)] carga además la cuenta de cada persona mediante una unión ([INNER JOIN users]): sin ella, [p.User] equivaldría a [null]. La cuenta se usa para mostrar el nombre de usuario en las listas. [AsNoTracking()] (véase el Ejemplo 28): estas listas las conserva en memoria [ApplicationModel] mucho después de que termine la consulta; no hay necesidad de que el [DbContext] las procese. Las expresiones como [p => p.LastName] no se ejecutan en [C#]: EF Core las analiza para traducirlas a SQL ([ORDER BY last_name, first_name]);
  • líneas 41–42: una persona y su cuenta, o [null]. Aquí no hay [AsNoTracking()]: la capa de negocio modifica la persona recuperada (y su cuenta) y luego llama a [SaveAsync]; el [DbContext], que rastrea ambos objetos, sabe qué ha cambiado;
  • líneas 45–46: la persona cuya cuenta es [userId]. Así es como un paciente conectado, cuyo token contiene el identificador de la cuenta, recupera su ficha de cliente. El filtro apunta a la propia clave externa ([WHERE clients.user = ...]); la unión con [users] sirve solo para cargar la cuenta ([Include]);
  • líneas 52–53: un posible homónimo. El operador [==] se convierte en el [=] de SQL: la comparación la realiza [MySQL], según la intercalación de la base de datos, sin distinguir mayúsculas ni acentos, exactamente como en la restricción de unicidad (véase el Ejemplo 28). Una comparación realizada con [C#] sí distinguiría las mayúsculas;
  • líneas 57–64: creación o modificación, como en el Ejemplo 28: una persona nueva ([Id] igual a 0) se agrega al [DbSet]; una persona que ya está en el sistema no requiere ninguna acción. Nota: [SaveChangesAsync] registra todos los cambios pendientes del [DbContext], no solo los de [person]: la cuenta modificada al mismo tiempo se incluye en la misma llamada;
  • línea 69: eliminación mediante [ExecuteDeleteAsync] (véase el Ejemplo 28): un [DELETE] enviado directamente a la base de datos, sin lectura previa. No pasa por el seguimiento de cambios y, por lo tanto, tampoco por el bloqueo optimista;
  • línea 73: el repositorio de los médicos: [PersonRepository<Doctor>], sin nada más. Reenvía el [DbContext] recibido al constructor de su clase padre; el punto y coma final reemplaza un cuerpo de clase vacío;
  • línea 75: el repositorio de clientes, con un método adicional;
  • líneas 89–92: lectura de un cliente con un bloqueo: [SELECT ... FOR UPDATE] coloca un bloqueo sobre la fila hasta el final de la transacción en curso; otra transacción que solicite el mismo bloqueo espera hasta que la primera termine. El método de programación de citas ([BusinessService.AddAppointmentAsync]) lo utiliza para procesar una tras otra dos reservas simultáneas para el mismo paciente: la segunda reserva ve la cita creada por la primera y, por lo tanto, respeta la regla de “una sola cita futura”. [LINQ] no puede expresar [FOR UPDATE]: hay que escribir uno mismo el SQL de la consulta mediante [FromSqlInterpolated]. La cadena [$"..."] es una cadena interpolada; [FromSqlInterpolated] no la copia tal cual: cada valor encerrado entre llaves ([{id}]) se convierte en un parámetro SQL. Por lo tanto, no hay concatenación de cadenas y no es posible la inyección SQL. La consulta se ejecuta tal cual ([ToListAsync]) y se toma el primer cliente de la lista resultante ([FirstOrDefault], en memoria): un operador [LINQ] agregado después de [FromSqlInterpolated] haría que EF Core envolviera nuestro SQL en una subconsulta.

11.11.2. Repositories/SlotRepository.cs

// =========================================================================
// Repositories/SlotRepository.cs
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Slot].
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class SlotRepository(RdvMedecinsDbContext db)
{
    public Task<Slot?> FindByIdAsync(int id) =>
        db.Slots.Include(s => s.Doctor).FirstOrDefaultAsync(s => s.Id == id);

    // las franjas de un médico, en orden cronológico
    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) =>
        db.Slots
            .Where(s => s.DoctorId == doctorId)
            .OrderBy(s => s.StartHour)
            .ThenBy(s => s.StartMinute)
            .ToListAsync();

    // elimina todas las franjas de un médico (eliminación de un médico):
    //   DELETE FROM slots WHERE doctor_id = ?
    public Task DeleteByDoctorAsync(int doctorId) =>
        db.Slots.Where(s => s.DoctorId == doctorId).ExecuteDeleteAsync();
}
  • líneas 15–16: una franja de cita, con su médico ([Include]);
  • líneas 19–24: las franjas horarias de un médico, en orden cronológico: [Where] filtra, [OrderBy] y [ThenBy] ordenan (por hora y luego por minuto de inicio). La consulta se construye método por método, como con QueryBuilder de [TypeORM], y solo se ejecuta cuando se llama a [ToListAsync]: [SELECT ... FROM slots WHERE doctor_id = @p ORDER BY start_hour, start_minute]. El valor [doctorId] también se pasa como parámetro a SQL;
  • líneas 28–29: eliminación de las franjas de citas de un médico mediante un solo [DELETE]. La capa de negocio lo llama antes de eliminar al médico; de lo contrario, la clave externa [slots.doctor_id] impediría la eliminación.

11.11.3. Repositories/AppointmentRepository.cs

// =========================================================================
// Repositories/AppointmentRepository.cs
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Appointment].
//
// Las consultas se escriben en LINQ: EF Core las traduce a SQL. Navegamos
// de una entidad a otra mediante las propiedades de navegación (a.Slot.DoctorId),
// y EF Core escribe por sí mismo las uniones necesarias.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class AppointmentRepository(RdvMedecinsDbContext db)
{
    public Task<Appointment?> FindByIdAsync(int id) =>
        db.Appointments.Include(a => a.Client).Include(a => a.Slot).FirstOrDefaultAsync(a => a.Id == id);

    public async Task<Appointment> SaveAsync(Appointment appointment)
    {
        if (appointment.Id == 0)
        {
            db.Appointments.Add(appointment);
        }
        await db.SaveChangesAsync();
        return appointment;
    }

    public Task DeleteByIdAsync(int id) => db.Appointments.Where(a => a.Id == id).ExecuteDeleteAsync();

    // las citas de un médico en un día dado, con cliente y franja incluidos.
    // a.Slot.DoctorId: la tabla [appointments] no referencia directamente
    // al médico; EF Core pasa por la unión con [slots].
    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) =>
        db.Appointments
            .Include(a => a.Client)
            .Include(a => a.Slot)
            .Where(a => a.Slot.DoctorId == doctorId && a.Day == day)
            .ToListAsync();

    // las citas de un cliente a partir del día [fromDay] (incluido), en
    // orden cronológico, con la franja Y el médico de esa franja
    // (Include y luego ThenInclude: cita -> franja -> médico)
    public Task<List<Appointment>> FindUpcomingByClientAsync(int clientId, DateOnly fromDay) =>
        db.Appointments
            .Include(a => a.Slot).ThenInclude(s => s.Doctor)
            .Where(a => a.ClientId == clientId && a.Day >= fromDay)
            .OrderBy(a => a.Day)
            .ThenBy(a => a.Slot.StartHour)
            .ThenBy(a => a.Slot.StartMinute)
            .ToListAsync();

    // cantidad de citas de un cliente a partir del día [fromDay] (incluido)
    public Task<int> CountUpcomingByClientAsync(int clientId, DateOnly fromDay) =>
        db.Appointments.CountAsync(a => a.ClientId == clientId && a.Day >= fromDay);

    // elimina TODAS las citas (pasadas y futuras) de un cliente:
    //   DELETE FROM appointments WHERE client_id = ?
    public Task DeleteByClientAsync(int clientId) =>
        db.Appointments.Where(a => a.ClientId == clientId).ExecuteDeleteAsync();

    // cantidad de citas (pasadas o futuras) de un médico:
    //   SELECT COUNT(*) FROM appointments INNER JOIN slots s ON ... WHERE s.doctor_id = ?
    public Task<int> CountByDoctorAsync(int doctorId) =>
        db.Appointments.CountAsync(a => a.Slot.DoctorId == doctorId);
}

Comentemos este código:

  • líneas 19–20: una cita con su cliente y su franja horaria: dos registros [Include], por lo tanto dos uniones;
  • líneas 22–29: mismo patrón que para las personas. En la práctica, solo se usa para la creación: la capa de negocio genera una [Appointment] en la que solo están rellenadas las claves externas; después de [SaveChangesAsync], [appointment.Id] contiene el identificador asignado por la base de datos;
  • línea 32: cancelación de una cita;
  • líneas 37–42: las citas de un médico para un día determinado, cada una con su paciente y su franja horaria (el equivalente de [leftJoinAndSelect] en la versión [NestJS]). La tabla [appointments] no hace referencia directamente a los médicos: el filtro [a.Slot.DoctorId == doctorId] pasa por la navegación [Slot], y EF Core agrega la unión con [slots]. Es importante distinguir los dos usos de una navegación: en [Where], se usa para filtrar; solo [Include] carga el objeto en el resultado;
  • líneas 47–54: las citas de un cliente a partir del día [fromDay], junto con su franja horaria y el médico de esa franja: [Include(a => a.Slot)] carga la franja horaria y luego [ThenInclude(s => s.Doctor)] carga el médico de esa franja (dos uniones en cascada). El orden se basa primero en el día y luego en la hora de la franja horaria. Esto es lo que se muestra en “Mi área”;
  • líneas 57–58: el número de esas citas ([SELECT COUNT(*)]), para la regla de “una sola cita futura”. [CountAsync] acepta directamente la condición, al igual que [FirstOrDefaultAsync];
  • líneas 62–63: la eliminación de todas las citas de un cliente, pasadas y futuras: la capa de negocio la llama antes de eliminar al cliente, algo que la clave externa [appointments.client_id] impediría de otro modo;
  • líneas 67–68: el número de citas de un médico, para impedir la eliminación de un médico que tenga alguna. Una vez más, la navegación [a.Slot] genera una unión ([INNER JOIN slots]) sin cargar nada: es el [innerJoin] de la versión [NestJS].

11.11.4. Repositories/UserRepository.cs

// =========================================================================
// Repositories/UserRepository.cs
// -------------------------------------------------------------------------
// Capa DAO de la entidad [User]. Crear (o eliminar) un médico o un
// cliente también crea (o elimina) su cuenta - ver Business/BusinessService.cs.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class UserRepository(RdvMedecinsDbContext db)
{
    // null si ningún usuario tiene este login
    public Task<User?> FindByLoginAsync(string login) => db.Users.FirstOrDefaultAsync(u => u.Login == login);

    public async Task<User> SaveAsync(User user)
    {
        if (user.Id == 0)
        {
            db.Users.Add(user);
        }
        await db.SaveChangesAsync();
        return user;
    }

    public Task DeleteByIdAsync(int id) => db.Users.Where(u => u.Id == id).ExecuteDeleteAsync();
}
  • línea 17: la cuenta asociada a este nombre de usuario, o [null]. Se usa para iniciar sesión ([AuthService]) y para verificar que un nombre de usuario esté disponible antes de asignarlo;
  • Líneas 19–26: creación o modificación de una cuenta. Para crear un médico o un cliente, primero hay que crear su cuenta: la persona necesita el identificador de la cuenta para su clave externa;
  • línea 29: eliminación de una cuenta. El orden es inverso al de la creación: la capa de negocio elimina primero a la persona, que hace referencia a la cuenta, y luego elimina la cuenta.

11.12. La capa de negocio

La capa de negocio contiene las reglas de negocio de la aplicación: no se permiten citas en el pasado, solo una cita futura por paciente, nombres de usuario y personas únicos, y la eliminación de un médico o un cliente. Se apoya en la capa DAO (carpeta [Repositories]) para leer y escribir, y no sabe nada de HTML ni del idioma de la interfaz. Más concretamente, es la capa [PersonsBusiness] del Ejemplo 28.

11.12.1. Business/Dates.cs

// =========================================================================
// Business/Dates.cs
// -------------------------------------------------------------------------
// La fecha de hoy. La usan las REGLAS DE NEGOCIO (ninguna reserva
// en el pasado, una sola cita PRÓXIMA por paciente): por lo tanto vive
// en la capa de negocio. La capa web la reutiliza.
// =========================================================================

namespace RdvMedecins.Business;

public static class Dates
{
    // la fecha de hoy, en la zona horaria del servidor
    public static DateOnly Today() => DateOnly.FromDateTime(DateTime.Now);
}
  • línea 11: una clase [static] no se instancia; simplemente agrupa métodos, que se llaman por el nombre de la clase ([Dates.Today()]);
  • línea 14: la fecha de hoy, en la zona horaria del servidor. [DateTime.Now] devuelve tanto la fecha como la hora; [DateOnly.FromDateTime] devuelve solo la fecha (el tipo [DateOnly] se trató en el Ejemplo 12; es el formato de la columna [appointments.day]). Dos valores [DateOnly] pueden compararse directamente con [<] o [>=]; la versión [NestJS], que procesaba cadenas [yyyy-mm-dd], tenía que generar ese formato por sí misma. La fecha actual se usa para las reglas de negocio, por lo que reside en la capa de negocio; la capa web la reutiliza (por ejemplo, en [ScheduleController], para determinar si un día todavía admite reservas).

11.12.2. Business/BusinessException.cs

// =========================================================================
// Business/BusinessException.cs
// -------------------------------------------------------------------------
// La excepción que lanza la capa de negocio cuando se VIOLA una REGLA DE NEGOCIO
// (login ya en uso, médico que todavía tiene citas, franja
// ya reservada...). No lleva un texto, sino una
// CLAVE de traducción (p. ej. "ERRORS.LOGIN_TAKEN"): es la capa web la que la
// traducirá al francés o al inglés al mostrar la página
// (ver i18n/fr.json, i18n/en.json).
//
// Una BusinessException no es una anomalía: es una respuesta normal
// ("este login ya está en uso"), que se muestra al usuario. Cualquier otra
// excepción es una verdadera anomalía, que termina en la página de error 500.
// =========================================================================

namespace RdvMedecins.Business;

public class BusinessException(string key, IReadOnlyDictionary<string, string>? messageParams = null) : Exception(key)
{
    // clave de traducción del mensaje
    public string Key { get; } = key;

    // posibles parámetros del mensaje ({minutes}...)
    public IReadOnlyDictionary<string, string> Params { get; } = messageParams ?? new Dictionary<string, string>();
}
  • Línea 18: la excepción lanzada cuando una regla de negocio rechaza una transacción (véase el Ejemplo 28). La clase usa un constructor principal (los parámetros [key] y [messageParams] se listan después del nombre de la clase); [: Exception(key)] pasa la clave al constructor de la clase padre [Exception], que la establece como la propiedad [Message] (útil en los registros de errores). Diferencia con el Ejemplo 28: la excepción no lleva un texto en inglés, sino una clave de traducción ([ERRORS.LOGIN_TAKEN]). Así, la capa de negocio ignora el idioma de la interfaz: es la capa web la que traducirá la clave, mediante los diccionarios [i18n/fr.json] y [i18n/en.json] (véase el Capítulo 5);
  • línea 21: la clave de traducción, de solo lectura ([get] sin [set]);
  • línea 24: los parámetros opcionales del mensaje, que reemplazarán marcadores como [{minutes}] en el texto traducido. [IReadOnlyDictionary] es un diccionario de solo lectura. El operador [??] devuelve un diccionario vacío cuando no se proporcionan parámetros: la capa web nunca necesita comprobar si hay [null]. En realidad, las excepciones lanzadas por [BusinessService] solo usan claves sin parámetros.

Una [BusinessException] no es un error: es una respuesta normal (“este nombre de usuario ya está en uso”), que los controladores interceptan para mostrarla al usuario, ya sea en la página o en un mensaje emergente. Cualquier otra excepción es un error verdadero, que da como resultado una página de error 500.

11.12.3. Business/IBusiness.cs

// =========================================================================
// Business/IBusiness.cs
// -------------------------------------------------------------------------
// El contrato de la capa de negocio: lecturas, agenda, citas, gestión
// de los médicos y de los clientes.
//
// Convención de .NET: un método asíncrono devuelve un Task<T> (el equivalente
// de una Promise<T>) y su nombre termina en "Async".
// =========================================================================

using RdvMedecins.Domain;
using RdvMedecins.Entities;

namespace RdvMedecins.Business;

// los datos escritos en el formulario de "médico" o de "cliente"
public record PersonData
{
    public required string Title { get; init; } // Mr, Mme, Melle
    public required string LastName { get; init; }
    public required string FirstName { get; init; }

    // creación: opcional, por defecto el apellido en minúsculas
    // actualización: opcional, el login no cambia si está ausente
    public string? Login { get; init; }

    // creación: opcional, por defecto el login
    // actualización: opcional, la contraseña no cambia si está ausente
    public string? Password { get; init; }

    // actualización: la versión del registro en el momento en que se mostró
    // el formulario (bloqueo optimista, ver AbstractEntity.Version)
    public int? Version { get; init; }
}

public interface IBusiness
{
    // ------------------------------------------------ lecturas
    Task<List<Client>> GetAllClientsAsync();
    Task<List<Doctor>> GetAllDoctorsAsync();
    Task<List<Slot>> GetAllSlotsAsync(int doctorId);
    Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day);
    Task<Client?> GetClientByIdAsync(int id);
    Task<Doctor?> GetDoctorByIdAsync(int id);
    Task<Appointment?> GetAppointmentByIdAsync(int id);
    Task<Slot?> GetSlotByIdAsync(int id);
    Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day);

    /// <summary>el cliente (paciente) cuya cuenta de usuario es [userId], o null</summary>
    Task<Client?> GetClientByUserIdAsync(int userId);

    /// <summary>las citas de un cliente, de hoy o futuras, con franja y médico</summary>
    Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId);

    // ------------------------------------------------ citas (ADMIN, DOCTOR, USER)
    /// <summary>
    /// lanza una BusinessException si:
    ///  - el día está en el pasado ("ERRORS.PAST_DATE");
    ///  - el paciente ya tiene una cita próxima ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    ///  - la franja ya está reservada ese día ("ERRORS.SLOT_ALREADY_BOOKED").
    /// </summary>
    Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client);

    Task DeleteAppointmentAsync(Appointment appointment);

    // ------------------------------------------------ médicos (ADMIN)
    /// <summary>crea el médico Y su cuenta de usuario (rol DOCTOR)</summary>
    Task<Doctor> AddDoctorAsync(PersonData data);

    /// <summary>actualiza el médico Y su cuenta de usuario</summary>
    Task<Doctor> EditDoctorAsync(int id, PersonData data);

    /// <summary>elimina el médico, sus franjas Y su cuenta - se rechaza si tiene citas</summary>
    Task DeleteDoctorAsync(int id);

    // ------------------------------------------------ clientes
    // (el ADMIN; AddClientAsync también se usa para el registro de un paciente,
    // EditClientAsync y DeleteClientAsync los usa el paciente para su propia cuenta)
    /// <summary>crea el cliente Y su cuenta de usuario (rol USER)</summary>
    Task<Client> AddClientAsync(PersonData data);

    Task<Client> EditClientAsync(int id, PersonData data);

    /// <summary>
    /// elimina el cliente, su cuenta Y todas sus citas (pasadas y futuras).
    /// Lo usan el ADMIN (página "Patients") y el propio paciente ("Manage my account").
    /// </summary>
    Task DeleteClientAsync(int id);
}
  • Líneas 17–33: los datos de un médico o cliente que se va a crear o modificar, tal como los transmite la capa web (véase el Ejemplo 28). [required] exige el título, el apellido y el nombre; [init] impide que se modifiquen posteriormente (véase el Ejemplo 18). El nombre de usuario y la contraseña son opcionales ([string?]): al crear, por defecto toman el apellido en minúsculas; al modificar, solo cambian si se han introducido. [Version] es la versión del registro leído cuando se muestra el formulario de edición: se usa para el bloqueo optimista (véase más abajo);
  • línea 36: el contrato de la capa de negocio: lo que las demás capas pueden solicitarle, sin especificar cómo se hace (las interfaces se trataron en el Ejemplo 06). Por convención, en [.NET], un método asíncrono devuelve un [Task<T>] (el equivalente de una [Promise<T>] de [JavaScript]) y su nombre termina en [Async];
  • líneas 39–53: las lecturas. Un tipo seguido de [?] ([Task<Client?>]) indica que el método puede devolver [null]: nadie tiene ese identificador. Los comentarios [/// <summary>] son comentarios de documentación: [Visual Studio Code] los muestra al pasar el cursor sobre el método;
  • líneas 57–64: las citas. El comentario de [AddAppointmentAsync] lista los posibles códigos de error: esto forma parte del contrato que los evaluadores deben conocer;
  • líneas 68–74: gestión de médicos (reservada a ADMIN). Cada médico se crea, modifica y elimina junto con su cuenta de usuario;
  • líneas 80–88: gestión de clientes, con la misma lógica. [AddClientAsync] se usa también para registrar a un paciente, mientras que [EditClientAsync] y [DeleteClientAsync] son para los pacientes que gestionan sus propias cuentas.

La implementación se registra en [Program.cs] mediante la línea [builder.Services.AddScoped<IBusiness, BusinessService>()]: “cuando un constructor solicite un [IBusiness], proporciónele un [BusinessService]”, uno por solicitud ([Scoped]), igual que el [DbContext] y los DAO que utiliza (véanse el Ejemplo 28 y el Capítulo 6). Con [NestJS], una interfaz [TypeScript] desaparecía en tiempo de compilación: eran necesarios un token ([BUSINESS_TOKEN]) y [@Inject(BUSINESS_TOKEN)]. En [C#], las interfaces existen en tiempo de ejecución: la propia interfaz sirve de token. El único servicio que recibe un [IBusiness] es [ApplicationModel] (carpeta [Web]), que también implementa [IBusiness]: los controladores ven así el mismo contrato, enriquecido con una caché de listas de médicos y clientes.

11.12.4. Business/BusinessService.cs

Este es el archivo más completo de la aplicación. Lo mostraremos en cinco extractos sucesivos.

11.12.4.1. Los descriptores

// =========================================================================
// Business/BusinessService.cs
// -------------------------------------------------------------------------
// Implementación de la capa de negocio.
//
// La gestión de los médicos y los clientes obedece a tres reglas de negocio:
//
//   1. una persona (médico o cliente) y su cuenta de usuario van
//      SIEMPRE juntas: se crean, actualizan y eliminan juntas, en
//      la misma TRANSACCIÓN - o todo tiene éxito, o no se escribe nada;
//   2. el login es único en toda la aplicación, y dos médicos (o
//      dos clientes) no pueden tener el mismo nombre y apellido;
//   3. eliminación:
//      - un MÉDICO que tiene citas no se puede eliminar (sus
//        pacientes perderían su cita sin ser avisados): primero se deben
//        cancelar. Sus franjas horarias desaparecen con él;
//      - un CLIENTE, en cambio, desaparece con TODAS sus citas (pasadas y
//        futuras), ya sea que la eliminación provenga del ADMIN o del
//        propio paciente.
//
// Y dos reglas para reservar citas, sea cual sea el rol de
// quien reserva (ADMIN, DOCTOR o el propio paciente):
//   4. ninguna cita en el pasado;
//   5. un paciente tiene una SOLA cita próxima a la vez.
//
// Los médicos y los clientes siguen exactamente las mismas reglas: el código común
// se escribe UNA sola vez (métodos privados genéricos XxxPersonAsync<T>), y
// se parametriza con un pequeño "descriptor" que indica de qué tipo de persona
// se trata.
// =========================================================================

using System.Text.RegularExpressions;
using Microsoft.EntityFrameworkCore;
using MySqlConnector;
using RdvMedecins.Data;
using RdvMedecins.Domain;
using RdvMedecins.Entities;
using RdvMedecins.Repositories;

namespace RdvMedecins.Business;

public class BusinessService : IBusiness
{
    // número de rondas de salting de bcrypt - el mismo que en el script SQL ($2b$10$...)
    private const int BcryptRounds = 10;

    // todo lo que distingue a un médico de un cliente para las reglas de negocio.
    // "where T : Person, new()": T es una Person, y podemos escribir new T().
    private record PersonDescriptor<T>(
        PersonRepository<T> Dao,
        Role Role, // DOCTOR o USER
        string NotFoundKey, // mensaje si la persona no existe
        string AlreadyExistsKey, // mensaje si ya existen el mismo nombre y apellido
        // opcional: si está presente, la eliminación se RECHAZA mientras la
        // persona tenga citas (CountAppointments > 0), con el mensaje HasAppointmentsKey
        Func<int, Task<int>>? CountAppointments = null,
        string? HasAppointmentsKey = null,
        // opcional: lo que se debe eliminar ANTES de la persona (las filas que
        // la referencian mediante una clave externa)
        Func<int, Task>? BeforeDelete = null) where T : Person, new();

    private readonly RdvMedecinsDbContext db;
    private readonly DoctorRepository doctorRepository;
    private readonly ClientRepository clientRepository;
    private readonly SlotRepository slotRepository;
    private readonly AppointmentRepository appointmentRepository;
    private readonly UserRepository userRepository;
    private readonly PersonDescriptor<Doctor> doctorDescriptor;
    private readonly PersonDescriptor<Client> clientDescriptor;

    // todas las dependencias las proporciona la inyección de dependencias
    // de ASP.NET Core (ver Program.cs). El DbContext se usa aquí SOLO para abrir
    // transacciones - las consultas propiamente dichas permanecen en la capa DAO.
    public BusinessService(
        RdvMedecinsDbContext db,
        DoctorRepository doctorRepository,
        ClientRepository clientRepository,
        SlotRepository slotRepository,
        AppointmentRepository appointmentRepository,
        UserRepository userRepository)
    {
        this.db = db;
        this.doctorRepository = doctorRepository;
        this.clientRepository = clientRepository;
        this.slotRepository = slotRepository;
        this.appointmentRepository = appointmentRepository;
        this.userRepository = userRepository;

        doctorDescriptor = new PersonDescriptor<Doctor>(
            doctorRepository,
            Role.DOCTOR,
            "ERRORS.DOCTOR_NOT_FOUND",
            "ERRORS.DOCTOR_ALREADY_EXISTS",
            CountAppointments: appointmentRepository.CountByDoctorAsync,
            HasAppointmentsKey: "ERRORS.DOCTOR_HAS_APPOINTMENTS",
            // un médico sin citas todavía puede tener franjas horarias:
            // ya no tienen sentido sin él, las eliminamos junto con el médico (de lo contrario
            // la clave externa slots.doctor_id impediría la eliminación)
            BeforeDelete: slotRepository.DeleteByDoctorAsync);

        clientDescriptor = new PersonDescriptor<Client>(
            clientRepository,
            Role.USER,
            "ERRORS.PATIENT_NOT_FOUND",
            "ERRORS.PATIENT_ALREADY_EXISTS",
            // sin CountAppointments: la eliminación de un cliente nunca se rechaza;
            // sus citas (pasadas y futuras) se eliminan con él (de lo contrario
            // la clave externa appointments.client_id impediría la eliminación)
            BeforeDelete: appointmentRepository.DeleteByClientAsync);
    }
  • líneas 6–29: el comentario de encabezado resume las cinco reglas de negocio que aplica la clase;
  • línea 34: el controlador [MySQL] (véase el Capítulo 9): la clase usa su excepción [MySqlException] para detectar las violaciones de las restricciones de unicidad;
  • línea 42: la clase implementa la interfaz; debe proporcionar todos sus métodos;
  • línea 45: el costo de [bcrypt] (véase el Ejemplo 25), que es el mismo que el de las contraseñas del script SQL (prefijo [$2b$10$]);
  • líneas 49–60: todo lo que distingue a un médico de un cliente en cuanto a reglas de negocio: su DAO, el rol de su cuenta ([DOCTOR] o [USER]), sus mensajes de error y lo que sucede cuando se eliminan. Como los médicos y los clientes siguen las mismas reglas, el código de estas reglas se escribe una sola vez, en métodos genéricos (parametrizados por un tipo [T]) que aceptan un descriptor. La restricción [where T : Person, new()] exige que [T] herede de [Person] (así podríamos leer [LastName], [FirstName], [User]...) y tenga un constructor sin parámetros (así podríamos escribir [new T()]). [Func<int, Task<int>>] es el tipo de una función que toma un [int] y devuelve un [Task<int>]; [Func<int, Task>] es el tipo de una función asíncrona que no devuelve nada. Estos parámetros tienen un valor predeterminado ([= null]): son opcionales;
  • líneas 62–69: los campos de la clase: el [DbContext], los cinco DAO y los dos descriptores. [readonly] impide que se modifiquen después del constructor;
  • líneas 74–87: todas las dependencias se proporcionan mediante inyección de dependencias. El [DbContext] se usa aquí solo para abrir transacciones: las consultas permanecen en la capa DAO. Como en el Ejemplo 28, los DAO y la capa de negocio reciben el mismo [DbContext] durante una solicitud y, por lo tanto, la misma conexión y la misma transacción;
  • líneas 89–99: el descriptor del médico. Los argumentos con nombre ([CountAppointments:], [HasAppointmentsKey:]...) hacen referencia a un parámetro por su nombre, lo que permite omitir parámetros opcionales (el descriptor del cliente, más abajo, omite así [CountAppointments] y [HasAppointmentsKey]). [appointmentRepository.CountByDoctorAsync] no se llama aquí: se pasa el método mismo, que se llamará más tarde (un método puede servir así como valor de tipo [Func]). La eliminación de un médico se denegará mientras tenga citas; en cambio, sus franjas horarias se eliminarán antes de eliminar al médico;
  • líneas 101–109: el descriptor del cliente. Sin [CountAppointments]: la eliminación de un cliente nunca se deniega, y sus citas (pasadas y futuras) se eliminan antes que el cliente; de lo contrario, la clave externa [appointments.client_id] impediría la eliminación.

11.12.4.2. Operaciones de lectura y el calendario

    // =======================================================================
    // lecturas
    // =======================================================================

    public Task<List<Client>> GetAllClientsAsync() => clientRepository.FindAllAsync();

    public Task<List<Doctor>> GetAllDoctorsAsync() => doctorRepository.FindAllAsync();

    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) => slotRepository.GetAllSlotsAsync(doctorId);

    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) =>
        appointmentRepository.GetDoctorDayAppointmentsAsync(doctorId, day);

    public Task<Client?> GetClientByIdAsync(int id) => clientRepository.FindByIdAsync(id);

    public Task<Doctor?> GetDoctorByIdAsync(int id) => doctorRepository.FindByIdAsync(id);

    public Task<Appointment?> GetAppointmentByIdAsync(int id) => appointmentRepository.FindByIdAsync(id);

    public Task<Slot?> GetSlotByIdAsync(int id) => slotRepository.FindByIdAsync(id);

    public Task<Client?> GetClientByUserIdAsync(int userId) => clientRepository.FindByUserIdAsync(userId);

    public Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId) =>
        appointmentRepository.FindUpcomingByClientAsync(clientId, Dates.Today());

    // mismo algoritmo que el servidor JSON (y que el proyecto Spring original)
    public async Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day)
    {
        var doctor = await GetDoctorByIdAsync(doctorId);
        if (doctor is null)
        {
            return null;
        }
        var timeSlots = await GetAllSlotsAsync(doctorId);
        var bookings = await GetDoctorDayAppointmentsAsync(doctorId, day);
        // n.º de franja -> cita reservada en esta franja
        var bookingsBySlot = bookings.ToDictionary(booking => booking.SlotId);
        var doctorDaySlots = timeSlots
            .Select(slot => new DoctorDaySlot(slot, bookingsBySlot.GetValueOrDefault(slot.Id)))
            .ToList();
        return new DoctorDaySchedule(doctor, day, doctorDaySlots);
    }
  • líneas 5–22: las operaciones de lectura simplemente delegan en la capa DAO. La sintaxis [=> expression] (un cuerpo de expresión) reemplaza un bloque [{ return expression; }]. Estos métodos no son [async]: devuelven directamente la [Task] del DAO, sin esperarla;
  • líneas 24–25: las citas futuras de un paciente: la capa de negocio proporciona la fecha actual al DAO;
  • líneas 28–42: cálculo de la agenda de un médico para un día determinado, con el mismo algoritmo que la versión [NestJS]. Un médico desconocido da como resultado [null]; de lo contrario, se leen las franjas horarias del médico y las citas del día;
  • línea 38: [ToDictionary] almacena las citas en un diccionario cuya clave es el identificador de la franja (equivalente a [Map] en la versión [NestJS]). El diccionario evita tener que recorrer la lista de citas para cada franja horaria;
  • líneas 39–41: cada franja horaria se asocia con su cita, o con [null] ([GetValueOrDefault] devuelve el valor predeterminado, [null], cuando falta la clave). [Select] transforma cada elemento de una lista (véase [LINQ], Capítulo 9). El resultado es un objeto [DoctorDaySchedule] de la carpeta [Domain], que mostrará la vista del calendario.

11.12.4.3. Programación de una cita

    // =======================================================================
    // citas
    // =======================================================================

    // -----------------------------------------------------------------------
    // reserva de una cita, en una transacción:
    //   1. ninguna cita en el pasado;
    //   2. BLOQUEAMOS la fila del paciente (SELECT ... FOR UPDATE): si el
    //      mismo paciente reserva dos franjas en el mismo instante (dos pestañas,
    //      doble clic...), la segunda transacción espera el fin de la
    //      primera - y entonces ve la cita que esta acaba de crear;
    //   3. una sola cita próxima por paciente;
    //   4. por último, la inserción. Si la franja acaba de ser tomada por OTRO
    //      paciente, es la restricción SQL unq1_appointments (day, slot_id) la que
    //      rechaza la inserción - traducida a una BusinessException por TransactionAsync.
    // -----------------------------------------------------------------------
    public Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client) =>
        TransactionAsync(async () =>
        {
            var today = Dates.Today();
            if (day < today)
            {
                throw new BusinessException("ERRORS.PAST_DATE");
            }
            if (await clientRepository.LockAsync(client.Id) is null)
            {
                throw new BusinessException("ERRORS.PATIENT_NOT_FOUND");
            }
            if (await appointmentRepository.CountUpcomingByClientAsync(client.Id, today) > 0)
            {
                throw new BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
            }
            // rellenamos las claves externas: no hace falta adjuntar los
            // propios objetos Slot y Client para escribir la fila de [appointments]
            var appointment = new Appointment { Day = day, SlotId = slot.Id, ClientId = client.Id };
            return await appointmentRepository.SaveAsync(appointment);
        });

    public Task DeleteAppointmentAsync(Appointment appointment) => appointmentRepository.DeleteByIdAsync(appointment.Id);
  • líneas 17–18: toda la reserva se realiza dentro de una sola transacción: el método pasa una función anónima asíncrona, [async () => { ... }], a [TransactionAsync] (véase más abajo), que se encarga de ejecutarla;
  • líneas 20–23: no se permiten citas en el pasado. La regla se verifica aquí sea cual sea el rol de la persona que hace la reserva (ADMIN, DOCTOR o el paciente), incluso si la capa web ya ha ocultado los botones “Reservar” para las fechas pasadas: una solicitud puede crearse manualmente;
  • líneas 25–27: la ficha del paciente se bloquea: [LockAsync] ejecuta [SELECT * FROM clients WHERE id = ... FOR UPDATE] (véase [Repositories/PersonRepository.cs]). Es un bloqueo pesimista: se adquiere antes de que comience el procesamiento, suponiendo un posible conflicto, y permanece hasta el final de la transacción. Sin él, dos reservas del mismo paciente enviadas exactamente al mismo tiempo (dos pestañas, un doble clic) podrían superar ambas la siguiente comprobación antes de que cualquiera haya escrito su cita en la base de datos. Con este bloqueo, la segunda transacción espera a que termine la primera y entonces ve la cita que esta creó. Un paciente que no se encuentra (eliminado entretanto) se rechaza;
  • líneas 29–31: solo una cita futura por paciente;
  • líneas 35–36: la inserción. Solo se especifican las claves externas [SlotId] y [ClientId] : no es necesario vincular los objetos [Slot] y [Client] para escribir la fila [appointments]. Si otro paciente acaba de reservar la misma franja horaria, el bloqueo no lo impidió (el bloqueo se aplica a la fila del paciente): es la restricción de unicidad [unq1_appointments (day, slot_id)] de la base de datos la que rechaza la inserción, y [TransactionAsync] traduce el error en una [BusinessException] con la clave [ERRORS.SLOT_ALREADY_BOOKED];
  • línea 39: cancelación de una cita: un simple [DELETE], sin reglas específicas.

11.12.4.4. Gestión de médicos y clientes

    // =======================================================================
    // médicos y clientes - los métodos públicos delegan en los métodos
    // privados comunes, con el descriptor adecuado
    // =======================================================================

    public Task<Doctor> AddDoctorAsync(PersonData data) => AddPersonAsync(doctorDescriptor, data);

    public Task<Doctor> EditDoctorAsync(int id, PersonData data) =>
        EditPersonAsync(doctorDescriptor, id, data);

    public Task DeleteDoctorAsync(int id) => DeletePersonAsync(doctorDescriptor, id);

    public Task<Client> AddClientAsync(PersonData data) => AddPersonAsync(clientDescriptor, data);

    public Task<Client> EditClientAsync(int id, PersonData data) =>
        EditPersonAsync(clientDescriptor, id, data);

    // el cliente, su cuenta Y todas sus citas (ADMIN, o el propio paciente
    // desde "Manage my account": mismo método, misma regla)
    public Task DeleteClientAsync(int id) => DeletePersonAsync(clientDescriptor, id);

    // -----------------------------------------------------------------------
    // creación: primero la cuenta de usuario (la persona la referencia),
    // luego la persona - todo en UNA sola transacción.
    // -----------------------------------------------------------------------
    private Task<T> AddPersonAsync<T>(PersonDescriptor<T> d, PersonData data) where T : Person, new()
    {
        var lastName = data.LastName.Trim().ToUpperInvariant();
        var firstName = data.FirstName.Trim();
        // las reglas de la base de datos dbrdvmedecins2: login = apellido en minúsculas,
        // contraseña = login - salvo que el ADMIN haya escrito otros
        var login = (string.IsNullOrEmpty(data.Login) ? lastName : data.Login).ToLowerInvariant();
        var password = string.IsNullOrEmpty(data.Password) ? login : data.Password;

        return TransactionAsync(async () =>
        {
            await CheckPersonUniqueAsync(d, firstName, lastName, null);
            await CheckLoginFreeAsync(login);

            var user = new User
            {
                Login = login,
                Password = BCrypt.Net.BCrypt.HashPassword(password, BcryptRounds),
                Name = $"{firstName} {lastName}",
                Role = d.Role,
            };
            await userRepository.SaveAsync(user);

            var person = new T { Title = data.Title, LastName = lastName, FirstName = firstName, User = user };
            return await d.Dao.SaveAsync(person);
        });
    }

    // -----------------------------------------------------------------------
    // actualización: la persona Y su cuenta (el nombre mostrado "firstName LASTNAME"
    // debe seguirla; el login y la contraseña solo cambian si se han
    // escrito).
    // -----------------------------------------------------------------------
    private Task<T> EditPersonAsync<T>(PersonDescriptor<T> d, int id, PersonData data)
        where T : Person, new() =>
        TransactionAsync(async () =>
        {
            var person = await d.Dao.FindByIdAsync(id) ?? throw new BusinessException(d.NotFoundKey);

            // bloqueo optimista: si la versión en la base de datos ya no es la del
            // formulario, alguien modificó este registro mientras tanto - lo rechazamos
            // en lugar de sobrescribir en silencio sus cambios.
            // (Si la actualización concurrente ocurre DESPUÉS de esta lectura, es
            // la cláusula "WHERE version = ..." del UPDATE la que la detecta.)
            if (data.Version is not null && data.Version != person.Version)
            {
                throw new BusinessException("ERRORS.CONCURRENT_UPDATE");
            }

            // nos limitamos a modificar los objetos: el DbContext, que les hace seguimiento,
            // enviará los UPDATE necesarios en el siguiente SaveChangesAsync
            person.Title = data.Title;
            person.LastName = data.LastName.Trim().ToUpperInvariant();
            person.FirstName = data.FirstName.Trim();
            await CheckPersonUniqueAsync(d, person.FirstName, person.LastName, id);

            var user = person.User;
            user.Name = $"{person.FirstName} {person.LastName}";
            if (!string.IsNullOrEmpty(data.Login) && data.Login.ToLowerInvariant() != user.Login)
            {
                var login = data.Login.ToLowerInvariant();
                await CheckLoginFreeAsync(login);
                user.Login = login;
            }
            if (!string.IsNullOrEmpty(data.Password))
            {
                user.Password = BCrypt.Net.BCrypt.HashPassword(data.Password, BcryptRounds);
            }
            await userRepository.SaveAsync(user);
            return await d.Dao.SaveAsync(person);
        });

    // -----------------------------------------------------------------------
    // eliminación, en UNA transacción, en el orden que imponen las claves
    // externas:
    //   1. posible rechazo si quedan citas (médico);
    //   2. lo que referencia a la persona (franjas de un médico, citas
    //      de un cliente);
    //   3. la persona (referencia a su cuenta);
    //   4. su cuenta.
    // -----------------------------------------------------------------------
    private Task DeletePersonAsync<T>(PersonDescriptor<T> d, int id) where T : Person, new() =>
        TransactionAsync(async () =>
        {
            var person = await d.Dao.FindByIdAsync(id) ?? throw new BusinessException(d.NotFoundKey);
            if (d.CountAppointments is not null && await d.CountAppointments(id) > 0)
            {
                throw new BusinessException(d.HasAppointmentsKey ?? "ERRORS.INVALID_FORM");
            }
            if (d.BeforeDelete is not null)
            {
                await d.BeforeDelete(id);
            }
            await d.Dao.DeleteByIdAsync(id);
            await userRepository.DeleteByIdAsync(person.UserId);
            return true; // TransactionAsync espera un resultado: aquí no necesitamos ninguno
        });

    // rechaza nombre y apellido ya usados por OTRA persona del mismo tipo
    // (currentId: la persona que se actualiza, que obviamente tiene
    // derecho a conservar su propio nombre y apellido; null en una creación)
    private static async Task CheckPersonUniqueAsync<T>(PersonDescriptor<T> d, string firstName, string lastName, int? currentId)
        where T : Person, new()
    {
        var namesake = await d.Dao.FindByFirstNameLastNameAsync(firstName, lastName);
        if (namesake is not null && namesake.Id != currentId)
        {
            throw new BusinessException(d.AlreadyExistsKey);
        }
    }

    private async Task CheckLoginFreeAsync(string login)
    {
        if (await userRepository.FindByLoginAsync(login) is not null)
        {
            throw new BusinessException("ERRORS.LOGIN_TAKEN");
        }
    }
  • líneas 6–20: los seis métodos públicos delegan en los tres métodos genéricos privados, usando el descriptor correcto. El compilador infiere [T] a partir del descriptor: [Doctor] for [doctorDescriptor], [Client] for [clientDescriptor];
  • líneas 26–50: creación de una persona y su cuenta;
  • líneas 28–33: preparación de los datos, fuera de una transacción. [Trim] elimina los espacios iniciales y finales de la cadena; el apellido se escribe con mayúscula inicial. De forma predeterminada, el nombre de usuario es igual al apellido y siempre está en minúsculas; de forma predeterminada, la contraseña es igual al nombre de usuario: estas son las reglas de las cuentas del script SQL;
  • líneas 37–38: dentro de la transacción, las dos reglas de unicidad: sin nombres duplicados y con libre elección del nombre de usuario. Se comprueban antes de escribir en la base de datos para dar un mensaje claro (véase el Ejemplo 28);
  • líneas 40–47: la cuenta de usuario se crea primero, ya que la persona hace referencia a ella (clave externa). La contraseña nunca se almacena en texto plano: [BCrypt.Net.BCrypt.HashPassword] calcula su hash (véase el Ejemplo 25). [$"{firstName} {lastName}"] es una cadena interpolada: el nombre que se muestra de la cuenta;
  • líneas 49–50: luego, gracias a la restricción [new()], la persona usa [new T] para generar un [Doctor] o un [Client]. Si esta segunda operación de escritura falla, la transacción también revierte la primera: una cuenta nunca puede existir sin una persona;
  • líneas 59–95: modificación de la persona y su cuenta en una sola transacción;
  • línea 63: una persona no encontrada es una [BusinessException], con la clave del descriptor. [?? throw] se vio en el Ejemplo 28;
  • líneas 70–72: el bloqueo optimista (véase el Ejemplo 28): el formulario ha llevado consigo la versión del registro leído al mostrarse; si la versión en la base de datos es distinta, alguien ha modificado el registro entretanto, y el sistema rechaza la actualización en lugar de sobrescribir silenciosamente su trabajo. A diferencia del bloqueo pesimista usado para las reservas, no se bloquea nada: se supone que los conflictos son raros y simplemente se detectan. Si la modificación concurrente se produce después de esta lectura, será la condición [WHERE version = ...] del [UPDATE] la que la detecte (véase [TranslateDatabaseError], más abajo);
  • líneas 77–80: el objeto leído simplemente se modifica: el [DbContext] enviará el [UPDATE] necesario en el siguiente [SaveChangesAsync]. La comprobación de nombre transmite el identificador de la persona: por supuesto, tiene derecho a conservar su propio nombre y apellido;
  • líneas 82–88: la cuenta sigue a la persona (propiedad de navegación [User], cargada por el DAO): se recalcula el nombre que se muestra. El nombre de usuario cambia solo si se ha introducido y es distinto del actual; en ese caso, debe estar disponible;
  • líneas 90–92: la contraseña cambia solo si se ha introducido; en ese caso se aplica el hash;
  • líneas 94–95: guardado de la cuenta y de la persona. Nuestro [DbContext] incrementa el número de versión de cada entidad modificada (véase [Data/RdvMedecinsDbContext.cs]);
  • líneas 107–121: eliminación, dentro de una sola transacción, en el orden dictado por las claves externas;
  • líneas 111–113: posible rechazo: un médico con citas programadas no puede eliminarse (sus pacientes perderían sus citas sin ser notificados). [d.CountAppointments(id)] llama a la función almacenada en el descriptor;
  • líneas 115–117: eliminación de lo que hace referencia a la persona: las franjas horarias de un médico, las citas de un cliente;
  • líneas 119–120: la persona y luego su cuenta, a la que la persona hacía referencia;
  • línea 121: [TransactionAsync] espera una función que devuelva un resultado: se devuelve uno, pero nadie lo usará;
  • líneas 127–133: se rechaza un homónimo, a menos que sea la persona que se está editando ([currentId], [null] para una creación nueva). El método es [static]: no utiliza ningún campo del objeto;
  • Líneas 137–141: se rechaza un nombre de usuario ya en uso, ya sea por un médico, un cliente o el administrador.

11.12.4.5. Transacciones y restricciones de unicidad

    // -----------------------------------------------------------------------
    // ejecuta [work] en una transacción:
    //   BeginTransactionAsync -> START TRANSACTION;
    //   CommitAsync            -> COMMIT, si todo salió bien;
    //   si se lanza una excepción (BusinessException incluida), no se confirma:
    //   "await using" cierra la transacción al salir del bloque, y una
    //   transacción cerrada sin COMMIT se cancela (ROLLBACK).
    //
    // Las verificaciones de "login libre" y "nombre + apellido únicos" se hacen ANTES de
    // la escritura, para dar un mensaje claro. Pero dos ADMIN podrían
    // guardar el mismo login (o el mismo médico) en el mismo instante: en este
    // caso poco frecuente, es una restricción SQL de unicidad la que rechaza la segunda
    // escritura - entonces traducimos este error SQL a la misma BusinessException.
    // -----------------------------------------------------------------------
    private async Task<R> TransactionAsync<R>(Func<Task<R>> work)
    {
        await using var transaction = await db.Database.BeginTransactionAsync();
        try
        {
            var result = await work();
            await transaction.CommitAsync();
            return result;
        }
        catch (Exception e)
        {
            // en caso de falla, el DbContext "olvida" todo lo que rastreaba: una
            // entidad que quedara en estado Added se enviaría de nuevo a la base de datos en el
            // siguiente SaveChangesAsync de la misma solicitud
            db.ChangeTracker.Clear();
            if (TranslateDatabaseError(e) is { } businessError)
            {
                throw businessError;
            }
            throw; // "throw;" vuelve a lanzar la excepción original, con su pila de llamadas intacta
        }
    }

    // -----------------------------------------------------------------------
    // Errores de base de datos -> BusinessException
    //
    // - DbUpdateConcurrencyException: el UPDATE "WHERE id = ... AND version = ..."
    //   no modificó ninguna fila (bloqueo optimista, ver AbstractEntity);
    // - DbUpdateException cuya causa (InnerException) es el error de MySQL
    //   ER_DUP_ENTRY (n.º 1062): una restricción UNIQUE rechazó la escritura. Su
    //   mensaje cita el NOMBRE de la restricción:
    //     Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name'
    //   (MySQL 8 antepone al nombre el de la tabla, MariaDB no). Por eso
    //   el script SQL NOMBRA todas sus restricciones.
    // Cualquier otro error es una verdadera anomalía: devolvemos null (sin traducir).
    // -----------------------------------------------------------------------
    private static readonly Dictionary<string, string> ConstraintMessages = new()
    {
        ["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",
    };

    private static BusinessException? TranslateDatabaseError(Exception e)
    {
        // cuidado con el orden: DbUpdateConcurrencyException hereda de DbUpdateException
        if (e is DbUpdateConcurrencyException)
        {
            return new BusinessException("ERRORS.CONCURRENT_UPDATE");
        }
        // "pattern matching": ¿e es una DbUpdateException
        // cuya InnerException es una MySqlException con el código DuplicateKeyEntry?
        if (e is DbUpdateException { InnerException: MySqlException { ErrorCode: MySqlErrorCode.DuplicateKeyEntry } sqlError })
        {
            // "... for key 'doctors.unq_doctors_first_name_last_name'" -> "unq_doctors_first_name_last_name"
            var match = Regex.Match(sqlError.Message, @"for key '(?:[^'.]*\.)?([^']+)'");
            if (match.Success && ConstraintMessages.TryGetValue(match.Groups[1].Value, out var key))
            {
                return new BusinessException(key);
            }
        }
        return null;
    }
}
  • línea 15: todas las operaciones de escritura de varios pasos pasan por este método genérico: [R] es el tipo del resultado de la operación ([Appointment], [Doctor], [Client], [bool]), y [Func<Task<R>>] es el tipo de una función asíncrona sin parámetros que devuelve un [R]. Es el método [TransactionAsync] del Ejemplo 28, ampliado;
  • línea 17: [BeginTransactionAsync] abre una transacción ([START TRANSACTION]). [await using var] declara una variable que se cerrará automáticamente al salir del bloque que la contiene, suceda lo que suceda (finalización normal o excepción); la versión [await] permite un cierre asíncrono. Una transacción que se cierra sin haber sido confirmada se revierte ([ROLLBACK]);
  • líneas 20–22: se ejecuta la tarea; si tiene éxito, [CommitAsync] confirma la transacción ([COMMIT]). Si se lanza una excepción, incluida una [BusinessException], [CommitAsync] nunca se alcanza: todo lo que se haya escrito se revierte;
  • línea 24: el Ejemplo 28 capturaba dos tipos específicos de excepciones; aquí capturamos todas las excepciones para limpiar antes de volver a lanzarlas;
  • línea 29: la limpieza. La base de datos ha revertido todo, pero el [DbContext] sigue rastreando entidades que ya no corresponden a nada: por ejemplo, el médico cuya inserción falló permanece en el estado [Added]. Como el [DbContext] persiste durante toda la solicitud, se enviaría de nuevo a la base de datos con el siguiente [SaveChangesAsync] de esa solicitud. [ChangeTracker.Clear()] hace que el [DbContext] olvide todas las entidades que estaba rastreando;
  • líneas 30–32: si el error es un error conocido de la base de datos, se lanza en su lugar la [BusinessException] correspondiente. [is { } businessError] es un filtro de patrón: comprueba que el valor no es [null] y lo almacena en la variable [businessError];
  • línea 34: en caso contrario, la excepción original se vuelve a lanzar tal cual. [throw;] solo, dentro de un [catch], mantiene intacta su pila de llamadas (la que indica dónde se produjo el error), mientras que [throw e;] la reiniciaría. Una [BusinessException] lanzada por la tarea se devuelve así, sin cambios, al controlador; cualquier otro error es una anomalía, que generará una página de error 500;
  • líneas 51–56: para cada restricción de unicidad con nombre del script SQL, su clave de traducción. Por eso el script SQL da nombre a todas sus restricciones. [new()] sin nombre de tipo se permite cuando el tipo ya está especificado a la izquierda; [["key"] = value] rellena el diccionario;
  • líneas 59–77: traducción de un error de la base de datos a una [BusinessException], o a [null] si el error no se reconoce;
  • líneas 62–64: [UPDATE ... WHERE id = ... AND version = ...] no modificó ninguna fila: EF Core lanza una [DbUpdateConcurrencyException] (bloqueo optimista; véase el Ejemplo 28). Esta comprobación va primero porque [DbUpdateConcurrencyException] hereda de [DbUpdateException]: si se colocara después, la comprobación siguiente la habría interceptado;
  • línea 68: una violación de una restricción de unicidad. El error de [MySQL] (código [DuplicateKeyEntry], n.º 1062) se produce anidado dentro de una [DbUpdateException], en su propiedad [InnerException]. El filtrado de patrones comprueba todo en una sola expresión, en dos niveles: [e] es una [DbUpdateException], cuya [InnerException] es una [MySqlException], que tiene un [ErrorCode] igual a [DuplicateKeyEntry]; esta [MySqlException] se almacena en [sqlError]. La versión [NestJS] también comprobaba el código [ER_DUP_ENTRY] de un [QueryFailedError];
  • línea 71: el mensaje de error indica el nombre de la restricción, por ejemplo, [Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name']. La expresión regular lo extrae: [(?:[^'.]*\.)?] omite el prefijo opcional [doctors.] (escrito por [MySQL] 8, no por [MariaDB]), y el grupo [([^']+)] captura el nombre hasta el apóstrofo. La [@] al comienzo de la cadena la convierte en una cadena literal, donde [\] no es un carácter de escape;
  • líneas 72–74: si se encontró el nombre y figura en el diccionario, [TryGetValue] almacena la clave de traducción en [key], y el error se convierte en una [BusinessException]. Cualquier otro error, incluida la violación de una restricción que no está en el diccionario, se deja sin traducir: es una verdadera anomalía.

11.13. Autenticación

La carpeta [Auth] incluye, de forma más completa, los ejemplos 25 a 27: el token JWT en una cookie, los roles, el CAPTCHA y los límites de intentos. También incluye un “pase” para crear una cuenta de cliente. El controlador [AuthController], tratado al final de esta sección, reúne estos componentes para la página de inicio de sesión.

11.13.1. Auth/ConnectedUser.cs

// =========================================================================
// Auth/ConnectedUser.cs
// -------------------------------------------------------------------------
// Lo que contiene el token JWT, y cómo leerlo de nuevo.
//
// En ASP.NET Core, el usuario de la solicitud es un ClaimsPrincipal
// (propiedad User de un controlador, HttpContext.User en otros lugares): una lista de
// "claims", pares tipo / valor - exactamente los
// campos del token JWT una vez verificado. El middleware de autenticación
// lo llena en CADA solicitud (ver Program.cs, UseAuthentication).
//
// Los claims de nuestros tokens (ver AuthService.SetToken):
//   sub   : el id de la cuenta de usuario (convención JWT: "subject")
//   login : el login
//   name  : el nombre mostrado ("Marie PELISSIER"), para la barra de navegación
//   role  : ADMIN, DOCTOR o USER
// =========================================================================

using System.Security.Claims;
using RdvMedecins.Entities;

namespace RdvMedecins.Auth;

public static class JwtClaims
{
    public const string Sub = "sub";
    public const string Login = "login";
    public const string Name = "name";
    public const string Role = "role";
}

// el usuario conectado, en forma tipada
public record ConnectedUser(int UserId, string Login, string Name, Role Role);

// -------------------------------------------------------------------------
// Un "método de extensión": se invoca como si fuera parte de
// ClaimsPrincipal (User.CurrentUser()), cuando en realidad se define aquí.
// -------------------------------------------------------------------------
public static class ClaimsPrincipalExtensions
{
    // el usuario conectado, o null si la solicitud no está autenticada
    public static ConnectedUser? CurrentUser(this ClaimsPrincipal principal)
    {
        if (principal.Identity?.IsAuthenticated != true
            || !int.TryParse(principal.FindFirstValue(JwtClaims.Sub), out var userId)
            || !Enum.TryParse<Role>(principal.FindFirstValue(JwtClaims.Role), out var role))
        {
            return null;
        }
        return new ConnectedUser(
            userId,
            principal.FindFirstValue(JwtClaims.Login) ?? "",
            principal.FindFirstValue(JwtClaims.Name) ?? "",
            role);
    }
}
  • líneas 24–29: los nombres de las claims del token, agrupados en constantes: un error tipográfico en [JwtClaims.Name] lo señala el compilador, mientras que un error en la cadena ["name"] solo se descubriría en tiempo de ejecución;
  • línea 33: el usuario conectado en forma tipada: un identificador entero, un rol de tipo [Role] (la enumeración ADMIN, DOCTOR, USER de la carpeta [Entities]), en lugar de la lista de pares de cadenas que constituyen las claims. Equivale al objeto [req.user] creado por la estrategia [Passport] del proyecto [NestJS];
  • líneas 39–42: un método de extensión (véase el Ejemplo 06) sobre ***[ClaimsPrincipal], el tipo de la propiedad ***[User] de los controladores y las vistas (véase el Ejemplo 25). Las páginas simplemente escriben [User.CurrentUser()];
  • líneas 44–48: el método devuelve [null] si la solicitud no está autenticada o si las claims no son las esperadas. [Identity?.IsAuthenticated] es igual a [null] si falta [Identity]: la comparación [!= true] trata este caso como “no autenticado”. [int.TryParse] y [Enum.TryParse<Role>] intentan una conversión y devuelven [false] si la conversión falla, en lugar de lanzar una excepción; el resultado se almacena en la variable declarada por [out var];
  • líneas 50–54: [FindFirstValue] devuelve el valor de la primera claim del tipo solicitado, o [null]; el operador [??] lo reemplaza entonces por una cadena vacía.

11.13.2. Auth/AuthService.cs

// =========================================================================
// Auth/AuthService.cs
// -------------------------------------------------------------------------
// La lógica de autenticación:
//   - ValidateUserAsync()      : verifica un par login / contraseña;
//   - SetToken()               : construye el token JWT de un usuario validado
//                                y lo guarda en una cookie;
//   - ClearToken()             : elimina esta cookie (cierre de sesión).
//
// ¿Por dónde viaja el token JWT?
// Con el cliente Angular, era el código JavaScript del cliente el que guardaba el
// token y lo agregaba él mismo a cada solicitud (encabezado "Authorization:
// Bearer ..."). Un navegador que muestra páginas HTML ordinarias no puede
// hacerlo: para que presente el token por sí solo en cada solicitud,
// debe guardarse en una COOKIE. Las opciones de esta cookie importan para la
// seguridad:
//   - HttpOnly : el JavaScript de la página no puede leer la cookie (un
//     script inyectado no podría entonces robar el token);
//   - SameSite=Lax : el navegador NO envía la cookie con un POST proveniente
//     de otro sitio. Como todas las acciones que modifican datos son
//     POST, una página trampa en otro sitio no puede reservar ni
//     eliminar nada haciéndose pasar por el usuario
//     (el llamado ataque CSRF);
//   - Secure : en producción (HTTPS), la cookie nunca viaja en claro;
//   - MaxAge : la cookie desaparece al mismo tiempo que expira el token.
// =========================================================================

using System.Text;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;
using RdvMedecins.Config;
using RdvMedecins.Entities;
using RdvMedecins.Repositories;

namespace RdvMedecins.Auth;

public class AuthService(UserRepository userRepository, IOptions<AuthOptions> options)
{
    // el nombre de la cookie que lleva el token
    public const string JwtCookie = "rdvmedecins_jwt";

    private readonly AuthOptions auth = options.Value;

    // la clave de firma de los tokens, construida a partir del secreto de
    // appsettings.json. También se usa para VERIFICAR los tokens (ver Program.cs).
    public static SymmetricSecurityKey SigningKey(AuthOptions auth)
    {
        var bytes = Encoding.UTF8.GetBytes(auth.JwtSecret);
        if (bytes.Length < 32)
        {
            // HMAC-SHA256 exige una clave de al menos 256 bits: lo decimos
            // claramente al arrancar y no en el primer inicio de sesión
            throw new InvalidOperationException("Auth:JwtSecret must be at least 32 characters long (see appsettings.json).");
        }
        return new SymmetricSecurityKey(bytes);
    }

    // null si el login no existe o si la contraseña es incorrecta.
    // BCrypt.Verify aplica el hash a la contraseña escrita con el "salt" contenido en el
    // hash guardado, y luego compara los dos resultados.
    public async Task<User?> ValidateUserAsync(string login, string password)
    {
        var user = await userRepository.FindByLoginAsync(login);
        if (user is null)
        {
            return null;
        }
        return BCrypt.Net.BCrypt.Verify(password, user.Password) ? user : null;
    }

    // -----------------------------------------------------------------------
    // construye el token JWT de [user] y lo coloca en una cookie.
    // El token está FIRMADO (HMAC-SHA256) con la clave secreta: el navegador
    // puede leerlo (no está cifrado), pero no modificarlo - cualquier
    // modificación invalidaría la firma.
    // -----------------------------------------------------------------------
    public void SetToken(HttpResponse response, User user)
    {
        var descriptor = new SecurityTokenDescriptor
        {
            Claims = new Dictionary<string, object>
            {
                [JwtClaims.Sub] = user.Id,
                [JwtClaims.Login] = user.Login,
                [JwtClaims.Name] = user.Name,
                [JwtClaims.Role] = user.Role.ToString(),
            },
            Expires = DateTime.UtcNow.AddSeconds(auth.JwtExpiresInSeconds),
            SigningCredentials = new SigningCredentials(SigningKey(auth), SecurityAlgorithms.HmacSha256),
        };
        var token = new JsonWebTokenHandler().CreateToken(descriptor);

        response.Cookies.Append(JwtCookie, token, new CookieOptions
        {
            HttpOnly = true,
            SameSite = SameSiteMode.Lax,
            Secure = auth.CookieSecure,
            MaxAge = TimeSpan.FromSeconds(auth.JwtExpiresInSeconds),
            Path = "/",
        });
    }

    public static void ClearToken(HttpResponse response) =>
        response.Cookies.Delete(JwtCookie, new CookieOptions { Path = "/" });
}

Comentemos este código:

  • línea 38: el servicio recibe, mediante inyección, el DAO que contiene las cuentas de usuario ([UserRepository], tratado con la capa DAO) y la configuración de autenticación. [IOptions<AuthOptions>] proporciona la sección [Auth] de [appsettings.json] en forma de un objeto [AuthOptions] (carpeta [Config]): su propiedad [Value] contiene la clave secreta, la duración del token y la opción [CookieSecure]. El servicio se registra como [Scoped] en [Program.cs], igual que el DAO que utiliza (véase el Capítulo 6);
  • línea 41: el nombre de la cookie que transporta el token;
  • líneas 47–56: la clave de firma (véase el Ejemplo 25). Novedad: una clave demasiado corta se rechaza con una excepción clara. El método es static: depende solo de su parámetro y se llama cuando se inicia la aplicación, desde [JwtAuthentication] (siguiente archivo), en un momento en que todavía no existe ningún servicio. Como la comprobación de la longitud se realiza en este punto, una configuración incorrecta impide que la aplicación se inicie, en lugar de hacer fallar la primera conexión;
  • líneas 62–69: la cuenta si el nombre de usuario y la contraseña son correctos; de lo contrario, [null] (véase el Ejemplo 25). El método es asíncrono: la búsqueda de la cuenta es una consulta a la base de datos (véase el Capítulo 9);
  • líneas 78–92: el token, generado como en el Ejemplo 25. Contiene el identificador de la cuenta, el nombre de usuario, el nombre que se muestra en la barra de navegación y el rol; su duración la determina la configuración (dos horas de forma predeterminada);
  • líneas 94–100: la cookie, con las opciones del Ejemplo 25 ([HttpOnly], [SameSite = Lax]) y dos adicionales: [Secure], habilitada en producción (el sitio se sirve con [HTTPS]), impide que el navegador envíe la cookie por una conexión sin cifrar; [Path = "/"] garantiza que se incluya en cada solicitud al sitio. [MaxAge] elimina la cookie cuando el token expira;
  • líneas 104–105: al cerrar la sesión se elimina la cookie. Para que el navegador reconozca la cookie que se debe eliminar, la ruta ([Path]) debe ser la del lugar de almacenamiento. El método es estático: también lo usan el manejador [JwtBearer] (siguiente archivo) y el filtro de excepciones [HtmlExceptionFilter] (carpeta [Web]), que no disponen de una instancia de [AuthService] .

11.13.3. Auth/JwtAuthentication.cs

// =========================================================================
// Auth/JwtAuthentication.cs
// -------------------------------------------------------------------------
// La configuración de la autenticación con token JWT, invocada desde
// Program.cs (builder.Services.AddJwtAuthentication(...)).
//
// El "handler" JwtBearer de ASP.NET Core hace, en cada solicitud, lo que
// hacían la estrategia 'jwt' de Passport y JwtAuthGuard en NestJS:
//   1. encontrar el token;
//   2. verificar su firma y su fecha de vencimiento;
//   3. derivar de él el usuario (HttpContext.User, ver ConnectedUser.cs).
//
// Tres adaptaciones a una aplicación HTML, gracias a los "eventos" del
// handler (funciones que invoca en momentos precisos):
//   - OnMessageReceived : el token se lee de una COOKIE, y no del
//     encabezado "Authorization: Bearer ...";
//   - OnChallenge : cuando se solicita una página protegida sin un token válido,
//     JwtBearer respondería 401 - lo cual conviene a un cliente JavaScript. Un
//     navegador, en cambio, debe ser REDIRIGIDO a la página de inicio de sesión;
//   - (403: rol insuficiente) nada que hacer aquí: la respuesta 403 vacía se
//     convierte en una página de error mediante UseStatusCodePagesWithReExecute
//     (ver Program.cs y Controllers/ErrorController.cs).
// =========================================================================

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using RdvMedecins.Config;
using RdvMedecins.Web;

namespace RdvMedecins.Auth;

public static class JwtAuthentication
{
    public static IServiceCollection AddJwtAuthentication(this IServiceCollection services, AuthOptions auth)
    {
        services
            .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(options =>
            {
                // conservamos los nombres de los claims del token tal cual ("role", "sub"...)
                // en lugar de traducirlos a nombres largos al estilo de Microsoft
                options.MapInboundClaims = false;

                options.TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateIssuerSigningKey = true,
                    IssuerSigningKey = AuthService.SigningKey(auth),
                    ValidateLifetime = true,
                    // un token vencido se rechaza de inmediato (por defecto, se concede una
                    // tolerancia de 5 minutos por diferencias de reloj)
                    ClockSkew = TimeSpan.Zero,
                    // nuestros tokens no tienen emisor (iss) ni audiencia (aud)
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    // qué claim contiene el nombre y cuál el rol:
                    // [Authorize(Roles = "ADMIN")] compara el claim "role"
                    NameClaimType = JwtClaims.Name,
                    RoleClaimType = JwtClaims.Role,
                };

                options.Events = new JwtBearerEvents
                {
                    // 1. el token está en la cookie
                    OnMessageReceived = context =>
                    {
                        context.Token = context.Request.Cookies[AuthService.JwtCookie];
                        return Task.CompletedTask;
                    },

                    // 2. página protegida sin un token válido -> página de inicio de sesión
                    OnChallenge = context =>
                    {
                        // HandleResponse(): "yo me encargo de la respuesta", JwtBearer
                        // por lo tanto no escribirá su 401
                        context.HandleResponse();
                        // había una cookie pero ya no es válida: la sesión expiró
                        if (context.Request.Cookies.ContainsKey(AuthService.JwtCookie))
                        {
                            AuthService.ClearToken(context.Response);
                            Flash.Put(context.HttpContext, FlashType.Danger, "ERRORS.SESSION_EXPIRED");
                        }
                        context.Response.Redirect("/login");
                        return Task.CompletedTask;
                    },
                };
            });

        return services;
    }
}

En el Ejemplo 25, la configuración de [JwtBearer] estaba escrita en [Program.cs]. Aquí se guarda en un método de extensión, al que [Program.cs] llama en una sola línea: [builder.Services.AddJwtAuthentication(authOptions)]. Comentemos este código:

  • líneas 32–34: el método de extensión (véase el Ejemplo 06). Recibe directamente un objeto [AuthOptions], leído de la configuración por [Program.cs]: cuando se registran los servicios, la inyección de dependencias aún no está disponible, por lo que no podemos solicitar un [IOptions<AuthOptions>];
  • líneas 37–42: el esquema de autenticación [JwtBearer], que almacena los nombres de las claims del token (véase el Ejemplo 25);
  • líneas 44–54: las comprobaciones realizadas en cada token: la firma, mediante la clave generada por [AuthService.SigningKey], y la fecha de expiración. Novedad respecto al Ejemplo 25: [ClockSkew = TimeSpan.Zero]. De forma predeterminada, [JwtBearer] sigue aceptando un token durante cinco minutos después de que expire, para tener en cuenta una ligera discrepancia entre los relojes del servidor que genera el token y el que lo verifica. Aquí es el mismo servidor: un token expirado se rechaza de inmediato;
  • líneas 57–58: la claim [name] produce [User.Identity.Name], la claim [role] es la que verifican [[Authorize(Roles = "ADMIN")]] y [User.IsInRole] (véase el Ejemplo 26);
  • líneas 64–67: el token se lee de la cookie, no del encabezado [Authorization] (véase el Ejemplo 25);
  • líneas 71–82: una solicitud de una página protegida sin un token válido redirige a la página de inicio de sesión (véase el Ejemplo 25). Novedad (líneas 77–80): si la solicitud incluía una cookie con el token, significa que el usuario había iniciado sesión, pero su token ha expirado (o fue manipulado). Eliminamos esta cookie ya inútil y mostramos un mensaje flash (véase el Ejemplo 20; la clase [Flash] se trata con la carpeta [Web]): la página de inicio de sesión mostrará “Su sesión ha expirado”, en lugar de dejar al usuario preguntándose por qué está allí. El mensaje es una clave de traducción (véase el Ejemplo 22).

Una respuesta 403 Forbidden (rol insuficiente) no requiere un evento: como en el Ejemplo 26, la respuesta vacía se convierte en una página de error mediante [UseStatusCodePagesWithReExecute]. En el proyecto [NestJS], esta tarea se repartía entre las estrategias [Passport] y [jwt] (leer y verificar el token), el guardia [JwtAuthGuard] (exigir un token) y el filtro de excepciones (convertir la denegación en una redirección); aquí bastan el manejador [JwtBearer], sus eventos y el atributo [[Authorize]] .

11.13.4. Auth/InvalidSessionException.cs

// =========================================================================
// Auth/InvalidSessionException.cs
// -------------------------------------------------------------------------
// El token es válido, pero la cuenta que designa ya no existe: fue
// eliminada después del inicio de sesión (por el propio paciente en otra
// pestaña, o por el ADMIN). Tratamos este caso como una sesión expirada:
// HtmlExceptionFilter borra la cookie y redirige a la página de inicio de sesión
// (el equivalente de UnauthorizedException de NestJS).
// =========================================================================

namespace RdvMedecins.Auth;

public class InvalidSessionException() : Exception("the account of the connected user no longer exists");
  • Línea 13: un token puede ser válido (correctamente firmado, no expirado) aunque la cuenta a la que hace referencia se haya eliminado desde el inicio de sesión. Las páginas del paciente detectan esto buscando el cliente asociado a la cuenta (método [ConnectedPatientAsync] en el archivo [Web/Utils.cs]) y luego lanzan esta excepción; el filtro de excepciones [HtmlExceptionFilter] (véase el Ejemplo 24 para los filtros) la intercepta, elimina la cookie y redirige a la página de inicio de sesión con el mensaje “sesión expirada”. La clase tiene un constructor principal sin parámetros, que pasa su mensaje al constructor de la clase padre [Exception].

11.13.5. Auth/CaptchaService.cs

// =========================================================================
// Auth/CaptchaService.cs
// -------------------------------------------------------------------------
// Un CAPTCHA ("prueba para distinguir a un humano de un robot") hecho por el
// propio servidor, sin ningún servicio externo: unos cuantos caracteres distorsionados,
// revueltos con trazos, en una imagen SVG. Un humano los lee sin
// dificultad; un robot que simplemente envía formularios en bucle
// no puede hacerlo.
//
// El proyecto NestJS usaba la biblioteca svg-captcha. Aquí no hay
// biblioteca: la imagen la dibuja la clase CaptchaDrawing (más abajo)
// a partir de una pequeña "fuente" vectorial escrita a mano. Un punto
// importante: cada carácter se dibuja con TRAZOS (<path>), nunca
// se escribe como texto (<text>) - de lo contrario un robot solo tendría que leer el código
// fuente de la imagen.
//
// Cómo funciona:
//   1. Generate() dibuja un texto aleatorio, lo convierte en imagen y guarda la
//      respuesta correcta EN LA MEMORIA DEL SERVIDOR, bajo un identificador aleatorio;
//   2. la página muestra la imagen y pone el identificador en un campo oculto del
//      formulario (la respuesta en sí nunca sale del servidor);
//   3. Verify(id, input) compara la entrada con la respuesta esperada y luego
//      OLVIDA este captcha: cada imagen se usa una sola vez, un robot no puede
//      reutilizar una respuesta ya encontrada.
//
// Servicio SINGLETON (una única instancia para todo el servidor, ver
// Program.cs), usado por varias solicitudes EN PARALELO: de ahí el
// ConcurrentDictionary, un diccionario que varios hilos pueden leer
// y modificar al mismo tiempo sin corromperlo.
//
// Límite aceptado: la memoria de un solo proceso. Con varios servidores
// detrás de un balanceador de carga, haría falta un almacenamiento compartido.
// =========================================================================

using System.Collections.Concurrent;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

namespace RdvMedecins.Auth;

// Id : para poner en el campo oculto "captchaId" del formulario
// Svg : la imagen, para insertar tal cual en la página
public record Captcha(string Id, string Svg);

public class CaptchaService
{
    // duración de validez de una imagen: tiene 10 minutos para llenar el formulario
    private static readonly TimeSpan Lifetime = TimeSpan.FromMinutes(10);

    // protección de memoria: más allá de este límite, olvidamos los captchas más antiguos
    private const int MaxCaptchas = 10_000;

    // id -> (respuesta esperada, fecha de vencimiento)
    private readonly ConcurrentDictionary<string, (string Text, DateTime Expires)> pending = new();

    public Captcha Generate()
    {
        Purge();
        var text = CaptchaDrawing.RandomText(5); // 5 caracteres
        var id = Guid.NewGuid().ToString();
        pending[id] = (text, DateTime.UtcNow + Lifetime);
        return new Captcha(id, CaptchaDrawing.Svg(text));
    }

    // true si [input] es la respuesta correcta al captcha [id] (sin distinguir
    // mayúsculas de minúsculas). El captcha se consume en todos los casos.
    // TryRemove es ATÓMICO: si dos solicitudes presentan el mismo captcha en el
    // mismo instante, solo una lo elimina - la otra falla.
    public bool Verify(string? id, string? input)
    {
        if (id is null || input is null || !pending.TryRemove(id, out var expected))
        {
            return false;
        }
        return expected.Expires > DateTime.UtcNow
            && string.Equals(expected.Text, input.Trim(), StringComparison.OrdinalIgnoreCase);
    }

    private void Purge()
    {
        var now = DateTime.UtcNow;
        foreach (var (id, captcha) in pending)
        {
            if (captcha.Expires <= now || pending.Count >= MaxCaptchas)
            {
                pending.TryRemove(id, out _);
            }
        }
    }
}

// -------------------------------------------------------------------------
// El dibujo de la imagen SVG (150 x 50 píxeles).
// -------------------------------------------------------------------------
internal static class CaptchaDrawing
{
    private const int Width = 150;
    private const int Height = 50;

    // La "fuente": cada carácter es una lista de trazos, cada trazo una
    // serie de puntos (x, y) en una cuadrícula de 4 x 6 (y apunta hacia abajo).
    // Caracteres demasiado fáciles de confundir entre sí: excluidos (0 O, 1 I L).
    private static readonly Dictionary<char, double[][]> Font = new()
    {
        ['A'] = [[0, 6, 2, 0, 4, 6], [0.8, 3.8, 3.2, 3.8]],
        ['B'] = [[0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3], [0, 0, 3, 0, 4, 1, 4, 2, 3, 3]],
        ['C'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5]],
        ['D'] = [[0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0]],
        ['E'] = [[4, 0, 0, 0, 0, 6, 4, 6], [0, 3, 3, 3]],
        ['F'] = [[4, 0, 0, 0, 0, 6], [0, 3, 3, 3]],
        ['G'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5]],
        ['H'] = [[0, 0, 0, 6], [4, 0, 4, 6], [0, 3, 4, 3]],
        ['J'] = [[4, 0, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['K'] = [[0, 0, 0, 6], [4, 0, 0, 3.5], [1.3, 2.6, 4, 6]],
        ['M'] = [[0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6]],
        ['N'] = [[0, 6, 0, 0, 4, 6, 4, 0]],
        ['P'] = [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3]],
        ['Q'] = [[1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0], [2.5, 4.5, 4, 6.3]],
        ['R'] = [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3], [2, 3, 4, 6]],
        ['S'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['T'] = [[0, 0, 4, 0], [2, 0, 2, 6]],
        ['U'] = [[0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0]],
        ['V'] = [[0, 0, 2, 6, 4, 0]],
        ['W'] = [[0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0]],
        ['X'] = [[0, 0, 4, 6], [4, 0, 0, 6]],
        ['Y'] = [[0, 0, 2, 3, 4, 0], [2, 3, 2, 6]],
        ['Z'] = [[0, 0, 4, 0, 0, 6, 4, 6]],
        ['2'] = [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6]],
        ['3'] = [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3], [3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['4'] = [[3, 6, 3, 0, 0, 4, 4, 4]],
        ['5'] = [[4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['6'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3]],
        ['7'] = [[0, 0, 4, 0, 1.5, 6]],
        ['8'] = [[1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3]],
        ['9'] = [[4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5]],
    };

    private static readonly char[] Alphabet = [.. Font.Keys];

    // unos pocos colores oscuros, fáciles de leer sobre el fondo claro
    private static readonly string[] Colors = ["#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b"];

    // RandomNumberGenerator: un generador de números aleatorios "criptográfico",
    // impredecible (a diferencia de Random, cuya secuencia podría adivinarse)
    public static string RandomText(int length) =>
        new(Enumerable.Range(0, length).Select(_ => Alphabet[RandomNumberGenerator.GetInt32(Alphabet.Length)]).ToArray());

    private static double RandomBetween(double min, double max) =>
        min + (max - min) * RandomNumberGenerator.GetInt32(1_000_001) / 1_000_000.0;

    public static string Svg(string text)
    {
        var svg = new StringBuilder();
        svg.Append($"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{Width}\" height=\"{Height}\" viewBox=\"0 0 {Width} {Height}\">");
        svg.Append($"<rect width=\"100%\" height=\"100%\" fill=\"#f5f7fa\"/>");

        // los caracteres: cada uno ampliado, inclinado, desplazado, y cada punto
        // ligeramente movido al azar
        var step = (Width - 20) / (double)text.Length;
        for (var i = 0; i < text.Length; i++)
        {
            var scale = RandomBetween(4.6, 5.6); // tamaño de una unidad de la cuadrícula, en píxeles
            var angle = RandomBetween(-0.35, 0.35); // rotación, en radianes (unos ±20°)
            var cx = 10 + step * (i + 0.5) + RandomBetween(-3, 3); // centro del carácter
            var cy = Height / 2.0 + RandomBetween(-4, 4);
            var color = Colors[RandomNumberGenerator.GetInt32(Colors.Length)];
            var d = new StringBuilder();
            foreach (var stroke in Font[text[i]])
            {
                for (var k = 0; k < stroke.Length; k += 2)
                {
                    // punto de la cuadrícula, centrado en (2, 3), distorsionado, rotado, colocado
                    var x = (stroke[k] - 2 + RandomBetween(-0.2, 0.2)) * scale;
                    var y = (stroke[k + 1] - 3 + RandomBetween(-0.2, 0.2)) * scale;
                    var px = cx + x * Math.Cos(angle) - y * Math.Sin(angle);
                    var py = cy + x * Math.Sin(angle) + y * Math.Cos(angle);
                    d.Append(k == 0 ? 'M' : 'L').Append(Number(px)).Append(' ').Append(Number(py)).Append(' ');
                }
            }
            svg.Append($"<path d=\"{d.ToString().TrimEnd()}\" fill=\"none\" stroke=\"{color}\" stroke-width=\"{Number(RandomBetween(2.2, 3))}\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>");
        }

        // 3 trazos de confusión: curvas que cruzan la imagen
        for (var n = 0; n < 3; n++)
        {
            var color = Colors[RandomNumberGenerator.GetInt32(Colors.Length)];
            svg.Append($"<path d=\"M{Number(RandomBetween(0, 20))} {Number(RandomBetween(5, 45))} " +
                       $"C{Number(RandomBetween(30, 60))} {Number(RandomBetween(0, 50))} {Number(RandomBetween(90, 120))} {Number(RandomBetween(0, 50))} " +
                       $"{Number(RandomBetween(130, 150))} {Number(RandomBetween(5, 45))}\" fill=\"none\" stroke=\"{color}\" stroke-width=\"1.3\"/>");
        }

        svg.Append("</svg>");
        return svg.ToString();
    }

    // un número con punto decimal, sea cual sea el idioma del servidor
    // (en francés, ToString() escribiría "12,5" - ilegible para SVG)
    private static string Number(double value) => value.ToString("0.#", CultureInfo.InvariantCulture);
}

El archivo contiene dos clases: la clase del servicio, que es idéntica a la del Ejemplo 27 salvo por una salvaguarda, y la clase [CaptchaDrawing] que genera la imagen, ya tratada en el Ejemplo 27 (archivo [Auth/CaptchaDrawing.cs]). Repasemos este código:

  • línea 44: un CAPTCHA, tal como lo recibe la página: el identificador, que se colocará en un campo oculto del formulario, y la imagen [SVG];
  • líneas 49–52: una imagen es válida durante diez minutos y hay un tope al número de CAPTCHA pendientes. Cada vez que se muestra la página de inicio de sesión, se agrega un CAPTCHA a la memoria; sin un tope, un bot que solicitara esta página millones de veces sin responder nunca terminaría agotando la memoria del servidor;
  • línea 55: id → (respuesta esperada, fecha de expiración). El par es una tupla cuyos elementos tienen nombre ([Text], [Expires]). El servicio es un singleton, usado por solicitudes concurrentes: de ahí el [ConcurrentDictionary] (véase el Ejemplo 27);
  • líneas 57–63: la limpieza, seguida de una cadena de texto de cinco caracteres generada aleatoriamente, almacenada con un identificador aleatorio ([Guid.NewGuid()], imposible de adivinar), y mostrada;
  • líneas 70–77: verificación, idéntica a la del Ejemplo 27: el CAPTCHA se consume en todos los casos ([TryRemove]), luego el sistema verifica que no haya expirado y que el texto introducido, sin espacios, sea correcto, sin distinguir mayúsculas de minúsculas. [TryRemove] es atómico: si dos solicitudes presentan el mismo CAPTCHA al mismo tiempo, solo una lo elimina;
  • líneas 80–87: los CAPTCHA expirados se descartan; si se alcanza el límite, también se eliminan los CAPTCHA válidos hasta que el número baje del límite. Un [ConcurrentDictionary] puede modificarse mientras se recorre, lo que no está permitido con un [Dictionary] estándar (véase [AttemptLimiterService], más abajo). Sin embargo, no conserva el orden de inserción: los CAPTCHA eliminados de esta manera no son necesariamente los más antiguos, mientras que el [Map] del proyecto [NestJS] permitía eliminar primero los más antiguos. Esta situación solo ocurre en caso de ataque: la aproximación es suficiente;
  • línea 96: el dibujo de la imagen. [internal]: la clase solo es visible dentro de la propia aplicación;
  • líneas 104–136: la “fuente tipográfica”: para cada carácter, una lista de trazos, cada trazo es una secuencia de coordenadas (x, y) en una cuadrícula de 4 × 6. Los corchetes [[...]] son expresiones de colección ([C#] 12), una notación compacta para arreglos;
  • línea 139: los caracteres utilizables, es decir, las claves de la fuente. [..] expande una colección dentro de otra;
  • líneas 146–147 y líneas 149–150: la aleatorización usa [RandomNumberGenerator], un generador criptográfico cuyas salidas son impredecibles;
  • líneas 152–194: la imagen es un texto [SVG], ensamblado en un [StringBuilder] (una cadena que se extiende sin reescribirse cada vez que se agrega un elemento). Cada carácter (líneas 160–181) se convierte en una ruta [<path>]: cada punto de la cuadrícula se desplaza ligeramente, se amplía, se rota y se coloca en su posición dentro de la imagen, con un color y un grosor de línea seleccionados al azar. Los caracteres son líneas, nunca texto: un bot no puede leerlos en el código de la imagen. Luego, tres curvas de distorsión cruzan la imagen (líneas 185–190);
  • línea 199: los números en [SVG] se escriben con punto decimal. [CultureInfo.InvariantCulture] impone esta notación sea cual sea el idioma del servidor: en francés, [ToString()] usaría una coma (véase el Capítulo 5).

11.13.6. Auth/AttemptLimiterService.cs

// =========================================================================
// Auth/AttemptLimiterService.cs
// -------------------------------------------------------------------------
// Segunda línea de defensa contra los robots (la primera es el captcha):
// CONTAMOS los intentos, y al superar un umbral BLOQUEAMOS por un tiempo.
//
//   - inicio de sesión: tras LoginMaxFailures fallos (captcha o contraseña
//     incorrectos) para el mismo login desde la misma dirección IP, este par
//     se bloquea LoginBlockMinutes minutos. La misma dirección IP también se
//     bloquea si acumula 5 veces más fallos, con todos los logins combinados (un
//     robot que prueba miles de logins distintos);
//   - creación de cuentas: como máximo RegistrationMaxPerHour cuentas creadas por
//     hora desde la misma dirección IP.
//
// Atención en un salón de clases: todas las computadoras suelen salir a Internet
// por la MISMA dirección IP. Por eso el bloqueo de inicio de sesión se aplica
// primero al par (IP, login) - un estudiante que se equivoca al escribir su
// contraseña no bloquea a sus compañeros - y por eso los umbrales son ajustables
// en appsettings.json (sección "Protection").
//
// Servicio singleton, invocado por solicitudes en paralelo: todas las
// operaciones sobre los contadores se hacen bajo un lock, lo que garantiza
// que un solo hilo a la vez lee Y modifica un contador.
// =========================================================================

using Microsoft.Extensions.Options;
using RdvMedecins.Config;

namespace RdvMedecins.Auth;

public class AttemptLimiterService(IOptions<ProtectionOptions> options)
{
    private class Counter
    {
        public int Count; // intentos contados en la ventana actual
        public DateTime Start; // inicio de la ventana de conteo
        public DateTime BlockedUntil; // DateTime.MinValue si no está bloqueado
    }

    private static readonly TimeSpan OneHour = TimeSpan.FromHours(1);

    private readonly Dictionary<string, Counter> counters = [];
    private readonly Lock syncLock = new(); // el tipo Lock de .NET 9+, hecho para "lock"

    private readonly int maxLoginFailures = options.Value.LoginMaxFailures;
    private readonly TimeSpan loginBlockDuration = TimeSpan.FromMinutes(options.Value.LoginBlockMinutes);
    private readonly int maxRegistrations = options.Value.RegistrationMaxPerHour;

    // ================================================================ login

    // número de minutos de bloqueo restantes (0 = el intento está permitido)
    public int LoginBlockMinutes(string ip, string login)
    {
        lock (syncLock)
        {
            return Math.Max(RemainingMinutes(LoginKey(ip, login)), RemainingMinutes(IpKey(ip)));
        }
    }

    public void LoginFailure(string ip, string login)
    {
        lock (syncLock)
        {
            Count(LoginKey(ip, login), maxLoginFailures, loginBlockDuration, loginBlockDuration);
            Count(IpKey(ip), maxLoginFailures * 5, loginBlockDuration, loginBlockDuration);
        }
    }

    // un login exitoso reinicia el contador de ESTE login
    public void LoginSuccess(string ip, string login)
    {
        lock (syncLock)
        {
            counters.Remove(LoginKey(ip, login));
        }
    }

    // ================================================================ registro

    public int RegistrationBlockMinutes(string ip)
    {
        lock (syncLock)
        {
            return RemainingMinutes($"registration|{ip}");
        }
    }

    // ventana de una hora; una vez alcanzada la cuota, bloqueado hasta el final de la hora
    public void RegistrationSuccess(string ip)
    {
        lock (syncLock)
        {
            Count($"registration|{ip}", maxRegistrations, OneHour, OneHour);
        }
    }

    // ================================================================ mecánica compartida
    // (los métodos privados siempre se invocan bajo el lock)

    private int RemainingMinutes(string key)
    {
        if (!counters.TryGetValue(key, out var c))
        {
            return 0;
        }
        var remaining = c.BlockedUntil - DateTime.UtcNow;
        return remaining > TimeSpan.Zero ? (int)Math.Ceiling(remaining.TotalMinutes) : 0;
    }

    // cuenta un intento; si se alcanza el umbral dentro de la ventana, bloquea
    private void Count(string key, int max, TimeSpan window, TimeSpan block)
    {
        var now = DateTime.UtcNow;
        Purge(now);
        if (!counters.TryGetValue(key, out var c) || now - c.Start > window)
        {
            c = new Counter { Count = 0, Start = now, BlockedUntil = DateTime.MinValue };
            counters[key] = c;
        }
        c.Count++;
        if (c.Count >= max)
        {
            c.BlockedUntil = now + block;
            c.Count = 0; // después del bloqueo, se empieza de nuevo desde cero
            c.Start = c.BlockedUntil;
        }
    }

    // olvidamos los contadores que ya no son útiles (ni bloqueados, ni recientes)
    private void Purge(DateTime now)
    {
        if (counters.Count < 1000)
        {
            return;
        }
        foreach (var (key, c) in counters.ToList())
        {
            if (c.BlockedUntil < now && now - c.Start > OneHour)
            {
                counters.Remove(key);
            }
        }
    }

    private static string LoginKey(string ip, string login) => $"login|{ip}|{login.Trim().ToLowerInvariant()}";

    private static string IpKey(string ip) => $"ip|{ip}";
}

En comparación con el Ejemplo 27, el limitador protege dos operaciones (la conexión y la creación de cuentas); el bloqueo de la conexión se aplica al par (dirección IP, nombre de usuario), y los umbrales son configurables en [appsettings.json]. Analicemos este código:

  • línea 31: [IOptions<ProtectionOptions>] especifica la sección [Protection] de [appsettings.json] (carpeta [Config]): el número de intentos fallidos de inicio de sesión permitidos (5 de forma predeterminada), la duración del bloqueo (15 minutos) y el número de cuentas creadas por hora (10);
  • líneas 33–37: un contador: el número de intentos, el inicio de la ventana de conteo y el final del bloqueo ([DateTime.MinValue], la fecha más temprana posible, si no hay bloqueo). Es una clase anidada y privada: existe solo para este servicio. Es una clase, no un [record] ni una estructura: un contador leído del diccionario se modifica en su sitio;
  • líneas 42–43: un [Dictionary] ordinario, protegido por un bloqueo (véase el Ejemplo 27). Un [ConcurrentDictionary] no sería suficiente: contar un intento implica leer un contador, modificarlo y posiblemente reemplazarlo, y toda esta secuencia de operaciones debe ejecutarse sin que otra solicitud la interrumpa. Por lo tanto, cada método público realiza su tarea dentro de un bloque [lock (syncLock)];
  • líneas 45–47: los umbrales, leídos una vez para siempre. El parámetro del constructor principal puede usarse para inicializar los campos;
  • líneas 52–56: el tiempo de bloqueo restante para un intento de conexión: el mayor de los dos períodos de bloqueo posibles, el del par (dirección IP, nombre de usuario) y el de la dirección IP sola;
  • líneas 60–65: un intento fallido se cuenta dos veces. Para el par (dirección IP, nombre de usuario): cinco intentos fallidos con el mismo nombre de usuario bloquean ese nombre de usuario, solo desde esa dirección. Para la dirección IP sola, con un umbral cinco veces mayor: un bot que prueba una gran cantidad de nombres de usuario distintos también queda bloqueado. En un aula, todas las computadoras suelen conectarse a Internet a través de la misma dirección IP: un estudiante que introduce mal su contraseña no debe bloquear a sus compañeros, de ahí el bloqueo por par;
  • líneas 70–74: un inicio de sesión correcto restablece el contador de ese nombre de usuario específico (no el de la dirección IP);
  • líneas 80–84 y líneas 89–93: para la creación de cuentas, solo se cuentan los intentos correctos: un máximo de diez cuentas por hora desde la misma dirección IP. Una vez alcanzada la cuota, la dirección se bloquea durante una hora;
  • líneas 100–107: los minutos restantes del bloqueo, redondeados al siguiente número entero ([Math.Ceiling]): muestra “1 minuto” en lugar de “0 minutos” cuando quedan 20 segundos. Estos métodos privados no adquieren el bloqueo: siempre los llama un método público que ya lo tiene;
  • líneas 111–125: el conteo. Una clave desconocida, o una cuya ventana de conteo ha expirado, comienza con un contador nuevo. Cuando se alcanza el umbral, la clave se bloquea y el conteo se reanudará desde cero al final del bloqueo;
  • líneas 130–140: limpieza de los contadores que ya no son necesarios (ni bloqueados ni recientes), que se realiza solo cuando el diccionario supera las 1000 entradas. Se recorre una copia de las entradas ([ToList()]): un [Dictionary] no puede modificarse mientras se recorre;
  • líneas 145–147: generación de las claves del diccionario. Se eliminan los espacios del nombre de usuario y se convierte a minúsculas: [Admin] y [admin] comparten el mismo contador; un bot no puede eludir el bloqueo cambiando las mayúsculas y minúsculas.

11.13.7. Auth/RegistrationPassService.cs

// =========================================================================
// Auth/RegistrationPassService.cs
// -------------------------------------------------------------------------
// El "pase" de creación de cuenta.
//
// Para abrir la página "Create a patient account", primero se debe haber
// copiado el CAPTCHA de la página de autenticación (ver
// RegistrationController, POST /register/access). Entonces el servidor emite
// un pase:
//   - un identificador aleatorio, almacenado en una cookie HttpOnly;
//   - válido durante 15 minutos (el tiempo para llenar el formulario, incluso si requiere
//     varios intentos tras errores de entrada);
//   - consumido apenas se crea una cuenta: UN CAPTCHA resuelto = UNA cuenta como
//     máximo. Un robot no puede crear cuentas en serie.
//
// Sin un pase válido, GET y POST /register redirigen a la
// página de autenticación: escribir directamente la URL /register no permite
// eludir el CAPTCHA.
//
// Igual que el CAPTCHA, los pases viven en la memoria del proceso.
// =========================================================================

using System.Collections.Concurrent;

namespace RdvMedecins.Auth;

public class RegistrationPassService
{
    public const string Cookie = "rdvmedecins_registration";

    private static readonly TimeSpan Lifetime = TimeSpan.FromMinutes(15);
    private const int MaxPasses = 10_000;

    // id -> fecha de expiración
    private readonly ConcurrentDictionary<string, DateTime> passes = new();

    // emite un nuevo pase; devuelve su identificador
    public string Issue()
    {
        Purge();
        var id = Guid.NewGuid().ToString();
        passes[id] = DateTime.UtcNow + Lifetime;
        return id;
    }

    // true si [id] es un pase existente y no expirado
    public bool IsValid(string? id) =>
        id is not null && passes.TryGetValue(id, out var expires) && expires > DateTime.UtcNow;

    // el pase ya se usó: lo olvidamos
    public void Consume(string? id)
    {
        if (id is not null)
        {
            passes.TryRemove(id, out _);
        }
    }

    // el navegador envía la cookie solo a las direcciones /register...
    public static CookieOptions GetCookieOptions() => new()
    {
        HttpOnly = true,
        SameSite = SameSiteMode.Lax,
        MaxAge = Lifetime,
        Path = "/register",
    };

    private void Purge()
    {
        var now = DateTime.UtcNow;
        foreach (var (id, expires) in passes)
        {
            if (expires <= now || passes.Count >= MaxPasses)
            {
                passes.TryRemove(id, out _);
            }
        }
    }
}

Se puede crear una cuenta de cliente desde la página de inicio de sesión, siempre que se haya resuelto el CAPTCHA. El formulario de registro se muestra y se envía mediante solicitudes posteriores: estas solicitudes deben saber que una solicitud anterior resolvió correctamente el CAPTCHA. Este es el papel del pase, emitido y verificado por [RegistrationController] (documentado en los controladores):

  • línea 29: el nombre de la cookie que transporta el pase;
  • líneas 31–35: un pase es válido durante quince minutos; los pases pendientes se conservan en memoria, como los CAPTCHA, con el mismo límite de tiempo;
  • líneas 38–43: un pase es un identificador aleatorio, almacenado junto con su fecha de expiración; el controlador lo coloca en una cookie;
  • líneas 47–48: el formulario de registro se muestra, y se acepta, solo con un pase válido. La verificación no consume el pase ([TryGetValue], no [TryRemove]): el usuario puede volver a enviar el formulario varias veces si cometió errores al introducir los datos;
  • líneas 51–55: la creación de una cuenta consume el pase: resolver un CAPTCHA da derecho a una cuenta, y no más;
  • líneas 60–65: opciones de la cookie. [new()] crea un objeto del tipo declarado por el método ([CookieOptions]). La opción [Path = "/register"] limita el envío de la cookie a las URL que comienzan con [/register]: las demás solicitudes no la transportan innecesariamente;
  • líneas 68–75: el proceso de limpieza, idéntico al del CAPTCHA.

11.13.8. Controllers/AuthController.cs

// =========================================================================
// Controllers/AuthController.cs
// -------------------------------------------------------------------------
// Las rutas NO protegidas del login:
//   GET  /        redirige a la página de inicio del rol (o a /login)
//   GET  /login   muestra el formulario de login (con su CAPTCHA)
//   POST /login   verifica límite de intentos, CAPTCHA, login / contraseña
//   POST /logout  borra la cookie del token
//
// Un controlador MVC hereda de Controller y devuelve un IActionResult:
// View(...) para mostrar una página, Redirect(...) para redirigir...
// [HttpGet("login")] / [HttpPost("login")]: "attribute routing",
// el equivalente de @Get('login') / @Post('login').
//
// Protección contra robots, en este orden:
//   1. ¿demasiados fallos recientes para este login desde esta dirección IP?
//      -> rechazo inmediato, sin siquiera mirar la contraseña;
//   2. ¿respuesta incorrecta al CAPTCHA? -> rechazo (contado como fallo);
//   3. solo entonces, verificación de la contraseña.
// NUNCA verificamos la contraseña de un intento rechazado en los pasos
// 1 o 2: un robot no puede aprender nada insistiendo.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Models;

namespace RdvMedecins.Controllers;

public class AuthController(
    AuthService authService,
    CaptchaService captchaService,
    AttemptLimiterService limiter) : Controller
{
    // la página de inicio de cada rol, justo después de iniciar sesión
    public static string HomePage(Role role) => role == Role.USER ? "/my-area" : "/schedule";

    [HttpGet("/")]
    public IActionResult Home()
    {
        // User: el usuario de la solicitud, reconstruido a partir del token por
        // el middleware de autenticación (ver Auth/ConnectedUser.cs)
        var user = User.CurrentUser();
        return Redirect(user is not null ? HomePage(user.Role) : "/login");
    }

    // GET /login[?login=xxx]: el parámetro opcional rellena previamente el campo
    // de login (se usa justo después de crear una cuenta, ver RegistrationController)
    [HttpGet("login")]
    public IActionResult ShowLogin(string? login)
    {
        // ya con sesión iniciada (token aún válido): directo a la página de inicio
        var user = User.CurrentUser();
        if (user is not null)
        {
            return Redirect(HomePage(user.Role));
        }
        return Form(login is null ? "" : login[..Math.Min(login.Length, 30)]);
    }

    // los parámetros de la acción se llenan con los campos del formulario del
    // mismo nombre (model binding); [FromForm] especifica que se buscan en
    // el cuerpo de la solicitud POST
    [HttpPost("login")]
    public async Task<IActionResult> LogIn(
        [FromForm] string? login,
        [FromForm] string? password,
        [FromForm] string? captchaId,
        [FromForm] string? captcha)
    {
        login = (login ?? "").Trim();
        password ??= "";
        var ip = IpAddress(HttpContext);

        // 1. ¿demasiados fallos recientes?
        var minutes = limiter.LoginBlockMinutes(ip, login);
        if (minutes > 0)
        {
            return Form(login, "ERRORS.TOO_MANY_ATTEMPTS", new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }

        // 2. el CAPTCHA
        if (!captchaService.Verify(captchaId, captcha))
        {
            limiter.LoginFailure(ip, login);
            return Form(login, "ERRORS.WRONG_CAPTCHA");
        }

        // 3. la contraseña
        var user = login != "" && password != "" ? await authService.ValidateUserAsync(login, password) : null;
        if (user is null)
        {
            limiter.LoginFailure(ip, login);
            return Form(login, "LOGIN.ERROR");
        }

        limiter.LoginSuccess(ip, login);
        authService.SetToken(Response, user);
        return Redirect(HomePage(user.Role));
    }

    // logout con un POST (y no con un simple enlace GET): un sitio de terceros no puede
    // cerrar la sesión del usuario sin que lo sepa (ver SameSite, AuthService)
    [HttpPost("logout")]
    public IActionResult LogOut()
    {
        AuthService.ClearToken(Response);
        return Redirect("/login");
    }

    // la dirección IP del visitante. Detrás de un proxy inverso (nginx...), habría que
    // activar el middleware UseForwardedHeaders para obtener la del
    // visitante y no la del proxy.
    public static string IpAddress(HttpContext http) => http.Connection.RemoteIpAddress?.ToString() ?? "unknown";

    // el formulario, siempre con un CAPTCHA NUEVO (cada imagen se usa una sola vez)
    private ViewResult Form(string login, string? error = null, IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Login", new LoginModel
        {
            PageTitle = "LOGIN.TITLE",
            Login = login, // volvemos a mostrar el login escrito, nunca la contraseña
            Captcha = captchaService.Generate(),
            Error = error,
            ErrorParams = errorParams,
        });
}

Comentemos este código:

  • líneas 31–34: el controlador recibe los tres servicios que necesita. Sin atributos [[Authorize]]: sus páginas son accesibles sin haber iniciado sesión;
  • línea 37: la página de inicio depende del rol: “Mi área” para un paciente, el calendario para los demás;
  • líneas 39–45: la raíz del sitio redirige a la página de inicio específica del rol o a la página de inicio de sesión. El middleware de autenticación se ejecuta para todas las solicitudes, protegidas o no: si la cookie contiene un token válido, [User] se rellena, incluso aquí. En cambio, el proyecto [NestJS] debía verificar el token por sí mismo (método [readToken]), ya que la verificación del token no se aplica a esta ruta;
  • líneas 50–59: un usuario que ya ha iniciado sesión se redirige a su página de inicio. El parámetro opcional [login], que proviene de la URL (véase el Ejemplo 07), rellena previamente el campo después de crear una cuenta. [login[..n]] (operador de rango) conserva los primeros [n] caracteres: su longitud se limita a 30, porque los datos de la solicitud nunca se usan sin tomar precauciones;
  • líneas 65–70: los campos del formulario de inicio de sesión (véase el Ejemplo 11), incluidos el identificador del CAPTCHA, transmitido mediante un campo oculto, y el texto introducido por el usuario. Todos se declaran como [string?]: un campo ausente produce [null], y es la acción la que determina qué hacer con él;
  • líneas 72–74: un nombre de usuario ausente se convierte en una cadena vacía; [password ??= ""] solo afecta a la cadena vacía si [password] es [null];
  • líneas 77–80: 1. un par bloqueado ni siquiera se procesa: no se comprueba ni el CAPTCHA ni la contraseña. El error es una clave de traducción con un parámetro: el número de minutos que hay que esperar;
  • líneas 84–87: 2. el CAPTCHA. Un CAPTCHA incorrecto cuenta como un fallo (véase el ejemplo 27);
  • líneas 91–95: 3. Solo entonces se comprueba la contraseña. Un nombre de usuario o una contraseña vacíos no se someten al costoso cálculo de [bcrypt]. Nombre de usuario desconocido o contraseña incorrecta: el mismo mensaje deliberadamente vago (véase el Ejemplo 25) y otro fallo;
  • líneas 98–100: éxito: contador restablecido a cero, token almacenado en la cookie, redirección a la página de inicio del rol;
  • líneas 105–109: cierre de sesión, mediante POST (véase el Ejemplo 25);
  • línea 115: la dirección IP del cliente, proporcionada por la conexión de red ([RemoteIpAddress], que puede ser [null], de ahí [?.] y [??]). El método es público y estático: [RegistrationController] y [PatientAreaController] también lo usan para el limitador. Detrás de un servidor intermediario (un proxy inverso como [nginx]), esta dirección sería la del proxy: el comentario especifica el middleware que se debe habilitar en este caso;
  • líneas 118–125: la página de inicio de sesión, siempre con un CAPTCHA nuevo : cada imagen se usa una sola vez. Su modelo, [LoginModel] (carpeta [Models]), contiene el título de la página (una clave de traducción), el nombre de usuario introducido (nunca la contraseña), el CAPTCHA y los posibles mensajes de error, junto con la clave de traducción y los parámetros. [error] y [errorParams] son parámetros opcionales: toman por defecto el valor [null] cuando la llamada no los proporciona.

11.14. La capa web: servicios compartidos

Antes de llegar a los controladores y las vistas, veamos lo que tienen en común: la traducción, la clase padre de las vistas, los mensajes flash, el filtro de excepciones, la caché de las listas de médicos y clientes, la preparación de los formularios que se vuelven a mostrar y algunas funciones de utilidad. Todos estos archivos están en la carpeta [Web]. Reúne la mayoría de las técnicas de los ejemplos 16 a 24.

11.14.1. Web/Translator.cs

// =========================================================================
// Web/Translator.cs
// -------------------------------------------------------------------------
// Traducción francés / inglés de la interfaz.
//
// Los diccionarios son los MISMOS archivos que los del proyecto NestJS
// (i18n/fr.json, i18n/en.json), leídos una sola vez al inicio. Una vista
// Razor traduce una clave con @T("KEY") (ver Web/ViewPage.cs).
//
// ASP.NET Core también ofrece su propio sistema (IStringLocalizer y
// archivos .resx); conservar los archivos JSON permite compartir los
// diccionarios con las otras versiones de la aplicación.
//
// EL IDIOMA ACTUAL: es el middleware de localización de ASP.NET Core
// (UseRequestLocalization, ver Program.cs) quien lo determina en cada solicitud,
// a partir de una cookie, y lo almacena en CultureInfo.CurrentUICulture.
// =========================================================================

using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;

namespace RdvMedecins.Web;

public partial class Translator
{
    public static readonly string[] Languages = ["fr", "en"];
    public const string DefaultLanguage = "en";

    // idioma -> (clave completa "LOGIN.TITLE" -> texto)
    private readonly Dictionary<string, Dictionary<string, string>> dictionaries = [];

    public Translator(IWebHostEnvironment environment)
    {
        foreach (var language in Languages)
        {
            var path = Path.Combine(environment.ContentRootPath, "i18n", $"{language}.json");
            using var document = JsonDocument.Parse(File.ReadAllText(path));
            var dictionary = new Dictionary<string, string>();
            Flatten(document.RootElement, "", dictionary);
            dictionaries[language] = dictionary;
        }
    }

    // el idioma de la solicitud actual: "fr" o "en"
    public static string CurrentLanguage()
    {
        var language = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
        return Languages.Contains(language) ? language : DefaultLanguage;
    }

    // -----------------------------------------------------------------------
    // Translate("DOCTORS.ADDED", { ["name"] = "Marie PELISSIER" })
    //   -> busca "DOCTORS.ADDED" en el diccionario del idioma actual,
    //      y reemplaza {name} por su valor. Una clave ausente del idioma
    //      solicitado se busca en el idioma predeterminado; si falta en todas partes,
    //      se muestra la propia clave (así una omisión se detecta de inmediato).
    // -----------------------------------------------------------------------
    public string Translate(string? key, IReadOnlyDictionary<string, string>? messageParams = null)
    {
        if (string.IsNullOrEmpty(key))
        {
            return "";
        }
        var text = dictionaries[CurrentLanguage()].GetValueOrDefault(key)
                    ?? dictionaries[DefaultLanguage].GetValueOrDefault(key)
                    ?? key;
        if (messageParams is null || messageParams.Count == 0)
        {
            return text;
        }
        return Parameter().Replace(text, m => messageParams.TryGetValue(m.Groups[1].Value, out var value) ? value : m.Value);
    }

    // { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
    private static void Flatten(JsonElement node, string prefix, Dictionary<string, string> result)
    {
        foreach (var property in node.EnumerateObject())
        {
            var key = prefix == "" ? property.Name : $"{prefix}.{property.Name}";
            if (property.Value.ValueKind == JsonValueKind.Object)
            {
                Flatten(property.Value, key, result);
            }
            else
            {
                result[key] = property.Value.GetString() ?? "";
            }
        }
    }

    // la expresión regular {name}, compilada de una vez por todas por el
    // compilador de C# ([GeneratedRegex] "source generator")
    [GeneratedRegex(@"\{(\w+)\}")]
    private static partial Regex Parameter();
}

Este es el servicio de traducción del Ejemplo 22, registrado como singleton en [Program.cs]: los diccionarios [i18n/fr.json] y [i18n/en.json] son los mismos archivos que los de la versión [NestJS], leídos una sola vez al inicio. Solo hay una diferencia:

  • líneas 65–67: una clave que falta en el diccionario francés se busca en el diccionario inglés ([DefaultLanguage]); si falta en todas partes, se muestra la propia clave. Los dos operadores [??] se encadenan: se toma el primer valor que no sea [null].

11.14.2. Web/ViewPage.cs

// =========================================================================
// Web/ViewPage.cs
// -------------------------------------------------------------------------
// La clase padre de TODAS las vistas Razor de la aplicación (ver
// Views/_ViewImports.cshtml: @inherits ViewPage<TModel>).
//
// Una vista .cshtml se compila en una clase C#, hija de RazorPage<TModel>.
// Al insertar nuestra propia clase, damos a todas las vistas lo que
// necesitan, sea cual sea la página:
//   - @T("KEY")          : la traducción de una clave (el equivalente del
//                          helper de Handlebars {{t 'KEY'}});
//   - Language           : "fr" o "en";
//   - CurrentUser        : el usuario conectado, para la barra de navegación;
//   - FlashMessage       : el mensaje flash de la solicitud;
//   - CurrentPath        : la URL solicitada (menú activo de la barra de navegación).
// En NestJS, esta información pasaba por res.locals.
// =========================================================================

using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Razor.Internal;
using RdvMedecins.Auth;

namespace RdvMedecins.Web;

public abstract class ViewPage<TModel> : RazorPage<TModel>
{
    // [RazorInject]: la propiedad se llena mediante inyección de dependencias,
    // como lo haría la directiva @inject en una vista
    [RazorInject]
    public Translator Translator { get; set; } = null!;

    // -----------------------------------------------------------------------
    // @T("BOOKING_DIALOG.SLOT", ("time", "8:00 - 8:20"))
    // Los parámetros son "tuplas" (nombre, valor): una sintaxis compacta
    // para escribir pares de valores.
    // El texto devuelto se ESCAPA luego por Razor (< pasa a ser &lt;): un nombre
    // escrito por un usuario no puede por lo tanto inyectar HTML en la página.
    // -----------------------------------------------------------------------
    public string T(string? key, params (string Name, object? Value)[] messageParams) =>
        Translator.Translate(key, messageParams.ToDictionary(p => p.Name, p => p.Value?.ToString() ?? ""));

    // lo mismo, con los parámetros de un mensaje flash o de una BusinessException
    public string T(string? key, IReadOnlyDictionary<string, string>? messageParams) => Translator.Translate(key, messageParams);

    public string Language => Translator.CurrentLanguage();

    public ViewUser? CurrentUser => ViewUser.Of(Context.User.CurrentUser());

    public FlashMessage? FlashMessage => Flash.Read(Context);

    public string CurrentPath => Context.Request.Path.Value ?? "/";

    // "active" si la página actual está bajo esta ruta (menú de la barra de navegación)
    public string Active(string prefix) => CurrentPath.StartsWith(prefix, StringComparison.Ordinal) ? "active" : "";
}

// -------------------------------------------------------------------------
// el usuario conectado, tal como lo ven las vistas
// -------------------------------------------------------------------------
public record ViewUser(string Login, string Name, string Role, bool IsAdmin, bool IsPatient)
{
    public static ViewUser? Of(ConnectedUser? u) =>
        u is null
            ? null
            : new ViewUser(
                u.Login,
                u.Name,
                u.Role.ToString(),
                IsAdmin: u.Role == Entities.Role.ADMIN, // ADMIN: menús Doctors / Patients
                IsPatient: u.Role == Entities.Role.USER); // USER: menú My area
}

Analicemos este código:

  • línea 25: la clase padre de todas las vistas, designada por la directiva [@inherits] de [Views/_ViewImports.cshtml], como en el Ejemplo 22. Cumple la misma función que [res.locals] en la versión [NestJS]: proporciona a cada vista lo que todas las páginas necesitan;
  • líneas 29–30: el servicio de traducción, inyectado en la propiedad (véase el Ejemplo 22);
  • líneas 39–40: el método [T] del Ejemplo 22: [@T("KEY", ("name", value))]. El texto generado lo escapa [Razor]: un nombre introducido por un usuario no puede inyectar HTML en la página;
  • línea 43: una segunda versión de [T], que acepta directamente un diccionario: esta es la forma en que se pasan los parámetros de un mensaje flash o de una [BusinessException]. Dos métodos con el mismo nombre, que difieren en sus parámetros, son métodos sobrecargados: el compilador selecciona el correcto según los argumentos;
  • línea 45: el idioma actual ([fr] o [en]), para el atributo [lang] de la página y el selector FR / EN;
  • línea 47: el usuario conectado, para la barra de navegación, o [null] si no hay ninguno. [Context.User] es el usuario de la solicitud, reconstruido a partir del token JWT por el middleware de autenticación (véase el Capítulo 8); el método [CurrentUser()] (archivo [Auth/ConnectedUser.cs]) extrae de él la cuenta. En la versión [NestJS], se requería un interceptor para copiar [req.user] en [res.locals] después de los guardias; aquí, la propiedad se calcula cuando la vista la lee, mucho después de la autenticación;
  • línea 49: el mensaje flash de la solicitud (véase [Web/Flash.cs], más abajo);
  • líneas 51–54: la ruta de la URL solicitada, y el método que devuelve [active] si la página actual está bajo una ruta determinada: así es como la barra de navegación resalta el elemento de menú actual, por ejemplo [@Active("/my-")] (véase el Ejemplo 16). [StringComparison.Ordinal] compara los caracteres uno por uno, sin tener en cuenta el idioma;
  • líneas 60–70: el usuario conectado tal como lo ven las vistas: nombre de usuario, nombre, rol y dos booleanos, [IsAdmin] y [IsPatient], que evitan que las vistas tengan que comparar roles. El método estático [Of] crea este objeto a partir de la cuenta conectada, o devuelve [null]; el operador [? :] elige entre los dos. Los argumentos [IsAdmin:] y [IsPatient:] son con nombre: el nombre del parámetro se escribe antes del valor, lo que hace la llamada más legible.

11.14.3. Web/Flash.cs

// =========================================================================
// Web/Flash.cs
// -------------------------------------------------------------------------
// Los mensajes "flash": un mensaje que se muestra UNA SOLA VEZ, en la
// página SIGUIENTE. Es el complemento natural del patrón "Post / Redirect / Get"
// usado por todos los formularios de la aplicación: un POST exitoso no
// construye una página, redirige (302) a una página GET - si
// el usuario recarga esta página (F5), el navegador no envía
// el formulario por segunda vez. El mensaje, sin embargo, debe sobrevivir a la
// redirección.
//
// En NestJS, lo habíamos programado nosotros mismos (una cookie de corta duración).
// ASP.NET Core MVC lo ofrece de forma estándar: es TempData. Un valor almacenado
// en TempData se conserva (por defecto en una cookie cifrada) hasta que
// una solicitud siguiente lo LEE; entonces se borra.
// =========================================================================

using System.Text.Json;
using Microsoft.AspNetCore.Mvc.ViewFeatures;

namespace RdvMedecins.Web;

public enum FlashType
{
    Success, // clase Bootstrap alert-success: en la parte superior de la página
    Danger, // un error: en la parte inferior de la página (ver Views/Shared/_Errors.cshtml)
}

// Key: clave de traducción; Params: sus parámetros ({name}, {login}...)
public record FlashMessage(FlashType Type, string Key, Dictionary<string, string>? Params = null);

public static class Flash
{
    private const string Key = "flash";

    // -----------------------------------------------------------------------
    // coloca un mensaje flash, que mostrará la página SIGUIENTE.
    // Pasamos por ITempDataDictionaryFactory (y no por la propiedad TempData
    // de un controlador) para poder colocar un mensaje desde CUALQUIER LUGAR:
    // un controlador, pero también la autenticación JWT (sesión expirada, ver
    // Auth/JwtAuthentication.cs), que se ejecuta fuera de MVC.
    // -----------------------------------------------------------------------
    public static void Put(HttpContext http, FlashType type, string key, Dictionary<string, string>? messageParams = null)
    {
        var tempData = TempDataOf(http);
        // TempData solo puede conservar valores simples: almacenamos el
        // mensaje como texto JSON
        tempData[Key] = JsonSerializer.Serialize(new FlashMessage(type, key, messageParams));
        // Save(): escribe la cookie de inmediato (fuera de MVC, nadie
        // lo haría por nosotros)
        tempData.Save();
    }

    // -----------------------------------------------------------------------
    // lee (y por lo tanto borra) el mensaje flash de la solicitud. La página puede
    // pedirlo varias veces (el mensaje de éxito se muestra arriba, el de
    // error abajo): lo conservamos en HttpContext.Items, un diccionario
    // que vive durante el tiempo de la solicitud.
    // -----------------------------------------------------------------------
    public static FlashMessage? Read(HttpContext http)
    {
        if (http.Items.TryGetValue(Key, out var alreadyRead))
        {
            return alreadyRead as FlashMessage;
        }
        FlashMessage? message = null;
        if (TempDataOf(http)[Key] is string json)
        {
            try
            {
                message = JsonSerializer.Deserialize<FlashMessage>(json);
            }
            catch (JsonException)
            {
                // mensaje ilegible: lo ignoramos
            }
        }
        http.Items[Key] = message;
        return message;
    }

    private static ITempDataDictionary TempDataOf(HttpContext http) =>
        http.RequestServices.GetRequiredService<ITempDataDictionaryFactory>().GetTempData(http);
}

Comentemos este código:

  • líneas 23–26: los dos tipos de mensajes: un mensaje de éxito, mostrado en la parte superior de la página (vista parcial [_Flash.cshtml]), y un mensaje de error, mostrado en la parte inferior (vista parcial [_Errors.cshtml]);
  • línea 30: un mensaje flash consta de una clave de traducción y sus parámetros, no de un texto ya traducido; se traducirá en la página siguiente, en el idioma de esa página;
  • línea 32: una clase estática que contiene solo funciones (véase [Web/Utils.cs]). [TempData] (véase el Ejemplo 20) hace la mayor parte del trabajo: almacena el valor en una cookie cifrada hasta la siguiente solicitud y lo elimina una vez leído. En la versión [NestJS], esta cookie de corta duración se había programado manualmente;
  • líneas 43–51: establece un mensaje. [TempData] solo puede almacenar valores simples (texto, números): el mensaje se almacena como JSON de texto ([JsonSerializer.Serialize]). El método recibe el [HttpContext] y no la propiedad [TempData] de un controlador: por lo tanto, puede llamarse desde fuera de MVC, por ejemplo desde la autenticación JWT, cuando una sesión ha expirado (véase [Auth/JwtAuthentication.cs]). Fuera de MVC, nadie guardaría [TempData] al final de la solicitud: [Save()] escribe la cookie de inmediato;
  • líneas 60–79: lee el mensaje de la solicitud. Leer [TempData] lo marca como consumido; sin embargo, la página lo solicita dos veces (en la parte superior para un éxito, en la parte inferior para un error). Por lo tanto, la primera llamada almacena el resultado en [HttpContext.Items], el diccionario de ámbito de solicitud (véase el Capítulo 6), donde la segunda llamada lo recupera (línea 62);
  • líneas 71–73: [Deserialize] reconstruye el objeto [FlashMessage] a partir del JSON. Un texto ilegible no debe hacer fallar la página: se captura la excepción y se ignora el mensaje;
  • líneas 82–83: el [TempData] de la solicitud, obtenido del servicio [ITempDataDictionaryFactory]. [RequestServices] da acceso a la inyección de dependencias desde una clase estática, que no puede recibir servicios mediante su constructor.

11.14.4. Web/HtmlExceptionFilter.cs

// =========================================================================
// Web/HtmlExceptionFilter.cs
// -------------------------------------------------------------------------
// Cómo los errores se convierten en páginas HTML. Tres mecanismos
// de ASP.NET Core se reparten el trabajo (ver Program.cs):
//
//   1. este filtro de excepciones MVC: una InvalidSessionException (cuenta
//      eliminada desde el login) -> de vuelta a la página de login;
//   2. UseStatusCodePagesWithReExecute("/error/{0}"): toda respuesta 400,
//      403 o 404 SIN contenido (return BadRequest(), rol insuficiente, página
//      desconocida...) se reemplaza por la página de error correspondiente;
//   3. UseExceptionHandler("/error/500"): cualquier otra excepción (una verdadera
//      anomalía) se escribe en el registro del servidor, y el usuario
//      ve la página de error 500, nunca la pila de llamadas.
//
// En NestJS, un único filtro (HtmlExceptionFilter) hacía todo esto.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using RdvMedecins.Auth;

namespace RdvMedecins.Web;

public class HtmlExceptionFilter : IExceptionFilter
{
    public void OnException(ExceptionContext context)
    {
        if (context.Exception is InvalidSessionException)
        {
            AuthService.ClearToken(context.HttpContext.Response);
            Flash.Put(context.HttpContext, FlashType.Danger, "ERRORS.SESSION_EXPIRED");
            context.Result = new RedirectResult("/login");
            context.ExceptionHandled = true;
        }
        // las otras excepciones no se manejan aquí: suben
        // hasta UseExceptionHandler (página 500)
    }
}

Comentemos este código:

  • Línea 25: un filtro de excepciones, como en el Ejemplo 24, agregado como filtro global en [Program.cs]. En la versión [NestJS], un único filtro convertía todos los errores en páginas HTML. Aquí, el trabajo se reparte entre dos componentes de middleware del framework, configurados en [Program.cs]: [UseStatusCodePagesWithReExecute] reemplaza las respuestas 400, 403 y 404 sin contenido por la página de error correspondiente (véase el Ejemplo 24), y [UseExceptionHandler("/error/500")] intercepta todas las demás excepciones: el error se registra en el registro del servidor, junto con su pila de llamadas, pero el usuario solo ve la página de error 500, ya que estos detalles podrían ayudar a un atacante;
  • líneas 29–34: el filtro maneja un solo escenario: la cuenta del usuario conectado fue eliminada después de iniciar sesión, aunque su token sigue siendo válido (vea [Web/Utils.cs], más adelante). Se borra la cookie del token, se muestra un mensaje flash de «sesión expirada» y se redirige al usuario a la página de inicio de sesión. Las demás excepciones no se marcan como gestionadas: continúan hacia [UseExceptionHandler].

11.14.5. Web/ApplicationModel.cs

// =========================================================================
// Web/ApplicationModel.cs
// -------------------------------------------------------------------------
// El caché / fachada ya presente en el servidor JSON (equivalente de la
// clase [ApplicationModel] del proyecto Spring): las listas de médicos y
// clientes se leen una vez al inicio y luego se sirven desde la memoria.
//
// Estas listas pueden CAMBIAR (el ADMIN agrega, edita y elimina
// médicos y clientes): cada escritura pasa por lo tanto por esta fachada,
// que recarga la lista afectada inmediatamente después. Ese es todo el sentido de un
// PUNTO DE ENTRADA ÚNICO a la capa de negocio: la regla "escritura =>
// recarga del caché" se escribe solo aquí.
//
// Diferencia importante con NestJS: el CICLO DE VIDA de los objetos.
//   - En NestJS, todos los servicios eran singletons.
//   - Aquí, el DbContext - y por lo tanto los repositorios y la capa de negocio - vive
//     durante UNA solicitud HTTP (ciclo de vida "scoped", ver Program.cs).
//   - Pero el caché debe sobrevivir de una solicitud a la siguiente.
// Por eso separamos los dos roles:
//   - ListCache (singleton): las dos listas, y nada más;
//   - ApplicationModel (scoped): la fachada, que usa la capa de negocio de
//     la solicitud actual y actualiza el caché.
// =========================================================================

using RdvMedecins.Domain;
using RdvMedecins.Entities;
using RdvMedecins.Business;

namespace RdvMedecins.Web;

// -------------------------------------------------------------------------
// El caché propiamente dicho, compartido por todas las solicitudes (singleton).
//
// ASP.NET Core procesa las solicitudes EN PARALELO, en varios hilos (Node,
// por su parte, tiene uno solo). Por eso nunca modificamos una lista in situ: la
// REEMPLAZAMOS por completo con una nueva. Intercambiar una referencia es atómico;
// "volatile" garantiza que todos los hilos vean de inmediato la nueva lista.
// -------------------------------------------------------------------------
public class ListCache
{
    private volatile IReadOnlyList<Doctor> doctors = [];
    private volatile IReadOnlyList<Client> clients = [];

    public IReadOnlyList<Doctor> Doctors
    {
        get => doctors;
        set => doctors = value;
    }

    public IReadOnlyList<Client> Clients
    {
        get => clients;
        set => clients = value;
    }
}

// -------------------------------------------------------------------------
// La fachada (scoped): mismo contrato que la capa de negocio (IBusiness).
// -------------------------------------------------------------------------
public class ApplicationModel(IBusiness business, ListCache cache) : IBusiness
{
    // carga inicial de las dos listas, invocada una sola vez al inicio
    // (ver Program.cs). Si la base de datos es inaccesible, la excepción detiene el
    // servidor con un mensaje explícito - más claro que iniciar "vacío".
    public async Task LoadAsync()
    {
        await ReloadDoctorsAsync();
        await ReloadClientsAsync();
    }

    private async Task ReloadDoctorsAsync() => cache.Doctors = await business.GetAllDoctorsAsync();

    private async Task ReloadClientsAsync() => cache.Clients = await business.GetAllClientsAsync();

    // ================================================ lecturas desde el caché

    public Task<List<Doctor>> GetAllDoctorsAsync() => Task.FromResult(cache.Doctors.ToList());

    public Task<List<Client>> GetAllClientsAsync() => Task.FromResult(cache.Clients.ToList());

    // el médico cuya cuenta de usuario es [userId] - sirve para preseleccionar,
    // para un médico conectado, su propia agenda
    public Doctor? GetDoctorByUserId(int userId) => cache.Doctors.FirstOrDefault(d => d.UserId == userId);

    // ================================================ delegaciones simples

    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) => business.GetAllSlotsAsync(doctorId);

    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) => business.GetDoctorDayAppointmentsAsync(doctorId, day);

    public Task<Client?> GetClientByIdAsync(int id) => business.GetClientByIdAsync(id);

    public Task<Doctor?> GetDoctorByIdAsync(int id) => business.GetDoctorByIdAsync(id);

    public Task<Appointment?> GetAppointmentByIdAsync(int id) => business.GetAppointmentByIdAsync(id);

    public Task<Slot?> GetSlotByIdAsync(int id) => business.GetSlotByIdAsync(id);

    public Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day) =>
        business.GetDoctorDayScheduleAsync(doctorId, day);

    // sin caché aquí: lo que importa son los datos más recientes (un paciente
    // que acaba de editar o eliminar su cuenta)
    public Task<Client?> GetClientByUserIdAsync(int userId) => business.GetClientByUserIdAsync(userId);

    public Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId) => business.GetClientUpcomingAppointmentsAsync(clientId);

    public Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client) => business.AddAppointmentAsync(day, slot, client);

    public Task DeleteAppointmentAsync(Appointment appointment) => business.DeleteAppointmentAsync(appointment);

    // ================================================ escrituras => recarga

    public async Task<Doctor> AddDoctorAsync(PersonData data)
    {
        var doctor = await business.AddDoctorAsync(data);
        await ReloadDoctorsAsync();
        return doctor;
    }

    public async Task<Doctor> EditDoctorAsync(int id, PersonData data)
    {
        var doctor = await business.EditDoctorAsync(id, data);
        await ReloadDoctorsAsync();
        return doctor;
    }

    public async Task DeleteDoctorAsync(int id)
    {
        await business.DeleteDoctorAsync(id);
        await ReloadDoctorsAsync();
    }

    public async Task<Client> AddClientAsync(PersonData data)
    {
        var client = await business.AddClientAsync(data);
        await ReloadClientsAsync();
        return client;
    }

    public async Task<Client> EditClientAsync(int id, PersonData data)
    {
        var client = await business.EditClientAsync(id, data);
        await ReloadClientsAsync();
        return client;
    }

    public async Task DeleteClientAsync(int id)
    {
        await business.DeleteClientAsync(id);
        await ReloadClientsAsync();
    }
}

Las listas de médicos y de clientes se muestran en casi todas las páginas (listas desplegables del calendario, páginas de administración). En lugar de recuperarlas de la base de datos en cada solicitud, se conservan en memoria: son datos de ámbito de aplicación (vea el Capítulo 6). La versión [NestJS] confiaba este rol a un único servicio, que era un singleton como todos los servicios de [NestJS]. En [ASP.NET Core], esto es imposible: la capa de negocio utiliza [DbContext], que existe únicamente durante una solicitud (servicio [Scoped]; vea el Capítulo 9), y un singleton no puede recibir un servicio [Scoped]. Por lo tanto, separamos los dos roles en dos clases.

Comentemos este código:

  • línea 39: la caché propiamente dicha, registrada como singleton ([AddSingleton<ListCache>()] en [Program.cs]). Contiene únicamente las dos listas;
  • líneas 41–42: [ASP.NET Core] procesa las solicitudes en paralelo en varios hilos ([threads]), mientras que [Node.js] solo tiene uno. Por lo tanto, una lista compartida nunca debe modificarse mientras otra solicitud la está recorriendo. La regla que elegimos es sencilla: nunca modificamos una lista; la reemplazamos por una nueva. Reemplazar una referencia se hace en una sola operación, y la palabra clave [volatile] garantiza que todos los hilos vean de inmediato la nueva lista. [IReadOnlyList] solo permite la lectura: el compilador prohíbe agregar o quitar un elemento;
  • línea 60: la fachada, registrada como servicio [Scoped] ([AddScoped<ApplicationModel>()]). Recibe la capa de negocio de la solicitud actual y la caché compartida. Implementa la misma interfaz [IBusiness] que la capa de negocio: para los controladores, es la capa de negocio, y es la única que reciben;
  • líneas 65–68: la carga inicial de las dos listas. Se llama una sola vez, desde [Program.cs], antes de que arranque el servidor. Un servicio [Scoped] solo existe dentro de un ámbito: [Program.cs] crea uno para este fin ([CreateScope]). Si la base de datos no está accesible, la excepción termina la aplicación con un mensaje explícito, lo cual es preferible a iniciar un servidor con listas vacías;
  • líneas 71–73: recarga de una lista: la lista completa se lee de la base de datos y reemplaza a la que está en la caché;
  • líneas 77–79: las listas se sirven desde la memoria. La interfaz [IBusiness] declara un método asíncrono: [Task.FromResult] crea una tarea ya completada, que contiene el resultado. [ToList()] devuelve una copia de la lista: quien la llama puede modificarla sin afectar la caché;
  • línea 83: el médico asociado a una cuenta, recuperado de la caché: un médico que ha iniciado sesión ve de inmediato su propia agenda;
  • líneas 87–110: las demás solicitudes se reenvían tal cual a la capa de negocio;
  • línea 104: un cliente asociado a una cuenta intencionalmente no se busca en la caché; un paciente que acaba de modificar o eliminar su cuenta debe mostrarse tal como aparece en la base de datos;
  • líneas 114–151: toda operación de escritura que involucre médicos o clientes va seguida de una actualización de la lista correspondiente. Como este servicio es el único punto de entrada de los controladores a la capa de negocio, la regla «escritura = actualización de la caché» se implementa únicamente aquí, y la caché no puede quedar desactualizada. Si la capa de negocio rechaza la operación ([BusinessException]), la excepción termina el método antes de que se recargue la caché, ya que este paso deja de ser necesario.

11.14.6. Web/Validation.cs

// =========================================================================
// Web/Validation.cs
// -------------------------------------------------------------------------
// Lo necesario para VOLVER A MOSTRAR un formulario rechazado: los errores de entrada
// campo por campo, y los campos que se deben resaltar en rojo.
// =========================================================================

using Microsoft.AspNetCore.Mvc.ModelBinding;
using RdvMedecins.Models;

namespace RdvMedecins.Web;

public static class Validation
{
    // -----------------------------------------------------------------------
    // ModelState (llenado por MVC al enlazar el formulario) -> el
    // diccionario campo -> clave de mensaje, conservando solo el primer
    // mensaje de cada campo: { "LastName": "ERRORS.LASTNAME_REQUIRED", ... }
    // -----------------------------------------------------------------------
    public static Dictionary<string, string> ErrorsOf(ModelStateDictionary modelState)
    {
        var errors = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        foreach (var (field, entry) in modelState)
        {
            if (entry.Errors.Count > 0)
            {
                var message = entry.Errors[0].ErrorMessage;
                errors[field] = string.IsNullOrEmpty(message) ? "ERRORS.INVALID_FORM" : message;
            }
        }
        return errors;
    }

    // -----------------------------------------------------------------------
    // los campos del formulario afectados por cada error de negocio de tipo
    // "input" (un duplicado): se resaltan en rojo, y el mensaje va en la parte inferior de la página
    // -----------------------------------------------------------------------
    public static readonly Dictionary<string, string[]> BusinessErrorFields = new()
    {
        ["ERRORS.LOGIN_TAKEN"] = ["login"],
        ["ERRORS.DOCTOR_ALREADY_EXISTS"] = ["firstName", "lastName"],
        ["ERRORS.PATIENT_ALREADY_EXISTS"] = ["firstName", "lastName"],
    };

    // -----------------------------------------------------------------------
    // prepara un modelo de formulario para su (re)visualización:
    //   errors       : mensaje bajo cada campo rechazado por la validación
    //   error        : EL mensaje de error de la página, mostrado en la parte inferior;
    //                  por defecto "The form contains errors." si hay
    //                  errores de campo
    //   otherFields  : campos que se resaltan en rojo SIN mensaje propio
    // -----------------------------------------------------------------------
    public static T Prepare<T>(
        T model,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) where T : FormView
    {
        model.Errors = errors ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        model.InvalidFields = new HashSet<string>(model.Errors.Keys.Concat(otherFields ?? []), StringComparer.OrdinalIgnoreCase);
        model.Error = error ?? (model.Errors.Count > 0 ? "ERRORS.INVALID_FORM" : null);
        model.ErrorParams = errorParams;
        return model;
    }
}

Comentemos este código:

  • Líneas 20–31: convierten [ModelState] (vea los ejemplos 07 y 19) en un diccionario simple «campo → clave de mensaje». Solo se conserva el primer mensaje de cada campo: se muestra un único mensaje debajo del campo. El diccionario ignora las mayúsculas (línea 22): [ModelState] nombra los campos según las propiedades ([LastName], [Login]), mientras que las vistas los solicitan según los campos HTML ([lastName], [login]);
  • líneas 27–28: por precaución, a un error sin mensaje (como el causado por una excepción) se le asigna el mensaje genérico [ERRORS.INVALID_FORM];
  • líneas 38–42: ciertos errores de la capa de negocio se refieren a campos específicos: un nombre de usuario que ya está en uso, o un médico o cliente con el mismo nombre. Estos campos se resaltarán en rojo, con el mensaje mostrado al pie de la página. La sintaxis [["key"] = value] rellena el diccionario en cuanto se crea;
  • líneas 53–64: prepara una plantilla de formulario para mostrarlo o volver a mostrarlo: los mensajes debajo de los campos ([Errors]), los campos que se enmarcarán en rojo ([InvalidFields]: los que tienen un mensaje, más los campos [otherFields], línea 61), el mensaje al pie de la página y sus parámetros. A falta de un mensaje explícito, los errores de campo producen el mensaje «El formulario contiene errores» (línea 62). El método es genérico: la restricción [where T : FormView] (línea 58) acepta cualquier modelo derivado de [FormView] (vea [Models/ViewModels.cs]), y devuelve el modelo con su tipo exacto, listo para pasarlo a [View]. Los parámetros tienen valores predeterminados ([= null]): quien llama proporciona únicamente los que necesita.

11.14.7. Web/Utils.cs

// =========================================================================
// Web/Utils.cs
// -------------------------------------------------------------------------
// Pequeñas funciones utilitarias de la capa web:
//   - Labels   : "Mme Alice DURAND";
//   - WebDates : fechas "yyyy-MM-dd", horas "8:05", días "Wednesday 23 September 2026";
//   - Input    : lectura de un entero positivo enviado por el navegador;
//   - Patient  : el paciente (entidad Client) del usuario conectado.
//
// clases "static": solo contienen funciones, nunca creamos
// un objeto de estas clases.
// =========================================================================

using System.Globalization;
using System.Security.Claims;
using RdvMedecins.Auth;
using RdvMedecins.Entities;

namespace RdvMedecins.Web;

public static class Labels
{
    // "Mme Alice DURAND"
    public static string Label(Person p) => $"{p.Title} {p.FirstName} {p.LastName}";
}

public static class WebDates
{
    // el formato de las fechas en las URL y en el campo <input type="date">
    public const string IsoFormat = "yyyy-MM-dd";

    // true si [day] es una fecha que existe en el formato yyyy-MM-dd
    // ("2026-02-30" se rechaza)
    public static bool IsValidDate(string? text, out DateOnly day) =>
        DateOnly.TryParseExact(text, IsoFormat, CultureInfo.InvariantCulture, DateTimeStyles.None, out day);

    public static string Iso(DateOnly day) => day.ToString(IsoFormat, CultureInfo.InvariantCulture);

    // "8:05" en lugar de "8:5"
    public static string FormatTime(int h, int m) => $"{h}:{m:00}";

    public static string Time(Slot s) => $"{FormatTime(s.StartHour, s.StartMinute)} - {FormatTime(s.EndHour, s.EndMinute)}";

    // "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", según el
    // idioma de la solicitud (CultureInfo.CurrentCulture, establecido por el
    // middleware de localización - ver Program.cs)
    public static string FormatDay(DateOnly day) =>
        day.ToString("dddd d MMMM yyyy", CultureInfo.CurrentCulture);
}

public static class Input
{
    // "3" -> 3 ; "", "abc", "-2", null -> null
    public static int? PositiveInteger(string? value) =>
        int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var n) && n > 0 ? n : null;
}

public static class Patient
{
    // -----------------------------------------------------------------------
    // El paciente (entidad Client) que corresponde al usuario conectado.
    //
    // El token JWT solo contiene el id de la CUENTA (users.id). Para un
    // rol USER, encontramos el cliente correspondiente gracias a la columna clients.user.
    //
    // Si no hay ninguno, la cuenta fue eliminada desde el
    // login mientras su token sigue siendo válido: lo tratamos como una sesión
    // expirada (ver InvalidSessionException).
    // -----------------------------------------------------------------------
    public static async Task<Client> ConnectedPatientAsync(ApplicationModel application, ClaimsPrincipal user)
    {
        var currentUser = user.CurrentUser() ?? throw new InvalidSessionException();
        return await application.GetClientByUserIdAsync(currentUser.UserId) ?? throw new InvalidSessionException();
    }
}

Analicemos este código:

  • línea 24: el nombre de un médico o de un cliente: «Mme Alice DURAND». El parámetro es de tipo [Person], la clase padre de las entidades [Doctor] y [Client]: la misma función sirve para ambas;
  • línea 30: el formato de fecha en la URL y en el campo [<input type="date">];
  • líneas 34–35: verdadero si el texto es una fecha existente en el formato [yyyy-MM-dd]; [2026-02-30] se rechaza (vea el Ejemplo 12). El resultado se devuelve en el parámetro [out day]. [CultureInfo.InvariantCulture] hace que el análisis sea independiente del idioma de la solicitud;
  • línea 37: la operación inversa: de una fecha al texto [yyyy-MM-dd];
  • líneas 40–42: una hora en el formato [8:05] (el formato [00] exige dos dígitos para los minutos), y el horario de una franja: [8:00 - 8:20];
  • líneas 47–48: un día escrito completo, según la configuración regional de la solicitud, determinada por el middleware de localización (vea el Ejemplo 22): «mercredi 23 septembre 2026» o «Wednesday 23 September 2026»;
  • líneas 54–55: un identificador enviado por el navegador (en la URL o en un campo de formulario): un entero estrictamente positivo, o [null]. [NumberStyles.None] acepta únicamente dígitos: sin signos, espacios ni separadores de miles. El controlador solo necesita probar [null];
  • líneas 70–73: el paciente (entidad [Client]) asociado al usuario conectado. El token JWT contiene únicamente el identificador de la cuenta; buscamos el cliente asociado a esa cuenta. Si ya no existe, significa que la cuenta fue eliminada desde que el usuario inició sesión: [InvalidSessionException] será procesada por el filtro [HtmlExceptionFilter] descrito anteriormente, que redirige a la página de inicio de sesión. [?? throw] lanza una excepción cuando el valor de la izquierda es [null] (vea el Capítulo 9).

11.15. Modelos de formulario y de vista

Dos tipos de clases transportan datos entre el navegador, los controladores y las vistas: los formularios, rellenados por el enlace de modelos a partir de lo que envía el navegador, y los modelos de vista, preparados por los controladores para las vistas. Los primeros corresponden a los objetos DTO de la versión [NestJS], mientras que los segundos corresponden a los objetos pasados a [res.render].

11.15.1. Models/Forms.cs

// =========================================================================
// Models/Forms.cs
// -------------------------------------------------------------------------
// Los campos de los formularios de "persona" y sus restricciones. Tres
// formularios comparten los mismos campos de identidad (título, nombre, apellido):
//
//   PersonFields                  título, nombre, apellido
//    ├─ PersonForm                + login / contraseña OPCIONALES, versión
//    │                              (el ADMIN agrega o edita un médico / cliente)
//    ├─ RegistrationForm          + login / contraseña / confirmación OBLIGATORIOS
//    │                              (un paciente crea su cuenta)
//    └─ MyAccountForm             + login, nueva contraseña opcional,
//                                   contraseña ACTUAL OBLIGATORIA, versión
//                                   (un paciente edita su cuenta)
//
// MODEL BINDING: cuando una acción de un controlador recibe
// un parámetro de una de estas clases, ASP.NET Core MVC crea el objeto y
// llena cada propiedad con el campo del formulario del mismo nombre (sin importar
// mayúsculas o minúsculas: el campo "lastName" llena la propiedad LastName).
//
// VALIDACIÓN: justo después, MVC verifica los atributos [Required],
// [MaxLength]... (espacio de nombres estándar System.ComponentModel.DataAnnotations,
// el equivalente de class-validator) y almacena los errores en ModelState.
// El controlador solo tiene que probar ModelState.IsValid.
//
// Los mensajes de error son CLAVES de traducción (ver i18n/*.json).
//
// LIMPIEZA DE ENTRADA (el equivalente del @Transform de class-transformer):
//   - MVC ya convierte un campo vacío en null;
//   - los setters de abajo eliminan los espacios sobrantes y ponen el
//     login en minúsculas. Una contraseña, en cambio, no se "limpia" (los
//     espacios pueden formar parte de ella).
// Todas las propiedades son "nullable" (string?): un campo siempre puede
// faltar en lo que envía el navegador; es [Required] quien lo exige.
// =========================================================================

using System.ComponentModel.DataAnnotations;

namespace RdvMedecins.Models;

public static class InputRules
{
    public static readonly string[] Titles = ["Mr", "Mme", "Melle"];

    // login: letras minúsculas, dígitos, punto, guion, guion bajo - 30 caracteres como máximo
    public const string LoginFormat = "^[a-z0-9._-]{1,30}$";

    // longitud mínima de una contraseña ELEGIDA por un paciente
    public const int PasswordMin = 6;

    // "  dupont " -> "dupont" ; "   " -> null
    public static string? Clean(string? value) => string.IsNullOrWhiteSpace(value) ? null : value.Trim();
}

// -------------------------------------------------------------------------
// Un atributo de validación "casero": el valor debe pertenecer a una lista.
// Basta con heredar de ValidationAttribute y escribir IsValid.
// -------------------------------------------------------------------------
public class OneOfAttribute(params string[] values) : ValidationAttribute
{
    // aquí se acepta null: es función de [Required] exigirlo
    public override bool IsValid(object? value) => value is null || values.Contains(value as string);
}

// ================================================================== base común
public class PersonFields
{
    [Required(ErrorMessage = "ERRORS.INVALID_TITLE")]
    [OneOf("Mr", "Mme", "Melle", ErrorMessage = "ERRORS.INVALID_TITLE")]
    public string? Title { get; set; }

    // longitudes máximas = las de las columnas SQL (VARCHAR(20))
    private string? firstName;

    [Required(ErrorMessage = "ERRORS.FIRSTNAME_REQUIRED")]
    [MaxLength(20, ErrorMessage = "ERRORS.FIRSTNAME_TOO_LONG")]
    public string? FirstName
    {
        get => firstName;
        set => firstName = InputRules.Clean(value);
    }

    private string? lastName;

    [Required(ErrorMessage = "ERRORS.LASTNAME_REQUIRED")]
    [MaxLength(20, ErrorMessage = "ERRORS.LASTNAME_TOO_LONG")]
    public string? LastName
    {
        get => lastName;
        set => lastName = InputRules.Clean(value);
    }
}

// ================================================================== ADMIN
public class PersonForm : PersonFields
{
    private string? login;

    // opcional (ver PersonData, Business/IBusiness.cs)
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    // opcional; 72 caracteres como máximo (más allá, bcrypt ignora el resto)
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    // campo oculto del formulario de edición (bloqueo optimista).
    // int?: un campo ausente o vacío da null; un texto que no es un
    // número produce un error de binding (ver Program.cs, ModelBindingMessageProvider)
    public int? Version { get; set; }
}

// ================================================================== registro de un paciente
public class RegistrationForm : PersonFields
{
    private string? login;

    [Required(ErrorMessage = "ERRORS.LOGIN_REQUIRED")]
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    [Required(ErrorMessage = "ERRORS.PASSWORD_REQUIRED")]
    [MinLength(InputRules.PasswordMin, ErrorMessage = "ERRORS.PASSWORD_TOO_SHORT")]
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    [Required(ErrorMessage = "ERRORS.CONFIRMATION_REQUIRED")]
    public string? Confirmation { get; set; }
}

// ================================================================== "Manage my account"
public class MyAccountForm : PersonFields
{
    private string? login;

    [Required(ErrorMessage = "ERRORS.LOGIN_REQUIRED")]
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    // opcional: vacío = contraseña sin cambios
    [MinLength(InputRules.PasswordMin, ErrorMessage = "ERRORS.PASSWORD_TOO_SHORT")]
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    public string? Confirmation { get; set; }

    // la contraseña ACTUAL, obligatoria para cualquier modificación de la cuenta
    [Required(ErrorMessage = "ERRORS.CURRENT_PASSWORD_REQUIRED")]
    public string? CurrentPassword { get; set; }

    public int? Version { get; set; }
}

Comentemos este código:

  • línea 43: títulos posibles;
  • línea 46: el formato de un nombre de usuario, descrito mediante una expresión regular: de 1 a 30 caracteres formados por letras minúsculas, dígitos, un punto, un guion y un guion bajo;
  • línea 49: la longitud mínima de una contraseña elegida por un paciente. Es una constante ([const]), por lo que puede usarse como argumento de un atributo, como [[MinLength(InputRules.PasswordMin)]] más abajo;
  • línea 52: limpieza de una entrada: se eliminan los espacios iniciales y finales, y un campo formado únicamente por espacios se convierte en [null], es decir, no es válido;
  • líneas 59–62: un atributo de validación escrito por nosotros: el valor debe figurar en una lista. Solo necesitamos derivarlo de [ValidationAttribute] y redefinir [IsValid]. [null] se acepta: es función de [[Required]] rechazar un campo ausente. Lo usamos con el nombre [[OneOf]]: por convención, el sufijo [Attribute] puede omitirse;
  • línea 66: los campos de identidad, comunes a los tres formularios. Todas las propiedades son de tipo [string?]: un campo siempre puede faltar en los datos enviados por el navegador, y es [[Required]] quien lo exige. Los mensajes de error son claves de traducción (vea el Ejemplo 22);
  • líneas 68–70: el título, que es obligatorio y se selecciona de la lista. Los valores se repiten en [[OneOf(...)]]: el argumento de un atributo debe conocerse en tiempo de compilación, lo que no ocurre con el arreglo [InputRules.Titles] (un campo [static readonly], creado en tiempo de ejecución);
  • líneas 73–80 y líneas 83–90: el nombre y el apellido, que son obligatorios y pueden tener hasta 20 caracteres (el ancho de las columnas SQL). Estas propiedades tienen cuerpo: su valor se almacena en un campo privado, y [set] lo limpia al pasar. Como el enlace de modelos asigna las propiedades antes de la validación, lo que se valida es el valor ya limpio. Esto equivale al [@Transform] de la versión [NestJS]; [ASP.NET Core MVC] ya convierte automáticamente un campo vacío en [null];
  • línea 95: el formulario ADMIN, para agregar o editar un médico o un cliente. La clase hereda los campos de identidad y sus atributos de validación;
  • líneas 97–104: el inicio de sesión (login), que aquí es opcional pero debe tener el formato correcto si está presente (línea 100); se limpia y se convierte a minúsculas. [?.] llama a [ToLowerInvariant] solo si el valor no es [null];
  • líneas 108–109: la contraseña, también opcional, con un máximo de 72 caracteres: el algoritmo [bcrypt], que la cifra, ignora cualquier carácter posterior. Una contraseña no se limpia: los espacios forman parte de ella;
  • línea 114: la versión del registro, en un campo oculto del formulario de actualización (bloqueo optimista; vea el Ejemplo 28). Un campo ausente o vacío produce [null]; un texto que no es un número produce un error de enlace, cuyo mensaje se configura en [Program.cs] (vea el Ejemplo 19);
  • línea 118: un paciente crea una cuenta: se requieren nombre de usuario, contraseña (de 6 a 72 caracteres, línea 131) y confirmación (líneas 135–136). Verificar que la contraseña coincida con su confirmación involucra dos campos: esto lo comprueba el validador ([Controllers/RegistrationController.cs]);
  • línea 140: un paciente que modifica su cuenta. La nueva contraseña es opcional (línea 153): si se deja en blanco, la contraseña no cambia; por lo tanto, su confirmación (línea 157) no es obligatoria aquí. En cambio, la contraseña actual es obligatoria para cualquier modificación (líneas 160–161), y la versión del registro se almacena en un campo oculto (línea 163).

11.15.2. Models/ViewModels.cs

// =========================================================================
// Models/ViewModels.cs
// -------------------------------------------------------------------------
// Los "modelos de vista": lo que cada controlador pasa a
// su vista (return View("...", model)), en una clase C# TIPADA. En una
// vista Razor, @model ScheduleModel declara el tipo del modelo: el compilador
// verifica entonces cada @Model.Xxx de la vista - un error tipográfico es un error
// de compilación, y no una zona vacía en la página.
//
// Regla ya seguida con Handlebars: sin lógica en las vistas. Los
// controladores preparan datos YA formateados ("Mme Marie
// PELISSIER", "8:00 - 8:20", Selected = true...) y ya filtrados según el rol
// del usuario; las vistas se limitan a colocarlos en el HTML.
// =========================================================================

namespace RdvMedecins.Models;

// -------------------------------------------------------------------------
// lo que TODAS las páginas tienen en común, leído por el layout
// (Views/Shared/_Layout.cshtml)
// -------------------------------------------------------------------------
public abstract class ViewModel
{
    // clave de traducción del título de la página (<title>)
    public string PageTitle { get; set; } = "APP.TITLE";

    // EL mensaje de error de la página, mostrado en la parte inferior
    // (ver Views/Shared/_Errors.cshtml); null = sin error
    public string? Error { get; set; }

    public IReadOnlyDictionary<string, string>? ErrorParams { get; set; }
}

// una opción de una lista desplegable (médico, paciente)
public record OptionView(int Id, string Label, bool Selected);

// ================================================================== login
public class LoginModel : ViewModel
{
    public string Login { get; set; } = "";
    public required Auth.Captcha Captcha { get; set; }
}

// ================================================================== agenda
public class ScheduleRowView
{
    public int SlotId { get; init; }
    public string Time { get; init; } = ""; // "8:00 - 8:20"
    public bool Free { get; init; }
    public string? Patient { get; init; } // nombre mostrado para una franja reservada; null = "Booked"
    public bool Mine { get; init; } // la cita del paciente conectado
    public bool Bookable { get; init; } // ¿mostrar el botón "Book"?
    public string BookUrl { get; init; } = "";
    public int? AppointmentId { get; init; } // se llena solo si se muestra el botón "Cancel"
}

public record ScheduleView(string Doctor, string Day, List<ScheduleRowView> Rows);

public class BookingView
{
    public int SlotId { get; init; }
    public string Time { get; init; } = "";
    // ADMIN / DOCTOR: la lista de pacientes entre los cuales elegir
    public List<OptionView> Clients { get; init; } = [];
    // USER: el paciente es él mismo
    public string? Patient { get; init; }
}

public class ScheduleModel : ViewModel
{
    public List<OptionView> Doctors { get; set; } = [];
    public int? DoctorId { get; set; }
    public string Day { get; set; } = ""; // "yyyy-MM-dd"
    public ScheduleView? Schedule { get; set; }
    public BookingView? Booking { get; set; }
    public string BackUrl { get; set; } = "/schedule"; // la agenda mostrada, sin diálogo de reserva
    // paciente que ya tiene una cita próxima: el mensaje que explica
    // por qué no hay botón "Book"
    public string? Info { get; set; }
}

// ================================================================== formularios de "persona"

// los valores mostrados en los campos del formulario (nunca la contraseña)
public class PersonValues
{
    public string Title { get; set; } = "Mr";
    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public string Login { get; set; } = "";
    public int? Version { get; set; }
}

// lo que usa el parcial común _PersonFields.cshtml (título, nombre, apellido)
public abstract class FormView : ViewModel
{
    public PersonValues Values { get; set; } = new();

    // campo -> clave del mensaje mostrado BAJO este campo (error de entrada)
    public Dictionary<string, string> Errors { get; set; } = new(StringComparer.OrdinalIgnoreCase);

    // campos que se resaltan en rojo (clase Bootstrap is-invalid): los que tienen
    // un mensaje, más posiblemente otros (nombre + apellido duplicados, login ya tomado...)
    public HashSet<string> InvalidFields { get; set; } = new(StringComparer.OrdinalIgnoreCase);

    public string? ErrorOf(string field) => Errors.GetValueOrDefault(field);

    public string InvalidClass(string field) => InvalidFields.Contains(field) ? "is-invalid" : "";

    public IEnumerable<(string Value, bool Selected)> Titles =>
        InputRules.Titles.Select(t => (t, t == Values.Title));
}

public class PersonFormModel : FormView
{
    public bool Creating { get; set; } // true: agregar; false: editar
    public string Action { get; set; } = ""; // URL del POST
    public string ListUrl { get; set; } = "";
}

public class RegistrationModel : FormView
{
    public int PasswordMin => InputRules.PasswordMin;
}

public class MyAccountModel : FormView
{
    public int PasswordMin => InputRules.PasswordMin;
}

// ================================================================== listas de médicos / clientes

// las claves de traducción específicas de cada tipo de persona
public record PersonKeys(
    string Title, // "Doctors"
    string Add, // "Add a doctor"
    string Edit, // "Edit a doctor"
    string Empty, // "No doctors."
    string ConfirmDelete, // "Delete this doctor, their time slots and their user account?"
    string Added, // "Doctor {name} has been added (login: {login})."
    string Edited,
    string Deleted);

public record PersonView(string Title, string FirstName, string LastName, string Login, string EditUrl, string DeleteUrl);

public class PersonListModel : ViewModel
{
    public required PersonKeys Keys { get; set; }
    public string AddUrl { get; set; } = "";
    public List<PersonView> Persons { get; set; } = [];
}

// ================================================================== área del paciente
public record AppointmentView(int Id, string Day, string Time, string Doctor, string ScheduleUrl);

public class AreaModel : ViewModel
{
    public string Patient { get; set; } = "";
    public List<AppointmentView> Appointments { get; set; } = [];
}

// ================================================================== página de error
public class ErrorModel : ViewModel
{
    public int Code { get; set; }
    public string Message { get; set; } = "ERRORS.SERVER_ERROR";
}

Las plantillas de vista siguen la regla ya aplicada con [Handlebars]: sin lógica en las vistas. Los controladores preparan datos ya formateados («Mme Marie PELISSIER», «8:00 – 8:20») y ya filtrados según el rol del usuario; las vistas se limitan a colocar esos datos en el HTML. Cada vista declara el tipo de su plantilla ([@model ScheduleModel], vea el Ejemplo 13): el compilador verifica cada [@Model.Xxx], y un error tipográfico produce un error de compilación.

Comentemos este código:

  • líneas 22–31: lo que tienen en común todas las páginas, tal como lo lee la plantilla [_Layout.cshtml]: la clave de traducción del título de la página (línea 25) y el mensaje de error de la página, mostrado al pie, junto con sus parámetros. La clase es abstracta: cada página tiene su propia plantilla, que deriva de ella;
  • línea 35: una opción de una lista desplegable (un médico, un paciente), ya marcada como seleccionada o no seleccionada (vea el Ejemplo 18);
  • líneas 38–41: la página de inicio de sesión: el nombre de usuario ya ingresado y el CAPTCHA que se mostrará. La palabra clave [required] exige que quien crea el objeto asigne un valor a la propiedad; no hacerlo produce un error de compilación;
  • líneas 45–54: una entrada del calendario, es decir, una franja horaria. El controlador ya determinó todo: si se muestra el nombre del paciente (un paciente no puede ver los nombres de los demás), si se muestra el botón «Book» y si se muestra el botón «Cancel» ([AppointmentId] está asignado). A las propiedades [init] solo se les puede asignar un valor cuando se crea el objeto;
  • línea 57: la agenda de un médico para un solo día: el nombre del médico, el día escrito completo y las filas;
  • líneas 59–66: la ventana de cita: la lista de pacientes para ADMIN y los médicos, o solo el nombre del paciente conectado;
  • líneas 69–79: la página del calendario: la lista de médicos, el médico y el día seleccionados, el calendario ([null] mientras no se seleccione ningún médico), la ventana de reserva (si está presente), la URL del calendario sin esta ventana (línea 76) y el mensaje que explica a un paciente por qué no puede reservar una cita;
  • líneas 85–91: los valores mostrados en los campos de un formulario de «persona», nunca la contraseña: una contraseña no se devuelve al navegador;
  • línea 95: la clase padre de las plantillas de los tres formularios de «persona», la que exige [Validation.Prepare]: los valores de los campos, los mensajes debajo de los campos (línea 100) y los campos que se resaltarán en rojo (línea 104). Un [HashSet] es un conjunto: cada elemento aparece una sola vez, y la prueba de pertenencia es rápida;
  • líneas 106–108: dos métodos para las vistas: el mensaje de un campo (o [null]), y la clase [Bootstrap] [is-invalid], que enmarca un campo en rojo. Las vistas los invocan, por ejemplo, así: [@Model.InvalidClass("login")];
  • líneas 110–111: las opciones de la lista de títulos, con la opción seleccionada marcada (vea el Ejemplo 18). Cada opción es una tupla [(Value, Selected)];
  • líneas 114–118: el formulario ADMIN, usado para agregar y modificar entradas (vea el Ejemplo 28): el modo, la URL de envío del formulario y la URL de la lista para el botón de regreso;
  • líneas 121–128: los formularios de registro y de gestión de cuenta; pasan a la vista la longitud mínima de la contraseña, que se usa como parámetro [{min}] del mensaje de error del campo y, en el registro, del texto de ayuda;
  • líneas 134–142: las páginas de gestión de médicos y de clientes son las mismas vistas; solo difiere su texto. Este [record] contiene las claves de traducción específicas de cada tipo de persona;
  • líneas 144–150: una fila de la lista de médicos o de clientes, con las direcciones de sus botones Editar y Eliminar, y la plantilla de la página de la lista;
  • líneas 154–159: el área del paciente: su nombre y sus próximas citas, cada una con un enlace al calendario del día;
  • líneas 163–166: la página de error: el código HTTP y la clave del mensaje, que por defecto es la de un error del servidor.

11.16. La capa web: los controladores

Los controladores son la parte visible de la capa web: cada uno recibe las solicitudes de un grupo de páginas, lee sus parámetros, consulta la capa de negocio (siempre a través del servicio [ApplicationModel]), luego selecciona una vista y le pasa un modelo tipado, o redirige la solicitud. Todos los formularios POST siguen el patrón Post/Redirect/Get (vea el Ejemplo 20); todos los mensajes son claves de traducción, traducidas por la vista. El controlador de inicio de sesión, [AuthController], se trató junto con la autenticación.

11.16.1. Controllers/LanguageController.cs

// =========================================================================
// Controllers/LanguageController.cs
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: los dos botones FR / EN de la barra de
// navegación. Ruta no protegida: debe ser posible cambiar de idioma antes de
// iniciar sesión.
//
// La elección se almacena en LA cookie del middleware de localización
// de ASP.NET Core (CookieRequestCultureProvider, ver Program.cs): en cada
// solicitud siguiente, este middleware la vuelve a leer y establece el idioma de la solicitud
// (CultureInfo.CurrentCulture / CurrentUICulture). Luego volvemos a la
// página de la que veníamos.
// =========================================================================

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

public class LanguageController : Controller
{
    [HttpGet("language/{language}")]
    public IActionResult Change(string language)
    {
        if (!Translator.Languages.Contains(language))
        {
            return NotFound(); // -> página de error 404 (ver Program.cs)
        }
        Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            // valor de la cookie: "c=en|uic=en" (idioma de los formatos, idioma de los textos)
            CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(language)),
            new CookieOptions { MaxAge = TimeSpan.FromDays(365), SameSite = SameSiteMode.Lax, HttpOnly = true, Path = "/" });
        return Redirect(OriginPage());
    }

    // la página anterior, según el encabezado HTTP "Referer" enviado por el
    // navegador. Solo conservamos su ruta (/schedule?...): redirigir a una
    // dirección completa suministrada por la solicitud permitiría enviar
    // al usuario a otro sitio (la llamada falla de "open redirect").
    private string OriginPage()
    {
        var referer = Request.Headers.Referer.ToString();
        if (!Uri.TryCreate(referer, UriKind.Absolute, out var url))
        {
            return "/";
        }
        return url.AbsolutePath.StartsWith("/language/", StringComparison.Ordinal) ? "/" : url.PathAndQuery;
    }
}

Este es, salvo por una línea, el controlador del Ejemplo 22: la misma ruta [/language/{language}], la misma cookie del middleware de localización, el mismo regreso a la página de origen mediante el encabezado [Referer]. Dos aclaraciones:

  • línea 34: la opción [Path = "/"] hace que la cookie sea válida para todas las direcciones del sitio, sin importar desde qué página se cambió el idioma;
  • línea 49: si la página de origen es en sí misma una página [/language/...], se redirige al usuario a la raíz del sitio en lugar de devolverlo a esa página, lo que haría que el navegador entrara en un bucle.

11.16.2. Controllers/ScheduleController.cs

La página principal de la aplicación y el controlador con más funcionalidades. Vamos a analizarlo sección por sección.

11.16.2.1. Las URL de la página

// =========================================================================
// Controllers/ScheduleController.cs
// -------------------------------------------------------------------------
// La página de la agenda: elección de un médico y un día, agenda de este
// médico en ese día, reserva y cancelación de citas.
//
//   GET  /schedule?doctorId=1&day=2026-09-23               la página
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        la misma página, con
//                                                          el diálogo de reserva
//                                                          de la franja 7 abierto
//   POST /schedule/book                                    crea una cita
//   POST /schedule/cancel                                  cancela una cita
//
// Toda la página queda descrita por su URL: se puede recargar, guardar como favorito,
// y usar el botón "Back" del navegador - sin una sola línea
// de JavaScript.
//
// Lo que cada uno ve y puede hacer:
//
//   | rol           | franja reservada mostrada         | Book               | Cancel  |
//   |===============|===================================|====================|=========|
//   | ADMIN, DOCTOR | nombre del paciente               | para un paciente   | sí      |
//   |               |                                   | elegido en una lista |         |
//   | USER (paciente)| "Booked", o SU nombre si es       | para sí mismo, si  | no (*)  |
//   |               | su propia cita                    | no tiene           |         |
//   |               |                                   | cita próxima       |         |
//
//   (*) el paciente cancela su cita desde su página "My area".
//
// CONFIDENCIALIDAD: para un paciente, el nombre de los OTROS pacientes no está
// simplemente oculto por la vista - nunca se coloca en el modelo
// pasado a la vista. Por lo tanto, el HTML enviado al navegador no lo contiene,
// ni siquiera oculto (un simple "View page source" lo revelaría de otro modo).
//
// Sin reservas en el pasado: el botón "Book" solo aparece
// para hoy y los días siguientes (y la capa de negocio lo rechazaría
// de todos modos).
//
// [Authorize] en la clase: todas las acciones requieren un usuario
// con sesión iniciada (el equivalente de @UseGuards(JwtAuthGuard)). [Authorize(Roles =
// "...")] en una acción exige además uno de los roles listados (RolesGuard +
// @Roles). Sin token válido: de vuelta a /login; rol insuficiente: página 403.
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize]
[Route("schedule")]
public class ScheduleController(ApplicationModel application) : Controller
{
    // lo que el controlador sabe del usuario, para decidir qué mostrar
    private record Rights(
        bool Manager, // ADMIN o DOCTOR
        Client? Patient, // el cliente conectado (rol USER), de lo contrario null
        bool PatientCanBook); // USER sin cita próxima
  • Líneas 7–12: las rutas de la página. Observe que la ventana de reserva no la abre [JavaScript]: es un parámetro de la URL ([book=7]) que indica al servidor que genere la página con la ventana abierta. Por lo tanto, el botón «Book» es simplemente un enlace. Toda la página queda descrita por su URL: se puede recargar, guardar como marcador o usar el botón «Atrás» del navegador;
  • líneas 18–28: lo que ve y puede hacer cada rol. Esta tabla es la «especificación» de la página: el resto del controlador la implementa;
  • líneas 30–33: la regla de privacidad, a la que volveremos: la vista no oculta los nombres de los demás pacientes; nunca se envían al navegador;
  • líneas 55–57: [[Authorize]] en la clase: todas las acciones requieren un usuario conectado, sin importar su rol (vea el Ejemplo 25). [[Route("schedule")]] es el prefijo de todas las rutas del controlador (vea el Ejemplo 02). El controlador recibe el servicio [ApplicationModel] por inyección (vea el Ejemplo 06) a través de su constructor principal: los parámetros escritos entre paréntesis después del nombre de la clase son accesibles en todos sus métodos;
  • líneas 60–63: lo que el controlador sabe del usuario conectado, calculado una vez por solicitud (vea [RightsAsync], más abajo). Un [record] privado, declarado dentro de la clase: solo lo usa esa clase. [Manager] es verdadero para un ADMIN o un DOCTOR; [Patient] solo se rellena para un cliente (rol USER).

11.16.2.2. GET /schedule

    // -----------------------------------------------------------------------
    // GET /schedule
    // Los parámetros de la URL se leen en bruto (Request.Query), para distinguir
    // un parámetro AUSENTE de uno VACÍO (?doctorId=).
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public async Task<IActionResult> Show()
    {
        string? error = null;
        var user = User.CurrentUser()!;
        var rights = await RightsAsync(user);

        // el día: el de la URL si es válido, de lo contrario hoy
        var day = Dates.Today();
        if (Request.Query.TryGetValue("day", out var rawDay))
        {
            if (WebDates.IsValidDate(rawDay, out var requestedDay))
            {
                day = requestedDay;
            }
            else
            {
                error = "ERRORS.INVALID_DATE";
            }
        }
        var dayBookable = day >= Dates.Today();

        // el médico: el de la URL; en su defecto, para un médico conectado, él mismo
        var doctorId = Input.PositiveInteger(Request.Query["doctorId"]);
        if (!Request.Query.ContainsKey("doctorId") && user.Role == Role.DOCTOR)
        {
            doctorId = application.GetDoctorByUserId(user.UserId)?.Id;
        }

        var doctors = (await application.GetAllDoctorsAsync())
            .Select(d => Option(d, d.Id == doctorId))
            .ToList();

        // la agenda, si se eligió un médico (y la fecha es válida)
        ScheduleView? schedule = null;
        if (doctorId is int id && error is null)
        {
            var doctorSchedule = await application.GetDoctorDayScheduleAsync(id, day);
            if (doctorSchedule is null)
            {
                error = "ERRORS.DOCTOR_NOT_FOUND";
            }
            else
            {
                var rows = doctorSchedule.DoctorDaySlots.Select(dds =>
                {
                    var (slot, appointment) = (dds.Slot, dds.Appointment);
                    var free = appointment is null;
                    // ¿la cita del paciente conectado?
                    var mine = appointment is not null && rights.Patient is not null && appointment.ClientId == rights.Patient.Id;
                    return new ScheduleRowView
                    {
                        SlotId = slot.Id,
                        Time = WebDates.Time(slot),
                        Free = free,
                        // EL punto de confidencialidad: un paciente solo recibe el nombre de
                        // SU cita; para las demás, null (la vista muestra "Booked")
                        Patient = appointment is not null && (rights.Manager || mine) ? Labels.Label(appointment.Client) : null,
                        Mine = mine,
                        Bookable = free && dayBookable && (rights.Manager || rights.PatientCanBook),
                        BookUrl = ScheduleUrl(id, day, slot.Id),
                        AppointmentId = appointment is not null && rights.Manager ? appointment.Id : null,
                    };
                }).ToList();
                schedule = new ScheduleView(Labels.Label(doctorSchedule.Doctor), WebDates.Iso(day), rows);
            }
        }
  • Líneas 6–7: la ruta [GET /schedule] (prefijo del controlador, seguido de una cadena vacía). La acción no tiene parámetros: lee la URL directamente como [Request.Query] (vea el Ejemplo 05). El enlace de modelos convertiría un parámetro [int? doctorId] en [null] tanto si falta como si está vacío; sin embargo, estos dos casos deben distinguirse (vea más abajo);
  • líneas 10–11: el usuario conectado y sus permisos. [CurrentUser()] es un método de extensión (vea el Ejemplo 06) definido en [Auth/ConnectedUser.cs]: lee las claims del token y las convierte en un objeto tipado. [!] informa al compilador de que el resultado no es [null]: esto es seguro, ya que [[Authorize]] ya filtró las solicitudes no autenticadas;
  • líneas 14–26: el día solicitado, si es válido; de lo contrario, hoy. [TryGetValue] devuelve [false] si el parámetro [day] falta: en ese caso, devuelve hoy, sin mensaje. Si está presente pero no es válido ([day=2026-02-30]), genera un mensaje de error. Las reservas solo pueden hacerse a partir de hoy ([dayBookable]);
  • líneas 29–32: el médico solicitado. [Input.PositiveInteger] (carpeta [Web]) devuelve un entero estrictamente positivo, o [null] si el valor falta, está vacío o no es válido. Si el parámetro [doctorId] falta en la URL, un médico conectado ve su propia agenda: es su página de inicio. Si está vacío ([doctorId=], la opción «-- choose a doctor --» de la lista), no se muestra ninguna agenda;
  • líneas 35–37: las opciones de la lista desplegable de médicos, leídas de la caché de [ApplicationModel]; se selecciona la opción del médico solicitado (vea la función [Option] al final del archivo y el Ejemplo 18);
  • líneas 40–46: la agenda se calcula únicamente si hay un médico seleccionado y la fecha es válida. [doctorId is int id] comprueba que el valor (de tipo [int?]) no es [null], y guarda su valor en una nueva variable [id], de tipo [int]. Un identificador de médico desconocido produce un mensaje, no una página de error;
  • líneas 50–56: la agenda calculada por la capa de negocio (un objeto [DoctorDaySchedule] de la carpeta [Domain]) se convierte en elementos de un arreglo, uno por franja horaria. [var (slot, appointment) = ...] descompone un par de valores en dos variables. [mine] determina si la cita pertenece al paciente conectado;
  • líneas 58–59: la vista recibe únicamente datos ya formateados ([8:00 - 8:20]); ya no tiene nada que calcular;
  • línea 63: el control de privacidad de la aplicación. El nombre del paciente se incluye en el modelo únicamente para un administrador o para el paciente a quien pertenece la cita. Para todos los demás, el modelo contiene [null], y la vista muestra «Booked». La vista no se limita a ocultar el nombre: nunca se envía al navegador, y «Ver código fuente de la página» no lo revelaría;
  • líneas 65–67: lo que debe mostrar la vista, según lo determina el controlador: el botón «Book» (franja disponible, fecha no pasada y usuario autorizado para reservar), su enlace (la URL de la página, con [book]) y el botón «Cancel» ([AppointmentId] solo se rellena para un administrador). La vista no toma ninguna decisión: sigue estas instrucciones;
  • línea 70: la agenda completa: el médico, el día, las filas.

11.16.2.3. La ventana de cita y la plantilla de vista

        // el diálogo de reserva: solo si la franja solicitada es
        // reservable por este usuario
        BookingView? booking = null;
        var slotId = Input.PositiveInteger(Request.Query["book"]);
        var row = schedule?.Rows.FirstOrDefault(r => r.SlotId == slotId && r.Bookable);
        if (row is not null)
        {
            booking = new BookingView
            {
                SlotId = row.SlotId,
                Time = row.Time,
                Clients = rights.Manager
                    ? (await application.GetAllClientsAsync()).Select(c => Option(c, false)).ToList()
                    : [],
                Patient = rights.Patient is not null ? Labels.Label(rights.Patient) : null,
            };
        }

        return View("Schedule", new ScheduleModel
        {
            PageTitle = "SCHEDULE.PAGE_TITLE",
            Doctors = doctors,
            DoctorId = doctorId,
            Day = WebDates.Iso(day),
            Schedule = schedule,
            Booking = booking,
            BackUrl = doctorId is int dId ? ScheduleUrl(dId, day) : "/schedule",
            Info = rights.Patient is not null && !rights.PatientCanBook ? "SCHEDULE.ALREADY_BOOKED_INFO" : null,
            Error = error,
        });
    }
  • líneas 3–5: la franja horaria para la cual la URL solicita una reserva ([book=7]). Debe aparecer en la agenda mostrada y poder ser reservada por este usuario: una URL creada manualmente (una franja pasada, una franja ya reservada o una franja de otro médico) no abre la ventana. [schedule?.Rows] equivale a [null] si [schedule] es [null] (operador [?.]);
  • líneas 6–15: la plantilla de la ventana. Un administrador selecciona un paciente de una lista (todos los clientes, leídos de la caché); un paciente hace una reserva para sí mismo: la ventana simplemente muestra su nombre. [[]] es una lista vacía;
  • líneas 19–29: la plantilla de la página. Sus clases ([ScheduleModel], [ScheduleView], [ScheduleRowView], [BookingView], [OptionView]) se definen en [Models/ViewModels.cs]; [PageTitle] y [Error] derivan de su clase padre común [ViewModel]. [PageTitle] es, como todos los textos, una clave de traducción;
  • línea 27: la dirección del calendario mostrado, sin la ventana de reserva; es la dirección del botón que cierra la ventana;
  • línea 28: un mensaje informativo para los pacientes que ya tienen una cita próxima: explica por qué no ven un botón «Book».

11.16.2.4. POST /schedule/book

    // -----------------------------------------------------------------------
    // POST /schedule/book   campos: doctorId, day, slotId, clientId
    //
    // Para un paciente (USER), el campo clientId se IGNORA: siempre reserva
    // para sí mismo. Confiar en un campo enviado por el
    // navegador permitiría a un paciente malintencionado reservar a nombre de otra persona.
    //
    // Patrón "Post / Redirect / Get": sea cual sea el resultado, aquí no
    // construimos una página - colocamos un mensaje flash y redirigimos
    // a la agenda (ver Web/Flash.cs).
    // -----------------------------------------------------------------------
    [HttpPost("book")]
    [Authorize(Roles = "ADMIN,DOCTOR,USER")]
    public async Task<IActionResult> Book(
        [FromForm] string? doctorId,
        [FromForm] string? day,
        [FromForm] string? slotId,
        [FromForm] string? clientId)
    {
        if (!ReadScheduleRequest(doctorId, day, out var docId, out var requestedDay)
            || Input.PositiveInteger(slotId) is not int sltId)
        {
            return BadRequest(); // -> página "invalid request" (ver Program.cs)
        }

        Client? client;
        if (User.IsInRole(nameof(Role.USER)))
        {
            client = await Patient.ConnectedPatientAsync(application, User);
        }
        else
        {
            if (Input.PositiveInteger(clientId) is not int cliId)
            {
                // ningún paciente elegido: reabrimos el diálogo de reserva
                Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CHOOSE_PATIENT");
                return Redirect(ScheduleUrl(docId, requestedDay, sltId));
            }
            client = await application.GetClientByIdAsync(cliId);
        }

        var slot = await application.GetSlotByIdAsync(sltId);
        if (client is null)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.PATIENT_NOT_FOUND");
        }
        else if (slot is null || slot.DoctorId != docId)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.SLOT_NOT_FOUND");
        }
        else
        {
            try
            {
                // las reglas (no en el pasado, una sola cita próxima por
                // paciente, franja libre) las verifica la capa de negocio
                await application.AddAppointmentAsync(requestedDay, slot, client);
                Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.BOOKED");
            }
            // "when": un filtro de excepciones. Misma regla, pero un mensaje en
            // segunda persona cuando es el propio paciente quien reserva ("You
            // already have..." en lugar de "This patient...")
            catch (BusinessException e) when (e.Key == "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT" && User.IsInRole(nameof(Role.USER)))
            {
                Flash.Put(HttpContext, FlashType.Danger, "SCHEDULE.ALREADY_BOOKED_INFO");
            }
            // cualquier otra BusinessException se convierte en un mensaje flash; las demás
            // excepciones (verdaderas anomalías) no se capturan: página 500
            catch (BusinessException e)
            {
                Flash.Put(HttpContext, FlashType.Danger, e.Key, new Dictionary<string, string>(e.Params));
            }
        }
        return Redirect(ScheduleUrl(docId, requestedDay));
    }
  • Líneas 12–13: [[Authorize(Roles = ...)]] en la acción se suma al [[Authorize]] de la clase: los tres roles pueden hacer reservas (vea el Ejemplo 26). Aquí, este atributo no impone ninguna restricción adicional; documenta la regla y la protegería si apareciera un cuarto rol;
  • líneas 15–18: los campos del formulario de la ventana de reserva (vea el Ejemplo 11). Se reciben como cadenas y luego se convierten con cuidado;
  • líneas 20–23: el médico y el día son campos ocultos del formulario; permiten al usuario volver al calendario mostrado. Si no son válidos, la solicitud no proviene de nuestra página: fue creada manualmente. [BadRequest()] devuelve una respuesta 400 sin contenido, que el middleware [UseStatusCodePagesWithReExecute] transforma en una página de error (vea el Ejemplo 24). [is not int sltId] es lo opuesto de [is int]: es verdadero si el valor es [null]; de lo contrario, [sltId] recibe el valor;
  • líneas 27–29: para un paciente, el campo [clientId] se ignora: el sistema siempre hace la reserva para el propio paciente. Confiar en este campo, enviado por el navegador, permitiría a un paciente malintencionado hacer una reserva a nombre de otra persona. [Patient.ConnectedPatientAsync] (carpeta [Web]) identifica al cliente mediante el token; [nameof(Role.USER)] es la cadena ["USER"], verificada por el compilador;
  • líneas 33–39: un gestor que no ha seleccionado un paciente es redirigido a la ventana de reserva (URL con [book]), acompañado de un mensaje de error emergente. [Flash.Put] (carpeta [Web]) almacena el mensaje en [TempData] (vea el Ejemplo 20);
  • líneas 42–49: el paciente debe existir, y la franja horaria debe existir y pertenecer al médico del calendario: no se puede reservar una franja que pertenece a un médico para otro;
  • líneas 57–58: las reglas de negocio (no estar en el pasado, franja disponible, una sola cita próxima por paciente) las verifica la capa de lógica de negocio, que lanza una [BusinessException] en caso de rechazo;
  • líneas 63–65: [when] agrega una condición a [catch]: es un filtro de excepciones de [C#]. Este bloque solo captura la [BusinessException] si la condición es verdadera: para un paciente, el mensaje «este paciente ya tiene una cita» se reemplaza por un mensaje en segunda persona. De lo contrario, la excepción pasa al siguiente [catch];
  • líneas 69–71: cualquier otra [BusinessException] se convierte en un mensaje flash, con su clave y sus parámetros ([e.Params] es un diccionario de solo lectura: se hace una copia de él, del tipo esperado por [Flash.Put]). Las demás excepciones no se capturan: son errores reales, que producen una página de error 500;
  • línea 74: el esquema PRG: sea cual sea el resultado, se muestra un mensaje flash y se redirige al usuario al calendario, que mostrará el mensaje. En la versión [NestJS], una función utilitaria se encargaba de esta conversión de errores de negocio; aquí bastan los dos bloques [catch].

11.16.2.5. POST /schedule/cancel

    // -----------------------------------------------------------------------
    // POST /schedule/cancel   campos: appointmentId, doctorId, day
    // (un paciente cancela SU cita desde "My area", no desde aquí)
    // -----------------------------------------------------------------------
    [HttpPost("cancel")]
    [Authorize(Roles = "ADMIN,DOCTOR")]
    public async Task<IActionResult> Cancel([FromForm] string? appointmentId, [FromForm] string? doctorId, [FromForm] string? day)
    {
        if (!ReadScheduleRequest(doctorId, day, out var docId, out var requestedDay)
            || Input.PositiveInteger(appointmentId) is not int id)
        {
            return BadRequest();
        }
        var appointment = await application.GetAppointmentByIdAsync(id);
        if (appointment is null)
        {
            // ya cancelada (por otra persona, o doble clic)
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.APPOINTMENT_NOT_FOUND");
        }
        else
        {
            await application.DeleteAppointmentAsync(appointment);
            Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.CANCELLED");
        }
        return Redirect(ScheduleUrl(docId, requestedDay));
    }
  • líneas 5–7: la cancelación está reservada a los administradores; un paciente cancela su cita desde «Mi área» (vea [PatientAreaController]). Un paciente que envíe esta solicitud recibiría una página 403;
  • líneas 9–12: las mismas comprobaciones que para la reserva;
  • líneas 14–18: una cita que ya fue cancelada (por un doble clic o por otro administrador) produce un mensaje de error, no una página de error;
  • líneas 22–25: eliminación, seguida del esquema PRG.

11.16.2.6. Permisos y funciones utilitarias

    // -----------------------------------------------------------------------
    // ¿quién tiene la sesión iniciada y qué puede hacer en esta página?
    // -----------------------------------------------------------------------
    private async Task<Rights> RightsAsync(ConnectedUser user)
    {
        if (user.Role != Role.USER)
        {
            return new Rights(Manager: true, Patient: null, PatientCanBook: false);
        }
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var upcoming = await application.GetClientUpcomingAppointmentsAsync(patient.Id);
        return new Rights(Manager: false, patient, PatientCanBook: upcoming.Count == 0);
    }

    // ================================================================== funciones utilitarias

    // los campos ocultos doctorId / day, comunes a los dos formularios POST
    private static bool ReadScheduleRequest(string? rawDoctorId, string? rawDay, out int doctorId, out DateOnly day)
    {
        doctorId = Input.PositiveInteger(rawDoctorId) ?? 0;
        return WebDates.IsValidDate(rawDay, out day) && doctorId > 0;
    }

    private static string ScheduleUrl(int doctorId, DateOnly day, int? book = null)
    {
        var url = $"/schedule?doctorId={doctorId}&day={WebDates.Iso(day)}";
        return book is null ? url : $"{url}&book={book}";
    }

    private static OptionView Option(Person p, bool selected) => new(p.Id, Labels.Label(p), selected);
}
  • líneas 4–12: un administrador tiene todos los permisos; un paciente puede hacer una reserva si no tiene citas próximas. Los argumentos con nombre ([Manager: true]) hacen legible la llamada al constructor del [record];
  • líneas 18–21: lectura de los dos campos ocultos comunes a los formularios POST. Los parámetros [out] son resultados adicionales del método: este devuelve un booleano (¿son válidos los campos?) y, mediante sus parámetros [out], los valores convertidos. Es el mismo mecanismo de [int.TryParse];
  • líneas 24–27: la URL de la agenda de un médico en un día dado, posiblemente con la ventana de reserva abierta. Todas las redirecciones de los controladores la generan mediante esta función: las URL de la página se escriben en un único lugar;
  • línea 30: una opción de lista desplegable (identificador, etiqueta, selección), tanto para un médico como para un cliente: el parámetro es de tipo [Person], la clase padre de ambas entidades.

11.16.3. Controllers/PersonsControllerBase.cs

// =========================================================================
// Controllers/PersonsControllerBase.cs
// -------------------------------------------------------------------------
// La gestión de los médicos y la de los clientes (reservada al ADMIN) son
// IDÉNTICAS: misma lista, mismo formulario, mismas reglas. En lugar de
// escribir dos veces las mismas acciones, las escribimos una sola vez en esta
// clase ABSTRACTA y GENÉRICA, de la cual heredan DoctorsController
// ([Route("doctors")]) y ClientsController ([Route("clients")]). Cada
// subclase solo tiene que proporcionar su "configuración": qué métodos
// invocar, qué etiquetas mostrar.
//
// Las rutas colocadas AQUÍ ([HttpGet("add")]...) se heredan, y
// complementan la ruta de la subclase. Obtenemos así, para cada una:
//
//   GET  /doctors                    lista
//   GET  /doctors/add                formulario vacío
//   POST /doctors/add                creación
//   GET  /doctors/{id}/edit          formulario prellenado
//   POST /doctors/{id}/edit          actualización
//   POST /doctors/{id}/delete        eliminación
//
// (y las mismas URL bajo /clients). Las vistas también son comunes:
// Views/Persons/List.cshtml y Views/Persons/Form.cshtml.
//
// MVC nunca toma una clase abstracta por un controlador: solo
// sus subclases concretas lo son.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

// lo que cada subclase debe proporcionar
public record PersonsConfig<T>(
    string Url, // "/doctors" o "/clients"
    PersonKeys Keys,
    Func<Task<List<T>>> List,
    Func<int, Task<T?>> Find,
    Func<PersonData, Task<T>> Add,
    Func<int, PersonData, Task<T>> Edit,
    Func<int, Task> Delete) where T : Person;

public abstract class PersonsControllerBase<T>(ApplicationModel application) : Controller where T : Person
{
    protected ApplicationModel Application { get; } = application;

    protected abstract PersonsConfig<T> Config { get; }

    // -----------------------------------------------------------------------
    // GET /doctors (o /clients)
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public async Task<IActionResult> List()
    {
        var persons = await Config.List();
        return View("~/Views/Persons/List.cshtml", new PersonListModel
        {
            PageTitle = Config.Keys.Title,
            Keys = Config.Keys,
            AddUrl = $"{Config.Url}/add",
            Persons = persons
                .Select(p => new PersonView(p.Title, p.FirstName, p.LastName, p.User?.Login ?? "",
                    $"{Config.Url}/{p.Id}/edit", $"{Config.Url}/{p.Id}/delete"))
                .ToList(),
        });
    }

    // -----------------------------------------------------------------------
    // GET /doctors/add
    // -----------------------------------------------------------------------
    [HttpGet("add")]
    public IActionResult AddForm() => ShowForm(null, new PersonValues());

    // -----------------------------------------------------------------------
    // POST /doctors/add
    // [form] fue llenado Y validado por MVC: ModelState indica si la
    // entrada es correcta.
    // -----------------------------------------------------------------------
    [HttpPost("add")]
    public async Task<IActionResult> Add(PersonForm form)
    {
        if (!ModelState.IsValid)
        {
            return ShowForm(null, EnteredValues(form), Validation.ErrorsOf(ModelState));
        }
        try
        {
            var person = await Config.Add(Data(form));
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Added, MessageParams(person));
            return Redirect(Config.Url);
        }
        catch (BusinessException e)
        {
            return ShowBusinessError(null, EnteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // GET /doctors/{id}/edit
    // {id:int}: una "route constraint" - /doctors/abc/edit no
    // coincide con ninguna ruta (página 404)
    // -----------------------------------------------------------------------
    [HttpGet("{id:int}/edit")]
    public async Task<IActionResult> EditForm(int id)
    {
        var person = await Config.Find(id);
        if (person is null)
        {
            return NotFound();
        }
        return ShowForm(id, new PersonValues
        {
            Title = person.Title,
            FirstName = person.FirstName,
            LastName = person.LastName,
            Login = person.User?.Login ?? "",
            Version = person.Version,
        });
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/edit
    // -----------------------------------------------------------------------
    [HttpPost("{id:int}/edit")]
    public async Task<IActionResult> Edit(int id, PersonForm form)
    {
        if (!ModelState.IsValid)
        {
            return ShowForm(id, EnteredValues(form), Validation.ErrorsOf(ModelState));
        }
        try
        {
            var person = await Config.Edit(id, Data(form));
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Edited, MessageParams(person));
            return Redirect(Config.Url);
        }
        catch (BusinessException e)
        {
            return ShowBusinessError(id, EnteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/delete
    // (la confirmación "Are you sure?" la solicita el navegador antes de
    // enviar el formulario, ver wwwroot/js/app.js)
    // -----------------------------------------------------------------------
    [HttpPost("{id:int}/delete")]
    public async Task<IActionResult> Delete(int id)
    {
        var person = await Config.Find(id);
        try
        {
            await Config.Delete(id);
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Deleted, MessageParams(person));
        }
        catch (BusinessException e)
        {
            Flash.Put(HttpContext, FlashType.Danger, e.Key, new Dictionary<string, string>(e.Params));
        }
        return Redirect(Config.Url);
    }

    // ================================================================== métodos privados

    // id null: formulario de creación; de lo contrario: formulario de edición
    private ViewResult ShowForm(
        int? id,
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null)
    {
        var creating = id is null;
        return View("~/Views/Persons/Form.cshtml", Validation.Prepare(
            new PersonFormModel
            {
                PageTitle = creating ? Config.Keys.Add : Config.Keys.Edit,
                Creating = creating,
                Action = creating ? $"{Config.Url}/add" : $"{Config.Url}/{id}/edit",
                ListUrl = Config.Url,
                Values = values,
            },
            errors, error, otherFields));
    }

    // una regla de negocio rechazó la escritura: volvemos a mostrar el formulario,
    // con la entrada del usuario y el mensaje de la capa de negocio
    private IActionResult ShowBusinessError(int? id, PersonValues values, BusinessException e)
    {
        if (e.Key is "ERRORS.DOCTOR_NOT_FOUND" or "ERRORS.PATIENT_NOT_FOUND")
        {
            // eliminado mientras tanto por otro ADMIN: de vuelta a la lista
            Flash.Put(HttpContext, FlashType.Danger, e.Key);
            return Redirect(Config.Url);
        }
        // el mensaje va en la parte inferior de la página; los campos afectados, si los hay, se
        // resaltan en rojo para que el usuario vea de inmediato qué corregir
        return ShowForm(id, values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
    }

    // lo que el usuario escribió (excepto la contraseña: nunca se la devolvemos al navegador)
    private static PersonValues EnteredValues(PersonForm f) => new()
    {
        Title = f.Title ?? "",
        FirstName = f.FirstName ?? "",
        LastName = f.LastName ?? "",
        Login = f.Login ?? "",
        Version = f.Version,
    };

    // el formulario validado -> los datos que espera la capa de negocio
    private static PersonData Data(PersonForm f) => new()
    {
        Title = f.Title!,
        LastName = f.LastName!,
        FirstName = f.FirstName!,
        Login = f.Login,
        Password = f.Password,
        Version = f.Version,
    };

    // {name} y {login} de los mensajes "added / updated / deleted"
    private static Dictionary<string, string> MessageParams(Person? person) => person is null
        ? new() { ["name"] = "", ["login"] = "" }
        : new() { ["name"] = $"{person.FirstName} {person.LastName}", ["login"] = person.User?.Login ?? "" };
}

La gestión de médicos y de clientes es idéntica. En lugar de escribir dos controladores similares, escribimos sus acciones una sola vez, en una clase padre abstracta y genérica. Comentemos este código:

  • líneas 15–20: las rutas de los médicos; las mismas existen en [/clients];
  • líneas 22–23: las vistas también se comparten (carpeta [Views/Persons]);
  • líneas 25–26: MVC solo acepta clases concretas como controladores: solo [DoctorsController] y [ClientsController] reciben solicitudes;
  • líneas 38–45: la configuración que proporciona cada subclase: la URL base, los textos (claves de traducción, agrupadas en [record] y [PersonKeys] de [Models/ViewModels.cs]) y las funciones que se invocarán para listar, buscar, agregar, modificar y eliminar. [Func<int, Task<T?>>] es el tipo de una función que toma un [int] y devuelve un [Task<T?>]: así se almacenan métodos en propiedades, para llamarlos más adelante. [where T : Person] es una restricción sobre el tipo genérico: [T] será [Doctor] o [Client], dos clases derivadas de [Person]; por lo tanto, el código puede usar [p.FirstName] o [p.User], que son comunes a todas las personas;
  • línea 47: la clase padre, que es genérica (vea la clase [ViewPage<TModel>] en el Ejemplo 22) y abstracta. Recibe [ApplicationModel] mediante su constructor principal y se lo pasa a sus subclases mediante la propiedad protegida [Application] ([protected]: visible solo para las subclases);
  • línea 51: una propiedad abstracta: cada subclase debe definirla;
  • líneas 56–69: la lista. Los atributos de ruta definidos en los métodos de una clase padre se heredan: combinados con el [[Route("doctors")]] de la subclase, dan como resultado [GET /doctors]. Para cada persona, el modelo contiene la URL de sus botones Editar y Eliminar. [p.User?.Login ?? ""]: el login de la cuenta asociada, o una cadena vacía si la persona no tiene cuenta;
  • línea 60: la vista se especifica con su ruta completa. Si solo se usara su nombre, MVC la buscaría en la carpeta del controlador ([Views/Doctors] o [Views/Clients], vea el Ejemplo 13), mientras que ambos la comparten;
  • líneas 75–76: el formulario vacío;
  • líneas 83–98: la adición, en tres pasos, como en el Ejemplo 28. El parámetro [form] fue rellenado y validado por MVC antes de la llamada (vea el Ejemplo 19): una entrada no válida vuelve a mostrar el formulario, con los valores ingresados y un mensaje debajo de cada campo incorrecto; una entrada válida se pasa a la capa de negocio y luego se redirige al navegador a la lista, con un mensaje flash (PRG); un rechazo de la capa de negocio (un homónimo, un login ya en uso) vuelve a mostrar el formulario;
  • líneas 107–121: el formulario de modificación prerrellenado. La restricción de ruta [:int] (vea el Ejemplo 02) solo acepta un identificador entero: [/doctors/abc/edit] no corresponde a ninguna ruta y produce una página 404 ([ParseIntPipe] de [NestJS] producía un error 400). Una persona inexistente también produce un 404. El número de versión, un campo oculto del formulario, se usará para el bloqueo optimista (vea el Ejemplo 28);
  • líneas 128–143: la actualización, siguiendo el mismo patrón que la inserción;
  • líneas 152–165: la eliminación. La persona se recupera antes para mostrar su nombre en el mensaje de confirmación. Un rechazo de la capa de negocio (por ejemplo, un médico que tiene citas) produce un mensaje flash de error en la página de la lista;
  • líneas 171–188: el formulario de creación ([id] equivale a [null]), igual que el de modificación: solo cambian el título y la dirección de envío ([Action]). [Validation.Prepare] (carpeta [Web]) rellena la plantilla con los mensajes de error específicos de cada campo, el mensaje al pie y los campos que se resaltarán en rojo;
  • líneas 193–203: una persona que ha sido eliminada entretanto (por otro administrador) vuelve a aparecer en la lista; los demás errores de negocio vuelven a mostrar el formulario, con el mensaje al pie y los campos afectados resaltados en rojo ([Validation.BusinessErrorFields] asocia cada código de error con sus campos correspondientes: [firstName] y [lastName] para un homónimo). [is "A" or "B"] compara un valor con varias constantes;
  • líneas 207–213: los valores que se volverán a mostrar, nunca la contraseña;
  • líneas 217–224: los datos transmitidos a la capa de negocio. Los campos [!] no presentan ningún riesgo: la validación verificó la presencia de estos campos;
  • líneas 228–230: los parámetros [{name}] y [{login}] de los mensajes de éxito: el nombre y el apellido de la persona, y su login.

11.16.4. Controllers/DoctorsController.cs

// =========================================================================
// Controllers/DoctorsController.cs
// -------------------------------------------------------------------------
// Gestión de los médicos (solo rol ADMIN). Todas las acciones se
// heredan de PersonsControllerBase: aquí solo queda indicar QUÉ
// invocar y QUÉ etiquetas mostrar.
//
// [Authorize(Roles = "ADMIN")] colocado en la CLASE se aplica a todas sus
// acciones, incluidas las heredadas.
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "ADMIN")]
[Route("doctors")]
public class DoctorsController(ApplicationModel application) : PersonsControllerBase<Doctor>(application)
{
    protected override PersonsConfig<Doctor> Config => new(
        Url: "/doctors",
        Keys: new PersonKeys(
            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: Application.GetAllDoctorsAsync,
        Find: Application.GetDoctorByIdAsync,
        Add: Application.AddDoctorAsync,
        Edit: Application.EditDoctorAsync,
        Delete: Application.DeleteDoctorAsync);
}
  • líneas 20–22: reservado para ADMIN. El atributo definido en la clase se aplica a todas sus acciones, incluidas las heredadas. El controlador hereda de [PersonsControllerBase<Doctor>]: el tipo de la clase padre, [T], pasa a ser [Doctor]. Su constructor principal pasa [application] al constructor de la clase padre. (En [TypeScript], había que escribir un constructor explícito para que [NestJS] supiera qué inyectar; aquí no es necesario);
  • líneas 24–34: la configuración. [override] redefine la propiedad abstracta de la clase padre; [=>] la convierte en una propiedad calculada, que crea el objeto cada vez que se lee. Los argumentos con nombre ([Url:], [Keys:]...) hacen legible la lista;
  • líneas 35–39: las funciones que se invocarán, que son métodos de [ApplicationModel]. [Application.GetAllDoctorsAsync], escrito sin paréntesis, no llama al método: se refiere a él, y el compilador lo convierte en un valor del tipo esperado [Func].

11.16.5. Controllers/ClientsController.cs

// =========================================================================
// Controllers/ClientsController.cs
// -------------------------------------------------------------------------
// Gestión de los clientes (los PACIENTES del consultorio), solo rol ADMIN.
// Mismo principio que DoctorsController (ver sus comentarios).
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "ADMIN")]
[Route("clients")]
public class ClientsController(ApplicationModel application) : PersonsControllerBase<Client>(application)
{
    protected override PersonsConfig<Client> Config => new(
        Url: "/clients",
        Keys: new PersonKeys(
            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: Application.GetAllClientsAsync,
        Find: Application.GetClientByIdAsync,
        Add: Application.AddClientAsync,
        Edit: Application.EditClientAsync,
        Delete: Application.DeleteClientAsync);
}

El mismo controlador, para los clientes: otra ruta, otras claves de traducción, otros métodos de [ApplicationModel].

11.16.6. Controllers/RegistrationController.cs

// =========================================================================
// Controllers/RegistrationController.cs
// -------------------------------------------------------------------------
// "Create a patient account": un paciente que aún no tiene cuenta
// la crea él mismo. Rutas NO protegidas (aún no tenemos cuenta, por
// definición):
//
//   POST /register/access     botón "Create a patient account" de la
//                             página de autenticación: verifica el CAPTCHA de
//                             ESTA página, luego abre el formulario
//   GET  /register            el formulario
//   POST /register            la creación, luego de vuelta a la página de login
//
// El flujo está protegido contra robots por UN solo CAPTCHA, el de la
// página de autenticación:
//   1. el botón "Create a patient account" envía el formulario de login
//      a /register/access; si el CAPTCHA se copió correctamente, el servidor
//      emite un pase (ver Auth/RegistrationPassService.cs);
//   2. sin un pase válido, /register redirige a la
//      página de autenticación - escribir la URL directamente no sirve;
//   3. el pase se consume en la creación: un CAPTCHA resuelto
//      permite crear UNA cuenta;
//   4. además, el número de cuentas creadas por hora y por dirección IP está
//      limitado (ver Auth/AttemptLimiterService.cs).
//
// La cuenta creada es exactamente la que el ADMIN crearía desde la
// página "Patients" (mismo método de la capa de negocio: AddClientAsync), salvo
// que el paciente ELIGE su login y su contraseña (obligatorios,
// con confirmación).
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Route("register")]
public class RegistrationController(
    ApplicationModel application,
    CaptchaService captchaService,
    AttemptLimiterService limiter,
    RegistrationPassService passes) : Controller
{
    // -----------------------------------------------------------------------
    // POST /register/access   campos: captchaId, captcha (los de la
    // página de autenticación; login y password, también enviados, se ignoran)
    // -----------------------------------------------------------------------
    [HttpPost("access")]
    public IActionResult Access([FromForm] string? captchaId, [FromForm] string? captcha)
    {
        var ip = AuthController.IpAddress(HttpContext);

        // demasiadas cuentas creadas recientemente desde esta dirección: no hace falta ir más lejos
        var minutes = limiter.RegistrationBlockMinutes(ip);
        if (minutes > 0)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.TOO_MANY_ACCOUNTS", new() { ["minutes"] = minutes.ToString() });
            return Redirect("/login");
        }

        // CAPTCHA ausente o incorrecto: de vuelta a la página de autenticación, con
        // una nueva imagen (un fallo cuenta como fallo de login)
        if (!captchaService.Verify(captchaId, captcha))
        {
            limiter.LoginFailure(ip, "");
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CAPTCHA_BEFORE_ACCOUNT");
            return Redirect("/login");
        }

        // CAPTCHA correcto: emitimos el pase y abrimos el formulario
        Response.Cookies.Append(RegistrationPassService.Cookie, passes.Issue(), RegistrationPassService.GetCookieOptions());
        return Redirect("/register");
    }

    // -----------------------------------------------------------------------
    // GET /register
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public IActionResult Form()
    {
        if (!HasPass())
        {
            return BackToLogin();
        }
        return Show(new PersonValues());
    }

    // -----------------------------------------------------------------------
    // POST /register
    // El parámetro [form] es llenado y VALIDADO por MVC antes de la llamada:
    // el resultado de la validación está en ModelState.
    // -----------------------------------------------------------------------
    [HttpPost("")]
    public async Task<IActionResult> Create(RegistrationForm form)
    {
        if (!HasPass())
        {
            return BackToLogin();
        }
        var ip = AuthController.IpAddress(HttpContext);
        var values = new PersonValues
        {
            Title = form.Title ?? "Mr",
            FirstName = form.FirstName ?? "",
            LastName = form.LastName ?? "",
            Login = form.Login ?? "",
        };

        // 1. ¿demasiadas cuentas creadas recientemente desde esta dirección?
        var minutes = limiter.RegistrationBlockMinutes(ip);
        if (minutes > 0)
        {
            return Show(values, null, "ERRORS.TOO_MANY_ACCOUNTS", null, new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }

        // 2. todos los errores de entrada a la vez (campos + confirmación):
        //    el usuario los corrige todos de una vez
        var errors = Validation.ErrorsOf(ModelState);
        if (!errors.ContainsKey("password") && !errors.ContainsKey("confirmation") && form.Password != form.Confirmation)
        {
            errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER";
        }
        if (errors.Count > 0)
        {
            return Show(values, errors);
        }

        // 3. la creación (cliente + cuenta USER, en una transacción)
        try
        {
            // "!": afirmamos al compilador que estos valores no son null -
            // lo cual es cierto, puesto que la validación ([Required]) tuvo éxito
            await application.AddClientAsync(new PersonData
            {
                Title = form.Title!,
                LastName = form.LastName!,
                FirstName = form.FirstName!,
                Login = form.Login,
                Password = form.Password,
            });
        }
        catch (BusinessException e)
        {
            // login o nombre + apellido ya tomados: el pase sigue siendo válido
            return Show(values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
        }

        // 4. el pase ya se usó: no permitirá crear una 2.ª cuenta
        passes.Consume(Request.Cookies[RegistrationPassService.Cookie]);
        Response.Cookies.Delete(RegistrationPassService.Cookie, new CookieOptions { Path = "/register" });
        limiter.RegistrationSuccess(ip);

        // 5. de vuelta a la página de login, con el login prellenado
        Flash.Put(HttpContext, FlashType.Success, "REGISTRATION.DONE", new() { ["login"] = form.Login! });
        return Redirect($"/login?login={Uri.EscapeDataString(form.Login!)}");
    }

    // ================================================================== métodos privados

    private bool HasPass() => passes.IsValid(Request.Cookies[RegistrationPassService.Cookie]);

    // sin pase válido: de vuelta a la página de autenticación
    private RedirectResult BackToLogin()
    {
        Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CAPTCHA_BEFORE_ACCOUNT");
        return Redirect("/login");
    }

    // el formulario; nunca se devuelve ninguna contraseña al navegador
    private ViewResult Show(
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Registration", Validation.Prepare(
            new RegistrationModel { PageTitle = "REGISTRATION.TITLE", Values = values },
            errors, error, otherFields, errorParams));
}

Comentemos este código:

  • líneas 14–24: protección contra bots, en cuatro pasos. El CAPTCHA y el limitador de intentos se presentaron en el Ejemplo 27;
  • líneas 40–45: el controlador no tiene el atributo [[Authorize]]; sus páginas están abiertas a todos. Recibe cuatro servicios mediante inyección;
  • líneas 51–52: el botón «Crear una cuenta de paciente» de la página de inicio de sesión envía el formulario de inicio de sesión a esta dirección (atributo [formaction]; vea el Ejemplo 20). Solo se leen los campos del CAPTCHA;
  • línea 54: la dirección IP del navegador, mediante un método estático de [AuthController];
  • líneas 57–61: se han creado demasiadas cuentas desde esta dirección durante la última hora: el usuario es redirigido a la página de inicio de sesión, con un mensaje emergente que indica el número de minutos que debe esperar. [new() { ["minutes"] = ... }] crea el diccionario de parámetros del mensaje: su tipo se infiere del parámetro de [Flash.Put];
  • líneas 66–70: un CAPTCHA ausente o incorrecto cuenta como un intento fallido de inicio de sesión (con un nombre de usuario vacío): un bot no puede seguir intentándolo indefinidamente. Al volver a la página de inicio de sesión se muestra una imagen nueva;
  • líneas 74–75: el CAPTCHA es correcto: se almacena un pase (vea [Auth/RegistrationPassService.cs]) en una cookie, y se redirige al navegador al formulario;
  • líneas 81–88: el formulario, solo con un pase válido. Escribir directamente la dirección [/register] no sirve de nada;
  • líneas 96–97: la creación. El formulario [RegistrationForm] (carpeta [Models]) fue enlazado y validado por MVC;
  • líneas 99–101: el pase se verifica de nuevo: la solicitud POST pudo haberse enviado sin pasar por el formulario;
  • líneas 104–109: los valores que se volverán a mostrar en caso de error, sin la contraseña. El título predeterminado es [Mr];
  • líneas 113–116: el límite de tiempo, comprobado de nuevo en el momento de la creación;
  • líneas 121–128: errores de entrada, campo por campo (vea el Ejemplo 19). La coincidencia entre la contraseña y su confirmación, que abarca dos campos, se verifica aquí manualmente; solo se prueba si estos dos campos son correctos por lo demás. Todos los errores se informan juntos: el usuario los corrige todos a la vez;
  • líneas 136–148: creación del cliente y de su cuenta USER, mediante el método de la capa de negocio que utiliza ADMIN. Si un nombre de usuario o una combinación de nombre y apellido ya está en uso, el formulario se vuelve a mostrar con los campos correspondientes resaltados en rojo; el pase sigue siendo válido;
  • líneas 152–154: el pase ya se usó: se consume en el servidor y se elimina su cookie. Para eliminar una cookie, hay que especificar la misma ruta ([Path]) que cuando se creó: la cookie del pase solo se envía a las direcciones [/register...]. Por último, la creación se cuenta para el límite por hora;
  • líneas 157–158: regreso a la página de inicio de sesión, con el nombre de usuario prerrellenado y un mensaje de éxito. [Uri.EscapeDataString] codifica el nombre de usuario para poder incluirlo en una URL;
  • línea 163: el pase se lee de la cookie de la solicitud;
  • líneas 166–169: si no hay ningún pase, se regresa a la página de inicio de sesión con un mensaje;
  • líneas 173–181: el formulario, preparado por [Validation.Prepare], es el mismo que los de médicos y clientes. [errorParams] se usa para los parámetros del mensaje al pie (el número de minutos).

11.16.7. Controllers/PatientAreaController.cs

// =========================================================================
// Controllers/PatientAreaController.cs
// -------------------------------------------------------------------------
// Las páginas PERSONALES del paciente (rol USER), las que ve justo
// después de iniciar sesión:
//
//   GET  /my-area                  página de inicio: [Manage my account],
//                                  [View a schedule], y su próxima cita
//   POST /my-area/cancel           cancela SU cita
//   GET  /my-account               formulario para editar su cuenta
//   POST /my-account               actualización
//   POST /my-account/delete        eliminación de la cuenta (y de sus citas)
//
// Regla de oro de este controlador: el paciente afectado es SIEMPRE el del
// token (Patient.ConnectedPatientAsync), nunca un identificador enviado por el
// navegador. Un paciente no puede por lo tanto ver, ni modificar, ni cancelar lo que
// pertenece a otro paciente, ni siquiera falsificando él mismo sus solicitudes.
//
// Cualquier modificación o eliminación de la cuenta requiere la contraseña
// ACTUAL: alguien que encontrara una sesión abierta
// no podría ni cambiar la contraseña, ni eliminar la cuenta. Los errores
// de contraseña actual se cuentan como fallos de login (mismo límite).
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "USER")]
public class PatientAreaController(
    ApplicationModel application,
    AuthService authService,
    AttemptLimiterService limiter) : Controller
{
    // -----------------------------------------------------------------------
    // GET /my-area
    // -----------------------------------------------------------------------
    [HttpGet("my-area")]
    public async Task<IActionResult> Area()
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var appointments = await application.GetClientUpcomingAppointmentsAsync(patient.Id);
        return View("Area", new AreaModel
        {
            PageTitle = "AREA.TITLE",
            Patient = Labels.Label(patient),
            Appointments = appointments.Select(a => new AppointmentView(
                a.Id,
                WebDates.FormatDay(a.Day),
                WebDates.Time(a.Slot),
                Labels.Label(a.Slot.Doctor),
                // enlace a la agenda del médico en ese día: el paciente ve allí su nombre
                $"/schedule?doctorId={a.Slot.Doctor.Id}&day={WebDates.Iso(a.Day)}")).ToList(),
        });
    }

    // -----------------------------------------------------------------------
    // POST /my-area/cancel   campo: appointmentId
    // -----------------------------------------------------------------------
    [HttpPost("my-area/cancel")]
    public async Task<IActionResult> CancelAppointment([FromForm] string? appointmentId)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var appointment = Input.PositiveInteger(appointmentId) is int id ? await application.GetAppointmentByIdAsync(id) : null;
        // una cita que no existe y la de OTRO paciente reciben
        // la misma respuesta: no revelamos nada sobre las citas de los demás
        if (appointment is null || appointment.ClientId != patient.Id)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.APPOINTMENT_NOT_FOUND");
        }
        else
        {
            await application.DeleteAppointmentAsync(appointment);
            Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.CANCELLED");
        }
        return Redirect("/my-area");
    }

    // -----------------------------------------------------------------------
    // GET /my-account
    // -----------------------------------------------------------------------
    [HttpGet("my-account")]
    public async Task<IActionResult> AccountForm()
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        return Show(new PersonValues
        {
            Title = patient.Title,
            FirstName = patient.FirstName,
            LastName = patient.LastName,
            Login = patient.User.Login,
            Version = patient.Version,
        });
    }

    // -----------------------------------------------------------------------
    // POST /my-account
    // -----------------------------------------------------------------------
    [HttpPost("my-account")]
    public async Task<IActionResult> EditAccount(MyAccountForm form)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var values = new PersonValues
        {
            Title = form.Title ?? patient.Title,
            FirstName = form.FirstName ?? "",
            LastName = form.LastName ?? "",
            Login = form.Login ?? "",
            Version = form.Version,
        };

        var errors = Validation.ErrorsOf(ModelState);
        if (!errors.ContainsKey("password") && form.Password is not null && form.Password != form.Confirmation)
        {
            errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER";
        }
        if (errors.Count > 0)
        {
            return Show(values, errors);
        }

        // la contraseña actual
        var passwordError = await CheckCurrentPasswordAsync(patient, form.CurrentPassword);
        if (passwordError is not null)
        {
            var (key, messageParams) = passwordError.Value;
            return Show(
                values,
                key == "ERRORS.WRONG_CURRENT_PASSWORD" ? new(StringComparer.OrdinalIgnoreCase) { ["currentPassword"] = key } : null,
                key,
                null,
                messageParams);
        }

        try
        {
            var client = await application.EditClientAsync(patient.Id, new PersonData
            {
                Title = form.Title!,
                LastName = form.LastName!,
                FirstName = form.FirstName!,
                Login = form.Login,
                Password = form.Password, // null = sin cambios
                Version = form.Version,
            });
            // el login y el nombre mostrado ESTÁN en el token: emitimos uno
            // nuevo, de lo contrario la barra de navegación conservaría el nombre antiguo
            authService.SetToken(Response, client.User);
            Flash.Put(HttpContext, FlashType.Success, "MY_ACCOUNT.UPDATED");
            return Redirect("/my-area");
        }
        catch (BusinessException e)
        {
            return Show(values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
        }
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   campo: deletePassword
    // La cuenta, el cliente y TODAS sus citas desaparecen juntos,
    // luego se cierra la sesión del paciente.
    // -----------------------------------------------------------------------
    [HttpPost("my-account/delete")]
    public async Task<IActionResult> DeleteAccount([FromForm] string? deletePassword)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var passwordError = await CheckCurrentPasswordAsync(patient, deletePassword);
        if (passwordError is not null)
        {
            var (key, messageParams) = passwordError.Value;
            Flash.Put(HttpContext, FlashType.Danger, key, messageParams);
            return Redirect("/my-account");
        }
        await application.DeleteClientAsync(patient.Id);
        AuthService.ClearToken(Response);
        Flash.Put(HttpContext, FlashType.Success, "MY_ACCOUNT.DELETED");
        return Redirect("/login");
    }

    // ================================================================== métodos privados

    // null si la contraseña actual es correcta; de lo contrario, la clave del mensaje
    // (y sus parámetros). El tipo de retorno es una "tupla" nullable.
    private async Task<(string Key, Dictionary<string, string>? Params)?> CheckCurrentPasswordAsync(
        Client patient, string? password)
    {
        var ip = AuthController.IpAddress(HttpContext);
        var login = patient.User.Login;
        var minutes = limiter.LoginBlockMinutes(ip, login);
        if (minutes > 0)
        {
            return ("ERRORS.TOO_MANY_ATTEMPTS", new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }
        var ok = !string.IsNullOrEmpty(password) && await authService.ValidateUserAsync(login, password) is not null;
        if (!ok)
        {
            limiter.LoginFailure(ip, login);
            return ("ERRORS.WRONG_CURRENT_PASSWORD", null);
        }
        return null;
    }

    private ViewResult Show(
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Account", Validation.Prepare(
            new MyAccountModel { PageTitle = "MY_ACCOUNT.TITLE", Values = values },
            errors, error, otherFields, errorParams));
}

Analicemos este código:

  • líneas 14–17: la regla de oro de este controlador: el paciente en cuestión es siempre el asociado al token, nunca un identificador enviado por el navegador;
  • líneas 35–39: reservado para pacientes. El controlador no tiene el atributo [[Route]]: cada acción indica su dirección completa, ya que no comparten un prefijo ([/my-area], [/my-account]);
  • líneas 44–59: la página «Mi área». [Patient.ConnectedPatientAsync] identifica al usuario a partir del token; si su cuenta fue eliminada desde que inició sesión, lanza una [InvalidSessionException], que el filtro [Web/HtmlExceptionFilter.cs] redirige de nuevo a la página de inicio de sesión. La fecha la formatea [WebDates.FormatDay] según el idioma de la solicitud, establecido por el middleware de localización (vea el Ejemplo 22); cada cita incluye un enlace a la agenda del médico para ese día;
  • líneas 66–82: cancelación de la cita del paciente. [condition ? value1 : value2] devuelve aquí la cita, o [null] si el identificador no es válido. Una cita inexistente y una que pertenece a otro paciente (línea 73) reciben la misma respuesta: no se revela ninguna información sobre las citas de otros pacientes;
  • líneas 88–98: el formulario de la cuenta, prerrellenado, con el número de versión (bloqueo optimista);
  • líneas 105–106: el proceso de modificación, en tres pasos: validación, verificación de la contraseña actual, lógica de negocio;
  • líneas 109–115: los valores que se volverán a mostrar en caso de error, nunca las contraseñas;
  • líneas 118–125: errores de entrada. La nueva contraseña es opcional (en blanco: sin cambios); su confirmación se compara solo si fue ingresada;
  • líneas 129–138: la contraseña actual. [var (key, messageParams) = ...] descompone el par devuelto por la verificación. Una contraseña incorrecta se muestra debajo de su campo y al pie de la página; un bloqueo (demasiados intentos) se muestra solo al pie de la página, junto con el número de minutos;
  • líneas 143–150: modificación por la capa de negocio, que aplica las mismas reglas que para ADMIN (unicidad, bloqueo optimista);
  • línea 154: el token contiene el login y el nombre para mostrar: tras un cambio, se emite un nuevo token; de lo contrario, la barra de navegación conservaría el nombre anterior;
  • líneas 158–160: un rechazo de la capa de negocio vuelve a mostrar el formulario, con los campos correspondientes resaltados en rojo;
  • líneas 169–183: eliminación de la cuenta, que también requiere la contraseña actual. Un error se indica mediante un mensaje emergente en la página de la cuenta (PRG);
  • líneas 180–181: eliminación del registro, de la cuenta y de todas las citas (el método de la capa de negocio que usa ADMIN), seguida del cierre de sesión: se borra la cookie del token;
  • líneas 190–191: verificación de la contraseña actual. Devuelve [null] si la contraseña es correcta; de lo contrario, devuelve una tupla: un par de valores con nombre (la clave del mensaje y sus parámetros). El [?] final hace que esta tupla admita valores nulos;
  • líneas 195–198: la contraseña actual está sujeta al mismo limitador que la conexión (vea el Ejemplo 27). Alguien que encontrara una sesión que se quedó abierta no podría cambiar la contraseña, eliminar la cuenta ni probar contraseñas indefinidamente;
  • líneas 200–204: el proceso de autenticación propiamente dicho, a cargo de [AuthService]; un intento de autenticación fallido se cuenta como un intento fallido de inicio de sesión;
  • líneas 209–217: el formulario de la cuenta.

11.16.8. Controllers/ErrorController.cs

// =========================================================================
// Controllers/ErrorController.cs
// -------------------------------------------------------------------------
// La página de error (400, 403, 404, 500).
//
// Nunca se llega a ella mediante un enlace: son los middlewares
// UseStatusCodePagesWithReExecute("/error/{0}") y
// UseExceptionHandler("/error/500") (ver Program.cs) los que RE-EJECUTAN la
// solicitud fallida con esta dirección, para construir la página que se envía
// en lugar de una respuesta vacía o una excepción.
//
// [Route] sin [HttpGet]: la acción acepta todos los métodos HTTP - la
// solicitud re-ejecutada conserva su método original (un POST rechazado sigue siendo POST).
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Models;

namespace RdvMedecins.Controllers;

public class ErrorController : Controller
{
    private static readonly Dictionary<int, string> Messages = new()
    {
        [StatusCodes.Status400BadRequest] = "ERRORS.BAD_REQUEST",
        [StatusCodes.Status403Forbidden] = "ERRORS.FORBIDDEN",
        [StatusCodes.Status404NotFound] = "ERRORS.NOT_FOUND",
    };

    [Route("error/{code:int}")]
    public IActionResult Show(int code)
    {
        // la página conserva el código de error original (404 sigue siendo 404...); un
        // código inesperado se convierte en un error 500
        if (code < 400 || code > 599)
        {
            code = StatusCodes.Status500InternalServerError;
        }
        Response.StatusCode = code;
        return View("Error", new ErrorModel
        {
            PageTitle = "ERROR_PAGE.TITLE",
            Code = code,
            Message = Messages.GetValueOrDefault(code, "ERRORS.SERVER_ERROR"),
        });
    }
}

Este es el controlador del Ejemplo 24, con los mensajes traducidos:

  • líneas 23–28: la clave de mensaje para cada código de error. [static readonly]: un único diccionario, creado cuando se carga la clase y nunca reemplazado;
  • líneas 30–31: [[Route]], que no especifica el método HTTP, acepta todos los métodos: una solicitud POST reejecutada (por ejemplo, un paciente que intenta una cancelación reservada a los administradores) sigue siendo una solicitud POST;
  • líneas 35–37: un código HTTP que no es de error (una dirección [/error/200] ingresada manualmente) se convierte en un error 500;
  • línea 39: la página conserva el código de error original;
  • líneas 40–44: la plantilla de la página. [GetValueOrDefault] devuelve la clave asociada al código, o [ERRORS.SERVER_ERROR] para cualquier otro código (en particular, 500).

11.17. Las vistas

Las vistas casi no tienen nada que decidir: su plantilla ha sido preparada por los controladores en las clases del archivo [Models/ViewModels.cs] (qué botones mostrar, qué elementos de URL, qué claves de traducción). Cada vista declara el tipo de su plantilla ([@model], vea el Ejemplo 13): un error tipográfico en [@Model.Xxx] producirá un error de compilación. Además, cada vista comienza con un comentario [Razor] [@* ... *@] que describe su función; estos comentarios no aparecen en las páginas enviadas al navegador.

Una diferencia con respecto a los ejemplos del Capítulo 4: el caso de estudio no utiliza Tag Helpers. Las vistas parciales se insertan mediante [@await Html.PartialAsync("_Name")], el equivalente de la etiqueta [<partial name="_Name">] del Ejemplo 15. Un segundo argumento, opcional, proporciona el modelo de la vista parcial; sin él, la vista parcial recibe el modelo de la página. El método es asíncrono (la vista parcial puede necesitar compilarse o leerse del disco): [await] espera su resultado.

11.17.1. La plantilla y las vistas parciales

11.17.1.1. Views/_ViewImports.cshtml

@* =========================================================================
   Views/_ViewImports.cshtml
   -------------------------------------------------------------------------
   Se lee antes de CADA vista de esta carpeta y sus subcarpetas: los
   "using" comunes y la clase padre de todas las vistas (Web/ViewPage.cs), que
   les aporta @T("KEY"), CurrentUser, FlashMessage...
   TModel designa el tipo del modelo de cada vista (@model ...).
   ========================================================================= *@
@using RdvMedecins
@using RdvMedecins.Models
@using RdvMedecins.Web
@inherits RdvMedecins.Web.ViewPage<TModel>
  • líneas 9–11: los espacios de nombres cuyos tipos usan las vistas: las plantillas de vista ([RdvMedecins.Models]), los mensajes flash ([RdvMedecins.Web]);
  • línea 12: la clase padre de todas las vistas, [Web/ViewPage.cs], como en el Ejemplo 22. Les proporciona la traducción [@T("KEY")], el idioma [Language], el usuario conectado [CurrentUser], el mensaje flash [FlashMessage], la ruta solicitada [CurrentPath], y el método [Active] (elemento de menú activo en la barra de navegación). En la versión [NestJS], esta información se pasaba mediante [res.locals]. No hay ninguna directiva [@addTagHelper]: la aplicación no utiliza Tag Helpers.

11.17.1.2. Views/_ViewStart.cshtml

@* =========================================================================
   Views/_ViewStart.cshtml
   -------------------------------------------------------------------------
   Se ejecuta antes de cada vista: todas las páginas usan el layout común
   Views/Shared/_Layout.cshtml (hbs lo hacía automáticamente para
   views/layout.hbs; aquí lo decimos explícitamente).
   ========================================================================= *@
@{
    Layout = "_Layout";
}
  • línea 9: todas las páginas usan la plantilla [Views/Shared/_Layout.cshtml] (vea el Ejemplo 15). [Handlebars] usaba automáticamente [views/layout.hbs]; [Razor] exige que se especifique.

11.17.1.3. Views/Shared/_Layout.cshtml

@* =========================================================================
   Views/Shared/_Layout.cshtml
   -------------------------------------------------------------------------
   El diseño (layout) COMÚN a todas las páginas. La página solicitada por el controlador
   (Schedule.cshtml, Login.cshtml...) se inserta en el lugar de
   @RenderBody().

   Razor ESCAPA todo lo que muestra con @ (los caracteres < > & " '
   se convierten en &lt; &gt;...): protección contra la inyección de HTML a través de un
   nombre escrito, por ejemplo. Para insertar HTML tal cual, hay que pedirlo
   explícitamente (@Html.Raw, ver _Captcha.cshtml).

   Mensajes: un éxito se muestra en la PARTE SUPERIOR de la página (_Flash), un error en la
   PARTE INFERIOR, sobre un fondo rosa claro (_Errors).

   El layout comparte el modelo de la página: si es un ViewModel (ver
   Models/ViewModels.cs), de él leemos el título y el error de la página.
   ========================================================================= *@
@{
    var page = ViewData.Model as ViewModel;
}
<!doctype html>
<html lang="@Language">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>@T(page?.PageTitle ?? "APP.TITLE") - @T("APP.TITLE")</title>
  <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-4">
    @await Html.PartialAsync("_Navbar")
    @await Html.PartialAsync("_Flash")
    @RenderBody()
    @await Html.PartialAsync("_Errors")
  </div>
  @* el cuadro de diálogo "Are you sure?", oculto mientras no se necesite *@
  @await Html.PartialAsync("_Confirmation")
  <script src="/js/app.js"></script>
</body>
</html>
  • línea 20: la plantilla comparte el modelo de la página, accesible mediante [ViewData.Model] (de tipo [object]). Todas las plantillas de página derivan de la clase abstracta [ViewModel], que contiene la clave del título ([PageTitle]) y el error de la página ([Error]). [as ViewModel] devuelve [null] si la plantilla no es un [ViewModel]: la plantilla funciona con cualquier página;
  • línea 23: el idioma de la página (vea el Ejemplo 22);
  • línea 27: el título, traducido, por ejemplo, «Schedule - RdvMedecins». A diferencia del Ejemplo 22, la clave no la establece la vista en [ViewData]: la proporciona el controlador en el modelo tipado. [page?.PageTitle] es igual a [null] si [page] es [null], y el operador [??] reemplaza entonces la clave por [APP.TITLE];
  • líneas 28–29: las hojas de estilo, servidas por [UseStaticFiles] desde la carpeta [wwwroot]: [Bootstrap] ([wwwroot/lib/bootstrap]) y la hoja de estilo propia de la aplicación;
  • líneas 33–36: la barra de navegación, el mensaje de éxito (en la parte superior), la página solicitada ([@RenderBody()]) y el área de error (en la parte inferior);
  • líneas 39–40: la ventana de confirmación (oculta) y su script (vea el Ejemplo 21), cargado al final de la página.

11.17.1.4. Views/Shared/_Navbar.cshtml

@* =========================================================================
   Views/Shared/_Navbar.cshtml - la barra de navegación.

   Título, FR/EN, rol, nombre, cierre de sesión - y un menú cuyas entradas
   dependen del rol: "Doctors" y "Patients" aparecen solo para
   el ADMIN. Es solo una comodidad de visualización: la protección real es
   el [Authorize(Roles = ...)] de los controladores (un USER que escribe /doctors
   a mano obtiene una página 403). Un paciente (USER) tiene además su
   menú "My area".
   ========================================================================= *@
@{
    var user = CurrentUser;
}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">@T("APP.TITLE")</span>

  @if (user is not null)
  {
    <ul class="navbar-nav me-auto">
      @if (user.IsPatient)
      {
        <li class="nav-item"><a class="nav-link @Active("/my-")" href="/my-area">@T("APP.MENU_MY_AREA")</a></li>
      }
      <li class="nav-item"><a class="nav-link @Active("/schedule")" href="/schedule">@T("APP.MENU_SCHEDULE")</a></li>
      @if (user.IsAdmin)
      {
        <li class="nav-item"><a class="nav-link @Active("/doctors")" href="/doctors">@T("APP.MENU_DOCTORS")</a></li>
        <li class="nav-item"><a class="nav-link @Active("/clients")" href="/clients">@T("APP.MENU_PATIENTS")</a></li>
      }
    </ul>
  }
  else
  {
    <div class="me-auto"></div>
  }

  <div class="d-flex align-items-center gap-2">
    @* FR / EN: enlaces simples (GET /language/fr), el idioma activo resaltado *@
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      <a class="btn @(Language == "fr" ? "btn-light" : "btn-outline-light")" href="/language/fr">FR</a>
      <a class="btn @(Language == "en" ? "btn-light" : "btn-outline-light")" href="/language/en">EN</a>
    </div>

    @if (user is not null)
    {
      <span class="badge text-bg-light text-primary">@user.Role</span>
      <span class="text-white">@user.Name</span>
      @* logout es un POST: un formulario reducido a su botón *@
      <form method="post" action="/logout" class="m-0">
        <button type="submit" class="btn btn-sm btn-outline-light">@T("APP.LOGOUT")</button>
      </form>
    }
  </div>
</nav>
  • línea 12: el usuario conectado, según lo describe la clase [ViewUser] de [Web/ViewPage.cs] (login, nombre, rol, [IsAdmin], [IsPatient]), derivada del token JWT. Vale [null] en las páginas públicas (inicio de sesión, creación de cuenta);
  • líneas 17–31: los menús dependen del rol: «Mi área» para un paciente, «Médicos» y «Pacientes» para ADMIN. Esto es solo por comodidad: la seguridad la garantizan los atributos [[Authorize(Roles = ...)]] de los controladores (un paciente que ingrese manualmente [/doctors] recibirá una página 403). [Active("/doctors")] devuelve [active] si la ruta solicitada comienza con [/doctors]: [Bootstrap] resalta entonces este menú. El prefijo [/my-] abarca las dos páginas del paciente, [/my-area] y [/my-account];
  • línea 34: sin menús, un bloque vacío ocupa su lugar ([me-auto]: margen derecho automático), de modo que el resto del contenido permanezca a la derecha de la barra;
  • líneas 40–41: los enlaces FR / EN del Ejemplo 22. La expresión [@( ... )] va entre paréntesis porque contiene espacios (vea el Ejemplo 14);
  • líneas 44–52: el rol, el nombre y el botón de cierre de sesión en un formulario POST (vea el Ejemplo 21).

11.17.1.5. Views/Shared/_Flash.cshtml

@* =========================================================================
   Views/Shared/_Flash.cshtml - el mensaje de ÉXITO puesto por la acción
   anterior (cita guardada, médico agregado...), mostrado una sola
   vez, en la parte superior de la página (ver Web/Flash.cs).
   Un mensaje flash de ERROR, por su parte, se muestra en la parte inferior de la página, mediante
   _Errors.cshtml.
   ========================================================================= *@
@{
    var flash = FlashMessage;
}
@if (flash is { Type: FlashType.Success })
{
  <div class="alert alert-success" role="status">
    @T(flash.Key, flash.Params)
  </div>
}
  • línea 9: el mensaje flash publicado por la acción anterior (vea el Ejemplo 20 y [Web/Flash.cs]). Leer un mensaje flash lo borra; como la página lo lee dos veces (aquí y en [_Errors.cshtml]), la clase [Flash] lo almacena, una vez leído, en [HttpContext.Items] (vea el Capítulo 6);
  • línea 11: [flash is { Type: FlashType.Success }] es un patrón de propiedades: la condición es verdadera si [flash] no es [null] y si su propiedad [Type] es igual a [FlashType.Success]. Aquí solo se muestra un mensaje de éxito;
  • línea 14: el mensaje es una clave; sus posibles parámetros ([name], [login], [minutes]) son un diccionario, que se pasa a la segunda forma del método [T]. [role="status"]: un lector de pantalla anuncia el mensaje sin interrumpir al usuario.

11.17.1.6. Views/Shared/_Errors.cshtml

@* =========================================================================
   Views/Shared/_Errors.cshtml - la zona de errores, al FINAL de cada página,
   sobre un fondo rosa claro (clase .error-zone, ver wwwroot/css/styles.css).

   Reúne las dos posibles fuentes de error:
     - Error: el error de la página mostrada (formulario rechazado, login o
       nombre + apellido ya utilizados, fecha inválida, contraseña incorrecta...);
     - un mensaje flash de error, puesto por la acción anterior antes de una
       redirección (horario ya reservado, eliminación rechazada...).

   role="alert": un lector de pantalla anuncia el mensaje apenas se muestra
   la página, aunque esté al final.
   ========================================================================= *@
@{
    var page = ViewData.Model as ViewModel;
    var error = page?.Error;
    var flash = FlashMessage;
    var flashError = flash is { Type: FlashType.Danger } ? flash : null;
}
@if (error is not null || flashError is not null)
{
  <div class="error-zone" role="alert">
    @if (error is not null)
    {
      <div>@T(error, page!.ErrorParams)</div>
    }
    @if (flashError is not null)
    {
      <div>@T(flashError.Key, flashError.Params)</div>
    }
  </div>
}
  • líneas 15–18: las dos fuentes de error: el error de la página mostrada (propiedad [Error] de la plantilla: formulario rechazado, contraseña incorrecta, etc.) y un mensaje flash de error mostrado antes de una redirección (franja ya reservada, eliminación rechazada, etc.);
  • líneas 20–22: el área se muestra si hay alguno de los dos presente. [role="alert"]: un lector de pantalla anuncia el mensaje en cuanto se muestra la página, aunque esté al final. La clase [error-zone] se define en [wwwroot/css/styles.css];
  • línea 25: el operador [!] indica al compilador que [page] no es [null]: no puede deducirlo por sí solo, aunque es seguro porque [error], leído de [page], no lo es.

11.17.1.7. Views/Shared/_Confirmation.cshtml

@* =========================================================================
   Views/Shared/_Confirmation.cshtml - el cuadro de diálogo modal "Are you sure?".

   Reemplaza el cuadro window.confirm() del navegador, que no se puede
   personalizar ni traducir (sus botones permanecen en el idioma del
   navegador, no en el de la página).

   UN SOLO cuadro de diálogo para toda la página, oculto (d-none) al inicio. Sus
   etiquetas se traducen aquí, en el servidor, como el resto de la página;
   el pequeño script wwwroot/js/app.js se limita a mostrarlo, a poner en él
   el mensaje propio del formulario (atributo data-confirmation) y a enviar
   el formulario si el usuario confirma.

   Mismas clases de Bootstrap que el cuadro de reserva (Schedule/_Booking.cshtml).
   ========================================================================= *@
<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" en lugar de "Cancel": la pregunta a veces es
             "Cancel this appointment?", y un botón "Cancel" sería ambiguo en ese caso *@
          <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>

La ventana del Ejemplo 21, con las etiquetas traducidas por el servidor, como el resto de la página, y con atributos de accesibilidad:

  • línea 16: una única ventana para toda la página, inicialmente oculta ([d-none]);
  • líneas 18–19: [role="alertdialog"] indica una ventana que espera una respuesta; [aria-modal="true"] indica que el resto de la página está inactivo; [aria-labelledby] y [aria-describedby] designan el título y el mensaje que lee un lector de pantalla;
  • línea 24: el botón de cierre, que significa «No» ([data-action="no"]). No tiene texto: [aria-label] proporciona un nombre para los lectores de pantalla;
  • líneas 32–33: «No, go back» en lugar de «Cancel»: a veces la pregunta es «¿Cancelar esta cita?», y un botón «Cancel» sería ambiguo en ese contexto.

11.17.1.8. Views/Auth/_Captcha.cshtml

@* =========================================================================
   Views/Auth/_Captcha.cshtml - el captcha de la página de autenticación
   (véase Auth/CaptchaService.cs). Protege tanto el inicio de sesión como
   el acceso a la creación de cuenta (botón "Create a patient account").

   @Html.Raw(...): la imagen SVG se inserta TAL CUAL en la página, sin
   escapar. Aquí es inofensivo porque este SVG lo construye el propio
   servidor y no contiene nada que provenga del usuario - NUNCA haríamos esto
   con datos del usuario.

   El campo oculto captchaId le indica al servidor QUÉ captcha verificar; la respuesta
   correcta, por su parte, nunca se envía al navegador.
   "Another image" simplemente recarga la página (path = la URL actual).
   ========================================================================= *@
@model RdvMedecins.Auth.Captcha
<div class="mb-3">
  <label class="form-label" for="captcha">@T("CAPTCHA.LABEL")</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="@T("CAPTCHA.IMAGE_ALT")">@Html.Raw(Model.Svg)</div>
    <a class="small" href="@CurrentPath">@T("CAPTCHA.NEW_IMAGE")</a>
  </div>
  <input type="hidden" name="captchaId" value="@Model.Id">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false" required
         class="form-control">
  <div class="form-text">@T("CAPTCHA.HELP")</div>
</div>
  • línea 15: la vista parcial tiene su propia plantilla, el CAPTCHA generado por [Auth/CaptchaService.cs] (vea el Ejemplo 27): su identificador y su imagen;
  • línea 19: la imagen SVG se inserta tal cual (vea el Ejemplo 14): la genera el servidor, sin ninguna entrada del usuario. [role="img"] y [aria-label] presentan una imagen a los lectores de pantalla;
  • línea 20: «Another image» simplemente recarga la página actual: se genera un nuevo CAPTCHA;
  • línea 22: el identificador del CAPTCHA, en un campo oculto: indica al servidor qué CAPTCHA verificar. La respuesta correcta, sin embargo, nunca sale del servidor;
  • líneas 23–24: el campo de entrada. [autocomplete="off"], [autocapitalize="off"] y [spellcheck="false"] impiden que el navegador sugiera, ponga en mayúscula o corrija los caracteres copiados.

11.17.1.9. Views/Shared/_PersonFields.cshtml

@* =========================================================================
   Views/Shared/_PersonFields.cshtml - los campos de identidad (título,
   nombre, apellido), comunes a tres formularios: el formulario de médico/cliente del ADMIN,
   "Create a patient account" y "Manage my account".
   El parcial recibe el modelo de la página que lo inserta (un FormView):
   valores, mensaje bajo cada campo, campos resaltados en rojo.

   selected="@selected": un atributo booleano. Razor escribe selected="selected"
   si el valor es true, y OMITE el atributo si es false.
   ========================================================================= *@
@model FormView
<div class="mb-3">
  <label class="form-label" for="title">@T("PERSONS.TITLE_LABEL")</label>
  <select id="title" name="title" class="form-select @Model.InvalidClass("title")">
    @foreach (var (value, selected) in Model.Titles)
    {
      <option value="@value" selected="@selected">@value</option>
    }
  </select>
  @if (Model.ErrorOf("title") is { } titleError)
  {
    <div class="invalid-feedback">@T(titleError)</div>
  }
</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 @Model.InvalidClass("firstName")" value="@Model.Values.FirstName">
    @if (Model.ErrorOf("firstName") is { } firstNameError)
    {
      <div class="invalid-feedback">@T(firstNameError)</div>
    }
  </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 @Model.InvalidClass("lastName")" value="@Model.Values.LastName">
    @if (Model.ErrorOf("lastName") is { } lastNameError)
    {
      <div class="invalid-feedback">@T(lastNameError)</div>
    }
  </div>
</div>

Los campos de identidad (título, nombre, apellido), comunes a tres formularios: médico o cliente de ADMIN, creación de cuenta y gestión de la cuenta del paciente.

  • línea 11: [FormView] es la clase padre (abstracta) de las plantillas de estos tres formularios. Contiene los valores ingresados ([Values]), el mensaje de error de cada campo rechazado ([Errors]) y los campos que se resaltarán en rojo ([InvalidFields]). Por lo tanto, la vista parcial acepta la plantilla de cada una de las tres páginas;
  • líneas 14–19: la lista de títulos. [Model.Titles] devuelve tuplas (valor, ¿seleccionado?); [var (value, selected)] descompone cada tupla en dos variables. [selected="@selected"] es un atributo booleano, que se escribe solo si el valor es verdadero (vea el Ejemplo 17). [InvalidClass("title")] devuelve [is-invalid] si el campo debe enmarcarse en rojo (vea el Ejemplo 19);
  • líneas 20–23: el mensaje de error del campo, si lo hay. [ErrorOf] devuelve el mensaje, o [null]; la condición [is { } titleError] es verdadera si el valor no es [null], y entonces lo almacena en la nueva variable [titleError];
  • líneas 26–45: el nombre y el apellido, con el mismo formato, uno junto al otro en una pantalla suficientemente ancha (cuadrícula de [Bootstrap]: [col-sm-6]). Los atributos [maxlength] y [required] son solo por comodidad: los formularios que insertan esta vista parcial tienen el atributo [novalidate], y el servidor se encarga de la validación.

11.17.1.10. Views/Schedule/_Booking.cshtml

@* =========================================================================
   Views/Schedule/_Booking.cshtml - el cuadro de reserva.

   Misma técnica que el cliente Angular (booking-dialog): las clases REALES de Bootstrap
   de un cuadro de diálogo modal (.modal, .modal-backdrop...), hechas
   visibles "a la fuerza" (show d-block) en lugar de mediante el JavaScript de
   Bootstrap. La diferencia: es el SERVIDOR quien decide mostrarlo
   (parámetro &book=... de la URL), y cerrarlo equivale a seguir un enlace
   a la misma página sin este parámetro.
   ========================================================================= *@
@model ScheduleModel
@{
    var booking = Model.Booking!;
}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="/schedule/book" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">@T("BOOKING_DIALOG.TITLE")</h5>
        <a class="btn-close" href="@Model.BackUrl" aria-label="@T("BOOKING_DIALOG.CLOSE_ARIA")"></a>
      </div>

      <div class="modal-body">
        <p>@T("BOOKING_DIALOG.SLOT", ("time", booking.Time))</p>

        @* lo que el servidor necesita saber además del paciente elegido *@
        <input type="hidden" name="doctorId" value="@Model.DoctorId">
        <input type="hidden" name="day" value="@Model.Day">
        <input type="hidden" name="slotId" value="@booking.SlotId">

        @if (booking.Patient is not null)
        {
          @* un paciente reserva para sí mismo: no hay lista de donde elegir
             (y el servidor ignora cualquier clientId de todos modos) *@
          <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>
            @foreach (var client in booking.Clients)
            {
              <option value="@client.Id">@client.Label</option>
            }
          </select>
        }
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" href="@Model.BackUrl">@T("BOOKING_DIALOG.CANCEL")</a>
        <button type="submit" class="btn btn-primary">@T("BOOKING_DIALOG.CONFIRM")</button>
      </div>
    </form>
  </div>
</div>
  • línea 11: la vista parcial recibe la plantilla de la página del calendario. [Model.Booking!]: la página la inserta solo si [Booking] no es [null], lo cual el operador [!] afirma al compilador;
  • líneas 15–16: las clases [Bootstrap] de una ventana modal y de su fondo gris, hechas visibles «a fuego» ([show d-block]): el servidor decide mostrar la ventana cuando la URL contiene el parámetro [book]. El [JavaScript] de [Bootstrap] no se utiliza (ni siquiera se carga);
  • línea 18: el contenido de la ventana es el propio formulario de reserva;
  • línea 21: cerrar la ventana sigue un enlace al mismo calendario, sin el parámetro [book] ([BackUrl], preparado por el controlador);
  • línea 25: «Slot 8:00 - 8:20»: un parámetro de traducción;
  • líneas 28–30: campos ocultos: información adicional que el servidor necesita además del paciente seleccionado;
  • líneas 32–48: un paciente ve su nombre; un administrador (ADMIN, DOCTOR) selecciona al paciente de una lista. La primera opción tiene un valor vacío: con [required], el navegador exige que se seleccione un paciente real. [autofocus] coloca el cursor en la lista;
  • líneas 52–53: «Cancel» es un enlace, igual que la X; «Confirm» envía el formulario.

11.17.2. Las páginas

11.17.2.1. Views/Auth/Login.cshtml

@* =========================================================================
   Views/Auth/Login.cshtml - el formulario de inicio de sesión.
   Un <form> HTML ordinario: el propio navegador envía login,
   contraseña y respuesta del captcha con POST /login, sin JavaScript. En
   caso de fallo, el servidor devuelve ESTA página, con el login ya escrito, un
   NUEVO captcha y el error, mostrado al final de la página por el layout.

   @model: el tipo del modelo de vista. El compilador verifica cada
   @Model.Xxx (un error tipográfico es un error de compilación).
   ========================================================================= *@
@model LoginModel
@{
    var loginTyped = Model.Login != "";
}
<div class="row justify-content-center">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3">@T("LOGIN.TITLE")</h5>

      <form method="post" action="/login">
        <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="@Model.Login" required autofocus="@(!loginTyped)">
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">@T("LOGIN.PASSWORD_LABEL")</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required autofocus="@loginTyped">
        </div>

        @await Html.PartialAsync("_Captcha", Model.Captcha)

        <button type="submit" class="btn btn-primary w-100">@T("LOGIN.SUBMIT")</button>

        @* aún no hay cuenta: un paciente puede crear una por sí mismo.
           NO es un simple enlace: es un segundo botón de envío de
           ESTE formulario, que va a otra dirección (formaction). El
           servidor verifica allí el CAPTCHA de arriba antes de abrir la página de
           creación de cuenta (ver RegistrationController).
           formnovalidate: el navegador no exige login ni contraseña
           (inútil para crear una cuenta); es el servidor quien verifica
           el CAPTCHA. Enter en un campo siempre activa el PRIMER
           botón del formulario, "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>
  • línea 13: tras un fallo, el controlador devuelve esta página con el nombre de usuario ya ingresado;
  • línea 20: un formulario HTML estándar: el navegador envía por sí solo el nombre de usuario, la contraseña y la respuesta del CAPTCHA;
  • líneas 23–29: [autofocus] es un atributo booleano: solo uno de los dos campos lo recibe. El cursor se coloca en el campo del nombre de usuario, o en el de la contraseña si el nombre de usuario ya se conoce. Los valores de [autocomplete] ([username], [current-password]) ayudan a los administradores de contraseñas de los navegadores;
  • línea 32: el CAPTCHA; el segundo argumento proporciona la plantilla de la vista parcial;
  • líneas 45–46: el segundo botón envía el mismo formulario a [/register/access] (atributo [formaction], vea el Ejemplo 20): allí el servidor verifica el CAPTCHA antes de abrir la página de creación de cuenta. [formnovalidate]: el navegador no exige un nombre de usuario ni una contraseña, ya que no son necesarios para crear una cuenta. Pulsar la tecla Entrar en un campo siempre activa el primer botón del formulario: «Log in»;
  • líneas 51–56: cuentas de demostración (contraseña = nombre de usuario).

11.17.2.2. Views/Schedule/Schedule.cshtml

@* =========================================================================
   Views/Schedule/Schedule.cshtml - la página principal (ver ScheduleController).
   Tres bloques, como los tres componentes del cliente Angular:
     1. la elección del médico y del día  (<app-doctor-day-picker>)
     2. la agenda                          (<app-agenda>)
     3. el cuadro de reserva                (<app-booking-dialog>)
   Un posible error (fecha inválida, médico desconocido) se muestra en la
   parte inferior de la página mediante el layout (ver Views/Shared/_Errors.cshtml).
   ========================================================================= *@
@model ScheduleModel

@* 1. elección del médico y del día: un formulario GET, que simplemente
   recarga esta página con ?doctorId=...&day=... en la URL *@
<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>
        @foreach (var doctor in Model.Doctors)
        {
          <option value="@doctor.Id" selected="@doctor.Selected">@doctor.Label</option>
        }
      </select>
    </div>
    <div class="col-sm-4">
      <label class="form-label" for="day">@T("DOCTOR_DAY_PICKER.DAY_LABEL")</label>
      <input id="day" name="day" type="date" class="form-control" value="@Model.Day" required>
    </div>
    <div class="col-sm-3">
      <button type="submit" class="btn btn-primary w-100">@T("DOCTOR_DAY_PICKER.VIEW_SCHEDULE")</button>
    </div>
  </div>
</form>

@* paciente que ya tiene una próxima cita: por eso no hay botón "Book" *@
@if (Model.Info is not null)
{
  <div class="alert alert-info">
    @T(Model.Info) <a href="/my-area" class="alert-link">@T("APP.MENU_MY_AREA")</a>
  </div>
}

@* 2. la agenda *@
@if (Model.Schedule is { } schedule)
{
  <div class="card p-3">
    <h5>@T("SCHEDULE.TITLE_PREFIX") @schedule.Day - @schedule.Doctor</h5>

    @if (schedule.Rows.Count > 0)
    {
      <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>
          @foreach (var row in schedule.Rows)
          {
            <tr class="@(row.Bookable ? "free-slot" : null)">
              <td>@row.Time</td>
              <td>
                @* [Patient] se rellena solo si el usuario tiene permiso para
                   ver este nombre (ADMIN, DOCTOR, o el paciente para SU
                   cita); de lo contrario, simplemente "Booked" *@
                @if (row.Free)
                {
                  <span class="badge text-bg-success">@T("SCHEDULE.FREE")</span>
                }
                else if (row.Patient is not null)
                {
                  <span class="badge @(row.Mine ? "text-bg-primary" : "text-bg-secondary")">@row.Patient</span>
                }
                else
                {
                  <span class="badge text-bg-secondary">@T("SCHEDULE.BOOKED_BY_OTHER")</span>
                }
              </td>
              <td>
                @* los botones mostrados los decidió el controlador
                   (Bookable, AppointmentId) según el rol del usuario *@
                @if (row.Bookable)
                {
                  @* "Book" es un simple enlace: reabre esta página
                     con el cuadro de reserva de este horario *@
                  <a class="btn btn-sm btn-outline-success" href="@row.BookUrl">@T("SCHEDULE.BOOK")</a>
                }
                @if (row.AppointmentId is not null)
                {
                  @* "Cancel" MODIFICA datos: por lo tanto es un POST *@
                  <form method="post" action="/schedule/cancel" class="m-0"
                        data-confirmation="@T("SCHEDULE.CANCEL_CONFIRM")">
                    <input type="hidden" name="appointmentId" value="@row.AppointmentId">
                    <input type="hidden" name="doctorId" value="@Model.DoctorId">
                    <input type="hidden" name="day" value="@Model.Day">
                    <button type="submit" class="btn btn-sm btn-outline-danger">@T("SCHEDULE.CANCEL_APPOINTMENT")</button>
                  </form>
                }
              </td>
            </tr>
          }
        </tbody>
      </table>
    }
    else
    {
      <p class="text-muted mb-0">@T("SCHEDULE.NO_SLOTS")</p>
    }
  </div>
}
else
{
  <p class="text-muted">@T("SCHEDULE.EMPTY_STATE")</p>
}

@* 3. el cuadro de reserva, solo si la URL contiene &book=... *@
@if (Model.Booking is not null)
{
  @await Html.PartialAsync("_Booking", Model)
}

Comentemos este código:

  • líneas 14–34: selección del médico y del día: un formulario GET (vea el Ejemplo 17), que recarga la página con [?doctorId=...&day=...] en la URL. Cada médico es un [OptionView] que indica si está seleccionado. Un campo [type="date"] envía la fecha en el formato [yyyy-mm-dd] (vea el Ejemplo 18);
  • líneas 37–42: un mensaje para un paciente que ya tiene una cita próxima: explica por qué faltan los botones «Book»;
  • línea 45: el calendario, si se solicitó. La condición [is { } schedule] comprueba que la propiedad no es [null] y almacena su valor en la variable [schedule];
  • línea 48: el título: «Schedule for 2026-09-25 – Mme Marie PELISSIER»;
  • línea 63: una franja reservable cambia de color al pasar el cursor (clase [free-slot], vea [styles.css]). Cuando el valor de un atributo es [null], [Razor] no escribe el atributo en absoluto: las demás filas no tienen el atributo [class];
  • líneas 69–80: tres casos: disponible; reservada, con el nombre del paciente (en azul si es la cita del paciente conectado, [Mine]); reservada sin nombre visible, «Booked». El controlador solo rellena [Patient] si el usuario tiene permiso para ver ese nombre;
  • líneas 85–90: «Book» es un enlace: vuelve a abrir esta página, mostrando la ventana de reserva para esta franja ([BookUrl], preparada por el controlador);
  • líneas 91–101: «Cancel» modifica datos: es un formulario POST, con confirmación ([data-confirmation], vea el Ejemplo 21). Los campos ocultos [doctorId] y [day] permiten al controlador redirigir al mismo calendario. Dentro del bucle, [Model] siempre se refiere a la plantilla de la página: no hace falta el equivalente de [@root] ni de [Handlebars];
  • líneas 110 y 116: un médico sin franjas disponibles, o aún no se ha solicitado ningún calendario;
  • líneas 120–123: la ventana de reserva, si el controlador la preparó.

11.17.2.3. Views/Persons/List.cshtml

@* =========================================================================
   Views/Persons/List.cshtml - la lista de los médicos O de los clientes (ADMIN).
   Una sola vista para ambos: las etiquetas propias de cada uno llegan en
   Model.Keys (ver DoctorsController / ClientsController).
   ========================================================================= *@
@model PersonListModel
<div class="d-flex justify-content-between align-items-center mb-3">
  <h4 class="mb-0">@T(Model.Keys.Title)</h4>
  <a class="btn btn-primary" href="@Model.AddUrl">@T(Model.Keys.Add)</a>
</div>

<div class="card p-3">
  @if (Model.Persons.Count > 0)
  {
    <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>
        @foreach (var person in Model.Persons)
        {
          <tr>
            <td>@person.Title</td>
            <td>@person.FirstName</td>
            <td>@person.LastName</td>
            <td><code>@person.Login</code></td>
            <td class="text-end">
              <div class="d-inline-flex gap-2">
                <a class="btn btn-sm btn-outline-primary" href="@person.EditUrl">@T("PERSONS.EDIT")</a>
                @* data-confirmation: se abrirá un cuadro de confirmación
                   antes de enviar el formulario (ver wwwroot/js/app.js) *@
                <form method="post" action="@person.DeleteUrl" class="m-0"
                      data-confirmation="@T(Model.Keys.ConfirmDelete)">
                  <button type="submit" class="btn btn-sm btn-outline-danger">@T("PERSONS.DELETE")</button>
                </form>
              </div>
            </td>
          </tr>
        }
      </tbody>
    </table>
  }
  else
  {
    <p class="text-muted mb-0">@T(Model.Keys.Empty)</p>
  }
</div>

Una sola vista para médicos y clientes:

  • líneas 8–9: los textos específicos de cada usuario aparecen como claves ([Model.Keys], del tipo [PersonKeys]), proporcionadas por [DoctorsController] o [ClientsController]: [DOCTORS.TITLE] o [CLIENTS.TITLE], etc.;
  • líneas 26–45: una fila por persona, con dos botones;
  • línea 35: «Edit» es un enlace al formulario;
  • líneas 38–41: «Delete» es un formulario POST, con confirmación;
  • línea 51: «No doctors.» o «No patients.»

11.17.2.4. Views/Persons/Form.cshtml

@* =========================================================================
   Views/Persons/Form.cshtml - creación O actualización de un médico
   o de un cliente (ADMIN). Model.Creating distingue los dos casos.

   Cuando se rechaza la entrada (campo vacío, login ya utilizado...), el
   controlador devuelve ESTA vista con:
     - los valores ya escritos (Model.Values);
     - los campos erróneos resaltados en rojo (clase "is-invalid" de Bootstrap);
     - bajo un campo rechazado por la validación, su mensaje;
     - el mensaje de error de la página, mostrado AL FINAL de la página por el
       layout (ver Views/Shared/_Errors.cshtml).
   ========================================================================= *@
@model PersonFormModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-3">@T(Model.PageTitle)</h5>

      @* novalidate: dejamos que el SERVIDOR valide (es quien tiene la autoridad);
         las verificaciones del navegador (required...) son solo una comodidad,
         que un usuario siempre puede eludir *@
      <form method="post" action="@Model.Action" novalidate>
        @if (!Model.Creating)
        {
          <input type="hidden" name="version" value="@Model.Values.Version">
        }

        @* título, nombre, apellido: parcial común a tres formularios *@
        @await Html.PartialAsync("_PersonFields", Model)

        <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 @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
          else
          {
            <div class="form-text">@T(Model.Creating ? "PERSONS.LOGIN_HELP_CREATE" : "PERSONS.LOGIN_HELP_EDIT")</div>
          }
        </div>

        <div class="mb-4">
          <label class="form-label" for="password">@T("PERSONS.PASSWORD_LABEL")</label>
          @* nunca se rellena previamente: la contraseña nunca vuelve al navegador *@
          <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                 class="form-control @Model.InvalidClass("password")">
          @if (Model.ErrorOf("password") is { } passwordError)
          {
            <div class="invalid-feedback">@T(passwordError)</div>
          }
          else
          {
            <div class="form-text">@T(Model.Creating ? "PERSONS.PASSWORD_HELP_CREATE" : "PERSONS.PASSWORD_HELP_EDIT")</div>
          }
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">@T("PERSONS.SAVE")</button>
          <a class="btn btn-secondary" href="@Model.ListUrl">@T("PERSONS.BACK")</a>
        </div>
      </form>
    </div>
  </div>
</div>

Comentemos este código:

  • línea 17: el título («Add a doctor», «Edit a patient», etc.) es la clave del título de la página, proporcionada por el controlador;
  • línea 22: la URL la proporciona el controlador: la misma vista se usa tanto para agregar como para editar médicos y clientes. [novalidate]: el servidor se encarga de la validación (vea el Ejemplo 19);
  • líneas 23–25: en una edición, la versión del registro, en un campo oculto: es el bloqueo optimista del Ejemplo 28;
  • línea 29: los campos de identidad;
  • líneas 34–44: el login, con un mensaje de error o, si no lo hay, un texto de ayuda. El texto de ayuda difiere según se trate de una adición («Optional: defaults to the last name in lower case.») o de una edición;
  • líneas 48–59: la contraseña, que nunca se rellena previamente; nunca se devuelve al navegador. [autocomplete="new-password"]: el navegador no sugiere la contraseña guardada del administrador. La longitud se limita a 72 caracteres porque el algoritmo [bcrypt] ignora los caracteres siguientes;
  • línea 64: el enlace de regreso a la lista es un hipervínculo.

11.17.2.5. Views/Registration/Registration.cshtml

@* =========================================================================
   Views/Registration/Registration.cshtml - "Create a patient account" (página
   pública, ver RegistrationController). Mismos campos de identidad que el formulario
   del ADMIN (parcial _PersonFields), pero el login y la
   contraseña son obligatorios, con confirmación.
   Sin CAPTCHA AQUÍ: a esta página solo se llega después de copiar
   el de la página de autenticación (botón "Create a patient account").
   ========================================================================= *@
@model RegistrationModel
<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>
        @await Html.PartialAsync("_PersonFields", Model)

        <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 @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
          else
          {
            <div class="form-text">@T("REGISTRATION.LOGIN_HELP")</div>
          }
        </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 @Model.InvalidClass("password")">
            @if (Model.ErrorOf("password") is { } passwordError)
            {
              <div class="invalid-feedback">@T(passwordError, ("min", Model.PasswordMin))</div>
            }
            else
            {
              <div class="form-text">@T("REGISTRATION.PASSWORD_HELP", ("min", Model.PasswordMin))</div>
            }
          </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 @Model.InvalidClass("confirmation")">
            @if (Model.ErrorOf("confirmation") is { } confirmationError)
            {
              <div class="invalid-feedback">@T(confirmationError)</div>
            }
          </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>

Creación de una cuenta de cliente, página pública. Aquí no hay CAPTCHA: solo se puede llegar a esta página después de resolver el CAPTCHA de la página de inicio de sesión.

  • línea 17: los mismos campos de identidad que en el formulario de ADMIN;
  • líneas 22–32: el nombre de usuario, que esta vez es obligatorio;
  • líneas 37–47: el texto de ayuda y el mensaje «demasiado corta» tienen un parámetro, [{min}], que es la longitud mínima de la contraseña proporcionada por la plantilla ([PasswordMin]). Un mensaje sin el parámetro [{min}] simplemente ignora el valor proporcionado;
  • líneas 50–56: confirmación de la contraseña;
  • línea 62: regreso a la página de inicio de sesión.

11.17.2.6. Views/PatientArea/Area.cshtml

@* =========================================================================
   Views/PatientArea/Area.cshtml - "My area": la página de inicio del
   paciente (rol USER), mostrada justo después de iniciar sesión.
     - dos opciones: [Manage my account] y [View a schedule];
     - su próxima cita, si tiene una, con el medio para cancelarla.
   ========================================================================= *@
@model AreaModel
<h4 class="mb-3">@T("AREA.HELLO", ("name", Model.Patient))</h4>

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

<div class="card p-3">
  <h5>@T("AREA.MY_APPOINTMENT")</h5>
  @if (Model.Appointments.Count > 0)
  {
    @* normalmente solo una (regla "una próxima cita a la vez"),
       pero la página puede mostrar varias *@
    for (var i = 0; i < Model.Appointments.Count; i++)
    {
      var appointment = Model.Appointments[i];
      var last = i == Model.Appointments.Count - 1;
      <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 @(last ? "" : "border-bottom")">
        <div>
          <div class="fw-semibold">@appointment.Day, @appointment.Time</div>
          <div class="text-muted">@appointment.Doctor - <a href="@appointment.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="@appointment.Id">
          <button type="submit" class="btn btn-outline-danger">@T("AREA.CANCEL_APPOINTMENT")</button>
        </form>
      </div>
    }
  }
  else
  {
    <p class="text-muted mb-0">@T("AREA.NO_APPOINTMENT")</p>
  }
</div>
  • línea 8: «Hello Mr Jean MARTIN»;
  • líneas 12–21: las dos opciones son enlaces, mostrados como tarjetas (clase [option-card], vea [styles.css]);
  • líneas 31–46: próximas citas (normalmente solo una). Dentro de un bloque [@if], el formato es [C#]: el bucle [for] se escribe sin [@]. Un borde ([border-bottom]) separa las citas, excepto después de la última;
  • líneas 40–44: la cancelación, un formulario POST con confirmación.

11.17.2.7. Views/PatientArea/Account.cshtml

@* =========================================================================
   Views/PatientArea/Account.cshtml - "Manage my account" (rol USER).
   Dos formularios independientes en la misma página:
     1. la actualización (identidad, login, nueva contraseña opcional);
     2. la eliminación de la cuenta, que también cancela sus citas.
   Ambos exigen la contraseña ACTUAL.
   ========================================================================= *@
@model MyAccountModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    @* 1. actualización *@
    <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="@Model.Values.Version">

        @await Html.PartialAsync("_PersonFields", Model)

        <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 @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
        </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 @Model.InvalidClass("password")">
            @if (Model.ErrorOf("password") is { } passwordError)
            {
              <div class="invalid-feedback">@T(passwordError, ("min", Model.PasswordMin))</div>
            }
            else
            {
              <div class="form-text">@T("PERSONS.PASSWORD_HELP_EDIT")</div>
            }
          </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 @Model.InvalidClass("confirmation")">
            @if (Model.ErrorOf("confirmation") is { } confirmationError)
            {
              <div class="invalid-feedback">@T(confirmationError)</div>
            }
          </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 @Model.InvalidClass("currentPassword")">
          @if (Model.ErrorOf("currentPassword") is { } currentError)
          {
            <div class="invalid-feedback">@T(currentError)</div>
          }
          else
          {
            <div class="form-text">@T("MY_ACCOUNT.CURRENT_PASSWORD_HELP")</div>
          }
        </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. eliminación *@
    <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>
  • líneas 16–76: modificación de la cuenta: identidad, login, nueva contraseña (opcional) y su confirmación;
  • línea 17: la versión del registro del cliente (bloqueo optimista);
  • líneas 59–69: la contraseña actual, obligatoria para cualquier modificación;
  • líneas 83–91: la eliminación, con confirmación. Dos formularios independientes en la misma página: cada uno envía solo sus propios campos. Por eso el campo de contraseña tiene aquí un nombre distinto ([deletePassword]) y un identificador distinto. Este formulario no tiene el atributo [novalidate]: el navegador exige la contraseña ([required]) incluso antes de desencadenar el evento [submit], es decir, antes de plantear la pregunta de confirmación.

11.17.2.8. Views/Shared/Error.cshtml

@* =========================================================================
   Views/Shared/Error.cshtml - la página de error (400, 403, 404, 500),
   construida por ErrorController.
   ========================================================================= *@
@model ErrorModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger">@Model.Code</h1>
      <p class="lead">@T(Model.Message)</p>
      <div><a class="btn btn-primary" href="/">@T("ERROR_PAGE.BACK")</a></div>
    </div>
  </div>
</div>
  • líneas 9–10: la página de error generada por [ErrorController] (400, 403, 404, 500): el código HTTP y el mensaje traducido. Al estar almacenada en [Views/Shared], se encuentra sin importar qué controlador la solicite.

11.18. Los diccionarios

Los diccionarios son los de la versión [NestJS], sin cambios: los lee el servicio [Translator] (vea el Ejemplo 22).

11.18.1. i18n/fr.json

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

11.18.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"
  }
}

El diccionario en inglés tiene exactamente las mismas claves.

11.19. Archivos estáticos

La carpeta [wwwroot] la sirve [UseStaticFiles] (vea el Ejemplo 15). La carpeta [wwwroot/lib/bootstrap] contiene [Bootstrap] (su hoja de estilo [css/bootstrap.min.css] y su licencia), que no se muestran.

11.19.1. wwwroot/css/styles.css

/* =========================================================================
   wwwroot/css/styles.css - algunos ajustes sobre Bootstrap
   (tomados de src/styles.css del cliente Angular, a través del proyecto NestJS).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

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

/* -------------------------------------------------------------------------
   .error-zone: los mensajes de error, al final de la página, sobre un fondo rosa claro
   (véase Views/Shared/_Errors.cshtml).
   position: sticky + bottom: si la página es más alta que la ventana (una
   agenda de 12 horarios, por ejemplo), la zona se queda pegada al final de la
   ventana en lugar de desaparecer bajo el borde inferior - sin cubrir nunca
   el contenido cuando la página es corta.
   z-index: por encima del fondo gris del diálogo de reserva (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* las dos grandes opciones de la página "My area" del paciente */
.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);
}

/* la imagen del CAPTCHA (SVG de 150 x 50 píxeles) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • líneas 10–12: una franja reservable cambia de color al pasar el cursor;
  • líneas 23–33: el área de error, sobre un fondo rosa claro. [position: sticky] y [bottom: 1rem]: si la página es más alta que la ventana, el área permanece en la parte inferior de la ventana en lugar de desaparecer de la pantalla; [z-index] la coloca por encima del fondo gris de la ventana de reserva;
  • líneas 36–43: las dos opciones “My area” responden al paso del mouse;
  • líneas 46–50: el marco de la imagen del CAPTCHA.

11.19.2. wwwroot/js/app.js

// =========================================================================
// wwwroot/js/app.js - el ÚNICO JavaScript de la aplicación.
// -------------------------------------------------------------------------
// Toda la aplicación funciona sin JavaScript. Este script agrega una
// comodidad: antes de enviar un formulario que lleva el atributo
// data-confirmation="...", un diálogo modal pregunta "Are you sure?"
// (el diálogo en sí está en la página: Views/Shared/_Confirmation.cshtml).
// Si JavaScript está desactivado, el formulario simplemente se envía sin
// confirmación - nada se rompe (principio de "progressive enhancement").
//
// ¿Por qué no window.confirm()? Su cuadro no se puede estilizar, y sus
// botones quedan en el idioma del navegador, no en el de la página.
// =========================================================================

(() => {
  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; // el formulario que se enviará si el usuario confirma
  let previousFocus = null; // el elemento al que se devuelve el foco al cerrar

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (y no innerHTML): el mensaje se muestra como TEXTO,
    // nunca se interpreta como HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // el foco va a "No": una pulsación distraída de Enter no elimina nada
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. interceptamos el envío de los formularios que requieren confirmación
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. los botones del diálogo (Yes / No / cruz de cierre)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() envía el formulario SIN volver a disparar el
      // evento 'submit': no hay nueva solicitud de confirmación
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // clic en el fondo gris, fuera del diálogo
    }
  });

  // 3. teclado: Escape cierra el diálogo; Tab permanece DENTRO del diálogo
  //    (de lo contrario el foco pasaría a la página atenuada, detrás)
  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();
      }
    }
  });
})();

El script de la ventana de confirmación del ejemplo 21, mejorado con el manejo del teclado. Sigue el mismo principio de mejora progresiva: sin [JavaScript], los formularios se envían sin confirmación y la aplicación sigue funcionando.

  • Líneas 16–19: una página sin ventana de confirmación no tiene nada que hacer;
  • línea 24: el elemento que tenía el foco (el que recibe las pulsaciones del teclado) antes de que se abriera la ventana: el foco se le devuelve cuando la ventana se cierra;
  • Líneas 26–35: el foco se coloca en “No, go back”; presionar Enter por accidente no elimina nada;
  • líneas 37–43: la ventana se oculta y se restablece el foco;
  • líneas 46–51: se intercepta el envío de los formularios que tienen el atributo [data-confirmation], como en el ejemplo 21;
  • Líneas 54–67: “Yes”, “No”, el botón de cierre y el clic fuera de la ventana. [closest('[data-action]')] encuentra el elemento que contiene el atributo, incluso si se hizo clic en un elemento interno. El operador [?.] devuelve [undefined] en lugar de fallar cuando no se encuentra ningún elemento;
  • líneas 71–86: la tecla Esc cierra la ventana; la tecla Tab (y Shift+Tab) hace circular el foco entre los botones de la ventana, en lugar de dejar que pase a la página atenuada que está detrás.