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 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 mayor aclaración. Cada carpeta de proyecto contiene además su propio archivo README.md, que incluye una versión resumida de estas explicaciones.

4.1. La base de datos

La base de datos [dbrdvmedecins] reproduce, en su estructura, 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 este
-- port). 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.
 -- =========================================================================

-- se parte de 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, siguiendo el orden inverso de las dependencias (comenzando por `appointments`, que referencia a `[slots]` y a `clients`, hasta llegar a `users`, a la que nadie 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 …] : un horario 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: un mismo horario en un mismo día solo puede reservarse una vez. Es esta restricción, y únicamente ella, la que 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 adelante, 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 cifrada mediante hash con 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. Dado que 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 cifradas con 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 responde al mismo principio de diseño del proyecto Spring original y hace que cada capa pueda reemplazarse independientemente de las demás.

4.3. Las entidades [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 mediante el SGBD, el equivalente exacto de @Id + @GeneratedValue(strategy = GenerationType.AUTO) en JPA;
  • Línea 7: [@VersionColumn()] : [TypeORM]’s mecanismo nativo de 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] 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 {] : incluye los campos comunes a un médico y a un paciente (título, apellido, nombre), y hereda id/version ([AbstractEntity]). Al igual que su clase padre, no está decorada con [@Entity]: es el equivalente en [TypeORM] de la clase [Personne], que en el proyecto original también era @MappedSuperclass;
  • líneas 5, 8, 11: [@Column({ length: N })], [@Column({ name: '...', length: N })]: tres columnas de texto de longitud limitada (la opción name indica el nombre real de la columna en snake_case: last_name, 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 [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 necesidad de volver a declararlos;
  • línea 7: [@OneToMany(() => Slot, (slot) => slot.doctor)] : declara la relación inversa «un médico tiene varios horarios»: 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 de tiempo del horario 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)] : varios horarios pertenecen al mismo médico. De forma predeterminada, [TypeORM] no carga la relación «doctor» al leer un horario (comportamiento «lazy» predeterminado): debe solicitarla explícitamente (opción de relación: [...] en una consulta), exactamente como FetchType.LAZY exigía, del lado de JPA, un `left join fetch` explícito en la consulta JPQL para recuperar 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], lo que resulta ú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 usarse en una cláusula WHERE de un «query builder» (véase más adelante, [SlotRepository]). Se utiliza únicamente para recuperar 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] se encarga de asignar '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 en TypeScript: los únicos dos roles que administra 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 [Vue.js]…);
  • línea 6: [@Entity({ name: 'users' })] : como las demás entidades, una tabla propia;
  • línea 12: [password: string;] : almacena una contraseña cifrada mediante 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 muchos a muchos (users/roles/users_roles) del proyecto Spring original. Esta aplicación solo reconoce 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 vimos antes 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 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 la franja está libre ese día
    ) {}
  }

Comentemos este código:

  • línea 4: [export class DoctorDaySlot {] : asocia un horario con la cita que pudo haberse programado en ese horario, 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 el horario 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 horarios (cada uno marcado como disponible o reservado; 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 [Vue.js].

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, etc.); Spring mismo generaba, al iniciar, una clase que la implementaba. Con [TypeORM], no existe la generación automática de una implementación a partir de una interfaz: se inyecta directamente el Repository<Entity> genérico que provee [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)] : le pide a [NestJS] que suministre 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 identificador (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, en principio, exactamente igual que [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 s se nombra, igual que [Creneau] c se nombra 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 que pueda usarse 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 los horarios cronológicamente, una adición útil que no existía de forma explícita en la versión Spring original.

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’] }] : relaciones: [...] le indica explícitamente a [TypeORM] que cargue también el cliente y el horario asociados (recordatorio: estas relaciones están en modo «lazy» de forma predeterminada; véase slot.entity.ts); es útil para construir el JSON de respuesta (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: recupera, en una sola consulta SQL, el cliente y el horario asociados a cada cita;
  • Línea 33: [.where(‘slot.doctor = :doctorId’, { doctorId })] : condición sobre el médico, obtenida mediante un join con el horario (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 requisito de la aplicación (listas, búsquedas por identificador, 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 y objetos de dominio importados (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 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 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 una lógica de negocio real (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. recuperar todos los horarios disponibles del médico;
  • línea 43: [const bookings = await this.getDoctorDayAppointments(doctorId, day);] : 2. recuperar 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 identificador del horario, de modo que puedan recuperarse 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 horario, se comprueba si coincide con alguna de las reservas encontradas: si es así, está «ocupado» (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 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 la ocasión 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: 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 lo permitía con tanta facilidad, con un tipo `Object`;
  • líneas 17–19: [static ok<T>(data: T): ServerResponse<T> {] : un pequeño método estático de tipo «factory», 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 inútil.

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 que espera 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()] : verifica que el valor recibido sea efectivamente un entero. Estos decoradores, combinados con [ValidationPipe], son el equivalente en [NestJS] de las conversiones de tipo automáticas 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 [PostAddAppointmentDto] anterior, para el cuerpo JSON que espera /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 «por qué» ocurrió 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 hace referencia; véase el parámetro {doctorId} en 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 {] : equivalente a Static.getMapForCreneau ([Creneau] horario): 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] : 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 (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, simple delegación 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 consultar la base de datos en cada solicitud). Esta clase cumple dos funciones, igual que la original: actúa como caché, por un lado, y como único punto de entrada del controlador a la capa de negocio, por el otro; 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 invocado automáticamente por [NestJS] inmediatamente después de inyectadas 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, traducidas al inglés, las del documento original (/getAllDoctors para /getAllMedecins, /addAppointment para /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 las once rutas de este controlador a la vez: 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 del 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), equivalente 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); nosotros mismos la convertimos 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 (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 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 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: la 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 el 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 su lugar 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 de 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 el envoltorio 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> lo genera el controlador para los errores de negocio (recurso no encontrado, fecha no válida, etc.). Por lo tanto, el cliente [Vue.js] 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 que espera POST /login ({ login, password }), el mismo mecanismo que el DTO que ya vimos 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 una finalidad puramente informativa: en realidad es [LocalStrategy] (véase más abajo) quien 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 del envoltorio 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 [Vue.js] pueda adaptar su interfaz (véase el capítulo siguiente: ocultar 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 utilizará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’ });] — por defecto, 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 utiliza “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 la solicitud llegue siquiera 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). 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 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 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, 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') {}

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 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 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 e @Injectable, que proporciona [NestJS]): simplemente adjunta 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á esos 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, a continuación de [JwtAuthGuard]: esta función 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 exigidos 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, […])] — los metadatos establecidos por [@Roles](...) se leen de nuevo 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; }] — sin metadatos de [@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] por lo tanto, se ejecuta 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 está entre los exigidos, 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 ese 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 un hash a la contraseña usando 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 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 (ya 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 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<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 este envoltorio.

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]),] — permite inyectar Repository<[User]> (véase repositories/user.repository.ts);
  • línea 15: [PassportModule,] — declara 'jwt' como la estrategia por defecto para [AuthGuard]() sin argumentos; nuestros guardias siguen especificando explícitamente [AuthGuard]('local')/AuthGuard('jwt') para que sean 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, p. ej., "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 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 precompilado (dist/main.js), sin pasar por la CLI ni recompilar; 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 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 únicamente durante el desarrollo (compilación, tipado), que nunca se incluyen en dist/: la CLI de [NestJS] en sí ([@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 [Vue.js] (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 producidos por la compilación; commonjs (require/module.exports) sigue siendo el formato que espera Node.js para este tipo de proyecto del lado del servidor, a diferencia del formato ESM (import/export nativos) que se encuentra del lado del cliente ([Vue.js]);
  • 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; es la información que [NestJS] lee para determinar por sí mismo qué 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 simplemente no funcionaría;
  • línea 9: [“target”: “ES2022”,]— la versión de JavaScript producida por la compilación; ES2022 cuenta con amplio soporte 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 el 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, que 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 se debe compilar; 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/ (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 fue eliminado permanezca indefinidamente en dist/.

Este archivo es específico del ecosistema [NestJS]: no tiene un equivalente directo en los proyectos [Vue.js] (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 {] — equivalente a la clase DomainAndPersitenceConfig del proyecto Spring original, que definía un DataSource (bloque @Bean). Aquí no hay clase: solo una función simple 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 con la incorporación de 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 a partir de las entidades: ú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 del 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 única finalidad 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 [Vue.js] (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 `DTO`;
  • Línea 16: [const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 8080;] — el puerto por defecto, 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; equivalente al @Bean DataSource del proyecto Spring original;
  • línea 10: [TypeOrmModule.forFeature([Doctor, Client, Slot, Appointment]),] — declara las entidades usadas en este módulo, haciendo que sus Repository<T> sean inyectables (mediante [@InjectRepository]) en las clases de src/repositories/. [User] no figura allí: 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, tokens 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 [IBusiness] 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 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 el envoltorio [ServerResponse]<T>);
  • GET /getAllDoctors sin 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 el envoltorio [ServerResponse]<T> habitual;
  • 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.