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

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:

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

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:


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:

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):

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:

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:

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

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:

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

11.2.4. Gestión de médicos y clientes
El administrador tiene dos menús adicionales, “Médicos” y “Pacientes”:


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

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

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

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:


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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
Cada carpeta contiene un archivo llamado [README.md] que enumera sus archivos. La consola al iniciar:
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

- [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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | |
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
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).
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 [__]:
El archivo [README.md] de la aplicación detalla estas opciones.
11.6.3. appsettings.Development.json
- 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
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
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
- 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
- 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
- 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
- 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
- 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é
- 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
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
- 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
- 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
- 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
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
- 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
- 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
- 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
- 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
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
- 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
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.
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
- 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
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
- 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
- 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
- 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
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | |
- 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
- 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
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | |
- 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
- 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
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | |
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
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
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | |
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
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | |
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
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
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
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
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | |
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
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
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 | |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 | |
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
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
- 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
- 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
- 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
- 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
- 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
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | |
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
- 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
El mismo controlador, para los clientes: otra ruta, otras claves de traducción, otros métodos de [ApplicationModel].
11.16.6. Controllers/RegistrationController.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | |
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
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
- 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
- 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
- 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
- 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
- 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
- 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
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
- 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
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
- 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
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | |
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
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
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
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
- 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
- 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
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
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
- 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
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.