Skip to content

11. Caso de estudio: la aplicación RdvMedecins

11.1. El problema

La aplicación RdvMedecins gestiona las citas de un consultorio médico. Cada médico tiene franjas horarias (de 8:00 a. m. a 12:00 p. m. en intervalos de 20 minutos, por ejemplo); una cita se compone de un día, una franja horaria y un cliente (un paciente). Es el port exacto, en [Django], de la aplicación [Symfony] de la lección anterior (que a su vez se portó de las versiones [Laravel], [Flask], [Spring MVC] y [ASP.NET Core MVC]): la misma base de datos, las mismas reglas de negocio, las mismas páginas, las mismas URL, los mismos textos. Las páginas HTML las genera el servidor con las plantillas de [Django]; el acceso a la base de datos pasa por el ORM de [Django].

Tres roles de usuario comparten la aplicación:

Rol
Quién
Permisos
ADMIN
El administrador ([admin])
Ver las agendas, reservar y cancelar citas para cualquier paciente; gestionar (listar, agregar, editar, eliminar) médicos y pacientes
DOCTOR
Los médicos
Ver las agendas, reservar y cancelar citas para cualquier paciente
USER
los clientes (pacientes)
ver las agendas sin ver los nombres de otros pacientes; reservar una cita para sí mismos; cancelar su cita; gestionar su cuenta; crear una cuenta

Principales reglas de gestión:

  • no se permiten citas en el pasado;
  • una franja horaria se reserva una sola vez por día;
  • un paciente tiene una sola cita próxima a la vez;
  • dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido, y un inicio de sesión pertenece a una sola cuenta;
  • no se puede eliminar a un médico que tiene citas; a un cliente se lo elimina junto con sus citas;
  • la página de inicio de sesión está protegida contra bots (CAPTCHA, intentos limitados), y la creación de una cuenta de paciente requiere resolver primero el CAPTCHA en esa página.

11.2. Uso de la aplicación

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

Image

La página presenta dos botones: Iniciar sesión y Crear una cuenta de paciente. Ambos exigen ingresar los caracteres que muestra la imagen. Los botones FR / EN cambian el idioma:

Image

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

Image

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

Una vez iniciada la sesión, el administrador llega a la página del calendario. Selecciona un médico y un día:

Image

Image

Cada franja horaria está disponible (botón Reservar) u ocupada (nombre del paciente, botón Cancelar). Al hacer clic en Reservar se abre una ventana que solicita los datos del paciente. Esta ventana la genera el servidor, igual que el resto de la página: la URL contiene ahora el parámetro [book=5], que es el número de la franja horaria seleccionada:

Image

Después de la reserva, un mensaje confirma la cita:

Image

Al hacer clic en «Cancelar» se solicita una confirmación (aquí, por parte de la Dra. Pélissier, cuya barra de navegación no incluye los menús de administración):

Image

11.2.3. El portal del paciente

Un paciente (rol USER) llega a «Mi área»: su próxima cita, que puede cancelar, y enlaces para gestionar su cuenta y ver su calendario. Aquí todavía no tiene ninguna cita:

Image

En el calendario no ve los nombres de los demás pacientes; estos se reemplazan por «Reservado»: ese nombre ni siquiera aparece en el código fuente de la página. Puede reservar una franja horaria disponible:

Image

La ventana de reserva no le pide que seleccione un paciente: reserva la cita para sí mismo.

Image

Image

Su panel ahora muestra su próxima cita, que puede cancelar:

Image

Como tiene una cita próxima, no puede programar otra: el botón «Reservar» no se muestra, y en el calendario de otro día o de otro médico, un mensaje explica la razón:

Image

Gestión de la cuenta: editar sus datos, cambiar su contraseña o eliminar su cuenta (y sus citas). Se requiere la contraseña actual para cualquier cambio:

Image

Un paciente que intenta abrir una página reservada al administrador (aquí, [/doctors], escrita manualmente) recibe una página de error:

Image

11.2.4. Gestión de médicos y pacientes

El administrador tiene dos menús adicionales, Médicos y Pacientes:

Image

Image

El formulario de alta de un médico, enviado con errores:

Image

Un nombre igual al de un médico existente se rechaza, incluso si está escrito en minúsculas y con acento (la propia base de datos compara los nombres sin distinguir mayúsculas de minúsculas ni acentos; véase el ejemplo 28):

Image

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

Image

11.2.5. Creación de una cuenta de paciente

Desde la página de inicio de sesión, el botón «Crear una cuenta de paciente» solo abre el formulario si el CAPTCHA se ingresó correctamente:

Image

Una vez creada la cuenta, el usuario es redirigido a la página de inicio de sesión con su nombre de usuario ya completado:

Image

11.2.6. Cierre de sesión

El token de inicio de sesión es válido durante dos horas. Transcurrido ese tiempo (o si el token ha sido manipulado), la página solicitada redirige a la página de inicio de sesión con el siguiente mensaje:

Image

11.3. Instalación y ejecución

La aplicación se encuentra en la carpeta [rdvmedecins2-django], junto a la carpeta [examples]. Es un proyecto independiente, con sus propios archivos [requirements.txt] y [.env] y su propio entorno virtual. El archivo [README.md] de la carpeta contiene todo lo que sigue. La introducción de este documento ya describió la instalación; aquí damos más detalles.

11.3.1. Software necesario

Bastan dos programas:

  • [Python] 3.12 o posterior ([Django] 6.1 requiere [Python] 3.12). Verifique la instalación en una terminal:
python --version
  • En [Linux] y [macOS], el comando suele llamarse [python3]. En [Linux], compilar [mysqlclient] requiere además algunos paquetes del sistema (véanse los apéndices);
  • un servidor [MySQL] versión 8.4 o posterior, como el de [Laragon] que se ejecuta en [Windows] (véanse los apéndices). [MariaDB] 10.11 o posterior también es adecuado. Estas son las versiones mínimas de [Django] 6.1: con [MySQL] 8.0, [Django] se niega a conectarse ([MySQL 8.4 or later is required]).

El editor recomendado es [Visual Studio Code], junto con las extensiones [Python] y [Django] (véanse los apéndices); sin embargo, todo puede hacerse desde la línea de comandos.

11.3.2. Instalación de las bibliotecas

Las bibliotecas no se incluyen: cree un entorno virtual de una vez por todas en la carpeta de la aplicación e instale allí las bibliotecas, en un terminal abierto en la carpeta [rdvmedecins2-django] (debe estar conectado a Internet):

1
2
3
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

(en [Linux] y [macOS], el segundo comando se escribe [source .venv/bin/activate]). [pip] lee el archivo [requirements.txt] (que se explica más adelante), descarga [Django], [mysqlclient], [PyJWT], [bcrypt] y las bibliotecas de las que dependen, y las instala en la carpeta [.venv]. El entorno debe activarse en cada terminal nuevo ([Visual Studio Code] lo hace automáticamente una vez seleccionado el intérprete del entorno; véase la introducción).

11.3.3. Creación de la base de datos

La base de datos [dbrdvmedecins2] se crea con el script [database/dbrdvmedecins2.sql]. Con [Laragon], abra la herramienta [HeidiSQL] (botón Database) y ejecute el script desde el menú File / Run SQL (véase la introducción). En la línea de comandos, en la carpeta de la aplicación:

mysql -u root -p < database/dbrdvmedecins2.sql

La opción [-p] solicita la contraseña de [root]; omítala si la cuenta no tiene una (como ocurre con [Laragon]). Es la misma base de datos que en las otras versiones de la aplicación: si ya existe, este paso es opcional. El script puede ejecutarse en cualquier momento para volver a los datos originales.

11.3.4. Configuración del acceso a la base de datos

Toda la configuración de la instalación está en el archivo [.env] (que se explica más adelante). De forma predeterminada, la aplicación se conecta a [MySQL] en [127.0.0.1], puerto 3306, con el usuario [root] sin contraseña: es la configuración predeterminada de [Laragon]. Si su cuenta [root] tiene contraseña, indíquela en este archivo, en la línea [DB_PASSWORD=]. Una variable de entorno del sistema tiene prioridad sobre el archivo (ejemplo 25): esto permite indicar la contraseña sin escribirla en un archivo del proyecto.

11.3.5. Ejecución de la aplicación

En una ventana de terminal abierta en la carpeta [rdvmedecins2-django], con el entorno virtual activado:

python manage.py runserver 8081
1
2
3
4
5
6
7
8
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 27, 2026 - 19:30:12
Django version 6.1.1, using settings 'config.settings'
Starting WSGI development server at http://127.0.0.1:8081/
Quit the server with CONTROL-C.

A continuación, abra la URL [http://localhost:8081] en un navegador y detenga la aplicación con [Ctrl-C]. El puerto 8081 permite ejecutar al mismo tiempo un ejemplo del curso (puerto 8000); las otras versiones de la aplicación también usan el puerto 8081: no las ejecute simultáneamente.

11.3.6. Cuentas de demostración

La contraseña de cada cuenta es su nombre de usuario; además, debe ingresar los caracteres que se muestran en la imagen, en mayúsculas o minúsculas:

Nombre de usuario
Rol
[admin]
ADMIN (el administrador)
[pelissier], [tatou], [dupont]
DOCTOR (los médicos)
[martin], [durand], [bistrou], [german]
USER (los pacientes)

Guía para explorar la aplicación:

  • [admin]: Schedule, agenda de la Dra. Marie PELISSIER, hoy: una franja horaria ya está reservada por la Sra. Brigitte BISTROU. Reserve una franja para el Sr. Jean MARTIN y luego intente reservarle una segunda cita (será rechazada). Menús Doctors y Patients: agregar, editar, eliminar (la Dra. PELISSIER, que tiene citas, no puede eliminarse);
  • [pelissier]: su agenda del día se muestra directamente; la dirección [/doctors], ingresada manualmente, devuelve una página de error 403;
  • [martin]: My area, su cita, el calendario donde los demás pacientes aparecen como “Reservado” (vea el código fuente de la página: sus nombres no aparecen allí); Manage my account;
  • Página de inicio de sesión: Create a patient account, y luego inicie sesión con la nueva cuenta;
  • botones FR / EN: toda la interfaz cambia de idioma, incluidas las fechas.

11.3.7. Modo de desarrollo

El archivo [.env] proporcionado configura la aplicación para el desarrollo ([DJANGO_DEBUG=1]):

  • la consola del servidor muestra cada solicitud y cada comando SQL enviado a la base de datos (ejemplo 28). Por ejemplo, para mostrar un calendario (después de los dos comandos de apertura de la conexión, ejemplo 28; líneas abreviadas):
1
2
3
4
(0.000) SELECT `doctors`.`id`, ..., `users`.`role` FROM `doctors` INNER JOIN `users` ON (`doctors`.`user` = `users`.`id`) WHERE `doctors`.`id` = 1 ORDER BY `doctors`.`id` ASC LIMIT 1; args=(1,); alias=default
(0.003) SELECT `appointments`.`id`, ..., `clients`.`user` FROM `appointments` INNER JOIN `slots` ON (`appointments`.`slot_id` = `slots`.`id`) INNER JOIN `clients` ON (`appointments`.`client_id` = `clients`.`id`) WHERE (`appointments`.`day` = '2026-09-28' AND `slots`.`doctor_id` = 1); args=('2026-09-28', 1); alias=default
(0.000) SELECT `slots`.`id`, ..., `slots`.`end_minute` FROM `slots` WHERE `slots`.`doctor_id` = 1 ORDER BY `slots`.`start_hour` ASC, `slots`.`start_minute` ASC; args=(1,); alias=default
[27/Sep/2026 19:50:21] "GET /schedule?doctorId=1&day=2026-09-28 HTTP/1.1" 200 9186

Aquí se identifican tres solicitudes: el médico y su cuenta (una combinación), las citas del día y sus pacientes, y las franjas horarias disponibles del médico. En cambio, la lista de médicos del menú desplegable no se recupera; proviene del caché (véase más adelante). Tampoco se recupera el usuario conectado; se identifica mediante su token (ejemplo 25);

  • una excepción inesperada muestra la página de depuración de [Django] (ejemplo 03), con el mensaje de la excepción y la pila de llamadas. En producción, la aplicación muestra en su lugar su propia página de error 500;
  • no hay nada que reiniciar tras un cambio: el servidor de desarrollo se reinicia automáticamente cuando cambia un archivo [Python] (ejemplo 01), y una plantilla modificada se vuelve a leer en la siguiente solicitud.

El depurador de la extensión [Python] de [Visual Studio Code] también permite ejecutar la aplicación paso a paso: basta con una configuración de inicio de tipo “Django” (archivo [.vscode/launch.json], que la extensión ofrece crear), con los parámetros [runserver 8081 --noreload]. La extensión [django-debug-toolbar] (que debe instalarse con [pip]) muestra, junto a cada página, los detalles de la solicitud: los comandos SQL y sus duraciones, las plantillas utilizadas, la configuración, las señales...

11.3.8. Un servidor de producción

El servidor de desarrollo de [Django] no está pensado para producción. En producción, la aplicación la sirve un servidor WSGI (ejemplo 01): [gunicorn] en [Linux] ([gunicorn config.wsgi:application --workers 4]), [waitress] en [Windows] ([waitress-serve --port=8081 config.wsgi:application]), normalmente detrás de un servidor web ([nginx], [Apache]) que recibe las conexiones HTTPS, sirve por sí mismo los archivos estáticos y delega el resto en el servidor WSGI. En el archivo [.env] hay que indicar el modo de producción, cambiar las claves secretas, declarar el nombre del sitio y especificar que el sitio se sirve mediante HTTPS:

1
2
3
4
5
DJANGO_DEBUG=0
DJANGO_SECRET_KEY=a-long-random-string
DJANGO_ALLOWED_HOSTS=rdvmedecins.example.com
JWT_SECRET=another-long-random-string
COOKIE_SECURE=1

Se puede obtener una cadena aleatoria adecuada con [Python] mismo: [python -c "import secrets; print(secrets.token_hex(32))"]. Luego, la aplicación se prepara con dos comandos:

python manage.py collectstatic
python manage.py check --deploy

El primer comando copia todos los archivos estáticos (los de la aplicación y los de [Django]) en la carpeta [var/static] (configuración [STATIC_ROOT]), que será la que sirva el servidor web (ejemplo 15). El segundo comando verifica la configuración de seguridad de un despliegue y señala la que falte (los encabezados HSTS, la redirección a HTTPS, etc.). Para probar el modo de producción con el servidor de desarrollo, que ya no sirve los archivos estáticos: [python manage.py runserver 8081 --insecure].

11.3.9. Problemas frecuentes

Con [MySQL], el comando [runserver] se conecta a la base de datos desde que arranca: sus verificaciones del proyecto (system checks, ejemplo 01) necesitan conocer la versión del servidor. Por lo tanto, una base de datos inaccesible impide su arranque: la consola muestra una larga pila de llamadas que termina con el error. Por ejemplo, con una base de datos que no existe:

django.db.utils.OperationalError: (1049, "Unknown database 'dbrdvmedecins2'")

Un servidor de producción ([gunicorn]...) no realiza estas verificaciones: el error aparece entonces en el registro, en la primera página que consulta la base de datos (la página de inicio de sesión no consulta la base de datos; el proceso de inicio de sesión sí). Los mensajes más frecuentes:

Mensaje
Causa
[ModuleNotFoundError: No module named 'django']
El entorno virtual no está activado, o [pip install -r requirements.txt] no se ha ejecutado
[Django 6.1 requires Python 3.12 or later] (durante la instalación)
La versión de [Python] es anterior a la 3.12
[OperationalError: (2002, "Can't connect to server on '127.0.0.1' ...")]
[MySQL] no se ha iniciado, o no escucha en [127.0.0.1:3306]
[OperationalError: (1045, "Access denied for user 'root'@'localhost' ...")]
La contraseña de [MySQL] debe ingresarse en [DB_PASSWORD] (véase “Configuración del acceso a la base de datos”)
[OperationalError: (1049, "Unknown database 'dbrdvmedecins2'")]
El script [database/dbrdvmedecins2.sql] no se ejecutó
[NotSupportedError: MySQL 8.4 or later is required]
El servidor [MySQL] es demasiado antiguo: actualice a [MySQL] 8.4 o a [MariaDB] 10.11
[ImproperlyConfigured: JWT_SECRET must be at least 32 characters long (see .env).]
La clave secreta de los tokens es demasiado corta en [.env]
[Error: That port is already in use.]
El puerto 8081 ya está en uso (¿se está ejecutando otra versión de la aplicación?): deténgala o elija otro puerto

11.4. Arquitectura de la aplicación

Image

  • El navegador envía sus solicitudes al servidor ([runserver], o [nginx] + [gunicorn]), que las transmite a [Django] mediante la aplicación WSGI del archivo [config/wsgi.py]. La solicitud atraviesa las capas de middleware (véase el capítulo sobre el ciclo de vida): el idioma de la solicitud ([SetLanguage]), la protección anti-CSRF, los mensajes flash y luego la autenticación: el usuario se identifica a partir del token JWT de su cookie ([Authentication]); tras el enrutamiento, [AccessControl] niega el acceso a las páginas protegidas a los visitantes no autorizados. Los errores se gestionan mediante páginas HTML ([ErrorPage] y las vistas de error);
  • [web]: la capa web. Las vistas ([web/views]), una familia de páginas por módulo, y sus rutas ([web/urls.py]); los formularios y sus restricciones ([web/forms.py]); los modelos de las plantillas ([web/view_models.py]). Todos pasan por un único objeto, [ApplicationModel] ([web/application.py]), que almacena en caché las listas de médicos y clientes y transmite las demás solicitudes a la capa de negocio;
  • [security]: tokens JWT, middleware de autenticación y de control de acceso, CAPTCHA, límites de intentos y pase de creación de cuentas;
  • [business]: reglas de negocio y transacciones; [domain]: objetos del calendario, calculados por la capa de negocio;
  • [dao]: la capa DAO, un módulo por tabla (o por familia de tablas);
  • [models]: los modelos del ORM (ejemplo 28), con los que la capa DAO lee y escribe en la base de datos;
  • [templates]: las plantillas, que generan las páginas HTML; [locale]: el diccionario en francés; [static]: la hoja de estilos, el script de la página y [Bootstrap];
  • La carpeta [config] y el archivo [.env]: la configuración que lo une todo.

La carpeta de la aplicación (sin [.venv] ni [var]):

rdvmedecins2-django/
├── business/
│   ├── README.md
│   ├── __init__.py
│   ├── business.py
│   ├── dates.py
│   ├── descriptor.py
│   ├── errors.py
│   ├── person_data.py
│   ├── provider.py
│   └── service.py
├── config/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── dao/
│   ├── README.md
│   ├── __init__.py
│   ├── appointments.py
│   ├── persons.py
│   ├── slots.py
│   └── users.py
├── database/
│   ├── README.md
│   └── dbrdvmedecins2.sql
├── domain/
│   ├── README.md
│   ├── __init__.py
│   └── schedule.py
├── locale/
│   └── fr/
│       └── LC_MESSAGES/
│           ├── django.mo
│           └── django.po
├── models/
│   ├── README.md
│   ├── __init__.py
│   ├── apps.py
│   └── models.py
├── security/
│   ├── README.md
│   ├── __init__.py
│   ├── access.py
│   ├── auth.py
│   ├── captcha_drawing.py
│   ├── captchas.py
│   ├── connected_user.py
│   ├── errors.py
│   ├── limiter.py
│   ├── middleware.py
│   ├── passwords.py
│   └── registration_pass.py
├── static/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── app.js
│   └── lib/
│       └── bootstrap/
├── templates/
│   ├── forms/
│   │   └── field.html
│   ├── fragments/
│   │   ├── booking.html
│   │   ├── captcha.html
│   │   ├── confirmation.html
│   │   ├── errors.html
│   │   ├── navbar.html
│   │   └── success.html
│   ├── persons/
│   │   ├── form.html
│   │   └── list.html
│   ├── README.md
│   ├── account.html
│   ├── area.html
│   ├── error.html
│   ├── layout.html
│   ├── login.html
│   ├── macros.html
│   ├── registration.html
│   └── schedule.html
├── web/
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── rdv.py
│   ├── views/
│   │   ├── README.md
│   │   ├── __init__.py
│   │   ├── area.py
│   │   ├── auth.py
│   │   ├── errors.py
│   │   ├── language.py
│   │   ├── persons.py
│   │   ├── registration.py
│   │   └── schedule.py
│   ├── README.md
│   ├── __init__.py
│   ├── application.py
│   ├── apps.py
│   ├── contexts.py
│   ├── forms.py
│   ├── middleware.py
│   ├── rendering.py
│   ├── urls.py
│   ├── utils.py
│   └── view_models.py
├── .env
├── .gitignore
├── README.md
├── manage.py
└── requirements.txt

Esta es la estructura de un proyecto [Django] típico (ejemplo 01): un paquete de configuración ([config]), un archivo [manage.py] y paquetes de código. Solo dos de ellos son aplicaciones de [Django], declaradas en [INSTALLED_APPS]: [models], porque contiene los modelos del ORM (que [Django] solo busca en las aplicaciones), y [web], porque contiene una biblioteca de etiquetas ([templatetags], ejemplo 16). Los demás ([dao], [business], [security], [domain]) son simples paquetes de [Python] que los otros importan: no tienen nada que declarar a [Django]. [Django] no impone ninguna de estas carpetas, y un proyecto típico tendría más bien una aplicación por dominio (calendarios, cuentas, etc.), cada una con sus propios modelos, vistas y plantillas; preferimos, como en las otras versiones del caso de estudio, una organización por capas, como se muestra en el ejemplo 28. [Bootstrap] forma parte de la aplicación esta vez (carpeta [static/lib/bootstrap]): el caso de estudio es autónomo.

11.5. La base de datos

La base de datos [dbrdvmedecins2] tiene cinco tablas:

  • [users]: usuarios autorizados a iniciar sesión;
  • [doctors] y [clients]: médicos y pacientes, cada uno vinculado a su cuenta de usuario;
  • [slots]: las franjas horarias disponibles de cada médico;
  • [appointments]: las citas, un cliente por franja horaria en un día determinado.

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Base de datos [dbrdvmedecins2] - MySQL 8
--
-- Evolución de [dbrdvmedecins]:
--   1. las tablas [doctors] y [clients] reciben una columna [user],
--      clave externa hacia users(id): cada médico y cada cliente es
--      ahora también un usuario capaz de iniciar sesión;
--   2. aparece un tercer rol: DOCTOR (además de ADMIN y USER);
--   3. el script crea una fila en [users] para cada médico (rol DOCTOR)
--      y para cada cliente (rol USER):
--        - login        = apellido en minúsculas
--        - password     = apellido en minúsculas, con hash bcrypt (10 rondas)
--        - nombre mostrado = nombre + apellido
--
--   4. restricciones de unicidad, todas con NOMBRE (la aplicación reconoce
--      el nombre de la restricción violada en el mensaje de error de MySQL):
--        - unq_users_login                   : un login pertenece a una sola cuenta;
--        - unq_doctors_first_name_last_name  : dos médicos no pueden tener los
--                                              mismos nombre y apellido;
--        - unq_clients_first_name_last_name  : igual para los clientes.
--      Atención: la collation utf8mb4_unicode_ci compara sin distinguir
--      mayúsculas ni acentos - "Hélène DUPONT" y "helene dupont"
--      se consideran, por lo tanto, idénticos.
--
-- La tabla [users] ahora debe crearse ANTES que [doctors] y [clients]
-- (que la referencian), y eliminarse DESPUÉS de ellas.
-- =========================================================================

-- el script está escrito en UTF-8
SET NAMES utf8mb4;

-- se parte de nuevo de una base de datos vacía en cada ejecución del script (práctico en desarrollo)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- orden de eliminación: de las tablas "hijas" a las tablas "padre"
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;

-- -------------------------------------------------------------------------
-- tabla [users]: los usuarios autorizados para iniciar sesión en la aplicación
-- -------------------------------------------------------------------------
CREATE TABLE users (
  id       INT AUTO_INCREMENT PRIMARY KEY,
  version  INT NOT NULL DEFAULT 0,
  login    VARCHAR(30) NOT NULL,                 -- login identifier
  password VARCHAR(100) NOT NULL,                -- HASHED password (bcrypt) - never in clear
  name     VARCHAR(40) NOT NULL,                 -- name displayed once logged in
  role     VARCHAR(10) NOT NULL,                 -- 'ADMIN', 'DOCTOR' or 'USER'
  -- un login puede pertenecer a una sola cuenta
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- tabla [doctors]: los médicos del consultorio
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
  id         INT AUTO_INCREMENT PRIMARY KEY,   -- primary key (technical identifier)
  version    INT NOT NULL DEFAULT 0,            -- row version number (optimistic lock)
  title      VARCHAR(5)  NOT NULL,              -- Melle, Mme, Mr
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- una cuenta por médico, y un médico por cuenta
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- dos médicos no pueden tener los mismos nombre y apellido
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabla [clients]: los pacientes de los médicos
-- -------------------------------------------------------------------------
CREATE TABLE clients (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  title      VARCHAR(5)  NOT NULL,
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- una cuenta por cliente, y un cliente por cuenta
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- dos clientes no pueden tener los mismos nombre y apellido
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabla [slots]: las franjas horarias de cada médico
-- -------------------------------------------------------------------------
CREATE TABLE slots (
  id           INT AUTO_INCREMENT PRIMARY KEY,
  version      INT NOT NULL DEFAULT 0,
  doctor_id    INT NOT NULL,                     -- foreign key -> doctors(id)
  start_hour   INT NOT NULL,                     -- start hour of the slot
  start_minute INT NOT NULL,                     -- start minute of the slot
  end_hour     INT NOT NULL,                     -- end hour of the slot
  end_minute   INT NOT NULL,                     -- end minute of the slot
  CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);

-- -------------------------------------------------------------------------
-- tabla [appointments]: las citas reservadas por los clientes
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  day        DATE NOT NULL,                      -- day of the appointment
  slot_id    INT NOT NULL,                       -- foreign key -> slots(id)
  client_id  INT NOT NULL,                       -- foreign key -> clients(id)
  CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
  CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
  -- la misma franja, el mismo día, solo puede reservarse una vez
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

-- =========================================================================
-- Datos de demostración
-- =========================================================================

-- los usuarios: contraseñas con hash bcrypt (10 rondas de salt)
--   admin/admin (ADMIN)
--   una cuenta DOCTOR por médico, una cuenta USER por cliente
--   (la cuenta de demostración user/user ya no existe: una cuenta USER es
--   ahora SIEMPRE la cuenta de un cliente, que puede reservar y administrar la cuenta)
--   (login = contraseña = apellido en minúsculas)
INSERT INTO users (login, password, name, role) VALUES
  ('admin',     '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator',    'ADMIN'),
  -- doctors
  ('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER',  'DOCTOR'),
  ('tatou',     '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU',       'DOCTOR'),
  ('dupont',    '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT',    'DOCTOR'),
  -- clients
  ('martin',    '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN',      'USER'),
  ('durand',    '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND',     'USER'),
  ('bistrou',   '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
  ('german',    '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN',       'USER');

-- los médicos: la columna [user] se busca a partir del login,
-- en lugar de suponer los valores de las claves primarias de [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
  ('Mme',  'PELISSIER', 'Marie',  (SELECT id FROM users WHERE login = 'pelissier')),
  ('Mr',   'TATOU',     'Paul',   (SELECT id FROM users WHERE login = 'tatou')),
  ('Melle','DUPONT',    'Sophie', (SELECT id FROM users WHERE login = 'dupont'));

INSERT INTO clients (title, last_name, first_name, `user`) VALUES
  ('Mr',   'MARTIN',  'Jean',     (SELECT id FROM users WHERE login = 'martin')),
  ('Mme',  'DURAND',  'Alice',    (SELECT id FROM users WHERE login = 'durand')),
  ('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
  ('Mr',   'GERMAN',  'Luc',      (SELECT id FROM users WHERE login = 'german'));

-- franjas del médico PELISSIER (doctor_id = 1): de 8:00 a 12:00 en intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- franjas del médico TATOU (doctor_id = 2): de 14:00 a 18:00 en intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- una cita ya reservada, para ver de inmediato una franja ocupada en la agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • línea 33: la base de datos se crea si no existe, con el conjunto de caracteres [utf8mb4] y la intercalación [utf8mb4_unicode_ci], que compara las cadenas sin distinguir mayúsculas ni acentos (ejemplo 28);
  • líneas 37–41: las tablas se eliminan y luego se vuelven a crear; el script restablece la base de datos a su estado inicial. El orden importa: una tabla no puede eliminarse mientras otra tabla la referencie mediante una clave externa;
  • líneas 46–55: users: un login, una contraseña con hash de [bcrypt] (ejemplo 25), el nombre para mostrar una vez iniciada la sesión y el rol ([ADMIN], [DOCTOR], o [USER]). La restricción [unq_users_login] garantiza que un nombre de usuario pertenezca a una sola cuenta;
  • Líneas 60–72: cada tabla tiene una clave primaria [id], generada por la base de datos, y una columna [version], que es el bloqueo optimista (ejemplo 28). La columna [user] es una clave externa hacia [users(id)]: la base de datos rechaza cualquier valor que no sea el identificador de un usuario existente. Como [user] es una palabra del lenguaje SQL, se escribe entre acentos graves. Tres restricciones: [fk_doctors_user] (la clave externa), [unq_doctors_user] (una cuenta por médico y un médico por cuenta) y [unq_doctors_first_name_last_name] (sin homónimos). Todas las restricciones tienen nombre: la aplicación reconoce una restricción violada por su nombre;
  • líneas 77–89: la tabla [clients] tiene exactamente las mismas columnas;
  • líneas 94–103: una franja horaria pertenece a un médico; sus horas de inicio y de fin se almacenan en horas y minutos;
  • líneas 108–118: una cita consta de un día (tipo [DATE], sin hora), una franja horaria y un cliente. La restricción [unq1_appointments] impide reservar dos veces la misma franja horaria el mismo día: la base de datos hace cumplir esta regla, incluso si dos usuarios intentan reservarla al mismo tiempo;
  • Líneas 130–140: usuarios de demostración, cuya contraseña es su login. Los hashes comienzan con [$2b$10$]: el algoritmo ([bcrypt], variante [2b]) y el costo (10: 2^10 rondas de cálculo). Siguen la sal (22 caracteres) y el hash. Estos hashes fueron calculados por la versión [Flask] de la aplicación, con la biblioteca [bcrypt] de [Python], que esta versión también utiliza;
  • líneas 144–147: la columna [user] de cada médico se obtiene mediante una subconsulta basada en el login, en lugar de suponer los valores de las claves primarias;
  • líneas 170–171: una cita ya programada para hoy ([CURDATE()]) en la segunda franja horaria de la Dra. PELISSIER para la Sra. BISTROU: así, el calendario muestra de inmediato que la franja está reservada.

A diferencia de lo que ocurre con [Django], la base de datos no se crea mediante las migraciones de [Django] (ejemplo 28): se comparte con las otras versiones de la aplicación y el script SQL es común a todas. Por lo tanto, los modelos se declaran con [managed = False], y el comando [python manage.py makemigrations] no tiene nada que hacer. El comando [python manage.py inspectdb] sirve para comparar la base de datos con los modelos.

11.6. Configuración del proyecto

11.6.1. requirements.txt

1
2
3
4
5
# las bibliotecas de la aplicación: pip install -r requirements.txt
Django==6.1.1
mysqlclient==2.3.0
PyJWT==2.15.0
bcrypt==5.0.0

Las cuatro bibliotecas que necesita la aplicación, con sus versiones exactas (véase la introducción): [Django], el controlador de [MySQL] ([mysqlclient], ejemplo 28), los tokens JWT ([PyJWT], ejemplo 25) y [bcrypt], para las contraseñas de la base de datos (véase más adelante). [pip] también instala las bibliotecas de las que dependen ([asgiref] y [sqlparse], para [Django]). El comando [pip freeze] muestra la lista exacta de lo que está instalado en el entorno, incluidas las dependencias: así se obtiene un archivo que fija todas las versiones. Un proyecto más grande usaría una herramienta de gestión de proyectos, como [uv] o [Poetry], que separa las bibliotecas solicitadas (archivo [pyproject.toml]) de las versiones exactas instaladas (un archivo de bloqueo, como [composer.lock] para [PHP]).

11.6.2. .env

# =========================================================================
# .env: los ajustes propios de ESTA instalación, leídos al inicio por
# config/settings.py. Cada línea NOMBRE=valor se convierte en una variable de entorno
# del proceso; una variable de entorno real del sistema
# tiene prioridad sobre este archivo.
# =========================================================================

# 1: desarrollo (páginas de error detalladas); 0: producción (véase README.md)
DJANGO_DEBUG=1
# la clave secreta de Django (firmas, tokens anti-CSRF...). En producción: otro
# valor, largo y aleatorio
DJANGO_SECRET_KEY=Hayf1oPBd4cm9qXHUGusMtUqCFqEyyj1nnwGxKvuJKYI0EDjjn
# los nombres de host que la aplicación acepta atender (separados por comas)
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

# ---- la base de datos MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql): el
# servidor, su puerto, la base de datos, el usuario y su contraseña (los de Laragon:
# root, sin contraseña)
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=dbrdvmedecins2
DB_USER=root
DB_PASSWORD=

# ---- autenticación (véase security/auth.py)
# clave secreta de los tokens JWT: al menos 32 caracteres (HMAC-SHA256)
JWT_SECRET=229b83fd9cc502aaebd911d2662753a8393b340edb296724
# duración de validez de un token, en minutos (120 min = 2 h)
JWT_DURATION_MINUTES=120
# 1 en producción (sitio servido por HTTPS): las cookies nunca viajan sin cifrar
COOKIE_SECURE=0

# ---- protección contra robots (véase security/limiter.py)
# fallos de inicio de sesión permitidos para el mismo login desde la misma dirección IP, luego
# bloqueo durante esta duración (en minutos); una dirección IP también se bloquea si
# acumula LOGIN_MAX_FAILURES_IP fallos, todos los logins juntos (un robot que prueba
# miles de logins distintos)
LOGIN_MAX_FAILURES=5
LOGIN_MAX_FAILURES_IP=25
LOGIN_BLOCK_MINUTES=15
# cuentas de cliente creadas como máximo por hora y por dirección IP. En un aula, todas
# las computadoras suelen salir por la misma dirección: aumente el valor si es necesario
REGISTRATION_MAX_PER_HOUR=10

El archivo que contiene la configuración específica de esta instalación (ejemplo 25): varía de una máquina a otra (la base de datos, sus credenciales) o son secretos (las claves). En un proyecto real, este archivo nunca se entrega con el código: cada instalación tiene el suyo, y los secretos de producción suelen proporcionarse mediante variables de entorno reales. [Django] no lee por sí mismo un archivo [.env]: lo lee el archivo [config/settings.py] (como se describe más adelante). La biblioteca [python-dotenv] haría lo mismo, y [django-environ] le agregaría la conversión de valores.

  • Línea 9: modo de depuración (ejemplo 01): 1 durante el desarrollo (páginas de error detalladas, comandos SQL en la consola), 0 en producción;
  • línea 12: la clave secreta de [Django], que se utiliza para los tokens anti-CSRF (ejemplo 18) y todas las firmas (cookies firmadas, mensajes flash, ejemplos 20 y 23);
  • línea 14: nombres de host aceptados (ejemplo 01);
  • líneas 19–23: la conexión a la base de datos (ejemplo 28);
  • líneas 25–43: configuración específica de la aplicación: los tokens JWT (ejemplo 25), el modo [Secure] de las cookies (que se explica más adelante) y la protección contra bots (ejemplo 27).

11.6.3. config/settings.py

El archivo de configuración contiene toda la configuración, escrita en [Python] (ejemplo 01):

# =========================================================================
# config/settings.py: la configuración de la aplicación RdvMedecins.
#
# Los ajustes propios de una instalación (contraseñas, claves secretas, umbrales)
# se leen de variables de entorno, que el archivo .env proporciona en
# desarrollo (véase read_env). Todo lo demás se escribe aquí.
# =========================================================================

import os
from pathlib import Path

# la carpeta del proyecto (la que contiene manage.py)
BASE_DIR = Path(__file__).resolve().parent.parent


# -------------------------------------------------------------------------
# lee el archivo .env: cada línea NOMBRE=valor se convierte en una variable
# de entorno, EXCEPTO si ya existe (setdefault): una variable de entorno
# real del sistema tiene prioridad sobre el archivo. Las líneas vacías y los
# comentarios (#) se ignoran; las comillas alrededor del valor se eliminan
# -------------------------------------------------------------------------
def read_env(file: Path) -> None:
    if not file.exists():
        return
    for line in file.read_text(encoding="utf-8").splitlines():
        line = line.strip()
        if line and not line.startswith("#") and "=" in line:
            name, value = line.split("=", 1)
            os.environ.setdefault(name.strip(), value.strip().strip('"'))


read_env(BASE_DIR / ".env")


# una variable de entorno: un texto, un entero, un booleano (1/0)
def env(name: str, default: str = "") -> str:
    return os.environ.get(name, default)


def env_int(name: str, default: int) -> int:
    return int(env(name, str(default)))


def env_bool(name: str, default: bool) -> bool:
    return env(name, "1" if default else "0") == "1"


# ---- modo de depuración y seguridad
DEBUG = env_bool("DJANGO_DEBUG", False)
SECRET_KEY = env("DJANGO_SECRET_KEY")
ALLOWED_HOSTS = [h.strip() for h in env("DJANGO_ALLOWED_HOSTS", "localhost").split(",")]

# ---- las aplicaciones: Django mismo (archivos estáticos, mensajes flash,
# formularios) y nuestras dos aplicaciones: models (las tablas) y web (las
# etiquetas de plantilla). Las demás carpetas (dao, business, security...) son
# paquetes de Python simples: no tienen ni modelos ni plantillas
INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "django.contrib.messages",
    "django.forms",
    "models",
    "web",
]

# ---- los middlewares, en orden (véase el ejemplo 24):
#   - SetLanguage: el idioma de la solicitud (cookie rdvmedecins_language);
#   - CsrfViewMiddleware: el token anti-CSRF de toda solicitud POST;
#   - MessageMiddleware: los mensajes flash;
#   - Authentication: el usuario, a partir del token JWT de su cookie;
#   - AccessControl: la regla de acceso de cada URL (después del enrutamiento);
#   - ErrorPage: los errores se convierten en páginas de la aplicación
MIDDLEWARE = [
    "web.middleware.SetLanguage",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "security.middleware.Authentication",
    "security.middleware.AccessControl",
    "web.middleware.ErrorPage",
]

ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

# ---- la base de datos: MySQL (o MariaDB), la base de datos dbrdvmedecins2
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "HOST": env("DB_HOST", "127.0.0.1"),
        "PORT": env("DB_PORT", "3306"),
        "NAME": env("DB_NAME", "dbrdvmedecins2"),
        "USER": env("DB_USER", "root"),
        "PASSWORD": env("DB_PASSWORD"),
        "OPTIONS": {"charset": "utf8mb4"},
    },
}

# ---- el CACHÉ: archivos de la carpeta var/cache, COMPARTIDOS por todos los
# procesos del servidor (captchas, contadores de fallos, pases, listas de
# médicos y clientes). Un caché en memoria (LocMemCache) sería propio de
# cada proceso: un servidor de producción inicia varios
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": BASE_DIR / "var" / "cache",
    },
}

# ---- las plantillas (carpeta templates) y sus procesadores de contexto
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.template.context_processors.i18n",
                "django.contrib.messages.context_processors.messages",
                # el usuario con sesión iniciada, en todas las plantillas (véase web/contexts.py)
                "web.contexts.user",
            ],
        },
    },
]

# los campos de los formularios se dibujan con las clases de Bootstrap 5 (véase el
# ejemplo 18 y templates/forms/field.html)
FORM_RENDERER = "web.rendering.BootstrapRenderer"

# ---- los idiomas (véase el ejemplo 22): inglés de forma predeterminada, francés; los
# diccionarios están en la carpeta locale
LANGUAGE_CODE = "en"
LANGUAGES = [("fr", "Français"), ("en", "English")]
LOCALE_PATHS = [BASE_DIR / "locale"]
# la cookie que recuerda el idioma elegido (véase web/views/language.py)
LANGUAGE_COOKIE_NAME = "rdvmedecins_language"

# ---- la zona horaria: la del consultorio médico. Determina la fecha de hoy (ninguna
# cita en el pasado, véase business/dates.py)
TIME_ZONE = "Europe/Paris"
USE_TZ = True

# ---- los archivos estáticos (carpeta static): Bootstrap, la hoja de estilo, el script
STATIC_URL = "static/"
STATICFILES_DIRS = [BASE_DIR / "static"]
# en producción, collectstatic reúne allí todos los archivos estáticos (véase README.md)
STATIC_ROOT = BASE_DIR / "var" / "static"

# ---- los mensajes flash: en una cookie firmada (véase el ejemplo 20)
MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

# ---- las cookies: nunca legibles por el JavaScript de la página (HttpOnly, ni siquiera la
# cookie anti-CSRF, que Django deja legible de forma predeterminada), nunca enviadas con una
# solicitud POST proveniente de otro sitio (Lax), nunca sin cifrar en producción (Secure)
COOKIE_SECURE = env_bool("COOKIE_SECURE", False)
CSRF_COOKIE_NAME = "rdvmedecins_csrf"
CSRF_COOKIE_SECURE = COOKIE_SECURE
CSRF_COOKIE_HTTPONLY = True
CSRF_COOKIE_SAMESITE = "Lax"
# un token anti-CSRF faltante o incorrecto: nuestra página de error 419 (véase web/views/errors.py)
CSRF_FAILURE_VIEW = "web.views.errors.csrf_rejected"

# ---- nuestros propios ajustes: autenticación (véase security/auth.py)...
JWT_SECRET = env("JWT_SECRET")
JWT_DURATION_MINUTES = env_int("JWT_DURATION_MINUTES", 120)
# ... y protección contra robots (véase security/limiter.py)
LOGIN_MAX_FAILURES = env_int("LOGIN_MAX_FAILURES", 5)
LOGIN_MAX_FAILURES_IP = env_int("LOGIN_MAX_FAILURES_IP", 25)
LOGIN_BLOCK_MINUTES = env_int("LOGIN_BLOCK_MINUTES", 15)
REGISTRATION_MAX_PER_HOUR = env_int("REGISTRATION_MAX_PER_HOUR", 10)

# ---- logging: en modo de depuración, las sentencias SQL enviadas a la base de datos se escriben en
# la consola (véase el ejemplo 28)
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "django.db.backends": {"handlers": ["console"], "level": "DEBUG"},
    },
}
  • Líneas 22–32: lectura del archivo [.env]. [read_text] lee el archivo completo, mientras que [splitlines] lo divide en líneas. Cada línea de la forma [NAME=value], excepto los comentarios, se convierte en una variable de entorno del proceso ([split("=", 1)]: divide solo en la primera aparición de [=], ya que un valor puede contenerlo). [setdefault] no sobrescribe una variable existente: una variable de entorno real tiene prioridad sobre el archivo (ejemplo 25);
  • líneas 36–45: tres pequeñas funciones que leen una variable de entorno (con un valor predeterminado) y la convierten (a un entero o a un valor booleano de 1 o 0);
  • líneas 49–51: el modo de depuración, la clave secreta y los nombres de host, leídos del entorno. Si [.env] no está presente, el modo de depuración se desactiva: es la opción segura. [ALLOWED_HOSTS] es una lista, construida a partir de una cadena de nombres separados por comas;
  • líneas 57–63: las aplicaciones (véase la arquitectura): tres aplicaciones de [Django] (archivos estáticos, ejemplo 15; mensajes flash, ejemplo 20; plantillas de formularios, ejemplo 18) y nuestras dos;
  • líneas 72–79: los seis componentes de middleware, en el orden en que los atraviesa la solicitud (ejemplo 24). El orden importa: el idioma se establece primero, para que todas las páginas, incluso las de error, estén en el idioma correcto; la protección anti-CSRF va antes de la autenticación; la autenticación (que identifica al usuario) va antes del control de acceso (que evalúa al usuario); y [ErrorPage], el último, es el primero en gestionar las excepciones lanzadas por las vistas ([process_exception] se llama en orden inverso, ejemplo 24);
  • líneas 85–95: la base de datos (ejemplo 28), cuyos parámetros provienen del entorno;
  • líneas 101–106: el caché de la aplicación (ejemplo 27). Se almacena en archivos ([FileBasedCache]) dentro de la carpeta [var/cache], que [Django] crea por sí mismo: a diferencia del caché en memoria del ejemplo 27, sobrevive a los reinicios del servidor (en un servidor de desarrollo, tras cada cambio de código) y es compartido por todos los procesos en un servidor de producción (véase el capítulo sobre los ámbitos). La aplicación almacena en este caché las listas de médicos y clientes, los CAPTCHA, los contadores de intentos y los pases. Con varios servidores, se elegiría un caché compartido, como [Redis];
  • líneas 109–124: las plantillas (ejemplo 13), junto con las plantillas de las aplicaciones ([APP_DIRS], para las de [django.forms], ejemplo 18) y cuatro procesadores de contexto: la solicitud, el idioma (ejemplo 22), los mensajes flash (ejemplo 20) y el nuestro, que pone al usuario conectado a disposición de todas las plantillas (véase más adelante);
  • línea 128: el motor de renderizado de formularios, con las clases de [Bootstrap] (ejemplo 18);
  • líneas 132–136: los idiomas y el diccionario (ejemplo 22). La cookie del idioma tiene un nombre propio de la aplicación;
  • líneas 140–141: la zona horaria del consultorio. [USE_TZ = True] (el valor predeterminado) hace que [Django] opere en hora universal coordinada (UTC) y convierta las horas a esta zona horaria para mostrarlas; [timezone.localdate()] devuelve la fecha actual en esta zona horaria. La fecha actual se usa para una regla de negocio (no se permiten citas en el pasado): en París, entre la medianoche y las 2:00 a.m. durante el horario de verano, la fecha en hora universal coordinada sigue siendo la del día anterior; por lo tanto, prevalece la zona horaria del consultorio;
  • líneas 144–147: los archivos estáticos (ejemplo 15): la carpeta [static] de la aplicación y la carpeta donde [collectstatic] los reúne para producción;
  • línea 150: los mensajes flash, en una cookie firmada (ejemplo 20);
  • líneas 155–161: las cookies de [Django]. [COOKIE_SECURE], leído de [.env], se utilizará también para nuestras propias cookies (el token, el idioma, etc.): en producción, con HTTPS, ninguna cookie se transmite en texto plano. A la cookie del token anti-CSRF se le da un nombre propio de la aplicación; se emite como [HttpOnly] (el [JavaScript] de la página no la necesita: no envía ninguna solicitud por sí mismo) y [SameSite=Lax]. Un token anti-CSRF ausente o inválido mostrará una página de la aplicación (véase más adelante), en lugar de la página 403 de [Django] (ejemplo 18);
  • líneas 164–170: configuración específica de la aplicación, leída del entorno: los tokens JWT (ejemplo 25) y la protección contra bots (ejemplo 27);
  • líneas 174–181: el registro de comandos SQL, en modo de depuración (ejemplo 28).

El comando [python manage.py diffsettings] muestra todos los parámetros de configuración que difieren de los valores predeterminados de [Django].

11.6.4. config/urls.py

# config/urls.py: la tabla de enrutamiento principal

from django.urls import include, path

urlpatterns = [
    path("", include("web.urls")),
]

# las vistas de las páginas de error que Django produce por sí mismo (véase web/views/errors.py):
# en modo de depuración, Django reemplaza las de los errores 400, 404 y 500 con sus
# páginas detalladas
handler400 = "web.views.errors.error_400"
handler403 = "web.views.errors.error_403"
handler404 = "web.views.errors.error_404"
handler500 = "web.views.errors.error_500"

Todas las rutas de la aplicación están en el archivo [web/urls.py] (la capa web, que se explica más adelante), montado en la raíz del sitio (ejemplo 04). Las cuatro vistas de las páginas de error que [Django] genera por sí mismo (ejemplo 24) se designan aquí mediante cadenas (la ruta completa de la función): [Django] las importará por sí mismo.

11.7. Inicio de la aplicación

11.7.1. manage.py y config/wsgi.py

Los archivos [manage.py] y [config/wsgi.py] son los del ejemplo 01: la herramienta de línea de comandos y la aplicación WSGI, que inician el servidor de desarrollo y los servidores de producción. Al arrancar, [Django] lee la configuración (el archivo [config/settings.py] lee a su vez el archivo [.env]), carga las aplicaciones de [INSTALLED_APPS] (sus modelos y su configuración, ejemplo 24), crea un objeto para cada componente de middleware (ejemplo 03) y luego espera solicitudes. Todo lo construido al arrancar es compartido por todas las solicitudes mientras el proceso esté activo: esto se aplica a los objetos únicos de la aplicación (la capa de negocio, la fachada [ApplicationModel]), que sus proveedores crean en el primer uso (ejemplo 06).

Al arrancar se verifican dos cosas, y un error detiene el servidor antes de procesar cualquier solicitud: la clave de los tokens JWT (si es demasiado corta, se rechaza; véase [security/auth.py]) y, con [MySQL], la conexión a la base de datos (véase “Problemas frecuentes”).

11.8. Los modelos

Los modelos del ORM (ejemplo 28): una clase por tabla, en el archivo [models/models.py] de la aplicación [models].

11.8.1. models/apps.py

1
2
3
4
5
6
7
# models/apps.py: la configuración de la aplicación models

from django.apps import AppConfig


class ModelsConfig(AppConfig):
    name = "models"

La configuración de la aplicación (ejemplo 24), reducida a su nombre. No es obligatoria: [Django] generaría una; la escribimos para que cada aplicación tenga la suya.

11.8.2. models/models.py

# =========================================================================
# models/models.py: los MODELOS de Django, una clase por tabla de la
# base de datos dbrdvmedecins2 (véase el ejemplo 28).
#
# Las tablas ya existen: las crea el script
# database/dbrdvmedecins2.sql, el mismo que el de las otras versiones de
# la aplicación. Cada modelo se lo indica a Django con managed = False: Django nunca
# crea, modifica ni elimina estas tablas (sin migraciones).
#
# Las claves externas (ForeignKey, OneToOneField) se declaran con
# on_delete=DO_NOTHING: cuando se elimina una fila, Django no busca por sí mismo
# las filas que la referencian. Es la capa de negocio la que elimina, en el orden
# correcto, lo que debe eliminarse (véase business/service.py); las restricciones de la base de datos
# rechazarían de todos modos una eliminación incompleta.
#
# Todas las tablas tienen una columna [version]: el bloqueo optimista, que la capa
# DAO usa para sus UPDATE (véase dao/persons.py).
# =========================================================================

from django.db import models


# los tres roles de un usuario (columna users.role):
#   - ADMIN  : el administrador - citas + administración de médicos y clientes;
#   - DOCTOR : un médico - reserva y cancela citas;
#   - USER   : un cliente (paciente) - reserva para sí mismo, administra su cuenta.
# TextChoices: una ENUMERACIÓN de Django, cada valor de la cual es una cadena (la que se
# almacena en la base de datos); Role("ADMIN") hace el camino inverso
class Role(models.TextChoices):
    ADMIN = "ADMIN"
    DOCTOR = "DOCTOR"
    USER = "USER"


# un usuario autorizado a iniciar sesión (tabla [users]). Cada médico y cada
# cliente posee SU cuenta (columna [user] de las tablas [doctors] y [clients]).
# restricción SQL de unicidad: unq_users_login (un login pertenece a una sola
# cuenta), reconocida por su NOMBRE en la capa de negocio (véase business/service.py)
class User(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    login = models.CharField(max_length=30)
    # la contraseña con HASH (bcrypt), nunca la contraseña misma
    password = models.CharField(max_length=100)
    # el nombre que se muestra una vez iniciada la sesión: "Marie PELISSIER"
    name = models.CharField(max_length=40)
    # choices: los valores posibles de la columna
    role = models.CharField(max_length=10, choices=Role.choices)

    class Meta:
        db_table = "users"
        managed = False

    def __str__(self):
        return self.login


# -------------------------------------------------------------------------
# lo que tienen en común los médicos (tabla [doctors]) y los clientes (tabla
# [clients]): un título, un apellido, un nombre - y la cuenta de
# usuario asociada (columna [user]).
#
# Las dos tablas tienen exactamente las mismas columnas: se describen UNA SOLA VEZ,
# en este modelo ABSTRACTO (abstract = True: nunca se crea una "Person", y
# no tiene tabla propia), del que heredan Doctor y Client; cada uno solo especifica
# el nombre de su tabla.
#
# Atención: [Client] aquí significa un PACIENTE del consultorio médico, ¡no un cliente
# HTTP! Es el vocabulario del dominio de negocio original, conservado tal cual.
# -------------------------------------------------------------------------
class Person(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # Mr, Mme, Melle
    title = models.CharField(max_length=5)
    last_name = models.CharField(max_length=20)
    first_name = models.CharField(max_length=20)
    # la RELACIÓN con la cuenta de usuario: una persona tiene UNA cuenta, designada por
    # la clave externa [user] (db_column). OneToOneField: una cuenta por persona,
    # una persona por cuenta. person.account devuelve un objeto User, leído de la base de datos en el
    # primer acceso - o por la propia consulta, si lo pide (select_related, véase
    # dao/persons.py). related_name: el nombre de la relación inversa,
    # user.doctor o user.client (%(class)s: el nombre del modelo, en minúsculas)
    account = models.OneToOneField(User, db_column="user", on_delete=models.DO_NOTHING,
                                   related_name="%(class)s")

    class Meta:
        abstract = True

    # "Mme Alice DURAND"
    def label(self) -> str:
        return f"{self.title} {self.first_name} {self.last_name}"

    def __str__(self):
        return self.label()


# un médico (tabla [doctors]). Restricción SQL de unicidad: unq_doctors_first_name_last_name
# (dos médicos no pueden tener el mismo nombre y apellido)
class Doctor(Person):
    class Meta:
        db_table = "doctors"
        managed = False


# un cliente, es decir, un PACIENTE (tabla [clients]). Restricción SQL de unicidad:
# unq_clients_first_name_last_name
class Client(Person):
    class Meta:
        db_table = "clients"
        managed = False


# un horario de un médico (tabla [slots]): 8:00 - 8:20, etc. Los
# horarios los crea el script SQL: la aplicación solo los lee
class Slot(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # varios horarios para el mismo médico: una clave externa, [doctor_id]
    doctor = models.ForeignKey(Doctor, db_column="doctor_id", on_delete=models.DO_NOTHING,
                               related_name="slots")
    start_hour = models.IntegerField()
    start_minute = models.IntegerField()
    end_hour = models.IntegerField()
    end_minute = models.IntegerField()

    class Meta:
        db_table = "slots"
        managed = False

    # "8:00 - 8:20"; :02d: con dos dígitos, "8:05" en lugar de "8:5"
    def time_range(self) -> str:
        return f"{self.start_hour}:{self.start_minute:02d} - {self.end_hour}:{self.end_minute:02d}"


# una cita (tabla [appointments]): un cliente, en un horario, en un día dado.
# Restricción SQL de unicidad: unq1_appointments (day, slot_id) - un horario se reserva
# solo una vez por día; reconocida por su nombre en la capa de negocio
class Appointment(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # DateField: la columna [day] (tipo SQL DATE) se convierte en un objeto date de Python
    day = models.DateField()
    slot = models.ForeignKey(Slot, db_column="slot_id", on_delete=models.DO_NOTHING,
                             related_name="appointments")
    client = models.ForeignKey(Client, db_column="client_id", on_delete=models.DO_NOTHING,
                               related_name="appointments")

    class Meta:
        db_table = "appointments"
        managed = False
  • líneas 29–32: los tres roles, en forma de una enumeración de [Django] ([models.TextChoices]), construida a su vez sobre las enumeraciones de [Python] (el módulo [enum]): un tipo cuyos únicos valores posibles son sus miembros: [Role.ADMIN], [Role.DOCTOR], y [Role.USER]. Cada elemento tiene un valor, en este caso la cadena base; un elemento de [TextChoices] es en sí mismo una cadena: [Role.ADMIN == "ADMIN"] es verdadero. [Role("ADMIN")] devuelve el elemento correspondiente (y lanza [ValueError] con un valor desconocido). [Role.choices] devuelve la lista de pares (valor, etiqueta), que puede pasarse al parámetro [choices] de un campo;
  • líneas 39–55: el esquema de la tabla [users]: la clave primaria, la versión (el bloqueo optimista, ejemplo 28), seguidas de las columnas. [choices] (línea 48) documenta los valores posibles de la columna; [Django] lo usa para validar un formulario basado en el esquema y para la interfaz de administración; la base de datos en sí no realiza ninguna verificación. [managed = False]: la tabla la crea el script SQL (ejemplo 28);
  • líneas 71–95: las tablas [doctors] y [clients] tienen las mismas columnas. Su descripción compartida se escribe una sola vez, en un modelo abstracto ([abstract = True], línea 88): un modelo que no tiene tabla propia y sirve solo para ser heredado. Los modelos [Doctor] y [Client] heredan de él: cada uno tiene los campos de [Person] en su propia tabla. ([Django] también admite verdaderas jerarquías de modelos, en las que cada clase hija tiene una tabla vinculada a la de la clase padre; este no es el caso aquí, donde las dos tablas son independientes);
  • Líneas 84–85: la relación con la cuenta. [OneToOneField]: una persona tiene una cuenta, y una cuenta pertenece a lo sumo a una persona. [db_column] designa la columna de la clave externa, [user] (sin este parámetro, [Django] la designaría como [account_id], el nombre del campo seguido de [_id]). [on_delete] especifica lo que hace [Django] cuando se elimina la cuenta: [DO_NOTHING], nada (el comentario de las líneas 10–14 explica esta elección; [CASCADE] también eliminaría a la persona, mientras que [PROTECT] rechazaría la eliminación). El atributo [account] es un objeto [User], no un número: ese es el propósito de un ORM. Cuando el ORM lee una persona, también lee su cuenta si la consulta lo especifica ([select_related]; véase la capa DAO); de lo contrario, la obtendrá mediante una consulta adicional en el primer acceso a [person.account]. El número en sí siempre está disponible, sin consulta, con el nombre [account_id]. [related_name] designa la relación inversa: [user.doctor] o [user.client], la persona asociada a una cuenta; [%(class)s] se reemplaza por el nombre del modelo, en minúsculas, lo que da un nombre distinto a cada uno de los dos modelos que heredan el campo;
  • líneas 91–95: el nombre de una persona, “Sra. Alice DURAND”, usado por todas las páginas;
  • líneas 100–111: dos modelos que solo especifican su tabla; todo lo demás se hereda. Un [Client] es un paciente del consultorio, no un cliente HTTP: es el vocabulario del dominio de negocio original, conservado en todas las versiones de la aplicación;
  • líneas 116–133: una franja horaria de cita. [ForeignKey] (línea 120): varias franjas horarias para un mismo médico, mediante la clave externa [doctor_id]; la relación inversa, [doctor.slots], devuelve las franjas horarias de un médico. El método [time_range] devuelve “8:00 - 8:20”: en una f-string, [{self.start_minute:02d}] escribe un entero de al menos dos dígitos, rellenado con ceros ([8:05] en lugar de [8:5]);
  • líneas 139–151: una cita. La columna [day] (tipo SQL [DATE]) se convierte en un objeto [date] de tipo [Python] ([DateField]); los objetos [date] son inmutables ([day + timedelta(days=1)] devuelve el día siguiente, [day] permanece sin cambios). Dos relaciones: una con la franja horaria y otra con el cliente de la cita.

11.9. El dominio: el calendario

11.9.1. domain/schedule.py

# =========================================================================
# domain/schedule.py: la agenda de un médico para un día dado. Objetos de
# "negocio" CALCULADOS por la capa de negocio (BusinessService.get_doctor_day_schedule),
# que no corresponden a ninguna tabla, y luego formateados para la plantilla por la
# vista de la agenda (web/views/schedule.py).
#
# frozen=True: los atributos los fija de una vez por todas el constructor -
# justo lo que se necesita para un objeto calculado, que nadie modifica después.
# =========================================================================

from dataclasses import dataclass
from datetime import date

from models.models import Appointment, Doctor, Slot


# un horario y la cita eventualmente reservada en este horario en un día
# dado (None si el horario está libre)
@dataclass(frozen=True)
class DoctorDaySlot:
    slot: Slot
    appointment: Appointment | None


# la agenda completa de un médico para un día dado: la lista de sus horarios,
# cada uno libre u ocupado
@dataclass(frozen=True)
class DoctorDaySchedule:
    doctor: Doctor
    day: date
    doctor_day_slots: list[DoctorDaySlot]

Dos objetos calculados que no corresponden a ninguna tabla: una franja horaria y su posible cita en un día determinado; la agenda de un médico para un solo día, la lista de sus franjas horarias. Son clases de datos inmutables (ejemplo 03), cuyos atributos están tipados: [Appointment | None] (una cita, o [None] para una franja horaria disponible), [list[DoctorDaySlot]] (una lista de franjas horarias). [Python] no valida estos tipos en tiempo de ejecución, pero los editores ([Pylance]) y las herramientas de análisis ([mypy]) los leen.

11.10. La capa DAO

La capa DAO (ejemplo 28) agrupa las consultas: un módulo por tabla (médicos y clientes comparten el suyo), sin reglas de negocio. Sus métodos no inician una transacción: la capa de negocio los llama dentro de sus propias transacciones. Están escritos con el [QuerySet] del ORM (ejemplo 28); los valores allí son parámetros de la consulta: no es posible la inyección SQL. Los DAO son clases, de las que la capa de negocio crea un objeto de cada una; no tienen estado: son colecciones de funciones.

11.10.1. dao/persons.py

# =========================================================================
# dao/persons.py: la capa DAO común a médicos y clientes.
#
# Los DAO de médicos y de clientes serían idénticos: la clase PersonDao
# los escribe una sola vez. self.model es el modelo en cuestión (Doctor o
# Client): las consultas se aplican a SU tabla.
#
# Las consultas se escriben con el ORM de Django (véase el ejemplo 28), que las traduce
# a SQL. Los valores (nombre, apellido...) se convierten en PARÁMETROS de la sentencia SQL:
# ninguna concatenación de cadenas, por lo tanto ninguna inyección SQL. Estos métodos no abren
# ninguna transacción: es la capa de negocio la que los llama, dentro de la suya.
# =========================================================================

from django.db.models import F, QuerySet

from models.models import Client, Doctor, Person


class PersonDao:
    # model: la CLASE del modelo, Doctor o Client (en Python, una clase es
    # un valor como cualquier otro, que puede almacenarse en una variable)
    def __init__(self, model: type[Person]):
        self.model = model

    # -----------------------------------------------------------------------
    # una consulta sobre la tabla del modelo, cuenta de usuario incluida.
    # select_related("account"): la unión (join) SQL con la tabla [users]
    #   SELECT doctors.*, users.* FROM doctors INNER JOIN users ON ...
    # las cuentas se cargan EN LA MISMA consulta. Sin ello, cada acceso a
    # person.account desencadenaría su propia consulta
    # -----------------------------------------------------------------------
    def _query(self) -> QuerySet:
        return self.model.objects.select_related("account")

    # lista ordenada por apellido y luego por nombre
    def list(self) -> list[Person]:
        return list(self._query().order_by("last_name", "first_name"))

    # una persona y su cuenta; None si no existen
    def read(self, id: int) -> Person | None:
        return self._query().filter(id=id).first()

    # la persona cuya cuenta de usuario es [user_id]; account_id: la
    # columna de la propia clave externa, sin unión
    def read_by_user(self, user_id: int) -> Person | None:
        return self._query().filter(account_id=user_id).first()

    # la persona con este nombre y apellido, si existe. La comparación la
    # hace MySQL, por lo tanto con la intercalación (collation) de la base de datos (utf8mb4_unicode_ci: sin distinguir
    # mayúsculas ni acentos) - exactamente la misma regla que
    # la de la restricción SQL de unicidad
    def namesake(self, first_name: str, last_name: str) -> Person | None:
        return self._query().filter(first_name=first_name, last_name=last_name).first()

    # INSERT: la base de datos genera el id, que Django almacena en el objeto creado
    def add(self, title: str, last_name: str, first_name: str, account) -> Person:
        return self.model.objects.create(title=title, last_name=last_name, first_name=first_name, account=account)

    # -----------------------------------------------------------------------
    # UPDATE con BLOQUEO OPTIMISTA (véase el ejemplo 28):
    #   UPDATE doctors SET title = ?, last_name = ?, first_name = ?, version = version + 1
    #   WHERE id = ? AND version = ?
    # devuelve False si no se modificó ninguna fila: el registro ha cambiado (o desapareció)
    # desde que se leyó
    # -----------------------------------------------------------------------
    def update(self, id: int, version: int, title: str, last_name: str, first_name: str) -> bool:
        return self.model.objects.filter(id=id, version=version).update(
            title=title, last_name=last_name, first_name=first_name, version=F("version") + 1) == 1

    # DELETE FROM doctors WHERE id = ?
    def delete(self, id: int) -> None:
        self.model.objects.filter(id=id).delete()


# el DAO de los médicos: todo se hereda de PersonDao
class DoctorDao(PersonDao):
    def __init__(self):
        super().__init__(Doctor)


# el DAO de los clientes: el de las personas, más un método de bloqueo
class ClientDao(PersonDao):
    def __init__(self):
        super().__init__(Client)

    # -----------------------------------------------------------------------
    # pone un BLOQUEO sobre la fila de un cliente hasta el final de la
    # transacción en curso (SELECT ... FOR UPDATE) y devuelve su id (None si el cliente no
    # existe). Una segunda transacción que solicite el mismo bloqueo ESPERA hasta que la
    # primera haya terminado. select_for_update: el bloqueo "pesimista" de
    # Django, que requiere una transacción abierta.
    # Se usa para reservar una cita (véase BusinessService.add_appointment): dos
    # reservas simultáneas para el mismo paciente se procesan así una
    # DESPUÉS de la otra, y la segunda ve la cita creada por la primera.
    # values_list("id", flat=True): la única columna id, sin un objeto Client
    # -----------------------------------------------------------------------
    def lock(self, id: int) -> int | None:
        return Client.objects.select_for_update().filter(id=id).values_list("id", flat=True).first()
  • Líneas 19–23: los objetos DAO de médicos y clientes serían idénticos, salvo por el modelo: la clase [PersonDao] los crea una sola vez y recibe el modelo como parámetro de su constructor. [type[Person]] es la anotación de una clase (no de un objeto): [Person] o una de sus clases hijas;
  • líneas 32–33: la consulta base, común a todos los métodos. [select_related("account")] indica al ORM que recupere también la cuenta de cada persona mediante una combinación ([INNER JOIN users]; véase la salida de la consola más arriba): una sola consulta, en lugar de una consulta adicional por persona. Sin ello, mostrar la lista de médicos con sus logins requeriría una consulta para la lista y luego una por médico: es el llamado problema de las “N + 1 consultas”, la trampa más común de los ORM. El guion bajo al comienzo del nombre del método indica que es interno a la clase (ejemplo 06);
  • líneas 36–46: las lecturas. [account_id] (línea 46) designa la propia columna de la clave externa: la condición se aplica a la tabla de personas, sin combinación;
  • líneas 52–53: búsqueda de un homónimo. La comparación la realiza [MySQL], con la intercalación de la base de datos: sin distinguir mayúsculas y sin tener en cuenta los acentos, exactamente como la restricción de unicidad (ejemplo 28);
  • líneas 56–57: la inserción; [account] es una instancia de [User], que ya ha sido insertada;
  • líneas 66–68: la actualización, con su bloqueo optimista (ejemplo 28): [update] devuelve el número de filas modificadas, 0 si la versión ha cambiado;
  • líneas 71–72: la eliminación, mediante un [QuerySet]: [delete()] envía un [DELETE] para todas las filas que designa;
  • líneas 76–78: el DAO de los médicos, que hereda todo. [super().__init__(Doctor)] llama al constructor de la clase padre con el modelo;
  • líneas 82–98: el DAO de los clientes, con un método adicional. [select_for_update()] agrega a la consulta [FOR UPDATE]: [MySQL] coloca un bloqueo sobre las filas leídas hasta el final de la transacción en curso. Una segunda transacción que solicite el mismo bloqueo espera hasta que la primera termine. Es un bloqueo “pesimista”: bloquea la transacción, en lugar de detectar los conflictos a posteriori como un bloqueo optimista. Solo se permite dentro de una transacción (de lo contrario, el ORM lanza una excepción). [values_list("id", flat=True)] lee solo la columna [id]: una lista de enteros, no de objetos. El comentario del código explica el propósito de este bloqueo; volveremos sobre ello al hablar de la capa de negocio.

11.10.2. dao/slots.py

# dao/slots.py: la capa DAO de los horarios

from models.models import Slot


class SlotDao:
    # un horario y su médico (una unión)
    def read(self, id: int) -> Slot | None:
        return Slot.objects.select_related("doctor").filter(id=id).first()

    # los horarios de un médico, en orden cronológico. doctor_id: la columna
    # de la clave externa, comparada con un id
    def list_by_doctor(self, doctor_id: int) -> list[Slot]:
        return list(Slot.objects.filter(doctor_id=doctor_id).order_by("start_hour", "start_minute"))

    # elimina todos los horarios de un médico (eliminación de un médico):
    #   DELETE FROM slots WHERE doctor_id = ?
    def delete_by_doctor(self, doctor_id: int) -> None:
        Slot.objects.filter(doctor_id=doctor_id).delete()

Las franjas horarias de cita de un médico, en orden cronológico; una franja horaria y su médico (una combinación); la eliminación de las franjas horarias de un médico (que precede a la eliminación del médico, debido a la restricción de clave externa).

11.10.3. dao/appointments.py

# =========================================================================
# dao/appointments.py: la capa DAO de las citas.
#
# La tabla [appointments] no hace referencia directa al médico: pasa por el horario.
# El ORM de Django escribe la unión por sí mismo cuando un filtro sigue una relación:
# slot__doctor_id (dos guiones bajos: "el médico del horario").
# =========================================================================

from datetime import date

from models.models import Appointment, Client, Slot


class AppointmentDao:
    # una cita, su cliente y su horario
    def read(self, id: int) -> Appointment | None:
        return Appointment.objects.select_related("client", "slot").filter(id=id).first()

    # las citas de un médico en un día dado, con su cliente
    def doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return list(Appointment.objects.select_related("client")
                    .filter(day=day, slot__doctor_id=doctor_id))

    # -----------------------------------------------------------------------
    # las citas de un cliente a partir del día [since] (incluido), en orden
    # cronológico, con el horario Y el médico de ese horario (dos uniones:
    # select_related("slot__doctor")). day__gte: day >= since (gte:
    # "greater than or equal", mayor o igual que)
    # -----------------------------------------------------------------------
    def client_upcoming_appointments(self, client_id: int, since: date) -> list[Appointment]:
        return list(Appointment.objects.select_related("slot__doctor")
                    .filter(client_id=client_id, day__gte=since)
                    .order_by("day", "slot__start_hour", "slot__start_minute"))

    # número de citas de un cliente a partir del día [since] (incluido):
    # count() hace que la base de datos cuente (SELECT COUNT(*) ...)
    def count_client_upcoming(self, client_id: int, since: date) -> int:
        return Appointment.objects.filter(client_id=client_id, day__gte=since).count()

    # número de citas (pasadas o futuras) de un médico
    def count_by_doctor(self, doctor_id: int) -> int:
        return Appointment.objects.filter(slot__doctor_id=doctor_id).count()

    # INSERT INTO appointments ...
    def add(self, day: date, slot: Slot, client: Client) -> Appointment:
        return Appointment.objects.create(day=day, slot=slot, client=client)

    def delete(self, id: int) -> None:
        Appointment.objects.filter(id=id).delete()

    # elimina TODAS las citas (pasadas y futuras) de un cliente
    def delete_by_client(self, client_id: int) -> None:
        Appointment.objects.filter(client_id=client_id).delete()
  • Líneas 20–22: las citas de un médico en un día determinado. La tabla [appointments] no hace referencia directa al médico: [slot__doctor_id] (dos guiones bajos) sigue la relación hacia la franja horaria y luego compara la columna [doctor_id] de la franja horaria. El ORM escribe la combinación por sí mismo ([INNER JOIN slots]; véase la salida de la consola más arriba). El cliente de cada cita se recupera con la misma consulta;
  • líneas 30–33: las próximas citas de un cliente. [select_related("slot__doctor")] combina dos tablas: la franja horaria y luego el médico del cliente (dos combinaciones). [day__gte]: el sufijo [gte] (“greater than or equal”, ejemplo 28) realiza una comparación con [>=]. El ordenamiento también sigue las relaciones;
  • líneas 37–42: [count()] cuenta la base ([SELECT COUNT(*)]) sin leer las filas;
  • líneas 45–53: inserciones y eliminaciones.

11.10.4. dao/users.py

# dao/users.py: la capa DAO de las cuentas de usuario. Crear (o eliminar) un
# médico o un cliente también crea (o elimina) su cuenta - véase business/service.py

from django.db.models import F

from models.models import User


class UserDao:
    # None si ningún usuario tiene este login
    def read_by_login(self, login: str) -> User | None:
        return User.objects.filter(login=login).first()

    def add(self, login: str, hash: str, name: str, role: str) -> User:
        return User.objects.create(login=login, password=hash, name=name, role=role)

    # UPDATE con bloqueo optimista (véase dao/persons.py); hash None: la
    # contraseña no cambia. **fields: el diccionario, "desempaquetado" en parámetros con nombre
    def update(self, id: int, version: int, login: str, name: str, hash: str | None) -> bool:
        fields = {"login": login, "name": name, "version": F("version") + 1}
        if hash is not None:
            fields["password"] = hash
        return User.objects.filter(id=id, version=version).update(**fields) == 1

    def delete(self, id: int) -> None:
        User.objects.filter(id=id).delete()

Las cuentas de usuario. La modificación (líneas 19–23) tiene un parámetro opcional: el hash de la nueva contraseña, o [None] para conservar la existente. Las columnas por modificar se agrupan en un diccionario, que [**fields] pasa a [update] como parámetros con nombre (el “desempaquetado” de un diccionario, ejemplo 08).

11.11. La capa de negocio

La capa de negocio (ejemplo 28): reglas de negocio y transacciones. No sabe nada de la web: ni solicitudes, ni respuestas, ni plantillas.

11.11.1. business/dates.py

# business/dates.py: la fecha de hoy. La usan las REGLAS DE NEGOCIO (ninguna
# reserva en el pasado, una sola cita PRÓXIMA por paciente): por eso vive
# en la capa de negocio. La capa web la reutiliza.

from datetime import date

from django.utils import timezone


# hoy, en la zona horaria de la aplicación (configuración TIME_ZONE)
def today() -> date:
    return timezone.localdate()

La fecha de hoy, en la zona horaria de la aplicación ([TIME_ZONE], véase [config/settings.py]): [timezone.localdate()] convierte la hora universal coordinada a esta zona horaria y luego devuelve la fecha. La fecha actual se usa para dos reglas de negocio (no se permiten citas en el pasado, solo una cita futura): por lo tanto, se calcula aquí, en un único lugar.

11.11.2. business/errors.py

# =========================================================================
# business/errors.py: la excepción que lanza la capa de negocio cuando se viola una REGLA
# DE NEGOCIO (login ya usado, médico que aún tiene citas,
# horario ya reservado...).
#
# Lleva un CÓDIGO (LOGIN_TAKEN...), que la capa web puede evaluar, y el mensaje
# destinado al usuario. Este mensaje se traduce al francés o al inglés en el
# momento de mostrarlo, en el idioma de la página: gettext_lazy devuelve una traducción
# "perezosa", que solo se calcula cuando se solicita su texto
# (str), y no cuando se carga el módulo (véase el ejemplo 22 y la carpeta locale).
#
# Un BusinessError no es una anomalía: es una respuesta normal ("este login
# ya está en uso"), que se muestra al usuario. Cualquier otra excepción es una verdadera
# anomalía, que termina en la página de error 500.
# =========================================================================

from django.utils.translation import gettext_lazy as _

# los códigos de los errores de negocio
LOGIN_TAKEN = "LOGIN_TAKEN"
DOCTOR_ALREADY_EXISTS = "DOCTOR_ALREADY_EXISTS"
CLIENT_ALREADY_EXISTS = "CLIENT_ALREADY_EXISTS"
DOCTOR_HAS_APPOINTMENTS = "DOCTOR_HAS_APPOINTMENTS"
SLOT_ALREADY_BOOKED = "SLOT_ALREADY_BOOKED"
CONCURRENT_UPDATE = "CONCURRENT_UPDATE"
DOCTOR_NOT_FOUND = "DOCTOR_NOT_FOUND"
CLIENT_NOT_FOUND = "CLIENT_NOT_FOUND"
PAST_DATE = "PAST_DATE"
PATIENT_HAS_APPOINTMENT = "PATIENT_HAS_APPOINTMENT"

# el mensaje de cada código
MESSAGES = {
    LOGIN_TAKEN: _("This login is already used by another account."),
    DOCTOR_ALREADY_EXISTS: _("A doctor with this first and last name already exists."),
    CLIENT_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)."),
    CLIENT_NOT_FOUND: _("This patient does not exist (any more)."),
    PAST_DATE: _("Appointments cannot be booked for a past date."),
    PATIENT_HAS_APPOINTMENT: _("This patient already has an upcoming appointment: it must be cancelled "
                               "before booking another one."),
}


class BusinessError(Exception):
    def __init__(self, code: str):
        super().__init__(code)
        self.code = code

    # el mensaje, en el idioma de la solicitud actual; @property: se escribe
    # error.message, sin paréntesis
    @property
    def message(self) -> str:
        return str(MESSAGES[self.code])
  • líneas 20–29: los códigos de error de negocio y las constantes (ejemplo 09). La capa web puede verificar un código de error para asociarlo con el campo correcto de un formulario (véase más adelante);
  • Líneas 32–45: el mensaje de cada código, marcado como “por traducir”. [gettext_lazy], importado con el nombre corto [_] (como se usa en el ejemplo 22), proporciona una traducción diferida: un objeto que obtiene su traducción solo cuando se solicita el texto. Una traducción estándar ([gettext]) se realizaría al cargar el módulo, al arrancar, una vez por todas, en el idioma predeterminado; la traducción diferida se realiza cada vez que se muestra el contenido, en el idioma de la solicitud actual. Dos cadenas escritas una junto a otra son concatenadas por [Python] (línea 38);
  • líneas 48–57: la excepción de la capa de negocio (ejemplo 28), que lleva su propio código. La propiedad [message] (ejemplo 14) muestra el mensaje en el idioma de la solicitud; [str] fuerza la traducción diferida.

Un [BusinessError] no es un error: es una respuesta normal (“este login ya está en uso”), que se muestra al usuario. Cualquier otra excepción es un error real, que genera una página de error 500.

11.11.3. business/person_data.py

# business/person_data.py: los datos ingresados en un formulario de "médico" o "cliente",
# tal como la capa web los pasa a la capa de negocio

from dataclasses import dataclass


@dataclass(frozen=True)
class PersonData:
    title: str          # Mr, Mme, Melle
    last_name: str
    first_name: str
    # creación: opcional (None), por defecto el apellido en minúsculas
    # actualización: opcional, el login no cambia si falta
    login: str | None = None
    # creación: opcional, por defecto el login
    # actualización: opcional, la contraseña no cambia si falta
    password: str | None = None
    # actualización: la versión del registro en el momento en que se
    # mostró el formulario (bloqueo optimista)
    version: int | None = None

Los datos de una persona, tal como la capa web los transmite a la capa de negocio (ejemplo 28). Los tres últimos atributos tienen un valor predeterminado, [None]: son opcionales. Se permite un comentario a continuación de un atributo (línea 9): el comentario se extiende desde [#] hasta el final de la línea.

11.11.4. business/business.py

# =========================================================================
# business/business.py: el CONTRATO de la capa de negocio: lecturas, agenda,
# citas, gestión de médicos y clientes.
#
# Una clase abstracta (ABC, véase el ejemplo 06) describe los métodos que una clase debe
# tener, sin decir cómo se escriben. BusinessService (la capa de negocio) y
# ApplicationModel (el caché de la capa web) heredan de ella; Python
# se niega a crear un objeto de una clase a la que le falta un método abstracto.
#
# X | None: un resultado que puede faltar (un médico que no existe...).
# =========================================================================

from abc import ABC, abstractmethod
from datetime import date

from domain.schedule import DoctorDaySchedule
from models.models import Appointment, Client, Doctor, Slot

from .person_data import PersonData


class Business(ABC):
    # ------------------------------------------------ lecturas
    @abstractmethod
    def get_all_clients(self) -> list[Client]: ...

    @abstractmethod
    def get_all_doctors(self) -> list[Doctor]: ...

    @abstractmethod
    def get_all_slots(self, doctor_id: int) -> list[Slot]: ...

    @abstractmethod
    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]: ...

    @abstractmethod
    def get_client_by_id(self, id: int) -> Client | None: ...

    @abstractmethod
    def get_doctor_by_id(self, id: int) -> Doctor | None: ...

    @abstractmethod
    def get_appointment_by_id(self, id: int) -> Appointment | None: ...

    @abstractmethod
    def get_slot_by_id(self, id: int) -> Slot | None: ...

    @abstractmethod
    def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None: ...

    # el cliente (paciente) cuya cuenta de usuario es [user_id]
    @abstractmethod
    def get_client_by_user_id(self, user_id: int) -> Client | None: ...

    # las citas de un cliente, de hoy o futuras, con horario y médico
    @abstractmethod
    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]: ...

    # ------------------------------------------------ citas (ADMIN, DOCTOR, USER)
    # lanza un BusinessError si:
    #  - el día ya pasó (PAST_DATE);
    #  - el paciente ya tiene una cita próxima (PATIENT_HAS_APPOINTMENT);
    #  - el horario ya está ocupado ese día (SLOT_ALREADY_BOOKED).
    @abstractmethod
    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment: ...

    @abstractmethod
    def delete_appointment(self, appointment: Appointment) -> None: ...

    # ------------------------------------------------ médicos (ADMIN)
    # crea al médico Y su cuenta de usuario (rol DOCTOR)
    @abstractmethod
    def add_doctor(self, data: PersonData) -> Doctor: ...

    # actualiza al médico Y su cuenta de usuario
    @abstractmethod
    def edit_doctor(self, id: int, data: PersonData) -> Doctor: ...

    # elimina al médico, sus horarios Y su cuenta - se rechaza si tiene citas
    @abstractmethod
    def delete_doctor(self, id: int) -> None: ...

    # ------------------------------------------------ clientes
    # (el ADMIN; add_client también se usa para el registro de un paciente,
    # edit_client y delete_client los usa el paciente para su propia cuenta)
    # crea al cliente Y su cuenta de usuario (rol USER)
    @abstractmethod
    def add_client(self, data: PersonData) -> Client: ...

    @abstractmethod
    def edit_client(self, id: int, data: PersonData) -> Client: ...

    # elimina al cliente, su cuenta Y todas sus citas (pasadas y futuras)
    @abstractmethod
    def delete_client(self, id: int) -> None: ...

El contrato de la capa de negocio, una clase abstracta (ejemplo 06): todos los métodos, con sus parámetros y tipos, y, en comentarios, las reglas que aplican. El cuerpo de un método abstracto puede escribirse en la misma línea que su firma ([: ...]). Dos clases heredan de este contrato: [BusinessService], la propia capa de negocio, y [ApplicationModel], la fachada de la capa web (que se explica más adelante), que puede así reemplazar a la capa de negocio dondequiera que se espere un objeto [Business].

11.11.5. business/descriptor.py

# business/descriptor.py: todo lo que distingue a un médico de un cliente para las
# reglas de negocio (véase business/service.py). Médicos y clientes siguen las
# mismas reglas: el código común se escribe UNA SOLA VEZ y se parametriza mediante un descriptor.

from collections.abc import Callable
from dataclasses import dataclass

from dao.persons import PersonDao


@dataclass(frozen=True)
class Descriptor:
    dao: PersonDao
    role: str                   # DOCTOR o USER
    not_found_code: str         # error si la persona no existe
    already_exists_code: str    # error si ya existen el mismo nombre y apellido
    # opcional (None): si está presente, la eliminación se RECHAZA mientras la
    # persona tenga citas (count_appointments(id) > 0), con el error has_appointments_code.
    # Callable[[int], int]: una función que recibe un entero y devuelve un entero
    count_appointments: Callable[[int], int] | None
    has_appointments_code: str | None
    # opcional: lo que debe eliminarse ANTES que la persona (las filas que
    # la referencian mediante una clave externa); recibe su id
    before_delete: Callable[[int], None] | None

Los médicos y los clientes siguen las mismas reglas de gestión, con algunas diferencias menores: los roles de sus cuentas, sus códigos de error y lo que impide o facilita su eliminación. Un descriptor reúne estos detalles; el código común, en [BusinessService], se define una sola vez y recibe el descriptor. Los tres últimos atributos son funciones: [Callable[[int], int]] declara una función que recibe un entero y devuelve un entero (el módulo [collections.abc] proporciona estos tipos abstractos); [| None]: o nada.

11.11.6. business/provider.py

# business/provider.py: el proveedor de la capa de negocio (véase el ejemplo 06):
# UN solo objeto BusinessService, creado en la primera solicitud y compartido luego por todas las
# solicitudes mientras el servidor se ejecute. No tiene estado propio de una solicitud:
# compartirlo es seguro, incluso entre varios hilos

from functools import cache

from .service import BusinessService


@cache
def business() -> BusinessService:
    return BusinessService()

El proveedor de la capa de negocio (ejemplo 06): un único objeto [BusinessService], creado en la primera solicitud y luego compartido por todas las solicitudes. Esto es seguro, incluso con varios hilos de ejecución (ejemplo 20): el objeto no tiene estado específico de la solicitud (sus objetos DAO tampoco), y cada hilo tiene su propia conexión a la base de datos (el ORM de [Django] abre una conexión por hilo de ejecución).

11.11.7. business/service.py

# =========================================================================
# business/service.py: la implementación de la capa de negocio.
#
# La gestión de médicos y clientes obedece tres reglas de negocio:
#
#   1. una persona (médico o cliente) y su cuenta de usuario van SIEMPRE
#      juntas: se crean, actualizan y eliminan juntas, en la misma
#      TRANSACCIÓN - o todo se completa, o no se escribe nada;
#   2. el login es único en toda la aplicación, y dos médicos (o dos
#      clientes) no pueden tener los mismos nombre y apellido;
#   3. eliminación:
#      - un MÉDICO que tiene citas no puede eliminarse (sus pacientes
#        perderían su cita sin ser avisados): primero deben
#        cancelarse. Sus horarios desaparecen con él;
#      - un CLIENTE, en cambio, desaparece con TODAS sus citas (pasadas y futuras) -
#        ya sea que la eliminación venga del ADMIN o del propio paciente.
#
# Y dos reglas para reservar citas, sea cual sea el rol de quien
# reserva (ADMIN, DOCTOR o el propio paciente):
#   4. ninguna cita en el pasado;
#   5. un paciente tiene una SOLA cita próxima a la vez.
#
# Médicos y clientes siguen exactamente las mismas reglas: el código común se
# escribe UNA SOLA VEZ (métodos _xxx_person) y se parametriza mediante un descriptor que indica
# con qué tipo de persona se trabaja.
#
# Las TRANSACCIONES las abre el método _transaction (al final del archivo),
# que además traduce a BusinessError los errores informados por la base de datos.
# =========================================================================

import re
from collections.abc import Callable
from datetime import date

from django.db import IntegrityError, transaction

from dao.slots import SlotDao
from dao.persons import ClientDao, DoctorDao
from dao.appointments import AppointmentDao
from dao.users import UserDao
from domain.schedule import DoctorDaySchedule, DoctorDaySlot
from models.models import Appointment, Client, Doctor, Person, Role, Slot
from security import passwords

from . import errors
from .dates import today
from .descriptor import Descriptor
from .person_data import PersonData
from .errors import BusinessError
from .business import Business

# -------------------------------------------------------------------------
# Errores de la base de datos -> BusinessError
#
# Cuando una restricción UNIQUE rechaza una escritura, Django lanza un IntegrityError,
# cuyo mensaje es el de MySQL. Cita el NOMBRE de la restricción:
#   (1062, "Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'")
# (MySQL 8 antepone al nombre el de la tabla, MariaDB no). Por eso
# el script SQL da NOMBRE a todas sus restricciones. La expresión regular CONSTRAINT
# extrae este nombre: (?:[^'.]*\.)? omite el prefijo opcional, ([^']+) captura el nombre
# -------------------------------------------------------------------------
CONSTRAINT_ERRORS = {
    "unq_users_login": errors.LOGIN_TAKEN,
    "unq_doctors_first_name_last_name": errors.DOCTOR_ALREADY_EXISTS,
    "unq_clients_first_name_last_name": errors.CLIENT_ALREADY_EXISTS,
    "unq1_appointments": errors.SLOT_ALREADY_BOOKED,
}

CONSTRAINT = re.compile(r"for key '(?:[^'.]*\.)?([^']+)'")


# un BusinessError CONCURRENT_UPDATE, lanzado DENTRO de una transacción para que
# se revierta: un UPDATE no modificó ninguna fila (bloqueo optimista)
class _StaleVersion(Exception):
    pass


class BusinessService(Business):
    # los DAO, creados una vez por todas; no tienen estado: un solo objeto de
    # cada uno atiende todas las solicitudes
    def __init__(self):
        self.doctors = DoctorDao()
        self.clients = ClientDao()
        self.slots = SlotDao()
        self.appointments = AppointmentDao()
        self.users = UserDao()

        self.doctor = Descriptor(
            dao=self.doctors,
            role=Role.DOCTOR,
            not_found_code=errors.DOCTOR_NOT_FOUND,
            already_exists_code=errors.DOCTOR_ALREADY_EXISTS,
            # self.appointments.count_by_doctor: el método mismo, sin llamarlo (un
            # "método enlazado" del objeto self.appointments, que se llamará más tarde)
            count_appointments=self.appointments.count_by_doctor,
            has_appointments_code=errors.DOCTOR_HAS_APPOINTMENTS,
            # un médico sin citas aún puede tener horarios:
            # no tienen sentido sin ellas, se eliminan con ellas (de lo contrario la
            # clave externa slots.doctor_id impediría la eliminación)
            before_delete=self.slots.delete_by_doctor)

        self.client = Descriptor(
            dao=self.clients,
            role=Role.USER,
            not_found_code=errors.CLIENT_NOT_FOUND,
            already_exists_code=errors.CLIENT_ALREADY_EXISTS,
            # sin count_appointments: la eliminación de un cliente nunca se rechaza;
            # sus citas (pasadas y futuras) se eliminan con él (de lo contrario
            # la clave externa appointments.client_id impediría la eliminación)
            count_appointments=None,
            has_appointments_code=None,
            before_delete=self.appointments.delete_by_client)

    # =======================================================================
    # lecturas
    # =======================================================================

    def get_all_clients(self) -> list[Client]:
        return self.clients.list()

    def get_all_doctors(self) -> list[Doctor]:
        return self.doctors.list()

    def get_all_slots(self, doctor_id: int) -> list[Slot]:
        return self.slots.list_by_doctor(doctor_id)

    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return self.appointments.doctor_day_appointments(doctor_id, day)

    def get_client_by_id(self, id: int) -> Client | None:
        return self.clients.read(id)

    def get_doctor_by_id(self, id: int) -> Doctor | None:
        return self.doctors.read(id)

    def get_appointment_by_id(self, id: int) -> Appointment | None:
        return self.appointments.read(id)

    def get_slot_by_id(self, id: int) -> Slot | None:
        return self.slots.read(id)

    def get_client_by_user_id(self, user_id: int) -> Client | None:
        return self.clients.read_by_user(user_id)

    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
        return self.appointments.client_upcoming_appointments(client_id, today())

    # la agenda de un médico en un día dado: sus horarios y, para cada uno, la
    # cita reservada ese día (None si está libre)
    def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
        doctor = self.get_doctor_by_id(doctor_id)
        if doctor is None:
            return None
        # una COMPRENSIÓN de diccionario: n.º de horario -> cita reservada en ese horario
        bookings = {a.slot_id: a for a in self.get_doctor_day_appointments(doctor_id, day)}
        # get(key): el valor, o None si la clave no existe
        doctor_day_slots = [DoctorDaySlot(slot, bookings.get(slot.id))
                            for slot in self.get_all_slots(doctor_id)]
        return DoctorDaySchedule(doctor, day, doctor_day_slots)

    # =======================================================================
    # citas
    # =======================================================================

    # -----------------------------------------------------------------------
    # reserva de una cita, en una transacción:
    #   1. ninguna cita en el pasado;
    #   2. la fila del paciente se BLOQUEA (SELECT ... FOR UPDATE): si el mismo
    #      paciente reserva dos horarios al mismo tiempo (dos pestañas, doble
    #      clic...), la segunda transacción espera a que termine la primera - y entonces ve
    #      la cita que esta acaba de crear;
    #   3. una sola cita próxima por paciente;
    #   4. por último, la inserción. Si el horario acaba de ser tomado por OTRO paciente,
    #      es la restricción SQL unq1_appointments (day, slot_id) la que rechaza
    #      la inserción - traducida a BusinessError por _transaction.
    # Una función definida DENTRO de un método (work) ve las variables de
    # ese método (day, slot, client): es una "clausura" (closure)
    # -----------------------------------------------------------------------
    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
        def work():
            if day < today():
                raise BusinessError(errors.PAST_DATE)
            patient_id = self.clients.lock(client.id)
            if patient_id is None:
                raise BusinessError(errors.CLIENT_NOT_FOUND)
            if self.appointments.count_client_upcoming(patient_id, today()) > 0:
                raise BusinessError(errors.PATIENT_HAS_APPOINTMENT)
            return self.appointments.add(day, slot, client)
        return self._transaction(work)

    def delete_appointment(self, appointment: Appointment) -> None:
        # lambda: una función anónima reducida a una expresión
        self._transaction(lambda: self.appointments.delete(appointment.id))

    # =======================================================================
    # médicos y clientes - los métodos públicos delegan en los métodos
    # comunes, con el descriptor adecuado
    # =======================================================================

    def add_doctor(self, data: PersonData) -> Doctor:
        return self._add_person(self.doctor, data)

    def edit_doctor(self, id: int, data: PersonData) -> Doctor:
        return self._edit_person(self.doctor, id, data)

    def delete_doctor(self, id: int) -> None:
        self._delete_person(self.doctor, id)

    def add_client(self, data: PersonData) -> Client:
        return self._add_person(self.client, data)

    def edit_client(self, id: int, data: PersonData) -> Client:
        return self._edit_person(self.client, id, data)

    # el cliente, su cuenta Y todas sus citas (el ADMIN, o el propio paciente
    # desde "Gestionar mi cuenta": mismo método, misma regla)
    def delete_client(self, id: int) -> None:
        self._delete_person(self.client, id)

    # -----------------------------------------------------------------------
    # creación: la cuenta de usuario, LUEGO la persona (que la referencia mediante su
    # clave externa [user]), en UNA transacción
    # -----------------------------------------------------------------------
    def _add_person(self, d: Descriptor, data: PersonData) -> Person:
        last_name = data.last_name.strip().upper()
        first_name = data.first_name.strip()
        # las reglas de la base de datos dbrdvmedecins2: login = apellido en minúsculas,
        # contraseña = login - salvo que el ADMIN (o el paciente) haya ingresado otros.
        login = (data.login or last_name).lower()
        password = data.password or login

        def work():
            self._check_person_unique(d, first_name, last_name, None)
            self._check_login_free(login)
            account = self.users.add(login, passwords.hash_password(password), f"{first_name} {last_name}", d.role)
            return d.dao.add(data.title, last_name, first_name, account)
        return self._transaction(work)

    # -----------------------------------------------------------------------
    # actualización: la persona Y su cuenta (el nombre mostrado "nombre APELLIDO" debe
    # acompañar el cambio; el login y la contraseña solo cambian si se ingresaron).
    # -----------------------------------------------------------------------
    def _edit_person(self, d: Descriptor, id: int, data: PersonData) -> Person:
        def work():
            person = d.dao.read(id)
            if person is None:
                raise BusinessError(d.not_found_code)
            # bloqueo optimista: si la versión en la base de datos ya no es la del
            # formulario, alguien modificó este registro mientras tanto - se rechaza
            # en lugar de sobrescribir silenciosamente sus cambios
            if data.version is not None and data.version != person.version:
                raise BusinessError(errors.CONCURRENT_UPDATE)
            last_name = data.last_name.strip().upper()
            first_name = data.first_name.strip()
            self._check_person_unique(d, first_name, last_name, id)
            # su cuenta: el nombre mostrado y, si se ingresaron, el login y la
            # contraseña
            account = person.account
            login = data.login.lower() if data.login else account.login
            if login != account.login:
                self._check_login_free(login)
            hash = passwords.hash_password(data.password) if data.password else None
            # los UPDATE, con su bloqueo optimista: si el registro (o la cuenta) fue
            # modificado DESPUÉS de la lectura anterior, no se modifica ninguna fila
            if not d.dao.update(id, person.version, data.title, last_name, first_name):
                raise _StaleVersion()
            if not self.users.update(account.id, account.version, login, f"{first_name} {last_name}", hash):
                raise _StaleVersion()
            # la persona leída de nuevo, con su cuenta: los valores guardados
            return d.dao.read(id)
        return self._transaction(work)

    # -----------------------------------------------------------------------
    # eliminación, en UNA transacción, en el orden impuesto por las claves
    # externas:
    #   1. posible rechazo si quedan citas (médico);
    #   2. lo que referencia a la persona (horarios de un médico, citas de un
    #      cliente);
    #   3. la persona (que referencia su cuenta), y luego su cuenta.
    # -----------------------------------------------------------------------
    def _delete_person(self, d: Descriptor, id: int) -> None:
        def work():
            person = d.dao.read(id)
            if person is None:
                raise BusinessError(d.not_found_code)
            if d.count_appointments is not None and d.count_appointments(id) > 0:
                raise BusinessError(d.has_appointments_code)
            if d.before_delete is not None:
                d.before_delete(id)
            d.dao.delete(id)
            self.users.delete(person.account_id)
        self._transaction(work)

    # rechaza nombres y apellidos ya usados por OTRA persona del mismo tipo
    # (current_id: la persona que se actualiza, que obviamente tiene derecho
    # a conservar su propio nombre y apellido; None en una creación)
    def _check_person_unique(self, d: Descriptor, first_name: str, last_name: str,
                             current_id: int | None) -> None:
        namesake = d.dao.namesake(first_name, last_name)
        if namesake is not None and namesake.id != current_id:
            raise BusinessError(d.already_exists_code)

    def _check_login_free(self, login: str) -> None:
        if self.users.read_by_login(login) is not None:
            raise BusinessError(errors.LOGIN_TAKEN)

    # -----------------------------------------------------------------------
    # ejecuta [work] en una transacción (transaction.atomic, véase el ejemplo 28):
    # si la función termina normalmente, la transacción se confirma (COMMIT);
    # si sale de ella una excepción (incluida BusinessError), se revierte
    # (ROLLBACK): no se escribe nada.
    #
    # Las verificaciones de "login libre" y "nombre + apellido únicos" se hacen ANTES de
    # la escritura, para dar un mensaje claro. Pero dos ADMIN podrían
    # guardar el mismo login (o el mismo médico) al mismo tiempo: en este
    # caso poco frecuente, es una restricción SQL de unicidad la que rechaza la segunda escritura.
    # Del mismo modo, dos actualizaciones simultáneas del mismo registro se resuelven mediante el
    # bloqueo optimista. Por eso estos errores se interceptan ALREDEDOR de la transacción,
    # para traducirlos a BusinessError. Cualquier otro error es una verdadera anomalía:
    # se deja propagar.
    # -----------------------------------------------------------------------
    def _transaction(self, work: Callable):
        try:
            with transaction.atomic():
                return work()
        except IntegrityError as e:
            # str(e): el mensaje de MySQL
            found = CONSTRAINT.search(str(e))
            if found and found.group(1) in CONSTRAINT_ERRORS:
                # from e: la nueva excepción conserva la huella de la que la causó
                raise BusinessError(CONSTRAINT_ERRORS[found.group(1)]) from e
            raise
        except _StaleVersion as e:
            raise BusinessError(errors.CONCURRENT_UPDATE) from e

11.11.7.1. Dependencias y descriptores

  • líneas 62–69: traducción de los errores de la base de datos a errores de negocio (véase “Transacciones”, más abajo);
  • líneas 74–75: una excepción interna, que señala un [UPDATE] sin efecto (el bloqueo optimista);
  • líneas 81–86: los objetos DAO, creados una vez por todas por el constructor;
  • líneas 88–112: los dos descriptores. Las funciones son métodos de los DAO, pasados sin paréntesis (línea 95): son métodos enlazados (bound methods), funciones que conservan una referencia a su objeto, y se llamarán más tarde ([d.count_appointments(id)], línea 286). Un médico que tiene citas no puede eliminarse; sus franjas horarias se eliminan junto con él. Un cliente se elimina junto con sus citas. Los parámetros tienen nombre: se ve de inmediato para qué sirve cada valor.

11.11.7.2. Operaciones de lectura y el calendario

  • líneas 118–146: las lecturas, delegadas a la capa DAO. La fecha actual se calcula aquí (línea 146), no en el DAO: es una regla de negocio (“próximas”);
  • líneas 150–159: la agenda de un médico para un día determinado. Un diccionario de solo lectura (ejemplo 18) asocia el número de cada franja horaria con la cita reservada en esa franja ese día ([a.slot_id]: la clave externa, sin consulta; véanse los modelos); luego, para cada franja horaria del médico, la cita correspondiente, o [None]. Solo dos consultas, sea cual sea el número de franjas horarias: las citas del día y las franjas horarias (más las notas del médico), como se muestra en la consola (“Modo de desarrollo”).

11.11.7.3. Programación de citas

  • Líneas 179–189: programación de una cita en una transacción. La función [work], definida dentro del método, recibe sus parámetros ([day], [slot], [client]): es una clausura (ejemplo 08). Se pasa a [_transaction], que la ejecuta dentro de una transacción;
  • líneas 181–182: no se permiten citas en el pasado;
  • líneas 183–185: el bloqueo “pesimista” sobre el registro del paciente ([SELECT ... FOR UPDATE]; véase la capa DAO). He aquí el porqué. La regla de “una sola cita futura” se verifica mediante un conteo (línea 186) y luego se inserta la cita (línea 188). Si el mismo paciente reserva dos franjas horarias al mismo tiempo (dos pestañas, un doble clic), dos transacciones podrían contar ambas cero citas y luego insertar ambas la cita: ninguna restricción de la base de datos lo impediría, ya que las dos franjas horarias son distintas. El bloqueo sobre la fila del paciente hace que la segunda transacción espere hasta que la primera termine: entonces cuenta una cita y falla. La base de datos no puede hacer cumplir por sí sola esta regla: la hace cumplir la capa de negocio, con la ayuda de la base de datos;
  • líneas 186–187: una sola cita futura por paciente;
  • línea 188: la inserción. Si la franja horaria acaba de ser tomada por otro paciente, es la restricción [unq1_appointments] de la base de datos la que rechaza la inserción, y [_transaction] traduce el error (más adelante);
  • líneas 191–193: cancelación de una cita. [lambda: ...] es una función anónima, reducida a una sola expresión (en este caso, una llamada): el equivalente de una función [def] de tres líneas.

11.11.7.4. Gestión de médicos y pacientes

  • líneas 200–218: los métodos públicos delegan en métodos comunes, con el descriptor correspondiente;
  • líneas 224–237: creación de una persona. El apellido se escribe en mayúsculas ([PELISSIER], la convención de la base de datos) y se eliminan los espacios que rodean la entrada. Las reglas de la base de datos [dbrdvmedecins2]: de forma predeterminada, el login es el nombre en minúsculas y la contraseña es, por defecto, el login ([a or b]: [a] si es “verdadero” (una cadena no vacía), [b] en caso contrario). Dentro de la transacción: las validaciones (verificación de homónimos, login libre), luego la cuenta (con el hash de la contraseña; véase [security/passwords.py]) y después la persona, que hace referencia a la cuenta mediante su clave externa: el orden es fijo;
  • líneas 243–271: modificación de una persona y de su cuenta. La versión del formulario se compara con la versión leída (línea 251): es el primer nivel del bloqueo optimista, que devuelve un mensaje claro. El segundo nivel es el del [UPDATE] (líneas 265–268): si el registro ha sido modificado entre la lectura (línea 245) y la escritura, [UPDATE] no modifica nada, y la excepción [_StaleVersion] revierte toda la transacción (así, la cuenta tampoco se modifica ). El login y la contraseña solo cambian si se han ingresado; el nombre de cuenta que se muestra sigue a la persona;
  • líneas 281–292: la eliminación, en el orden que dictan las claves externas: lo que hace referencia a la persona (sus franjas horarias o citas), la persona y luego su cuenta. [person.account_id] es la clave externa, leída sin consulta;
  • líneas 297–305: las dos verificaciones de unicidad, realizadas antes de la escritura, para garantizar un mensaje claro. Una persona que se está editando tiene derecho a conservar su propio nombre y apellido: [current_id] lo excluye.

11.11.7.5. Transacciones y errores de la base de datos

  • líneas 322–334: toda operación de escritura se ejecuta dentro de una transacción ([transaction.atomic], ejemplo 28): si [work] termina con normalidad, la transacción se confirma ([COMMIT]); si se produce una excepción (incluida una [BusinessError]), se revierte ([ROLLBACK]): no se escribe nada. Así, la capa de negocio determina el alcance de las transacciones: una operación de negocio, una transacción;
  • Líneas 326–332: las verificaciones realizadas antes de escribir no siempre bastan: dos administradores podrían guardar el mismo login al mismo tiempo. En ese caso, una restricción de unicidad de la base de datos rechaza la segunda escritura, y el ORM lanza una [IntegrityError], cuyo mensaje es el de [MySQL]: [(1062, "Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'")]. La expresión regular [CONSTRAINT] (línea 69) extrae el nombre de la restricción ([search] busca la expresión en la cadena; [group(1)] devuelve lo que capturó el primer grupo entre paréntesis; [(?:...)] es un grupo sin captura, y [?] lo hace opcional: [MySQL] 8 antepone el nombre de la tabla al nombre, [MariaDB] no). Por eso el script SQL nombra todas sus restricciones. Una restricción conocida se convierte en la [BusinessError] correspondiente; otra, [IntegrityError], se vuelve a lanzar tal cual ([raise] sin parámetros): se trata de una verdadera anomalía. [raise ... from e] adjunta la excepción original a la nueva (ejemplo 28);
  • Líneas 333–334: un bloqueo optimista fallido produce el error [CONCURRENT_UPDATE]. La excepción [_StaleVersion] se lanza dentro del bloque [atomic] para revertir la transacción, y luego se propaga fuera del bloque.

Las excepciones se capturan fuera del bloque [with transaction.atomic()], no dentro de él: tras un error de la base de datos, la transacción ya no es válida y primero debe revertirse, que es lo que hace la salida del bloque (ejemplo 28).

11.12. Autenticación y seguridad

El paquete [security] abarca todo lo relacionado con la autenticación (¿quién es el usuario?), los permisos (¿tiene el usuario acceso a esta página?) y la protección contra bots. Es la versión completa de los ejemplos 25 a 27.

11.12.1. security/passwords.py

# =========================================================================
# security/passwords.py: el hash de las contraseñas, con el algoritmo bcrypt
# (biblioteca bcrypt), 10 rondas, como los hashes del script SQL.
#
# Un HASH es unidireccional: la contraseña no se puede recuperar a partir
# de él. Para verificar una contraseña ingresada, se le aplica el hash con la "sal" (un
# valor aleatorio) contenida en el hash almacenado, y los dos
# resultados se comparan: eso es lo que hace bcrypt.checkpw.
#
# Los hashes del script SQL comienzan con $2b$; los de las otras versiones de
# la aplicación, que comparten la misma base de datos, con $2y$ (PHP) o $2a$ (Java):
# bcrypt verifica las tres formas.
#
# bcrypt solo toma en cuenta los primeros 72 BYTES de la contraseña (y la
# biblioteca se niega a aplicar el hash a más): por eso los formularios limitan la
# longitud de las contraseñas (véase web/forms.py).
# =========================================================================

import bcrypt

# el número de rondas: el hash cuesta 2^10 cálculos elementales
ROUNDS = 10
MAX_BYTES = 72


def hash_password(password: str) -> str:
    # encode: la cadena a bytes (UTF-8); decode: los bytes a una cadena
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt(ROUNDS)).decode()


def check_password(password: str, hash: str) -> bool:
    data = password.encode()
    if len(data) > MAX_BYTES:
        return False
    return bcrypt.checkpw(data, hash.encode())

Las contraseñas de la base de datos tienen su hash calculado por [bcrypt] (el script SQL mencionado antes), y no por PBKDF2, el algoritmo predeterminado de [Django] (ejemplo 25). La biblioteca [bcrypt] las verifica directamente:

  • líneas 26–28: el hash de una contraseña. [gensalt(10)] genera una sal aleatoria con un costo de 10; [hashpw] calcula el hash, que contiene el algoritmo, el costo y la sal (ejemplo 25). La biblioteca opera con bytes: [encode()] convierte la cadena en bytes ([UTF-8]) y [decode()] realiza la operación inversa;
  • líneas 31–35: la verificación. [checkpw] obtiene el costo y la sal del hash almacenado, calcula con ellos el hash de la contraseña ingresada y compara los resultados (en tiempo constante, ejemplo 23). [bcrypt] solo considera los primeros 72 bytes de una contraseña, y la biblioteca, desde la versión 5, se niega a calcular el hash de más de eso (lanza una excepción): por lo tanto, una contraseña más larga se rechaza de entrada. Los formularios también limitan la longitud de la contraseña (capa web, que se explica más adelante).

[Django] podría haber verificado estos hashes por sí mismo, con su algoritmo [BCryptPasswordHasher] (configuración [PASSWORD_HASHERS]): pero espera hashes con el prefijo [bcrypt$], y la base de datos se comparte con otras versiones de la aplicación, que no reconocen este prefijo.

11.12.2. security/connected_user.py

# =========================================================================
# security/connected_user.py: el usuario conectado, tal como lo describe su token JWT
# (véase el ejemplo 25).
#
# Los claims de nuestros tokens (véase security/auth.py):
#   sub   : el id de la cuenta de usuario (convención JWT: "subject"), como texto
#   login : el login
#   name  : el nombre mostrado ("Marie PELISSIER"), para la barra de navegación
#   role  : ADMIN, DOCTOR o USER
#   iat, exp : fechas de creación y de expiración del token
#
# Este objeto NO proviene de la base de datos: se reconstruye, en cada solicitud, a partir
# del token, cuya firma garantiza el contenido.
# =========================================================================

from dataclasses import dataclass

from models.models import Role


@dataclass(frozen=True)
class ConnectedUser:
    user_id: int
    login: str
    name: str
    role: str

    # el usuario descrito por los claims de un token ya verificado; None si falta un claim
    # o no tiene la forma esperada. @staticmethod: una función almacenada en
    # la clase, que no recibe ni objeto ni clase
    @staticmethod
    def from_claims(claims: dict) -> "ConnectedUser | None":
        role = claims.get("role")
        sub = str(claims.get("sub", ""))
        # Role.values: los valores de la enumeración; isdigit: solo dígitos
        if role not in Role.values or not sub.isdigit() or "login" not in claims or "name" not in claims:
            return None
        return ConnectedUser(int(sub), str(claims["login"]), str(claims["name"]), role)

    @property
    def is_admin(self) -> bool:
        return self.role == Role.ADMIN

    @property
    def is_doctor(self) -> bool:
        return self.role == Role.DOCTOR

    @property
    def is_patient(self) -> bool:
        return self.role == Role.USER

El usuario conectado, tal como lo describe su token (ejemplo 25). Este objeto no proviene de la base de datos: se reconstruye en cada solicitud a partir del token, cuya firma garantiza su contenido.

  • Líneas 31–38: un método estático ([@staticmethod]): un método definido dentro de la clase que no recibe ni un objeto ni una clase como argumento, y se llama [ConnectedUser.from_claims(claims)]. Construye el objeto de usuario a partir de las claims de un token ya verificado. Aunque lo firmemos nosotros, un token se verifica con cuidado: un rol desconocido, un identificador que no es un número o una claim ausente harán que se niegue el acceso al usuario ([None]). [Role.values] es la lista de valores de la enumeración; [isdigit] verifica que una cadena conste únicamente de dígitos. La anotación del tipo devuelto va entre comillas: en este punto la clase aún no está completamente definida;
  • líneas 40–50: tres propiedades para las plantillas (ejemplo 26).

11.12.3. security/auth.py

# =========================================================================
# security/auth.py: la lógica de autenticación:
#   - validate()         : verifica un par login / contraseña;
#   - set_token()        : construye el token JWT de un usuario validado y
#                          lo coloca en una cookie de la respuesta;
#   - user()             : el usuario descrito por un token.
#
# ¿Por dónde viaja el token JWT? En una COOKIE (véase el ejemplo 25): un navegador que
# muestra páginas HTML ordinarias lo presenta así por sí mismo, en cada solicitud.
# Las opciones de esta cookie importan para la seguridad:
#   - HttpOnly: el JavaScript de la página no puede leer la cookie (un script
#     inyectado no podría entonces robar el token);
#   - SameSite=Lax: el navegador NO envía la cookie con un POST proveniente de otro
#     sitio (primera protección contra el llamado ataque CSRF; la segunda es
#     el token anti-CSRF de los formularios);
#   - Secure: en producción (HTTPS), la cookie nunca viaja sin cifrar;
#   - duración: la cookie desaparece al mismo tiempo que expira el token.
# =========================================================================

import time

import jwt
from django.conf import settings
from django.core.exceptions import ImproperlyConfigured

from dao.users import UserDao
from models.models import User

from . import passwords
from .connected_user import ConnectedUser

# el nombre de la cookie que lleva el token
COOKIE = "rdvmedecins_jwt"

# HMAC-SHA256 exige una clave de al menos 256 bits: lo decimos claramente, desde que se
# carga el módulo, en lugar de dejar que la biblioteca falle más adelante
if len(settings.JWT_SECRET) < 32:
    raise ImproperlyConfigured("JWT_SECRET must be at least 32 characters long (see .env).")

_users = UserDao()


# None si el login no existe o si la contraseña es incorrecta
def validate(login: str, password: str) -> User | None:
    user = _users.read_by_login(login)
    if user is None or not passwords.check_password(password, user.password):
        return None
    return user


# -------------------------------------------------------------------------
# el token JWT de [user], colocado en la cookie que lo transporta. El token está
# FIRMADO (HMAC-SHA256) con la clave secreta: el navegador puede leerlo (no está
# cifrado), pero no modificarlo - cualquier modificación invalidaría
# la firma.
# -------------------------------------------------------------------------
def set_token(response, user: User):
    now = int(time.time())
    duration = settings.JWT_DURATION_MINUTES * 60
    claims = {
        "sub": str(user.id),
        "login": user.login,
        "name": user.name,
        "role": user.role,
        "iat": now,
        "exp": now + duration,
    }
    token = jwt.encode(claims, settings.JWT_SECRET, algorithm="HS256")
    response.set_cookie(COOKIE, token, max_age=duration, secure=settings.COOKIE_SECURE,
                        httponly=True, samesite="Lax")
    return response


# borra la cookie del token: la respuesta lleva una cookie del mismo nombre, vacía y ya expirada
def clear_token(response):
    response.delete_cookie(COOKIE, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# el usuario descrito por un token; None si el token está expirado, falsificado o
# malformado. jwt.decode verifica la firma Y la fecha de expiración (claim exp).
# -------------------------------------------------------------------------
def user(token: str) -> ConnectedUser | None:
    try:
        claims = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
    except jwt.InvalidTokenError:
        return None
    return ConnectedUser.from_claims(claims)

El servicio de autenticación del ejemplo 25, con algunas diferencias:

  • Líneas 37–38: la clave de los tokens se verifica al cargar el módulo, es decir, al arrancar la aplicación: si la clave es demasiado corta, el proceso se detiene por completo, con un mensaje de error claro ([ImproperlyConfigured] es la excepción de [Django] para una configuración incorrecta), en lugar de una simple advertencia como la de [PyJWT] (ejemplo 25);
  • líneas 44–48: verificación de un nombre de usuario y una contraseña por la capa DAO (la cuenta, obtenida de la base de datos) y por el módulo de contraseñas. La capa web llama directamente a este módulo: la autenticación es un asunto de seguridad, no una regla de negocio;
  • líneas 57–71: generación del token y almacenamiento en una cookie de la respuesta (ejemplo 25). El identificador de la cuenta ([sub]) se escribe en texto plano: el estándar JWT lo exige. La cookie es [Secure] en producción ([COOKIE_SECURE], véase [config/settings.py]);
  • líneas 75–77: eliminación de la cookie: una cookie con el mismo nombre, vacía y ya vencida (ejemplo 25);
  • líneas 84–89: el usuario se identifica mediante un token, o [None] (ejemplo 25).

11.12.4. security/access.py

# =========================================================================
# security/access.py: LA REGLA DE ACCESO de cada URL.
#
# Las reglas se examinan en orden; se aplica la primera cuyo patrón (una
# expresión regular) coincide con la ruta de la URL:
#   - algunas URL PÚBLICAS: la página de inicio, el login, la elección de idioma, la
#     creación de una cuenta;
#   - URL reservadas a ciertos roles (un conjunto de roles: basta UNO de ellos);
#   - todas las DEMÁS requieren un usuario autenticado (última regla).
# Es la regla "todo está prohibido excepto lo que se permite": una URL agregada
# más tarde, que olvidamos proteger, queda protegida automáticamente.
#
# El middleware AccessControl (véase security/middleware.py) aplica estas reglas: un
# visitante anónimo rechazado es enviado a la página de login; un
# usuario autenticado sin el rol requerido obtiene una página de error 403.
# =========================================================================

import re

from models.models import Role

# dos valores especiales en lugar de un conjunto de roles
PUBLIC = "PUBLIC"
AUTHENTICATED = "AUTHENTICATED"

# re.compile: la expresión regular, analizada una vez por todas
RULES = [
    (re.compile(r"^/$"), PUBLIC),
    (re.compile(r"^/(login|logout)$"), PUBLIC),
    (re.compile(r"^/language/"), PUBLIC),
    (re.compile(r"^/register"), PUBLIC),
    # un paciente cancela SU cita desde "Mi área", no desde la agenda
    (re.compile(r"^/schedule/cancel$"), {Role.ADMIN, Role.DOCTOR}),
    (re.compile(r"^/(doctors|clients)"), {Role.ADMIN}),
    (re.compile(r"^/my-"), {Role.USER}),
    (re.compile(r"^/"), AUTHENTICATED),
]


# la regla de la ruta [path]: PUBLIC, AUTHENTICATED o un conjunto de roles
def rule(path: str):
    for pattern, requirement in RULES:
        if pattern.match(path):
            return requirement
    return AUTHENTICATED

Las reglas de acceso de la aplicación, agrupadas en una sola lista. El ejemplo 26 protegía cada vista con un decorador; aquí la protección está centralizada, como en las reglas [access_control] de [Symfony]:

  • líneas 27–37: cada regla asocia un patrón (una expresión regular, compilada una vez por todas con [re.compile]) con un requisito: [PUBLIC], [AUTHENTICATED], o un conjunto de roles, cualquiera de los cuales basta. [^] marca el inicio de la ruta, [$] marca su final; [(login|logout)]: una u otra. Las URL públicas son la página de inicio, el inicio de sesión, la selección de idioma y la creación de cuentas. Siguen las URL reservadas a ciertos roles: la cancelación desde el calendario (un paciente cancela desde “My area”), la gestión de médicos y clientes, y la cuenta del paciente. La última regla, [^/], se aplica a todas las demás URL y exige un usuario autenticado;
  • líneas 41–45: la regla de la ruta: se aplica la primera que coincide ([match]: la expresión reconocida al comienzo de la cadena).

Esta es la regla de “todo está prohibido excepto lo que está permitido”: una URL agregada más tarde, cuya protección podría haberse olvidado, queda protegida automáticamente. El error opuesto (una URL pública a la que se olvidó hacer pública) se nota de inmediato; el error de una página protegida olvidada es mucho menos evidente.

11.12.5. security/middleware.py

# =========================================================================
# security/middleware.py: los dos middlewares de seguridad (véanse los ejemplos 24 a 26).
#
#   1. Autenticación, ANTES del enrutamiento: ¿quién es el usuario? A partir del
#      token JWT de su cookie. No rechaza nada por sí misma: un token ausente o
#      inválido deja al visitante como ANÓNIMO (request.user es None); la
#      cookie de un token inválido se borra de la respuesta;
#   2. AccessControl, DESPUÉS del enrutamiento (process_view): ¿tiene el usuario permiso
#      para acceder a esta URL? Las reglas están en security/access.py. Una URL
#      que no tiene ruta no llega hasta aquí: obtiene una página 404.
# =========================================================================

from django.contrib import messages
from django.core.exceptions import PermissionDenied
from django.shortcuts import redirect
from django.utils.translation import gettext as _

from . import access, auth


class Authentication:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        token = request.COOKIES.get(auth.COOKIE, "")
        request.user = auth.user(token) if token else None
        response = self.get_response(request)
        # un token inválido (expirado, falsificado): se borra la cookie, en la respuesta
        # sea cual sea - salvo que la solicitud acabe de establecer uno nuevo (un
        # login exitoso)
        if token and request.user is None and auth.COOKIE not in response.cookies:
            auth.clear_token(response)
        return response


class AccessControl:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    def process_view(self, request, view_func, view_args, view_kwargs):
        # path_info: la ruta de la URL, sin sus parámetros
        requirement = access.rule(request.path_info)
        if requirement == access.PUBLIC:
            return None
        user = request.user
        if user is None:
            # un visitante anónimo: directo a la página de login. Si tenía una
            # cookie de token, significa que su token ya no es válido (expirado,
            # falsificado): su sesión ha expirado, se lo decimos
            if auth.COOKIE in request.COOKIES:
                messages.error(request, _("Your session has expired: please log in again."))
            return redirect("login")
        if requirement != access.AUTHENTICATED and user.role not in requirement:
            # autenticado, pero sin el rol requerido: error 403 (vista handler403, véase config/urls.py)
            raise PermissionDenied("insufficient role")
        return None

Los dos componentes de middleware de seguridad:

  • líneas 21–34: la autenticación (ejemplo 25), antes del enrutamiento. No rechaza nada: un token ausente o inválido deja al visitante como anónimo. Elimina en la respuesta la cookie asociada a un token inválido, sea cual sea esa respuesta, salvo que la respuesta establezca una nueva (un inicio de sesión exitoso): [response.cookies] es el diccionario de cookies que establece la respuesta;
  • líneas 37–60: el control de acceso, después del enrutamiento (su método [process_view], ejemplo 24). Por lo tanto, una URL que no tiene ruta no llega hasta aquí: recibe directamente una página 404, sin que se pida al visitante iniciar sesión. [request.path_info] es la ruta de la URL, sin sus parámetros. Un visitante anónimo al que se le niega el acceso es enviado a la página de inicio de sesión; si tenía una cookie de token, significa que su token ya no es válido: un mensaje emergente le informa que su sesión ha expirado (véase la captura de pantalla titulada “Fin de la sesión”). Un usuario autenticado que no tiene el rol requerido provoca [PermissionDenied]: como la excepción se lanza en [process_view], y no en la vista, [Django] la transforma por sí mismo en una respuesta mediante la vista [handler403] de la aplicación (ejemplo 24), tanto en modo de depuración como en producción.

El mensaje se traduce con [gettext] (línea 16), y no con [gettext_lazy]: se traduce durante la solicitud, en su idioma; la traducción diferida solo es útil para el texto definido cuando se carga un módulo.

11.12.6. security/errors.py

1
2
3
4
5
6
7
8
# security/errors.py: el token es válido, pero la cuenta que designa ya no
# existe: fue eliminada desde el login (por el propio paciente en otra
# pestaña, o por el ADMIN). Este caso se trata como una sesión expirada: el
# middleware ErrorPage borra la cookie y redirige a la página de login.


class InvalidSession(Exception):
    pass

Un caso especial: el token es válido, pero la cuenta a la que hace referencia ya no existe (el paciente la eliminó en otra pestaña, o la eliminó el administrador). Las vistas que requieren la cuenta lanzan entonces esta excepción, que el middleware [ErrorPage] trata como una sesión expirada (véase más adelante).

11.12.7. security/captchas.py y captcha_drawing.py

# =========================================================================
# security/captchas.py: un CAPTCHA ("prueba para distinguir a un humano de un robot")
# generado por el propio servidor, sin ningún servicio externo (véase el ejemplo 27).
#
# Cómo funciona:
#   1. generate() sortea un texto aleatorio, genera una imagen con él y guarda la respuesta
#      correcta EN EL CACHÉ del servidor, bajo un identificador aleatorio;
#   2. la página muestra la imagen y coloca el identificador en un campo oculto del
#      formulario (la respuesta en sí nunca sale del servidor);
#   3. verify(id, input) compara lo ingresado con la respuesta esperada y luego OLVIDA
#      este captcha: cada imagen se usa una sola vez, un robot no puede reenviar
#      una respuesta ya encontrada.
#
# ¿Por qué el caché, y no una simple variable del módulo? Porque un servidor de
# producción inicia VARIOS procesos (véase README.md), que no comparten su
# memoria: la solicitud que verifica el captcha no necesariamente la atiende el
# proceso que lo generó. El caché de la aplicación (archivos, véase
# config/settings.py) sí es compartido por todos.
# =========================================================================

import secrets
from dataclasses import dataclass

from django.core.cache import cache

from . import captcha_drawing

# duración de validez de una imagen, en segundos: 10 minutos para llenar el formulario
LIFETIME = 600


# un captcha: su identificador, para colocar en el campo oculto [captcha_id] del
# formulario, y su imagen (SVG), para insertar tal cual en la página
@dataclass(frozen=True)
class Captcha:
    id: str
    svg: str


def generate() -> Captcha:
    text = captcha_drawing.random_text(5)        # 5 caracteres
    id = secrets.token_hex(12)                     # un identificador imposible de adivinar
    # el caché olvidará la respuesta por sí mismo después de 10 minutos
    cache.set(f"captcha.{id}", text, LIFETIME)
    return Captcha(id, captcha_drawing.svg(text))


# verdadero si [answer] es la respuesta correcta al captcha [id] (sin distinguir
# mayúsculas de minúsculas). El captcha se consume en todos los casos.
def verify(id: str, answer: str) -> bool:
    # el identificador proviene del navegador: 24 dígitos hexadecimales, o nada
    if len(id) != 24 or any(c not in "0123456789abcdef" for c in id) or not answer:
        return False
    expected = cache.get(f"captcha.{id}")
    # delete devuelve True si el elemento existía: si dos solicitudes presentan el mismo
    # captcha al mismo tiempo, solo una lo elimina realmente - la otra falla
    if expected is None or not cache.delete(f"captcha.{id}"):
        return False
    return expected.casefold() == answer.strip().casefold()

El servicio de CAPTCHA del ejemplo 27, con dos precauciones adicionales:

  • líneas 51–52: el identificador proviene del navegador; verificamos que conste de 24 dígitos hexadecimales (los de [token_hex(12)]) antes de usarlo como clave del caché. [any] devuelve [True] si alguno de los elementos producidos por la expresión generadora es verdadero;
  • líneas 53–56: [cache.delete] devuelve [True] si el elemento existía. Si dos solicitudes presentan el mismo CAPTCHA al mismo tiempo, solo una lo elimina realmente; la otra falla. Una imagen se usa una sola vez.

El comentario del archivo (líneas 17–22) explica por qué los CAPTCHA se almacenan en el caché (un conjunto de archivos compartido por todos los procesos del servidor) y no en una variable de módulo. El archivo [security/captcha_drawing.py] es el del ejemplo 27, con un comentario de encabezado más extenso: cada carácter se dibuja con líneas, nunca se escribe como texto, de lo contrario un bot solo tendría que leer el código fuente de la imagen.

11.12.8. security/limiter.py

# =========================================================================
# security/limiter.py: segunda barrera contra los robots (la primera es el
# captcha): los intentos se CUENTAN y, al superar un umbral, se BLOQUEAN durante
# un tiempo (véase el ejemplo 27).
#
#   - login: tras LOGIN_MAX_FAILURES fallos (captcha incorrecto o contraseña
#     incorrecta) para el mismo login desde la misma dirección IP, este par se bloquea
#     hasta el final de una ventana de LOGIN_BLOCK_MINUTES minutos, contada desde
#     el primer fallo. La misma dirección IP también se bloquea si acumula
#     LOGIN_MAX_FAILURES_IP fallos, con todos los logins juntos (un robot que prueba
#     miles de logins distintos);
#   - creación de cuentas: como máximo REGISTRATION_MAX_PER_HOUR cuentas creadas por hora
#     desde la misma dirección IP.
#
# Atención en un aula: todas las computadoras suelen salir a Internet por la
# MISMA dirección IP. Por eso el bloqueo del login se aplica primero al
# par (IP, login) - un estudiante que se equivoca al escribir su contraseña no bloquea a sus
# compañeros - y por qué los umbrales son configurables (archivo .env).
#
# Cada contador se almacena en el caché (véase security/captchas.py), junto con el final
# de su ventana: {"count": 3, "end": 1790531419.2}.
# =========================================================================

import hashlib
import math
import time

from django.conf import settings
from django.core.cache import cache


# ---------------------------------------------------------------- login
# cantidad de minutos de bloqueo restantes (0 = el intento está permitido)
def login_block_minutes(ip: str, login: str) -> int:
    return max(_remaining_minutes(_login_key(ip, login), settings.LOGIN_MAX_FAILURES),
               _remaining_minutes(f"login_ip.{ip}", settings.LOGIN_MAX_FAILURES_IP))


# un fallo más; el primero abre una ventana de LOGIN_BLOCK_MINUTES minutos,
# al final de la cual el contador vuelve a empezar desde cero
def login_failure(ip: str, login: str) -> None:
    duration = settings.LOGIN_BLOCK_MINUTES * 60
    _count(_login_key(ip, login), duration)
    _count(f"login_ip.{ip}", duration)


# un login exitoso reinicia el contador de ESTE login
def login_success(ip: str, login: str) -> None:
    cache.delete(_login_key(ip, login))


# ---------------------------------------------------------------- registro
def registration_block_minutes(ip: str) -> int:
    return _remaining_minutes(f"registration.{ip}", settings.REGISTRATION_MAX_PER_HOUR)


def registration_success(ip: str) -> None:
    _count(f"registration.{ip}", 3600)


# ---------------------------------------------------------------- mecánica común
# la clave del par (IP, login). El login proviene del navegador: puede contener
# cualquier cosa (espacios...). Su huella SHA-256, formada por 64 dígitos
# hexadecimales, da una clave de caché siempre válida
def _login_key(ip: str, login: str) -> str:
    fingerprint = hashlib.sha256(f"{ip}|{login.strip().lower()}".encode()).hexdigest()
    return f"login.{fingerprint}"


# los minutos que faltan para el final de la ventana si el contador alcanzó el
# límite, 0 en caso contrario; los segundos se redondean HACIA ARRIBA al minuto (ceil):
# 30 s -> "1 minuto"
def _remaining_minutes(key: str, limit: int) -> int:
    state = cache.get(key)
    if state is None or state["count"] < limit:
        return 0
    return max(1, math.ceil((state["end"] - time.time()) / 60))


# un intento más en la ventana actual (o en una nueva ventana de
# [duration] segundos). El caché olvida el contador al final de la ventana (timeout).
# La lectura y luego la escritura no son ATÓMICAS: dos intentos simultáneos
# podrían contar como uno solo. Para un contador de fallos, no importa
def _count(key: str, duration: int) -> None:
    state = cache.get(key) or {"count": 0, "end": time.time() + duration}
    state["count"] += 1
    cache.set(key, state, timeout=max(1, math.ceil(state["end"] - time.time())))

El límite de intentos del ejemplo 27, más refinado:

  • líneas 34–49: el inicio de sesión. Los intentos fallidos se cuentan por cada par (dirección IP, nombre de usuario): cinco intentos fallidos (configuración [LOGIN_MAX_FAILURES]) bloquean ese nombre de usuario desde esa dirección durante quince minutos, a partir del primer intento fallido. En un aula, donde todas las computadoras suelen acceder a Internet con la misma dirección IP, un estudiante que ingresa mal la contraseña no bloquea a sus compañeros. Sin embargo, la misma dirección también se bloquea si acumula 25 intentos fallidos entre todos los logins: es el caso de un bot que prueba miles de logins distintos. Un inicio de sesión exitoso borra los intentos fallidos de ese login;
  • líneas 53–58: la creación de cuentas: un máximo de diez cuentas por hora por dirección IP;
  • líneas 65–67: la clave del par (IP, login). El login proviene del navegador: puede contener cualquier cosa. Su huella SHA-256 ([hashlib.sha256], de la biblioteca estándar), compuesta por 64 dígitos hexadecimales, produce una clave de caché siempre válida y de longitud fija;
  • líneas 73–77: los minutos de bloqueo restantes, redondeados al minuto siguiente ([math.ceil]: 30 segundos equivalen a “1 minuto”);
  • líneas 84–87: el contador, dentro de una ventana fija (ejemplo 27). [cache.get(key) or {...}]: el estado actual, o un estado nuevo. El comentario del código reconoce la debilidad del ejemplo 27 (dos fallos simultáneos pueden contar como uno solo); para un contador de fallos, esto no es un problema grave.

11.12.9. security/registration_pass.py

# =========================================================================
# security/registration_pass.py: el "pase" de creación de cuentas.
#
# Para abrir la página "Crear una cuenta de paciente", primero se debe haber escrito el captcha
# de la página de autenticación (véase web/views/registration.py, POST
# /register/access). Entonces el servidor emite un pase:
#   - un identificador aleatorio, almacenado en una cookie HttpOnly;
#   - válido por 15 minutos (el tiempo para llenar el formulario, incluso después de varios
#     intentos por errores de ingreso);
#   - consumido en cuanto se crea una cuenta: UN captcha resuelto = UNA cuenta como máximo.
#     Un robot no puede crear cuentas en serie.
#
# Sin un pase válido, GET y POST /register redirigen a la página de
# autenticación (véase el decorador @registration_pass_required): escribir
# directamente la URL /register no evita el captcha.
#
# Como los captchas, los pases viven en el caché.
# =========================================================================

import secrets
from functools import wraps

from django.conf import settings
from django.contrib import messages
from django.core.cache import cache
from django.shortcuts import redirect
from django.utils.translation import gettext as _

COOKIE = "rdvmedecins_registration"
# el navegador envía la cookie solo a las direcciones /register...
PATH = "/register"
# duración de un pase, en minutos
LIFETIME = 15


# emite un nuevo pase, en una cookie de la respuesta
def issue(response):
    id = secrets.token_hex(12)
    cache.set(f"pass.{id}", True, LIFETIME * 60)
    response.set_cookie(COOKIE, id, max_age=LIFETIME * 60, path=PATH,
                        secure=settings.COOKIE_SECURE, httponly=True, samesite="Lax")
    return response


# verdadero si [id] es un pase existente y no expirado
def is_valid(id: str | None) -> bool:
    return bool(id) and id.isalnum() and cache.get(f"pass.{id}") is not None


# el pase ya se usó: se olvida...
def consume(id: str | None) -> None:
    if id and id.isalnum():
        cache.delete(f"pass.{id}")


# ... y su cookie se borra mediante una cookie del mismo nombre y la misma ruta, ya expirada
def clear_cookie(response):
    response.delete_cookie(COOKIE, path=PATH, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# @registration_pass_required: un decorador (véase el ejemplo 26), colocado en las vistas que
# exigen un pase (GET y POST /register). Sin un pase válido,
# no se llama a la vista: se vuelve a la página de autenticación, con un mensaje
# -------------------------------------------------------------------------
def registration_pass_required(view):
    @wraps(view)
    def wrapper(request, *args, **kwargs):
        if not is_valid(request.COOKIES.get(COOKIE)):
            messages.error(request, _("To create an account, first type the characters shown in the image "
                                      "correctly, then click \"Create a patient account\"."))
            return redirect("login")
        return view(request, *args, **kwargs)
    return wrapper

El token de creación de cuentas. Para crear una cuenta, primero hay que ingresar el CAPTCHA de la página de inicio de sesión (el botón “Create a patient account”): el servidor emite entonces un token, un identificador aleatorio almacenado en el caché y en una cookie. Sin un pase, la página de creación de cuentas redirige a la página de inicio de sesión: escribir la URL [/register] directamente no evita el CAPTCHA; y un pase solo sirve para crear una cuenta: un bot no puede crear cuentas en masa.

  • líneas 29–33: el navegador envía la cookie solo a las direcciones que comienzan con [/register] (parámetro de cookie [path]): no viaja con las demás solicitudes;
  • líneas 37–42: la cookie se emite por quince minutos: tiempo suficiente para completar el formulario, incluso si hay que intentarlo varias veces tras cometer errores de ingreso;
  • líneas 46–59: verificación, uso y eliminación de la cookie (que debe tener la misma ruta que la cookie por eliminar). [isalnum] verifica que el identificador conste únicamente de letras y números;
  • líneas 67–75: el decorador [@registration_pass_required] (ejemplo 26), aplicado a la vista de creación de cuentas.

11.13. La capa web: servicios compartidos

La carpeta [web] contiene la aplicación de [Django] de la capa web (declarada en [INSTALLED_APPS]; véase [config/settings.py]; su archivo [web/apps.py] contiene solo su nombre). Reúne las rutas, las vistas, los formularios y lo que todas las vistas tienen en común: de eso trata esta sección.

11.13.1. web/application.py

# =========================================================================
# web/application.py: el caché / fachada de la capa de negocio (el equivalente de la
# clase [ApplicationModel] de las otras versiones de la aplicación): las listas de
# médicos y clientes se leen una vez de la base de datos y luego se sirven desde el caché.
#
# ¿Por qué el CACHE de Django, y no simplemente un atributo de este objeto? Un
# proceso de Python sí conserva sus objetos de una solicitud a otra (véase el ejemplo 20);
# pero un servidor de producción inicia VARIOS procesos, cada uno de los cuales tendría SU
# copia de las listas: el ADMIN que agrega un médico solo actualizaría la del
# proceso que atendió su solicitud. El caché de la aplicación (archivos, véase
# config/settings.py) sí es compartido por todos los procesos.
#
# Estas listas pueden CAMBIAR (el ADMIN agrega, actualiza y elimina médicos y
# clientes): por eso cada escritura pasa por esta fachada, que OLVIDA la lista
# afectada justo después; la siguiente solicitud que la necesite la lee de nuevo de la base de datos. Ese es
# todo el sentido de un ÚNICO punto de entrada a la capa de negocio: la regla
# "escritura => actualización del caché" se escribe solo aquí.
# =========================================================================

from datetime import date
from functools import cache as once

from django.core.cache import cache

from domain.schedule import DoctorDaySchedule
from business.person_data import PersonData
from business.provider import business
from business.business import Business
from models.models import Appointment, Client, Doctor, Slot

DOCTORS = "rdvmedecins.doctors"
CLIENTS = "rdvmedecins.clients"


# mismo contrato que la capa de negocio
class ApplicationModel(Business):
    def __init__(self):
        self.business = business()

    # ------------------------------------------------ lecturas desde el caché
    # get_or_set(key, function, timeout): el valor del caché si existe; de lo contrario,
    # se llama a la función y su resultado se almacena en el caché (timeout=None:
    # sin límite de tiempo) antes de devolverse. Los objetos se almacenan allí serializados
    # (módulo pickle): cada solicitud que los lee obtiene copias de ellos
    def get_all_doctors(self) -> list[Doctor]:
        return cache.get_or_set(DOCTORS, self.business.get_all_doctors, timeout=None)

    def get_all_clients(self) -> list[Client]:
        return cache.get_or_set(CLIENTS, self.business.get_all_clients, timeout=None)

    # el médico cuya cuenta de usuario es [user_id] - se usa para preseleccionar,
    # en el caso de un médico conectado, su propia agenda
    def get_doctor_by_user_id(self, user_id: int) -> Doctor | None:
        return next((d for d in self.get_all_doctors() if d.account_id == user_id), None)

    # ------------------------------------------------ delegaciones simples
    def get_all_slots(self, doctor_id: int) -> list[Slot]:
        return self.business.get_all_slots(doctor_id)

    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return self.business.get_doctor_day_appointments(doctor_id, day)

    def get_client_by_id(self, id: int) -> Client | None:
        return self.business.get_client_by_id(id)

    def get_doctor_by_id(self, id: int) -> Doctor | None:
        return self.business.get_doctor_by_id(id)

    def get_appointment_by_id(self, id: int) -> Appointment | None:
        return self.business.get_appointment_by_id(id)

    def get_slot_by_id(self, id: int) -> Slot | None:
        return self.business.get_slot_by_id(id)

    def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
        return self.business.get_doctor_day_schedule(doctor_id, day)

    # aquí no hay caché: lo que cuenta son los datos más recientes (un paciente que
    # acaba de actualizar o eliminar su cuenta)
    def get_client_by_user_id(self, user_id: int) -> Client | None:
        return self.business.get_client_by_user_id(user_id)

    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
        return self.business.get_client_upcoming_appointments(client_id)

    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
        return self.business.add_appointment(day, slot, client)

    def delete_appointment(self, appointment: Appointment) -> None:
        self.business.delete_appointment(appointment)

    # ------------------------------------------------ escrituras => caché olvidado
    # (delete: el elemento se elimina del caché)
    def add_doctor(self, data: PersonData) -> Doctor:
        doctor = self.business.add_doctor(data)
        cache.delete(DOCTORS)
        return doctor

    def edit_doctor(self, id: int, data: PersonData) -> Doctor:
        doctor = self.business.edit_doctor(id, data)
        cache.delete(DOCTORS)
        return doctor

    def delete_doctor(self, id: int) -> None:
        self.business.delete_doctor(id)
        cache.delete(DOCTORS)

    def add_client(self, data: PersonData) -> Client:
        client = self.business.add_client(data)
        cache.delete(CLIENTS)
        return client

    def edit_client(self, id: int, data: PersonData) -> Client:
        client = self.business.edit_client(id, data)
        cache.delete(CLIENTS)
        return client

    def delete_client(self, id: int) -> None:
        self.business.delete_client(id)
        cache.delete(CLIENTS)


# el proveedor de la fachada: un único objeto compartido (véase business/provider.py)
@once
def application() -> ApplicationModel:
    return ApplicationModel()

Todas las versiones de la aplicación tienen una clase [ApplicationModel]: un punto de entrada único de la capa web hacia la capa de negocio, que mantiene en memoria las listas de médicos y clientes. Casi todas las páginas solicitan estas listas (la lista desplegable de médicos del calendario, la lista de pacientes de la ventana de reserva, las páginas de administración), y rara vez cambian.

Un proceso de [Python] conserva sus objetos de una solicitud a la siguiente (ejemplo 20): por lo tanto, la versión [Flask] simplemente almacenaba estas listas en los atributos de un único objeto. El comentario de encabezado explica por qué esta versión las almacena en cambio en el caché de [Django] (ejemplo 20): un servidor de producción ejecuta varios procesos, y cada uno tendría su propia copia de las listas.

  • línea 36: la clase hereda el contrato [Business], igual que [BusinessService]: las vistas llaman a los mismos métodos, sin importar qué clase los atienda;
  • Líneas 45–49: [get_or_set(key, function, timeout)] devuelve el valor almacenado con esta clave; si no existe, llama a la función (aquí, un método enlazado de la capa de negocio, pasado sin paréntesis, que lee la lista de la base de datos), almacena su resultado en el caché de forma indefinida ([timeout=None]) y lo devuelve. La primera solicitud que necesita la lista la lee de la base de datos; las siguientes la encuentran en el caché. El caché almacena la lista serializada por el módulo [pickle] (ejemplo 20) y la reconstruye al recuperarla, junto con las relaciones ya cargadas: la cuenta de cada persona, obtenida mediante la combinación [select_related("account")] de la capa DAO. Los objetos reconstruidos son copias: se usan para mostrar, nunca para escribir (la capa de negocio siempre vuelve a leer de la base de datos lo que modifica);
  • líneas 53–54: el médico asociado a una cuenta, obtenido de la lista en caché. [next(generator, None)] devuelve el primer elemento producido por la expresión generadora, o [None] si no hay ninguno (ejemplo 06);
  • Líneas 57–90: los demás métodos del contrato simplemente delegan en la capa de negocio. El cliente de una cuenta ([get_client_by_user_id]) siempre se obtiene de la base de datos, no del caché: lo que importa son los datos más recientes (un paciente que acaba de modificar o eliminar su cuenta);
  • Líneas 94–120: las actualizaciones. Cada operación de escritura de un médico o cliente borra la lista correspondiente ([delete]): la siguiente consulta que la necesite la volverá a leer de la base de datos. Este es todo el sentido de un punto de entrada único: la regla “una escritura actualiza el caché” se implementa solo aquí. Si la escritura falla (una [BusinessError]), la excepción sale del método antes del [delete]: la lista no se sobrescribe; no ha cambiado. Una aplicación que escribiera en la base de datos por otra vía (otro programa, otra versión de la aplicación que use la misma base de datos) dejaría el caché desactualizado: en ese caso, bastaría con borrar la carpeta [var/cache];
  • Líneas 124–126: el proveedor de la fachada, siguiendo el modelo del proveedor de la capa de negocio: un único objeto, creado en la primera solicitud. [functools.cache], importado con el nombre [once], almacena el resultado de una función (ejemplo 06): la función [application()] se ejecuta una sola vez y luego devuelve siempre el mismo objeto.

11.13.2. web/utils.py

# =========================================================================
# web/utils.py: pequeñas funciones utilitarias de la capa web:
#   - fechas: "aaaa-mm-dd", días "Wednesday 23 September 2026";
#   - entrada: lectura de un entero positivo, de una fecha, enviados por el navegador;
#   - usuario: el usuario conectado y su paciente (modelo Client).
# =========================================================================

import re
from datetime import date, datetime

from django.utils import dateformat

from models.models import Client
from security.errors import InvalidSession
from security.connected_user import ConnectedUser

from .application import application


# ----------------------------------------------------------------- fechas
# la fecha, si [text] es una fecha que existe en el formato aaaa-mm-dd; None en caso contrario.
# strptime rechaza fechas que no existen ("2026-02-30")
def valid_date(text: str | None) -> date | None:
    if text is None or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", text):
        return None
    try:
        return datetime.strptime(text, "%Y-%m-%d").date()
    except ValueError:
        return None


# "2026-09-23"
def iso(day: date) -> str:
    return day.isoformat()


# "Wednesday 23 September 2026" / "mercredi 23 septembre 2026", en el idioma
# activo (véase web/middleware.py). dateformat.format da formato a una fecha como el
# filtro date de las plantillas: l el día de la semana completo, j el día,
# F el mes completo, Y el año; los nombres los traduce Django
def format_day(day: date) -> str:
    return dateformat.format(day, "l j F Y")


# ----------------------------------------------------------------- entrada
# "3" -> 3; "", "abc", "-2", "+2", None -> None
def positive_integer(value: str | None) -> int | None:
    if value is None or not re.fullmatch(r"\d{1,9}", value):
        return None
    n = int(value)
    return n if n > 0 else None


# ----------------------------------------------------------------- usuario
# el usuario conectado. Las vistas protegidas solo se llaman si existe (véase
# security/middleware.py); por precaución, su ausencia se trata como una
# sesión expirada
def user(request) -> ConnectedUser:
    if request.user is None:
        raise InvalidSession()
    return request.user


# -------------------------------------------------------------------------
# El paciente (modelo Client) que corresponde al usuario conectado.
#
# El token JWT solo contiene el id de la CUENTA (users.id). Para un rol USER, el
# cliente correspondiente se encuentra gracias a la columna clients.user.
#
# Si no hay ninguno, la cuenta fue eliminada desde el login mientras
# su token sigue siendo válido: se trata como una sesión expirada.
# -------------------------------------------------------------------------
def connected_patient(request) -> Client:
    client = application().get_client_by_user_id(user(request).user_id)
    if client is None:
        raise InvalidSession()
    return client


# la dirección IP del cliente
def ip(request) -> str:
    return request.META.get("REMOTE_ADDR", "")

Algunas funciones de utilidad que todas las vistas necesitan:

  • Líneas 23–29: la fecha de un parámetro [yyyy-mm-dd] o [None]. Dos verificaciones: el formato (una expresión regular; [fullmatch] exige que toda la cadena coincida) y luego la existencia de la fecha: [strptime] lanza una [ValueError] para el 30 de febrero;
  • líneas 41–42: “Wednesday 23 September 2026” o “mercredi 23 septembre 2026”, según el idioma de la solicitud. [dateformat.format] da formato a una fecha como el filtro [date] de las plantillas (ejemplo 16), con los mismos códigos; los nombres de los días y de los meses los traduce [Django] mismo, en el idioma activo;
  • líneas 47–51: un parámetro de consulta es una cadena, o [None]. Solo se aceptan dígitos (hasta nueve: una cantidad razonable que la base de datos acepta), y el número debe ser estrictamente positivo;
  • líneas 58–61: el usuario conectado, determinado por el middleware [Authentication]. Las vistas protegidas solo se llaman para un usuario autenticado (control de acceso), pero la ausencia de usuario se trata igualmente como una sesión expirada;
  • líneas 73–77: el paciente ([Client]) asociado al usuario conectado. El token contiene solo el identificador de la cuenta; el cliente se identifica por la columna [clients.user]. Si no existe, la cuenta ha sido eliminada desde que el usuario inició sesión: [InvalidSession] (el middleware [ErrorPage], que se explica más adelante);
  • líneas 81–82: la dirección (IP) del cliente para el limitador de intentos. [REMOTE_ADDR] es la dirección de la máquina que estableció la conexión. Detrás de un proxy inverso (véase “Un servidor de producción”), esta sería siempre la dirección del proxy: habría que leer entonces el encabezado que este agrega ([X-Forwarded-For]), y solo el que él agrega, ya que el navegador puede enviar cualquier encabezado.

11.13.3. web/contexts.py

# =========================================================================
# web/contexts.py: un procesador de contexto (véase el ejemplo 15): las variables que
# necesitan TODAS las páginas:
#   - user: el usuario conectado (o None), para la barra de navegación;
#   - menu: las entradas del menú de la barra de navegación, que dependen del rol.
#
# El menú se calcula AQUÍ, en Python, y no en la plantilla: "Médicos" y
# "Pacientes" solo aparecen para el ADMIN. Es solo una comodidad de visualización: la
# protección real son las reglas de acceso (un USER que escribe /doctors a
# mano obtiene una página 403).
# =========================================================================

from dataclasses import dataclass

from django.urls import reverse
from django.utils.translation import gettext_lazy as _

from security import auth


# una entrada de menú: su URL, su etiqueta y si es la de la página actual
@dataclass(frozen=True)
class MenuEntry:
    url: str
    label: str
    active: bool


def user(request):
    # el usuario establecido por el middleware de Authentication. Por precaución, si
    # falta (una página de error debida a un error ocurrido antes de este middleware), se
    # lee directamente del token, para que la barra de navegación esté completa
    connected = getattr(request, "user", None)
    if connected is None and request.COOKIES.get(auth.COOKIE):
        connected = auth.user(request.COOKIES[auth.COOKIE])
    return {"user": connected, "menu": menu(request, connected)}


# las entradas del menú: (nombre de la ruta, etiqueta, prefijos de las rutas para
# las cuales la entrada está activa)
def menu(request, connected):
    if connected is None:
        return []
    entries = []
    if connected.is_patient:
        # activa para /my-area Y /my-account
        entries.append(("area", _("My area"), ["/my-"]))
    entries.append(("schedule", _("Schedule"), ["/schedule"]))
    if connected.is_admin:
        entries.append(("doctors_list", _("Doctors"), ["/doctors"]))
        entries.append(("clients_list", _("Patients"), ["/clients"]))
    # any: verdadero si uno de los prefijos coincide
    return [MenuEntry(reverse(route), label, any(request.path.startswith(p) for p in prefixes))
            for route, label, prefixes in entries]

Un procesador de contexto (Ejemplo 15), declarado en [config/settings.py]: las variables que necesitan todas las páginas, dentro del contexto de todas las plantillas:

  • [user]: el usuario conectado, o [None], para la barra de navegación. Normalmente es el del middleware [Authentication]; [getattr(object, name, default)] lee un atributo o devuelve el valor predeterminado si no existe. Por precaución, si falta, el usuario se lee directamente del token (líneas 34–35);
  • [menu]: las entradas del menú de la barra de navegación, que dependen del rol (líneas 41–54). Cada entrada es un objeto [MenuEntry] (una clase de datos, líneas 22–26): la URL (generada por [reverse], ejemplo 04), la etiqueta traducida y el indicador de entrada activa (la de la página mostrada actualmente), que la plantilla resalta. La entrada [My area] está activa para todas las URL que comienzan con [/my-]: [/my-area] y [/my-account].

El menú se calcula en [Python], no en la plantilla (no hay lógica en las plantillas; más adelante se profundiza en esto). Ocultar las entradas “Médicos” y “Pacientes” es solo una comodidad de visualización: la protección real proviene de las reglas de acceso.

11.13.4. web/templatetags/rdv.py

# =========================================================================
# web/templatetags/rdv.py: las etiquetas (tags) de nuestras plantillas (véase el ejemplo 16), cargadas
# mediante {% load rdv %}.
#
#   {% success_zone %}: los mensajes flash de ÉXITO, en la parte superior de la página;
#   {% error_zone %}: la zona de errores, en la parte INFERIOR de cada página, sobre un fondo
#   rosa claro. Reúne las tres posibles fuentes de error:
#     - [error]: el error de la página mostrada (fecha inválida, captcha mal escrito,
#       login ya usado...), transmitido por la vista;
#     - los mensajes flash de error, dejados por la vista anterior antes de una
#       redirección (horario ya reservado, eliminación rechazada...);
#     - los errores de ingreso de un formulario inválido (véase el ejemplo 19): sus
#       mensajes se muestran DEBAJO de los campos; aquí, si no hay otro
#       mensaje, una simple frase "The form contains errors.".
# =========================================================================

from django import template
from django.contrib import messages as flash
from django.utils.translation import gettext as _

register = template.Library()


# takes_context: la función recibe el contexto de la plantilla que la llama; messages:
# la variable del procesador de contexto de los mensajes flash; level: el nivel de un mensaje
@register.inclusion_tag("fragments/success.html", takes_context=True)
def success_zone(context):
    return {"texts": [m.message for m in context.get("messages", []) if m.level == flash.SUCCESS]}


@register.inclusion_tag("fragments/errors.html", takes_context=True)
def error_zone(context):
    texts = [m.message for m in context.get("messages", []) if m.level == flash.ERROR]
    if context.get("error"):
        texts.insert(0, context["error"])
    form = context.get("form")
    # un formulario ENLAZADO (enviado) e inválido, sin ningún otro mensaje
    if not texts and form is not None and form.is_bound and form.errors:
        texts.append(_("The form contains errors."))
    return {"texts": texts}

Dos etiquetas de inclusión (ejemplo 16), cargadas en las plantillas mediante [{% load rdv %}]. Cada una devuelve una pequeña plantilla (un fragmento, que se trata más adelante) que contiene las variables devueltas por la función:

  • Líneas 26–28: [{% success_zone %}]: mensajes flash de éxito (ejemplo 20), que se muestran en la parte superior de la página. [takes_context=True]: la función recibe el contexto de la plantilla que la invoca, donde el procesador de contexto de mensajes ha almacenado la variable [messages]. [level] es el nivel de un mensaje ([flash.SUCCESS], [flash.ERROR]...);
  • líneas 31–40: [{% error_zone %}]: el área de errores, al final de cada página. Agrupa las tres posibles fuentes de errores: el error de la página (la variable [error], pasada por la vista y colocada al inicio de la lista por [insert(0, ...)]), los mensajes flash de error (establecidos por la vista anterior antes de una redirección) y los errores de entrada de un formulario no válido, cuyos mensajes se muestran debajo de los campos: el área de errores muestra entonces simplemente la frase “El formulario contiene errores.” [is_bound]: el formulario ha recibido datos (ejemplo 19).

Ambas etiquetas leen la misma lista, y cada una conserva un solo nivel. Una lista de mensajes que ya fue leída se vacía al final de la solicitud (ejemplo 20): cada mensaje se muestra una sola vez.

11.13.5. web/middleware.py

# =========================================================================
# web/middleware.py: dos middlewares de la capa web (véase el ejemplo 24).
# =========================================================================

from django.conf import settings
from django.contrib import messages
from django.core.exceptions import BadRequest, PermissionDenied
from django.http import Http404
from django.shortcuts import redirect
from django.utils import translation
from django.utils.translation import gettext as _

from security import auth
from security.errors import InvalidSession

from .views.errors import error_page


# -------------------------------------------------------------------------
# el idioma de la solicitud (véase el ejemplo 22): el de la cookie [rdvmedecins_language]
# si es un idioma admitido, inglés en caso contrario. Ubicado al inicio de la lista de
# middlewares, actúa para TODAS las solicitudes, incluso las que terminan en
# ninguna ruta (página 404): su página de error está en el idioma correcto
# -------------------------------------------------------------------------
class SetLanguage:
    # los idiomas admitidos; el idioma por defecto es LANGUAGE_CODE
    LANGUAGES = [code for code, name in settings.LANGUAGES]

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        language = request.COOKIES.get(settings.LANGUAGE_COOKIE_NAME)
        if language not in self.LANGUAGES:
            language = settings.LANGUAGE_CODE
        translation.activate(language)
        # el idioma de la solicitud, almacenado como lo hace LocaleMiddleware (véase el ejemplo 22)
        request.LANGUAGE_CODE = language
        return self.get_response(request)


# -------------------------------------------------------------------------
# cómo los errores se convierten en páginas HTML. Tres casos:
#   1. una InvalidSession (cuenta eliminada desde el login) -> de vuelta a la
#      página de login, como en una sesión expirada;
#   2. un error HTTP lanzado por una vista: solicitud inválida (BadRequest, 400),
#      rol insuficiente (PermissionDenied, 403), objeto desconocido (Http404) -> la página
#      de error, con el código original;
#   3. cualquier otra excepción (una verdadera anomalía): Django la escribe en el
#      log, con su traza de pila; en producción (DEBUG falso), el usuario
#      ve la página de error 500 (handler500, véase config/urls.py) - nunca la traza
#      de pila; en desarrollo, la página de depuración de Django.
# Un método HTTP rechazado (405) no es una excepción: los decoradores
# require_GET... devuelven una respuesta 405 vacía, que __call__ reemplaza por nuestra página.
# -------------------------------------------------------------------------
class ErrorPage:
    CODES = {BadRequest: 400, PermissionDenied: 403, Http404: 404}

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        if response.status_code == 405 and not response.content:
            page = error_page(request, 405)
            # el encabezado Allow: los métodos aceptados
            page["Allow"] = response["Allow"]
            return page
        return response

    def process_exception(self, request, exception):
        if isinstance(exception, InvalidSession):
            messages.error(request, _("Your session has expired: please log in again."))
            return auth.clear_token(redirect("login"))
        for cls, code in self.CODES.items():
            if isinstance(exception, cls):
                return error_page(request, code)
        return None

Los dos componentes de middleware de la capa web (Ejemplo 24). Recuerde su orden en la lista [MIDDLEWARE] de [config/settings.py]: [SetLanguage] primero, [ErrorPage] al final.

  • Líneas 25–39: el idioma de la solicitud; si coincide con el idioma de la cookie [rdvmedecins_language], se usa ese idioma; en caso contrario, se usa inglés. Este es el middleware [SetLanguage] del Ejemplo 16, no [LocaleMiddleware] (Ejemplo 22): [LocaleMiddleware] elegiría el idioma preferido del navegador si no hubiera cookie; las demás versiones de la aplicación siempre inician en inglés, y esta hace lo mismo. Los idiomas admitidos se leen de la configuración [LANGUAGES] (línea 27, una lista de solo lectura que se ejecuta una vez al cargar la clase). [translation.activate] (línea 36) establece el idioma activo (ejemplo 16): el idioma usado para las traducciones, las fechas y la variable [LANGUAGE_CODE] en las plantillas (procesador de contexto [i18n], ejemplo 22). El idioma también se almacena en [request.LANGUAGE_CODE] (línea 38), como hace [LocaleMiddleware], para las vistas que necesiten acceder a él. Al estar en la parte superior, este middleware se aplica a todas las solicitudes antes de cualquier otro procesamiento: todas las páginas, incluidas las de error, quedan en el idioma correcto;
  • Líneas 62–69: un método HTTP rechazado (una llamada GET a [/logout], que solo acepta POST) no lanza una excepción: los decoradores [require_GET], [require_POST]... devuelven una respuesta 405 sin contenido. [__call__] la reemplaza por la página de error, conservando el encabezado [Allow] (los métodos aceptados), que es obligatorio en una respuesta 405;
  • Líneas 71–78: excepciones lanzadas por las vistas ([process_exception], Ejemplo 24). Una [InvalidSession] (la cuenta fue eliminada): el mensaje “sesión expirada”, la eliminación de la cookie del token y la página de inicio de sesión. Un error HTTP lanzado por una vista ([BadRequest], [PermissionDenied], [Http404]): la página de error, con su código, tanto en producción como en desarrollo. Cualquier otra excepción es una verdadera anomalía: el método devuelve [None], y [Django] la maneja por sí mismo; la registra en el log, junto con su pila de llamadas, y luego muestra su página de depuración en desarrollo y la página de error 500 ([handler500]) en producción. El usuario nunca ve la pila de llamadas de una aplicación en producción.
1
2
3
4
5
6
7
$ curl -si http://localhost:8081/logout
HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=utf-8
Allow: POST
...
<!doctype html>
...

El código 405 (Method Not Allowed) se presenta al usuario como una página no encontrada (el mensaje de la página de error, que se explica más adelante). Una URL que no coincide con ninguna ruta no pasa por [ErrorPage]: [Django] llama directamente a la vista [handler404] en producción y muestra su página 404 detallada en desarrollo (Ejemplo 24).

11.14. Diccionarios

El texto de la interfaz es el mismo que en las otras versiones de la aplicación, que lo almacenaban en archivos JSON bajo claves ([LOGIN.TITLE] hacía referencia al texto [Sign in]). [Django] funciona de otra manera (ejemplo 22): el texto original, en inglés, se escribe directamente en el código ([_("Sign in")]) y en las plantillas ([{% translate "Sign in" %}]); sirve como clave en el diccionario de francés, el archivo [locale/fr/LC_MESSAGES/django.po]:

#: web/views/schedule.py:202 web/views/area.py:75
msgid "Appointment cancelled."
msgstr "Rendez-vous annulé."

#: web/views/auth.py:62 web/views/area.py:142
#, python-format
msgid "Too many failed attempts. Try again in %(minutes)d minute."
msgid_plural "Too many failed attempts. Try again in %(minutes)d minutes."
msgstr[0] "Trop de tentatives infructueuses. Réessayez dans %(minutes)d minute."
msgstr[1] ""
"Trop de tentatives infructueuses. Réessayez dans %(minutes)d minutes."

Este archivo, que contiene aproximadamente 140 textos, no se reproduce aquí. Fue generado con el comando [python manage.py makemessages -l fr], que recupera todos los textos marcados en el código y en las plantillas, luego se completó manualmente y se compiló en [django.mo] con [python manage.py compilemessages] (ejemplo 22). El archivo compilado [django.mo] se entrega con el código: la aplicación funciona sin las herramientas [gettext]. No hay diccionario en inglés: un texto sin traducción se muestra tal cual, es decir, en inglés.

Las líneas [#:] indican dónde se usa cada texto; [#, python-format] identifica un texto con parámetros ([%(minutes)d]), cuya traducción [makemessages] verificará. [gettext] permite algo que las otras versiones no podían hacer: el plural (“1 minuto”, “15 minutos”), con [ngettext] en el código (véase más adelante) y [msgid_plural] en el diccionario (ejemplo 22). Se agregaron algunos textos: el mensaje de la página 419, que las otras versiones no tienen.

Los mensajes de error de los formularios se traducen de la misma manera (véase más adelante). Los mensajes que [Django] genera por sí mismo (número demasiado grande, dirección de correo no válida, etc.) se traducen con los diccionarios de [Django].

11.15. Formularios

Los formularios de “persona” son formularios de [Django] (ejemplos 18 y 19): una clase describe los campos y sus restricciones; la vista construye el formulario con los datos del usuario ([PersonForm(request.POST)]) y luego comprueba si es válido ([is_valid]). Un formulario no válido se vuelve a mostrar, con los datos del usuario y los mensajes de error debajo de los campos (excepto las contraseñas: un campo [PasswordInput] nunca se vuelve a mostrar). El token anti-CSRF es verificado para todos los formularios por el middleware [CsrfViewMiddleware].

11.15.1. web/forms.py

# =========================================================================
# web/forms.py: los formularios de "persona" y sus restricciones (véanse los
# ejemplos 18 y 19). Tres formularios comparten los mismos campos de identidad
# (título, nombre, apellido):
#
#   PersonFieldsForm            título, nombre, apellido
#    ├─ PersonForm              + login / contraseña OPCIONALES, versión
#    │                            (el ADMIN agrega o actualiza un médico / cliente)
#    ├─ RegistrationForm        + login / contraseña / confirmación OBLIGATORIOS
#    │                            (un paciente crea su cuenta)
#    └─ MyAccountForm           + login, nueva contraseña opcional, contraseña
#                                 ACTUAL OBLIGATORIA, versión
#                                 (un paciente actualiza su cuenta)
#
# Las clases hijas HEREDAN de PersonFieldsForm: tienen sus campos, además de
# los propios. Lo ingresado y validado (cleaned_data) se convierte en PersonData
# para la capa de negocio mediante el método person_data().
#
# Las etiquetas, los textos de ayuda y los mensajes de error están traducidos (gettext_lazy,
# véase business/errors.py). Las longitudes máximas son las de las columnas SQL.
# =========================================================================

from django import forms
from django.core.exceptions import ValidationError
from django.core.validators import RegexValidator
from django.utils.translation import gettext_lazy as _

from business.person_data import PersonData
from security import passwords

TITLES = ["Mr", "Mme", "Melle"]
# longitud mínima de una contraseña ELEGIDA por un paciente
PASSWORD_MIN = 6

# login: letras minúsculas, dígitos, punto, guion, guion bajo - 30 caracteres como máximo
LOGIN_FORMAT = RegexValidator(r"^[a-z0-9._-]{1,30}$", message=_(
    "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore."))


# bcrypt solo toma en cuenta los primeros 72 bytes de una contraseña (véase
# security/passwords.py); una letra acentuada ocupa dos bytes en UTF-8
def bcrypt_length(value: str) -> None:
    if len(value.encode()) > passwords.MAX_BYTES:
        raise ValidationError(_("The password must not exceed 72 characters."))


# -------------------------------------------------------------------------
# un login siempre está en minúsculas: el campo convierte lo ingresado ANTES de su
# validación (to_python se llama antes que los validadores)
# -------------------------------------------------------------------------
class LoginField(forms.CharField):
    def to_python(self, value):
        text = super().to_python(value)
        return text.lower() if text else text


# un campo de contraseña: nunca se vuelve a mostrar y sin eliminar los espacios
# (strip=False: un espacio forma parte de la contraseña)
def password_field(label, required, help_text="", min_length=None):
    messages = {
        "required": _("The password is required."),
        # %(limit_value)d: la longitud mínima, colocada en el mensaje por Django
        "min_length": _("The password must be at least %(limit_value)d characters long."),
    }
    return forms.CharField(label=label, required=required, help_text=help_text, strip=False,
                           min_length=min_length, validators=[bcrypt_length],
                           error_messages=messages,
                           widget=forms.PasswordInput(attrs={"maxlength": 72,
                                                             "autocomplete": "new-password"}))


# -------------------------------------------------------------------------
# la clase padre de nuestros formularios (véase el ejemplo 18): cada zona de ingreso recibe
# la clase CSS de Bootstrap que le corresponde; flag() enmarca en rojo (clase
# is-invalid) los campos que tienen un error de ingreso, y aquellos que designa un error de NEGOCIO
# (un login ya usado...), con el mensaje entonces al pie de la página
# -------------------------------------------------------------------------
class BootstrapForm(forms.Form):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        for field in self.fields.values():
            css_class = "form-select" if isinstance(field.widget, forms.Select) else "form-control"
            field.widget.attrs["class"] = css_class

    def flag(self, fields=()):
        # errors: los errores de ingreso; |: la unión de dos conjuntos
        for name in set(self.errors) | set(fields):
            if name in self.fields:
                self.fields[name].widget.attrs["class"] += " is-invalid"
        return self


class PersonFieldsForm(BootstrapForm):
    title = forms.ChoiceField(label=_("Title"), choices=[(t, t) for t in TITLES], error_messages={
        "required": _("Choose a title from the list."),
        "invalid_choice": _("Choose a title from the list.")})
    first_name = forms.CharField(label=_("First name"), max_length=20, error_messages={
        "required": _("The first name is required."),
        "max_length": _("The first name must not exceed 20 characters.")})
    last_name = forms.CharField(label=_("Last name"), max_length=20, error_messages={
        "required": _("The last name is required."),
        "max_length": _("The last name must not exceed 20 characters.")})

    # lo ingresado y validado -> los datos que espera la capa de negocio. Un campo
    # vacío es None (o None: una cadena vacía es "falsy")
    def person_data(self) -> PersonData:
        d = self.cleaned_data
        return PersonData(d["title"], d["last_name"], d["first_name"], d.get("login") or None,
                          d.get("password") or None, d.get("version"))


# el formulario de un médico o de un cliente (ADMIN): login y
# contraseña OPCIONALES; creation=False: el formulario de actualización, con la versión
class PersonForm(PersonFieldsForm):
    def __init__(self, *args, creation=True, **kwargs):
        super().__init__(*args, **kwargs)
        # se acepta un campo vacío: los validadores solo se aplican a un valor ingresado
        self.fields["login"] = LoginField(
            label=_("Login"), required=False, max_length=30, validators=[LOGIN_FORMAT],
            help_text=_("Optional: defaults to the last name in lower case.") if creation
            else _("Leave empty to keep it unchanged."),
            widget=forms.TextInput(attrs={"class": "form-control", "autocomplete": "off"}))
        self.fields["password"] = password_field(
            _("Password"), False,
            _("Optional: defaults to the login.") if creation
            else _("Leave empty to keep it unchanged."))
        self.fields["password"].widget.attrs["class"] = "form-control"
        # actualización: la versión del registro mostrado, en un campo oculto (el
        # bloqueo optimista)
        if not creation:
            self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)


# -------------------------------------------------------------------------
# la contraseña y su confirmación: dos campos, comparados por clean (véase el
# ejemplo 19). Común al registro (obligatoria) y a la cuenta del paciente
# (opcional: vacía = contraseña sin cambios)
# -------------------------------------------------------------------------
class WithConfirmation(PersonFieldsForm):
    def add_passwords(self, required: bool):
        self.fields["login"] = LoginField(
            label=_("Login"), max_length=30, validators=[LOGIN_FORMAT],
            help_text=_("Unaccented lower-case letters, digits, dot, hyphen, underscore.")
            if required else "",
            error_messages={"required": _("The login is required.")},
            widget=forms.TextInput(attrs={"class": "form-control", "autocomplete": "username"}))
        self.fields["password"] = password_field(
            _("Password") if required else _("New password"), required,
            _("At least 6 characters.") if required else _("Leave empty to keep it unchanged."),
            min_length=PASSWORD_MIN)
        self.fields["confirmation"] = password_field(_("Confirm password"), required)
        self.fields["confirmation"].error_messages["required"] = _("Please confirm the password.")
        for name in ("password", "confirmation"):
            self.fields[name].widget.attrs["class"] = "form-control"

    # la validación del formulario completo, después de la de cada campo
    def clean(self):
        data = super().clean()
        password = data.get("password")
        confirmation = data.get("confirmation")
        if password and password != confirmation and "confirmation" not in self.errors:
            self.add_error("confirmation", _("The confirmation does not match the password."))
        return data


# "Crear una cuenta de paciente": login, contraseña y confirmación OBLIGATORIOS
class RegistrationForm(WithConfirmation):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.add_passwords(required=True)


# "Gestionar mi cuenta" (un paciente): login obligatorio, nueva contraseña opcional,
# contraseña ACTUAL OBLIGATORIA, versión
class MyAccountForm(WithConfirmation):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.add_passwords(required=False)
        # la contraseña ACTUAL, obligatoria para cualquier actualización de la cuenta
        self.fields["current_password"] = forms.CharField(
            label=_("Current password"), strip=False,
            help_text=_("Required to save any change."),
            error_messages={"required": _("Enter your current password.")},
            widget=forms.PasswordInput(attrs={"class": "form-control", "maxlength": 72,
                                              "autocomplete": "current-password"}))
        self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)

Tres formularios comparten los campos de identidad (título, nombre, apellido): el formulario del administrador (para un médico o un cliente), el formulario de creación de cuenta de paciente y “Administrar mi cuenta”. El comentario de encabezado describe su jerarquía de herencia: su clase padre común, [PersonFieldsForm], define los campos de identidad; cada hija agrega los suyos. Las etiquetas, los consejos y los mensajes se traducen de forma diferida ([gettext_lazy]): se definen cuando se carga el módulo y se traducen cada vez que se muestra la página, al idioma de la solicitud (la capa de negocio, mencionada anteriormente).

  • Líneas 36–37: un formulario de inicio de sesión, un validador ([RegexValidator]) que comprueba una expresión regular. Un validador es un objeto invocable que lanza [ValidationError] ante un valor incorrecto (Ejemplo 19); se asigna a un campo mediante su parámetro [validators];
  • líneas 42–44: un validador escrito como una función simple. [bcrypt] solo considera los primeros 72 bytes de una contraseña (la capa de seguridad, tratada anteriormente): el límite se aplica a bytes, no a caracteres ([encode()]: una letra con acento ocupa dos bytes en [UTF-8]);
  • líneas 51–54: un nombre de usuario siempre está en minúsculas. Un campo personalizado, hijo de [CharField], redefine [to_python], el método que convierte la entrada en un valor de Python: se llama antes que los validadores, que por lo tanto verifican la entrada una vez convertida. [super().to_python(value)] primero realiza el procesamiento estándar de [CharField] (eliminar los espacios que rodean la entrada);
  • Líneas 59–69: una función que crea un campo de contraseña. [strip=False]: los espacios no se eliminan; pueden formar parte de una contraseña. [min_length]: la longitud mínima, que [Django] verifica por sí mismo; su mensaje contiene [%(limit_value)d], el parámetro que [Django] coloca allí. El widget [PasswordInput] nunca se vuelve a dibujar; el atributo HTML [maxlength] impide que los usuarios escriban más de 72 caracteres; [autocomplete="new-password"] indica al navegador que solicite una contraseña nueva, en lugar de rellenar el campo con la contraseña guardada;
  • líneas 78–90: la clase padre de nuestros formularios (Ejemplo 18). Su constructor asigna a cada campo de entrada la clase CSS adecuada ([form-select] para una lista, [form-control] para los demás). El método [flag] agrega la clase [is-invalid] (un borde rojo) a los campos con errores de entrada y a los señalados por un error de regla de negocio (un nombre de usuario que ya está en uso): [set(a) | set(b)] es la unión de dos conjuntos. Devuelve el propio formulario: las vistas lo llaman al pasar el formulario a la plantilla;
  • líneas 93–102: el título, una lista ([ChoiceField], ejemplo 18); el nombre y el apellido, 20 caracteres como máximo, los anchos de columna SQL (el atributo [maxlength] del campo de entrada lo agrega [Django] por sí mismo). Cada mensaje de error se reemplaza por uno propio ([error_messages], ejemplo 19). [invalid_choice] es el mensaje para un valor que no está en la lista (una solicitud creada manualmente). Los espacios que rodean una entrada los elimina [CharField];
  • líneas 106–109: los datos validados ([cleaned_data]), convertidos a [PersonData] para la capa de negocio: la capa de negocio no conoce los formularios. [d.get(key)] devuelve [None] para un campo que el formulario no tiene; [x or None] convierte una cadena vacía en [None] (sin cambios, o el valor predeterminado);
  • líneas 114–131: el formulario del administrador. El parámetro [creation], que hemos creado, distingue entre creación y modificación; se coloca después de [*args]: es un parámetro obligatorio ([PersonForm(request.POST, creation=False)]). Los campos propios de este formulario los agrega el constructor en el diccionario [self.fields]: sus opciones dependen de [creation] (los consejos difieren: “Opcional: de forma predeterminada, el apellido en minúsculas.”, “Dejar vacío para mantenerlo sin cambios.”). El nombre de usuario y la contraseña son opcionales ([required=False]): un validador solo se aplica a un valor ingresado, por lo que un campo vacío es aceptado. Solo el formulario de “modificación” tiene el campo oculto “version” (el bloqueo optimista, capa de negocio);
  • líneas 139–163: la contraseña y su confirmación, comunes tanto al registro como a la cuenta del paciente. Los dos campos se comparan mediante el método [clean] del formulario (Ejemplo 19), que se invoca después de validar cada campo. [add_error] adjunta el mensaje al campo de confirmación, a menos que ese campo ya contenga un error (“Confirme la contraseña.”): un solo mensaje por campo. El requisito de longitud mínima se aplica solo a una contraseña elegida por un paciente (6 caracteres);
  • líneas 167–170: creación de una cuenta de paciente: el inicio de sesión, la contraseña y la confirmación son obligatorios;
  • líneas 175–186: “Administrar mi cuenta”: la nueva contraseña es opcional (en blanco: sin cambios), la contraseña actual es obligatoria. No la valida el formulario, sino la vista: una contraseña incorrecta debe ser contada por el limitador de intentos como un inicio de sesión fallido. [autocomplete="current-password"]: en este caso, el navegador puede sugerir la contraseña guardada.

11.15.2. web/rendering.py

1
2
3
4
5
6
7
8
9
# web/rendering.py: el motor de renderizado de los formularios (véase el ejemplo 18): un
# campo completo (etiqueta, zona de ingreso, ayuda, errores) lo dibuja la plantilla
# templates/forms/field.html, con las clases de Bootstrap 5

from django.forms.renderers import TemplatesSetting


class BootstrapRenderer(TemplatesSetting):
    field_template_name = "forms/field.html"

El motor de renderizado de formularios del Ejemplo 18, definido por la configuración [FORM_RENDERER] de [config/settings.py]: cada campo completo (etiqueta, campo de entrada, consejo, mensajes de error) se renderiza con la plantilla [templates/forms/field.html] (que se trata más adelante), con clases de [Bootstrap].

11.16. Modelos de vista

# =========================================================================
# web/view_models.py: los "modelos de vista": objetos construidos
# de una sola vez por una vista, que la plantilla se limita a leer. Regla que siguen
# todas las páginas: nada de lógica en las plantillas. Las vistas preparan datos
# YA formateados ("Mme Marie PELISSIER", "8:00 - 8:20",
# selected = True...) y ya filtrados según el rol del usuario; las
# plantillas se limitan a colocarlos en el HTML.
# =========================================================================

from dataclasses import dataclass


# una opción de una lista desplegable (médico, paciente)
@dataclass(frozen=True)
class OptionView:
    id: int
    label: str
    selected: bool


# una fila de la agenda mostrada (un horario)
@dataclass(frozen=True)
class ScheduleRow:
    slot_id: int
    time_range: str         # "8:00 - 8:20"
    free: bool
    # nombre mostrado para un horario ocupado; None = "Reservado"
    patient: str | None
    me: bool                # la cita del paciente con sesión iniciada
    bookable: bool          # ¿mostrar el botón "Book"?
    book_url: str
    # se define solo si se muestra el botón "Cancelar"
    appointment_id: int | None


# la agenda mostrada: el médico, el día, las filas
@dataclass(frozen=True)
class ScheduleView:
    doctor: str             # "Mme Marie PELISSIER"
    day: str                # "Wednesday 23 September 2026"
    rows: list[ScheduleRow]


# el diálogo de reserva de un horario
@dataclass(frozen=True)
class BookingView:
    slot_id: int
    time_range: str
    # ADMIN / DOCTOR: los pacientes entre los cuales elegir
    clients: list[OptionView]
    # USER: el paciente es él mismo
    patient: str | None


# una cita próxima, en el área del paciente
@dataclass(frozen=True)
class AppointmentView:
    id: int
    day: str                # "Wednesday 23 September 2026"
    time_range: str         # "8:00 - 8:20"
    doctor: str             # "Mme Marie PELISSIER"
    schedule_url: str       # la agenda del médico ese día

El archivo [web/view_models.py] contiene los modelos de vista: objetos construidos por una vista, que la plantilla simplemente lee. La regla, seguida por todas las páginas: ninguna lógica en las plantillas. Las vistas preparan datos ya formateados (“Sra. Marie PELISSIER”, “8:00 – 8:20”) y ya filtrados según el rol del usuario; las plantillas los colocan en el HTML. Son clases de datos inmutables ([frozen=True], ejemplo 08): una vez construido, un modelo de vista nunca cambia.

  • Líneas 14–18: una opción de una lista desplegable: el ID, la etiqueta y si la opción está seleccionada.
  • Líneas 22–33: una entrada del calendario: una franja horaria y lo que el usuario conectado está autorizado a ver y hacer con ella. [patient] se completa solo si el usuario está autorizado a ver el nombre del paciente; [bookable] indica si se debe mostrar el botón “Reservar”; [appointment_id] indica si se debe mostrar el botón “Cancelar”;
  • líneas 37–52: el calendario mostrado y la ventana de reserva: para el administrador y los médicos, la lista de pacientes entre los que elegir; para un paciente, su propio nombre;
  • líneas 56–62: una cita próxima en la sección del paciente.

11.17. La capa web: rutas y vistas

11.17.1. Rutas

# =========================================================================
# web/urls.py: las rutas de la aplicación. Su protección no se escribe aquí,
# sino en security/access.py (una regla por prefijo de URL).
# =========================================================================

from django.urls import path, re_path

from .views import area, auth, language, registration, schedule
from .views.persons import clients, doctors

urlpatterns = [
    # login
    path("", auth.home, name="home"),
    path("login", auth.login, name="login"),
    path("logout", auth.logout, name="logout"),
    # el idioma: solo fr o en
    re_path(r"^language/(?P<code>fr|en)$", language.change, name="language"),
    # la agenda
    path("schedule", schedule.show, name="schedule"),
    path("schedule/book", schedule.book, name="schedule_book"),
    path("schedule/cancel", schedule.cancel, name="schedule_cancel"),
    # la creación de una cuenta de cliente
    path("register/access", registration.access, name="registration_access"),
    path("register", registration.registration, name="registration"),
    # el área del paciente
    path("my-area", area.area, name="area"),
    path("my-area/cancel", area.cancel_appointment, name="area_cancel"),
    path("my-account", area.account, name="account"),
    path("my-account/delete", area.delete_account, name="account_delete"),
    # la gestión de médicos y clientes: las rutas construidas por los dos
    # objetos PersonManagement; * "desempaqueta" la lista que devuelven
    *doctors.urls(),
    *clients.urls(),
]

Las rutas de la aplicación, montadas en la raíz del sitio por [config/urls.py]. Las rutas para administrar médicos y clientes las generan dos objetos (que se tratan más adelante); [*list] coloca los elementos de una lista dentro de otra lista (líneas 32–33). El comando [show_urls] no existe en [Django] (proviene de una extensión); un breve script, lanzado con [python manage.py shell], las lista todas, junto con sus nombres:

$ python manage.py shell -v 0 -c "from django.urls import get_resolver; [print(f'{str(p.pattern):32} {p.name}') for p in get_resolver().url_patterns[0].url_patterns]"
                                 home
login                            login
logout                           logout
^language/(?P<code>fr|en)$       language
schedule                         schedule
schedule/book                    schedule_book
schedule/cancel                  schedule_cancel
register/access                  registration_access
register                         registration
my-area                          area
my-area/cancel                   area_cancel
my-account                       account
my-account/delete                account_delete
doctors                          doctors_list
doctors/add                      doctors_add
doctors/<int:id>/edit            doctors_edit
doctors/<int:id>/delete          doctors_delete
clients                          clients_list
clients/add                      clients_add
clients/<int:id>/edit            clients_edit
clients/<int:id>/delete          clients_delete

Las URL son las de las otras versiones de la aplicación: no tienen barra final ([/schedule], no [/schedule/]), y editar y eliminar un médico son solicitudes POST ([/doctors/{id}/edit], [/doctors/{id}/delete]), no PUT y DELETE como en el Ejemplo 28. El código siempre genera las URL a partir de los nombres de las rutas ([redirect("login")], [reverse("schedule")], [{% url 'schedule' %}] en las plantillas, Ejemplo 04): cambiar una URL requiere modificar solo su ruta.

Los métodos aceptados por cada ruta se declaran con los decoradores [require_GET], [require_POST], y [require_http_methods] en las vistas (ejemplo 02). Las reglas de acceso no están en las vistas, sino en el archivo [security/access.py], como se vio antes: una regla por prefijo de URL ([^/(doctors|clients)] para el administrador, [^/my-] para los pacientes...), y una regla final que exige un usuario autenticado para todas las demás URL. Las URL de la aplicación se eligieron con este fin: todas las páginas de un mismo rol comienzan de la misma manera.

11.17.2. web/views/errors.py

# =========================================================================
# web/views/errors.py: la página de error (400, 403, 404, 405, 419, 500) y las vistas
# que Django llama para los errores que detecta por sí mismo (véase config/urls.py:
# handler400, handler403, handler404, handler500 y la configuración CSRF_FAILURE_VIEW).
# =========================================================================

from django.shortcuts import render
from django.utils.translation import gettext_lazy as _

# el mensaje de cada código
MESSAGES = {
    400: _("The request is invalid."),
    403: _("Your role does not allow you to access this page."),
    404: _("This page does not exist."),
    405: _("This page does not exist."),
    419: _("The page has expired: reload it, then try again."),
    500: _("An unexpected error occurred. Please try again later."),
}


def error_page(request, code: int):
    return render(request, "error.html", {
        "page_title": _("Error"), "code": code, "message": MESSAGES.get(code, MESSAGES[500]),
    }, status=code)


# las vistas de los errores detectados por Django (exception: la excepción que causó
# el error; la vista 500 no la recibe)
def error_400(request, exception):
    return error_page(request, 400)


def error_403(request, exception):
    return error_page(request, 403)


def error_404(request, exception):
    return error_page(request, 404)


def error_500(request):
    return error_page(request, 500)


# -------------------------------------------------------------------------
# un token anti-CSRF ausente o incorrecto: la página probablemente se mostró hace
# mucho tiempo, en otra pestaña, antes de un cambio de la cookie del token... Error
# 419, el código (no oficial, pero muy extendido) de una página expirada. reason: el motivo
# del rechazo, dado por CsrfViewMiddleware (en inglés)
# -------------------------------------------------------------------------
def csrf_rejected(request, reason=""):
    return error_page(request, 419)

La página de error y las vistas de error que [Django] detecta por sí mismo:

  • líneas 11–18: el mensaje para cada código. El código 405 se muestra como un error de “página no encontrada”;
  • líneas 21–24: la página de error, plantilla [error.html], con el código de respuesta HTTP ([status=code]). Un código desconocido recibe el mensaje del error 500 ([dict.get(key, default)]);
  • líneas 29–42: las cuatro vistas [handler400]... [handler500], referenciadas en [config/urls.py] (ejemplo 24). Su firma la determina [Django]: la solicitud y la excepción que causó el error (excepto en el error 500);
  • líneas 51–52: un token anti-CSRF ausente o no válido. El middleware [CsrfViewMiddleware] rechaza la solicitud antes de invocar la vista (Ejemplo 21) y, en su lugar, invoca la vista asociada a la configuración [CSRF_FAILURE_VIEW] (véase [config/settings.py]): la página de error 419, el código (no oficial pero ampliamente utilizado) para una página expirada. Esto ocurre cuando una página ha permanecido abierta en una pestaña durante mucho tiempo, aunque la cookie del token haya cambiado desde entonces. La página muestra entonces: “La página ha expirado: vuelva a cargarla e inténtelo de nuevo.” Su parámetro [reason] es el motivo del rechazo, en inglés, destinado al log y no al usuario.

11.17.3. web/views/language.py

# =========================================================================
# web/views/language.py: GET /language/fr, GET /language/en: los dos botones FR / EN de
# la barra de navegación. Ruta pública: el idioma debe poder cambiarse antes de
# iniciar sesión.
#
# La elección se recuerda en una cookie: en cada solicitud siguiente, el middleware
# SetLanguage la lee de nuevo y establece el idioma de la solicitud. Luego se vuelve a la página
# de la que se venía (véase el ejemplo 22).
# =========================================================================

from urllib.parse import urlsplit

from django.conf import settings
from django.shortcuts import redirect
from django.views.decorators.http import require_GET


# code: fr o en (véase web/urls.py: /language/de da una página 404)
@require_GET
def change(request, code):
    response = redirect(origin_page(request))
    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, code, max_age=365 * 24 * 3600,
                        secure=settings.COOKIE_SECURE, httponly=True, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# la página anterior, a partir del encabezado HTTP "Referer" enviado por el navegador. Solo se
# conservan su ruta y sus parámetros (/schedule?...): redirigir a una
# dirección completa proporcionada por la solicitud permitiría enviar al usuario a
# otro sitio (la llamada falla de "redirección abierta"). urlsplit divide una URL en sus
# componentes: scheme (http), netloc (la máquina), path, query...
# -------------------------------------------------------------------------
def origin_page(request) -> str:
    referer = urlsplit(request.headers.get("Referer", ""))
    path = referer.path
    # "//site.com/..." el navegador la entendería como una dirección en
    # OTRO sitio: también se rechaza
    if not referer.scheme or not path.startswith("/") or path.startswith("//") \
            or path.startswith("/language/"):
        return "/"
    return f"{path}?{referer.query}" if referer.query else path

Los botones FR / EN de la barra de navegación: la selección de idioma se almacena en una cookie durante un año (ejemplo 22), y luego el navegador regresa a la página de la que venía. La cookie es [HttpOnly]: el [JavaScript] de la página no necesita leerla. No está firmada: el middleware [SetLanguage] verifica su valor, y un valor desconocido da como resultado inglés (véase el capítulo sobre los ámbitos).

  • Línea 20: [code] equivale a [fr] o [en]: la ruta (una expresión regular, [re_path], ejemplo 02) acepta solo estos dos valores. [/language/de] no coincide con ninguna ruta (página 404);
  • líneas 34–42: la página anterior se especifica mediante el encabezado HTTP [Referer] que el navegador envía con la solicitud. Este dato lo proporciona el cliente y por lo tanto es sospechoso: redirigir a una URL completa tomada de la solicitud permitiría a un atacante enviar al usuario a su propio sitio mediante un enlace a [/language/fr] con un [Referer] falso (la llamada vulnerabilidad de “redirección abierta”). Por eso, conservamos solo la ruta y los parámetros ([/schedule?doctorId=1&...]), extraídos por la función [urlsplit] de la biblioteca estándar, que divide una URL en sus partes ([scheme], [netloc], [path], [query]...). Una ruta que comienza con [//] también se rechaza: un navegador interpreta [//site.com/page] como una dirección en otro sitio. Por último, no se puede volver a [/language/...]: sería un bucle. Una barra invertida ([\]) al final de una línea ([Python]) extiende la instrucción a la línea siguiente.
1
2
3
4
5
6
7
8
9
$ curl -si http://localhost:8081/language/fr -H "Referer: http://localhost:8081/schedule?doctorId=1&day=2026-09-30"
HTTP/1.1 302 Found
Location: /schedule?doctorId=1&day=2026-09-30
Set-Cookie: rdvmedecins_language=fr; expires=Mon, 27 Sep 2027 17:56:57 GMT; HttpOnly; Max-Age=31536000; Path=/; SameSite=Lax
...
$ curl -si http://localhost:8081/language/fr -H "Referer: https://pirate.com//page"
HTTP/1.1 302 Found
Location: /
...

11.17.4. web/views/auth.py

# =========================================================================
# web/views/auth.py: las rutas PÚBLICAS de login:
#   GET  /        redirige a la página de inicio del rol (o a /login)
#   GET  /login   muestra el formulario de login (con su captcha)
#   POST /login   verifica el límite de intentos, el captcha, login / contraseña
#   POST /logout  cierre de sesión
#
# Protección contra robots, en este orden:
#   1. ¿demasiados fallos recientes para este login desde esta dirección IP?
#      -> rechazo inmediato, sin siquiera mirar la contraseña;
#   2. ¿respuesta incorrecta al captcha? -> rechazo (contado como un fallo);
#   3. solo entonces, verificación de la contraseña.
# La contraseña de un intento rechazado en los pasos 1 o 2 NUNCA se verifica:
# un robot no puede aprender nada insistiendo.
# =========================================================================

from django.shortcuts import redirect, render
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from models.models import Role
from security import auth, captchas, limiter

from .. import utils


# la página de inicio de cada rol, justo después del login: el nombre de su ruta
def home_page(role: str) -> str:
    return "area" if role == Role.USER else "schedule"


# GET /: la ruta es pública; el usuario, si lo hay, es conocido
@require_GET
def home(request):
    if request.user is not None:
        return redirect(home_page(request.user.role))
    return redirect("login")


# GET /login[?login=xxx]: el formulario; el parámetro opcional rellena previamente el
# campo login (se usa justo después de la creación de una cuenta, véase views/registration.py).
# POST /login: login
@require_http_methods(["GET", "POST"])
def login(request):
    if request.method == "POST":
        return log_in(request)
    # ya conectado (token todavía válido): directo a la página de inicio
    if request.user is not None:
        return redirect(home_page(request.user.role))
    # [:30]: 30 caracteres como máximo
    return page(request, request.GET.get("login", "")[:30], None)


def log_in(request):
    login = request.POST.get("login", "")
    password = request.POST.get("password", "")
    ip = utils.ip(request)
    # 1. ¿demasiados fallos recientes? ngettext: el singular o el plural, según el número
    minutes = limiter.login_block_minutes(ip, login)
    if minutes > 0:
        return page(request, login, ngettext(
            "Too many failed attempts. Try again in %(minutes)d minute.",
            "Too many failed attempts. Try again in %(minutes)d minutes.",
            minutes) % {"minutes": minutes})
    # 2. el captcha
    if not captchas.verify(request.POST.get("captcha_id", ""), request.POST.get("captcha", "")):
        limiter.login_failure(ip, login)
        return page(request, login, _("The characters you typed do not match the image. "
                                      "A new image is shown."))
    # 3. la contraseña
    user = auth.validate(login, password) if login and password else None
    if user is None:
        limiter.login_failure(ip, login)
        return page(request, login, _("Incorrect login or password."))
    limiter.login_success(ip, login)
    return auth.set_token(redirect(home_page(user.role)), user)


# POST /logout: borra la cookie del token y luego va a la página de login.
# Solo POST: un simple enlace (GET), puesto en otro sitio, no puede
# cerrar la sesión del usuario sin que se entere
@require_POST
def logout(request):
    return auth.clear_token(redirect("login"))


# el formulario, siempre con un captcha NUEVO (cada imagen se usa una sola
# vez); el login ingresado se muestra de nuevo, nunca la contraseña. Un error: el
# código 422, como en un formulario inválido (véase el ejemplo 19)
def page(request, login: str, error: str | None):
    return render(request, "login.html", {
        "page_title": _("Sign in"), "error": error, "login": login,
        "captcha": captchas.generate(),
    }, status=422 if error else 200)

El inicio de sesión, que sigue el Ejemplo 27:

  • líneas 28–29: la página de inicio de cada rol, junto con el nombre de su ruta: “Mi espacio” para un paciente y el calendario para los demás;
  • líneas 33–37: la dirección [/] redirige a la página de inicio del rol o a la página de inicio de sesión. La ruta es pública (security/access.py): [request.user] es el usuario establecido por el middleware [Authentication], si lo hay;
  • líneas 43–51: un usuario que ya inició sesión es llevado directamente a su página de inicio. El parámetro opcional [login] de la URL rellena previamente el campo (después de crear una cuenta); [[:30]] lo trunca a 30 caracteres;
  • líneas 54–76: el proceso de inicio de sesión, en el orden indicado en el Ejemplo 27: posible bloqueo, el CAPTCHA, la contraseña (el token anti-CSRF ya fue verificado por el middleware). Nunca se verifica una contraseña en un intento rechazado por el limitador o por el CAPTCHA: un bot no aprende nada al insistir. [ngettext(singular, plural, number)] (líneas 61–64) selecciona el formato apropiado para el número en el idioma de la solicitud (Ejemplo 22); el parámetro [%(minutes)d] se establece después de la traducción. Si el intento falla, la página se renderiza directamente (sin redirección): el formulario que se vuelve a mostrar siempre tiene un CAPTCHA nuevo y el inicio de sesión ingresado. Si tiene éxito, el contador de intentos de inicio de sesión se restablece a cero y el navegador es redirigido a la página de inicio del rol con la cookie del token;
  • líneas 82–84: el cierre de sesión elimina la cookie del token (Ejemplo 25). Solo acepta POST, junto con el token anti-CSRF: un simple enlace colocado en otro sitio no puede cerrar la sesión del usuario sin que este lo sepa;
  • líneas 90–94: la página de inicio de sesión. Se devuelve un error con el código 422 (Unprocessable Content), por ejemplo ante un formulario no válido (ejemplo 19).

La página de inicio de sesión recibe la variable [page_title], el título de la página, que ya está traducido: todas las vistas proporcionan este dato a su plantilla para la etiqueta [<title>] y el título de la página (véase más adelante).

11.17.5. web/views/schedule.py

# =========================================================================
# web/views/schedule.py: la página de la agenda: elección de un médico y un día,
# agenda de este médico ese día, reserva y cancelación de citas.
#
#   GET  /schedule?doctorId=1&day=2026-09-23              la página
#   GET  /schedule?doctorId=1&day=2026-09-23&book=7       la misma página, con el
#                                                         diálogo de reserva
#                                                         del horario 7 abierto
#   POST /schedule/book                                   crea una cita
#   POST /schedule/cancel                                 cancela una cita
#
# Toda la página se describe mediante su URL: se puede recargar, guardar como favorito,
# se puede usar el botón "Atrás" del navegador - sin una sola línea de
# JavaScript.
#
# Lo que cada uno ve y puede hacer:
#
#   | rol           | horario ocupado mostrado          | Reservar           | Cancelar|
#   |---------------|-----------------------------------|--------------------|---------|
#   | ADMIN, DOCTOR | nombre del paciente               | para un paciente   | sí      |
#   |               |                                   | elegido de una lista|        |
#   | USER (paciente)| "Reservado", o SU nombre si es   | para sí mismo, si  | no (*)  |
#   |               | su propia cita                    | no tiene una cita  |         |
#   |               |                                   | próxima            |         |
#
#   (*) el paciente cancela su cita desde su página "Mi área".
#
# CONFIDENCIALIDAD: para un paciente, el nombre de los OTROS pacientes no está
# simplemente oculto por la plantilla - nunca se pasa a la plantilla. El HTML
# enviado al navegador por lo tanto no lo contiene, ni siquiera oculto (de lo contrario un simple "Ver
# código fuente de la página" lo revelaría).
#
# Ninguna reserva en el pasado: el botón "Reservar" solo aparece para
# hoy y los días siguientes (y la capa de negocio la rechazaría
# de todos modos).
#
# Seguridad: todas las URL /schedule requieren un usuario autenticado y
# /schedule/cancel el rol ADMIN o DOCTOR (véase security/access.py).
# =========================================================================

from dataclasses import dataclass
from datetime import date
from urllib.parse import urlencode

from django.contrib import messages
from django.core.exceptions import BadRequest
from django.shortcuts import redirect, render
from django.urls import reverse
from django.utils.translation import gettext as _
from django.views.decorators.http import require_GET, require_POST

from domain.schedule import DoctorDaySchedule
from business import errors
from business.dates import today
from business.errors import BusinessError
from models.models import Client, Person, Role

from .. import utils
from ..application import application
from ..view_models import BookingView, OptionView, ScheduleRow, ScheduleView


# ¿quién está conectado y qué puede hacer en esta página?
@dataclass(frozen=True)
class Rights:
    manager: bool                      # ADMIN o DOCTOR
    patient: Client | None             # el cliente con sesión iniciada (rol USER), de lo contrario None
    patient_can_book: bool             # un USER sin una próxima cita


# -------------------------------------------------------------------------
# GET /schedule
# Los parámetros de la URL se leen sin procesar (request.GET), para distinguir un
# parámetro AUSENTE (None) de un parámetro VACÍO (?doctorId=).
# -------------------------------------------------------------------------
@require_GET
def show(request):
    error = None
    user = utils.user(request)
    rights = compute_rights(request)
    app = application()
    # el día: el de la URL si es válido; de lo contrario, hoy
    day = today()
    raw_day = request.GET.get("day")
    if raw_day is not None:
        requested_day = utils.valid_date(raw_day)
        if requested_day is not None:
            day = requested_day
        else:
            error = _("The requested date is not valid.")
    bookable_day = day >= today()
    # el médico: el de la URL; en su defecto, para un médico conectado, él mismo
    raw_doctor_id = request.GET.get("doctorId")
    doctor_id = utils.positive_integer(raw_doctor_id)
    if raw_doctor_id is None and user.role == Role.DOCTOR:
        doctor = app.get_doctor_by_user_id(user.user_id)
        doctor_id = doctor.id if doctor else None
    # la lista desplegable de los médicos
    doctors = [option(d, d.id == doctor_id) for d in app.get_all_doctors()]
    # la agenda, si se eligió un médico (y la fecha es válida)
    schedule = None
    if doctor_id is not None and error is None:
        doctor_schedule = app.get_doctor_day_schedule(doctor_id, day)
        if doctor_schedule is None:
            error = _("This doctor does not exist (any more).")
        else:
            schedule = schedule_view(doctor_schedule, rights, bookable_day)
    # el diálogo de reserva: solo si el horario solicitado puede ser reservado por
    # este usuario
    booking = None
    slot_id = utils.positive_integer(request.GET.get("book"))
    if schedule is not None and slot_id is not None:
        row = next((r for r in schedule.rows if r.slot_id == slot_id and r.bookable), None)
        if row is not None:
            booking = BookingView(
                row.slot_id,
                row.time_range,
                [option(c, False) for c in app.get_all_clients()] if rights.manager else [],
                rights.patient.label() if rights.patient else None)
    return render(request, "schedule.html", {
        "page_title": _("Schedule"),
        "error": error,
        "doctors": doctors,
        "doctor_id": doctor_id,
        "day": utils.iso(day),
        "schedule": schedule,
        "booking": booking,
        # la agenda mostrada, sin diálogo de reserva
        "back_url": schedule_url(doctor_id, day) if doctor_id is not None else reverse("schedule"),
        "info": patient_info(rights, schedule),
    })


# -------------------------------------------------------------------------
# POST /schedule/book   campos: doctorId, day, slotId, clientId
#
# Para un paciente (USER), el campo clientId se IGNORA: siempre reserva para
# sí mismo. Confiar en un campo enviado por el navegador permitiría a un
# paciente astuto reservar a nombre de otro.
#
# Patrón "Post / Redirect / Get": sea cual sea el resultado, aquí no se construye ninguna página
# - se deja un mensaje flash y se redirige a la agenda (véase el ejemplo 20).
# -------------------------------------------------------------------------
@require_POST
def book(request):
    doctor_id, day = requested_schedule(request)
    slot_id = utils.positive_integer(request.POST.get("slotId"))
    if doctor_id is None or slot_id is None:
        # -> página de "solicitud inválida" (véase web/middleware.py)
        raise BadRequest("invalid schedule or slot")
    app = application()
    user = utils.user(request)
    if user.is_patient:
        client = utils.connected_patient(request)
    else:
        client_id = utils.positive_integer(request.POST.get("clientId"))
        if client_id is None:
            # ningún paciente elegido: el diálogo de reserva se abre de nuevo
            messages.error(request, _("Choose a patient."))
            return redirect(schedule_url(doctor_id, day, slot_id))
        client = app.get_client_by_id(client_id)
    slot = app.get_slot_by_id(slot_id)
    if client is None:
        messages.error(request, _("This patient does not exist (any more)."))
    elif slot is None or slot.doctor_id != doctor_id:
        messages.error(request, _("This slot does not exist (any more)."))
    else:
        try:
            # las reglas (no en el pasado, una sola cita próxima por
            # paciente, horario libre) las verifica la capa de negocio
            app.add_appointment(day, slot, client)
            messages.success(request, _("Appointment booked."))
        except BusinessError as e:
            # misma regla, pero un mensaje en segunda persona cuando es el propio paciente
            # quien reserva ("Ya tiene..." en lugar de "Este paciente...").
            # Las otras excepciones (verdaderas anomalías) no se capturan: página 500
            if e.code == errors.PATIENT_HAS_APPOINTMENT and user.is_patient:
                messages.error(request, _("You already have an upcoming appointment: "
                                          "cancel it to book another one."))
            else:
                messages.error(request, e.message)
    return redirect(schedule_url(doctor_id, day))


# -------------------------------------------------------------------------
# POST /schedule/cancel   campos: appointmentId, doctorId, day
# (un paciente cancela SU cita desde "Mi área", no desde aquí)
# -------------------------------------------------------------------------
@require_POST
def cancel(request):
    doctor_id, day = requested_schedule(request)
    appointment_id = utils.positive_integer(request.POST.get("appointmentId"))
    if doctor_id is None or appointment_id is None:
        raise BadRequest("invalid schedule or appointment")
    app = application()
    appointment = app.get_appointment_by_id(appointment_id)
    if appointment is None:
        # ya cancelada (por otra persona, o por doble clic)
        messages.error(request, _("This appointment does not exist (any more)."))
    else:
        app.delete_appointment(appointment)
        messages.success(request, _("Appointment cancelled."))
    return redirect(schedule_url(doctor_id, day))


# -------------------------------------------------------------------------
# ¿quién está conectado y qué puede hacer en esta página?
# -------------------------------------------------------------------------
def compute_rights(request) -> Rights:
    if not utils.user(request).is_patient:
        return Rights(manager=True, patient=None, patient_can_book=False)
    patient = utils.connected_patient(request)
    upcoming = application().get_client_upcoming_appointments(patient.id)
    # not list: verdadero para una lista vacía
    return Rights(manager=False, patient=patient, patient_can_book=not upcoming)


# -------------------------------------------------------------------------
# la agenda del médico, formateada para la plantilla - y filtrada según los derechos
# -------------------------------------------------------------------------
def schedule_view(doctor_schedule: DoctorDaySchedule, rights: Rights, bookable_day: bool) -> ScheduleView:
    doctor_id = doctor_schedule.doctor.id
    day = doctor_schedule.day
    rows = []
    for dds in doctor_schedule.doctor_day_slots:
        slot = dds.slot
        appointment = dds.appointment
        free = appointment is None
        # ¿la cita del paciente conectado?
        me = appointment is not None and rights.patient is not None and appointment.client_id == rights.patient.id
        rows.append(ScheduleRow(
            slot_id=slot.id,
            time_range=slot.time_range(),
            free=free,
            # EL punto de confidencialidad: un paciente solo recibe el nombre de SU
            # cita; para las demás, None (la plantilla muestra "Reservado")
            patient=appointment.client.label() if appointment is not None and (rights.manager or me) else None,
            me=me,
            bookable=free and bookable_day and (rights.manager or rights.patient_can_book),
            book_url=schedule_url(doctor_id, day, slot.id),
            appointment_id=appointment.id if appointment is not None and rights.manager else None))
    return ScheduleView(doctor_schedule.doctor.label(), utils.format_day(day), rows)


# ----------------------------------------------------------------- funciones utilitarias
# los campos ocultos doctorId / day de los formularios POST; (None, None) si son
# inválidos
def requested_schedule(request) -> tuple[int | None, date | None]:
    doctor_id = utils.positive_integer(request.POST.get("doctorId"))
    day = utils.valid_date(request.POST.get("day"))
    return (None, None) if doctor_id is None or day is None else (doctor_id, day)


# /schedule?doctorId=1&day=2026-09-23[&book=7]: reverse construye el path de la
# ruta, urlencode los parámetros de la URL, correctamente codificados (véase el ejemplo 04)
def schedule_url(doctor_id: int, day: date, book: int | None = None) -> str:
    parameters = {"doctorId": doctor_id, "day": utils.iso(day)}
    if book is not None:
        parameters["book"] = book
    return f"{reverse('schedule')}?{urlencode(parameters)}"


def option(p: Person, selected: bool) -> OptionView:
    return OptionView(p.id, p.label(), selected)


# -------------------------------------------------------------------------
# el mensaje informativo de un paciente que ya tiene una cita próxima (por qué
# no hay botón "Reservar"), o None. Inútil si SU cita aparece
# en la agenda mostrada (en azul): es el caso justo después de que la
# reservó, cuando el mensaje estaría fuera de lugar
# -------------------------------------------------------------------------
def patient_info(rights: Rights, schedule: ScheduleView | None) -> str | None:
    if rights.patient is None or rights.patient_can_book:
        return None
    appointment_shown = schedule is not None and any(r.me for r in schedule.rows)
    return None if appointment_shown else _("You already have an upcoming appointment: "
                                            "cancel it to book another one.")

La página principal de la aplicación. El comentario de encabezado resume lo que cada usuario ve y puede hacer.

11.17.5.1. Los elementos de la URL de la página

Toda la página está descrita por su URL: [/schedule?doctorId=1&day=2026-09-30] muestra la agenda del médico 1 para ese día; [&book=4] abre además la ventana para reservar la franja 4. Se puede recargar la página, guardarla como marcador o usar el botón Atrás del navegador sin una sola línea de [JavaScript]. El formulario de la parte superior de la página (para seleccionar el médico y el día) es un formulario GET (ejemplo 17): recarga la página con nuevos parámetros. La ventana de reserva de citas se abre con un simple enlace y se cierra con un enlace a la misma página sin el parámetro [book].

11.17.5.2. GET /schedule

Líneas 76–131:

  • los parámetros de la URL se leen como datos sin procesar ([request.GET.get("day")]), sin un formulario: un parámetro ausente ([None]) no es un error (se asume el día de hoy o ningún médico); una fecha no válida es un error, que se muestra en la parte inferior de la página (las selecciones de médico y día permanecen visibles, pero no el calendario); un número de médico o de franja horaria que no sea un entero positivo simplemente se ignora;
  • un usuario conectado que no ha seleccionado un médico ve su propia agenda: el sistema busca a su médico a partir de su cuenta ([get_doctor_by_user_id]);
  • la lista desplegable de médicos: una lista por comprensión convierte el nombre de cada médico en [OptionView];
  • el calendario, formateado y filtrado según los permisos del usuario ([schedule_view], más abajo);
  • la ventana de reserva, solo si el usuario puede reservar la franja horaria solicitada: un paciente que intente generar la URL [&book=2] para una franja ya reservada no obtendría nada. [next(...)] devuelve la primera fila del calendario correspondiente, o [None]. La lista de pacientes se proporciona solo al administrador y a los médicos; un paciente ve únicamente su propio nombre;
  • la plantilla recibe sus variables ([render], ejemplo 13), entre ellas [page_title] y [error], que lee la plantilla base.

11.17.5.3. POST /schedule/book

Líneas 144–182:

  • los campos ocultos del formulario de la cita (médico, día, franja horaria). Si no son válidos, solo puede tratarse de una solicitud creada manualmente: [BadRequest], la página de “solicitud no válida” (400), a través del middleware [ErrorPage];
  • Para un paciente, el campo [clientId] se ignora: el paciente siempre reserva para sí mismo ([utils.connected_patient]). Confiar en un campo enviado por el navegador permitiría que un paciente malintencionado hiciera una reserva a nombre de otra persona. Para el administrador y los médicos, debe haberse seleccionado un paciente; de lo contrario, la ventana de reserva se vuelve a abrir con un mensaje;
  • la franja horaria debe pertenecer al médico de la página ([slot.doctor_id]: la clave externa, sin consulta);
  • las reglas de negocio (no en el pasado, una sola cita próxima, franja horaria disponible) las verifica la capa de negocio. Un [BusinessError] se convierte en un mensaje de error flash. El mismo rechazo, “una cita próxima”, se muestra a la segunda persona en nombre del propio paciente (“Ya tiene…”). Cualquier otra excepción no se intercepta: es un error real (página 500);
  • en todos los casos se aplica el patrón Post/Redirect/Get (ejemplo 20): un mensaje emergente y una redirección al calendario.

11.17.5.4. POST /schedule/cancel

Líneas 189–203: cancelación de una cita por parte del administrador o de un médico (regla [^/schedule/cancel$] derivada de [security/access.py]). Una cita que ya no existe (porque alguien más ya la canceló, o por un doble clic) no es un error: solo se muestra un mensaje.

11.17.5.5. Permisos, calendario formateado y funciones de utilidad

  • líneas 64–68 y 209–215: lo que el usuario está autorizado a hacer en la página, dentro de una clase de datos: ¿es el usuario un administrador (ADMIN o DOCTOR)? ¿un paciente (y cuál)? ¿Puede este paciente hacer una reserva (sin citas próximas)? [not list] es verdadero para una lista vacía;
  • Líneas 221–242: la agenda del médico, convertida en filas para la plantilla. El problema de la confidencialidad está en la línea 237: a un paciente solo se le muestra el nombre de su propia cita. Para los demás, el atributo [patient] se establece en [None], y la plantilla muestra “Reservada”. El nombre no lo oculta la plantilla: nunca se transmite a la plantilla y, por lo tanto, no aparece en el código fuente de la página, donde sería fácil de leer. El botón “Reservar” se muestra para una franja disponible en una fecha futura a un administrador o a un paciente que puede hacer una reserva; el botón “Cancelar” se muestra solo a los administradores. Los parámetros con nombre ([slot_id=slot.id]) hacen legible la construcción de un objeto con ocho atributos;
  • líneas 248–251: los campos ocultos de los formularios POST. La función devuelve una tupla, que la vista desempaqueta en dos variables ([doctor_id, day = requested_schedule(request)], líneas 146 y 191);
  • líneas 256–260: la URL de la agenda de un médico en un día determinado. [reverse("schedule")] devuelve la ruta; [urlencode] genera los parámetros, codificados correctamente: [/schedule?doctorId=1&day=2026-09-30];
  • líneas 273–278: el mensaje que explica a un paciente por qué no hay botón “Reservar” (ya tiene una cita próxima), a menos que esa cita esté en el calendario mostrado (inmediatamente después de reservarla, el mensaje se desplazaría). [any(...)]: ¿alguna fila cumple la condición?

11.17.6. web/views/persons.py

# =========================================================================
# web/views/persons.py: la gestión de médicos y la de clientes (reservadas al
# ADMIN) son IDÉNTICAS: misma lista, mismo formulario, mismas reglas. En lugar de
# escribir dos veces las mismas vistas, se escriben una sola vez, como los MÉTODOS
# de una clase, PersonManagement; dos OBJETOS de esta clase, doctors y
# clients, solo difieren en lo que los distingue: el nombre de la sección
# (médicos o clientes), los textos y los métodos del ApplicationModel a llamar.
#
# Un método de un objeto se llama con el objeto (self): la vista object.list(request)
# sabe así de qué sección se trata. El método urls() construye las rutas de
# la sección:
#
#   GET  /doctors                    lista                     doctors_list
#   GET  /doctors/add                formulario vacío          doctors_add
#   POST /doctors/add                creación                  doctors_add
#   GET  /doctors/{id}/edit          formulario rellenado      doctors_edit
#   POST /doctors/{id}/edit          actualización             doctors_edit
#   POST /doctors/{id}/delete        eliminación               doctors_delete
#
# (y las mismas URL bajo /clients). Las plantillas también son comunes:
# templates/persons/list.html y persons/form.html.
#
# SEGURIDAD: la regla ^/(doctors|clients) de security/access.py reserva todas estas
# URL al ADMIN - incluidas las que se agreguen más tarde.
# =========================================================================

from collections.abc import Callable
from dataclasses import dataclass

from django.contrib import messages
from django.http import Http404
from django.shortcuts import redirect, render
from django.urls import path, reverse
from django.utils.translation import gettext_lazy as _
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from business import errors
from business.errors import BusinessError
from models.models import Person

from ..application import application
from ..forms import PersonForm

# los campos del formulario afectados por cada error de negocio de "ingreso" (un
# duplicado): se enmarcan en rojo, con el mensaje al pie de la página
BUSINESS_ERROR_FIELDS = {
    errors.LOGIN_TAKEN: ["login"],
    errors.DOCTOR_ALREADY_EXISTS: ["first_name", "last_name"],
    errors.CLIENT_ALREADY_EXISTS: ["first_name", "last_name"],
}


# los textos propios de cada tipo de persona; %(name)s, %(login)s: los
# parámetros de los mensajes
@dataclass(frozen=True)
class Texts:
    title: str                  # "Doctors"
    add: str                    # "Add a doctor"
    edit: str                   # "Edit a doctor"
    empty: str                  # "No doctors."
    confirm_delete: str         # "Delete this doctor... ?"
    added: str                  # "Doctor %(name)s has been added (login: %(login)s)."
    updated: str
    deleted: str


class PersonManagement:
    def __init__(self, section: str, texts: Texts, list_all: Callable, find: Callable,
                 create: Callable, update: Callable, remove: Callable):
        # "doctors" o "clients": el inicio de la ruta y del nombre de las rutas
        self.section = section
        self.texts = texts
        # los métodos del ApplicationModel a llamar (funciones, véase más abajo)
        self.list_all = list_all
        self.find = find
        self.create = create
        self.update = update
        self.remove = remove

    # las rutas de la sección; self.list: el método enlazado a ESTE objeto
    def urls(self):
        s = self.section
        return [
            path(f"{s}", require_GET(self.list), name=f"{s}_list"),
            path(f"{s}/add", require_http_methods(["GET", "POST"])(self.add), name=f"{s}_add"),
            path(f"{s}/<int:id>/edit", require_http_methods(["GET", "POST"])(self.edit),
                 name=f"{s}_edit"),
            path(f"{s}/<int:id>/delete", require_POST(self.delete), name=f"{s}_delete"),
        ]

    # -------------------------------------------------------------------
    # GET /doctors (o /clients)
    # -------------------------------------------------------------------
    def list(self, request):
        return render(request, "persons/list.html", {
            "page_title": self.texts.title, "texts": self.texts, "section": self.section,
            "add_url": reverse(f"{self.section}_add"), "persons": self.list_all()})

    # -------------------------------------------------------------------
    # GET /doctors/add: el formulario vacío; POST: la creación
    # -------------------------------------------------------------------
    def add(self, request):
        if request.method == "GET":
            return self.page(request, PersonForm(initial={"title": "Mr"}), None)
        form = PersonForm(request.POST)
        if not form.is_valid():
            return self.page(request, form, None)
        try:
            person = self.create(form.person_data())
        except BusinessError as e:
            return self.business_error(request, e, form, None)
        messages.success(request, str(self.texts.added) % parameters(person))
        return redirect(f"{self.section}_list")

    # -------------------------------------------------------------------
    # GET /doctors/{id}/edit: el formulario rellenado; POST: la actualización.
    # <int:id>: un parámetro formado por dígitos (véase el ejemplo 02):
    # /doctors/abc/edit no coincide con ninguna ruta (página 404)
    # -------------------------------------------------------------------
    def edit(self, request, id):
        person = self.find(id)
        if person is None:
            raise Http404("unknown person")
        if request.method == "GET":
            # el formulario, rellenado con los valores de la persona (la
            # contraseña en sí nunca se muestra)
            form = PersonForm(creation=False, initial={
                "title": person.title, "first_name": person.first_name, "last_name": person.last_name,
                "login": person.account.login, "version": person.version})
            return self.page(request, form, person)
        form = PersonForm(request.POST, creation=False)
        if not form.is_valid():
            return self.page(request, form, person)
        try:
            person = self.update(id, form.person_data())
        except BusinessError as e:
            return self.business_error(request, e, form, person)
        messages.success(request, str(self.texts.updated) % parameters(person))
        return redirect(f"{self.section}_list")

    # -------------------------------------------------------------------
    # POST /doctors/{id}/delete (la confirmación "¿Está seguro?" se solicita
    # antes de enviar el formulario, véase static/js/app.js)
    # -------------------------------------------------------------------
    def delete(self, request, id):
        person = self.find(id)
        try:
            self.remove(id)
            messages.success(request, str(self.texts.deleted) % parameters(person))
        except BusinessError as e:
            messages.error(request, e.message)
        return redirect(f"{self.section}_list")

    # ----------------------------------------------------------------- funciones internas
    # person None: formulario de creación; en caso contrario: formulario de actualización.
    # Un formulario rechazado (ingreso inválido o regla de negocio): el código 422
    def page(self, request, form, person, error=None, invalid_fields=()):
        refused = error is not None or (form.is_bound and bool(form.errors))
        title = self.texts.add if person is None else self.texts.edit
        return render(request, "persons/form.html", {
            "page_title": title,
            "form": form.flag(invalid_fields),
            "error": error,
            "list_url": reverse(f"{self.section}_list"),
        }, status=422 if refused else 200)

    # una regla de negocio rechazó la escritura: el formulario se muestra de nuevo, con
    # lo ingresado por el usuario (sin la contraseña), el mensaje de la capa de
    # negocio (al pie de la página) y los campos afectados, si los hay, enmarcados en
    # rojo para que el usuario vea de inmediato qué debe corregir
    def business_error(self, request, e: BusinessError, form, person):
        if e.code in (errors.DOCTOR_NOT_FOUND, errors.CLIENT_NOT_FOUND):
            # eliminado mientras tanto por otro ADMIN: de vuelta a la lista
            messages.error(request, e.message)
            return redirect(f"{self.section}_list")
        return self.page(request, form, person, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))


# los parámetros %(name)s y %(login)s de los mensajes de "agregado / actualizado / eliminado"
def parameters(person: Person | None) -> dict:
    if person is None:
        return {"name": "", "login": ""}
    return {"name": f"{person.first_name} {person.last_name}", "login": person.account.login}


# -------------------------------------------------------------------------
# los dos objetos. lambda: una pequeña función anónima, que llama al método adecuado
# del ApplicationModel en el momento de la solicitud. Los textos se traducen
# de forma "perezosa" (gettext_lazy): en el momento de mostrarlos, en el
# idioma de la solicitud, y no cuando se carga el módulo
# -------------------------------------------------------------------------

doctors = PersonManagement(
    "doctors",
    Texts(_("Doctors"), _("Add a doctor"), _("Edit a doctor"), _("No doctors."),
          _("Delete this doctor, their time slots and their user account?"),
          _("Doctor %(name)s has been added (login: %(login)s)."),
          _("Doctor %(name)s has been updated."), _("Doctor %(name)s has been deleted.")),
    list_all=lambda: application().get_all_doctors(),
    find=lambda id: application().get_doctor_by_id(id),
    create=lambda data: application().add_doctor(data),
    update=lambda id, data: application().edit_doctor(id, data),
    remove=lambda id: application().delete_doctor(id))

clients = PersonManagement(
    "clients",
    Texts(_("Patients"), _("Add a patient"), _("Edit a patient"), _("No patients."),
          _("Delete this patient, their user account and all their appointments?"),
          _("Patient %(name)s has been added (login: %(login)s)."),
          _("Patient %(name)s has been updated."), _("Patient %(name)s has been deleted.")),
    list_all=lambda: application().get_all_clients(),
    find=lambda id: application().get_client_by_id(id),
    create=lambda data: application().add_client(data),
    update=lambda id, data: application().edit_client(id, data),
    remove=lambda id: application().delete_client(id))

La gestión de médicos y clientes es idéntica: la misma lista, el mismo formulario, las mismas reglas. Las vistas se escriben una sola vez, como los métodos de una clase, [PersonManagement]; dos objetos de esta clase, [doctors] y [clients], se diferencian solo en lo que los distingue: el nombre de la sección, los textos y los métodos de [ApplicationModel] que se deben invocar. Una vista no tiene que ser una función: es cualquier objeto invocable que recibe una solicitud y devuelve una respuesta. [self.list], un método asociado a un objeto, es una de esas vistas: [Django] lo invoca con la solicitud, y el método recibe además su objeto ([self]), que es su sección. Para agregar una vista a las secciones de gestión de médicos y de clientes, basta con escribirla aquí.

  • Líneas 46–50: los campos afectados por cada error de entrada de la capa de negocio: un nombre de usuario duplicado afecta al campo “login”; un conflicto de nombres afecta a los campos “nombre” y “apellido”. Estos campos se resaltarán en rojo;
  • Líneas 55–64: los textos específicos de cada sección, en una clase de datos;
  • líneas 68–78: el constructor. Los últimos cinco parámetros son funciones ([Callable]): leer la lista, buscar, crear, modificar o eliminar una persona;
  • líneas 81–89: las rutas de la sección. Los decoradores se invocan aquí como funciones ([require_GET(self.list)]: la vista decorada [self.list]): es exactamente lo que hace la sintaxis [@require_GET] cuando se coloca sobre una función (Ejemplo 02). El prefijo de la ruta y de los nombres de las rutas es la sección: la vista [list] se convierte en las rutas [doctors_list] ([/doctors]) y [clients_list] ([/clients]);
  • líneas 94–97: la lista. La plantilla es compartida por ambas secciones: recibe el texto de la sección y la URL del botón de agregar;
  • líneas 102–113: la función de agregar. Una sola vista para GET (el formulario vacío, con el título [Mr] seleccionado mediante [initial], Ejemplo 18) y POST (creación), como se muestra en el Ejemplo 19. Una entrada no válida vuelve a mostrar el formulario. Una entrada válida pasa a la capa de negocio, que puede rechazar la operación de escritura (por un homónimo o un login ya en uso); de lo contrario, se muestra un mensaje flash de éxito y el usuario regresa a la lista (patrón PRG). El texto del mensaje es una traducción diferida: [str(...)] lo traduce antes de que el operador [%]inserte sus parámetros;
  • líneas 120–139: la actualización, para una persona que existe; de lo contrario, [Http404] devuelve una página 404. [<int:id>] acepta solo números para el parámetro [id] (p. ej., 02) y lo convierte en un entero. El formulario GET se rellena previamente con los valores de la persona y su versión; un formulario POST recibe los datos ingresados;
  • líneas 145–152: la eliminación. El formulario solicitó confirmación en el navegador (ejemplo 21). La persona se recupera antes de eliminarla para el mensaje de éxito (“Se eliminó al médico Paul TATOU.”);
  • líneas 157–165: el formulario, para la creación ([person] es igual a [None]) o la modificación. Un formulario rechazado (entrada no válida o infracción de una regla de negocio) se devuelve con el código de estado 422 (ejemplo 19). Aquí, [flag] resalta en rojo los campos con errores;
  • líneas 171–176: la capa de negocio rechazó la operación de escritura. Si una persona fue eliminada mientras tanto (por otro administrador): regreso a la lista. De lo contrario, el formulario se vuelve a mostrar directamente (sin redirección), como en un error de entrada: ya contiene los datos ingresados por el usuario. A esto se suman el mensaje de la capa de negocio (que se muestra en la parte inferior de la página, en el área de errores) y los campos que se deben resaltar en rojo;
  • líneas 180–183: los parámetros [%(name)s] y [%(login)s] para los mensajes de éxito;
  • líneas 193–215: los dos objetos. Cada [lambda] invoca el método correspondiente de [ApplicationModel] cuando se realiza la solicitud: la fachada no se crea al cargar el módulo, sino la primera vez que se usa.

11.17.7. web/views/registration.py

# =========================================================================
# web/views/registration.py: "Crear una cuenta de paciente": un paciente que todavía no
# tiene cuenta la crea él mismo. Rutas PÚBLICAS (todavía no se tiene cuenta,
# por definición):
#
#   POST /register/access     botón "Crear una cuenta de paciente" de la
#                             página de autenticación: verifica el captcha de ESTA
#                             página y luego abre el formulario
#   GET  /register            el formulario
#   POST /register            la creación, y luego de vuelta a la página de login
#
# El camino está protegido contra robots por UN solo captcha, el de la
# página de autenticación:
#   1. el botón "Crear una cuenta de paciente" envía el formulario de login a
#      /register/access; si el captcha se escribe correctamente, el servidor emite un
#      pase (véase security/registration_pass.py);
#   2. sin un pase válido, /register devuelve a la
#      página de autenticación (decorador @registration_pass_required);
#   3. el pase se consume en la creación: un captcha resuelto permite la creación de
#      UNA cuenta;
#   4. además, se limita el número de cuentas creadas por hora y por dirección IP
#      (véase security/limiter.py).
#
# La cuenta creada es exactamente la que crearía el ADMIN desde la página "Pacientes"
# (mismo método de la capa de negocio: add_client), salvo que el paciente
# ELIGE su login y su contraseña (obligatorios, con confirmación).
# =========================================================================

from urllib.parse import urlencode

from django.contrib import messages
from django.shortcuts import redirect, render
from django.urls import reverse
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_http_methods, require_POST

from business.errors import BusinessError
from security import captchas, limiter, registration_pass
from security.registration_pass import registration_pass_required

from .. import utils
from ..application import application
from ..forms import RegistrationForm
from .persons import BUSINESS_ERROR_FIELDS


# el mensaje de "demasiadas cuentas creadas", en singular o en plural
def too_many_accounts(minutes: int) -> str:
    return ngettext(
        "Too many accounts have been created from your connection. Try again in %(minutes)d minute.",
        "Too many accounts have been created from your connection. Try again in %(minutes)d minutes.",
        minutes) % {"minutes": minutes}


# -------------------------------------------------------------------------
# POST /register/access   campos: captcha_id, captcha (los de la
# página de autenticación; login y contraseña, también enviados, se ignoran)
# -------------------------------------------------------------------------
@require_POST
def access(request):
    ip = utils.ip(request)
    # demasiadas cuentas creadas recientemente desde esta dirección: no tiene sentido seguir
    minutes = limiter.registration_block_minutes(ip)
    if minutes > 0:
        messages.error(request, too_many_accounts(minutes))
        return redirect("login")
    # captcha ausente o incorrecto: de vuelta a la página de autenticación, con una
    # nueva imagen (un fallo cuenta como un fallo de login)
    if not captchas.verify(request.POST.get("captcha_id", ""), request.POST.get("captcha", "")):
        limiter.login_failure(ip, "")
        messages.error(request, _("To create an account, first type the characters shown in the image "
                                  "correctly, then click \"Create a patient account\"."))
        return redirect("login")
    # captcha correcto: se emite el pase y se abre el formulario
    return registration_pass.issue(redirect("registration"))


# -------------------------------------------------------------------------
# GET /register: el formulario; POST /register: la creación. El
# pase se verificó ANTES de la llamada a la vista (@registration_pass_required).
# El formulario valida TODO lo ingresado (campos y confirmación de contraseña):
# el usuario corrige todos sus errores de una sola vez
# -------------------------------------------------------------------------
@require_http_methods(["GET", "POST"])
@registration_pass_required
def registration(request):
    if request.method == "GET":
        return page(request, RegistrationForm(initial={"title": "Mr"}))
    form = RegistrationForm(request.POST)
    if not form.is_valid():
        return page(request, form)
    ip = utils.ip(request)
    # 1. ¿demasiadas cuentas creadas recientemente desde esta dirección?
    minutes = limiter.registration_block_minutes(ip)
    if minutes > 0:
        return page(request, form, too_many_accounts(minutes))
    # 2. la creación (cliente + cuenta USER, en una transacción)
    data = form.person_data()
    try:
        application().add_client(data)
    except BusinessError as e:
        # login o nombre + apellido ya usados: el pase sigue siendo válido
        return page(request, form, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))
    # 3. el pase se ha usado: no permitirá la creación de una 2.ª cuenta
    registration_pass.consume(request.COOKIES.get(registration_pass.COOKIE))
    limiter.registration_success(ip)
    # 4. de vuelta a la página de login, con el login rellenado
    messages.success(request, _("Your account has been created. You can now log in with "
                                "the login %(login)s.") % {"login": data.login})
    url = f"{reverse('login')}?{urlencode({'login': data.login})}"
    return registration_pass.clear_cookie(redirect(url))


# el formulario; un formulario rechazado: el código 422
def page(request, form, error=None, invalid_fields=()):
    refused = error is not None or (form.is_bound and bool(form.errors))
    return render(request, "registration.html", {
        "page_title": _("Create a patient account"),
        "form": form.flag(invalid_fields), "error": error,
    }, status=422 if refused else 200)

El paciente crea él mismo una cuenta de paciente. El flujo está protegido por un CAPTCHA, el mismo que se usa en la página de inicio de sesión.

  • Líneas 59–75: el botón “Crear una cuenta de paciente” de la página de inicio de sesión envía el formulario de inicio de sesión a esta dirección (que más adelante se convierte en la plantilla [login.html]). Si se han creado demasiadas cuentas recientemente desde esta dirección (IP), no es necesario continuar. Si falta el CAPTCHA o es incorrecto: regreso a la página de inicio de sesión con una imagen nueva y un mensaje; el fallo cuenta como un intento fallido de inicio de sesión (con un nombre de usuario vacío). Si el CAPTCHA es correcto: se almacena un token en una cookie y el usuario es redirigido al formulario;
  • líneas 84–91: el formulario. El decorador [@registration_pass_required] (línea 85) verifica el token antes de invocar la vista. El orden de los decoradores importa: el más cercano a la función se aplica primero; [require_http_methods], colocado encima, rechaza por lo tanto un método no permitido antes de cualquier otra verificación. El formulario valida toda la entrada, incluida la confirmación de la contraseña: el usuario ve todos sus errores a la vez;
  • Líneas 92–111: la creación de la cuenta. El cliente y su cuenta se crean con el mismo método de la capa de negocio que para el administrador ([add_client]); solo el nombre de usuario y la contraseña los elige el paciente. Si un nombre de usuario o un homónimo ya está en uso: regreso al formulario sin consumir el token. Crear una cuenta consume el token (un CAPTCHA resuelto equivale a una cuenta), cuenta para el límite por hora y redirige a la página de inicio de sesión con el nombre de usuario prellenado (parámetro [?login=...], generado por [urlencode]), junto con un mensaje de éxito. La cookie de pase se elimina.

11.17.8. web/views/area.py

# =========================================================================
# web/views/area.py: las páginas PERSONALES del paciente (rol USER), la que
# ve justo después de iniciar sesión:
#
#   GET  /my-area                  página de inicio: [Gestionar mi cuenta], [Ver una
#                                  agenda] y su próxima cita
#   POST /my-area/cancel           cancela SU cita
#   GET  /my-account               formulario de actualización de su cuenta
#   POST /my-account               actualización
#   POST /my-account/delete        eliminación de la cuenta (y de sus citas)
#
# Regla de oro de este módulo: el paciente afectado es SIEMPRE el del token
# (utils.connected_patient), nunca un identificador enviado por el navegador. Un
# paciente no puede por lo tanto ver, ni modificar, ni cancelar lo que pertenece a otro
# paciente, ni siquiera construyendo él mismo sus solicitudes.
#
# Toda actualización o eliminación de la cuenta exige la contraseña ACTUAL:
# alguien que encontrara una sesión abierta no podría ni cambiar la
# contraseña ni eliminar la cuenta. Los errores de contraseña actual se
# cuentan como fallos de login (mismo límite).
#
# Seguridad: todas estas URL están reservadas al rol USER (regla ^/my- de
# security/access.py).
# =========================================================================

from django.contrib import messages
from django.shortcuts import redirect, render
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from business.errors import BusinessError
from models.models import Client
from security import auth, limiter

from .. import utils
from ..application import application
from ..forms import MyAccountForm
from ..view_models import AppointmentView
from .schedule import schedule_url
from .persons import BUSINESS_ERROR_FIELDS


# -------------------------------------------------------------------------
# GET /my-area
# -------------------------------------------------------------------------
@require_GET
def area(request):
    patient = utils.connected_patient(request)
    appointments = [AppointmentView(
        a.id,
        utils.format_day(a.day),
        a.slot.time_range(),
        a.slot.doctor.label(),
        # enlace a la agenda del médico ese día: el paciente ve allí su nombre
        schedule_url(a.slot.doctor_id, a.day))
        for a in application().get_client_upcoming_appointments(patient.id)]
    return render(request, "area.html", {"page_title": _("My area"),
                                         "patient": patient.label(), "appointments": appointments})


# -------------------------------------------------------------------------
# POST /my-area/cancel   campo: appointmentId
# -------------------------------------------------------------------------
@require_POST
def cancel_appointment(request):
    patient = utils.connected_patient(request)
    appointment_id = utils.positive_integer(request.POST.get("appointmentId"))
    appointment = application().get_appointment_by_id(appointment_id) if appointment_id is not None else None
    # una cita que no existe y la de OTRO paciente reciben la misma
    # respuesta: no se revela nada sobre las citas de los demás
    if appointment is None or appointment.client_id != patient.id:
        messages.error(request, _("This appointment does not exist (any more)."))
    else:
        application().delete_appointment(appointment)
        messages.success(request, _("Appointment cancelled."))
    return redirect("area")


# -------------------------------------------------------------------------
# GET /my-account: el formulario, rellenado con los valores del paciente;
# POST /my-account: la actualización
# -------------------------------------------------------------------------
@require_http_methods(["GET", "POST"])
def account(request):
    patient = utils.connected_patient(request)
    if request.method == "GET":
        return page(request, MyAccountForm(initial={
            "title": patient.title, "first_name": patient.first_name, "last_name": patient.last_name,
            "login": patient.account.login, "version": patient.version}))
    form = MyAccountForm(request.POST)
    if not form.is_valid():
        return page(request, form)
    # la contraseña actual; si es incorrecta: el mensaje va DEBAJO del campo (un error agregado
    # al campo mediante add_error) y al pie de la página
    error = check_current_password(request, patient, form.cleaned_data["current_password"])
    if error is not None:
        form.add_error("current_password", error)
        return page(request, form, error)
    try:
        client = application().edit_client(patient.id, form.person_data())
    except BusinessError as e:
        return page(request, form, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))
    # el login y el nombre mostrado están EN el token: se emite uno nuevo, de lo contrario
    # la barra de navegación conservaría el nombre anterior
    messages.success(request, _("Your account has been updated."))
    return auth.set_token(redirect("area"), client.account)


# -------------------------------------------------------------------------
# POST /my-account/delete   campo: current_password
# La cuenta, el cliente y TODAS sus citas desaparecen juntos, y luego el
# paciente cierra sesión.
# -------------------------------------------------------------------------
@require_POST
def delete_account(request):
    patient = utils.connected_patient(request)
    error = check_current_password(request, patient, request.POST.get("current_password", ""))
    if error is not None:
        messages.error(request, error)
        return redirect("account")
    application().delete_client(patient.id)
    messages.success(request, _("Your account has been deleted."))
    return auth.clear_token(redirect("login"))


# ----------------------------------------------------------------- funciones internas
# la página de la cuenta; un formulario rechazado: el código 422
def page(request, form, error=None, invalid_fields=()):
    refused = error is not None or (form.is_bound and bool(form.errors))
    return render(request, "account.html", {
        "page_title": _("Manage my account"),
        "form": form.flag(invalid_fields), "error": error,
    }, status=422 if refused else 200)


# None si la contraseña actual es correcta; de lo contrario, el mensaje de error
def check_current_password(request, patient: Client, password: str) -> str | None:
    ip = utils.ip(request)
    login = patient.account.login
    minutes = limiter.login_block_minutes(ip, login)
    if minutes > 0:
        return ngettext("Too many failed attempts. Try again in %(minutes)d minute.",
                        "Too many failed attempts. Try again in %(minutes)d minutes.",
                        minutes) % {"minutes": minutes}
    if not password or auth.validate(login, password) is None:
        limiter.login_failure(ip, login)
        return _("Incorrect current password.")
    return None

Las páginas personales del paciente. La regla de oro de este módulo: el paciente en cuestión es siempre el asociado al token ([utils.connected_patient]), nunca un identificador enviado por el navegador. Por lo tanto, un paciente no puede ver, modificar ni cancelar información de otro paciente, aunque genere sus propias solicitudes.

  • Líneas 46–58: Mi espacio: el nombre del paciente y sus próximas citas, formateadas ([AppointmentView]), cada una con un enlace a la agenda del médico para ese día. La función [schedule_url] forma parte del módulo del calendario (línea 39, [from .schedule import schedule_url]);
  • líneas 64–76: la cancelación de su cita. Tanto una cita inexistente como la cita de otro paciente reciben la misma respuesta: no se revela ninguna información sobre las citas de otros pacientes (ni siquiera su existencia);
  • líneas 83–92: el formulario “Administrar mi cuenta”, rellenado previamente con los datos del paciente, y su envío;
  • líneas 95–106: la modificación. Toda modificación requiere la contraseña actual: alguien que encontrara una sesión abierta no podría cambiar la contraseña ni hacer nada más. Si la contraseña actual es incorrecta, el formulario se vuelve a mostrar, con el mensaje debajo del campo y en la parte inferior de la página. [add_error(field, message)] agrega un error a un campo, como si la validación lo hubiera detectado (ejemplo 19). Después de la modificación se genera un nuevo token: el login y el nombre mostrado están incluidos en el token, y de lo contrario la barra de navegación conservaría el nombre anterior hasta el siguiente inicio de sesión;
  • líneas 114–123: la eliminación de la cuenta, del cliente y de todas sus citas, con el mismo método de la capa de negocio que para el administrador. Este segundo formulario de la página está codificado a mano (un solo campo: la contraseña actual). Luego se cierra la sesión del paciente (se elimina la cookie del token);
  • líneas 137–148: verificación de la contraseña actual. Está sujeta al limitador de intentos, igual que un inicio de sesión: sin esto, alguien con una sesión abierta podría probar miles de contraseñas mediante el formulario “Administrar mi cuenta” y descubrir la correcta.

11.18. Las plantillas

Las plantillas de la carpeta [templates] (configuración [TEMPLATES] derivada de [config/settings.py]): una plantilla padre, fragmentos, fragmentos de formulario con nombre y páginas.

11.18.1. La plantilla padre y los fragmentos

11.18.1.1. templates/layout.html

<!doctype html>
{% comment %}
  =========================================================================
  templates/layout.html
  -------------------------------------------------------------------------
  La plantilla PADRE de todas las páginas (ver ejemplo 15): cada página
  (schedule.html, login.html...) la EXTIENDE ({% extends %}) y rellena su
  bloque [content].

  Django ESCAPA todo lo que muestra con {{ ... }} (los caracteres < > & " '
  se convierten en &lt; &gt;...): protección contra la inyección de HTML a través de un
  nombre ingresado, por ejemplo. Para insertar HTML tal cual, hay que solicitarlo
  explícitamente (filtro safe, ver fragments/captcha.html).

  Mensajes: un éxito se muestra en la PARTE SUPERIOR de la página, un error en la PARTE INFERIOR, sobre un fondo
  rosa claro (etiquetas success_zone y error_zone, ver web/templatetags/rdv.py).

  La plantilla comparte las variables de la página: [page_title] (el título de la
  página, transmitido por la vista, ya traducido). LANGUAGE_CODE: el idioma de la
  solicitud (ver web/middleware.py).
  =========================================================================
{% endcomment %}
{% load static i18n rdv %}
<html lang="{{ LANGUAGE_CODE }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ page_title }} - RdvMedecins</title>
  {# static: la URL de un archivo de la carpeta static #}
  <link rel="stylesheet" href="{% static 'lib/bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-4">
    {% include "fragments/navbar.html" %}
    {% success_zone %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {% error_zone %}
  </div>
  {# el cuadro de diálogo "Are you sure?", oculto mientras no se necesite #}
  {% include "fragments/confirmation.html" %}
  <script src="{% static 'js/app.js' %}"></script>
</body>
</html>

La plantilla padre de todas las páginas (Ejemplo 15): cada página la extiende ([{% extends "layout.html" %}]) y completa su bloque [content] (línea 38).

  • Línea 23: las bibliotecas de etiquetas utilizadas: [static] (archivos estáticos), [i18n] (traducciones, Ejemplo 22) y [rdv], la nuestra (capa web, más arriba). Una plantilla padre no transmite sus bibliotecas a las plantillas que la extienden: cada página carga las que necesita;
  • línea 24: el idioma de la página, [fr] o [en]: el idioma activo de la solicitud, establecido por el middleware [SetLanguage];
  • línea 28: el título de la página, ya traducido por la vista, que lo transmite en la variable [page_title];
  • líneas 30–31: la etiqueta [{% static %}] genera la URL de un archivo de la carpeta [static] (Ejemplo 15);
  • líneas 35–40: la barra de navegación, los mensajes de éxito en la parte superior de la página, el contenido de la página y el área de errores en la parte inferior. El fragmento de la barra de navegación se inserta con [{% include %}] (Ejemplo 15): accede a las variables de la página. Las dos áreas de mensajes son las etiquetas de inclusión de [web/templatetags/rdv.py];
  • líneas 43–44: la ventana “¿Está seguro?”, oculta hasta que se necesita, y el script que la muestra.

El comentario de encabezado (líneas 2–22) es una etiqueta [{% comment %}]: un comentario de plantilla que puede abarcar varias líneas ([{# ... #}] cabe en una sola línea, ejemplo 14). Se escribe después de [<!doctype html>]: la primera línea de la página enviada debe ser la declaración del tipo de documento. El DTL escapa todo lo que muestra mediante [{{ ... }}] (Ejemplo 14): un nombre ingresado por el usuario que contenga HTML ([<script>]) se muestra tal cual, sin ser interpretado. Esto evita que se inyecte HTML (XSS) sin esfuerzo en todas las páginas.

11.18.1.2. templates/fragments/navbar.html

{% comment %}
  =========================================================================
  templates/fragments/navbar.html - la barra de navegación.

  Título, FR/EN, rol, nombre, cierre de sesión - y el menú, cuyas entradas dependen
  del rol: las calcula el procesador de contexto web/contexts.py
  (variable menu), con, para cada una, su URL, su etiqueta y si es la
  de la página actual (clase "active").

  user: el usuario con sesión iniciada, o None (ver web/contexts.py).
  =========================================================================
{% endcomment %}
{% load i18n %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">RdvMedecins</span>

  <ul class="navbar-nav me-auto">
    {% for entry in menu %}
    <li class="nav-item">
      <a class="nav-link{% if entry.active %} active{% endif %}" href="{{ entry.url }}">{{ entry.label }}</a>
    </li>
    {% endfor %}
  </ul>

  <div class="d-flex align-items-center gap-2">
    {# FR / EN: enlaces simples (GET /language/fr), el idioma activo resaltado #}
    {% get_available_languages as languages %}
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      {% for code, name in languages %}
      <a class="btn {% if code == LANGUAGE_CODE %}btn-light{% else %}btn-outline-light{% endif %}"
         href="{% url 'language' code %}">{{ code|upper }}</a>
      {% endfor %}
    </div>

    {% if user %}
    <span class="badge text-bg-light text-primary">{{ user.role }}</span>
    <span class="text-white">{{ user.name }}</span>
    {# logout es un POST: un formulario reducido a su botón (y al token anti-CSRF) #}
    <form method="post" action="{% url 'logout' %}" class="m-0">
      {% csrf_token %}
      <button type="submit" class="btn btn-sm btn-outline-light">{% translate "Log out" %}</button>
    </form>
    {% endif %}
  </div>
</nav>

La barra de navegación. Simplemente muestra lo que ha preparado el procesador de contexto [web/contexts.py]: el usuario conectado ([user]) y las entradas del menú ([menu]), que dependen del rol.

  • líneas 17–23: el menú, en el que cada entrada tiene su propia URL y etiqueta; la clase [active] de [Bootstrap] resalta la entrada de la página mostrada actualmente;
  • Líneas 27–32: los botones FR / EN, simples enlaces ([/language/fr]), con el idioma activo resaltado. [{% get_available_languages as languages %}] (biblioteca [i18n]) almacena la configuración [LANGUAGES]—una lista de pares (código, nombre)—en la variable [languages], que el bucle desempaqueta ([{% for code, name in languages %}]); el filtro [upper] convierte el código a mayúsculas. [{% url 'language' code %}] crea la URL de una ruta que tiene un parámetro (ejemplo 15);
  • Líneas 35–43: para un usuario conectado, su rol, su nombre y el botón de cierre de sesión. El cierre de sesión es una solicitud POST: un formulario reducido a su botón, con su token anti-CSRF ([{% csrf_token %}], Ejemplo 21).

11.18.1.3. templates/fragments/success.html y errors.html

1
2
3
4
{# templates/fragments/success.html - los mensajes de ÉXITO (etiqueta success_zone, ver web/templatetags/rdv.py) #}
{% for text in texts %}
<div class="alert alert-success" role="status">{{ text }}</div>
{% endfor %}
{% comment %}
  templates/fragments/errors.html - la zona de errores, en la PARTE INFERIOR de cada página, sobre un
  fondo rosa claro (clase .error-zone, ver static/css/styles.css). Los mensajes
  los reúne la etiqueta error_zone (ver web/templatetags/rdv.py).
  role="alert": un lector de pantalla anuncia el mensaje apenas se muestra la página,
  incluso si está al final.
{% endcomment %}
{% if texts %}
<div class="error-zone" role="alert">
  {% for text in texts %}
  <div>{{ text }}</div>
  {% endfor %}
</div>
{% endif %}

Las dos plantillas de las etiquetas de inclusión [success_zone] y [error_zone] (capa web, más arriba): reciben la lista [texts], preparada por la etiqueta, y la muestran. [role="status"]: un lector de pantalla anuncia el mensaje de éxito. [role="alert"]: anuncia la sección de errores en cuanto se muestra la página, aunque esté al final. La sección de errores permanece anclada en la parte inferior de la ventana cuando la página es larga (véase la hoja de estilos más adelante).

11.18.1.4. templates/fragments/confirmation.html

{% comment %}
  =========================================================================
  templates/fragments/confirmation.html - el cuadro de diálogo modal "Are you sure?"
  (ver ejemplo 21).

  Reemplaza el cuadro window.confirm() del navegador, que no se puede
  personalizar ni traducir (sus botones permanecen en el idioma del navegador, no
  en el de la página).

  Un ÚNICO cuadro de diálogo para toda la página, oculto (d-none) al principio. Sus etiquetas
  se traducen aquí, en el servidor, como el resto de la página; el pequeño script
  static/js/app.js se limita a mostrarlo, a colocar en él el mensaje propio del
  formulario (atributo data-confirmation) y a enviar el formulario si
  el usuario confirma.
  =========================================================================
{% endcomment %}
{% load i18n %}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title">{% translate "Confirmation" %}</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="{% translate 'Close' %}"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          {# "No, go back" en lugar de "Cancel": a veces la pregunta es "Cancel this appointment?" #}
          <button type="button" class="btn btn-secondary" data-action="no">{% translate "No, go back" %}</button>
          <button type="button" class="btn btn-danger" data-action="yes">{% translate "Yes, confirm" %}</button>
        </div>
      </div>
    </div>
  </div>
</div>

La ventana modal “¿Está seguro?” del Ejemplo 21, que reemplaza el cuadro de diálogo [window.confirm()] del navegador: este cuadro de diálogo no se formatea correctamente, y sus botones permanecen en el idioma del navegador, no en el de la página. Una sola ventana para toda la página, inicialmente oculta (clase [d-none] proveniente de [Bootstrap]); sus etiquetas las traduce el servidor, igual que el resto de la página. El script [static/js/app.js] la muestra, coloca en ella el mensaje del formulario que se va a confirmar (su atributo [data-confirmation]) y envía el formulario si el usuario confirma. El botón "Cancelar" se rotula “No, volver” en lugar de “Cancelar”: la pregunta a veces es “¿Cancelar esta cita?”, y un botón “Cancelar” sería ambiguo en ese contexto. Los atributos [role="alertdialog"], [aria-modal], [aria-labelledby] y [aria-describedby] describen la ventana a los lectores de pantalla: un cuadro de diálogo que espera una respuesta, su título y su mensaje.

11.18.1.5. templates/fragments/booking.html

{% comment %}
  =========================================================================
  templates/fragments/booking.html - el cuadro de diálogo de reserva de la agenda.

  Las clases REALES de Bootstrap de un cuadro de diálogo modal (.modal, .modal-backdrop...),
  hechas visibles "a fuego" (show d-block) en lugar de mediante el JavaScript de
  Bootstrap. Es el SERVIDOR quien decide mostrarlo (parámetro &book=... de
  la URL), y cerrarlo equivale a seguir un enlace a la misma página sin este
  parámetro.

  El fragmento lee directamente las variables de la página que lo incluye
  (booking, doctor_id, day, back_url).
  =========================================================================
{% endcomment %}
{% load i18n %}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="{% url 'schedule_book' %}" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">{% translate "Book this slot" %}</h5>
        <a class="btn-close" href="{{ back_url }}" aria-label="{% translate 'Close' %}"></a>
      </div>

      <div class="modal-body">
        <p>{% blocktranslate with time_range=booking.time_range %}Slot {{ time_range }}{% endblocktranslate %}</p>

        {# lo que el servidor debe saber además del paciente elegido #}
        {% csrf_token %}
        <input type="hidden" name="doctorId" value="{{ doctor_id }}">
        <input type="hidden" name="day" value="{{ day }}">
        <input type="hidden" name="slotId" value="{{ booking.slot_id }}">

        {# un paciente reserva para sí mismo: no hay lista para elegir (y el servidor ignora cualquier clientId de todos modos) #}
        {% if booking.patient %}
        <p class="mb-0">
          <span>{% translate "Patient" %}</span>:
          <strong>{{ booking.patient }}</strong>
        </p>
        {% else %}
        <label class="form-label" for="clientId">{% translate "Patient" %}</label>
        <select id="clientId" name="clientId" class="form-select" required autofocus>
          <option value="">{% translate "-- choose a patient --" %}</option>
          {% for client in booking.clients %}
          <option value="{{ client.id }}">{{ client.label }}</option>
          {% endfor %}
        </select>
        {% endif %}
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" href="{{ back_url }}">{% translate "Cancel" %}</a>
        <button type="submit" class="btn btn-primary">{% translate "Confirm" %}</button>
      </div>
    </form>
  </div>
</div>

La ventana de reserva del calendario. Usa las clases reales de una ventana modal de [Bootstrap] ([modal], [modal-backdrop]...), pero se hace visible “directamente en el código” ([show d-block]), en lugar de mediante el [JavaScript] de [Bootstrap]: es el servidor quien decide mostrarla cuando la URL contiene [&book=...]. Cerrarla (con la X o el botón Cancelar) equivale a seguir un enlace a la misma página sin ese parámetro ([back_url]).

  • Línea 26: [{% blocktranslate with time_range=booking.time_range %}]: un texto traducido que contiene una variable (ejemplo 22). En un [blocktranslate] solo se permiten variables simples ([{{ time_range }}], no [{{ booking.time_range }}]): la cláusula [with] crea una.
  • líneas 29–32: el token anti-CSRF y lo que el servidor necesita saber: el médico, el día y la franja horaria;
  • líneas 35–48: un paciente hace una reserva para sí mismo: su nombre, sin lista para elegir (y el servidor ignora de todos modos cualquier campo [clientId]). El administrador y los médicos seleccionan al paciente de una lista; [required] y [autofocus]: el navegador exige una selección y coloca el cursor en la lista.

11.18.1.6. templates/fragments/captcha.html

{% comment %}
  =========================================================================
  templates/fragments/captcha.html - el captcha de la página de autenticación
  (ver security/captchas.py). Protege tanto el inicio de sesión como el acceso a la
  creación de cuenta (botón "Create a patient account"). Lee la variable
  [captcha] de la página.

  captcha.svg|safe: la imagen SVG se inserta TAL CUAL en la página, sin
  escapar. Es seguro aquí porque este SVG lo genera el servidor
  mismo y no contiene nada que provenga del usuario - NUNCA se haría
  eso con una entrada del usuario.

  El campo oculto captcha_id le indica al servidor QUÉ captcha verificar; la respuesta
  correcta, por su parte, nunca se envía al navegador. "Another image" simplemente recarga
  la página ({% url 'login' %}: la URL de la página, sin sus parámetros).
  =========================================================================
{% endcomment %}
{% load i18n %}
<div class="mb-3">
  <label class="form-label" for="captcha">{% translate "Type the characters shown in the image" %}</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="{% translate 'Anti-robot verification image' %}">{{ captcha.svg|safe }}</div>
    <a class="small" href="{% url 'login' %}">{% translate "Another image" %}</a>
  </div>
  <input type="hidden" name="captcha_id" value="{{ captcha.id }}">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
         spellcheck="false" required class="form-control">
  <div class="form-text">{% translate "Upper or lower case, it does not matter." %}</div>
</div>

El CAPTCHA (ejemplo 27). [captcha.svg|safe] inserta la imagen SVG tal cual, sin escaparla: de lo contrario, el navegador mostraría su código XML. Esto es seguro aquí porque este SVG lo genera el servidor y no contiene nada proporcionado por el usuario: nunca haríamos esto con datos ingresados por el usuario. El campo oculto [captcha_id] indica al servidor qué CAPTCHA verificar; la respuesta en sí nunca se envía al navegador. El enlace “Otra imagen” recarga la página de inicio de sesión y, con ella, el CAPTCHA. Los atributos de los campos de entrada ([autocomplete="off"], [autocapitalize="off"], [spellcheck="false"]) evitan que el navegador sugiera una entrada anterior y que el teclado del teléfono ponga letras en mayúscula o corrija la ortografía.

11.18.2. Los campos del formulario

11.18.2.1. templates/forms/field.html

{% comment %}
  templates/forms/field.html - un campo completo de un formulario: etiqueta,
  zona de entrada, luego su mensaje de error o su ayuda (ver ejemplo 18 y la
  configuración FORM_RENDERER). La zona de entrada se enmarca en rojo (clase
  is-invalid) mediante el método flag del formulario (ver web/forms.py).
{% endcomment %}
<div class="mb-3">
  <label class="form-label" for="{{ field.id_for_label }}">{{ field.label }}</label>
  {{ field }}
  {% if field.errors %}<div class="invalid-feedback d-block" id="{{ field.auto_id }}_error">{% for error in field.errors %}{{ error }}{% if not forloop.last %}<br>{% endif %}{% endfor %}</div>{% endif %}
  {% if field.help_text and not field.errors %}<div class="form-text" id="{{ field.auto_id }}_helptext">{{ field.help_text }}</div>{% endif %}
</div>

La plantilla de un campo completo —la del motor de renderizado [BootstrapRenderer] (capa web, más arriba)—, como se vio en el Ejemplo 18: la etiqueta, el campo de entrada ([{{ field }}], con las clases CSS proporcionadas por el formulario), seguido del mensaje de error o, si no hay, del texto de ayuda. Las clases [invalid-feedback] (el mensaje en rojo) y [form-text] (el texto de ayuda en gris) son las de [Bootstrap]; [d-block] muestra el mensaje aunque el campo de entrada no lo preceda inmediatamente. Un campo puede tener varios errores: se separan con un salto de línea ([forloop.last], ejemplo 14).

Los identificadores [..._error] y [..._helptext] no se eligen al azar: son los que [Django] referencia en los atributos [aria-describedby] del campo de entrada, junto con [aria-invalid] para un campo con error. Así, un lector de pantalla lee el mensaje de error o el texto de ayuda junto con el campo:

1
2
3
4
5
<div class="mb-3">
  <label class="form-label" for="id_first_name">First name</label>
  <input type="text" name="first_name" maxlength="20" class="form-control is-invalid" required aria-invalid="true" aria-describedby="id_first_name_error" id="id_first_name">
  <div class="invalid-feedback d-block" id="id_first_name_error">The first name is required.</div>
</div>

El borde rojo ([is-invalid]) fue agregado por el método [flag] del formulario; [maxlength] y [required] por [Django], según las opciones del campo. El atributo [required] no impide que se envíe un formulario vacío: los formularios de la aplicación llevan el atributo [novalidate] (véase más adelante); la validación la realiza el servidor.

11.18.2.2. templates/macros.html

{% comment %}
  templates/macros.html - los fragmentos con nombre de los formularios (ver ejemplo 15).

  identity: los campos de identidad (título, nombre, apellido), comunes a tres
  formularios: médico/cliente del ADMIN, "Create a patient account" y "Manage my
  account". Lee la variable [form] de la página que lo incluye:
  {% include "macros.html#identity" %}.
{% endcomment %}
{% partialdef identity %}
  {{ form.title.as_field_group }}
  <div class="row g-3">
    <div class="col-sm-6">{{ form.first_name.as_field_group }}</div>
    <div class="col-sm-6">{{ form.last_name.as_field_group }}</div>
  </div>
{% endpartialdef %}

Un fragmento con nombre ([{% partialdef %}], ejemplo 15), usado por las tres páginas que muestran un formulario de “persona”: los campos de identificación, el título y luego el nombre y el apellido lado a lado (la cuadrícula de [Bootstrap]: [row], [col-sm-6]). Cada campo se renderiza con [as_field_group] (Ejemplo 18), es decir, con la plantilla [field.html]. Una página lo inserta mediante [{% include "macros.html#identity" %}]: el fragmento lee la variable [form] de la página.

11.18.3. Las páginas

11.18.3.1. templates/login.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/login.html - el formulario de inicio de sesión (ver web/views/auth.py).
  Un <form> HTML ordinario, escrito a mano: el propio navegador envía login,
  contraseña y respuesta del captcha en POST /login, sin JavaScript. En caso
  de fallo, el servidor devuelve ESTA página, con el login ya ingresado, un NUEVO
  captcha y el error, que muestra al pie de la página la plantilla padre.
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{% translate "Sign in" %}</h5>

      <form method="post" action="{% url 'login' %}">
        {% csrf_token %}
        <div class="mb-3">
          <label class="form-label" for="login">{% translate "Login" %}</label>
          {# autofocus: un atributo booleano, escrito si la condición es verdadera. El cursor va al primer campo por completar #}
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="{{ login }}" required{% if not login %} autofocus{% endif %}>
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">{% translate "Password" %}</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required{% if login %} autofocus{% endif %}>
        </div>

        {% include "fragments/captcha.html" %}

        <button type="submit" class="btn btn-primary w-100">{% translate "Log in" %}</button>

        {% comment %}
          aún no hay cuenta: un paciente puede crear una por sí mismo. NO es
          un simple enlace: es un segundo botón de envío de ESTE formulario, que va
          a otra dirección (formaction). Allí el servidor verifica el captcha
          de arriba antes de abrir la página de creación de cuenta (ver
          web/views/registration.py). formnovalidate: el navegador no exige
          login ni contraseña (inútil para crear una cuenta). Enter en un
          campo siempre activa el PRIMER botón del formulario, "Log in".
        {% endcomment %}
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="{% url 'registration_access' %}" formnovalidate>{% translate "Create a patient account" %}</button>
        <div class="form-text text-center">{% translate "To create an account, first type the characters shown in the image." %}</div>
      </form>

      <div class="text-muted small mt-3">
        <span>{% translate "Demo accounts (password = login):" %}</span>
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - <span>{% translate "ADMIN role: appointments + doctor and patient management" %}</span></li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{% translate "DOCTOR role: booking and cancelling appointments" %}</span></li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{% translate "USER role (patients): booking for themselves, managing their account" %}</span></li>
        </ul>
      </div>
    </div>
  </div>
</div>
{% endblock %}

El formulario de inicio de sesión, un [<form>] escrito a mano, se envía mediante POST a [/login]. La etiqueta [{% extends %}] es la primera de la plantilla (línea 1), como lo exige DTL; el comentario va a continuación.

  • Líneas 24–30: el login ingresado se vuelve a mostrar después de un intento fallido ([login]). El atributo [autofocus] coloca el cursor en el primer campo que se debe completar: el nombre de usuario si está vacío y, de lo contrario, la contraseña (después de un intento de inicio de sesión fallido o de crear una cuenta). Un atributo booleano está presente o ausente: [{% if not login %} autofocus{% endif %}];
  • línea 33: el CAPTCHA;
  • líneas 46–47: el botón “Crear una cuenta de paciente” no es un enlace; es un segundo botón que envía el mismo formulario a otra dirección (atributo de botón [formaction]). El servidor verifica allí el CAPTCHA antes de abrir la página de creación de la cuenta ([registration.access]). [formnovalidate]: el navegador no exige un nombre de usuario ni una contraseña (atributos [required]), ya que no son necesarios para crear una cuenta. Al presionar la tecla Enter en un campo, siempre se activa el primer botón de envío del formulario: Iniciar sesión;
  • líneas 51–58: cuentas de demostración, para pruebas.

11.18.3.2. templates/schedule.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/schedule.html - la página principal (ver web/views/schedule.py).
  Tres bloques:
    1. la elección del médico y del día;
    2. la agenda;
    3. el cuadro de diálogo de reserva (fragmento booking).
  Un posible error (fecha inválida, médico desconocido) se muestra al pie de
  la página mediante la plantilla padre (etiqueta error_zone).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  {# 1. elección del médico y del día: un formulario GET, que simplemente recarga esta página con ?doctorId=...&day=... #}
  <form method="get" action="{% url 'schedule' %}" class="card p-3 mb-3">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="doctorId">{% translate "Doctor" %}</label>
        <select id="doctorId" name="doctorId" class="form-select" required>
          <option value="">{% translate "-- choose a doctor --" %}</option>
          {% for doctor in doctors %}
          <option value="{{ doctor.id }}"{% if doctor.selected %} selected{% endif %}>{{ doctor.label }}</option>
          {% endfor %}
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day">{% translate "Day" %}</label>
        <input id="day" name="day" type="date" class="form-control" value="{{ day }}" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100">{% translate "View schedule" %}</button>
      </div>
    </div>
  </form>

  {# paciente que ya tiene una próxima cita: por eso no hay botón "Book" #}
  {% if info %}
  <div class="alert alert-info">
    <span>{{ info }}</span>
    <a href="{% url 'area' %}" class="alert-link">{% translate "My area" %}</a>
  </div>
  {% endif %}

  {# 2. la agenda #}
  {% if schedule %}
  <div class="card p-3">
    <h5>{% translate "Schedule for" %} {{ schedule.day }} - {{ schedule.doctor }}</h5>

    {% if schedule.rows %}
    <table class="table table-hover align-middle">
      <thead>
        <tr>
          <th>{% translate "Slot" %}</th>
          <th>{% translate "Status" %}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {% for row in schedule.rows %}
        <tr{% if row.bookable %} class="free-slot"{% endif %}>
          <td>{{ row.time_range }}</td>
          <td>
            {% comment %}
              [patient] solo se establece si el usuario tiene permiso para ver este
              nombre (ADMIN, DOCTOR, o el paciente para SU cita) - de lo contrario,
              simplemente "Booked"
            {% endcomment %}
            {% if row.free %}
            <span class="badge text-bg-success">{% translate "Free" %}</span>
            {% elif row.patient %}
            <span class="badge {% if row.me %}text-bg-primary{% else %}text-bg-secondary{% endif %}">{{ row.patient }}</span>
            {% else %}
            <span class="badge text-bg-secondary">{% translate "Booked" %}</span>
            {% endif %}
          </td>
          <td>
            {% comment %}
              los botones mostrados los decidió la vista (bookable, appointment_id)
              según el rol del usuario. "Book" es un simple enlace: vuelve a abrir
              esta página con el cuadro de diálogo de reserva de este horario
            {% endcomment %}
            {% if row.bookable %}
            <a class="btn btn-sm btn-outline-success" href="{{ row.book_url }}">{% translate "Book" %}</a>
            {% endif %}
            {# "Cancel" MODIFICA datos: por lo tanto es un POST #}
            {% if row.appointment_id %}
            <form method="post" action="{% url 'schedule_cancel' %}" class="m-0"
                  data-confirmation="{% translate 'Cancel this appointment?' %}">
              {% csrf_token %}
              <input type="hidden" name="appointmentId" value="{{ row.appointment_id }}">
              <input type="hidden" name="doctorId" value="{{ doctor_id }}">
              <input type="hidden" name="day" value="{{ day }}">
              <button type="submit" class="btn btn-sm btn-outline-danger">{% translate "Cancel" %}</button>
            </form>
            {% endif %}
          </td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
    {% else %}
    <p class="text-muted mb-0">{% translate "This doctor has no time slots." %}</p>
    {% endif %}
  </div>
  {% else %}
  <p class="text-muted">{% translate 'Choose a doctor and a day, then click "View schedule".' %}</p>
  {% endif %}

  {# 3. el cuadro de diálogo de reserva, solo si la URL contiene &book=... #}
  {% if booking %}
  {% include "fragments/booking.html" %}
  {% endif %}
{% endblock %}

La página principal. Tres secciones: la selección de un médico y un día, el calendario y la ventana de reserva.

  • Líneas 17–36: selección de un médico y un día: un formulario GET (ejemplo 17), que recarga la página con [?doctorId=...&day=...] en la URL. El día es un campo [type="date"]: el navegador muestra un calendario y envía la fecha en el formato [yyyy-mm-dd], sin importar cómo la muestre ([30/09/2026] en francés); el valor inicial ([value]) se escribe en este mismo formato;
  • líneas 39–44: para un paciente que ya tiene una cita próxima, el motivo por el que no hay botón “Reservar”, con un enlace a “Mi espacio”;
  • Líneas 70–76: el estado de la franja: Libre (en verde), el nombre del paciente (en azul si es una cita reservada por el paciente conectado, en gris en caso contrario) o “Reservada”. La plantilla no determina nada: [row.patient] solo se muestra si el usuario tiene permiso para ver ese nombre;
  • líneas 84–86: “Reservar” es un simple enlace: vuelve a abrir la página con la ventana de reserva para esa franja horaria ([row.book_url]). No modifica nada: basta con un GET;
  • líneas 88–97: “Cancelar” modifica datos: es un formulario POST (ejemplo 21), con su token anti-CSRF, la cita que se va a cancelar y la información para volver a la misma página (el médico, el día). El atributo [data-confirmation] hace que el script de la página solicite confirmación; su texto lo representa [{% translate %}], encerrado entre comillas simples dentro del atributo, que a su vez está encerrado entre comillas dobles;
  • líneas 112–114: la ventana de reserva, si la URL lo solicita (y si la franja horaria se puede reservar).

11.18.3.3. templates/persons/list.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/persons/list.html - la lista de los médicos O de los clientes (ADMIN).
  Una sola plantilla para ambos: los textos propios de cada uno llegan en
  [texts], y [section] ("doctors" o "clients") da el comienzo de los nombres de las
  rutas (ver web/views/persons.py).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0">{{ texts.title }}</h4>
    <a class="btn btn-primary" href="{{ add_url }}">{{ texts.add }}</a>
  </div>

  <div class="card p-3">
    {% if persons %}
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{% translate "Title" %}</th>
          <th>{% translate "First name" %}</th>
          <th>{% translate "Last name" %}</th>
          <th>{% translate "Login" %}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {# person.account.login: la cuenta, cargada por la misma consulta (select_related) #}
        {% for person in persons %}
        <tr>
          <td>{{ person.title }}</td>
          <td>{{ person.first_name }}</td>
          <td>{{ person.last_name }}</td>
          <td><code>{{ person.account.login }}</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              {# section|add:"_edit": "doctors_edit", el nombre de la ruta #}
              <a class="btn btn-sm btn-outline-primary"
                 href="{% url section|add:'_edit' person.id %}">{% translate "Edit" %}</a>
              {# data-confirmation: se abrirá un cuadro de diálogo de confirmación antes de enviar el formulario (ver static/js/app.js) #}
              <form method="post" action="{% url section|add:'_delete' person.id %}" class="m-0"
                    data-confirmation="{{ texts.confirm_delete }}">
                {% csrf_token %}
                <button type="submit" class="btn btn-sm btn-outline-danger">{% translate "Delete" %}</button>
              </form>
            </div>
          </td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
    {% else %}
    <p class="text-muted mb-0">{{ texts.empty }}</p>
    {% endif %}
  </div>
{% endblock %}

La lista de médicos o de clientes: el texto específico de cada uno se almacena en la variable [texts], y los nombres de las rutas se generan a partir del nombre de la sección: [section|add:'_edit'] produce [doctors_edit] o [clients_edit] (el filtro [add] suma dos números o, como en este caso, concatena dos cadenas). [{% url %}] acepta así, como nombre de ruta, una expresión calculada seguida de los parámetros de la ruta ([person.id]). [person.account.login]: el login de la cuenta, cargado junto con la lista (capa DAO) y almacenado con ella en la caché. El botón Eliminar es un formulario POST, con confirmación.

11.18.3.4. templates/persons/form.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/persons/form.html - creación O actualización de un médico o
  de un cliente (ADMIN), con el formulario PersonForm.

  Cuando se rechaza la entrada (campo vacío, login ya en uso...), la vista muestra
  de nuevo ESTA página, y la plantilla muestra:
    - los valores ya ingresados (excepto la contraseña);
    - los campos defectuosos enmarcados en rojo (clase Bootstrap "is-invalid");
    - bajo un campo rechazado por la validación, su mensaje;
    - el mensaje de error de la página, AL PIE de la página (etiqueta error_zone).
  El formulario se envía a la URL de la propia página (sin atributo action).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{{ page_title }}</h5>

      <form method="post" novalidate>
        {% csrf_token %}
        {# título, nombre, apellido: un fragmento común a tres formularios #}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        {# nunca se rellena previamente: la contraseña nunca vuelve al navegador #}
        {{ form.password.as_field_group }}
        {# solo en modo de actualización: la versión del registro, en un campo oculto (el bloqueo optimista) #}
        {% if form.version %}{{ form.version }}{% endif %}

        <div class="d-flex gap-2 mt-4">
          <button type="submit" class="btn btn-primary">{% translate "Save" %}</button>
          <a class="btn btn-secondary" href="{{ list_url }}">{% translate "Back to the list" %}</a>
        </div>
      </form>
    </div>
  </div>
</div>
{% endblock %}

Creación o modificación de un médico o de un cliente mediante el formulario [PersonForm].

  • Línea 24: un formulario POST sin el atributo [action]: se envía a la URL de la propia página ([/doctors/add] o [/doctors/3/edit]). [novalidate] desactiva la validación del navegador ([required], [maxlength]...) cuando se envía el formulario: la validación la realiza el servidor, y su resultado es el que cuenta (ejemplo 19);
  • línea 27: título, nombre y apellido, mediante el fragmento [identity];
  • líneas 30–32: el nombre de usuario y la contraseña, que nunca se rellenan previamente. Sus descripciones emergentes difieren entre la creación y la modificación (según el constructor del formulario);
  • línea 34: solo para la edición, el campo oculto de versión (el bloqueo optimista). [{{ form.version }}] genera únicamente el campo de entrada, sin etiqueta: [<input type="hidden" name="version" value="1" id="id_version">]. Al crear un registro, el formulario no tiene un campo [version]: la variable está vacía y la prueba se evalúa como falsa.

Los errores del formulario en sí que no involucran ningún campo ([non_field_errors], ejemplo 19) no necesitan mostrarse: el formulario no genera ninguno, y un token anti-CSRF no válido se rechaza antes de la vista (la página 419).

11.18.3.5. templates/registration.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/registration.html - "Create a patient account" (página pública, ver
  web/views/registration.py), con el formulario RegistrationForm. Los mismos campos
  de identidad que el formulario ADMIN (fragmento identity), pero el login y la
  contraseña son obligatorios, con confirmación. Aquí NO hay captcha: a esta página
  solo se llega después de resolver el de la
  página de autenticación (botón "Create a patient account").
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{% translate "Create a patient account" %}</h5>
      <p class="text-muted small mb-3">{% translate "With this account you can book your own appointments." %}</p>

      <form method="post" action="{% url 'registration' %}" novalidate>
        {% csrf_token %}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        {# la contraseña y su confirmación, una al lado de la otra #}
        <div class="row g-3">
          <div class="col-sm-6">{{ form.password.as_field_group }}</div>
          <div class="col-sm-6">{{ form.confirmation.as_field_group }}</div>
        </div>

        <div class="d-flex gap-2 mt-3">
          <button type="submit" class="btn btn-primary">{% translate "Create my account" %}</button>
          <a class="btn btn-secondary" href="{% url 'login' %}">{% translate "Back to login" %}</a>
        </div>
      </form>
    </div>
  </div>
</div>
{% endblock %}

Creación de una cuenta de paciente: los campos de identidad, seguidos del nombre de usuario, la contraseña y la confirmación de la contraseña —todos campos obligatorios— lado a lado (líneas 28–31). El texto de ayuda de la contraseña indica la longitud mínima: “Al menos 6 caracteres.” Aquí no hay CAPTCHA: solo se puede llegar a esta página después de resolver el CAPTCHA de la página de inicio de sesión.

11.18.3.6. templates/area.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/area.html - "My area": la página de inicio del paciente (rol USER),
  que se muestra justo después de iniciar sesión.
    - dos opciones: [Manage my account] y [View a schedule];
    - su próxima cita, si tiene una, con los medios para cancelarla.
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  <h4 class="mb-3">{% blocktranslate %}Hello {{ patient }}{% endblocktranslate %}</h4>

  <div class="row g-3 mb-4">
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="{% url 'account' %}">
        <h5 class="mb-1">{% translate "Manage my account" %}</h5>
        <span class="text-muted">{% translate "Change my details or password, or delete my account." %}</span>
      </a>
    </div>
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="{% url 'schedule' %}">
        <h5 class="mb-1">{% translate "View a schedule" %}</h5>
        <span class="text-muted">{% translate "See a doctor's schedule and book a slot." %}</span>
      </a>
    </div>
  </div>

  <div class="card p-3">
    <h5>{% translate "My appointment" %}</h5>
    {% comment %}
      normalmente solo una (regla "una próxima cita a la vez"), pero la página
      puede mostrar varias. {% for %} ... {% empty %}: un bucle, y lo que
      se muestra si la lista está vacía; forloop.last: ¿último elemento?
    {% endcomment %}
    {% for appointment in appointments %}
    <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{% if not forloop.last %} border-bottom{% endif %}">
      <div>
        <div class="fw-semibold">{{ appointment.day }}, {{ appointment.time_range }}</div>
        <div class="text-muted">
          <span>{{ appointment.doctor }}</span> -
          <a href="{{ appointment.schedule_url }}">{% translate "see in the schedule" %}</a>
        </div>
      </div>
      <form method="post" action="{% url 'area_cancel' %}" class="m-0"
            data-confirmation="{% translate 'Cancel this appointment?' %}">
        {% csrf_token %}
        <input type="hidden" name="appointmentId" value="{{ appointment.id }}">
        <button type="submit" class="btn btn-outline-danger">{% translate "Cancel this appointment" %}</button>
      </form>
    </div>
    {% empty %}
    <p class="text-muted mb-0">{% translate "You have no upcoming appointment." %}</p>
    {% endfor %}
  </div>
{% endblock %}

“Mi espacio”, la página de inicio del paciente: dos tarjetas grandes (“Administrar mi cuenta”, “Ver una agenda”) y su cita próxima.

  • línea 13: [{% blocktranslate %}Hello {{ patient }}{% endblocktranslate %}]: un texto traducido que contiene una variable ([Bonjour %(patient)s] en el diccionario francés);
  • líneas 37–55: [{% for %}] ... [{% empty %}] (Ejemplo 14) es un bucle, seguido de lo que se muestra si la lista está vacía. Normalmente, un paciente tiene como máximo una cita próxima; sin embargo, la página es capaz de mostrar varias citas. [forloop.last] (Ejemplo 14): el último elemento no lleva separador;
  • líneas 46–51: cada cita tiene un formulario de cancelación (POST, con confirmación), que envía solo su ID: el servidor verificará que pertenece al paciente conectado.

11.18.3.7. templates/account.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/account.html - "Manage my account" (rol USER). Dos formularios
  independientes en la misma página:
    1. la actualización (identidad, login, nueva contraseña opcional), con
       el formulario MyAccountForm;
    2. la eliminación de la cuenta - que también cancela sus citas: un
       formulario escrito a mano.
  Ambos exigen la contraseña ACTUAL (campo current_password).
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    {# 1. actualización; novalidate: es el SERVIDOR quien valida (ver ejemplo 19) #}
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3">{% translate "Manage my account" %}</h5>

      <form method="post" action="{% url 'account' %}" novalidate>
        {% csrf_token %}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        <div class="row g-3">
          <div class="col-sm-6">{{ form.password.as_field_group }}</div>
          <div class="col-sm-6">{{ form.confirmation.as_field_group }}</div>
        </div>
        {{ form.current_password.as_field_group }}
        {# la versión del registro: un campo oculto (el bloqueo optimista) #}
        {{ form.version }}

        <div class="d-flex gap-2 mt-4">
          <button type="submit" class="btn btn-primary">{% translate "Save" %}</button>
          <a class="btn btn-secondary" href="{% url 'area' %}">{% translate "Back to my area" %}</a>
        </div>
      </form>
    </div>

    {% comment %}
      2. eliminación. El campo de contraseña tiene el mismo NOMBRE que el del primer
      formulario (current_password), pero otro id: dos elementos de la misma
      página no pueden tener el mismo id
    {% endcomment %}
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">{% translate "Delete my account" %}</h5>
      <p class="text-muted small">{% translate "Your account will be permanently deleted, together with all your appointments." %}</p>
      <form method="post" action="{% url 'account_delete' %}" class="d-flex flex-wrap gap-2 align-items-end"
            data-confirmation="{% translate 'Permanently delete your account? Any appointment you have will be cancelled.' %}">
        {% csrf_token %}
        <div class="flex-grow-1">
          <label class="form-label" for="delete_password">{% translate "Current password" %}</label>
          <input id="delete_password" name="current_password" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger">{% translate "Delete my account" %}</button>
      </form>
    </div>

  </div>
</div>
{% endblock %}

“Administrar mi cuenta”: dos formularios independientes en la misma página.

  • Líneas 20–42: la actualización, mediante el formulario [MyAccountForm]: los campos de identidad, el login, la nueva contraseña y su confirmación (opcionales), la contraseña actual (obligatoria) y el campo oculto de versión;
  • Líneas 49–62: la eliminación de la cuenta, un formulario escrito a mano con su propio campo para la contraseña actual y un campo de confirmación. El campo tiene el mismo nombre que el del primer formulario ([current_password]), pero un ID distinto: dos elementos de una página no pueden tener el mismo ID, como lo indica el atributo [for] de una etiqueta. Los dos formularios son independientes: el navegador envía solo los campos del formulario cuyo botón se presionó.

11.18.3.8. templates/error.html

{% extends "layout.html" %}
{% comment %}
  templates/error.html - la página de error (400, 403, 404, 405, 419, 500...),
  construida por web/views/errors.py.
{% endcomment %}
{% load i18n %}

{% block content %}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger">{{ code }}</h1>
      <p class="lead">{{ message }}</p>
      <div><a class="btn btn-primary" href="{% url 'home' %}">{% translate "Back to the home page" %}</a></div>
    </div>
  </div>
</div>
{% endblock %}

La página de error, generada por [web/views/errors.py]: el código HTTP, el mensaje y un enlace a la página de inicio ([/], que redirige a la página de inicio del rol o a la página de inicio de sesión). Extiende la plantilla padre como las demás páginas: la barra de navegación, incluido el menú del usuario, también se incluye.

11.19. Archivos estáticos

La carpeta [static] contiene los archivos que el servidor envía tal cual (ejemplo 15): [Bootstrap] ([lib/bootstrap], solo la hoja de estilos, y su licencia), una hoja de estilos y un script. Durante el desarrollo, el servidor de [Django] los sirve por sí mismo (aplicación [django.contrib.staticfiles]); en producción, se copian a [var/static] con el comando [collectstatic] y los sirve el servidor web (“Un servidor de producción”).

11.19.1. static/css/styles.css

/* =========================================================================
   static/css/styles.css - algunos ajustes sobre Bootstrap
   (los mismos que en las otras versiones de esta aplicación).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

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

/* ─────────────────────────────────────────────────────────────────────────
   .error-zone: los mensajes de error, al pie de la página, sobre un fondo rosa claro
   (vea templates/fragments/errors.html).
   position: sticky + bottom: si la página es más alta que la ventana (una
   agenda de 12 franjas, por ejemplo), la zona se queda pegada al borde inferior de la
   ventana en lugar de desaparecer bajo el pliegue - sin cubrir nunca el
   contenido cuando la página es corta.
   z-index: por encima del fondo gris del diálogo de reserva (.modal-backdrop).
   ───────────────────────────────────────────────────────────────────────── */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* las dos grandes opciones 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;
}

Algunos ajustes adicionales para [Bootstrap], los mismos que en las otras versiones de la aplicación.

  • líneas 10–12: una franja reservable del calendario se pone verde al pasar el mouse por encima;
  • líneas 23–33: el área de errores en la parte inferior de la página tiene un fondo rosa claro. [position: sticky] con [bottom: 1rem]: si la página es más alta que la ventana (un calendario con 12 franjas horarias), el área permanece anclada en la parte inferior de la ventana en lugar de desaparecer debajo de la barra de desplazamiento; si la página es corta, se queda en su lugar sin cubrir nada. [z-index]: aparece sobre el fondo gris de la ventana de reserva;
  • líneas 36–43: las dos tarjetas grandes de “Mi espacio”, que se iluminan cuando el mouse pasa sobre ellas;
  • líneas 46–50: la imagen del CAPTCHA, con un borde.

11.19.2. static/js/app.js

// =========================================================================
// static/js/app.js - el ÚNICO JavaScript de la aplicación.
// -------------------------------------------------------------------------
// Toda la aplicación funciona sin JavaScript. Este script agrega una
// comodidad: antes de enviar un formulario que lleva el atributo
// data-confirmation="...", un diálogo modal pregunta "¿Está seguro?"
// (el diálogo en sí está en la página: templates/fragments/confirmation.html).
// Si JavaScript está desactivado, el formulario simplemente se envía sin
// confirmación - nada se rompe (principio de "mejora progresiva").
//
// ¿Por qué no window.confirm()? Su cuadro no se puede personalizar y sus
// botones permanecen en el idioma del navegador, no en el de la página.
// =========================================================================

(() => {
  const modal = document.getElementById('confirmation-modal');
  if (!modal) {
    return;
  }
  const message = document.getElementById('confirmation-modal-message');
  const noButton = modal.querySelector('.modal-footer [data-action="no"]');

  let pendingForm = null; // el formulario que se enviará si el usuario confirma
  let previousFocus = null; // el elemento al que se devuelve el foco al cerrar

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (y no innerHTML): el mensaje se muestra como TEXTO,
    // nunca se interpreta como HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // el foco va a "No": una pulsación distraída de Enter no elimina nada
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. se interceptan los envíos de los formularios que requieren confirmación
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. los botones del diálogo (Sí / No / cruz de cierre)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() envía el formulario SIN volver a activar el
      // evento 'submit': no hay una nueva solicitud de confirmación
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // clic en el fondo gris, fuera del diálogo
    }
  });

  // 3. teclado: Escape cierra el diálogo; Tab permanece DENTRO del diálogo
  //    (de lo contrario el foco pasaría a la página atenuada, detrás)
  modal.addEventListener('keydown', (event) => {
    if (event.key === 'Escape') {
      close();
    } else if (event.key === 'Tab') {
      const buttons = [...modal.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  });
})();

El único [JavaScript] de la aplicación —el del Ejemplo 21— con algunas adiciones. Toda la aplicación funciona sin [JavaScript]: este script agrega comodidad al ofrecer una confirmación antes de enviar un formulario que lleva el atributo [data-confirmation]. Si [JavaScript] está desactivado, el formulario se envía sin confirmación: nada se rompe (principio de mejora progresiva).

  • Líneas 15–19: el script es una función que se invoca en cuanto se define ([(() => { ... })()]); sus variables no son visibles para el resto de la página. Si no hay una ventana de confirmación en la página, no hace nada;
  • Líneas 26–35: apertura de la ventana: se guarda el formulario que se enviará si el usuario confirma y el mensaje del formulario se muestra en la ventana. [textContent], no [innerHTML]: el mensaje se muestra como texto y nunca se interpreta como HTML. El foco se mueve al botón “No”: presionar Enter por accidente no elimina nada;
  • líneas 37–43: cierre de la ventana; el foco regresa al elemento que lo tenía anteriormente;
  • líneas 46–51: se intercepta el envío de cada formulario que requiere confirmación ([preventDefault] lo impide) y se abre la ventana. El evento [submit] ocurre solo después de las validaciones del navegador: la contraseña actual, que es obligatoria ([required]) en el formulario de eliminación de la cuenta, se exige antes de la solicitud de confirmación;
  • líneas 54–67: los botones de la ventana. Un único manejador para toda la ventana: [closest('[data-action]')] encuentra el botón en el que se hizo clic o el elemento que lo contiene; [?.] garantiza que [undefined] no produzca un error si no hay coincidencias. “Sí” envía el formulario mediante [form.submit()], que no activa el evento [submit]: no aparece una nueva solicitud de confirmación. Hacer clic en el fondo gris fuera de la ventana la cierra;
  • líneas 71–86: el teclado. Esc cierra la ventana; la tecla Tab mueve el foco de un botón a otro sin salir de la ventana (de lo contrario, pasaría a la página en gris que está detrás): es lo que esperan los usuarios que navegan con el teclado y los lectores de pantalla.