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 (por ejemplo, de 8:00 a.m. a 12:00 p.m., en incrementos de 20 minutos); una cita consta de un día, una franja horaria y un cliente (un paciente). Es el port exacto, en [Flask], de la aplicación [Spring MVC] de la lección anterior (que a su vez se portó de la versión [ASP.NET Core MVC]): la misma base de datos, las mismas reglas de negocio, las mismas páginas, las mismas URL y los mismos diccionarios de traducción. El servidor genera las páginas HTML mediante vistas [Jinja2]; el acceso a la base de datos se realiza con [SQLAlchemy].
Tres roles de usuario comparten la aplicación:
Rol | Quién | Qué pueden hacer |
ADMIN | El administrador ([admin]) | Ver las agendas, programar y cancelar citas de cualquier paciente; administrar (listar, agregar, editar, eliminar) médicos y clientes |
DOCTOR | Los médicos | ver las agendas, programar citas y cancelar citas de 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; administrar su cuenta; crear una cuenta |
Principales reglas de gestión:
- no se permiten citas en el pasado;
- una franja horaria solo puede reservarse una vez por día;
- un paciente solo puede tener una cita próxima a la vez;
- dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido, y un nombre de usuario pertenece a una sola cuenta;
- un médico con citas no puede eliminarse; un cliente se 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 cliente exige resolver primero el CAPTCHA de esa página.
11.2. Uso de la aplicación
11.2.1. La página de inicio de sesión

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

Un error (en este caso, un CAPTCHA introducido incorrectamente) se muestra en la parte inferior de la página sobre un fondo rosa claro:

11.2.2. El calendario, tal como lo ven 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:


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. El servidor genera esta ventana, igual que el resto de la página: la URL contiene ahora el parámetro [book=4], que es el número de la franja horaria seleccionada:

Tras la reserva, un mensaje confirma la cita:

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

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 administrar su cuenta y ver su calendario. Aquí todavía no tiene ninguna cita:

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

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


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

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 el motivo:

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

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

11.2.4. Administración de médicos y pacientes
El administrador tiene dos menús adicionales, Médicos y Pacientes:


El formulario para agregar un médico, enviado con errores:

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

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

11.2.5. Creación de una cuenta de paciente
En la página de inicio de sesión, el botón "Crear una cuenta de paciente" solo abre el formulario si el CAPTCHA se ha introducido correctamente:

Una vez creada la cuenta, se redirige al usuario de nuevo a la página de inicio de sesión con su nombre de usuario ya rellenado:

11.2.6. Fin de la 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:

11.3. Instalación y ejecución
La aplicación se encuentra en la carpeta [rdvmedecins2-flask], junto a la carpeta [examples]. Es un proyecto independiente, con sus propios archivos [requirements.txt] 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 (la aplicación utiliza la sintaxis de clases genéricas introducida en la versión 3.12). Verifique la instalación en un terminal:
- un servidor [MySQL] 8, por ejemplo el de [Laragon] que se ejecuta en [Windows] (véanse los apéndices). [MariaDB] también funciona: la aplicación se ha probado con él.
[pip] descarga las bibliotecas desde el repositorio [PyPI] (*Python Package Index*): por lo tanto, debe estar conectado a Internet durante su instalación. El editor recomendado es [Visual Studio Code], junto con la extensión [Python] de Microsoft (véanse los apéndices); no obstante, todo puede hacerse desde la línea de comandos.
11.3.2. Crear la base de datos
La base de datos [dbrdvmedecins2] se crea mediante el script [database/dbrdvmedecins2.sql]. Con [Laragon], abra la herramienta [HeidiSQL] (botón Base de datos) y ejecute el script desde el menú Archivo / Ejecutar archivo SQL. Desde 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 contraseña (como ocurre con [Laragon]). Es la misma base de datos que usan las versiones [ASP.NET Core] y [Spring MVC]: si ya existe, este paso es opcional. El script puede ejecutarse en cualquier momento para volver a los datos originales.
11.3.3. Configurar el acceso a la base de datos
Todos los parámetros de configuración están en el archivo [config.py] (que se comenta más adelante). De forma predeterminada, la aplicación se conecta a [MySQL] en [localhost], puerto 3306, con el usuario [root] sin contraseña: es la configuración predeterminada de [Laragon]. Si su cuenta [root] tiene contraseña, lo más sencillo es escribirla en este archivo, en la línea [DB_PASSWORD = ""]. Para evitar escribir una contraseña en un archivo del proyecto, también puede indicarla mediante una variable de entorno, que tiene prioridad sobre el archivo. Su nombre es el mismo que el de la variable del archivo, precedido de [FLASK_] (ejemplo 25):
| export FLASK_DB_PASSWORD=myPassword # Linux, macOS
set FLASK_DB_PASSWORD=myPassword # Windows (cmd)
$env:FLASK_DB_PASSWORD="myPassword" # Windows (PowerShell)
|
La variable se aplica solo al terminal donde se definió; la aplicación se inicia entonces desde ese mismo terminal.
11.3.4. Inicio de la aplicación
En una ventana de terminal abierta en la carpeta [rdvmedecins2-flask], con el entorno virtual creado y activado, y las bibliotecas instaladas (véase la introducción):
La introducción mostró la salida de la consola. A continuación, abra la URL [http://localhost:8081] en un navegador y detenga la aplicación con [Ctrl-C].
11.3.5. Cuentas de demostración
La contraseña de cada cuenta es su nombre de usuario; además, debe introducir los caracteres de la imagen, en mayúsculas o minúsculas:
Nombres de usuario | Rol |
[admin] | ADMIN (el administrador) |
[pelissier], [tatou], [dupont] | DOCTOR (médicos) |
[martin], [durand], [bistrou], [german] | USER (pacientes) |
Una guía para explorar la aplicación:
- [admin]: agenda, Sra. 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 (se rechaza). Menús Médicos y Pacientes: 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], escrita manualmente, devuelve una página de error 403;
- [martin]: Mi área, su cita, el calendario en el que los demás pacientes aparecen como «Reservado»; Administrar mi cuenta;
- página de inicio de sesión: Crear una cuenta de paciente y luego iniciar sesión con la nueva cuenta;
- botones FR / EN: toda la interfaz cambia de idioma, incluidas las fechas.
11.3.6. Modo de desarrollo
El archivo [app.py] inicia la aplicación con el perfil [dev] (el archivo [config_dev.py], que se comenta más adelante): la consola muestra entonces cada comando SQL enviado a la base de datos por [SQLAlchemy]. El modo de depuración del servidor de desarrollo añade dos funciones:
- recarga automática: la aplicación se reinicia automáticamente en cuanto se modifica un archivo [.py]. Una vista [templates/*.html] modificada se recarga la próxima vez que se muestra la página;
- la página de depuración de excepciones (ejemplo 03), que aquí se desactiva con el parámetro [PROPAGATE_EXCEPTIONS = False] (véase más adelante): la aplicación muestra su propia página de error, incluso durante el desarrollo, y la pila de llamadas de la excepción se escribe en la consola.
El depurador de [Visual Studio Code] también permite ejecutar la aplicación paso a paso: establezca un punto de interrupción haciendo clic en el margen de una línea de código y luego inicie el archivo [app.py] mediante el menú Ejecutar / Iniciar depuración (tecla [F5]), seleccionando «Python Debugger» y luego «Python File». Conviene evitar la recarga automática (inicia la aplicación en un proceso aparte, que el depurador no sigue): desactívela iniciando la aplicación con el comando [flask --app rdvmedecins run --port 8081] (sin [--debug]).
11.3.7. Un servidor de producción
El servidor de desarrollo [Werkzeug] no está destinado a producción: él mismo lo indica al iniciar. En producción, la aplicación se despliega en un servidor WSGI (véase el capítulo sobre el ciclo de vida). La aplicación declara uno en su archivo [requirements.txt]: [Waitress], un servidor escrito en [Python], que funciona igual de bien en [Windows] que en [Linux]. Ya está instalado en el entorno virtual:
| waitress-serve --port=8081 --call rdvmedecins:create_app
|
| INFO:waitress:Serving on http://0.0.0.0:8081
|
La opción [--call] especifica una fábrica a la que llamar ([create_app], dentro del paquete [rdvmedecins]) para obtener la aplicación. Cuando se inicia de esta manera, la aplicación no tiene el perfil [dev] (la consola no muestra los comandos SQL) ni está en modo de depuración. [Waitress] procesa varias solicitudes en paralelo, en varios hilos (cuatro de forma predeterminada; opción [--threads]). En [Linux], [Gunicorn] también se utiliza ampliamente; sin embargo, no funciona en [Windows]. En ambos casos, el servidor WSGI suele colocarse detrás de un servidor web ([nginx], [Apache]), que atiende las solicitudes en modo HTTPS y las reenvía a la aplicación.
En producción, también debe cambiar las claves secretas e indicar, mediante variables de entorno, que el sitio se sirve por HTTPS:
| export FLASK_SECRET_KEY="<a long random string>"
export FLASK_JWT_SECRET="<another long random string>"
export FLASK_COOKIE_SECURE=true
|
Puede obtenerse una cadena aleatoria adecuada con [Python] mismo: [python -c "import secrets; print(secrets.token_urlsafe(48))"].
11.3.8. Problemas comunes
Al iniciar, la aplicación lee las listas de médicos y clientes: si la base de datos no está accesible, la aplicación se detiene de inmediato, con un error en la consola. Este error está precedido por una larga pila de llamadas; el mensaje relevante está al final, antes de la línea [(Background on this error at: ...)]. Por ejemplo, con una base de datos que no existe:
| ...
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (1049, "Unknown database 'dbunknown'")
(Background on this error at: https://sqlalche.me/e/21/e3q8)
|
Los mensajes más frecuentes:
Mensaje | Causa |
[Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)] ([[WinError 10061]] en [Windows]) | [MySQL] no se ha iniciado o no escucha en [localhost:3306] |
[Access denied for user 'root'@'localhost'] | Debe introducirse la contraseña de [MySQL] (véase «Configurar el acceso a la base de datos») |
[Unknown database 'dbrdvmedecins2'] | No se ha ejecutado el script [database/dbrdvmedecins2.sql] |
[JWT_SECRET must be at least 32 characters long (see config.py).] | La clave secreta de los tokens es demasiado corta en [config.py] (o en la variable [FLASK_JWT_SECRET]) |
[ModuleNotFoundError: No module named 'flask'] | El entorno virtual no está activado o las bibliotecas no se han instalado en él |
[Address already in use] o [Port 8081 is in use by another program] | El puerto 8081 ya está en uso (¿se está ejecutando la versión [Spring MVC] ?): deténgala o cambie el puerto en [app.py] |
['cryptography' package is required for sha256_password or caching_sha2_password auth methods] | La cuenta [MySQL] utiliza los parámetros de autenticación de [MySQL] 8: falta la biblioteca [cryptography], instalada por [PyMySQL[rsa]] (véase [requirements.txt]) |
[SyntaxError] al iniciar, en una línea [class ...[T: ...]] | la versión de [Python] es anterior a la 3.12 |
11.4. La arquitectura de la aplicación

- El navegador envía sus solicitudes al servidor (el servidor de desarrollo [Werkzeug] o [Waitress]), que las reenvía a la aplicación [Flask]. Cada solicitud pasa primero por las funciones [before_request] (véase el capítulo sobre el ciclo de vida): el idioma de la solicitud, luego el usuario (identificado a partir del token JWT de su cookie) y la regla de acceso, que niega las páginas protegidas a los visitantes que no están autorizados a verlas ([auth/security.py]);
- [controllers]: los controladores de la capa web, un blueprint por cada parte de la aplicación. Todos pasan por un único objeto, [ApplicationModel] (carpeta [web]), que almacena en memoria las listas de médicos y clientes y reenvía las demás solicitudes a la capa de negocio;
- [auth]: autenticación, tokens JWT, CAPTCHA, límites de intentos y creación de cuentas;
- [web]: elementos comunes de la capa web: el caché y la fachada [ApplicationModel], la traducción, los mensajes flash, la validación, las variables comunes a todas las vistas y las páginas de error; [forms]: formularios; [WTForms]; [models]: modelos de las vistas;
- [business]: reglas de negocio y transacciones;
- [repositories]: la capa DAO, una clase por tabla;
- [entities]: las entidades que [SQLAlchemy] lee y escribe en la base de datos; [domain]: los objetos del calendario, calculados por la capa de negocio;
- [templates]: las vistas [Jinja2], que generan las páginas HTML; [i18n]: los diccionarios, utilizados por el traductor; [static]: la hoja de estilos, el script de la página y [Bootstrap];
- [rdvmedecins/__init__.py]: el constructor [create_app], que lo ensambla todo; [config.py]: la configuración.
La carpeta de la aplicación:
| rdvmedecins2-flask/
├── app.py
├── config.py
├── config_dev.py
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── rdvmedecins/
│ ├── __init__.py
│ ├── auth/
│ │ ├── auth_service.py
│ │ ├── captcha.py
│ │ ├── captcha_drawing.py
│ │ ├── connected_user.py
│ │ ├── limiter.py
│ │ ├── passwords.py
│ │ ├── README.md
│ │ ├── registration_pass.py
│ │ └── security.py
│ ├── business/
│ │ ├── business.py
│ │ ├── dates.py
│ │ ├── exception.py
│ │ ├── person_data.py
│ │ ├── README.md
│ │ └── service.py
│ ├── controllers/
│ │ ├── area.py
│ │ ├── auth.py
│ │ ├── clients.py
│ │ ├── doctors.py
│ │ ├── language.py
│ │ ├── persons.py
│ │ ├── README.md
│ │ ├── registration.py
│ │ └── schedule.py
│ ├── domain/
│ │ ├── README.md
│ │ └── schedule.py
│ ├── entities/
│ │ ├── appointment.py
│ │ ├── base.py
│ │ ├── person.py
│ │ ├── README.md
│ │ ├── role.py
│ │ ├── slot.py
│ │ └── user.py
│ ├── forms/
│ │ ├── forms.py
│ │ ├── README.md
│ │ └── rules.py
│ ├── i18n/
│ │ ├── en.json
│ │ └── fr.json
│ ├── models/
│ │ ├── README.md
│ │ └── view_models.py
│ ├── repositories/
│ │ ├── appointment_repository.py
│ │ ├── client_repository.py
│ │ ├── doctor_repository.py
│ │ ├── person_repository.py
│ │ ├── README.md
│ │ ├── slot_repository.py
│ │ └── user_repository.py
│ ├── static/
│ │ ├── css/
│ │ │ └── styles.css
│ │ ├── js/
│ │ │ └── app.js
│ │ └── lib/
│ │ └── bootstrap/
│ ├── templates/
│ │ ├── account.html
│ │ ├── area.html
│ │ ├── error.html
│ │ ├── fragments/
│ │ │ ├── booking.html
│ │ │ ├── captcha.html
│ │ │ ├── confirmation.html
│ │ │ ├── errors.html
│ │ │ ├── flash.html
│ │ │ ├── navbar.html
│ │ │ └── person_fields.html
│ │ ├── layout.html
│ │ ├── login.html
│ │ ├── persons/
│ │ │ ├── form.html
│ │ │ └── list.html
│ │ ├── README.md
│ │ ├── registration.html
│ │ └── schedule.html
│ └── web/
│ ├── application_model.py
│ ├── common_model.py
│ ├── errors.py
│ ├── flash.py
│ ├── README.md
│ ├── services.py
│ ├── translator.py
│ ├── utils.py
│ └── validation.py
├── README.md
└── requirements.txt
|
Cada carpeta de paquete contiene además un archivo llamado [__init__.py], normalmente vacío, que convierte la carpeta en un [Python] paquete: esto es lo que permite escribir [from rdvmedecins.entities import Doctor]. [Bootstrap] forma parte de la aplicación (carpeta [static/lib/bootstrap]) esta vez: el caso de estudio es autónomo.
Observe la decisión tomada para el paquete [rdvmedecins]: la aplicación ya no es un simple módulo [app.py], sino un paquete, cuyo archivo [__init__.py] contiene la fábrica [create_app]. Es la estructura que recomienda la documentación de [Flask] para una aplicación de este tamaño: el archivo [app.py], situado en la raíz, sirve únicamente para iniciar el servidor de desarrollo.
11.5. La base de datos
La base de datos [dbrdvmedecins2] tiene cinco tablas:
- [users]: los usuarios autorizados a iniciar sesión;
- [doctors] y [clients]: médicos y pacientes, cada uno vinculado a su respectiva 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] obtienen una columna [user],
-- clave externa hacia users(id): cada médico y cada cliente es
-- ahora también un usuario que puede 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
-- - contraseña = 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 el
-- mismo nombre y apellido;
-- - unq_clients_first_name_last_name : lo mismo 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 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 "padres"
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 a 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 el mismo 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 el mismo 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, en 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 gestionar 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 tener en cuenta las mayúsculas ni los acentos (ejemplo 28);
- líneas 37–41: las tablas se eliminan y luego se vuelven a crear; el script restaura 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–54: users: un nombre de usuario, una contraseña con hash generado por [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–71: 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 que referencia [users(id)]: la base de datos rechaza cualquier valor que no sea el identificador de un usuario existente. Como [user] es una palabra reservada de 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–88: la tabla [clients] tiene exactamente las mismas columnas;
- líneas 94–102: una franja horaria pertenece a un médico; sus horas de inicio y de fin se almacenan en horas y minutos;
- líneas 108–117: una cita consta de un día (tipo [DATE], sin hora), una franja horaria y un cliente. La restricción [unq1_appointments] impide que la misma franja horaria se reserve dos veces el mismo día: la base de datos hace cumplir esta regla, incluso si dos usuarios la reservan al mismo tiempo;
- líneas 130–140: usuarios de demostración, cuya contraseña es su nombre de usuario. Los hashes comienzan con [$2b$10$]: el algoritmo ([bcrypt], variante [2b]) y el costo (10). A continuación vienen la sal y el hash;
- líneas 144–147: la columna [user] de cada médico se obtiene mediante una subconsulta basada en el nombre de usuario, 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: el calendario muestra así de inmediato una franja horaria reservada.
11.6. Configuración del proyecto
11.6.1. requirements.txt
| # las bibliotecas de la aplicación: pip install -r requirements.txt
Flask==3.1.3
Flask-WTF==1.3.0
SQLAlchemy==2.1.1
PyMySQL[rsa]==1.2.3
PyJWT==2.15.0
bcrypt==5.0.0
Babel==2.18.0
# un servidor WSGI para producción (vea README.md)
waitress==3.0.2
|
Las bibliotecas de la aplicación, con sus versiones exactas ([==]). Especificar las versiones garantiza que la aplicación funcione igual en todas las máquinas, incluso dentro de un año. [PyMySQL[rsa]] instala el controlador [PyMySQL] junto con sus dependencias opcionales [rsa], es decir, la biblioteca [cryptography], necesaria para los métodos de autenticación de [MySQL] 8. [pip install -r requirements.txt] instala estas bibliotecas y aquellas de las que dependen ([Werkzeug], [Jinja2], [WTForms]...). El comando [pip freeze] muestra la lista completa de lo que está instalado en el entorno virtual.
11.6.2. config.py
| # =========================================================================
# config.py - la configuración de la aplicación.
#
# Flask solo conserva las variables en MAYÚSCULAS (vea rdvmedecins/__init__.py,
# app.config.from_pyfile). Cada valor puede reemplazarse, sin modificar este
# archivo, mediante una variable de entorno con el prefijo FLASK_:
# DB_PASSWORD se escribe entonces FLASK_DB_PASSWORD (app.config.from_prefixed_env).
# Los valores de estas variables se leen como JSON cuando es posible:
# FLASK_LOGIN_MAX_FAILURES=3 da el número 3, FLASK_COOKIE_SECURE=true el booleano True.
# =========================================================================
# ---- la base de datos MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql):
# el servidor, su puerto, el usuario y su contraseña (los de Laragon:
# root, sin contraseña), la base de datos
DB_HOST = "localhost"
DB_PORT = 3306
DB_USER = "root"
DB_PASSWORD = ""
DB_NAME = "dbrdvmedecins2"
# True: las sentencias SQL enviadas a la base de datos se muestran en la consola
SQL_ECHO = False
# ---- la clave secreta de Flask: FIRMA la cookie de sesión (mensajes
# flash, token anti-CSRF). Debe cambiarse sin falta en producción.
SECRET_KEY = "change-me-too-to-a-long-random-string"
# ---- autenticación (vea rdvmedecins/auth/)
# clave secreta de los tokens JWT: al menos 32 caracteres (HMAC-SHA256).
# Debe cambiarse sin falta en producción (cadena aleatoria larga).
JWT_SECRET = "change-me-to-a-long-random-string"
# duración de validez de un token, en segundos (7200 s = 2 h); la cookie que
# transporta el token tiene la misma duración
JWT_EXPIRES_IN_SECONDS = 7200
# True en producción (sitio servido por HTTPS): las cookies de la aplicación
# nunca se envían entonces por una conexión sin cifrar
COOKIE_SECURE = False
# ---- protección contra robots (vea rdvmedecins/auth/limiter.py)
# inicio de sesión: fallos permitidos para un mismo login desde una misma dirección IP...
LOGIN_MAX_FAILURES = 5
# ... antes de un bloqueo de esta duración (toda la dirección IP también se bloquea
# si acumula 5 veces más fallos, todos los logins juntos)
LOGIN_BLOCK_MINUTES = 15
# creación de cuentas de cliente: máximo de cuentas creadas por hora y por dirección
# IP. En un salón de clases, todas las computadoras suelen salir por la misma dirección:
# auméntelo si es necesario.
REGISTRATION_MAX_PER_HOUR = 10
|
La configuración de la aplicación, leída por [app.config.from_pyfile] (ejemplo 25):
- líneas 15–19: acceso a la base de datos: el servidor, su puerto, el nombre de usuario y la contraseña, y la base de datos. Estos valores se utilizan para construir la cadena de conexión URL de [SQLAlchemy] (véase más adelante);
- línea 22: visualización de los comandos SQL, desactivada de forma predeterminada;
- línea 26: la clave secreta de [Flask], que firma la cookie de sesión (ejemplo 20);
- líneas 31–34: la clave que firma los tokens JWT y su duración: dos horas;
- línea 37: en producción, las cookies de la aplicación tienen el atributo [Secure]; el navegador las envía únicamente a través de una conexión HTTPS;
- líneas 41–48: parámetros de protección contra bots: el número de intentos fallidos de inicio de sesión permitidos y la duración del bloqueo resultante; el número de cuentas de cliente que una misma dirección IP puede crear por hora.
Cada valor puede reemplazarse por una variable de entorno con el prefijo [FLASK_]. Las dos claves secretas del archivo son solo valores de desarrollo: en producción deben reemplazarse (véase «Un servidor de producción»).
11.6.3. config_dev.py
| # =========================================================================
# config_dev.py - completa config.py en desarrollo (vea app.py, que inicia
# la aplicación con el perfil "dev"): las sentencias SQL enviadas por
# SQLAlchemy se muestran en la consola.
# =========================================================================
SQL_ECHO = True
|
El perfil de desarrollo: un segundo archivo, leído después de [config.py], cuyos valores reemplazan a los del primero. Solo contiene uno: la visualización de los comandos SQL. También podría escribirse un [config_test.py] para las pruebas, con una base de datos diferente.
11.7. Inicio de la aplicación
11.7.1. app.py
| # =========================================================================
# app.py - inicia la aplicación EN DESARROLLO: python app.py
#
# El servidor de desarrollo de Flask (Werkzeug), en el puerto 8081, con:
# - el perfil "dev" (config_dev.py: se muestran las sentencias SQL);
# - debug=True: la aplicación se reinicia sola en cuanto se modifica un archivo .py
# y una vista modificada se vuelve a leer al recargar la página.
# En producción se usa un verdadero servidor WSGI (vea README.md: waitress).
# =========================================================================
from rdvmedecins import create_app
if __name__ == "__main__":
create_app(profile="dev").run(port=8081, debug=True)
|
El archivo que inicia la aplicación en desarrollo: se llama a la fábrica [create_app] con el perfil [dev] y luego se entrega la aplicación al servidor de desarrollo en el puerto 8081 en modo de depuración. En producción, este archivo no se utiliza: el servidor WSGI llama a [create_app] (véase «Un servidor de producción»).
11.7.2. rdvmedecins/__init__.py
El constructor de la aplicación. Es el archivo que reúne todo lo demás: es el «plano» de la aplicación.
| # =========================================================================
# rdvmedecins/__init__.py
# -------------------------------------------------------------------------
# La FÁBRICA de la aplicación (vea el ejemplo 02): create_app construye y
# configura la aplicación Flask. Aquí se ensambla todo:
# 1. la configuración (config.py, config_dev.py, variables FLASK_...);
# 2. el acceso a la base de datos: el engine y la fábrica de sesiones de SQLAlchemy;
# 3. los objetos compartidos: DAO -> capa de negocio -> caché (ApplicationModel),
# autenticación, captcha, limitador, pases de registro, traductor -
# esto es inyección de dependencias, escrita "a mano";
# 4. lo que se ejecuta en cada solicitud: idioma, autenticación;
# 5. los blueprints (los controladores), los manejadores de errores, la
# protección anti-CSRF.
#
# Este archivo hace de [rdvmedecins] un PAQUETE Python: "from rdvmedecins
# import create_app" ejecuta este archivo.
# =========================================================================
from pathlib import Path
from flask import Flask, g, request
from flask_wtf.csrf import CSRFProtect
from sqlalchemy import URL, create_engine
from sqlalchemy.orm import sessionmaker
from rdvmedecins.auth import security
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.controllers.schedule import schedule
from rdvmedecins.controllers.auth import auth
from rdvmedecins.controllers.clients import clients
from rdvmedecins.controllers.area import area
from rdvmedecins.controllers.registration import registration
from rdvmedecins.controllers.language import language
from rdvmedecins.controllers.doctors import doctors
from rdvmedecins.business.service import BusinessService
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
from rdvmedecins.web import errors, common_model, translator
from rdvmedecins.web.application_model import ApplicationModel
from rdvmedecins.web.translator import Translator
# la carpeta del proyecto (la que contiene config.py), padre de este paquete
ROOT = Path(__file__).resolve().parent.parent
def create_app(profile: str | None = None) -> Flask:
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
# ---- 1. la configuración: config.py, luego config_<perfil>.py si hay
# un perfil, luego las variables de entorno FLASK_...
app.config.from_pyfile(ROOT / "config.py")
if profile:
app.config.from_pyfile(ROOT / f"config_{profile}.py")
app.config.from_prefixed_env()
app.config.update(
# la cookie de sesión de Flask (mensajes flash, token anti-CSRF)
SESSION_COOKIE_NAME="rdvmedecins_session",
SESSION_COOKIE_SAMESITE="Lax",
SESSION_COOKIE_SECURE=app.config["COOKIE_SECURE"],
# el token anti-CSRF sigue siendo válido mientras dure la sesión del navegador
WTF_CSRF_TIME_LIMIT=None,
# una excepción no controlada se entrega a nuestros manejadores de errores
# (página 500), incluso en modo debug
PROPAGATE_EXCEPTIONS=False,
)
# ---- 2. acceso a la base de datos. La URL de conexión de SQLAlchemy
# (mysql+pymysql://root:@localhost:3306/dbrdvmedecins2?charset=utf8mb4),
# construida por URL.create: una contraseña que contiene caracteres
# especiales (@, :, /...) se codifica correctamente en ella. str(...): una variable
# FLASK_DB_PASSWORD=123456 se leería como un NÚMERO (vea config.py)
url = URL.create("mysql+pymysql", username=str(app.config["DB_USER"]),
password=str(app.config["DB_PASSWORD"]), host=app.config["DB_HOST"],
port=int(app.config["DB_PORT"]), database=app.config["DB_NAME"],
query={"charset": "utf8mb4"})
# El engine administra un POOL de conexiones; pool_pre_ping: una conexión se
# prueba antes de reutilizarse; pool_recycle: se renueva después de
# una hora (MySQL cierra por sí mismo las conexiones que llevan
# demasiado tiempo inactivas)
engine = create_engine(url, echo=app.config["SQL_ECHO"], pool_pre_ping=True,
pool_recycle=3600)
# expire_on_commit=False: los objetos leídos siguen siendo utilizables después del fin
# de la transacción (por las vistas, por el caché)
sessions = sessionmaker(engine, expire_on_commit=False)
# ---- 3. los objetos compartidos, creados de una vez por todas
business = BusinessService(sessions, DoctorRepository(), ClientRepository(),
SlotRepository(), AppointmentRepository(), UserRepository())
# el caché lee los médicos y los clientes: una base de datos inalcanzable detiene
# la aplicación AQUÍ, al iniciar
app.extensions["rdvmedecins.application"] = ApplicationModel(business)
auth_service = AuthService(sessions, UserRepository(), app.config["JWT_SECRET"],
app.config["JWT_EXPIRES_IN_SECONDS"], app.config["COOKIE_SECURE"])
app.extensions["rdvmedecins.auth"] = auth_service
app.extensions["rdvmedecins.captchas"] = CaptchaService()
app.extensions["rdvmedecins.limiter"] = AttemptLimiter(
app.config["LOGIN_MAX_FAILURES"], app.config["LOGIN_BLOCK_MINUTES"],
app.config["REGISTRATION_MAX_PER_HOUR"])
app.extensions["rdvmedecins.passes"] = RegistrationPass()
trans = Translator(Path(app.root_path) / "i18n")
# ---- 4. en cada solicitud, en el orden de registro:
# el idioma (cookie rdvmedecins_language, inglés en caso contrario)...
@app.before_request
def set_language():
g.language = translator.language(request.cookies.get(translator.LANGUAGE_COOKIE))
# ... luego el usuario, y la regla de acceso (vea auth/security.py)
security.register(app, auth_service)
# las variables comunes a todas las vistas
common_model.register(app, trans)
# ---- 5. los controladores, las páginas de error, la protección anti-CSRF
for blueprint in (auth, language, schedule, doctors, clients, registration, area):
app.register_blueprint(blueprint)
errors.register(app)
# toda solicitud POST debe devolver el token anti-CSRF de la página
# (campo oculto csrf_token): de lo contrario, respuesta 400
CSRFProtect(app)
return app
|
- línea 48: la carpeta del proyecto, que contiene [config.py]: la carpeta superior ([parent.parent]) de la carpeta de este archivo;
- líneas 52–54: la aplicación; [__name__] equivale aquí a [rdvmedecins], el nombre del paquete: [Flask] busca, por tanto, las carpetas [templates] y [static] dentro de la carpeta del paquete;
- líneas 58–61: la configuración, en tres pasos: el archivo [config.py], el archivo del perfil (si lo hay) y las variables de entorno. Cada fuente reemplaza los valores de las anteriores;
- líneas 62–71: algunos parámetros de [Flask] y de [Flask-WTF], escritos aquí en lugar de en [config.py] porque no están pensados para cambiarse. [SESSION_COOKIE_NAME] cambia el nombre de la cookie de sesión (valor predeterminado: [session]) para que no entre en conflicto con la de otra aplicación servida desde [localhost], como se vio en los ejemplos; [SESSION_COOKIE_SAMESITE] y [SESSION_COOKIE_SECURE] le asignan los atributos [SameSite=Lax] y, en producción, [Secure] (ejemplo 25). [WTF_CSRF_TIME_LIMIT=None]: de forma predeterminada, un token anti-CSRF es válido solo durante una hora, y un formulario que se deje abierto más tiempo sería rechazado; aquí sigue siendo válido durante toda la sesión del navegador. [PROPAGATE_EXCEPTIONS=False]: en modo de depuración, [Flask] permite que ciertas excepciones se propaguen hasta la página de depuración; este parámetro hace que pasen por nuestros manejadores de errores;
- líneas 79–82: la URL de conexión para [SQLAlchemy] (ejemplo 28), generada por [URL.create] a partir de sus componentes. Cuando se escribe a mano, una URL debe codificar los caracteres especiales de una contraseña ([@], [:], [/]...), que tienen un significado dentro de una URL; [URL.create] lo hace por sí mismo. [str(...)] e [int(...)] protegen frente a las conversiones de las variables de entorno: [FLASK_DB_PASSWORD=123456] se interpretaría como un número;
- líneas 87–88: el engine y su grupo de conexiones. [pool_recycle=3600] renueva una conexión después de una hora; [MySQL] cierra automáticamente las conexiones que han estado inactivas demasiado tiempo (ocho horas de forma predeterminada);
- línea 91: la fábrica de sesiones (ejemplo 28);
- líneas 94–106: objetos compartidos, creados de una vez por todas y almacenados en [app.extensions] (ejemplo 06). Es inyección de dependencias, escrita a mano: cada objeto recibe en su constructor los objetos que necesita. La capa de negocio recibe la fábrica de sesiones y las cinco clases de la capa DAO; el caché [ApplicationModel] recibe la capa de negocio; el servicio de autenticación recibe la fábrica de sesiones, la clase DAO de usuarios y la configuración de los tokens. Las claves de [app.extensions] llevan el prefijo [rdvmedecins.] para evitar conflictos con las de las extensiones ([Flask-WTF] también almacena allí sus objetos). El constructor de [ApplicationModel] lee la lista de médicos y clientes: si la base de datos no está accesible, la aplicación se detiene aquí, al iniciar, y no en la primera solicitud;
- línea 107: el servicio de traducción (ejemplo 22);
- líneas 111–113: la primera función [before_request] obtiene el idioma de la solicitud a partir de la cookie [rdvmedecins_language];
- línea 116: la segunda: el usuario de la solicitud y la regla de acceso (véase [auth/security.py]). El orden importa: la página de inicio de sesión a la que se redirige a un visitante no autorizado necesita conocer el idioma;
- línea 118: las variables comunes a todas las vistas (el procesador de contexto del ejemplo 15; véase [web/common_model.py]);
- líneas 121–122: los siete blueprints de la aplicación;
- línea 123: los manejadores de errores (véase [web/errors.py]);
- línea 126: protección CSRF para todas las solicitudes (POST, ejemplo 21).
Este archivo equivale a la clase de inicio y a las clases de configuración de una aplicación [Spring Boot], y al archivo [Program.cs] de una aplicación [ASP.NET Core]. La diferencia principal: [Flask] no crea ni inyecta nada por sí mismo. Todo lo que existe en la aplicación se creó aquí de forma explícita, y se puede seguir cada objeto desde su creación hasta su uso.
11.8. Entidades
La carpeta [entities] contiene una clase por tabla: las entidades que [SQLAlchemy] lee y escribe en la base de datos (ejemplo 28). Sus atributos se nombran según las columnas, salvo indicación en contrario.
11.8.1. entities/base.py
| # =========================================================================
# entities/base.py
# -------------------------------------------------------------------------
# La clase padre de todas las entidades, y las dos columnas comunes a
# todas las tablas: el identificador [id] y el número de versión [version].
#
# SQLAlchemy "declarativo": cada clase hija de Base describe una tabla
# (__tablename__), cada atributo Mapped[...] una columna. SQLAlchemy lee
# estas declaraciones al iniciar para saber qué clase corresponde a qué
# tabla, y qué atributo a qué columna.
# =========================================================================
from sqlalchemy.orm import DeclarativeBase, Mapped, declared_attr, mapped_column
class Base(DeclarativeBase):
pass
# un MIXIN: una clase sin tabla, cuyas columnas se agregan a las
# de las clases que heredan de ella (Doctor, Client, Slot, Appointment, User)
class WithIdAndVersion:
# la clave primaria, generada por la base de datos (columna AUTO_INCREMENT):
# SQLAlchemy vuelve a leer su valor después de cada INSERT. Una entidad aún no
# guardada tiene un id None.
id: Mapped[int] = mapped_column(primary_key=True)
# el bloqueo optimista. Cada UPDATE enviado por SQLAlchemy lleva la
# condición "WHERE id = ... AND version = <valor leído>", y escribe la
# versión incrementada en 1. Si alguien modificó la fila mientras tanto,
# no se actualiza ninguna fila: SQLAlchemy lanza una StaleDataError
# (vea business/service.py).
version: Mapped[int] = mapped_column()
# @declared_attr: un atributo calculado para CADA clase hija;
# version_id_col: la columna usada como bloqueo optimista
@declared_attr.directive
def __mapper_args__(cls):
return {"version_id_col": cls.version}
|
- líneas 15–16: la clase padre de todas las entidades (ejemplo 28);
- líneas 21–39: las dos columnas comunes a todas las tablas, [id] y [version], definidas una sola vez. [WithIdAndVersion] es un mixin: una clase que no tiene tabla y nunca se crea por sí sola, pero de la cual las clases hijas heredan columnas. Una entidad hereda así de dos clases: [class User(WithIdAndVersion, Base)] (herencia múltiple de [Python]);
- líneas 37–39: el bloqueo optimista (ejemplo 28). [__mapper_args__] debe hacer referencia a la columna [version] de cada clase hija, no a la del mixin: el decorador [@declared_attr.directive] convierte este método en un atributo calculado para cada clase que hereda del mixin. [SQLAlchemy] lo invoca cuando analiza la clase hija, pasándole la clase hija como parámetro ([cls]).
11.8.2. entities/role.py
| # =========================================================================
# entities/role.py
# -------------------------------------------------------------------------
# Los tres roles de un usuario (columna users.role):
# - ADMIN : el administrador - citas + gestión de médicos y clientes;
# - DOCTOR : un médico - reserva y cancela citas;
# - USER : un cliente (paciente) - reserva para sí mismo, gestiona su cuenta.
#
# Una enumeración (Enum): no es posible ningún otro valor. StrEnum: sus
# valores también son cadenas ("ADMIN"), almacenadas tal cual en la base de datos,
# como lo hace el script SQL (vea user.py).
# =========================================================================
from enum import StrEnum
class Role(StrEnum):
ADMIN = "ADMIN"
DOCTOR = "DOCTOR"
USER = "USER"
|
Una enumeración: un tipo cuyos valores posibles se fijan de una vez por todas ([Role.ADMIN], [Role.DOCTOR], [Role.USER]). [StrEnum] (módulo estándar [enum], [Python] 3.11): cada valor es también una cadena, igual a ["ADMIN"], etc. Por lo tanto, puede compararse con una cadena, escribirse en un token JWT o incluirse en una página sin conversión.
11.8.3. entities/user.py
| # =========================================================================
# entities/user.py
# -------------------------------------------------------------------------
# Un usuario autorizado a iniciar sesión en la aplicación (tabla [users]).
# Cada médico y cada cliente tiene SU cuenta de usuario (columna
# [user] de las tablas [doctors] y [clients], vea person.py).
#
# Restricción de unicidad SQL: unq_users_login (un login pertenece a una sola
# cuenta). La crea el script database/dbrdvmedecins2.sql;
# la capa de negocio la reconoce por su NOMBRE (vea business/service.py).
# =========================================================================
from sqlalchemy import Enum, String
from sqlalchemy.orm import Mapped, mapped_column
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.role import Role
class User(WithIdAndVersion, Base):
__tablename__ = "users"
login: Mapped[str] = mapped_column(String(30))
# la contraseña con HASH (bcrypt) - nunca en claro
password: Mapped[str] = mapped_column(String(100))
# el nombre que se muestra una vez iniciada la sesión - para un médico o un cliente:
# "nombre APELLIDO" (p. ej.: "Marie PELISSIER")
name: Mapped[str] = mapped_column(String(40))
# ADMIN, DOCTOR o USER, almacenado en la base de datos como texto.
# native_enum=False: una simple columna VARCHAR (y no el tipo ENUM de MySQL)
role: Mapped[Role] = mapped_column(Enum(Role, native_enum=False, length=10))
|
- línea 19: la entidad hereda el identificador y la versión del mixin, y de [Base];
- línea 24: la contraseña con hash;
- línea 30: un atributo de tipo [Role]. El tipo [Enum] de [SQLAlchemy] convierte la enumeración en texto al escribir (["ADMIN"]) y el texto en enumeración al leer. [native_enum=False]: la columna es un simple [VARCHAR], como en el script SQL, y no el tipo [ENUM] propio de [MySQL].
11.8.4. entities/person.py
| # =========================================================================
# entities/person.py
# -------------------------------------------------------------------------
# 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 el mixin Person, del que heredan Doctor y Client. Una
# relación declarada en un mixin debe declararse mediante un método @declared_attr:
# SQLAlchemy lo invoca para cada clase hija, que recibe así SU relación.
#
# Atención: [Client] aquí designa a un PACIENTE del consultorio médico, ¡no a un
# cliente HTTP! Es el vocabulario del dominio de negocio original, conservado
# tal cual (tabla [clients]).
#
# Restricciones de unicidad SQL: unq_doctors_first_name_last_name, unq_clients_first_name_last_name
# (dos médicos, o dos clientes, no pueden tener el mismo nombre y
# apellido) - creadas por el script SQL, reconocidas por su nombre en la capa de negocio.
# =========================================================================
from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import Mapped, declared_attr, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.user import User
class Person(WithIdAndVersion):
title: Mapped[str] = mapped_column(String(5)) # Melle, Mme, Mr
last_name: Mapped[str] = mapped_column(String(20))
first_name: Mapped[str] = mapped_column(String(20))
# la clave externa a users(id), leída como un simple número: así conocemos
# el id de la cuenta sin cargar el User. "user" es el nombre de la
# columna (una palabra clave SQL, que SQLAlchemy mismo encierra entre
# comillas invertidas `user` si el SGBD lo exige); user_id, el del atributo Python
@declared_attr
def user_id(cls) -> Mapped[int]:
return mapped_column("user", ForeignKey("users.id"))
# -----------------------------------------------------------------------
# La relación con la cuenta de usuario: un médico (un cliente) tiene UNA
# cuenta. relationship: el atributo [user] es un objeto User, y no un
# número. SQLAlchemy solo lo lee de la base de datos si se le pide: en la
# consulta (opciones joinedload, vea repositories/), o en el primer acceso al
# atributo, mientras la sesión siga abierta.
# -----------------------------------------------------------------------
@declared_attr
def user(cls) -> Mapped[User]:
return relationship()
class Doctor(Person, Base):
__tablename__ = "doctors"
class Client(Person, Base):
__tablename__ = "clients"
|
- línea 27: como las tablas [doctors] y [clients] tienen exactamente las mismas columnas, se describen una sola vez en el mixin [Person], que a su vez hereda del mixin [WithIdAndVersion];
- líneas 29–31: las columnas ordinarias, declaradas como en el ejemplo 28;
- líneas 9–39: la clave externa a la cuenta de usuario. En un mixin, una columna que sirve de clave externa debe declararse mediante el método [@declared_attr]: cada clase hija recibe así su propia columna. [ForeignKey("users.id")] especifica la columna referenciada; el primer parámetro de [mapped_column] es el nombre de la columna en la tabla ([user]), que difiere del del atributo [Python] ([user_id]);
- líneas 37–50: la relación con la cuenta: el atributo [user] es un objeto [User], no un número. [SQLAlchemy] deduce la unión por clave externa. Una relación no es una columna: es un medio para obtener el objeto vinculado. De forma predeterminada, [SQLAlchemy] solo la lee de la base de datos en el primer acceso al atributo (carga diferida), lo que supone que la sesión siga abierta;
- líneas 53–58: dos entidades, que difieren solo en su tabla.
Observe la terminología: un [Client] designa aquí a un paciente del consultorio médico, no a un cliente HTTP. Es la terminología de la aplicación original, que se conserva tal cual.
11.8.5. entities/slot.py
| # =========================================================================
# entities/slot.py
# -------------------------------------------------------------------------
# Un intervalo horario de un médico (tabla [slots]): 8:00 - 8:20, etc.
# =========================================================================
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.person import Doctor
class Slot(WithIdAndVersion, Base):
__tablename__ = "slots"
start_hour: Mapped[int] # hora de inicio de la franja
start_minute: Mapped[int] # minuto de inicio de la franja
end_hour: Mapped[int] # hora de fin de la franja
end_minute: Mapped[int] # minuto de fin de la franja
# varios intervalos para el mismo médico: la clave externa [doctor_id]
# (un número), y la relación [doctor] (el objeto Doctor)
doctor_id: Mapped[int] = mapped_column(ForeignKey("doctors.id"))
doctor: Mapped[Doctor] = relationship()
|
Una franja horaria y su médico: la clave externa [doctor_id] (un número) y la relación [doctor] (el objeto). Sin mixin, la relación se declara directamente, como un atributo.
11.8.6. entities/appointment.py
| # =========================================================================
# entities/appointment.py
# -------------------------------------------------------------------------
# Una cita (tabla [appointments]): un cliente, en un intervalo, en un día dado.
#
# Restricción de unicidad SQL: unq1_appointments (day, slot_id) - un intervalo se
# reserva una sola vez por día. La crea el script SQL, reconocida por su
# nombre en la capa de negocio.
# =========================================================================
from datetime import date
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client
class Appointment(WithIdAndVersion, Base):
__tablename__ = "appointments"
# date: una fecha SIN hora, que corresponde exactamente al tipo SQL DATE
# de la columna [day]
day: Mapped[date]
client_id: Mapped[int] = mapped_column(ForeignKey("clients.id"))
client: Mapped[Client] = relationship()
slot_id: Mapped[int] = mapped_column(ForeignKey("slots.id"))
slot: Mapped[Slot] = relationship()
|
- línea 25: el tipo [date] de [Python], una fecha sin hora, corresponde exactamente al tipo SQL [DATE];
- líneas 27–31: las dos claves externas y sus relaciones.
11.8.7. entities/__init__.py
| # =========================================================================
# entities/ - las ENTIDADES: una clase por tabla de la base de datos dbrdvmedecins2.
# Este archivo agrupa las importaciones: "from rdvmedecins.entities import
# Doctor" basta en el resto de la aplicación.
# =========================================================================
from rdvmedecins.entities.base import Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client, Doctor, Person
from rdvmedecins.entities.role import Role
from rdvmedecins.entities.appointment import Appointment
from rdvmedecins.entities.user import User
__all__ = ["Base", "Client", "Slot", "Doctor", "Person", "Role", "Appointment", "User"]
|
El archivo [__init__.py] de un paquete se ejecuta cuando se importa el paquete. Este archivo importa las entidades desde sus respectivos módulos; en el resto del código, [from rdvmedecins.entities import Doctor] basta, sin necesidad de saber en qué módulo está definida la clase. La lista [__all__] declara los nombres que el paquete pone a disposición.
11.9. SQLAlchemy: sesiones y carga de relaciones
El ejemplo 28 trató los fundamentos de [SQLAlchemy]. El caso de estudio utiliza dos aspectos adicionales, relacionados entre sí.
La vida útil de los objetos leídos. Cada método de la capa de negocio abre una sesión y una transacción, y las cierra al salir (ejemplo 28). Las entidades que devuelve quedan entonces desconectadas: ya no están asociadas a ninguna sesión. Gracias al parámetro [expire_on_commit=False], sus atributos ordinarios siguen siendo legibles. Sin embargo, una relación que no se haya cargado ya no puede cargarse: habría que consultar la base de datos y ya no hay sesión. El acceso al atributo lanza entonces una excepción [DetachedInstanceError]. Es el problema que [Spring Boot] resuelve, junto con [Hibernate], mediante el parámetro [open-in-view] (una sesión abierta durante toda la solicitud), que la versión [Spring MVC] del caso de estudio desactivó por la misma razón que nosotros: una vista no debe desencadenar consultas SQL. La regla es, por tanto: cada método de la capa DAO carga explícitamente las relaciones que necesitará quien lo llama.
Opciones de carga. [SQLAlchemy] ofrece varias maneras de cargar una relación junto con la entidad:
- [joinedload(Doctor.user)]: añade una unión ([LEFT OUTER JOIN users ...]) a la consulta, cuyas columnas se utilizan para construir los objetos [User]. Una sola consulta devuelve los médicos y sus cuentas;
- [contains_eager(Appointment.slot)]: cuando la consulta ya contiene una unión ([select(Appointment).join(Appointment.slot)], escrita para filtrar por una columna de la tabla unida), esta opción indica a [SQLAlchemy] que use las columnas de esa unión para poblar la relación, en lugar de añadir una segunda;
- Las opciones se encadenan para cargar una relación a partir de otra relación: [contains_eager(Appointment.slot).joinedload(Slot.doctor)] carga la franja horaria de cada cita y luego el médico de cada franja horaria.
Son los equivalentes de [JOIN FETCH] en [JPA] y de [Include] en [Entity Framework Core].
11.10. El dominio: el calendario
11.10.1. domain/schedule.py
| # =========================================================================
# domain/schedule.py
# -------------------------------------------------------------------------
# Objetos de "negocio" calculados, que no corresponden a ninguna tabla:
# - DoctorDaySlot: un intervalo horario, y la cita eventualmente
# reservada en ese intervalo en un día dado (None si el intervalo está libre);
# - DoctorDaySchedule: la agenda completa de un médico para un día dado,
# la lista de sus intervalos, cada uno libre o reservado. La calcula
# BusinessService.get_doctor_day_schedule, y controllers/schedule.py la convierte
# en una tabla HTML.
#
# frozen=True: objetos inmutables, cuyos campos los fija una vez
# por todas el constructor - exactamente lo que se necesita para un
# objeto calculado, que nadie modifica después.
# =========================================================================
from dataclasses import dataclass
from datetime import date
from rdvmedecins.entities import Slot, Doctor, Appointment
@dataclass(frozen=True)
class DoctorDaySlot:
slot: Slot
appointment: Appointment | None
@dataclass(frozen=True)
class DoctorDaySchedule:
doctor: Doctor
day: date
doctor_day_slots: list[DoctorDaySlot]
|
Dos clases que no corresponden a ninguna tabla: la agenda de un médico para un solo día, calculada por la capa de negocio. [DoctorDaySlot] asocia una franja horaria con la cita reservada en esa franja ese día, o con [None] si está disponible; [DoctorDaySchedule] combina el médico, el día y la lista de franjas horarias del médico. Son objetos [dataclass] inmutables ([frozen=True]): un objeto calculado que nadie modifica después.
11.11. La capa DAO
La carpeta [repositories] (el nombre inglés habitual de las clases DAO, «repositories») contiene una clase por entidad. Como en el ejemplo 28, cada método recibe la sesión abierta por la capa de negocio y no contiene lógica de negocio.
11.11.1. repositories/person_repository.py
| # =========================================================================
# repositories/person_repository.py
# -------------------------------------------------------------------------
# La capa DAO común a los médicos y los clientes.
#
# Cada método recibe la SESIÓN de SQLAlchemy abierta por la capa
# de negocio (vea business/service.py): todas las consultas de la misma operación
# usan así la misma conexión y la misma TRANSACCIÓN.
#
# Las consultas se escriben con los objetos de SQLAlchemy (select, where,
# order_by...), que se aplican a las CLASES y sus atributos; SQLAlchemy
# las traduce a SQL. Los valores (first_name, last_name...) pasan a ser PARÁMETROS
# de la consulta: sin concatenación de cadenas, y por lo tanto sin inyección SQL.
#
# Los DAO de los médicos y de los clientes serían idénticos: esta clase
# GENÉRICA los escribe una sola vez. [T: Person]: un parámetro de tipo,
# que es Doctor o Client; self.entity es la clase correspondiente.
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Person
class PersonRepository[T: Person]:
def __init__(self, entity: type[T]):
self.entity = entity
# lista ordenada por apellido y luego por nombre, cuenta de usuario incluida.
# joinedload(user): trae TAMBIÉN la cuenta, mediante una unión (join)
# (SELECT ... FROM doctors LEFT OUTER JOIN users ...). Sin él, la
# cuenta solo se leería en el primer acceso - imposible una vez cerrada la sesión:
# estas listas las conserva en memoria el caché
# (web/application_model.py), mucho después del fin de la solicitud.
def list(self, session: Session) -> list[T]:
e = self.entity
query = select(e).options(joinedload(e.user)).order_by(e.last_name, e.first_name)
return list(session.scalars(query))
# una persona y su cuenta; None si no existen
def read(self, session: Session, id: int) -> T | None:
return session.get(self.entity, id, options=[joinedload(self.entity.user)])
# la persona cuya cuenta de usuario es [user_id]
def read_by_user(self, session: Session, user_id: int) -> T | None:
e = self.entity
query = select(e).options(joinedload(e.user)).where(e.user_id == user_id)
return session.scalars(query).first()
# la persona que tiene este nombre y apellido, si la hay. La comparación
# la hace MySQL, y por lo tanto con la 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 de unicidad SQL.
def namesake(self, session: Session, first_name: str, last_name: str) -> T | None:
e = self.entity
return session.scalars(select(e).where(e.first_name == first_name, e.last_name == last_name).limit(1)).first()
def add(self, session: Session, person: T) -> T:
session.add(person)
return person
# un DELETE enviado directamente a la base de datos, sin leer antes a la persona
def remove(self, session: Session, id: int):
session.execute(delete(self.entity).where(self.entity.id == id))
|
- línea 25: una clase genérica, escrita con la sintaxis de [Python] 3.12 (PEP 695). [T] es un parámetro de tipo: la clase se usará como [PersonRepository[Doctor]] o [PersonRepository[Client]]. [T: Person] restringe [T] a las clases que heredan de [Person]. [Python] no verifica los tipos en tiempo de ejecución (ejemplo 06): documentan el código y permiten que el editor sepa que [list()] devuelve una lista de [Doctor] para el DAO de médicos. Antes de [Python] 3.12, se habría escrito [T = TypeVar("T", bound=Person)] seguido de [class PersonRepository(Generic[T])];
- líneas 27–28: el parámetro de tipo no existe en tiempo de ejecución: por eso la clase real ([Doctor] o [Client]) se pasa al constructor y se almacena en [self.entity]. [type[T]] es el tipo de una clase (no de un objeto);
- líneas 36–39: la lista ordenada, con el recuento de cada persona, cargada mediante una unión ([joinedload]). Esto es esencial aquí: estas listas se conservan en memoria en el caché [ApplicationModel], mucho después de que la sesión haya terminado;
- líneas 42–43: la lectura por clave primaria también acepta opciones de carga;
- líneas 46–49: la persona asociada a una cuenta; así se identifica al cliente que inició sesión;
- líneas 55–57: búsqueda de un homónimo. La comparación la realiza [MySQL], con la intercalación de la base de datos: es exactamente la regla de la restricción de unicidad;
- líneas 59–61: el alta, sin [flush]: la capa de negocio decide cuándo se envían los comandos SQL;
- líneas 64–65: un [DELETE] enviado directamente a la base de datos.
11.11.2. repositories/doctor_repository.py
| # =========================================================================
# repositories/doctor_repository.py
# -------------------------------------------------------------------------
# El DAO de los médicos: todo se hereda de PersonRepository.
# =========================================================================
from rdvmedecins.entities import Doctor
from rdvmedecins.repositories.person_repository import PersonRepository
class DoctorRepository(PersonRepository[Doctor]):
def __init__(self):
super().__init__(Doctor)
|
La clase DAO de los médicos hereda de [PersonRepository[Doctor]] y pasa la clase [Doctor] al constructor de su clase padre; todo lo demás se hereda.
11.11.3. repositories/client_repository.py
| # =========================================================================
# repositories/client_repository.py
# -------------------------------------------------------------------------
# El DAO de los clientes: el de las personas, más un método de bloqueo.
# =========================================================================
from sqlalchemy import select
from sqlalchemy.orm import Session
from rdvmedecins.entities import Client
from rdvmedecins.repositories.person_repository import PersonRepository
class ClientRepository(PersonRepository[Client]):
def __init__(self):
super().__init__(Client)
# -----------------------------------------------------------------------
# pone un BLOQUEO (LOCK) en la fila de un cliente hasta el final de la
# transacción actual (SELECT ... FOR UPDATE), y devuelve su id (None
# si el cliente no existe). Una segunda transacción que pida el mismo
# bloqueo ESPERA a que termine la primera.
# Se usa para reservar una cita (vea 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.
# with_for_update: agrega "FOR UPDATE" a la consulta.
# -----------------------------------------------------------------------
def lock(self, session: Session, id: int) -> int | None:
return session.scalars(select(Client.id).where(Client.id == id).with_for_update()).first()
|
- líneas 28–29: un método más, que coloca un bloqueo en el registro de un cliente: [with_for_update()] añade [FOR UPDATE] a la consulta ([SELECT clients.id FROM clients WHERE clients.id = ? FOR UPDATE]). Hasta que termine la transacción, cualquier otra transacción que solicite el mismo bloqueo espera. La capa de negocio lo utiliza para programar citas: dos citas 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 (regla: una sola cita próxima por paciente). Este bloqueo pesimista complementa al bloqueo optimista: el bloqueo optimista detecta una modificación concurrente de una fila, mientras que el bloqueo pesimista impide que dos transacciones tomen una decisión basada en los mismos datos al mismo tiempo.
11.11.4. repositories/slot_repository.py
| # =========================================================================
# repositories/slot_repository.py
# -------------------------------------------------------------------------
# Capa DAO de la entidad [Slot].
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Slot
class SlotRepository:
# un intervalo y su médico
def read(self, session: Session, id: int) -> Slot | None:
return session.get(Slot, id, options=[joinedload(Slot.doctor)])
# los intervalos de un médico, en orden cronológico
def list_by_doctor(self, session: Session, doctor_id: int) -> list[Slot]:
query = (select(Slot).where(Slot.doctor_id == doctor_id)
.order_by(Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# elimina todos los intervalos de un médico (eliminación de un médico):
# DELETE FROM slots WHERE doctor_id = ?
def delete_by_doctor(self, session: Session, doctor_id: int):
session.execute(delete(Slot).where(Slot.doctor_id == doctor_id))
|
Una franja horaria (con su médico), las franjas horarias de un médico en orden cronológico y la eliminación de las franjas horarias de un médico (cuando se elimina al médico).
11.11.5. repositories/appointment_repository.py
| # =========================================================================
# repositories/appointment_repository.py
# -------------------------------------------------------------------------
# Capa DAO de la entidad [Appointment].
#
# join(Appointment.slot): una unión SQL, escrita a partir de la RELACIÓN entre
# las dos clases (SQLAlchemy conoce la clave externa). contains_eager:
# las columnas de la tabla unida sirven TAMBIÉN para llenar la relación
# (appointment.slot), sin una nueva consulta.
# =========================================================================
from datetime import date
from sqlalchemy import delete, func, select
from sqlalchemy.orm import Session, contains_eager, joinedload
from rdvmedecins.entities import Slot, Appointment
class AppointmentRepository:
# una cita, su cliente y su intervalo
def read(self, session: Session, id: int) -> Appointment | None:
return session.get(Appointment, id, options=[joinedload(Appointment.client), joinedload(Appointment.slot)])
# las citas de un médico en un día dado, cliente e intervalo incluidos.
# La tabla [appointments] no hace referencia directa al médico: pasamos por el intervalo.
def doctor_day_appointments(self, session: Session, doctor_id: int, day: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot), joinedload(Appointment.client))
.where(Slot.doctor_id == doctor_id, Appointment.day == day))
return list(session.scalars(query))
# las citas de un cliente desde el día [since] (incluido), en
# orden cronológico, con el intervalo Y el médico de ese intervalo
def client_upcoming_appointments(self, session: Session, client_id: int, since: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot).joinedload(Slot.doctor))
.where(Appointment.client_id == client_id, Appointment.day >= since)
.order_by(Appointment.day, Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# número de citas de un cliente desde el día [since] (incluido)
def count_client_upcoming(self, session: Session, client_id: int, since: date) -> int:
query = select(func.count(Appointment.id)).where(Appointment.client_id == client_id, Appointment.day >= since)
return session.scalar(query)
# número de citas (pasadas o futuras) de un médico
def count_by_doctor(self, session: Session, doctor_id: int) -> int:
query = select(func.count(Appointment.id)).join(Appointment.slot).where(Slot.doctor_id == doctor_id)
return session.scalar(query)
def add(self, session: Session, appointment: Appointment) -> Appointment:
session.add(appointment)
return appointment
# elimina una cita: DELETE FROM appointments WHERE id = ?
def remove(self, session: Session, id: int):
session.execute(delete(Appointment).where(Appointment.id == id))
# elimina TODAS las citas (pasadas y futuras) de un cliente
def delete_by_client(self, session: Session, client_id: int):
session.execute(delete(Appointment).where(Appointment.client_id == client_id))
|
- líneas 27–31: las citas de un médico en un día determinado. La tabla [appointments] no hace referencia directa al médico: pasa por la franja horaria. [join(Appointment.slot)] escribe la unión a partir de la relación; el filtro se aplica a una columna de la tabla unida ([Slot.doctor_id]). [contains_eager] reutiliza la unión para poblar [appointment.slot]; [joinedload] carga el cliente: la agenda se construye en una sola consulta SQL;
- líneas 35–39: las próximas citas de un cliente, con sus franjas horarias y el médico asignado a cada franja;
- líneas 43–45: [func.count] genera la función SQL [COUNT], y [session.scalar] (en singular); [session.scalar] devuelve la primera columna de la primera fila: el recuento;
- líneas 48–50: el número de citas de un médico, para determinar si el médico puede eliminarse;
- líneas 61–62: la eliminación de las citas de un cliente (cuando se elimina al cliente).
11.11.6. repositories/user_repository.py
| # =========================================================================
# repositories/user_repository.py
# -------------------------------------------------------------------------
# Capa DAO de la entidad [User]. Crear (o eliminar) un médico o un
# cliente también crea (o elimina) su cuenta - vea business/service.py.
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session
from rdvmedecins.entities import User
class UserRepository:
# None si ningún usuario tiene este login
def read_by_login(self, session: Session, login: str) -> User | None:
return session.scalars(select(User).where(User.login == login)).first()
def add(self, session: Session, user: User) -> User:
session.add(user)
return user
def remove(self, session: Session, id: int):
session.execute(delete(User).where(User.id == id))
|
Lectura de un usuario por su nombre de usuario (para el inicio de sesión), alta y eliminación de una cuenta.
11.12. La capa de negocio
La carpeta [business] contiene las reglas de negocio, y solo esas reglas. No conoce [Flask], ni HTML, ni la solicitud HTTP: podría usarse tal cual en una aplicación de línea de comandos o en una API.
11.12.1. business/dates.py
| # =========================================================================
# business/dates.py
# -------------------------------------------------------------------------
# La fecha de hoy. La usan REGLAS DE NEGOCIO (ninguna reserva
# en el pasado, una sola cita PRÓXIMA por paciente): por lo tanto vive
# en la capa de negocio. La capa web la reutiliza.
# =========================================================================
from datetime import date
# la fecha de hoy, en la zona horaria del servidor
def today() -> date:
return date.today()
|
La fecha actual se utiliza en dos reglas de negocio (no se permiten citas en el pasado, una sola cita próxima por paciente): pertenece a la capa de negocio. Aislarla en una función tiene otra ventaja: una prueba automatizada podría reemplazarla por una fecha fija.
11.12.2. business/exception.py
| # =========================================================================
# business/exception.py
# -------------------------------------------------------------------------
# La excepción que lanza la capa de negocio cuando se VIOLA una REGLA DE NEGOCIO
# (login ya tomado, médico que todavía tiene citas, intervalo
# ya reservado...). No lleva un texto, sino una CLAVE de
# traducción (p. ej.: "ERRORS.LOGIN_TAKEN"): es la capa web la que la
# traducirá al francés o al inglés al mostrar la página
# (vea i18n/fr.json, i18n/en.json).
#
# Una BusinessException no es una anomalía: es una respuesta normal
# ("este login ya está tomado"), que se muestra al usuario. Cualquier otra
# excepción es una verdadera anomalía, que termina en la página de error 500.
# =========================================================================
class BusinessException(Exception):
def __init__(self, key: str, params: dict[str, str] | None = None):
super().__init__(key)
# clave de traducción del mensaje
self.key = key
# posibles parámetros del mensaje ({minutes}...)
self.params = params or {}
|
La excepción de la capa de negocio no lleva texto, como en el ejemplo 28, sino una clave de traducción ([ERRORS.LOGIN_TAKEN]) y los parámetros que correspondan: la capa de negocio no sabe en qué idioma ve la página el usuario. La capa web traducirá la clave. [super().__init__(key)] pasa la clave al constructor de la clase [Exception]: es el valor que se muestra si la excepción se registra en el log.
Una [BusinessException] no es un error: es una respuesta normal («este nombre de usuario ya está en uso»), que se muestra al usuario. Cualquier otra excepción es un error real, que produce una página de error 500.
11.12.3. business/person_data.py
| # =========================================================================
# business/person_data.py
# -------------------------------------------------------------------------
# Los datos ingresados en el formulario "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
# edición: opcional, el login no cambia si falta
login: str | None = None
# creación: opcional, por defecto el login
# edición: opcional, la contraseña no cambia si falta
password: str | None = None
# edición: la versión del registro en el momento en que se
# mostró el formulario (bloqueo optimista, vea entities/base.py)
version: int | None = None
|
Datos de un formulario de «médico» o «cliente», transmitidos por la capa web (ejemplo 28). El nombre de usuario, la contraseña y la versión son opcionales: los comentarios explican qué significa su ausencia durante la creación y la modificación.
11.12.4. business/business.py
| # =========================================================================
# business/business.py
# -------------------------------------------------------------------------
# El CONTRATO de la capa de negocio: lecturas, agenda, citas, gestión
# de los médicos y de los clientes.
#
# Un Protocol describe los métodos que debe tener un objeto, sin decir cómo
# se escriben (el equivalente de una interfaz). BusinessService (la
# capa de negocio) y ApplicationModel (el caché de la capa web) ambos
# lo cumplen. Python no verifica nada en tiempo de ejecución: son
# las herramientas de análisis (la de VS Code, por ejemplo) las que señalan una discrepancia.
#
# T | None: un resultado que puede faltar (un médico que no existe...).
# =========================================================================
from datetime import date
from typing import Protocol
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
class Business(Protocol):
# ------------------------------------------------ lecturas
def get_all_clients(self) -> list[Client]: ...
def get_all_doctors(self) -> list[Doctor]: ...
def get_all_slots(self, doctor_id: int) -> list[Slot]: ...
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]: ...
def get_client_by_id(self, id: int) -> Client | None: ...
def get_doctor_by_id(self, id: int) -> Doctor | None: ...
def get_appointment_by_id(self, id: int) -> Appointment | None: ...
def get_slot_by_id(self, id: int) -> Slot | None: ...
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None: ...
# el cliente (paciente) cuya cuenta de usuario es [user_id]
def get_client_by_user_id(self, user_id: int) -> Client | None: ...
# las citas de un cliente, de hoy o futuras, con intervalo y médico
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]: ...
# ------------------------------------------------ citas (ADMIN, DOCTOR, USER)
# lanza una BusinessException si:
# - el día es pasado ("ERRORS.PAST_DATE");
# - el paciente ya tiene una cita próxima ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
# - el intervalo ya está ocupado ese día ("ERRORS.SLOT_ALREADY_BOOKED").
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment: ...
def delete_appointment(self, appointment: Appointment) -> None: ...
# ------------------------------------------------ médicos (ADMIN)
# crea el médico Y su cuenta de usuario (rol DOCTOR)
def add_doctor(self, data: PersonData) -> Doctor: ...
# edita el médico Y su cuenta de usuario
def edit_doctor(self, id: int, data: PersonData) -> Doctor: ...
# elimina el médico, sus intervalos Y su cuenta - se rechaza si tiene citas
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 el cliente Y su cuenta de usuario (rol USER)
def add_client(self, data: PersonData) -> Client: ...
def edit_client(self, id: int, data: PersonData) -> Client: ...
# elimina el cliente, su cuenta Y todas sus citas (pasadas y futuras)
def delete_client(self, id: int) -> None: ...
|
- línea 23: el contrato de la capa de negocio: una lista de sus métodos, junto con sus parámetros y valores devueltos. Un [Protocol] (módulo estándar [typing]) es el equivalente en [Python] de una interfaz: describe los métodos que debe tener un objeto, sin especificar cómo se implementan. Una clase lo cumple siempre que tenga esos métodos, sin necesidad de declararlo (es lo que se conoce como tipado estructural, o *duck typing*: «si camina como un pato…»). Dos clases lo cumplen: [BusinessService], la capa de negocio, y [ApplicationModel], el caché de la capa web (que se comenta más adelante). [Python] no verifica nada en tiempo de ejecución: son las herramientas de análisis, como la de [Visual Studio Code], las que señalan una discrepancia;
- línea 26: el cuerpo de un método de protocolo se reduce a [...] (el [Ellipsis] objeto de [Python], que no hace nada);
- líneas 55–78: los comentarios documentan la lógica de negocio y los códigos de error de cada método.
11.12.5. business/service.py
La implementación de la capa de negocio. Este es el archivo más importante de la aplicación.
| # =========================================================================
# business/service.py
# -------------------------------------------------------------------------
# Implementación de la capa de negocio.
#
# La gestión de los médicos y de los clientes sigue tres reglas de negocio:
#
# 1. una persona (médico o cliente) y su cuenta de usuario van SIEMPRE
# juntas: se crean, se editan y se eliminan juntas, en
# la misma TRANSACCIÓN - o todo tiene éxito, 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 el mismo 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 intervalos horarios desaparecen con él;
# - un CLIENTE, en cambio, desaparece con TODAS sus citas (pasadas y
# futuras) - ya sea que la eliminación provenga del ADMIN o del propio
# paciente.
#
# Y dos reglas para la reserva de 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 privados _xxx_person), y se parametriza con un
# pequeño "descriptor" que dice con qué tipo de persona estamos tratando.
#
# Las TRANSACCIONES las abre el método _transaction (al final del
# archivo), que también traduce a BusinessException los errores que la base de datos
# informa cuando se le envían las sentencias SQL.
# =========================================================================
import re
from collections.abc import Callable
from dataclasses import dataclass
from datetime import date
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session, sessionmaker
from sqlalchemy.orm.exc import StaleDataError
from rdvmedecins.auth.passwords import hash_password
from rdvmedecins.domain.schedule import DoctorDaySchedule, DoctorDaySlot
from rdvmedecins.entities import Client, Slot, Doctor, Person, Role, Appointment, User
from rdvmedecins.business import dates
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.person_repository import PersonRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
# todo lo que distingue a un médico de un cliente para las reglas de negocio
@dataclass(frozen=True)
class Descriptor:
dao: PersonRepository
factory: type[Person] # Médico o Cliente
role: Role # DOCTOR o USER
not_found_key: str # mensaje si la persona no existe
already_exists_key: str # mensaje 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 > 0), con el mensaje has_appointments_key
count_appointments: Callable[[Session, int], int] | None
has_appointments_key: str | None
# opcional: lo que debe eliminarse ANTES que la persona (las filas que
# la referencian mediante una clave externa)
before_delete: Callable[[Session, int], None] | None
# -----------------------------------------------------------------------
# Errores de la base de datos -> BusinessException
#
# Cuando una restricción UNIQUE rechaza una escritura, SQLAlchemy lanza una
# IntegrityError, cuyo atributo [orig] es el error original, el del
# controlador PyMySQL. Su mensaje cita el NOMBRE de la restricción:
# 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 NOMBRA todas sus restricciones.
# -----------------------------------------------------------------------
CONSTRAINT_MESSAGES = {
"unq_users_login": "ERRORS.LOGIN_TAKEN",
"unq_doctors_first_name_last_name": "ERRORS.DOCTOR_ALREADY_EXISTS",
"unq_clients_first_name_last_name": "ERRORS.PATIENT_ALREADY_EXISTS",
"unq1_appointments": "ERRORS.SLOT_ALREADY_BOOKED",
}
CONSTRAINT = re.compile(r"for key '(?:[^'.]*\.)?([^']+)'")
class BusinessService:
# todas las dependencias las proporciona la fábrica de la aplicación
# (vea rdvmedecins/__init__.py): es inyección de dependencias "a
# mano". sessions: la fábrica de sesiones de SQLAlchemy.
def __init__(self, sessions: sessionmaker, doctors: DoctorRepository,
clients: ClientRepository, slots: SlotRepository, appointments: AppointmentRepository,
users: UserRepository):
self._sessions = sessions
self._doctors = doctors
self._clients = clients
self._slots = slots
self._appointments = appointments
self._users = users
self._doctor = Descriptor(
dao=doctors, factory=Doctor, role=Role.DOCTOR,
not_found_key="ERRORS.DOCTOR_NOT_FOUND",
already_exists_key="ERRORS.DOCTOR_ALREADY_EXISTS",
count_appointments=appointments.count_by_doctor,
has_appointments_key="ERRORS.DOCTOR_HAS_APPOINTMENTS",
# un médico sin citas todavía puede tener intervalos horarios:
# no tienen sentido sin él, se eliminan con él (de lo contrario
# la clave externa slots.doctor_id impediría la eliminación)
before_delete=slots.delete_by_doctor)
self._client = Descriptor(
dao=clients, factory=Client, role=Role.USER,
not_found_key="ERRORS.PATIENT_NOT_FOUND",
already_exists_key="ERRORS.PATIENT_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_key=None,
before_delete=appointments.delete_by_client)
# =======================================================================
# lecturas: una sesión, durante el tiempo de la lectura; los objetos leídos siguen
# siendo utilizables después (expire_on_commit=False, vea rdvmedecins/__init__.py)
# =======================================================================
def _read[R](self, work: Callable[[Session], R]) -> R:
with self._sessions() as session:
return work(session)
def get_all_clients(self) -> list[Client]:
return self._read(self._clients.list)
def get_all_doctors(self) -> list[Doctor]:
return self._read(self._doctors.list)
def get_all_slots(self, doctor_id: int) -> list[Slot]:
return self._read(lambda s: self._slots.list_by_doctor(s, doctor_id))
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
return self._read(lambda s: self._appointments.doctor_day_appointments(s, doctor_id, day))
def get_client_by_id(self, id: int) -> Client | None:
return self._read(lambda s: self._clients.read(s, id))
def get_doctor_by_id(self, id: int) -> Doctor | None:
return self._read(lambda s: self._doctors.read(s, id))
def get_appointment_by_id(self, id: int) -> Appointment | None:
return self._read(lambda s: self._appointments.read(s, id))
def get_slot_by_id(self, id: int) -> Slot | None:
return self._read(lambda s: self._slots.read(s, id))
def get_client_by_user_id(self, user_id: int) -> Client | None:
return self._read(lambda s: self._clients.read_by_user(s, user_id))
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
return self._read(lambda s: self._appointments.client_upcoming_appointments(s, client_id, dates.today()))
# la agenda de un médico en un día dado: sus intervalos, 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
time_slots = self.get_all_slots(doctor_id)
# n.º de intervalo -> cita reservada en este intervalo (una "comprensión" de diccionario)
bookings = {a.slot_id: a for a in self.get_doctor_day_appointments(doctor_id, day)}
doctor_day_slots = [DoctorDaySlot(slot, bookings.get(slot.id))
for slot in time_slots]
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 intervalos al mismo tiempo (dos pestañas,
# doble clic...), la segunda transacción espera el fin de la
# primera - y luego ve la cita que esta acaba de crear;
# 3. una sola cita próxima por paciente;
# 4. por último, la inserción. Si el intervalo 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 BusinessException por _transaction.
# -----------------------------------------------------------------------
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
def work(session: Session) -> Appointment:
today = dates.today()
if day < today:
raise BusinessException("ERRORS.PAST_DATE")
patient_id = self._clients.lock(session, client.id)
if patient_id is None:
raise BusinessException("ERRORS.PATIENT_NOT_FOUND")
if self._appointments.count_client_upcoming(session, patient_id, today) > 0:
raise BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT")
# conocer los ids del intervalo y del paciente basta para escribir
# las claves externas: no es necesario volver a leer estos objetos en la sesión
return self._appointments.add(session, Appointment(day=day, slot_id=slot.id,
client_id=patient_id))
return self._transaction(work)
def delete_appointment(self, appointment: Appointment) -> None:
self._transaction(lambda session: self._appointments.remove(session, appointment.id))
# =======================================================================
# médicos y clientes - los métodos públicos delegan en los métodos
# privados 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 (ADMIN, o el propio paciente
# desde "Manage my account": mismo método, misma regla)
def delete_client(self, id: int) -> None:
self._delete_person(self._client, id)
# -----------------------------------------------------------------------
# creación: la cuenta de usuario Y la persona, en UNA transacción.
# -----------------------------------------------------------------------
def _add_person(self, d: Descriptor, data: PersonData):
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 haya escrito otros
login = (data.login or last_name).lower()
password = data.password or login
def work(session: Session):
self._check_person_unique(session, d, first_name, last_name, None)
self._check_login_free(session, login)
user = User(login=login, password=hash_password(password), name=f"{first_name} {last_name}", role=d.role)
person = d.factory(title=data.title, last_name=last_name, first_name=first_name, user=user)
# la persona hace referencia a su cuenta: SQLAlchemy inserta primero la
# cuenta (para conocer su id), luego la persona
d.dao.add(session, person)
# flush: los INSERT salen de inmediato (y no en el COMMIT); una
# restricción violada lanza por lo tanto su error AQUÍ
session.flush()
return person
return self._transaction(work)
# -----------------------------------------------------------------------
# edición: la persona Y su cuenta (el nombre mostrado "nombre APELLIDO"
# debe seguirla; el login y la contraseña solo cambian si se han
# escrito).
# -----------------------------------------------------------------------
def _edit_person(self, d: Descriptor, id: int, data: PersonData):
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
# bloqueo optimista: si la versión en la base de datos ya no es la del
# formulario, alguien editó este registro mientras tanto - rechazamos
# en lugar de sobrescribir en silencio sus cambios.
# (Si la edición concurrente ocurre DESPUÉS de esta lectura, es
# la cláusula "WHERE version = ..." del UPDATE la que la detecta.)
if data.version is not None and data.version != person.version:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
last_name = data.last_name.strip().upper()
first_name = data.first_name.strip()
self._check_person_unique(session, d, first_name, last_name, id)
# nos limitamos a modificar los objetos: están "rastreados" por la
# sesión, que enviará ella misma los UPDATE necesarios
person.title = data.title
person.last_name = last_name
person.first_name = first_name
user = person.user
user.name = f"{first_name} {last_name}"
if data.login and data.login.lower() != user.login:
login = data.login.lower()
self._check_login_free(session, login)
user.login = login
if data.password:
user.password = hash_password(data.password)
session.flush()
return person
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 hace referencia a la persona (intervalos de un médico, citas
# de un cliente);
# 3. la persona (hace referencia a su cuenta);
# 4. su cuenta.
# -----------------------------------------------------------------------
def _delete_person(self, d: Descriptor, id: int) -> None:
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
if d.count_appointments is not None and d.count_appointments(session, id) > 0:
raise BusinessException(d.has_appointments_key)
if d.before_delete is not None:
d.before_delete(session, id)
d.dao.remove(session, id)
self._users.remove(session, person.user_id)
self._transaction(work)
# rechaza nombres y apellidos ya usados por OTRA persona del mismo tipo
# (current_id: la persona que se edita, que obviamente tiene
# derecho a conservar su propio nombre y apellido; None para una creación)
@staticmethod
def _check_person_unique(session: Session, d: Descriptor, first_name: str, last_name: str,
current_id: int | None):
namesake = d.dao.namesake(session, first_name, last_name)
if namesake is not None and namesake.id != current_id:
raise BusinessException(d.already_exists_key)
def _check_login_free(self, session: Session, login: str):
if self._users.read_by_login(session, login) is not None:
raise BusinessException("ERRORS.LOGIN_TAKEN")
# -----------------------------------------------------------------------
# ejecuta [work] en una transacción:
# sessions.begin() -> una sesión y su transacción (START TRANSACTION);
# al salir del bloque with: COMMIT si todo salió bien; si sale de él una
# excepción (BusinessException incluida), ROLLBACK: no se escribe nada.
#
# Las verificaciones de "login libre" y de "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) en el mismo instante: en este
# raro caso, es una restricción de unicidad SQL la que rechaza la segunda
# escritura. Los errores de la base de datos se interceptan por lo tanto ALREDEDOR de la
# transacción, para traducirlos a la misma BusinessException:
# - StaleDataError: el UPDATE "WHERE id = ... AND version = ..." no
# modificó ninguna fila (bloqueo optimista);
# - IntegrityError: una restricción de la base de datos rechazó la escritura.
# Cualquier otro error es una verdadera anomalía: se deja pasar.
# -----------------------------------------------------------------------
def _transaction[R](self, work: Callable[[Session], R]) -> R:
try:
with self._sessions.begin() as session:
return work(session)
except StaleDataError:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
except IntegrityError as e:
match = CONSTRAINT.search(str(e.orig))
if match and match.group(1) in CONSTRAINT_MESSAGES:
raise BusinessException(CONSTRAINT_MESSAGES[match.group(1)])
raise
|
11.12.5.1. Los descriptores
Los médicos y los clientes siguen exactamente las mismas reglas de negocio, con algunas diferencias menores: un DAO distinto, un rol distinto para su cuenta, mensajes de error distintos y una regla de eliminación distinta. En lugar de escribir cada método dos veces, el código común se escribe una sola vez (los métodos [_add_person], [_edit_person], [_delete_person]) y se configura mediante un descriptor que especifica qué tipo de persona se está tratando:
- líneas 59–71: el descriptor es una [dataclass] inmutable. Tres de sus campos son funciones: [Callable[[Session, int], int]] es el tipo de una función que recibe una sesión y un entero, y devuelve un entero. [count_appointments] cuenta las citas de una persona (para impedir la eliminación de un médico que tenga alguna); [before_delete] elimina las referencias a la persona (las franjas horarias de un médico, las citas de un cliente);
- líneas 109–118: el descriptor de los médicos. [appointments.count_by_doctor] es un método asociado al objeto [appointments] (Ejemplo 22): una función que recibirá la sesión y el ID;
- líneas 120–128: el de los clientes: sin denegación de eliminación ([count_appointments=None]), pero con la eliminación previa de todas sus citas.
11.12.5.2. Operaciones de lectura y el calendario
- líneas 135–137: las lecturas se gestionan mediante un pequeño método genérico: [R] es el tipo del resultado, que es el mismo que el de la función [work]. La sesión se abre con [self._sessions()] (sin [begin]) mientras la función se ejecuta, y luego se cierra con el bloque [with]. [SQLAlchemy] inicia de todos modos una transacción en la primera solicitud ([BEGIN (implicit)] en la consola); como no se escribió nada, al cerrar la sesión se cancela ([ROLLBACK]): son las líneas que la consola muestra cuando se inicia la aplicación;
- líneas 139–167: cada lectura indica a [_read] que llame al método del DAO. Cuando el método del DAO tiene parámetros además de la sesión, una función anónima ([lambda s: ...]) los proporciona;
- Líneas 171–180: la agenda de un médico para un solo día. Las citas del día se almacenan en un diccionario ([{key: value for ...}]) que asocia el número de cada franja horaria con su cita correspondiente; cada franja se asocia entonces con su cita, o con [None] ([bookings.get(slot.id)]). Son tres lecturas, en tres sesiones: cualquier inconsistencia entre ellas (una cita programada entre dos lecturas) no tendría consecuencias, ya que la agenda es solo una visualización.
11.12.5.3. Programación de una cita
- Líneas 198–213: el método define una función interna, [work], que contiene las operaciones que se realizarán en la transacción, y se la pasa al método [_transaction] (véase más adelante). Las reglas, en orden: - No se permiten citas en el pasado ([day < today]: las fechas en [Python] se comparan con los operadores habituales); - el registro del paciente se bloquea ([lock], véase [ClientRepository]): si el mismo paciente reserva dos franjas horarias al mismo tiempo (dos pestañas, un doble clic), la segunda transacción espera a que la primera termine y luego ve la cita que esta creó; - solo una cita próxima por paciente; - por último, la inserción. La cita se crea usando el ID de la franja y el ID del paciente: basta con conocer los valores de las claves externas; no es necesario volver a leer los objetos. Los parámetros con nombre del constructor ([Appointment(day=..., slot_id=...)]) los proporciona [SQLAlchemy] a toda entidad que no tenga su propio constructor.
- Queda un escenario: que la franja horaria haya sido tomada por otro paciente entre el momento en que se muestra el calendario y el momento en que se hace la reserva. En este caso, la restricción de la base de datos [unq1_appointments] impide la inserción durante la operación [COMMIT]. El método [_transaction] traduce este error a [BusinessException];
- líneas 215–216: cancelación de una cita. Las comprobaciones de permisos (un paciente solo puede cancelar sus propias citas) las realiza la capa web, que conoce al usuario.
11.12.5.4. Gestión de médicos y clientes
- líneas 223–241: los métodos públicos delegan en métodos comunes, usando el descriptor correcto;
- líneas 246–267: creación. El apellido se escribe con mayúscula inicial y se eliminan los espacios del nombre; el nombre de usuario predeterminado es el apellido en minúsculas, y la contraseña es el nombre de usuario (la regla de las cuentas de demostración en el script SQL). En la transacción: validaciones (sin homónimos, nombre de usuario libre), seguidas de la creación de la cuenta y de la persona. La persona recibe su cuenta a través de su relación ([user=user]): [SQLAlchemy] sabe que primero debe insertar la cuenta para obtener su ID y luego la persona. [session.flush()] envía [INSERT] de inmediato: una restricción violada provoca un error en la transacción, y la persona devuelta ya tiene su ID;
- Líneas 274–309: la actualización. La versión del formulario se compara con la versión de la base de datos (bloqueo optimista, ejemplo 28); luego simplemente actualizamos los objetos recuperados: la sesión los rastrea y será ella misma quien envíe las instrucciones [UPDATE] necesarias. El nombre de cuenta mostrado sigue al nombre y al apellido; el nombre de usuario y la contraseña cambian solo si se han introducido;
- líneas 320–332: eliminación, en el orden que dictan las claves externas: posible rechazo (un médico que tiene citas), eliminación de las referencias a la persona, de la persona misma y, por último, de su cuenta. En el orden inverso, la base de datos rechazaría cada [DELETE]. Todo esto ocurre en una sola transacción: si falla cualquiera de los pasos, no se ejecuta ninguno;
- líneas 337–342: se rechaza un homónimo, salvo que sea la persona que se está editando, que tiene derecho a conservar su propio nombre y apellido;
- líneas 344–346: un nombre de usuario solo puede pertenecer a una cuenta.
11.12.5.5. Transacciones y restricciones de unicidad
- líneas 365–375: todas las actualizaciones pasan por este método. [sessions.begin()] abre una sesión y su transacción; al salir del bloque [with], la transacción se confirma ([COMMIT]) si todo salió bien, o se revierte ([ROLLBACK]) si se produce una excepción, incluida [BusinessException];
- Líneas 369–370: el bloqueo optimista detectó una modificación concurrente (ejemplo 28);
- líneas 371–374: una restricción de la base de datos rechazó la escritura. Las comprobaciones realizadas antes de la escritura (nombre de usuario único, sin homónimos) proporcionan un mensaje claro en la gran mayoría de los casos; sin embargo, dos administradores podrían registrar el mismo nombre de usuario al mismo tiempo, o dos pacientes podrían reservar la misma franja horaria. La restricción de unicidad rechaza entonces la segunda escritura, y [SQLAlchemy] lanza una [IntegrityError]. Su mensaje original ([e.orig], el error de [PyMySQL]) cita el nombre de la restricción (aquí con [MariaDB], para la segunda franja horaria reservada dos veces el mismo día):
| (1062, "Duplicate entry '2026-09-26-2' for key 'unq1_appointments'")
|
- La expresión regular [CONSTRAINT] (línea 91) extrae este nombre. [MySQL] 8 agrega el prefijo con el nombre de la tabla (['appointments.unq1_appointments']), [MariaDB] no lo hace: la parte [(?:[^'.]*\.)?] acepta este prefijo opcional ([(?:...)] es un grupo sin captura, [?] lo hace opcional). El diccionario [CONSTRAINT_MESSAGES] (líneas 84–88) asocia cada restricción conocida con la clave de su mensaje. Por eso el script SQL nombra todas sus restricciones;
- línea 375: cualquier otro error es una verdadera anomalía: [raise], sin parámetros, vuelve a lanzar la excepción actual, lo que resultará en una página de error 500.
Observe la estructura de todos los métodos de escritura: una función interna [work], que contiene las operaciones, se pasa a [_transaction], que la ejecuta dentro de una transacción y traduce los errores. Esto equivale a la anotación ***[@Transactional]*** de *[Spring]*, escrita en unas pocas líneas: una función es un objeto como cualquier otro, que se puede pasar como parámetro.
11.13. Autenticación
La carpeta [auth] incorpora los mecanismos de los ejemplos 25 a 27, con tres diferencias: la regla de acceso se invierte (todo está prohibido excepto lo que se declara público), los usuarios se recuperan de la base de datos y la creación de una cuenta de cliente está protegida por un “pase”.
11.13.1. auth/passwords.py
| # =========================================================================
# auth/passwords.py
# -------------------------------------------------------------------------
# Hash de contraseñas: bcrypt, 10 rondas, versión $2b$ - como los
# hashes del script SQL.
#
# bcrypt solo toma en cuenta los primeros 72 BYTES de una contraseña (un
# carácter acentuado ocupa dos de ellos, en UTF-8); la biblioteca bcrypt
# incluso rechaza una contraseña más larga. Por eso solo le pasamos estos
# 72 bytes, tanto al crear como al verificar.
# =========================================================================
import bcrypt
def _bytes(password: str) -> bytes:
return password.encode("utf-8")[:72]
# el hash que se almacena en la base de datos: "$2b$10$" + la sal + el resultado
def hash_password(password: str) -> str:
return bcrypt.hashpw(_bytes(password), bcrypt.gensalt(rounds=10)).decode("ascii")
# checkpw calcula el hash de la contraseña escrita con la "sal" contenida en el
# hash almacenado, y luego compara los dos resultados
def verify(password: str, hashed: str) -> bool:
return bcrypt.checkpw(_bytes(password), hashed.encode("ascii"))
|
- Líneas 15–16: [bcrypt] considera solo los primeros 72 bytes de una contraseña, y la versión 5 de la biblioteca rechaza las contraseñas más largas (Ejemplo 25). Por lo tanto, solo se le pasan esos 72 bytes, tanto en la creación como en la verificación: una contraseña más larga se acepta, pero los caracteres posteriores al byte 72 se ignoran. Un carácter acentuado ocupa dos bytes en [UTF-8];
- líneas 20–21: el hash se almacena en forma de texto: [decode("ascii")] convierte los bytes devueltos por [bcrypt] en una cadena;
- líneas 26–27: verificación (ejemplo 25). Este módulo lo utilizan la autenticación y la capa de negocio (creación de cuentas, cambio de contraseña).
11.13.2. auth/connected_user.py
| # =========================================================================
# auth/connected_user.py
# -------------------------------------------------------------------------
# Lo que contiene el token JWT, y cómo volver a leerlo.
#
# Los claims de nuestros tokens (vea AuthService.set_token):
# 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
# =========================================================================
from dataclasses import dataclass
from rdvmedecins.entities import Role
# el usuario conectado, en forma tipada
@dataclass(frozen=True)
class ConnectedUser:
user_id: int
login: str
name: str
role: Role
# el usuario descrito por los claims de un token ya verificado; None si
# falta un claim o no tiene la forma esperada
@staticmethod
def of(claims: dict) -> "ConnectedUser | None":
try:
return ConnectedUser(int(claims["sub"]), claims["login"], claims["name"],
Role(claims["role"]))
except (KeyError, ValueError, TypeError):
return None
@property
def is_admin(self) -> bool:
return self.role == Role.ADMIN
@property
def is_patient(self) -> bool:
return self.role == Role.USER
|
- líneas 20–24: el usuario conectado, en forma tipada: el ejemplo 25 almacenaba el diccionario de aserciones del token en [g.user]; la aplicación almacena este objeto, cuyos atributos conoce el editor ([g.user.role]), y cuyo rol es un valor de la enumeración [Role];
- Líneas 29–34: construcción a partir de las aserciones de un token ya verificado. El tipo del resultado se escribe entre comillas (["ConnectedUser | None"]): cuando [Python] lee la definición del método, la clase [ConnectedUser] aún no está completamente definida, y su nombre no se puede usar directamente. Un token al que le falta una aserción ([KeyError]) o con un valor inesperado ([ValueError]: un rol desconocido, un [sub] que no es un número) da como resultado [None]: el usuario no está autenticado;
- líneas 36–42: dos propiedades: el decorador [@property] transforma un método en una propiedad calculada, que se usa sin paréntesis: [g.user.is_admin].
El token contiene el ID de la cuenta ([sub], en forma de texto, como exige el estándar JWT), el nombre de usuario, el nombre para mostrar y el rol: todo lo que la barra de navegación y las reglas de acceso necesitan, sin tener que consultar la base de datos en cada solicitud.
11.13.3. auth/auth_service.py
| # =========================================================================
# auth/auth_service.py
# -------------------------------------------------------------------------
# La lógica de autenticación:
# - validate_user() : 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;
# - clear_token() : elimina esta cookie;
# - current_user() : el usuario descrito por la cookie de la solicitud.
#
# ¿Por dónde viaja el token JWT?
# Con un cliente JavaScript, era el código del cliente el que conservaba el token
# y lo agregaba él mismo a cada solicitud (encabezado "Authorization: Bearer
# ..."). Un navegador que muestra páginas HTML ordinarias no puede
# hacerlo: para que presente el token por sí solo en cada solicitud, debe
# almacenarse en una COOKIE. 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, por lo tanto, 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, ver rdvmedecins/__init__.py);
# - Secure: en producción (HTTPS), la cookie nunca viaja en claro;
# - Max-Age: la cookie desaparece al mismo tiempo que expira el token.
# =========================================================================
from datetime import datetime, timedelta, timezone
import jwt
from flask import Request, Response
from rdvmedecins.auth.passwords import verify
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import User
from rdvmedecins.repositories.user_repository import UserRepository
# el nombre de la cookie que transporta el token
JWT_COOKIE = "rdvmedecins_jwt"
class AuthService:
def __init__(self, sessions, users: UserRepository, secret: str, duration_seconds: int,
cookie_secure: bool):
# HMAC-SHA256 requiere una clave de al menos 256 bits: lo indicamos
# claramente al arrancar en lugar de hacerlo en el primer inicio de sesión
if len(secret.encode("utf-8")) < 32:
raise RuntimeError("JWT_SECRET must be at least 32 characters long (see config.py).")
self._sessions = sessions
self._users = users
self._secret = secret
self._duration = timedelta(seconds=duration_seconds)
self._cookie_secure = cookie_secure
# None si el login no existe o si la contraseña es incorrecta
def validate_user(self, login: str, password: str) -> User | None:
with self._sessions() as session:
user = self._users.read_by_login(session, login)
if user is None or not verify(password, user.password):
return None
return user
# -----------------------------------------------------------------------
# construye el token JWT de [user] y lo coloca en una cookie.
# 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(self, response: Response, user: User):
now = datetime.now(timezone.utc)
claims = {
"sub": str(user.id),
"login": user.login,
"name": user.name,
"role": user.role.value,
"iat": now,
"exp": now + self._duration,
}
token = jwt.encode(claims, self._secret, algorithm="HS256")
response.set_cookie(JWT_COOKIE, token, max_age=self._duration, path="/", httponly=True,
samesite="Lax", secure=self._cookie_secure)
# elimina la cookie: se establece de nuevo, vacía, con una duración cero
@staticmethod
def clear_token(response: Response):
response.delete_cookie(JWT_COOKIE, path="/")
# el token presente en la solicitud, sea válido o no
@staticmethod
def token_of(request: Request) -> str | None:
return request.cookies.get(JWT_COOKIE)
# -----------------------------------------------------------------------
# el usuario descrito por la cookie de la solicitud; None si no hay
# token, o si el token está vencido, falsificado o malformado.
# jwt.decode verifica la firma Y la fecha de expiración (claim exp).
# -----------------------------------------------------------------------
def current_user(self, request: Request) -> ConnectedUser | None:
token = self.token_of(request)
if not token:
return None
try:
claims = jwt.decode(token, self._secret, algorithms=["HS256"])
except jwt.InvalidTokenError:
return None
return ConnectedUser.of(claims)
|
- líneas 46–47: una clave de firma demasiado corta se detecta al iniciar la aplicación, en lugar de en el primer inicio de sesión: [create_app] crea el servicio, y la excepción termina la aplicación con este mensaje;
- Líneas 55–60: verificación de un nombre de usuario y una contraseña. El servicio lee al usuario mediante el DAO, en una sesión que permanece abierta solo mientras dura esta lectura; la verificación de la contraseña ([bcrypt], que es lenta) se realiza después de cerrar la sesión, para evitar mantener una conexión innecesaria con la base de datos;
- Líneas 68–80: el token (ejemplo 25) y su cookie, [rdvmedecins_jwt]. [user.role.value]: el valor de la enumeración, la cadena ["USER"]. A la cookie se le asigna el atributo [Secure] en producción ([COOKIE_SECURE]);
- líneas 84–85: eliminación de la cookie. Es un método estático: no requiere un objeto y se invoca sobre la clase ([AuthService.clear_token(response)]);
- líneas 97–105: el usuario identificado por la cookie de la solicitud, o [None].
11.13.4. auth/security.py
El núcleo de la seguridad: la autenticación de cada solicitud y la regla de acceso.
| # =========================================================================
# auth/security.py
# -------------------------------------------------------------------------
# Quién puede acceder a qué, y cómo se reconoce al usuario en cada
# solicitud (ver ejemplos 25 y 26).
#
# Para cada solicitud, la función authenticate (un before_request de
# la aplicación):
# 1. lee el token de la cookie, verifica su firma y su fecha de expiración,
# y almacena al usuario en g.user (None si no hay);
# 2. aplica la regla de acceso: TODAS las acciones requieren un usuario
# autenticado, excepto las marcadas con @public (inicio de sesión,
# creación de cuenta, elección de idioma) y los archivos estáticos.
# Es la regla "todo está prohibido excepto lo permitido": una acción
# agregada después, que se hubiera olvidado de proteger, queda protegida por defecto.
# Solo entonces Flask llama a la acción, cuyo decorador
# @roles_required(...) verifica el rol.
#
# Dos casos de falla, dos respuestas adecuadas para una aplicación HTML:
# - ningún usuario autenticado (sin token, token vencido o falsificado)
# -> redirección a la página de inicio de sesión;
# - rol insuficiente -> respuesta 403, que web/errors.py convierte en una página.
# =========================================================================
from functools import wraps
from flask import abort, current_app, g, redirect, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.entities import Role
from rdvmedecins.web.flash import flash_error
# el token es válido, pero la cuenta que designa ya no existe: fue
# eliminada desde el inicio de sesión (por el propio paciente en otra
# pestaña, o por el ADMIN). Este caso se trata como una sesión vencida:
# web/errors.py borra la cookie y devuelve a la página de inicio de sesión.
class InvalidSession(Exception):
pass
# un decorador que MARCA una acción como pública (ver ejemplo 24)
def public(action):
action.public = True
return action
def register(app, auth_service: AuthService):
@app.before_request
def authenticate():
g.user = auth_service.current_user(request)
# ninguna ruta coincide (seguirá la página 404), o un archivo estático
if request.endpoint is None or request.endpoint == "static":
return None
action = current_app.view_functions[request.endpoint]
if getattr(action, "public", False) or g.user is not None:
return None
# una respuesta devuelta por un before_request detiene el procesamiento:
# la acción no se llama
return to_login()
# -----------------------------------------------------------------------
# ningún usuario autenticado -> página de inicio de sesión. Si había una cookie
# presente, su token ya no es válido: la sesión ha vencido.
# Entonces se borra la cookie y se advierte al usuario con un mensaje flash.
# -----------------------------------------------------------------------
def to_login():
response = redirect(url_for("auth.show_login"))
if AuthService.token_of(request):
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
# -----------------------------------------------------------------------
# el rol del usuario debe ser uno de [roles]; de lo contrario, respuesta 403.
# require_roles se llama desde un before_request de blueprint (todas las
# acciones del blueprint, ver controllers/persons.py); roles_required es
# el decorador de una acción (ver ejemplo 26).
# -----------------------------------------------------------------------
def require_roles(*roles: Role):
if g.user is None:
raise InvalidSession()
if g.user.role not in roles:
abort(403)
def roles_required(*roles: Role):
def decorator(action):
@wraps(action)
def protected_action(*args, **kwargs):
require_roles(*roles)
return action(*args, **kwargs)
return protected_action
return decorator
|
- líneas 37–38: una excepción para un caso especial: el token es válido, pero la cuenta a la que se refiere ya no existe (el paciente la eliminó en otra pestaña, o la eliminó el administrador). Las acciones que requieren la cuenta lanzan esta excepción; el manejador de errores la trata como una sesión expirada (véase [web/errors.py]);
- líneas 42–44: el decorador que marca una acción como pública (ejemplo 24);
- líneas 50–60: la función [before_request] de la aplicación. Primero, se autentica al usuario en todas las solicitudes, incluidas las públicas: la página de inicio de sesión debe saber si el usuario ya ha iniciado sesión. Luego, la regla de acceso: se permite una solicitud que no coincide con ninguna ruta ([request.endpoint is None]: seguirá la página 404) o que solicita un archivo estático; se permite una acción marcada como pública; se permite a un usuario autenticado. En caso contrario, la función devuelve una respuesta (redirección a la página de inicio de sesión), que detiene el procesamiento: la acción no se invoca.
Esta es la regla de “todo está prohibido a menos que se permita explícitamente”: una acción agregada más adelante, incluso si olvidó protegerla, queda protegida automáticamente. Olvidar incluir [@public] en una acción pública se nota de inmediato (la página redirige a la de inicio de sesión); no proteger una acción privada no se nota de inmediato: la regla predeterminada debe ser la más segura. Esta es también la regla de la versión [Spring MVC] ([anyRequest().authenticated()]);
- líneas 68–73: la redirección a la página de inicio de sesión. Si la solicitud contenía una cookie de token, significa que ese token ya no es válido (expiró o fue manipulado): se elimina la cookie y un mensaje emergente explica al usuario que su sesión ha expirado (la captura de pantalla del mensaje de fin de sesión, mostrada anteriormente);
- líneas 82–86: autorización. El parámetro [*roles] acepta cualquier cantidad de roles en una tupla: [require_roles(Role.ADMIN, Role.DOCTOR)]. Un rol que no figura en la lista da como resultado un error 403. La comprobación [g.user is None] nunca debería ser verdadera (la regla de acceso ya ha filtrado a los visitantes anónimos), a menos que [require_roles] se invocara desde una acción pública: esto proporciona una capa adicional de seguridad;
- líneas 89–98: el decorador con parámetros del ejemplo 26, que invoca a [require_roles]. [require_roles] también se puede usar por sí solo, dentro del [before_request] de un blueprint, para proteger todas sus acciones a la vez (véase [controllers/persons.py]).
11.13.5. auth/captcha_drawing.py
El renderizado de la imagen es el mismo que en el ejemplo 27, reproducido exactamente tal cual. Su comentario de encabezado destaca un punto importante: cada carácter se dibuja mediante líneas (elementos [<path>]), y nunca se escribe como texto (un elemento [<text>]); de lo contrario, a un bot le bastaría con leer el código fuente de la imagen.
11.13.6. auth/captcha.py
| # =========================================================================
# auth/captcha.py
# -------------------------------------------------------------------------
# Un CAPTCHA ("prueba para distinguir a un humano de un robot") hecho por el
# propio servidor, sin ningún servicio externo: unos pocos caracteres deformados,
# confundidos con líneas, en una imagen SVG (ver captcha_drawing.py). Un
# humano los lee fácilmente; un robot que se limita a enviar
# formularios en bucle no puede hacerlo.
#
# Cómo funciona:
# 1. generate() dibuja un texto aleatorio, crea una imagen con él y almacena la
# respuesta correcta EN LA MEMORIA 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, typed) compara lo ingresado con la respuesta esperada y luego
# OLVIDA este CAPTCHA: cada imagen se usa una sola vez, un robot no puede
# reproducir una respuesta ya encontrada.
#
# Un único objeto CaptchaService para todo el servidor, usado por varias
# solicitudes EN PARALELO (el servidor las procesa en varios hilos): un
# candado (Lock) garantiza que un solo hilo a la vez lee o modifica el
# diccionario de CAPTCHA pendientes.
#
# Límite aceptado: la memoria de un único proceso. Con varios procesos
# o varios servidores, haría falta un almacenamiento compartido.
# =========================================================================
import secrets
from dataclasses import dataclass
from datetime import datetime, timedelta
from threading import Lock
from rdvmedecins.auth import captcha_drawing
# duración de validez de una imagen: se tienen 10 minutos para completar el formulario
LIFETIME = timedelta(minutes=10)
# salvaguarda de memoria: más allá de este límite, se olvidan todos los CAPTCHA pendientes
MAX_CAPTCHAS = 10_000
# un CAPTCHA: id, para colocar en el campo oculto "captchaId" del formulario;
# svg, la imagen, para insertar tal cual en la página
@dataclass(frozen=True)
class Captcha:
id: str
svg: str
class CaptchaService:
def __init__(self):
# id -> (respuesta esperada, fecha de expiración)
self._pending: dict[str, tuple[str, datetime]] = {}
self._lock = Lock()
def generate(self) -> Captcha:
text = captcha_drawing.random_text(5) # 5 caracteres
id = secrets.token_urlsafe(16) # un identificador aleatorio, imposible de adivinar
with self._lock:
self._purge()
self._pending[id] = (text, datetime.now() + LIFETIME)
return Captcha(id, captcha_drawing.svg(text))
# true si [typed] es la respuesta correcta al CAPTCHA [id] (sin distinguir
# mayúsculas de minúsculas). El CAPTCHA se consume en todos los casos: si dos
# solicitudes presentan el mismo CAPTCHA en el mismo instante, solo una
# lo elimina (pop, bajo el candado) - la otra falla.
def verify(self, id: str | None, typed: str | None) -> bool:
with self._lock:
expected = self._pending.pop(id, None) if id else None
if expected is None or typed is None:
return False
text, expires = expected
return expires > datetime.now() and text.lower() == typed.strip().lower()
# (llamado bajo el candado)
def _purge(self):
now = datetime.now()
for id in [id for id, (_, expires) in self._pending.items() if expires <= now]:
del self._pending[id]
if len(self._pending) >= MAX_CAPTCHAS:
self._pending.clear()
|
El servicio del ejemplo 27, con una adición: el método [_purge] (líneas 77–82), que se invoca cada vez que se crea un CAPTCHA, descarta los CAPTCHA expirados. Sin él, los CAPTCHA que se muestran pero nunca se utilizan (por ejemplo, cuando se abre una página de inicio de sesión y luego se abandona) se acumularían en la memoria. [MAX_CAPTCHAS] actúa como salvaguarda: un bot que solicite millones de páginas de inicio de sesión no podría agotar la memoria del servidor. El número [10_000] se escribe con un guion bajo, que separa los miles para facilitar la lectura ([Python] lo ignora). La lista de identificadores que se van a eliminar se construye antes del bucle de eliminación: no se pueden eliminar claves de un diccionario mientras se itera sobre él.
11.13.7. auth/limiter.py
| # =========================================================================
# auth/limiter.py
# -------------------------------------------------------------------------
# Segunda línea de defensa contra los robots (la primera es el CAPTCHA): CONTAMOS
# los intentos y, superado un umbral, BLOQUEAMOS por un tiempo.
#
# - inicio de sesión: 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 LOGIN_BLOCK_MINUTES minutos. La misma dirección IP también se
# bloquea si acumula 5 veces más fallos, sumando todos los logins (un
# robot que prueba miles de logins distintos);
# - creación de cuenta: como máximo REGISTRATION_MAX_PER_HOUR cuentas creadas
# por hora desde la misma dirección IP.
#
# Atención en un salón de clases: todas las computadoras suelen salir a Internet
# por la MISMA dirección IP. Por eso el bloqueo de inicio de sesión 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 eso los umbrales pueden configurarse
# en config.py.
#
# Un único objeto para todo el servidor, llamado por solicitudes en paralelo:
# todos los métodos públicos toman el candado - un solo hilo a la
# vez lee Y modifica los contadores.
# =========================================================================
import math
from datetime import datetime, timedelta
from threading import Lock
ONE_HOUR = timedelta(hours=1)
class Counter:
def __init__(self, start: datetime):
self.number = 0 # intentos contados en la ventana actual
self.start = start # inicio de la ventana de conteo
self.blocked_until = datetime.min # datetime.min si no está bloqueado
class AttemptLimiter:
def __init__(self, login_max_failures: int, login_block_minutes: int,
registration_max_per_hour: int):
self._counters: dict[str, Counter] = {}
self._lock = Lock()
self._max_login_failures = login_max_failures
self._login_block_duration = timedelta(minutes=login_block_minutes)
self._max_registrations = registration_max_per_hour
# ---------------------------------------------------------------- inicio de sesión
# número de minutos de bloqueo restantes (0 = el intento está permitido)
def login_block_minutes(self, ip: str, login: str) -> int:
with self._lock:
return max(self._remaining_minutes(self._login_key(ip, login)),
self._remaining_minutes(self._ip_key(ip)))
def login_failure(self, ip: str, login: str):
with self._lock:
self._count(self._login_key(ip, login), self._max_login_failures,
self._login_block_duration, self._login_block_duration)
self._count(self._ip_key(ip), self._max_login_failures * 5,
self._login_block_duration, self._login_block_duration)
# un inicio de sesión exitoso reinicia el contador de ESTE login
def login_success(self, ip: str, login: str):
with self._lock:
self._counters.pop(self._login_key(ip, login), None)
# ---------------------------------------------------------------- creación de cuenta
def registration_block_minutes(self, ip: str) -> int:
with self._lock:
return self._remaining_minutes(f"registration|{ip}")
# ventana de una hora; una vez alcanzada la cuota, bloqueado hasta el final de la hora
def registration_success(self, ip: str):
with self._lock:
self._count(f"registration|{ip}", self._max_registrations, ONE_HOUR, ONE_HOUR)
# ---------------------------------------------------------------- mecánica común
# (los métodos privados siempre se llaman bajo el candado)
def _remaining_minutes(self, key: str) -> int:
counter = self._counters.get(key)
if counter is None:
return 0
remaining = (counter.blocked_until - datetime.now()).total_seconds()
# redondeado HACIA ARRIBA al minuto: 30 s de bloqueo restante -> "1 minute"
return max(0, math.ceil(remaining / 60))
# cuenta un intento; si se alcanza el umbral dentro de la ventana, bloquea
def _count(self, key: str, maximum: int, window: timedelta, block: timedelta):
now = datetime.now()
self._purge(now)
counter = self._counters.get(key)
if counter is None or now - counter.start > window:
counter = Counter(now)
self._counters[key] = counter
counter.number += 1
if counter.number >= maximum:
counter.blocked_until = now + block
counter.number = 0 # después del bloqueo, se empieza de nuevo desde cero
counter.start = counter.blocked_until
# se olvidan los contadores que ya no son útiles (ni bloqueados, ni recientes)
def _purge(self, now: datetime):
if len(self._counters) < 1000:
return
for key in [key for key, c in self._counters.items()
if c.blocked_until < now and now - c.start > ONE_HOUR]:
del self._counters[key]
@staticmethod
def _login_key(ip: str, login: str) -> str:
return f"login|{ip}|{login.strip().lower()}"
@staticmethod
def _ip_key(ip: str) -> str:
return f"ip|{ip}"
|
Una versión más completa del limitador del ejemplo 27:
- El bloqueo de conexión se dirige primero al par (dirección IP, nombre de usuario): en un aula, todas las computadoras suelen acceder a Internet a través de la misma dirección IP, y un estudiante que introduce mal la contraseña no debería bloquear a sus compañeros. Sin embargo, también se bloquea una dirección si acumula cinco veces más intentos fallidos, entre todos los nombres de usuario: es el caso de un bot que prueba miles de nombres de usuario distintos (líneas 57–61);
- la creación de cuentas está limitada a cierto número de cuentas por hora y por dirección IP (líneas 71–78);
- los contadores se almacenan en un único diccionario, bajo claves con un prefijo según su uso ([login|...], [ip|...], [registration|...]);
- líneas 92–103: un contador registra los intentos dentro de una ventana de tiempo; un intento que se produce después de que termina la ventana inicia una nueva. Cuando se alcanza el umbral, la clave se bloquea y el contador se restablece a cero;
- líneas 106–111: cuando el contador supera las 1000 entradas, se descartan las que ya no están en uso (ni bloqueadas ni recientes).
Al igual que el CAPTCHA, el limitador almacena sus datos en la memoria del proceso: esto es aceptable para una aplicación atendida por un solo proceso (el servidor de desarrollo, [Waitress]), pero no para varios procesos o varios servidores, que no compartirían sus contadores (entonces sería necesario un almacenamiento compartido, como [Redis]).
11.13.8. auth/registration_pass.py
| # =========================================================================
# auth/registration_pass.py
# -------------------------------------------------------------------------
# El "pase" de creación de cuenta.
#
# Para abrir la página "Create a patient account", primero hay que haber
# escrito el CAPTCHA de la página de autenticación (ver
# controllers/registration.py, POST /register/access). Entonces el servidor emite
# un pase:
# - un identificador aleatorio, almacenado en una cookie HttpOnly;
# - válido 15 minutos (el tiempo para completar el formulario, incluso al intentarlo
# varias veces tras errores de entrada);
# - se consume 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 devuelven a la
# página de autenticación: escribir directamente la URL /register no permite
# eludir el CAPTCHA.
#
# Al igual que los CAPTCHA, los pases viven en la memoria del proceso.
# =========================================================================
import secrets
from datetime import datetime, timedelta
from threading import Lock
from flask import Response
COOKIE = "rdvmedecins_registration"
LIFETIME = timedelta(minutes=15)
MAX_PASSES = 10_000
class RegistrationPass:
def __init__(self):
# id -> fecha de expiración
self._passes: dict[str, datetime] = {}
self._lock = Lock()
# emite un nuevo pase; devuelve su identificador
def issue(self) -> str:
id = secrets.token_urlsafe(16)
with self._lock:
self._purge()
self._passes[id] = datetime.now() + LIFETIME
return id
# true si [id] es un pase existente y no vencido
def is_valid(self, id: str | None) -> bool:
with self._lock:
expires = self._passes.get(id) if id else None
return expires is not None and expires > datetime.now()
# el pase ha sido usado: se olvida
def consume(self, id: str | None):
with self._lock:
self._passes.pop(id, None)
# (llamado bajo el candado)
def _purge(self):
now = datetime.now()
for id in [id for id, expires in self._passes.items() if expires <= now]:
del self._passes[id]
if len(self._passes) >= MAX_PASSES:
self._passes.clear()
# el navegador envía la cookie solo a las direcciones /register...
def set_cookie(response: Response, id: str, secure: bool):
response.set_cookie(COOKIE, id, max_age=LIFETIME, path="/register", httponly=True,
samesite="Lax", secure=secure)
# ... y se borra estableciéndola de nuevo vacía, con una duración cero
def clear_cookie(response: Response):
response.delete_cookie(COOKIE, path="/register")
|
La creación de una cuenta de paciente es una página pública: un bot podría crear cuentas de forma masiva. Por eso está protegida por el CAPTCHA de la página de inicio de sesión: el botón “Crear una cuenta de paciente” envía este CAPTCHA al servidor, que, si es correcto, emite un token:
- líneas 42–47: un identificador aleatorio, válido durante 15 minutos, almacenado en memoria como los CAPTCHA;
- líneas 50–53: la página de registro verifica el pase en cada solicitud: GET se trata igual que POST;
- líneas 56–58: la creación de una cuenta consume el pase: un CAPTCHA resuelto equivale, como máximo, a una cuenta;
- líneas 70–72: el pase se almacena en una cookie. Su atributo, [path="/register"], limita las solicitudes a las que el navegador la adjunta: solo las direcciones que comienzan con [/register];
- líneas 76–77: para eliminar una cookie, se debe especificar la misma ruta que cuando se estableció.
11.13.9. controllers/auth.py
El controlador de conexión, que utiliza todos estos servicios.
| # =========================================================================
# controllers/auth.py
# -------------------------------------------------------------------------
# Las rutas PÚBLICAS del inicio de sesión:
# GET / redirige a la página de inicio del rol (o a /login)
# GET /login muestra el formulario de inicio de sesión (con su CAPTCHA)
# POST /login verifica el límite de intentos, el CAPTCHA, login / contraseña
# POST /logout el 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, por lo tanto, no puede aprender nada insistiendo.
# =========================================================================
from flask import Blueprint, g, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import public
from rdvmedecins.entities import Role
from rdvmedecins.models.view_models import LoginModel, Message
from rdvmedecins.web.services import auth_service, captchas, limiter
auth = Blueprint("auth", __name__)
# la página de inicio de cada rol, justo después del inicio de sesión
def home_page(role: Role) -> str:
return url_for("area.patient_area") if role == Role.USER else url_for("schedule.show")
# la dirección IP del visitante. Detrás de un proxy inverso (nginx...), sería
# la del proxy: habría que envolver entonces la aplicación en el
# middleware ProxyFix de Werkzeug, que lee el encabezado X-Forwarded-For.
def ip_address() -> str:
return request.remote_addr or ""
# -----------------------------------------------------------------------
# GET /
# La ruta es pública: el usuario ha sido establecido, si lo hay, por
# auth/security.py (g.user), pero no se exige nada.
# -----------------------------------------------------------------------
@auth.get("/")
@public
def home():
return redirect(home_page(g.user.role) if g.user else url_for("auth.show_login"))
# -----------------------------------------------------------------------
# GET /login[?login=xxx]: el parámetro opcional rellena previamente el campo
# login (se usa justo después de la creación de una cuenta, ver controllers/registration.py)
# -----------------------------------------------------------------------
@auth.get("/login")
@public
def show_login():
# ya con sesión iniciada (token todavía válido): directo a la página de inicio
if g.user:
return redirect(home_page(g.user.role))
return form(request.args.get("login", "")[:30], None)
# -----------------------------------------------------------------------
# POST /login
# request.form.get: un campo ausente da None (y no un error 400) -
# es el código el que decide qué hacer con él.
# -----------------------------------------------------------------------
@auth.post("/login")
@public
def log_in():
login = (request.form.get("login") or "").strip()
password = request.form.get("password") or ""
ip = ip_address()
# 1. ¿demasiados fallos recientes?
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return form(login, Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)}))
# 2. el CAPTCHA
if not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, login)
return form(login, Message("ERRORS.WRONG_CAPTCHA"))
# 3. la contraseña
user = auth_service().validate_user(login, password) if login and password else None
if user is None:
limiter().login_failure(ip, login)
return form(login, Message("LOGIN.ERROR"))
limiter().login_success(ip, login)
response = redirect(home_page(user.role))
auth_service().set_token(response, user)
return response
# -----------------------------------------------------------------------
# POST /logout: borrar la cookie del token y luego ir a la página
# de inicio de sesión. Solo POST: un simple enlace (GET), colocado en otro sitio,
# no puede cerrar la sesión del usuario sin que lo sepa.
# -----------------------------------------------------------------------
@auth.post("/logout")
@public
def log_out():
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# el formulario, siempre con un CAPTCHA NUEVO (cada imagen se usa una
# sola vez); se muestra de nuevo el login escrito, nunca la contraseña
def form(login: str, error: Message | None):
model = LoginModel("LOGIN.TITLE", error, login, captchas().generate())
return render_template("login.html", model=model)
|
- línea 24: los servicios compartidos se obtienen mediante pequeñas funciones del módulo [web/services.py] (que se explica más adelante), que los recuperan de [app.extensions];
- líneas 30–31: cada rol tiene su propia página de inicio: un portal del paciente para los pacientes, y el calendario para los demás;
- líneas 37–38: la dirección IP del visitante. Detrás de un proxy inverso ([nginx], [Apache]), esta sería la dirección del proxy, que es la misma para todos los visitantes: la aplicación tendría entonces que envolverse en el middleware [ProxyFix] de [Werkzeug] (véase el capítulo sobre el ciclo de vida), que lee la dirección original del encabezado [X-Forwarded-For] añadido por el proxy;
- líneas 46–49: la raíz pública del sitio: redirige a la página de inicio del usuario o a la página de inicio de sesión;
- líneas 56–62: la página de inicio de sesión. Un usuario que ya ha iniciado sesión (cuyo token sigue siendo válido) es enviado directamente a su página de inicio. El parámetro opcional [login] rellena previamente el campo (después de crear una cuenta); [[:30]] limita su longitud a la de un nombre de usuario;
- Líneas 70–96: el proceso de inicio de sesión, en tres pasos y en este orden: posible bloqueo, el CAPTCHA y, solo entonces, la contraseña. Un intento rechazado en los dos primeros pasos nunca llega a verificar la contraseña: un bot no puede aprender nada por insistir. [request.form.get(...) or ""]: un campo vacío devuelve una cadena vacía. El mensaje de error es un objeto [Message]: una clave de traducción y sus parámetros (se explica más adelante);
- líneas 104–109: cierre de sesión, mediante POST (ejemplo 25). Es público: un usuario cuya sesión ha expirado debe poder hacer clic en “Cerrar sesión” sin ser redirigido antes;
- líneas 114–116: la página de inicio de sesión, siempre con un nuevo CAPTCHA. Su plantilla es un objeto [LoginModel] (véase [models/view_models.py]).
Observe que el formulario de inicio de sesión no utiliza [WTForms]: sus tres campos no tienen reglas de validación (un nombre de usuario vacío simplemente produce un inicio de sesión fallido), y el formulario está protegido contra ataques CSRF mediante [CSRFProtect], como todos los formularios de la aplicación.
11.14. La capa web: servicios compartidos
La carpeta [web] contiene lo que los controladores tienen en común. Cada módulo de ella responde a una pregunta que se hacen todos los controladores: cómo obtener un servicio, traducir un texto, mostrar un mensaje después de una redirección, volver a mostrar un formulario rechazado o convertir un error en una página.
11.14.1. web/services.py
| # =========================================================================
# web/services.py
# -------------------------------------------------------------------------
# Los objetos compartidos de la aplicación (ver ejemplo 06): se crean UNA sola vez,
# por la fábrica de la aplicación (rdvmedecins/__init__.py), y se
# almacenan en el diccionario app.extensions. Estas pequeñas funciones los
# encuentran allí, para la aplicación que procesa la solicitud actual
# (current_app); también les dan su TIPO a las herramientas de análisis.
# =========================================================================
from flask import current_app
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.web.application_model import ApplicationModel
def application() -> ApplicationModel:
return current_app.extensions["rdvmedecins.application"]
def auth_service() -> AuthService:
return current_app.extensions["rdvmedecins.auth"]
def captchas() -> CaptchaService:
return current_app.extensions["rdvmedecins.captchas"]
def limiter() -> AttemptLimiter:
return current_app.extensions["rdvmedecins.limiter"]
def passes() -> RegistrationPass:
return current_app.extensions["rdvmedecins.passes"]
|
Los objetos compartidos, creados por la fábrica y almacenados en [app.extensions], se recuperan mediante estas pequeñas funciones (ejemplo 06). Evitan tener que repetir la clave del diccionario en cada controlador y proporcionan su tipo a las herramientas de análisis: en un controlador, el editor sabe que [application()] es un [ApplicationModel] y ofrece sus métodos.
11.14.2. web/translator.py
| # =========================================================================
# web/translator.py
# -------------------------------------------------------------------------
# Traducción francés / inglés de la interfaz (ver ejemplo 22).
#
# Los diccionarios son los MISMOS archivos que los de las versiones NestJS,
# ASP.NET Core y Spring MVC de la aplicación (i18n/fr.json, i18n/en.json),
# leídos una sola vez al arrancar.
#
# En las vistas, la función t (ver web/common_model.py):
# {{ t("LOGIN.TITLE") }} sin parámetro;
# {{ t("AREA.HELLO", name=model.patient) }} parámetros con nombre;
# {{ t(message.key, message.params) }} un diccionario de parámetros.
#
# EL IDIOMA ACTUAL: g.language, establecido en cada solicitud a partir de una cookie
# (ver rdvmedecins/__init__.py, función set_language).
# =========================================================================
import json
import re
from pathlib import Path
from flask import g
LANGUAGES = ("fr", "en")
DEFAULT_LANGUAGE = "en"
# la cookie que recuerda el idioma elegido (ver controllers/language.py)
LANGUAGE_COOKIE = "rdvmedecins_language"
# {name}: un parámetro en un texto
PARAMETER = re.compile(r"\{(\w+)\}")
# el idioma admitido que corresponde a [code]: "fr" -> "fr"; "de" o None -> "en"
def language(code: str | None) -> str:
return code if code in LANGUAGES else DEFAULT_LANGUAGE
class Translator:
def __init__(self, folder: Path):
# idioma -> (clave completa "LOGIN.TITLE" -> texto)
self._dictionaries: dict[str, dict[str, str]] = {}
for code in LANGUAGES:
with open(folder / f"{code}.json", encoding="utf-8") as file:
self._dictionaries[code] = self._flatten(json.load(file))
# -----------------------------------------------------------------------
# translate("DOCTORS.ADDED", {"name": "Marie PELISSIER"})
# -> busca "DOCTORS.ADDED" en el diccionario del idioma y
# reemplaza {name} por su valor. Una clave ausente del idioma solicitado
# se busca en inglés; si falta en todas partes, se muestra la propia clave
# (así una omisión se detecta de inmediato).
# Los parámetros: un diccionario y/o parámetros con nombre.
# -----------------------------------------------------------------------
def translate(self, key: str | None, params: dict | None = None, **others) -> str:
if not key:
return ""
text = self._dictionaries[language(g.get("language"))].get(key)
if text is None:
text = self._dictionaries[DEFAULT_LANGUAGE].get(key, key)
values = {**(params or {}), **others}
if not values:
return text
return PARAMETER.sub(lambda m: str(values.get(m.group(1), m.group(0))), text)
# { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
@classmethod
def _flatten(cls, node: dict, prefix: str = "") -> dict[str, str]:
result = {}
for key, value in node.items():
full_key = f"{prefix}.{key}" if prefix else key
if isinstance(value, dict):
result.update(cls._flatten(value, full_key))
else:
result[full_key] = value
return result
|
El traductor del ejemplo 22, con tres adiciones:
- Líneas 56–65: los parámetros de un texto pueden proporcionarse mediante un diccionario (el segundo parámetro, [params]), mediante parámetros con nombre ([**others]), o ambos. Los mensajes de la aplicación (la clase [Message], que se explica más adelante) llevan sus parámetros en un diccionario; las vistas, en cambio, prefieren los parámetros con nombre. [{**a, **b}] crea un diccionario que combina los de [a] y [b];
- línea 61: una clave que falta en el idioma solicitado se busca en inglés antes de mostrarse tal cual;
- línea 59: [g.get("language")] devuelve [None] si [g] carece del atributo [language], en lugar de lanzar una excepción: el traductor funciona incluso si se produce un error antes de la función [before_request] que establece el idioma.
El nombre de la cookie de idioma lleva como prefijo el nombre de la aplicación ([rdvmedecins_language]), igual que el token y el pase: las cookies se asocian a un nombre de dominio ([localhost]), no a un puerto. Los ejemplos, que también se sirven desde [localhost], podrían de otro modo leer las cookies de la aplicación.
11.14.3. web/common_model.py
| # =========================================================================
# web/common_model.py
# -------------------------------------------------------------------------
# Lo que NECESITAN TODAS las vistas, sea cual sea la página (ver ejemplo
# 15): un "context processor", ejecutado antes de que se construya
# cada vista, agrega sus variables al modelo de todas las vistas:
# - user : el usuario conectado (o None), para la barra de navegación;
# - language : "fr" o "en";
# - path : la URL solicitada (menú activo de la barra de navegación,
# enlace "Another image" del CAPTCHA);
# - t : la función de traducción (ver web/translator.py).
# Los mensajes flash los lee el layout (get_flashed_messages).
# =========================================================================
from flask import g, request
from rdvmedecins.web.translator import Translator
def register(app, translator: Translator):
@app.context_processor
def common_model():
return {
"user": g.get("user"),
"language": g.get("language", "en"),
"path": request.path,
"t": translator.translate,
}
|
El procesador de contexto del ejemplo 15: cuatro variables disponibles en todas las vistas, sin que las acciones tengan que proporcionarlas: el usuario conectado (para la barra de navegación), el idioma (para el atributo [lang] de la página y los botones FR / EN), la ruta de la URL solicitada (para el menú activo y el enlace “Otra imagen” del CAPTCHA) y la función de traducción [t]. [g.get("user")] devuelve [None] si el atributo no existe (por ejemplo, una página de error generada antes de la autenticación).
11.14.4. web/flash.py
| # =========================================================================
# web/flash.py
# -------------------------------------------------------------------------
# Los mensajes "flash": un mensaje que se muestra UNA sola vez, en la SIGUIENTE
# página (ver ejemplo 20). Es el complemento natural del
# patrón "Post / Redirect / Get" usado por todos los formularios de la aplicación:
# un POST exitoso no construye una página, redirige (302) a una
# página GET; el mensaje, sin embargo, debe sobrevivir a la redirección.
#
# Flask los almacena en la SESIÓN, es decir, en una cookie FIRMADA con la
# clave secreta (SECRET_KEY): el servidor permanece SIN ESTADO, no guarda nada en
# memoria entre dos solicitudes. El navegador puede leer esta cookie (no está
# cifrada), pero no modificarla sin que la firma lo delate.
#
# Un mensaje no contiene un texto, sino una CLAVE de traducción y sus
# parámetros: se traduce al momento de mostrarse, en el idioma de
# la página (ver templates/layout.html). Su categoría: "success" (se muestra en
# la parte superior de la página) o "danger" (un error, se muestra en la parte inferior).
# =========================================================================
from flask import flash
def flash_success(key: str, **params):
flash({"key": key, "params": params}, "success")
def flash_error(key: str, **params):
flash({"key": key, "params": params}, "danger")
|
Los mensajes flash del ejemplo 20. Un mensaje no es un texto, sino un diccionario: la clave de traducción y sus parámetros. Se traducirá en el momento de mostrarlo, mediante la plantilla, al idioma de la página. [Flask] almacena los mensajes en la sesión, que es una cookie: para ello, los convierte a JSON, que acepta un diccionario de cadenas. La categoría del mensaje ([success] o [danger], los nombres de colores de [Bootstrap]) determina su ubicación: en la parte superior de la página para un éxito, en la parte inferior para un error.
11.14.5. web/errors.py
| # =========================================================================
# web/errors.py
# -------------------------------------------------------------------------
# Cómo los errores se convierten en páginas HTML. Tres manejadores se reparten
# el trabajo (ver ejemplo 24):
#
# 1. una InvalidSession (cuenta eliminada desde el inicio de sesión) -> de vuelta a
# la página de inicio de sesión, como con una sesión vencida;
# 2. un error HTTP: abort(400), abort(403) (rol insuficiente), página
# desconocida (404), método no admitido (405), token anti-CSRF
# ausente o incorrecto (400)... -> la página de error, con el código original;
# 3. cualquier otra excepción (una anomalía real) -> se escribe en el log
# del servidor, con su stack trace; el usuario ve la
# página de error 500 - nunca el stack trace.
# =========================================================================
from flask import current_app, redirect, render_template, url_for
from werkzeug.exceptions import HTTPException
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.models.view_models import ErrorModel
from rdvmedecins.web.flash import flash_error
MESSAGES = {
400: "ERRORS.BAD_REQUEST",
403: "ERRORS.FORBIDDEN",
404: "ERRORS.NOT_FOUND",
}
def error_page(code: int):
model = ErrorModel("ERROR_PAGE.TITLE", None, code, MESSAGES.get(code, "ERRORS.SERVER_ERROR"))
# la página conserva el código de error (404 sigue siendo 404...)
return render_template("error.html", model=model), code
def register(app):
@app.errorhandler(InvalidSession)
def invalid_session(e):
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
@app.errorhandler(HTTPException)
def http_error(e: HTTPException):
return error_page(e.code or 500)
# Exception: la clase padre de todas las excepciones; este manejador
# solo recibe las que ningún manejador más específico ha procesado
@app.errorhandler(Exception)
def anomaly(e: Exception):
current_app.logger.exception("unexpected error")
return error_page(500)
|
Los manejadores de errores del ejemplo 24:
- líneas 31–34: la página de error, con el código de error original (una página 404 sigue siendo una respuesta 404) y un mensaje traducido elegido según el código;
- líneas 39–44: una cuenta eliminada desde el inicio de sesión: redirección a la página de inicio de sesión, como con una sesión expirada;
- líneas 46–48: todos los errores HTTP: [abort(403)], una página desconocida (404), un método prohibido (405), un token anti-CSRF ausente o no válido (400, gestionado por [CSRFProtect])...;
- líneas 52–55: cualquier otra excepción, es decir, una verdadera anomalía (un error de programación, una base de datos que se ha vuelto inaccesible). [current_app.logger] es el registro de la aplicación (un objeto del módulo estándar [logging]); su método [exception] escribe en él el mensaje, seguido de la pila de llamadas de la excepción actual. El usuario, sin embargo, solo ve la página de error 500: nunca la pila de llamadas, que revelaría detalles internos de la aplicación. [Flask] siempre selecciona el manejador más específico: un error HTTP lo gestiona el segundo manejador, no este.
11.14.6. web/application_model.py
| # =========================================================================
# web/application_model.py
# -------------------------------------------------------------------------
# El caché / fachada de la capa de negocio (el equivalente de la clase
# [ApplicationModel] de las versiones anteriores de la aplicación): las
# listas de médicos y de clientes se leen una vez al arrancar y luego se
# sirven desde la memoria.
#
# Estas listas pueden CAMBIAR (el ADMIN agrega, edita y elimina
# médicos y clientes): cada escritura pasa por lo tanto por esta fachada,
# que recarga la lista afectada inmediatamente después. Este es todo el sentido de un
# ÚNICO punto de entrada a la capa de negocio: la regla "escritura =>
# recarga del caché" está escrita solo aquí.
#
# Un único objeto para toda la aplicación, usado por solicitudes
# procesadas EN PARALELO, en varios hilos. Por lo tanto, una lista nunca se modifica
# in situ: se REEMPLAZA por completo por una nueva. En Python,
# la asignación de un atributo es atómica: un hilo que lee la lista ve
# la antigua o la nueva, nunca una lista a medio construir.
# =========================================================================
from datetime import date
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.business import Business
# mismo contrato que la capa de negocio (Business)
class ApplicationModel:
def __init__(self, business: Business):
self._business = business
# carga inicial de las dos listas, al arrancar la aplicación.
# Un error de lectura (base de datos inaccesible...) no se captura:
# detiene el servidor, en lugar de dejarlo arrancar "vacío"
self._doctors: list[Doctor] = []
self._clients: list[Client] = []
self._reload_doctors()
self._reload_clients()
def _reload_doctors(self):
self._doctors = list(self._business.get_all_doctors())
def _reload_clients(self):
self._clients = list(self._business.get_all_clients())
# ------------------------------------------------ lecturas desde el caché
def get_all_doctors(self) -> list[Doctor]:
return self._doctors
def get_all_clients(self) -> list[Client]:
return self._clients
# el médico cuya cuenta de usuario es [user_id] - se usa para preseleccionar,
# para 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._doctors if d.user_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 importa son los datos más recientes (un paciente
# que acaba de editar 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 => recarga
def add_doctor(self, data: PersonData) -> Doctor:
doctor = self._business.add_doctor(data)
self._reload_doctors()
return doctor
def edit_doctor(self, id: int, data: PersonData) -> Doctor:
doctor = self._business.edit_doctor(id, data)
self._reload_doctors()
return doctor
def delete_doctor(self, id: int) -> None:
self._business.delete_doctor(id)
self._reload_doctors()
def add_client(self, data: PersonData) -> Client:
client = self._business.add_client(data)
self._reload_clients()
return client
def edit_client(self, id: int, data: PersonData) -> Client:
client = self._business.edit_client(id, data)
self._reload_clients()
return client
def delete_client(self, id: int) -> None:
self._business.delete_client(id)
self._reload_clients()
|
La caché de la capa web y su interfaz con la capa de negocio:
- líneas 32–40: las listas de médicos y pacientes se leen una sola vez, al iniciar. Se utilizan cada vez que se muestra el calendario (la lista desplegable de médicos, la lista de pacientes): mantenerlas en memoria evita dos consultas SQL por página. Un error de lectura no se captura: provoca que la aplicación falle al iniciar (véase “Problemas comunes”);
- líneas 50–59: datos recuperados de la caché. [get_doctor_by_user_id] identifica al médico conectado para preseleccionar su propio calendario;
- líneas 63–96: las demás operaciones de lectura, y las citas, simplemente se transmiten a la capa de negocio. [get_client_by_user_id] no utiliza la caché: un paciente que acaba de modificar o eliminar su cuenta debe ver los datos más recientes;
- líneas 100–126: cada actualización de médicos o clientes refresca la lista correspondiente. Esta es la ventaja de tener un único punto de entrada a la capa de negocio: la regla “actualizar y luego refrescar la caché” se implementa solo aquí.
Este objeto único lo utilizan solicitudes procesadas en paralelo en varios hilos: por lo tanto, una lista nunca se modifica en el lugar (mediante [append] o [remove]); en su lugar, se reemplaza por completo con una nueva. En [Python], la asignación de un atributo es atómica: un hilo que lee la lista ve la versión antigua o la nueva, nunca una lista construida parcialmente. Por lo tanto, no se necesita ningún bloqueo.
[ApplicationModel] cumple el contrato [Business] (tiene los mismos métodos que [BusinessService]): para los controladores, es la capa de negocio. Se podría eliminar la caché sin tocar los controladores colocando directamente [BusinessService] dentro de [app.extensions].
11.14.7. web/validation.py
| # =========================================================================
# web/validation.py
# -------------------------------------------------------------------------
# Lo necesario para MOSTRAR DE NUEVO un formulario rechazado: los errores de entrada
# campo por campo y los campos que se resaltan en rojo.
# =========================================================================
from flask_wtf import FlaskForm
from rdvmedecins.models.view_models import FormState, Message
# -----------------------------------------------------------------------
# el formulario validado (ver forms/forms.py) -> el diccionario
# campo -> clave del mensaje, conservando solo el primer mensaje de cada
# campo: { "last_name": "ERRORS.LASTNAME_REQUIRED", ... }
#
# Nuestros mensajes son claves de traducción ("ERRORS...."). Un mensaje que
# WTForms ha escrito por sí mismo (en inglés) se reemplaza por la clave
# ERRORS.INVALID_FORM.
# -----------------------------------------------------------------------
def errors_of(form: FlaskForm) -> dict[str, str]:
errors = {}
for field, messages in form.errors.items():
message = str(messages[0])
errors[field] = message if message.startswith("ERRORS.") else "ERRORS.INVALID_FORM"
return errors
# -----------------------------------------------------------------------
# los campos del formulario afectados por cada error de negocio de "entrada"
# (un duplicado): se resaltan en rojo, y el mensaje va en la parte inferior de la página
# -----------------------------------------------------------------------
BUSINESS_ERROR_FIELDS = {
"ERRORS.LOGIN_TAKEN": ["login"],
"ERRORS.DOCTOR_ALREADY_EXISTS": ["first_name", "last_name"],
"ERRORS.PATIENT_ALREADY_EXISTS": ["first_name", "last_name"],
}
# el estado de un formulario que se muestra (de nuevo): un mensaje bajo cada campo
# rechazado por la validación (errors) y los campos que se resaltan en rojo,
# esos más posibles otros (other_fields)
def state(errors: dict[str, str], other_fields: list[str] | None = None) -> FormState:
return FormState(dict(errors), set(errors) | set(other_fields or []))
# EL mensaje de error de la página, mostrado en la parte inferior de la página: [error] si
# lo hay; de lo contrario "The form contains errors." si hay
# errores de campo; de lo contrario, nada
def page_message(errors: dict[str, str], error: Message | None) -> Message | None:
if error is not None:
return error
return Message("ERRORS.INVALID_FORM") if errors else None
|
Lo necesario para volver a mostrar un formulario rechazado:
- líneas 21–26: los errores de un formulario de [WTForms] (ejemplo 19), en forma de un diccionario “campo → clave de mensaje”, conservando solo el primer mensaje de cada campo. Los mensajes de nuestros validadores son claves de traducción ([ERRORS.LASTNAME_REQUIRED], véase [forms/forms.py]); un mensaje que [WTForms] hubiera generado por sí mismo, en inglés, se reemplaza por una clave genérica;
- líneas 33–36: algunos errores de lógica de negocio se refieren a campos específicos, como un nombre de usuario que ya está en uso o un nombre con la misma ortografía. Sus mensajes de error aparecen en la parte inferior de la página, pero los campos afectados se resaltan en rojo para que el usuario vea de inmediato qué debe corregir (véase la captura de pantalla del nombre con la misma ortografía, más arriba);
- líneas 43–44: el estado de un formulario que se va a mostrar de nuevo: los mensajes debajo de los campos y todos los campos que deben resaltarse en rojo. [set(errors)] es el conjunto de claves del diccionario; el operador [|] realiza la unión de dos conjuntos;
- líneas 50–53: el mensaje general del pie de página.
11.14.8. web/utils.py
| # =========================================================================
# web/utils.py
# -------------------------------------------------------------------------
# Pequeñas funciones utilitarias de la capa web:
# - etiquetas: "Mme Alice DURAND";
# - fechas: "yyyy-mm-dd", horas "8:05", días "Wednesday 23 September 2026";
# - entrada: lectura de un entero positivo enviado por el navegador;
# - usuario: el usuario conectado y su paciente (entidad Client).
# =========================================================================
import re
from datetime import date, datetime
from babel.dates import format_date
from flask import g
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import Client, Slot, Person
# ----------------------------------------------------------------- etiquetas
# "Mme Alice DURAND"
def label(p: Person) -> str:
return f"{p.title} {p.first_name} {p.last_name}"
# ----------------------------------------------------------------- fechas
# el formato de las fechas en las URL y en el campo <input type="date">
ISO_FORMAT = re.compile(r"\d{4}-\d{2}-\d{2}")
# la fecha, si [text] es una fecha que existe en el formato yyyy-mm-dd; None en caso contrario.
# strptime verifica que la fecha exista: "2026-02-30" se rechaza
def valid_date(text: str | None) -> date | None:
if text is None or not ISO_FORMAT.fullmatch(text):
return None
try:
return datetime.strptime(text, "%Y-%m-%d").date()
except ValueError:
return None
def iso(day: date) -> str:
return day.isoformat()
# "8:05" en lugar de "8:5"
def format_time(h: int, m: int) -> str:
return f"{h}:{m:02d}"
def time(s: Slot) -> str:
return f"{format_time(s.start_hour, s.start_minute)} - {format_time(s.end_hour, s.end_minute)}"
# "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", según el
# idioma de la solicitud (g.language). El formato de Babel: EEEE el día de la
# semana completo, d el día, MMMM el mes completo, y, el año
def format_day(day: date) -> str:
return format_date(day, "EEEE d MMMM y", locale=g.language)
# ----------------------------------------------------------------- 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 (ver auth/security.py). Las acciones protegidas
# solo se llaman si existen; por precaución, su ausencia se trata
# como una sesión vencida.
def user() -> ConnectedUser:
if g.user is None:
raise InvalidSession()
return g.user
# -----------------------------------------------------------------------
# El paciente (entidad 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
# inicio de sesión mientras su token sigue siendo válido: se trata como una
# sesión vencida (ver InvalidSession).
# -----------------------------------------------------------------------
def connected_patient(application) -> Client:
patient = application.get_client_by_user_id(user().user_id)
if patient is None:
raise InvalidSession()
return patient
|
Funciones de utilidad usadas por varios controladores:
- línea 24: el tratamiento de una persona, “Mme Alice DURAND”;
- líneas 31–42: análisis de una fecha en el formato [yyyy-mm-dd], que es el mismo que se usa para las entradas de URL en el calendario ([day=2026-09-26]) y para el campo [<input type="date">]. La expresión regular verifica el formato ([fullmatch]: toda la cadena debe coincidir), mientras que [strptime] verifica que la fecha exista. Una fecha no válida da como resultado [None]: la acción determina el desenlace;
- líneas 50–51: el formato [02d] produce un entero de dos dígitos, rellenado con ceros: [8:05];
- líneas 61–62: una fecha escrita completa, en el idioma de la solicitud, con [Babel] (ejemplo 16). Aquí el formato se especifica explícitamente: [EEEE], el día de la semana en letras; [d], el día; [MMMM], el mes en letras; [y], el año;
- líneas 69–73: lectura de un identificador enviado por el navegador (un parámetro de URL, un campo oculto). [\d{1,9}]: de uno a nueve dígitos, lo que excluye letras, espacios y números demasiado grandes para una columna [INT]. Todo lo que proviene del navegador pudo haber sido modificado: debe verificarse antes de usarse;
- líneas 82–85: el usuario conectado; su ausencia (que no debería ocurrir en una acción protegida) se trata como una sesión expirada;
- líneas 98–102: el paciente (la entidad [Client]) correspondiente al usuario conectado. El token contiene solo el ID de la cuenta: el paciente se identifica mediante la columna [clients.user]. Si no existe, significa que la cuenta fue eliminada desde que el usuario inició sesión.
| # =========================================================================
# forms/rules.py
# -------------------------------------------------------------------------
# Las reglas de entrada comunes a los formularios de "persona", y los FILTROS
# de WTForms (ver ejemplo 19): funciones que transforman el valor
# recibido ANTES de la validación.
# =========================================================================
TITLES = ("Mr", "Mme", "Melle")
# login: letras minúsculas, dígitos, punto, guion, guion bajo - 30 caracteres como máximo
LOGIN_FORMAT = r"^[a-z0-9._-]{1,30}$"
# longitud mínima de una contraseña ELEGIDA por un paciente
PASSWORD_MIN = 6
# " dupont " -> "dupont" ; " " -> None
def clean(value):
if not isinstance(value, str):
return value
return value.strip() or None
# " Dupont " -> "dupont": un login siempre va en minúsculas
def login(value):
value = clean(value)
return value.lower() if isinstance(value, str) else value
# un campo vacío -> None; en una contraseña, los espacios NO se eliminan
# (pueden formar parte de ella)
def empty_to_none(value):
return value if value else None
# el campo oculto [version]: un entero, o None si falta o está vacío.
# Un texto que no es un número: un ValueError, que WTForms convierte
# en un error de campo, con este mensaje (una clave de traducción)
def version(value):
if value in (None, ""):
return None
try:
return int(value)
except (TypeError, ValueError):
raise ValueError("ERRORS.INVALID_FORM")
|
Reglas de entrada comunes a todos los formularios, y los filtros de [WTForms] (ejemplo 19):
- líneas 8–14: tratamientos permitidos, el formato de un nombre de usuario (letras minúsculas, números, punto, guion, guion bajo, hasta 30 caracteres) y la longitud mínima de una contraseña elegida por un paciente;
- Líneas 18–21: se eliminan los espacios que rodean una entrada; una entrada vacía se convierte en [None]. [a or b] equivale a [b] si [a] es “falso” (en este caso, una cadena vacía);
- líneas 25–27: un nombre de usuario siempre está en minúsculas;
- líneas 32–33: en una contraseña, los espacios no se eliminan, ya que pueden formar parte de la contraseña;
- líneas 39–45: el campo oculto de versión (el bloqueo optimista): un entero, o [None]. Un filtro que lanza una excepción como [ValueError] provoca un error de campo, con el mensaje de error correspondiente al de la excepción: un navegador que envíe algo distinto de un número recibiría el error “formulario no válido”.
| # =========================================================================
# forms/forms.py
# -------------------------------------------------------------------------
# Los campos de los formularios de "persona" y sus restricciones (ver ejemplos
# 19 y 28). Tres formularios comparten los mismos campos de identidad
# (título, nombre, apellido):
#
# PersonFields título, nombre, apellido
# ├─ PersonForm + login / contraseña OPCIONALES, versión
# │ (el ADMIN agrega o edita 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 edita su cuenta)
#
# Una clase de WTForms que hereda de otra también hereda sus campos.
#
# ENLACE (BINDING): PersonForm() lee por sí mismo los campos con el mismo nombre de la
# solicitud POST actual (request.form) y les aplica sus filtros
# (espacios superfluos eliminados, login en minúsculas...).
# VALIDACIÓN: form.validate() verifica luego las restricciones de cada
# campo, en orden; la primera que falla guarda su mensaje en
# form.<field>.errors. Estos mensajes son CLAVES de traducción (ver i18n/*.json).
#
# Los formularios se usan aquí solo para leer y validar la entrada: las vistas
# escriben ellas mismas sus etiquetas <input>, a partir de los modelos de vista
# (ver models/view_models.py).
# =========================================================================
from flask_wtf import FlaskForm
from wtforms import PasswordField, StringField
from wtforms.validators import AnyOf, DataRequired, InputRequired, Length, Optional, Regexp
from rdvmedecins.forms import rules
# ------------------------------------------------------------------ base común
class PersonFields(FlaskForm):
title = StringField(validators=[AnyOf(rules.TITLES, message="ERRORS.INVALID_TITLE")])
# longitudes máximas = las de las columnas SQL (VARCHAR(20)).
# DataRequired detiene la validación del campo si está vacío: el mensaje
# de Length, por lo tanto, nunca se agrega a ese
first_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.FIRSTNAME_REQUIRED"),
Length(max=20, message="ERRORS.FIRSTNAME_TOO_LONG")])
last_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.LASTNAME_REQUIRED"),
Length(max=20, message="ERRORS.LASTNAME_TOO_LONG")])
# ------------------------------------------------------------------ ADMIN
class PersonForm(PersonFields):
# opcional (ver business/person_data.py): Optional detiene la validación de un
# campo vacío, sin error
login = StringField(filters=[rules.login], validators=[
Optional(), Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# opcional; 72 caracteres como máximo (más allá, bcrypt ignora el resto)
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False), Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
# campo oculto del formulario de edición (bloqueo optimista)
version = StringField(filters=[rules.version])
# ------------------------------------------------------------------ registro de un paciente
class RegistrationForm(PersonFields):
# InputRequired: la entrada no debe estar vacía
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# dos restricciones Length, cada una con su mensaje
password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.PASSWORD_REQUIRED"),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CONFIRMATION_REQUIRED")])
# ------------------------------------------------------------------ "Manage my account"
class MyAccountForm(PersonFields):
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# opcional: vacío = contraseña sin cambios
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none])
# la contraseña ACTUAL, requerida para cualquier edición de la cuenta
current_password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CURRENT_PASSWORD_REQUIRED")])
version = StringField(filters=[rules.version])
|
- Líneas 38–51: los campos comunes a los tres formularios: tratamiento, nombre, apellido. Los mensajes de los validadores son claves de traducción: la vista los traducirá al idioma de la página. El validador [AnyOf] acepta un valor de una lista. Las longitudes máximas son las de las columnas SQL: una entrada más larga sería rechazada por la base de datos;
- líneas 55–67: el formulario del administrador: un nombre de usuario y una contraseña opcional (el validador [Optional] deja de validar un campo vacío sin informar de un error; [strip_whitespace=False]: una contraseña formada por espacios no se considera vacía), y la versión;
- líneas 71–85: el formulario de registro de pacientes: el nombre de usuario, la contraseña y la confirmación son obligatorios. Dos validadores, [Length], cada uno con su propio mensaje: demasiado corta, demasiado larga;
- líneas 89–107: “Administrar mi cuenta”: una nueva contraseña opcional y la contraseña actual, que es obligatoria para cualquier cambio.
Una clase de [WTForms] que hereda de otra clase hereda sus campos: los tres formularios comparten los campos de [PersonFields]. La comparación de la contraseña con su confirmación no la gestiona el validador [EqualTo] (ejemplo 19), sino que la realiza la acción, que así elige el mensaje y el campo correspondiente.
Observe que estos formularios se usan únicamente para leer y validar los datos introducidos por el usuario: las vistas no invocan los campos de [WTForms] para renderizarlos (ejemplo 18); en su lugar, escriben sus propias etiquetas [<input>] a partir de las plantillas de las vistas. Este enfoque mantiene las vistas idénticas para los tres formularios y da a la acción el control total de lo que se muestra (nunca una contraseña, por ejemplo). Este es también el enfoque utilizado en las versiones anteriores de la aplicación.
11.15.3. models/view_models.py
| # =========================================================================
# models/view_models.py
# -------------------------------------------------------------------------
# Los "modelos de vista": lo que cada acción pasa a su
# vista, con el nombre [model]. Son dataclasses: objetos construidos
# de una sola vez por la acción, que la vista se limita a leer
# ({{ model.schedule.rows }}...).
#
# Regla que siguen todas las páginas: sin lógica en las vistas. Las
# acciones preparan datos YA formateados ("Mme Marie
# PELISSIER", "8:00 - 8:20", selected = True...) y ya filtrados según
# el rol del usuario; las vistas se limitan a colocarlos en el HTML.
#
# Cada modelo de página tiene dos campos, leídos por el layout (templates/layout.html):
# page_title, la clave del título de la página, y error, EL mensaje de error de
# la página, mostrado en la parte inferior de la página (None: sin error).
# =========================================================================
from dataclasses import dataclass, field
from rdvmedecins.auth.captcha import Captcha
from rdvmedecins.forms import rules
# un mensaje por traducir: su clave y sus parámetros
@dataclass(frozen=True)
class Message:
key: str
params: dict[str, str] = field(default_factory=dict)
# una opción de una lista desplegable (médico, paciente)
@dataclass(frozen=True)
class OptionView:
id: int
label: str
selected: bool
# ------------------------------------------------------------------ inicio de sesión
@dataclass
class LoginModel:
page_title: str
error: Message | None
login: str
captcha: Captcha
# ------------------------------------------------------------------ agenda
@dataclass(frozen=True)
class ScheduleRowView:
slot_id: int
time: str # "8:00 - 8:20"
free: bool
patient: str | None # nombre mostrado para una franja reservada; None = "Booked"
mine: bool # la cita del paciente conectado
bookable: bool # ¿mostrar el botón "Book"?
book_url: str
appointment_id: int | None # se llena solo si se muestra el botón "Cancel"
@dataclass(frozen=True)
class ScheduleView:
doctor: str
day: str
rows: list[ScheduleRowView]
@dataclass(frozen=True)
class BookingView:
slot_id: int
time: str
clients: list[OptionView] # ADMIN / DOCTOR: los pacientes entre los que se puede elegir
patient: str | None # USER: el paciente es él mismo
@dataclass
class ScheduleModel:
page_title: str
error: Message | None
doctors: list[OptionView]
doctor_id: int | None
day: str # "yyyy-mm-dd"
schedule: ScheduleView | None
booking: BookingView | None
back_url: str # la agenda mostrada, sin diálogo de reserva
# paciente que ya tiene una cita próxima: el mensaje que explica
# por qué no hay un botón "Book"
info: str | None
# ------------------------------------------------------------------ formularios de "persona"
# los valores mostrados en los campos del formulario (nunca la contraseña)
@dataclass(frozen=True)
class PersonValues:
title: str = "Mr"
first_name: str = ""
last_name: str = ""
login: str = ""
version: int | None = None
# el estado de un formulario rechazado: el mensaje mostrado BAJO cada campo
# (campo -> clave del mensaje) y los campos que se resaltan en rojo (clase
# de Bootstrap is-invalid): los que tienen un mensaje, más posibles otros
# (nombre + apellido duplicados, login ya en uso...)
@dataclass(frozen=True)
class FormState:
errors: dict[str, str] = field(default_factory=dict)
invalid_fields: set[str] = field(default_factory=set)
def error_of(self, field: str) -> str | None:
return self.errors.get(field)
def invalid_class(self, field: str) -> str:
return "is-invalid" if field in self.invalid_fields else ""
# una opción de la lista de títulos
@dataclass(frozen=True)
class TitleOption:
value: str
selected: bool
# lo que usa el fragmento común person_fields.html (título, nombre, apellido):
# una clase base de la que heredan los tres modelos de formulario
@dataclass
class FormView:
page_title: str
error: Message | None
values: PersonValues
state: FormState
# una propiedad: se lee como un atributo (model.titles), pero se calcula
@property
def titles(self) -> list[TitleOption]:
return [TitleOption(t, t == self.values.title) for t in rules.TITLES]
@property
def password_min(self) -> int:
return rules.PASSWORD_MIN
@dataclass
class PersonFormModel(FormView):
creating: bool # True: agregar; False: editar
action: str # URL del POST
list_url: str
@dataclass
class RegistrationModel(FormView):
pass
@dataclass
class MyAccountModel(FormView):
pass
# ------------------------------------------------------------------ listas de médicos / clientes
# las claves de traducción específicas de cada tipo de persona
@dataclass(frozen=True)
class PersonKeys:
title: str # "Doctors"
add: str # "Add a doctor"
edit: str # "Edit a doctor"
empty: str # "No doctors."
confirm_delete: str # "Delete this doctor and their account?"
added: str # "Doctor {name} has been added (login: {login})."
edited: str
deleted: str
@dataclass(frozen=True)
class PersonView:
title: str
first_name: str
last_name: str
login: str
edit_url: str
delete_url: str
@dataclass
class PersonListModel:
page_title: str
error: Message | None
keys: PersonKeys
add_url: str
persons: list[PersonView]
# ------------------------------------------------------------------ área del paciente
@dataclass(frozen=True)
class AppointmentView:
id: int
day: str
time: str
doctor: str
schedule_url: str
@dataclass
class AreaModel:
page_title: str
error: Message | None
patient: str
appointments: list[AppointmentView]
# ------------------------------------------------------------------ página de error
@dataclass
class ErrorModel:
page_title: str
error: Message | None
code: int
message: str
|
Los modelos de vista (*view models*): lo que cada acción pasa a su vista, con el nombre [model]. La regla que siguen todas las páginas: sin lógica en las vistas. Las acciones preparan datos ya formateados (“Mme Marie PELISSIER”, “8:00 – 8:20”) y ya filtrados según el rol del usuario; las vistas simplemente colocan estos datos en el HTML.
- líneas 26–28: un mensaje que se debe traducir: una clave y sus parámetros. [field(default_factory=dict)]: el valor predeterminado es un diccionario nuevo y vacío para cada objeto. No se puede escribir [= {}]: ese diccionario se crearía una sola vez y lo compartirían todos los objetos;
- líneas 33–36: una opción de una lista desplegable;
- líneas 41–45: el modelo de la página de inicio de sesión. Cada modelo de página tiene dos campos que lee la plantilla: [page_title], la clave del título de la página, y [error], el mensaje de error que se muestra en la parte inferior de la página;
- líneas 50–58: una fila del calendario, ya completada para el usuario conectado: [patient] es igual a [None] para una franja horaria ocupada por otro paciente, cuando el usuario es un paciente (la vista mostrará “Reservado”); [bookable] indica si se debe mostrar el botón “Reservar”; [appointment_id] solo se completa si se debe mostrar el botón “Cancelar”. Todas estas decisiones las toma la acción;
- líneas 69–73: la ventana de reserva: la lista de pacientes para un administrador o un médico, el nombre del paciente para un paciente;
- líneas 77–88: el modelo de la página del calendario;
- líneas 108–116: el estado de un formulario rechazado, con dos métodos invocados por las vistas: el mensaje de un campo y la clase CSS que lo resalta en rojo;
- líneas 129–142: la clase base de los tres modelos de formulario, utilizada por el fragmento común [person_fields.html]. Sus dos propiedades calculan la lista de tratamientos (incluido el tratamiento seleccionado) y la longitud mínima de una contraseña;
- Líneas 146–158: los tres modelos de formulario heredan de [FormView]. Una [dataclass] que hereda de otra agrega sus campos a los de su clase padre;
- líneas 166–174: claves de traducción específicas de los médicos o de los clientes: la misma vista muestra ambas listas;
- líneas 198–211: el área del paciente;
- líneas 216–220: la página de error.
11.16. La capa web: controladores
La carpeta [controllers] contiene un blueprint por cada parte de la aplicación (el controlador de inicio de sesión, [controllers/auth.py], se presentó junto con la autenticación):
Blueprint | Direcciones |
[language] | [GET /language/<code>] |
[schedule] | [GET /schedule], [POST /schedule/book], [POST /schedule/cancel] |
[doctors], [clients] | [/doctors/...], [/clients/...]: listar, agregar, editar, eliminar |
[registration] | [POST /register/access], [GET], y [POST /register] |
[area] | [/my-area], [/my-area/cancel], [/my-account], [/my-account/delete] |
Todas las acciones siguen el mismo patrón: leer y validar la solicitud, invocar la capa de negocio (mediante [ApplicationModel]) y construir el modelo de vista; o bien, para una acción como POST, registrar un mensaje flash y redirigir (flujo PRG, ejemplo 20).
11.16.1. controllers/language.py
| # =========================================================================
# controllers/language.py
# -------------------------------------------------------------------------
# GET /language/fr, GET /language/en: los dos botones FR / EN de la
# barra de navegación. Ruta pública: se debe poder cambiar el idioma antes de
# iniciar sesión.
#
# La elección se recuerda en una cookie: en cada solicitud siguiente, la
# función set_language (ver rdvmedecins/__init__.py) la lee de nuevo y establece el
# idioma de la solicitud (g.language). Luego se vuelve a la página de origen.
# =========================================================================
from datetime import timedelta
from urllib.parse import urlsplit
from flask import Blueprint, abort, current_app, redirect, request
from rdvmedecins.auth.security import public
from rdvmedecins.web.translator import LANGUAGE_COOKIE, LANGUAGES
language = Blueprint("language", __name__)
@language.get("/language/<code>")
@public
def change(code: str):
if code not in LANGUAGES:
abort(404) # -> página de error 404 (véase web/errors.py)
response = redirect(origin_page())
response.set_cookie(LANGUAGE_COOKIE, code, max_age=timedelta(days=365), path="/",
httponly=True, samesite="Lax", secure=current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# la página anterior, según el encabezado HTTP "Referer" enviado por el
# navegador. Solo se conserva su ruta (/schedule?...): redirigir a
# una dirección completa proporcionada por la solicitud permitiría enviar
# al usuario a otro sitio (la falla conocida como "open redirect").
# -----------------------------------------------------------------------
def origin_page() -> str:
referer = request.headers.get("Referer")
if not referer:
return "/"
url = urlsplit(referer)
path = url.path
# "//site.com/..." sería interpretado por el navegador como una dirección
# en OTRO sitio: también se rechaza
if not url.scheme or not path.startswith("/") or path.startswith("//") \
or path.startswith("/language/"):
return "/"
return f"{path}?{url.query}" if url.query else path
|
La selección de idioma del ejemplo 22, con dos precauciones adicionales en [origin_page] (líneas 40–51): un [Referer] sin esquema ([http], [https]) no es una dirección completa, y un [Referer] que fuera a su vez una dirección [/language/...] redirigiría a esta acción, creando un bucle. En ambos casos, el usuario es redirigido de vuelta a la raíz del sitio. La duración de la cookie se especifica mediante un [timedelta]: [set_cookie] lo acepta igual de bien que un número de segundos.
La página principal de la aplicación, para todos los roles.
| # =========================================================================
# controllers/schedule.py
# -------------------------------------------------------------------------
# La página de la agenda: elección de un médico y un día, agenda de este
# médico en 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
# de la franja 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 marcador,
# usar el botón "Back" del navegador - sin una sola línea
# de JavaScript.
#
# Qué ve y qué puede hacer cada uno:
#
# | rol | franja reservada mostrada | Book | Cancel |
# |---------------|-----------------------------------|--------------------|---------|
# | ADMIN, DOCTOR | nombre del paciente | para un paciente | sí |
# | | | elegido en una lista | |
# | USER (paciente)| "Booked", 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 "My area".
#
# CONFIDENCIALIDAD: para un paciente, el nombre de los OTROS pacientes no está
# simplemente oculto por la vista - nunca se coloca en el modelo
# pasado a la vista. El HTML enviado al navegador, por lo tanto, no lo contiene,
# ni siquiera oculto (de lo contrario, un simple "View page source" lo revelaría).
#
# Sin reservas en el pasado: el botón "Book" solo aparece
# para hoy y los días siguientes (y la capa de negocio de todos modos
# la rechazaría).
#
# Seguridad: todas las URL /schedule requieren un usuario autenticado
# (ver auth/security.py: todo lo que no es @public). @roles_required
# en una acción exige además uno de los roles indicados. Sin un token válido:
# de vuelta a /login; rol insuficiente: página 403.
# =========================================================================
from dataclasses import dataclass
from datetime import date
from flask import Blueprint, abort, redirect, render_template, request, url_for
from rdvmedecins.auth.security import roles_required
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Person, Role
from rdvmedecins.business import dates
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (ScheduleModel, ScheduleView, ScheduleRowView, Message,
OptionView, BookingView)
from rdvmedecins.web import utils
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application
schedule = Blueprint("schedule", __name__, url_prefix="/schedule")
# lo que el controlador sabe del usuario, para decidir qué mostrar
@dataclass(frozen=True)
class Rights:
manager: bool # ADMIN o DOCTOR
patient: Client | None # el cliente conectado (rol USER), de lo contrario None
patient_can_book: bool # USER sin una cita próxima
# -----------------------------------------------------------------------
# GET /schedule
# Los parámetros de la URL se leen en bruto (request.args.get), para
# distinguir un parámetro AUSENTE (None) de un parámetro VACÍO (?doctorId=).
# -----------------------------------------------------------------------
@schedule.get("")
def show():
error = None
user = utils.user()
rights = compute_rights()
# el día: el de la URL si es válido; de lo contrario, hoy
day = dates.today()
raw_day = request.args.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 = "ERRORS.INVALID_DATE"
day_bookable = day >= dates.today()
# el médico: el de la URL; en su defecto, para un médico conectado, él mismo
raw_doctor_id = request.args.get("doctorId")
doctor_id = utils.positive_integer(raw_doctor_id)
if raw_doctor_id is None and user.role == Role.DOCTOR:
doctor = application().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 application().get_all_doctors()]
# la agenda, si se elige un médico (y la fecha es válida)
view = None
if doctor_id is not None and error is None:
doctor_schedule = application().get_doctor_day_schedule(doctor_id, day)
if doctor_schedule is None:
error = "ERRORS.DOCTOR_NOT_FOUND"
else:
view = schedule_view(doctor_schedule, rights, day_bookable)
# el diálogo de reserva: solo si la franja solicitada es
# reservable por este usuario
booking = None
slot_id = utils.positive_integer(request.args.get("book"))
if view is not None and slot_id is not None:
row = next((r for r in view.rows if r.slot_id == slot_id and r.bookable),
None)
if row is not None:
booking = BookingView(
row.slot_id,
row.time,
[option(c, False) for c in application().get_all_clients()]
if rights.manager else [],
utils.label(rights.patient) if rights.patient else None)
model = ScheduleModel(
page_title="SCHEDULE.PAGE_TITLE",
error=Message(error) if error else None,
doctors=doctors,
doctor_id=doctor_id,
day=utils.iso(day),
schedule=view,
booking=booking,
back_url=schedule_url(doctor_id, day) if doctor_id is not None else url_for("schedule.show"),
info=patient_info(rights, view))
return render_template("schedule.html", model=model)
# -----------------------------------------------------------------------
# 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 establece un mensaje flash y se redirige
# a la agenda (ver ejemplo 20).
# -----------------------------------------------------------------------
@schedule.post("/book")
@roles_required(Role.ADMIN, Role.DOCTOR, Role.USER)
def book():
doctor_id, day = read_schedule_request()
slot_id = utils.positive_integer(request.form.get("slotId"))
if doctor_id is None or slot_id is None:
abort(400) # -> página "invalid request" (véase web/errors.py)
user = utils.user()
if user.is_patient:
client = utils.connected_patient(application())
else:
client_id = utils.positive_integer(request.form.get("clientId"))
if client_id is None:
# ningún paciente elegido: el diálogo de reserva se abre de nuevo
flash_error("ERRORS.CHOOSE_PATIENT")
return redirect(schedule_url(doctor_id, day, slot_id))
client = application().get_client_by_id(client_id)
slot = application().get_slot_by_id(slot_id)
if client is None:
flash_error("ERRORS.PATIENT_NOT_FOUND")
elif slot is None or slot.doctor_id != doctor_id:
flash_error("ERRORS.SLOT_NOT_FOUND")
else:
try:
# las reglas (no en el pasado, una sola cita próxima por
# paciente, franja libre) las verifica la capa de negocio
application().add_appointment(day, slot, client)
flash_success("SCHEDULE.BOOKED")
except BusinessException as e:
# misma regla, pero con un mensaje en segunda persona cuando es el
# propio paciente quien reserva ("You already have..." en lugar
# de "This patient..."). Las demás excepciones (anomalías
# reales) no se capturan: página 500.
if e.key == "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT" and user.is_patient:
flash_error("SCHEDULE.ALREADY_BOOKED_INFO")
else:
flash_error(e.key, **e.params)
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# POST /schedule/cancel campos: appointmentId, doctorId, day
# (un paciente cancela SU cita desde "My area", no desde aquí)
# -----------------------------------------------------------------------
@schedule.post("/cancel")
@roles_required(Role.ADMIN, Role.DOCTOR)
def cancel():
doctor_id, day = read_schedule_request()
appointment_id = utils.positive_integer(request.form.get("appointmentId"))
if doctor_id is None or appointment_id is None:
abort(400)
appointment = application().get_appointment_by_id(appointment_id)
if appointment is None:
# ya cancelada (por otra persona, o por doble clic)
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# ¿quién está conectado y qué puede hacer en esta página?
# -----------------------------------------------------------------------
def compute_rights() -> Rights:
if not utils.user().is_patient:
return Rights(True, None, False)
patient = utils.connected_patient(application())
upcoming = application().get_client_upcoming_appointments(patient.id)
return Rights(False, patient, not upcoming)
# -----------------------------------------------------------------------
# la agenda del médico, formateada para la vista - y filtrada según los derechos
# -----------------------------------------------------------------------
def schedule_view(doctor_schedule: DoctorDaySchedule, rights: Rights, day_bookable: bool) -> ScheduleView:
doctor_id = doctor_schedule.doctor.id
day = doctor_schedule.day
rows = []
for dds in doctor_schedule.doctor_day_slots:
slot, appointment = dds.slot, dds.appointment
free = appointment is None
# ¿la cita del paciente conectado?
mine = appointment is not None and rights.patient is not None and appointment.client_id == rights.patient.id
rows.append(ScheduleRowView(
slot_id=slot.id,
time=utils.time(slot),
free=free,
# EL punto de confidencialidad: un paciente solo recibe el nombre
# de SU cita; para las demás, None (la vista muestra "Booked")
patient=utils.label(appointment.client) if appointment is not None and (rights.manager or mine) else None,
mine=mine,
bookable=free and day_bookable 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(utils.label(doctor_schedule.doctor), utils.format_day(day), rows)
# ----------------------------------------------------------------- funciones utilitarias
# los campos ocultos doctorId / day de los formularios POST; (None, None) si no son válidos
def read_schedule_request() -> tuple[int | None, date | None]:
doctor_id = utils.positive_integer(request.form.get("doctorId"))
day = utils.valid_date(request.form.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]: url_for agrega al final de
# la URL los parámetros que no son variables de la ruta
def schedule_url(doctor_id: int, day: date, book: int | None = None) -> str:
if book is None:
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day))
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day), book=book)
def option(p: Person, selected: bool) -> OptionView:
return OptionView(p.id, utils.label(p), selected)
# -----------------------------------------------------------------------
# el mensaje informativo de un paciente que ya tiene una cita próxima
# (por qué no hay un botón "Book"), o None. Inútil si SU
# cita aparece en la agenda mostrada (en azul): es el caso justo
# después de que la acaba de reservar, cuando el mensaje estaría fuera de lugar.
# -----------------------------------------------------------------------
def patient_info(rights: Rights, view: ScheduleView | None) -> str | None:
if rights.patient is None or rights.patient_can_book:
return None
appointment_shown = view is not None and any(row.mine for row in view.rows)
return None if appointment_shown else "SCHEDULE.ALREADY_BOOKED_INFO"
|
11.16.2.1. La URL de la página
Toda la página se describe mediante su URL: [/schedule?doctorId=1&day=2026-09-26] muestra la agenda del médico n.º 1 para ese día; [&book=4] abre además la ventana de reserva de la franja n.º 4. Por lo tanto, la ventana de reserva de citas no la abre [JavaScript]: el servidor genera una página que contiene la ventana. Esto significa que se puede recargar la página, guardarla como marcador, usar el botón “Atrás” del navegador, y la aplicación funciona sin [JavaScript] (el único script de la aplicación se usa para las ventanas de confirmación, y también funciona sin él; véase el ejemplo 21).
11.16.2.2. GET /schedule
- líneas 65–68: lo que la acción sabe sobre el usuario para determinar la visualización: un “gestor” (ADMIN o DOCTOR) o un paciente, que puede o no hacer una reserva;
- líneas 83–91: el día: el día especificado en la URL si es válido; en caso contrario, hoy. Los parámetros se leen en bruto ([request.args.get]) para distinguir entre un parámetro ausente ([None]: se usa el valor predeterminado, sin error) y un parámetro no válido (se informa de un error). Solo se pueden reservar el día de hoy y los días siguientes;
- líneas 94–98: el médico: el de la URL; en caso contrario, para un médico conectado, el propio médico: un médico puede ver su agenda diaria directamente al iniciar sesión;
- línea 101: la lista desplegable de médicos, leída de la caché, con el médico seleccionado resaltado;
- líneas 104–110: la agenda, si hay un médico seleccionado y la fecha es válida. Un médico inexistente (un ID modificado manualmente en la URL) provoca un mensaje de error, no una página de error;
- líneas 114–125: la ventana de reserva, solo si la franja horaria solicitada existe y puede ser reservada por este usuario: un paciente que agregue [&book=2] a la URL para una franja horaria que ya está reservada no verá nada. [next(...)] busca la entrada correspondiente del calendario (ejemplo 21). La ventana muestra una lista de pacientes a un administrador; para cada paciente, muestra su propio nombre;
- Líneas 127–137: el modelo de la página. [back_url] es la URL del calendario sin la ventana de reserva; el botón "Cancelar" de la ventana lleva allí.
11.16.2.3. POST /schedule/book
- línea 152: todos los roles pueden hacer reservas. El decorador documenta la regla y la protege por si en el futuro apareciera un cuarto rol;
- líneas 154–157: los campos ocultos del formulario. Los campos no válidos solo pueden provenir de una solicitud construida manualmente: error 400;
- líneas 160–168: el paciente de la cita. Para un paciente, es siempre el propio paciente: el campo [clientId] se ignora. Confiar en un campo enviado por el navegador permitiría que un paciente reservara en nombre de otro. Si un administrador no ha seleccionado un paciente, la ventana de reserva se vuelve a abrir con un mensaje;
- líneas 170–189: validaciones (el paciente existe, la franja horaria existe y pertenece al médico del calendario), seguidas de la reserva. Las reglas de negocio las verifica la capa de lógica de negocio; una [BusinessException] se convierte en un mensaje flash de error. El mensaje “solo una cita próxima” se adapta cuando el paciente hace la reserva por sí mismo (“Usted ya tiene...” en lugar de “Este paciente ya tiene...”);
- línea 190: en todos los casos, regreso al calendario (patrón PRG).
11.16.2.4. POST /schedule/cancel
- Líneas 197–211: cancelación de una cita, reservada a los administradores (un paciente cancela su cita desde su cuenta). Una cita que ya ha sido cancelada (por otra persona o por un doble clic) muestra un mensaje, no un error.
- líneas 217–222: permisos del usuario. Para un paciente, es necesario ver sus próximas citas: una lista vacía es “incorrecta”, de ahí [not upcoming];
- líneas 228–248: el calendario del dominio, formateado para su visualización y filtrado según los permisos. Aquí es donde entra en juego la confidencialidad del paciente (línea 243): para un paciente, los nombres de otros pacientes no solo se ocultan a la vista; nunca se incluyen en el modelo. Por lo tanto, el HTML enviado al navegador no los contiene, ni siquiera ocultos (de lo contrario, un simple “Ver código fuente” los revelaría). El botón “Reservar” aparece solo cuando hay una franja horaria disponible, un día reservable y un usuario con derecho a hacer una reserva; el botón “Cancelar” aparece solo para un administrador;
- líneas 254–257: los campos ocultos [doctorId] y [day] de los formularios POST, validados;
- líneas 262–265: la URL del calendario. [url_for] agrega a la URL, como parámetros, los parámetros con nombre que no son variables de ruta (ejemplo 16);
- líneas 278–282: el mensaje informativo para un paciente que ya tiene una cita próxima: explica por qué faltan los botones “Reservar”. No se muestra si la propia cita del paciente aparece en el calendario (en azul), que es lo que ocurre inmediatamente después de reservar. [any(...)] devuelve [True] si se cumple cualquiera de las dos condiciones.
11.16.3. controllers/persons.py
La gestión de médicos y clientes, reservada al administrador, es idéntica: la misma lista, el mismo formulario, las mismas reglas. En lugar de escribir las mismas acciones dos veces, se escriben una sola vez, en una fábrica de blueprints.
| # =========================================================================
# controllers/persons.py
# -------------------------------------------------------------------------
# La gestión de los médicos y la de los clientes (reservada al ADMIN) son
# IDÉNTICAS: misma lista, mismo formulario, mismas reglas. En lugar de
# escribir dos veces las mismas acciones, se escriben una sola vez en una
# FÁBRICA DE BLUEPRINTS: la función create_blueprint construye un
# blueprint completo, a partir de una "configuración" que indica QUÉ llamar y
# QUÉ etiquetas mostrar. controllers/doctors.py y controllers/clients.py
# la llaman cada uno con la suya. Así obtenemos, para cada uno:
#
# GET /doctors lista
# GET /doctors/add formulario vacío
# POST /doctors/add creación
# GET /doctors/<id>/edit formulario prerrellenado
# POST /doctors/<id>/edit edición
# POST /doctors/<id>/delete eliminación
#
# (y las mismas URL bajo /clients). Las vistas también son comunes:
# templates/persons/list.html y templates/persons/form.html.
#
# SEGURIDAD: un before_request DEL BLUEPRINT exige el rol ADMIN. Se
# ejecuta antes de CADA acción del blueprint - incluidas las que se
# le agreguen después: la regla se escribe una vez para siempre.
# =========================================================================
from collections.abc import Callable
from dataclasses import dataclass
from flask import Blueprint, abort, redirect, render_template, url_for
from rdvmedecins.auth.security import require_roles
from rdvmedecins.entities import Person, Role
from rdvmedecins.forms.forms import PersonForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (PersonKeys, FormState, PersonFormModel,
PersonListModel, Message, PersonView,
PersonValues)
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
# -----------------------------------------------------------------------
# lo que cada tipo de persona debe proporcionar. Los últimos cinco campos
# son FUNCIONES: doctors.py y clients.py colocan en ellos lambdas que
# llaman a los métodos de ApplicationModel (get_all_doctors...).
# -----------------------------------------------------------------------
@dataclass(frozen=True)
class PersonsConfig:
name: str # "doctors" o "clients": el nombre del blueprint y el inicio de las URL
keys: PersonKeys
list: Callable[[], list[Person]] # () -> list
find: Callable[[int], Person | None] # id -> person
add: Callable[[PersonData], Person] # data -> created person
edit: Callable[[int, PersonData], Person] # (id, data) -> edited person
delete: Callable[[int], None] # id -> nothing
def create_blueprint(config: PersonsConfig) -> Blueprint:
bp = Blueprint(config.name, __name__, url_prefix=f"/{config.name}")
# la URL de una acción de ESTE blueprint: url("list_persons") -> "/doctors"
def url(action: str, **params) -> str:
return url_for(f"{config.name}.{action}", **params)
# todas las acciones del blueprint están reservadas al ADMIN
@bp.before_request
def admin_only():
require_roles(Role.ADMIN)
# -------------------------------------------------------------------
# GET /doctors (o /clients)
# -------------------------------------------------------------------
@bp.get("")
def list_persons():
persons = [PersonView(p.title, p.first_name, p.last_name, login(p),
url("edit_form", id=p.id),
url("delete", id=p.id))
for p in config.list()]
model = PersonListModel(config.keys.title, None, config.keys, url("add_form"),
persons)
return render_template("persons/list.html", model=model)
# -------------------------------------------------------------------
# GET /doctors/add
# -------------------------------------------------------------------
@bp.get("/add")
def add_form():
return show_form(None, PersonValues(), {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/add
# PersonForm() lee la entrada; validate() la verifica.
# -------------------------------------------------------------------
@bp.post("/add")
def add():
form = PersonForm()
if not form.validate():
return show_form(None, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.add(data(form))
except BusinessException as e:
return show_business_error(None, entered_values(form), e)
flash_success(config.keys.added, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# GET /doctors/<id>/edit
# <int:id>: el id debe estar formado por dígitos - /doctors/abc/edit no
# coincide con ninguna ruta (página 404)
# -------------------------------------------------------------------
@bp.get("/<int:id>/edit")
def edit_form(id: int):
person = config.find(id)
if person is None:
abort(404)
values = PersonValues(person.title, person.first_name, person.last_name, login(person),
person.version)
return show_form(id, values, {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/<id>/edit
# -------------------------------------------------------------------
@bp.post("/<int:id>/edit")
def edit(id: int):
form = PersonForm()
if not form.validate():
return show_form(id, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.edit(id, data(form))
except BusinessException as e:
return show_business_error(id, entered_values(form), e)
flash_success(config.keys.edited, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# POST /doctors/<id>/delete
# (la confirmación "Are you sure?" se solicita antes de que se envíe
# el formulario, ver static/js/app.js)
# -------------------------------------------------------------------
@bp.post("/<int:id>/delete")
def delete(id: int):
person = config.find(id)
try:
config.delete(id)
flash_success(config.keys.deleted, **params(person))
except BusinessException as e:
flash_error(e.key, **e.params)
return redirect(url("list_persons"))
# ----------------------------------------------------------------- funciones internas
# id None: formulario de creación; de lo contrario: formulario de edición.
# errors: campo -> clave del mensaje; error: la clave del mensaje al pie
# de la página; other_fields: campos adicionales que se resaltan en rojo
def show_form(id: int | None, values: PersonValues, errors: dict[str, str],
error: str | None, other_fields: list[str] | None):
creating = id is None
state: FormState = validation.state(errors, other_fields)
model = PersonFormModel(
page_title=config.keys.add if creating else config.keys.edit,
error=validation.page_message(errors, Message(error) if error else None),
values=values,
state=state,
creating=creating,
action=url("add") if creating else url("edit", id=id),
list_url=url("list_persons"))
return render_template("persons/form.html", model=model)
# una regla de negocio ha rechazado la escritura: el formulario se muestra de nuevo,
# con la entrada del usuario y el mensaje de la capa de negocio
def show_business_error(id: int | None, values: PersonValues, e: BusinessException):
if e.key in ("ERRORS.DOCTOR_NOT_FOUND", "ERRORS.PATIENT_NOT_FOUND"):
# eliminado mientras tanto por otro ADMIN: de vuelta a la lista
flash_error(e.key)
return redirect(url("list_persons"))
# el mensaje va al pie de la página; los campos afectados, si los hay, se
# resaltan en rojo para que el usuario vea de inmediato qué corregir
return show_form(id, values, {}, e.key, validation.BUSINESS_ERROR_FIELDS.get(e.key))
return bp
# lo que el usuario ha escrito (contraseña excluida: nunca se devuelve
# al navegador). form.<field>.data: el valor, después de los filtros
def entered_values(form: PersonForm) -> PersonValues:
return PersonValues(form.title.data or "", form.first_name.data or "", form.last_name.data or "",
form.login.data or "", form.version.data)
# el formulario validado -> los datos esperados por la capa de negocio
def data(form: PersonForm) -> PersonData:
return PersonData(form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, form.version.data)
# {name} y {login} de los mensajes "added / edited / deleted"
def params(person: Person | None) -> dict[str, str]:
if person is None:
return {"name": "", "login": ""}
return {"name": f"{person.first_name} {person.last_name}", "login": login(person)}
def login(person: Person) -> str:
return person.user.login if person.user else ""
|
- líneas 49–56: lo que cada tipo de entidad debe proporcionar: el nombre del blueprint (que también es el comienzo de la URL), las claves de traducción y cinco funciones: listar, buscar, agregar, editar y eliminar. Es el mismo procedimiento que el de los descriptores de la capa de negocio;
- Líneas 59–60: la fábrica crea un blueprint, cuyo nombre y prefijo de URL provienen de la configuración. Las acciones son funciones internas de [create_blueprint]: tienen acceso a la variable [config] de la fábrica. Cada llamada a [create_blueprint] crea un nuevo blueprint, con sus propias acciones;
- líneas 63–64: la URL de una acción de este blueprint: [url("list_persons")] devuelve [/doctors] para el blueprint de los médicos y [/clients] para el de los clientes;
- líneas 67–69: un [before_request] de blueprint: se ejecuta antes de cada acción del blueprint (y solo de este), después de las de la aplicación. Así, todas las acciones quedan reservadas al administrador, incluidas las que se agreguen más adelante: la regla se escribe una vez y se aplica a todas;
- líneas 74–82: la lista. [@bp.get("")]: la ruta es el propio prefijo del blueprint ([/doctors]);
- líneas 95–106: la operación de agregar: validación del formulario (errores de entrada, mostrados debajo de los campos), llamada a la capa de negocio (errores de negocio, mostrados en la parte inferior de la página), seguida de un mensaje flash y una redirección a la lista. Los mensajes flash reciben parámetros: el nombre de la persona y su nombre de usuario;
- líneas 113–120: el formulario de edición, rellenado previamente con la versión del registro (bloqueo optimista). Una persona inexistente da como resultado una página 404;
- líneas 125–136: la actualización, siguiendo el modelo de la operación de agregar;
- líneas 143–151: la operación de eliminar, confirmada previamente mediante la ventana de confirmación (ejemplo 21). Un rechazo por parte de la capa de negocio (un médico que tiene citas) produce un mensaje flash de error;
- líneas 158–170: el formulario de agregar ([id] es igual a [None]) o de editar, junto con su estado (valores, errores, campos resaltados en rojo);
- líneas 174–181: un error de negocio: una persona que ha sido eliminada entretanto por otro administrador se devuelve a la lista; en los demás casos se vuelve a mostrar el formulario, con los campos pertinentes resaltados en rojo;
- líneas 188–190: los valores que se volverán a mostrar: lo que el usuario introdujo, nunca la contraseña;
- líneas 194–196: el formulario validado, convertido en datos para la capa de negocio;
- líneas 200–203: los parámetros de los mensajes “agregado/modificado/eliminado”.
11.16.4. controllers/doctors.py y controllers/clients.py
| # =========================================================================
# controllers/doctors.py
# -------------------------------------------------------------------------
# Gestión de los médicos (solo rol ADMIN). Todas las acciones las
# construye controllers/persons.py: aquí solo queda indicar QUÉ
# llamar y QUÉ etiquetas mostrar.
#
# Las funciones de la configuración son LAMBDAS (funciones sin
# nombre, escritas en el momento): application() solo se llama cuando
# la acción se ejecuta, durante una solicitud - ApplicationModel aún no existe
# cuando se importa este módulo.
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
doctors = create_blueprint(PersonsConfig(
name="doctors",
keys=PersonKeys(
title="DOCTORS.TITLE",
add="DOCTORS.ADD",
edit="DOCTORS.EDIT",
empty="DOCTORS.EMPTY",
confirm_delete="DOCTORS.DELETE_CONFIRM",
added="DOCTORS.ADDED",
edited="DOCTORS.UPDATED",
deleted="DOCTORS.DELETED"),
list=lambda: application().get_all_doctors(),
find=lambda id: application().get_doctor_by_id(id),
add=lambda data: application().add_doctor(data),
edit=lambda id, data: application().edit_doctor(id, data),
delete=lambda id: application().delete_doctor(id)))
|
El blueprint de los médicos, generado por [create_blueprint] junto con su configuración. Las funciones de configuración son funciones anónimas ([lambda]), que invocan a [ApplicationModel]. ¿Por qué no escribir [list=application().get_all_doctors] directamente? Porque este módulo se ejecuta al importarse, al iniciar, antes de que se cree la aplicación: [application()], que requiere [current_app], fallaría. La función anónima difiere la llamada hasta que se ejecuta la acción, durante una solicitud.
| # =========================================================================
# controllers/clients.py
# -------------------------------------------------------------------------
# Gestión de los clientes (los PACIENTES del consultorio), solo rol ADMIN.
# Mismo principio que controllers/doctors.py (ver sus comentarios).
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
clients = create_blueprint(PersonsConfig(
name="clients",
keys=PersonKeys(
title="CLIENTS.TITLE",
add="CLIENTS.ADD",
edit="CLIENTS.EDIT",
empty="CLIENTS.EMPTY",
confirm_delete="CLIENTS.DELETE_CONFIRM",
added="CLIENTS.ADDED",
edited="CLIENTS.UPDATED",
deleted="CLIENTS.DELETED"),
list=lambda: application().get_all_clients(),
find=lambda id: application().get_client_by_id(id),
add=lambda data: application().add_client(data),
edit=lambda id, data: application().edit_client(id, data),
delete=lambda id: application().delete_client(id)))
|
El blueprint de los clientes, que sigue el mismo patrón.
11.16.5. controllers/registration.py
| # =========================================================================
# controllers/registration.py
# -------------------------------------------------------------------------
# "Create a patient account": 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 "Create a patient account" de la
# página de autenticación: verifica el CAPTCHA de
# ESA 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 inicio de sesión
#
# El flujo está protegido contra robots por UN solo CAPTCHA, el de la
# página de autenticación:
# 1. el botón "Create a patient account" envía el formulario de inicio de sesión
# a /register/access; si el CAPTCHA se escribe correctamente, el servidor
# emite un pase (ver auth/registration_pass.py);
# 2. sin un pase válido, /register devuelve a la
# página de autenticación - escribir la URL directamente no sirve de nada;
# 3. el pase se consume al crear la cuenta: un CAPTCHA resuelto
# permite crear UNA cuenta;
# 4. además, el número de cuentas creadas por hora y por dirección IP está
# limitado (ver auth/limiter.py).
#
# La cuenta creada es exactamente la que el ADMIN crearía desde la
# página "Patients" (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 flask import Blueprint, current_app, redirect, render_template, request, url_for
from rdvmedecins.auth import registration_pass
from rdvmedecins.auth.security import public
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.forms.forms import RegistrationForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import RegistrationModel, Message, PersonValues
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, captchas, limiter, passes
registration = Blueprint("registration", __name__, url_prefix="/register")
# -----------------------------------------------------------------------
# POST /register/access campos: captchaId, captcha (los de la
# página de autenticación; login y contraseña, también enviados, se ignoran)
# -----------------------------------------------------------------------
@registration.post("/access")
@public
def access():
ip = ip_address()
# demasiadas cuentas creadas recientemente desde esta dirección: no hace falta ir más lejos
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
flash_error("ERRORS.TOO_MANY_ACCOUNTS", minutes=str(minutes))
return redirect(url_for("auth.show_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 inicio de sesión)
if not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, "")
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# CAPTCHA correcto: se emite el pase y se abre el formulario
response = redirect(url_for("registration.form"))
registration_pass.set_cookie(response, passes().issue(), current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# GET /register
# -----------------------------------------------------------------------
@registration.get("")
@public
def form():
if not passes().is_valid(request.cookies.get(registration_pass.COOKIE)):
return back_to_login()
return show(PersonValues(), {}, None, None)
# -----------------------------------------------------------------------
# POST /register
# -----------------------------------------------------------------------
@registration.post("")
@public
def create():
pass_id = request.cookies.get(registration_pass.COOKIE)
if not passes().is_valid(pass_id):
return back_to_login()
ip = ip_address()
form = RegistrationForm()
form.validate()
values = PersonValues(form.title.data or "Mr", form.first_name.data or "",
form.last_name.data or "", form.login.data or "", None)
# 1. ¿demasiadas cuentas creadas recientemente desde esta dirección?
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
return show(values, {}, Message("ERRORS.TOO_MANY_ACCOUNTS", {"minutes": str(minutes)}),
None)
# 2. todos los errores de entrada a la vez (campos + confirmación):
# el usuario los corrige todos de una vez
errors = validation.errors_of(form)
if "password" not in errors and "confirmation" not in errors \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# 3. la creación (cliente + cuenta USER, en una transacción)
try:
application().add_client(PersonData(form.title.data, form.last_name.data,
form.first_name.data, form.login.data,
form.password.data))
except BusinessException as e:
# login o nombre + apellido ya en uso: el pase sigue siendo válido
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# 4. el pase ha sido usado: no permitirá crear una 2.ª cuenta
passes().consume(pass_id)
limiter().registration_success(ip)
# 5. de vuelta a la página de inicio de sesión, con el login prerrellenado
flash_success("REGISTRATION.DONE", login=form.login.data)
response = redirect(url_for("auth.show_login", login=form.login.data))
registration_pass.clear_cookie(response)
return response
# ----------------------------------------------------------------- funciones internas
# ningún pase válido: de vuelta a la página de autenticación
def back_to_login():
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# el formulario; nunca se devuelve una contraseña al navegador
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = RegistrationModel("REGISTRATION.TITLE", validation.page_message(errors, error),
values, validation.state(errors, other_fields))
return render_template("registration.html", model=model)
|
- Líneas 51–72: 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 acción (mediante el atributo [formaction], ejemplo 20). Comprueba el límite de creaciones de cuentas y luego el CAPTCHA de la página de inicio de sesión; si es correcto, emite un token ([auth/registration_pass.py]) y redirige al formulario de registro. Un fallo se cuenta como un intento fallido de inicio de sesión (con un nombre de usuario vacío);
- líneas 78–83: el formulario, solo con un pase válido: escribir directamente la dirección [/register] redirige a la página de inicio de sesión;
- líneas 89–133: creación de la cuenta: - el pase, de nuevo; - se invoca [form.validate()] , pero se ignora su resultado: queremos todos los errores de entrada a la vez, incluida cualquier discrepancia entre la contraseña y su confirmación, que luego verifica la acción (siempre que ambos campos sean válidos por lo demás). El usuario los corrige todos a la vez; - el cliente y su cuenta se crean con el mismo método de la lógica de negocio que para el administrador; - se consume el pase y el limitador contabiliza la creación; - regreso a la página de inicio de sesión, con un mensaje y el nombre de usuario rellenado previamente (parámetro [login] de la URL). Se elimina la cookie del pase.
11.16.6. controllers/area.py
Las páginas personales del paciente.
| # =========================================================================
# controllers/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: [Manage my account],
# [View a schedule] y su próxima cita
# POST /my-area/cancel cancela SU cita
# GET /my-account formulario para editar su cuenta
# POST /my-account edición
# POST /my-account/delete eliminación de la cuenta (y de sus citas)
#
# Regla de oro de este controlador: el paciente afectado es SIEMPRE el del
# token (utils.connected_patient), nunca un identificador enviado por el
# navegador. Por lo tanto, un paciente no puede ver, editar ni cancelar lo que
# pertenece a otro paciente, ni siquiera fabricando él mismo sus solicitudes.
#
# Toda edición o eliminación de la cuenta requiere la contraseña
# ACTUAL: alguien que encontrara una sesión abierta no podría
# cambiar la contraseña ni eliminar la cuenta. Los errores de contraseña
# actual incorrecta se cuentan como fallos de inicio de sesión (mismo límite).
# =========================================================================
from flask import Blueprint, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import require_roles
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.entities import Client, Role
from rdvmedecins.forms.forms import MyAccountForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (AreaModel, Message, MyAccountModel, AppointmentView,
PersonValues)
from rdvmedecins.web import utils, validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, auth_service, limiter
area = Blueprint("area", __name__)
# todas las acciones de este blueprint están reservadas al rol USER
@area.before_request
def patient_only():
require_roles(Role.USER)
# -----------------------------------------------------------------------
# GET /my-area
# -----------------------------------------------------------------------
@area.get("/my-area")
def patient_area():
patient = utils.connected_patient(application())
appointments = [AppointmentView(
a.id,
utils.format_day(a.day),
utils.time(a.slot),
utils.label(a.slot.doctor),
# enlace a la agenda del médico en ese día: el paciente ve allí su nombre
url_for("schedule.show", doctorId=a.slot.doctor_id, day=utils.iso(a.day)))
for a in application().get_client_upcoming_appointments(patient.id)]
model = AreaModel("AREA.TITLE", None, utils.label(patient), appointments)
return render_template("area.html", model=model)
# -----------------------------------------------------------------------
# POST /my-area/cancel campo: appointmentId
# -----------------------------------------------------------------------
@area.post("/my-area/cancel")
def cancel_appointment():
patient = utils.connected_patient(application())
appointment_id = utils.positive_integer(request.form.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:
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(url_for("area.patient_area"))
# -----------------------------------------------------------------------
# GET /my-account
# -----------------------------------------------------------------------
@area.get("/my-account")
def account_form():
patient = utils.connected_patient(application())
values = PersonValues(patient.title, patient.first_name, patient.last_name, patient.user.login,
patient.version)
return show(values, {}, None, None)
# -----------------------------------------------------------------------
# POST /my-account
# -----------------------------------------------------------------------
@area.post("/my-account")
def edit_account():
patient = utils.connected_patient(application())
form = MyAccountForm()
form.validate()
values = PersonValues(form.title.data or patient.title, form.first_name.data or "",
form.last_name.data or "", form.login.data or "", form.version.data)
errors = validation.errors_of(form)
if "password" not in errors and form.password.data is not None \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# la contraseña actual
password_error = check_current_password(patient, form.current_password.data)
if password_error is not None:
# contraseña incorrecta: el mensaje también va BAJO el campo
field_errors = ({"current_password": password_error.key}
if password_error.key == "ERRORS.WRONG_CURRENT_PASSWORD" else {})
return show(values, field_errors, password_error, None)
try:
client = application().edit_client(patient.id, PersonData(
form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, # None = sin cambios
form.version.data))
except BusinessException as e:
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# 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 antiguo
flash_success("MY_ACCOUNT.UPDATED")
response = redirect(url_for("area.patient_area"))
auth_service().set_token(response, client.user)
return response
# -----------------------------------------------------------------------
# POST /my-account/delete campo: delete_password
# La cuenta, el cliente y TODAS sus citas desaparecen juntos,
# y luego se cierra la sesión del paciente.
# -----------------------------------------------------------------------
@area.post("/my-account/delete")
def delete_account():
patient = utils.connected_patient(application())
password_error = check_current_password(
patient, request.form.get("delete_password"))
if password_error is not None:
flash_error(password_error.key, **password_error.params)
return redirect(url_for("area.account_form"))
application().delete_client(patient.id)
flash_success("MY_ACCOUNT.DELETED")
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# ----------------------------------------------------------------- funciones internas
# None si la contraseña actual es correcta; de lo contrario, el mensaje de error
def check_current_password(patient: Client, password: str | None) -> Message | None:
ip = ip_address()
login = patient.user.login
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)})
ok = bool(password) and auth_service().validate_user(login, password) is not None
if not ok:
limiter().login_failure(ip, login)
return Message("ERRORS.WRONG_CURRENT_PASSWORD")
return None
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = MyAccountModel("MY_ACCOUNT.TITLE", validation.page_message(errors, error), values,
validation.state(errors, other_fields))
return render_template("account.html", model=model)
|
- líneas 43–45: todas las acciones del blueprint están reservadas al rol USER;
- líneas 51–63: el panel del paciente: sus próximas citas, formateadas, cada una con un enlace a la agenda del médico para ese día. El paciente es siempre el asociado al token ([utils.connected_patient]), nunca un identificador enviado por el navegador: un paciente no puede ver, modificar ni cancelar la información de otro paciente;
- líneas 69–81: cancelación de la cita del paciente. Una cita inexistente y la cita de otro paciente reciben la misma respuesta: no se revela ninguna información sobre las citas de otros pacientes (de lo contrario, un paciente podría descubrir qué números de cita existen);
- líneas 87–92: el formulario de la cuenta del usuario, rellenado previamente;
- líneas 98–133: la edición: validación de los campos y de la confirmación, verificación de la contraseña actual y luego una llamada a la capa de negocio. El nombre de usuario y el nombre mostrado están en el token: la acción emite uno nuevo; de lo contrario, la barra de navegación conservaría el nombre anterior hasta el siguiente inicio de sesión;
- líneas 141–153: eliminación de la cuenta, que también está protegida por la contraseña actual. La cuenta, el cliente y todas sus citas se eliminan juntos; se cierra la sesión del paciente;
- líneas 159–169: la contraseña actual protege la cuenta de cualquiera que encuentre una sesión que se haya dejado abierta. Los errores se cuentan como fallos de inicio de sesión, con el mismo límite: no pueden usarse para adivinar la contraseña.
11.17. Las vistas
La carpeta [templates] contiene las vistas [Jinja2] de la aplicación: una plantilla, siete fragmentos y ocho páginas. Todas siguen la misma regla: sin lógica en las vistas. Las acciones les pasan modelos ya preparados ([models/view_models.py]); las vistas simplemente colocan los datos en el HTML y traducen el texto mediante la función [t]. No contienen ningún texto escrito directamente en el código: todo pasa por los diccionarios.
11.17.1. La plantilla y los fragmentos
11.17.1.1. templates/layout.html
| <!doctype html>
{# =========================================================================
templates/layout.html
-------------------------------------------------------------------------
El layout COMÚN a todas las páginas (véase el ejemplo 15): cada página
(schedule.html, login.html...) lo EXTIENDE ({% extends %}) y llena su bloque
[content].
Jinja2 ESCAPA todo lo que muestra con {{ ... }} (los caracteres
< > & " ' se convierten en < >...): protección contra la inyección de HTML
mediante un nombre escrito, por ejemplo. Para insertar HTML tal cual, hay que
solicitarlo explícitamente (filtro safe, véase 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 (fragmento errors.html).
El layout comparte las variables de la página: [model] (el modelo de vista
pasado por la acción, véase models/view_models.py), donde lee la clave del
título de la página; [language], [user], [path], [t], agregadas a
todas las vistas por web/common_model.py.
========================================================================= #}
<html lang="{{ language }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# t(key): la traducción de una clave; aquí, la clave es una VARIABLE (model.page_title) #}
<title>{{ t(model.page_title) }} - {{ t("APP.TITLE") }}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='lib/bootstrap/css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
{# los mensajes flash dejados por la solicitud anterior: se leen UNA SOLA VEZ
(get_flashed_messages los olvida de inmediato), luego se separan: los éxitos
arriba, los errores abajo #}
{% set flashes = get_flashed_messages(with_categories=true) %}
<div class="container py-4">
{% include "fragments/navbar.html" %}
{% include "fragments/flash.html" %}
<main>
{% block content %}{% endblock %}
</main>
{% include "fragments/errors.html" %}
</div>
{# el diálogo "Are you sure?", oculto hasta que se necesita #}
{% include "fragments/confirmation.html" %}
<script src="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
|
- línea 22: el idioma de la página, proporcionado por el procesador de contexto;
- línea 27: el título de la página. La clave del título es una variable ([model.page_title]): cada modelo de página proporciona una (el procedimiento del ejemplo 22, que usa el modelo de la vista en lugar de una variable [{% set %}]);
- línea 28: [Bootstrap] forma parte de la aplicación, ubicado en su carpeta [static];
- Línea 35: la plantilla lee los mensajes flash una sola vez ; [get_flashed_messages] los olvida de inmediato, y una segunda llamada devolvería una lista vacía. Con [with_categories=true], la función devuelve tuplas (categoría, mensaje). La variable [flashes] la leen luego los dos fragmentos que los muestran: los mensajes de éxito en la parte superior y los de error en la inferior. Una variable definida con [{% set %}] es visible para los fragmentos incluidos mediante [{% include %}];
- líneas 37–42: la barra de navegación, los mensajes de éxito, el contenido de la página y el área de errores;
- líneas 45–46: la ventana de confirmación y el script que la gestiona (ejemplo 21).
11.17.1.2. templates/fragments/navbar.html
| {# =========================================================================
templates/fragments/navbar.html - la barra de navegación.
Título, FR/EN, rol, nombre, cierre de sesión - y un menú cuyas entradas
dependen del rol: "Doctors" y "Patients" solo aparecen para
el ADMIN. Es solo una comodidad de presentación: la protección real son
las verificaciones de rol de las acciones (un USER que escribe /doctors a mano
obtiene una página 403). Un paciente (USER) tiene además su menú "My area".
El menú de la página actual aparece resaltado (clase "active"):
[path] es la URL solicitada (véase web/common_model.py). Una macro escribe
una sola vez el HTML de una entrada de menú; su parámetro opcional [prefix]
(href por defecto), es el inicio de las rutas para las que la entrada está activa.
========================================================================= #}
{% macro entry(href, key, prefix=none) %}
<li class="nav-item">
<a class="nav-link{{ ' active' if path.startswith(prefix or href) }}" href="{{ href }}">{{ t(key) }}</a>
</li>
{% endmacro %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ t("APP.TITLE") }}</span>
{% if user %}
<ul class="navbar-nav me-auto">
{% if user.is_patient %}
{# activo para /my-area Y /my-account #}
{{ entry("/my-area", "APP.MENU_MY_AREA", "/my-") }}
{% endif %}
{{ entry("/schedule", "APP.MENU_SCHEDULE") }}
{% if user.is_admin %}
{{ entry("/doctors", "APP.MENU_DOCTORS") }}
{{ entry("/clients", "APP.MENU_PATIENTS") }}
{% endif %}
</ul>
{% else %}
<div class="me-auto"></div>
{% endif %}
<div class="d-flex align-items-center gap-2">
{# FR / EN: enlaces simples (GET /language/fr), el idioma activo resaltado #}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
{% for code in ["fr", "en"] %}
<a class="btn {{ 'btn-light' if language == code else 'btn-outline-light' }}" href="/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>
{# el cierre de sesión es un POST: un formulario reducido a su botón (y al token anti-CSRF) #}
<form method="post" action="/logout" class="m-0">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-light">{{ t("APP.LOGOUT") }}</button>
</form>
{% endif %}
</div>
</nav>
|
- líneas 15–19: un elemento del menú, resaltado (clase [active]) si la ruta de la página actual comienza con su prefijo. El parámetro [prefix] es opcional ([none] para [Jinja2], igual que [None] para [Python]); en caso contrario, es la dirección de la entrada ([prefix or href]). La entrada “Mi área” tiene el prefijo [/my-]: está activa tanto para [/my-area] como para [/my-account];
- líneas 23–37: el menú depende del rol: “Mi área” para un paciente, “Médicos” y “Pacientes” para el administrador. Esto es solo una comodidad de visualización; la seguridad real proviene de los controles basados en roles en las acciones. Un paciente que escriba manualmente [/doctors] recibirá una página de error 403;
- líneas 42–44: los botones FR y EN son simplemente enlaces a [/language/fr] y [/language/en];
- líneas 48–54: rol, nombre de usuario y cierre de sesión: un formulario POST reducido a su botón, con el token anti-CSRF.
11.17.1.3. templates/fragments/flash.html
| {# =========================================================================
templates/fragments/flash.html - los mensajes de ÉXITO dejados por
la acción anterior (cita guardada, médico agregado...),
mostrados una sola vez, en la parte superior de la página (véase web/flash.py).
Un mensaje flash de ERROR se muestra en la parte inferior de la página, mediante
fragments/errors.html.
[flashes]: la lista de los pares (category, message), leída por el layout.
t(message.key, message.params): el mensaje cuya clave es
message.key, con como parámetro el diccionario de los valores de {name},
{login}... (véase web/translator.py).
========================================================================= #}
{% for category, message in flashes if category == "success" %}
<div class="alert alert-success" role="status">{{ t(message.key, message.params) }}</div>
{% endfor %}
|
- línea 13: un bucle [for] de [Jinja2] puede filtrar sus elementos: [for ... in ... if condition] itera solo sobre los elementos que cumplen la condición. Cada elemento es un par, con ambas partes almacenadas en dos variables;
- línea 14: el mensaje es un diccionario (véase [web/flash.py]): su clave y sus parámetros. La notación de punto en [Jinja2] también lee las claves de un diccionario (ejemplo 13).
11.17.1.4. templates/fragments/errors.html
| {# =========================================================================
templates/fragments/errors.html - la zona de errores, en la parte INFERIOR de cada
página, sobre un fondo rosa claro (clase .error-zone, véase static/css/styles.css).
Agrupa las dos posibles fuentes de error:
- model.error: el error de la página mostrada (formulario rechazado, login
o nombre + apellido ya usados, fecha inválida, contraseña incorrecta...);
- los mensajes flash de error, dejados por la acción anterior antes de una
redirección (franja ya reservada, eliminación rechazada...).
Un bucle for puede filtrar sus elementos: "for ... in ... if condition".
role="alert": un lector de pantalla anuncia el mensaje en cuanto se muestra la página,
aunque esté al final.
========================================================================= #}
{% set flash_errors = flashes | selectattr(0, "equalto", "danger") | list %}
{% if model.error or flash_errors %}
<div class="error-zone" role="alert">
{% if model.error %}
<div>{{ t(model.error.key, model.error.params) }}</div>
{% endif %}
{% for category, message in flash_errors %}
<div>{{ t(message.key, message.params) }}</div>
{% endfor %}
</div>
{% endif %}
|
- línea 15: mensajes flash de error, extraídos mediante dos filtros: [selectattr(0, "equalto", "danger")] conserva solo aquellos elementos cuyo atributo [0] (el primer elemento del par, la categoría) es igual a ["danger"]; [list] convierte el resultado en una lista (los filtros de este tipo devuelven un iterador que solo se puede recorrer una vez y no permite comprobar si está vacío);
- Líneas 16–25: el área de errores combina las dos fuentes de errores: los errores de la página mostrada (un formulario rechazado, una fecha no válida) y los errores generados por la acción anterior antes de una redirección (una franja horaria ya ocupada, una eliminación rechazada). El área existe solo si hay al menos un error.
11.17.1.5. templates/fragments/confirmation.html
| {# =========================================================================
templates/fragments/confirmation.html - el diálogo modal "Are you sure?".
Reemplaza el cuadro window.confirm() del navegador, que no se puede
estilizar ni traducir (sus botones se quedan en el idioma del
navegador, no en el de la página).
UN SOLO diálogo para toda la página, oculto (d-none) al inicio. Sus
etiquetas se traducen aquí, por el servidor, como el resto de la página;
el pequeño script static/js/app.js se limita a mostrarlo, a poner en él
el mensaje propio del formulario (atributo data-confirmation) y a enviar
el formulario si el usuario confirma.
Mismas clases de Bootstrap que el diálogo de reserva (fragments/booking.html).
========================================================================= #}
<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">{{ t("CONFIRMATION.TITLE") }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ t('BOOKING_DIALOG.CLOSE_ARIA') }}"></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": la pregunta es a veces
"Cancel this appointment?", y un botón "Cancel" sería ambiguo allí #}
<button type="button" class="btn btn-secondary" data-action="no">{{ t("CONFIRMATION.NO") }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ t("CONFIRMATION.YES") }}</button>
</div>
</div>
</div>
</div>
</div>
|
La ventana de confirmación del ejemplo 21, con etiquetas traducidas por el servidor (el cuadro [window.confirm()] del navegador muestra sus botones en el idioma del navegador, no en el de la página), un botón de cierre y atributos de accesibilidad: [aria-labelledby] y [aria-describedby] hacen referencia al título y al mensaje de la ventana, que los lectores de pantalla anuncian cuando esta se abre. Se prefiere el botón “No, volver” a “Cancelar”: la pregunta a veces es “¿Cancelar esta cita?”, y un botón “Cancelar” sería ambiguo en ese contexto.
11.17.1.6. templates/fragments/captcha.html
| {# =========================================================================
templates/fragments/captcha.html - el captcha de la página de autenticación
(véase auth/captcha.py). Protege tanto el inicio de sesión como el acceso a
la creación de cuenta (botón "Create a patient account").
Una macro, cuyo parámetro es un objeto Captcha (id, svg).
El filtro safe: la imagen SVG se inserta TAL CUAL en la página, sin
escapar. Es inofensivo aquí porque este SVG lo construye el propio
servidor y no contiene nada que provenga del usuario - NUNCA
se haría esto con una entrada.
El campo oculto captchaId indica al servidor CUÁL captcha verificar; la respuesta
correcta nunca se envía al navegador.
"Another image" simplemente recarga la página ([path] = la URL actual).
Una macro no ve las variables de la página que la llama ("with
context": sí las ve, al importar, en login.html): aquí, t y path.
========================================================================= #}
{% macro captcha(captcha) %}
<div class="mb-3">
<label class="form-label" for="captcha">{{ t("CAPTCHA.LABEL") }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ t('CAPTCHA.IMAGE_ALT') }}">{{ captcha.svg | safe }}</div>
<a class="small" href="{{ path }}">{{ t("CAPTCHA.NEW_IMAGE") }}</a>
</div>
<input type="hidden" name="captchaId" 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">{{ t("CAPTCHA.HELP") }}</div>
</div>
{% endmacro %}
|
- línea 18: una macro que recibe un objeto [Captcha];
- línea 22: la imagen SVG, insertada tal cual (ejemplo 27). El atributo [role="img"] y su [aria-label] describen la imagen a los lectores de pantalla;
- línea 23: el enlace “Otra imagen” simplemente recarga la página: cada vista genera un nuevo CAPTCHA;
- Líneas 25–27: el ID del CAPTCHA y el campo de entrada. [autocapitalize="off"] y [spellcheck="false"] impiden que los teléfonos modifiquen lo escrito (letra inicial mayúscula, corrector ortográfico).
De forma predeterminada, una macro importada no puede acceder a las variables de la página que la importa: la función [t] y la variable [path], proporcionadas por el procesador de contexto, le serían desconocidas. Por eso [login.html] la importa con la referencia [with context].
11.17.1.7. templates/fragments/person_fields.html
| {# =========================================================================
templates/fragments/person_fields.html - 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".
El fragmento, insertado con {% include %}, lee la variable [model] de la
página que lo inserta (un FormView, véase models/view_models.py):
valores, mensaje bajo cada campo, campos delineados en rojo.
selected: un atributo booleano, escrito si la opción está elegida, omitido en caso contrario.
state.invalid_class(field): "is-invalid" (contorno rojo de Bootstrap)
para un campo rechazado, "" en caso contrario.
========================================================================= #}
{% set state = model.state %}
<div class="mb-3">
<label class="form-label" for="title">{{ t("PERSONS.TITLE_LABEL") }}</label>
<select id="title" name="title" class="form-select {{ state.invalid_class('title') }}">
{% for title in model.titles %}
<option value="{{ title.value }}"{{ " selected" if title.selected }}>{{ title.value }}</option>
{% endfor %}
</select>
{% if state.error_of("title") %}
<div class="invalid-feedback">{{ t(state.error_of("title")) }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="first_name">{{ t("PERSONS.FIRSTNAME_LABEL") }}</label>
<input id="first_name" name="first_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('first_name') }}" value="{{ model.values.first_name }}">
{% if state.error_of("first_name") %}
<div class="invalid-feedback">{{ t(state.error_of("first_name")) }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="last_name">{{ t("PERSONS.LASTNAME_LABEL") }}</label>
<input id="last_name" name="last_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('last_name') }}" value="{{ model.values.last_name }}">
{% if state.error_of("last_name") %}
<div class="invalid-feedback">{{ t(state.error_of("last_name")) }}</div>
{% endif %}
</div>
</div>
|
Los campos de identidad (tratamiento, nombre, apellido), comunes a los tres formularios de la aplicación. El fragmento, insertado mediante [{% include %}], lee la variable [model] de la página que lo inserta: un modelo que hereda de [FormView].
- Líneas 16–20: la lista de tratamientos, calculada por la propiedad [titles] del modelo, con el tratamiento seleccionado resaltado;
- líneas 29–30: el campo de entrada del nombre, con el valor que se volverá a mostrar, y la clase [is-invalid] si el campo es rechazado ([state.invalid_class('first_name')]);
- líneas 31–33: el mensaje debajo del campo, traducido.
Los atributos [maxlength] y [required] son controles del navegador. Los formularios de la aplicación incluyen el atributo [novalidate] (ejemplo 19): estas comprobaciones no se realizan antes del envío; la validación la gestiona el servidor. [maxlength], en cambio, siempre impide que los usuarios introduzcan más caracteres de los que cabe en una columna.
11.17.1.8. templates/fragments/booking.html
| {# =========================================================================
templates/fragments/booking.html - el diálogo de reserva de la
agenda.
Las clases REALES de Bootstrap de un diálogo modal (.modal,
.modal-backdrop...), hechas visibles "en duro" (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 la variable [model] de la página que lo inserta
(un ScheduleModel).
========================================================================= #}
{% set booking = model.booking %}
<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="/schedule/book" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ t("BOOKING_DIALOG.TITLE") }}</h5>
<a class="btn-close" href="{{ model.back_url }}" aria-label="{{ t('BOOKING_DIALOG.CLOSE_ARIA') }}"></a>
</div>
<div class="modal-body">
<p>{{ t("BOOKING_DIALOG.SLOT", time=booking.time) }}</p>
{# lo que el servidor debe saber además del paciente elegido #}
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.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 de todos modos un posible clientId) #}
{% if booking.patient %}
<p class="mb-0">
<span>{{ t("BOOKING_DIALOG.PATIENT_LABEL") }}</span>:
<strong>{{ booking.patient }}</strong>
</p>
{% else %}
<label class="form-label" for="clientId">{{ t("BOOKING_DIALOG.PATIENT_LABEL") }}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{ t("BOOKING_DIALOG.CHOOSE_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="{{ model.back_url }}">{{ t("BOOKING_DIALOG.CANCEL") }}</a>
<button type="submit" class="btn btn-primary">{{ t("BOOKING_DIALOG.CONFIRM") }}</button>
</div>
</form>
</div>
</div>
|
La ventana de reserva. Utiliza las clases reales de una ventana modal de [Bootstrap] ([modal], [modal-backdrop]...), hechas visibles de forma "fija" en el código ([show d-block]) en lugar de mediante el [JavaScript] de [Bootstrap]: el servidor decide si se muestra (el parámetro [book] de la URL), y cerrarla equivale a seguir un enlace a la misma página sin ese parámetro ([model.back_url]).
- Líneas 29–31: campos ocultos: información que el servidor necesita conocer, además del paciente seleccionado;
- líneas 35–48: un paciente hace una reserva para sí mismo: se muestra su nombre, sin lista para elegir (y el servidor ignoraría de todos modos un campo [clientId]). Para un administrador, se muestra la lista de pacientes, cuya primera opción, con un valor vacío, invita a seleccionar uno.
11.17.2. Las páginas
11.17.2.1. templates/login.html
| {# =========================================================================
templates/login.html - el formulario de inicio de sesión (véase controllers/auth.py).
Un <form> HTML ordinario: 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 escrito, un
NUEVO captcha y el error, mostrado en la parte inferior de la página por el layout.
========================================================================= #}
{% extends "layout.html" %}
{# with context: la macro ve las variables de esta página (t, path) #}
{% from "fragments/captcha.html" import captcha with context %}
{% block content %}
{% set login_typed = model.login != "" %}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t("LOGIN.TITLE") }}</h5>
<form method="post" action="/login">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="mb-3">
<label class="form-label" for="login">{{ t("LOGIN.LOGIN_LABEL") }}</label>
{# autofocus: un atributo booleano, escrito si la condición es verdadera, omitido en caso contrario #}
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{ model.login }}" required{{ " autofocus" if not login_typed }}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ t("LOGIN.PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required{{ " autofocus" if login_typed }}>
</div>
{{ captcha(model.captcha) }}
<button type="submit" class="btn btn-primary w-100">{{ t("LOGIN.SUBMIT") }}</button>
{# aún sin 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). El
servidor verifica allí el captcha de arriba antes de abrir la página
de creación de cuenta (véase controllers/registration.py).
formnovalidate: el navegador no exige login ni contraseña
(inútiles para crear una cuenta); es el servidor quien verifica
el captcha. Enter en un campo siempre activa el PRIMER
botón del formulario, "Log in". #}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="/register/access" formnovalidate>{{ t("LOGIN.CREATE_ACCOUNT") }}</button>
<div class="form-text text-center">{{ t("LOGIN.CREATE_ACCOUNT_HELP") }}</div>
</form>
<div class="text-muted small mt-3">
<span>{{ t("LOGIN.DEMO_ACCOUNTS") }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ t("LOGIN.DEMO_ADMIN") }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ t("LOGIN.DEMO_DOCTOR") }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ t("LOGIN.DEMO_USER") }}</span></li>
</ul>
</div>
</div>
</div>
</div>
{% endblock %}
|
- línea 10: se importa la macro, junto con el contexto de la página;
- línea 13: el cursor se coloca en el campo del nombre de usuario si está vacío, o en el campo de la contraseña en caso contrario (después de un intento de inicio de sesión fallido o de crear una cuenta): el atributo booleano [autofocus] se asigna a uno u otro;
- líneas 24–30: los valores del atributo [autocomplete] ayudan a los administradores de contraseñas de los navegadores a rellenar el formulario;
- líneas 46–47: el botón “Crear una cuenta de paciente” no es un enlace, sino un segundo botón para enviar este formulario, que lo envía a una dirección distinta ([formaction], ejemplo 20). El servidor verifica allí el CAPTCHA antes de abrir la página de creación de la cuenta. [formnovalidate]: el navegador no exige el nombre de usuario ni la contraseña, marcados como [required], que son innecesarios para crear una cuenta. Pulsar la tecla Enter en un campo siempre activa el primer botón del formulario, “Iniciar sesión”.
11.17.2.2. templates/schedule.html
| {# =========================================================================
templates/schedule.html - la página principal (véase controllers/schedule.py).
Tres bloques:
1. la elección del médico y del día;
2. la agenda;
3. el diálogo de reserva (fragments/booking.html).
Un posible error (fecha inválida, médico desconocido) se muestra en la
parte inferior de la página por el layout (véase fragments/errors.html).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{# 1. elección del médico y del día: un formulario GET, que simplemente
recarga esta página con ?doctorId=...&day=... en la URL #}
<form method="get" action="/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">{{ t("DOCTOR_DAY_PICKER.DOCTOR_LABEL") }}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{ t("DOCTOR_DAY_PICKER.CHOOSE_DOCTOR") }}</option>
{% for doctor in model.doctors %}
<option value="{{ doctor.id }}"{{ " selected" if doctor.selected }}>{{ doctor.label }}</option>
{% endfor %}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ t("DOCTOR_DAY_PICKER.DAY_LABEL") }}</label>
<input id="day" name="day" type="date" class="form-control" value="{{ model.day }}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{ t("DOCTOR_DAY_PICKER.VIEW_SCHEDULE") }}</button>
</div>
</div>
</form>
{# paciente que ya tiene una cita próxima: por qué no hay botón "Book" #}
{% if model.info %}
<div class="alert alert-info">
<span>{{ t(model.info) }}</span>
<a href="/my-area" class="alert-link">{{ t("APP.MENU_MY_AREA") }}</a>
</div>
{% endif %}
{# 2. la agenda #}
{% set schedule = model.schedule %}
{% if schedule %}
<div class="card p-3">
<h5>{{ t("SCHEDULE.TITLE_PREFIX") }} {{ schedule.day }} - {{ schedule.doctor }}</h5>
{% if schedule.rows %}
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{ t("SCHEDULE.COLUMN_SLOT") }}</th>
<th>{{ t("SCHEDULE.COLUMN_STATUS") }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for row in schedule.rows %}
<tr class="{{ 'free-slot' if row.bookable }}">
<td>{{ row.time }}</td>
<td>
{# [patient] se llena solo si el usuario está autorizado a
ver este nombre (ADMIN, DOCTOR, o el paciente para SU
cita) - de lo contrario, simplemente "Booked" #}
{% if row.free %}
<span class="badge text-bg-success">{{ t("SCHEDULE.FREE") }}</span>
{% elif row.patient %}
<span class="badge {{ 'text-bg-primary' if row.mine else 'text-bg-secondary' }}">{{ row.patient }}</span>
{% else %}
<span class="badge text-bg-secondary">{{ t("SCHEDULE.BOOKED_BY_OTHER") }}</span>
{% endif %}
</td>
<td>
{# los botones mostrados los decidió el controlador
(bookable, appointment_id) según el rol del usuario.
"Book" es un enlace simple: reabre esta página
con el diálogo de reserva de esta franja #}
{% if row.bookable %}
<a class="btn btn-sm btn-outline-success" href="{{ row.book_url }}">{{ t("SCHEDULE.BOOK") }}</a>
{% endif %}
{# "Cancel" MODIFICA datos: por lo tanto es un POST #}
{% if row.appointment_id %}
<form method="post" action="/schedule/cancel" class="m-0"
data-confirmation="{{ t('SCHEDULE.CANCEL_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ row.appointment_id }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.day }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("SCHEDULE.CANCEL_APPOINTMENT") }}</button>
</form>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t("SCHEDULE.NO_SLOTS") }}</p>
{% endif %}
</div>
{% else %}
<p class="text-muted">{{ t("SCHEDULE.EMPTY_STATE") }}</p>
{% endif %}
{# 3. el diálogo de reserva, solo si la URL contiene &book=... #}
{% if model.booking %}
{% include "fragments/booking.html" %}
{% endif %}
{% endblock %}
|
- Líneas 15–34: selección de un médico y un día: un formulario GET (ejemplo 17), que simplemente recarga la página con los parámetros [doctorId] y [day] en la URL. El campo [<input type="date">] muestra sus valores en el formato [yyyy-mm-dd], independientemente del idioma en que el navegador lo muestre;
- líneas 37–42: el mensaje informativo para un paciente que ya tiene una cita próxima;
- Líneas 61–95: una entrada de la agenda. Hay tres estados posibles: disponible, reservada con el nombre del paciente (en azul si es la cita del paciente conectado) o reservada sin el nombre (“Reservado”). Los botones que se muestran los determina la acción. “Reservar” es un simple enlace: vuelve a abrir esta página con la ventana de reserva de esa franja horaria. “Cancelar” modifica datos: es un formulario POST, con su solicitud de confirmación (ejemplo 21);
- líneas 108–110: la ventana de reserva, solo si la acción la ha preparado.
11.17.2.3. templates/persons/list.html
| {# =========================================================================
templates/persons/list.html - la lista de los médicos O de los clientes (ADMIN).
Una sola vista para ambos: las etiquetas propias de cada uno llegan en
model.keys (véase controllers/doctors.py / controllers/clients.py).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ t(model.keys.title) }}</h4>
<a class="btn btn-primary" href="{{ model.add_url }}">{{ t(model.keys.add) }}</a>
</div>
<div class="card p-3">
{% if model.persons %}
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{ t("PERSONS.COLUMN_TITLE") }}</th>
<th>{{ t("PERSONS.COLUMN_FIRSTNAME") }}</th>
<th>{{ t("PERSONS.COLUMN_LASTNAME") }}</th>
<th>{{ t("PERSONS.COLUMN_LOGIN") }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for person in model.persons %}
<tr>
<td>{{ person.title }}</td>
<td>{{ person.first_name }}</td>
<td>{{ person.last_name }}</td>
<td><code>{{ person.login }}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary" href="{{ person.edit_url }}">{{ t("PERSONS.EDIT") }}</a>
{# data-confirmation: se abrirá un diálogo de confirmación
antes de enviar el formulario (véase static/js/app.js) #}
<form method="post" action="{{ person.delete_url }}" class="m-0"
data-confirmation="{{ t(model.keys.confirm_delete) }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("PERSONS.DELETE") }}</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t(model.keys.empty) }}</p>
{% endif %}
</div>
{% endblock %}
|
Una sola vista para ambas listas, médicos y clientes: las etiquetas específicas de cada una aparecen en [model.keys]; [t(model.keys.title)] muestra una clave que es en sí misma una variable. Cada fila tiene un enlace “Editar” y un formulario “Eliminar”, que requiere confirmación.
| {# =========================================================================
templates/persons/form.html - creación O edición de un
médico o de un cliente (ADMIN). model.creating distingue los dos casos.
Cuando se rechaza la entrada (campo vacío, login ya tomado...), la acción
devuelve ESTA vista con:
- los valores ya escritos (model.values);
- los campos defectuosos delineados en rojo (clase de Bootstrap "is-invalid");
- bajo un campo rechazado por la validación, su mensaje;
- el mensaje de error de la página, mostrado en la PARTE INFERIOR de la página por el
layout (véase fragments/errors.html).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t(model.page_title) }}</h5>
{# novalidate: dejamos que el SERVIDOR valide (es la autoridad);
las verificaciones del navegador (required...) son solo una comodidad,
que un usuario siempre puede eludir #}
<form method="post" action="{{ model.action }}" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% if not model.creating %}
<input type="hidden" name="version" value="{{ model.values.version }}">
{% endif %}
{# título, nombre, apellido: fragmento común a tres formularios #}
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="off"
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.LOGIN_HELP_CREATE" if model.creating else "PERSONS.LOGIN_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="mb-4">
<label class="form-label" for="password">{{ t("PERSONS.PASSWORD_LABEL") }}</label>
{# nunca se rellena previamente: la contraseña nunca vuelve al navegador #}
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_CREATE" if model.creating else "PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("PERSONS.SAVE") }}</button>
<a class="btn btn-secondary" href="{{ model.list_url }}">{{ t("PERSONS.BACK") }}</a>
</div>
</form>
</div>
</div>
</div>
{% endblock %}
|
- línea 25: la dirección de envío la proporciona la acción: [/doctors/add], [/clients/3/edit]...;
- líneas 27–29: al actualizar, la versión del registro se almacena en un campo oculto (bloqueo optimista);
- línea 32: los campos de identidad;
- líneas 38–44: el nombre de usuario, opcional, con una información sobre herramientas que depende de si el registro se está creando o editando ([t("..." if model.creating else "...")]);
- líneas 50-50: la contraseña nunca se rellena previamente; nunca se devuelve al navegador. [autocomplete="new-password"] impide que el navegador sugiera aquí la contraseña del administrador.
11.17.2.5. templates/registration.html
| {# =========================================================================
templates/registration.html - "Create a patient account" (página pública,
véase controllers/registration.py). Mismos campos de identidad que el formulario
del ADMIN (fragmento person_fields.html), pero el login y la
contraseña son obligatorios, con confirmación.
Aquí NO hay captcha: solo se llega a esta página después de haber escrito
el de la página de autenticación (botón "Create a patient account").
t(key, min=...): el mensaje cuya clave es el valor de [key], con el
parámetro {min} (véase web/translator.py).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1">{{ t("REGISTRATION.TITLE") }}</h5>
<p class="text-muted small mb-3">{{ t("REGISTRATION.INTRO") }}</p>
<form method="post" action="/register" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.LOGIN_HELP") }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{ t("PERSONS.PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.PASSWORD_HELP", min=model.password_min) }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{ t("ACCOUNT.CONFIRMATION_LABEL") }}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("REGISTRATION.SUBMIT") }}</button>
<a class="btn btn-secondary" href="/login">{{ t("REGISTRATION.BACK_TO_LOGIN") }}</a>
</div>
</form>
</div>
</div>
</div>
{% endblock %}
|
El formulario de creación de cuentas de paciente: los campos de información personal, seguidos del nombre de usuario, la contraseña y la confirmación de la contraseña, son obligatorios. El mensaje que indica que una contraseña es demasiado corta tiene un parámetro que especifica la longitud mínima: [t(state.error_of("password"), min=model.password_min)]. Aquí no hay CAPTCHA: solo se puede acceder a esta página después de resolver el CAPTCHA de la página de inicio de sesión.
11.17.2.6. templates/area.html
| {# =========================================================================
templates/area.html - "My area": la página de inicio del paciente
(rol USER), mostrada justo después de iniciar sesión.
- dos opciones: [Manage my account] y [View a schedule];
- su cita próxima, si tiene una, con el medio para cancelarla.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<h4 class="mb-3">{{ t("AREA.HELLO", name=model.patient) }}</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="/my-account">
<h5 class="mb-1">{{ t("AREA.MANAGE_ACCOUNT") }}</h5>
<span class="text-muted">{{ t("AREA.MANAGE_ACCOUNT_HELP") }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
<h5 class="mb-1">{{ t("AREA.VIEW_SCHEDULE") }}</h5>
<span class="text-muted">{{ t("AREA.VIEW_SCHEDULE_HELP") }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ t("AREA.MY_APPOINTMENT") }}</h5>
{# normalmente solo una (regla "una cita próxima a la vez"),
pero la página puede mostrar varias. loop.last: ¿último elemento?
El bloque else de un bucle for: la lista está vacía #}
{% for appointment in model.appointments %}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{{ '' if loop.last else ' border-bottom' }}">
<div>
<div class="fw-semibold">{{ appointment.day }}, {{ appointment.time }}</div>
<div class="text-muted">
<span>{{ appointment.doctor }}</span> -
<a href="{{ appointment.schedule_url }}">{{ t("AREA.SEE_IN_SCHEDULE") }}</a>
</div>
</div>
<form method="post" action="/my-area/cancel" class="m-0"
data-confirmation="{{ t('SCHEDULE.CANCEL_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ appointment.id }}">
<button type="submit" class="btn btn-outline-danger">{{ t("AREA.CANCEL_APPOINTMENT") }}</button>
</form>
</div>
{% else %}
<p class="text-muted mb-0">{{ t("AREA.NO_APPOINTMENT") }}</p>
{% endfor %}
</div>
{% endblock %}
|
El panel del paciente: dos pestañas grandes (“Administrar mi cuenta”, “Ver una agenda”) y sus próximas citas. El bucle [for ... else] (ejemplo 14) muestra un mensaje si la lista está vacía; [loop.last] elimina el borde inferior de la última cita. La página puede mostrar varias citas, aunque la regla de gestión permita solo una.
11.17.2.7. templates/account.html
| {# =========================================================================
templates/account.html - "Manage my account" (rol USER).
Dos formularios independientes en la misma página:
1. la edición (identidad, login, nueva contraseña opcional);
2. la eliminación de la cuenta - que también cancela sus citas.
Ambos requieren la contraseña ACTUAL.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{# 1. edición #}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{ t("MY_ACCOUNT.TITLE") }}</h5>
<form method="post" action="/my-account" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="version" value="{{ model.values.version }}">
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{ t("MY_ACCOUNT.NEW_PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{ t("ACCOUNT.CONFIRMATION_LABEL") }}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</div>
</div>
<div class="mb-4">
<label class="form-label" for="current_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="current_password" name="current_password" type="password" maxlength="72"
autocomplete="current-password" required
class="form-control {{ state.invalid_class('current_password') }}">
{% if state.error_of("current_password") %}
<div class="invalid-feedback">{{ t(state.error_of("current_password")) }}</div>
{% else %}
<div class="form-text">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_HELP") }}</div>
{% endif %}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("PERSONS.SAVE") }}</button>
<a class="btn btn-secondary" href="/my-area">{{ t("MY_ACCOUNT.BACK") }}</a>
</div>
</form>
</div>
{# 2. eliminación #}
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1">{{ t("MY_ACCOUNT.DELETE_TITLE") }}</h5>
<p class="text-muted small">{{ t("MY_ACCOUNT.DELETE_HELP") }}</p>
<form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{ t('MY_ACCOUNT.DELETE_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="delete_password" name="delete_password" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger">{{ t("MY_ACCOUNT.DELETE_SUBMIT") }}</button>
</form>
</div>
</div>
</div>
{% endblock %}
|
Dos formularios independientes en la misma página: modificación de la cuenta (líneas 19–73) y eliminación de la cuenta (líneas 80–89), confirmada mediante la ventana de confirmación. Ambos requieren la contraseña actual, introducida en dos campos separados (un formulario envía solo sus propios campos).
11.17.2.8. templates/error.html
| {# =========================================================================
templates/error.html - la página de error (400, 403, 404, 500...),
construida por web/errors.py.
========================================================================= #}
{% extends "layout.html" %}
{% 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">{{ model.code }}</h1>
<p class="lead">{{ t(model.message) }}</p>
<div><a class="btn btn-primary" href="/">{{ t("ERROR_PAGE.BACK") }}</a></div>
</div>
</div>
</div>
{% endblock %}
|
La página de error: el código, mostrado de forma destacada, y el mensaje traducido. Extiende la plantilla: incluso en caso de error, el usuario conserva su barra de navegación y puede cambiar de idioma.
11.18. Los diccionarios
Los textos de la interfaz están contenidos en dos diccionarios JSON, [i18n/fr.json] e [i18n/en.json], que el traductor lee al iniciar. Son los mismos archivos que en las versiones [NestJS], [ASP.NET Core MVC], y [Spring MVC] de la aplicación.
11.18.1. i18n/fr.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace"
},
"LOGIN": {
"TITLE": "Connexion",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"SUBMIT": "Se connecter",
"ERROR": "Login ou mot de passe incorrect.",
"DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
"DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
"DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
"DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
"CREATE_ACCOUNT": "Créer un compte client",
"CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Médecin",
"CHOOSE_DOCTOR": "-- choisir un médecin --",
"DAY_LABEL": "Jour",
"VIEW_SCHEDULE": "Voir l'agenda"
},
"SCHEDULE": {
"PAGE_TITLE": "Agenda",
"TITLE_PREFIX": "Agenda du",
"COLUMN_SLOT": "Créneau",
"COLUMN_STATUS": "Statut",
"FREE": "Libre",
"BOOK": "Réserver",
"CANCEL_APPOINTMENT": "Annuler",
"CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
"EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
"NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
"BOOKED": "Rendez-vous enregistré.",
"CANCELLED": "Rendez-vous annulé.",
"BOOKED_BY_OTHER": "Réservé",
"ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
},
"BOOKING_DIALOG": {
"TITLE": "Réserver ce créneau",
"CLOSE_ARIA": "Fermer",
"SLOT": "Créneau de {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choisir un patient --",
"CANCEL": "Annuler",
"CONFIRM": "Confirmer"
},
"PERSONS": {
"COLUMN_TITLE": "Titre",
"COLUMN_FIRSTNAME": "Prénom",
"COLUMN_LASTNAME": "Nom",
"COLUMN_LOGIN": "Login",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"SAVE": "Enregistrer",
"BACK": "Retour à la liste",
"TITLE_LABEL": "Titre",
"FIRSTNAME_LABEL": "Prénom",
"LASTNAME_LABEL": "Nom",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
"LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
"PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"ACCOUNT_SECTION": "Compte utilisateur"
},
"DOCTORS": {
"TITLE": "Médecins",
"ADD": "Ajouter un médecin",
"EDIT": "Modifier un médecin",
"EMPTY": "Aucun médecin.",
"DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
"ADDED": "Le médecin {name} a été ajouté (login : {login}).",
"UPDATED": "Le médecin {name} a été modifié.",
"DELETED": "Le médecin {name} a été supprimé."
},
"CLIENTS": {
"TITLE": "Clients",
"ADD": "Ajouter un client",
"EDIT": "Modifier un client",
"EMPTY": "Aucun client.",
"DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
"ADDED": "Le client {name} a été ajouté (login : {login}).",
"UPDATED": "Le client {name} a été modifié.",
"DELETED": "Le client {name} a été supprimé."
},
"ERROR_PAGE": {
"TITLE": "Erreur",
"BACK": "Retour à l'accueil"
},
"ERRORS": {
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
"SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
"DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
"APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
"INVALID_DATE": "La date demandée n'est pas valide.",
"CHOOSE_PATIENT": "Choisissez un patient.",
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"BAD_REQUEST": "La requête est invalide.",
"FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
"NOT_FOUND": "Cette page n'existe pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
"TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
"WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
"TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
"LOGIN_REQUIRED": "Le login est obligatoire.",
"PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
"PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
"CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
"PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
"CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
"WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
"PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
"CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
},
"CAPTCHA": {
"LABEL": "Recopiez les caractères de l'image",
"IMAGE_ALT": "Image de vérification anti-robots",
"NEW_IMAGE": "Autre image",
"HELP": "Majuscules ou minuscules, peu importe."
},
"REGISTRATION": {
"TITLE": "Créer un compte client",
"INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
"LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_HELP": "Au moins {min} caractères.",
"SUBMIT": "Créer mon compte",
"BACK_TO_LOGIN": "Retour à la connexion",
"DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirmation du mot de passe"
},
"AREA": {
"TITLE": "Mon espace",
"HELLO": "Bonjour {name}",
"MANAGE_ACCOUNT": "Gérer mon compte",
"MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
"VIEW_SCHEDULE": "Voir un agenda",
"VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
"MY_APPOINTMENT": "Mon rendez-vous",
"SEE_IN_SCHEDULE": "voir dans l'agenda",
"CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
"NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
},
"MY_ACCOUNT": {
"TITLE": "Gérer mon compte",
"NEW_PASSWORD_LABEL": "Nouveau mot de passe",
"CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
"CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
"BACK": "Retour à mon espace",
"DELETE_TITLE": "Supprimer mon compte",
"DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
"DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
"DELETE_SUBMIT": "Supprimer mon compte",
"UPDATED": "Votre compte a été modifié.",
"DELETED": "Votre compte a été supprimé."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "Non, revenir",
"YES": "Oui, confirmer"
}
}
|
Las claves se agrupan por página o por tema: [APP] (la barra de navegación), [LOGIN], [SCHEDULE], [BOOKING_DIALOG] (la ventana de reserva), [PERSONS], [DOCTORS], [CLIENTS], [ERRORS] (todos los mensajes de error, incluidos los de los validadores de formularios y los de la capa de negocio)... Los parámetros de los mensajes se escriben como [{name}], [{login}], [{minutes}], [{min}], [{time}].
11.18.2. i18n/en.json
El diccionario en inglés tiene exactamente las mismas claves. Estas son algunas líneas a modo de comparación:
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Log out",
"MENU_SCHEDULE": "Schedule",
"MENU_DOCTORS": "Doctors",
"MENU_PATIENTS": "Patients",
"MENU_MY_AREA": "My area"
},
"LOGIN": {
"TITLE": "Login",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"SUBMIT": "Log in",
"ERROR": "Incorrect login or password.",
"DEMO_ACCOUNTS": "Demo accounts (password = login):",
"DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
"DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
"DEMO_USER": "USER role (patients): booking for themselves, managing their account",
"CREATE_ACCOUNT": "Create a patient account",
"CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
|
Bastaría con un diccionario más para un tercer idioma: habría que agregarlo a la lista del traductor ([LANGUAGES]) y añadir un botón a la barra de navegación.
11.19. Archivos estáticos
La carpeta [static] contiene la hoja de estilos de la aplicación, su script y [Bootstrap] (carpeta [lib/bootstrap]: la hoja de estilos [bootstrap.min.css] de la distribución oficial y su licencia; la aplicación no utiliza el [JavaScript] de [Bootstrap]).
11.19.1. static/css/styles.css
| /* =========================================================================
static/css/styles.css - unos pocos ajustes sobre Bootstrap
(los mismos que en las versiones ASP.NET Core MVC y Spring MVC 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 pie 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 "My area" 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;
}
|
Algunas reglas adicionales para [Bootstrap], las mismas que en las versiones anteriores de la aplicación. El área de errores (líneas 23–32) es fija (sticky) ([position: sticky], [bottom: 1rem]): si la página es más alta que la ventana (un calendario con doce franjas horarias), permanece visible en la parte inferior de la ventana en lugar de desaparecer bajo el borde inferior. [z-index: 1060] la coloca por encima del fondo gris de las ventanas modales.
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 lleve el atributo
// data-confirmation="...", un diálogo modal pregunta "Are you sure?"
// (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 "progressive enhancement").
//
// ¿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 devolver 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": presionar Enter por descuido no elimina nada
noButton.focus();
}
function close() {
modal.classList.add('d-none');
pendingForm = null;
if (previousFocus) {
previousFocus.focus();
}
}
// 1. interceptamos el envío 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 (Yes / 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 disparar el evento
// 'submit': sin 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 irí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 script del ejemplo 21, completado:
- líneas 16–18: el script no hace nada si la página no tiene una ventana de confirmación;
- líneas 26–34: al abrirse, el mensaje se coloca mediante [textContent], no [innerHTML]: se muestra como texto y nunca se interpreta como HTML. El foco se desplaza al botón “No”: pulsar Enter accidentalmente no elimina nada;
- líneas 37–41: al cerrarse, el foco vuelve al elemento que lo tenía anteriormente (el botón “Eliminar”), lo que es importante para la navegación con el teclado;
- líneas 54–65: clics dentro de la ventana. [closest('[data-action]')] busca el elemento con el atributo [data-action], a partir del elemento sobre el que se hizo clic y subiendo por sus elementos padre: un clic en un icono dentro de un botón se atribuye así al botón. El operador [?.] devuelve [undefined] en lugar de lanzar un error si no se encuentra ningún elemento. Un clic en el fondo atenuado cierra la ventana;
- líneas 71–83: comportamiento del teclado: Esc cierra la ventana; Tab y Shift-Tab recorren el foco entre los botones de la ventana, sin pasar a la página atenuada que queda detrás.