Skip to content

10. Caso de estudio: el cliente Vue.js de la aplicación RdvMedecins

10.1. El problema

La aplicación [RdvMedecins] permite programar citas en un consultorio médico. El curso de [NestJS] la escribió como una aplicación HTML, en la que el servidor generaba las páginas. Aquí escribimos el cliente [Vue.js]: las MISMAS páginas, generadas en el navegador a partir de los datos JSON del servidor descritos en el capítulo “El servidor RdvMedecins: una caja negra”.

El cliente debe ofrecer todo lo que ofrecía la aplicación HTML:

  • una página de inicio de sesión, protegida por un CAPTCHA, con la opción de crear una cuenta de paciente;
  • la agenda de un médico para un día determinado, con reserva de citas (ventana de selección de paciente) y cancelación;
  • para el administrador, la gestión de médicos y clientes (listar, agregar, editar, eliminar);
  • para el paciente, un panel personal (que muestra las citas próximas, que puede cancelar) y la gestión de su cuenta;
  • dos idiomas: francés e inglés;
  • URL únicas ([/schedule?doctorId=1&day=...]), que pueden recargarse, guardarse como marcadores y recorrerse con los botones Atrás/Adelante del navegador.

10.2. Instalación y ejecución

El servidor JSON debe estar instalado y en ejecución (véase el capítulo anterior). Para usar el cliente en un navegador, no necesita el modo de prueba del CAPTCHA: NO debe activarlo en el archivo [.env] del servidor.

En una ventana de consola abierta en la carpeta [rdvmedecins-vuejs]:

npm install
npm run dev

Luego abra http://localhost:5173 en un navegador. Las cuentas de demostración se enumeran en la página de inicio de sesión (contraseña = nombre de usuario).

El servidor [Vite] de los ejemplos también usa el puerto 5173. Si este puerto ya está en uso, [Vite] tomará otro (5174...) y lo mostrará en la consola: deberá abrir entonces esa dirección.

10.3. Uso de la aplicación

10.3.1. La página de inicio de sesión

Image

Contraseña incorrecta: aparece un mensaje en la parte inferior de la página y se muestra una nueva imagen (cada imagen solo puede usarse una vez):

Image

10.3.2. El calendario, visto por el administrador y los médicos

Al iniciar sesión como [admin], se accede al calendario:

Image

Seleccione un médico y un día, y luego haga clic en “Ver agenda”. La URL pasa a ser [/schedule?doctorId=1&day=2026-09-28]:

Image

“Reservar” abre la ventana de reserva. La URL pasa a ser [/schedule?doctorId=1&day=2026-09-28&book=3]: al recargar la página (F5) se vuelve a abrir la misma ventana.

Image

La cita queda registrada:

Image

“Cancelar” solicita confirmación:

Image

Un médico accede directamente a SU PROPIA agenda del día:

Image

10.3.3. El portal del paciente

Un paciente ([martin]) accede a “Mi área”:

Image

En un calendario, ve “Reservado” junto a los horarios de otros pacientes:

Image

Reserva una cita para sí mismo sin seleccionar a un paciente:

Image

Su cita aparece bajo su nombre; el botón “Reservar” ya no está disponible (solo una cita próxima) y un mensaje explica el motivo:

Image

Su panel muestra esto:

Image

“Gestionar mi cuenta”: cualquier cambio requiere la contraseña actual; los errores provienen del servidor:

Image

Si ingresa la dirección [/doctors], reservada para el administrador:

Image

10.3.4. Gestión de médicos y clientes

Image

Un registro llenado incorrectamente:

Image

Una alta exitosa:

Image

Un homónimo:

Image

La solicitud de eliminar a un médico con citas programadas es denegada:

Image

10.3.5. Creación de una cuenta

En la página de inicio de sesión, ingrese el CAPTCHA y luego haga clic en “Crear una cuenta de paciente”. El formulario, llenado de forma incorrecta, es rechazado por el servidor:

Image

Una vez creada la cuenta, regrese a la página de inicio de sesión; los campos de acceso aparecen rellenados:

Image

10.3.6. En francés

Los botones FR / EN traducen la página al instante, sin enviar ninguna solicitud al servidor:

Image

10.3.7. Sesión vencida, dirección desconocida

Si el token vence (o si se elimina la cookie), la siguiente solicitud recibe una respuesta 401; el cliente es redirigido a la página de inicio de sesión:

Image

Una dirección desconocida:

Image

10.4. Arquitectura del cliente

Image

rdvmedecins-vuejs/
├── index.html             THE page of the application
├── public/favicon.svg     the tab icon
├── package.json, vite.config.ts, tsconfig.json, env.d.ts
└── src/
    ├── main.ts            the startup
    ├── App.vue            the layout shared by all the pages
    ├── styles.css
    ├── router.ts          the pages and their access rights
    ├── i18n.ts            the languages
    ├── locales/           fr.json, en.json
    ├── api/               the API access layer
    ├── stores/            session.ts, messages.ts
    ├── composables/       useConfirmation, useFormatting, useForm
    ├── components/        the reusable components
    └── views/             the pages

La siguiente tabla compara la aplicación HTML del curso de [NestJS] con este cliente:

Aplicación HTML (NestJS)
Cliente Vue.js
El servidor genera cada página ([res.render])
El servidor devuelve JSON; los componentes de [src/views/] generan las páginas
[views/layout.hbs] y sus vistas parciales
[App.vue] y los componentes de [src/components/]
las rutas de los controladores ([@Controller('schedule')])
rutas del cliente ([router.ts]); el servidor solo tiene rutas [/api/...]
[JwtAuthGuard] y [RolesGuard] redirigen a [/login] o a una página 403
la guardia del enrutador; el servidor mantiene sus propias guardias, que responden con 401 / 403
mensaje flash en una cookie
mensaje flash en un store de Pinia
Diccionarios leídos por el servidor, helper [{{t}}]
diccionarios en el cliente, [vue-i18n]; el servidor devuelve solo claves
idioma almacenado en una cookie
idioma almacenado en [localStorage]
formulario rechazado: el servidor recarga la página
formulario rechazado: respuesta 400/409; el cliente muestra los errores
ventana de confirmación: un pequeño script, [public/js/app.js]
un componente, [ConfirmDialog.vue]
La aplicación funciona sin JavaScript
La aplicación ES JavaScript

10.5. Configuración del proyecto

10.5.1. package.json

{
  "name": "rdvmedecins-vuejs",
  "version": "1.0.0",
  "description": "Vue.js client of the medical appointment booking application [RdvMedecins] - client of the JSON server [rdvmedecins-nestjs-json]",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build",
    "preview": "vite preview",
    "check": "vue-tsc --noEmit"
  },
  "dependencies": {
    "bootstrap": "^5.3.8",
    "pinia": "^3.0.4",
    "vue": "^3.5.22",
    "vue-i18n": "~11.3.2",
    "vue-router": "^4.6.3"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "@vitejs/plugin-vue": "^6.0.1",
    "@vue/tsconfig": "^0.8.1",
    "typescript": "~5.9.3",
    "vite": "^7.1.12",
    "vue-tsc": "^3.1.3"
  }
}

Las mismas bibliotecas que en los ejemplos. Un comando adicional:

  • Línea 10: [npm run preview] sirve la versión compilada de la aplicación (carpeta [dist/], generada por [npm run build]), para verificarla antes de desplegarla.

10.5.2. vite.config.ts

// =========================================================================
// vite.config.ts
// -------------------------------------------------------------------------
//   - npm run dev   : servidor de desarrollo en http://localhost:5173;
//                     las solicitudes /api/... son reenviadas al servidor JSON
//                     (puerto 8080) por el proxy: la página y la API tienen el mismo
//                     origen, la cookie del token viaja con normalidad;
//   - npm run build : la aplicación compilada, en dist/. Para ponerla en
//                     producción, copie el CONTENIDO de dist/ en la carpeta
//                     client/ del servidor JSON, que entonces la sirve por sí mismo
//                     (vea el capítulo "Despliegue").
// =========================================================================

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 5173,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },
  // npm run preview: sirve dist/ (después de npm run build), con el mismo proxy
  preview: {
    port: 4173,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },
});
  • líneas 21–23: el proxy para las solicitudes de [/api] hacia el servidor JSON;
  • líneas 26–31: el mismo proxy para [npm run preview].

Un detalle importante: la aplicación usa direcciones “limpias” ([/schedule], [/my-area]). Si se recarga la página [/schedule], el navegador solicita [/schedule] al servidor [Vite]. Como el servidor no encuentra un archivo con ese nombre, devuelve [index.html] (este es su comportamiento por defecto para una aplicación de página única); la aplicación se inicia y su enrutador muestra la página del calendario.

10.5.3. tsconfig.json y env.d.ts

Idénticos a los de los ejemplos, salvo por la lista de archivos:

1
2
3
4
5
6
7
8
9
{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "types": ["vite/client"],
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["src/**/*.ts", "src/**/*.vue", "env.d.ts"]
}

10.6. Inicio de la aplicación

10.6.1. index.html

<!doctype html>
<!--
  index.html - LA página de la aplicación (Single Page Application).
  El servidor nunca envía otra: todo lo demás se construye en
  el navegador mediante Vue.js, dentro de <div id="app">. lang y title son
  actualizados por la aplicación según el idioma y la página mostrada.
-->
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
  <title>RdvMedecins</title>
</head>
<body>
  <div id="app"></div>
  <!-- sin JavaScript, una aplicación Vue.js no puede mostrar nada: lo indicamos -->
  <noscript>RdvMedecins requires JavaScript. / RdvMedecins a besoin de JavaScript.</noscript>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>
  • Línea 12: el ícono de la pestaña. Los archivos de la carpeta [public/] se sirven tal cual, en la raíz del sitio;
  • línea 18: sin [JavaScript], una aplicación [Vue.js] no puede mostrar nada. En cambio, la aplicación HTML del curso de [NestJS] funcionaba sin [JavaScript]: esa es la contrapartida de una aplicación de página única;
  • Línea 19: el programa.

10.6.2. src/main.ts

// =========================================================================
// main.ts - el arranque de la aplicación
// -------------------------------------------------------------------------
//   1. Bootstrap (CSS) y nuestros pocos estilos;
//   2. Pinia (stores), vue-i18n (idiomas), el enrutador;
//   3. la reacción a una respuesta 401 proveniente de cualquier solicitud:
//      la sesión ha expirado - olvidamos al usuario y volvemos a la
//      página de inicio de sesión, con un mensaje;
//   4. la visualización en <div id="app">.
// =========================================================================

import { createApp } from 'vue';
import { createPinia } from 'pinia';
import 'bootstrap/dist/css/bootstrap.min.css';
import './styles.css';
import App from './App.vue';
import { i18n } from './i18n';
import { router } from './router';
import { whenUnauthenticated } from './api/http-client';
import { useSessionStore } from './stores/session';
import { useMessagesStore } from './stores/messages';

const app = createApp(App);
app.use(createPinia());
app.use(i18n);
app.use(router);

whenUnauthenticated(() => {
  useSessionStore().forget();
  useMessagesStore().flash('error', 'ERRORS.SESSION_EXPIRED');
  router.push({ name: 'login' });
});

app.mount('#app');
  • Líneas 24–26: las tres extensiones: stores, idiomas y el enrutador. [Pinia] debe instalarse ANTES que el enrutador: la guardia del enrutador usa un store;
  • Líneas 28–32: qué hacer cuando cualquier solicitud recibe una respuesta 401 (sesión vencida, cuenta eliminada, etc.): olvidar al usuario, preparar el mensaje “Su sesión ha vencido” para la siguiente página y redirigir a la página de inicio de sesión. Esta respuesta se declara UNA sola vez aquí; la función [whenUnauthenticated] se describe junto con [http-client.ts].

10.6.3. src/App.vue

<!--
  =========================================================================
  App.vue - el componente raíz: la PLANTILLA común a todas las páginas
  -------------------------------------------------------------------------
  El equivalente de views/layout.hbs de la aplicación HTML:
    - la barra de navegación;
    - un mensaje de éxito en la parte SUPERIOR;
    - la página actual (<RouterView>);
    - el panel de errores en la parte INFERIOR;
    - el diálogo de confirmación, una sola vez para toda la aplicación.

  :key="String(route.name)" en <RouterView>: al pasar de una ruta a
  OTRA (de /doctors a /clients, por ejemplo), el componente de página
  se vuelve a crear; cuando solo cambia el query (/schedule?day=...), se
  conserva, y es el componente quien sigue a la URL.
  =========================================================================
-->
<script setup lang="ts">
import { RouterView, useRoute } from 'vue-router';
import NavBar from './components/NavBar.vue';
import SuccessMessage from './components/SuccessMessage.vue';
import ErrorPanel from './components/ErrorPanel.vue';
import ConfirmDialog from './components/ConfirmDialog.vue';

const route = useRoute();
</script>

<template>
  <div class="container py-4">
    <NavBar />
    <SuccessMessage />
    <RouterView :key="String(route.name)" />
    <ErrorPanel />
  </div>
  <ConfirmDialog />
</template>

La plantilla común a todas las páginas, equivalente a [views/layout.hbs]:

  • línea 30: la barra de navegación;
  • línea 31: un mensaje de éxito en la parte superior;
  • línea 32: la página actual. El atributo [:key]: cuando la clave de un componente cambia, [Vue.js] lo destruye y crea uno nuevo. Con el NOMBRE de la ruta como clave, al pasar de [/doctors] a [/clients] (dos rutas distintas, mostradas por el mismo componente) se recrea la página, que vuelve a cargar sus datos. Cuando solo cambia el [query] (a [/schedule?day=...]), la página se conserva, y es esta página la que sigue su URL;
  • línea 33: la zona de errores, en la parte inferior;
  • línea 35: la ventana de confirmación, mostrada una sola vez para toda la aplicación.

10.6.4. src/styles.css

/* =========================================================================
   styles.css - algunos ajustes sobre Bootstrap
   (tomados de public/css/styles.css de la aplicación HTML)
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-panel: los mensajes de error, al pie de la página, sobre un fondo
   rosa claro (véase components/ErrorPanel.vue).
   position: sticky + bottom: si la página es más alta que la ventana, el
   panel queda pegado al borde inferior de la ventana en lugar de desaparecer debajo del
   pliegue - sin cubrir nunca el contenido cuando la página
   es corta. z-index: por encima del fondo gris de los cuadros de diálogo modales.
   pointer-events: none: el panel no contiene nada en lo que se pueda hacer clic; si
   se superpone a un botón, el clic lo atraviesa.
   ------------------------------------------------------------------------- */
.error-panel {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  pointer-events: none;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* las dos opciones principales de la página "Mi área" del paciente */
.option-card {
  transition: border-color 0.15s, box-shadow 0.15s;
}

.option-card:hover {
  border-color: #0d6efd;
  box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}

/* la imagen del captcha (SVG de 150 x 50 píxeles) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}

Los estilos de la aplicación HTML, con una adición:

  • Línea 28: la zona de errores, que se “pega” a la parte inferior de la ventana, puede superponerse a un botón (una ventana de confirmación en el centro de una página corta, por ejemplo); no contiene nada en lo que se pueda hacer clic, y un clic la atraviesa sin problema.

10.7. La capa de acceso a la API

10.7.1. src/api/types.ts

Los objetos JSON de la API, descritos en el capítulo sobre la caja negra, traducidos a interfaces de [TypeScript]:

// =========================================================================
// api/types.ts - los objetos JSON intercambiados con el servidor
// -------------------------------------------------------------------------
// La traducción, a interfaces TypeScript, de la API descrita en el capítulo
// "El servidor, una caja negra". Así el compilador verifica que el cliente
// solo usa campos que realmente existen.
// =========================================================================

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

// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
export interface User {
  login: string;
  name: string; // nombre para mostrar: "Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string;
}

// un título, un nombre, un apellido
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// un médico o un cliente: GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
  id: number;
  version: number; // bloqueo optimista: para devolver con una actualización
  login?: string; // solo para el ADMIN
}

// lo que se envía para crear / actualizar una persona (ADMIN)
export interface PersonData extends Identity {
  login: string; // '' = valor predeterminado (creación) o sin cambios (actualización)
  password: string; // igual
  version?: number;
}

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

// una fila de la agenda, con los DERECHOS del usuario conectado
export interface ScheduleSlot extends Slot {
  free: boolean;
  patient: Identity | null; // null: libre, o tomada por otro paciente
  mine: boolean; // la cita del paciente conectado
  bookable: boolean;
  appointmentId: number | null; // se completa si el usuario puede cancelar
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string; // "yyyy-MM-dd"
  slots: ScheduleSlot[];
  info: string | null; // clave de traducción (paciente que ya tiene una cita)
}

// GET /api/my-area
export interface MyArea {
  patient: Identity;
  appointments: { id: number; day: string; slot: Slot; doctor: Person }[];
}

// GET /api/my-account
export interface MyAccount extends Identity {
  login: string;
  version: number;
}

// PUT /api/my-account
export interface MyAccountUpdate extends Identity {
  login: string;
  password: string; // '' = sin cambios
  confirmation: string;
  currentPassword: string;
  version: number;
}

// POST /api/register
export interface Registration extends Identity {
  login: string;
  password: string;
  confirmation: string;
}
  • línea 32: una interfaz puede extender a otra: una [Person] es una [Identity] que además tiene un ID, una versión y, para el ADMIN, un nombre de usuario;
  • Línea 54: una entrada del calendario: un horario, más los permisos del usuario conectado;
  • líneas 39 y siguientes: lo que el cliente ENVÍA al servidor.

10.7.2. src/api/http-client.ts

La función [request] del Ejemplo 19 ([common/api.ts]), con manejo centralizado de la respuesta 401:

// =========================================================================
// api/http-client.ts - la función que envía TODAS las solicitudes a la API
// -------------------------------------------------------------------------
// Tomada de common/api.ts de los ejemplos, con una novedad: el manejo
// centralizado de la respuesta 401.
//
// Un 401 puede ocurrir en cualquier momento: el token ha expirado (2 horas), la
// cuenta ha sido eliminada, el servidor se ha reiniciado con otra clave
// secreta... En lugar de manejar este caso en cada componente,
// notificamos a UNA función, registrada al arrancar (vea main.ts), que olvida al
// usuario y lo envía de vuelta a la página de inicio de sesión.
// =========================================================================

export class ApiError extends Error {
  constructor(
    public readonly statusCode: number, // 0: el servidor no respondió
    public readonly key: string, // clave de traducción: 'ERRORS.LOGIN_TAKEN'
    public readonly params: Record<string, string> = {},
    public readonly fields: Record<string, string> = {}, // error de cada campo
  ) {
    super(key);
    this.name = 'ApiError';
  }
}

// la función llamada en cada respuesta 401 (vea main.ts)
let onUnauthenticated: (error: ApiError) => void = () => {};

export function whenUnauthenticated(callback: (error: ApiError) => void): void {
  onUnauthenticated = callback;
}

type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

export interface RequestOptions {
  // las rutas públicas (login, captcha...) y GET /api/auth/me
  // manejan el 401 por sí mismas: sin redirección automática
  ignore401?: boolean;
}

export async function request<T>(method: Method, url: string, body?: unknown, options: RequestOptions = {}): Promise<T> {
  let response: Response;
  try {
    response = await fetch(`/api${url}`, {
      method,
      headers: body !== undefined ? { 'Content-Type': 'application/json', Accept: 'application/json' } : { Accept: 'application/json' },
      body: body !== undefined ? JSON.stringify(body) : undefined,
    });
  } catch {
    throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
  }

  // leído como texto y luego convertido: una respuesta vacía, o una que no es
  // JSON (servidor detenido: es el proxy de Vite quien responde), no
  // bloquea la aplicación
  const text = await response.text();
  let data: unknown = null;
  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    data = null;
  }

  if (response.ok) {
    return data as T;
  }

  const e = (data ?? {}) as { key?: string; params?: Record<string, string>; fields?: Record<string, string> };
  const error = new ApiError(
    response.status,
    // sin clave: no es nuestro servidor quien respondió, sino un proxy
    // (Vite: 500 sin cuerpo; nginx: 502, 504...)
    e.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR'),
    e.params,
    e.fields,
  );
  if (response.status === 401 && !options.ignore401) {
    onUnauthenticated(error);
  }
  throw error;
}
  • líneas 14–23: un error de solicitud: código HTTP, clave del mensaje, parámetros, error de cada campo;
  • línea 27: la función que se debe llamar ante cada respuesta 401. Al inicio no hace nada; [main.ts] proporciona una, mediante [whenUnauthenticated]. ¿Por qué no llamar directamente al enrutador aquí? Porque la capa de acceso a la API no debe saber nada de las páginas: señala el error y la aplicación decide;
  • líneas 35–39: algunas solicitudes esperan un 401 y lo manejan por sí mismas: una contraseña incorrecta ([POST /api/auth/login] responde con un 401), o la pregunta “¿quién ha iniciado sesión?” ([GET /api/auth/me], 401 si nadie ha iniciado sesión). Para estas no hay redirección automática;
  • línea 46: el encabezado [Accept] indica al servidor el formato de respuesta deseado;
  • línea 50: ninguna respuesta en absoluto;
  • línea 73: una respuesta sin clave no proviene de nuestro servidor: cuando el servidor JSON está caído, responde el proxy (el de [Vite] devuelve un error 500 sin cuerpo; un proxy de producción como [nginx] devuelve un 502 o un 504);
  • líneas 77–79: un 401 inesperado: se notifica a la aplicación y luego se rechaza la promesa como en cualquier otro error.

10.7.3. src/api/rdvmedecins.api.ts

Una función por ruta de la API:

// =========================================================================
// api/rdvmedecins.api.ts - una función por ruta de la API
// -------------------------------------------------------------------------
// La "capa de acceso a datos" del cliente: los componentes llaman a estas
// funciones tipadas, sin saber nada de URL, fetch ni JSON. Si la API
// cambia, solo cambia este archivo.
// =========================================================================

import { request } from './http-client';
import type {
  Schedule,
  Captcha,
  PersonData,
  Registration,
  MyAccountUpdate,
  MyAccount,
  MyArea,
  Person,
  User,
} from './types';

// /api/doctors o /api/clients: ambos se gestionan de la misma manera
export type PersonType = 'doctors' | 'clients';

type Empty = Record<string, never>;

export const rdvApi = {
  // ———————————————————————————————— inicio de sesión (rutas públicas)
  captcha: () => request<Captcha>('GET', '/captcha', undefined, { ignore401: true }),
  me: () => request<User>('GET', '/auth/me', undefined, { ignore401: true }),
  logIn: (login: string, password: string, captchaId: string, captcha: string) =>
    request<User>('POST', '/auth/login', { login, password, captchaId, captcha }, { ignore401: true }),
  logOut: () => request<Empty>('POST', '/auth/logout', {}, { ignore401: true }),

  // ———————————————————————————————— creación de cuentas (público)
  registrationAccess: (captchaId: string, captcha: string) =>
    request<Empty>('POST', '/register/access', { captchaId, captcha }, { ignore401: true }),
  registrationAccessStatus: () => request<{ valid: boolean }>('GET', '/register/access', undefined, { ignore401: true }),
  register: (data: Registration) => request<{ login: string }>('POST', '/register', data, { ignore401: true }),

  // ———————————————————————————————— agenda y citas
  // doctorId null: para un médico con sesión iniciada, SU agenda
  schedule: (doctorId: number | null, day: string) => {
    const params = new URLSearchParams({ day });
    if (doctorId !== null) {
      params.set('doctorId', String(doctorId));
    }
    return request<Schedule>('GET', `/schedule?${params}`);
  },
  book: (day: string, slotId: number, clientId: number | null) =>
    request<{ id: number }>('POST', '/appointments', { day, slotId, clientId: clientId ?? undefined }),
  cancelAppointment: (appointmentId: number) => request<Empty>('DELETE', `/appointments/${appointmentId}`),

  // ———————————————————————————————— médicos y clientes
  list: (type: PersonType) => request<Person[]>('GET', `/${type}`),
  read: (type: PersonType, id: number) => request<Person>('GET', `/${type}/${id}`),
  add: (type: PersonType, data: PersonData) => request<Person>('POST', `/${type}`, data),
  edit: (type: PersonType, id: number, data: PersonData) =>
    request<Person>('PUT', `/${type}/${id}`, data),
  remove: (type: PersonType, id: number) => request<Empty>('DELETE', `/${type}/${id}`),

  // ———————————————————————————————— el área del paciente
  myArea: () => request<MyArea>('GET', '/my-area'),
  myAccount: () => request<MyAccount>('GET', '/my-account'),
  editMyAccount: (data: MyAccountUpdate) => request<User>('PUT', '/my-account', data),
  deleteMyAccount: (currentPassword: string) => request<Empty>('DELETE', '/my-account', { currentPassword }),
};
  • línea 23: los médicos y los clientes se manejan de la misma manera; solo cambia la dirección: [/api/doctors] o [/api/clients];
  • línea 25: el tipo de un objeto vacío, [{}];
  • líneas 29–33: las rutas de conexión, que manejan su propio 401 ([ignore401]);
  • líneas 43–49: si no hay ningún médico disponible, se omite el parámetro [doctorId] ; si hay un médico disponible, el servidor devuelve SU agenda;
  • líneas 50–51: [clientId ?? undefined]: [null] se convierte en [undefined], y [JSON.stringify] omite las propiedades con valor [undefined]: un paciente no envía [clientId];
  • líneas 55–60: las cinco operaciones sobre las personas, definidas por su tipo;
  • línea 66: una solicitud DELETE también puede tener cuerpo.

10.8. Idiomas

10.8.1. src/i18n.ts

// =========================================================================
// i18n.ts - francés e inglés
// -------------------------------------------------------------------------
// Los diccionarios locales/fr.json y locales/en.json son los del
// curso de NestJS (i18n/*.json), completados con algunas claves propias del cliente
// (ERRORS.SERVER_UNREACHABLE...). El servidor JSON solo devuelve CLAVES
// ('ERRORS.LOGIN_TAKEN'): son las mismas que las de los diccionarios.
//
// El idioma elegido se almacena en localStorage (una preferencia, no un dato
// sensible); en su defecto, se usa el idioma del navegador.
// =========================================================================

import { createI18n } from 'vue-i18n';
import fr from './locales/fr.json';
import en from './locales/en.json';

export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
const STORAGE_KEY = 'rdvmedecins.language';

function initialLanguage(): Language {
  try {
    const stored = localStorage.getItem(STORAGE_KEY);
    if (stored === 'fr' || stored === 'en') {
      return stored;
    }
  } catch {
    // localStorage no disponible (navegación privada estricta...): no importa
  }
  return navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en';
}

export const i18n = createI18n({
  legacy: false,
  locale: initialLanguage(),
  fallbackLocale: 'en',
  messages: { fr, en },
  // sin advertencia en la consola para una clave traducida por respaldo
  fallbackWarn: false,
  missingWarn: false,
});

// cambiar el idioma: toda la aplicación se traduce de nuevo de una vez
export function changeLanguage(language: Language): void {
  i18n.global.locale.value = language;
  document.documentElement.lang = language;
  try {
    localStorage.setItem(STORAGE_KEY, language);
  } catch {
    // sin importancia
  }
}

document.documentElement.lang = i18n.global.locale.value;
  • líneas 21–31: el idioma almacenado y, en su defecto, el idioma del navegador. El acceso a [localStorage] está protegido por [try / catch]: algunos navegadores, en modo incógnito, lo bloquean;
  • líneas 39–40: ninguna advertencia en la consola cuando falta una clave o proviene del diccionario de respaldo;
  • líneas 44–52: cambiar de idioma: [i18n.global.locale] es el idioma de toda la aplicación; también se actualiza el atributo [lang] de la página y se guarda la selección.

10.8.2. Los diccionarios

Estas son las claves del curso de [NestJS], complementadas con algunas claves propias del cliente ([APP.LOADING], [ERRORS.AUTH_REQUIRED], [ERRORS.JSON_REQUIRED], [ERRORS.SERVER_UNREACHABLE]). Los códigos de error son los devueltos por el servidor.

10.8.2.1. src/locales/fr.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace",
    "LOADING": "Chargement...",
    "LANGUAGE": "Langue"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {name} a été ajouté (login : {login}).",
    "UPDATED": "Le médecin {name} a été modifié.",
    "DELETED": "Le médecin {name} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {name} a été ajouté (login : {login}).",
    "UPDATED": "Le client {name} a été modifié.",
    "DELETED": "Le client {name} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client ».",
    "AUTH_REQUIRED": "Connectez-vous pour accéder à cette page.",
    "JSON_REQUIRED": "Requête refusée : le serveur attend du JSON.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas. Réessayez plus tard."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {min} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {name}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}

10.8.2.2. src/locales/en.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area",
    "LOADING": "Loading...",
    "LANGUAGE": "Language"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {name} has been added (login: {login}).",
    "UPDATED": "Doctor {name} has been updated.",
    "DELETED": "Doctor {name} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {name} has been added (login: {login}).",
    "UPDATED": "Patient {name} has been updated.",
    "DELETED": "Patient {name} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
    "SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
    "CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
    "DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\".",
    "AUTH_REQUIRED": "Please log in to access this page.",
    "JSON_REQUIRED": "Request refused: the server expects JSON.",
    "SERVER_UNREACHABLE": "The server does not respond. Please try again later."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {min} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {name}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

10.9. Los stores

10.9.1. src/stores/session.ts

// =========================================================================
// stores/session.ts - ¿QUIÉN ha iniciado sesión?
// -------------------------------------------------------------------------
// El store de Pinia de la sesión: el usuario conectado (o null), y lo que
// se deduce de él (¿el usuario es ADMIN? ¿un paciente?).
//
// El token JWT en sí NO está aquí: está en una cookie httpOnly que
// solo maneja el navegador. El store guarda únicamente la DESCRIPCIÓN del
// usuario, devuelta por el servidor ({ login, name, role }).
//
// Al arrancar (y después de un F5), el store está vacío: check() le pregunta al
// servidor, una sola vez, quién ha iniciado sesión (GET /api/auth/me).
// =========================================================================

import { computed, ref } from 'vue';
import { defineStore } from 'pinia';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Role, User } from '../api/types';

export const useSessionStore = defineStore('session', () => {
  const user = ref<User | null>(null);
  // ¿ya se le hizo al servidor la pregunta "¿quién ha iniciado sesión?"
  let checking: Promise<void> | null = null;

  const loggedIn = computed(() => user.value !== null);
  const role = computed<Role | null>(() => user.value?.role ?? null);
  const isAdmin = computed(() => role.value === 'ADMIN');
  const isPatient = computed(() => role.value === 'USER');
  // ADMIN y DOCTOR: reservan y cancelan las citas de cualquier paciente
  const isManager = computed(() => role.value === 'ADMIN' || role.value === 'DOCTOR');

  // la página de inicio de cada rol, justo después de iniciar sesión
  const homePage = computed(() => (isPatient.value ? '/my-area' : '/schedule'));

  // llamada por la guardia del enrutador antes de CADA navegación; solo consulta
  // al servidor la primera vez (la promesa se conserva y se reutiliza)
  function check(): Promise<void> {
    checking ??= rdvApi
      .me()
      .then((u) => {
        user.value = u;
      })
      .catch(() => {
        user.value = null; // 401: nadie; o servidor inalcanzable
      });
    return checking;
  }

  async function logIn(login: string, password: string, captchaId: string, captcha: string): Promise<void> {
    user.value = await rdvApi.logIn(login, password, captchaId, captcha);
  }

  // el usuario ha cambiado de nombre o de login (PUT /api/my-account)
  function update(u: User): void {
    user.value = u;
  }

  async function logOut(): Promise<void> {
    try {
      await rdvApi.logOut();
    } finally {
      forget();
    }
  }

  // sin preguntarle nada al servidor: sesión expirada, cuenta eliminada
  function forget(): void {
    user.value = null;
  }

  return {
    user,
    loggedIn,
    role,
    isAdmin,
    isPatient,
    isManager,
    homePage,
    check,
    logIn,
    update,
    logOut,
    forget,
  };
});
  • Línea 21: el usuario conectado, tal como lo describe el servidor. El token en sí no está aquí: está en una cookie que solo maneja el navegador;
  • líneas 25–30: lo que se infiere de ello, utilizado por las páginas y la barra de navegación;
  • línea 33: la página de inicio de cada rol: “Mi área” para un paciente, el calendario para los demás;
  • líneas 37–47: la pregunta “¿Quién ha iniciado sesión?”, formulada al servidor solo la PRIMERA vez. La promesa se conserva en [checking]: las llamadas posteriores la reutilizan (el operador [??=] solo asigna un valor si la variable es [null] o [undefined]). No puede fallar: un error (401, servidor inaccesible) significa “nadie”;
  • líneas 49–51: el inicio de sesión. Si falla, [rdvApi.logIn] rechaza su promesa con un [ApiError], que atraviesa esta función hasta llegar a la página de inicio de sesión;
  • línea 54: tras modificar su cuenta, el paciente pudo haber cambiado de nombre;
  • líneas 58–64: [finally]: se olvida al usuario, incluso si el servidor no respondió;
  • línea 67: sin hacer ninguna solicitud al servidor (sesión vencida, cuenta eliminada).

10.9.2. src/stores/messages.ts

// =========================================================================
// stores/messages.ts - los mensajes mostrados al usuario
// -------------------------------------------------------------------------
// La misma presentación que la aplicación HTML:
//   - un ÉXITO se muestra en la PARTE SUPERIOR de la página (banner verde);
//   - un ERROR en la PARTE INFERIOR, sobre un fondo rosa claro (panel "sticky").
// Un mensaje es una CLAVE de traducción (+ sus parámetros): por lo tanto se
// traduce de nuevo por sí solo si el usuario cambia de idioma.
//
// Los mensajes "flash": una acción que termina con un cambio de
// página (reserva, alta de un médico...) deja su mensaje con flash();
// se mostrará en la SIGUIENTE página, y desaparecerá en la navegación
// siguiente (vea router.afterEach en router.ts). Del lado del servidor, ese era el
// papel de la cookie efímera "rdvmedecins_flash".
// =========================================================================

import { ref } from 'vue';
import { defineStore } from 'pinia';
import { ApiError } from '../api/http-client';

export interface Message {
  key: string;
  params?: Record<string, string>;
}

export const useMessagesStore = defineStore('messages', () => {
  const success = ref<Message | null>(null);
  const error = ref<Message | null>(null);
  // los mensajes a mostrar en la siguiente página
  let pending: { success: Message | null; error: Message | null } | null = null;

  function showSuccess(key: string, params?: Record<string, string>): void {
    success.value = { key, params };
    error.value = null;
  }

  function showError(key: string, params?: Record<string, string>): void {
    error.value = { key, params };
    success.value = null;
  }

  // un ApiError -> el mensaje de la página; cualquier otro error es una
  // anomalía del cliente, que se deja pasar (consola del navegador)
  function showApiError(e: unknown): void {
    if (!(e instanceof ApiError)) {
      throw e;
    }
    showError(e.key, e.params);
  }

  function clear(): void {
    success.value = null;
    error.value = null;
  }

  // para la SIGUIENTE página
  function flash(type: 'success' | 'error', key: string, params?: Record<string, string>): void {
    pending ??= { success: null, error: null };
    pending[type] = { key, params };
  }

  // llamada después de cada navegación (router.afterEach)
  function newPage(): void {
    success.value = pending?.success ?? null;
    error.value = pending?.error ?? null;
    pending = null;
  }

  return { success, error, showSuccess, showError, showApiError, clear, flash, newPage };
});
  • líneas 21–24: un mensaje consta de una CLAVE de traducción y sus parámetros. Por lo tanto, se traduce automáticamente si el usuario cambia de idioma;
  • líneas 27–28: el mensaje de éxito (mostrado en la parte superior) y el mensaje de error (en la parte inferior) de la página actual;
  • líneas 44–49: un [ApiError] se convierte en el mensaje de la página. Cualquier otro error es una anomalía del CLIENTE (un error de programación): puede registrarse y se mostrará en la consola del navegador;
  • líneas 57–60: un mensaje para la SIGUIENTE página. Una acción que provoca un cambio de página (reservar, agregar un médico, iniciar sesión tras crear una cuenta) muestra este mensaje antes de navegar a la página siguiente;
  • líneas 63–67: se llama después de cada navegación entre páginas (véase [router.ts]): los mensajes de la página anterior desaparecen y aparecen los mensajes pendientes. En la aplicación HTML, este era el papel de la cookie de corta duración [rdvmedecins_flash].

10.10. Los composables

10.10.1. src/composables/useConfirmation.ts

El composable del Ejemplo 12, con tres diferencias:

// =========================================================================
// composables/useConfirmation.ts - "Are you sure?"
// -------------------------------------------------------------------------
// Tomado del ejemplo 12: confirm(key) abre el cuadro de diálogo de confirmación
// (components/ConfirmDialog.vue, colocado una vez en App.vue) y
// devuelve una promesa resuelta a true (Sí) o false (No). El mensaje es
// una CLAVE de traducción: el cuadro de diálogo la traduce al idioma actual.
//
//     if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }
// =========================================================================

import { readonly, ref } from 'vue';
import { useMessagesStore } from '../stores/messages';

const messageKey = ref<string | null>(null); // null: cuadro de diálogo cerrado
let answer: ((yes: boolean) => void) | null = null;

export function useConfirmation() {
  function confirm(key: string): Promise<boolean> {
    answer?.(false); // ¿una pregunta todavía abierta? cuenta como "no"
    // una nueva pregunta: los mensajes de la acción anterior quedan obsoletos
    useMessagesStore().clear();
    messageKey.value = key;
    return new Promise<boolean>((resolve) => {
      answer = resolve;
    });
  }

  function respond(yes: boolean): void {
    messageKey.value = null;
    const r = answer;
    answer = null;
    r?.(yes);
  }

  return { messageKey: readonly(messageKey), confirm, respond };
}
  • línea 19: el mensaje es una CLAVE de traducción: la ventana la traduce al idioma actual;
  • línea 20: una pregunta abierta (escenario improbable) recibe la respuesta “no”;
  • línea 22: una nueva pregunta deja obsoletos los mensajes de la acción anterior.

10.10.2. src/composables/useFormatting.ts

// =========================================================================
// composables/useFormatting.ts - la visualización de personas, horas y días
// -------------------------------------------------------------------------
// El servidor envía datos SIN PROCESAR (startHour: 8, startMinute: 0; day:
// "2026-10-05"); el formato, que depende del idioma, es asunto
// del cliente. longDate() sigue el idioma actual de vue-i18n.
// =========================================================================

import { useI18n } from 'vue-i18n';
import type { Slot, Identity } from '../api/types';

// "Mme Alice DURAND"
export function label(p: Identity): string {
  return `${p.title} ${p.firstName} ${p.lastName}`;
}

// "8:05" en lugar de "8:5"
export function time(h: number, m: number): string {
  return `${h}:${String(m).padStart(2, '0')}`;
}

// "8:00 - 8:20"
export function timeRange(s: Slot): string {
  return `${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}`;
}

// la fecha de hoy, en el formato "yyyy-MM-dd" (el de <input type="date"> y de la API)
export function today(): string {
  const d = new Date();
  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}

// true si [day] es una fecha que existe en el formato yyyy-MM-dd
export function isValidDate(day: unknown): day is string {
  if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
    return false;
  }
  const date = new Date(`${day}T00:00:00Z`);
  return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}

export function useFormatting() {
  const { locale } = useI18n();

  // "lundi 5 octobre 2026" / "Monday 5 October 2026"
  function longDate(day: string): string {
    return new Intl.DateTimeFormat(locale.value === 'en' ? 'en-GB' : 'fr-FR', {
      dateStyle: 'full',
      timeZone: 'UTC', // "2026-10-05T00:00:00Z" debe seguir siendo el 5, sin importar la zona horaria
    }).format(new Date(`${day}T00:00:00Z`));
  }

  return { label, time, timeRange, longDate };
}

El servidor envía datos sin procesar ([startHour: 8, startMinute: 0], [day: "2026-10-05"]); dar formato a estos datos, que depende del idioma, es responsabilidad del cliente:

  • líneas 13–39: funciones ordinarias, no reactivas, exportadas una por una;
  • líneas 42–54: un composable, porque [longDate] requiere el idioma ACTUAL, que obtiene mediante [useI18n()]. Cuando cambia el idioma, se vuelve a calcular una plantilla que muestre [longDate(...)] ;
  • línea 49: [new Date("2026-10-05T00:00:00Z")] es medianoche UTC; mostrada en la zona horaria de París, seguiría siendo el 5 de octubre, ¡pero en Nueva York sería el 4 de octubre! Por eso se solicita una visualización en la zona horaria UTC.

10.10.3. src/composables/useForm.ts

// =========================================================================
// composables/useForm.ts - los errores de un formulario enviado al servidor
// -------------------------------------------------------------------------
// Todos los formularios de la aplicación siguen el mismo patrón que el
// ejemplo 20: ninguna regla se verifica en el navegador (viven
// en UN solo lugar, el servidor), y ante un rechazo:
//   - el error de cada campo (ApiError.fields) se muestra debajo del campo,
//     resaltado en rojo;
//   - el mensaje general (ApiError.key) se muestra al final de la página.
// Este composable agrupa este estado y estas acciones.
// =========================================================================

import { ref } from 'vue';
import { ApiError } from '../api/http-client';
import { useMessagesStore } from '../stores/messages';

export function useForm() {
  const messages = useMessagesStore();
  const errors = ref<Record<string, string>>({}); // campo -> clave del mensaje
  const params = ref<Record<string, string>>({}); // parámetros de los mensajes ({min}...)
  const submitting = ref(false);

  function clearErrors(): void {
    errors.value = {};
    params.value = {};
  }

  // ejecuta el envío; devuelve true si tuvo éxito. Ante un ApiError, los
  // errores se muestran y se devuelve false.
  async function submit(action: () => Promise<void>): Promise<boolean> {
    clearErrors();
    submitting.value = true;
    try {
      await action();
      return true;
    } catch (e) {
      if (e instanceof ApiError) {
        errors.value = e.fields;
        params.value = e.params;
      }
      messages.showApiError(e);
      return false;
    } finally {
      submitting.value = false;
    }
  }

  return { errors, params, submitting, submit, clearErrors };
}

Todos los formularios de la aplicación siguen el enfoque mostrado en el Ejemplo 20: ninguna regla se valida en el navegador; el servidor valida todo y los errores se muestran debajo de los campos. Este composable agrupa el estado y las acciones comunes:

  • líneas 19–21: el error de cada campo, los parámetros del mensaje y un indicador de envío (el botón se deshabilita durante el envío para evitar el doble clic);
  • líneas 30–46: ejecuta el envío (una función proporcionada por la página); si se produce un [ApiError], borra los errores de los campos, muestra el mensaje general en la parte inferior de la página y devuelve [false].

10.11. El enrutador

// =========================================================================
// router.ts - las páginas de la aplicación y sus derechos de acceso
// -------------------------------------------------------------------------
// Las MISMAS direcciones que la aplicación HTML (/login, /schedule, /doctors,
// /my-area...), pero ahora son rutas del CLIENTE:
// createWebHistory produce direcciones "limpias", sin #. El navegador
// envía una solicitud al servidor solo para la primerísima página; después,
// el enrutador cambia la dirección y el componente mostrado.
//
// La otra cara de la moneda: si el usuario recarga /schedule (F5), el
// navegador efectivamente solicita /schedule al servidor, que debe entonces
// devolver index.html (Vite lo hace en desarrollo; en producción, vea
// web/client-spa.ts del servidor JSON).
//
// Cada ruta lleva metadatos (meta):
//   - title   : clave de traducción del título de la pestaña;
//   - public  : accesible sin haber iniciado sesión;
//   - roles   : los roles permitidos (ausente = todos los roles con sesión iniciada);
//   - type    : 'doctors' o 'clients' para las páginas comunes a ambos.
//
// RECORDATORIO: estas verificaciones son solo una COMODIDAD (no mostrar una
// página inútil). Los datos están protegidos por el servidor, que
// verifica de nuevo el token y el rol en CADA solicitud.
// =========================================================================

import { createRouter, createWebHistory } from 'vue-router';
import type { Role } from './api/types';
import type { PersonType } from './api/rdvmedecins.api';
import { i18n } from './i18n';
import { useSessionStore } from './stores/session';
import { useMessagesStore } from './stores/messages';
import { rdvApi } from './api/rdvmedecins.api';
import LoginView from './views/LoginView.vue';
import ScheduleView from './views/ScheduleView.vue';

declare module 'vue-router' {
  interface RouteMeta {
    title: string;
    public?: boolean;
    roles?: Role[];
    type?: PersonType;
  }
}

// las rutas para gestionar médicos Y clientes (ADMIN), con el mismo modelo
function personRoutes(type: PersonType, title: string, addTitle: string, editTitle: string) {
  const roles: Role[] = ['ADMIN'];
  return [
    { path: `/${type}`, name: type, component: () => import('./views/PersonsView.vue'), meta: { title, roles, type } },
    {
      path: `/${type}/add`,
      name: `${type}-add`,
      component: () => import('./views/PersonFormView.vue'),
      meta: { title: addTitle, roles, type },
    },
    {
      path: `/${type}/:id(\\d+)/edit`, // (\\d+): el id debe ser un número
      name: `${type}-edit`,
      component: () => import('./views/PersonFormView.vue'),
      props: (route: { params: { id?: string | string[] } }) => ({ id: Number(route.params.id) }),
      meta: { title: editTitle, roles, type },
    },
  ];
}

export const router = createRouter({
  history: createWebHistory(),
  routes: [
    // "/": a /login, que a su vez envía a la página de inicio del rol si hay sesión iniciada
    { path: '/', redirect: '/login' },
    { path: '/login', name: 'login', component: LoginView, meta: { title: 'LOGIN.TITLE', public: true } },
    { path: '/schedule', name: 'schedule', component: ScheduleView, meta: { title: 'SCHEDULE.PAGE_TITLE' } },
    ...personRoutes('doctors', 'DOCTORS.TITLE', 'DOCTORS.ADD', 'DOCTORS.EDIT'),
    ...personRoutes('clients', 'CLIENTS.TITLE', 'CLIENTS.ADD', 'CLIENTS.EDIT'),
    {
      path: '/register',
      name: 'register',
      component: () => import('./views/RegisterView.vue'),
      meta: { title: 'REGISTRATION.TITLE', public: true },
      // una guardia ESPECÍFICA de la ruta: sin pase (captcha resuelto en la
      // página de inicio de sesión), de vuelta a la página de inicio de sesión
      beforeEnter: async () => {
        const { valid } = await rdvApi.registrationAccessStatus().catch(() => ({ valid: false }));
        if (!valid) {
          useMessagesStore().flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
          return { name: 'login' };
        }
        return true;
      },
    },
    {
      path: '/my-area',
      name: 'my-area',
      component: () => import('./views/PatientAreaView.vue'),
      meta: { title: 'AREA.TITLE', roles: ['USER'] },
    },
    {
      path: '/my-account',
      name: 'my-account',
      component: () => import('./views/MyAccountView.vue'),
      meta: { title: 'MY_ACCOUNT.TITLE', roles: ['USER'] },
    },
    {
      path: '/forbidden',
      name: 'forbidden',
      component: () => import('./views/ErrorView.vue'),
      props: { code: 403 },
      meta: { title: 'ERROR_PAGE.TITLE' },
    },
    {
      path: '/:pathMatch(.*)*',
      name: 'not-found',
      component: () => import('./views/ErrorView.vue'),
      props: { code: 404 },
      meta: { title: 'ERROR_PAGE.TITLE', public: true },
    },
  ],
});

// -------------------------------------------------------------------------
// la guardia GLOBAL, antes de cada navegación
// -------------------------------------------------------------------------
router.beforeEach(async (to) => {
  const session = useSessionStore();
  // la primera vez (arranque, F5): le preguntamos al servidor quién ha iniciado sesión
  await session.check();

  if (to.meta.public) {
    // ya con sesión iniciada: la página de inicio de sesión ya no tiene sentido
    if (to.name === 'login' && session.loggedIn) {
      return session.homePage;
    }
    return true;
  }
  if (!session.loggedIn) {
    // la página solicitada se recuerda, para volver a ella después de iniciar sesión
    return { name: 'login', query: { redirect: to.fullPath } };
  }
  if (to.meta.roles && !to.meta.roles.includes(session.role!)) {
    return { name: 'forbidden' };
  }
  return true;
});

// -------------------------------------------------------------------------
// después de cada navegación: mensajes "flash", título de la pestaña
// -------------------------------------------------------------------------
router.afterEach((to, from) => {
  // una navegación que cambia solo la query (/schedule?...) sigue siendo una
  // "página" nueva: como con la aplicación HTML, los mensajes de la
  // página anterior desaparecen, los mensajes flash aparecen
  if (to.fullPath !== from.fullPath) {
    useMessagesStore().newPage();
  }
  document.title = `${i18n.global.t(to.meta.title)} - ${i18n.global.t('APP.TITLE')}`;
});
  • líneas 36–43: metadatos de nuestras rutas: el título de la pestaña (una clave de traducción), el acceso público, los roles autorizados y el tipo de usuario;
  • Líneas 46–64: las tres rutas de gestión de médicos (lista, alta, edición) y las mismas tres para los clientes, generadas por una función. Las páginas se cargan bajo demanda ([() => import(...)]): un paciente nunca descargará el código de gestión de médicos;
  • Línea 57: [(\d+)]: una expresión regular restringe el parámetro [id] a números. [/doctors/abc/edit] no coincide con esta ruta: se muestra la página “página no encontrada”;
  • línea 60: la propiedad [id] del componente, convertida a número;
  • línea 67: direcciones “limpias”, sin [#];
  • línea 70: la dirección [/] conduce a [/login], que a su vez conduce a la página de inicio del rol cuando hay una sesión iniciada;
  • líneas 82–89: una guardia ESPECÍFICA de una ruta, ejecutada antes de entrar en ella: sin un pase (CAPTCHA resuelto en la página de inicio de sesión), la creación de cuenta redirige a la página de inicio de sesión con un mensaje;
  • línea 107: [props] también puede ser un objeto estático: se usa la misma página de error para los errores 403 y 404;
  • Líneas 123–143: la guardia GLOBAL, antes de cada navegación:
    • [await session.check()]: la primera vez (al iniciar, F5), se consulta al servidor para saber quién ha iniciado sesión. La guardia es [async]: la navegación espera la respuesta;
    • una página pública siempre es accesible; sin embargo, la página de inicio de sesión, para un usuario con sesión iniciada, redirige a su página de inicio;
    • sin sesión iniciada: página de inicio de sesión, conservando la página solicitada;
    • rol no válido: página 403;
  • líneas 148–156: después de cada navegación: los mensajes se muestran una sola vez (flash) y se traduce el título de la pestaña. [i18n.global.t]: fuera de un componente, se usa directamente el objeto [i18n].

10.12. Los componentes

10.12.1. src/components/NavBar.vue

<!--
  =========================================================================
  components/NavBar.vue - la barra de navegación
  -------------------------------------------------------------------------
  Mismo contenido que la de la aplicación HTML (views/partials/navbar.hbs):
  título, menús según el rol, FR / EN, rol, nombre, logout.
  "Doctors" y "Patients" aparecen solo para el ADMIN: una mera comodidad
  de visualización, siendo la protección real la del servidor.
  =========================================================================
-->
<script setup lang="ts">
import { RouterLink, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { useSessionStore } from '../stores/session';
import { changeLanguage, LANGUAGES } from '../i18n';

const { t, locale } = useI18n();
const session = useSessionStore();
const router = useRouter();

async function logOut(): Promise<void> {
  await session.logOut().catch(() => {}); // incluso si el servidor no responde
  router.push({ name: 'login' });
}
</script>

<template>
  <nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
    <span class="navbar-brand mb-0">{{ t('APP.TITLE') }}</span>

    <ul v-if="session.loggedIn" class="navbar-nav me-auto">
      <li v-if="session.isPatient" class="nav-item">
        <!-- active-class: la clase de Bootstrap del menú de la página mostrada -->
        <RouterLink class="nav-link" active-class="active" to="/my-area">{{ t('APP.MENU_MY_AREA') }}</RouterLink>
      </li>
      <li class="nav-item">
        <RouterLink class="nav-link" active-class="active" to="/schedule">{{ t('APP.MENU_SCHEDULE') }}</RouterLink>
      </li>
      <template v-if="session.isAdmin">
        <li class="nav-item">
          <RouterLink class="nav-link" active-class="active" to="/doctors">{{ t('APP.MENU_DOCTORS') }}</RouterLink>
        </li>
        <li class="nav-item">
          <RouterLink class="nav-link" active-class="active" to="/clients">{{ t('APP.MENU_PATIENTS') }}</RouterLink>
        </li>
      </template>
    </ul>
    <div v-else class="me-auto"></div>

    <div class="d-flex align-items-center gap-2">
      <!-- FR / EN: sin solicitud al servidor, la página se traduce de nuevo en su lugar -->
      <div class="btn-group btn-group-sm" role="group" :aria-label="t('APP.LANGUAGE')">
        <button
          v-for="l in LANGUAGES"
          :key="l"
          type="button"
          class="btn"
          :class="locale === l ? 'btn-light' : 'btn-outline-light'"
          :aria-pressed="locale === l"
          @click="changeLanguage(l)"
        >
          {{ l.toUpperCase() }}
        </button>
      </div>

      <template v-if="session.user">
        <span class="badge text-bg-light text-primary">{{ session.user.role }}</span>
        <span class="text-white">{{ session.user.name }}</span>
        <button type="button" class="btn btn-sm btn-outline-light" @click="logOut">{{ t('APP.LOGOUT') }}</button>
      </template>
    </div>
  </nav>
</template>
  • líneas 21–24: cierre de sesión, seguido de la página de inicio de sesión. [.catch(() => {})]: incluso si el servidor no responde, el cliente se desconecta;
  • línea 31: los menús solo aparecen una vez iniciada la sesión, según el rol: “Mi área” para un paciente, “Médicos” y “Pacientes” para el ADMIN. Esto es solo por comodidad de visualización; la verdadera seguridad la proporciona el servidor;
  • línea 34: al menú de la página mostrada se le asigna la clase [active];
  • líneas 53–63: los botones FR / EN. [:aria-pressed] indica a los lectores de pantalla qué botón está presionado;
  • línea 66: el rol, el nombre y la función de cierre de sesión.

10.12.2. src/components/SuccessMessage.vue y ErrorPanel.vue

<!--
  components/SuccessMessage.vue - el mensaje de ÉXITO, en la parte superior de la página
  (cita reservada, médico agregado...) - vea stores/messages.ts.
  role="status": un lector de pantalla lo anuncia sin interrumpir al usuario.
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import { useMessagesStore } from '../stores/messages';

const { t } = useI18n();
const messages = useMessagesStore();
</script>

<template>
  <div v-if="messages.success" class="alert alert-success" role="status">
    {{ t(messages.success.key, messages.success.params ?? {}) }}
  </div>
</template>
<!--
  components/ErrorPanel.vue - el panel de errores, en la parte INFERIOR de cada página, sobre un
  fondo rosa claro (clase .error-panel, vea styles.css) - como
  views/partials/errors.hbs de la aplicación HTML.
  role="alert": un lector de pantalla anuncia el mensaje apenas aparece.
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import { useMessagesStore } from '../stores/messages';

const { t } = useI18n();
const messages = useMessagesStore();
</script>

<template>
  <div v-if="messages.error" class="error-panel" role="alert">
    {{ t(messages.error.key, messages.error.params ?? {}) }}
  </div>
</template>

Dos componentes muy cortos que muestran los mensajes del store [messages], traducidos al idioma actual:

  • línea 16: un lector de pantalla anuncia el mensaje de error en cuanto aparece, incluso si está al final de la página; el mensaje de éxito es [role="status"], y se anuncia sin interrumpir al usuario.

10.12.3. src/components/ConfirmDialog.vue

<!--
  =========================================================================
  components/ConfirmDialog.vue - el diálogo "Are you sure?"
  -------------------------------------------------------------------------
  El del ejemplo 12, completado para el teclado como public/js/app.js
  de la aplicación HTML:
    - al abrir, el foco va a "No, go back": una pulsación distraída de
      Enter no elimina nada;
    - Escape cierra el diálogo (= No);
    - Tab y Shift+Tab permanecen DENTRO del diálogo (de lo contrario el foco iría a
      la página atenuada, detrás);
    - al cerrar, el foco regresa al elemento que lo tenía (el botón
      "Delete" en el que se hizo clic, por ejemplo).
  "No, go back" en lugar de "Cancel": la pregunta a veces es "Cancel this
  appointment?", y un botón "Cancel" sería ambiguo ahí.
  =========================================================================
-->
<script setup lang="ts">
import { nextTick, useTemplateRef, watch } from 'vue';
import { useI18n } from 'vue-i18n';
import { useConfirmation } from '../composables/useConfirmation';

const { t } = useI18n();
const { messageKey, respond } = useConfirmation();
const dialog = useTemplateRef<HTMLElement>('dialog');
const noButton = useTemplateRef<HTMLButtonElement>('noButton');
let previousFocus: HTMLElement | null = null;

watch(messageKey, async (key, oldKey) => {
  if (key !== null && oldKey === null) {
    previousFocus = document.activeElement as HTMLElement | null;
    await nextTick(); // el cuadro de diálogo ahora está en la página
    noButton.value?.focus();
  } else if (key === null) {
    previousFocus?.focus();
    previousFocus = null;
  }
});

function onKeydown(e: KeyboardEvent): void {
  if (e.key === 'Escape') {
    respond(false);
  } else if (e.key === 'Tab' && dialog.value) {
    const buttons = [...dialog.value.querySelectorAll<HTMLButtonElement>('button')];
    const first = buttons[0];
    const last = buttons[buttons.length - 1];
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last?.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first?.focus();
    }
  }
}
</script>

<template>
  <Teleport to="body">
    <div v-if="messageKey !== null" @keydown="onKeydown">
      <div class="modal-backdrop fade show"></div>
      <div
        ref="dialog"
        class="modal fade show d-block"
        tabindex="-1"
        role="alertdialog"
        aria-modal="true"
        aria-labelledby="confirmation-title"
        aria-describedby="confirmation-message"
        @click.self="respond(false)"
      >
        <div class="modal-dialog modal-dialog-centered">
          <div class="modal-content">
            <div class="modal-header">
              <h5 id="confirmation-title" class="modal-title">{{ t('CONFIRMATION.TITLE') }}</h5>
              <button type="button" class="btn-close" :aria-label="t('BOOKING_DIALOG.CLOSE_ARIA')" @click="respond(false)"></button>
            </div>
            <div class="modal-body">
              <p id="confirmation-message" class="mb-0">{{ t(messageKey) }}</p>
            </div>
            <div class="modal-footer">
              <button ref="noButton" type="button" class="btn btn-secondary" @click="respond(false)">{{ t('CONFIRMATION.NO') }}</button>
              <button type="button" class="btn btn-danger" @click="respond(true)">{{ t('CONFIRMATION.YES') }}</button>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Teleport>
</template>

La ventana del Ejemplo 12, mejorada para la navegación con teclado mediante el script [public/js/app.js] de la aplicación HTML:

  • líneas 29–38: al abrirse, se conserva el elemento que tenía el foco (el botón “Eliminar” en el que se hizo clic, por ejemplo) y luego se da el foco al botón “No, volver”; al cerrarse, el foco se devuelve al elemento conservado. Un usuario que navega con el teclado recupera así su posición en la página;
  • líneas 40–55: Esc se trata como “No”; Tab y Shift+Tab permanecen dentro de la ventana: al llegar al último botón, Tab vuelve al primero (de lo contrario, el foco pasaría a la página atenuada que está detrás);
  • línea 60: la propia ventana maneja la entrada de teclado: no hace falta agregar ni quitar un listener en el documento;
  • línea 68: para los lectores de pantalla, el título y el mensaje de la ventana;
  • línea 79: el mensaje, traducido.

10.12.4. src/components/InputField.vue

Un campo de formulario completo, reutilizado por todos los formularios de la aplicación:

<!--
  =========================================================================
  components/InputField.vue - un campo de formulario completo
  -------------------------------------------------------------------------
  Etiqueta + campo + mensaje de ayuda O mensaje de error, con v-model (vea el
  ejemplo 08). Todos los formularios de la aplicación lo usan:

    <InputField v-model="form.lastName" id="lastName" label="PERSONS.LASTNAME_LABEL"
                :error="errors.lastName" :params="params" :maxlength="20" />

  label, help y error son CLAVES de traducción. Un error resalta el
  campo en rojo (clase de Bootstrap is-invalid) y reemplaza la ayuda.
  =========================================================================
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';

const model = defineModel<string>({ required: true });

withDefaults(
  defineProps<{
    id: string;
    label: string;
    type?: 'text' | 'password';
    error?: string; // clave del mensaje de error de este campo
    params?: Record<string, string>; // parámetros de los mensajes ({min}...)
    help?: string; // clave del mensaje de ayuda
    maxlength?: number;
    autocomplete?: string;
    required?: boolean;
  }>(),
  { type: 'text', error: undefined, params: () => ({}), help: undefined, maxlength: undefined, autocomplete: 'off', required: false },
);

const { t } = useI18n();
</script>

<template>
  <div>
    <label class="form-label" :for="id">{{ t(label) }}</label>
    <input
      :id="id"
      v-model="model"
      :type="type"
      class="form-control"
      :class="{ 'is-invalid': error }"
      :maxlength="maxlength"
      :autocomplete="autocomplete"
      :required="required"
      :aria-invalid="error ? 'true' : undefined"
      :aria-describedby="`${id}-message`"
    >
    <div v-if="error" :id="`${id}-message`" class="invalid-feedback">{{ t(error, params) }}</div>
    <div v-else-if="help" :id="`${id}-message`" class="form-text">{{ t(help, params) }}</div>
  </div>
</template>
  • línea 18: el campo se usa con [v-model] (véase el ejemplo 08);
  • líneas 20–33: las props: el ID del campo y las CLAVES de traducción de la etiqueta, la información sobre herramientas y el mensaje de error;
  • línea 46: un error resalta el campo en rojo;
  • línea 51: el mensaje de ayuda o de error se asocia con el campo para los lectores de pantalla;
  • líneas 53–54: el mensaje de error SUSTITUYE al texto de ayuda.

Cuando se coloca dentro de un componente padre, el componente también hereda los atributos que este le transmite, aunque no sean props: [<InputField class="col-sm-6" ...>] agrega la clase [col-sm-6] a su elemento raíz, [<div>] (son los llamados atributos “heredados”, [fallthrough attributes]).

10.12.5. src/components/PersonFields.vue

El título, el nombre y el apellido son comunes a tres formularios:

<!--
  =========================================================================
  components/PersonFields.vue - título, nombre, apellido
  -------------------------------------------------------------------------
  Los campos de identidad, comunes a tres formularios: el formulario de médico / cliente
  del ADMIN, "Create a patient account" y "Manage my account" (el equivalente de la
  vista parcial views/partials/personFields.hbs). Tres v-model con nombre:
      <PersonFields v-model:title="f.title" v-model:firstName="f.firstName"
                    v-model:lastName="f.lastName" :errors="errors" />
  =========================================================================
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import InputField from './InputField.vue';

const title = defineModel<string>('title', { required: true });
const firstName = defineModel<string>('firstName', { required: true });
const lastName = defineModel<string>('lastName', { required: true });
defineProps<{ errors: Record<string, string> }>();

const { t } = useI18n();
const TITLES = ['Mr', 'Mme', 'Melle'];
</script>

<template>
  <div class="mb-3">
    <label class="form-label" for="title">{{ t('PERSONS.TITLE_LABEL') }}</label>
    <select id="title" v-model="title" class="form-select" :class="{ 'is-invalid': errors.title }">
      <option v-for="tt in TITLES" :key="tt" :value="tt">{{ tt }}</option>
    </select>
    <div v-if="errors.title" class="invalid-feedback">{{ t(errors.title) }}</div>
  </div>
  <div class="row g-3 mb-3">
    <InputField v-model="firstName" class="col-sm-6" id="firstName" label="PERSONS.FIRSTNAME_LABEL" :error="errors.firstName" :maxlength="20" required />
    <InputField v-model="lastName" class="col-sm-6" id="lastName" label="PERSONS.LASTNAME_LABEL" :error="errors.lastName" :maxlength="20" required />
  </div>
</template>
  • Líneas 16–18: tres campos [v-model] con nombre: el padre escribe [v-model:title="..."], [v-model:firstName="..."], [v-model:lastName="..."];
  • línea 34: los dos campos de texto son [InputField]. [firstName] es el [ref] de [defineModel]: la cadena padre-hijo -> PersonFields -> InputField -> [<input>] funciona en ambos sentidos.

Un componente puede tener varios elementos raíz (aquí, el [<div>] del título y la fila que contiene los dos campos): esto se denomina “fragmento”.

10.12.6. src/components/CaptchaField.vue

<!--
  =========================================================================
  components/CaptchaField.vue - la imagen del captcha y el campo de entrada
  -------------------------------------------------------------------------
  Carga un captcha (GET /api/captcha) cuando se muestra. El padre obtiene
  la entrada mediante v-model, y el identificador del captcha mediante el método
  expuesto captchaId(); llama a reload() después de cada intento, porque una
  imagen se usa solo UNA vez (el servidor la olvida apenas la ha verificado).

  defineExpose: lo que un componente PADRE puede llamar en este componente,
  mediante un template ref (vea LoginView.vue).

  v-html: la imagen SVG se inserta tal cual. Inofensivo AQUÍ porque
  la construye nuestro servidor (biblioteca svg-captcha) y no
  contiene nada que provenga de un usuario - vea el ejemplo 17.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Captcha } from '../api/types';

const input = defineModel<string>({ required: true });
defineProps<{ error?: string }>();

const { t } = useI18n();
const captcha = ref<Captcha | null>(null);

async function reload(): Promise<void> {
  input.value = '';
  try {
    captcha.value = await rdvApi.captcha();
  } catch {
    captcha.value = null; // servidor inalcanzable: el inicio de sesión fallará con un mensaje claro
  }
}

defineExpose({ reload, captchaId: () => captcha.value?.id ?? '' });
onMounted(reload);
</script>

<template>
  <div class="mb-3">
    <label class="form-label" for="captcha">{{ t('CAPTCHA.LABEL') }}</label>
    <div class="d-flex align-items-center gap-3 mb-2">
      <div class="captcha-image" role="img" :aria-label="t('CAPTCHA.IMAGE_ALT')" v-html="captcha?.svg ?? ''"></div>
      <a href="#" class="small" @click.prevent="reload">{{ t('CAPTCHA.NEW_IMAGE') }}</a>
    </div>
    <input id="captcha" v-model="input" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false"
           class="form-control" :class="{ 'is-invalid': error }">
    <div v-if="error" class="invalid-feedback">{{ t(error) }}</div>
    <div v-else class="form-text">{{ t('CAPTCHA.HELP') }}</div>
  </div>
</template>
  • líneas 30–37: un nuevo CAPTCHA; se borra la entrada anterior;
  • línea 39: lo que el PADRE puede llamar en este componente, mediante una referencia de plantilla (véase [LoginView.vue]). Sin [defineExpose], un componente [<script setup>] no expone nada;
  • Línea 47: la imagen SVG, insertada tal cual: proviene de nuestro servidor (véase el Ejemplo 17).

10.12.7. src/components/BookingDialog.vue

<!--
  =========================================================================
  components/BookingDialog.vue - el diálogo para reservar un horario
  -------------------------------------------------------------------------
  El mismo diálogo que views/partials/booking.hbs de la aplicación HTML
  (y que el componente booking-dialog del cliente Angular): las clases de
  Bootstrap de un diálogo modal, mostrado "a la fuerza" (show d-block).

  El componente no habla con el servidor: emite
    - 'confirm' con el paciente elegido (null para un paciente que reserva
      para sí mismo);
    - 'close'.
  La página de la agenda decide qué hacer con ello (ScheduleView.vue).
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, onUnmounted, ref, useTemplateRef } from 'vue';
import { useI18n } from 'vue-i18n';
import type { Person } from '../api/types';
import { label } from '../composables/useFormatting';

const props = defineProps<{
  time: string; // "8:00 - 8:20"
  clients: Person[]; // ADMIN / DOCTOR: los pacientes entre los que elegir
  patient: string | null; // USER: el paciente es él mismo
  submitting: boolean;
}>();

const emit = defineEmits<{ confirm: [clientId: number | null]; close: [] }>();

const { t } = useI18n();
const clientId = ref<number | null>(null);
const list = useTemplateRef<HTMLSelectElement>('list');
const confirmButton = useTemplateRef<HTMLButtonElement>('confirmButton');

function onEscape(e: KeyboardEvent): void {
  if (e.key === 'Escape') {
    emit('close');
  }
}

onMounted(() => {
  // el foco en el primer elemento útil del cuadro de diálogo
  (props.patient === null ? list.value : confirmButton.value)?.focus();
  document.addEventListener('keydown', onEscape);
});
onUnmounted(() => document.removeEventListener('keydown', onEscape));
</script>

<template>
  <Teleport to="body">
    <div class="modal-backdrop fade show"></div>
    <div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title"
         @click.self="emit('close')">
      <div class="modal-dialog modal-dialog-centered">
        <form class="modal-content" @submit.prevent="emit('confirm', clientId)">
          <div class="modal-header">
            <h5 id="booking-title" class="modal-title">{{ t('BOOKING_DIALOG.TITLE') }}</h5>
            <button type="button" class="btn-close" :aria-label="t('BOOKING_DIALOG.CLOSE_ARIA')" @click="emit('close')"></button>
          </div>

          <div class="modal-body">
            <p>{{ t('BOOKING_DIALOG.SLOT', { time }) }}</p>
            <!-- un paciente reserva para sí mismo: sin lista (y el servidor
                 ignoraría de todos modos un posible clientId) -->
            <p v-if="patient !== null" class="mb-0">{{ t('BOOKING_DIALOG.PATIENT_LABEL') }}: <strong>{{ patient }}</strong></p>
            <template v-else>
              <label class="form-label" for="clientId">{{ t('BOOKING_DIALOG.PATIENT_LABEL') }}</label>
              <select id="clientId" ref="list" v-model="clientId" class="form-select">
                <option :value="null">{{ t('BOOKING_DIALOG.CHOOSE_PATIENT') }}</option>
                <option v-for="c in clients" :key="c.id" :value="c.id">{{ label(c) }}</option>
              </select>
            </template>
          </div>

          <div class="modal-footer">
            <button type="button" class="btn btn-secondary" @click="emit('close')">{{ t('BOOKING_DIALOG.CANCEL') }}</button>
            <button ref="confirmButton" type="submit" class="btn btn-primary" :disabled="submitting">{{ t('BOOKING_DIALOG.CONFIRM') }}</button>
          </div>
        </form>
      </div>
    </div>
  </Teleport>
</template>

La ventana de reserva de citas. No se comunica con el servidor: envía [confirm] con el paciente seleccionado, o [close]. La página del calendario decide qué hacer con ello.

  • líneas 22–27: el horario de la cita y, o bien la lista de pacientes (ADMIN, DOCTOR), o bien el nombre del paciente conectado (USER);
  • Líneas 42–46: al abrirse, el foco pasa al primer elemento aplicable (la lista de pacientes o el botón “Confirmar”); la tecla Esc cierra la ventana;
  • línea 56: un formulario real: la tecla Enter confirma;
  • línea 66: un paciente hace una reserva para sí mismo: sin lista.

10.13. Las páginas

10.13.1. src/views/LoginView.vue

<!--
  =========================================================================
  views/LoginView.vue - la página de inicio de sesión (/login)
  -------------------------------------------------------------------------
  La misma página que views/login.hbs de la aplicación HTML: login,
  contraseña, captcha, y un segundo botón "Create a patient account" que verifica
  el MISMO captcha antes de abrir la creación de cuenta.

  /login?login=jbernard: el campo login aparece rellenado (justo después de la
  creación de una cuenta).
  /login?redirect=/doctors: después de iniciar sesión, se abre esta página
  (establecida por el guard del enrutador) en lugar de la página de inicio del rol.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref, useTemplateRef } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { ApiError } from '../api/http-client';
import { rdvApi } from '../api/rdvmedecins.api';
import { useSessionStore } from '../stores/session';
import { useMessagesStore } from '../stores/messages';
import CaptchaField from '../components/CaptchaField.vue';

const { t } = useI18n();
const route = useRoute();
const router = useRouter();
const session = useSessionStore();
const messages = useMessagesStore();

const form = reactive({
  login: typeof route.query.login === 'string' ? route.query.login.slice(0, 30) : '',
  password: '',
  captcha: '',
});
const captchaError = ref<string | undefined>(undefined);
const submitting = ref(false);
const captchaField = useTemplateRef<InstanceType<typeof CaptchaField>>('captchaField');
const loginField = useTemplateRef<HTMLInputElement>('loginField');
const passwordField = useTemplateRef<HTMLInputElement>('passwordField');

// el foco: en la contraseña si el login ya está completado
onMounted(() => (form.login ? passwordField.value : loginField.value)?.focus());

// ambos botones comparten esta secuencia: envío y, en caso de fallo,
// mensaje de error y una imagen NUEVA (cada una se usa una sola vez)
async function attempt(action: () => Promise<void>): Promise<void> {
  messages.clear();
  captchaError.value = undefined;
  submitting.value = true;
  try {
    await action();
  } catch (e) {
    messages.showApiError(e);
    if (e instanceof ApiError) {
      captchaError.value = e.fields.captcha;
    }
    await captchaField.value?.reload();
  } finally {
    submitting.value = false;
  }
}

function logIn(): Promise<void> {
  return attempt(async () => {
    await session.logIn(form.login.trim(), form.password, captchaField.value?.captchaId() ?? '', form.captcha);
    const redirect = route.query.redirect;
    // solo una ruta INTERNA: nunca una redirección a otro sitio
    router.push(typeof redirect === 'string' && redirect.startsWith('/') && !redirect.startsWith('//') ? redirect : session.homePage);
  });
}

function createAccount(): Promise<void> {
  return attempt(async () => {
    await rdvApi.registrationAccess(captchaField.value?.captchaId() ?? '', form.captcha);
    router.push({ name: 'register' });
  });
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-sm-8 col-md-6 col-lg-5">
      <div class="card p-4">
        <h5 class="card-title mb-3">{{ t('LOGIN.TITLE') }}</h5>

        <form @submit.prevent="logIn">
          <div class="mb-3">
            <label class="form-label" for="login">{{ t('LOGIN.LOGIN_LABEL') }}</label>
            <input id="login" ref="loginField" v-model="form.login" type="text" class="form-control" autocomplete="username" required>
          </div>
          <div class="mb-3">
            <label class="form-label" for="password">{{ t('LOGIN.PASSWORD_LABEL') }}</label>
            <input id="password" ref="passwordField" v-model="form.password" type="password" class="form-control"
                   autocomplete="current-password" required>
          </div>

          <CaptchaField ref="captchaField" v-model="form.captcha" :error="captchaError" />

          <!-- type="submit": Enter en un campo activa "Log in" -->
          <button type="submit" class="btn btn-primary w-100" :disabled="submitting">{{ t('LOGIN.SUBMIT') }}</button>

          <!-- type="button": este botón no envía el formulario (sin verificación de
               required en login y contraseña, inútil aquí) -->
          <button type="button" class="btn btn-outline-primary w-100 mt-3" :disabled="submitting" @click="createAccount">
            {{ t('LOGIN.CREATE_ACCOUNT') }}
          </button>
          <div class="form-text text-center">{{ t('LOGIN.CREATE_ACCOUNT_HELP') }}</div>
        </form>

        <div class="text-muted small mt-3">
          {{ t('LOGIN.DEMO_ACCOUNTS') }}
          <ul class="mb-0 mt-1">
            <li><code>admin</code> - {{ t('LOGIN.DEMO_ADMIN') }}</li>
            <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {{ t('LOGIN.DEMO_DOCTOR') }}</li>
            <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {{ t('LOGIN.DEMO_USER') }}</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</template>
  • línea 32: [/login?login=jbernard] rellena previamente el campo de inicio de sesión (inmediatamente después de crear una cuenta);
  • línea 38: una referencia al COMPONENTE [CaptchaField]: podemos llamar a lo que expone ([reload()], [captchaId()]). [InstanceType<typeof CaptchaField>] es su tipo;
  • línea 43: el foco va al campo de contraseña si el nombre de usuario ya está completado;
  • líneas 47–62: ambos botones siguen la misma secuencia: envío; si no tiene éxito, aparece un mensaje de error, junto con un error debajo del campo CAPTCHA si corresponde, y una NUEVA imagen;
  • líneas 64–71: el inicio de sesión, seguido de la página solicitada antes de iniciar sesión (parámetro [redirect], establecido por el enrutador), o de la página de inicio del rol. Solo se acepta una ruta interna: debe comenzar con [/], pero no con [//] ([//site.com/...] se refiere a OTRO sitio);
  • líneas 73–78: “Crear una cuenta de paciente”: el servidor verifica el CAPTCHA y emite un token; luego se abre la página de creación de cuenta;
  • línea 105: [type="button"]: este botón no envía el formulario. En la aplicación HTML, era un segundo botón para enviar el mismo formulario a una dirección distinta ([formaction]).

10.13.2. src/views/ScheduleView.vue

La página principal. Como en la aplicación HTML, TODO su estado está en la URL:

1
2
3
/schedule                                           choice of the doctor and the day
/schedule?doctorId=1&day=2026-10-05                 the schedule
/schedule?doctorId=1&day=2026-10-05&book=7          + the booking dialog for slot 7
<!--
  =========================================================================
  views/ScheduleView.vue - la página de la agenda (/schedule)
  -------------------------------------------------------------------------
  Tres bloques, como views/schedule.hbs de la aplicación HTML:
    1. la elección del médico y del día;
    2. la agenda de ese médico en ese día;
    3. el diálogo para reservar un horario.

  Como en la aplicación HTML, TODO el estado de la página está en su URL:
      /schedule?doctorId=1&day=2026-10-05             la agenda
      /schedule?doctorId=1&day=2026-10-05&book=7      + el diálogo de reserva
  Por lo tanto, la página se puede recargar, guardar en marcadores, y se pueden usar los botones Atrás /
  Adelante del navegador. La página SIGUE a su URL: un watch sobre el
  query recarga la agenda; las acciones del usuario, en cambio, cambian
  la URL (router.push).

  Lo que cada usuario ve y puede hacer lo decide el SERVIDOR (campos
  patient, mine, bookable, appointmentId de cada horario): la página se limita a
  mostrarlo. Un paciente ni siquiera recibe el nombre de los demás pacientes.
  =========================================================================
-->
<script setup lang="ts">
import { computed, onMounted, reactive, ref, watch } from 'vue';
import { RouterLink, useRoute, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { ApiError } from '../api/http-client';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Schedule, ScheduleSlot, Person } from '../api/types';
import { today, isValidDate, label, useFormatting } from '../composables/useFormatting';
import { useConfirmation } from '../composables/useConfirmation';
import { useSessionStore } from '../stores/session';
import { useMessagesStore } from '../stores/messages';
import BookingDialog from '../components/BookingDialog.vue';

const { t } = useI18n();
const route = useRoute();
const router = useRouter();
const session = useSessionStore();
const messages = useMessagesStore();
const { timeRange, longDate } = useFormatting();
const { confirm } = useConfirmation();

const doctors = ref<Person[]>([]);
const clients = ref<Person[]>([]); // ADMIN / DOCTOR: para el cuadro de diálogo de reserva
const schedule = ref<Schedule | null>(null);
const loading = ref(false);
const submitting = ref(false);

// los valores del formulario "médico + día", copiados de la URL
const choice = reactive<{ doctorId: number | null; day: string }>({ doctorId: null, day: today() });

// "3" -> 3 ; "", "abc", "-2", ausente -> null
function positiveInteger(value: unknown): number | null {
  const n = Number(value);
  return typeof value === 'string' && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}

// la agenda mostrada, sin cuadro de diálogo de reserva: la query "back"
const scheduleQuery = computed(() => ({ doctorId: String(choice.doctorId ?? ''), day: choice.day }));

// la franja cuyo cuadro de diálogo de reserva está abierto (?book=7),
// solo si este usuario puede reservarla
const slotToBook = computed<ScheduleSlot | null>(() => {
  const id = positiveInteger(route.query.book);
  return schedule.value?.slots.find((s) => s.id === id && s.bookable) ?? null;
});

// -------------------------------------------------------------------------
// cargando
// -------------------------------------------------------------------------
onMounted(async () => {
  try {
    doctors.value = await rdvApi.list('doctors');
    // la lista de pacientes: solo para quienes tienen permiso de leerla
    if (session.isManager) {
      clients.value = await rdvApi.list('clients');
    }
  } catch (e) {
    messages.showApiError(e);
  }
});

// la agenda sigue la URL (médico y día)
watch(() => [route.query.doctorId, route.query.day], loadSchedule, { immediate: true });

async function loadSchedule(): Promise<void> {
  // el día: el de la URL si es válido, de lo contrario hoy
  const rawDay = route.query.day;
  choice.day = today();
  if (rawDay !== undefined) {
    if (!isValidDate(rawDay)) {
      schedule.value = null;
      messages.showError('ERRORS.INVALID_DATE');
      return;
    }
    choice.day = rawDay;
  }
  // el médico: el de la URL; sin médico, un DOCTOR ve SU agenda
  // (el servidor la encuentra a partir del token)
  choice.doctorId = positiveInteger(route.query.doctorId);
  if (choice.doctorId === null && session.role !== 'DOCTOR') {
    schedule.value = null;
    return;
  }
  loading.value = true;
  try {
    schedule.value = await rdvApi.schedule(choice.doctorId, choice.day);
    choice.doctorId = schedule.value.doctor.id;
  } catch (e) {
    schedule.value = null;
    messages.showApiError(e);
  } finally {
    loading.value = false;
  }
}

// -------------------------------------------------------------------------
// acciones
// -------------------------------------------------------------------------

// "View schedule": se cambia la URL, la agenda la sigue (watch de arriba)
function viewSchedule(): void {
  router.push({ query: scheduleQuery.value });
}

function closeBooking(): void {
  router.push({ query: scheduleQuery.value });
}

async function book(clientId: number | null): Promise<void> {
  const slot = slotToBook.value;
  if (slot === null) {
    return;
  }
  submitting.value = true;
  try {
    await rdvApi.book(choice.day, slot.id, session.isManager ? clientId : null);
    messages.flash('success', 'SCHEDULE.BOOKED');
  } catch (e) {
    if (e instanceof ApiError && e.key === 'ERRORS.CHOOSE_PATIENT') {
      // ningún paciente elegido: el cuadro de diálogo permanece abierto
      messages.showError(e.key);
      return; // (finally se ejecuta de todos modos)
    }
    if (!(e instanceof ApiError)) {
      throw e;
    }
    // franja tomada mientras tanto, paciente que ya tiene una cita...:
    // el mensaje se mostrará en la agenda, con el cuadro de diálogo cerrado
    messages.flash('error', e.key, e.params);
  } finally {
    submitting.value = false;
  }
  await router.push({ query: scheduleQuery.value });
  await loadSchedule(); // el servidor es la referencia: la agenda se lee de nuevo
}

async function cancel(s: ScheduleSlot): Promise<void> {
  if (s.appointmentId === null || !(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
    return;
  }
  try {
    await rdvApi.cancelAppointment(s.appointmentId);
    messages.showSuccess('SCHEDULE.CANCELLED');
  } catch (e) {
    messages.showApiError(e);
  }
  await loadSchedule();
}
</script>

<template>
  <!-- 1. la elección del médico y del día -->
  <form class="card p-3 mb-3" @submit.prevent="viewSchedule">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="doctorId">{{ t('DOCTOR_DAY_PICKER.DOCTOR_LABEL') }}</label>
        <select id="doctorId" v-model="choice.doctorId" class="form-select" required>
          <option :value="null">{{ t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR') }}</option>
          <option v-for="d in doctors" :key="d.id" :value="d.id">{{ label(d) }}</option>
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day">{{ t('DOCTOR_DAY_PICKER.DAY_LABEL') }}</label>
        <input id="day" v-model="choice.day" type="date" class="form-control" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100">{{ t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE') }}</button>
      </div>
    </div>
  </form>

  <!-- paciente que ya tiene una cita próxima: por qué no hay botón "Book" -->
  <div v-if="schedule?.info" class="alert alert-info">
    {{ t(schedule.info) }} <RouterLink to="/my-area" class="alert-link">{{ t('APP.MENU_MY_AREA') }}</RouterLink>
  </div>

  <!-- 2. la agenda -->
  <p v-if="loading && !schedule" class="text-muted">{{ t('APP.LOADING') }}</p>
  <div v-else-if="schedule" class="card p-3">
    <h5>{{ t('SCHEDULE.TITLE_PREFIX') }} {{ longDate(schedule.day) }} - {{ label(schedule.doctor) }}</h5>
    <table v-if="schedule.slots.length > 0" class="table table-hover align-middle">
      <thead>
        <tr>
          <th>{{ t('SCHEDULE.COLUMN_SLOT') }}</th>
          <th>{{ t('SCHEDULE.COLUMN_STATUS') }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="s in schedule.slots" :key="s.id" :class="{ 'free-slot': s.bookable }">
          <td>{{ timeRange(s) }}</td>
          <td>
            <span v-if="s.free" class="badge text-bg-success">{{ t('SCHEDULE.FREE') }}</span>
            <span v-else-if="s.patient" class="badge" :class="s.mine ? 'text-bg-primary' : 'text-bg-secondary'">{{ label(s.patient) }}</span>
            <span v-else class="badge text-bg-secondary">{{ t('SCHEDULE.BOOKED_BY_OTHER') }}</span>
          </td>
          <td class="text-end">
            <!-- "Book" es un ENLACE: agrega ?book=... a la URL, lo que
                 abre el diálogo de reserva -->
            <RouterLink v-if="s.bookable" class="btn btn-sm btn-outline-success" :to="{ query: { ...scheduleQuery, book: s.id } }">
              {{ t('SCHEDULE.BOOK') }}
            </RouterLink>
            <button v-if="s.appointmentId !== null" type="button" class="btn btn-sm btn-outline-danger" @click="cancel(s)">
              {{ t('SCHEDULE.CANCEL_APPOINTMENT') }}
            </button>
          </td>
        </tr>
      </tbody>
    </table>
    <p v-else class="text-muted mb-0">{{ t('SCHEDULE.NO_SLOTS') }}</p>
  </div>
  <p v-else class="text-muted">{{ t('SCHEDULE.EMPTY_STATE') }}</p>

  <!-- 3. el cuadro de diálogo de reserva, solo si la URL contiene &book=... -->
  <BookingDialog
    v-if="slotToBook"
    :time="timeRange(slotToBook)"
    :clients="clients"
    :patient="session.isPatient ? (session.user?.name ?? '') : null"
    :submitting="submitting"
    @confirm="book"
    @close="closeBooking"
  />
</template>

Datos de la página:

  • líneas 44–48: las listas, el calendario mostrado y los indicadores de carga y de envío;
  • línea 51: los valores del formulario “médico + día”. Se copian DESDE la URL; el usuario puede modificarlos sin ningún efecto hasta que haga clic en “Ver agenda”;
  • línea 60: el [query] del calendario mostrado, sin ventana de reserva;
  • Líneas 64–67: el horario para el cual está abierta la ventana: [?book=...], si existe Y si es reservable por este usuario. Por lo tanto, una URL creada manualmente ([book=] en un horario ya reservado) no abre ninguna ventana de reserva.

Carga:

  • Líneas 72–82: la lista de médicos es visible para todos, mientras que la lista de pacientes solo es visible para quienes están autorizados a verla;
  • línea 85: la página SIGUE la URL. [immediate]: el calendario se carga en cuanto se muestra la página (una URL guardada como marcador, un F5); luego, cada vez que cambia el médico o la fecha en la URL (al hacer clic en “Ver agenda” o en los botones Anterior/Siguiente). Un cambio solo en [book] no vuelve a cargar el calendario: simplemente abre o cierra la ventana (véase [slotToBook]);
  • líneas 87–116: el día tomado de la URL (hoy por defecto; se produce un error si no existe); el médico tomado de la URL; si no se especifica ningún médico, un médico con sesión iniciada ve SU calendario (el servidor lo obtiene a partir del token), y el médico devuelto por el servidor se copia entonces en el formulario.

Acciones:

  • líneas 123–125: “Ver agenda” no carga nada por sí mismo: cambia la URL y el calendario se actualiza en consecuencia;
  • líneas 131–157: la cita:
    • si no se selecciona ningún paciente: el servidor usa el del token;
    • ningún paciente seleccionado (ADMIN, DOCTOR): la ventana permanece abierta, mostrando el mensaje;
    • éxito u otro rechazo (horario tomado entretanto, el paciente ya tiene una cita): un mensaje emergente, luego la URL sin [book] (la ventana se cierra), seguida de una recarga del calendario: la versión del servidor es la definitiva;
  • líneas 159–170: cancelación, tras la confirmación. El servidor devuelve [appointmentId] para los horarios que el usuario puede cancelar: para un ADMIN o un DOCTOR, todos; para un paciente, los suyos (la aplicación HTML solo le permitía cancelar desde “Mi área”; la API también lo permite desde el calendario).

La plantilla:

  • línea 175: selección del médico y del día;
  • línea 195: un paciente que ya tiene una cita próxima: por qué no hay botón “Reservar”;
  • línea 202: el día, con formato según el idioma actual;
  • líneas 216 y 217: el nombre del paciente, si fue enviado; de lo contrario, “Reservado”;
  • línea 222: “Reservar” es un ENLACE: agrega [book=...] a la URL. Por lo tanto, el botón Atrás del navegador cierra la ventana;
  • líneas 237–244: la ventana, cuando la solicita la URL.

10.13.3. src/views/persons.config.ts

Las páginas de gestión de médicos y de clientes son compartidas. Lo que las distingue:

// =========================================================================
// views/persons.config.ts - ¿médicos o clientes?
// -------------------------------------------------------------------------
// Las páginas para gestionar médicos y clientes son IDÉNTICAS: la misma
// lista, el mismo formulario. Como en la aplicación HTML (clase abstracta
// PersonsController), se escriben UNA SOLA VEZ (PersonsView.vue,
// PersonFormView.vue); solo cambian la dirección de la API y las
// claves de las etiquetas, descritas aquí. El enrutador da el tipo en la
// propiedad meta de cada ruta (vea router.ts).
// =========================================================================

import type { PersonType } from '../api/rdvmedecins.api';

export interface PersonKeys {
  title: string; // "Doctors"
  add: string; // "Add a doctor"
  edit: string; // "Edit a doctor"
  empty: string; // "No doctors."
  confirmDelete: string;
  added: string; // "Doctor {name} has been added (login: {login})."
  edited: string;
  deleted: string;
}

export const PERSON_KEYS: Record<PersonType, PersonKeys> = {
  doctors: {
    title: 'DOCTORS.TITLE',
    add: 'DOCTORS.ADD',
    edit: 'DOCTORS.EDIT',
    empty: 'DOCTORS.EMPTY',
    confirmDelete: 'DOCTORS.DELETE_CONFIRM',
    added: 'DOCTORS.ADDED',
    edited: 'DOCTORS.UPDATED',
    deleted: 'DOCTORS.DELETED',
  },
  clients: {
    title: 'CLIENTS.TITLE',
    add: 'CLIENTS.ADD',
    edit: 'CLIENTS.EDIT',
    empty: 'CLIENTS.EMPTY',
    confirmDelete: 'CLIENTS.DELETE_CONFIRM',
    added: 'CLIENTS.ADDED',
    edited: 'CLIENTS.UPDATED',
    deleted: 'CLIENTS.DELETED',
  },
};

// {name} y {login} de los mensajes "agregado / actualizado / eliminado"
export function messageParams(p: { firstName: string; lastName: string; login?: string }): Record<string, string> {
  return { name: `${p.firstName} ${p.lastName}`, login: p.login ?? '' };
}
  • línea 25: las claves de las etiquetas específicas de cada tipo, como en los controladores [DoctorsController] y [ClientsController] de la aplicación HTML;
  • líneas 49–51: los parámetros [{name}] y [{login}] para los mensajes de “agregado/modificado/eliminado”.

10.13.4. src/views/PersonsView.vue

<!--
  =========================================================================
  views/PersonsView.vue - la lista de médicos O de clientes (ADMIN)
  -------------------------------------------------------------------------
  Una sola página para ambos: el tipo ('doctors' o 'clients') está en
  los metadatos de la ruta (route.meta.type, vea router.ts), las etiquetas
  específicas de cada uno en persons.config.ts. Equivalente de
  views/persons/list.hbs de la aplicación HTML.
  =========================================================================
-->
<script setup lang="ts">
import { computed, onMounted, ref } from 'vue';
import { RouterLink, useRoute } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi, type PersonType } from '../api/rdvmedecins.api';
import type { Person } from '../api/types';
import { useConfirmation } from '../composables/useConfirmation';
import { useMessagesStore } from '../stores/messages';
import { PERSON_KEYS, messageParams } from './persons.config';

const { t } = useI18n();
const route = useRoute();
const messages = useMessagesStore();
const { confirm } = useConfirmation();

const type = route.meta.type as PersonType;
const keys = PERSON_KEYS[type];
const persons = ref<Person[] | null>(null); // null: todavía no cargado
const empty = computed(() => persons.value !== null && persons.value.length === 0);

async function load(): Promise<void> {
  try {
    persons.value = await rdvApi.list(type);
  } catch (e) {
    messages.showApiError(e);
  }
}

async function remove(p: Person): Promise<void> {
  if (!(await confirm(keys.confirmDelete))) {
    return;
  }
  try {
    await rdvApi.remove(type, p.id);
    messages.showSuccess(keys.deleted, messageParams(p));
  } catch (e) {
    // un médico que todavía tiene citas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
    messages.showApiError(e);
  }
  await load();
}

onMounted(load);
</script>

<template>
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0">{{ t(keys.title) }}</h4>
    <RouterLink class="btn btn-primary" :to="`/${type}/add`">{{ t(keys.add) }}</RouterLink>
  </div>

  <div class="card p-3">
    <p v-if="persons === null" class="text-muted mb-0">{{ t('APP.LOADING') }}</p>
    <p v-else-if="empty" class="text-muted mb-0">{{ t(keys.empty) }}</p>
    <table v-else class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{{ t('PERSONS.COLUMN_TITLE') }}</th>
          <th>{{ t('PERSONS.COLUMN_FIRSTNAME') }}</th>
          <th>{{ t('PERSONS.COLUMN_LASTNAME') }}</th>
          <th>{{ t('PERSONS.COLUMN_LOGIN') }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="p in persons" :key="p.id">
          <td>{{ p.title }}</td>
          <td>{{ p.firstName }}</td>
          <td>{{ p.lastName }}</td>
          <td><code>{{ p.login }}</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              <RouterLink class="btn btn-sm btn-outline-primary" :to="`/${type}/${p.id}/edit`">{{ t('PERSONS.EDIT') }}</RouterLink>
              <button type="button" class="btn btn-sm btn-outline-danger" @click="remove(p)">{{ t('PERSONS.DELETE') }}</button>
            </div>
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</template>
  • línea 26: el tipo de personas, leído de los metadatos de la ruta. No cambiará durante la vida del componente: al pasar de [/doctors] a [/clients], la clave [:key] de [<RouterView>] recrea la página;
  • línea 28: [null] mientras la lista no se haya cargado: esto distingue entre “cargando” y “lista vacía”;
  • líneas 39–51: confirmación, eliminación, mensaje y recarga de la lista. Si un médico aún tiene citas: el servidor devuelve una respuesta 409 y el mensaje se muestra en la parte inferior de la página.

10.13.5. src/views/PersonFormView.vue

<!--
  =========================================================================
  views/PersonFormView.vue - creación O actualización de un médico
  o de un cliente (ADMIN)
  -------------------------------------------------------------------------
    /doctors/add               -> creación (sin prop id)
    /doctors/3/edit            -> actualización (prop id = 3, vea router.ts)
  (y las mismas direcciones bajo /clients). Equivalente de
  views/persons/form.hbs de la aplicación HTML.

  Aquí no se verifica ninguna regla: el servidor valida todo, y sus errores
  se muestran debajo de los campos (vea composables/useForm.ts).
  La VERSIÓN leída con el registro regresa con la actualización: si otro
  ADMIN lo ha cambiado mientras tanto, el servidor responde 409 CONCURRENT_UPDATE.
  =========================================================================
-->
<script setup lang="ts">
import { computed, onMounted, reactive } from 'vue';
import { RouterLink, useRoute, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { ApiError } from '../api/http-client';
import { rdvApi, type PersonType } from '../api/rdvmedecins.api';
import type { PersonData } from '../api/types';
import { useForm } from '../composables/useForm';
import { useMessagesStore } from '../stores/messages';
import PersonFields from '../components/PersonFields.vue';
import InputField from '../components/InputField.vue';
import { PERSON_KEYS, messageParams } from './persons.config';

const props = defineProps<{ id?: number }>();

const { t } = useI18n();
const route = useRoute();
const router = useRouter();
const messages = useMessagesStore();
const { errors, params, submitting, submit } = useForm();

const type = route.meta.type as PersonType;
const keys = PERSON_KEYS[type];
const creating = computed(() => props.id === undefined);

const form = reactive<PersonData>({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: undefined });

// actualización: se lee el registro (incluida su versión)
onMounted(async () => {
  if (props.id === undefined) {
    return;
  }
  try {
    const p = await rdvApi.read(type, props.id);
    Object.assign(form, { title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', version: p.version });
  } catch (e) {
    // registro que no existe (eliminado mientras tanto...): de vuelta a la lista
    if (e instanceof ApiError) {
      messages.flash('error', e.key, e.params);
      router.push(`/${type}`);
      return;
    }
    throw e;
  }
});

async function save(): Promise<void> {
  const succeeded = await submit(async () => {
    const p = props.id === undefined ? await rdvApi.add(type, form) : await rdvApi.edit(type, props.id, form);
    messages.flash('success', creating.value ? keys.added : keys.edited, messageParams(p));
  });
  if (succeeded) {
    router.push(`/${type}`);
  } else if (messages.error?.key === 'ERRORS.DOCTOR_NOT_FOUND' || messages.error?.key === 'ERRORS.PATIENT_NOT_FOUND') {
    // eliminado mientras tanto por otro ADMIN: de vuelta a la lista
    messages.flash('error', messages.error.key);
    router.push(`/${type}`);
  }
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
      <div class="card p-4">
        <h5 class="card-title mb-3">{{ t(creating ? keys.add : keys.edit) }}</h5>
        <!-- novalidate: es el SERVIDOR quien valida (es la referencia) -->
        <form novalidate @submit.prevent="save">
          <PersonFields v-model:title="form.title" v-model:firstName="form.firstName" v-model:lastName="form.lastName" :errors="errors" />

          <h6 class="mt-4 text-muted">{{ t('PERSONS.ACCOUNT_SECTION') }}</h6>
          <InputField v-model="form.login" class="mb-3" id="login" label="PERSONS.LOGIN_LABEL" :maxlength="30"
                      :error="errors.login" :help="creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'" />
          <!-- nunca se rellena previamente: la contraseña nunca vuelve del servidor -->
          <InputField v-model="form.password" class="mb-4" id="password" type="password" label="PERSONS.PASSWORD_LABEL"
                      :maxlength="72" autocomplete="new-password" :error="errors.password" :params="params"
                      :help="creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT'" />

          <div class="d-flex gap-2">
            <button type="submit" class="btn btn-primary" :disabled="submitting">{{ t('PERSONS.SAVE') }}</button>
            <RouterLink class="btn btn-secondary" :to="`/${type}`">{{ t('PERSONS.BACK') }}</RouterLink>
          </div>
        </form>
      </div>
    </div>
  </div>
</template>
  • línea 30: creación sin [id], modificación con él (la propiedad proviene de la ruta; véase [router.ts]);
  • línea 36: errores del formulario (véase [useForm.ts]);
  • líneas 45–61: durante la modificación, se lee el registro, incluida la versión. Si no existe (eliminado entretanto), se vuelve a la lista con un mensaje;
  • líneas 63–75: POST o PUT; si tiene éxito, se muestra un mensaje y se vuelve a la lista. Si la operación falla, [useForm] ya ha mostrado los errores; si un registro fue eliminado entretanto, el programa vuelve a la lista;
  • línea 84: [novalidate]: el servidor se encarga de validar;
  • línea 85: las tres [v-model] con nombre;
  • línea 91: la contraseña nunca se rellena previamente: el servidor nunca la devuelve.

10.13.6. src/views/RegisterView.vue

<!--
  =========================================================================
  views/RegisterView.vue - "Create a patient account" (/register, pública)
  -------------------------------------------------------------------------
  Solo se llega aquí después de escribir el captcha de la página de login
  (botón "Create a patient account"): el servidor ha emitido entonces un
  pase, que el guard de la ruta ha verificado (vea router.ts).
  Mismos campos que el formulario del ADMIN, pero el login y la contraseña
  son obligatorios, con confirmación. Equivalente de
  views/account/registration.hbs de la aplicación HTML.
  =========================================================================
-->
<script setup lang="ts">
import { reactive } from 'vue';
import { RouterLink, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Registration } from '../api/types';
import { useForm } from '../composables/useForm';
import { useMessagesStore } from '../stores/messages';
import PersonFields from '../components/PersonFields.vue';
import InputField from '../components/InputField.vue';

const { t } = useI18n();
const router = useRouter();
const messages = useMessagesStore();
const { errors, params, submitting, submit } = useForm();

// longitud mínima de una contraseña elegida por un paciente: el mismo valor
// que el servidor (que también devuelve {min} con el error PASSWORD_TOO_SHORT)
const PASSWORD_MIN = '6';

const form = reactive<Registration>({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '' });

async function create(): Promise<void> {
  let login = '';
  const succeeded = await submit(async () => {
    login = (await rdvApi.register(form)).login;
  });
  if (succeeded) {
    // de vuelta a la página de inicio de sesión, con el login ya completado
    messages.flash('success', 'REGISTRATION.DONE', { login });
    router.push({ name: 'login', query: { login } });
  } else if (messages.error?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
    // pase expirado (15 minutos): de vuelta al captcha
    messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
    router.push({ name: 'login' });
  }
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
      <div class="card p-4">
        <h5 class="card-title mb-1">{{ t('REGISTRATION.TITLE') }}</h5>
        <p class="text-muted small mb-3">{{ t('REGISTRATION.INTRO') }}</p>
        <form novalidate @submit.prevent="create">
          <PersonFields v-model:title="form.title" v-model:firstName="form.firstName" v-model:lastName="form.lastName" :errors="errors" />

          <h6 class="mt-4 text-muted">{{ t('PERSONS.ACCOUNT_SECTION') }}</h6>
          <InputField v-model="form.login" class="mb-3" id="login" label="PERSONS.LOGIN_LABEL" :maxlength="30"
                      autocomplete="username" required :error="errors.login" help="REGISTRATION.LOGIN_HELP" />
          <div class="row g-3 mb-3">
            <InputField v-model="form.password" class="col-sm-6" id="password" type="password" label="PERSONS.PASSWORD_LABEL"
                        :maxlength="72" autocomplete="new-password" required :error="errors.password"
                        :params="{ min: PASSWORD_MIN, ...params }" help="REGISTRATION.PASSWORD_HELP" />
            <InputField v-model="form.confirmation" class="col-sm-6" id="confirmation" type="password"
                        label="ACCOUNT.CONFIRMATION_LABEL" :maxlength="72" autocomplete="new-password" required
                        :error="errors.confirmation" />
          </div>
          <div class="d-flex gap-2">
            <button type="submit" class="btn btn-primary" :disabled="submitting">{{ t('REGISTRATION.SUBMIT') }}</button>
            <RouterLink class="btn btn-secondary" to="/login">{{ t('REGISTRATION.BACK_TO_LOGIN') }}</RouterLink>
          </div>
        </form>
      </div>
    </div>
  </div>
</template>
  • línea 31: la longitud mínima de la contraseña, para el mensaje de ayuda (el servidor también la devuelve en [params], junto con el error);
  • líneas 35–49: creación de la cuenta, seguida de la página de inicio de sesión con el nombre de usuario rellenado. Si el token ha vencido (15 minutos), el servidor responde con un error 403: se vuelve a la página de inicio de sesión para resolver un nuevo CAPTCHA;
  • línea 67: los parámetros del mensaje para el campo; [...params] (el operador de propagación) copia los devueltos por el servidor.

El acceso a esta página está controlado por la guardia [beforeEnter] de su ruta (véase [router.ts]).

10.13.7. src/views/PatientAreaView.vue

<!--
  =========================================================================
  views/PatientAreaView.vue - "My area" (/my-area, rol USER)
  -------------------------------------------------------------------------
  La página de inicio del paciente, justo después de iniciar sesión:
    - dos opciones: [Manage my account] y [View a schedule];
    - su cita próxima, si tiene una, con los medios para cancelarla.
  Equivalente de views/patient/area.hbs de la aplicación HTML.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { RouterLink } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { MyArea } from '../api/types';
import { useFormatting } from '../composables/useFormatting';
import { useConfirmation } from '../composables/useConfirmation';
import { useMessagesStore } from '../stores/messages';

const { t } = useI18n();
const messages = useMessagesStore();
const { label, timeRange, longDate } = useFormatting();
const { confirm } = useConfirmation();

const area = ref<MyArea | null>(null);

async function load(): Promise<void> {
  try {
    area.value = await rdvApi.myArea();
  } catch (e) {
    messages.showApiError(e);
  }
}

async function cancel(appointmentId: number): Promise<void> {
  if (!(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
    return;
  }
  try {
    await rdvApi.cancelAppointment(appointmentId);
    messages.showSuccess('SCHEDULE.CANCELLED');
  } catch (e) {
    messages.showApiError(e);
  }
  await load();
}

onMounted(load);
</script>

<template>
  <template v-if="area">
    <h4 class="mb-3">{{ t('AREA.HELLO', { name: label(area.patient) }) }}</h4>
    <div class="row g-3 mb-4">
      <div class="col-sm-6">
        <RouterLink class="card p-4 h-100 text-decoration-none option-card" to="/my-account">
          <h5 class="mb-1">{{ t('AREA.MANAGE_ACCOUNT') }}</h5>
          <span class="text-muted">{{ t('AREA.MANAGE_ACCOUNT_HELP') }}</span>
        </RouterLink>
      </div>
      <div class="col-sm-6">
        <RouterLink class="card p-4 h-100 text-decoration-none option-card" to="/schedule">
          <h5 class="mb-1">{{ t('AREA.VIEW_SCHEDULE') }}</h5>
          <span class="text-muted">{{ t('AREA.VIEW_SCHEDULE_HELP') }}</span>
        </RouterLink>
      </div>
    </div>

    <div class="card p-3">
      <h5>{{ t('AREA.MY_APPOINTMENT') }}</h5>
      <!-- normalmente solo una (regla "una cita próxima a la vez"),
           pero la página puede mostrar varias -->
      <div
        v-for="(a, i) in area.appointments"
        :key="a.id"
        class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2"
        :class="{ 'border-bottom': i < area.appointments.length - 1 }"
      >
        <div>
          <div class="fw-semibold">{{ longDate(a.day) }}, {{ timeRange(a.slot) }}</div>
          <div class="text-muted">
            {{ label(a.doctor) }} -
            <!-- la agenda del médico en ese día: el paciente ve su nombre en ella -->
            <RouterLink :to="{ path: '/schedule', query: { doctorId: a.doctor.id, day: a.day } }">{{ t('AREA.SEE_IN_SCHEDULE') }}</RouterLink>
          </div>
        </div>
        <button type="button" class="btn btn-outline-danger" @click="cancel(a.id)">{{ t('AREA.CANCEL_APPOINTMENT') }}</button>
      </div>
      <p v-if="area.appointments.length === 0" class="text-muted mb-0">{{ t('AREA.NO_APPOINTMENT') }}</p>
    </div>
  </template>
  <p v-else class="text-muted">{{ t('APP.LOADING') }}</p>
</template>
  • líneas 36–47: el paciente cancela SU cita (el servidor rechazaría la de otra persona);
  • línea 57: una tarjeta completa es un enlace;
  • línea 75: normalmente solo una cita (la regla de “una cita próxima a la vez”), pero la página puede mostrar varias;
  • línea 85: la agenda del médico para ese día, donde el paciente ve su nombre.

10.13.8. src/views/MyAccountView.vue

<!--
  =========================================================================
  views/MyAccountView.vue - "Manage my account" (/my-account, rol USER)
  -------------------------------------------------------------------------
  Dos formularios independientes, como views/patient/account.hbs:
    1. la actualización (identidad, login, nueva contraseña opcional);
    2. la eliminación de la cuenta - que también cancela sus citas.
  Ambos exigen la contraseña ACTUAL (verificada por el servidor).
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';
import { RouterLink, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { MyAccountUpdate } from '../api/types';
import { useForm } from '../composables/useForm';
import { useConfirmation } from '../composables/useConfirmation';
import { useSessionStore } from '../stores/session';
import { useMessagesStore } from '../stores/messages';
import PersonFields from '../components/PersonFields.vue';
import InputField from '../components/InputField.vue';

const { t } = useI18n();
const router = useRouter();
const session = useSessionStore();
const messages = useMessagesStore();
const { confirm } = useConfirmation();
// dos formularios, por lo tanto dos conjuntos de errores
const update = useForm();
const deletion = useForm();

const form = reactive<MyAccountUpdate>({
  title: 'Mr',
  firstName: '',
  lastName: '',
  login: '',
  password: '',
  confirmation: '',
  currentPassword: '',
  version: 0,
});
const deletePassword = ref('');

onMounted(async () => {
  try {
    Object.assign(form, await rdvApi.myAccount());
  } catch (e) {
    messages.showApiError(e);
  }
});

async function save(): Promise<void> {
  const succeeded = await update.submit(async () => {
    // el servidor ha emitido un NUEVO token (nombre, login): la barra de
    // navegación debe seguirlo
    session.update(await rdvApi.editMyAccount(form));
    messages.flash('success', 'MY_ACCOUNT.UPDATED');
  });
  // nunca una contraseña que quede en los campos después de un envío
  form.currentPassword = '';
  if (succeeded) {
    router.push('/my-area');
  }
}

async function remove(): Promise<void> {
  if (!(await confirm('MY_ACCOUNT.DELETE_CONFIRM'))) {
    return;
  }
  const succeeded = await deletion.submit(async () => {
    await rdvApi.deleteMyAccount(deletePassword.value);
  });
  deletePassword.value = '';
  if (succeeded) {
    session.forget(); // el servidor ha borrado la cookie del token
    messages.flash('success', 'MY_ACCOUNT.DELETED');
    router.push({ name: 'login' });
  }
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
      <!-- 1. actualización -->
      <div class="card p-4 mb-4">
        <h5 class="card-title mb-3">{{ t('MY_ACCOUNT.TITLE') }}</h5>
        <form novalidate @submit.prevent="save">
          <PersonFields v-model:title="form.title" v-model:firstName="form.firstName" v-model:lastName="form.lastName" :errors="update.errors.value" />

          <h6 class="mt-4 text-muted">{{ t('PERSONS.ACCOUNT_SECTION') }}</h6>
          <InputField v-model="form.login" class="mb-3" id="login" label="PERSONS.LOGIN_LABEL" :maxlength="30"
                      autocomplete="username" required :error="update.errors.value.login" />
          <div class="row g-3 mb-3">
            <InputField v-model="form.password" class="col-sm-6" id="password" type="password" label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
                        :maxlength="72" autocomplete="new-password" :error="update.errors.value.password"
                        :params="update.params.value" help="PERSONS.PASSWORD_HELP_EDIT" />
            <InputField v-model="form.confirmation" class="col-sm-6" id="confirmation" type="password"
                        label="ACCOUNT.CONFIRMATION_LABEL" :maxlength="72" autocomplete="new-password"
                        :error="update.errors.value.confirmation" />
          </div>
          <InputField v-model="form.currentPassword" class="mb-4" id="currentPassword" type="password"
                      label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL" :maxlength="72" autocomplete="current-password" required
                      :error="update.errors.value.currentPassword" help="MY_ACCOUNT.CURRENT_PASSWORD_HELP" />
          <div class="d-flex gap-2">
            <button type="submit" class="btn btn-primary" :disabled="update.submitting.value">{{ t('PERSONS.SAVE') }}</button>
            <RouterLink class="btn btn-secondary" to="/my-area">{{ t('MY_ACCOUNT.BACK') }}</RouterLink>
          </div>
        </form>
      </div>

      <!-- 2. eliminación -->
      <div class="card p-4 border-danger">
        <h5 class="card-title text-danger mb-1">{{ t('MY_ACCOUNT.DELETE_TITLE') }}</h5>
        <p class="text-muted small">{{ t('MY_ACCOUNT.DELETE_HELP') }}</p>
        <form class="d-flex flex-wrap gap-2 align-items-end" novalidate @submit.prevent="remove">
          <InputField v-model="deletePassword" class="flex-grow-1" id="deletePassword" type="password"
                      label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL" :maxlength="72" autocomplete="current-password" required
                      :error="deletion.errors.value.currentPassword" />
          <button type="submit" class="btn btn-danger" :disabled="deletion.submitting.value">{{ t('MY_ACCOUNT.DELETE_SUBMIT') }}</button>
        </form>
      </div>
    </div>
  </div>
</template>
  • líneas 30–31: dos formularios, por lo tanto dos conjuntos de errores: un composable puede llamarse tantas veces como se desee, y cada llamada tiene su propio estado;
  • línea 47: los valores leídos se copian en el formulario, incluida la versión;
  • líneas 53–65: el servidor ha emitido un nuevo token (el nombre y el nombre de usuario pueden haber cambiado); devuelve al usuario tal como lo describe este token, y la sesión se actualiza: la barra de navegación hace lo mismo. La contraseña actual se borra después de cada envío;
  • líneas 67–80: confirmación, eliminación; el servidor ha eliminado la cookie del token: se olvida al usuario y este es redirigido de nuevo a la página de inicio de sesión;
  • línea 90: [update] es un objeto normal que CONTIENE [ref]s: en la plantilla, hay que escribir [.value] (véase el Ejemplo 11).

10.13.9. src/views/ErrorView.vue

<!--
  views/ErrorView.vue - la página de error: 404 (dirección desconocida) o 403
  (rol insuficiente, vea el guard del enrutador). Equivalente de views/error.hbs.
-->
<script setup lang="ts">
import { computed } from 'vue';
import { RouterLink } from 'vue-router';
import { useI18n } from 'vue-i18n';

const props = defineProps<{ code: 403 | 404 }>();
const { t } = useI18n();
const message = computed(() => (props.code === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND'));
</script>

<template>
  <div class="card p-4">
    <h4 class="text-danger">{{ t('ERROR_PAGE.TITLE') }} {{ code }}</h4>
    <p>{{ t(message) }}</p>
    <RouterLink to="/" class="btn btn-primary align-self-start">{{ t('ERROR_PAGE.BACK') }}</RouterLink>
  </div>
</template>

La página de error para una URL desconocida (404) o una página restringida al rol del usuario (403).