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 en intervalos de 20 minutos, por ejemplo); una cita consta de un día, una franja horaria y un cliente (un paciente). Utiliza las capas de base de datos y de negocio del servidor [NestJS] de los cursos «Un ejemplo cliente/servidor Flutter / NestJS» y «Un ejemplo cliente/servidor Angular / NestJS», y muestra las mismas páginas que el cliente [Angular]; pero en lugar de servir JSON a un cliente [JavaScript] o [Flutter], genera sus propias páginas HTML.
Tres roles de usuario comparten la aplicación:
Rol | Quién | Qué puede hacer |
ADMIN | El administrador ([admin]) | ver agendas, reservar y cancelar citas para cualquier paciente; administrar (listar, agregar, editar, eliminar) médicos y clientes |
DOCTOR | Médicos | Ver agendas, reservar y cancelar citas para cualquier paciente |
USER | Clientes (pacientes) | ver agendas sin ver los nombres de otros pacientes; reservar una cita para sí mismos; cancelar su cita; administrar su cuenta; crear una cuenta |
Reglas de gestión principales:
- 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 futura a la vez;
- dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido, y un nombre de usuario 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: Log in y Create a patient account. Ambos requieren ingresar los caracteres que se muestran en la imagen. Los botones FR / EN cambian el idioma:

Un error (en este caso, un CAPTCHA mal escrito) se muestra al final de la página sobre un fondo rosa claro:

11.2.2. El calendario, visto por el administrador y los médicos
Una vez que inicia 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 Book) u ocupada (nombre del paciente, botón Cancel). Al hacer clic en Book se abre una ventana que solicita los datos del paciente:

Al hacer clic en “Cancel” 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 My area: su próxima cita, que puede cancelar, y enlaces a la administración de su cuenta y al calendario:

En el calendario, ve su propia cita, pero no los nombres de otros pacientes (Booked). Como ya tiene una cita futura, no puede programar otra:

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

Administración de la cuenta: editar sus datos, cambiar su contraseña o eliminar su 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, “Doctors” y “Patients”:


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

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

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

11.2.5. Creación de una cuenta de paciente
Desde la página de inicio de sesión, el botón "Create a patient account" solo abre el formulario si el CAPTCHA se ingresó correctamente:


11.3. Instalación y ejecución
La carpeta de la aplicación:
| rdvmedecins-nestjs-html/
├── database/
│ ├── README.md
│ └── dbrdvmedecins2.sql
├── i18n/
│ ├── en.json
│ └── fr.json
├── public/
│ ├── css/
│ │ └── styles.css
│ └── js/
│ └── app.js
├── src/
│ ├── auth/
│ │ ├── README.md
│ │ ├── attempt-limiter.service.ts
│ │ ├── auth.constants.ts
│ │ ├── auth.controller.ts
│ │ ├── auth.module.ts
│ │ ├── auth.service.ts
│ │ ├── captcha.service.ts
│ │ ├── jwt-auth.guard.ts
│ │ ├── jwt.strategy.ts
│ │ ├── registration-pass.service.ts
│ │ ├── roles.decorator.ts
│ │ └── roles.guard.ts
│ ├── business/
│ │ ├── README.md
│ │ ├── business.exception.ts
│ │ ├── business.interface.ts
│ │ ├── business.service.ts
│ │ └── dates.ts
│ ├── config/
│ │ ├── README.md
│ │ ├── database.config.ts
│ │ └── paths.ts
│ ├── domain/
│ │ ├── README.md
│ │ ├── doctor-day-schedule.ts
│ │ └── doctor-day-slot.ts
│ ├── entities/
│ │ ├── README.md
│ │ ├── abstract.entity.ts
│ │ ├── appointment.entity.ts
│ │ ├── client.entity.ts
│ │ ├── doctor.entity.ts
│ │ ├── person.entity.ts
│ │ ├── slot.entity.ts
│ │ └── user.entity.ts
│ ├── repositories/
│ │ ├── README.md
│ │ ├── appointment.repository.ts
│ │ ├── client.repository.ts
│ │ ├── doctor.repository.ts
│ │ ├── slot.repository.ts
│ │ └── user.repository.ts
│ ├── web/
│ │ ├── controllers/
│ │ │ ├── clients.controller.ts
│ │ │ ├── doctors.controller.ts
│ │ │ ├── language.controller.ts
│ │ │ ├── patient-area.controller.ts
│ │ │ ├── persons.controller.ts
│ │ │ ├── registration.controller.ts
│ │ │ └── schedule.controller.ts
│ │ ├── helpers/
│ │ │ ├── dates.helper.ts
│ │ │ ├── form.helper.ts
│ │ │ └── patient.helper.ts
│ │ ├── models/
│ │ │ └── person-form.dto.ts
│ │ ├── views/
│ │ │ └── handlebars-helpers.ts
│ │ ├── README.md
│ │ ├── application-model.service.ts
│ │ ├── html-exception.filter.ts
│ │ ├── i18n.ts
│ │ ├── view-context.ts
│ │ └── view-user.interceptor.ts
│ ├── README.md
│ ├── app.module.ts
│ └── main.ts
├── views/
│ ├── account/
│ │ └── registration.hbs
│ ├── partials/
│ │ ├── booking.hbs
│ │ ├── captcha.hbs
│ │ ├── confirmation.hbs
│ │ ├── errors.hbs
│ │ ├── flash.hbs
│ │ ├── navbar.hbs
│ │ └── personFields.hbs
│ ├── patient/
│ │ ├── account.hbs
│ │ └── area.hbs
│ ├── persons/
│ │ ├── form.hbs
│ │ └── list.hbs
│ ├── README.md
│ ├── error.hbs
│ ├── layout.hbs
│ ├── login.hbs
│ └── schedule.hbs
├── .env.example
├── README.md
├── nest-cli.json
├── package-lock.json
├── package.json
└── tsconfig.json
|
Los archivos [README.md] describen el propósito de cada carpeta; no se reproducen aquí. Para instalar y ejecutar la aplicación:
- cree la base de datos [dbrdvmedecins2] ejecutando el script [database/dbrdvmedecins2.sql] (véanse los apéndices);
- en una ventana de consola abierta en la carpeta de la aplicación, instale las dependencias: [npm install];
- cambie el nombre del archivo [.env.example] a [.env] y actualice en él los parámetros de conexión para que coincidan con los de [MySQL];
- ejecute la aplicación: [npm run start:dev]y luego abra [http://localhost:8081].
Las contraseñas de las cuentas de demostración son sus nombres de usuario: [admin] (ADMIN), [pelissier], [tatou], [dupont] (DOCTOR), [martin], [durand], [bistrou], [german] (USER). Al iniciar:
| [Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [NestFactory] Starting Nest application...
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized +84ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] PassportModule dependencies initialized +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] JwtModule dependencies initialized +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmCoreModule dependencies initialized +58ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] AuthModule dependencies initialized +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] AppModule dependencies initialized +3ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] ScheduleController {/schedule}: +15ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/schedule, GET} route +3ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/schedule/book, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/schedule/cancel, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] DoctorsController {/doctors}: +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/add, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/add, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/:id/edit, GET} route +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/:id/edit, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/:id/delete, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] ClientsController {/clients}: +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients, GET} route +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/add, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/add, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/:id/edit, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/:id/edit, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/:id/delete, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] LanguageController {/language}: +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LO
|
(se han eliminado las solicitudes SQL mostradas por [TypeORM] )
11.4. Arquitectura de la aplicación

- [src/main.ts] configura la aplicación: motor de vistas, archivos estáticos, cookies, filtro de excepciones;
- [src/auth]: autenticación, tokens (JWT), roles, CAPTCHA y límite de intentos;
- [src/web]: la capa web. Sus controladores ([src/web/controllers]) pasan todos por un único servicio, [ApplicationModelService], que almacena en memoria las listas de médicos y clientes y reenvía las demás solicitudes a la capa de negocio;
- [src/business]: las reglas de negocio;
- [src/repositories]: la capa DAO, una clase por tabla;
- [src/entities]: las entidades [TypeORM]; [src/domain]: los objetos del calendario, calculados por la capa de negocio;
- [views]: las vistas [Handlebars]; [i18n]: los diccionarios; [public]: la hoja de estilos y el script de las páginas.
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
El archivo [database/dbrdvmedecins2.sql]:
| -- =========================================================================
-- Base de datos [dbrdvmedecins2] - MySQL 8
--
-- Evolución de [dbrdvmedecins]:
-- 1. las tablas [doctors] y [clients] reciben una columna [user],
-- clave externa a users(id): cada médico y cada cliente es
-- ahora también un usuario que puede iniciar sesión;
-- 2. aparece un tercer rol: DOCTOR (además de ADMIN y USER);
-- 3. el script crea una fila en [users] para cada médico (rol DOCTOR)
-- y para cada cliente (rol USER):
-- - login = apellido en minúsculas
-- - password = apellido en minúsculas, con hash bcrypt (10 rondas)
-- - nombre visible = nombre + apellido
--
-- 4. restricciones de unicidad, todas con NOMBRE (la aplicación NestJS reconoce
-- el nombre de la restricción violada en el mensaje de error de MySQL):
-- - unq_users_login : un login pertenece a una sola cuenta;
-- - unq_doctors_first_name_last_name : dos médicos no pueden tener
-- el mismo nombre y apellido;
-- - unq_clients_first_name_last_name : lo mismo para los clientes.
-- Atención: la collation utf8mb4_unicode_ci compara sin distinguir
-- mayúsculas ni acentos - "Hélène DUPONT" y "helene dupont"
-- se consideran por tanto idénticos.
--
-- La tabla [users] ahora debe crearse ANTES que [doctors] y [clients]
-- (estas la referencian), y eliminarse DESPUÉS de ellas.
-- =========================================================================
-- se parte de una base de datos vacía en cada ejecución del script (práctico en desarrollo)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;
-- orden de eliminación: de las tablas "hijas" a las tablas "padre"
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;
-- -------------------------------------------------------------------------
-- tabla [users]: los usuarios autorizados a iniciar sesión en la aplicación
-- -------------------------------------------------------------------------
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
login VARCHAR(30) NOT NULL, -- login identifier
password VARCHAR(100) NOT NULL, -- HASHED password (bcrypt) - never in clear
name VARCHAR(40) NOT NULL, -- name displayed once logged in
role VARCHAR(10) NOT NULL, -- 'ADMIN', 'DOCTOR' or 'USER'
-- un login puede pertenecer a una sola cuenta
CONSTRAINT unq_users_login UNIQUE (login)
);
-- -------------------------------------------------------------------------
-- tabla [doctors]: los médicos del consultorio
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
id INT AUTO_INCREMENT PRIMARY KEY, -- primary key (technical identifier)
version INT NOT NULL DEFAULT 0, -- row version number (optimistic lock)
title VARCHAR(5) NOT NULL, -- Melle, Mme, Mr
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
-- una cuenta por médico, y un médico por cuenta
CONSTRAINT unq_doctors_user UNIQUE (`user`),
-- dos médicos no pueden tener el mismo nombre y apellido
CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- tabla [clients]: los pacientes de los médicos
-- -------------------------------------------------------------------------
CREATE TABLE clients (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
title VARCHAR(5) NOT NULL,
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
-- una cuenta por cliente, y un cliente por cuenta
CONSTRAINT unq_clients_user UNIQUE (`user`),
-- dos clientes no pueden tener el mismo nombre y apellido
CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- tabla [slots]: los intervalos de tiempo de cada médico
-- -------------------------------------------------------------------------
CREATE TABLE slots (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
doctor_id INT NOT NULL, -- foreign key -> doctors(id)
start_hour INT NOT NULL, -- start hour of the slot
start_minute INT NOT NULL, -- start minute of the slot
end_hour INT NOT NULL, -- end hour of the slot
end_minute INT NOT NULL, -- end minute of the slot
CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);
-- -------------------------------------------------------------------------
-- tabla [appointments]: las citas reservadas por los clientes
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
day DATE NOT NULL, -- day of the appointment
slot_id INT NOT NULL, -- foreign key -> slots(id)
client_id INT NOT NULL, -- foreign key -> clients(id)
CONSTRAINT fk_appointments_slot FOREIGN KEY (slot_id) REFERENCES slots(id),
CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
-- un mismo intervalo, en el mismo día, solo puede reservarse una vez
CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);
-- =========================================================================
-- Datos de demostración
-- =========================================================================
-- los usuarios: contraseñas con hash bcrypt (10 rondas de sal)
-- admin/admin (ADMIN)
-- una cuenta DOCTOR por médico, una cuenta USER por cliente
-- (la cuenta de demostración user/user ya no existe: una cuenta USER es
-- ahora SIEMPRE la cuenta de un cliente, quien puede reservar y administrar la cuenta)
-- (login = contraseña = apellido en minúsculas)
INSERT INTO users (login, password, name, role) VALUES
('admin', '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator', 'ADMIN'),
-- doctors
('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER', 'DOCTOR'),
('tatou', '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU', 'DOCTOR'),
('dupont', '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT', 'DOCTOR'),
-- clients
('martin', '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN', 'USER'),
('durand', '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND', 'USER'),
('bistrou', '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
('german', '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN', 'USER');
-- los médicos: la columna [user] se busca a partir del login,
-- en lugar de suponer los valores de las claves primarias de [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
('Mme', 'PELISSIER', 'Marie', (SELECT id FROM users WHERE login = 'pelissier')),
('Mr', 'TATOU', 'Paul', (SELECT id FROM users WHERE login = 'tatou')),
('Melle','DUPONT', 'Sophie', (SELECT id FROM users WHERE login = 'dupont'));
INSERT INTO clients (title, last_name, first_name, `user`) VALUES
('Mr', 'MARTIN', 'Jean', (SELECT id FROM users WHERE login = 'martin')),
('Mme', 'DURAND', 'Alice', (SELECT id FROM users WHERE login = 'durand')),
('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
('Mr', 'GERMAN', 'Luc', (SELECT id FROM users WHERE login = 'german'));
-- intervalos del médico PELISSIER (doctor_id = 1): de 8:00 a 12:00 en pasos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
(1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
(1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
(1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);
-- intervalos del médico TATOU (doctor_id = 2): de 14:00 a 18:00 en pasos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
(2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
(2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
(2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);
-- una cita ya reservada, para ver de inmediato un intervalo ocupado en la agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
(CURDATE(), 2, 3);
|
Comentemos este script:
- línea 30: como en el ejemplo 28, la intercalación [utf8mb4_unicode_ci] ignora las mayúsculas y los acentos en las comparaciones;
- líneas 34–38: las tablas se eliminan desde las tablas «hijas» hacia las tablas «padre»: una tabla referenciada por una clave externa no puede eliminarse antes que las tablas que la referencian;
- líneas 43–52: cuentas de usuario. [password] contiene el hash bcrypt de la contraseña (véase el ejemplo 25). Línea 51: un nombre de usuario es único;
- Líneas 57–69: médicos. Cada uno tiene una cuenta (columna [user], clave externa hacia [users], línea 64). El nombre [user] es una palabra reservada de [MySQL]: por eso se encierra entre acentos graves. Línea 66: una cuenta pertenece a un solo médico; línea 68: no puede haber dos médicos con el mismo nombre y apellido;
- líneas 74–86: clientes, con el mismo formato;
- líneas 91–100: las franjas horarias de cada médico (horas de inicio y de fin en horas y minutos);
- líneas 105–115: citas: un día, una franja horaria, un cliente. Línea 114: una franja horaria se reserva una sola vez por día;
- líneas 127–137: cuentas de demostración; la contraseña de cada cuenta es su nombre de usuario;
- líneas 141–144: la columna [user] de cada médico se obtiene mediante una subconsulta sobre el nombre de usuario, en lugar de suponer las credenciales generadas;
- líneas 167–168: una cita el mismo día ([CURDATE()]), para mostrar de inmediato una franja horaria reservada.
11.6. Configuración del proyecto
El archivo [package.json]:
| {
"name": "rdvmedecins-nestjs-html",
"version": "1.0.0",
"description": "NestJS web application (HTML pages generated server-side) for booking medical appointments [RdvMedecins] - database [dbrdvmedecins2], roles ADMIN / DOCTOR / USER",
"private": true,
"license": "UNLICENSED",
"scripts": {
"build": "nest build",
"start": "nest start",
"start:dev": "nest start --watch --watchAssets",
"start:debug": "nest start --debug --watch --watchAssets",
"start:prod": "node dist/main"
},
"dependencies": {
"@nestjs/common": "^10.4.0",
"@nestjs/core": "^10.4.0",
"@nestjs/jwt": "^10.2.0",
"@nestjs/passport": "^10.0.3",
"@nestjs/platform-express": "^10.4.0",
"@nestjs/typeorm": "^10.0.2",
"bcryptjs": "^3.0.3",
"bootstrap": "^5.3.3",
"class-transformer": "^0.5.1",
"class-validator": "^0.14.1",
"cookie-parser": "^1.4.7",
"dotenv": "^17.4.2",
"hbs": "^4.2.0",
"mysql2": "^3.11.0",
"passport-jwt": "^4.0.1",
"reflect-metadata": "^0.2.2",
"rxjs": "^7.8.1",
"svg-captcha": "^1.4.0",
"typeorm": "^0.3.20"
},
"devDependencies": {
"@nestjs/cli": "^10.4.5",
"@types/bcryptjs": "^2.4.6",
"@types/cookie-parser": "^1.4.7",
"@types/express": "^4.17.21",
"@types/node": "^20.14.0",
"@types/passport-jwt": "^4.0.1",
"typescript": "^5.5.0"
}
}
|
- líneas 7–13: los comandos [npm run ...]. [start:dev] inicia la aplicación en modo «watch»: el código se recompila y el servidor se reinicia con cada cambio; la opción [--watchAssets] también supervisa los archivos que no son de código;
- Líneas 14–34: las bibliotecas de la aplicación, todas ellas tratadas en los ejemplos. [dotenv] lee el archivo [.env]; [mysql2] es el controlador [MySQL] que utiliza [TypeORM]; [reflect-metadata] y [rxjs] son requeridos por [NestJS];
- Líneas 35–43: herramientas de desarrollo: la herramienta [nest], el compilador de [TypeScript] y las declaraciones de tipos ([@types/...]) para las bibliotecas escritas en [JavaScript].
El archivo [tsconfig.json]:
| {
"compilerOptions": {
"module": "commonjs",
"declaration": false,
"removeComments": true,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"allowSyntheticDefaultImports": true,
"target": "ES2022",
"lib": ["ES2022"],
"sourceMap": true,
"outDir": "./dist",
"baseUrl": "./",
"incremental": true,
"skipLibCheck": true,
"strictNullChecks": true,
"noImplicitAny": false,
"strictBindCallApply": false,
"forceConsistentCasingInFileNames": true,
"noFallthroughCasesInSwitch": false
}
}
|
Este archivo lo genera la herramienta [nest] para un proyecto nuevo. En comparación con los ejemplos: línea 5, los comentarios no se copian en el código compilado; línea 14, solo se recompilan los archivos modificados; línea 17: se acepta una variable sin tipo explícito ni inferible (entonces es de tipo [any]); esto es lo que permite importar el paquete [hbs], que no tiene declaraciones de tipos.
El archivo [nest-cli.json]:
| {
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"deleteOutDir": true
}
}
|
Idéntico al de los ejemplos.
El archivo [.env.example]:
| # -----------------------------------------------------------------------
# Archivo de configuración de ejemplo.
# Copie este archivo a [.env] y luego adapte los valores a su máquina.
# El archivo [.env] nunca debe compartirse ni incluirse en el control de versiones (contraseñas).
# -----------------------------------------------------------------------
# puerto de escucha del servidor NestJS. El servidor JSON ya escucha en 8080:
# elegimos otro puerto para que ambos puedan ejecutarse al mismo tiempo.
PORT=8081
# parámetros de conexión a la base de datos MySQL [dbrdvmedecins2]
# (script: database/dbrdvmedecins2.sql)
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=dbrdvmedecins2
# -----------------------------------------------------------------------
# autenticación (ver src/auth/)
# -----------------------------------------------------------------------
# clave secreta usada para firmar/verificar los tokens JWT - DEBE cambiarse
# en producción (una cadena aleatoria larga, nunca incluida en el control de versiones).
JWT_SECRET=change-me-to-a-long-random-string
# validez de un token JWT, en segundos (7200 s = 2 h). La cookie
# que transporta el token tiene la misma duración.
JWT_EXPIRES_IN_SECONDS=7200
# establézcalo en true en producción (sitio servido por HTTPS): la cookie de autenticación
# nunca se enviará entonces por una conexión sin cifrar.
COOKIE_SECURE=false
# -----------------------------------------------------------------------
# protección contra bots (ver src/auth/attempt-limiter.service.ts)
# -----------------------------------------------------------------------
# inicio de sesión: número de fallos (captcha o contraseña incorrectos) permitidos para
# el mismo login desde la misma dirección IP, antes de que este par quede bloqueado...
LOGIN_MAX_FAILURES=5
# ... durante este tiempo (una dirección IP también se bloquea si acumula
# 5 veces más fallos, sumando todos los logins)
LOGIN_BLOCK_MINUTES=15
# creación de cuentas de cliente: número máximo de cuentas creadas por hora
# desde la misma dirección IP. En un aula, todas las computadoras suelen salir
# por la misma dirección: aumente el valor si es necesario.
REGISTRATION_MAX_PER_HOUR=10
|
- Un archivo llamado [.env] contiene los parámetros de configuración específicos de cada máquina: nunca se comparte (contiene contraseñas). El archivo [.env.example] sirve como plantilla que debe copiarse;
- línea 9: el puerto de la aplicación;
- líneas 13–17: la conexión a la base de datos;
- líneas 24–30: la clave del token, su duración (dos horas) y la opción de cookie [secure] (en producción, el sitio se sirve mediante HTTPS y la cookie nunca debe transmitirse por una conexión sin cifrar);
- líneas 37–44: los umbrales de la protección contra bots.
El archivo [src/config/database.config.ts]:
| // =========================================================================
// config/database.config.ts
// -------------------------------------------------------------------------
// Configuración de la conexión a la base de datos MySQL, utilizada por
// TypeORM. Es el equivalente de la clase [DomainAndPersitenceConfig] del
// proyecto Spring original, que definía un [DataSource] (bloque @Bean).
//
// Aquí no hay clase: NestJS/TypeORM prefiere una función simple que
// devuelve un objeto de configuración, leído de las variables de entorno
// (archivo .env en la raíz del proyecto, cargado automáticamente por NestJS
// mediante el módulo @nestjs/config si está instalado - aquí leemos
// process.env directamente para mantenerlo simple y didáctico).
// =========================================================================
import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { Doctor } from '../entities/doctor.entity';
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
import { User } from '../entities/user.entity';
export function getDatabaseConfig(): TypeOrmModuleOptions {
return {
// 'mysql': usamos el controlador de MySQL, como el proyecto original (MySQL5 -> MySQL8 aquí).
type: 'mysql',
host: process.env.DB_HOST ?? 'localhost',
port: process.env.DB_PORT ? parseInt(process.env.DB_PORT, 10) : 3306,
username: process.env.DB_USERNAME ?? 'root',
password: process.env.DB_PASSWORD ?? '',
database: process.env.DB_DATABASE ?? 'dbrdvmedecins2',
// la lista de entidades (clases @Entity) que TypeORM debe gestionar.
// Es el equivalente del "escaneo" automático de las clases @Entity que hace Spring Boot.
entities: [Doctor, Client, Slot, Appointment, User],
// IMPORTANTE: synchronize=false en todo momento en este curso.
// Si synchronize fuera true, TypeORM modificaría por sí mismo el esquema de la base de datos
// a partir de las entidades: práctico para un prototipo desechable, peligroso en cuanto hay
// datos reales (riesgo de pérdida de datos). Como lo haría un equipo real, preferimos
// mantener el control del esquema mediante el script database/dbrdvmedecins2.sql.
synchronize: false,
// muestra en la consola las consultas SQL generadas por TypeORM: muy útil para
// entender qué hace el ORM por usted, exactamente como los logs de Hibernate
// del proyecto Spring original.
logging: process.env.NODE_ENV !== 'production',
};
}
|
La conexión a la base de datos (véase el ejemplo 28). Línea 46: las solicitudes SQL se muestran, salvo en producción.
El archivo [src/config/paths.ts]:
| // =========================================================================
// config/paths.ts
// -------------------------------------------------------------------------
// Las carpetas NO compiladas del proyecto (vistas Handlebars, archivos estáticos,
// diccionarios de traducción) están en la raíz del proyecto, junto a
// src/ y dist/. Una vez compilado, este mismo archivo se encuentra en
// dist/config/: la raíz del proyecto está por lo tanto dos niveles más arriba.
// =========================================================================
import { join, resolve } from 'path';
export const PROJECT_ROOT = resolve(__dirname, '..', '..');
export const VIEWS_DIR = join(PROJECT_ROOT, 'views'); // plantillas de página (.hbs)
export const PARTIALS_DIR = join(VIEWS_DIR, 'partials'); // piezas de página reutilizables
export const PUBLIC_DIR = join(PROJECT_ROOT, 'public'); // CSS, JS, imágenes
export const I18N_DIR = join(PROJECT_ROOT, 'i18n'); // fr.json, en.json
export const BOOTSTRAP_DIR = join(PROJECT_ROOT, 'node_modules', 'bootstrap', 'dist');
|
- Línea 12: una vez compilado, este archivo se encuentra en [dist/config]: la raíz del proyecto está dos niveles más arriba;
- líneas 14–18: las carpetas sin compilar (vistas, archivos estáticos, diccionarios) y la de [Bootstrap].
11.7. Inicio de la aplicación
El archivo [src/main.ts]:
| // =========================================================================
// main.ts
// -------------------------------------------------------------------------
// Punto de entrada de la aplicación. En comparación con el servidor JSON, el
// arranque también configura todo lo necesario para CONSTRUIR PÁGINAS HTML
// del lado del servidor:
// - un motor de vistas (Handlebars, archivos views/*.hbs);
// - los archivos estáticos (Bootstrap, CSS, un poco de JavaScript);
// - el análisis de cookies (token JWT, idioma, mensajes flash);
// - un filtro que convierte los errores en páginas HTML.
// Ya no hay que permitir CORS: las páginas y los datos provienen ahora del
// MISMO servidor.
// =========================================================================
import 'dotenv/config'; // DEBE seguir siendo la primera importación (ver servidor JSON)
import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import * as cookieParser from 'cookie-parser';
import * as hbs from 'hbs';
import { AppModule } from './app.module';
import { BOOTSTRAP_DIR, PARTIALS_DIR, PUBLIC_DIR, VIEWS_DIR } from './config/paths';
import { registerHelpers } from './web/views/handlebars-helpers';
import { viewContextMiddleware } from './web/view-context';
import { HtmlExceptionFilter } from './web/html-exception.filter';
import { ViewUserInterceptor } from './web/view-user.interceptor';
async function bootstrap() {
// NestExpressApplication: indicamos que la plataforma subyacente es
// Express, para acceder a sus propios métodos (setViewEngine,
// useStaticAssets...) - no existen para la plataforma Fastify.
const app = await NestFactory.create<NestExpressApplication>(AppModule);
// 1. archivos estáticos: /css/..., /js/... (carpeta public/) y
// /bootstrap/css/bootstrap.min.css (directamente desde node_modules:
// no hace falta copiar Bootstrap al proyecto)
app.useStaticAssets(PUBLIC_DIR);
app.useStaticAssets(BOOTSTRAP_DIR, { prefix: '/bootstrap/' });
// 2. el motor de vistas. El archivo views/layout.hbs lo usa hbs
// AUTOMÁTICAMENTE como plantilla común de todas las páginas:
// cada vista se inserta en el lugar de {{{body}}} de esta plantilla.
app.setBaseViewsDir(VIEWS_DIR);
app.setViewEngine('hbs');
registerHelpers(hbs);
// los "partials" (views/partials/*.hbs): piezas de página reutilizables,
// insertadas con {{> name}}. registerPartials lee la carpeta
// de forma asíncrona: esperamos a que termine antes de aceptar solicitudes.
await new Promise<void>((done) => hbs.registerPartials(PARTIALS_DIR, () => done()));
// 3. cookie-parser llena req.cookies; luego nuestro middleware prepara el
// idioma y el mensaje flash de cada página (ver web/view-context.ts)
app.use(cookieParser());
app.use(viewContextMiddleware);
// 4. el usuario conectado, visible para todas las vistas; y los errores
// convertidos en páginas HTML (o en una redirección a /login)
app.useGlobalInterceptors(new ViewUserInterceptor());
app.useGlobalFilters(new HtmlExceptionFilter());
const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 8081;
await app.listen(port);
// eslint-disable-next-line no-console
console.log(`[RdvMedecins] web application started on http://localhost:${port}`);
}
bootstrap();
|
Analicemos este código:
- Línea 15: [dotenv/config] lee el archivo [.env] y coloca sus valores en [process.env]. Esta importación debe ser la primera: los demás módulos leen [process.env] en cuanto se cargan ([JWT_SECRET], por ejemplo);
- líneas 37–38: archivos estáticos (véase el ejemplo 15);
- líneas 43–49: el motor de vistas, los helpers y las vistas parciales (véanse los ejemplos 15 y 16);
- líneas 53–54: lectura de cookies, seguida del middleware que prepara el idioma y el mensaje flash para cada página (véase [web/view-context.ts]);
- líneas 58–59: un interceptor global expone el usuario conectado a las vistas, y un filtro global convierte las excepciones en páginas HTML (véase el capítulo 7);
- línea 61: el puerto, leído de [.env] (8081 por defecto).
El archivo [src/app.module.ts]:
| // =========================================================================
// app.module.ts
// -------------------------------------------------------------------------
// El módulo raíz. Las mismas capas que el servidor JSON (DAO, negocio,
// caché/fachada); solo cambian los controladores: ahora construyen
// páginas HTML en lugar de respuestas JSON.
// =========================================================================
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { getDatabaseConfig } from './config/database.config';
import { Doctor } from './entities/doctor.entity';
import { Client } from './entities/client.entity';
import { Slot } from './entities/slot.entity';
import { Appointment } from './entities/appointment.entity';
import { DoctorRepository } from './repositories/doctor.repository';
import { ClientRepository } from './repositories/client.repository';
import { SlotRepository } from './repositories/slot.repository';
import { AppointmentRepository } from './repositories/appointment.repository';
import { BUSINESS_TOKEN } from './business/business.interface';
import { BusinessService } from './business/business.service';
import { ApplicationModelService } from './web/application-model.service';
import { ScheduleController } from './web/controllers/schedule.controller';
import { DoctorsController } from './web/controllers/doctors.controller';
import { ClientsController } from './web/controllers/clients.controller';
import { LanguageController } from './web/controllers/language.controller';
import { RegistrationController } from './web/controllers/registration.controller';
import { PatientAreaController } from './web/controllers/patient-area.controller';
import { AuthModule } from './auth/auth.module';
@Module({
imports: [
TypeOrmModule.forRoot(getDatabaseConfig()),
TypeOrmModule.forFeature([Doctor, Client, Slot, Appointment]),
// AuthModule proporciona /login y /logout; exporta UserRepository
// (inyectado en BusinessService), AuthService, CaptchaService y
// AttemptLimiterService (inyectados en los controladores de src/web/)
AuthModule,
],
controllers: [
ScheduleController,
DoctorsController,
ClientsController,
LanguageController,
RegistrationController, // "Create a patient account" (public)
PatientAreaController, // "My area", "Manage my account" (USER)
],
providers: [
DoctorRepository,
ClientRepository,
SlotRepository,
AppointmentRepository,
{ provide: BUSINESS_TOKEN, useClass: BusinessService },
ApplicationModelService,
],
})
export class AppModule {}
|
- línea 38: la conexión a la base de datos;
- línea 39: los repositorios de las cuatro entidades administradas por este módulo (el de [User] lo declara [AuthModule]);
- línea 43: el módulo de autenticación, con su propio controlador y sus propios servicios;
- líneas 45–52: los controladores de la capa web;
- Líneas 53–60: los servicios: la capa DAO (los cuatro repositorios), la capa de negocio y la caché de la capa web. Línea 58: la capa de negocio se registra bajo un token ([BUSINESS_TOKEN]) en lugar del nombre de su clase: quienes la utilizan dependen de la interfaz [IBusiness], no de la clase [BusinessService]. La implementación podría reemplazarse (por una versión de prueba, por ejemplo) modificando solo esta línea.
11.8. Las entidades
Las entidades de [TypeORM] se asignan a las tablas de la base de datos y a clases de [TypeScript] (véase el ejemplo 28). Sus comentarios suelen hacer referencia al proyecto [Java] / [Spring] , del que la aplicación es una descendiente lejana, y al «servidor JSON»: el servidor [NestJS] de los cursos cliente/servidor, cuyo caso de estudio incorpora las capas DAO y de negocio.
11.8.1. src/entities/abstract.entity.ts
| // =========================================================================
// entities/abstract.entity.ts
// -------------------------------------------------------------------------
// Equivalente de la clase [AbstractEntity] del proyecto Spring original,
// que estaba anotada con @MappedSuperclass. Agrupa los dos campos
// comunes a todas nuestras entidades persistentes: el identificador [id] y el
// número de versión [version] usado para gestionar los accesos concurrentes.
//
// En JPA, @MappedSuperclass significa "esta clase no es una tabla,
// pero sus campos deben agregarse a las tablas de las clases hijas".
// TypeORM ofrece exactamente el mismo mecanismo: basta con que una clase
// abstracta (no decorada con @Entity) sea heredada por una clase que,
// a su vez, lleve la anotación @Entity. TypeORM agrega entonces automáticamente
// las columnas heredadas a la tabla de la clase hija.
// =========================================================================
import { PrimaryGeneratedColumn, VersionColumn } from 'typeorm';
export abstract class AbstractEntity {
// equivalente de:
// @Id
// @GeneratedValue(strategy = GenerationType.AUTO)
// protected Long id;
//
// @PrimaryGeneratedColumn() declara una clave primaria autoincrementada por el SGBD,
// exactamente como GenerationType.AUTO se la delegaba al SGBD.
@PrimaryGeneratedColumn()
id: number;
// equivalente de:
// @Version
// protected Long version;
//
// @VersionColumn() es EL mecanismo nativo de TypeORM para el bloqueo optimista:
// TypeORM incrementa automáticamente esta columna en cada UPDATE y lanza un error
// al intentar guardar una entidad cuya versión ya no coincide con la de la
// base de datos (otra persona la modificó entretanto). Corresponde directamente al
// papel de @Version en JPA/Hibernate.
@VersionColumn()
version: number;
}
|
- línea 19: una clase abstracta sin el decorador [@Entity]: no corresponde a ninguna tabla, pero sus columnas se agregan a las de las clases hijas;
- líneas 27–28: la clave primaria, generada por la base de datos;
- líneas 39–40: la versión de la fila, incrementada por [TypeORM] con cada modificación (bloqueo optimista; véase el ejemplo 28).
11.8.2. src/entities/person.entity.ts
| // =========================================================================
// entities/person.entity.ts
// -------------------------------------------------------------------------
// Clase padre (no persistida por sí misma) de las entidades [Doctor] y
// [Client]: un título, un apellido, un nombre - y, novedad en la base de datos
// [dbrdvmedecins2], la cuenta de usuario asociada (columna [user]).
//
// Una relación declarada en una clase abstracta se hereda a las
// clases hijas exactamente como las columnas: TypeORM agrega por lo tanto la
// relación [user] a la tabla [doctors] Y a la tabla [clients].
// =========================================================================
import { Column, JoinColumn, OneToOne, RelationId } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { User } from './user.entity';
export abstract class Person extends AbstractEntity {
@Column({ length: 5 })
title: string; // Melle, Mme, Mr
@Column({ name: 'last_name', length: 20 })
lastName: string;
@Column({ name: 'first_name', length: 20 })
firstName: string;
// @OneToOne: un médico (o un cliente) tiene UNA cuenta de usuario, y una
// cuenta de usuario pertenece como máximo a UNA persona (la columna [user]
// está declarada UNIQUE en el script SQL).
// @JoinColumn({ name: 'user' }): es ESTA tabla (doctors / clients)
// la que lleva la clave externa, en la columna llamada [user].
// Como en las demás relaciones, [user] solo se carga a petición
// (opción `relations`) - ver doctor.repository.ts.
@OneToOne(() => User)
@JoinColumn({ name: 'user' })
user: User;
// el valor en bruto de la clave externa, sin cargar el User completo
// (misma técnica que Slot.doctorId, ver slot.entity.ts)
@RelationId((person: Person) => person.user)
userId: number;
}
|
- línea 17: la clase padre de [Doctor] y [Client], que a su vez es hija de [AbstractEntity];
- Líneas 18–25: tratamiento, apellido, nombre;
- líneas 34–36: una relación uno a uno con la cuenta de usuario. [@JoinColumn] indica que esta tabla contiene la clave externa, en la columna [user]. La relación se carga solo si se solicita (opción [relations] en las consultas);
- Líneas 40–41: [@RelationId] expone el valor de la clave externa (el identificador de la cuenta) sin cargar la cuenta en sí.
11.8.3. src/entities/doctor.entity.ts
| // =========================================================================
// entities/doctor.entity.ts
// -------------------------------------------------------------------------
// Equivalente de la entidad JPA [Medecin] (un médico):
//
// @Entity
// @Table(name = "medecins")
// public class Medecin extends Personne { ... }
// =========================================================================
import { Entity, OneToMany, Unique } from 'typeorm';
import { Person } from './person.entity';
import { Slot } from './slot.entity';
// @Entity({ name: 'doctors' }): declara la clase como entidad de TypeORM,
// persistida en la tabla [doctors]. Es el equivalente exacto de
// @Entity + @Table(name = "doctors") en JPA.
@Entity({ name: 'doctors' })
// recordatorio de la restricción SQL del script database/dbrdvmedecins2.sql: dos
// médicos no pueden tener el mismo nombre y apellido. Igual que unq1_appointments
// (ver appointment.entity.ts), es documentación: con synchronize=false, es el
// script SQL el que realmente crea la restricción - con ESTE nombre, que la
// capa de negocio reconoce en los mensajes de error de MySQL (ver business.service.ts).
@Unique('unq_doctors_first_name_last_name', ['firstName', 'lastName'])
export class Doctor extends Person {
// relación inversa (opcional, práctica para navegar de un médico a sus horarios).
// El proyecto original no la definía en el lado de [Medecin] (solo en el lado de [Creneau]),
// pero TypeORM hace que agregarla sea casi gratuito y es útil didácticamente:
// muestra la relación "1 médico -> varios horarios" en ambos sentidos.
@OneToMany(() => Slot, (slot) => slot.doctor)
slots: Slot[];
}
|
- línea 18: la clase corresponde a la tabla [doctors];
- línea 24: la restricción de unicidad, incluida aquí con fines de documentación; en realidad la crea el script SQL ([synchronize: false]);
- Líneas 30–31: la relación uno a muchos con las franjas horarias del médico, la inversa de la relación [@ManyToOne] de [Slot].
11.8.4. src/entities/client.entity.ts
| // =========================================================================
// entities/client.entity.ts
// -------------------------------------------------------------------------
// Equivalente de la entidad JPA [Client]:
//
// @Entity
// @Table(name = "clients")
// public class Client extends Personne { ... }
//
// Atención: [Client] aquí significa un PACIENTE del consultorio médico, no un
// cliente HTTP. Es el vocabulario del dominio de negocio original, conservado
// tal cual para ser fiel al documento fuente.
// =========================================================================
import { Entity, Unique } from 'typeorm';
import { Person } from './person.entity';
@Entity({ name: 'clients' })
// dos clientes no pueden tener el mismo nombre y apellido
// (ver la misma restricción en Doctor, doctor.entity.ts)
@Unique('unq_clients_first_name_last_name', ['firstName', 'lastName'])
export class Client extends Person {}
|
Un cliente (un paciente): una [Person] de la tabla [clients], sin campos adicionales.
11.8.5. src/entities/slot.entity.ts
| // =========================================================================
// entities/slot.entity.ts
// -------------------------------------------------------------------------
// Equivalente de la entidad JPA [Creneau] (un horario):
//
// @Entity
// @Table(name = "creneaux")
// public class Creneau extends AbstractEntity {
// private int hdebut, mdebut, hfin, mfin;
// @ManyToOne(fetch = FetchType.LAZY)
// @JoinColumn(name = "id_medecin")
// private Medecin medecin;
// @Column(name = "id_medecin", insertable = false, updatable = false)
// private long idMedecin;
// }
// =========================================================================
import { Column, Entity, JoinColumn, ManyToOne, RelationId } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { Doctor } from './doctor.entity';
@Entity({ name: 'slots' })
export class Slot extends AbstractEntity {
@Column({ name: 'start_hour' }) startHour: number; // hora de inicio del horario
@Column({ name: 'start_minute' }) startMinute: number; // minuto de inicio del horario
@Column({ name: 'end_hour' }) endHour: number; // hora de fin del horario
@Column({ name: 'end_minute' }) endMinute: number; // minuto de fin del horario
// equivalente de:
// @ManyToOne(fetch = FetchType.LAZY)
// @JoinColumn(name = "id_medecin")
// private Medecin medecin;
//
// @ManyToOne: varios horarios para el mismo médico.
// Por defecto, TypeORM NO carga la relación [doctor] al leer un horario
// (comportamiento "lazy" por defecto): hay que pedirla explícitamente, mediante la opción
// `relations: ['doctor']` de una consulta - exactamente como FetchType.LAZY exigía
// en JPA un `left join fetch` explícito en la consulta JPQL para traer al médico.
@ManyToOne(() => Doctor, (doctor) => doctor.slots)
@JoinColumn({ name: 'doctor_id' })
doctor: Doctor;
// equivalente de:
// @Column(name = "id_medecin", insertable = false, updatable = false)
// private long idMedecin;
//
// @RelationId: es el equivalente EXACTO e idiomático en TypeORM del campo de solo lectura
// "idMedecin" del proyecto original. Expone directamente el valor
// de la clave externa, SIN tener que cargar la entidad [Doctor] completa.
// Muy útil para comparar identificadores sin cargar las entidades relacionadas.
@RelationId((slot: Slot) => slot.doctor)
doctorId: number;
}
|
- líneas 24–27: las horas y los minutos de inicio y de fin;
- líneas 39–41: la relación muchos a uno con el médico: varias franjas horarias para un mismo médico. La clave externa es la columna [doctor_id];
- líneas 51–52: el identificador del médico, sin cargar al médico.
11.8.6. src/entities/appointment.entity.ts
| // =========================================================================
// entities/appointment.entity.ts
// -------------------------------------------------------------------------
// Equivalente de la entidad JPA [Rv] (una cita):
//
// @Entity
// @Table(name = "rv")
// public class Rv extends AbstractEntity {
// @Temporal(TemporalType.DATE) private Date jour;
// @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "id_client") private Client client;
// @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "id_creneau") private Creneau creneau;
// @Column(name = "id_client", insertable = false, updatable = false) private long idClient;
// @Column(name = "id_creneau", insertable = false, updatable = false) private long idCreneau;
// }
//
// La restricción de unicidad SQL sobre (day, slot_id) - que impide dos
// citas en el mismo horario el mismo día - se define directamente
// en el script database/dbrdvmedecins2.sql (CONSTRAINT unq1_appointments UNIQUE).
// =========================================================================
import { Column, Entity, JoinColumn, ManyToOne, RelationId, Unique } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { Client } from './client.entity';
import { Slot } from './slot.entity';
@Entity({ name: 'appointments' })
// recuerda, del lado de TypeORM, la restricción SQL del script de la BD. Atención: aquí se hace referencia
// al nombre de la RELACIÓN ('slot'), no al campo @RelationId ('slotId') - este último es
// una columna "virtual" (calculada), que TypeORM no acepta en una restricción @Unique.
// El propio TypeORM traduce 'slot' a su columna de clave externa real (slot_id).
@Unique('unq1_appointments', ['day', 'slot'])
export class Appointment extends AbstractEntity {
// equivalente de: @Temporal(TemporalType.DATE) private Date jour;
// tipo 'date' (y no 'datetime'): solo se conserva el día, no la hora,
// exactamente como lo especificaba TemporalType.DATE del lado de JPA.
@Column({ type: 'date' })
day: string; // formato "yyyy-MM-dd", p. ej. "2026-09-13"
@ManyToOne(() => Client)
@JoinColumn({ name: 'client_id' })
client: Client;
@ManyToOne(() => Slot)
@JoinColumn({ name: 'slot_id' })
slot: Slot;
// equivalentes de los campos de solo lectura idClient / idCreneau del proyecto original
// (ver la explicación detallada en slot.entity.ts sobre @RelationId)
@RelationId((appointment: Appointment) => appointment.client)
clientId: number;
@RelationId((appointment: Appointment) => appointment.slot)
slotId: number;
}
|
- línea 31: una franja horaria de cita se reserva una sola vez por día;
- líneas 36–37: una columna de tipo [DATE], tratada como una cadena [yyyy-mm-dd]: sin problemas de zona horaria, y dos fechas se comparan como cadenas;
- líneas 39–45: el cliente y la franja horaria de la cita;
- líneas 49–53: sus identificadores.
11.8.7. src/entities/user.entity.ts
| // =========================================================================
// entities/user.entity.ts
// -------------------------------------------------------------------------
// Un usuario autorizado para iniciar sesión en la aplicación (tabla [users]).
//
// Novedad en la base de datos [dbrdvmedecins2]: cada médico y cada cliente
// tiene ahora SU PROPIA cuenta de usuario (columna [user] de las
// tablas [doctors] y [clients], ver person.entity.ts). De ahí un tercer rol:
// - ADMIN : el administrador - citas + gestión de médicos y clientes;
// - DOCTOR : un médico - reserva y cancela citas;
// - USER : un cliente (paciente) - reserva para sí mismo, gestiona su cuenta.
//
// Los roles siguen siendo mutuamente excluyentes: una simple columna [role]
// sigue bastando (sin tabla [roles] / [users_roles] como en el
// proyecto Spring original).
// =========================================================================
import { Column, Entity, Unique } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';
@Entity({ name: 'users' })
// un login pertenece a una sola cuenta (restricción SQL unq_users_login)
@Unique('unq_users_login', ['login'])
export class User extends AbstractEntity {
@Column({ length: 30 })
login: string;
// la contraseña CIFRADA con hash (bcrypt) - nunca en claro
@Column({ length: 100 })
password: string;
// el nombre que se muestra una vez iniciada la sesión - para un médico o un cliente:
// "firstName LASTNAME" (p. ej. "Marie PELISSIER")
@Column({ length: 40 })
name: string;
@Column({ type: 'varchar', length: 10 })
role: Role;
}
|
- línea 21: un tipo unión de cadenas: una variable de tipo [Role] solo puede ser una de estas tres cadenas;
- líneas 31–32: el hash de la contraseña;
- líneas 36–37: el nombre que se muestra en la barra de navegación («Marie PELISSIER»);
- líneas 39–40: el rol. Se especifica el tipo de la columna: [TypeORM] no puede inferir un tipo SQL a partir de un tipo unión.
11.9. 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.
11.9.1. src/domain/doctor-day-slot.ts
| // =========================================================================
// domain/doctor-day-slot.ts
// -------------------------------------------------------------------------
// Equivalente de la clase [CreneauMedecinJour] del proyecto Spring original:
// una entidad "de negocio" (no persistida en la base de datos) que vincula un
// horario con la cita que posiblemente esté reservada en ese horario.
//
// public class CreneauMedecinJour implements Serializable {
// private Creneau creneau;
// private Rv rv; // null si el horario está libre
// }
//
// Este tipo de clase no tiene tabla en la base de datos: solo existe durante
// el cálculo de la agenda de un médico, que la capa web convierte luego
// en filas de la tabla HTML de la agenda (ver schedule.controller.ts).
// =========================================================================
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
export class DoctorDaySlot {
constructor(
public slot: Slot,
public appointment: Appointment | null, // null si el horario está libre ese día
) {}
}
|
líneas 22–25: una franja horaria y la cita programada para esa franja en ese día ([null] si la franja está disponible). La sintaxis [public slot: Slot] en los parámetros de un constructor declara e inicializa el campo en un solo paso.
11.9.2. src/domain/doctor-day-schedule.ts
| // =========================================================================
// domain/doctor-day-schedule.ts
// -------------------------------------------------------------------------
// Equivalente de la clase [AgendaMedecinJour] del proyecto Spring original:
// la agenda completa de un médico para un día dado, es decir, la lista de los
// horarios del médico, cada uno libre u ocupado por una cita.
//
// public class AgendaMedecinJour implements Serializable {
// private Medecin medecin;
// private Date jour;
// private CreneauMedecinJour[] creneauxMedecinJour;
// }
// =========================================================================
import { Doctor } from '../entities/doctor.entity';
import { DoctorDaySlot } from './doctor-day-slot';
export class DoctorDaySchedule {
constructor(
public doctor: Doctor,
public day: string, // formato "yyyy-MM-dd"
public doctorDaySlots: DoctorDaySlot[],
) {}
}
|
La agenda: un médico, un día y la lista de sus franjas horarias, ya sean disponibles o reservadas.
11.10. La capa DAO
Una clase por tabla. Todas siguen el modelo del ejemplo 28: un [Repository] [TypeORM] inyectado, un método [repo(manager)] que selecciona el repositorio de la transacción actual y métodos cortos sin lógica de negocio.
11.10.1. src/repositories/doctor.repository.ts
| // =========================================================================
// repositories/doctor.repository.ts
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Doctor]. En comparación con el servidor JSON, tres
// novedades, todas relacionadas con la gestión de médicos por el ADMIN:
// - las lecturas también traen la cuenta de usuario asociada (relación
// [user]), para mostrar el login en la lista de médicos;
// - save() / deleteById(): creación, actualización, eliminación;
// - cada método de escritura acepta un EntityManager OPCIONAL: cuando
// la capa de negocio lo proporciona, la operación se ejecuta DENTRO de la transacción
// de esa capa (ver business.service.ts, dataSource.transaction(...)).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Doctor } from '../entities/doctor.entity';
@Injectable()
export class DoctorRepository {
constructor(
@InjectRepository(Doctor)
private readonly repository: Repository<Doctor>,
) {}
// el Repository que se debe usar: el de la transacción en curso si existe
// una, el Repository "ordinario" en caso contrario.
private repo(manager?: EntityManager): Repository<Doctor> {
return manager ? manager.getRepository(Doctor) : this.repository;
}
// lista ordenada por apellido y luego por nombre, con la cuenta de usuario incluida
findAll(): Promise<Doctor[]> {
return this.repository.find({ relations: { user: true }, order: { lastName: 'ASC', firstName: 'ASC' } });
}
findById(id: number, manager?: EntityManager): Promise<Doctor | null> {
return this.repo(manager).findOne({ where: { id }, relations: { user: true } });
}
// la persona con este nombre y apellido, si existe. La comparación
// la hace MySQL, por lo tanto con la collation de la base de datos (utf8mb4_unicode_ci:
// sin distinguir mayúsculas ni acentos) - exactamente la misma
// regla que la de la restricción de unicidad SQL.
findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<Doctor | null> {
return this.repo(manager).findOneBy({ firstName, lastName });
}
save(doctor: Doctor, manager?: EntityManager): Promise<Doctor> {
return this.repo(manager).save(doctor);
}
async deleteById(id: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete(id);
}
}
|
- líneas 28–30: dentro de una transacción, el repositorio de la transacción actual ([manager]);
- líneas 33–35: todos los médicos, junto con su cuenta ([relations: { user: true }]), ordenados por apellido y luego por nombre. La cuenta se usa para mostrar el nombre de usuario en la lista de médicos;
- líneas 45–47: los posibles homónimos. La comparación la realiza [MySQL], según la intercalación de la base de datos;
- líneas 49–51 y 53–55: operaciones de escritura y eliminación.
11.10.2. src/repositories/client.repository.ts
| // =========================================================================
// repositories/client.repository.ts
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Client] (un PACIENTE del consultorio). Estrictamente
// el mismo principio que doctor.repository.ts (ver sus comentarios).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Client } from '../entities/client.entity';
@Injectable()
export class ClientRepository {
constructor(
@InjectRepository(Client)
private readonly repository: Repository<Client>,
) {}
private repo(manager?: EntityManager): Repository<Client> {
return manager ? manager.getRepository(Client) : this.repository;
}
findAll(): Promise<Client[]> {
return this.repository.find({ relations: { user: true }, order: { lastName: 'ASC', firstName: 'ASC' } });
}
findById(id: number, manager?: EntityManager): Promise<Client | null> {
return this.repo(manager).findOne({ where: { id }, relations: { user: true } });
}
// el cliente (paciente) cuya cuenta de usuario es [userId], o null.
// where: { user: { id } }: TypeORM traduce este filtro sobre la relación a
// un simple "WHERE clients.user = ?" (sin necesidad de join)
findByUserId(userId: number): Promise<Client | null> {
return this.repository.findOne({ where: { user: { id: userId } }, relations: { user: true } });
}
// lee un cliente colocando un BLOQUEO sobre su fila hasta el final de la
// transacción en curso (SELECT ... FOR UPDATE). Una segunda transacción que
// solicite el mismo bloqueo ESPERA hasta que la primera haya terminado.
// Se usa al reservar una cita (ver BusinessService.addAppointment): dos
// reservas simultáneas del mismo paciente se procesan así una
// DESPUÉS de la otra, y la segunda ve la cita creada por la primera.
lock(id: number, manager: EntityManager): Promise<Client | null> {
return manager.getRepository(Client).findOne({ where: { id }, lock: { mode: 'pessimistic_write' } });
}
// la persona con este nombre y apellido, si existe. La comparación
// la hace MySQL, por lo tanto con la collation de la base de datos (utf8mb4_unicode_ci:
// sin distinguir mayúsculas ni acentos) - exactamente la misma
// regla que la de la restricción de unicidad SQL.
findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<Client | null> {
return this.repo(manager).findOneBy({ firstName, lastName });
}
save(client: Client, manager?: EntityManager): Promise<Client> {
return this.repo(manager).save(client);
}
async deleteById(id: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete(id);
}
}
|
Los mismos métodos que para los médicos, más dos:
- líneas 35–37: el cliente cuya cuenta se especifica; así es como un paciente conectado (cuyo token contiene el identificador de su cuenta) recupera su registro de cliente. [TypeORM] traduce el filtro [where: { user: { id: userId } }] a [WHERE clients.user = ?];
- líneas 45–47: una lectura con bloqueo ([lock: { mode: 'pessimistic_write' }], es decir, [SELECT ... FOR UPDATE] en SQL). Hasta el final de la transacción, cualquier otra transacción que solicite el mismo bloqueo espera. El módulo de programación de citas utiliza esto para procesar una después de otra dos reservas simultáneas para el mismo paciente.
11.10.3. src/repositories/slot.repository.ts
| // =========================================================================
// repositories/slot.repository.ts
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Slot]. Novedad: deleteByDoctor(), usado
// cuando se elimina un médico (los horarios del médico desaparecen
// junto con el médico - ver BusinessService.deleteDoctor).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Slot } from '../entities/slot.entity';
@Injectable()
export class SlotRepository {
constructor(
@InjectRepository(Slot)
private readonly repository: Repository<Slot>,
) {}
findById(id: number): Promise<Slot | null> {
return this.repository.findOne({ where: { id }, relations: { doctor: true } });
}
// los horarios de un médico, en orden cronológico
// (misma consulta que en el servidor JSON - ver sus comentarios)
getAllSlots(doctorId: number): Promise<Slot[]> {
return this.repository
.createQueryBuilder('s')
.where('s.doctor = :doctorId', { doctorId })
.orderBy('s.startHour', 'ASC')
.addOrderBy('s.startMinute', 'ASC')
.getMany();
}
// elimina todos los horarios de un médico. delete({ doctor: { id } })
// genera: DELETE FROM slots WHERE doctor_id = ?
async deleteByDoctor(doctorId: number, manager?: EntityManager): Promise<void> {
const repo = manager ? manager.getRepository(Slot) : this.repository;
await repo.delete({ doctor: { id: doctorId } });
}
}
|
- Líneas 27–34: las franjas horarias de un médico, en orden cronológico. La consulta se escribe con el QueryBuilder de [TypeORM], que construye una consulta SQL método por método: [createQueryBuilder('s')] (la tabla, con el alias [s]), [where] (con un parámetro llamado [:doctorId], nunca una concatenación de cadenas, que abriría la puerta a las inyecciones SQL), [orderBy] y luego [getMany], que ejecuta la consulta;
- líneas 38–41: eliminación de las franjas horarias de un médico, utilizada cuando se elimina a ese médico.
11.10.4. src/repositories/appointment.repository.ts
| // =========================================================================
// repositories/appointment.repository.ts
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Appointment]. Novedades:
// - el número de citas de un médico, para RECHAZAR la eliminación
// de un médico que aún tiene citas (ver BusinessService);
// - las citas PRÓXIMAS de un cliente (página "Mi área" del paciente, y
// regla "una sola cita próxima por paciente");
// - la eliminación de todas las citas de un cliente (un cliente se
// elimina junto con sus citas, por el ADMIN o por él mismo).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Appointment } from '../entities/appointment.entity';
@Injectable()
export class AppointmentRepository {
constructor(
@InjectRepository(Appointment)
private readonly repository: Repository<Appointment>,
) {}
private repo(manager?: EntityManager): Repository<Appointment> {
return manager ? manager.getRepository(Appointment) : this.repository;
}
findById(id: number): Promise<Appointment | null> {
return this.repository.findOne({ where: { id }, relations: { client: true, slot: true } });
}
save(appointment: Appointment, manager?: EntityManager): Promise<Appointment> {
return this.repo(manager).save(appointment);
}
async deleteById(id: number): Promise<void> {
await this.repository.delete(id);
}
// las citas de un médico en un día dado, con cliente y horario incluidos
// (misma consulta que en el servidor JSON - ver sus comentarios)
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
return this.repository
.createQueryBuilder('appointment')
.leftJoinAndSelect('appointment.client', 'client')
.leftJoinAndSelect('appointment.slot', 'slot')
.where('slot.doctor = :doctorId', { doctorId })
.andWhere('appointment.day = :day', { day })
.getMany();
}
// las citas de un cliente desde el día [from] (incluido), en
// orden cronológico, con el horario Y el médico de ese horario
// (innerJoinAndSelect en cascada: appointment -> slot -> doctor)
findUpcomingByClient(clientId: number, from: string): Promise<Appointment[]> {
return this.repository
.createQueryBuilder('appointment')
.innerJoinAndSelect('appointment.slot', 'slot')
.innerJoinAndSelect('slot.doctor', 'doctor')
.where('appointment.client = :clientId', { clientId })
.andWhere('appointment.day >= :from', { from })
.orderBy('appointment.day', 'ASC')
.addOrderBy('slot.startHour', 'ASC')
.addOrderBy('slot.startMinute', 'ASC')
.getMany();
}
// número de citas de un cliente desde el día [from] (incluido)
countUpcomingByClient(clientId: number, from: string, manager?: EntityManager): Promise<number> {
return this.repo(manager)
.createQueryBuilder('appointment')
.where('appointment.client = :clientId', { clientId })
.andWhere('appointment.day >= :from', { from })
.getCount();
}
// elimina TODAS las citas (pasadas y futuras) de un cliente:
// DELETE FROM appointments WHERE client_id = ?
async deleteByClient(clientId: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete({ client: { id: clientId } });
}
// número de citas (pasadas o futuras) de un médico - hay que pasar
// por los horarios del médico, ya que [appointments] no hace referencia directa a [doctors]:
// SELECT COUNT(*) FROM appointments INNER JOIN slots s ON ... WHERE s.doctor_id = ?
countByDoctor(doctorId: number, manager?: EntityManager): Promise<number> {
return this.repo(manager)
.createQueryBuilder('appointment')
.innerJoin('appointment.slot', 'slot')
.where('slot.doctor = :doctorId', { doctorId })
.getCount();
}
}
|
- líneas 43–51: las citas de un médico en un día determinado. [leftJoinAndSelect] realiza una unión y carga la entidad unida: cada cita se recupera junto con su paciente y su franja horaria;
- líneas 56–67: las citas de un cliente a partir de un día determinado, con su franja horaria y el médico asignado a esa franja (dos uniones en cascada): esto es lo que se muestra en «My area»;
- líneas 70–76: su recuento, para la regla de «una sola cita futura»;
- líneas 80–82: la eliminación de todas las citas de un cliente;
- líneas 87–93: el número de citas de un médico. La tabla [appointments] no hace referencia directa a los médicos: hay que pasar por las franjas horarias ([innerJoin], una unión sin carga).
11.10.5. src/repositories/user.repository.ts
| // =========================================================================
// repositories/user.repository.ts
// -------------------------------------------------------------------------
// Capa DAO de la entidad [User]. Novedad: save() / deleteById(), porque
// crear (o eliminar) un médico o un cliente también crea (o elimina) la
// cuenta de usuario - ver BusinessService.
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { User } from '../entities/user.entity';
@Injectable()
export class UserRepository {
constructor(
@InjectRepository(User)
private readonly repository: Repository<User>,
) {}
private repo(manager?: EntityManager): Repository<User> {
return manager ? manager.getRepository(User) : this.repository;
}
// devuelve null si ningún usuario tiene este login
findByLogin(login: string, manager?: EntityManager): Promise<User | null> {
return this.repo(manager).findOneBy({ login });
}
save(user: User, manager?: EntityManager): Promise<User> {
return this.repo(manager).save(user);
}
async deleteById(id: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete(id);
}
}
|
Líneas 26–28: la cuenta de un nombre de usuario, utilizada para iniciar sesión y para comprobar si un nombre de usuario está disponible.
11.11. La capa de negocio
11.11.1. src/business/dates.ts
| // =========================================================================
// business/dates.ts
// -------------------------------------------------------------------------
// La fecha de hoy en formato "yyyy-MM-dd" (el de la columna appointments.day).
// La usan las REGLAS DE NEGOCIO (sin reservas en el pasado, una sola cita
// PRÓXIMA por paciente): por lo tanto reside en la capa de
// negocio. La capa web la reutiliza (ver web/helpers/dates.helper.ts).
//
// Dos fechas "yyyy-MM-dd" pueden compararse directamente como cadenas:
// "2026-09-23" < "2026-10-01" - el orden alfabético es el orden cronológico.
// =========================================================================
// la fecha de hoy, en la zona horaria del servidor
export function today(): string {
const d = new Date();
const twoDigits = (n: number) => n.toString().padStart(2, '0');
return `${d.getFullYear()}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
}
|
Líneas 14–18: la fecha de hoy en el formato [yyyy-mm-dd]; la fecha de la columna [appointments.day]. [padStart(2, '0')] sirve para rellenar un número de un dígito hasta dos (9 se convierte en [09]). En este formato, el orden alfabético es el orden cronológico: dos fechas se comparan mediante [<].
11.11.2. src/business/business.exception.ts
| // =========================================================================
// business/business.exception.ts
// -------------------------------------------------------------------------
// La excepción que lanza la capa de negocio cuando se viola una REGLA DE NEGOCIO
// (login ya en uso, médico que aún tiene citas, horario ya
// reservado...). No lleva un texto, sino una CLAVE de traducción
// (p. ej. 'ERRORS.LOGIN_TAKEN'): es la capa web la que la
// traducirá al francés o al inglés al mostrar la página
// (ver i18n/fr.json, i18n/en.json).
//
// Así, la capa de negocio permanece independiente del idioma de la interfaz -
// como ya lo era del formato de salida (JSON o HTML).
// =========================================================================
export class BusinessException extends Error {
constructor(
public readonly key: string, // clave de traducción del mensaje
public readonly params: Record<string, string> = {}, // parámetros opcionales del mensaje
) {
super(key);
this.name = 'BusinessException';
}
}
|
- línea 17: una [BusinessException] no lleva un mensaje, sino una clave de traducción ([ERRORS.LOGIN_TAKEN]). De este modo, la capa de negocio ignora el idioma de la interfaz: la vista traducirá la clave (véase el capítulo 5);
- línea 18: los parámetros del mensaje, si los hay;
- línea 21: el nombre de la excepción, que se muestra en los registros de errores.
11.11.3. src/business/business.interface.ts
| // =========================================================================
// business/business.interface.ts
// -------------------------------------------------------------------------
// El contrato de la capa de negocio. A los 11 métodos del servidor JSON (lectura de
// listas, agenda, adición/eliminación de una cita) se agregan 2
// métodos para el área del paciente y 6 métodos para gestionar médicos
// y clientes.
// =========================================================================
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Doctor } from '../entities/doctor.entity';
import { Appointment } from '../entities/appointment.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';
// los datos ingresados en el formulario de "médico" o de "cliente"
export interface PersonData {
title: string; // Mr, Mme, Melle
lastName: string;
firstName: string;
// creación: opcional, por defecto el apellido en minúsculas
// actualización: opcional, el login no cambia si se omite
login?: string;
// creación: opcional, por defecto el login
// actualización: opcional, la contraseña no cambia si se omite
password?: string;
// actualización: la versión del registro cuando se mostró
// el formulario (bloqueo optimista, ver AbstractEntity.version)
version?: number;
}
export interface IBusiness {
// ------------------------------------------------ lecturas (sin cambios)
getAllClients(): Promise<Client[]>;
getAllDoctors(): Promise<Doctor[]>;
getAllSlots(doctorId: number): Promise<Slot[]>;
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]>;
getClientById(id: number): Promise<Client | null>;
getDoctorById(id: number): Promise<Doctor | null>;
getAppointmentById(id: number): Promise<Appointment | null>;
getSlotById(id: number): Promise<Slot | null>;
getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null>;
/** el cliente (paciente) cuya cuenta de usuario es [userId], o null */
getClientByUserId(userId: number): Promise<Client | null>;
/** las citas de un cliente, de hoy o futuras, con horario y médico */
getClientUpcomingAppointments(clientId: number): Promise<Appointment[]>;
// ------------------------------------------------ citas (ADMIN, DOCTOR, USER)
/**
* lanza una BusinessException si:
* - el día está en el pasado ('ERRORS.PAST_DATE');
* - el paciente ya tiene una cita próxima ('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
* - el intervalo ya está tomado ese día ('ERRORS.SLOT_ALREADY_BOOKED').
*/
addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment>;
deleteAppointment(appointment: Appointment): Promise<void>;
// ------------------------------------------------ médicos (ADMIN)
/** crea el médico Y la cuenta de usuario del médico (rol DOCTOR) */
addDoctor(data: PersonData): Promise<Doctor>;
/** actualiza el médico Y la cuenta de usuario del médico */
editDoctor(id: number, data: PersonData): Promise<Doctor>;
/** elimina el médico, los horarios Y la cuenta - rechazado si hay citas */
deleteDoctor(id: number): Promise<void>;
// ------------------------------------------------ clientes
// (el ADMIN; addClient también se usa para el registro de un paciente,
// editClient y deleteClient los usa el paciente para su propia cuenta)
/** crea el cliente Y la cuenta de usuario del cliente (rol USER) */
addClient(data: PersonData): Promise<Client>;
editClient(id: number, data: PersonData): Promise<Client>;
/**
* elimina el cliente, la cuenta Y todas las citas (pasadas y futuras).
* Lo usan el ADMIN (página "Clientes") y el propio paciente
* ("Administrar mi cuenta").
*/
deleteClient(id: number): Promise<void>;
}
export const BUSINESS_TOKEN = 'IBusiness';
|
- líneas 17–30: los datos de un médico o cliente que se va a crear o modificar. El nombre de usuario y la contraseña son opcionales: al crear, por defecto son el nombre en minúsculas; al modificar, solo cambian si se han ingresado;
- líneas 32–78: el contrato de la capa de negocio: lo que las demás capas pueden solicitarle. Los comentarios [/** ... */] son comentarios de documentación, que [VS Code] muestra al pasar el cursor sobre el método;
- línea 80: el token bajo el cual se registra la implementación en [app.module.ts]. Una interfaz de [TypeScript] desaparece en tiempo de compilación: no puede usarse para la inyección de dependencias. Por eso la inyección se realiza mediante este token: [@Inject(BUSINESS_TOKEN)].
11.11.4. src/business/business.service.ts
| // =========================================================================
// business/business.service.ts
// -------------------------------------------------------------------------
// Implementación de la capa de negocio.
//
// Las lecturas y la agenda se toman tal cual del servidor JSON. La
// novedad es la gestión de médicos y clientes, que obedece a tres
// reglas de negocio:
//
// 1. una persona (médico o cliente) y su cuenta de usuario van SIEMPRE
// juntas: se crean, se actualizan y se eliminan juntas, en
// una sola TRANSACCIÓN - o todo tiene éxito, o no se escribe nada;
// 2. el login es único en toda la aplicación, y dos médicos (o
// dos clientes) no pueden tener el mismo nombre y apellido;
// 3. eliminación:
// - un MÉDICO que tiene citas no puede eliminarse (los pacientes
// del médico perderían su cita sin ser avisados): estas
// deben cancelarse primero. Los horarios del médico también desaparecen;
// - un CLIENTE, en cambio, desaparece con TODAS sus citas (pasadas y
// futuras) - ya sea que la eliminación provenga del ADMIN o del propio
// paciente.
//
// Y dos reglas para la reserva de citas, sea cual sea el rol de
// quien reserva (ADMIN, DOCTOR o el propio paciente):
// 4. ninguna cita en el pasado;
// 5. un paciente tiene una sola cita PRÓXIMA a la vez.
//
// Médicos y clientes siguen exactamente las mismas reglas: el código común
// se escribe UNA SOLA VEZ (métodos privados xxxPerson), y se parametriza con un
// pequeño "descriptor" que indica con qué tipo de persona se trabaja.
// =========================================================================
import { Injectable } from '@nestjs/common';
import { DataSource, EntityManager, QueryFailedError } from 'typeorm';
import * as bcrypt from 'bcryptjs';
import { PersonData, IBusiness } from './business.interface';
import { BusinessException } from './business.exception';
import { DoctorRepository } from '../repositories/doctor.repository';
import { ClientRepository } from '../repositories/client.repository';
import { SlotRepository } from '../repositories/slot.repository';
import { AppointmentRepository } from '../repositories/appointment.repository';
import { UserRepository } from '../repositories/user.repository';
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Doctor } from '../entities/doctor.entity';
import { Person } from '../entities/person.entity';
import { Appointment } from '../entities/appointment.entity';
import { Role, User } from '../entities/user.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';
import { DoctorDaySlot } from '../domain/doctor-day-slot';
import { today } from './dates';
// número de rondas de salt de bcrypt - el mismo que en el script SQL ($2b$10$...)
const BCRYPT_ROUNDS = 10;
// lo que tienen en común los dos DAO DoctorRepository y ClientRepository
// (TypeScript verifica la compatibilidad por la FORMA de los objetos: ambas
// clases satisfacen esta interfaz sin necesidad de declararlo)
interface PersonDao<T extends Person> {
findById(id: number, manager?: EntityManager): Promise<T | null>;
findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<T | null>;
save(person: T, manager?: EntityManager): Promise<T>;
deleteById(id: number, manager?: EntityManager): Promise<void>;
}
// todo lo que distingue a un médico de un cliente para las reglas de negocio
interface PersonDescriptor<T extends Person> {
dao: PersonDao<T>;
create: () => T; // new Doctor() o new Client()
role: Role; // DOCTOR o USER
notFoundKey: string; // mensaje si la persona no existe
alreadyExistsKey: string; // mensaje si ya existe el mismo nombre y apellido
// opcional: si está presente, la eliminación se RECHAZA mientras la persona
// tenga citas (countAppointments > 0), con el mensaje hasAppointmentsKey
countAppointments?: (id: number, manager: EntityManager) => Promise<number>;
hasAppointmentsKey?: string;
// opcional: lo que debe eliminarse ANTES que la persona (las filas que
// hacen referencia a la persona mediante una clave externa)
beforeDelete?: (id: number, manager: EntityManager) => Promise<void>;
}
@Injectable()
export class BusinessService implements IBusiness {
private readonly doctorDescriptor: PersonDescriptor<Doctor>;
private readonly clientDescriptor: PersonDescriptor<Client>;
constructor(
// DataSource: la propia conexión de TypeORM, proporcionada por
// TypeOrmModule.forRoot(...). Lo usamos SOLO para abrir
// transacciones (dataSource.transaction(...)) - las consultas, en cambio,
// permanecen en la capa DAO.
private readonly dataSource: DataSource,
private readonly doctorRepository: DoctorRepository,
private readonly clientRepository: ClientRepository,
private readonly slotRepository: SlotRepository,
private readonly appointmentRepository: AppointmentRepository,
private readonly userRepository: UserRepository,
) {
this.doctorDescriptor = {
dao: doctorRepository,
create: () => new Doctor(),
role: 'DOCTOR',
notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
countAppointments: (id, manager) => appointmentRepository.countByDoctor(id, manager),
hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
// un médico sin citas aún puede tener horarios:
// no tienen sentido sin el médico, también se eliminan (de lo contrario
// la clave externa slots.doctor_id impediría la eliminación).
beforeDelete: (id, manager) => slotRepository.deleteByDoctor(id, manager),
};
this.clientDescriptor = {
dao: clientRepository,
create: () => new Client(),
role: 'USER',
notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
// sin countAppointments: la eliminación de un cliente nunca se rechaza;
// sus citas (pasadas y futuras) se eliminan con él (de lo contrario
// la clave externa appointments.client_id impediría la eliminación)
beforeDelete: (id, manager) => appointmentRepository.deleteByClient(id, manager),
};
}
// =======================================================================
// lecturas - sin cambios respecto al servidor JSON
// =======================================================================
getAllClients(): Promise<Client[]> {
return this.clientRepository.findAll();
}
getAllDoctors(): Promise<Doctor[]> {
return this.doctorRepository.findAll();
}
getAllSlots(doctorId: number): Promise<Slot[]> {
return this.slotRepository.getAllSlots(doctorId);
}
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
return this.appointmentRepository.getDoctorDayAppointments(doctorId, day);
}
getClientById(id: number): Promise<Client | null> {
return this.clientRepository.findById(id);
}
getDoctorById(id: number): Promise<Doctor | null> {
return this.doctorRepository.findById(id);
}
getAppointmentById(id: number): Promise<Appointment | null> {
return this.appointmentRepository.findById(id);
}
getSlotById(id: number): Promise<Slot | null> {
return this.slotRepository.findById(id);
}
getClientByUserId(userId: number): Promise<Client | null> {
return this.clientRepository.findByUserId(userId);
}
getClientUpcomingAppointments(clientId: number): Promise<Appointment[]> {
return this.appointmentRepository.findUpcomingByClient(clientId, today());
}
// mismo algoritmo que el servidor JSON (y que el proyecto Spring original)
async getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null> {
const doctor = await this.getDoctorById(doctorId);
if (doctor === null) {
return null;
}
const timeSlots = await this.getAllSlots(doctorId);
const bookings = await this.getDoctorDayAppointments(doctorId, day);
const bookingsBySlot = new Map<number, Appointment>();
for (const booking of bookings) {
bookingsBySlot.set(booking.slotId, booking);
}
const doctorDaySlots = timeSlots.map(
(slot) => new DoctorDaySlot(slot, bookingsBySlot.get(slot.id) ?? null),
);
return new DoctorDaySchedule(doctor, day, doctorDaySlots);
}
// =======================================================================
// citas
// =======================================================================
// -----------------------------------------------------------------------
// reserva de una cita, en una transacción:
// 1. ninguna cita en el pasado;
// 2. BLOQUEAMOS la fila del paciente (SELECT ... FOR UPDATE): si el
// mismo paciente reserva dos horarios al mismo tiempo (dos pestañas,
// doble clic...), la segunda transacción espera al final de la
// primera - y luego ve la cita que esta acaba de crear;
// 3. una sola cita próxima por paciente;
// 4. por último, la inserción. Si el horario acaba de ser tomado por OTRO
// paciente, es la restricción SQL unq1_appointments (day, slot_id) la que
// rechaza la inserción - traducida a una BusinessException por transaction().
// -----------------------------------------------------------------------
addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment> {
return this.transaction(async (manager) => {
const todayDate = today();
if (day < todayDate) {
throw new BusinessException('ERRORS.PAST_DATE');
}
if ((await this.clientRepository.lock(client.id, manager)) === null) {
throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
}
if ((await this.appointmentRepository.countUpcomingByClient(client.id, todayDate, manager)) > 0) {
throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
}
const appointment = new Appointment();
appointment.day = day;
appointment.slot = slot;
appointment.client = client;
return this.appointmentRepository.save(appointment, manager);
});
}
async deleteAppointment(appointment: Appointment): Promise<void> {
await this.appointmentRepository.deleteById(appointment.id);
}
// =======================================================================
// médicos y clientes - los métodos públicos delegan en los métodos
// privados comunes, con el descriptor adecuado
// =======================================================================
addDoctor(data: PersonData): Promise<Doctor> {
return this.addPerson(this.doctorDescriptor, data);
}
editDoctor(id: number, data: PersonData): Promise<Doctor> {
return this.editPerson(this.doctorDescriptor, id, data);
}
deleteDoctor(id: number): Promise<void> {
return this.deletePerson(this.doctorDescriptor, id);
}
addClient(data: PersonData): Promise<Client> {
return this.addPerson(this.clientDescriptor, data);
}
editClient(id: number, data: PersonData): Promise<Client> {
return this.editPerson(this.clientDescriptor, id, data);
}
// el cliente, la cuenta Y todas las citas (el ADMIN, o el propio paciente
// desde "Manage my account": mismo método, misma regla)
deleteClient(id: number): Promise<void> {
return this.deletePerson(this.clientDescriptor, id);
}
// -----------------------------------------------------------------------
// creación: primero la cuenta de usuario (la persona hace referencia a ella),
// luego la persona - todo en UNA sola transacción.
// -----------------------------------------------------------------------
private addPerson<T extends Person>(d: PersonDescriptor<T>, data: PersonData): Promise<T> {
const lastName = data.lastName.trim().toUpperCase();
const firstName = data.firstName.trim();
// las reglas de la base de datos dbrdvmedecins2: login = apellido en minúsculas,
// contraseña = login - a menos que el ADMIN ingrese otros valores
const login = (data.login || lastName).toLowerCase();
const password = data.password || login;
return this.transaction(async (manager) => {
await this.checkPersonUnique(d, firstName, lastName, null, manager);
await this.checkLoginFree(login, manager);
const user = new User();
user.login = login;
user.password = await bcrypt.hash(password, BCRYPT_ROUNDS);
user.name = `${firstName} ${lastName}`;
user.role = d.role;
await this.userRepository.save(user, manager);
const person = d.create();
person.title = data.title;
person.lastName = lastName;
person.firstName = firstName;
person.user = user;
return d.dao.save(person, manager);
});
}
// -----------------------------------------------------------------------
// actualización: la persona Y la cuenta (el nombre mostrado "firstName LASTNAME"
// debe seguir el cambio; el login y la contraseña cambian solo si se
// han ingresado).
// -----------------------------------------------------------------------
private editPerson<T extends Person>(
d: PersonDescriptor<T>,
id: number,
data: PersonData,
): Promise<T> {
return this.transaction(async (manager) => {
const person = await d.dao.findById(id, manager);
if (person === null) {
throw new BusinessException(d.notFoundKey);
}
// bloqueo optimista: si la versión en la base de datos ya no es la del
// formulario, alguien modificó este registro entretanto - lo rechazamos
// en lugar de sobrescribir en silencio sus cambios.
if (data.version !== undefined && data.version !== person.version) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
person.title = data.title;
person.lastName = data.lastName.trim().toUpperCase();
person.firstName = data.firstName.trim();
await this.checkPersonUnique(d, person.firstName, person.lastName, id, manager);
const user = person.user;
user.name = `${person.firstName} ${person.lastName}`;
if (data.login && data.login.toLowerCase() !== user.login) {
const login = data.login.toLowerCase();
await this.checkLoginFree(login, manager);
user.login = login;
}
if (data.password) {
user.password = await bcrypt.hash(data.password, BCRYPT_ROUNDS);
}
await this.userRepository.save(user, manager);
return d.dao.save(person, manager);
});
}
// -----------------------------------------------------------------------
// eliminación, en UNA sola transacción, en el orden impuesto por las claves
// externas:
// 1. posible rechazo si aún hay citas (médico);
// 2. lo que hace referencia a la persona (horarios de un médico, citas
// de un cliente);
// 3. la persona (hace referencia a la cuenta);
// 4. la cuenta.
// -----------------------------------------------------------------------
private deletePerson<T extends Person>(d: PersonDescriptor<T>, id: number): Promise<void> {
return this.transaction(async (manager) => {
const person = await d.dao.findById(id, manager);
if (person === null) {
throw new BusinessException(d.notFoundKey);
}
if (d.countAppointments && (await d.countAppointments(id, manager)) > 0) {
throw new BusinessException(d.hasAppointmentsKey ?? 'ERRORS.INVALID_FORM');
}
if (d.beforeDelete) {
await d.beforeDelete(id, manager);
}
await d.dao.deleteById(id, manager);
await this.userRepository.deleteById(person.userId, manager);
});
}
// rechaza un nombre y apellido ya utilizado por OTRA persona del mismo tipo
// (currentId: la persona que se actualiza, que obviamente tiene
// derecho a conservar su propio nombre y apellido; null para una creación)
private async checkPersonUnique<T extends Person>(
d: PersonDescriptor<T>,
firstName: string,
lastName: string,
currentId: number | null,
manager: EntityManager,
): Promise<void> {
const namesake = await d.dao.findByFirstNameLastName(firstName, lastName, manager);
if (namesake !== null && namesake.id !== currentId) {
throw new BusinessException(d.alreadyExistsKey);
}
}
private async checkLoginFree(login: string, manager: EntityManager): Promise<void> {
if ((await this.userRepository.findByLogin(login, manager)) !== null) {
throw new BusinessException('ERRORS.LOGIN_TAKEN');
}
}
// -----------------------------------------------------------------------
// ejecuta [work] en una transacción: dataSource.transaction() hace
// START TRANSACTION, llama a [work] con un EntityManager vinculado a esta
// transacción, luego COMMIT si todo salió bien - o ROLLBACK si se
// lanzó una excepción (BusinessException incluida).
//
// Las verificaciones de "login libre" y de "nombre + apellido único" se hacen ANTES de
// la escritura, para dar un mensaje claro. Pero dos ADMIN podrían
// guardar el mismo login (o el mismo médico) al mismo tiempo: en ese
// raro caso, es una restricción de unicidad SQL la que rechaza la segunda
// escritura - entonces traducimos este error SQL a la misma BusinessException.
// -----------------------------------------------------------------------
private async transaction<R>(work: (manager: EntityManager) => Promise<R>): Promise<R> {
try {
return await this.dataSource.transaction(work);
} catch (e) {
throw translateDuplicate(e);
}
}
}
// -------------------------------------------------------------------------
// Violaciones de restricciones de unicidad -> BusinessException
//
// Cuando una restricción UNIQUE rechaza una escritura, MySQL devuelve el error
// ER_DUP_ENTRY (n.º 1062), cuyo mensaje cita el NOMBRE de la restricción:
// Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name'
// (MySQL 8 antepone el nombre de la tabla, MariaDB no). Por eso
// el script SQL da NOMBRE a todas sus restricciones: cada una puede entonces
// traducirse a su propio mensaje.
// -------------------------------------------------------------------------
const CONSTRAINT_MESSAGES: Record<string, string> = {
unq_users_login: 'ERRORS.LOGIN_TAKEN',
unq_doctors_first_name_last_name: 'ERRORS.DOCTOR_ALREADY_EXISTS',
unq_clients_first_name_last_name: 'ERRORS.PATIENT_ALREADY_EXISTS',
unq1_appointments: 'ERRORS.SLOT_ALREADY_BOOKED',
};
// devuelve la BusinessException correspondiente a la restricción violada, o
// el error original, sin cambios, si no es una violación conocida
function translateDuplicate(e: unknown): unknown {
if (!(e instanceof QueryFailedError)) {
return e;
}
const sqlError = e.driverError as { code?: string; sqlMessage?: string };
if (sqlError?.code !== 'ER_DUP_ENTRY') {
return e;
}
// "... for key 'doctors.unq_doctors_first_name_last_name'" -> "unq_doctors_first_name_last_name"
const constraint = /for key '(?:[^'.]*\.)?([^']+)'/.exec(sqlError.sqlMessage ?? e.message)?.[1];
const key = constraint ? CONSTRAINT_MESSAGES[constraint] : undefined;
return key ? new BusinessException(key) : e;
}
|
Este es el archivo más extenso de la aplicación. Analicémoslo sección por sección.
11.11.4.1. Los descriptores
- línea 54: el costo de bcrypt, el mismo que en el script SQL;
- líneas 59–64: lo que tienen en común los DAO de médicos y de clientes. [TypeScript] compara los tipos por su forma: [DoctorRepository] y [ClientRepository] satisfacen esta interfaz sin declararla ([implements]);
- Líneas 67–80: todo lo que distingue a un médico de un cliente desde el punto de vista de la lógica de negocio: su DAO, cómo crear una instancia, el rol de su cuenta, sus mensajes de error y lo que ocurre cuando se elimina. 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 descriptor;
- líneas 87–98: el constructor recibe el [DataSource] (para abrir transacciones) y los cinco DAO. Construye los dos descriptores. El de los médicos (líneas 99–111) impide eliminar a un médico que tiene citas ([countAppointments]) y elimina sus franjas horarias antes de eliminar al médico ([beforeDelete]). El de los clientes (líneas 112–122) no tiene [countAppointments]: un cliente se elimina junto con sus citas.
11.11.4.2. Operaciones de lectura y el calendario
- líneas 129–167: las consultas delegan en la capa DAO;
- líneas 170–185: cálculo del calendario. Se leen las franjas horarias del médico y las citas del día; las citas se almacenan en un [Map] indexado por el identificador de su franja horaria; luego cada franja horaria se asocia con su cita, o con [null]. El [Map] evita tener que recorrer la lista de citas por cada franja horaria.
11.11.4.3. Programación de una cita
- líneas 203–221: todo ocurre dentro de una sola transacción;
- líneas 206–208: no se permiten citas en el pasado;
- líneas 209–211: el registro del paciente se bloquea. Sin este bloqueo, dos citas para el mismo paciente enviadas al mismo tiempo (dos pestañas, un doble clic) podrían pasar ambas la siguiente prueba antes de que cualquiera haya escrito su cita en la base de datos. Con el bloqueo, la segunda transacción espera a que termine la primera y luego ve la cita que esta creó;
- líneas 212–214: solo una cita futura por paciente;
- líneas 215–219: la inserción. Si otro paciente acaba de reservar la misma franja horaria, la restricción [unq1_appointments] rechaza la inserción y el método [transaction] maneja el error (véase más adelante);
- líneas 223–225: eliminación de una cita.
11.11.4.4. Gestión de médicos y clientes
- líneas 232–256: los seis métodos públicos delegan en los tres métodos genéricos, usando el descriptor correcto;
- Líneas 262–288: creación. El nombre se escribe con mayúscula inicial; por defecto, el nombre de usuario es el nombre en minúsculas y la contraseña es el nombre de usuario (líneas 267–268). Dentro de la transacción: se verifican las reglas de unicidad, se crea la cuenta (la contraseña se convierte en hash) y luego la persona, que se vincula a la cuenta. Si falla la segunda operación de escritura, se revierte la primera: nunca se crea una cuenta sin una persona;
- líneas 295–299: la actualización. El bloqueo optimista (líneas 308–310) rechaza un registro que se haya modificado entretanto. El nombre mostrado de la cuenta sigue al nombre y al apellido; el nombre de usuario y la contraseña solo cambian si se han ingresado;
- líneas 341–356: la eliminación, en el orden dictado por las claves externas: posible rechazo (un médico que tiene citas), eliminación de las referencias a la persona (las franjas horarias de un médico, las citas de un cliente), eliminación de la persona y luego eliminación de su cuenta;
- líneas 361–367: se rechaza a una persona con el mismo nombre, a menos que sea la propia persona (modificación);
- líneas 374–378: se rechaza un nombre de usuario que ya está en uso.
11.11.4.5. Transacciones y restricciones de unicidad
- líneas 392–398: todas las escrituras pasan por este método: [dataSource.transaction] confirma o revierte la transacción (véase el ejemplo 28), y un error se traduce mediante [translateDuplicate];
- líneas 411–416: cada restricción de unicidad con nombre del script SQL tiene su propio mensaje de error;
- líneas 420–432: un error SQL ([QueryFailedError]) con el código [ER_DUP_ENTRY] es una violación de una restricción de unicidad. Su mensaje incluye el nombre de la restricción (con el nombre de la tabla como prefijo en [MySQL] 8, sin prefijo en [MariaDB]): la expresión regular de la línea 429 lo extrae. Una restricción conocida se convierte en [BusinessException]; cualquier otro error se notifica tal cual: es una verdadera anomalía.
11.12. 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 la creación de cuentas.
11.12.1. src/auth/auth.constants.ts
| // =========================================================================
// auth/auth.constants.ts
// -------------------------------------------------------------------------
// ¿Por dónde viaja el token JWT?
//
// Con el cliente Angular, era el código JavaScript del cliente el que conservaba
// el token (localStorage) y lo agregaba por sí mismo a cada solicitud (encabezado
// "Authorization: Bearer ..."). Un navegador que muestra páginas HTML
// ordinarias no puede hacerlo: para que presente el token por su
// cuenta en cada solicitud, el token debe almacenarse en una COOKIE.
//
// Las opciones de esta cookie importan para la seguridad:
// - httpOnly: el JavaScript de la página no puede leer la cookie (un
// script inyectado no podría, por lo tanto, robar el token);
// - sameSite 'lax': el navegador NO envía la cookie con un POST
// proveniente de otro sitio. Como todas las acciones que modifican
// datos son POST, una página trampa en otro sitio no puede
// reservar ni eliminar nada haciéndose pasar por
// el usuario (el llamado ataque CSRF);
// - secure: en producción (HTTPS), la cookie nunca viaja en claro;
// - maxAge: la cookie desaparece al mismo tiempo que expira el token.
// =========================================================================
import { CookieOptions } from 'express';
export const COOKIE_JWT = 'rdvmedecins_jwt';
export const JWT_SECRET = process.env.JWT_SECRET ?? 'dev-secret-change-in-production';
export const JWT_EXPIRES_IN_SECONDS = process.env.JWT_EXPIRES_IN_SECONDS
? parseInt(process.env.JWT_EXPIRES_IN_SECONDS, 10)
: 7200;
export function jwtCookieOptions(): CookieOptions {
return {
httpOnly: true,
sameSite: 'lax',
secure: process.env.COOKIE_SECURE === 'true',
maxAge: JWT_EXPIRES_IN_SECONDS * 1000, // en milisegundos para Express
path: '/',
};
}
|
- líneas 4–21: el comentario explica por qué el token se almacena en una cookie y la finalidad de cada una de sus opciones (véase el ejemplo 25);
- línea 28: la clave, leída de [.env]. El valor predeterminado solo debe usarse durante el desarrollo;
- líneas 30–32: la duración del token: dos horas por defecto;
- líneas 34–42: las opciones de la cookie, agrupadas en un solo lugar (se usan para iniciar sesión y para modificar la cuenta de un paciente). [secure] solo se habilita en producción, donde el sitio se sirve mediante HTTPS; [maxAge] está en milisegundos.
11.12.2. src/auth/auth.service.ts
| // =========================================================================
// auth/auth.service.ts
// -------------------------------------------------------------------------
// La lógica de autenticación:
// - validateUser() : verifica un par login / contraseña;
// - createToken() : construye el token JWT de un usuario validado;
// - readToken() : verifica un token (página de inicio de sesión: si el
// usuario ya está conectado, no hace falta volver a pedirle
// la contraseña).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcryptjs';
import { UserRepository } from '../repositories/user.repository';
import { User } from '../entities/user.entity';
import { JwtPayload } from './jwt.strategy';
@Injectable()
export class AuthService {
constructor(
private readonly userRepository: UserRepository,
private readonly jwtService: JwtService,
) {}
async validateUser(login: string, password: string): Promise<User | null> {
const user = await this.userRepository.findByLogin(login);
if (user === null) {
return null;
}
return (await bcrypt.compare(password, user.password)) ? user : null;
}
createToken(user: User): string {
const payload: JwtPayload = { sub: user.id, login: user.login, name: user.name, role: user.role };
return this.jwtService.sign(payload);
}
// devuelve el contenido del token si es válido (firma correcta, no
// expirado), null en caso contrario
readToken(token: string | undefined): JwtPayload | null {
if (!token) {
return null;
}
try {
return this.jwtService.verify<JwtPayload>(token);
} catch {
return null;
}
}
}
|
- líneas 26–32: la cuenta si el nombre de usuario y la contraseña son correctos ([bcrypt.compare]), [null] en caso contrario;
- líneas 34–37: el token, que contiene el identificador, el nombre de usuario, el nombre para mostrar y el rol;
- líneas 41–50: [jwtService.verify] verifica la firma y la fecha de vencimiento de un token, y lanza una excepción si no es válido. Este método lo utilizan las páginas no protegidas (la página de inicio de sesión) que quieren determinar si el usuario ya está conectado.
11.12.3. src/auth/jwt.strategy.ts
| // =========================================================================
// auth/jwt.strategy.ts
// -------------------------------------------------------------------------
// La estrategia de Passport que autentica CADA solicitud protegida a partir del
// token JWT. Única diferencia con el servidor JSON: el token se lee de la cookie
// [rdvmedecins_jwt] (ver auth.constants.ts) en lugar del encabezado
// "Authorization: Bearer ...".
// =========================================================================
import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { Request } from 'express';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { Role } from '../entities/user.entity';
import { COOKIE_JWT, JWT_SECRET } from './auth.constants';
// lo que se almacena EN el token al construirlo (ver AuthService).
// El nombre mostrado también está ahí, para que la barra de navegación
// pueda mostrarlo sin consultar la base de datos en cada página.
export interface JwtPayload {
sub: number; // el id del usuario (convención JWT)
login: string;
name: string;
role: Role;
}
// lo que contendrá request.user una vez verificado el token
export interface ConnectedUser {
userId: number;
login: string;
name: string;
role: Role;
}
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
constructor() {
super({
// fromExtractors([...]): proporcionamos NUESTRA propia función de extracción
// del token - aquí, la lectura de una cookie (req.cookies lo llena el
// middleware cookie-parser, ver main.ts).
jwtFromRequest: ExtractJwt.fromExtractors([(req: Request) => req?.cookies?.[COOKIE_JWT] ?? null]),
ignoreExpiration: false,
secretOrKey: JWT_SECRET,
});
}
validate(payload: JwtPayload): ConnectedUser {
return { userId: payload.sub, login: payload.login, name: payload.name, role: payload.role };
}
}
|
- líneas 20–25: el contenido del token;
- líneas 28–33: lo que contendrá [req.user];
- líneas 38–45: el token se lee de la cookie; si ha vencido o tiene una firma incorrecta, se rechaza;
- líneas 48–50: el contenido del token se convierte en [req.user].
11.12.4. src/auth/jwt-auth.guard.ts
| // =========================================================================
// auth/jwt-auth.guard.ts
// -------------------------------------------------------------------------
// El guard que protege todas las páginas de la aplicación (excepto /login):
// exige un token JWT válido (ver jwt.strategy.ts, registrada bajo el nombre
// 'jwt'). Sin token, o con un token inválido/expirado, lanza una
// UnauthorizedException - que HtmlExceptionFilter convierte en una redirección
// a la página de inicio de sesión (ver web/html-exception.filter.ts).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}
|
La guardia que exige un token válido (véase el ejemplo 25). Sin token, lanza una [UnauthorizedException], que el filtro de excepciones convierte en una redirección a [/login].
11.12.5. src/auth/roles.decorator.ts
| // =========================================================================
// auth/roles.decorator.ts
// -------------------------------------------------------------------------
// @Roles('ADMIN') es un decorador CASERO (lo escribimos nosotros mismos,
// a diferencia de @Get/@Post/@Injectable, que proporciona NestJS): se limita a
// adjuntar un metadato ("este método requiere tal rol") al
// método que decora, sin verificar nada por sí mismo - es RolesGuard
// (ver roles.guard.ts) quien leerá este metadato y hará la verificación.
//
// SetMetadata(key, value) es la función de bajo nivel de NestJS que permite
// escribir este tipo de decoradores "personalizados": la usamos aquí para no
// tener que repetir la cadena 'roles' por todas partes en el código.
// =========================================================================
import { SetMetadata } from '@nestjs/common';
import { Role } from '../entities/user.entity';
export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);
|
Línea 19: el decorador [@Roles(...)] (véase el ejemplo 26). Sus parámetros son de tipo [Role]: [@Roles('ADMIM')] (error tipográfico) es rechazado por el compilador.
11.12.6. src/auth/roles.guard.ts
| // =========================================================================
// auth/roles.guard.ts
// -------------------------------------------------------------------------
// Segundo nivel de control, DESPUÉS de JwtAuthGuard: este último solo verifica
// que estamos efectivamente autenticados (un token JWT válido); RolesGuard
// verifica además que el rol del usuario conectado (request.user.role,
// establecido por JwtStrategy) esté entre los exigidos por @Roles(...)
// en el método de destino.
//
// Sin cambios respecto al servidor JSON, salvo el destino del error:
// la ForbiddenException lanzada aquí se convierte en una PÁGINA "403 - acceso
// prohibido" mediante HtmlExceptionFilter (ver web/html-exception.filter.ts).
//
// Es el equivalente, en espíritu, de la regla de Spring Security:
// http.authorizeRequests().antMatchers(...).hasRole("ADMIN")
// pero aplicada aquí método por método en lugar de URL por URL, gracias a la
// pareja decorador (@Roles) + Reflector (que puede volver a leer los metadatos
// establecidos por un decorador).
// =========================================================================
import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from './roles.decorator';
import { Role } from '../entities/user.entity';
import { ConnectedUser } from './jwt.strategy';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private readonly reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
// volvemos a leer los metadatos establecidos por @Roles(...) en el método de destino -
// getAllAndOverride busca primero en el método y luego en la clase.
const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [context.getHandler(), context.getClass()]);
// sin metadatos @Roles(...) en este método: sin restricción de rol
// adicional (JwtAuthGuard ya habrá exigido una autenticación
// válida, sea cual sea el rol).
if (!requiredRoles || requiredRoles.length === 0) {
return true;
}
// request.user fue establecido por JwtStrategy.validate() (ver jwt.strategy.ts) -
// RolesGuard se ejecuta por lo tanto SIEMPRE después de JwtAuthGuard (ver su orden
// en @UseGuards(JwtAuthGuard, RolesGuard), ver src/web/controllers/).
const request = context.switchToHttp().getRequest<{ user: ConnectedUser }>();
const user = request.user;
if (!requiredRoles.includes(user.role)) {
throw new ForbiddenException(
`role [${user.role}] does not allow this action (required role: ${requiredRoles.join(', ')})`,
);
}
return true;
}
}
|
La correspondencia de roles es idéntica a la del ejemplo 26.
11.12.7. src/auth/captcha.service.ts
| // =========================================================================
// auth/captcha.service.ts
// -------------------------------------------------------------------------
// Un CAPTCHA ("prueba para distinguir a un humano de un robot") construido por el
// propio servidor, sin ningún servicio externo: la biblioteca svg-captcha
// dibuja unos cuantos caracteres distorsionados, difuminados por líneas, en una
// imagen SVG. Un humano los lee fácilmente; un robot que solo
// envía formularios en bucle no puede.
//
// Cómo funciona:
// 1. generate() dibuja un texto aleatorio, lo convierte en imagen y almacena
// la respuesta correcta EN LA MEMORIA DEL SERVIDOR, bajo un identificador aleatorio;
// 2. la página muestra la imagen y coloca el identificador en un campo oculto
// del formulario (la respuesta misma nunca sale del servidor);
// 3. verify(id, input) compara la entrada con la respuesta esperada y luego
// OLVIDA este captcha: cada imagen se usa una sola vez, un robot no puede
// reutilizar una respuesta ya encontrada.
//
// Límite aceptado: la memoria de un único proceso de Node. Con varios
// servidores detrás de un balanceador de carga, haría falta un almacenamiento
// compartido (Redis, base de datos...).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { randomUUID } from 'crypto';
import * as svgCaptcha from 'svg-captcha';
// validez de una imagen: dispone de 10 minutos para completar el formulario
const LIFETIME_MS = 10 * 60 * 1000;
// protección de memoria: más allá de ese límite, se olvidan los captchas más antiguos
const MAX_CAPTCHAS = 10_000;
export interface Captcha {
id: string; // para colocar en el campo oculto "captchaId" del formulario
svg: string; // la imagen, para insertar tal cual en la página
}
@Injectable()
export class CaptchaService {
// id -> { respuesta esperada, fecha de expiración }. Un Map conserva el orden
// de inserción: sus primeras entradas son las más antiguas.
private readonly pending = new Map<string, { text: string; expires: number }>();
generate(): Captcha {
this.purge();
const { text, data } = svgCaptcha.create({
size: 5, // 5 caracteres
noise: 3, // 3 líneas de difuminado
color: true,
background: '#f5f7fa',
// caracteres demasiado fáciles de confundir entre sí: excluidos
ignoreChars: '0oO1iIlL',
});
const id = randomUUID();
this.pending.set(id, { text: text.toLowerCase(), expires: Date.now() + LIFETIME_MS });
return { id, svg: data };
}
// true si [input] es la respuesta correcta al captcha [id] (sin distinguir
// mayúsculas de minúsculas). El captcha se consume en todos los casos.
verify(id: unknown, input: unknown): boolean {
if (typeof id !== 'string' || typeof input !== 'string') {
return false;
}
const expected = this.pending.get(id);
this.pending.delete(id);
return expected !== undefined && expected.expires > Date.now() && expected.text === input.trim().toLowerCase();
}
private purge(): void {
const now = Date.now();
for (const [id, { expires }] of this.pending) {
if (expires <= now || this.pending.size >= MAX_CAPTCHAS) {
this.pending.delete(id);
}
}
}
}
|
- Líneas 29–31: en comparación con el ejemplo 27, un CAPTCHA tiene una duración de vida (diez minutos) y el número de CAPTCHA en memoria está limitado: un bot que solicitara la página de inicio de sesión millones de veces no podría agotar la memoria del servidor;
- línea 42: un [Map] conserva el orden de inserción: sus primeras entradas son las más antiguas;
- líneas 44–57: la imagen, su respuesta esperada (en minúsculas) y su fecha de expiración;
- líneas 61–68: la respuesta se compara sin distinguir entre mayúsculas y minúsculas; el CAPTCHA se consume en todos los casos;
- líneas 70–77: los CAPTCHA vencidos se descartan, al igual que los más antiguos si se alcanza el límite.
11.12.8. src/auth/attempt-limiter.service.ts
| // =========================================================================
// auth/attempt-limiter.service.ts
// -------------------------------------------------------------------------
// Segunda línea de defensa contra los bots (la primera es el captcha):
// CONTAMOS los intentos y, superado un umbral, BLOQUEAMOS por un tiempo.
//
// - inicio de sesión: tras LOGIN_MAX_FAILURES fallos (captcha o contraseña
// incorrectos) para el mismo login desde la misma dirección IP, este par
// se bloquea durante LOGIN_BLOCK_MINUTES minutos. La misma dirección IP también se
// bloquea si acumula 5 veces más fallos, sumando todos los logins (un
// bot que prueba miles de logins distintos);
// - creación de cuentas: como máximo REGISTRATION_MAX_PER_HOUR cuentas creadas
// por hora desde la misma dirección IP.
//
// Atención en un aula: todas las computadoras suelen salir a Internet
// por la MISMA dirección IP. Por eso el bloqueo de inicio de sesión se aplica
// primero al par (IP, login) - un estudiante que se equivoca al escribir su
// contraseña no bloquea a sus compañeros - y por eso los umbrales pueden
// configurarse en el archivo .env.
//
// Al igual que el captcha, los contadores viven en la memoria del proceso.
// =========================================================================
import { Injectable } from '@nestjs/common';
interface Counter {
count: number; // intentos contados en la ventana actual
start: number; // inicio de la ventana de conteo (ms)
blockedUntil: number; // 0 si no está bloqueado
}
const MINUTE = 60 * 1000;
function envInteger(name: string, fallback: number): number {
const value = parseInt(process.env[name] ?? '', 10);
return Number.isInteger(value) && value > 0 ? value : fallback;
}
@Injectable()
export class AttemptLimiterService {
private readonly counters = new Map<string, Counter>();
private readonly maxLoginFailures = envInteger('LOGIN_MAX_FAILURES', 5);
private readonly loginBlockDuration = envInteger('LOGIN_BLOCK_MINUTES', 15) * MINUTE;
private readonly maxRegistrations = envInteger('REGISTRATION_MAX_PER_HOUR', 10);
// ---------------------------------------------------------------- inicio de sesión
// número de minutos de bloqueo restantes (0 = se permite el intento)
loginBlockMinutes(ip: string, login: string): number {
return Math.max(this.remainingMinutes(loginKey(ip, login)), this.remainingMinutes(ipKey(ip)));
}
loginFailure(ip: string, login: string): void {
this.count(loginKey(ip, login), this.maxLoginFailures, this.loginBlockDuration, this.loginBlockDuration);
this.count(ipKey(ip), this.maxLoginFailures * 5, this.loginBlockDuration, this.loginBlockDuration);
}
// un inicio de sesión exitoso reinicia el contador de ESTE login
loginSuccess(ip: string, login: string): void {
this.counters.delete(loginKey(ip, login));
}
// ---------------------------------------------------------------- registro
registrationBlockMinutes(ip: string): number {
return this.remainingMinutes(`registration|${ip}`);
}
registrationSuccess(ip: string): void {
// ventana de una hora; una vez alcanzada la cuota, bloqueado hasta el final de la hora
this.count(`registration|${ip}`, this.maxRegistrations, 60 * MINUTE, 60 * MINUTE);
}
// ---------------------------------------------------------------- mecánica común
private remainingMinutes(key: string): number {
const c = this.counters.get(key);
const remaining = c ? c.blockedUntil - Date.now() : 0;
return remaining > 0 ? Math.ceil(remaining / MINUTE) : 0;
}
// cuenta un intento; si se alcanza el umbral dentro de la ventana, bloquea
private count(key: string, max: number, window: number, block: number): void {
const now = Date.now();
this.purge(now);
let c = this.counters.get(key);
if (!c || now - c.start > window) {
c = { count: 0, start: now, blockedUntil: 0 };
this.counters.set(key, c);
}
c.count++;
if (c.count >= max) {
c.blockedUntil = now + block;
c.count = 0; // después del bloqueo, se vuelve a empezar desde cero
c.start = c.blockedUntil;
}
}
// olvidamos los contadores que ya no son útiles (ni bloqueados, ni recientes)
private purge(now: number): void {
if (this.counters.size < 1000) {
return;
}
for (const [key, c] of this.counters) {
if (c.blockedUntil < now && now - c.start > 60 * MINUTE) {
this.counters.delete(key);
}
}
}
}
function loginKey(ip: string, login: string): string {
return `login|${ip}|${login.trim().toLowerCase()}`;
}
function ipKey(ip: string): string {
return `ip|${ip}`;
}
|
- líneas 26–30: un contador de intentos, con el inicio de su ventana de conteo y su fecha de fin de bloqueo;
- líneas 34–37: un umbral leído de [.env], con un valor predeterminado;
- líneas 50–52: el bloqueo se aplica al par (dirección IP, login) y a la dirección IP sola cuando acumula un gran número de intentos fallidos, sea cual sea el login. En un aula, todas las estaciones de trabajo suelen conectarse con la misma dirección IP: un estudiante que ingresa mal su contraseña no debe bloquear a sus compañeros;
- líneas 54–57: un intento fallido cuenta para ambas claves;
- líneas 66–68 y 70–73: el número de cuentas creadas por hora desde la misma dirección IP está limitado;
- líneas 84–98: el conteo. Una ventana vencida se reinicia a cero; cuando se alcanza el umbral, la clave queda bloqueada;
- líneas 101–110: limpieza de los contadores antiguos para evitar que las claves se acumulen indefinidamente en memoria;
- líneas 113–118: generación de las claves para el [Map].
11.12.9. src/auth/registration-pass.service.ts
| // =========================================================================
// auth/registration-pass.service.ts
// -------------------------------------------------------------------------
// El "pase" para la creación de cuentas.
//
// Para abrir la página "Create a patient account", primero hay que haber
// escrito el captcha de la página de autenticación (ver
// RegistrationController, POST /register/access). El servidor emite entonces
// un pase:
// - un identificador aleatorio, almacenado en una cookie httpOnly;
// - válido durante 15 minutos (tiempo para llenar el formulario, incluso al
// intentarlo varias veces tras errores de entrada);
// - consumido en cuanto se crea una cuenta: UN captcha resuelto = UNA cuenta como
// máximo. Un bot no puede crear cuentas en masa.
//
// Sin un pase válido, GET y POST /register devuelven a la página de
// autenticación: escribir directamente la URL /register no
// evita el captcha.
//
// Al igual que el captcha, los pases viven en la memoria del proceso.
// =========================================================================
import { Injectable } from '@nestjs/common';
import { randomUUID } from 'crypto';
import { CookieOptions } from 'express';
export const COOKIE_REGISTRATION_PASS = 'rdvmedecins_registration';
const LIFETIME_MS = 15 * 60 * 1000;
const MAX_PASSES = 10_000;
@Injectable()
export class RegistrationPassService {
// id -> fecha de expiración
private readonly passes = new Map<string, number>();
// emite un nuevo pase; devuelve su identificador
issue(): string {
this.purge();
const id = randomUUID();
this.passes.set(id, Date.now() + LIFETIME_MS);
return id;
}
// true si [id] es un pase existente y no expirado
isValid(id: unknown): boolean {
if (typeof id !== 'string') {
return false;
}
const expires = this.passes.get(id);
return expires !== undefined && expires > Date.now();
}
// el pase ya se usó: lo olvidamos
consume(id: unknown): void {
if (typeof id === 'string') {
this.passes.delete(id);
}
}
cookieOptions(): CookieOptions {
return { httpOnly: true, sameSite: 'lax', maxAge: LIFETIME_MS, path: '/register' };
}
private purge(): void {
const now = Date.now();
for (const [id, expires] of this.passes) {
if (expires <= now || this.passes.size >= MAX_PASSES) {
this.passes.delete(id);
}
}
}
}
|
La creación de una cuenta de paciente está disponible desde la página de inicio de sesión, siempre que se haya resuelto el CAPTCHA. Por lo tanto, una solicitud (el formulario de registro) debe saber que una solicitud anterior resolvió el CAPTCHA. Este es el papel del pase:
- líneas 38–43: un identificador aleatorio, válido durante 15 minutos, almacenado en memoria; se guardará en una cookie;
- líneas 46–52: el formulario de registro solo se muestra y se acepta con un pase válido;
- líneas 55–59: la creación de una cuenta consume el pase: un CAPTCHA resuelto da derecho a una cuenta, y nada más;
- líneas 61–63: la opción [path: '/register'] restringe el envío de la cookie a las URL que comienzan con [/register].
11.12.10. src/auth/auth.controller.ts
| // =========================================================================
// auth/auth.controller.ts
// -------------------------------------------------------------------------
// Las rutas de inicio de sesión NO protegidas:
// GET / redirige a la página de inicio del rol (o a /login)
// GET /login muestra el formulario de inicio de sesión (con su captcha)
// POST /login verifica el límite de intentos, el captcha, login / contraseña
// POST /logout borra la cookie del token
//
// El servidor JSON usaba un guard "local" de Passport para POST /login:
// en caso de fallo, respondía 401 directamente, lo cual conviene a un cliente
// JavaScript. Una página HTML, en cambio, debe MOSTRAR el formulario DE NUEVO
// con un mensaje de error: por eso llamamos nosotros mismos a AuthService.
//
// Protección contra bots, en este orden (ver captcha.service.ts y
// attempt-limiter.service.ts):
// 1. ¿demasiados fallos recientes para este login desde esta dirección IP?
// -> rechazo inmediato, sin siquiera mirar la contraseña;
// 2. ¿respuesta incorrecta al captcha? -> rechazo (contado como un fallo);
// 3. solo entonces se verifica la contraseña.
// La contraseña de un intento rechazado en los pasos 1 o 2 NUNCA se verifica:
// un bot no puede por lo tanto aprender nada insistiendo.
// =========================================================================
import { Body, Controller, Get, HttpCode, Post, Query, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { AuthService } from './auth.service';
import { CaptchaService } from './captcha.service';
import { AttemptLimiterService } from './attempt-limiter.service';
import { COOKIE_JWT, jwtCookieOptions } from './auth.constants';
import { Role } from '../entities/user.entity';
// la página de inicio de cada rol, justo después de iniciar sesión
export function homePage(role: Role): string {
return role === 'USER' ? '/my-area' : '/schedule';
}
@Controller()
export class AuthController {
constructor(
private readonly authService: AuthService,
private readonly captchaService: CaptchaService,
private readonly limiter: AttemptLimiterService,
) {}
@Get()
home(@Req() req: Request, @Res() res: Response): void {
const token = this.authService.readToken(req.cookies?.[COOKIE_JWT]);
res.redirect(token ? homePage(token.role) : '/login');
}
// GET /login[?login=xxx]: el parámetro opcional rellena previamente el campo
// login (se usa justo después de crear una cuenta, ver RegistrationController)
@Get('login')
showLogin(@Req() req: Request, @Res() res: Response, @Query('login') login?: string): void {
// ya conectado (token aún válido): directo a la página de inicio
const token = this.authService.readToken(req.cookies?.[COOKIE_JWT]);
if (token !== null) {
return res.redirect(homePage(token.role));
}
this.showForm(res, typeof login === 'string' ? login.slice(0, 30) : '');
}
// @HttpCode(200): por defecto, NestJS responde 201 (Created) a un POST - lo cual
// no tiene sentido cuando el formulario se MUESTRA DE NUEVO (una redirección, por su
// parte, impone de todos modos su propio código, 302).
@Post('login')
@HttpCode(200)
async logIn(
@Body() body: { login?: string; password?: string; captchaId?: string; captcha?: string },
@Req() req: Request,
@Res() res: Response,
): Promise<void> {
const login = (body.login ?? '').trim();
const password = body.password ?? '';
const ip = req.ip ?? 'unknown';
// 1. ¿demasiados fallos recientes?
const minutes = this.limiter.loginBlockMinutes(ip, login);
if (minutes > 0) {
return this.showForm(res, login, 'ERRORS.TOO_MANY_ATTEMPTS', { minutes: String(minutes) });
}
// 2. el captcha
if (!this.captchaService.verify(body.captchaId, body.captcha)) {
this.limiter.loginFailure(ip, login);
return this.showForm(res, login, 'ERRORS.WRONG_CAPTCHA');
}
// 3. la contraseña
const user = login && password ? await this.authService.validateUser(login, password) : null;
if (user === null) {
this.limiter.loginFailure(ip, login);
return this.showForm(res, login, 'LOGIN.ERROR');
}
this.limiter.loginSuccess(ip, login);
res.cookie(COOKIE_JWT, this.authService.createToken(user), jwtCookieOptions());
res.redirect(homePage(user.role));
}
// cierre de sesión con un POST (y no con un simple enlace GET): un sitio de terceros
// no puede cerrar la sesión del usuario a sus espaldas (ver sameSite, auth.constants.ts)
@Post('logout')
logOut(@Res() res: Response): void {
res.clearCookie(COOKIE_JWT, { path: '/' });
res.redirect('/login');
}
// el formulario, siempre con un captcha NUEVO (cada imagen se usa una sola vez)
private showForm(
res: Response,
login: string,
error?: string,
errorParams?: Record<string, string>,
): void {
res.render('login', {
pageTitle: 'LOGIN.TITLE',
login, // el login ingresado se muestra de nuevo, nunca la contraseña
captcha: this.captchaService.generate(),
error,
errorParams,
});
}
}
|
Comentemos este código:
- líneas 34–36: la página de inicio depende del rol del usuario: “Mi área” para los pacientes, el calendario para los demás;
- líneas 46–50: la raíz del sitio redirige según el usuario haya iniciado sesión o no. Como la ruta no está protegida por la guardia, el token es verificado por [readToken];
- líneas 54–62: un usuario que ya inició sesión es enviado a su página de inicio. El parámetro [login] rellena previamente el campo (después de crear una cuenta). [slice(0, 30)] limita su longitud: los datos de la solicitud nunca se usan sin precauciones;
- líneas 69–73: el proceso de inicio de sesión, en orden: posible bloqueo, CAPTCHA y luego contraseña (véase el ejemplo 27). [req.ip] es la dirección IP del cliente. Si tiene éxito: el contador se restablece a cero, se establece la cookie y se redirige a la página de inicio del rol;
- líneas 104–108: cierre de sesión;
- líneas 111–116: la página de inicio de sesión, siempre con un nuevo CAPTCHA. El error es una clave de traducción, junto con sus parámetros (el número de minutos de bloqueo).
11.12.11. src/auth/auth.module.ts
| // =========================================================================
// auth/auth.module.ts
// -------------------------------------------------------------------------
// El módulo de autenticación. EXPORTA:
// - UserRepository, que la capa de negocio necesita (crear, actualizar,
// eliminar la cuenta de un médico o de un cliente - ver business.service.ts);
// - AuthService, CaptchaService, AttemptLimiterService y
// RegistrationPassService, usados también por las páginas "Create an account"
// y "Manage my account" (src/web/).
// =========================================================================
import { Module } from '@nestjs/common';
import { JwtModule } from '@nestjs/jwt';
import { PassportModule } from '@nestjs/passport';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from '../entities/user.entity';
import { UserRepository } from '../repositories/user.repository';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { JwtStrategy } from './jwt.strategy';
import { CaptchaService } from './captcha.service';
import { AttemptLimiterService } from './attempt-limiter.service';
import { RegistrationPassService } from './registration-pass.service';
import { JWT_EXPIRES_IN_SECONDS, JWT_SECRET } from './auth.constants';
@Module({
imports: [
TypeOrmModule.forFeature([User]),
PassportModule,
JwtModule.register({
secret: JWT_SECRET,
signOptions: { expiresIn: JWT_EXPIRES_IN_SECONDS },
}),
],
controllers: [AuthController],
providers: [
AuthService,
UserRepository,
JwtStrategy,
CaptchaService,
AttemptLimiterService,
RegistrationPassService,
],
exports: [UserRepository, AuthService, CaptchaService, AttemptLimiterService, RegistrationPassService],
})
export class AuthModule {}
|
- línea 28: el repositorio de la entidad [User];
- líneas 30–33: la configuración de [JwtService];
- línea 44: los servicios exportados al módulo raíz (véase el ejemplo 06): [UserRepository] para la capa de negocio (crear una cuenta de médico o de cliente), los demás para los controladores de la capa web (creación de cuentas, gestión de la cuenta por el paciente).
11.13. La capa web: servicios comunes
Antes de ver los controladores, veamos lo que tienen en común: la traducción, el contexto de cada página, el interceptor, el filtro de excepciones, el caché de listas y los helpers.
11.13.1. src/web/i18n.ts
| // =========================================================================
// web/i18n.ts
// -------------------------------------------------------------------------
// Traducción francés / inglés de la interfaz.
//
// El cliente Angular cargaba sus diccionarios (public/i18n/fr.json y
// en.json) en el NAVEGADOR con @ngx-translate. Aquí, las páginas se
// construyen en el SERVIDOR: son por lo tanto los mismos diccionarios (las mismas
// claves, ampliadas), pero leídos una sola vez por el servidor al inicio.
// Una vista Handlebars traduce una clave con el helper {{t 'KEY'}}
// (ver views/handlebars-helpers.ts), el equivalente del pipe `| translate`.
// =========================================================================
import { readFileSync } from 'fs';
import { join } from 'path';
import { I18N_DIR } from '../config/paths';
export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const DEFAULT_LANGUAGE: Language = 'en';
// un diccionario es un objeto JSON anidado: { "LOGIN": { "TITLE": "Login" } }
type Dictionary = { [key: string]: string | Dictionary };
const dictionaries: Record<Language, Dictionary> = {
fr: JSON.parse(readFileSync(join(I18N_DIR, 'fr.json'), 'utf-8')),
en: JSON.parse(readFileSync(join(I18N_DIR, 'en.json'), 'utf-8')),
};
export function isLanguage(value: unknown): value is Language {
return typeof value === 'string' && (LANGUAGES as string[]).includes(value);
}
// -------------------------------------------------------------------------
// translate('en', 'DOCTORS.ADDED', { name: 'Marie PELISSIER' })
// -> busca DOCTORS y luego ADDED en el diccionario inglés, y reemplaza
// {name} por su valor. Una clave ausente del idioma solicitado se
// busca en el idioma por defecto; si falta en todas partes, se muestra la propia clave
// (así, una omisión en los diccionarios se detecta de inmediato).
// -------------------------------------------------------------------------
export function translate(language: Language, key: string, params: Record<string, unknown> = {}): string {
const text = lookup(dictionaries[language], key) ?? lookup(dictionaries[DEFAULT_LANGUAGE], key) ?? key;
return text.replace(/\{(\w+)\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
}
function lookup(dictionary: Dictionary, key: string): string | null {
let node: string | Dictionary | undefined = dictionary;
for (const part of key.split('.')) {
if (typeof node !== 'object' || node === null) {
return null;
}
node = node[part];
}
return typeof node === 'string' ? node : null;
}
|
El módulo de traducción del ejemplo 22, con una precisión (línea 42): si falta una clave en el diccionario francés, se busca en el diccionario inglés (el idioma predeterminado); si falta en ambos, se muestra la propia clave.
11.13.2. src/web/view-context.ts
| // =========================================================================
// web/view-context.ts
// -------------------------------------------------------------------------
// Lo que TODAS las páginas necesitan saber, sea cual sea la ruta
// que las muestra: el idioma de la interfaz, el posible mensaje "flash" que
// se debe mostrar y el usuario conectado (para la barra de navegación).
//
// Express ofrece [res.locals] para eso: un objeto asociado a la respuesta, cuyo
// contenido se fusiona AUTOMÁTICAMENTE con el modelo de cada vista en el
// momento de res.render(...). Los controladores no tienen por lo tanto que repetir esta
// información en cada uno de sus modelos.
//
// Recordatorio: el cliente Angular conservaba esta información en el navegador
// (signals + localStorage). Un servidor HTML, en cambio, debe volver a encontrarla en
// CADA solicitud - aquí, en las cookies.
// =========================================================================
import { NextFunction, Request, Response } from 'express';
import { Language, DEFAULT_LANGUAGE, isLanguage } from './i18n';
import { ConnectedUser } from '../auth/jwt.strategy';
export const COOKIE_LANGUAGE = 'rdvmedecins_language';
export const COOKIE_FLASH = 'rdvmedecins_flash';
// un mensaje que se muestra UNA SOLA VEZ, en la página siguiente
export interface FlashMessage {
type: 'success' | 'danger'; // clases de Bootstrap alert-success / alert-danger
key: string; // clave de traducción
params?: Record<string, string>;
}
// el usuario conectado, tal como lo ven las vistas
export interface ViewUser {
login: string;
name: string;
role: string;
isAdmin: boolean; // ADMIN: menús Doctors / Clients
isPatient: boolean; // USER: menú My area
}
// -------------------------------------------------------------------------
// Middleware de Express, ejecutado ANTES de cualquier ruta (ver main.ts):
// - res.locals.lang : idioma elegido (cookie), inglés por defecto;
// - res.locals.flash : el posible mensaje flash, que se borra
// de inmediato (debe mostrarse una sola vez);
// - res.locals.currentPath: la URL solicitada (menú activo de la barra de navegación).
// -------------------------------------------------------------------------
export function viewContextMiddleware(req: Request, res: Response, next: NextFunction): void {
res.locals.lang = languageOf(req);
res.locals.currentPath = req.path;
res.locals.flash = null;
res.locals.currentUser = null;
const raw = req.cookies?.[COOKIE_FLASH];
if (raw) {
try {
res.locals.flash = JSON.parse(raw) as FlashMessage;
} catch {
// cookie ilegible: se ignora
}
res.clearCookie(COOKIE_FLASH);
}
next();
}
export function languageOf(req: Request): Language {
const value = req.cookies?.[COOKIE_LANGUAGE];
return isLanguage(value) ? value : DEFAULT_LANGUAGE;
}
// -------------------------------------------------------------------------
// establece un mensaje flash, que mostrará la página SIGUIENTE. Es el
// complemento natural del patrón "Post / Redirect / Get" que usan todos los
// formularios de la aplicación: un POST exitoso no construye una página,
// redirige (302) a una página GET - si el usuario recarga entonces esta
// página (F5), el navegador no envía el formulario por segunda vez.
// Sin embargo, el mensaje debe sobrevivir a la redirección: una cookie
// de corta duración cumple esa función.
// -------------------------------------------------------------------------
export function flash(res: Response, message: FlashMessage): void {
res.cookie(COOKIE_FLASH, JSON.stringify(message), { httpOnly: true, sameSite: 'lax', maxAge: 60_000 });
}
// -------------------------------------------------------------------------
// expone el usuario conectado (request.user, establecido por JwtStrategy) a las
// vistas. Lo llaman ViewUserInterceptor (rutas normales) y
// HtmlExceptionFilter (páginas de error).
// -------------------------------------------------------------------------
export function exposeUser(req: Request, res: Response): void {
const user = (req as Request & { user?: ConnectedUser }).user;
if (!user) {
return;
}
const currentUser: ViewUser = {
login: user.login,
name: user.name,
role: user.role,
isAdmin: user.role === 'ADMIN',
isPatient: user.role === 'USER',
};
res.locals.currentUser = currentUser;
}
|
Comentemos este código:
- líneas 22–23: los nombres de las cookies del idioma y del mensaje flash;
- líneas 26–30: un mensaje flash: un tipo (éxito o error), una clave de traducción y sus parámetros. Se almacena en la cookie como JSON;
- líneas 33–39: el usuario que inició sesión, tal como lo ven las vistas. Los booleanos [isAdmin] y [isPatient] evitan que las vistas tengan que comparar cadenas;
- líneas 48–64: el middleware que se ejecuta antes de cualquier ruta (véanse los ejemplos 20 y 22): el idioma, la ruta (para el menú activo) y el mensaje flash, que se lee y luego se borra. [JSON.parse] está protegido por un [try]: una cookie modificada manualmente no debe hacer fallar la página;
- líneas 66–69: el idioma, según su cookie;
- líneas 80–82: muestra un mensaje flash (véase el ejemplo 20);
- líneas 89–102: copia el usuario que inició sesión ([req.user]) en [res.locals] para la barra de navegación. El middleware no llama a esta función: el middleware se ejecuta antes de las guardias y, por lo tanto, antes de que [req.user] exista (véase el capítulo 7). La llaman el interceptor siguiente y el filtro de excepciones.
11.13.3. src/web/view-user.interceptor.ts
| // =========================================================================
// web/view-user.interceptor.ts
// -------------------------------------------------------------------------
// ¿Por qué un interceptor y no simplemente el middleware de
// view-context.ts? Porque el ORDEN de ejecución importa:
//
// middlewares -> guards (JwtAuthGuard...) -> interceptors -> controlador
//
// Es el guard JwtAuthGuard el que establece request.user: un middleware se ejecuta
// demasiado pronto para verlo. Un interceptor, en cambio, se ejecuta DESPUÉS de los guards y
// ANTES del controlador - el momento justo para copiar el usuario conectado
// en res.locals, donde todas las vistas lo encontrarán.
// =========================================================================
import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Request, Response } from 'express';
import { Observable } from 'rxjs';
import { exposeUser } from './view-context';
@Injectable()
export class ViewUserInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
const http = context.switchToHttp();
exposeUser(http.getRequest<Request>(), http.getResponse<Response>());
return next.handle();
}
}
|
líneas 22–26: un interceptor se ejecuta después de las guardias y antes de la acción: es el momento adecuado para exponer el usuario transmitido por [JwtAuthGuard]. No tiene nada que hacer después de la acción: devuelve [next.handle()] directamente.
11.13.4. src/web/html-exception.filter.ts
| // =========================================================================
// web/html-exception.filter.ts
// -------------------------------------------------------------------------
// Un "filtro de excepciones" de NestJS recibe toda excepción que no fue
// controlada por el código de los controladores. Por defecto, NestJS responde en JSON
// ({"statusCode":403,"message":...}) - perfecto para el servidor JSON, pero
// ilegible en un navegador. En su lugar, este filtro construye una respuesta
// adecuada para una aplicación HTML:
//
// 401 (no conectado, o token expirado) -> redirección a /login
// 403 (rol insuficiente) -> página de error "acceso prohibido"
// 404 (página desconocida) -> página de error "página no encontrada"
// 400 (parámetro inválido) -> página de error "solicitud inválida"
// todo lo demás -> página de error 500
//
// @Catch() sin argumento: el filtro captura TODAS las excepciones. Se
// registra una sola vez para toda la aplicación en main.ts.
// =========================================================================
import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus, Logger } from '@nestjs/common';
import { Request, Response } from 'express';
import { COOKIE_JWT } from '../auth/auth.constants';
import { exposeUser, flash } from './view-context';
const MESSAGES: Record<number, string> = {
[HttpStatus.BAD_REQUEST]: 'ERRORS.BAD_REQUEST',
[HttpStatus.FORBIDDEN]: 'ERRORS.FORBIDDEN',
[HttpStatus.NOT_FOUND]: 'ERRORS.NOT_FOUND',
};
@Catch()
export class HtmlExceptionFilter implements ExceptionFilter {
private readonly logger = new Logger(HtmlExceptionFilter.name);
catch(exception: unknown, host: ArgumentsHost): void {
const http = host.switchToHttp();
const req = http.getRequest<Request>();
const res = http.getResponse<Response>();
const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
if (status === HttpStatus.UNAUTHORIZED) {
// una cookie estaba presente pero ya no es válida: la sesión ha expirado
if (req.cookies?.[COOKIE_JWT]) {
res.clearCookie(COOKIE_JWT, { path: '/' });
flash(res, { type: 'danger', key: 'ERRORS.SESSION_EXPIRED' });
}
res.redirect('/login');
return;
}
if (status >= 500) {
// una verdadera anomalía: conservamos el rastreo completo en la consola
// del servidor, sin mostrarlo nunca al usuario
this.logger.error(exception instanceof Error ? exception.stack : String(exception));
}
// la página de error conserva la barra de navegación del usuario conectado
// (si lo hay - un 403 ocurre DESPUÉS de la autenticación)
exposeUser(req, res);
res.status(status).render('error', {
pageTitle: 'ERROR_PAGE.TITLE',
code: status,
message: MESSAGES[status] ?? 'ERRORS.SERVER_ERROR',
});
}
}
|
- líneas 25–29: la clave del mensaje para cada código de error;
- líneas 42–50: un 401 redirige a la página de inicio de sesión. Si había una cookie de token, esta ha expirado (o la cuenta fue eliminada): se elimina y se notifica al usuario mediante un mensaje emergente;
- líneas 52–56: un error genuino se registra en la consola del servidor, junto con su pila de llamadas, pero nunca se revela al usuario: estos detalles ayudarían a un atacante;
- líneas 60–65: la página de error, con la barra de navegación del usuario que inició sesión.
11.13.5. src/web/application-model.service.ts
| // =========================================================================
// web/application-model.service.ts
// -------------------------------------------------------------------------
// El caché / fachada ya presente en el servidor JSON (equivalente de la
// clase [ApplicationModel] del proyecto Spring): las listas de médicos y
// de clientes se leen una vez al inicio y luego se sirven desde la memoria.
//
// Novedad: estas listas ahora pueden CAMBIAR (el ADMIN agrega,
// edita y elimina médicos y clientes). Un caché que
// nunca se actualizara mostraría datos obsoletos: cada escritura
// pasa por lo tanto por este servicio, que recarga la lista afectada justo después.
// Ese es todo el sentido de tener un ÚNICO punto de entrada a la capa de
// negocio: la regla "escritura => recarga del caché" se escribe solo aquí.
// =========================================================================
import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
import { PersonData, IBusiness, BUSINESS_TOKEN } from '../business/business.interface';
import { Client } from '../entities/client.entity';
import { Doctor } from '../entities/doctor.entity';
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';
@Injectable()
export class ApplicationModelService implements IBusiness, OnModuleInit {
private doctors: Doctor[] = [];
private clients: Client[] = [];
constructor(@Inject(BUSINESS_TOKEN) private readonly business: IBusiness) {}
// si la base de datos no está disponible al arrancar, la excepción detiene el servidor
// con un mensaje explícito - más claro, para una aplicación HTML, que
// arrancar "vacía" y mostrar listas vacías.
async onModuleInit(): Promise<void> {
await this.reloadDoctors();
await this.reloadClients();
}
private async reloadDoctors(): Promise<void> {
this.doctors = await this.business.getAllDoctors();
}
private async reloadClients(): Promise<void> {
this.clients = await this.business.getAllClients();
}
// ──────────────────────────────────────────────── lecturas desde la caché
async getAllDoctors(): Promise<Doctor[]> {
return this.doctors;
}
async getAllClients(): Promise<Client[]> {
return this.clients;
}
// el médico cuya cuenta de usuario es [userId] - sirve para preseleccionar,
// en el caso de un médico con sesión iniciada, su propia agenda
getDoctorByUserId(userId: number): Doctor | null {
return this.doctors.find((d) => d.userId === userId) ?? null;
}
// ──────────────────────────────────────────────── delegaciones simples
getAllSlots(doctorId: number): Promise<Slot[]> {
return this.business.getAllSlots(doctorId);
}
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
return this.business.getDoctorDayAppointments(doctorId, day);
}
getClientById(id: number): Promise<Client | null> {
return this.business.getClientById(id);
}
getDoctorById(id: number): Promise<Doctor | null> {
return this.business.getDoctorById(id);
}
getAppointmentById(id: number): Promise<Appointment | null> {
return this.business.getAppointmentById(id);
}
getSlotById(id: number): Promise<Slot | null> {
return this.business.getSlotById(id);
}
getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null> {
return this.business.getDoctorDaySchedule(doctorId, day);
}
// sin caché aquí: lo que importa son los datos más recientes (un paciente
// que acaba de modificar o eliminar su cuenta)
getClientByUserId(userId: number): Promise<Client | null> {
return this.business.getClientByUserId(userId);
}
getClientUpcomingAppointments(clientId: number): Promise<Appointment[]> {
return this.business.getClientUpcomingAppointments(clientId);
}
addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment> {
return this.business.addAppointment(day, slot, client);
}
deleteAppointment(appointment: Appointment): Promise<void> {
return this.business.deleteAppointment(appointment);
}
// ──────────────────────────────────────────────── escrituras => recarga
async addDoctor(data: PersonData): Promise<Doctor> {
const doctor = await this.business.addDoctor(data);
await this.reloadDoctors();
return doctor;
}
async editDoctor(id: number, data: PersonData): Promise<Doctor> {
const doctor = await this.business.editDoctor(id, data);
await this.reloadDoctors();
return doctor;
}
async deleteDoctor(id: number): Promise<void> {
await this.business.deleteDoctor(id);
await this.reloadDoctors();
}
async addClient(data: PersonData): Promise<Client> {
const client = await this.business.addClient(data);
await this.reloadClients();
return client;
}
async editClient(id: number, data: PersonData): Promise<Client> {
const client = await this.business.editClient(id, data);
await this.reloadClients();
return client;
}
async deleteClient(id: number): Promise<void> {
await this.business.deleteClient(id);
await this.reloadClients();
}
}
|
Comentemos este código:
- línea 25: el servicio tiene la misma interfaz que la capa de negocio: para los controladores, es la capa de negocio. Se interpone entre ambos para almacenar en memoria (ámbito de aplicación, véase el capítulo 6) las listas de médicos y de clientes, que se muestran en casi todas las páginas;
- línea 29: la capa de negocio se inyecta mediante su token;
- líneas 34–37: [onModuleInit] es llamado por [NestJS] una vez construido el módulo, antes de que arranque el servidor: las listas se leen al inicio. Si la base de datos es inaccesible, la aplicación termina con un mensaje claro;
- líneas 49–55: las listas se sirven desde la memoria;
- líneas 59–61: la cuenta de un médico: un médico que inició sesión ve de inmediato su propia agenda;
- líneas 65–109: las demás solicitudes se reenvían tal cual;
- líneas 113–145: cualquier operación de escritura que involucre médicos o clientes actualiza la lista correspondiente. Como este servicio es el único punto de entrada a la capa de negocio, la regla “escritura = actualización del caché” se implementa solo aquí, y el caché no puede quedar desactualizado.
11.13.6. src/web/views/handlebars-helpers.ts
| // =========================================================================
// web/views/handlebars-helpers.ts
// -------------------------------------------------------------------------
// Handlebars es deliberadamente un lenguaje de plantillas SIN LÓGICA: sin
// expresiones JavaScript en las vistas, solo {{variables}},
// bloques {{#if}} / {{#each}}... Cuando una vista necesita algo más, le
// damos un "helper": una función TypeScript, invocable desde la vista.
//
// La aplicación solo necesita cuatro helpers:
// {{t 'KEY'}} traducción (equivalente del pipe `| translate`)
// {{t 'KEY' name=person.lastName}} traducción con parámetro(s)
// {{#if (eq a b)}} comparación de igualdad
// {{#if (or a b)}} verdadero si al menos uno de los argumentos es verdadero
// {{active currentPath '/doctors'}} "active" si la página actual está bajo esta ruta
// =========================================================================
import { HelperOptions } from 'handlebars';
import { Language, DEFAULT_LANGUAGE, isLanguage, translate } from '../i18n';
// el módulo 'hbs' no tiene declaraciones de tipos: aquí describimos lo poco
// que usamos de él
interface Hbs {
registerHelper(name: string, fn: (...args: any[]) => unknown): void;
}
export function registerHelpers(hbs: Hbs): void {
// El último argumento que recibe un helper es siempre el objeto Handlebars [options]:
// options.hash contiene los parámetros con nombre (name=...), y
// options.data.root el modelo COMPLETO de la página - por lo tanto también res.locals.lang,
// el idioma elegido (véase view-context.ts), incluso dentro de un {{#each}}.
hbs.registerHelper('t', (key: unknown, options: HelperOptions) => {
const lang = options.data?.root?.lang;
const language: Language = isLanguage(lang) ? lang : DEFAULT_LANGUAGE;
// Handlebars escapa luego el texto devuelto ({{ }} y no {{{ }}}):
// por lo tanto, un nombre ingresado por el usuario no puede inyectar HTML
return typeof key === 'string' ? translate(language, key, options.hash) : '';
});
hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);
// ...args: todos los argumentos; el último es el objeto Handlebars [options]
// (véase arriba), que separamos antes de evaluar los demás
hbs.registerHelper('or', (...args: unknown[]) => args.slice(0, -1).some(Boolean));
hbs.registerHelper('active', (path: unknown, prefix: unknown) =>
typeof path === 'string' && typeof prefix === 'string' && path.startsWith(prefix) ? 'active' : '',
);
}
|
- líneas 31–37: el helper de traducción (véase el ejemplo 22);
- línea 39: la comprobación de igualdad (véase el ejemplo 16);
- línea 43: verdadero si alguno de los argumentos es verdadero. [...args] recibe todos los argumentos; el último es el objeto [options] de [Handlebars], que se descarta;
- líneas 45–47: la clase [active] del menú actual (véase el ejemplo 16).
| // =========================================================================
// web/models/person-form.dto.ts
// -------------------------------------------------------------------------
// Los campos de los formularios de "persona" y sus restricciones. Tres
// formularios comparten los mismos campos de identidad (título, nombre, apellido):
//
// PersonFieldsDto title, firstName, lastName
// ├─ PersonFormDto + login / password OPCIONALES, version
// │ (el ADMIN agrega o edita un médico / cliente)
// ├─ RegistrationFormDto + login / password / confirmación OBLIGATORIOS
// │ (un paciente crea su cuenta)
// └─ MyAccountFormDto + login, nueva contraseña opcional,
// contraseña ACTUAL obligatoria, version
// (un paciente edita su cuenta)
//
// La herencia de clases también se aplica a los decoradores de class-validator:
// una clase hija hereda las restricciones de los campos de su clase padre.
//
// Los mensajes de error son CLAVES de traducción (véase i18n/*.json).
// @Transform(...) (class-transformer) limpia la entrada ANTES de la
// validación: elimina espacios sobrantes, convierte en `undefined` los campos
// opcionales vacíos, pone el login en minúsculas, convierte version en número
// (todo lo que viene de un formulario HTML es una cadena de caracteres).
//
// La verificación "contraseña = confirmación" involucra DOS campos:
// la realiza el controlador, después de la validación de cada campo.
// =========================================================================
import { Transform } from 'class-transformer';
import { IsIn, IsInt, IsNotEmpty, IsOptional, Matches, MaxLength, MinLength } from 'class-validator';
export const TITLES = ['Mr', 'Mme', 'Melle'];
const clean = ({ value }: { value: unknown }) => (typeof value === 'string' ? value.trim() : value);
const emptyToUndefined = ({ value }: { value: unknown }) =>
typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
const cleanLogin = ({ value }: { value: unknown }) => emptyToUndefined({ value })?.toLowerCase();
// una contraseña no se "limpia" (los espacios pueden formar parte de ella)
const passwordOrUndefined = ({ value }: { value: unknown }) =>
typeof value === 'string' && value !== '' ? value : undefined;
const numberOrUndefined = ({ value }: { value: unknown }) =>
value === undefined || value === '' ? undefined : Number(value);
// login: letras minúsculas, dígitos, punto, guion, guion bajo - 30 caracteres como máximo
const LOGIN_FORMAT = /^[a-z0-9._-]{1,30}$/;
// longitud mínima de una contraseña ELEGIDA por un paciente
export const PASSWORD_MIN = 6;
// ────────────────────────────────────────────────────────────────── base común
export class PersonFieldsDto {
@IsIn(TITLES, { message: 'ERRORS.INVALID_TITLE' })
title: string;
// longitudes máximas = las de las columnas SQL (VARCHAR(20))
@Transform(clean)
@IsNotEmpty({ message: 'ERRORS.FIRSTNAME_REQUIRED' })
@MaxLength(20, { message: 'ERRORS.FIRSTNAME_TOO_LONG' })
firstName: string;
@Transform(clean)
@IsNotEmpty({ message: 'ERRORS.LASTNAME_REQUIRED' })
@MaxLength(20, { message: 'ERRORS.LASTNAME_TOO_LONG' })
lastName: string;
}
// ────────────────────────────────────────────────────────────────── ADMIN
export class PersonFormDto extends PersonFieldsDto {
// opcional (véase PersonData, business.interface.ts)
@Transform(cleanLogin)
@IsOptional()
@Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
login?: string;
// opcional; 72 caracteres como máximo (más allá, bcrypt ignora el resto)
@Transform(passwordOrUndefined)
@IsOptional()
@MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
password?: string;
// campo oculto del formulario de edición (bloqueo optimista)
@Transform(numberOrUndefined)
@IsOptional()
@IsInt({ message: 'ERRORS.INVALID_FORM' })
version?: number;
}
// ────────────────────────────────────────────────────────────────── registro de un paciente
export class RegistrationFormDto extends PersonFieldsDto {
@Transform(cleanLogin)
@IsNotEmpty({ message: 'ERRORS.LOGIN_REQUIRED' })
@Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
login: string;
@Transform(passwordOrUndefined)
@IsNotEmpty({ message: 'ERRORS.PASSWORD_REQUIRED' })
@MinLength(PASSWORD_MIN, { message: 'ERRORS.PASSWORD_TOO_SHORT' })
@MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
password: string;
@Transform(passwordOrUndefined)
@IsNotEmpty({ message: 'ERRORS.CONFIRMATION_REQUIRED' })
confirmation: string;
}
// ────────────────────────────────────────────────────────────────── "Manage my account"
export class MyAccountFormDto extends PersonFieldsDto {
@Transform(cleanLogin)
@IsNotEmpty({ message: 'ERRORS.LOGIN_REQUIRED' })
@Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
login: string;
// opcional: vacía = contraseña sin cambios
@Transform(passwordOrUndefined)
@IsOptional()
@MinLength(PASSWORD_MIN, { message: 'ERRORS.PASSWORD_TOO_SHORT' })
@MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
password?: string;
@Transform(passwordOrUndefined)
@IsOptional()
confirmation?: string;
// la contraseña ACTUAL, obligatoria para cualquier modificación de la cuenta
@Transform(passwordOrUndefined)
@IsNotEmpty({ message: 'ERRORS.CURRENT_PASSWORD_REQUIRED' })
currentPassword: string;
@Transform(numberOrUndefined)
@IsOptional()
@IsInt({ message: 'ERRORS.INVALID_FORM' })
version?: number;
}
|
Comentemos este código:
- línea 32: los tratamientos posibles;
- líneas 34–42: las funciones de limpieza aplicadas por [@Transform] antes de la validación: eliminación de espacios, campos vacíos reducidos a [undefined] (para que [@IsOptional] los acepte), login en minúsculas, versión convertida a número. Una contraseña no se sanea: sus espacios forman parte de ella;
- línea 45: el formato de un nombre de usuario, descrito mediante una expresión regular;
- líneas 50–64: los campos de identidad, comunes a tres formularios. Las longitudes máximas son las de las columnas SQL. Los mensajes son claves de traducción;
- líneas 67–85: el formulario ADMIN (médico o cliente): nombre de usuario y contraseña opcionales, y la versión para el bloqueo optimista. [extends]: la clase hereda los campos y decoradores de su clase padre. Una contraseña debe tener 72 caracteres o menos; bcrypt ignora los caracteres más allá de ese límite;
- líneas 88–103: un paciente crea una cuenta: nombre de usuario y contraseña obligatorios, al menos seis caracteres, y confirmación;
- líneas 106–132: un paciente que modifica su cuenta: nueva contraseña opcional, contraseña actual obligatoria.
| // =========================================================================
// web/helpers/form.helper.ts
// -------------------------------------------------------------------------
// Validación de un formulario HTML con class-validator.
//
// El servidor JSON dejaba la validación al ValidationPipe global: ante un
// error, respondía 400 Bad Request por sí mismo - lo cual conviene a un cliente
// JavaScript, que luego muestra el error a su manera. En una página
// HTML, por el contrario, queremos MOSTRAR el formulario DE NUEVO, con los valores
// ya ingresados y un mensaje bajo cada campo inválido. Por eso llamamos
// a class-validator nosotros mismos, para controlar lo que sucede después.
// =========================================================================
import { ClassConstructor, plainToInstance } from 'class-transformer';
import { validate } from 'class-validator';
import { TITLES } from '../models/person-form.dto';
// errores por campo: { lastName: 'ERRORS.LASTNAME_REQUIRED', ... } - cada
// mensaje es una CLAVE de traducción (véanse los decoradores de los DTO)
export type FormErrors = Record<string, string>;
export interface ValidationResult<T> {
dto: T; // los datos, convertidos y limpiados (véanse los @Transform de los DTO)
errors: FormErrors | null; // null = formulario válido
}
export async function validateForm<T extends object>(
cls: ClassConstructor<T>,
body: Record<string, unknown>,
): Promise<ValidationResult<T>> {
// plainToInstance: convierte el objeto plano recibido ({ lastName: ' dupont ' })
// en una instancia de la clase DTO, aplicando sus @Transform(...)
const dto = plainToInstance(cls, body);
// validate: verifica todas las restricciones (@IsNotEmpty, @MaxLength...);
// forbidUnknownValues:false porque validamos un objeto que construimos nosotros
const violations = await validate(dto, { forbidUnknownValues: false });
if (violations.length === 0) {
return { dto, errors: null };
}
const errors: FormErrors = {};
for (const violation of violations) {
// conservamos solo el primer mensaje de cada campo
errors[violation.property] = Object.values(violation.constraints ?? {})[0] ?? 'ERRORS.INVALID_FORM';
}
return { dto, errors };
}
// -------------------------------------------------------------------------
// los campos del formulario afectados por cada error de negocio de tipo "input"
// (un duplicado): se enmarcan en rojo, y el mensaje queda al pie de la página
// -------------------------------------------------------------------------
export const BUSINESS_ERROR_FIELDS: Record<string, string[]> = {
'ERRORS.LOGIN_TAKEN': ['login'],
'ERRORS.DOCTOR_ALREADY_EXISTS': ['firstName', 'lastName'],
'ERRORS.PATIENT_ALREADY_EXISTS': ['firstName', 'lastName'],
};
// { firstName: true, lastName: true }: los campos que se enmarcan en rojo (is-invalid) -
// los que tienen un mensaje de validación, más otros posibles
export function invalidFields(errors: FormErrors, others: string[] = []): Record<string, boolean> {
const fields: Record<string, boolean> = {};
for (const field of [...Object.keys(errors), ...others]) {
fields[field] = true;
}
return fields;
}
// las opciones de la lista desplegable "Title", con la de [value] seleccionada
export function titleOptions(value: string): { value: string; selected: boolean }[] {
return TITLES.map((t) => ({ value: t, selected: t === value }));
}
|
- líneas 27–30: validación de formularios, como en el ejemplo 19. La opción [forbidUnknownValues: false] es necesaria porque validamos un objeto generado por [plainToInstance], y no uno recibido de [ValidationPipe];
- líneas 52–56: ciertos errores de negocio se refieren a campos específicos (por ejemplo, un nombre de usuario que ya está en uso): estos campos se resaltarán en rojo, con el mensaje al pie de la página;
- líneas 60–66: los campos que se resaltarán en rojo;
- líneas 69–71: las opciones de la lista de tratamientos, con la seleccionada resaltada (véase el ejemplo 18).
11.13.9. src/web/helpers/dates.helper.ts
| // =========================================================================
// web/helpers/dates.helper.ts
// -------------------------------------------------------------------------
// Pequeñas funciones sobre fechas en formato "yyyy-MM-dd" (el de la columna
// appointments.day y del campo <input type="date"> de los formularios).
// =========================================================================
// fecha de hoy: definida en la capa de negocio, que la necesita para
// sus reglas de negocio - aquí simplemente la reexportamos
export { today } from '../../business/dates';
// true si [day] es una fecha que existe, en formato yyyy-MM-dd
// (misma verificación que el servidor JSON: "2026-02-30" se rechaza)
export function isValidDate(day: unknown): day is string {
if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
return false;
}
const date = new Date(`${day}T00:00:00Z`);
return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}
// "8:05" en lugar de "8:5"
export function formatTime(h: number, m: number): string {
return `${h}:${twoDigits(m)}`;
}
// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", según el idioma
// (Intl.DateTimeFormat: la API de formato de fechas integrada en JavaScript)
export function formatDay(day: string, language: string): string {
return new Intl.DateTimeFormat(language === 'en' ? 'en-GB' : 'fr-FR', {
dateStyle: 'full',
timeZone: 'UTC', // "2026-09-23T00:00:00Z" debe seguir siendo el día 23, sea cual sea la zona horaria del servidor
}).format(new Date(`${day}T00:00:00Z`));
}
function twoDigits(n: number): string {
return n.toString().padStart(2, '0');
}
|
- Línea 10: la fecha actual se define en la capa de negocio; este módulo la reexporta: los controladores importan todas las funciones de fechas desde un solo lugar;
- líneas 14–20: una fecha [yyyy-mm-dd] que existe (véase el ejemplo 12);
- líneas 29–34: una fecha escrita en su totalidad, según el idioma. La opción [timeZone: 'UTC'] evita un desfase de un día cuando el servidor no está configurado en la hora del meridiano de Greenwich.
11.13.10. src/web/helpers/patient.helper.ts
| // =========================================================================
// web/helpers/patient.helper.ts
// -------------------------------------------------------------------------
// El paciente (entidad Client) que corresponde al usuario con sesión iniciada.
//
// El token JWT contiene solo el id de la CUENTA (users.id). Para un rol USER,
// el cliente correspondiente se encuentra mediante la columna clients.user.
//
// Si no hay ninguno, la cuenta fue eliminada después del inicio de sesión
// (por el propio paciente en otra pestaña, o por el ADMIN) mientras
// el token sigue siendo válido: lo tratamos como una sesión expirada
// (UnauthorizedException -> regreso a la página de inicio de sesión, véase
// HtmlExceptionFilter).
// =========================================================================
import { UnauthorizedException } from '@nestjs/common';
import { ApplicationModelService } from '../application-model.service';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { Client } from '../../entities/client.entity';
import { Person } from '../../entities/person.entity';
// "Mme Alice DURAND"
export function label(p: Person): string {
return `${p.title} ${p.firstName} ${p.lastName}`;
}
export async function connectedPatient(
application: ApplicationModelService,
user: ConnectedUser,
): Promise<Client> {
const client = await application.getClientByUserId(user.userId);
if (client === null) {
throw new UnauthorizedException();
}
return client;
}
|
- líneas 23–25: “Mme Alice DURAND”;
- líneas 27–30: la ficha del paciente que inició sesión, obtenida a partir de su cuenta. Si ya no existe (cuenta eliminada en otra pestaña, o por el ADMIN, aunque el token siga siendo válido), se devuelve un error 401: redirección a la página de inicio de sesión.
11.14. La capa web: los controladores
11.14.1. src/web/controllers/language.controller.ts
| // =========================================================================
// web/controllers/language.controller.ts
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: los dos botones FR / EN de la
// barra de navegación. La elección se guarda en una cookie (el cliente Angular
// la guardaba en localStorage), y luego volvemos a la página de origen.
// Ruta sin protección: el idioma debe poder cambiarse antes de iniciar sesión.
// =========================================================================
import { Controller, Get, NotFoundException, Param, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { isLanguage } from '../i18n';
import { COOKIE_LANGUAGE } from '../view-context';
const ONE_YEAR = 365 * 24 * 3600 * 1000;
@Controller('language')
export class LanguageController {
@Get(':language')
change(@Param('language') language: string, @Req() req: Request, @Res() res: Response): void {
if (!isLanguage(language)) {
throw new NotFoundException();
}
res.cookie(COOKIE_LANGUAGE, language, { maxAge: ONE_YEAR, sameSite: 'lax', httpOnly: true });
res.redirect(originPage(req));
}
}
// la página anterior, según el encabezado HTTP "Referer" enviado por el
// navegador. Solo se conserva su ruta (/schedule?...): redirigir a
// una dirección completa proporcionada por la solicitud permitiría enviar
// al usuario a otro sitio (la llamada vulnerabilidad de "open redirect").
function originPage(req: Request): string {
const referer = req.get('referer');
if (!referer) {
return '/';
}
try {
const url = new URL(referer);
return url.pathname.startsWith('/language/') ? '/' : url.pathname + url.search;
} catch {
return '/';
}
}
|
El controlador del ejemplo 22. Nota: si la página de origen es en sí misma una página [/language/...] (línea 40), la solicitud se redirige a la raíz del sitio para evitar un bucle infinito.
| // =========================================================================
// web/controllers/schedule.controller.ts
// -------------------------------------------------------------------------
// La página de la agenda: elección de un médico y un día, agenda de ese
// médico en ese día, reserva y cancelación de citas.
// Es el equivalente en el servidor de los componentes Angular
// <app-doctor-day-picker>, <app-agenda> y <app-booking-dialog>.
//
// GET /schedule?doctorId=1&day=2026-09-23 la página
// GET /schedule?doctorId=1&day=2026-09-23&book=7 la misma página, con
// el diálogo de reserva
// de la franja 7 abierto
// POST /schedule/book crea una cita
// POST /schedule/cancel cancela una cita
//
// La página completa queda descrita por su URL: se puede recargar, guardar como favorito,
// usar el botón "Back" del navegador - sin una sola línea
// de JavaScript.
//
// Lo que cada usuario ve y puede hacer:
//
// | rol | franja ocupada mostrada | Reservar | Cancelar |
// |───────────────|───────────────────────────────────|────────────────────|──────────|
// | ADMIN, DOCTOR | nombre del paciente | para un paciente | sí |
// | | | elegido de una lista | |
// | USER (paciente)| "Booked", o SU nombre si es | para sí mismo, si | no (*) |
// | | su propia cita | no tiene ninguna | |
// | | | próxima | |
//
// (*) el paciente cancela su cita desde su página "My area".
//
// CONFIDENCIALIDAD: para un paciente, el nombre de los OTROS pacientes no está
// simplemente oculto por la vista - nunca se incluye en el modelo
// pasado a la vista. Por lo tanto, el HTML enviado al navegador no lo contiene,
// ni siquiera oculto (de lo contrario, un simple "View page source" lo revelaría).
//
// Sin reservas en el pasado: el botón "Book" solo aparece
// para hoy y los días siguientes (y la capa de negocio lo rechazaría
// de todos modos).
// =========================================================================
import { BadRequestException, Body, Controller, Get, Post, Query, Render, Req, Res, UseGuards } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { BusinessException } from '../../business/business.exception';
import { flash } from '../view-context';
import { today, isValidDate, formatTime } from '../helpers/dates.helper';
import { label, connectedPatient } from '../helpers/patient.helper';
import { Client } from '../../entities/client.entity';
import { Person } from '../../entities/person.entity';
type AuthenticatedRequest = Request & { user: ConnectedUser };
// ───────────────────────────────────────────────────────────────── modelo de vista
// (lo que muestra views/schedule.hbs - solo datos ya formateados
// Y ya filtrados según el rol: la vista no decide nada)
interface OptionView {
id: number;
label: string; // "Mme Marie PELISSIER"
selected: boolean;
}
interface ScheduleRowView {
slotId: number;
time: string; // "8:00 - 8:20"
free: boolean;
patient: string | null; // nombre mostrado para una franja ocupada; null = "Booked"
mine: boolean; // la cita del paciente con sesión iniciada
bookable: boolean; // ¿mostrar el botón "Book"?
bookUrl: string;
appointmentId: number | null; // definido solo si se muestra el botón "Cancel"
}
interface ScheduleView {
doctor: string;
day: string;
rows: ScheduleRowView[];
}
interface BookingView {
slotId: number;
time: string;
// ADMIN / DOCTOR: la lista de pacientes entre los que elegir
clients: OptionView[];
// USER: el paciente es el propio usuario
patient: string | null;
}
export interface ScheduleModel {
pageTitle: string;
doctors: OptionView[];
doctorId: number | null;
day: string;
schedule: ScheduleView | null;
booking: BookingView | null;
backUrl: string; // la agenda mostrada, sin el diálogo de reserva
// paciente que ya tiene una cita próxima: el mensaje que explica
// por qué no hay botón "Book"
info: string | null;
error: string | null;
}
// lo que el controlador sabe del usuario, para decidir qué mostrar
interface Rights {
manager: boolean; // ADMIN o DOCTOR
patient: Client | null; // el cliente con sesión iniciada (rol USER), null en caso contrario
patientCanBook: boolean; // USER sin una cita próxima
}
@UseGuards(JwtAuthGuard, RolesGuard)
@Controller('schedule')
export class ScheduleController {
constructor(private readonly application: ApplicationModelService) {}
// -----------------------------------------------------------------------
// GET /schedule
// @Render('schedule'): el objeto devuelto por el método se convierte en el modelo de
// la vista views/schedule.hbs (+ el contenido de res.locals, véase view-context.ts).
// -----------------------------------------------------------------------
@Get()
@Render('schedule')
async show(
@Req() req: AuthenticatedRequest,
@Query('doctorId') rawDoctorId?: string,
@Query('day') rawDay?: string,
@Query('book') rawBook?: string,
): Promise<ScheduleModel> {
let error: string | null = null;
const rights = await this.rights(req.user);
// el día: el de la URL si es válido, hoy en caso contrario
let day = today();
if (rawDay !== undefined) {
if (isValidDate(rawDay)) {
day = rawDay;
} else {
error = 'ERRORS.INVALID_DATE';
}
}
const dayBookable = day >= today();
// el médico: el de la URL; en su defecto, para un médico con sesión iniciada, el propio médico
let doctorId = positiveInteger(rawDoctorId);
if (rawDoctorId === undefined && req.user.role === 'DOCTOR') {
doctorId = this.application.getDoctorByUserId(req.user.userId)?.id ?? null;
}
const doctors = (await this.application.getAllDoctors()).map((d) => option(d, d.id === doctorId));
// la agenda, si se elige un médico (y la fecha es válida)
let schedule: ScheduleView | null = null;
if (doctorId !== null && error === null) {
const doctorSchedule = await this.application.getDoctorDaySchedule(doctorId, day);
if (doctorSchedule === null) {
error = 'ERRORS.DOCTOR_NOT_FOUND';
} else {
schedule = {
doctor: label(doctorSchedule.doctor),
day,
rows: doctorSchedule.doctorDaySlots.map(({ slot, appointment }) => {
const free = appointment === null;
// ¿la cita del paciente con sesión iniciada?
const mine = !free && rights.patient !== null && appointment.clientId === rights.patient.id;
return {
slotId: slot.id,
time: `${formatTime(slot.startHour, slot.startMinute)} - ${formatTime(slot.endHour, slot.endMinute)}`,
free,
// EL punto de confidencialidad: un paciente recibe el nombre solo
// de SU cita; para las demás, null (la vista muestra "Booked")
patient: free ? null : rights.manager || mine ? label(appointment.client) : null,
mine,
bookable: free && dayBookable && (rights.manager || rights.patientCanBook),
bookUrl: scheduleUrl(doctorId as number, day, slot.id),
appointmentId: !free && rights.manager ? appointment.id : null,
};
}),
};
}
}
// el diálogo de reserva: solo si la franja solicitada
// puede ser reservada por este usuario
let booking: BookingView | null = null;
const slotId = positiveInteger(rawBook);
const row = schedule?.rows.find((r) => r.slotId === slotId && r.bookable);
if (row) {
booking = {
slotId: row.slotId,
time: row.time,
clients: rights.manager ? (await this.application.getAllClients()).map((c) => option(c, false)) : [],
patient: rights.patient ? label(rights.patient) : null,
};
}
return {
pageTitle: 'SCHEDULE.PAGE_TITLE',
doctors,
doctorId,
day,
schedule,
booking,
backUrl: doctorId !== null ? scheduleUrl(doctorId, day) : '/schedule',
info: rights.patient !== null && !rights.patientCanBook ? 'SCHEDULE.ALREADY_BOOKED_INFO' : null,
error,
};
}
// -----------------------------------------------------------------------
// POST /schedule/book campos: doctorId, day, slotId, clientId
//
// Para un paciente (USER), el campo clientId se IGNORA: siempre reserva
// para sí mismo. Confiar en un campo enviado por el
// navegador permitiría que un paciente astuto reservara a nombre de otra persona.
//
// Patrón "Post / Redirect / Get": sea cual sea el resultado, aquí no
// construimos una página - definimos un mensaje flash y redirigimos
// a la agenda (véase flash(), view-context.ts).
// -----------------------------------------------------------------------
@Post('book')
@Roles('ADMIN', 'DOCTOR', 'USER')
async book(
@Body() body: Record<string, string>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const { doctorId, day } = readScheduleRequest(body);
const slotId = positiveInteger(body.slotId);
if (slotId === null) {
throw new BadRequestException();
}
let client: Client | null;
if (req.user.role === 'USER') {
client = await connectedPatient(this.application, req.user);
} else {
const clientId = positiveInteger(body.clientId);
if (clientId === null) {
// ningún paciente elegido: se vuelve a abrir el diálogo de reserva
flash(res, { type: 'danger', key: 'ERRORS.CHOOSE_PATIENT' });
return res.redirect(scheduleUrl(doctorId, day, slotId));
}
client = await this.application.getClientById(clientId);
}
const slot = await this.application.getSlotById(slotId);
if (client === null) {
flash(res, { type: 'danger', key: 'ERRORS.PATIENT_NOT_FOUND' });
} else if (slot === null || slot.doctorId !== doctorId) {
flash(res, { type: 'danger', key: 'ERRORS.SLOT_NOT_FOUND' });
} else {
try {
// las reglas (no en el pasado, una sola cita próxima por
// paciente, franja libre) las verifica la capa de negocio
await this.application.addAppointment(day, slot, client);
flash(res, { type: 'success', key: 'SCHEDULE.BOOKED' });
} catch (e) {
// misma regla, pero con un mensaje en 2.ª persona cuando es el propio paciente
// quien reserva ("You already have..." en lugar de "This patient...")
if (
req.user.role === 'USER' &&
e instanceof BusinessException &&
e.key === 'ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT'
) {
flash(res, { type: 'danger', key: 'SCHEDULE.ALREADY_BOOKED_INFO' });
} else {
flashBusinessError(res, e);
}
}
}
res.redirect(scheduleUrl(doctorId, day));
}
// -----------------------------------------------------------------------
// POST /schedule/cancel campos: appointmentId, doctorId, day
// (un paciente cancela SU cita desde "My area", no desde aquí)
// -----------------------------------------------------------------------
@Post('cancel')
@Roles('ADMIN', 'DOCTOR')
async cancel(@Body() body: Record<string, string>, @Res() res: Response): Promise<void> {
const { doctorId, day } = readScheduleRequest(body);
const appointmentId = positiveInteger(body.appointmentId);
if (appointmentId === null) {
throw new BadRequestException();
}
const appointment = await this.application.getAppointmentById(appointmentId);
if (appointment === null) {
// ya cancelada (por otra persona, o por doble clic)
flash(res, { type: 'danger', key: 'ERRORS.APPOINTMENT_NOT_FOUND' });
} else {
await this.application.deleteAppointment(appointment);
flash(res, { type: 'success', key: 'SCHEDULE.CANCELLED' });
}
res.redirect(scheduleUrl(doctorId, day));
}
// -----------------------------------------------------------------------
// ¿quién tiene sesión iniciada y qué puede hacer en esta página?
// -----------------------------------------------------------------------
private async rights(user: ConnectedUser): Promise<Rights> {
if (user.role !== 'USER') {
return { manager: true, patient: null, patientCanBook: false };
}
const patient = await connectedPatient(this.application, user);
const upcoming = await this.application.getClientUpcomingAppointments(patient.id);
return { manager: false, patient, patientCanBook: upcoming.length === 0 };
}
}
// ───────────────────────────────────────────────────────────────── funciones utilitarias
// "3" -> 3 ; "", "abc", "-2", undefined -> null
function positiveInteger(value: unknown): number | null {
const n = Number(value);
return typeof value === 'string' && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}
// los campos ocultos doctorId / day, comunes a ambos formularios POST
function readScheduleRequest(body: Record<string, string>): { doctorId: number; day: string } {
const doctorId = positiveInteger(body.doctorId);
if (doctorId === null || !isValidDate(body.day)) {
throw new BadRequestException(); // -> página "invalid request" (véase HtmlExceptionFilter)
}
return { doctorId, day: body.day };
}
function scheduleUrl(doctorId: number, day: string, book?: number): string {
const params = new URLSearchParams({ doctorId: String(doctorId), day });
if (book !== undefined) {
params.set('book', String(book));
}
return `/schedule?${params.toString()}`;
}
function option(p: Person, selected: boolean): OptionView {
return { id: p.id, label: label(p), selected };
}
// una BusinessException se convierte en un mensaje flash; cualquier otro error es una
// anomalía real, que dejamos propagar hasta HtmlExceptionFilter
function flashBusinessError(res: Response, e: unknown): void {
if (e instanceof BusinessException) {
flash(res, { type: 'danger', key: e.key, params: e.params });
return;
}
throw e;
}
|
La página principal de la aplicación. Recorramos este código sección por sección.
11.14.2.1. La sección de URL de la página
Los comentarios de las líneas 9–14 describen las rutas. Observe que la ventana de reserva no se abre mediante [JavaScript]: es un parámetro de la URL ([book=7]) que indica al servidor que muestre la página con la ventana abierta. El botón “Reservar” es, por tanto, simplemente un enlace. Toda la página queda descrita por su URL: se puede recargar, guardar como favorito o usar el botón “Atrás” del navegador.
11.14.2.2. La plantilla de la vista
- línea 56: el tipo de solicitud para una ruta protegida: una solicitud de [Express] cuyo campo [user] fue establecido por [JwtAuthGuard];
- líneas 62–106: la plantilla de la vista está tipada. La vista recibe únicamente datos ya formateados ([time: "8:00 - 8:20"]) y filtrados según el rol del usuario; no toma ninguna decisión. En [ScheduleRowView] (líneas 68–77), [patient] es igual a [null] cuando el usuario no tiene permiso para ver el nombre del paciente; [bookable] y [appointmentId] determinan si deben mostrarse los botones “Reservar” y “Cancelar” ;
- líneas 109–113: lo que el controlador sabe sobre el usuario que inició sesión.
11.14.2.3. GET /schedule
- líneas 115–116: todas las rutas requieren un usuario que haya iniciado sesión. Sin [@Roles] en la clase, todos los roles tienen acceso a la página;
- líneas 127–132: los tres parámetros de la URL, todos opcionales, recibidos como cadenas y convertidos más adelante;
- líneas 137–145: la fecha solicitada, si es válida; de lo contrario, hoy. Las citas solo pueden reservarse a partir de hoy;
- líneas 148–151: el médico solicitado; de lo contrario, un médico que inició sesión ve su propia agenda;
- línea 153: la lista desplegable de médicos, obtenida del caché;
- líneas 157–184: el calendario, calculado por la capa de negocio, se convierte en filas de una tabla. La línea 175 es el punto de control de privacidad de la aplicación: un paciente recibe únicamente el nombre de su propia cita. Para los demás, el modelo contiene [null], y la vista muestra “Reservado”. El nombre no se oculta simplemente en la vista: nunca se envía al navegador;
- líneas 188–198: la ventana de reserva se abre solo si el intervalo solicitado puede reservarse por ese usuario. Un administrador selecciona al paciente de una lista; un paciente reserva para sí mismo;
- líneas 200–210: la plantilla [info] explica a un paciente que ya tiene una cita por qué no ve un botón “Reservar”.
11.14.2.4. POST /schedule/book
- línea 225: los tres roles pueden hacer una reserva;
- línea 231: los campos [doctorId] y [day], que están ocultos en el formulario, permiten al usuario volver al calendario mostrado;
- líneas 238–239: para un paciente, el campo [clientId] se ignora: el paciente siempre reserva para sí mismo. Confiar en este campo, enviado por el navegador, permitiría a un paciente malintencionado reservar en nombre de otra persona;
- Líneas 242–246: un administrador que no ha seleccionado un paciente regresa a la ventana de reserva, junto con un mensaje;
- líneas 251–254: el intervalo debe existir y pertenecer al médico del calendario;
- líneas 256–261: las reglas de la lógica de negocio las verifica la capa de negocio. Para un paciente, el mensaje “Este paciente ya tiene una cita próxima” se reemplaza por un mensaje dirigido directamente al paciente;
- Línea 275: patrón PRG: sea cual sea el resultado, se muestra un mensaje emergente y se redirige al calendario.
11.14.2.5. POST /schedule/cancel
Líneas 282–299: reservado para los administradores; un paciente cancela su cita desde “Mi área”. Una cita que ya fue cancelada (por doble clic o por otro administrador) devuelve un mensaje de error, no una página de error.
11.14.2.6. Permisos y funciones de utilidad
- Líneas 304–311: un administrador tiene todos los permisos; un paciente puede hacer una reserva si no tiene citas próximas;
- líneas 317–320: conversión segura de un parámetro en un identificador;
- líneas 323–329: los campos ocultos no válidos solo pueden provenir de una solicitud elaborada manualmente: error 400;
- líneas 331–337: [URLSearchParams] construye una cadena de consulta correctamente codificada;
- líneas 345–351: una [BusinessException] se convierte en un mensaje flash; cualquier otra excepción se propaga hasta el filtro de excepciones.
11.14.3. src/web/controllers/persons.controller.ts
| // =========================================================================
// web/controllers/persons.controller.ts
// -------------------------------------------------------------------------
// La gestión de los médicos y la de los clientes (reservada al ADMIN) son
// IDÉNTICAS: misma lista, mismo formulario, mismas reglas. En lugar de
// escribir las mismas rutas dos veces, las escribimos una sola vez en esta
// clase ABSTRACTA, heredada por DoctorsController (@Controller('doctors'))
// y ClientsController (@Controller('clients')). Cada subclase solo
// tiene que proporcionar su "configuración": qué métodos llamar, qué
// etiquetas mostrar.
//
// Los decoradores de ruta (@Get, @Post...) definidos AQUÍ se heredan: NestJS
// recorre toda la cadena de prototipos de la clase del controlador. Por
// lo tanto, obtenemos, para cada una de las dos subclases:
//
// GET /doctors lista
// GET /doctors/add formulario vacío
// POST /doctors/add creación
// GET /doctors/:id/edit formulario prellenado
// POST /doctors/:id/edit actualización
// POST /doctors/:id/delete eliminación
//
// (y las mismas URL bajo /clients). Las vistas también se comparten:
// views/persons/list.hbs y views/persons/form.hbs.
// =========================================================================
import { Body, Get, HttpCode, NotFoundException, Param, ParseIntPipe, Post, Render, Res } from '@nestjs/common';
import { Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { PersonData } from '../../business/business.interface';
import { BusinessException } from '../../business/business.exception';
import { Person } from '../../entities/person.entity';
import { flash } from '../view-context';
import {
BUSINESS_ERROR_FIELDS,
FormErrors,
invalidFields,
titleOptions,
validateForm,
} from '../helpers/form.helper';
import { PersonFormDto } from '../models/person-form.dto';
// las claves de traducción específicas de cada tipo de persona
export interface PersonKeys {
title: string; // "Doctors"
add: string; // "Add a doctor"
edit: string; // "Edit a doctor"
empty: string; // "No doctors."
confirmDelete: string; // "Delete this doctor and their account?"
added: string; // "Doctor {name} has been added (login: {login})."
edited: string;
deleted: string;
}
export interface PersonsConfig<T extends Person> {
url: string; // '/doctors' o '/clients'
keys: PersonKeys;
list(): Promise<T[]>;
find(id: number): Promise<T | null>;
add(data: PersonData): Promise<T>;
edit(id: number, data: PersonData): Promise<T>;
delete(id: number): Promise<void>;
}
// los valores mostrados en los campos del formulario
interface FormValues {
title: string;
firstName: string;
lastName: string;
login: string;
version: number | null;
}
export abstract class PersonsController<T extends Person> {
protected abstract readonly config: PersonsConfig<T>;
constructor(protected readonly application: ApplicationModelService) {}
// -----------------------------------------------------------------------
// GET /doctors (o /clients)
// -----------------------------------------------------------------------
@Get()
@Render('persons/list')
async list() {
const persons = await this.config.list();
return {
pageTitle: this.config.keys.title,
keys: this.config.keys,
addUrl: `${this.config.url}/add`,
persons: persons.map((p) => ({
title: p.title,
firstName: p.firstName,
lastName: p.lastName,
login: p.user?.login ?? '',
editUrl: `${this.config.url}/${p.id}/edit`,
deleteUrl: `${this.config.url}/${p.id}/delete`,
})),
};
}
// -----------------------------------------------------------------------
// GET /doctors/add
// -----------------------------------------------------------------------
@Get('add')
addForm(@Res() res: Response): void {
this.showForm(res, null, { title: 'Mr', firstName: '', lastName: '', login: '', version: null });
}
// -----------------------------------------------------------------------
// POST /doctors/add
// -----------------------------------------------------------------------
@Post('add')
@HttpCode(200) // si el formulario se muestra de nuevo (véase auth.controller.ts)
async add(@Body() body: Record<string, unknown>, @Res() res: Response): Promise<void> {
const { dto, errors } = await validateForm(PersonFormDto, body);
if (errors !== null) {
return this.showForm(res, null, enteredValues(dto), errors);
}
try {
const person = await this.config.add(dto);
flash(res, { type: 'success', key: this.config.keys.added, params: messageParams(person) });
res.redirect(this.config.url);
} catch (e) {
this.showBusinessError(res, null, enteredValues(dto), e);
}
}
// -----------------------------------------------------------------------
// GET /doctors/:id/edit
// ParseIntPipe: si :id no es un entero, NestJS lanza una
// BadRequestException (página "invalid request", véase HtmlExceptionFilter)
// -----------------------------------------------------------------------
@Get(':id/edit')
async editForm(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
const person = await this.config.find(id);
if (person === null) {
throw new NotFoundException();
}
this.showForm(res, id, {
title: person.title,
firstName: person.firstName,
lastName: person.lastName,
login: person.user?.login ?? '',
version: person.version,
});
}
// -----------------------------------------------------------------------
// POST /doctors/:id/edit
// -----------------------------------------------------------------------
@Post(':id/edit')
@HttpCode(200)
async edit(
@Param('id', ParseIntPipe) id: number,
@Body() body: Record<string, unknown>,
@Res() res: Response,
): Promise<void> {
const { dto, errors } = await validateForm(PersonFormDto, body);
if (errors !== null) {
return this.showForm(res, id, enteredValues(dto), errors);
}
try {
const person = await this.config.edit(id, dto);
flash(res, { type: 'success', key: this.config.keys.edited, params: messageParams(person) });
res.redirect(this.config.url);
} catch (e) {
this.showBusinessError(res, id, enteredValues(dto), e);
}
}
// -----------------------------------------------------------------------
// POST /doctors/:id/delete
// (el navegador solicita la confirmación "Are you sure?" antes de
// enviar el formulario, véase public/js/app.js)
// -----------------------------------------------------------------------
@Post(':id/delete')
async delete(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
const person = await this.config.find(id);
try {
await this.config.delete(id);
flash(res, { type: 'success', key: this.config.keys.deleted, params: messageParams(person) });
} catch (e) {
if (!(e instanceof BusinessException)) {
throw e;
}
flash(res, { type: 'danger', key: e.key, params: e.params });
}
res.redirect(this.config.url);
}
// ───────────────────────────────────────────────────────────────── métodos privados
// id === null: formulario de creación; en caso contrario: formulario de edición
// errors : mensaje bajo cada campo rechazado por la validación
// error : EL mensaje de error de la página, mostrado al pie de la página
// (véase views/partials/errors.hbs)
// otherFields : campos que se enmarcan en rojo SIN mensaje propio (p. ej.:
// nombre + apellido de un homónimo - el mensaje está al pie)
private showForm(
res: Response,
id: number | null,
values: FormValues,
errors: FormErrors = {},
error: string | null = null,
otherFields: string[] = [],
): void {
const creating = id === null;
res.render('persons/form', {
pageTitle: creating ? this.config.keys.add : this.config.keys.edit,
creating,
action: creating ? `${this.config.url}/add` : `${this.config.url}/${id}/edit`,
listUrl: this.config.url,
values,
titles: titleOptions(values.title),
errors,
invalidFields: invalidFields(errors, otherFields),
error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
});
}
// una regla de negocio rechazó la escritura: el formulario se muestra de nuevo,
// con lo ingresado por el usuario y el mensaje de la capa de negocio
private showBusinessError(res: Response, id: number | null, values: FormValues, e: unknown): void {
if (!(e instanceof BusinessException)) {
throw e; // anomalía real -> HtmlExceptionFilter (página 500)
}
if (e.key === 'ERRORS.DOCTOR_NOT_FOUND' || e.key === 'ERRORS.PATIENT_NOT_FOUND') {
// eliminado mientras tanto por otro ADMIN: regreso a la lista
flash(res, { type: 'danger', key: e.key });
return res.redirect(this.config.url);
}
// el mensaje va al pie de la página; los campos afectados, si los hay, se
// enmarcan en rojo para que el usuario vea de inmediato qué corregir
this.showForm(res, id, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
}
}
// lo que ingresó el usuario (excepto la contraseña: nunca se devuelve al navegador)
function enteredValues(dto: PersonFormDto): FormValues {
return {
title: dto.title ?? '',
firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
login: dto.login ?? '',
version: dto.version ?? null,
};
}
// {name} y {login} de los mensajes "added / updated / deleted"
function messageParams(person: Person | null): Record<string, string> {
if (person === null) {
return { name: '', login: '' };
}
return { name: `${person.firstName} ${person.lastName}`, login: person.user?.login ?? '' };
}
|
El manejo de médicos y clientes es idéntico. En lugar de escribir dos controladores similares, creamos una clase abstracta de la que heredan ambos controladores.
- líneas 44–53: los textos específicos de cada tipo de persona (claves de traducción);
- líneas 55–63: la configuración que proporciona cada subclase: la URL base, los textos y las funciones que se llamarán para listar, buscar, agregar, modificar y eliminar;
- línea 75: un campo abstracto: cada subclase debe definirlo;
- líneas 82–99: la lista. Los decoradores de ruta aplicados a una clase padre se heredan: [NestJS] los encuentra recorriendo la cadena de prototipos. El modelo contiene, para cada persona, la URL de sus botones;
- líneas 104–107 y 112–126: la adición, en tres pasos, como en el ejemplo 28: validación, capa de negocio, PRG;
- líneas 133–146 y 151–157: la modificación. [ParseIntPipe] rechaza un identificador no numérico (error 400);
- líneas 176–189: la eliminación. La persona se obtiene de antemano para mostrar su nombre en el mensaje de confirmación;
- líneas 199–206: el formulario, tanto para la creación ([id === null]) como para la modificación;
- líneas 223–235: una persona que fue eliminada mientras tanto regresa a la lista; los demás errores de negocio vuelven a mostrar el formulario, con los campos pertinentes resaltados en rojo;
- líneas 239–247: los valores que se volverán a mostrar (nunca la contraseña).
11.14.4. src/web/controllers/doctors.controller.ts
| // =========================================================================
// web/controllers/doctors.controller.ts
// -------------------------------------------------------------------------
// Gestión de los médicos (solo rol ADMIN). Todas las rutas se
// heredan de PersonsController (véase persons.controller.ts): aquí solo
// queda indicar QUÉ llamar y QUÉ etiquetas mostrar.
//
// @Roles('ADMIN') definido en la CLASE se aplica a todas sus rutas,
// incluidas las heredadas (RolesGuard busca los metadatos en el método,
// luego en la clase - véase auth/roles.guard.ts).
// =========================================================================
import { Controller, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ApplicationModelService } from '../application-model.service';
import { Doctor } from '../../entities/doctor.entity';
import { PersonsConfig, PersonsController } from './persons.controller';
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Controller('doctors')
export class DoctorsController extends PersonsController<Doctor> {
protected readonly config: PersonsConfig<Doctor> = {
url: '/doctors',
keys: {
title: 'DOCTORS.TITLE',
add: 'DOCTORS.ADD',
edit: 'DOCTORS.EDIT',
empty: 'DOCTORS.EMPTY',
confirmDelete: 'DOCTORS.DELETE_CONFIRM',
added: 'DOCTORS.ADDED',
edited: 'DOCTORS.UPDATED',
deleted: 'DOCTORS.DELETED',
},
list: () => this.application.getAllDoctors(),
find: (id) => this.application.getDoctorById(id),
add: (data) => this.application.addDoctor(data),
edit: (id, data) => this.application.editDoctor(id, data),
delete: (id) => this.application.deleteDoctor(id),
};
// un constructor explícito, para que TypeScript emita en ESTA clase los
// metadatos de tipo de los parámetros, que NestJS necesita para
// saber qué inyectar (la clase padre, abstracta y sin decorador,
// no los tiene)
constructor(application: ApplicationModelService) {
super(application);
}
}
|
- líneas 21–22: reservado para ADMIN. [@Roles] aplicado a la clase se aplica a todas sus rutas, incluidas las heredadas;
- líneas 25–42: la configuración: las claves de traducción para los médicos y los métodos del caché que se llamarán;
- líneas 48–50: un constructor explícito, aunque solo llame al constructor de la clase padre; esto es lo que permite al compilador generar, para esta clase, los metadatos de tipo que [NestJS] necesita para saber qué inyectar.
11.14.5. src/web/controllers/clients.controller.ts
| // =========================================================================
// web/controllers/clients.controller.ts
// -------------------------------------------------------------------------
// Gestión de los clientes (los PACIENTES del consultorio), solo rol ADMIN.
// Mismo principio que DoctorsController (véanse sus comentarios).
// =========================================================================
import { Controller, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ApplicationModelService } from '../application-model.service';
import { Client } from '../../entities/client.entity';
import { PersonsConfig, PersonsController } from './persons.controller';
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Controller('clients')
export class ClientsController extends PersonsController<Client> {
protected readonly config: PersonsConfig<Client> = {
url: '/clients',
keys: {
title: 'CLIENTS.TITLE',
add: 'CLIENTS.ADD',
edit: 'CLIENTS.EDIT',
empty: 'CLIENTS.EMPTY',
confirmDelete: 'CLIENTS.DELETE_CONFIRM',
added: 'CLIENTS.ADDED',
edited: 'CLIENTS.UPDATED',
deleted: 'CLIENTS.DELETED',
},
list: () => this.application.getAllClients(),
find: (id) => this.application.getClientById(id),
add: (data) => this.application.addClient(data),
edit: (id, data) => this.application.editClient(id, data),
delete: (id) => this.application.deleteClient(id),
};
constructor(application: ApplicationModelService) {
super(application);
}
}
|
El mismo controlador, para los clientes.
11.14.6. src/web/controllers/registration.controller.ts
| // =========================================================================
// web/controllers/registration.controller.ts
// -------------------------------------------------------------------------
// "Create a patient account": un paciente que aún no tiene cuenta
// la crea por sí mismo. Rutas SIN protección (por definición,
// todavía no se tiene cuenta):
//
// POST /register/access botón "Create a patient account" de la página de
// autenticación: verifica el captcha de
// ESA página y luego abre el formulario
// GET /register el formulario
// POST /register la creación, y luego regreso a la página de inicio de sesión
//
// El flujo está protegido contra bots por UN solo captcha, el de la
// página de autenticación:
// 1. el botón "Create a patient account" envía el formulario de inicio de sesión
// a /register/access; si el captcha se escribe correctamente, el servidor
// emite un pase (véase auth/registration-pass.service.ts);
// 2. sin un pase válido, /register redirige a la
// página de autenticación - escribir la URL directamente no sirve de nada;
// 3. el pase se consume al crear la cuenta: un captcha resuelto
// permite crear UNA cuenta;
// 4. además, el número de cuentas creadas por hora y por dirección IP
// está limitado (véase auth/attempt-limiter.service.ts).
//
// La cuenta creada es exactamente la que el ADMIN crearía desde la
// página "Clients" (mismo método de la capa de negocio: addClient), salvo
// que el paciente ELIGE su login y su contraseña (obligatorios, con
// confirmación).
// =========================================================================
import { Body, Controller, Get, HttpCode, Post, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { CaptchaService } from '../../auth/captcha.service';
import { AttemptLimiterService } from '../../auth/attempt-limiter.service';
import { COOKIE_REGISTRATION_PASS, RegistrationPassService } from '../../auth/registration-pass.service';
import { BusinessException } from '../../business/business.exception';
import { flash } from '../view-context';
import {
BUSINESS_ERROR_FIELDS,
FormErrors,
invalidFields,
titleOptions,
validateForm,
} from '../helpers/form.helper';
import { RegistrationFormDto, PASSWORD_MIN } from '../models/person-form.dto';
interface RegistrationValues {
title: string;
firstName: string;
lastName: string;
login: string;
}
@Controller('register')
export class RegistrationController {
constructor(
private readonly application: ApplicationModelService,
private readonly captchaService: CaptchaService,
private readonly limiter: AttemptLimiterService,
private readonly passes: RegistrationPassService,
) {}
// -----------------------------------------------------------------------
// POST /register/access campos: captchaId, captcha (los de la
// página de autenticación; login y password, también enviados, se ignoran)
// -----------------------------------------------------------------------
@Post('access')
access(@Body() body: Record<string, unknown>, @Req() req: Request, @Res() res: Response): void {
const ip = req.ip ?? 'unknown';
// demasiadas cuentas creadas recientemente desde esta dirección: no tiene sentido continuar
const minutes = this.limiter.registrationBlockMinutes(ip);
if (minutes > 0) {
flash(res, { type: 'danger', key: 'ERRORS.TOO_MANY_ACCOUNTS', params: { minutes: String(minutes) } });
return res.redirect('/login');
}
// captcha ausente o incorrecto: regreso a la página de autenticación, con
// una nueva imagen (un fallo cuenta como un fallo de inicio de sesión)
if (!this.captchaService.verify(body.captchaId, body.captcha)) {
this.limiter.loginFailure(ip, '');
flash(res, { type: 'danger', key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
return res.redirect('/login');
}
// captcha correcto: emitimos el pase y abrimos el formulario
res.cookie(COOKIE_REGISTRATION_PASS, this.passes.issue(), this.passes.cookieOptions());
res.redirect('/register');
}
// -----------------------------------------------------------------------
// GET /register
// -----------------------------------------------------------------------
@Get()
form(@Req() req: Request, @Res() res: Response): void {
if (!this.hasPass(req, res)) {
return;
}
this.show(res, { title: 'Mr', firstName: '', lastName: '', login: '' });
}
// -----------------------------------------------------------------------
// POST /register
// -----------------------------------------------------------------------
@Post()
@HttpCode(200) // si el formulario se muestra de nuevo (véase auth.controller.ts)
async create(@Body() body: Record<string, unknown>, @Req() req: Request, @Res() res: Response): Promise<void> {
if (!this.hasPass(req, res)) {
return;
}
const ip = req.ip ?? 'unknown';
const { dto, errors } = await validateForm(RegistrationFormDto, body);
const values: RegistrationValues = {
title: dto.title ?? 'Mr',
firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
login: dto.login ?? '',
};
// 1. ¿demasiadas cuentas creadas recientemente desde esta dirección?
const minutes = this.limiter.registrationBlockMinutes(ip);
if (minutes > 0) {
return this.show(res, values, {}, 'ERRORS.TOO_MANY_ACCOUNTS', [], { minutes: String(minutes) });
}
// 2. todos los errores de entrada a la vez (campos + confirmación):
// el usuario los corrige todos de una vez
const allErrors: FormErrors = { ...(errors ?? {}) };
if (!allErrors.password && !allErrors.confirmation && dto.password !== dto.confirmation) {
allErrors.confirmation = 'ERRORS.PASSWORDS_DIFFER';
}
if (Object.keys(allErrors).length > 0) {
return this.show(res, values, allErrors);
}
// 3. la creación (cliente + cuenta USER, en una transacción)
try {
await this.application.addClient({
title: dto.title,
lastName: dto.lastName,
firstName: dto.firstName,
login: dto.login,
password: dto.password,
});
} catch (e) {
if (!(e instanceof BusinessException)) {
throw e;
}
// login o nombre + apellido ya en uso: el pase sigue siendo válido
return this.show(res, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
}
// 4. el pase se ha usado: no permitirá crear una 2.ª cuenta
this.passes.consume(req.cookies?.[COOKIE_REGISTRATION_PASS]);
res.clearCookie(COOKIE_REGISTRATION_PASS, { path: '/register' });
this.limiter.registrationSuccess(ip);
// 5. regreso a la página de inicio de sesión, con el login prellenado
flash(res, { type: 'success', key: 'REGISTRATION.DONE', params: { login: dto.login } });
res.redirect(`/login?${new URLSearchParams({ login: dto.login }).toString()}`);
}
// ───────────────────────────────────────────────────────────────── métodos privados
// sin pase válido: regreso a la página de autenticación
private hasPass(req: Request, res: Response): boolean {
if (this.passes.isValid(req.cookies?.[COOKIE_REGISTRATION_PASS])) {
return true;
}
flash(res, { type: 'danger', key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
res.redirect('/login');
return false;
}
// el formulario; nunca se devuelve ninguna contraseña al navegador
private show(
res: Response,
values: RegistrationValues,
errors: FormErrors = {},
error: string | null = null,
otherFields: string[] = [],
errorParams?: Record<string, string>,
): void {
res.render('account/registration', {
pageTitle: 'REGISTRATION.TITLE',
values,
titles: titleOptions(values.title),
errors,
invalidFields: invalidFields(errors, otherFields),
error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
errorParams,
passwordMin: PASSWORD_MIN,
});
}
}
|
Comentemos este código:
- líneas 69–91: 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]; véase el ejemplo 20). Se verifica el CAPTCHA de la página; si es correcto, se almacena un pase en una cookie y se redirige al navegador al formulario;
- líneas 96–102: el formulario, pero solo con un pase válido;
- líneas 109–163: creación de la cuenta: pase, límite de tiempo, validación (incluida la verificación de que la contraseña coincide con su confirmación) y creación por la capa de negocio. Luego se consume el pase y se redirige al paciente a la página de inicio de sesión con su nombre de usuario ya rellenado;
- líneas 168–175: sin pase, se regresa a la página de inicio de sesión con un mensaje;
- líneas 178–185: el formulario. [passwordMin] se usa para el texto de ayuda (“Al menos 6 caracteres”).
11.14.7. src/web/controllers/patient-area.controller.ts
| // =========================================================================
// web/controllers/patient-area.controller.ts
// -------------------------------------------------------------------------
// Las páginas PERSONALES del paciente (rol USER), las que ve justo
// después de iniciar sesión:
//
// GET /my-area página de inicio: [Manage my account],
// [View a schedule], y la próxima cita
// POST /my-area/cancel cancela SU cita
// GET /my-account formulario para editar su cuenta
// POST /my-account actualización
// POST /my-account/delete eliminación de la cuenta (y de sus citas)
//
// Regla de oro de este controlador: el paciente afectado es SIEMPRE el del
// token (connectedPatient), nunca un identificador enviado por el navegador.
// Por lo tanto, un paciente no puede ver, ni editar, ni cancelar lo que pertenece
// a otro paciente, ni siquiera fabricando sus propias solicitudes.
//
// Cualquier modificación o eliminación de la cuenta exige la contraseña
// ACTUAL: alguien que encontrara una sesión abierta
// no podría cambiar la contraseña ni eliminar la cuenta. Los errores de
// contraseña actual se cuentan como fallos de inicio de sesión (mismo límite).
// =========================================================================
import { Body, Controller, Get, HttpCode, Post, Render, Req, Res, UseGuards } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { AuthService } from '../../auth/auth.service';
import { AttemptLimiterService } from '../../auth/attempt-limiter.service';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { COOKIE_JWT, jwtCookieOptions } from '../../auth/auth.constants';
import { BusinessException } from '../../business/business.exception';
import { Client } from '../../entities/client.entity';
import { flash } from '../view-context';
import { formatTime, formatDay } from '../helpers/dates.helper';
import { label, connectedPatient } from '../helpers/patient.helper';
import {
BUSINESS_ERROR_FIELDS,
FormErrors,
invalidFields,
titleOptions,
validateForm,
} from '../helpers/form.helper';
import { MyAccountFormDto, PASSWORD_MIN } from '../models/person-form.dto';
type AuthenticatedRequest = Request & { user: ConnectedUser };
interface MyAccountValues {
title: string;
firstName: string;
lastName: string;
login: string;
version: number | null;
}
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('USER')
@Controller()
export class PatientAreaController {
constructor(
private readonly application: ApplicationModelService,
private readonly authService: AuthService,
private readonly limiter: AttemptLimiterService,
) {}
// -----------------------------------------------------------------------
// GET /my-area
// @Res({ passthrough: true }): accedemos a la respuesta (para leer el idioma
// en res.locals) SIN renunciar al funcionamiento normal de @Render.
// -----------------------------------------------------------------------
@Get('my-area')
@Render('patient/area')
async area(@Req() req: AuthenticatedRequest, @Res({ passthrough: true }) res: Response) {
const patient = await connectedPatient(this.application, req.user);
const appointments = await this.application.getClientUpcomingAppointments(patient.id);
return {
pageTitle: 'AREA.TITLE',
patient: label(patient),
appointments: appointments.map((appointment) => ({
id: appointment.id,
day: formatDay(appointment.day, res.locals.lang),
time: `${formatTime(appointment.slot.startHour, appointment.slot.startMinute)} - ${formatTime(appointment.slot.endHour, appointment.slot.endMinute)}`,
doctor: label(appointment.slot.doctor),
// enlace a la agenda del médico en ese día: allí el paciente ve su nombre
scheduleUrl: `/schedule?${new URLSearchParams({ doctorId: String(appointment.slot.doctor.id), day: appointment.day })}`,
})),
};
}
// -----------------------------------------------------------------------
// POST /my-area/cancel campo: appointmentId
// -----------------------------------------------------------------------
@Post('my-area/cancel')
async cancelAppointment(
@Body() body: Record<string, string>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
const appointment = await this.application.getAppointmentById(Number(body.appointmentId) || 0);
// una cita que no existe y una de OTRO paciente reciben
// la misma respuesta: no se revela nada sobre las citas de otras personas
if (appointment === null || appointment.clientId !== patient.id) {
flash(res, { type: 'danger', key: 'ERRORS.APPOINTMENT_NOT_FOUND' });
} else {
await this.application.deleteAppointment(appointment);
flash(res, { type: 'success', key: 'SCHEDULE.CANCELLED' });
}
res.redirect('/my-area');
}
// -----------------------------------------------------------------------
// GET /my-account
// -----------------------------------------------------------------------
@Get('my-account')
async accountForm(@Req() req: AuthenticatedRequest, @Res() res: Response): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
this.show(res, {
title: patient.title,
firstName: patient.firstName,
lastName: patient.lastName,
login: patient.user.login,
version: patient.version,
});
}
// -----------------------------------------------------------------------
// POST /my-account
// -----------------------------------------------------------------------
@Post('my-account')
@HttpCode(200) // si el formulario se muestra de nuevo (véase auth.controller.ts)
async editAccount(
@Body() body: Record<string, unknown>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
const { dto, errors } = await validateForm(MyAccountFormDto, body);
const values: MyAccountValues = {
title: dto.title ?? patient.title,
firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
login: dto.login ?? '',
version: dto.version ?? null,
};
const allErrors: FormErrors = { ...(errors ?? {}) };
if (!allErrors.password && dto.password !== undefined && dto.password !== dto.confirmation) {
allErrors.confirmation = 'ERRORS.PASSWORDS_DIFFER';
}
if (Object.keys(allErrors).length > 0) {
return this.show(res, values, allErrors);
}
// la contraseña actual
const passwordError = await this.checkCurrentPassword(req, patient, dto.currentPassword);
if (passwordError !== null) {
return this.show(
res,
values,
passwordError.key === 'ERRORS.WRONG_CURRENT_PASSWORD' ? { currentPassword: passwordError.key } : {},
passwordError.key,
[],
passwordError.params,
);
}
try {
const client = await this.application.editClient(patient.id, {
title: dto.title,
lastName: dto.lastName,
firstName: dto.firstName,
login: dto.login,
password: dto.password, // undefined = sin cambios
version: dto.version,
});
// el login y el nombre mostrado están EN el token: emitimos uno
// nuevo; de lo contrario, la barra de navegación conservaría el nombre anterior
res.cookie(COOKIE_JWT, this.authService.createToken(client.user), jwtCookieOptions());
flash(res, { type: 'success', key: 'MY_ACCOUNT.UPDATED' });
res.redirect('/my-area');
} catch (e) {
if (!(e instanceof BusinessException)) {
throw e;
}
this.show(res, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
}
}
// -----------------------------------------------------------------------
// POST /my-account/delete campo: deletePassword
// La cuenta, el cliente y TODAS sus citas desaparecen juntos,
// y luego se cierra la sesión del paciente.
// -----------------------------------------------------------------------
@Post('my-account/delete')
async deleteAccount(
@Body() body: Record<string, string>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
const passwordError = await this.checkCurrentPassword(req, patient, body.deletePassword);
if (passwordError !== null) {
flash(res, { type: 'danger', key: passwordError.key, params: passwordError.params });
return res.redirect('/my-account');
}
await this.application.deleteClient(patient.id);
res.clearCookie(COOKIE_JWT, { path: '/' });
flash(res, { type: 'success', key: 'MY_ACCOUNT.DELETED' });
res.redirect('/login');
}
// ───────────────────────────────────────────────────────────────── métodos privados
// null si la contraseña actual es correcta; en caso contrario, la clave del mensaje
private async checkCurrentPassword(
req: Request,
patient: Client,
password: unknown,
): Promise<{ key: string; params?: Record<string, string> } | null> {
const ip = req.ip ?? 'unknown';
const login = patient.user.login;
const minutes = this.limiter.loginBlockMinutes(ip, login);
if (minutes > 0) {
return { key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: String(minutes) } };
}
const ok =
typeof password === 'string' &&
password !== '' &&
(await this.authService.validateUser(login, password)) !== null;
if (!ok) {
this.limiter.loginFailure(ip, login);
return { key: 'ERRORS.WRONG_CURRENT_PASSWORD' };
}
return null;
}
private show(
res: Response,
values: MyAccountValues,
errors: FormErrors = {},
error: string | null = null,
otherFields: string[] = [],
errorParams?: Record<string, string>,
): void {
res.render('patient/account', {
pageTitle: 'MY_ACCOUNT.TITLE',
values,
titles: titleOptions(values.title),
errors,
invalidFields: invalidFields(errors, otherFields),
error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
errorParams,
passwordMin: PASSWORD_MIN,
});
}
}
|
Comentemos este código:
- líneas 59–60: reservado para los pacientes;
- 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 74–91: la página “Mi área”. [@Res({ passthrough: true })] da acceso a la respuesta (para leer el idioma en [res.locals] y formatear la fecha) sin renunciar a [@Render] (véase el ejemplo 05);
- líneas 96–101: cancelación de una cita. Una cita inexistente y la cita de otro paciente reciben la misma respuesta: no se revela ninguna información sobre las citas de otros pacientes;
- líneas 118–128: el formulario de la cuenta, rellenado previamente;
- líneas 133–139: la actualización: validación, verificación de la contraseña actual y luego la capa de lógica de negocio. El token contiene el login y el nombre para mostrar: después de una actualización, se emite un nuevo token (línea 182); de lo contrario, la barra de navegación conservaría el nombre anterior;
- Líneas 198–203: eliminar la cuenta, la ficha y todas las citas (con el mismo método de la capa de negocio que para el ADMIN) y luego cerrar la sesión;
- líneas 219–223: la contraseña actual es obligatoria para cualquier cambio: alguien que encuentre una sesión que se dejó abierta no podría cambiar la contraseña ni eliminar la cuenta. Los errores cuentan como fallos de inicio de sesión;
- líneas 241–248: el formulario.
11.15. Las vistas
Las vistas casi no tienen decisiones que tomar: los controladores ya prepararon su plantilla. Cada vista comienza con un comentario [Handlebars] [{{!-- ... --}}] que describe su función; estos comentarios no aparecen en las páginas enviadas al navegador.
11.15.1. Los archivos de plantilla y parciales
11.15.1.1. views/layout.hbs
| {{!--
==========================================================================
views/layout.hbs
--------------------------------------------------------------------------
La plantilla COMÚN a todas las páginas. hbs la usa automáticamente
(archivo llamado "layout.hbs" en la raíz de la carpeta views): la página
solicitada por el controlador (schedule.hbs, login.hbs...) se inserta en
el lugar de {{{body}}}.
Llaves triples {{{ }}}: el contenido se inserta TAL CUAL, sin
escape; es indispensable aquí, ya que [body] ya es HTML construido.
En todos los demás lugares usamos {{ }}, que escapa los caracteres < > & " '
(protección contra la inyección de HTML mediante un nombre ingresado, por ejemplo).
Mensajes: un éxito se muestra en la parte SUPERIOR de la página ({{> flash}}), un
error en la parte INFERIOR, sobre un fondo rosa claro ({{> errors}}).
Equivalente de src/index.html + app.html del cliente Angular.
==========================================================================
--}}
<!doctype html>
<html lang="{{lang}}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{t pageTitle}} - {{t 'APP.TITLE'}}</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-4">
{{> navbar}}
{{> flash}}
{{{body}}}
{{> errors}}
</div>
{{!-- el diálogo "¿Está seguro?", oculto mientras no se necesite --}}
{{> confirmation}}
<script src="/js/app.js"></script>
</body>
</html>
|
- línea 22: el idioma de la página (véase el ejemplo 22);
- línea 26: el título, traducido: la clave [pageTitle] la proporciona cada acción;
- líneas 32–35: la barra de navegación, el mensaje de éxito, la página y el área de errores;
- líneas 38–39: la ventana de confirmación y su script (véase el ejemplo 21).
11.15.1.2. views/partials/navbar.hbs
| {{!--
views/partials/navbar.hbs - la barra de navegación (insertada mediante {{> navbar}}).
Mismo contenido que el del cliente Angular (título, FR/EN, rol, nombre,
cierre de sesión), más un menú cuyas entradas dependen del rol:
"Médicos" y "Clientes" aparecen solo para el ADMIN. Es solo una
comodidad de visualización: la protección real son los guards de los
controladores (un USER que escribe /doctors a mano obtiene una página 403).
Un paciente (USER) tiene además su menú "Mi espacio".
--}}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{t 'APP.TITLE'}}</span>
{{#if currentUser}}
<ul class="navbar-nav me-auto">
{{#if currentUser.isPatient}}
<li class="nav-item"><a class="nav-link {{active currentPath '/my-'}}" href="/my-area">{{t 'APP.MENU_MY_AREA'}}</a></li>
{{/if}}
<li class="nav-item"><a class="nav-link {{active currentPath '/schedule'}}" href="/schedule">{{t 'APP.MENU_SCHEDULE'}}</a></li>
{{#if currentUser.isAdmin}}
<li class="nav-item"><a class="nav-link {{active currentPath '/doctors'}}" href="/doctors">{{t 'APP.MENU_DOCTORS'}}</a></li>
<li class="nav-item"><a class="nav-link {{active currentPath '/clients'}}" href="/clients">{{t 'APP.MENU_PATIENTS'}}</a></li>
{{/if}}
</ul>
{{else}}
<div class="me-auto"></div>
{{/if}}
<div class="d-flex align-items-center gap-2">
{{!-- FR / EN: enlaces simples (GET /language/fr), el idioma activo resaltado --}}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
<a class="btn {{#if (eq lang 'fr')}}btn-light{{else}}btn-outline-light{{/if}}" href="/language/fr">FR</a>
<a class="btn {{#if (eq lang 'en')}}btn-light{{else}}btn-outline-light{{/if}}" href="/language/en">EN</a>
</div>
{{#if currentUser}}
<span class="badge text-bg-light text-primary">{{currentUser.role}}</span>
<span class="text-white">{{currentUser.name}}</span>
{{!-- logout es un POST: un formulario reducido a su botón --}}
<form method="post" action="/logout" class="m-0">
<button type="submit" class="btn btn-sm btn-outline-light">{{t 'APP.LOGOUT'}}</button>
</form>
{{/if}}
</div>
</nav>
|
- líneas 14–25: los menús dependen del rol: “Mi área” para un paciente, “Médicos” y “Pacientes” para el ADMIN. Esto es solo por comodidad; la seguridad la garantizan las guardias de los controladores;
- líneas 31–34: los enlaces FR / EN;
- líneas 36–43: el rol, el nombre y el botón de cierre de sesión en un formulario POST.
11.15.1.3. views/partials/flash.hbs
| {{!--
views/partials/flash.hbs - el mensaje de ÉXITO establecido por la acción
anterior (cita reservada, médico agregado...), que se muestra una sola
vez, en la parte superior de la página (ver src/web/view-context.ts).
Un mensaje flash de ERROR, por su parte, se muestra al pie de la página, mediante
views/partials/errors.hbs.
--}}
{{#if (eq flash.type 'success')}}
<div class="alert alert-success" role="status">
{{t flash.key name=flash.params.name login=flash.params.login minutes=flash.params.minutes}}
</div>
{{/if}}
|
línea 10: el mensaje es una clave; sus posibles parámetros ([name], [login], [minutes]) se pasan al helper [t].
11.15.1.4. views/partials/errors.hbs
| {{!--
==========================================================================
views/partials/errors.hbs - la zona de errores, al PIE de cada página, sobre
un fondo rosa claro (clase .error-zone, ver public/css/styles.css).
Agrupa las dos fuentes de error posibles:
- [error]: el error de la página mostrada (formulario rechazado, login o
nombre + apellido ya usados, fecha inválida, contraseña incorrecta...);
- un mensaje flash de error, establecido por la acción anterior antes de una
redirección (horario ya reservado, eliminación rechazada...).
role="alert": un lector de pantalla anuncia el mensaje en cuanto
se muestra la página, incluso si está al pie.
==========================================================================
--}}
{{#if (or error (eq flash.type 'danger'))}}
<div class="error-zone" role="alert">
{{#if error}}
<div>{{t error minutes=errorParams.minutes}}</div>
{{/if}}
{{#if (eq flash.type 'danger')}}
<div>{{t flash.key name=flash.params.name login=flash.params.login minutes=flash.params.minutes}}</div>
{{/if}}
</div>
{{/if}}
|
Línea 16: el área se muestra si hay un error de página o un mensaje de error flash: el helper [or] combina ambas condiciones, con [eq] usado como subexpresión.
11.15.1.5. views/partials/confirmation.hbs
| {{!--
==========================================================================
views/partials/confirmation.hbs - el diálogo modal "¿Está seguro?".
Reemplaza el cuadro window.confirm() del navegador, que no se puede
personalizar ni traducir (sus botones permanecen en el idioma del
navegador, no en el de la página).
UN solo diálogo para toda la página, oculto (d-none) al inicio. Sus
etiquetas se traducen aquí, desde el servidor, como el resto de la página;
el pequeño script public/js/app.js se limita a mostrarlo, a colocar en él
el mensaje propio del formulario (atributo data-confirmation) y a enviar
el formulario si el usuario confirma.
Mismas clases de Bootstrap que el diálogo de reserva (partials/booking.hbs).
==========================================================================
--}}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="confirmation-modal-title">{{t 'CONFIRMATION.TITLE'}}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{t 'BOOKING_DIALOG.CLOSE_ARIA'}}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
{{!-- "No, volver" en lugar de "Cancelar": la pregunta a veces es
"¿Cancelar esta cita?", y un botón "Cancelar" sería ambiguo --}}
<button type="button" class="btn btn-secondary" data-action="no">{{t 'CONFIRMATION.NO'}}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{t 'CONFIRMATION.YES'}}</button>
</div>
</div>
</div>
</div>
</div>
|
La ventana del ejemplo 21, con etiquetas traducidas y atributos de accesibilidad: [role="alertdialog"], y [aria-labelledby] / [aria-describedby], que especifican el título y el mensaje que lee un lector de pantalla.
11.15.1.6. views/partials/captcha.hbs
| {{!--
==========================================================================
views/partials/captcha.hbs - el captcha de la página de autenticación
(ver src/auth/captcha.service.ts). Protege tanto el inicio de sesión como
el acceso a la creación de cuenta (botón "Crear una cuenta de paciente").
{{{captcha.svg}}}: llaves triples, la imagen SVG se inserta TAL CUAL
en la página. Aquí es seguro porque este SVG lo construye el
propio servidor (biblioteca svg-captcha) y no contiene nada que
provenga del usuario; NUNCA haríamos esto con datos del usuario.
El campo oculto captchaId le indica al servidor QUÉ captcha verificar; la respuesta
correcta, por su parte, nunca se envía al navegador.
"Otra imagen" simplemente recarga la página (path = la URL actual).
==========================================================================
--}}
<div class="mb-3">
<label class="form-label" for="captcha">{{t 'CAPTCHA.LABEL'}}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{t 'CAPTCHA.IMAGE_ALT'}}">{{{captcha.svg}}}</div>
<a class="small" href="{{currentPath}}">{{t 'CAPTCHA.NEW_IMAGE'}}</a>
</div>
<input type="hidden" name="captchaId" value="{{captcha.id}}">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false" required
class="form-control {{#if invalidFields.captcha}}is-invalid{{/if}}">
{{#if errors.captcha}}
<div class="invalid-feedback">{{t errors.captcha}}</div>
{{else}}
<div class="form-text">{{t 'CAPTCHA.HELP'}}</div>
{{/if}}
</div>
|
- línea 20: la imagen SVG, insertada tal cual (triples llaves): la genera el servidor, sin datos del usuario;
- línea 21: “Otra imagen” simplemente vuelve a cargar la página;
- línea 23: el identificador del CAPTCHA, en un campo oculto.
11.15.1.7. views/partials/personFields.hbs
| {{!--
views/partials/personFields.hbs - los campos de identidad (título, nombre,
apellido), comunes a tres formularios: el formulario de médico/cliente del ADMIN,
"Crear una cuenta de paciente" y "Administrar mi cuenta".
El partial usa el modelo de la página que lo inserta: values, titles,
errors (mensaje bajo el campo) e invalidFields (marco rojo).
--}}
<div class="mb-3">
<label class="form-label" for="title">{{t 'PERSONS.TITLE_LABEL'}}</label>
<select id="title" name="title" class="form-select {{#if invalidFields.title}}is-invalid{{/if}}">
{{#each titles}}
<option value="{{value}}" {{#if selected}}selected{{/if}}>{{value}}</option>
{{/each}}
</select>
{{#if errors.title}}<div class="invalid-feedback">{{t errors.title}}</div>{{/if}}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="firstName">{{t 'PERSONS.FIRSTNAME_LABEL'}}</label>
<input id="firstName" name="firstName" type="text" maxlength="20" required
class="form-control {{#if invalidFields.firstName}}is-invalid{{/if}}" value="{{values.firstName}}">
{{#if errors.firstName}}<div class="invalid-feedback">{{t errors.firstName}}</div>{{/if}}
</div>
<div class="col-sm-6">
<label class="form-label" for="lastName">{{t 'PERSONS.LASTNAME_LABEL'}}</label>
<input id="lastName" name="lastName" type="text" maxlength="20" required
class="form-control {{#if invalidFields.lastName}}is-invalid{{/if}}" value="{{values.lastName}}">
{{#if errors.lastName}}<div class="invalid-feedback">{{t errors.lastName}}</div>{{/if}}
</div>
</div>
|
Los campos de identidad, comunes a tres formularios (véase el ejemplo 19). Un parcial insertado sin parámetros usa la plantilla de la página que lo inserta: [values], [titles], [errors], [invalidFields].
11.15.1.8. views/partials/booking.hbs
| {{!--
==========================================================================
views/partials/booking.hbs - el diálogo de reserva.
Misma técnica que el cliente Angular (booking-dialog): las clases Bootstrap
REALES de un diálogo modal (.modal, .modal-backdrop...), hechas
visibles "a la fuerza" (show d-block) en lugar de mediante el JavaScript
de Bootstrap. La diferencia: es el SERVIDOR quien decide mostrarlo
(parámetro &book=... de la URL), y cerrarlo equivale a seguir un enlace
a la misma página sin este parámetro.
==========================================================================
--}}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
<div class="modal-dialog modal-dialog-centered">
<form method="post" action="/schedule/book" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{t 'BOOKING_DIALOG.TITLE'}}</h5>
<a class="btn-close" href="{{backUrl}}" aria-label="{{t 'BOOKING_DIALOG.CLOSE_ARIA'}}"></a>
</div>
<div class="modal-body">
<p>{{t 'BOOKING_DIALOG.SLOT' time=booking.time}}</p>
{{!-- lo que el servidor necesita saber además del paciente elegido --}}
<input type="hidden" name="doctorId" value="{{doctorId}}">
<input type="hidden" name="day" value="{{day}}">
<input type="hidden" name="slotId" value="{{booking.slotId}}">
{{#if booking.patient}}
{{!-- un paciente reserva para sí mismo: no hay lista para elegir
(y el servidor ignora de todos modos cualquier clientId) --}}
<p class="mb-0">{{t 'BOOKING_DIALOG.PATIENT_LABEL'}}: <strong>{{booking.patient}}</strong></p>
{{else}}
<label class="form-label" for="clientId">{{t 'BOOKING_DIALOG.PATIENT_LABEL'}}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{t 'BOOKING_DIALOG.CHOOSE_PATIENT'}}</option>
{{#each booking.clients}}
<option value="{{id}}">{{label}}</option>
{{/each}}
</select>
{{/if}}
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{backUrl}}">{{t 'BOOKING_DIALOG.CANCEL'}}</a>
<button type="submit" class="btn btn-primary">{{t 'BOOKING_DIALOG.CONFIRM'}}</button>
</div>
</form>
</div>
</div>
|
- líneas 13–14: las clases de [Bootstrap] de una ventana modal, hecha visible “de forma fija”: el servidor decide mostrarla;
- línea 19: cerrar la ventana significa seguir un enlace a la misma página, sin el parámetro [book];
- líneas 26–28: los campos ocultos del formulario;
- líneas 30–34: un paciente ve su nombre; un administrador selecciona al paciente de una lista.
11.15.2. Las páginas
11.15.2.1. views/login.hbs
| {{!--
==========================================================================
views/login.hbs - el formulario de inicio de sesión.
Equivalente de features/login/ del cliente Angular. Un <form> HTML
ordinario: el propio navegador envía login, contraseña y respuesta del captcha con
POST /login, sin JavaScript. En caso de fallo, el servidor devuelve ESTA
página, con el login ya ingresado, un captcha NUEVO y [error], mostrado
al pie de la página por el layout.
==========================================================================
--}}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{t 'LOGIN.TITLE'}}</h5>
<form method="post" action="/login">
<div class="mb-3">
<label class="form-label" for="login">{{t 'LOGIN.LOGIN_LABEL'}}</label>
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{login}}" required {{#unless login}}autofocus{{/unless}}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{t 'LOGIN.PASSWORD_LABEL'}}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required {{#if login}}autofocus{{/if}}>
</div>
{{> captcha}}
<button type="submit" class="btn btn-primary w-100">{{t 'LOGIN.SUBMIT'}}</button>
{{!-- aún sin cuenta: un paciente puede crearla por sí mismo.
NO es un simple enlace: es un segundo botón de envío de
ESTE formulario, que va a otra dirección (formaction). Allí el
servidor verifica el captcha de arriba antes de abrir la página
de creación de cuenta (ver RegistrationController).
formnovalidate: el navegador no exige login ni contraseña
(inútiles para crear una cuenta); es el servidor quien verifica el
captcha. Enter en un campo siempre activa el PRIMER
botón del formulario, "Iniciar sesión". --}}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="/register/access" formnovalidate>{{t 'LOGIN.CREATE_ACCOUNT'}}</button>
<div class="form-text text-center">{{t 'LOGIN.CREATE_ACCOUNT_HELP'}}</div>
</form>
<div class="text-muted small mt-3">
{{t 'LOGIN.DEMO_ACCOUNTS'}}
<ul class="mb-0 mt-1">
<li><code>admin</code> - {{t 'LOGIN.DEMO_ADMIN'}}</li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {{t 'LOGIN.DEMO_DOCTOR'}}</li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {{t 'LOGIN.DEMO_USER'}}</li>
</ul>
</div>
</div>
</div>
</div>
|
- línea 20: el cursor se coloca en el campo de login, o en el campo de contraseña si el login ya se conoce;
- línea 28: el CAPTCHA;
- líneas 41–42: el segundo botón envía el mismo formulario a [/register/access] ([formaction]). [formnovalidate]: el navegador no exige un nombre de usuario ni una contraseña, ya que no son necesarios para crear una cuenta.
11.15.2.2. views/schedule.hbs
| {{!--
==========================================================================
views/schedule.hbs - la página principal (ver ScheduleController).
Tres bloques, como los tres componentes del cliente Angular:
1. la elección del médico y del día (<app-doctor-day-picker>)
2. la agenda (<app-agenda>)
3. el diálogo de reserva (<app-booking-dialog>)
==========================================================================
--}}
{{!-- un posible error (fecha inválida, médico desconocido) se muestra
al pie de la página mediante el layout (ver views/partials/errors.hbs) --}}
{{!-- 1. elección del médico y del día: un formulario GET, que simplemente
recarga esta página con ?doctorId=...&day=... en la URL --}}
<form method="get" action="/schedule" class="card p-3 mb-3">
<div class="row g-2 align-items-end">
<div class="col-sm-5">
<label class="form-label" for="doctorId">{{t 'DOCTOR_DAY_PICKER.DOCTOR_LABEL'}}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{t 'DOCTOR_DAY_PICKER.CHOOSE_DOCTOR'}}</option>
{{#each doctors}}
<option value="{{id}}" {{#if selected}}selected{{/if}}>{{label}}</option>
{{/each}}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{t 'DOCTOR_DAY_PICKER.DAY_LABEL'}}</label>
<input id="day" name="day" type="date" class="form-control" value="{{day}}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{t 'DOCTOR_DAY_PICKER.VIEW_SCHEDULE'}}</button>
</div>
</div>
</form>
{{!-- paciente que ya tiene una cita próxima: por eso no hay botón "Reservar" --}}
{{#if info}}
<div class="alert alert-info">
{{t info}} <a href="/my-area" class="alert-link">{{t 'APP.MENU_MY_AREA'}}</a>
</div>
{{/if}}
{{!-- 2. la agenda --}}
{{#if schedule}}
<div class="card p-3">
<h5>{{t 'SCHEDULE.TITLE_PREFIX'}} {{schedule.day}} - {{schedule.doctor}}</h5>
{{#if schedule.rows.length}}
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{t 'SCHEDULE.COLUMN_SLOT'}}</th>
<th>{{t 'SCHEDULE.COLUMN_STATUS'}}</th>
<th></th>
</tr>
</thead>
<tbody>
{{#each schedule.rows}}
<tr {{#if bookable}}class="free-slot"{{/if}}>
<td>{{time}}</td>
<td>
{{!-- [patient] se establece solo si el usuario tiene permiso
para ver este nombre (ADMIN, DOCTOR, o el paciente para SU
cita); de lo contrario, simplemente "Reservada" --}}
{{#if free}}
<span class="badge text-bg-success">{{t 'SCHEDULE.FREE'}}</span>
{{else if patient}}
<span class="badge {{#if mine}}text-bg-primary{{else}}text-bg-secondary{{/if}}">{{patient}}</span>
{{else}}
<span class="badge text-bg-secondary">{{t 'SCHEDULE.BOOKED_BY_OTHER'}}</span>
{{/if}}
</td>
<td>
{{!-- los botones mostrados los decidió el controlador
(bookable, appointmentId) según el rol del usuario --}}
{{#if bookable}}
{{!-- "Reservar" es un enlace simple: reabre esta página
con el diálogo de reserva de este horario --}}
<a class="btn btn-sm btn-outline-success" href="{{bookUrl}}">{{t 'SCHEDULE.BOOK'}}</a>
{{/if}}
{{#if appointmentId}}
{{!-- "Cancelar" MODIFICA datos: por eso es un POST.
@root: el modelo de la PÁGINA (dentro de un {{#each}},
los nombres simples se refieren a los campos de la fila actual) --}}
<form method="post" action="/schedule/cancel" class="m-0"
data-confirmation="{{t 'SCHEDULE.CANCEL_CONFIRM'}}">
<input type="hidden" name="appointmentId" value="{{appointmentId}}">
<input type="hidden" name="doctorId" value="{{@root.doctorId}}">
<input type="hidden" name="day" value="{{@root.day}}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{t 'SCHEDULE.CANCEL_APPOINTMENT'}}</button>
</form>
{{/if}}
</td>
</tr>
{{/each}}
</tbody>
</table>
{{else}}
<p class="text-muted mb-0">{{t 'SCHEDULE.NO_SLOTS'}}</p>
{{/if}}
</div>
{{else}}
<p class="text-muted">{{t 'SCHEDULE.EMPTY_STATE'}}</p>
{{/if}}
{{!-- 3. el diálogo de reserva, solo si la URL contiene &book=... --}}
{{#if booking}}
{{> booking}}
{{/if}}
|
- Líneas 16–35: selección de un médico y una fecha: un formulario GET (véase el ejemplo 17). Un campo [type="date"] envía la fecha en el formato [yyyy-mm-dd];
- Líneas 38–42: un mensaje para un paciente que ya tiene una cita;
- líneas 59–96: una línea por intervalo de tiempo. [{{else if patient}}] enumera los estados en secuencia: disponible, reservado con nombre visible, reservado sin nombre (“Reservado”);
- línea 80: “Reservar” es un enlace;
- líneas 86–92: “Cancelar” es un formulario POST con confirmación. En el bucle, [@root.doctorId] se refiere al campo de la plantilla de la página, no al de la fila;
- líneas 108–110: la ventana de reserva, si el controlador la ha preparado.
11.15.2.3. views/persons/list.hbs
| {{!--
==========================================================================
views/persons/list.hbs - la lista de médicos O de clientes (ADMIN).
Una sola vista para ambos: las etiquetas propias de cada uno llegan en
[keys] (ver DoctorsController / ClientsController).
==========================================================================
--}}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{t keys.title}}</h4>
<a class="btn btn-primary" href="{{addUrl}}">{{t keys.add}}</a>
</div>
<div class="card p-3">
{{#if persons.length}}
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{t 'PERSONS.COLUMN_TITLE'}}</th>
<th>{{t 'PERSONS.COLUMN_FIRSTNAME'}}</th>
<th>{{t 'PERSONS.COLUMN_LASTNAME'}}</th>
<th>{{t 'PERSONS.COLUMN_LOGIN'}}</th>
<th></th>
</tr>
</thead>
<tbody>
{{#each persons}}
<tr>
<td>{{title}}</td>
<td>{{firstName}}</td>
<td>{{lastName}}</td>
<td><code>{{login}}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary" href="{{editUrl}}">{{t 'PERSONS.EDIT'}}</a>
{{!-- data-confirmation: se abrirá un diálogo de confirmación
antes de enviar el formulario (ver public/js/app.js) --}}
<form method="post" action="{{deleteUrl}}" class="m-0"
data-confirmation="{{t @root.keys.confirmDelete}}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{t 'PERSONS.DELETE'}}</button>
</form>
</div>
</td>
</tr>
{{/each}}
</tbody>
</table>
{{else}}
<p class="text-muted mb-0">{{t keys.empty}}</p>
{{/if}}
</div>
|
Una única vista para médicos y clientes: los textos se proporcionan como claves ([keys.title], [keys.add]...). Línea 38: [@root.keys] es necesario en el bucle.
| {{!--
==========================================================================
views/persons/form.hbs - creación O actualización de un médico
o de un cliente (ADMIN). [creating] distingue los dos casos.
Cuando se rechaza la entrada (campo vacío, login ya en uso...), el
controlador devuelve ESTA vista con:
- los valores ya ingresados (values.xxx);
- los campos erróneos enmarcados en rojo (invalidFields.xxx, clase
de Bootstrap "is-invalid");
- bajo un campo rechazado por la validación, su mensaje (errors.xxx);
- el mensaje de error de la página (error), mostrado AL PIE de la página
por el layout (ver views/partials/errors.hbs).
==========================================================================
--}}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{t pageTitle}}</h5>
{{!-- novalidate: dejamos que el SERVIDOR valide (es quien
tiene la última palabra); las verificaciones del navegador (required...) son solo una
comodidad, que un usuario siempre puede eludir --}}
<form method="post" action="{{action}}" novalidate>
{{#unless creating}}
<input type="hidden" name="version" value="{{values.version}}">
{{/unless}}
{{!-- título, nombre, apellido: partial común a tres formularios --}}
{{> personFields}}
<h6 class="mt-4 text-muted">{{t 'PERSONS.ACCOUNT_SECTION'}}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{t 'PERSONS.LOGIN_LABEL'}}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="off"
class="form-control {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
{{#if errors.login}}
<div class="invalid-feedback">{{t errors.login}}</div>
{{else}}
<div class="form-text">{{#if creating}}{{t 'PERSONS.LOGIN_HELP_CREATE'}}{{else}}{{t 'PERSONS.LOGIN_HELP_EDIT'}}{{/if}}</div>
{{/if}}
</div>
<div class="mb-4">
<label class="form-label" for="password">{{t 'PERSONS.PASSWORD_LABEL'}}</label>
{{!-- nunca se rellena previamente: la contraseña nunca vuelve al navegador --}}
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{#if invalidFields.password}}is-invalid{{/if}}">
{{#if errors.password}}
<div class="invalid-feedback">{{t errors.password}}</div>
{{else}}
<div class="form-text">{{#if creating}}{{t 'PERSONS.PASSWORD_HELP_CREATE'}}{{else}}{{t 'PERSONS.PASSWORD_HELP_EDIT'}}{{/if}}</div>
{{/if}}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{t 'PERSONS.SAVE'}}</button>
<a class="btn btn-secondary" href="{{listUrl}}">{{t 'PERSONS.BACK'}}</a>
</div>
</form>
</div>
</div>
</div>
|
- Línea 24: la dirección de envío ([action]) la proporciona el controlador. [novalidate]: el servidor se encarga de validar;
- Líneas 25–27: el número de versión, para una modificación;
- línea 30: los campos de identidad;
- líneas 35–42: el login, con un texto de ayuda o un mensaje de error;
- líneas 46–54: la contraseña, que nunca se rellena previamente.
11.15.2.5. views/account/registration.hbs
| {{!--
==========================================================================
views/account/registration.hbs - "Crear una cuenta de paciente" (página pública,
ver RegistrationController). Mismos campos de identidad que el formulario del
ADMIN (partial personFields), pero el login y la contraseña son
obligatorios, con confirmación.
Aquí NO hay captcha: a esta página solo se puede llegar tras escribir
el de la página de autenticación (botón "Crear una cuenta de paciente").
"Volver al inicio de sesión" lleva de vuelta a la página de autenticación.
==========================================================================
--}}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1">{{t 'REGISTRATION.TITLE'}}</h5>
<p class="text-muted small mb-3">{{t 'REGISTRATION.INTRO'}}</p>
<form method="post" action="/register" novalidate>
{{> personFields}}
<h6 class="mt-4 text-muted">{{t 'PERSONS.ACCOUNT_SECTION'}}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{t 'PERSONS.LOGIN_LABEL'}}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
{{#if errors.login}}
<div class="invalid-feedback">{{t errors.login}}</div>
{{else}}
<div class="form-text">{{t 'REGISTRATION.LOGIN_HELP'}}</div>
{{/if}}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{t 'PERSONS.PASSWORD_LABEL'}}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{#if invalidFields.password}}is-invalid{{/if}}">
{{#if errors.password}}
<div class="invalid-feedback">{{t errors.password min=passwordMin}}</div>
{{else}}
<div class="form-text">{{t 'REGISTRATION.PASSWORD_HELP' min=passwordMin}}</div>
{{/if}}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{t 'ACCOUNT.CONFIRMATION_LABEL'}}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{#if invalidFields.confirmation}}is-invalid{{/if}}">
{{#if errors.confirmation}}<div class="invalid-feedback">{{t errors.confirmation}}</div>{{/if}}
</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{t 'REGISTRATION.SUBMIT'}}</button>
<a class="btn btn-secondary" href="/login">{{t 'REGISTRATION.BACK_TO_LOGIN'}}</a>
</div>
</form>
</div>
</div>
</div>
|
Creación de una cuenta. Línea 42: el texto de ayuda tiene un parámetro (la longitud mínima de la contraseña) que proporciona el controlador.
11.15.2.6. views/patient/area.hbs
| {{!--
==========================================================================
views/patient/area.hbs - "Mi espacio": la página de inicio del paciente
(rol USER), mostrada justo después del inicio de sesión (ver PatientAreaController).
- dos opciones: [Manage my account] y [View a schedule];
- su cita próxima, si la tiene, con el medio para cancelarla.
==========================================================================
--}}
<h4 class="mb-3">{{t 'AREA.HELLO' name=patient}}</h4>
<div class="row g-3 mb-4">
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
<h5 class="mb-1">{{t 'AREA.MANAGE_ACCOUNT'}}</h5>
<span class="text-muted">{{t 'AREA.MANAGE_ACCOUNT_HELP'}}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
<h5 class="mb-1">{{t 'AREA.VIEW_SCHEDULE'}}</h5>
<span class="text-muted">{{t 'AREA.VIEW_SCHEDULE_HELP'}}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{t 'AREA.MY_APPOINTMENT'}}</h5>
{{#if appointments.length}}
{{!-- normalmente solo una (regla "una cita próxima a la vez"),
pero la página puede mostrar varias --}}
{{#each appointments}}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 {{#unless @last}}border-bottom{{/unless}}">
<div>
<div class="fw-semibold">{{day}}, {{time}}</div>
<div class="text-muted">{{doctor}} - <a href="{{scheduleUrl}}">{{t 'AREA.SEE_IN_SCHEDULE'}}</a></div>
</div>
<form method="post" action="/my-area/cancel" class="m-0"
data-confirmation="{{t 'SCHEDULE.CANCEL_CONFIRM'}}">
<input type="hidden" name="appointmentId" value="{{id}}">
<button type="submit" class="btn btn-outline-danger">{{t 'AREA.CANCEL_APPOINTMENT'}}</button>
</form>
</div>
{{/each}}
{{else}}
<p class="text-muted mb-0">{{t 'AREA.NO_APPOINTMENT'}}</p>
{{/if}}
</div>
|
- Línea 9: “Hola Sr. Jean MARTIN”;
- Líneas 13–19: las dos opciones, enlaces;
- líneas 31–43: la cita próxima. [{{#unless @last}}]: un borde separa las citas, excepto después de la última.
11.15.2.7. views/patient/account.hbs
| {{!--
==========================================================================
views/patient/account.hbs - "Administrar mi cuenta" (rol USER).
Dos formularios independientes en la misma página:
1. la actualización (identidad, login, nueva contraseña opcional);
2. la eliminación de la cuenta, que también cancela sus citas.
Ambos requieren la contraseña ACTUAL.
==========================================================================
--}}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{{!-- 1. actualización --}}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{t 'MY_ACCOUNT.TITLE'}}</h5>
<form method="post" action="/my-account" novalidate>
<input type="hidden" name="version" value="{{values.version}}">
{{> personFields}}
<h6 class="mt-4 text-muted">{{t 'PERSONS.ACCOUNT_SECTION'}}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{t 'PERSONS.LOGIN_LABEL'}}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
{{#if errors.login}}<div class="invalid-feedback">{{t errors.login}}</div>{{/if}}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{t 'MY_ACCOUNT.NEW_PASSWORD_LABEL'}}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{#if invalidFields.password}}is-invalid{{/if}}">
{{#if errors.password}}
<div class="invalid-feedback">{{t errors.password min=passwordMin}}</div>
{{else}}
<div class="form-text">{{t 'PERSONS.PASSWORD_HELP_EDIT'}}</div>
{{/if}}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{t 'ACCOUNT.CONFIRMATION_LABEL'}}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{#if invalidFields.confirmation}}is-invalid{{/if}}">
{{#if errors.confirmation}}<div class="invalid-feedback">{{t errors.confirmation}}</div>{{/if}}
</div>
</div>
<div class="mb-4">
<label class="form-label" for="currentPassword">{{t 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL'}}</label>
<input id="currentPassword" name="currentPassword" type="password" maxlength="72" autocomplete="current-password" required
class="form-control {{#if invalidFields.currentPassword}}is-invalid{{/if}}">
{{#if errors.currentPassword}}
<div class="invalid-feedback">{{t errors.currentPassword}}</div>
{{else}}
<div class="form-text">{{t 'MY_ACCOUNT.CURRENT_PASSWORD_HELP'}}</div>
{{/if}}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{t 'PERSONS.SAVE'}}</button>
<a class="btn btn-secondary" href="/my-area">{{t 'MY_ACCOUNT.BACK'}}</a>
</div>
</form>
</div>
{{!-- 2. eliminación --}}
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1">{{t 'MY_ACCOUNT.DELETE_TITLE'}}</h5>
<p class="text-muted small">{{t 'MY_ACCOUNT.DELETE_HELP'}}</p>
<form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{t 'MY_ACCOUNT.DELETE_CONFIRM'}}">
<div class="flex-grow-1">
<label class="form-label" for="deletePassword">{{t 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL'}}</label>
<input id="deletePassword" name="deletePassword" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger">{{t 'MY_ACCOUNT.DELETE_SUBMIT'}}</button>
</form>
</div>
</div>
</div>
|
- líneas 17–65: modificación de la cuenta;
- líneas 72–80: eliminación, con confirmación. Dos formularios independientes en la misma página: cada uno envía solo sus propios campos.
11.15.2.8. views/error.hbs
| {{!--
views/error.hbs - la página de error (403, 404, 400, 500), construida por
HtmlExceptionFilter (src/web/html-exception.filter.ts).
--}}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4 text-center">
<h1 class="display-4 text-danger">{{code}}</h1>
<p class="lead">{{t message}}</p>
<div><a class="btn btn-primary" href="/">{{t 'ERROR_PAGE.BACK'}}</a></div>
</div>
</div>
</div>
|
La página de error del filtro de excepciones: el código HTTP y el mensaje traducido.
11.16. Los diccionarios
11.16.1. i18n/fr.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace"
},
"LOGIN": {
"TITLE": "Connexion",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"SUBMIT": "Se connecter",
"ERROR": "Login ou mot de passe incorrect.",
"DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
"DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
"DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
"DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
"CREATE_ACCOUNT": "Créer un compte client",
"CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Médecin",
"CHOOSE_DOCTOR": "-- choisir un médecin --",
"DAY_LABEL": "Jour",
"VIEW_SCHEDULE": "Voir l'agenda"
},
"SCHEDULE": {
"PAGE_TITLE": "Agenda",
"TITLE_PREFIX": "Agenda du",
"COLUMN_SLOT": "Créneau",
"COLUMN_STATUS": "Statut",
"FREE": "Libre",
"BOOK": "Réserver",
"CANCEL_APPOINTMENT": "Annuler",
"CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
"EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
"NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
"BOOKED": "Rendez-vous enregistré.",
"CANCELLED": "Rendez-vous annulé.",
"BOOKED_BY_OTHER": "Réservé",
"ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
},
"BOOKING_DIALOG": {
"TITLE": "Réserver ce créneau",
"CLOSE_ARIA": "Fermer",
"SLOT": "Créneau de {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choisir un patient --",
"CANCEL": "Annuler",
"CONFIRM": "Confirmer"
},
"PERSONS": {
"COLUMN_TITLE": "Titre",
"COLUMN_FIRSTNAME": "Prénom",
"COLUMN_LASTNAME": "Nom",
"COLUMN_LOGIN": "Login",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"SAVE": "Enregistrer",
"BACK": "Retour à la liste",
"TITLE_LABEL": "Titre",
"FIRSTNAME_LABEL": "Prénom",
"LASTNAME_LABEL": "Nom",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
"LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
"PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"ACCOUNT_SECTION": "Compte utilisateur"
},
"DOCTORS": {
"TITLE": "Médecins",
"ADD": "Ajouter un médecin",
"EDIT": "Modifier un médecin",
"EMPTY": "Aucun médecin.",
"DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
"ADDED": "Le médecin {name} a été ajouté (login : {login}).",
"UPDATED": "Le médecin {name} a été modifié.",
"DELETED": "Le médecin {name} a été supprimé."
},
"CLIENTS": {
"TITLE": "Clients",
"ADD": "Ajouter un client",
"EDIT": "Modifier un client",
"EMPTY": "Aucun client.",
"DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
"ADDED": "Le client {name} a été ajouté (login : {login}).",
"UPDATED": "Le client {name} a été modifié.",
"DELETED": "Le client {name} a été supprimé."
},
"ERROR_PAGE": {
"TITLE": "Erreur",
"BACK": "Retour à l'accueil"
},
"ERRORS": {
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
"SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
"DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
"APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
"INVALID_DATE": "La date demandée n'est pas valide.",
"CHOOSE_PATIENT": "Choisissez un patient.",
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"BAD_REQUEST": "La requête est invalide.",
"FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
"NOT_FOUND": "Cette page n'existe pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
"TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
"WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
"TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
"LOGIN_REQUIRED": "Le login est obligatoire.",
"PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
"PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
"CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
"PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
"CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
"WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
"PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
"CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
},
"CAPTCHA": {
"LABEL": "Recopiez les caractères de l'image",
"IMAGE_ALT": "Image de vérification anti-robots",
"NEW_IMAGE": "Autre image",
"HELP": "Majuscules ou minuscules, peu importe."
},
"REGISTRATION": {
"TITLE": "Créer un compte client",
"INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
"LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_HELP": "Au moins {min} caractères.",
"SUBMIT": "Créer mon compte",
"BACK_TO_LOGIN": "Retour à la connexion",
"DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirmation du mot de passe"
},
"AREA": {
"TITLE": "Mon espace",
"HELLO": "Bonjour {name}",
"MANAGE_ACCOUNT": "Gérer mon compte",
"MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
"VIEW_SCHEDULE": "Voir un agenda",
"VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
"MY_APPOINTMENT": "Mon rendez-vous",
"SEE_IN_SCHEDULE": "voir dans l'agenda",
"CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
"NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
},
"MY_ACCOUNT": {
"TITLE": "Gérer mon compte",
"NEW_PASSWORD_LABEL": "Nouveau mot de passe",
"CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
"CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
"BACK": "Retour à mon espace",
"DELETE_TITLE": "Supprimer mon compte",
"DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
"DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
"DELETE_SUBMIT": "Supprimer mon compte",
"UPDATED": "Votre compte a été modifié.",
"DELETED": "Votre compte a été supprimé."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "Non, revenir",
"YES": "Oui, confirmer"
}
}
|
- Las secciones agrupan los textos por página ([LOGIN], [SCHEDULE], [AREA]...) o por tema ([ERRORS], [CONFIRMATION]);
- línea 80: un texto con dos parámetros, [{name}] y [{login}];
- líneas 98–137: mensajes de error. Son las claves que usan la [BusinessException] de la capa de negocio, los decoradores de validación de formularios y el filtro de excepciones.
11.16.2. i18n/en.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Log out",
"MENU_SCHEDULE": "Schedule",
"MENU_DOCTORS": "Doctors",
"MENU_PATIENTS": "Patients",
"MENU_MY_AREA": "My area"
},
"LOGIN": {
"TITLE": "Login",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"SUBMIT": "Log in",
"ERROR": "Incorrect login or password.",
"DEMO_ACCOUNTS": "Demo accounts (password = login):",
"DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
"DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
"DEMO_USER": "USER role (patients): booking for themselves, managing their account",
"CREATE_ACCOUNT": "Create a patient account",
"CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Doctor",
"CHOOSE_DOCTOR": "-- choose a doctor --",
"DAY_LABEL": "Day",
"VIEW_SCHEDULE": "View schedule"
},
"SCHEDULE": {
"PAGE_TITLE": "Schedule",
"TITLE_PREFIX": "Schedule for",
"COLUMN_SLOT": "Slot",
"COLUMN_STATUS": "Status",
"FREE": "Free",
"BOOK": "Book",
"CANCEL_APPOINTMENT": "Cancel",
"CANCEL_CONFIRM": "Cancel this appointment?",
"EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
"NO_SLOTS": "This doctor has no time slots.",
"BOOKED": "Appointment booked.",
"CANCELLED": "Appointment cancelled.",
"BOOKED_BY_OTHER": "Booked",
"ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
},
"BOOKING_DIALOG": {
"TITLE": "Book this slot",
"CLOSE_ARIA": "Close",
"SLOT": "Slot {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choose a patient --",
"CANCEL": "Cancel",
"CONFIRM": "Confirm"
},
"PERSONS": {
"COLUMN_TITLE": "Title",
"COLUMN_FIRSTNAME": "First name",
"COLUMN_LASTNAME": "Last name",
"COLUMN_LOGIN": "Login",
"EDIT": "Edit",
"DELETE": "Delete",
"SAVE": "Save",
"BACK": "Back to the list",
"TITLE_LABEL": "Title",
"FIRSTNAME_LABEL": "First name",
"LASTNAME_LABEL": "Last name",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
"LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
"PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
"PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
"ACCOUNT_SECTION": "User account"
},
"DOCTORS": {
"TITLE": "Doctors",
"ADD": "Add a doctor",
"EDIT": "Edit a doctor",
"EMPTY": "No doctors.",
"DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
"ADDED": "Doctor {name} has been added (login: {login}).",
"UPDATED": "Doctor {name} has been updated.",
"DELETED": "Doctor {name} has been deleted."
},
"CLIENTS": {
"TITLE": "Patients",
"ADD": "Add a patient",
"EDIT": "Edit a patient",
"EMPTY": "No patients.",
"DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
"ADDED": "Patient {name} has been added (login: {login}).",
"UPDATED": "Patient {name} has been updated.",
"DELETED": "Patient {name} has been deleted."
},
"ERROR_PAGE": {
"TITLE": "Error",
"BACK": "Back to the home page"
},
"ERRORS": {
"LOGIN_TAKEN": "This login is already used by another account.",
"DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
"PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
"DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
"SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
"CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
"DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
"PATIENT_NOT_FOUND": "This patient does not exist (any more).",
"SLOT_NOT_FOUND": "This slot does not exist (any more).",
"APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
"INVALID_DATE": "The requested date is not valid.",
"CHOOSE_PATIENT": "Choose a patient.",
"INVALID_FORM": "The form contains errors.",
"INVALID_TITLE": "Choose a title from the list.",
"FIRSTNAME_REQUIRED": "The first name is required.",
"FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
"LASTNAME_REQUIRED": "The last name is required.",
"LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
"INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
"SESSION_EXPIRED": "Your session has expired: please log in again.",
"BAD_REQUEST": "The request is invalid.",
"FORBIDDEN": "Your role does not allow you to access this page.",
"NOT_FOUND": "This page does not exist.",
"SERVER_ERROR": "An unexpected error occurred. Please try again later.",
"TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
"WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
"TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
"LOGIN_REQUIRED": "The login is required.",
"PASSWORD_REQUIRED": "The password is required.",
"PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
"CONFIRMATION_REQUIRED": "Please confirm the password.",
"PASSWORDS_DIFFER": "The confirmation does not match the password.",
"CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
"WRONG_CURRENT_PASSWORD": "Incorrect current password.",
"PAST_DATE": "Appointments cannot be booked for a past date.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
"CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\"."
},
"CAPTCHA": {
"LABEL": "Type the characters shown in the image",
"IMAGE_ALT": "Anti-robot verification image",
"NEW_IMAGE": "Another image",
"HELP": "Upper or lower case, it does not matter."
},
"REGISTRATION": {
"TITLE": "Create a patient account",
"INTRO": "With this account you can book your own appointments.",
"LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_HELP": "At least {min} characters.",
"SUBMIT": "Create my account",
"BACK_TO_LOGIN": "Back to login",
"DONE": "Your account has been created. You can now log in with the login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirm password"
},
"AREA": {
"TITLE": "My area",
"HELLO": "Hello {name}",
"MANAGE_ACCOUNT": "Manage my account",
"MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
"VIEW_SCHEDULE": "View a schedule",
"VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
"MY_APPOINTMENT": "My appointment",
"SEE_IN_SCHEDULE": "see in the schedule",
"CANCEL_APPOINTMENT": "Cancel this appointment",
"NO_APPOINTMENT": "You have no upcoming appointment."
},
"MY_ACCOUNT": {
"TITLE": "Manage my account",
"NEW_PASSWORD_LABEL": "New password",
"CURRENT_PASSWORD_LABEL": "Current password",
"CURRENT_PASSWORD_HELP": "Required to save any change.",
"BACK": "Back to my area",
"DELETE_TITLE": "Delete my account",
"DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
"DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
"DELETE_SUBMIT": "Delete my account",
"UPDATED": "Your account has been updated.",
"DELETED": "Your account has been deleted."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "No, go back",
"YES": "Yes, confirm"
}
}
|
El diccionario en inglés tiene exactamente las mismas claves.
11.17. Archivos estáticos
11.17.1. public/css/styles.css
| /* =========================================================================
public/css/styles.css - unos pocos ajustes sobre Bootstrap
(tomados de src/styles.css del cliente Angular).
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* -------------------------------------------------------------------------
.error-zone: los mensajes de error, al pie de la página, sobre un fondo rosa claro
(ver views/partials/errors.hbs).
position: sticky + bottom: si la página es más alta que la ventana (una
agenda de 12 intervalos, por ejemplo), la zona se queda pegada al pie de la
ventana en lugar de desaparecer bajo el borde visible - sin tapar nunca
el contenido cuando la página es corta.
z-index: por encima del fondo gris del diálogo de reserva (.modal-backdrop).
------------------------------------------------------------------------- */
.error-zone {
position: sticky;
bottom: 1rem;
z-index: 1060;
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef; /* rosa claro */
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
/* las dos opciones principales de la página "My area" del paciente */
.option-card {
transition: border-color 0.15s, box-shadow 0.15s;
}
.option-card:hover {
border-color: #0d6efd;
box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}
/* la imagen del captcha (SVG de 150 x 50 píxeles) */
.captcha-image svg {
display: block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
|
- Líneas 10–12: un intervalo de tiempo reservable cambia de color al pasar el mouse;
- líneas 23–33: el área de errores, 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 las ventanas modales;
- líneas 36–43: las dos opciones de “Mi área” responden al paso del mouse;
- líneas 46–50: el marco de la imagen del CAPTCHA.
11.17.2. public/js/app.js
| // =========================================================================
// public/js/app.js - el ÚNICO JavaScript de la aplicación.
// -------------------------------------------------------------------------
// Toda la aplicación funciona sin JavaScript. Este script añade una
// comodidad: antes de enviar un formulario que tiene el atributo
// data-confirmation="...", un diálogo modal pregunta "Are you sure?"
// (el diálogo en sí está en la página: views/partials/confirmation.hbs).
// Si JavaScript está desactivado, el formulario simplemente se envía sin
// confirmación - nada se rompe (principio de "mejora progresiva").
//
// ¿Por qué no window.confirm()? Su cuadro no se puede personalizar y sus
// botones permanecen en el idioma del navegador, no en el de la página.
// =========================================================================
(() => {
const modal = document.getElementById('confirmation-modal');
if (!modal) {
return;
}
const message = document.getElementById('confirmation-modal-message');
const noButton = modal.querySelector('.modal-footer [data-action="no"]');
let pendingForm = null; // el formulario que se enviará si el usuario confirma
let previousFocus = null; // el elemento al que se devuelve el foco al cerrar
function open(form) {
pendingForm = form;
previousFocus = document.activeElement;
// textContent (y no innerHTML): el mensaje se muestra como TEXTO,
// nunca se interpreta como HTML
message.textContent = form.dataset.confirmation;
modal.classList.remove('d-none');
// el foco va a "No": una pulsación distraída de Enter no elimina nada
noButton.focus();
}
function close() {
modal.classList.add('d-none');
pendingForm = null;
if (previousFocus) {
previousFocus.focus();
}
}
// 1. interceptamos el envío de los formularios que requieren confirmación
document.querySelectorAll('form[data-confirmation]').forEach((form) => {
form.addEventListener('submit', (event) => {
event.preventDefault();
open(form);
});
});
// 2. los botones del diálogo (Yes / No / cruz de cierre)
modal.addEventListener('click', (event) => {
const action = event.target.closest('[data-action]')?.dataset.action;
if (action === 'yes') {
const form = pendingForm;
close();
// form.submit() envía el formulario SIN volver a disparar el
// evento 'submit': no hay una nueva solicitud de confirmación
form.submit();
} else if (action === 'no') {
close();
} else if (event.target.classList.contains('modal')) {
close(); // clic en el fondo gris, fuera del diálogo
}
});
// 3. teclado: Escape cierra el diálogo; Tab permanece DENTRO del diálogo
// (de lo contrario, el foco iría a la página atenuada, detrás)
modal.addEventListener('keydown', (event) => {
if (event.key === 'Escape') {
close();
} else if (event.key === 'Tab') {
const buttons = [...modal.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (event.shiftKey && document.activeElement === first) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault();
first.focus();
}
}
});
})();
|
El script completo de la ventana de confirmación del ejemplo 21:
- líneas 17–19: una página sin ventana de confirmación no tiene nada que hacer;
- línea 24: el elemento que tenía el foco del teclado antes de que se abriera la ventana, al que se devuelve el foco cuando la ventana se cierra;
- líneas 26–35: el foco se coloca en “No, volver”; una pulsación accidental de Enter no elimina nada;
- líneas 37–43: la ventana se oculta y se restablece el foco;
- Líneas 54–67: “Sí”, “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 dentro de él;
- líneas 71–86: la tecla Esc cierra la ventana; la tecla Tab recorre el foco dentro de la ventana, en lugar de dejarlo pasar a la página atenuada que está detrás.