Skip to content

4. Capítulo 3 - El servidor [NestJS] de la aplicación [RdvMedecins]

Este capítulo detalla, archivo por archivo, el contenido de la carpeta [rdvmedecins-nestjs-server] incluida con este documento. Sigue el mismo formato utilizado a lo largo de este curso: el código fuente, numerado línea por línea, seguido de una sección titulada «Comentemos este código», que explica las líneas que requieren mayor aclaración. Cada carpeta de proyecto contiene además su propio archivo README.md, que incluye una versión condensada de estas explicaciones.

4.1. La base de datos

La estructura de la base de datos [dbrdvmedecins] reproduce la del documento original (2014, Spring 4 / [MySQL] 5): las mismas tablas ([doctors], [clients], [slots], [appointments]), las mismas claves externas y la misma restricción de unicidad. La única novedad, introducida por la etapa de «autenticación» de esta adaptación: la tabla [users].

4.1.1. [database/dbrdvmedecins.sql]

  -- =========================================================================
-- Base de datos [dbrdvmedecins] - MySQL 8
  --
-- Este script reproduce EXACTAMENTE el esquema relacional del documento original
-- (2014, Spring 4 / Spring Data / MySQL 5): mismas tablas, mismas columnas,
-- mismas claves externas, misma restricción de unicidad. Solo el motor de base de datos
-- cambia de nombre (MySQL 5 -> MySQL 8), no la estructura.
  --
-- La tabla [users] aparece ahora (paso de "autenticación" de esta
-- migración). El documento original usaba TRES tablas (users, roles,
-- users_roles) para permitir que un usuario tuviera VARIOS roles.
-- Como esta aplicación solo conoce dos roles mutuamente excluyentes
-- (ADMIN, USER), aquí simplificamos a una sola columna [role]
-- en la tabla [users] en lugar de reconstruir la relación original
-- muchos a muchos - una simplificación didáctica deliberada, documentada
-- en el capítulo "Autenticación" del curso.
 -- =========================================================================

-- empezamos de nuevo con una base de datos vacía en cada ejecución del script (práctico en desarrollo)
 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;

 CREATE DATABASE IF NOT EXISTS dbrdvmedecins CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 USE dbrdvmedecins;

 CREATE TABLE doctors (
   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
 );

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

 CREATE TABLE slots (
   id           INT AUTO_INCREMENT PRIMARY KEY,
   version      INT NOT NULL DEFAULT 0,
   doctor_id    INT NOT NULL,
   start_hour   INT NOT NULL,
   start_minute INT NOT NULL,
   end_hour     INT NOT NULL,
   end_minute   INT NOT NULL,
   CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
 );

 CREATE TABLE appointments (
   id         INT AUTO_INCREMENT PRIMARY KEY,
   version    INT NOT NULL DEFAULT 0,
   day        DATE NOT NULL,
   slot_id    INT NOT NULL,
   client_id  INT NOT NULL,
   CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
   CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
   CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
 );

 CREATE TABLE users (
   id       INT AUTO_INCREMENT PRIMARY KEY,
   version  INT NOT NULL DEFAULT 0,
   login    VARCHAR(30) NOT NULL UNIQUE,
   password VARCHAR(100) NOT NULL,
   name     VARCHAR(40) NOT NULL,
   role     VARCHAR(10) NOT NULL
 );

 INSERT INTO doctors (title, last_name, first_name) VALUES
   ('Mme', 'PELISSIER', 'Marie'), ('Mr', 'TATOU', 'Paul'), ('Melle','DUPONT', 'Sophie');

 INSERT INTO clients (title, last_name, first_name) VALUES
   ('Mr', 'MARTIN', 'Jean'), ('Mme', 'DURAND', 'Alice'),
   ('Melle','BISTROU', 'Brigitte'), ('Mr', 'GERMAN', 'Luc');

 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, 11, 40, 12, 0);

 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, 17, 40, 18, 0);

 INSERT INTO appointments (day, slot_id, client_id) VALUES (CURDATE(), 2, 3);

 INSERT INTO users (login, password, name, role) VALUES
   ('admin', '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator', 'ADMIN'),
   ('user',  '$2b$10$6Cvoion7AgJkpYHw5N0jMuWPf8T90J28En56kWBL9PT0bXt7lwW7.', 'User',          'USER');

Comentemos este código:

  • líneas 20–24: [DROP TABLE IF EXISTS …] : el script parte de una base de datos vacía en cada ejecución, en el orden inverso de las dependencias (comenzando por `appointments`, que referencia a `[slots]` y a `clients`, hasta `users`, a la que nadie hace referencia): [MySQL] se negaría a eliminar una tabla que todavía es referenciada por una clave externa;
  • línea 48: [doctor_id INT NOT NULL], luego la línea 53: [CONSTRAINT fk_slots_doctor FOREIGN KEY …] : una franja horaria siempre pertenece a un médico;
  • línea 64: [CONSTRAINT unq1_appointments UNIQUE (day, slot_id)] : la regla de negocio central de la aplicación: una misma franja horaria en un mismo día solo puede reservarse una vez. Esta restricción, y solo ella, impide una cita duplicada; ni el validador ni la capa de lógica de negocio la vuelven a verificar explícitamente (véase más adelante, addAppointment);
  • líneas 67–74: [CREATE TABLE users (…)] : la tabla añadida en esta etapa. `login` es UNIQUE (dos usuarios no pueden compartir el mismo identificador de inicio de sesión); `password` almacena una contraseña con hash mediante bcrypt (nunca en texto plano); role es 'ADMIN' o 'USER': una simple columna de texto, mientras que el documento original utilizaba tres tablas (users, roles, users_roles) para permitir varios roles por usuario. Como esta aplicación solo requiere dos roles mutuamente excluyentes, la relación muchos a muchos original habría sido excesiva;
  • líneas 91–93: [INSERT INTO users …] : dos cuentas de demostración, admin/admin (rol ADMIN) y user/user (rol USER), con sus contraseñas ya procesadas con hash mediante bcrypt (10 rondas de salt), nunca en texto plano, ni siquiera en este script de demostración.

4.2. Organización por capas

El servidor sigue la estructura por capas del proyecto original:

Image

Cada capa se comunica únicamente con la capa inmediatamente a su derecha, [5-8]: así, el controlador [5] nunca se comunica directamente con la capa [7], por ejemplo. Esto sigue el mismo principio de diseño del proyecto Spring original y hace que cada capa pueda reemplazarse de forma independiente de las demás.

4.3. Las entidades [TypeORM] (src/entities/)

Las entidades son las clases que representan filas de las tablas de la base de datos como objetos TypeScript; son el equivalente directo de las entidades JPA del proyecto original (paquete rdvmedecins.entities).

4.3.1. src/entities/abstract.entity.ts

Image

1
2
3
4
5
6
7
8
9
  import { [PrimaryGeneratedColumn], [VersionColumn] } from 'typeorm';

  export abstract class AbstractEntity {
    @PrimaryGeneratedColumn()
    id: number;

    @VersionColumn()
    version: number;
  }

Comentemos este código:

  • línea 4: [@PrimaryGeneratedColumn()] : declara una clave primaria autoincremental gestionada por el SGBD, el equivalente exacto de @Id + @GeneratedValue(strategy = GenerationType.AUTO) en JPA;
  • línea 7: [@VersionColumn()] : el mecanismo nativo de [TypeORM] para el bloqueo optimista: [TypeORM] incrementa automáticamente esta columna con cada modificación y genera un error si se intenta guardar una entidad cuya versión ya no coincide con la de la base de datos (alguien más la ha modificado entretanto); es el equivalente exacto de @Version en JPA/Hibernate;
  • línea 3: [export abstract class AbstractEntity {] : esta clase no está decorada con [@Entity]: no corresponde por sí sola a ninguna tabla. [TypeORM] denomina a esta técnica «Concrete Table Inheritance»: cada subclase decorada con [@Entity] obtiene su propia tabla, con todas las columnas heredadas; es el equivalente exacto de @MappedSuperclass en JPA.

4.3.2. src/entities/person.entity.ts

  import { [Column] } from 'typeorm';
  import { AbstractEntity } from './abstract.entity';

  export abstract class Person extends AbstractEntity {
    @Column({ length: 5 })
    title: string;

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

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

Comentemos este código:

  • línea 4: [export abstract class Person extends AbstractEntity {] : agrupa los campos comunes a un médico y a un paciente (título, apellido, nombre), a la vez que hereda id/version ([AbstractEntity]). Al igual que su clase padre, no está decorada con [@Entity]: es la contraparte en [TypeORM] de la clase [Personne], que también es @MappedSuperclass, del proyecto original;
  • líneas 5, 8, 11: [@Column({ length: N })] / [@Column({ name: '...', length: N })]: tres columnas de texto de longitud acotada (las dos últimas mapeadas explícitamente a las columnas snake_case last_name y first_name), equivalente a [@Column](length = N) private String ... en JPA.

4.3.3. src/entities/doctor.entity.ts

1
2
3
4
5
6
7
8
9
  import { [Entity], [OneToMany] } from 'typeorm';
  import { Person } from './person.entity';
  import { Slot } from './slot.entity';

  @Entity({ name: 'doctors' })
  export class Doctor extends Person {
    @OneToMany(() => Slot, (slot) => slot.doctor)
    slots: Slot[];
  }

Comentemos este código:

  • línea 5: [@Entity({ name: 'doctors' })] : declara la clase como la entidad de [TypeORM], almacenada en la tabla [doctors]; es el equivalente exacto de [@Entity] + @Table(name = "[doctors]") en JPA;
  • línea 6: [export class Doctor extends Person {] : hereda título/apellido/nombre (de [Person]) e id/version (de [AbstractEntity]), sin tener que volver a declararlos;
  • línea 7: [@OneToMany(() => Slot, (slot) => slot.doctor)] : declara la relación inversa «un médico tiene varias franjas horarias»: una facilidad de navegación, ausente del proyecto original (que la declaraba solo en el otro sentido, del lado de [Creneau]), pero fácil de añadir con TypeORM.

4.3.4. src/entities/client.entity.ts

1
2
3
4
5
  import { [Entity] } from 'typeorm';
  import { Person } from './person.entity';

  @Entity({ name: 'clients' })
  export class Client extends Person {}

Comentemos este código:

  • líneas 4–5: [@Entity({ name: 'clients' }) export class Client extends Person {}] : exactamente el mismo principio que [Doctor], sin relaciones adicionales: una tabla [clients], con las mismas tres columnas heredadas de Person. Recordatorio de vocabulario: [Client] designa aquí a un paciente del consultorio médico (vocabulario del dominio de negocio original), que no debe confundirse con «cliente HTTP».

4.3.5. src/entities/slot.entity.ts

  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;
    @Column({ name: 'start_minute' }) startMinute: number;
    @Column({ name: 'end_hour' }) endHour: number;
   @Column({ name: 'end_minute' }) endMinute: number;

   @ManyToOne(() => Doctor, (doctor) => doctor.slots)
   @JoinColumn({ name: 'doctor_id' })
   doctor: Doctor;

   @RelationId((slot: Slot) => slot.doctor)
   doctorId: number;
 }

Analicemos este código:

  • líneas 7–10: [@Column({ name: 'start_hour' }) startHour: number; …] — los cuatro límites horarios de la franja de la cita (hora y minuto de inicio y de fin), cuatro enteros simples, cada uno mapeado explícitamente a su columna snake_case (start_hour, start_minute, end_hour, end_minute);
  • línea 12: [@ManyToOne(() => Doctor, (doctor) => doctor.slots)] : varias franjas horarias pertenecen al mismo médico. De forma predeterminada, [TypeORM] no carga la relación «doctor» al leer una franja horaria (comportamiento «lazy» predeterminado): debe solicitarse explícitamente (opción relations: [...] en una consulta); exactamente como FetchType.LAZY exigía, del lado de JPA, un `left join fetch` explícito en la consulta JPQL para obtener al médico;
  • línea 13: [@JoinColumn({ name: 'doctor_id' })] : especifica el nombre de la columna de la clave externa en la tabla [slots];
  • línea 16: [@RelationId((slot: Slot) => slot.doctor)] : el equivalente exacto e idiomático, del lado de [TypeORM], del campo de solo lectura idMedecin del proyecto original ([@Column](name = "id_medecin", insertable = false, updatable = false)): expone directamente el valor de la clave externa, sin necesidad de cargar toda la entidad [Doctor]; útil para construir respuestas JSON ligeras (véase más adelante, la capa web).

Nota: un campo [@RelationId] es una columna virtual, calculada a posteriori por [TypeORM]; no es una verdadera columna SQL que pueda utilizarse en una cláusula WHERE de un «query builder» (véase más adelante, [SlotRepository]). Sirve únicamente para obtener el valor de la clave externa una vez cargada la entidad.

4.3.6. src/entities/appointment.entity.ts

  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' })
  @Unique('unq1_appointments', ['day', 'slot'])
  export class Appointment extends AbstractEntity {
    @Column({ type: 'date' })
   day: string;

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

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

   @RelationId((appointment: Appointment) => appointment.client)
   clientId: number;

   @RelationId((appointment: Appointment) => appointment.slot)
   slotId: number;
 }

Comentemos este código:

  • línea 7: [@Unique('unq1_appointments', ['day', 'slot'])] : hace referencia, del lado de [TypeORM], a la restricción SQL del script de la base de datos. Nota: aquí se hace referencia al nombre de la relación («slot»), no al campo [@RelationId] («slotId»); este último es una columna virtual que [TypeORM] no acepta en una restricción @Unique. [TypeORM] mismo mapea 'slot' a su columna real de clave externa (slot_id);
  • línea 9: [@Column({ type: 'date' })] : tipo 'date' (no 'datetime'): solo se conserva el día, no la hora; exactamente como especificaba TemporalType.DATE del lado de JPA;
  • líneas 12–18: [@ManyToOne(...) / @JoinColumn(...)] : dos relaciones, con [Client] y con [Slot], siguiendo el mismo principio que [slot.entity.ts];
  • líneas 20–24: [@RelationId(...)] : los equivalentes de solo lectura de los campos idClient/idCreneau del proyecto original (mismo mecanismo que Slot.doctorId, véase más arriba).

4.3.7. src/entities/user.entity.ts

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

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

  @Entity({ name: 'users' })
  export class User extends AbstractEntity {
    @Column()
    login: string;

   @Column()
   password: string;

   @Column()
   name: string;

   @Column()
   role: Role;
 }

Comentemos este código:

  • línea 4: [export type Role = ‘ADMIN’ | ‘USER’;] : una simple unión de dos cadenas de TypeScript: los únicos dos roles gestionados por la aplicación. Este tipo se reutiliza en todos los demás lugares donde se maneja un rol (roles.decorator.ts, jwt.strategy.ts, el cliente [Angular]…);
  • línea 6: [@Entity({ name: 'users' })] : como las demás entidades, una tabla propia;
  • línea 11: [password: string;] : almacena una contraseña con hash (bcrypt), nunca en texto plano; véase auth.service.ts;
  • línea 17: [role: Role;] : una sola columna, en lugar de la relación muchos a muchos (users/roles/users_roles) del proyecto Spring original. Esta aplicación reconoce solo dos roles mutuamente excluyentes (un usuario es ADMIN o USER, nunca ambos): reconstruir la relación original habría añadido complejidad sin ningún beneficio real. Es una simplificación deliberada con fines didácticos, al igual que la enumeración `[ResponseStatus]` que encontraremos más adelante en este capítulo.

4.4. Objetos de negocio (src/domain/)

Image

Estas clases no corresponden a ninguna tabla de la base de datos: se construyen sobre la marcha combinando varias entidades para representar un concepto útil para la aplicación («la agenda del Dr. Pelissier para el 13/09/2026») pero que no necesita almacenarse tal cual. Equivalen al mismo subdirectorio (o paquete) «domain» del proyecto original.

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

1
2
3
4
5
6
7
8
9
  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
    ) {}
  }

Analicemos este código:

  • línea 4: [export class DoctorDaySlot {] : asocia una franja horaria con la cita que puede programarse en esa franja, para un día determinado;
  • líneas 5–8: [constructor(public slot: Slot, public appointment: Appointment | null) {}] : la sintaxis [public] directamente en los parámetros del constructor es un atajo de TypeScript: declara E inicializa ambas propiedades en una sola línea cada una, sin tener que escribir [this.slot = slot] por separado. [appointment] es null cuando la franja horaria está disponible.

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

  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[],
    ) {}
 }

Comentemos este código:

  • línea 4: [export class DoctorDaySchedule {] : la agenda completa de un médico para un día determinado: el médico en cuestión, el día y la lista de sus franjas horarias (cada una marcada como disponible o reservada; véase [DoctorDaySlot] más arriba);
  • línea 8: [public doctorDaySlots: DoctorDaySlot[],] : calculada por [BusinessService.getDoctorDaySchedule] (véase más adelante); es esta lista la que el controlador convierte a JSON para el cliente Angular.

4.5. La capa DAO (src/repositories/)

La capa DAO (Data Access Object) es la única parte del proyecto que se comunica directamente con TypeORM/MySQL; equivale a las interfaces de Spring Data del proyecto original (paquete rdvmedecins.repositories).

Image

La diferencia más importante que hay que comprender entre Spring Data y [TypeORM]: con Spring Data, bastaba con declarar una interfaz (extends CrudRepository<...>) para obtener automáticamente los métodos básicos (findAll, findOne, save, delete…); el propio Spring generaba al iniciar una clase que la implementaba. Con [TypeORM] no hay generación automática de una implementación a partir de una interfaz: se inyecta directamente el Repository<Entity> genérico que proporciona [TypeORM] (mediante [@InjectRepository]) y se escriben uno mismo los métodos que se desea exponer, apoyándose en los métodos predefinidos de este Repository o utilizando el query builder para consultas más específicas.

4.5.1. src/repositories/doctor.repository.ts

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

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

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

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

Comentemos este código:

  • línea 9: [@InjectRepository(Doctor)] : solicita a [NestJS] que proporcione el Repository<[Doctor]> generado automáticamente por [TypeORM] para la entidad Doctor. Equivale a la inyección automática (@Autowired) de la implementación generada por Spring Data;
  • línea 14: [return this.repository.find();] : equivalente a medecinRepository.findAll(), heredado de CrudRepository;
  • línea 18: [return this.repository.findOneBy({ id });] : equivalente a medecinRepository.findOne(id); devuelve null si ningún médico tiene ese ID (como findOne en Spring Data, en lugar de lanzar una excepción).

4.5.2. src/repositories/client.repository.ts

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

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

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

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

Este archivo es exactamente igual en principio a [DoctorRepository] (véase la explicación anterior), pero aplicado a la entidad [Client] (un paciente).

4.5.3. src/repositories/slot.repository.ts

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

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

   findAll(): Promise<Slot[]> {
     return this.repository.find();
   }

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

   getAllSlots(doctorId: number): Promise<Slot[]> {
     return this.repository
       .createQueryBuilder('s')
       .where('s.doctor = :doctorId', { doctorId })
       .orderBy('s.startHour', 'ASC')
       .addOrderBy('s.startMinute', 'ASC')
       .getMany();
   }
 }

Comentemos este código:

  • líneas 13–19: [findAll() / findById(id)] : idénticos al principio ya visto en [DoctorRepository];
  • línea 21: [getAllSlots(doctorId: number): Promise<Slot[]> {] : una consulta «personalizada», equivalente a la consulta JPQL original select c from [Creneau] c where c.medecin.[id]=?1;
  • línea 23: [.createQueryBuilder(‘s’)] : el alias SQL se llama s, tal como [Creneau] se llama c en JPQL;
  • línea 24: [.where(‘s.doctor = :doctorId’, { doctorId })] : aquí se compara la relación misma (s.doctor), no el campo [@RelationId] (s.doctorId): como se indicó antes (slot.entity.ts), este último no es una columna utilizable en un WHERE. Al comparar la relación con un número, [TypeORM] reconoce que se apunta a su clave externa y genera el SQL correcto, sin un join;
  • líneas 25–26: [.orderBy(‘s.startHour’, ‘ASC’).addOrderBy(‘s.startMinute’, ‘ASC’)] : ordena las franjas horarias cronológicamente, una adición útil que no existía explícitamente en la versión original de Spring.

4.5.4. src/repositories/appointment.repository.ts

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

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

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

   save(appointment: Appointment): Promise<Appointment> {
     return this.repository.save(appointment);
   }

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

   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();
   }
 }

Comentemos este código:

  • líneas 13–18: [findById(id) { … relations: [‘client’, ‘slot’] }] : relations: [...] indica explícitamente a [TypeORM] que cargue también el cliente y la franja horaria asociados (recordatorio: estas relaciones están en modo «lazy» de forma predeterminada; véase slot.entity.ts); útil para construir la respuesta JSON (véase más adelante, getMapForAppointment);
  • línea 21: [return this.repository.save(appointment);] : equivalente a rvRepository.save(new Rv(jour, client, creneau));
  • línea 25: [await this.repository.delete(id);] : equivalente a rvRepository.delete(rv.getId());
  • línea 28: [getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {]: equivalente a la consulta JPQL original: select rv from Rv rv left join fetch rv.client c left join fetch rv.creneau cr where cr.medecin.[id]=?1 and rv.[jour]=?2;
  • líneas 31–32: [.leftJoinAndSelect(‘appointment.client’, ‘client’) / .leftJoinAndSelect(‘appointment.slot’, ‘slot’)] : el equivalente del LEFT JOIN FETCH del JPQL original: obtiene, en una sola consulta SQL, el cliente y la franja horaria asociados a cada cita;
  • línea 33: [.where(‘slot.doctor = :doctorId’, { doctorId })] : condición sobre el médico, obtenida mediante el join con la franja horaria (rv.creneau.medecin.[id]=?1 en JPQL); de nuevo, se compara la relación «doctor», no el campo [@RelationId] correspondiente.

4.5.5. src/repositories/user.repository.ts

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

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

   findByLogin(login: string): Promise<User | null> {
     return this.repository.findOneBy({ login });
   }
 }

Comentemos este código:

  • línea 13: [findByLogin(login: string): Promise<User | null> {] : el único método de búsqueda necesario aquí, utilizado por el inicio de sesión (véase auth.service.ts): reemplaza la búsqueda de roles a través de tres tablas del proyecto original, que dejó de ser necesaria al simplificarse a una sola columna [role] (véase user.entity.ts).

4.6. La capa de negocio (src/business/)

Es aquí, y en ningún otro lugar, donde residen las reglas de negocio de la aplicación; equivale al paquete rdvmedecins.metier del proyecto original.

4.6.1. src/business/business.interface.ts

  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';

  export interface IBusiness {
    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>;
   addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment>;
   deleteAppointment(appointment: Appointment): Promise<void>;
   getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null>;
 }

 export const BUSINESS_TOKEN = 'IBusiness';

Comentemos este código:

  • línea 7: [export interface IBusiness {] : el contrato de la capa de negocio, independiente de su implementación; el equivalente exacto de la interfaz Java [IMetier] del proyecto original;
  • líneas 8–18: once métodos, uno por cada necesidad de la aplicación (listados, búsquedas por ID, adición/eliminación de citas, cálculo de la agenda);
  • línea 21: [export const BUSINESS_TOKEN = ‘IBusiness’;]: definimos un «token» de inyección (InjectionToken) para poder inyectar esta interfaz en el controlador, exactamente como Spring inyectaba la referencia de negocio [IMetier] sin conocer su clase de implementación concreta [Metier]. En TypeScript, las interfaces se eliminan durante la compilación: por lo tanto, no pueden usarse directamente como tokens de inyección ([NestJS]); esta solución alternativa es necesaria (véase su uso en app.module.ts y application-model.service.ts).

4.6.2. src/business/business.service.ts

  import { Injectable } from '@nestjs/common';
  import { IBusiness } from './business.interface';
  import { DoctorRepository } from '../repositories/doctor.repository';
  import { ClientRepository } from '../repositories/client.repository';
  import { SlotRepository } from '../repositories/slot.repository';
  import { AppointmentRepository } from '../repositories/appointment.repository';
  // ... entidades importadas y objetos de negocio (ver arriba)

  @Injectable()
 export class BusinessService implements IBusiness {
   constructor(
     private readonly doctorRepository: DoctorRepository,
     private readonly clientRepository: ClientRepository,
     private readonly slotRepository: SlotRepository,
     private readonly appointmentRepository: AppointmentRepository,
   ) {}

   getAllClients(): Promise<Client[]> { return this.clientRepository.findAll(); }
   getAllDoctors(): Promise<Doctor[]> { return this.doctorRepository.findAll(); }
   getAllSlots(doctorId: number): Promise<Slot[]> {
     return this.slotRepository.getAllSlots(doctorId);
   }
   // ... otros 5 métodos de delegación simples (mismo principio)

   addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment> {
     const appointment = new Appointment();
     appointment.day = day;
     appointment.slot = slot;
     appointment.client = client;
     return this.appointmentRepository.save(appointment);
   }

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

   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 hBookings = new Map<number, Appointment>();
     for (const booking of bookings) {
       hBookings.set(booking.slotId, booking);
     }

     const doctorDaySlots = timeSlots.map((slot) => {
       const appointment = hBookings.get(slot.id) ?? null;
       return new DoctorDaySlot(slot, appointment);
     });

     return new DoctorDaySchedule(doctor, day, doctorDaySlots);
   }
 }

Comentemos este código:

  • línea 10: [export class BusinessService implements IBusiness {]: [@Injectable]() equivale a @Service("business"): esta clase se convierte en un «proveedor» ([NestJS]) que [NestJS] puede construir e inyectar donde sea necesario;
  • líneas 11–16: [constructor(private readonly doctorRepository: …, …) {}] : inyección de los cuatro DAO, equivalente a los cuatro campos @Autowired del proyecto original. [NestJS] elige aquí la inyección por constructor en lugar de la inyección por campo (como hace @Autowired en un campo Java): es el enfoque recomendado en TypeScript; hace explícitas las dependencias y facilita las pruebas;
  • líneas 18–23: la mayoría de los métodos simplemente delegan en la capa DAO, sin lógica de negocio propia;
  • líneas 25–31: [addAppointment(…) { const appointment = new Appointment(); … }]: crea una nueva entidad Appointment y la guarda; es la restricción SQL unq1_appointments (véase más arriba, el script de la base de datos), y solo ella, la que impide una reserva duplicada; aquí no se realiza ninguna verificación explícita; un intento de duplicado desencadenará una excepción SQL, propagada por la capa DAO;
  • línea 37: [async getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null> {] : el único método de la capa de negocio que realiza una verdadera lógica de negocio (los demás solo delegan): calcula la agenda completa de un médico para un día determinado. El algoritmo se reproduce exactamente como en el documento original, en tres pasos;
  • línea 42: [const timeSlots = await this.getAllSlots(doctorId);] : 1. obtener todas las franjas horarias del médico;
  • línea 43: [const bookings = await this.getDoctorDayAppointments(doctorId, day);] : 2. obtener todas las citas del médico para el día solicitado;
  • líneas 45–48: [const hBookings = new Map<number, Appointment>(); …] : estas citas se almacenan en un diccionario indexado por el ID de la franja horaria, para poder recuperarlas rápidamente en el paso siguiente; equivalente al `Map<Long, Rv> hReservations` del código original;
  • líneas 50–53: [const doctorDaySlots = timeSlots.map((slot) => { … })] : 3. para cada franja horaria, se verifica si coincide con alguna de las reservas encontradas: si es así, está «ocupada» (se le asocia la cita encontrada); de lo contrario, está «libre» (appointment = null).

4.7. La capa web (src/web/)

Este es el punto de entrada HTTP de la aplicación; equivale al paquete [rdvmedecins.web] del proyecto original.

Image

4.7.1. src/web/models/response.model.ts

  export enum ResponseStatus {
    OK = 0,
    RESOURCE_NOT_FOUND = 1,
    INVALID_DATE = 2,
    SERVER_ERROR = 3,
  }

  export class ServerResponse<T = unknown> {
    status: ResponseStatus;
   data: T | null;

   constructor(status: ResponseStatus, data: T | null) {
     this.status = status;
     this.data = data;
   }

   static ok<T>(data: T): ServerResponse<T> {
     return new ServerResponse<T>(ResponseStatus.OK, data);
   }

   static error<T = unknown>(status: ResponseStatus, data: T | null = null): ServerResponse<T> {
     return new ServerResponse<T>(status, data);
   }
 }

Comentemos este código:

  • líneas 1–6: [export enum ResponseStatus { … }] : el proyecto Spring original utilizaba números «ad hoc» (0, 1, 2, 3, 4…) cuyo significado variaba de un método de controlador a otro. Esta adaptación aprovecha para consolidar todos los códigos posibles en una única enumeración, más fácil de aprender y de mantener: el comportamiento observable para el cliente (0 = éxito, cualquier otro valor = fallo) sigue siendo estrictamente el mismo;
  • línea 8: [export class ServerResponse<T = unknown> {] : el contenedor común para todas las respuestas JSON del servicio web: { "status": 0, "data": ... }. Novedad respecto al original: esta clase es genérica ([ServerResponse]<T>) gracias a TypeScript, de modo que el tipo de los datos se conoce en tiempo de compilación (p. ej., [ServerResponse]<[Doctor][]>); el lenguaje Java del proyecto original no permitía esto con tanta facilidad con un tipo `Object`;
  • líneas 17–19: [static ok<T>(data: T): ServerResponse<T> {] : un pequeño método «factory» estático, para escribir un código de controlador más legible (ServerResponse.ok([doctors]) en lugar de new [ServerResponse](ResponseStatus.OK, [doctors]));
  • líneas 21–23: [static error<T = unknown>(status: ResponseStatus, data: T | null = null): ServerResponse<T> {] : su contraparte para las respuestas de error.

4.7.2. src/web/models/post-add-appointment.dto.ts

  import { IsDateString, IsInt } from 'class-validator';

  export class PostAddAppointmentDto {
    @IsDateString()
    day: string;

    @IsInt()
    clientId: number;

   @IsInt()
   slotId: number;
 }

Comentemos este código:

  • línea 3: [export class PostAddAppointmentDto {] : describe el formato del cuerpo JSON esperado por la ruta /addAppointment ({ day, clientId, slotId }); un «DTO» (Data Transfer Object), una clase cuyo único propósito es describir el formato de los datos intercambiados, sin ninguna lógica;
  • línea 4: [@IsDateString()] : verifica que la cadena recibida sea efectivamente una fecha válida en formato ISO. Si no lo es, [NestJS] devuelve automáticamente un error HTTP 400 (Bad [Request]) antes de ejecutar el controlador, gracias al [ValidationPipe] global declarado en [main.ts] (véase más adelante);
  • líneas 7, 10: [@IsInt()] : comprueba que el valor recibido sea efectivamente un entero. Estos decoradores, combinados con [ValidationPipe], son el equivalente en [NestJS] de las conversiones automáticas de tipos que Spring MVC realizaba con @RequestBody.

4.7.3. src/web/models/post-delete-appointment.dto.ts

1
2
3
4
5
6
import { IsInt } from 'class-validator';

export class PostDeleteAppointmentDto {
  @IsInt()
  appointmentId: number;
}

Mismo principio que [PostAddAppointmentDto] más arriba, para el cuerpo JSON esperado por /deleteAppointment ({ appointmentId }).

4.7.4. src/web/helpers/static.helper.ts

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

  export function getErrorsForException(exception: unknown): string[] {
    const errors: string[] = [];
    let cause: unknown = exception;
    while (cause instanceof Error) {
      errors.push(cause.message);
      cause = cause.cause;
   }
   if (errors.length === 0) {
     errors.push(String(exception));
   }
   return errors;
 }

 export interface SlotJson {
   id: number; startHour: number; startMinute: number; endHour: number; endMinute: number;
 }

 export function getMapForSlot(slot: Slot | null | undefined): SlotJson | null {
   if (!slot) { return null; }
   return {
     id: slot.id, startHour: slot.startHour, startMinute: slot.startMinute,
     endHour: slot.endHour, endMinute: slot.endMinute,
   };
 }

 export function getListMapForSlots(slots: Slot[]): SlotJson[] {
   return slots.map((slot) => getMapForSlot(slot) as SlotJson);
 }

 export interface AppointmentJson {
   id: number;
   day: string;
   client: { id: number; title: string; lastName: string; firstName: string } | null;
   slot: SlotJson | null;
 }

 export function getMapForAppointment(appointment: Appointment | null | undefined): AppointmentJson | null {
   if (!appointment) { return null; }
   return {
     id: appointment.id,
     day: appointment.day,
     client: appointment.client
       ? { id: appointment.client.id, title: appointment.client.title, lastName: appointment.client.lastName, firstName: appointment.client.firstName }
       : null,
     slot: getMapForSlot(appointment.slot),
   };
 }

 export function getListMapForAppointments(appointments: Appointment[]): AppointmentJson[] {
   return appointments.map((appointment) => getMapForAppointment(appointment) as AppointmentJson);
 }

Comentemos este código:

  • línea 4: [export function getErrorsForException(exception: unknown): string[] {] : equivalente a Static.getErreursForException (Exception exception). Java podía encadenar excepciones (exception.getCause()) para explicar el «porqué» de una excepción; en el JavaScript/TypeScript moderno (ES2022), los errores también tienen una cadena de causas, mediante la propiedad `cause`;
  • líneas 6–10: [while (cause instanceof Error) { … cause = cause.cause; }] : se procesa del mismo modo que en el código Java original, apilando cada mensaje encontrado;
  • líneas 17–19: [export interface SlotJson { … }] : la entidad [Slot] no se devuelve tal cual en JSON: contiene una relación con «doctor» que, si se cargara, duplicaría información que el cliente ya conoce (el cliente ya sabe de qué médico se trata; véase el parámetro {doctorId} de la URL). Por lo tanto, se construye un objeto «a la medida» que contiene solo los campos necesarios para la visualización;
  • línea 21: [export function getMapForSlot(slot: Slot | null | undefined): SlotJson | null {] : equivalente a Static.getMapForCreneau (franja horaria [Creneau]): convierte una entidad en un objeto JSON ligero;
  • línea 29: [export function getListMapForSlots(slots: Slot[]): SlotJson[] {] : su contraparte para una lista completa (equivalente a Static.getListMapForCreneaux);
  • líneas 33–38, 40–50, 52–54: [AppointmentJson / getMapForAppointment / getListMapForAppointments] : mismo principio, aplicado a las citas: el cliente incrustado (appointment.client) también se reduce a los campos necesarios para la visualización.

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

  import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
  import { IBusiness, BUSINESS_TOKEN } from '../business/business.interface';
  // ... entidades, DoctorDaySchedule, getErrorsForException (ver arriba)

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

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

   async onModuleInit(): Promise<void> {
     try {
       this.doctors = await this.business.getAllDoctors();
       this.clients = await this.business.getAllClients();
     } catch (ex) {
       this.messages = getErrorsForException(ex);
     }
   }

   getMessages(): string[] | null {
     return this.messages;
   }

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

   getAllSlots(doctorId: number): Promise<Slot[]> {
     return this.business.getAllSlots(doctorId);
   }
   // ... otros 6 métodos, delegación simple a this.business
 }

Comentemos este código:

  • línea 6: [export class ApplicationModelService implements IBusiness, OnModuleInit {] : equivalente a la clase ApplicationModel del proyecto original: una caché, construida una sola vez al iniciar el servidor, que almacena en memoria la lista de médicos y de clientes (listas cortas que cambian poco, por lo que no hace falta consultarlas en la base de datos en cada solicitud). Esta clase cumple dos funciones, igual que la original: por un lado, una caché y, por el otro, un único punto de entrada del controlador a la capa de negocio; si alguna vez se cambia la estrategia de caché, solo hay que modificar este archivo;
  • línea 11: [constructor(@Inject(BUSINESS_TOKEN) private readonly business: IBusiness) {}]: aquí se inyecta la interfaz [IBusiness] (mediante el token [BUSINESS_TOKEN], véase app.module.ts), no la clase concreta [BusinessService], exactamente como el código Java original escribía `@Autowired private [IMetier] métier;` sin mencionar nunca la clase `Metier`;
  • línea 13: [async onModuleInit(): Promise<void> {] : [OnModuleInit] es la interfaz de «ciclo de vida» de [NestJS], que cumple exactamente el mismo papel que @PostConstruct en Spring: [NestJS] llama automáticamente a onModuleInit() inmediatamente después de que se hayan inyectado todas las dependencias de esta clase;
  • líneas 17–18: [catch (ex) { this.messages = getErrorsForException(ex); }]: si la base de datos no está disponible al iniciar, el error se captura y se almacena en `messages`, en lugar de provocar la caída del servidor; exactamente el comportamiento del proyecto original;
  • línea 26: [async getAllClients(): Promise<Client[]> { return this.clients; }] : las listas de médicos y de clientes provienen de la caché; todo lo demás (línea 29 y siguientes) se delega simplemente en la capa de negocio.

4.7.6. src/web/rdvmedecins.controller.ts

RdvMedecinsController declara las once rutas de la aplicación, que reflejan intencionalmente las del documento original, simplemente traducidas al inglés (/getAllDoctors por /getAllMedecins, /addAppointment por /ajouterRv…) en lugar de «modernizadas» al estilo REST (/doctors, /clients/:id…): el propósito de este documento es comparar las dos implementaciones, no modernizar la API.

  import { Body, Controller, Get, Param, Post, UseGuards } from '@nestjs/common';
  import { ApplicationModelService } from './application-model.service';
  import { ServerResponse, ResponseStatus } from './models/response.model';
  import { PostAddAppointmentDto } from './models/post-add-appointment.dto';
  import { PostDeleteAppointmentDto } from './models/post-delete-appointment.dto';
  import { getErrorsForException, getListMapForSlots, getListMapForAppointments, getMapForAppointment } from './helpers/static.helper';
  // ... entidades
  import { JwtAuthGuard } from '../auth/jwt-auth.guard';
  import { RolesGuard } from '../auth/roles.guard';
 import { Roles } from '../auth/roles.decorator';

 @UseGuards(JwtAuthGuard)
 @Controller()
 export class RdvMedecinsController {
   constructor(private readonly application: ApplicationModelService) {}

   @Get('getAllDoctors')
   async getAllDoctors(): Promise<ServerResponse<Doctor[]>> {
     const messages = this.application.getMessages();
     if (messages !== null) {
       return new ServerResponse(ResponseStatus.SERVER_ERROR, messages as unknown as Doctor[]);
     }
     try {
       return ServerResponse.ok(await this.application.getAllDoctors());
     } catch (e) {
       return ServerResponse.error(ResponseStatus.SERVER_ERROR, getErrorsForException(e) as unknown as Doctor[]);
     }
   }

   // ... getAllClients: mismo principio, sobre Client

   @Get('getAllSlots/:doctorId')
   async getAllSlots(@Param('doctorId') doctorId: string) {
     const id = Number(doctorId);
     const doctor = await this.application.getDoctorById(id);
     if (doctor === null) {
       return ServerResponse.error(ResponseStatus.RESOURCE_NOT_FOUND);
     }
     try {
       const slots = await this.application.getAllSlots(doctor.id);
       return ServerResponse.ok(getListMapForSlots(slots));
     } catch (e) {
       return ServerResponse.error(ResponseStatus.SERVER_ERROR, getErrorsForException(e));
     }
   }

   // ... getDoctorAppointmentsOfDay/:doctorId/:day: verifica isValidDate(day) y luego el mismo principio

   @Get('getDoctorScheduleOfDay/:doctorId/:day')
   async getDoctorScheduleOfDay(@Param('doctorId') doctorId: string, @Param('day') day: string) {
     if (!isValidDate(day)) {
       return ServerResponse.error(ResponseStatus.INVALID_DATE);
     }
     try {
       const schedule = await this.application.getDoctorDaySchedule(Number(doctorId), day);
       if (schedule === null) {
         return ServerResponse.error(ResponseStatus.RESOURCE_NOT_FOUND);
       }
       return ServerResponse.ok({
         doctor: schedule.doctor,
         day: schedule.day,
         slots: schedule.doctorDaySlots.map((s) => ({
           slot: { id: s.slot.id, startHour: s.slot.startHour, startMinute: s.slot.startMinute, endHour: s.slot.endHour, endMinute: s.slot.endMinute },
           appointment: getMapForAppointment(s.appointment),
         })),
       });
     } catch (e) {
       return ServerResponse.error(ResponseStatus.SERVER_ERROR, getErrorsForException(e));
     }
   }

   // ... getDoctorById/:id, getClientById/:id, getSlotById/:id, getAppointmentById/:id:
   // cuatro métodos similares, buscan una entidad por id, RESOURCE_NOT_FOUND en caso contrario

   @UseGuards(RolesGuard)
   @Roles('ADMIN')
   @Post('addAppointment')
   async addAppointment(@Body() post: PostAddAppointmentDto) {
     const client = await this.application.getClientById(post.clientId);
     if (client === null) {
       return ServerResponse.error(ResponseStatus.RESOURCE_NOT_FOUND);
     }
     const slot = await this.application.getSlotById(post.slotId);
     if (slot === null) {
       return ServerResponse.error(ResponseStatus.RESOURCE_NOT_FOUND);
     }
     try {
       const appointment = await this.application.addAppointment(post.day, slot, client);
       return ServerResponse.ok(getMapForAppointment(appointment));
     } catch (e) {
       return ServerResponse.error(ResponseStatus.SERVER_ERROR, getErrorsForException(e));
     }
   }

   @UseGuards(RolesGuard)
   @Roles('ADMIN')
   @Post('deleteAppointment')
   async deleteAppointment(@Body() post: PostDeleteAppointmentDto) {
     const appointment = await this.application.getAppointmentById(post.appointmentId);
    if (appointment === null) {
      return ServerResponse.error(ResponseStatus.RESOURCE_NOT_FOUND);
    }
    try {
      await this.application.deleteAppointment(appointment);
      return ServerResponse.ok(null);
    } catch (e) {
      return ServerResponse.error(ResponseStatus.SERVER_ERROR, getErrorsForException(e));
    }
  }
 }

 function isValidDate(day: string): boolean {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) {
     return false;
   }
   const date = new Date(`${day}T00:00:00Z`);
   return date.toISOString().slice(0, 10) === day;
 }

Comentemos este código:

  • línea 12: [@UseGuards(JwtAuthGuard)] : aplicado a la clase, protege a la vez las once rutas de este controlador: ninguna es accesible sin un token JWT válido (véase el capítulo «Autenticación» más adelante). Equivale a la regla original de Spring Security .antMatchers("/**").hasRole("ADMIN"), salvo que aquí el único requisito es estar autenticado (cualquier rol); la restricción al rol ADMIN se aplica solo a las dos rutas que modifican datos (líneas 75–76 y 95–96);
  • línea 13: [@Controller()] : sin prefijo: por lo tanto, las rutas son exactamente /getAllDoctors, /getAllClients, etc. Equivale a @RestController en Spring: cada valor devuelto por un método se serializa automáticamente como JSON;
  • línea 15: [constructor(private readonly application: ApplicationModelService) {}] : inyección de la caché/fachada, equivalente a @Autowired private ApplicationModel application;
  • líneas 19–22: [const messages = this.application.getMessages(); if (messages !== null) { … }] : primero se verifica que la aplicación se haya inicializado correctamente (véase ApplicationModelService.onModuleInit), equivalente a `if (messages != null) { return new [Reponse](-1, messages); }`;
  • línea 33: [async getAllSlots(@Param('doctorId') doctorId: string) {]: [@Param]('doctorId') obtiene el segmento {doctorId} de la URL, como cadena (similar a @PathVariable(String) en Spring); lo convertimos nosotros mismos en número (línea 34), mientras que Spring lo habría hecho automáticamente para un parámetro declarado como `long`;
  • líneas 35–38: [const doctor = await this.application.getDoctorById(id); if (doctor === null) { … }] : primero obtenemos al médico para verificar que existe antes de continuar (equivalente al método privado getMedecin(id) del controlador original);
  • línea 41: [return ServerResponse.ok(getListMapForSlots(slots));] : convierte la lista de entidades [Slot] en una lista de objetos JavaScript «ligeros» (véase static.helper.ts);
  • línea 59: [return ServerResponse.ok({ doctor: …, day: …, slots: … });] : la agenda se formatea en modo «ligero» para JSON, siguiendo los mismos principios que getMapForSlot/getMapForAppointment;
  • línea 75: [@UseGuards(RolesGuard)], luego la línea 76: [@Roles('ADMIN')] : además de estar autenticado (ya exigido por [@UseGuards] ([JwtAuthGuard]) para la clase), aquí se debe tener el rol ADMIN; el rol USER recibe una respuesta 403 Forbidden (véase roles.guard.ts). [RolesGuard] lee request.user (proporcionado por JwtAuthGuard/JwtStrategy): por lo tanto, debe ejecutarse después de [JwtAuthGuard] ([NestJS] aplica primero los guardias de clase y luego los de método, en el orden en que aparecen);
  • líneas 87–92: [try { const appointment = await this.application.addAppointment(…); … } catch (e) { … }] : en este punto, class-validator (véase [PostAddAppointmentDto]) ya ha verificado que post.[day] es una fecha válida y que post.clientId/post.slotId son efectivamente enteros. La restricción SQL unq1_appointments (day, slot_id) impide que se realicen dos reservas para la misma franja horaria en el mismo día: un intento de duplicado lanzará una excepción, capturada aquí, exactamente como la SQLException del controlador JDBC original;
  • línea 95: misma restricción que en la línea 75, para deleteAppointment: solo el rol ADMIN puede cancelar una cita;
  • línea 112: [function isValidDate(day: string): boolean {] : una pequeña función de utilidad local, equivalente al par SimpleDateFormat("yyyy-MM-dd") + setLenient(false) del código original, que rechazaba, por ejemplo, «2026-13-40» (mes y día no válidos): Date.toISOString() reconstruye la fecha a partir de la cadena recibida; si difiere de la entrada, significa que la fecha no existía.

4.8. Autenticación (src/auth/)

Image

Esta sección documenta la incorporación, en esta etapa del curso, de la autenticación basada en tokens (JWT) y del control de acceso basado en roles (ADMIN/USER), el equivalente funcional de la capa Spring Security del documento original, reescrita con herramientas estándar del ecosistema [NestJS]: [@nestjs/passport] y @nestjs/jwt.

Dos diferencias intencionales respecto al proyecto original, documentadas aquí de una vez por todas:

  1. JWT en lugar de HTTP Basic. El proyecto Spring original enviaba el encabezado Authorization: Basic <login:password en Base64> con cada solicitud: la contraseña (codificada, no cifrada) se transmitía, por lo tanto, por la red en cada llamada. Esta migración utiliza un token en su lugar: JWT (JSON Web Token). La contraseña se presenta una sola vez, al iniciar sesión (POST /login); el servidor devuelve entonces un token firmado, que el cliente incluye después en cada solicitud posterior (encabezado Authorization: Bearer <token>). Esta es la práctica actual para este tipo de API, como ya se mencionó en la conclusión del capítulo anterior.
  2. Un rol por usuario, una sola columna de la base de datos, en lugar de la relación muchos a muchos (users/roles/users_roles) del proyecto original; véase user.entity.ts más arriba.

Un punto de arquitectura que conviene entender antes de leer el código siguiente: cuando un guardia (Guard) rechaza una solicitud (401 Unauthorized, 403 Forbidden), la respuesta nunca pasa por la envoltura habitual [ServerResponse]<T> ({ status, data }): [NestJS] responde directamente en su formato JSON nativo, { statusCode, message, error }. Es una decisión deliberada: los errores de seguridad se tratan antes de entrar al controlador (mediante un guardia), mientras que [ServerResponse]<T> es generado por el controlador para los errores de negocio (recurso no encontrado, fecha no válida, etc.). El cliente [Angular] debe, por lo tanto, distinguir entre estos dos tipos de respuestas de error (véase el capítulo siguiente, auth.interceptor.ts).

4.8.1. src/auth/dto/login.dto.ts

import { IsNotEmpty, IsString } from 'class-validator';

export class LoginDto {
  @IsString()
  @IsNotEmpty()
  login: string;

  @IsString()
  @IsNotEmpty()
  password: string;
}

Comentemos este código:

  • Línea 3: [export class LoginDto {] — describe el formato del cuerpo JSON esperado por POST /login ({ login, password }), con el mismo mecanismo que el DTO ya visto en src/web/models;
  • líneas 4–5, 8–9: [@IsString() @IsNotEmpty()] — verifica que ambos campos sean cadenas no vacías.

Aquí este DTO tiene un fin puramente informativo: en realidad es [LocalStrategy] (véase más abajo) quien lee {login, password} del cuerpo de la solicitud, no un parámetro @Body del controlador. No obstante, [LoginDto] describe al lector el formato exacto que espera esta ruta.

4.8.2. src/auth/login-result.model.ts

1
2
3
4
5
6
7
8
  import { Role } from '../entities/user.entity';

  export interface LoginResult {
    accessToken: string;
    login: string;
    name: string;
    role: Role;
  }

Comentemos este código:

  • línea 3: [export interface LoginResult {] — el formato de los datos devueltos por POST /login en caso de éxito, dentro de la envoltura estándar [ServerResponse]<T>: { "status": 0, "data": { accessToken, login, name, role } };
  • línea 4: [accessToken: string;] — el token JWT que debe incluirse en cada solicitud posterior;
  • línea 7: [role: Role;] — el rol del usuario conectado, para que el cliente [Angular] pueda adaptar su interfaz (véase el capítulo siguiente: se ocultan los botones “Book”/“Cancel” para el rol USER).

4.8.3. src/auth/local.strategy.ts

Una “estrategia” de Passport describe cómo autenticar una solicitud. [LocalStrategy] puede leer un par {login, password} del cuerpo de una solicitud POST y delegar la verificación en AuthService. Se utiliza una sola vez, en la ruta POST /login (mediante [LocalAuthGuard]): todas las demás rutas protegidas usarán entonces [JwtStrategy] (véase más abajo), no esta.

  import { Injectable, UnauthorizedException } from '@nestjs/common';
  import { PassportStrategy } from '@nestjs/passport';
  import { Strategy } from 'passport-local';
  import { AuthService } from './auth.service';
  import { User } from '../entities/user.entity';

  @Injectable()
  export class LocalStrategy extends PassportStrategy(Strategy) {
    constructor(private readonly authService: AuthService) {
     super({ usernameField: 'login', passwordField: 'password' });
   }

   async validate(login: string, password: string): Promise<User> {
     const user = await this.authService.validateUser(login, password);
     if (user === null) {
       throw new UnauthorizedException('incorrect login or password');
     }
     return user;
   }
 }

Analicemos este código:

  • línea 8: [export class LocalStrategy extends PassportStrategy(Strategy) {] — conceptualmente equivalente a la clase AppUserDetailsService del proyecto original con Spring Security: “dadas unas credenciales, indica quién es este usuario”;
  • línea 10: [super({ usernameField: ‘login’, passwordField: ‘password’ });] — de forma predeterminada, passport-local espera en el cuerpo de la solicitud campos llamados “username” y “password”; aquí los renombramos para que coincidan con nuestro DTO ([LoginDto]), que usa “login” en lugar de “username”;
  • línea 13: [async validate(login: string, password: string): Promise<User> {] — Passport la llama automáticamente con los dos campos extraídos de la solicitud. Lo que devuelve se convierte en request.user en el controlador (véase auth.controller.ts);
  • línea 16: [throw new UnauthorizedException(‘incorrect login or password’);] — Passport convierte automáticamente esta excepción en una respuesta HTTP 401 Unauthorized, antes de que siquiera llegue al controlador.

4.8.4. src/auth/jwt.strategy.ts

La segunda estrategia de Passport: puede leer un token JWT del encabezado HTTP Authorization: Bearer <token> de cada solicitud, verificar su firma y extraer la identidad del usuario, sin consultar nunca la base de datos (el token ya contiene todo lo necesario). Este es el mecanismo que protege las once rutas de RdvMedecinsController.

  import { Injectable } from '@nestjs/common';
  import { PassportStrategy } from '@nestjs/passport';
  import { ExtractJwt, Strategy } from 'passport-jwt';

  export interface JwtPayload {
    sub: number;
    login: string;
    role: 'ADMIN' | 'USER';
  }

 export interface ConnectedUser {
   userId: number;
   login: string;
   role: 'ADMIN' | 'USER';
 }

 @Injectable()
 export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
   constructor() {
     super({
       jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
       ignoreExpiration: false,
       secretOrKey: process.env.JWT_SECRET ?? 'dev-secret-to-change-in-production',
     });
   }

   validate(payload: JwtPayload): ConnectedUser {
     return { userId: payload.sub, login: payload.login, role: payload.role };
   }
 }

Comentemos este código:

  • líneas 5–9: [export interface JwtPayload { sub: number; login: string; role: … }] — el formato de la información que elegimos almacenar en el token JWT cuando se generó (véase auth.service.ts); sub (“subject”) es el nombre convencional, en JWT, del campo que contiene el identificador del usuario;
  • líneas 11–15: [export interface ConnectedUser { … }] — lo que contendrá request.user en los controladores una vez verificado el token;
  • línea 18: [export class JwtStrategy extends PassportStrategy(Strategy, ‘jwt’) {] — el segundo argumento 'jwt' da nombre a esta estrategia (a diferencia de [LocalStrategy], que no especificaba ninguno): es el nombre que [JwtAuthGuard] ([AuthGuard]('jwt'), véase más abajo) usa para indicar “utiliza esta estrategia”;
  • línea 21: [jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),] — el token se espera en el encabezado Authorization: Bearer xxx;
  • línea 22: [ignoreExpiration: false,] — si el token ha expirado, Passport lo rechaza (401) antes incluso de llamar a validate();
  • línea 23: [secretOrKey: process.env.JWT_SECRET ?? ‘…’] — la clave secreta utilizada para verificar la firma del token, la misma que se usó para firmarlo (véase auth.module.ts, que la lee de la misma variable de entorno, JWT_SECRET);
  • línea 27: [validate(payload: JwtPayload): ConnectedUser {] — Passport la llama automáticamente una vez verificada la firma del token; convierte el contenido del token en request.user.

4.8.5. src/auth/local-auth.guard.ts

1
2
3
4
5
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class LocalAuthGuard extends AuthGuard('local') {}

Comentemos este código:

  • Línea 5: [export class LocalAuthGuard extends AuthGuard(‘local’) {}] — un "guardia" (Guard) de [NestJS] determina, antes de que se ejecute un método del controlador, si la solicitud está autorizada para acceder a él. [AuthGuard]('local') es una fábrica proporcionada por [@nestjs/passport] que construye un guardia basado en la estrategia de Passport llamada 'local' (implícitamente, [LocalStrategy], a la que no se dio un nombre explícito en su propio constructor). Este guardia solo lo usa la ruta POST /login (véase auth.controller.ts).

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

1
2
3
4
5
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

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

Comentemos este código:

  • línea 5: [export class JwtAuthGuard extends AuthGuard(‘jwt’) {}] — el guardia que protege las once rutas de RdvMedecinsController: exige un token JWT válido (“jwt” remite a [JwtStrategy]; véase más arriba). Sin token, o con un token no válido o expirado, [NestJS] responde automáticamente con un error 401 Unauthorized, incluso antes de llegar al controlador.

4.8.7. src/auth/roles.decorator.ts

1
2
3
4
5
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);

Comentemos este código:

  • línea 5: [export const Roles = (…roles: Role[]) => SetMetadata(ROLES_KEY, roles);] — [@Roles]('ADMIN') es un decorador personalizado (lo escribimos nosotros, a diferencia de @Get, @Post y @Injectable, que proporciona [NestJS]): se limita a asociar metadatos (“este método requiere tal o cual rol”) al método que decora, sin realizar ninguna verificación por sí mismo; es [RolesGuard] (más abajo) quien leerá estos metadatos y efectuará la verificación. [SetMetadata](key, value) es la función de bajo nivel de [NestJS] que permite escribir sus “propios” decoradores de este tipo.

4.8.8. src/auth/roles.guard.ts

Segundo nivel de validación, posterior a [JwtAuthGuard]: este solo verifica que el usuario esté correctamente autenticado (un token JWT válido); [RolesGuard] verifica además que el rol del usuario conectado figure entre los requeridos por @Roles en el método de destino.

  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 {
     const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
       context.getHandler(),
       context.getClass(),
     ]);

     if (!requiredRoles || requiredRoles.length === 0) {
       return true;
     }

     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;
   }
 }

Comentemos este código:

  • línea 8: [export class RolesGuard implements CanActivate {] — conceptualmente equivalente a 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 al par de decoradores ([@Roles]) + [Reflector] (que puede volver a leer los metadatos establecidos por un decorador);
  • línea 12: [const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, […])] — se vuelven a leer los metadatos establecidos por [@Roles](...) en el método de destino; getAllAndOverride busca primero en el método (línea 13) y luego en la clase (línea 14);
  • líneas 17–19: [if (!requiredRoles || requiredRoles.length === 0) { return true; }] — no hay metadatos [@Roles](...) para este método: no hay restricciones de rol adicionales ([JwtAuthGuard], en cambio, ya habrá exigido una autenticación válida, sea cual sea el rol);
  • línea 21: [const request = context.switchToHttp().getRequest<{ user: ConnectedUser }>();] — request.user fue proporcionado por JwtStrategy.validate(): [RolesGuard] se ejecuta, por lo tanto, siempre después de [JwtAuthGuard] (véase su orden en [@UseGuards](...), rdvmedecins.controller.ts);
  • Líneas 24–28: [if (!requiredRoles.includes(user.role)) { throw new ForbiddenException(…); }] — si el rol del usuario conectado no figura entre los requeridos, se lanza una excepción 403 Forbidden, con un mensaje que indica el rol recibido y el rol esperado.

4.8.9. src/auth/auth.service.ts

El servicio que se encarga de toda la lógica de autenticación: verificar un par usuario/contraseña y generar el token JWT que se devuelve al cliente una vez validado el usuario.

  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 { LoginResult } from './login-result.model';
  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;
     }
     const passwordCorrect = await bcrypt.compare(password, user.password);
     return passwordCorrect ? user : null;
   }

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

Comentemos este código:

  • línea 10: [export class AuthService {] — conceptualmente equivalente a la clase AppUserDetailsService del proyecto original con Spring Security, combinada aquí con la generación del token;
  • línea 16: [async validateUser(login: string, password: string): Promise<User | null> {] — verifica que exista un usuario con este login y que la contraseña proporcionada coincida; devuelve el usuario si todo es correcto y null en caso contrario;
  • línea 21: [const passwordCorrect = await bcrypt.compare(password, user.password);] — bcrypt.compare() calcula el hash de la contraseña con la misma sal que la almacenada en user.[password] y luego compara los dos resultados; la contraseña almacenada nunca se descifra (el hash no es reversible);
  • línea 25: [login(user: User): LoginResult {] — genera el token JWT para un usuario ya autenticado (lo llama [AuthController], una vez que LocalAuthGuard/LocalStrategy se han completado con éxito);
  • línea 28: [accessToken: this.jwtService.sign(payload),] — jwtService.sign() firma el payload con la clave secreta y el tiempo de expiración configurados en auth.module.ts (JwtModule.register).

4.8.10. src/auth/auth.controller.ts

Una sola ruta: POST /login. Es la única ruta de toda la aplicación que no exige ya un token JWT (puesto que es precisamente la ruta que lo emite).

  import { Controller, Post, Request, UseGuards } from '@nestjs/common';
  import { LocalAuthGuard } from './local-auth.guard';
  import { AuthService } from './auth.service';
  import { ServerResponse } from '../web/models/response.model';
  import { LoginResult } from './login-result.model';
  import { User } from '../entities/user.entity';

  @Controller()
  export class AuthController {
   constructor(private readonly authService: AuthService) {}

   @UseGuards(LocalAuthGuard)
   @Post('login')
   login(@Request() req: { user: User }): ServerResponse<LoginResult> {
     return ServerResponse.ok<LoginResult>(this.authService.login(req.user));
   }
 }

Comentemos este código:

  • línea 12: [@UseGuards(LocalAuthGuard)] — coloca este guardia delante del método: activa LocalStrategy.validate(), que verifica el par login/contraseña. Si la verificación falla, [NestJS] devuelve una respuesta 401 Unauthorized antes incluso de ejecutar el cuerpo de este método;
  • línea 14: [login(@Request() req: { user: User }): ServerResponse<LoginResult> {] — si se llega a este punto, [LocalAuthGuard] tuvo éxito: req.user contiene el usuario devuelto por LocalStrategy.validate(). Observe la ausencia de un parámetro [@Body]([LoginDto]): fue el guardia, y no este método, quien leyó {login, password} del cuerpo de la solicitud;
  • Línea 15: [return ServerResponse.ok<LoginResult>(this.authService.login(req.user));] — genera el token JWT y lo envuelve en la respuesta estándar [ServerResponse]<T>; a diferencia de las respuestas 401/403 de los guardias (véase más arriba), una conexión exitosa pasa por esta envoltura.

4.8.11. src/auth/auth.module.ts

El módulo que gestiona todo lo relacionado con la autenticación. AppModule lo importa una sola vez.

  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 { LocalStrategy } from './local.strategy';
 import { JwtStrategy } from './jwt.strategy';

 @Module({
   imports: [
     TypeOrmModule.forFeature([User]),
     PassportModule,
     JwtModule.register({
       secret: process.env.JWT_SECRET ?? 'dev-secret-to-change-in-production',
       signOptions: { expiresIn: process.env.JWT_EXPIRES_IN ?? '2h' },
     }),
   ],
   controllers: [AuthController],
   providers: [
     AuthService,
     UserRepository,
     LocalStrategy,
     JwtStrategy,
   ],
 })
 export class AuthModule {}

Comentemos este código:

  • línea 14: [TypeOrmModule.forFeature([User]),] — hace inyectable Repository<[User]> (véase repositories/user.repository.ts);
  • línea 15: [PassportModule,] — declara 'jwt' como la estrategia predeterminada de [AuthGuard]() sin argumentos; nuestros guardias siguen especificando explícitamente [AuthGuard]('local')/AuthGuard('jwt') para seguir siendo legibles;
  • líneas 16–19: [JwtModule.register({ secret: …, signOptions: { expiresIn: … } }),] — configura la generación y la verificación de los tokens: la clave secreta de firma (JWT_SECRET, véase .env) y su período de validez (JWT_EXPIRES_IN, p. ej., "2h");
  • líneas 25–26: [LocalStrategy, JwtStrategy,] — registran en Passport la estrategia 'local' y la estrategia 'jwt', respectivamente; sin esta declaración en `providers`, [NestJS] no podría construir estas dos clases.

4.9. Configuración y puesta en marcha

4.9.1. package.json

{
  "name": "rdvmedecins-nestjs-server",
  "version": "1.0.0",
  "description": "NestJS server of the medical appointment booking application [RdvMedecins] - port of the original Spring 4 / Spring Data server",
  "private": true,
  "license": "UNLICENSED",
  "scripts": {
    "build": "nest build",
    "start": "nest start",
    "start:dev": "nest start --watch",
    "start:debug": "nest start --debug --watch",
    "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",
    "class-transformer": "^0.5.1",
    "class-validator": "^0.14.1",
    "dotenv": "^17.4.2",
    "mysql2": "^3.11.0",
    "passport-jwt": "^4.0.1",
    "passport-local": "^1.0.0",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.1",
    "typeorm": "^0.3.20"
  },
  "devDependencies": {
    "@nestjs/cli": "^10.4.5",
    "@types/bcryptjs": "^2.4.6",
    "@types/node": "^20.14.0",
    "@types/passport-jwt": "^4.0.1",
    "@types/passport-local": "^1.0.38",
    "typescript": "^5.5.0"
  }
}

Comentemos este código:

  • líneas 7–13: [“scripts”: { … }] — los comandos `npm run <name>` disponibles. start:dev (usado a lo largo de este documento) recompila y reinicia automáticamente el servidor cada vez que se modifica un archivo .ts (la opción --watch de la CLI de [NestJS], equivalente a devtools de Spring Boot). start:prod lanza directamente el JavaScript ya compilado (dist/main.js), sin pasar por la CLI ni recompilar; este es el modo que se usaría en producción;
  • Líneas 14–31: [“dependencies”: { … }]— los paquetes necesarios para ejecutar el servidor. Contiene el núcleo de [NestJS] ([@nestjs/common], [@nestjs/core], [@nestjs/platform-express]), el paquete de integración de [TypeORM] ([@nestjs/typeorm], typeorm, mysql2, el controlador de [MySQL] que usa [TypeORM]), la validación de DTO (class-validator, class-transformer), la lectura del archivo .env (dotenv) y, aportados por la autenticación (véase el capítulo siguiente), [@nestjs/jwt] y [@nestjs/passport] (la integración de Passport.js con [NestJS]), passport-jwt/passport-local (las dos estrategias de Passport utilizadas) y bcryptjs (hash de contraseñas);
  • líneas 32–39: [“devDependencies”: { … }] — paquetes necesarios solo durante el desarrollo (compilación, tipado), que nunca se incluyen en dist/: la propia CLI de [NestJS] ([@nestjs/cli]), el compilador de TypeScript y las definiciones de tipos (@types/...) de los paquetes de JavaScript que no las incluyen de forma nativa (bcryptjs, passport-jwt, passport-local).

Al igual que con el cliente [Angular] (véase el capítulo siguiente), este es el archivo que lee [npm install] (Capítulo 1) para determinar qué descargar en node_modules/; es el equivalente, en el ecosistema Node/TypeScript, del pom.xml del proyecto Spring original.

4.9.2. [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
  }
}

Comentemos este código:

  • línea 3: [“module”: “commonjs”,] — el formato de los módulos JavaScript producidos por la compilación; commonjs (require/module.exports) sigue siendo el formato que Node.js espera para este tipo de proyecto del lado del servidor, a diferencia del formato ESM (import/export nativos) que se usa del lado del cliente ([Angular]);
  • líneas 6–7: [“emitDecoratorMetadata”: true, “experimentalDecorators”: true,] — las dos opciones esenciales para que [NestJS] (y [TypeORM]) funcionen: habilitan la compatibilidad con decoradores ([@Controller](), [@Injectable](), [@Entity](), etc.) y, sobre todo, garantizan que el compilador conserve, en tiempo de ejecución, el TIPO de cada parámetro del constructor; esa es la información que [NestJS] lee para deducir por sí mismo qué debe inyectar (véase el Capítulo 2, sección sobre la inyección de dependencias). Sin estas dos líneas, la inyección por constructor sencillamente no funcionaría;
  • línea 9: [“target”: “ES2022”,]— la versión de JavaScript producida por la compilación; ES2022 es compatible con las versiones de Node.js utilizadas en este curso (20+) y permite usar directamente en el código fuente características recientes de JavaScript (campos privados de clase #x, Array.at()…);
  • línea 16: [“strictNullChecks”: true,] — exige un tratamiento explícito de los valores null/undefined (mediante ?, ??, una instrucción if…); es una de las opciones del modo estricto de TypeScript, habilitada aquí de forma aislada en lugar del modo estricto completo (línea 17: noImplicitAny sigue en false, lo cual es más permisivo): un compromiso didáctico, para conservar lo esencial de la seguridad de tipos sin exigir una anotación de tipo en cada variable.

4.9.3. nest-cli.json

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

Comentemos este código:

  • línea 3: [“collection”: “@nestjs/schematics”,] — el generador de código que usan los comandos `nest generate ...` (no se utiliza en este documento, donde todos los archivos se escribieron a mano, pero está disponible para el resto del curso);
  • línea 4: [“sourceRoot”: “src”,] — indica a la CLI de [NestJS] dónde se encuentra el código fuente que debe compilarse; esto es lo que le permite saber, por ejemplo, que el punto de entrada es [src/main.ts];
  • línea 6: [“deleteOutDir”: true] — antes de cada compilación, la carpeta dist/ (la línea outDir de [tsconfig.json]) se vacía por completo: así se evita que un archivo .js compilado a partir de un archivo .ts que ya se eliminó permanezca indefinidamente en dist/.

Este archivo es específico del ecosistema [NestJS]: no tiene un equivalente directo en los proyectos [Angular] (véase el capítulo siguiente), donde angular.json desempeña un papel bastante similar.

4.9.4. src/config/database.config.ts

Image

  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 {
     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 ?? 'dbrdvmedecins',
     entities: [Doctor, Client, Slot, Appointment, User],
     synchronize: false,
     logging: process.env.NODE_ENV !== 'production',
   };
 }

Comentemos este código:

  • línea 8: [export function getDatabaseConfig(): TypeOrmModuleOptions {] — equivalente a la clase DomainAndPersitenceConfig del proyecto Spring original, que definía un DataSource (bloque @Bean). Aquí no hay clase: solo una función sencilla que devuelve un objeto de configuración, leído de las variables de entorno (el archivo .env; véase más abajo);
  • línea 16: [entities: [Doctor, Client, Slot, Appointment, User],] — la lista de entidades que [TypeORM] debe gestionar; equivale al “escaneo” automático de las clases [@Entity] que realiza Spring Boot. [User] se añadió a esta lista al implementar la autenticación: omitirla provocaría el error “no metadata found for [User]” al arrancar;
  • Línea 17: [synchronize: false,] — de manera constante en este curso: si `synchronize` estuviera en `true`, [TypeORM] modificaría automáticamente el esquema de la base de datos según las entidades; es útil para un prototipo desechable, pero peligroso con datos reales (riesgo de pérdida de datos). Mantenemos el control del esquema mediante el script [database/dbrdvmedecins.sql];
  • línea 18: [logging: process.env.NODE_ENV !== ‘production’,] — muestra en la consola las consultas SQL generadas por [TypeORM], exactamente como los registros de Hibernate en el proyecto Spring original.

4.9.5. [src/main.ts]

Image

  import 'dotenv/config';
  import 'reflect-metadata';
  import { NestFactory } from '@nestjs/core';
  import { ValidationPipe } from '@nestjs/common';
  import { AppModule } from './app.module';

  async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    app.enableCors();
   app.useGlobalPipes(
     new ValidationPipe({
       transform: true,
       whitelist: true,
     }),
   );
   const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 8080;
   await app.listen(port);
   console.log(`[RdvMedecins] NestJS server started on http://localhost:${port}`);
 }

 bootstrap();

Comentemos este código:

  • línea 1: [import ‘dotenv/config’;] — debe ser la primera importación de este archivo: su único propósito es leer el archivo .env y copiar su contenido en process.env, antes de que se evalúe cualquier otra cosa; en concreto, antes de que app.module.ts (importado en la línea 5) cargue a su vez database.config.ts y auth/auth.module.ts, que leen process.env en cuanto se cargan (DB_HOST, JWT_SECRET…). Sin esta línea, en este lugar preciso, un archivo .env presente en el disco no serviría de nada: las variables sencillamente no existirían en process.env cuando estos módulos las necesitan;
  • línea 8: [const app = await NestFactory.create(AppModule);] — construye la aplicación a partir del módulo raíz; es el equivalente de SpringApplication.run(Boot.class, args);
  • línea 9: [app.enableCors();] — autoriza al cliente [Angular] (que se ejecuta en un puerto distinto) a llamar a este servidor. Sin esto, el navegador bloquearía las solicitudes por razones de seguridad;
  • líneas 10–15: [app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));] — verifica automáticamente, en cada solicitud entrante, que el cuerpo JSON se ajuste al formato esperado (véanse las clases decoradas con `class-validator`); `transform: true` convierte automáticamente los tipos (p. ej., la cadena "3" → el número 3) y `whitelist: true` elimina de los datos recibidos los campos que no están declarados en el formato `DTO`;
  • Línea 16: [const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 8080;] — el puerto predeterminado, 8080, es el mismo que el del servidor Spring Boot original.

4.9.6. src/app.module.ts

  import { Module } from '@nestjs/common';
  import { TypeOrmModule } from '@nestjs/typeorm';
  import { getDatabaseConfig } from './config/database.config';
  // ... entidades, repositorios, BUSINESS_TOKEN/BusinessService, ApplicationModelService, RdvMedecinsController
  import { AuthModule } from './auth/auth.module';

  @Module({
    imports: [
      TypeOrmModule.forRoot(getDatabaseConfig()),
     TypeOrmModule.forFeature([Doctor, Client, Slot, Appointment]),
     AuthModule,
   ],
   controllers: [
     RdvMedecinsController,
   ],
   providers: [
     DoctorRepository,
     ClientRepository,
     SlotRepository,
     AppointmentRepository,
     { provide: BUSINESS_TOKEN, useClass: BusinessService },
     ApplicationModelService,
   ],
 })
 export class AppModule {}

Comentemos este código:

  • línea 9: [TypeOrmModule.forRoot(getDatabaseConfig()),] — configura la conexión global a la base de datos; equivale al @Bean DataSource del proyecto Spring original;
  • línea 10: [TypeOrmModule.forFeature([Doctor, Client, Slot, Appointment]),] — declara las entidades utilizadas en este módulo, haciendo inyectables sus Repository<T> (mediante [@InjectRepository]) en las clases de src/repositories/. [User] no figura aquí: es [AuthModule] (línea 11) quien declara su propio TypeOrmModule.forFeature([User]) (véase auth/auth.module.ts);
  • línea 11: [AuthModule,] — aporta su propia ruta (POST /login) y sus propios proveedores (estrategias de Passport, guardia JWT…): un módulo [NestJS] completo, en lugar de archivos añadidos directamente a [AppModule], para mantener la autenticación aislada y fácil de quitar o reemplazar;
  • línea 21: [{ provide: BUSINESS_TOKEN, useClass: BusinessService },] — [BusinessService] se registra bajo el token [BUSINESS_TOKEN], de modo que cualquier clase que solicite [IBusiness] (mediante [@Inject]([BUSINESS_TOKEN])) reciba una instancia de [BusinessService]; exactamente en el espíritu de la inyección por interfaz de Spring (@Autowired [IMetier] business).

4.9.7. .env.example

  PORT=8080

  DB_HOST=localhost
  DB_PORT=3306
  DB_USERNAME=root
  DB_PASSWORD=
  DB_DATABASE=dbrdvmedecins

  DB_SYNCHRONIZE=false

 JWT_SECRET=change-me-to-a-long-random-string
 JWT_EXPIRES_IN=2h

Comentemos este código:

  • línea 1: [PORT=8080] — usa el puerto del servidor Spring Boot original;
  • Líneas 11–12: [JWT_SECRET=… / JWT_EXPIRES_IN=2h] — las dos variables nuevas que introduce la autenticación: la clave secreta de firma de los tokens (debe cambiarse en producción; una cadena aleatoria larga, que nunca se sube al repositorio) y su período de validez.

Este archivo es solo un ejemplo: cópielo a .env (nunca lo suba al repositorio, ya que puede contener secretos) y luego ajuste los valores para su equipo.

4.10. Verificación de extremo a extremo

Este paso se verificó con unos diez escenarios de curl contra una copia de prueba del servidor (base de datos en memoria, prepoblada con las dos cuentas admin/admin y user/user):

  • POST /login con las credenciales correctas devuelve correctamente { "status": 0, "data": { "accessToken": "...", "login": "admin", "name": "Administrator", "role": "ADMIN" } };
  • POST /login con una contraseña incorrecta devuelve 401 Unauthorized (formato JSON nativo de [NestJS], no la envoltura [ServerResponse]<T>);
  • GET /getAllDoctors sin el encabezado Authorization devuelve una respuesta 401 Unauthorized;
  • GET /getAllDoctors con un token JWT válido (admin o user) devuelve normalmente la lista de médicos en la envoltura habitual [ServerResponse]<T>;
  • POST /addAppointment con el token de admin reserva normalmente un horario disponible;
  • POST /addAppointment con el token de user devuelve un error 403 Forbidden, con el mensaje de que el rol [USER] no permite esta acción (rol requerido: ADMIN);
  • POST /deleteAppointment se comporta de forma simétrica a /addAppointment según el rol del token presentado.