11. Caso de estudio: el cliente Flutter de la aplicación RdvMedecins
11.1. El problema
La aplicación [RdvMedecins] permite programar citas en un consultorio médico. El curso de [NestJS] la desarrolló como una aplicación HTML, en la que el servidor generaba las páginas; los cursos de [Vue.js], [Angular] y [React] escribieron clientes web para ella, que generan las MISMAS páginas en el navegador a partir de los datos JSON del servidor presentados en el capítulo “El servidor RdvMedecins, una caja negra”. Aquí describimos el cliente [Flutter]: una aplicación móvil ([Android]), que también se puede compilar para la web.
El cliente debe ofrecer todo lo que ofrecían los demás:
- una pantalla de inicio de sesión, protegida por un CAPTCHA, con la opción de crear una cuenta de paciente;
- la agenda de un médico para un día determinado, con reserva de citas (ventana de selección de paciente) y cancelación;
- para el administrador, gestión de médicos y clientes (listar, agregar, editar, eliminar);
- para el paciente, un panel personal (que muestra las citas próximas, que puede cancelar) y gestión de la cuenta;
- dos idiomas: francés e inglés;
- las mismas direcciones que los clientes web ([/schedule?doctorId=1&day=...]). En el teléfono son invisibles, pero organizan la aplicación; en la web, los usuarios pueden recargarlas, guardarlas como marcadores y navegar por la aplicación con los botones Atrás/Adelante del navegador.
Una aplicación móvil añade sus propios requisitos: una pantalla estrecha (sin tablas de cinco columnas), un teclado que oculta la mitad de la pantalla, un botón Atrás, un administrador de contraseñas y la ausencia de un navegador que guarde la cookie del token.
11.2. Instalación y ejecución
El servidor JSON debe estar instalado y en ejecución (véase el capítulo “El servidor RdvMedecins: una caja negra”). No se necesita el modo de prueba del CAPTCHA: puede dejar el campo [CAPTCHA_TEST] vacío en el archivo [.env] del servidor.
En una ventana de consola abierta en la carpeta [rdvmedecins_flutter]:
| flutter create --platforms=android,web --org fr.stahe --project-name rdvmedecins_flutter .
flutter pub get
|
El primer comando agrega al proyecto las carpetas específicas de cada plataforma ([android/], [web/]), como en los ejemplos; no modifica ningún archivo existente y se conserva el archivo [android/app/src/main/AndroidManifest.xml] entregado (el del ejemplo 22). Luego, elija una de las siguientes opciones:
| flutter run -d emulator-5554
flutter run -d R58N12ABCDE --dart-define=SERVER=http://192.168.1.20:8080
flutter run -d chrome
|
- La primera línea inicia la aplicación en el emulador de [Android] (el comando [flutter devices] lista los dispositivos disponibles). El emulador se conecta al servidor en la dirección [10.0.2.2:8080] (véase el ejemplo 22);
- la segunda línea ejecuta la aplicación en un teléfono real conectado por USB (con la “depuración USB” habilitada en sus opciones de desarrollador) o conectado por Wi-Fi. El teléfono y la computadora deben estar en la misma red; indique la dirección de la computadora en esta red ([ipconfig] en [Windows]). El firewall de [Windows] debe permitir las conexiones entrantes en el puerto 8080;
- la tercera, en [Chrome], en la dirección http://localhost:5173: el servidor de desarrollo web de [Flutter] reenvía las solicitudes /api al servidor JSON (archivo [web_dev_config.yaml]).
Las cuentas de demostración se muestran en la pantalla de inicio de sesión (contraseña = nombre de usuario). Mientras la aplicación está en ejecución, la tecla [r] en la consola realiza una “recarga en caliente” después de un cambio de código; [R] la reinicia; [q] la detiene.
11.3. Uso de la aplicación
Las capturas de pantalla de esta sección provienen de un teléfono con una resolución de 1080 × 2340 píxeles (412 × 891 puntos).
11.3.1. La pantalla de inicio de sesión
La pantalla de inicio de sesión; contraseña incorrecta: el mensaje aparece en la parte inferior de la pantalla y se muestra una nueva imagen (cada imagen se usa una sola vez):
11.3.2. La agenda, vista por el administrador y los médicos
Con la sesión iniciada como [admin], se llega a la agenda. El botón ☰ abre el menú: las pantallas accesibles para el administrador y, en la parte superior, quién tiene la sesión iniciada:
Seleccione un médico y una fecha (la fecha en un calendario) y luego pulse “Ver agenda”. La URL cambia a [/schedule?doctorId=1&day=2026-10-05]. Al pulsar “Reservar” se abre la ventana de reserva; la URL cambia a [/schedule?doctorId=1&day=2026-10-05&book=3]:
La cita se guarda; “Cancelar” solicita confirmación:
Un médico llega directamente a SU agenda de hoy:

11.3.3. El portal del paciente
Un paciente ([martin]) accede a “Mi área”. En una agenda, ve “Reservado” junto a los horarios de otros pacientes y reserva una cita para sí mismo sin seleccionar un paciente específico:
Su cita aparece con su nombre; el botón “Reservar” ya no está disponible (solo una cita próxima). En la agenda de otro médico, donde su cita no aparece, un mensaje explica por qué no puede reservar. Su área (“Mi área”) muestra la cita:
“Gestionar mi cuenta”: cualquier cambio requiere la contraseña actual; los errores provienen del servidor:

El menú de un paciente no incluye una entrada “Médicos”. En la web, si el paciente escribe por sí mismo la dirección /doctors, el enrutador muestra una página de error 403 (véase [router.dart]).
11.3.4. Gestión de médicos y clientes
La lista de médicos; una entrada mal completada:
Una adición exitosa; un homónimo; se deniega la eliminación de un médico que tiene citas:
11.3.5. Creación de una cuenta
En la pantalla de inicio de sesión, escriba el CAPTCHA y luego pulse “Crear una cuenta de paciente”. El servidor rechaza el formulario; una vez creada la cuenta, se vuelve a la pantalla de inicio de sesión con los datos de acceso ya completados:
11.3.6. En francés; en una pantalla grande
El menú FR / EN de la barra superior vuelve a renderizar la pantalla localmente, sin hacer ninguna solicitud al servidor. En una pantalla ancha (la web, una tableta), el menú permanece visible a la izquierda:
11.3.7. Sesión vencida
Si el token vence (o si se elimina la cookie), la siguiente solicitud recibe una respuesta 401; la aplicación redirige a la pantalla de inicio de sesión:

11.4. Arquitectura del cliente
| rdvmedecins_flutter/
├── pubspec.yaml the libraries, the resources
├── analysis_options.yaml the rules of the code analyzer
├── web_dev_config.yaml the web development server (proxy /api)
├── android/ the Android project (including AndroidManifest.xml)
├── web/ the HTML page of the web version
├── assets/
│ ├── i18n/ the dictionaries fr.json, en.json
│ └── fonts/ the RobotoMono font
├── test/ unit tests; making of the screenshots
└── lib/
├── main.dart the startup
├── config.dart the server address
├── router.dart the screens, their addresses, their access rights
├── formatting.dart the formatting of times and days
├── api/ the API access layer
├── i18n/ the languages
├── state/ session, messages, cache (ChangeNotifier)
├── widgets/ the layout and the reusable widgets
└── pages/ the screens
|
Esta es la arquitectura recomendada por la guía de [Flutter] (“App architecture”), explicada de forma más sencilla:
- una capa de datos ([api/]): la única capa que conoce el paquete [http], las URL y el JSON;
- una capa de estado ([state/]): objetos [ChangeNotifier] proporcionados a toda la aplicación ([provider]), que las pantallas observan;
- una capa de interfaz ([pages/], [widgets/]): widgets que muestran el estado y transmiten las acciones del usuario.
La siguiente tabla compara la aplicación HTML del curso de [NestJS], el cliente [React] y este cliente:
Aplicación HTML (NestJS) | Cliente React | Cliente Flutter |
El servidor renderiza cada página ([res.render]) | Los componentes renderizan las páginas en el navegador | Los widgets renderizan las pantallas en el teléfono |
[views/layout.hbs] y sus vistas parciales | [Layout.tsx] y los componentes | [layout.dart] (una [ShellRoute]) y los widgets |
rutas de los controladores | [React Router] | [go_router] |
[JwtAuthGuard], [RolesGuard] | guardias del enrutador (middleware) | La función [redirect] del enrutador |
la cookie del token, guardada por el navegador | igual que el anterior | Un cliente HTTP que gestiona las cookies (en el teléfono) |
mensaje flash en una cookie | un store llamado [Zustand] | un [ChangeNotifier], [Messages] |
diccionarios leídos por el servidor | [i18next] | [Translations] (ejemplo 21) |
idioma guardado en una cookie | en [localStorage] | en [shared_preferences] |
datos ya leídos | [TanStack Query] | [Cache] (unas pocas líneas) |
Formulario rechazado: el servidor recarga la página | respuesta 400/409, errores debajo de los campos | igual que el anterior |
A continuación se presentan todos los archivos del cliente. Están ampliamente comentados; sus comentarios forman parte del curso.
11.5. Configuración del proyecto
11.5.1. pubspec.yaml
| # ==========================================================================
# pubspec.yaml - el cliente Flutter de la aplicación RdvMedecins
# ==========================================================================
name: rdvmedecins_flutter
description: The Flutter client (Android, web) of the RdvMedecins appointment booking application.
publish_to: none
version: 1.0.0
environment:
sdk: ^3.12.0
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
flutter_web_plugins:
sdk: flutter
intl: any
go_router: ^16.2.0
provider: ^6.1.5
shared_preferences: ^2.5.3
http: ^1.5.0
flutter_svg: ^2.2.1
dev_dependencies:
flutter_test:
sdk: flutter
flutter_lints: ^6.0.0
flutter:
uses-material-design: true
assets:
- assets/i18n/
fonts:
- family: RobotoMono
fonts:
- asset: assets/fonts/RobotoMono-Regular.ttf
- asset: assets/fonts/RobotoMono-Bold.ttf
weight: 700
|
Las bibliotecas de los ejemplos, salvo [flutter_svg]... que se mantiene: el CAPTCHA es una imagen (SVG). Los únicos recursos son los diccionarios y la fuente monoespaciada para las cuentas de demostración.
11.5.2. analysis_options.yaml
| # ==========================================================================
# analysis_options.yaml - las reglas del analizador de código Dart
# --------------------------------------------------------------------------
# El analizador revisa el código mientras se escribe (VS Code subraya los
# errores) y con el comando flutter analyze. Partimos de las reglas
# recomendadas por el equipo de Flutter (paquete flutter_lints)...
# ==========================================================================
include: package:flutter_lints/flutter.yaml
analyzer:
language:
# ... más estrictas: sin conversión implícita de un tipo dynamic
strict-casts: true
strict-raw-types: true
linter:
rules:
# comillas simples en todas partes, como en los ejemplos del curso
prefer_single_quotes: true
# "final" para una variable local que nunca se reasigna
prefer_final_locals: true
# se permiten cadenas de caracteres demasiado largas (textos de la interfaz)
lines_longer_than_80_chars: false
|
Las reglas del analizador, como en los ejemplos:
- línea 9: las reglas recomendadas por el equipo de [Flutter];
- líneas 14–15: verificación de tipos más estricta: un [dynamic] (como los que devuelve [jsonDecode]) no se puede usar como un [String] sin una conversión explícita ([as String], o filtrado mediante [Dart] 3);
- líneas 20–24: tres reglas de formato.
El comando [flutter analyze] aplica estas reglas a todo el proyecto; [VS Code] las aplica mientras se escribe.
11.5.3. web_dev_config.yaml
| # ==========================================================================
# web_dev_config.yaml - el servidor de desarrollo WEB de Flutter
# --------------------------------------------------------------------------
# flutter run -d chrome sirve la aplicación en http://localhost:5173 y
# reenvía cualquier solicitud /api/... al servidor JSON de RdvMedecins (puerto 8080):
# para el navegador, la aplicación y la API tienen el MISMO origen (sin
# CORS, y la cookie del token viaja).
# ==========================================================================
server:
host: localhost
port: 5173
proxy:
- target: "http://localhost:8080/"
prefix: "/api/"
|
El del ejemplo 22: en el desarrollo web, las solicitudes /api se envían al servidor JSON.
11.6. Inicio de la aplicación
11.6.1. lib/config.dart
| // =========================================================================
// lib/config.dart - ¿DÓNDE está el servidor JSON?
// -------------------------------------------------------------------------
// La pregunta no se plantea para una aplicación web servida por el
// propio servidor: las solicitudes van al MISMO origen que la página
// (una dirección relativa, /api/...). Pero una aplicación MÓVIL no tiene
// origen: hay que darle la dirección completa del servidor.
// - el emulador de Android ve la computadora que lo ejecuta en
// la dirección 10.0.2.2 (localhost, para él, es el propio emulador);
// - un teléfono real, conectado a la misma red Wi-Fi que la computadora, debe
// usar la dirección de la computadora en esta red (192.168.1.20...):
// se indica al lanzar la aplicación:
// flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...
// - en desarrollo web (flutter run -d chrome), el servidor de desarrollo
// de Flutter reenvía las solicitudes /api al servidor JSON
// (archivo web_dev_config.yaml): basta una dirección relativa;
// - en una computadora (Windows, macOS, Linux): localhost.
// =========================================================================
import 'package:flutter/foundation.dart';
// el valor dado por --dart-define=SERVER=..., '' por defecto.
// String.fromEnvironment se evalúa en tiempo de COMPILACIÓN: es una constante
const _forcedServer = String.fromEnvironment('SERVER');
class Config {
// kIsWeb: true si la aplicación se ejecuta en un navegador;
// defaultTargetPlatform: el sistema (android, iOS, windows...)
static String serverUrl = _forcedServer.isNotEmpty
? _forcedServer
: kIsWeb
? '' // mismo origen: direcciones relativas
: defaultTargetPlatform == TargetPlatform.android
? 'http://10.0.2.2:8080'
: 'http://localhost:8080';
}
|
La dirección del servidor, según la plataforma (véase el ejemplo 22):
- línea 24: el valor proporcionado al iniciar mediante [--dart-define=SERVER=...]. [String.fromEnvironment] se evalúa en tiempo de compilación: la dirección queda incorporada en la aplicación compilada;
- líneas 29–35: de lo contrario, una dirección relativa en la web (el servidor de desarrollo y, en producción, el propio servidor JSON, sirven la página Y la API), [10.0.2.2] en [Android] (la computadora, vista desde el emulador), [localhost] en los demás casos. [static]: una variable de clase, no de objeto; no es [final], para que las pruebas puedan modificarla.
11.6.2. lib/main.dart
| // =========================================================================
// lib/main.dart - el arranque de la aplicación
// -------------------------------------------------------------------------
// Construimos, una vez por todas, los objetos compartidos por toda la
// aplicación, y luego los PROVEEMOS a todas las pantallas (provider):
// - el cliente HTTP (que gestiona la cookie del token en el teléfono) y la
// capa de acceso a la API;
// - la sesión (¿quién ha iniciado sesión?), los mensajes, el caché de datos;
// - las traducciones (francés, inglés);
// - el enrutador, que muestra la pantalla de la dirección actual.
// Dos mecanismos vinculan estos objetos entre sí:
// 1. la respuesta 401 de una solicitud protegida (sesión expirada): se olvida
// al usuario y se prepara el mensaje; el enrutador, que escucha a la
// sesión, vuelve entonces a la pantalla de inicio de sesión (vea api/api_client.dart);
// 2. los mensajes "flash": al final de CADA navegación, los mensajes
// de la pantalla anterior desaparecen, los dejados para la siguiente
// pantalla aparecen (vea state/messages.dart).
// =========================================================================
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_web_plugins/url_strategy.dart';
import 'package:go_router/go_router.dart';
import 'package:intl/date_symbol_data_local.dart';
import 'package:provider/provider.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'api/api_client.dart';
import 'api/http_client.dart';
import 'api/rdvmedecins_api.dart';
import 'state/cache.dart';
import 'state/messages.dart';
import 'state/session.dart';
import 'i18n/translations.dart';
import 'router.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
usePathUrlStrategy(); // en la web: /schedule en lugar de /#/schedule
await initializeDateFormatting();
final storage = await SharedPreferences.getInstance();
final translations = Translations(storage);
await translations.start();
runApp(Application(storage: storage, translations: translations));
}
class Application extends StatefulWidget {
final SharedPreferences storage;
final Translations translations;
const Application({super.key, required this.storage, required this.translations});
@override
State<Application> createState() => _ApplicationState();
}
class _ApplicationState extends State<Application> {
late final ApiClient _client = ApiClient(CookieClient(widget.storage));
late final RdvMedecinsApi _api = RdvMedecinsApi(_client);
late final Session _session = Session(_api);
final Messages _messages = Messages();
final Cache _cache = Cache();
late final GoRouter _router = createRouter(_session, _messages, _api);
String? _address;
@override
void initState() {
super.initState();
// 1. la sesión expirada
_client.onSessionExpired = () {
_session.forget();
_cache.clear();
_messages.flash(success: false, key: 'ERRORS.SESSION_EXPIRED');
// sin _router.go('/login'): el guardia del enrutador se encarga, y
// recuerda la pantalla actual (?redirect=...) para volver a ella
};
// la sesión cambia (inicio, cierre de sesión): los datos leídos para
// el usuario anterior ya no valen nada
_session.addListener(_cache.clear);
// 2. en cada navegación completada (la dirección cambió): página nueva
_router.routerDelegate.addListener(() {
// state: la pantalla en la CIMA de la pila (incluida una pantalla colocada con push)
final address = _router.state.uri.toString();
if (address != _address) {
_address = address;
_messages.newPage();
}
});
}
@override
void dispose() {
_router.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return MultiProvider(
providers: [
// objetos ordinarios...
Provider.value(value: _api),
// ... y objetos que notifican sus cambios
ChangeNotifierProvider.value(value: _cache),
ChangeNotifierProvider.value(value: _session),
ChangeNotifierProvider.value(value: _messages),
ChangeNotifierProvider.value(value: widget.translations),
],
child: Consumer<Translations>(
builder: (context, translations, _) => MaterialApp.router(
debugShowCheckedModeBanner: false,
onGenerateTitle: (context) => translations.t('APP.TITLE'),
theme: ThemeData(colorSchemeSeed: const Color(0xFF0D6EFD)),
// los textos del propio Flutter (calendario...) en el idioma elegido
locale: Locale(translations.language),
supportedLocales: [for (final l in languages) Locale(l)],
localizationsDelegates: GlobalMaterialLocalizations.delegates,
routerConfig: _router,
),
),
);
}
}
|
- líneas 37–44: antes de mostrar cualquier cosa, se prepara lo que hay que preparar: direcciones web sin [#] (ejemplo 17), los nombres de los días y los meses en todos los idiomas ([intl], ejemplo 09), el almacenamiento del dispositivo y el diccionario del idioma inicial. [WidgetsFlutterBinding.ensureInitialized()]: estas operaciones requieren el motor de [Flutter], así que se lo inicia antes de [runApp];
- líneas 58–63: los objetos compartidos, creados UNA sola vez, en el estado del widget raíz. Cada uno recibe al crearse los que necesita: es la inyección de dependencias, hecha manualmente. [late]: la inicialización ocurre en el primer uso, cuando [widget] ya existe;
- líneas 70–76: 1. la sesión vencida. La capa de acceso a la API no conoce ni la sesión ni los mensajes; se le confía esta función, que llamará en cada respuesta 401. Se olvida al usuario, se vacía la caché y se prepara el mensaje para la siguiente pantalla. El cambio de pantalla en sí lo gestiona el enrutador, que vigila la sesión;
- línea 79: cada vez que cambia el usuario, se vacía la caché: los datos leídos para el usuario anterior no sirven al siguiente (un paciente no debe ver la agenda consultada por el administrador);
- Líneas 81–88: 2. mensajes flash. El [routerDelegate] del enrutador avisa a sus oyentes en cada transmisión; la dirección se compara con la anterior ([_router.state]: la pantalla en la PARTE SUPERIOR de la pila, incluida una pantalla apilada por [push], como la ventana de reserva) y, si cambió, el sistema pasa a una “página nueva”: los mensajes de la pantalla anterior desaparecen y aparecen los colocados en esta (véase [messages.dart]);
- líneas 99–107: los objetos compartidos se proporcionan a todas las pantallas (ejemplo 20). [.value]: el objeto ya existe; el proveedor no lo crea (ni lo destruirá);
- líneas 109–118: la aplicación en sí, reconstruida con cada cambio de idioma ([Consumer], véase el ejemplo 20): el título ([onGenerateTitle]) y el idioma de los textos del propio [Flutter] (el calendario, las sugerencias). [colorSchemeSeed]: un color a partir del cual [Material] deriva toda la paleta; es el azul de [Bootstrap], el color que usan los clientes web.
11.7. La capa de acceso a la API
11.7.1. lib/api/http_client.dart
| // =========================================================================
// lib/api/http_client.dart - un cliente HTTP que gestiona las COOKIES
// -------------------------------------------------------------------------
// El servidor de RdvMedecins coloca el token JWT en una COOKIE (httpOnly).
// En un navegador, es el navegador quien guarda las cookies y las reenvía
// con cada solicitud: el código de la aplicación no tiene nada que hacer.
// En un teléfono NO hay navegador: le corresponde a la aplicación
// cumplir su función, es decir:
// 1. leer el encabezado "Set-Cookie" de cada respuesta y guardar las cookies;
// 2. reenviarlas en el encabezado "Cookie" de cada solicitud.
// Este cliente HTTP lo hace, ENVOLVIENDO el cliente del paquete http
// (http.BaseClient: basta con escribir el método send). Las cookies se
// guardan también en el dispositivo (shared_preferences): seguimos con la sesión
// iniciada al detener y reiniciar la aplicación.
// En la web, no hace más que el cliente ordinario: el
// navegador prohíbe a la aplicación leer o escribir estos encabezados.
// =========================================================================
import 'dart:convert';
import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';
class CookieClient extends http.BaseClient {
static const _key = 'rdvmedecins.cookies';
final http.Client _inner = http.Client();
final SharedPreferences? _storage;
// nombre de la cookie -> su valor
final Map<String, String> _cookies = {};
CookieClient([this._storage]) {
// las cookies guardadas durante un uso anterior
final stored = _storage?.getString(_key);
if (stored != null) {
_cookies.addAll((jsonDecode(stored) as Map<String, Object?>).cast<String, String>());
}
}
@override
Future<http.StreamedResponse> send(http.BaseRequest request) async {
if (!kIsWeb && _cookies.isNotEmpty) {
// "rdvmedecins_jwt=eyJhbGci...; other=value"
request.headers['cookie'] = [for (final MapEntry(:key, :value) in _cookies.entries) '$key=$value'].join('; ');
}
final response = await _inner.send(request);
final setCookie = response.headers['set-cookie'];
if (!kIsWeb && setCookie != null) {
_store(setCookie);
}
return response;
}
// Set-Cookie: rdvmedecins_jwt=eyJ...; Max-Age=7200; Path=/api; Expires=Tue, 29 Sep 2026 ...; HttpOnly
// (varias cookies se separan con comas). Solo conservamos el
// nombre y el valor de cada cookie; un valor vacío (cierre de sesión) la elimina
void _store(String setCookie) {
// un nombre seguido de "=", al comienzo del encabezado o después de una coma
for (final m in RegExp(r'(?:^|,)\s*([^=;,\s]+)=([^;]*)').allMatches(setCookie)) {
final name = m[1]!;
final value = m[2]!.trim();
if (value.isEmpty) {
_cookies.remove(name);
} else {
_cookies[name] = value;
}
}
_storage?.setString(_key, jsonEncode(_cookies));
}
@override
void close() => _inner.close();
}
|
El cliente HTTP del ejemplo 23, sin cambios: guarda las cookies recibidas (encabezado [Set-Cookie]) y las reenvía (encabezado [Cookie]) en el teléfono; en la web, deja que lo gestione el navegador.
11.7.2. lib/api/api_client.dart
| // =========================================================================
// lib/api/api_client.dart - TODAS las solicitudes a la API pasan por aquí
// -------------------------------------------------------------------------
// Tomado de common/api.dart de los ejemplos, con algo nuevo: el tratamiento
// centralizado de la respuesta 401.
//
// Un 401 puede ocurrir en cualquier momento: el token ha expirado (2 horas), la
// cuenta ha sido eliminada, el servidor se reinició con otra clave
// secreta... En lugar de tratar este caso en cada pantalla, lo tratamos
// AQUÍ, una sola vez. Pero este archivo no conoce ni el enrutador ni los mensajes
// (no depende de nada): llama a una función que se le dio al
// arrancar (onSessionExpired, vea main.dart), que olvida al usuario y
// vuelve a la página de inicio de sesión.
//
// Algunas solicitudes tratan su 401 por sí mismas (el inicio de sesión, GET
// /api/auth/me...): son "públicas" (vea rdvmedecins_api.dart).
// =========================================================================
import 'dart:convert';
import 'package:http/http.dart' as http;
import '../config.dart';
import 'api_error.dart';
class ApiClient {
final http.Client _client;
// qué hacer cuando el servidor responde 401 a una solicitud protegida
void Function() onSessionExpired = () {};
ApiClient(this._client);
// isPublic: true para las rutas que tratan el 401 por sí mismas
Future<Object?> request(String method, String url, {Object? body, bool isPublic = false}) async {
final request = http.Request(method, Uri.parse('${Config.serverUrl}/api$url'));
if (body != null) {
request.headers['content-type'] = 'application/json';
request.body = jsonEncode(body);
}
final http.Response response;
try {
response = await http.Response.fromStream(await _client.send(request));
} catch (_) {
// sin respuesta: red caída, servidor detenido, dirección incorrecta
throw const ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
}
if (response.statusCode >= 400) {
final error = ApiError.fromResponse(response);
if (error.statusCode == 401 && !isPublic) {
onSessionExpired();
// la pantalla que esperaba la respuesta mostrará TAMBIÉN este mensaje
throw const ApiError(401, 'ERRORS.SESSION_EXPIRED');
}
throw error;
}
return response.bodyBytes.isEmpty ? null : jsonDecode(utf8.decode(response.bodyBytes));
}
}
|
El archivo [common/api.dart] de los ejemplos, con una novedad: la respuesta 401.
- Línea 29: una función a la que se llama en caso de error 401, especificada al inicio (véase [main.dart]). De forma predeterminada, no hace nada;
- línea 34: [isPublic] es un parámetro con nombre, opcional (entre llaves): [request('GET', '/captcha', isPublic: true)];
- líneas 35–38: la solicitud, construida pieza por pieza: método, dirección, encabezado y cuerpo JSON;
- líneas 40–45: se envía la solicitud. Una excepción aquí significa que no se recibió ninguna respuesta (red caída, servidor caído, dirección incorrecta). [final http.Response response;]: una variable [final] declarada sin valor; [Dart] verifica que reciba un valor, una sola vez, antes de ser leída;
- líneas 47–54: una respuesta de error se convierte en un [ApiError]. Un 401 en una solicitud protegida significa que la sesión venció: se llama a [onSessionExpired] y luego se lanza un error de todos modos (la pantalla que esperaba la respuesta debe saber que no llegó), con la clave [ERRORS.SESSION_EXPIRED]: si esta pantalla muestra el error, es el mismo mensaje;
- línea 56: una respuesta sin cuerpo (204) produce [null]. Decodificamos los bytes a UTF-8: sin el encabezado [charset], el paquete [http] decodificaría [response.body] en Latin-1 y los acentos se corromperían.
11.7.3. lib/api/api_error.dart
| // =========================================================================
// lib/api/api_error.dart - UNA sola clase para todos los errores de la API
// -------------------------------------------------------------------------
// Todas las respuestas de error del servidor RdvMedecins tienen la misma forma:
// { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Pero una solicitud también puede fallar de OTRA manera: sin ninguna respuesta
// (red caída, servidor detenido, dirección incorrecta), o con una respuesta que no
// viene de nuestro servidor (una página de error de un proxy). Convertimos
// todo esto en UNA sola clase, ApiError, que lleva la clave de traducción
// enviada por el servidor (y, si los hay, sus parámetros y el error de
// cada campo).
// =========================================================================
import 'dart:convert';
import 'package:http/http.dart' as http;
// "implements Exception": un objeto que se puede lanzar (throw) y capturar (catch)
class ApiError implements Exception {
final int statusCode; // 0: el servidor no respondió
final String key; // p. ej. 'ERRORS.LOGIN_TAKEN'
final Map<String, String> params;
final Map<String, String> fields;
const ApiError(this.statusCode, this.key, {this.params = const {}, this.fields = const {}});
// una respuesta de error (4xx, 5xx) -> un ApiError
factory ApiError.fromResponse(http.Response response) {
Object? body;
try {
body = jsonDecode(utf8.decode(response.bodyBytes));
} on FormatException {
body = null; // no es JSON: no respondió nuestro servidor
}
// el "pattern matching" de un Map: si el cuerpo tiene una clave
// "key" de tipo String, se almacena en la variable key
if (body case {'key': final String key}) {
final json = body as Map<String, Object?>;
return ApiError(response.statusCode, key, params: _strings(json['params']), fields: _strings(json['fields']));
}
// sin clave: respondió el proxy o la red en su lugar
return ApiError(
response.statusCode,
response.statusCode >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
);
}
// un objeto JSON { "name": "ERRORS..." } -> Map<String, String> (vacío en caso contrario)
static Map<String, String> _strings(Object? json) =>
json is Map<String, Object?> ? {for (final e in json.entries) e.key: '${e.value}'} : const {};
@override
String toString() => '$statusCode $key';
}
|
El del ejemplo 24: toda solicitud que falla termina con un [ApiError], que contiene la clave de traducción del mensaje, sus parámetros y el error de cada campo.
11.7.4. lib/api/types.dart
| // =========================================================================
// lib/api/types.dart - los objetos JSON intercambiados con el servidor
// -------------------------------------------------------------------------
// La traducción, a clases Dart, de la API descrita en el capítulo "El
// servidor, una caja negra" (vea common/types.dart de los ejemplos). Cada
// clase lee su JSON con el pattern matching de Dart 3: una respuesta que no
// tiene la forma esperada se detecta apenas se recibe.
// =========================================================================
enum Role { admin, doctor, user }
Role _role(String name) => Role.values.byName(name.toLowerCase());
Never _unexpected(String what, Object? json) => throw FormatException('unexpected $what: $json');
// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
class User {
final String login;
final String name; // nombre mostrado: "Marie PELISSIER"
final Role role;
const User(this.login, this.name, this.role);
factory User.fromJson(Object? json) => switch (json) {
{'login': final String login, 'name': final String name, 'role': final String role} => User(
login,
name,
_role(role),
),
_ => _unexpected('User', json),
};
}
// GET /api/captcha
class Captcha {
final String id;
final String svg;
const Captcha(this.id, this.svg);
factory Captcha.fromJson(Object? json) => switch (json) {
{'id': final String id, 'svg': final String svg} => Captcha(id, svg),
_ => _unexpected('Captcha', json),
};
}
// un título, un nombre, un apellido
class Identity {
final String title;
final String firstName;
final String lastName;
const Identity(this.title, this.firstName, this.lastName);
factory Identity.fromJson(Object? json) => switch (json) {
{'title': final String title, 'firstName': final String firstName, 'lastName': final String lastName} => Identity(
title,
firstName,
lastName,
),
_ => _unexpected('Identity', json),
};
// "Mme Alice DURAND"
String get label => '$title $firstName $lastName';
}
// un médico o un cliente: GET /api/doctors, GET /api/clients/:id...
class Person extends Identity {
final int id;
final int version; // bloqueo optimista: se reenvía con una actualización
final String? login; // solo para el ADMIN
const Person(this.id, this.version, super.title, super.firstName, super.lastName, [this.login]);
factory Person.fromJson(Object? json) => switch (json) {
{
'id': final int id,
'version': final int version,
'title': final String title,
'firstName': final String firstName,
'lastName': final String lastName,
} =>
Person(id, version, title, firstName, lastName, (json as Map<String, Object?>)['login'] as String?),
_ => _unexpected('Person', json),
};
static List<Person> list(Object? json) => [for (final p in json as List<Object?>) Person.fromJson(p)];
}
// una franja horaria
class Slot {
final int id;
final int startHour;
final int startMinute;
final int endHour;
final int endMinute;
const Slot(this.id, this.startHour, this.startMinute, this.endHour, this.endMinute);
factory Slot.fromJson(Object? json) => switch (json) {
{'id': final int id, 'startHour': final int sh, 'startMinute': final int sm, 'endHour': final int eh, 'endMinute': final int em} =>
Slot(id, sh, sm, eh, em),
_ => _unexpected('Slot', json),
};
}
// una línea de la agenda, con los DERECHOS del usuario que inició sesión
class ScheduleSlot extends Slot {
final bool free;
final Identity? patient; // null: libre, o tomada por otro paciente
final bool mine; // la cita del paciente que inició sesión
final bool bookable;
final int? appointmentId; // definido si el usuario puede cancelar
const ScheduleSlot(
super.id,
super.startHour,
super.startMinute,
super.endHour,
super.endMinute,
this.free,
this.patient,
this.mine,
this.bookable,
this.appointmentId,
);
factory ScheduleSlot.fromJson(Object? json) {
final s = Slot.fromJson(json);
return switch (json) {
{
'free': final bool free,
'patient': final Object? patient,
'mine': final bool mine,
'bookable': final bool bookable,
'appointmentId': final int? appointmentId,
} =>
ScheduleSlot(
s.id,
s.startHour,
s.startMinute,
s.endHour,
s.endMinute,
free,
patient == null ? null : Identity.fromJson(patient),
mine,
bookable,
appointmentId,
),
_ => _unexpected('Slot', json),
};
}
}
// GET /api/schedule?doctorId=...&day=...
class Schedule {
final Person doctor;
final String day; // "yyyy-MM-dd"
final List<ScheduleSlot> slots;
final String? info; // clave de traducción (paciente que ya tiene una cita)
const Schedule(this.doctor, this.day, this.slots, this.info);
factory Schedule.fromJson(Object? json) => switch (json) {
{
'doctor': final Object doctor,
'day': final String day,
'slots': final List<Object?> slots,
'info': final String? info,
} =>
Schedule(Person.fromJson(doctor), day, [for (final s in slots) ScheduleSlot.fromJson(s)], info),
_ => _unexpected('Schedule', json),
};
}
// una cita de GET /api/my-area
class Appointment {
final int id;
final String day;
final Slot slot;
final Person doctor;
const Appointment(this.id, this.day, this.slot, this.doctor);
factory Appointment.fromJson(Object? json) => switch (json) {
{'id': final int id, 'day': final String day, 'slot': final Object slot, 'doctor': final Object doctor} =>
Appointment(id, day, Slot.fromJson(slot), Person.fromJson(doctor)),
_ => _unexpected('Appointment', json),
};
}
// GET /api/my-area
class MyArea {
final Identity patient;
final List<Appointment> appointments;
const MyArea(this.patient, this.appointments);
factory MyArea.fromJson(Object? json) => switch (json) {
{'patient': final Object patient, 'appointments': final List<Object?> a} => MyArea(Identity.fromJson(patient), [
for (final r in a) Appointment.fromJson(r),
]),
_ => _unexpected('Area', json),
};
}
// GET /api/my-account
class MyAccount extends Identity {
final String login;
final int version;
const MyAccount(super.title, super.firstName, super.lastName, this.login, this.version);
factory MyAccount.fromJson(Object? json) {
final i = Identity.fromJson(json);
return switch (json) {
{'login': final String login, 'version': final int version} => MyAccount(
i.title,
i.firstName,
i.lastName,
login,
version,
),
_ => _unexpected('Account', json),
};
}
}
|
Los objetos JSON de la API, en clases [Dart] (véase el ejemplo 24):
- línea 14: una función que nunca termina con normalidad (lanza una excepción): su tipo de retorno es [Never]. Por lo tanto, puede servir como caso final de un [switch] de cualquier tipo;
- líneas 24–30: filtrado de un [Map]: este caso se aplica si el JSON tiene (al menos) estas tres claves, con valores de estos tipos, que se guardan en variables sobre la marcha;
- líneas 69–88: un médico o un cliente: una [Identity], más un identificador, una versión (el bloqueo optimista: se reenvía con una modificación) y un nombre de usuario, que solo recibe ADMIN (de ahí el parámetro opcional entre corchetes);
- Líneas 109–114: una entrada de la agenda, que muestra los DERECHOS del usuario con sesión iniciada, calculados por el servidor: [patient] solo se muestra a quienes tienen permiso para verlo, [bookable] indica si el usuario puede hacer una reserva; [appointmentId] solo se proporciona a quienes pueden cancelar;
- líneas 129–151: primero se lee el horario en sí ([Slot.fromJson]), seguido de sus campos específicos;
- líneas 209–213: la cuenta del paciente con sesión iniciada: su identidad, nombre de usuario y versión. [super.title]: el parámetro se pasa tal cual al constructor de la clase padre.
11.7.5. lib/api/rdvmedecins_api.dart
| // =========================================================================
// lib/api/rdvmedecins_api.dart - un método por cada ruta de la API
// -------------------------------------------------------------------------
// La "capa de acceso a datos" del cliente (un "repository", en el
// vocabulario de la guía de arquitectura de Flutter): las pantallas llaman a
// estos métodos tipados, sin saber nada de las URL, del paquete http ni del
// JSON. Si la API cambia, solo cambia este archivo.
// Cada método devuelve un Future; si falla, se completa con un
// ApiError (vea api_client.dart).
// Los datos enviados (formularios) son simples Map<String, Object?>:
// sus claves son los nombres de los campos esperados por el servidor - y los
// de los errores que este devuelve (ApiError.fields).
// =========================================================================
import 'api_client.dart';
import 'types.dart';
// /api/doctors o /api/clients: ambos se tratan igual
enum PersonType { doctors, clients }
typedef Data = Map<String, Object?>;
class RdvMedecinsApi {
final ApiClient _client;
RdvMedecinsApi(this._client);
Future<Object?> _get(String url, {bool isPublic = false}) => _client.request('GET', url, isPublic: isPublic);
Future<Object?> _post(String url, Object body, {bool isPublic = false}) =>
_client.request('POST', url, body: body, isPublic: isPublic);
// ================================================ inicio de sesión (rutas públicas)
Future<Captcha> captcha() async => Captcha.fromJson(await _get('/captcha', isPublic: true));
Future<User> me() async => User.fromJson(await _get('/auth/me', isPublic: true));
Future<User> logIn(String login, String password, String captchaId, String captcha) async =>
User.fromJson(
await _post('/auth/login', {
'login': login,
'password': password,
'captchaId': captchaId,
'captcha': captcha,
}, isPublic: true),
);
Future<void> logOut() => _post('/auth/logout', {}, isPublic: true);
// ================================================ creación de cuenta (pública)
Future<void> registrationAccess(String captchaId, String captcha) =>
_post('/register/access', {'captchaId': captchaId, 'captcha': captcha}, isPublic: true);
Future<bool> registrationAccessStatus() async => switch (await _get('/register/access', isPublic: true)) {
{'valid': true} => true,
_ => false,
};
Future<String> register(Data data) async => switch (await _post('/register', data, isPublic: true)) {
{'login': final String login} => login,
final other => throw FormatException('Unexpected response: $other'),
};
// ================================================ agenda y citas
// doctorId null: para un médico que inició sesión, SU agenda
Future<Schedule> schedule(int? doctorId, String day) async {
final params = Uri(queryParameters: {'day': day, 'doctorId': ?doctorId?.toString()}).query;
return Schedule.fromJson(await _get('/schedule?$params'));
}
Future<void> book(String day, int slotId, int? clientId) =>
_post('/appointments', {'day': day, 'slotId': slotId, 'clientId': ?clientId});
Future<void> cancelAppointment(int appointmentId) => _client.request('DELETE', '/appointments/$appointmentId');
// ================================================ médicos y clientes
Future<List<Person>> list(PersonType type) async => Person.list(await _get('/${type.name}'));
Future<Person> read(PersonType type, int id) async => Person.fromJson(await _get('/${type.name}/$id'));
Future<Person> add(PersonType type, Data data) async =>
Person.fromJson(await _post('/${type.name}', data));
Future<Person> edit(PersonType type, int id, Data data) async =>
Person.fromJson(await _client.request('PUT', '/${type.name}/$id', body: data));
Future<void> remove(PersonType type, int id) => _client.request('DELETE', '/${type.name}/$id');
// ================================================ el área del paciente
Future<MyArea> myArea() async => MyArea.fromJson(await _get('/my-area'));
Future<MyAccount> myAccount() async => MyAccount.fromJson(await _get('/my-account'));
Future<User> editMyAccount(Data data) async =>
User.fromJson(await _client.request('PUT', '/my-account', body: data));
Future<void> deleteMyAccount(String currentPassword) =>
_client.request('DELETE', '/my-account', body: {'currentPassword': currentPassword});
}
|
Un método por ruta de la API: es la clase [RdvMedecins] del ejemplo 24, ampliada.
- Línea 19: [/api/doctors] y [/api/clients] se tratan de la misma manera: una enumeración, donde el nombre de cada valor ([PersonType.doctors.name], “doctors”) es el de la ruta;
- Línea 21: un alias de tipo: un nombre más descriptivo para un tipo existente;
- líneas 33–47: las rutas de conexión, que son públicas: un 401 tiene aquí su propio significado específico (“nadie tiene la sesión iniciada”, “contraseña incorrecta”) y no significa que la sesión haya vencido;
- línea 53: ¿es válido el token de creación de cuenta? Una expresión [switch] sobre la respuesta: [true] solo para [{"valid": true}];
- Líneas 65–67: los parámetros de la dirección, construidos por [Uri] (que los codifica). ['doctorId': ?doctorId?.toString()]: un elemento opcional de un [Map] ([Dart] 3.8): la clave se agrega solo si el valor no es [null]. Un médico con sesión iniciada solicita la agenda sin [doctorId]: el servidor devuelve la agenda del propio médico;
- línea 71: de forma similar, [clientId] solo se envía si se conoce (un paciente hace una reserva para sí mismo);
- líneas 76–86: las cinco operaciones con médicos o clientes: [/api/${type.name}];
- líneas 89–97: el área del paciente. Eliminar la cuenta envía un cuerpo de mensaje con una solicitud [DELETE] (la contraseña actual): HTTP lo permite, y el paquete [http] también lo admite, mediante un [http.Request] construido manualmente (véase [api_client.dart]).
11.8. Idiomas
11.8.1. lib/i18n/translations.dart
| // =========================================================================
// lib/i18n/translations.dart - los diccionarios, el idioma actual
// -------------------------------------------------------------------------
// Tomado del ejemplo 21. Los diccionarios (assets/i18n/fr.json, en.json)
// son los de los clientes Vue.js, Angular y React: mismas claves, mismas
// convenciones ({{param}}, plurales _one / _other). El servidor solo devuelve
// CLAVES ("ERRORS.LOGIN_TAKEN"): aquí es donde se convierten en
// texto, en el idioma elegido por el usuario.
// - t('KEY', {'param': value}) : el texto del idioma actual;
// - changeLanguage('fr') : carga el otro diccionario, notifica
// a las pantallas (ChangeNotifier), almacena
// la elección en el dispositivo.
// =========================================================================
import 'dart:convert';
import 'package:flutter/services.dart';
import 'package:flutter/widgets.dart';
import 'package:intl/intl.dart';
import 'package:shared_preferences/shared_preferences.dart';
const languages = ['fr', 'en'];
class Translations extends ChangeNotifier {
final SharedPreferences? _storage;
String _language = 'en';
Map<String, Object?> _dictionary = {};
Translations([this._storage]);
String get language => _language;
// el idioma inicial: el guardado en el dispositivo, o si no el del
// teléfono (si se conoce), o si no inglés
Future<void> start() async {
final stored = _storage?.getString('rdvmedecins.language');
final device = WidgetsBinding.instance.platformDispatcher.locale.languageCode;
await changeLanguage(stored ?? (languages.contains(device) ? device : 'en'));
}
Future<void> changeLanguage(String language) async {
// rootBundle: los archivos distribuidos con la aplicación (sección assets del pubspec)
final json = await rootBundle.loadString('assets/i18n/$language.json');
_dictionary = jsonDecode(json) as Map<String, Object?>;
_language = language;
await _storage?.setString('rdvmedecins.language', language);
notifyListeners();
}
// "HOME.HELLO" -> dictionary['HOME']['HELLO']; null si falta
String? _find(String key) {
Object? node = _dictionary;
for (final part in key.split('.')) {
node = node is Map<String, Object?> ? node[part] : null;
}
return node is String ? node : null;
}
String t(String key, [Map<String, Object?> params = const {}]) {
String? text;
final count = params['count'];
if (count is int) {
// Intl.pluralLogic: la forma plural, según las reglas del idioma
text = Intl.pluralLogic(
count,
locale: _language,
zero: _find('${key}_zero'),
one: _find('${key}_one'),
other: _find('${key}_other'),
);
}
text ??= _find(key);
// una clave desconocida se muestra tal cual: vemos de inmediato qué falta
if (text == null) return key;
// {{name}} -> el valor del parámetro name
return text.replaceAllMapped(RegExp(r'\{\{(\w+)\}\}'), (m) => '${params[m[1]] ?? m[0]}');
}
}
|
La clase [Translations] del ejemplo 21, simplificada: los diccionarios siempre tienen el mismo nombre ([assets/i18n/fr.json]).
- líneas 35–38: el idioma inicial: el seleccionado durante un uso anterior; de lo contrario, el idioma del teléfono si la aplicación lo conoce; de lo contrario, inglés. [platformDispatcher.locale]: el idioma del sistema;
- líneas 59–76: la traducción de una clave, incluidos los plurales ([_zero], [_one], [_other]) y los parámetros ([{{name}}]), según las convenciones de [i18next], que son las mismas que se usan en los diccionarios de los demás clientes.
11.8.2. Los diccionarios
Los diccionarios son los del cliente [React], complementados con algunas claves propias de la aplicación móvil (el menú “Mi cuenta”, “Elija el día”, etc.). El comienzo del diccionario en francés:
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace",
"LOADING": "Chargement...",
"LANGUAGE": "Langue",
"MENU_ACCOUNT": "Mon compte",
"CONNECTED_AS": "Connecté : {{name}}",
"RETRY": "Réessayer"
},
"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",
"CHOOSE_DAY": "Choisir le jour"
},
|
Un archivo por idioma, con las mismas claves en cada uno; un grupo de claves por pantalla; las claves [ERRORS.*] son las que devuelve el servidor.
11.9. El estado compartido
Tres [ChangeNotifier] entradas, proporcionadas a toda la aplicación por [main.dart].
11.9.1. lib/state/session.dart
| // =========================================================================
// lib/state/session.dart - ¿QUIÉN ha iniciado sesión?
// -------------------------------------------------------------------------
// El usuario que inició sesión (o null), en un ChangeNotifier provisto a toda la
// aplicación (provider, vea el ejemplo 20): legible por las pantallas Y por el
// enrutador, que lo escucha para reevaluar sus guardias (refreshListenable).
//
// El token JWT en sí NO está aquí: está en una cookie (gestionada por el
// navegador en la web, por CookieClient en el teléfono). La
// sesión solo guarda la DESCRIPCIÓN del usuario ({ login, name, role }).
//
// Cuando la aplicación arranca, la sesión está vacía: check() pregunta
// al servidor, una sola vez, quién ha iniciado sesión (GET /api/auth/me).
// =========================================================================
import 'package:flutter/foundation.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
class Session extends ChangeNotifier {
final RdvMedecinsApi _api;
User? _user;
// true después de un cierre de sesión DESEADO (botón, eliminación de la cuenta); false
// después de una sesión expirada. El enrutador lo tiene en cuenta (vea router.dart)
bool _voluntaryLogout = false;
// ¿ya se le hizo al servidor la pregunta "¿quién ha iniciado sesión?"?
Future<void>? _checking;
Session(this._api);
User? get user => _user;
bool get voluntaryLogout => _voluntaryLogout;
// solo pregunta al servidor la primera vez (se conserva el Future)
Future<void> check() => _checking ??= _api.me().then(
(u) => _change(u),
onError: (Object _) => _change(null), // 401: nadie; o servidor inaccesible
);
Future<void> logIn(String login, String password, String captchaId, String captcha) async {
_change(await _api.logIn(login, password, captchaId, captcha));
}
// el usuario cambió su nombre o su login (PUT /api/my-account)
void update(User u) => _change(u);
Future<void> logOut() async {
try {
await _api.logOut();
} finally {
forget(voluntary: true);
}
}
// sin preguntar nada al servidor: sesión expirada, cuenta eliminada
void forget({bool voluntary = false}) => _change(null, voluntary: voluntary);
// notifyListeners: el enrutador (refreshListenable) reevalúa sus guardias, y
// abandona por sí mismo una pantalla que el nuevo usuario no puede ver
void _change(User? u, {bool voluntary = false}) {
_user = u;
_voluntaryLogout = voluntary;
notifyListeners();
}
}
// lo que deducimos del usuario: extensiones ("getters" agregados a User?)
extension Rights on User? {
bool get isAdmin => this?.role == Role.admin;
bool get isPatient => this?.role == Role.user;
// ADMIN y DOCTOR: reservan y cancelan las citas de cualquier paciente
bool get isManager => this?.role == Role.admin || this?.role == Role.doctor;
// la página de inicio de cada rol, justo después de iniciar sesión
String get homePage => isPatient ? '/my-area' : '/schedule';
}
|
¿Quién tiene la sesión iniciada? La sesión guarda la DESCRIPCIÓN del usuario (nombre de usuario, nombre, rol), no el token, que permanece en la cookie del usuario.
- Líneas 36–38: la pregunta “¿quién tiene la sesión iniciada?” se envía al servidor ([GET /api/auth/me]) UNA sola vez, al inicio: [??=] solo asigna el [Future] si [_checking] es [null]. Las llamadas posteriores devuelven el mismo [Future], que ya se completó: el enrutador puede llamar a [check()] antes de cada navegación sin costo alguno. Al inicio, si la cookie guardada contiene un token todavía válido, el usuario conserva la sesión iniciada;
- líneas 41–42: la conexión: si el servidor la rechaza, [_api.logIn] lanza un [ApiError], y no se llama a [_change] ;
- líneas 48–52: cierre de sesión: se olvida al usuario aunque el servidor no responda ([finally]);
- líneas 61–64: todos los cambios pasan por aquí y notifican a los oyentes: las pantallas que muestran al usuario (el diseño), la caché (que se vacía) y el enrutador (que reevalúa sus guardias). [_voluntaryLogout] distingue entre un cierre de sesión intencional y una sesión vencida (véase [router.dart]);
- líneas 69–75: una extensión agrega getters a un tipo existente, en este caso a [User?]: [session.user.isAdmin] es [false] si nadie tiene la sesión iniciada, sin verificar antes si es [null] ([this?.role]).
11.9.2. lib/state/messages.dart
| // =========================================================================
// lib/state/messages.dart - los mensajes mostrados al usuario
// -------------------------------------------------------------------------
// Misma presentación que los otros clientes de RdvMedecins:
// - un ÉXITO se muestra en la parte SUPERIOR de la pantalla (banner verde);
// - un ERROR en la parte INFERIOR (banner rosado), siempre visible.
// Un mensaje es una CLAVE de traducción (+ sus parámetros): por lo tanto,
// se traduce de nuevo por sí solo si el usuario cambia de idioma.
//
// Los mensajes "flash": una acción que termina con un cambio de
// pantalla (reserva, alta de un médico...) deja su mensaje con
// flash(); se mostrará en la SIGUIENTE pantalla, y luego desaparecerá en la
// navegación posterior. Es el enrutador quien llama a newPage() al
// final de cada navegación (vea router.dart).
// =========================================================================
import 'package:flutter/foundation.dart';
import '../api/api_error.dart';
typedef Message = ({String key, Map<String, String> params});
class Messages extends ChangeNotifier {
Message? success;
Message? error;
// los mensajes que se mostrarán en la siguiente pantalla
Message? _pendingSuccess;
Message? _pendingError;
void showSuccess(String key, [Map<String, String> params = const {}]) {
success = (key: key, params: params);
error = null;
notifyListeners();
}
void showError(String key, [Map<String, String> params = const {}]) {
error = (key: key, params: params);
success = null;
notifyListeners();
}
// un ApiError -> el mensaje de la pantalla; cualquier otro error es un
// bug del cliente, que dejamos propagar
void showApiError(Object e) {
if (e is! ApiError) throw e;
showError(e.key, e.params);
}
void clear() {
success = null;
error = null;
notifyListeners();
}
// para la SIGUIENTE pantalla
void flash({bool success = true, required String key, Map<String, String> params = const {}}) {
if (success) {
_pendingSuccess = (key: key, params: params);
} else {
_pendingError = (key: key, params: params);
}
}
// una pantalla nueva: los mensajes de la anterior desaparecen, los mensajes
// flash aparecen
void newPage() {
success = _pendingSuccess;
error = _pendingError;
_pendingSuccess = null;
_pendingError = null;
notifyListeners();
}
}
|
Mensajes de la aplicación: un mensaje de éxito en la parte superior de la pantalla, un mensaje de error en la parte inferior (véase [layout.dart]).
- Línea 21: un mensaje es una CLAVE de traducción y sus parámetros (un solo registro). Solo se traduce al mostrarse: al cambiar el idioma se vuelven a traducir los mensajes mostrados;
- Líneas 44–46: un [ApiError] se convierte en el mensaje de error de la pantalla. Cualquier otra excepción es un problema del lado del cliente: la volvemos a lanzar para que aparezca en la consola durante el desarrollo, en lugar de ocultarla;
- líneas 56–60: un mensaje para la SIGUIENTE pantalla: una acción que termina con un cambio de pantalla (una reserva, una adición, etc.) coloca aquí su mensaje;
- líneas 66–71: se llama cada vez que cambia la dirección (véase [main.dart]): los mensajes de la pantalla anterior desaparecen y aparecen los mensajes flash.
11.9.3. lib/state/cache.dart
| // =========================================================================
// lib/state/cache.dart - los datos ya leídos del servidor
// -------------------------------------------------------------------------
// La lista de médicos casi nunca cambia: no hace falta leerla de nuevo en
// cada visita de la agenda. El caché conserva el Future de cada lectura,
// bajo una CLAVE ('doctors', 'schedule/1/2026-10-05'...):
//
// cache.read('doctors', () => api.list(PersonType.doctors))
//
// devuelve el Future ya conservado, o inicia la lectura y lo conserva.
// Después de un cambio, INVALIDAMOS las claves afectadas (se
// volverán a leer en la siguiente solicitud): cache.invalidate('schedule').
// Una lectura fallida no se conserva: la siguiente volverá a intentarlo.
// El caché es un ChangeNotifier: invalidate() notifica a sus oyentes. Una
// pantalla todavía viva (incluso oculta bajo otra en la pila, como
// la agenda bajo su diálogo de reserva) puede así volver a leer sus datos.
// Esto es, en pocas líneas, lo que hace la biblioteca TanStack Query del
// cliente React.
// =========================================================================
import 'package:flutter/foundation.dart';
class Cache extends ChangeNotifier {
final Map<String, Future<Object?>> _futures = {};
Future<T> read<T>(String key, Future<T> Function() load) {
final future = _futures.putIfAbsent(key, () {
final f = load();
// si falla, olvidamos este Future (la siguiente solicitud volverá a intentarlo)
f.then((_) {}, onError: (Object _) => _futures.remove(key));
return f;
});
return future.then((v) => v as T);
}
// olvida todas las claves que comienzan con prefix, y notifica a las pantallas
void invalidate(String prefix) {
_futures.removeWhere((key, _) => key.startsWith(prefix));
notifyListeners();
}
// cambio de usuario: olvidamos todo, SIN notificar (las pantallas del
// usuario anterior están por desaparecer, no deben volver a leer nada)
void clear() => _futures.clear();
}
|
Datos ya leídos del servidor: el equivalente, en pocas líneas, de [TanStack Query] en el cliente [React].
- Línea 24: la caché guarda [Future], no valores reales: dos pantallas que piden los mismos datos mientras están en tránsito reciben el MISMO [Future], y se envía una sola solicitud;
- Líneas 26–33: un método genérico: [read<List<Person>>(...)] devuelve un [Future<List<Person>>] (el tipo [T] casi siempre se infiere de la función [load]). [putIfAbsent]: el valor de la clave o, si la clave no existe, el resultado de la función, guardado bajo esa clave. Una lectura fallida se ignora: la siguiente solicitud volverá a intentarlo;
- líneas 37–39: tras una modificación, se descartan las claves afectadas y se notifica a las pantallas. La pantalla de la agenda escucha esto: después de una reserva, se vuelve a cargar, incluso si está oculta detrás de la ventana de reserva;
- línea 44: cuando cambia el usuario, todo se vacía sin notificar a nadie: las pantallas del usuario anterior desaparecerán; no tienen nada que recargar.
| // =========================================================================
// lib/formatting.dart - la presentación de horas y días
// -------------------------------------------------------------------------
// El servidor envía datos SIN PROCESAR (startHour: 8, startMinute: 0; day:
// "2026-10-05"); el formato, que depende del idioma, es asunto
// del cliente (vea el ejemplo 09).
// =========================================================================
import 'package:intl/intl.dart';
import 'api/types.dart';
String _twoDigits(int n) => n.toString().padLeft(2, '0');
// "8:05" en lugar de "8:5"
String time(int h, int m) => '$h:${_twoDigits(m)}';
// "8:00 - 8:20"
String timeRange(Slot s) => '${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}';
// una fecha -> "yyyy-MM-dd" (el formato de la API)
String toDay(DateTime d) => '${d.year}-${_twoDigits(d.month)}-${_twoDigits(d.day)}';
String today() => toDay(DateTime.now());
// true si day es una fecha que existe, en el formato yyyy-MM-dd
bool isValidDate(String day) {
if (!RegExp(r'^\d{4}-\d{2}-\d{2}$').hasMatch(day)) return false;
final d = DateTime.tryParse(day);
return d != null && toDay(d) == day; // 2026-02-30 -> 2026-03-02: rechazada
}
// "Monday, October 5, 2026" / "lundi 5 octobre 2026"
String longDate(String day, String language) => DateFormat.yMMMMEEEEd(language).format(DateTime.parse(day));
|
Formateo de los datos sin procesar del servidor (véase el ejemplo 09):
- línea 22: un [DateTime] en el formato de la API (“2026-10-05”);
- líneas 27–30: ¿es válida la fecha de la dirección? [DateTime.tryParse] acepta “2026-02-30” (2 de marzo): se verifica que esté presente la misma cadena;
- línea 34: “Monday, October 5, 2026” o “lundi 5 octobre 2026”, según el idioma ([DateFormat.yMMMMEEEEd] derivado de [intl]).
11.11. El enrutador
11.11.1. lib/router.dart
| // =========================================================================
// lib/router.dart - las pantallas de la aplicación y sus derechos de acceso
// -------------------------------------------------------------------------
// Las MISMAS direcciones que los otros clientes (/login, /schedule, /doctors,
// /my-area...). En la web, se muestran en la barra de direcciones;
// en el teléfono, permanecen invisibles, pero organizan la aplicación
// igual de bien (y la pila de pantallas del botón Atrás).
//
// Todas las pantallas están en un ShellRoute, cuyo widget, AppLayout, las muestra
// entre la barra superior y el panel de errores.
//
// Los GUARDIAS: la función redirect del GoRouter se llama antes de CADA
// navegación. Puede ser asíncrona: la primera vez (arranque de
// la aplicación, F5 en la web), espera la respuesta del servidor a la
// pregunta "¿quién ha iniciado sesión?" (session.check()). Luego verifica los
// derechos de la pantalla solicitada (rightsOf), y redirige si es necesario.
// RECORDATORIO: estas verificaciones son solo una COMODIDAD (no mostrar una
// pantalla inútil). La protección de los datos la garantiza el servidor, que
// verifica de nuevo el token y el rol en CADA solicitud.
// =========================================================================
import 'package:go_router/go_router.dart';
import 'api/rdvmedecins_api.dart';
import 'api/types.dart';
import 'state/messages.dart';
import 'state/session.dart';
import 'pages/schedule.dart';
import 'pages/login.dart';
import 'pages/patient_area.dart';
import 'pages/register.dart';
import 'pages/my_account.dart';
import 'pages/error_page.dart';
import 'pages/person_form.dart';
import 'pages/persons.dart';
import 'widgets/layout.dart';
// los derechos de acceso de una pantalla: pública (sin inicio de sesión), o reservada a
// ciertos roles (null: todos los roles con sesión iniciada)
typedef Rights = ({bool public, Set<Role>? roles});
Rights rightsOf(String path) => switch (path) {
'/login' || '/register' => (public: true, roles: null),
_ when path.startsWith('/doctors') || path.startsWith('/clients') => (public: false, roles: {Role.admin}),
'/my-area' || '/my-account' => (public: false, roles: {Role.user}),
'/schedule' || '/forbidden' || '/' => (public: false, roles: null),
_ => (public: true, roles: null), // dirección desconocida: la página 404, para todos
};
// solo una ruta INTERNA ("/doctors"): nunca "//other-site.com"
String? internalPath(String? r) => r != null && r.startsWith('/') && !r.startsWith('//') ? r : null;
// "3" -> 3; "", "abc", "-2", ausente (null) -> null
int? positiveInteger(String? value) {
final n = int.tryParse(value ?? '');
return n != null && n > 0 ? n : null;
}
GoRouter createRouter(Session session, Messages messages, RdvMedecinsApi api) {
// las tres pantallas de gestión de los médicos O de los clientes (ADMIN)
List<GoRoute> personRoutes(PersonType type) => [
GoRoute(
path: '/${type.name}',
builder: (_, _) => PersonsPage(type: type),
),
GoRoute(
path: '/${type.name}/add',
builder: (_, _) => PersonFormPage(type: type),
),
GoRoute(
path: '/${type.name}/:id/edit',
builder: (_, state) {
final id = positiveInteger(state.pathParameters['id']);
// /doctors/abc/edit: esta dirección no existe
return id == null ? const ErrorPage(code: 404) : PersonFormPage(type: type, id: id);
},
),
];
return GoRouter(
initialLocation: '/login',
// la sesión cambia (inicio, cierre de sesión, expiración): los guardias
// se reevalúan para la pantalla actual
refreshListenable: session,
redirect: (context, state) async {
await session.check();
final user = session.user;
final path = state.uri.path;
final rights = rightsOf(path);
if (rights.public) {
// sesión iniciada: la pantalla de inicio de sesión ya no tiene sentido. Es AQUÍ donde
// la dejamos, justo después de iniciar sesión: la sesión cambió, el enrutador
// (que la escucha) reevalúa sus guardias. Vamos a la pantalla solicitada antes del
// inicio de sesión (?redirect=...), de lo contrario a la página de inicio del rol
if (path == '/login' && user != null) {
return internalPath(state.uri.queryParameters['redirect']) ?? user.homePage;
}
return null;
}
if (user == null) {
// cierre de sesión deseado: la pantalla de inicio de sesión, simplemente
if (session.voluntaryLogout) return '/login';
// sesión expirada, dirección abierta sin haber iniciado sesión: recordamos
// la pantalla solicitada, para volver a ella después de iniciar sesión
return Uri(path: '/login', queryParameters: {'redirect': state.uri.toString()}).toString();
}
if (path == '/') return user.homePage;
if (rights.roles != null && !rights.roles!.contains(user.role)) return '/forbidden';
return null;
},
routes: [
ShellRoute(
builder: (context, state, child) => AppLayout(child: child),
routes: [
GoRoute(path: '/', builder: (_, _) => const ErrorPage(code: 404)), // (redirigido arriba)
GoRoute(
path: '/login',
builder: (_, state) {
// el login de la dirección: 30 caracteres como máximo
final login = state.uri.queryParameters['login'] ?? '';
return LoginPage(login: login.length > 30 ? login.substring(0, 30) : login);
},
),
GoRoute(
path: '/schedule',
builder: (_, state) => SchedulePage(
doctorId: positiveInteger(state.uri.queryParameters['doctorId']),
day: state.uri.queryParameters['day'],
book: positiveInteger(state.uri.queryParameters['book']),
),
),
...personRoutes(PersonType.doctors),
...personRoutes(PersonType.clients),
GoRoute(
path: '/register',
// un guardia ESPECÍFICO de esta ruta: sin un pase (captcha
// resuelto en la pantalla de inicio de sesión), de vuelta a la pantalla de inicio de sesión
redirect: (context, state) async {
final valid = await api.registrationAccessStatus().catchError((_) => false);
if (valid) return null;
messages.flash(success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
return '/login';
},
builder: (_, _) => const RegisterPage(),
),
GoRoute(path: '/my-area', builder: (_, _) => const PatientAreaPage()),
GoRoute(path: '/my-account', builder: (_, _) => const MyAccountPage()),
GoRoute(path: '/forbidden', builder: (_, _) => const ErrorPage(code: 403)),
],
),
],
// una dirección que ninguna ruta describe: la página 404, dentro del layout
errorBuilder: (context, state) => const AppLayout(child: ErrorPage(code: 404)),
);
}
|
Las pantallas de la aplicación, sus direcciones y sus derechos de acceso (véanse los ejemplos 17 y 18).
- línea 40: los derechos de acceso de una pantalla: pública, o restringida a ciertos roles ([null]: todos los roles);
- líneas 42–47: los permisos de cada dirección; en UN solo lugar: una expresión [switch] sobre cadenas. ['/login' || '/register']: un patrón “o”; [_ when ...]: un patrón “cualquier cosa”, con una condición (una guardia);
- línea 51: la dirección [?redirect=] solo se sigue si es una ruta INTERNA: en la web, una dirección [/login?redirect=//pirate-site.com] enviada por correo electrónico no debe llevar al usuario a otro sitio después de iniciar sesión;
- líneas 54–56: los parámetros de una dirección son cadenas, escritas por cualquiera (en la web): “abc” o “-2” se convierten en [null];
- líneas 61–78: una función local que genera las tres rutas para los médicos O los clientes: [/doctors], [/doctors/add], [/doctors/:id/edit]. [:id]: un parámetro de ruta, leído mediante [state.pathParameters['id']];
- línea 81: la pantalla inicial en el teléfono (en la web, es la dirección ingresada);
- línea 84: el enrutador vigila la sesión: con cada cambio (conexión, desconexión, expiración), vuelve a evaluar sus guardias para la pantalla actual y cambia de pantalla si es necesario;
- líneas 85–109: LA guardia, invocada antes de cada navegación:
- línea 86: la primera vez, se espera la respuesta del servidor a la pregunta “¿quién ha iniciado sesión?”; después, esta llamada no cuesta nada;
- líneas 90–98: una pantalla pública es accesible para todos; sin embargo, un usuario con sesión iniciada no tiene nada que hacer en la pantalla de inicio de sesión: se le envía a la pantalla que solicitó antes de iniciar sesión, o a la pantalla de inicio de su rol. Así es como la aplicación sale de la pantalla de inicio de sesión tras un inicio de sesión exitoso: la pantalla de inicio de sesión no necesita navegar por sí misma;
- líneas 100–105: nadie ha iniciado sesión: se pasa a la pantalla de inicio de sesión. Tras la expiración de una sesión, o si se abrió directamente una URL protegida (en la web), la pantalla solicitada ([?redirect=]) se conserva para que el usuario pueda volver a ella después de iniciar sesión; tras un cierre de sesión intencional, no se conserva;
- líneas 107–108: [/] lleva a la página de inicio del rol; un rol insuficiente lleva a una página 403;
- líneas 112–113: todas las pantallas se muestran dentro del layout (la barra superior, el menú, los mensajes);
- líneas 117–121: [/login?login=jbernard] (tras crear una cuenta) rellena previamente el campo de inicio de sesión;
- líneas 125–129: los tres parámetros del calendario, leídos de la URL; todo el estado de la pantalla está allí (véase [schedule.dart]);
- líneas 135–142: una guardia ESPECÍFICA de una ruta: la creación de una cuenta requiere un pase, que el servidor emite una vez que se ha ingresado el CAPTCHA ([POST /api/register/access], véase la pantalla de inicio de sesión). Sin él, se redirige a la pantalla de inicio de sesión con un mensaje;
- línea 153: una dirección no asociada a ninguna ruta: la página 404, dentro del layout.
Estas salvaguardas son solo una formalidad: evitan que se muestre una pantalla inútil. La protección de los datos la garantiza el servidor, que vuelve a verificar el token y el rol en cada solicitud.
| // =========================================================================
// lib/widgets/layout.dart - el LAYOUT común a todas las pantallas
// -------------------------------------------------------------------------
// El widget del ShellRoute del enrutador (vea router.dart):
// - la barra superior: título, idioma (FR / EN), cierre de sesión;
// - el menú lateral ("drawer", Drawer), abierto con el botón ☰: las
// pantallas permitidas para el rol del usuario. "Doctors" y "Patients"
// solo aparecen para el ADMIN: una simple comodidad de visualización,
// la protección real es la del servidor;
// - un mensaje de éxito en la parte SUPERIOR;
// - la pantalla actual (child);
// - el panel de errores en la parte INFERIOR.
// En una pantalla grande (web, tableta), el menú se muestra de forma permanente
// a la izquierda: un NavigationRail en lugar del drawer.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../state/messages.dart';
import '../state/session.dart';
import '../i18n/translations.dart';
// una entrada de menú: ruta, clave de la etiqueta, ícono
typedef MenuEntry = ({String path, String key, IconData icon});
List<MenuEntry> menuEntries(Session session) {
final u = session.user;
if (u == null) return const [];
return [
if (u.isPatient) (path: '/my-area', key: 'APP.MENU_MY_AREA', icon: Icons.home),
(path: '/schedule', key: 'APP.MENU_SCHEDULE', icon: Icons.calendar_month),
if (u.isAdmin) ...[
(path: '/doctors', key: 'APP.MENU_DOCTORS', icon: Icons.medical_services),
(path: '/clients', key: 'APP.MENU_PATIENTS', icon: Icons.people),
],
if (u.isPatient) (path: '/my-account', key: 'APP.MENU_ACCOUNT', icon: Icons.manage_accounts),
];
}
class AppLayout extends StatelessWidget {
final Widget child;
const AppLayout({super.key, required this.child});
@override
Widget build(BuildContext context) {
final translations = context.watch<Translations>();
final t = translations.t;
final session = context.watch<Session>();
final u = session.user;
final entries = menuEntries(session);
// la dirección actual, tal como la conoce el enrutador
final path = GoRouter.of(context).routerDelegate.currentConfiguration.uri.path;
final active = entries.indexWhere((e) => path.startsWith(e.path));
// MediaQuery: las dimensiones de la pantalla; a partir de 800 puntos, pantalla grande
final largeScreen = MediaQuery.sizeOf(context).width >= 800;
// la sesión queda vacía; el enrutador, que la escucha, muestra la pantalla de inicio de sesión
Future<void> logOut() => session.logOut().catchError((_) {}); // incluso si el servidor no responde
final content = Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
const _SuccessMessage(),
Expanded(child: child),
const _ErrorPanel(),
],
);
return Scaffold(
appBar: AppBar(
title: Text(t('APP.TITLE')),
backgroundColor: Theme.of(context).colorScheme.primary,
foregroundColor: Theme.of(context).colorScheme.onPrimary,
actions: [
// FR / EN: sin solicitud al servidor, la pantalla se traduce de nuevo en el acto
PopupMenuButton<String>(
tooltip: t('APP.LANGUAGE'),
// el texto, del color de los íconos de la barra (onPrimary)
icon: Text(
translations.language.toUpperCase(),
style: TextStyle(fontWeight: FontWeight.bold, color: Theme.of(context).colorScheme.onPrimary),
),
onSelected: translations.changeLanguage,
itemBuilder: (_) => [for (final l in languages) PopupMenuItem(value: l, child: Text(l.toUpperCase()))],
),
if (u != null) IconButton(tooltip: t('APP.LOGOUT'), icon: const Icon(Icons.logout), onPressed: logOut),
],
),
// el drawer: solo con la sesión iniciada, y solo en una pantalla pequeña
drawer: u == null || largeScreen
? null
: NavigationDrawer(
selectedIndex: active < 0 ? null : active,
onDestinationSelected: (i) {
Navigator.pop(context); // cierra el drawer
context.go(entries[i].path);
},
children: [
// el encabezado: quién ha iniciado sesión
Padding(
padding: const EdgeInsets.fromLTRB(28, 16, 16, 10),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(u.name, style: Theme.of(context).textTheme.titleMedium),
Chip(label: Text(u.role.name.toUpperCase())),
],
),
),
for (final e in entries) NavigationDrawerDestination(icon: Icon(e.icon), label: Text(t(e.key))),
],
),
body: u == null || !largeScreen
? content
: Row(
children: [
NavigationRail(
selectedIndex: active < 0 ? null : active,
labelType: NavigationRailLabelType.all,
onDestinationSelected: (i) => context.go(entries[i].path),
destinations: [
for (final e in entries) NavigationRailDestination(icon: Icon(e.icon), label: Text(t(e.key))),
],
),
const VerticalDivider(width: 1),
Expanded(child: content),
],
),
);
}
}
// el mensaje de éxito, en la parte superior
class _SuccessMessage extends StatelessWidget {
const _SuccessMessage();
@override
Widget build(BuildContext context) {
final success = context.watch<Messages>().success;
if (success == null) return const SizedBox.shrink();
final t = context.watch<Translations>().t;
return Material(
color: Colors.green.shade50,
child: ListTile(
leading: Icon(Icons.check_circle, color: Colors.green.shade700),
title: Text(t(success.key, success.params), style: TextStyle(color: Colors.green.shade900)),
trailing: IconButton(icon: const Icon(Icons.close), onPressed: context.read<Messages>().clear),
),
);
}
}
// el panel de errores, en la parte inferior: siempre visible, incluso si la pantalla se desplaza
class _ErrorPanel extends StatelessWidget {
const _ErrorPanel();
@override
Widget build(BuildContext context) {
final error = context.watch<Messages>().error;
if (error == null) return const SizedBox.shrink();
final t = context.watch<Translations>().t;
return Material(
color: const Color(0xFFF8D7DA),
// SafeArea: por encima de la barra de navegación del teléfono
child: SafeArea(
top: false,
child: ListTile(
leading: Icon(Icons.error, color: Colors.red.shade800),
title: Text(t(error.key, error.params), style: TextStyle(color: Colors.red.shade900)),
trailing: IconButton(icon: const Icon(Icons.close), onPressed: context.read<Messages>().clear),
),
),
);
}
}
|
El layout, el widget de [ShellRoute]: el elemento que rodea todas las pantallas.
- Línea 26: una entrada de menú: un registro;
- líneas 28–38: entradas permitidas para el rol del usuario, mediante un [if] en una lista (ejemplo 03). [...[...]]: el operador spread inserta varios elementos a la vez;
- línea 55: la dirección actual, para marcar la entrada activa del menú;
- línea 58: el ancho de la pantalla, en puntos. Por encima de 800 puntos (la web, una tableta en modo horizontal), el menú se muestra de forma permanente;
- línea 61: cierre de sesión: se borra la sesión, y el enrutador, que está a la escucha, muestra la pantalla de inicio de sesión. [catchError]: incluso si el servidor no responde, se considera que el usuario cerró sesión;
- líneas 63–68: el mensaje de éxito arriba, la pantalla en el medio ([Expanded]: todo el espacio restante), el error abajo;
- líneas 73–89: la barra superior: el título, el menú de idioma ([PopupMenuButton]: un botón que abre una lista; aquí su ícono es texto, “FR” o “EN”), el botón de cierre de sesión;
- líneas 93–113: en una pantalla pequeña, un panel lateral ([NavigationDrawer]), que se abre con el botón ☰ que [Scaffold] agrega automáticamente a la barra superior. Tocar una entrada cierra el panel ([Navigator.pop]) y cambia la URL;
- líneas 116–129: en una pantalla grande, un [NavigationRail]: el menú, dispuesto en una columna a la izquierda del contenido;
- líneas 137–154: el mensaje de éxito. [context.watch<Messages>()]: el widget se reconstruye cada vez que cambian los mensajes; cuando no hay mensajes, no ocupa espacio ([SizedBox.shrink]);
- líneas 168–169: la zona de errores está en la parte inferior de la pantalla: [SafeArea] la mantiene separada de la barra de navegación del teléfono (los botones o la barra de gestos de [Android]).
11.12.2. lib/widgets/page_title.dart
| // =========================================================================
// lib/widgets/page_title.dart - el título de la pantalla, traducido
// -------------------------------------------------------------------------
// En la web: el título de la pestaña; en Android: el nombre de la aplicación
// en la lista de aplicaciones recientes. "Schedule - RdvMedecins"
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../i18n/translations.dart';
class PageTitle extends StatelessWidget {
final String titleKey;
final Widget child;
const PageTitle({super.key, required this.titleKey, required this.child});
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
return Title(title: '${t(titleKey)} - ${t('APP.TITLE')}', color: Theme.of(context).colorScheme.primary, child: child);
}
}
|
El título de la pantalla, traducido ([Title], véase el ejemplo 02): el título de la pestaña en la web, el nombre de la aplicación en la lista de aplicaciones recientes de [Android].
| // =========================================================================
// lib/widgets/form_submit.dart - envío de un formulario al servidor
// -------------------------------------------------------------------------
// Todos los formularios de la aplicación siguen el mismo patrón que el
// ejemplo 25: no se verifica ninguna regla en el teléfono (viven
// en UN solo lugar, el servidor), y en caso de rechazo:
// - el error de cada campo (ApiError.fields) se muestra debajo del campo;
// - el mensaje general (ApiError.key) se muestra en la parte inferior de la pantalla.
// Esta clase agrupa estos pasos (es el Command del ejemplo 23,
// completado con los errores de los campos). Cada pantalla crea una por formulario:
//
// final _submit = FormSubmit(messages);
// if (await _submit.submit(() => api.register(input))) { ... }
// InputField(..., error: _submit.errors['lastName'])
// =========================================================================
import 'package:flutter/foundation.dart';
import '../api/api_error.dart';
import '../state/messages.dart';
class FormSubmit extends ChangeNotifier {
final Messages _messages;
// el error de cada campo: una CLAVE de traducción
Map<String, String> errors = {};
// los parámetros de los mensajes de error ({{min}}...), devueltos por el servidor
Map<String, String> params = {};
bool submitting = false;
FormSubmit(this._messages);
// ejecuta el envío; devuelve true si tuvo éxito. Ante un ApiError, los
// errores se muestran y devolvemos false
Future<bool> submit(Future<void> Function() action) async {
if (submitting) return false; // sin doble envío
errors = {};
params = {};
submitting = true;
notifyListeners();
try {
await action();
return true;
} on ApiError catch (e) {
_messages.showApiError(e);
errors = e.fields;
params = e.params;
return false;
} finally {
submitting = false;
notifyListeners();
}
}
// el usuario cambia un campo: su error desaparece
void clearError(String field) {
if (errors.containsKey(field)) {
errors = {...errors}..remove(field);
notifyListeners();
}
}
}
|
El envío de un formulario al servidor: el [Command] del ejemplo 23, complementado con errores de campo (ejemplo 25).
- líneas 34–50: envío: sin envíos duplicados; durante el envío, [submitting] (los botones se deshabilitan); ante un [ApiError], se muestran el mensaje general en la parte inferior de la pantalla y el error de cada campo. [finally] se ejecuta en todos los casos, incluso después de un [return];
- líneas 55–57: el usuario corrige un campo; el error desaparece. Se reemplaza el [Map] por una copia, en lugar de modificarlo: el anterior pudo haber sido proporcionado por el servidor ([e.fields]), y un [Map] constante ([const {}]) no cambia.
| // =========================================================================
// lib/widgets/input_field.dart - un campo de formulario completo
// -------------------------------------------------------------------------
// Etiqueta + campo + mensaje de ayuda O mensaje de error. Todos los
// formularios de la aplicación lo usan:
//
// InputField(label: 'PERSONS.LASTNAME_LABEL', maxLength: 20,
// value: _input['lastName'], onChanged: (v) => _edit('lastName', v),
// error: _submit.errors['lastName'])
//
// Es un widget CONTROLADO (vea el ejemplo 11): el valor pertenece al
// formulario padre; didUpdateWidget copia al campo un valor que
// el padre ha cambiado por sí mismo. label, help y error son CLAVES de
// traducción; params, los parámetros de sus mensajes ({{min}}...).
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../i18n/translations.dart';
class InputField extends StatefulWidget {
final String label;
final String value;
final ValueChanged<String> onChanged;
final String? error;
final String? help;
final Map<String, String> params;
final bool secret; // una contraseña: caracteres ocultos
final int? maxLength;
final bool autofocus;
final Iterable<String>? autofill; // para el administrador de contraseñas del teléfono
const InputField({
super.key,
required this.label,
required this.value,
required this.onChanged,
this.error,
this.help,
this.params = const {},
this.secret = false,
this.maxLength,
this.autofocus = false,
this.autofill,
});
@override
State<InputField> createState() => _InputFieldState();
}
class _InputFieldState extends State<InputField> {
late final _controller = TextEditingController(text: widget.value);
@override
void didUpdateWidget(InputField old) {
super.didUpdateWidget(old);
if (widget.value != _controller.text) _controller.text = widget.value;
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
final error = widget.error;
return Padding(
padding: const EdgeInsets.only(bottom: 8),
child: TextField(
controller: _controller,
obscureText: widget.secret,
autocorrect: !widget.secret,
autofocus: widget.autofocus,
maxLength: widget.maxLength,
autofillHints: widget.autofill,
decoration: InputDecoration(
labelText: t(widget.label),
errorText: error == null ? null : t(error, widget.params),
helperText: widget.help == null ? null : t(widget.help!, widget.params),
helperMaxLines: 2,
errorMaxLines: 3,
counterText: '', // sin contador "0/20" debajo del campo
),
onChanged: widget.onChanged,
),
);
}
}
|
Un campo de formulario completo: etiqueta, campo, texto de ayuda o mensaje de error. Todos los formularios lo usan.
- líneas 22–32: los parámetros. La etiqueta, el texto de ayuda y el mensaje de error son CLAVES de traducción;
- líneas 53–58: un widget controlado (ejemplo 11): el valor pertenece al padre. Si el padre lo cambia por sí mismo (el CAPTCHA se borra tras un fallo), [didUpdateWidget] lo vuelve a copiar en el campo;
- líneas 75–79: una contraseña se oculta, y el corrector ortográfico no interfiere; [autofillHints] le indica al administrador de contraseñas del teléfono qué contiene el campo (un nombre de usuario, una contraseña, una contraseña nueva);
- líneas 80–86: la etiqueta, el mensaje de error (que reemplaza el texto de ayuda) y el texto de ayuda. [maxLength] limita la entrada y mostraría un contador (“3/20”) debajo del campo; [counterText: ''] lo oculta.
| // =========================================================================
// lib/widgets/person_fields.dart - título, nombre, apellido
// -------------------------------------------------------------------------
// Los campos de identidad, comunes a tres formularios: el formulario de médico / cliente
// del ADMIN, "Create a patient account" y "Manage my account". El padre
// le pasa los valores, los errores y la función que cambia un campo:
// PersonFields(values: _input, errors: _submit.errors, onChanged: _edit)
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../i18n/translations.dart';
import 'input_field.dart';
const titles = ['Mr', 'Mme', 'Melle'];
class PersonFields extends StatelessWidget {
final Map<String, Object?> values;
final Map<String, String> errors;
final void Function(String field, String value) onChanged;
const PersonFields({super.key, required this.values, required this.errors, required this.onChanged});
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
final titleError = errors['title'];
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
// DropdownButtonFormField: una lista desplegable con etiqueta y error
DropdownButtonFormField<String>(
// key: si el código cambia el valor, el campo se vuelve a crear con él
key: ValueKey(values['title']),
initialValue: values['title'] as String,
decoration: InputDecoration(
labelText: t('PERSONS.TITLE_LABEL'),
errorText: titleError == null ? null : t(titleError),
),
items: [for (final title in titles) DropdownMenuItem(value: title, child: Text(title))],
onChanged: (title) => onChanged('title', title!),
),
const SizedBox(height: 8),
InputField(
label: 'PERSONS.FIRSTNAME_LABEL',
maxLength: 20,
value: values['firstName'] as String,
onChanged: (v) => onChanged('firstName', v),
error: errors['firstName'],
),
InputField(
label: 'PERSONS.LASTNAME_LABEL',
maxLength: 20,
value: values['lastName'] as String,
onChanged: (v) => onChanged('lastName', v),
error: errors['lastName'],
),
],
);
}
}
|
Los campos de identidad (título, nombre, apellido), comunes a los formularios de ADMIN, al formulario de creación de cuenta y al formulario “Administrar mi cuenta”.
- Línea 21: el padre pasa los valores, los errores y UNA función para modificar cualquier campo;
- líneas 33–42: el título, en una lista desplegable, con etiqueta y mensaje de error, como un campo de entrada. [initialValue] se lee solo cuando se crea el campo; la clave ([ValueKey]) lo vuelve a crear si el valor cambia mediante código.
| // =========================================================================
// lib/widgets/captcha_field.dart - la imagen del captcha y el campo de entrada
// -------------------------------------------------------------------------
// Un widget de visualización: la imagen (svg), el botón "Another image"
// (onReload), y el campo, CONTROLADO por el formulario padre (value,
// onChanged). La imagen y su identificador los solicita al servidor la
// página de inicio de sesión, que los necesita para enviar la respuesta.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';
import 'package:provider/provider.dart';
import '../i18n/translations.dart';
import 'input_field.dart';
class CaptchaField extends StatelessWidget {
final String? svg;
final String value;
final ValueChanged<String> onChanged;
final VoidCallback onReload;
final String? error;
const CaptchaField({
super.key,
required this.svg,
required this.value,
required this.onChanged,
required this.onReload,
this.error,
});
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(t('CAPTCHA.LABEL'), style: Theme.of(context).textTheme.bodySmall),
Row(
children: [
Container(
height: 54,
width: 160,
decoration: BoxDecoration(
color: const Color(0xFFF5F7FA),
border: Border.all(color: Colors.grey.shade300),
borderRadius: BorderRadius.circular(6),
),
// Semantics: lo que lee un lector de pantalla en lugar de la imagen
child: svg == null
? null
: Semantics(
label: t('CAPTCHA.IMAGE_ALT'),
child: SvgPicture.string(svg!, fit: BoxFit.contain),
),
),
TextButton.icon(
onPressed: onReload,
icon: const Icon(Icons.refresh),
label: Text(t('CAPTCHA.NEW_IMAGE')),
),
],
),
InputField(
label: 'CAPTCHA.LABEL',
help: 'CAPTCHA.HELP',
maxLength: 10,
value: value,
onChanged: onChanged,
error: error,
),
],
);
}
}
|
La imagen del CAPTCHA, el botón “Otra imagen” y el campo. El widget no llama al servidor: la pantalla de inicio de sesión solicita la imagen porque necesita su identificador para enviar la respuesta.
- líneas 51–53: la imagen SVG, recibida como texto ([SvgPicture.string], ejemplo 22). [Semantics]: lo que lee un lector de pantalla ([TalkBack] de [Android]) en lugar de la imagen.
| // =========================================================================
// lib/widgets/confirmation.dart - "Are you sure?"
// -------------------------------------------------------------------------
// Tomado del ejemplo 16. El mensaje es una CLAVE de traducción:
// if (await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) { ... }
// "No, go back" en lugar de "Cancel": la pregunta a veces es "Cancel this
// appointment?", y un botón "Cancel" sería ambiguo ahí. El foco está en
// "No": una pulsación distraída de Enter no elimina nada.
// Una nueva pregunta borra los mensajes de la acción anterior.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../state/messages.dart';
import '../i18n/translations.dart';
Future<bool> confirm(BuildContext context, String key) async {
context.read<Messages>().clear();
final t = context.read<Translations>().t;
final yes = await showDialog<bool>(
context: context,
builder: (context) => AlertDialog(
title: Text(t('CONFIRMATION.TITLE')),
content: Text(t(key)),
actions: [
TextButton(autofocus: true, onPressed: () => Navigator.pop(context, false), child: Text(t('CONFIRMATION.NO'))),
FilledButton(
style: FilledButton.styleFrom(backgroundColor: Colors.red.shade700),
onPressed: () => Navigator.pop(context, true),
child: Text(t('CONFIRMATION.YES')),
),
],
),
);
return yes ?? false;
}
|
La ventana de confirmación del ejemplo 16, traducida: [if (await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) ...]. El foco está en “No” ([autofocus]): en la web, presionar Enter por accidente no elimina nada.
| // =========================================================================
// lib/widgets/booking_dialog.dart - el diálogo de reserva de una franja
// -------------------------------------------------------------------------
// Una ventana sobre la agenda, con fondo gris incluido. NO se abre
// con showDialog: forma parte de la pantalla de la agenda, que
// la muestra cuando su DIRECCIÓN lo pide (/schedule?...&book=7, vea
// pages/schedule.dart). La dirección describe así toda la pantalla, diálogo incluido.
//
// El widget no habla con el servidor: llama a
// - onConfirm, con el paciente elegido (null para un paciente que reserva
// para sí mismo);
// - onClose.
// Es la pantalla de la agenda la que decide qué hacer con ellos.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../api/types.dart';
import '../i18n/translations.dart';
class BookingDialog extends StatefulWidget {
final String time; // "8:00 - 8:20"
final List<Person> clients; // ADMIN / DOCTOR: los pacientes entre los que elegir
final String? patient; // USER: el paciente es el propio usuario
final bool submitting;
final ValueChanged<int?> onConfirm;
final VoidCallback onClose;
const BookingDialog({
super.key,
required this.time,
required this.clients,
required this.patient,
required this.submitting,
required this.onConfirm,
required this.onClose,
});
@override
State<BookingDialog> createState() => _BookingDialogState();
}
class _BookingDialogState extends State<BookingDialog> {
int? _clientId;
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
final patient = widget.patient;
return Stack(
children: [
// ModalBarrier: el fondo gris; al tocarlo se cierra el diálogo
ModalBarrier(color: Colors.black54, onDismiss: widget.onClose),
Center(
child: Card(
margin: const EdgeInsets.all(24),
child: Padding(
padding: const EdgeInsets.all(20),
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Text(t('BOOKING_DIALOG.TITLE'), style: Theme.of(context).textTheme.titleLarge),
const SizedBox(height: 12),
Text(t('BOOKING_DIALOG.SLOT', {'time': widget.time})),
const SizedBox(height: 12),
// un paciente reserva para sí mismo: sin lista (y el servidor
// ignoraría de todos modos un posible clientId)
if (patient != null)
Text.rich(
TextSpan(
children: [
TextSpan(text: '${t('BOOKING_DIALOG.PATIENT_LABEL')}: '),
TextSpan(
text: patient,
style: const TextStyle(fontWeight: FontWeight.bold),
),
],
),
)
else
DropdownButtonFormField<int?>(
initialValue: _clientId,
isExpanded: true,
decoration: InputDecoration(labelText: t('BOOKING_DIALOG.PATIENT_LABEL')),
items: [
DropdownMenuItem(value: null, child: Text(t('BOOKING_DIALOG.CHOOSE_PATIENT'))),
for (final c in widget.clients) DropdownMenuItem(value: c.id, child: Text(c.label)),
],
onChanged: (id) => setState(() => _clientId = id),
),
const SizedBox(height: 20),
// OverflowBar: los botones lado a lado, uno debajo del otro si no caben
OverflowBar(
alignment: MainAxisAlignment.end,
spacing: 8,
children: [
TextButton(onPressed: widget.onClose, child: Text(t('BOOKING_DIALOG.CANCEL'))),
FilledButton(
onPressed: widget.submitting ? null : () => widget.onConfirm(_clientId),
child: Text(t('BOOKING_DIALOG.CONFIRM')),
),
],
),
],
),
),
),
),
],
);
}
}
|
La ventana de reserva de una franja horaria. NO se abre con [showDialog]: forma parte de la pantalla del calendario, que la muestra cuando su dirección lo solicita ([&book=7]).
- Líneas 23–28: el widget no se comunica con el servidor; recibe los datos que muestra, junto con dos funciones que se invocan para confirmar (con el paciente seleccionado) o cerrar;
- líneas 51–54: un [Stack] superpone sus hijos: primero, un [ModalBarrier]—con un fondo atenuado—que cubre toda la pantalla y bloquea los toques destinados al calendario (tocarlo cierra la ventana), seguido de la ventana en sí, centrada;
- líneas 70–91: un paciente hace una reserva para sí mismo: su nombre, sin lista. El ADMIN o el médico selecciona al paciente de una lista desplegable; la selección determina el estado de la ventana;
- líneas 95–102: los botones ([OverflowBar]: uno al lado del otro, o uno debajo del otro si no caben); “Confirmar” se deshabilita durante el envío.
11.13. Las pantallas
11.13.1. lib/pages/login.dart
| // =========================================================================
// lib/pages/login.dart - la pantalla de inicio de sesión (/login)
// -------------------------------------------------------------------------
// La misma pantalla que en los otros clientes: login, contraseña, captcha, y
// un segundo botón "Create a patient account" que verifica el MISMO captcha
// antes de abrir la creación de la cuenta.
//
// /login?login=jbernard: el campo login viene rellenado (justo después de la
// creación de una cuenta).
// Después de un inicio de sesión exitoso, esta pantalla NO navega por sí misma: la
// sesión cambia, y es el enrutador quien abandona la pantalla de inicio de sesión
// (hacia /login?redirect=... o la página de inicio del rol, vea router.dart).
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/messages.dart';
import '../state/session.dart';
import '../i18n/translations.dart';
import '../widgets/captcha_field.dart';
import '../widgets/input_field.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';
class LoginPage extends StatefulWidget {
final String login; // el login de la dirección (?login=...)
const LoginPage({super.key, this.login = ''});
@override
State<LoginPage> createState() => _LoginPageState();
}
class _LoginPageState extends State<LoginPage> {
late final _api = context.read<RdvMedecinsApi>();
late final _messages = context.read<Messages>();
late final _submit = FormSubmit(_messages);
late final Map<String, String> _input = {'login': widget.login, 'password': '', 'captcha': ''};
Captcha? _captcha;
@override
void initState() {
super.initState();
_reloadCaptcha();
}
@override
void dispose() {
_submit.dispose();
super.dispose();
}
// una imagen nueva: se necesita después de CADA intento, porque una imagen solo
// se puede usar UNA vez (el servidor la olvida en cuanto la ha verificado)
Future<void> _reloadCaptcha() async {
Captcha? captcha;
try {
captcha = await _api.captcha();
} catch (_) {
captcha = null; // servidor inaccesible: el inicio de sesión fallará con un mensaje claro
}
if (mounted) setState(() => _captcha = captcha);
}
void _edit(String field, String value) {
setState(() => _input[field] = value);
_submit.clearError(field);
}
// los dos botones comparten este flujo: envío y, si falla,
// mensaje de error y una imagen NUEVA
Future<void> _attempt(Future<void> Function() action) async {
_messages.clear();
final succeeded = await _submit.submit(action);
if (!succeeded && mounted) {
setState(() => _input['captcha'] = '');
await _reloadCaptcha();
}
}
// si tiene éxito, no hay nada más que hacer aquí: el enrutador cambia la pantalla
Future<void> _logIn() => _attempt(
() => context.read<Session>().logIn(
_input['login']!.trim(),
_input['password']!,
_captcha?.id ?? '',
_input['captcha']!,
),
);
Future<void> _createAccount() => _attempt(() async {
await _api.registrationAccess(_captcha?.id ?? '', _input['captcha']!);
if (mounted) context.go('/register');
});
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
return PageTitle(
titleKey: 'LOGIN.TITLE',
child: ListenableBuilder(
listenable: _submit,
builder: (context, _) => ListView(
padding: const EdgeInsets.all(16),
children: [
Text(t('LOGIN.TITLE'), style: Theme.of(context).textTheme.headlineSmall),
const SizedBox(height: 12),
// AutofillGroup: el administrador de contraseñas del teléfono puede completar el formulario
AutofillGroup(
child: Column(
children: [
InputField(
label: 'LOGIN.LOGIN_LABEL',
value: _input['login']!,
onChanged: (v) => _edit('login', v),
error: _submit.errors['login'],
autofill: const [AutofillHints.username],
),
InputField(
label: 'LOGIN.PASSWORD_LABEL',
secret: true,
value: _input['password']!,
onChanged: (v) => _edit('password', v),
error: _submit.errors['password'],
autofill: const [AutofillHints.password],
),
],
),
),
CaptchaField(
svg: _captcha?.svg,
value: _input['captcha']!,
onChanged: (v) => _edit('captcha', v),
onReload: _reloadCaptcha,
error: _submit.errors['captcha'],
),
const SizedBox(height: 8),
FilledButton(onPressed: _submit.submitting ? null : _logIn, child: Text(t('LOGIN.SUBMIT'))),
const SizedBox(height: 12),
OutlinedButton(onPressed: _submit.submitting ? null : _createAccount, child: Text(t('LOGIN.CREATE_ACCOUNT'))),
Padding(
padding: const EdgeInsets.only(top: 4),
child: Text(
t('LOGIN.CREATE_ACCOUNT_HELP'),
textAlign: TextAlign.center,
style: Theme.of(context).textTheme.bodySmall,
),
),
const SizedBox(height: 16),
_DemoAccounts(t: t),
],
),
),
);
}
}
// las cuentas de demostración
class _DemoAccounts extends StatelessWidget {
final String Function(String, [Map<String, Object?>]) t;
const _DemoAccounts({required this.t});
@override
Widget build(BuildContext context) {
const code = TextStyle(fontFamily: 'RobotoMono', fontSize: 12);
final style = Theme.of(context).textTheme.bodySmall!.copyWith(color: Colors.grey.shade700);
return DefaultTextStyle(
style: style,
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(t('LOGIN.DEMO_ACCOUNTS')),
for (final (accounts, roleKey) in [
('admin', 'LOGIN.DEMO_ADMIN'),
('pelissier, tatou, dupont', 'LOGIN.DEMO_DOCTOR'),
('martin, durand, bistrou, german', 'LOGIN.DEMO_USER'),
])
Text.rich(
TextSpan(
children: [
const TextSpan(text: '• '),
TextSpan(text: accounts, style: code),
TextSpan(text: ' - ${t(roleKey)}'),
],
),
),
],
),
);
}
}
|
La pantalla de inicio de sesión.
- Líneas 39–43: estado: la capa de acceso a la API y los mensajes (leídos UNA sola vez, [late]: en el primer uso), el envío del formulario, los datos ingresados (un [Map]: nombre del campo -> valor) y el CAPTCHA recibido;
- líneas 59–66: una imagen nueva, cuando se abre la pantalla, a solicitud y después de CADA intento (una imagen se usa una sola vez);
- líneas 76–81: ambos botones siguen esta secuencia: envío y, si no tiene éxito, se borra el CAPTCHA y se muestra una imagen nueva;
- líneas 86–93: inicio de sesión. Si tiene éxito, la pantalla no hace nada más: cambia la sesión, y el enrutador, que está a la escucha, sale de la pantalla de inicio de sesión (véase [router.dart]);
- líneas 95–97: “Crear una cuenta de paciente”: el servidor verifica el CAPTCHA y emite un token (una cookie); luego se abre la pantalla de creación de cuenta;
- líneas 105–106: la pantalla se vuelve a cargar cuando cambia el estado del envío (en curso, errores);
- líneas 113–129: [AutofillGroup] combina el nombre de usuario y la contraseña: el administrador de contraseñas del teléfono los rellena juntos y ofrece guardar la cuenta después del inicio de sesión;
- líneas 163–195: cuentas de demostración. [for (final (accounts, roleKey) in [...])]: un ciclo sobre una lista de registros, que se desestructuran sobre la marcha (ejemplo 03).
11.13.2. lib/pages/schedule.dart
| // =========================================================================
// lib/pages/schedule.dart - la pantalla de la agenda (/schedule)
// -------------------------------------------------------------------------
// Tres bloques, como en los otros clientes:
// 1. la elección del médico y del día;
// 2. la agenda de este médico en ese día;
// 3. el diálogo de reserva de una franja.
//
// TODO el estado de la pantalla está en su DIRECCIÓN:
// /schedule?doctorId=1&day=2026-10-05 la agenda
// /schedule?doctorId=1&day=2026-10-05&book=7 + el diálogo de reserva
// El enrutador pasa estos tres parámetros al widget; la pantalla DEDUCE
// de ellos lo que muestra, y las acciones del usuario cambian la dirección
// (context.go, context.push). En la web, por lo tanto, se puede recargar la página,
// guardarla en favoritos, usar Atrás / Adelante; en el teléfono, el
// botón Atrás cierra el diálogo de reserva.
//
// Lo que cada uno ve y puede hacer lo decide el SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada franja): la pantalla solo
// lo muestra. Un paciente ni siquiera recibe el nombre de los demás pacientes.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../state/session.dart';
import '../formatting.dart';
import '../i18n/translations.dart';
import '../widgets/confirmation.dart';
import '../widgets/booking_dialog.dart';
import '../widgets/page_title.dart';
// la dirección de la agenda (sin diálogo de reserva, o con él)
String scheduleAddress(int? doctorId, String day, [int? book]) => Uri(
path: '/schedule',
queryParameters: {'doctorId': '${doctorId ?? ''}', 'day': day, 'book': ?book?.toString()},
).toString();
class SchedulePage extends StatefulWidget {
final int? doctorId;
final String? day; // tal cual en la dirección: quizá no válido
final int? book;
const SchedulePage({super.key, this.doctorId, this.day, this.book});
@override
State<SchedulePage> createState() => _SchedulePageState();
}
class _SchedulePageState extends State<SchedulePage> {
late final _api = context.read<RdvMedecinsApi>();
late final _cache = context.read<Cache>();
late final _messages = context.read<Messages>();
Future<List<Person>>? _doctors;
List<Person> _clients = [];
Future<Schedule>? _schedule;
bool _submitting = false;
// el día: el de la dirección si es válido, de lo contrario hoy
bool get _invalidDay => widget.day != null && !isValidDate(widget.day!);
String get _day => widget.day != null && !_invalidDay ? widget.day! : today();
@override
void initState() {
super.initState();
final user = context.read<Session>().user;
_doctors = _cache.read('doctors', () => _api.list(PersonType.doctors));
// los pacientes: solo para quienes tienen permiso de leerlos (diálogo de reserva)
if (user.isManager) {
_cache.read('clients', () => _api.list(PersonType.clients)).then((c) {
if (mounted) setState(() => _clients = c);
}, onError: _messages.showApiError);
}
if (_invalidDay) {
// después de construir la pantalla: no cambiamos otro estado durante un build
WidgetsBinding.instance.addPostFrameCallback((_) => _messages.showError('ERRORS.INVALID_DATE'));
}
_loadSchedule();
// datos invalidados (reserva, cancelación): leemos de nuevo la agenda.
// Útil sobre todo para la pantalla oculta BAJO el diálogo de reserva (vea _confirmBooking)
_cache.addListener(_loadSchedule);
}
@override
void dispose() {
_cache.removeListener(_loadSchedule);
super.dispose();
}
// el enrutador reutiliza la pantalla con otra dirección (otro médico, otro día)
@override
void didUpdateWidget(SchedulePage old) {
super.didUpdateWidget(old);
if (old.doctorId != widget.doctorId || old.day != widget.day) _loadSchedule();
}
void _loadSchedule() {
final user = context.read<Session>().user;
// sin un médico en la dirección, un DOCTOR ve SU agenda (el servidor
// la encuentra a partir del token); los demás no ven nada
final withSchedule = !_invalidDay && (widget.doctorId != null || user?.role == Role.doctor);
setState(() {
_schedule = withSchedule
? _cache.read('schedule/${widget.doctorId}/$_day', () => _api.schedule(widget.doctorId, _day))
: null;
});
// una lectura fallida: su mensaje, en la parte inferior de la pantalla
_schedule?.then((_) {}, onError: (Object e) => _messages.showApiError(e));
}
// el servidor es la referencia: después de cada acción, leemos de nuevo la agenda
// (y el área del paciente, que muestra su cita). La invalidación
// notifica a todas las pantallas de agenda vivas, incluida esta (_loadSchedule)
void _reload() {
_cache.invalidate('my-area');
_cache.invalidate('schedule');
}
void _closeBooking(int? doctorId) {
if (context.canPop()) {
context.pop();
} else {
context.go(scheduleAddress(doctorId, _day));
}
}
Future<void> _confirmBooking(ScheduleSlot slot, int? doctorId, int? clientId) async {
final manager = context.read<Session>().user.isManager;
setState(() => _submitting = true);
try {
await _api.book(_day, slot.id, manager ? clientId : null);
_messages.flash(key: 'SCHEDULE.BOOKED');
} on ApiError catch (e) {
if (e.key == 'ERRORS.CHOOSE_PATIENT') {
// ningún paciente elegido: el diálogo permanece abierto
_messages.showError(e.key);
return; // (finally se ejecuta de todos modos)
}
// franja tomada mientras tanto, paciente que ya tiene una cita...: el
// mensaje se mostrará en la agenda, con el diálogo cerrado
_messages.flash(success: false, key: e.key, params: e.params);
} finally {
if (mounted) setState(() => _submitting = false);
}
if (!mounted) return;
_closeBooking(doctorId);
_reload();
}
Future<void> _cancel(ScheduleSlot s) async {
if (s.appointmentId == null || !await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) return;
try {
await _api.cancelAppointment(s.appointmentId!);
_messages.showSuccess('SCHEDULE.CANCELLED');
} on ApiError catch (e) {
_messages.showApiError(e);
}
if (mounted) _reload();
}
@override
Widget build(BuildContext context) {
final translations = context.watch<Translations>();
final t = translations.t;
final user = context.watch<Session>().user;
return PageTitle(
titleKey: 'SCHEDULE.PAGE_TITLE',
// FutureBuilder: la agenda (null mientras no haya llegado, o si no hay ninguna)
child: FutureBuilder<Schedule>(
future: _schedule,
builder: (context, state) {
final s = state.data;
// el médico mostrado: el de la dirección, o el de la agenda recibida (DOCTOR)
final doctorId = widget.doctorId ?? s?.doctor.id;
// la franja cuyo diálogo de reserva está abierto (&book=7),
// solo si este usuario puede reservarla
final toBook = s?.slots.where((c) => c.id == widget.book && c.bookable).firstOrNull;
// el mensaje del servidor para el paciente que ya tiene una cita próxima
// ("cancel it to book another one") no explica nada si ESTA
// cita está en la agenda mostrada: la vemos, bajo su nombre,
// con su botón "Cancel". Solo se muestra en las OTRAS agendas
final info = s != null && !s.slots.any((c) => c.mine) ? s.info : null;
final Widget content;
if (state.connectionState == ConnectionState.waiting) {
content = const Padding(
padding: EdgeInsets.all(24),
child: Center(child: CircularProgressIndicator()),
);
} else if (s != null) {
content = _Schedule(
schedule: s,
language: translations.language,
onBook: (c) => context.push(scheduleAddress(doctorId, _day, c.id)),
onCancel: _cancel,
);
} else {
content = Padding(padding: const EdgeInsets.all(16), child: Text(t('SCHEDULE.EMPTY_STATE')));
}
return Stack(
children: [
ListView(
padding: const EdgeInsets.all(12),
children: [
// 1. la elección del médico y del día. Su key cambia con la dirección:
// Flutter entonces lo vuelve a crear, y parte de los nuevos valores
FutureBuilder<List<Person>>(
future: _doctors,
builder: (context, doctors) => _DoctorDayPicker(
key: ValueKey('$doctorId|$_day'),
doctors: doctors.data ?? const [],
doctorId: doctorId,
day: _day,
onView: (id, day) => context.go(scheduleAddress(id, day)),
),
),
// paciente que ya tiene una cita próxima: por qué no hay botón "Book"
if (info != null)
Card(
color: Colors.lightBlue.shade50,
child: ListTile(
title: Text(t(info)),
trailing: TextButton(
onPressed: () => context.go('/my-area'),
child: Text(t('APP.MENU_MY_AREA')),
),
),
),
content,
],
),
// 3. el diálogo de reserva, solo si la dirección contiene &book=...
if (toBook != null)
BookingDialog(
time: timeRange(toBook),
clients: _clients,
patient: user.isPatient ? user!.name : null,
submitting: _submitting,
onConfirm: (clientId) => _confirmBooking(toBook, doctorId, clientId),
onClose: () => _closeBooking(doctorId),
),
],
);
},
),
);
}
}
// -------------------------------------------------------------------------
// 1. la elección del médico y del día: un formulario pequeño, cuyo estado
// solo es útil antes del envío. PARTE de los valores de la dirección.
// -------------------------------------------------------------------------
class _DoctorDayPicker extends StatefulWidget {
final List<Person> doctors;
final int? doctorId;
final String day;
final void Function(int? doctorId, String day) onView;
const _DoctorDayPicker({
super.key,
required this.doctors,
required this.doctorId,
required this.day,
required this.onView,
});
@override
State<_DoctorDayPicker> createState() => _DoctorDayPickerState();
}
class _DoctorDayPickerState extends State<_DoctorDayPicker> {
late int? _doctorId = widget.doctorId;
late String _day = widget.day;
Future<void> _pickDay() async {
final choice = await showDatePicker(
context: context,
initialDate: DateTime.parse(_day),
firstDate: DateTime(2020),
lastDate: DateTime(2035, 12, 31),
);
if (choice != null) setState(() => _day = toDay(choice));
}
@override
Widget build(BuildContext context) {
final translations = context.watch<Translations>();
final t = translations.t;
// el médico elegido debe estar en la lista (de lo contrario: ninguno)
final knownId = widget.doctors.any((d) => d.id == _doctorId) ? _doctorId : null;
return Card(
child: Padding(
padding: const EdgeInsets.all(12),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
DropdownButtonFormField<int?>(
key: ValueKey('${widget.doctors.length}/$knownId'),
initialValue: knownId,
isExpanded: true,
decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')),
items: [
DropdownMenuItem(value: null, child: Text(t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR'))),
for (final d in widget.doctors) DropdownMenuItem(value: d.id, child: Text(d.label)),
],
onChanged: (id) => setState(() => _doctorId = id),
),
const SizedBox(height: 8),
// el día: un botón que abre el calendario
InputDecorator(
decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DAY_LABEL')),
child: InkWell(
onTap: _pickDay,
child: Row(
children: [
Expanded(child: Text(longDate(_day, translations.language))),
const Icon(Icons.calendar_month),
],
),
),
),
const SizedBox(height: 12),
FilledButton(
onPressed: knownId == null ? null : () => widget.onView(knownId, _day),
child: Text(t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')),
),
],
),
),
);
}
}
// -------------------------------------------------------------------------
// 2. la agenda
// -------------------------------------------------------------------------
class _Schedule extends StatelessWidget {
final Schedule schedule;
final String language;
final ValueChanged<ScheduleSlot> onBook;
final ValueChanged<ScheduleSlot> onCancel;
const _Schedule({required this.schedule, required this.language, required this.onBook, required this.onCancel});
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
final s = schedule;
return Card(
child: Padding(
padding: const EdgeInsets.symmetric(vertical: 8),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
ListTile(
title: Text(
'${t('SCHEDULE.TITLE_PREFIX')} ${longDate(s.day, language)}',
style: Theme.of(context).textTheme.titleMedium,
),
subtitle: Text(s.doctor.label),
),
if (s.slots.isEmpty) Padding(padding: const EdgeInsets.all(16), child: Text(t('SCHEDULE.NO_SLOTS'))),
for (final c in s.slots) ...[
const Divider(height: 1),
ListTile(
// las franjas reservables tienen un ligero color
tileColor: c.bookable ? Colors.green.shade50 : null,
leading: SizedBox(
width: 96,
child: Text(timeRange(c), style: const TextStyle(fontWeight: FontWeight.w500)),
),
title: Align(
alignment: Alignment.centerLeft,
child: c.free
? _Badge(t('SCHEDULE.FREE'), Colors.green.shade700)
: c.patient != null
? _Badge(c.patient!.label, c.mine ? Colors.indigo : Colors.grey.shade600)
: _Badge(t('SCHEDULE.BOOKED_BY_OTHER'), Colors.grey.shade600),
),
// "Book" cambia la DIRECCIÓN (&book=...), lo que abre el diálogo de reserva
trailing: c.bookable
? OutlinedButton(onPressed: () => onBook(c), child: Text(t('SCHEDULE.BOOK')))
: c.appointmentId != null
? OutlinedButton(
style: OutlinedButton.styleFrom(foregroundColor: Colors.red.shade700),
onPressed: () => onCancel(c),
child: Text(t('SCHEDULE.CANCEL_APPOINTMENT')),
)
: null,
),
],
],
),
),
);
}
}
// una etiqueta de color (el "badge" de los otros clientes)
class _Badge extends StatelessWidget {
final String text;
final Color color;
const _Badge(this.text, this.color);
@override
Widget build(BuildContext context) {
return Container(
padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 3),
decoration: BoxDecoration(color: color, borderRadius: BorderRadius.circular(6)),
child: Text(
text,
style: const TextStyle(color: Colors.white, fontSize: 12, fontWeight: FontWeight.bold),
),
);
}
}
|
La pantalla con más funciones: selección de un médico y un día, el calendario y la ventana de reserva.
- líneas 40–43: la dirección del calendario. TODO el estado de la pantalla está contenido en su dirección; las acciones del usuario la modifican, y la pantalla determina qué mostrar a partir de ella;
- Líneas 66–67: el día tomado de la dirección, si es válido; de lo contrario, hoy;
- líneas 70–87: cuando se abre la pantalla: los médicos (desde el caché; se cargan una sola vez para toda la sesión), los pacientes si el usuario tiene permiso para verlos (para la ventana de reserva) y el calendario. Si la fecha de la dirección no es válida: se muestra un mensaje DESPUÉS de que se construye la pantalla ([addPostFrameCallback]: no se modifica otro estado durante la construcción de la pantalla). Por último, la pantalla lee del caché;
- líneas 98–100: “Ver agenda” cambia la dirección; el enrutador REUTILIZA la pantalla (misma ruta) con nuevos parámetros: [didUpdateWidget] vuelve entonces a leer el calendario;
- líneas 103–114: el caché lee la agenda. Si no hay ningún médico indicado en la dirección, un médico con sesión iniciada ve SU agenda (el servidor la obtiene mediante el token);
- líneas 120–122: tras una reserva o una cancelación, los datos del servidor tienen prioridad: se invalida el calendario (y el área del paciente); el caché notifica a las pantallas de calendario, que se recargan;
- líneas 125–129: cerrar la ventana: volver a la URL anterior. “Reservar” APILÓ la URL con [&book=] ([context.push]): se retrocede ([context.pop]), exactamente como lo hace el botón Atrás del teléfono. Si la pantalla se abrió directamente en esta dirección (en la web), no hay nada a lo que retroceder: se va a la dirección del calendario;
- líneas 133–153: la reserva de la cita. Si no hay ningún paciente seleccionado, la ventana permanece abierta y muestra el mensaje. Cualquier otra acción cierra la ventana, y el mensaje (de éxito o de error, como una franja horaria tomada mientras tanto...) aparece como mensaje emergente para el calendario. La pantalla de calendario que contiene la ventana desaparece; reaparece la que está debajo, gracias al caché;
- líneas 156–164: cancelación, tras la confirmación;
- líneas 176–184: la pantalla muestra el calendario ([FutureBuilder]). La franja horaria de la ventana de reserva es la de la dirección ([&book=7]), solo si puede ser reservada POR ESTE USUARIO (una franja tomada mientras tanto, una dirección creada manualmente: sin ventana);
- línea 189: el servidor envía este mensaje ([info]) junto con TODOS los calendarios; pero en el calendario que contiene la cita del paciente (una franja horaria [mine]), es innecesario, e incluso engañoso, inmediatamente después de una reserva: el paciente ve su cita, listada bajo su nombre, con un botón “Cancelar”. Por lo tanto, solo se muestra en los demás calendarios. [s.slots.any((c) => c.mine)]: verdadero si al menos una franja horaria cumple la condición;
- líneas 201–202: “Reservar” apila la dirección de la ventana;
- líneas 215–222: selección del médico y del día. Su clave contiene el médico y el día de la URL: cuando cambia la URL (el botón Atrás del teléfono, el botón Atrás del navegador), [Flutter] vuelve a crear el widget, que empieza de nuevo con los nuevos valores;
- líneas 226–233: un paciente que ya tiene una próxima cita: por qué no hay botón “Reservar” (véase [info], arriba);
- líneas 241–248: la ventana de reserva, sobre el calendario (en [Stack]);
- líneas 280–291: selección del médico y del día: un formulario breve, cuyo estado COMIENZA con los valores de la dirección. [late int? _doctorId = widget.doctorId;]: un campo inicializado a partir de [widget], posible gracias a [late]. [showDatePicker] abre el calendario de [Material] en el idioma de la aplicación;
- líneas 319–326: el día se muestra como un campo de entrada ([InputDecorator]: la etiqueta y el borde de un campo, que rodean cualquier widget), que se toca para abrir el calendario;
- líneas 346–406: la agenda. Una línea por franja horaria: la hora, una etiqueta (texto personalizado, el nombre del paciente o “Reservado” para otro paciente) y el botón habilitado por el SERVIDOR ([bookable], [appointmentId]).
11.13.3. lib/pages/persons_config.dart
| // =========================================================================
// lib/pages/persons_config.dart - ¿médicos o clientes?
// -------------------------------------------------------------------------
// Las pantallas de gestión de los médicos y de los clientes son IDÉNTICAS: la misma
// lista, el mismo formulario. Las escribimos UNA sola vez (persons.dart,
// person_form.dart); solo cambian la dirección de la API y las
// claves de las etiquetas, descritas aquí. El enrutador pasa el tipo a cada pantalla.
// =========================================================================
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
typedef PersonKeys = ({
String title, // "Doctors"
String add, // "Add a doctor"
String edit, // "Edit a doctor"
String empty, // "No doctors."
String confirmDelete,
String added, // "Doctor {{name}} has been added (login: {{login}})."
String edited,
String deleted,
String notFound, // el registro fue eliminado mientras tanto
});
PersonKeys keys(PersonType type) => switch (type) {
PersonType.doctors => (
title: 'DOCTORS.TITLE',
add: 'DOCTORS.ADD',
edit: 'DOCTORS.EDIT',
empty: 'DOCTORS.EMPTY',
confirmDelete: 'DOCTORS.DELETE_CONFIRM',
added: 'DOCTORS.ADDED',
edited: 'DOCTORS.UPDATED',
deleted: 'DOCTORS.DELETED',
notFound: 'ERRORS.DOCTOR_NOT_FOUND',
),
PersonType.clients => (
title: 'CLIENTS.TITLE',
add: 'CLIENTS.ADD',
edit: 'CLIENTS.EDIT',
empty: 'CLIENTS.EMPTY',
confirmDelete: 'CLIENTS.DELETE_CONFIRM',
added: 'CLIENTS.ADDED',
edited: 'CLIENTS.UPDATED',
deleted: 'CLIENTS.DELETED',
notFound: 'ERRORS.PATIENT_NOT_FOUND',
),
};
// {{name}} y {{login}} de los mensajes "added / updated / deleted"
Map<String, String> messageParams(Person p) => {'name': '${p.firstName} ${p.lastName}', 'login': p.login ?? ''};
|
Las pantallas de médicos y clientes son idénticas; solo difieren las claves de las etiquetas, que se describen aquí.
- líneas 13–22: un registro con campos con nombre, que contiene las claves de un tipo de persona;
- líneas 25–37: una expresión sobre una enumeración: [Dart] garantiza que se manejen todos los casos. Agregar un valor a [PersonType] provocaría aquí un error de compilación;
- línea 51: los parámetros de los mensajes de “agregado”, “modificado” y “eliminado”.
11.13.4. lib/pages/persons.dart
| // =========================================================================
// lib/pages/persons.dart - la lista de los médicos O de los clientes (ADMIN)
// -------------------------------------------------------------------------
// Una pantalla para ambos: el tipo (médicos o clientes) llega como
// parámetro (vea router.dart); las etiquetas específicas de cada uno están en
// persons_config.dart.
// En un teléfono, una tabla de cinco columnas no cabe: una línea de lista
// por persona (nombre, login), con sus dos botones; el botón redondo
// "+" (FloatingActionButton) agrega una persona.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../i18n/translations.dart';
import '../widgets/confirmation.dart';
import '../widgets/page_title.dart';
import 'persons_config.dart';
class PersonsPage extends StatefulWidget {
final PersonType type;
const PersonsPage({super.key, required this.type});
@override
State<PersonsPage> createState() => _PersonsPageState();
}
class _PersonsPageState extends State<PersonsPage> {
late final _api = context.read<RdvMedecinsApi>();
late final _cache = context.read<Cache>();
late final _messages = context.read<Messages>();
Future<List<Person>>? _list;
@override
void initState() {
super.initState();
_load();
}
// el enrutador reutiliza la pantalla para el otro tipo (/doctors -> /clients)
@override
void didUpdateWidget(PersonsPage old) {
super.didUpdateWidget(old);
if (old.type != widget.type) _load();
}
void _load() {
final type = widget.type;
setState(() {
_list = _cache.read(type.name, () => _api.list(type));
});
_list!.then((_) {}, onError: (Object e) => _messages.showApiError(e));
}
Future<void> _delete(Person p) async {
final k = keys(widget.type);
if (!await confirm(context, k.confirmDelete)) return;
try {
await _api.remove(widget.type, p.id);
_messages.showSuccess(k.deleted, messageParams(p));
} on ApiError catch (e) {
// un médico que todavía tiene citas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
_messages.showApiError(e);
}
_cache.invalidate(widget.type.name);
if (mounted) _load();
}
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
final k = keys(widget.type);
final type = widget.type.name;
return PageTitle(
titleKey: k.title,
// un Scaffold DENTRO del layout: para su botón flotante
child: Scaffold(
floatingActionButton: FloatingActionButton.extended(
onPressed: () => context.go('/$type/add'),
icon: const Icon(Icons.add),
label: Text(t(k.add)),
),
body: FutureBuilder<List<Person>>(
future: _list,
builder: (context, state) {
final list = state.data;
if (list == null) {
// todavía no cargado (o carga fallida: el mensaje está en la parte inferior de la pantalla)
return state.hasError ? const SizedBox.shrink() : const Center(child: CircularProgressIndicator());
}
return ListView(
// espacio en la parte inferior, para no ocultar la última línea bajo el botón flotante
padding: const EdgeInsets.fromLTRB(8, 8, 8, 88),
children: [
Padding(
padding: const EdgeInsets.all(8),
child: Text(t(k.title), style: Theme.of(context).textTheme.headlineSmall),
),
if (list.isEmpty) ListTile(title: Text(t(k.empty))),
for (final p in list)
Card(
child: ListTile(
leading: CircleAvatar(child: Text('${p.firstName[0]}${p.lastName[0]}')),
title: Text(p.label),
subtitle: Text(p.login ?? '', style: const TextStyle(fontFamily: 'RobotoMono')),
trailing: Row(
mainAxisSize: MainAxisSize.min,
children: [
IconButton(
tooltip: t('PERSONS.EDIT'),
icon: const Icon(Icons.edit),
onPressed: () => context.go('/$type/${p.id}/edit'),
),
IconButton(
tooltip: t('PERSONS.DELETE'),
icon: Icon(Icons.delete_outline, color: Colors.red.shade700),
onPressed: () => _delete(p),
),
],
),
),
),
],
);
},
),
),
);
}
}
|
La lista de médicos o clientes.
- líneas 54–59: la lista, desde el caché. Cuidado con las llaves en [setState(() { ... })]: escrita con una flecha, [setState(() => _list = ...)], la función DEVOLVERÍA el valor asignado, en este caso un [Future], y [setState] rechaza una función que devuelve un [Future] (la actualización del estado debe ser sincrónica): [Flutter] lo señala con un error;
- líneas 62–73: eliminación, tras la confirmación. El servidor rechaza a un médico con citas (409 [DOCTOR_HAS_APPOINTMENTS]);
- líneas 84–88: un [Scaffold] dentro del [Scaffold] del layout, para su botón flotante “+ Agregar” ([FloatingActionButton]) en la esquina inferior derecha;
- líneas 107–124: un elemento de lista por persona ([ListTile]): un avatar con sus iniciales, nombre, nombre de usuario y dos botones. Una tabla de cinco columnas, como la de los clientes web, no cabría en un teléfono.
11.13.5. lib/pages/person_form.dart
| // =========================================================================
// lib/pages/person_form.dart - creación O actualización de un
// médico o de un cliente (ADMIN)
// -------------------------------------------------------------------------
// /doctors/add -> creación (sin id)
// /doctors/3/edit -> actualización (id = 3)
// (y las mismas direcciones bajo /clients).
//
// Dos widgets:
// - PersonFormPage lee el registro por actualizar (si lo hay);
// - _Form solo se muestra una vez leído el registro: PARTE de
// sus valores (estado inicial), sin tener que copiarlos después.
// Aquí no se verifica ninguna regla: el servidor valida todo, y sus errores
// se muestran debajo de los campos (vea widgets/form_submit.dart).
// La VERSIÓN leída con el registro vuelve con la actualización: si otro
// ADMIN lo cambió mientras tanto, el servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../i18n/translations.dart';
import '../widgets/input_field.dart';
import '../widgets/person_fields.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';
import 'persons_config.dart';
const _empty = <String, Object?>{'title': 'Mr', 'firstName': '', 'lastName': '', 'login': '', 'password': ''};
class PersonFormPage extends StatefulWidget {
final PersonType type;
final int? id; // null: creación
const PersonFormPage({super.key, required this.type, this.id});
@override
State<PersonFormPage> createState() => _PersonFormPageState();
}
class _PersonFormPageState extends State<PersonFormPage> {
Future<Person>? _details;
@override
void initState() {
super.initState();
final id = widget.id;
if (id != null) {
// actualización: leemos el registro (incluida su versión), SIN caché: debe
// estar al día (de lo contrario el formulario partiría con una versión
// desactualizada: 409 CONCURRENT_UPDATE)
_details = context.read<RdvMedecinsApi>().read(widget.type, id);
// registro que no existe (eliminado mientras tanto...): de vuelta a la lista
_details!.then(
(_) {},
onError: (Object e) {
if (e is! ApiError || !mounted) return;
context.read<Messages>().flash(success: false, key: e.key, params: e.params);
context.go('/${widget.type.name}');
},
);
}
}
@override
Widget build(BuildContext context) {
final k = keys(widget.type);
return PageTitle(
titleKey: widget.id == null ? k.add : k.edit,
child: widget.id == null
? _Form(type: widget.type, id: null, initial: _empty)
: FutureBuilder<Person>(
future: _details,
builder: (context, state) {
final p = state.data;
if (p == null) return const Center(child: CircularProgressIndicator());
return _Form(
type: widget.type,
id: p.id,
initial: {
'title': p.title,
'firstName': p.firstName,
'lastName': p.lastName,
'login': p.login ?? '',
'password': '',
'version': p.version,
},
);
},
),
);
}
}
// el formulario en sí
class _Form extends StatefulWidget {
final PersonType type;
final int? id;
final Map<String, Object?> initial;
const _Form({required this.type, required this.id, required this.initial});
@override
State<_Form> createState() => _FormState();
}
class _FormState extends State<_Form> {
late final _messages = context.read<Messages>();
late final _submit = FormSubmit(_messages);
// una COPIA modificable de los valores iniciales
late final Map<String, Object?> _input = {...widget.initial};
bool get _creating => widget.id == null;
@override
void dispose() {
_submit.dispose();
super.dispose();
}
void _edit(String field, String value) {
setState(() => _input[field] = value);
_submit.clearError(field);
}
Future<void> _save() async {
final api = context.read<RdvMedecinsApi>();
final cache = context.read<Cache>();
final k = keys(widget.type);
final succeeded = await _submit.submit(() async {
final id = widget.id;
final p = id == null ? await api.add(widget.type, _input) : await api.edit(widget.type, id, _input);
_messages.flash(key: _creating ? k.added : k.edited, params: messageParams(p));
});
if (!mounted) return;
final errorKey = _messages.error?.key;
if (succeeded) {
cache.invalidate(widget.type.name); // la lista cambió
context.go('/${widget.type.name}');
} else if (errorKey == k.notFound) {
// eliminado mientras tanto por otro ADMIN: de vuelta a la lista
_messages.flash(success: false, key: errorKey!);
context.go('/${widget.type.name}');
}
}
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
final k = keys(widget.type);
return ListenableBuilder(
listenable: _submit,
builder: (context, _) => ListView(
padding: const EdgeInsets.all(16),
children: [
Text(t(_creating ? k.add : k.edit), style: Theme.of(context).textTheme.headlineSmall),
const SizedBox(height: 8),
PersonFields(values: _input, errors: _submit.errors, onChanged: _edit),
const SizedBox(height: 16),
Text(t('PERSONS.ACCOUNT_SECTION'), style: Theme.of(context).textTheme.titleSmall),
InputField(
label: 'PERSONS.LOGIN_LABEL',
maxLength: 30,
value: _input['login'] as String,
onChanged: (v) => _edit('login', v),
error: _submit.errors['login'],
help: _creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT',
),
// nunca rellenado: la contraseña nunca regresa del servidor
InputField(
label: 'PERSONS.PASSWORD_LABEL',
secret: true,
maxLength: 72,
value: _input['password'] as String,
onChanged: (v) => _edit('password', v),
error: _submit.errors['password'],
params: _submit.params,
help: _creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT',
),
const SizedBox(height: 16),
Wrap(
spacing: 8,
children: [
FilledButton(onPressed: _submit.submitting ? null : _save, child: Text(t('PERSONS.SAVE'))),
OutlinedButton(onPressed: () => context.go('/${widget.type.name}'), child: Text(t('PERSONS.BACK'))),
],
),
],
),
);
}
}
|
Agregar o modificar un médico o un cliente.
- líneas 54–65: para hacer una modificación, se lee el registro; SIN caché: su versión debe estar actualizada. Si no se encuentra un registro (eliminado mientras tanto): se vuelve a la lista con un mensaje;
- líneas 78–92: el formulario se muestra solo después de haber leído el registro, y COMIENZA con sus valores; el usuario nunca tiene que volver a ingresarlos después;
- línea 117: una COPIA modificable de los valores iniciales ([...]: el operador de descomposición, dentro de un [Map]);
- líneas 132–149: el registro: [POST] o [PUT], según haya o no un identificador. El mensaje de éxito es un mensaje flash: aparecerá en la lista. Si otro ADMIN eliminó mientras tanto un registro: se vuelve a la lista;
- líneas 167–184: el nombre de usuario y la contraseña, con mensajes de ayuda distintos para la creación y la modificación (dejar en blanco el campo de la contraseña no cambia la contraseña). La contraseña nunca se rellena previamente: el servidor nunca la devuelve.
11.13.6. lib/pages/register.dart
| // =========================================================================
// lib/pages/register.dart - "Create a patient account" (/register)
// -------------------------------------------------------------------------
// Solo llegamos aquí después de haber copiado el captcha de la pantalla de inicio de sesión
// (botón "Create a patient account"): el servidor entonces emitió un
// pase (una cookie), que el guardia de la ruta verificó (vea
// router.dart). Los mismos campos que el formulario del ADMIN, pero el login
// y la contraseña son obligatorios, con confirmación.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../api/rdvmedecins_api.dart';
import '../state/messages.dart';
import '../i18n/translations.dart';
import '../widgets/input_field.dart';
import '../widgets/person_fields.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';
// longitud mínima de una contraseña elegida por un paciente: el mismo valor
// que en el servidor (que también devuelve {min} con el error PASSWORD_TOO_SHORT)
const passwordMin = '6';
class RegisterPage extends StatefulWidget {
const RegisterPage({super.key});
@override
State<RegisterPage> createState() => _RegisterPageState();
}
class _RegisterPageState extends State<RegisterPage> {
late final _messages = context.read<Messages>();
late final _submit = FormSubmit(_messages);
final Map<String, Object?> _input = {
'title': 'Mr',
'firstName': '',
'lastName': '',
'login': '',
'password': '',
'confirmation': '',
};
@override
void dispose() {
_submit.dispose();
super.dispose();
}
void _edit(String field, String value) {
setState(() => _input[field] = value);
_submit.clearError(field);
}
Future<void> _create() async {
final api = context.read<RdvMedecinsApi>();
var login = '';
final succeeded = await _submit.submit(() async => login = await api.register(_input));
if (!mounted) return;
if (succeeded) {
// de vuelta a la pantalla de inicio de sesión, con el login rellenado
_messages.flash(key: 'REGISTRATION.DONE', params: {'login': login});
context.go(Uri(path: '/login', queryParameters: {'login': login}).toString());
} else if (_messages.error?.key == 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
// pase expirado (15 minutos): de vuelta al captcha
_messages.flash(success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
context.go('/login');
}
}
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
// los parámetros del mensaje de ayuda Y de los errores de contraseña
final passwordParams = {'min': passwordMin, ..._submit.params};
return PageTitle(
titleKey: 'REGISTRATION.TITLE',
child: ListenableBuilder(
listenable: _submit,
builder: (context, _) => ListView(
padding: const EdgeInsets.all(16),
children: [
Text(t('REGISTRATION.TITLE'), style: Theme.of(context).textTheme.headlineSmall),
Text(t('REGISTRATION.INTRO'), style: const TextStyle(color: Colors.grey)),
const SizedBox(height: 8),
PersonFields(values: _input, errors: _submit.errors, onChanged: _edit),
const SizedBox(height: 16),
Text(t('PERSONS.ACCOUNT_SECTION'), style: Theme.of(context).textTheme.titleSmall),
InputField(
label: 'PERSONS.LOGIN_LABEL',
maxLength: 30,
value: _input['login'] as String,
onChanged: (v) => _edit('login', v),
error: _submit.errors['login'],
help: 'REGISTRATION.LOGIN_HELP',
autofill: const [AutofillHints.newUsername],
),
InputField(
label: 'PERSONS.PASSWORD_LABEL',
secret: true,
maxLength: 72,
value: _input['password'] as String,
onChanged: (v) => _edit('password', v),
error: _submit.errors['password'],
params: passwordParams,
help: 'REGISTRATION.PASSWORD_HELP',
autofill: const [AutofillHints.newPassword],
),
InputField(
label: 'ACCOUNT.CONFIRMATION_LABEL',
secret: true,
maxLength: 72,
value: _input['confirmation'] as String,
onChanged: (v) => _edit('confirmation', v),
error: _submit.errors['confirmation'],
),
const SizedBox(height: 16),
Wrap(
spacing: 8,
children: [
FilledButton(onPressed: _submit.submitting ? null : _create, child: Text(t('REGISTRATION.SUBMIT'))),
OutlinedButton(onPressed: () => context.go('/login'), child: Text(t('REGISTRATION.BACK_TO_LOGIN'))),
],
),
],
),
),
);
}
}
|
Creación de una cuenta de paciente, accesible con el pase emitido por la pantalla de inicio de sesión (véase la guardia de la ruta en [router.dart]).
- línea 25: la longitud mínima de la contraseña; para el mensaje de ayuda: el mismo valor que el servidor (que también lo devuelve con el error [PASSWORD_TOO_SHORT]);
- líneas 57–69: creación. Si tiene éxito: vuelve a la pantalla de inicio de sesión, con el nombre de usuario rellenado previamente ([/login?login=...]), junto con un mensaje emergente. Si falla porque el pase expiró (15 minutos): vuelve al CAPTCHA. Cualquier otro error permanece visible debajo de los campos;
- línea 77: los parámetros del mensaje de ayuda y del error de contraseña ([{{min}}]);
- líneas 98–109: una cuenta NUEVA: el administrador de contraseñas puede sugerir una contraseña segura y guardarla.
11.13.7. lib/pages/patient_area.dart
| // =========================================================================
// lib/pages/patient_area.dart - "My area" (/my-area, rol USER)
// -------------------------------------------------------------------------
// La pantalla de inicio del paciente, justo después de iniciar sesión:
// - dos opciones: [Manage my account] y [View a schedule];
// - su próxima cita, si tiene una, con el medio para cancelarla.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../formatting.dart';
import '../i18n/translations.dart';
import '../widgets/confirmation.dart';
import '../widgets/page_title.dart';
import 'schedule.dart';
class PatientAreaPage extends StatefulWidget {
const PatientAreaPage({super.key});
@override
State<PatientAreaPage> createState() => _PatientAreaPageState();
}
class _PatientAreaPageState extends State<PatientAreaPage> {
late final _api = context.read<RdvMedecinsApi>();
late final _cache = context.read<Cache>();
late final _messages = context.read<Messages>();
Future<MyArea>? _area;
@override
void initState() {
super.initState();
_load();
}
void _load() {
// llaves: una función de flecha DEVOLVERÍA el Future asignado, y
// setState rechaza una función que devuelve un Future
setState(() {
_area = _cache.read('my-area', _api.myArea);
});
_area!.then((_) {}, onError: (Object e) => _messages.showApiError(e));
}
Future<void> _cancel(int appointmentId) async {
if (!await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) return;
try {
await _api.cancelAppointment(appointmentId);
_messages.showSuccess('SCHEDULE.CANCELLED');
} on ApiError catch (e) {
_messages.showApiError(e);
}
// el área Y las agendas han cambiado
_cache.invalidate('my-area');
_cache.invalidate('schedule');
if (mounted) _load();
}
@override
Widget build(BuildContext context) {
final translations = context.watch<Translations>();
final t = translations.t;
return PageTitle(
titleKey: 'AREA.TITLE',
child: FutureBuilder<MyArea>(
future: _area,
builder: (context, state) {
final a = state.data;
if (a == null) return const Center(child: CircularProgressIndicator());
return ListView(
padding: const EdgeInsets.all(12),
children: [
Padding(
padding: const EdgeInsets.all(4),
child: Text(
t('AREA.HELLO', {'name': a.patient.label}),
style: Theme.of(context).textTheme.headlineSmall,
),
),
_Option(
icon: Icons.manage_accounts,
title: t('AREA.MANAGE_ACCOUNT'),
help: t('AREA.MANAGE_ACCOUNT_HELP'),
onTap: () => context.go('/my-account'),
),
_Option(
icon: Icons.calendar_month,
title: t('AREA.VIEW_SCHEDULE'),
help: t('AREA.VIEW_SCHEDULE_HELP'),
onTap: () => context.go('/schedule'),
),
const SizedBox(height: 8),
Card(
child: Padding(
padding: const EdgeInsets.all(12),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(t('AREA.MY_APPOINTMENT'), style: Theme.of(context).textTheme.titleMedium),
// normalmente solo una (regla "una cita próxima a la
// vez"), pero la pantalla puede mostrar varias
for (final ap in a.appointments) ...[
const SizedBox(height: 8),
Text(
'${longDate(ap.day, translations.language)}, ${timeRange(ap.slot)}',
style: const TextStyle(fontWeight: FontWeight.w600),
),
Text(ap.doctor.label),
Wrap(
spacing: 8,
children: [
// la agenda del médico en ese día: el paciente ve allí su nombre
TextButton(
onPressed: () => context.go(scheduleAddress(ap.doctor.id, ap.day)),
child: Text(t('AREA.SEE_IN_SCHEDULE')),
),
OutlinedButton(
style: OutlinedButton.styleFrom(foregroundColor: Colors.red.shade700),
onPressed: () => _cancel(ap.id),
child: Text(t('AREA.CANCEL_APPOINTMENT')),
),
],
),
],
if (a.appointments.isEmpty)
Padding(
padding: const EdgeInsets.only(top: 8),
child: Text(t('AREA.NO_APPOINTMENT'), style: const TextStyle(color: Colors.grey)),
),
],
),
),
),
],
);
},
),
);
}
}
// una "tarjeta" de opción, que se toca para abrir una pantalla
class _Option extends StatelessWidget {
final IconData icon;
final String title;
final String help;
final VoidCallback onTap;
const _Option({required this.icon, required this.title, required this.help, required this.onTap});
@override
Widget build(BuildContext context) {
return Card(
child: ListTile(
leading: Icon(icon, size: 32, color: Theme.of(context).colorScheme.primary),
title: Text(title, style: Theme.of(context).textTheme.titleMedium),
subtitle: Text(help),
trailing: const Icon(Icons.chevron_right),
onTap: onTap,
),
);
}
}
|
La pantalla de inicio del paciente: dos opciones y su próxima cita.
- líneas 52–63: cancelación de la cita: el área Y las agendas han cambiado;
- Líneas 109–127: la cita y dos botones: ver la agenda del médico para ese día (el paciente ve allí su nombre), cancelar;
- líneas 150–166: una opción: una tarjeta que se toca para abrir una pantalla.
11.13.8. lib/pages/my_account.dart
| // =========================================================================
// lib/pages/my_account.dart - "Manage my account" (/my-account, rol USER)
// -------------------------------------------------------------------------
// Dos formularios independientes:
// 1. la actualizació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 (verificada por el servidor).
// Dos formularios, por lo tanto dos FormSubmit (dos conjuntos de errores). Como
// para el formulario de personas, la actualización solo se muestra una vez
// leída la cuenta, y parte de sus valores.
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../state/session.dart';
import '../i18n/translations.dart';
import '../widgets/input_field.dart';
import '../widgets/person_fields.dart';
import '../widgets/confirmation.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';
class MyAccountPage extends StatefulWidget {
const MyAccountPage({super.key});
@override
State<MyAccountPage> createState() => _MyAccountPageState();
}
class _MyAccountPageState extends State<MyAccountPage> {
// se lee de nuevo en cada visita, sin caché: su versión debe estar al día
late final Future<MyAccount> _account = context.read<RdvMedecinsApi>().myAccount();
@override
Widget build(BuildContext context) {
return PageTitle(
titleKey: 'MY_ACCOUNT.TITLE',
child: ListView(
padding: const EdgeInsets.all(12),
children: [
FutureBuilder<MyAccount>(
future: _account,
builder: (context, state) => state.hasData
? _Update(account: state.data!)
: const Padding(
padding: EdgeInsets.all(24),
child: Center(child: CircularProgressIndicator()),
),
),
const _Deletion(),
],
),
);
}
}
// -------------------------------------------------------------------------
// 1. la actualización
// -------------------------------------------------------------------------
class _Update extends StatefulWidget {
final MyAccount account;
const _Update({required this.account});
@override
State<_Update> createState() => _UpdateState();
}
class _UpdateState extends State<_Update> {
late final _messages = context.read<Messages>();
late final _submit = FormSubmit(_messages);
late final Map<String, Object?> _input = {
'title': widget.account.title,
'firstName': widget.account.firstName,
'lastName': widget.account.lastName,
'login': widget.account.login,
'password': '',
'confirmation': '',
'currentPassword': '',
'version': widget.account.version,
};
@override
void dispose() {
_submit.dispose();
super.dispose();
}
void _edit(String field, String value) {
setState(() => _input[field] = value);
_submit.clearError(field);
}
Future<void> _save() async {
final api = context.read<RdvMedecinsApi>();
final session = context.read<Session>();
final cache = context.read<Cache>();
final succeeded = await _submit.submit(() async {
// el servidor emitió un NUEVO token (nombre, login): la barra superior debe seguirlo
session.update(await api.editMyAccount(_input));
_messages.flash(key: 'MY_ACCOUNT.UPDATED');
});
if (!mounted) return;
if (succeeded) {
cache.invalidate('my-area');
context.go('/my-area');
} else {
// nunca una contraseña dejada en el campo después de un envío rechazado;
// cambiamos el valor SIN pasar por _edit(), para no borrar
// el error que el servidor acaba de asociarle
setState(() => _input['currentPassword'] = '');
}
}
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
return ListenableBuilder(
listenable: _submit,
builder: (context, _) => Card(
child: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Text(t('MY_ACCOUNT.TITLE'), style: Theme.of(context).textTheme.titleLarge),
PersonFields(values: _input, errors: _submit.errors, onChanged: _edit),
const SizedBox(height: 12),
Text(t('PERSONS.ACCOUNT_SECTION'), style: Theme.of(context).textTheme.titleSmall),
InputField(
label: 'PERSONS.LOGIN_LABEL',
maxLength: 30,
value: _input['login'] as String,
onChanged: (v) => _edit('login', v),
error: _submit.errors['login'],
),
InputField(
label: 'MY_ACCOUNT.NEW_PASSWORD_LABEL',
secret: true,
maxLength: 72,
value: _input['password'] as String,
onChanged: (v) => _edit('password', v),
error: _submit.errors['password'],
params: _submit.params,
help: 'PERSONS.PASSWORD_HELP_EDIT',
),
InputField(
label: 'ACCOUNT.CONFIRMATION_LABEL',
secret: true,
maxLength: 72,
value: _input['confirmation'] as String,
onChanged: (v) => _edit('confirmation', v),
error: _submit.errors['confirmation'],
),
InputField(
label: 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL',
secret: true,
maxLength: 72,
value: _input['currentPassword'] as String,
onChanged: (v) => _edit('currentPassword', v),
error: _submit.errors['currentPassword'],
help: 'MY_ACCOUNT.CURRENT_PASSWORD_HELP',
),
const SizedBox(height: 8),
Wrap(
spacing: 8,
children: [
FilledButton(onPressed: _submit.submitting ? null : _save, child: Text(t('PERSONS.SAVE'))),
OutlinedButton(onPressed: () => context.go('/my-area'), child: Text(t('MY_ACCOUNT.BACK'))),
],
),
],
),
),
),
);
}
}
// -------------------------------------------------------------------------
// 2. la eliminación: un formulario con un solo campo
// -------------------------------------------------------------------------
class _Deletion extends StatefulWidget {
const _Deletion();
@override
State<_Deletion> createState() => _DeletionState();
}
class _DeletionState extends State<_Deletion> {
late final _messages = context.read<Messages>();
late final _submit = FormSubmit(_messages);
String _currentPassword = '';
@override
void dispose() {
_submit.dispose();
super.dispose();
}
Future<void> _delete() async {
final api = context.read<RdvMedecinsApi>();
final session = context.read<Session>();
if (!await confirm(context, 'MY_ACCOUNT.DELETE_CONFIRM')) return;
final succeeded = await _submit.submit(() => api.deleteMyAccount(_currentPassword));
if (succeeded) {
// primero el mensaje: se mostrará en la pantalla de inicio de sesión, adonde el
// enrutador nos lleva en cuanto la sesión queda vacía
_messages.flash(key: 'MY_ACCOUNT.DELETED');
session.forget(voluntary: true); // el servidor borró la cookie del token
}
}
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
return ListenableBuilder(
listenable: _submit,
builder: (context, _) => Card(
shape: RoundedRectangleBorder(
side: BorderSide(color: Colors.red.shade300),
borderRadius: BorderRadius.circular(12),
),
child: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Text(
t('MY_ACCOUNT.DELETE_TITLE'),
style: Theme.of(context).textTheme.titleLarge!.copyWith(color: Colors.red.shade700),
),
Text(t('MY_ACCOUNT.DELETE_HELP'), style: const TextStyle(color: Colors.grey)),
InputField(
label: 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL',
secret: true,
maxLength: 72,
value: _currentPassword,
onChanged: (v) {
setState(() => _currentPassword = v);
_submit.clearError('currentPassword');
},
error: _submit.errors['currentPassword'],
),
Align(
alignment: Alignment.centerLeft,
child: FilledButton(
style: FilledButton.styleFrom(backgroundColor: Colors.red.shade700),
onPressed: _submit.submitting ? null : _delete,
child: Text(t('MY_ACCOUNT.DELETE_SUBMIT')),
),
),
],
),
),
),
);
}
}
|
“Administrar mi cuenta”: dos formularios independientes, cada uno con su propio [FormSubmit].
- línea 38: la cuenta, recargada en cada visita, sin caché (su versión debe estar actualizada);
- líneas 100–117: la modificación. El servidor devuelve el usuario actualizado (y un nuevo token en su cookie): se actualiza la sesión, y el nombre que se muestra en el menú se actualiza en consecuencia. Tras un rechazo, se borra del campo la contraseña actual;
- líneas 207–216: eliminación de la cuenta, tras la confirmación. Primero, el mensaje (un mensaje emergente); luego se borra la sesión, y el enrutador muestra la pantalla de inicio de sesión, junto con el mensaje.
11.13.9. lib/pages/error_page.dart
| // =========================================================================
// lib/pages/error_page.dart - la pantalla de error: 404 (dirección desconocida) o
// 403 (rol insuficiente, vea router.dart)
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';
import '../i18n/translations.dart';
import '../widgets/page_title.dart';
class ErrorPage extends StatelessWidget {
final int code; // 403 o 404
const ErrorPage({super.key, required this.code});
@override
Widget build(BuildContext context) {
final t = context.watch<Translations>().t;
return PageTitle(
titleKey: 'ERROR_PAGE.TITLE',
child: Padding(
padding: const EdgeInsets.all(24),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
'${t('ERROR_PAGE.TITLE')} $code',
style: Theme.of(context).textTheme.headlineMedium!.copyWith(color: Colors.red.shade700),
),
const SizedBox(height: 8),
Text(t(code == 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND')),
const SizedBox(height: 16),
FilledButton(onPressed: () => context.go('/'), child: Text(t('ERROR_PAGE.BACK'))),
],
),
),
);
}
}
|
La página de error: 404 (dirección desconocida) o 403 (rol insuficiente). “Volver a la página de inicio” lleva a [/], que el enrutador redirige a la página de inicio del rol.