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 en todo 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 una aclaración adicional. Cada carpeta de proyecto contiene además su propio archivo README.md, con una versión condensada de estas explicaciones.

4.1. La base de datos

La estructura de la base de datos [dbrdvmedecins] refleja 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 adición nueva, introducida por la etapa de “autenticación” de esta adaptación: la tabla [users].

4.1.1. [database/dbrdvmedecins.sql]

  -- =========================================================================
  -- Database [dbrdvmedecins] - MySQL 8
  --
  -- This script reproduces EXACTLY the relational schema of the original document
  -- (2014, Spring 4 / Spring Data / MySQL 5): same tables, same columns,
  -- same foreign keys, same uniqueness constraint. Only the database engine
  -- changes its name (MySQL 5 -> MySQL 8), not the structure.
  --
  -- The [users] table now appears ("authentication" step of this
 -- port). The original document used THREE tables (users, roles,
 -- users_roles) to allow a user to have SEVERAL roles.
 -- Since this application only knows two mutually exclusive roles
 -- (ADMIN, USER), we simplify here to a single [role] column
 -- on the [users] table rather than rebuilding the original many-to-
 -- many relation - a deliberate teaching simplification, documented
 -- in the "Authentication" chapter of the course.
 -- =========================================================================

 -- we start again from an empty database on each run of the script (handy in development)
 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 está referenciada por una clave externa;
  • línea 48: [doctor_id INT NOT NULL], luego 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: la misma franja horaria en el 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 comprobar explícitamente (véase más abajo, addAppointment);
  • líneas 67–74: [CREATE TABLE users (…)] : la tabla agregada 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 usaba 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 original de muchos a muchos 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, tampoco en este script de demostración.

4.2. Organización en capas

El servidor sigue la estructura en 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 permite reemplazar cada capa de forma independiente de las demás.

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

Las entidades son las clases que representan las 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 modificó 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 a ninguna tabla por sí sola. [TypeORM] llama 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 ([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 fija (con un nombre de columna explícito en snake_case, last_name / first_name, para las dos últimas), 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 una entidad de [TypeORM], persistida en la tabla [doctors]: el equivalente exacto de [@Entity] + @Table(name = "[doctors]") en JPA;
  • línea 6: [export class Doctor extends Person {] : hereda title/lastName/firstName (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 comodidad de navegación, ausente del proyecto original (que la declaraba solo en el otro sentido, del lado de [Creneau]), pero fácil de agregar 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 el “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 asignado a su columna en 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): hay que solicitarla explícitamente (opción relations: ['doctor'] 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 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 abajo, la capa web).

Nota: Un campo [@RelationId] es una columna virtual, calculada a posteriori por [TypeORM]: no es una verdadera columna SQL que pueda usarse en una cláusula WHERE de un “query builder” (véase más abajo, [SlotRepository]). Se utiliza ú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. Observe que 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] asigna por sí mismo 'slot' a su verdadera columna 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], según 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 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 que gestiona 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 [React]…);
  • línea 6: [@Entity({ name: 'users' })] : como las demás entidades, una tabla propia;
  • línea 12: [password: string;] : almacena una contraseña con hash (bcrypt), nunca en texto plano; véase auth.service.ts;
  • línea 18: [role: Role;]: una sola columna, en lugar de la relación de 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 agregado complejidad sin ningún beneficio real. Es una simplificación deliberada con fines didácticos, igual que la enumeración `[ResponseStatus]` que aparece 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”) que no necesita almacenarse tal cual. Equivalen a la misma subcarpeta (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
    ) {}
  }

Comentemos este código:

  • línea 4: [export class DoctorDaySlot {] : asocia una franja horaria con la cita que pudo haberse programado en esa franja, para un día dado;
  • 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 dado: 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 abajo); es esta lista la que el controlador convierte a JSON para el cliente [React].

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; es el equivalente de las interfaces de Spring Data del proyecto original (paquete rdvmedecins.repositories).

Image

La diferencia más importante que hay que entender 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, etc.); 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 usando 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();] : equivale a medecinRepository.findAll(), heredado de CrudRepository;
  • línea 18: [return this.repository.findOneBy({ id });] : equivale 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’)]: se asigna el alias SQL s, tal como en JPQL se declara [Creneau] c;
  • 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 en orden cronológico, un agregado ú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 (recuerde: estas relaciones están en modo “lazy” de forma predeterminada; véase slot.entity.ts); resulta útil para construir la respuesta JSON (véase más abajo, getMapForAppointment);
  • línea 21: [return this.repository.save(appointment);] : equivale a rvRepository.save(new Rv(jour, client, creneau));
  • línea 25: [await this.repository.delete(id);] : equivale a rvRepository.delete(rv.getId());
  • línea 28: [getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {]: equivale 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 un 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 tras la simplificación 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, alta y baja de citas, cálculo de la agenda);
  • línea 21: [export const BUSINESS_TOKEN = ‘IBusiness’;]: se define 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 en tiempo de compilación, por lo que 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 y objetos de negocio importados (vea 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 simples de delegación (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("métier"): esta clase se convierte en un “proveedor” ([NestJS]) que [NestJS] puede construir e inyectar donde se necesite;
  • líneas 11–16: [constructor(private readonly doctorRepository: …, …) {}] : inyección de las cuatro instancias 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 sobre 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 comprobación explícita; un intento de duplicado provocará 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 lógica de negocio propiamente dicha (los demás se limitan a delegar): calcula la agenda completa de un médico para un día dado. 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 disponibles 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; equivale al `Map<Long, Rv> hReservations` del código original;
  • líneas 50–53: [const doctorDaySlots = timeSlots.map((slot) => { … })] : 3. para cada franja horaria, se comprueba si corresponde a alguna de las reservas encontradas: si es así, está “ocupada” (se le asocia la cita encontrada); en caso 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 usaba 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 por el cliente (0 = éxito, cualquier otro valor = fallo) sigue siendo estrictamente el mismo;
  • Línea 8: [export class ServerResponse<T = unknown> {] : el cuerpo de respuesta común para todas las respuestas JSON del servicio web: { "status": 0, "data": ... }. Novedad respecto del original: gracias a TypeScript, esta clase es genérica ([ServerResponse]<T>), de modo que el tipo de los datos se conoce en tiempo de compilación (por ejemplo, [ServerResponse]<[Doctor][]>); el lenguaje Java del proyecto original no permitía hacerlo con tanta facilidad con un tipo `Object`;
  • líneas 17–19: [static ok(data: T): ServerResponse {] : un pequeño método estático de “fábrica”, 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 {] : 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 abajo);
  • líneas 7, 10: [@IsInt()] : verifica 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;
}

El mismo principio que el de [PostAddAppointmentDto] visto 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[] {] : equivale 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 de la misma manera 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 a qué médico se refiere; véase el parámetro {doctorId} de la URL). Por eso se construye un objeto “personalizado” que contiene solo los campos necesarios para la visualización;
  • línea 21: [export function getMapForSlot(slot: Slot | null | undefined): SlotJson | null {] : equivale a Static.getMapForCreneau([Creneau] creneau): convierte una entidad en un objeto JSON ligero;
  • línea 29: [export function getListMapForSlots(slots: Slot[]): SlotJson[] {] : su contraparte para una lista completa (equivale a Static.getListMapForCreneaux);
  • líneas 33–38, 40–50, 52–54: [AppointmentJson / getMapForAppointment / getListMapForAppointments] : el mismo principio, aplicado a las citas: el cliente incrustado (appointment.client) también se reduce únicamente 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 (vea 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 {] : equivale a la clase ApplicationModel del proyecto original: una memoria 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 consultar 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 habrá 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: onModuleInit() es llamado automáticamente por [NestJS] 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) simplemente se delega en la capa de negocio.

4.7.6. src/web/rdvmedecins.controller.ts

RdvMedecinsController declara las once rutas de la aplicación, que intencionalmente reproducen las del documento original (/getAllDoctors, /addAppointment…, versiones en inglés de /getAllMedecins, /ajouterRv…) en lugar de “modernizarlas” 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), 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 abajo). Equivale a la regla original de Spring Security .antMatchers("/**").hasRole("ADMIN"), salvo que aquí el único requisito es estar autenticado (con 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 que 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 verificamos que la aplicación se haya inicializado correctamente (véase ApplicationModelService.onModuleInit), lo que equivale a `if (messages != null) { return new [Reponse](-1, messages); }`;
  • línea 33: [async getAllSlots(@Param('doctorId') doctorId: string) {] — [@Param]('doctorId') recupera el segmento {doctorId} de la URL, como una cadena (similar a @PathVariable(String) en Spring); la convertimos nosotros mismos a 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 recuperamos al médico para verificar que existe antes de continuar (equivale 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 (algo que ya exige [@UseGuards]([JwtAuthGuard]) para toda 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 (aportado 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 verificó 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 hagan dos reservas para la misma franja horaria el mismo día: un intento 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 utilitaria 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 con 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 la red en cada llamada. Este port utiliza en cambio un token: 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 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 que sigue: cuando un guardia 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 manejan 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.). Por lo tanto, el cliente [React] debe 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 }), 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.

Este DTO cumple aquí una función puramente informativa: en realidad es [LocalStrategy] (véase más abajo) la que lee {login, password} del cuerpo de la solicitud, y no un parámetro [@Body]([LoginDto]) del controlador. Sin embargo, [LoginDto] ilustra 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 que devuelve 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 que inició sesión, para que el cliente [React] pueda adaptar su interfaz (véase el capítulo siguiente, que oculta los botones “Reservar”/“Cancelar” 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 Spring Security original: “dadas unas credenciales, dime quién es este usuario”;
  • línea 10: [super({ usernameField: ‘login’, passwordField: ‘password’ });] — de forma predeterminada, passport-local espera campos llamados “username” y “password” en el cuerpo de la solicitud; 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 invoca 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 la solicitud 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 al generarlo (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 manejadores 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 especificó ninguno): es el nombre que [JwtAuthGuard] ([AuthGuard]('jwt'), véase más abajo) utiliza para indicar “use 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; es 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 invoca 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') {}

Analicemos este código:

  • línea 5: [export class LocalAuthGuard extends AuthGuard(‘local’) {}] — un “guardia” ([NestJS]) determina, antes de ejecutar 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 a partir de la estrategia de Passport llamada 'local' (implícitamente, [LocalStrategy], a la que no se le dio un nombre explícito en su propio constructor). Este guardia lo usa únicamente 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” hace referencia 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 mismos, a diferencia de @Get, @Post y @Injectable, que provee [NestJS]): simplemente asocia 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 decoradores “propios” 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 que inició sesión esté 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 y no URL por URL, gracias al par de decoradores ([@Roles]) + [Reflector] (que permite volver a leer los metadatos definidos por un decorador);
  • línea 12: [const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, […])] — los metadatos definidos por [@Roles](...) se vuelven a leer 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, sin importar el rol);
  • línea 21: [const request = context.switchToHttp().getRequest<{ user: ConnectedUser }>();] — request.user fue aportado por JwtStrategy.validate(): [RolesGuard] por lo tanto siempre se ejecuta 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 que inició sesión no está 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 gestiona 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 Spring Security original, 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() aplica el hash a la contraseña con el mismo salt que el almacenado 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 invoca [AuthController], una vez que LocalAuthGuard y LocalStrategy se completaron 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 (pues 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 antes 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 llegamos 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(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. Lo importa una sola vez AppModule.

  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 para [AuthGuard]() sin argumentos; nuestros guardias siguen especificando explícitamente [AuthGuard]('local')/AuthGuard('jwt') para mantenerse legibles;
  • líneas 16–19: [JwtModule.register({ secret: …, signOptions: { expiresIn: … } }),] — configura la generación y verificación de tokens: la clave secreta de firma (JWT_SECRET, véase .env) y su período de validez (JWT_EXPIRES_IN, por ejemplo, "2h");
  • líneas 25–26: [LocalStrategy, JwtStrategy,] — registran las estrategias 'local' y 'jwt' en Passport, respectivamente; sin esta declaración en `providers`, [NestJS] no podría construir estas dos clases.

4.9. Configuración y ejecución

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 (utilizado 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 precompilado (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 utiliza [TypeORM]), la validación mediante 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 en [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 CLI de [NestJS] misma ([@nestjs/cli]), el compilador de TypeScript y las definiciones de tipos (@types/...) de los paquetes de JavaScript que no las proveen de forma nativa (bcryptjs, passport-jwt, passport-local).

Al igual que con el cliente [React] (véase el capítulo siguiente), este es el archivo que [npm install] lee (capítulo 1) para determinar qué descargar en node_modules/, 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 que produce la compilación; commonjs (require/module.exports) sigue siendo el formato que Node.js espera para este tipo de proyecto de servidor, a diferencia del formato ESM (import/export nativos) que se usa del lado del cliente ([React]);
  • 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, hacen que el compilador conserve, en tiempo de ejecución, el TIPO de cada parámetro del constructor; esta es la información que [NestJS] lee para determinar por sí mismo qué inyectar (véase el capítulo 2, sección sobre inyección de dependencias). Sin estas dos líneas, la inyección por constructor simplemente no funcionaría;
  • línea 9: [“target”: “ES2022”,]— la versión de JavaScript que produce la compilación; ES2022 cuenta con amplia compatibilidad en 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 manejo 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 utilizan los comandos `nest generate ...` (no se usa 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 propio del ecosistema [NestJS]: no tiene un equivalente directo en los proyectos [React] (véase el capítulo siguiente), donde vite.config.ts 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 {] — equivale a la clase DomainAndPersitenceConfig del proyecto Spring original, que definía un DataSource (bloque @Bean). Aquí no hay clase: solo una simple función 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 agregó a esta lista al incorporar la autenticación: omitirlo provocaría un error “no metadata found for [User]” al iniciar;
  • Línea 17: [synchronize: false,] — siempre presente 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 en cuanto hay 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 simplemente 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; el equivalente de SpringApplication.run(Boot.class, args);
  • línea 9: [app.enableCors();] — autoriza al cliente [React] (que se ejecuta en otro puerto) 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 (por ejemplo, la cadena “3” → el número 3) y `whitelist: true` elimina de los datos recibidos los campos que no están declarados en el `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 aparece aquí: es [AuthModule] (línea 11) el que 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 agregados 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] métier).

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] — utiliza 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 máquina.

4.10. Verificación de extremo a extremo

Esta etapa se verificó mediante unos diez escenarios con 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 (forma JSON nativa de [NestJS], no la envoltura [ServerResponse]<T>);
  • GET /getAllDoctors sin un 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 dentro de la envoltura habitual [ServerResponse]<T>;
  • POST /addAppointment con el token de admin reserva normalmente una franja horaria 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.