Skip to content

5. Capítulo 4 - El cliente Flutter de la aplicación RdvMedecins

5.1. Visión general de la arquitectura

Image

Este cliente se comunica con el servidor [rdvmedecins-nestjs-server] del curso, que permanece estrictamente sin cambios, mediante las mismas rutas HTTP ya documentadas (POST [/login], GET [/getAllDoctors], GET [/getAllClients], GET [/getDoctorScheduleOfDay/:doctorId/:day], POST [/addAppointment], POST [/deleteAppointment]), con el mismo envoltorio JSON [{ status, data }] y la misma autenticación basada en tokens [JWT] (encabezado [Authorization: Bearer <token>]). En esta variante, la arquitectura general incorpora un tercer componente: según el destino de compilación elegido (véase el capítulo 5), ya no es solo un navegador el que ejecuta el cliente, sino, potencialmente, un sistema operativo móvil o de escritorio que ejecuta directamente el código [Dart] compilado; el servidor [NestJS], por su parte, sigue procesando únicamente las mismas solicitudes HTTP, sea cual sea el destino.

5.2. Estructura de directorios del proyecto

Image

rdvmedecins_flutter_client/
├── pubspec.yaml                      configuración del proyecto (dependencias, assets)
├── assets/
│   └── i18n/                         diccionarios de traducción (fr.json, en.json)
└── lib/
    ├── main.dart                     punto de entrada (construye los servicios, los proporciona, inicia la app)
    ├── app.dart                      root widget (conductor + authentication guard)
    ├── core/
    │   ├── models/                   clases de datos (reflejo del JSON intercambiado con el servidor)
    │   ├── services/                 SettingsService, AuthService, AppointmentService
    │   ├── http/                     AuthHttpClient (token JWT + cierre de sesión ante un 401)
    │   └── i18n/                     TranslationsService (francés/inglés)
    └── features/                     un widget por funcionalidad, incluida la pantalla de inicio de sesión

Esta estructura de directorios reproduce, carpeta por carpeta, la del cliente [Vue.js] de este curso ([core/models], [core/composables] -> [core/services], [core/interceptors] -> [core/http], [features/] sin cambios); una decisión deliberada: la organización de una aplicación, en la mayoría de los casos, no es específica de ningún framework de interfaz en particular.

5.3. Archivos de configuración del proyecto

5.3.1. pubspec.yaml

name: rdvmedecins_flutter_client
description: >
  Flutter client (mobile, desktop and web from one and the same source code)
  for the RdvMedecins application - NestJS / Flutter port of this course.
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: '>=3.4.0 <4.0.0'
  flutter: '>=3.24.0'

dependencies:
  flutter:
    sdk: flutter

  # http: el cliente HTTP "de bajo nivel" oficial del ecosistema Dart - el
  # equivalente exacto del fetch() usado en el lado Vue.js (auth.interceptor.ts,
  # appointment.service.ts). Flutter no tiene un fetch() integrado en el lenguaje: esta
  # biblioteca ocupa su lugar.
  http: ^1.2.2

  # provider: la forma más extendida de exponer un estado COMPARTIDO a todo un
  # árbol de widgets de Flutter - exactamente el papel que cumplen provide()/inject()
  # en el lado Vue.js (settings.composable.ts, auth.composable.ts,
  # language.composable.ts). Vea el capítulo "Introducción a Flutter" para
  # la correspondencia detallada.
  provider: ^6.1.2

  # shared_preferences: un almacenamiento persistente de clave/valor, disponible de la
  # MISMA forma en móvil, escritorio Y web - el equivalente multiplataforma de
  # localStorage (que, por su parte, solo existe en un navegador).
  shared_preferences: ^2.3.2

  # intl: formato de fechas (yyyy-MM-dd, ver DoctorDayPicker) - el mismo
  # papel que Date.toISOString().slice(0, 10) en el lado Vue.js/TypeScript, pero
  # explícito en lugar de un simple recorte de cadena.
  intl: ^0.19.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true

  # the translation dictionaries - the equivalent of public/i18n/*.json en el
  # lado Vue.js, pero INCLUIDOS en el paquete de la aplicación en lugar de ser servidos
  # por un servidor web (vea el Capítulo "Portar la aplicación" para conocer el motivo
  # de esta diferencia, que concierne precisamente a los 3 entornos de destino).
  assets:
    - assets/i18n/

Revisemos este código:

  • líneas 9–10: [sdk: '>=3.4.0 <4.0.0'] / [flutter: '>=3.24.0'] : equivalente al campo [engines] de un [package.json] [Node.js]: el rango de versiones del lenguaje [Dart] y del SDK de [Flutter] requerido para este proyecto.
  • Líneas 16–20, 22–27, 29–32, 34–37: las cuatro dependencias de este cliente, cada una anotada en su lugar con su equivalente en [Vue.js]; véase también la sección “Herramientas utilizadas” de la introducción.
  • línea 42: [flutter_lints: ^4.0.0]: el equivalente en [Dart] de [ESLint]: un conjunto de reglas de estilo y calidad verificadas por [flutter analyze], que no estaba presente en los clientes web anteriores de este curso, pero que fue generado automáticamente por [flutter create].
  • Líneas 51–52: [assets: - assets/i18n/] : declara EXPLÍCITAMENTE que todo el contenido de [assets/i18n/] debe incorporarse al paquete de la aplicación; sin esta declaración, [rootBundle.loadString(...)] (véase [core/i18n/translations_service.dart] más adelante) fallaría en tiempo de ejecución: un archivo que existe en disco en el momento de [flutter build] no se incluye automáticamente en el paquete final, a diferencia de [public/] en el caso de [Vite]/[Vue.js], que se sirve tal cual, sin declaración previa.

5.4. Inicio de la aplicación

Image

5.4.1. lib/main.dart

Adaptación de [src/main.ts] (cliente [Vue.js]): construye los servicios de este cliente, los pone a disposición de todo el árbol de widgets mediante [provider] y luego inicia la aplicación.

// =========================================================================
// main.dart
// -------------------------------------------------------------------------
// Punto de entrada del cliente Flutter. Equivalente de src/main.ts en el lado cliente
// Vue.js de este curso: este archivo inicia explícitamente la aplicación
// (aquí runApp(...); createApp(...).mount(...) en el lado Vue.js) Y
// la configura.
//
// Vue.js configura su aplicación con app.provide(key, value), llamado
// directamente sobre la instancia de la aplicación - Flutter/provider usa
// un widget, MultiProvider, situado en la raíz del árbol (ver runApp(...)
// más abajo): cada ChangeNotifierProvider/Provider que contiene hace
// disponible una instancia para TODO el subárbol que envuelve, exactamente
// como app.provide(...) lo hacía para todos los componentes descendientes -
// la misma idea, expresada como un WIDGET en lugar de como una llamada
// imperativa a un método, porque TODO, en Flutter, es un widget (incluida
// la configuración de un estado compartido).
//
// El ORDEN de las construcciones sigue siendo importante, por las mismas razones que
// en el lado Vue.js: AuthService(settings) necesita que settings ya exista
// (para leer apiBaseUrl); AppointmentService necesita authHttp Y settings.
//
// DIFERENCIA IMPORTANTE con Vue.js: createAuthStore(settings) y
// createLanguageStore() en el lado Vue.js leen localStorage de forma SÍNCRONA
// durante su construcción, incluso antes del primer renderizado. Sus
// equivalentes en Flutter (AuthService.init(), TranslationsService.init())
// son ASÍNCRONOS (ver sus archivos respectivos): por lo tanto, main() debe
// volverse una función async y ESPERAR (await) estas dos
// inicializaciones ANTES de llamar a runApp(...) - de lo contrario, la primera pantalla
// mostrada ignoraría una sesión o un idioma posiblemente ya almacenados, durante
// el tiempo que shared_preferences tarde en responder.
//
// Como los clientes Angular, React y Vue.js de este curso (una sola página,
// sin tabla de rutas), este cliente Flutter usa ÚNICAMENTE la navegación
// mínima que ofrece MaterialApp (indispensable para showDialog(), ver
// features/booking_dialog/booking_dialog.dart): AppRoot (ver app.dart)
// muestra la pantalla de inicio de sesión o el resto de la aplicación, según
// AuthService.isLoggedIn - basta un simple if/else de Dart; un paquete de enrutamiento
// (go_router u otro) no habría aportado nada a una aplicación
// con una sola pantalla.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import 'app.dart';
import 'core/http/auth_http_client.dart';
import 'core/i18n/translations_service.dart';
import 'core/services/auth_service.dart';
import 'core/services/appointment_service.dart';
import 'core/services/settings_service.dart';

Future<void> main() async {
  // WidgetsFlutterBinding.ensureInitialized(): indispensable en cuanto se
  // llama a una API de Flutter ANTES de runApp(...) (aquí, shared_preferences y
  // rootBundle.loadString(...) en TranslationsService.init()) - sin
  // esta línea, esas llamadas fallarían al arrancar. Vue.js no tiene nada
  // comparable: el navegador siempre está "listo" incluso antes de que
  // se ejecute src/main.ts.
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Primero SettingsService: AuthService y AppointmentService lo necesitan
  //    (apiBaseUrl).
  final settings = SettingsService();

  // 2. AuthService: recibe settings directamente en su constructor, como
  //    createAuthStore(settingsStore) en el lado Vue.js - luego init() restaura una
  //    sesión posiblemente almacenada (ver el comentario de encabezado
  //    más arriba sobre la naturaleza asíncrona de este paso).
  final auth = AuthService(settings);
  await auth.init();

  // 3. la capa HTTP autenticada y luego el servicio de negocio - ambos
  //    construidos AQUÍ, una sola vez, en lugar de dentro de un widget
  //    (donde se reconstruirían en cada renderizado): exactamente el mismo
  //    principio que createSettingsStore()/createAuthStore(...), llamados una sola
  //    vez antes de app.mount(...) en el lado Vue.js.
  final authHttp = AuthHttpClient(auth);
  final api = AppointmentService(authHttp, settings);

  // 4. TranslationsService: carga el diccionario inicial (el idioma
  //    almacenado o, por defecto, el del dispositivo) - SIN dependencia de orden
  //    con los pasos anteriores (a diferencia de
  //    createLanguageStore() en el lado Vue.js, que debía esperar a
  //    app.use(i18n): este archivo reimplementa todo por sí mismo, ver
  //    core/i18n/translations_service.dart, por lo que no hay ningún plugin
  //    de terceros que instalar antes de poder usarlo).
  final translations = TranslationsService();
  await translations.init();

  runApp(
    // MultiProvider: agrupa varios proveedores en un solo widget,
    // en lugar de anidarlos a mano (Provider(...) > Provider(...)
    // > Provider(...) > ...) - una legibilidad comparable a la secuencia
    // de llamadas "app.provide(SettingsKey, ...); app.provide(AuthKey, ...);
    // app.provide(LanguageKey, ...);" en el lado Vue.js, a pesar de la diferencia
    // de forma (una lista de widgets en lugar de una secuencia de instrucciones).
    MultiProvider(
      providers: [
        // .value(...) en lugar de Provider(create: ...): estas instancias
        // ya existen (construidas arriba) - .value(...) simplemente las hace
        // disponibles para el árbol de widgets, sin construir
        // nuevas. ChangeNotifierProvider, en concreto, también se suscribe
        // a notifyListeners() y redibuja automáticamente cualquier
        // widget que haya hecho context.watch<...>() sobre este proveedor (ver
        // lib/app.dart) - el papel que cumple la naturaleza "reactiva" de un
        // reactive(...) en el lado Vue.js.
        ChangeNotifierProvider.value(value: settings),
        ChangeNotifierProvider.value(value: auth),
        ChangeNotifierProvider.value(value: translations),
        // AppointmentService NO es un ChangeNotifier (nada, en este servicio,
        // varía con el tiempo una vez construido): basta un simple Provider,
        // que solo hace disponible esta instancia, sin
        // ninguna noción de notificación.
        Provider.value(value: api),
      ],
      child: const RdvMedecinsApp(),
    ),
  );
}

Revisemos este código:

  • línea 60: [WidgetsFlutterBinding.ensureInitialized();] : necesaria siempre que se llama a una API de [Flutter] ANTES de [runApp(...)] (aquí, [shared_preferences] y [rootBundle.loadString(...)]); sin esta línea, estas llamadas fallarían al iniciar; [Vue.js] no tiene que anticipar nada semejante, ya que el navegador siempre está “listo” incluso antes de que se ejecute [src/main.ts].
  • Líneas 70–71: [final auth = AuthService(settings); await auth.init();] : DIFERENCIA IMPORTANTE con [createAuthStore(settingsStore)] del lado de [Vue.js], que lee [localStorage] de forma SINCRÓNICA tan pronto como se construye: [AuthService.init()] es explícitamente [async], y [main()] debe serlo también para poder ESPERAR antes de [runApp(...)]; de lo contrario, la primera pantalla mostrada ignoraría una sesión ya almacenada mientras se espera a que [shared_preferences] responda.
  • Línea 89: [await translations.init();] : la misma observación que antes respecto del idioma almacenado; a diferencia de [createLanguageStore()] en [Vue.js], que tenía que esperar a [app.use(i18n)], este paso no tiene ninguna dependencia secuencial con los anteriores: [TranslationsService] reimplementa todo por sí mismo, sin necesidad de instalar previamente ningún complemento de terceros.
  • Líneas 98–116: [MultiProvider(providers: [...], child: const RdvMedecinsApp())] : el equivalente, en forma de WIDGET y no de llamadas imperativas, de la secuencia [app.provide(SettingsKey, ...); app.provide(AuthKey, ...); app.provide(LanguageKey, ...);] del lado de [Vue.js]: cada [ChangeNotifierProvider.value(...)] pone una instancia ya construida a disposición de todo el subárbol.

5.4.2. lib/app.dart

Adaptación de [src/app/App.vue]: el widget RAÍZ de la aplicación (construido por [lib/main.dart]); el “director de orquesta” que mantiene el estado de negocio y responde a las acciones de los widgets de [lib/features/] y la “guardia” de autenticación.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
// =========================================================================
// app.dart
// -------------------------------------------------------------------------
// Port de src/app/App.vue (cliente Vue.js de este curso): el widget
// RAÍZ de la aplicación (construido por lib/main.dart). Como en las
// otras tres variantes de este curso, es quien hace de
// "director de orquesta": mantiene el estado de la aplicación (médicos, clientes,
// agenda mostrada, último médico/día buscado...) y reacciona a las acciones
// de los widgets de "negocio" de lib/features/ para llamar al servidor NestJS en el
// momento adecuado, a través de AppointmentService.
//
// Desde que se añadió la autenticación, este widget también hace de
// "guardia": mientras AuthService.isLoggedIn sea false, solo muestra
// LoginPage (ver lib/features/login/); como todas las rutas del servidor están
// protegidas por JwtAuthGuard, de todos modos sería inútil (y fuente
// de errores 401) cargar médicos/clientes/agenda antes de iniciar sesión.
//
// Dos clases, como en los demás archivos "con estado" de este cliente:
// RdvMedecinsApp (el MaterialApp - la raíz ABSOLUTA, ver lib/main.dart) y
// AppRoot/_AppRootState (el verdadero equivalente de App.vue, con todo su estado).
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import 'core/i18n/translations_service.dart';
import 'core/models/appointment_models.dart';
import 'core/services/auth_service.dart';
import 'core/services/appointment_service.dart';
import 'core/services/settings_service.dart';
import 'features/schedule/schedule_view.dart';
import 'features/booking_dialog/booking_dialog.dart';
import 'features/doctor_day_picker/doctor_day_picker.dart';
import 'features/login/login_page.dart';

// -------------------------------------------------------------------------
// RdvMedecinsApp: la raíz de Flutter en sentido estricto - MaterialApp proporciona
// el tema, la navegación (Navigator, usado por showDialog(), ver
// features/booking_dialog/booking_dialog.dart) y las traducciones del sistema
// (desplazamiento, cuadros de diálogo...). Es el equivalente, muy
// aproximadamente, de lo que index.html + el montaje app.mount('#app')
// hacían juntos en el lado Vue.js (src/main.ts) - salvo que aquí este
// "armazón" forma parte del propio código Dart de la aplicación, en lugar
// de un archivo HTML aparte.
// -------------------------------------------------------------------------
class RdvMedecinsApp extends StatelessWidget {
  const RdvMedecinsApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      // appBarTheme explícito: el tema Material 3 por defecto da a
      // AppBar un fondo claro (colorScheme.surface) - para recuperar la barra
      // azul con texto blanco de "navbar navbar-dark bg-primary" en el lado
      // Vue.js (ver App.vue), el fondo y el texto se definen explícitamente aquí,
      // en lugar de fijar un color de texto en cada Text()
      // individual de AppRoot más abajo (ver auth.name, más adelante) - una
      // única fuente de verdad para el aspecto de la barra.
      theme: ThemeData(
        colorSchemeSeed: Colors.blue,
        useMaterial3: true,
        appBarTheme: const AppBarTheme(
          backgroundColor: Colors.blue,
          foregroundColor: Colors.white,
        ),
      ),
      home: const AppRoot(),
    );
  }
}

class AppRoot extends StatefulWidget {
  const AppRoot({super.key});

  @override
  State<AppRoot> createState() => _AppRootState();
}

class _AppRootState extends State<AppRoot> {
  // --- estado de la aplicación -------------------------------------------------
  // el equivalente directo de los ref(...) de App.vue, como simples
  // campos mutables de _AppRootState: setState(...) (ver los métodos
  // más abajo) sustituye a la reactividad automática de Vue.js.
  List<Doctor> _doctors = [];
  List<Client> _clients = [];
  DoctorDaySchedule? _schedule;
  String? _error;

  // la última búsqueda (médico + día) se recuerda para poder
  // refrescar la agenda después de una reserva o una cancelación - mismo
  // papel que lastDoctorId/lastDay en el lado Vue.js.
  int? _lastDoctorId;
  String? _lastDay;

  // referencia conservada de forma permanente a AuthService, para poder
  // cancelar la suscripción limpiamente en dispose() (ver más abajo) - vea el
  // comentario de initState() más abajo para conocer el motivo de esta elección.
  late final AuthService _auth;

  @override
  void initState() {
    super.initState();
    // context.read<AuthService>(): cuando se ejecuta initState(), el
    // widget ya está correctamente insertado en el árbol (a diferencia del
    // constructor, donde context aún no puede usarse para la
    // inyección de dependencias) - pero aquí NO se usa context.watch(...):
    // un StatefulWidget debe suscribirse a un proveedor una sola vez,
    // explícitamente, nunca dentro de initState() con watch()
    // (que supone un contexto de compilación). Por eso la referencia se guarda en
    // un campo (_auth) y nos suscribimos nosotros mismos con addListener(...).
    _auth = context.read<AuthService>();
    _auth.addListener(_onAuthChange);

    // equivalente de "watch(() => auth.isLoggedIn, ..., { immediate: true })"
    // en el lado Vue.js: { immediate: true } dispara el callback
    // INMEDIATAMENTE, sin esperar a un primer cambio - útil si ya había una sesión
    // almacenada (ver AuthService.init(), esperado con await por
    // lib/main.dart antes de runApp(...)). Vue.js ofrece esta opción
    // directamente; Flutter no tiene un mecanismo equivalente integrado en
    // addListener(...), así que el mismo efecto se reproduce A MANO: una
    // llamada explícita justo después de suscribirse, además de la suscripción
    // en sí.
    if (_auth.isLoggedIn) {
      _loadInitialLists();
    }
  }

  @override
  void dispose() {
    // cancelar la suscripción es ESENCIAL aquí: sin ello, _onAuthChange
    // seguiría siendo llamado después de que este widget sea destruido (por
    // ejemplo durante un hot reload o un cambio de ruta), y
    // provocaría una excepción en el primer setState(...) sobre un widget
    // desmontado. Vue.js no tiene nada comparable que prever: watch(...) se
    // "limpia" automáticamente cuando se destruye el componente que lo creó.
    _auth.removeListener(_onAuthChange);
    super.dispose();
  }

  void _onAuthChange() {
    if (_auth.isLoggedIn) {
      _loadInitialLists();
    }
  }

  // -----------------------------------------------------------------------
  // cuando pasamos a estar conectados (inicio de sesión exitoso o sesión
  // restaurada desde shared_preferences), las listas de médicos y clientes
  // se cargan de una vez por todas.
  // -----------------------------------------------------------------------
  void _loadInitialLists() {
    final api = context.read<AppointmentService>();
    api.getAllDoctors().then((result) {
      if (mounted) setState(() => _doctors = result);
    }).catchError((Object err) {
      if (mounted) setState(() => _error = err.toString());
    });
    api.getAllClients().then((result) {
      if (mounted) setState(() => _clients = result);
    }).catchError((Object err) {
      if (mounted) setState(() => _error = err.toString());
    });
  }

  // -----------------------------------------------------------------------
  // reacciona al botón "Log out": borra la sesión Y el estado de negocio
  // mostrado - sin esto, un nuevo usuario que iniciara sesión después
  // vería brevemente la agenda del anterior.
  // -----------------------------------------------------------------------
  Future<void> _onLogout() async {
    await _auth.logOut();
    setState(() {
      _doctors = [];
      _clients = [];
      _schedule = null;
      _error = null;
      _lastDoctorId = null;
      _lastDay = null;
    });
  }

  // -----------------------------------------------------------------------
  // reacciona a la llamada de onSearch(...) por parte del widget DoctorDayPicker
  // -----------------------------------------------------------------------
  void _onSearchSchedule(int doctorId, String day) {
    setState(() {
      _error = null;
      _lastDoctorId = doctorId;
      _lastDay = day;
    });
    _loadSchedule();
  }

  // -----------------------------------------------------------------------
  // reacciona a la llamada de onBook(...) por parte del widget ScheduleView: AQUÍ, a diferencia de
  // Vue.js (que se limitaba a abrir la ventana recordando
  // slotBeingBooked), el cuadro de diálogo se abre DIRECTAMENTE
  // con showDialog (a través de openBookingDialog(...)) y su resultado se
  // ESPERA con await - vea el encabezado de booking_dialog.dart para los detalles de
  // esta diferencia estructural.
  // -----------------------------------------------------------------------
  Future<void> _onBookingRequest(SlotJson slot) async {
    final lastDay = _lastDay;
    if (lastDay == null) {
      return;
    }
    final clientId = await openBookingDialog(context: context, slot: slot, clients: _clients);
    if (clientId == null) {
      return; // el usuario cerró el cuadro de diálogo sin elegir un paciente
    }
    try {
      await context.read<AppointmentService>().addAppointment(lastDay, clientId, slot.id);
      _loadSchedule(); // se refresca la agenda: el horario ahora aparece reservado
    } catch (err) {
      if (mounted) setState(() => _error = err.toString());
    }
  }

  // -----------------------------------------------------------------------
  // reacciona a la llamada de onCancel(...) por parte del widget ScheduleView
  // -----------------------------------------------------------------------
  Future<void> _onCancelAppointment(AppointmentJson appointment) async {
    try {
      await context.read<AppointmentService>().deleteAppointment(appointment.id);
      _loadSchedule(); // se refresca la agenda: el horario vuelve a quedar libre
    } catch (err) {
      if (mounted) setState(() => _error = err.toString());
    }
  }

  void _loadSchedule() {
    final doctorId = _lastDoctorId;
    final day = _lastDay;
    if (doctorId == null || day == null) {
      return;
    }
    context.read<AppointmentService>().getDoctorScheduleOfDay(doctorId, day).then((result) {
      if (mounted) setState(() => _schedule = result);
    }).catchError((Object err) {
      if (mounted) setState(() => _error = err.toString());
    });
  }

  @override
  Widget build(BuildContext context) {
    // context.watch<...>() sobre los TRES proveedores de los que depende directamente
    // lo que se muestra: cada llamada suscribe este widget a los cambios futuros de
    // ese proveedor - si uno de ellos notifica (notifyListeners()), se vuelve a llamar
    // a build(...) automáticamente. Es el mecanismo que
    // sustituye, aquí, la reactividad automática de Vue.js mencionada en
    // core/services/settings_service.dart.
    final t = context.watch<TranslationsService>().t;
    final language = context.watch<TranslationsService>();
    final auth = context.watch<AuthService>();
    final settings = context.watch<SettingsService>();
    // pantalla estrecha (teléfono en modo vertical): la barra de título se aligera
    // (ver actions: más abajo), por falta de espacio para mostrar todo lo que
    // cabe fácilmente en una pantalla ancha.
    final narrow = MediaQuery.sizeOf(context).width < 600;

    return Scaffold(
      appBar: AppBar(
        title: Text(t('APP.TITLE')),
        actions: [
          // selector FR/EN: SIEMPRE visible (incluso en la pantalla de inicio de
          // sesión) - el equivalente del <div class="btn-group"> siempre
          // mostrado en App.vue.
          SegmentedButton<String>(
            segments: const [
              ButtonSegment(value: 'fr', label: Text('FR')),
              ButtonSegment(value: 'en', label: Text('EN')),
            ],
            selected: {language.currentLanguage},
            onSelectionChanged: (choice) => language.changeLanguage(choice.first),
            showSelectedIcon: false,
          ),
          const SizedBox(width: 12),
          // la insignia del rol + el nombre + el botón de cierre de sesión, en cambio, solo
          // se muestran una vez iniciada la sesión (auth.isLoggedIn) - misma
          // condición que el <template v-if="auth.isLoggedIn"> de App.vue.
          if (auth.isLoggedIn) ...[
            Chip(label: Text(auth.role?.asString() ?? '')),
            const SizedBox(width: 8),
            // aquí no hay estilo de color fijo: este Text() hereda el
            // foregroundColor blanco definido en appBarTheme (ver RdvMedecinsApp
            // más arriba), exactamente como "navbar-dark" en el lado Bootstrap
            // coloreaba por defecto todo su contenido de blanco.
            // en una pantalla estrecha, el nombre se oculta: la insignia del rol y el botón
            // de cierre de sesión bastan, y la barra de título cabe en el ancho disponible.
            if (!narrow) Text(auth.name ?? ''),
            IconButton(
              tooltip: t('APP.LOGOUT'),
              icon: const Icon(Icons.logout),
              onPressed: _onLogout,
            ),
          ],
          const SizedBox(width: 8),
        ],
      ),
      body: SafeArea(
        child: SingleChildScrollView(
          padding: const EdgeInsets.all(16),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              // URL del servidor: útil tanto antes como después de iniciar sesión -
              // extraído a un pequeño widget privado dedicado, _ServerUrlField
              // (ver más abajo), por las razones explicadas junto a su
              // definición.
              ConstrainedBox(
                constraints: const BoxConstraints(maxWidth: 320),
                child: _ServerUrlField(settings: settings, label: t('APP.SERVER_URL_LABEL')),
              ),
              const SizedBox(height: 16),

              if (_error != null) ...[
                Container(
                  width: double.infinity,
                  padding: const EdgeInsets.all(12),
                  decoration: BoxDecoration(
                    color: Theme.of(context).colorScheme.errorContainer,
                    borderRadius: BorderRadius.circular(4),
                  ),
                  child: Text(
                    _error!,
                    style: TextStyle(color: Theme.of(context).colorScheme.onErrorContainer),
                  ),
                ),
                const SizedBox(height: 16),
              ],

              // sin sesión iniciada: nada más que la pantalla de inicio de sesión -
              // el equivalente exacto de "<Login v-if="!auth.isLoggedIn" />"
              // en el lado Vue.js.
              if (!auth.isLoggedIn)
                const LoginPage()
              else ...[
                // widget 1: elección del médico y del día
                DoctorDayPicker(doctors: _doctors, onSearch: _onSearchSchedule),
                const SizedBox(height: 16),
                // widget 2: visualización de la agenda - canEdit oculta
                // "Book"/"Cancel" para un rol USER
                ScheduleView(
                  schedule: _schedule,
                  canEdit: auth.isAdmin,
                  onBook: _onBookingRequest,
                  onCancel: _onCancelAppointment,
                ),
              ],
            ],
          ),
        ),
      ),
    );
  }
}

// -------------------------------------------------------------------------
// _ServerUrlField: un pequeño StatefulWidget PRIVADO dedicado al campo "Server
// URL". En el lado Vue.js, este campo cabe en una sola línea, directamente
// en el <template> de App.vue (<input v-model="settings.apiBaseUrl">):
// v-model se encarga por sí mismo, entre bastidores, de la sincronización entre el
// campo mostrado y settings.apiBaseUrl. Flutter no tiene enlace bidireccional
// integrado en TextField (ver ya lib/features/login/login_page.dart):
// requiere un TextEditingController y, por lo tanto, un propietario capaz de crearlo
// y liberarlo (initState/dispose) - un TEXTO EDITABLE enlazado a un
// proveedor NO puede ser un simple StatelessWidget en Flutter, a diferencia de
// un campo Vue.js equivalente, que no necesita ningún
// "componente" aparte para existir.
// -------------------------------------------------------------------------
class _ServerUrlField extends StatefulWidget {
  final SettingsService settings;
  final String label;

  const _ServerUrlField({required this.settings, required this.label});

  @override
  State<_ServerUrlField> createState() => _ServerUrlFieldState();
}

class _ServerUrlFieldState extends State<_ServerUrlField> {
  late final TextEditingController _controller;

  @override
  void initState() {
    super.initState();
    _controller = TextEditingController(text: widget.settings.apiBaseUrl);
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return TextField(
      controller: _controller,
      decoration: InputDecoration(labelText: widget.label, isDense: true),
      // onChanged en lugar de onSubmitted: cada pulsación de tecla se transmite
      // de inmediato a SettingsService, exactamente como lo hace
      // v-model en el lado Vue.js con cada carácter escrito (y no solo al
      // enviar el formulario).
      onChanged: widget.settings.setApiBaseUrl,
    );
  }
}

Revisemos este código:

  • líneas 46–71: [class RdvMedecinsApp extends StatelessWidget] : el widget raíz [Flutter] en sentido estricto: [MaterialApp] proporciona el tema y la navegación (esenciales para [showDialog(...)], véase [booking_dialog.dart] más adelante); aproximadamente equivalente a lo que hacían conjuntamente [index.html] + [app.mount('#app')] del lado de [Vue.js].
  • líneas 60–66: [appBarTheme: const AppBarTheme(backgroundColor: Colors.blue, foregroundColor: Colors.white)] : reproduce el aspecto de ["navbar navbar-dark bg-primary"] ([Bootstrap], véase [App.vue]): un tema predeterminado [Material 3] daría a [AppBar] un fondo claro, por lo que debe configurarse explícitamente para recuperar el conocido banner azul con texto blanco.
  • líneas 96–127: [initState()] reproduce, A MANO, el equivalente de [watch(() => auth.isLoggedIn, ..., { immediate: true })] del lado de [Vue.js] (véase [App.vue]): [Flutter] no tiene la opción [immediate] incorporada en [addListener(...)], por lo que hay que suscribirse y LUEGO verificar explícitamente el estado actual una vez; dos pasos allí donde [Vue.js] solo necesita uno.
  • Líneas 129–139: [dispose() { _auth.removeListener(_onAuthChange); }] — INDISPENSABLE: sin esta cancelación de la suscripción, [_onAuthChange] se seguiría llamando después de que el widget fuera destruido y provocaría una excepción en la primera llamada a [setState(...)] sobre un widget desmontado. [Vue.js] no tiene nada comparable que prever, ya que [watch(...)] se “limpia” automáticamente cuando se destruye el componente que lo creó.
  • Líneas 203–218: [_onBookingRequest(...)] — AQUÍ está la diferencia estructural más visible de todo este cliente: en lugar de abrir una “ventana” almacenando un estado booleano (véase [slotBeingBooked] del lado de [Vue.js]), este widget espera directamente con [await] el resultado de [openBookingDialog(...)]; véase el comentario completo en [booking_dialog.dart], más adelante en este capítulo.
  • Líneas 253–256: cuatro [context.watch<...>()] al comienzo de [build(...)]: este widget se redibuja automáticamente en cuanto uno cualquiera de estos cuatro servicios (CUALQUIERA de ellos) notifica un cambio ([notifyListeners()]), exactamente el papel que desempeña la reactividad automática de [Vue.js] para [auth], [settings], y [language] en [App.vue].
  • Líneas 260 y 291: [MediaQuery.sizeOf(context).width < 600] : el ancho de la pantalla (o de la ventana) se usa para aligerar la barra de título en un teléfono en modo vertical: se oculta el nombre del usuario ([if (!narrow) Text(...)], un simple [if] de Dart en medio de una lista de widgets), mientras que la insignia del rol y el botón de cierre de sesión permanecen visibles. En la línea 276, [showSelectedIcon: false] elimina la marca de verificación que [SegmentedButton] agrega a la opción seleccionada, la cual ensanchaba innecesariamente el selector [FR]/[EN]. Sin estos dos ajustes, los elementos [actions:] de la [AppBar] exceden el ancho de un teléfono en orientación vertical.
  • Líneas 359–409: [class _ServerUrlField] : un pequeño [StatefulWidget] PRIVADO dedicado al campo “URL del servidor”. Al igual que en [Vue.js], este campo cabía en una sola línea ([<input v-model="settings.apiBaseUrl">]): [Flutter] no tiene un enlace bidireccional integrado con [TextField], por lo que se requiere un [TextEditingController] junto con un propietario capaz de crearlo o liberarlo; un texto editable vinculado a un proveedor no puede ser simplemente un [StatelessWidget] en [Flutter].

5.5. La capa core/models

Image

5.5.1. lib/core/models/appointment_models.dart

Adaptación de [core/models/appointment.models.ts], copiado a su vez literalmente de los clientes [Angular] y [React]: las clases que describen el formato de los datos JSON intercambiados con el servidor, sin dependencias de [Flutter], es decir, [Dart] “puro”.

// =========================================================================
// core/models/appointment_models.dart
// -------------------------------------------------------------------------
// Port de core/models/appointment.models.ts (cliente Vue.js de este curso), a su vez
// copiado tal cual de los clientes Angular y React: las clases Dart que
// describen la forma de los datos JSON recibidos del servidor NestJS. Como sus
// equivalentes TypeScript, estas clases no dependen de ningún framework de UI
// (aquí no hay ninguna importación de Flutter) - es Dart "puro", igual que
// appointment.models.ts era TypeScript "puro".
//
// DIFERENCIA ESTRUCTURAL con TypeScript: una "interface" de TypeScript es
// una simple descripción de una FORMA, verificada solo en tiempo de compilación -
// en tiempo de ejecución, un objeto JSON decodificado (JSON.parse) se usa TAL CUAL,
// sin conversión, y TypeScript "confía" en el desarrollador (ver el
// "as ServerResponse<T>" de appointment.service.ts). Dart no tiene esa noción de
// tipado estructural implícito: jsonDecode(...) siempre devuelve tipos
// dynamic (Map<String, dynamic>, List<dynamic>...), que deben
// convertirse explícitamente en instancias de clases Dart mediante un
// constructor fromJson(...) - presente en CADA una de las clases siguientes. Es más
// verboso de escribir una vez, pero la conversión se verifica en tiempo de ejecución
// (una clave ausente o de tipo incorrecto lanza de inmediato una excepción
// explícita), mientras que un tipado TypeScript erróneo puede pasar inadvertido.
// =========================================================================

// -------------------------------------------------------------------------
// envoltorio común a todas las respuestas del servidor (ver ServerResponse<T> en el
// lado NestJS, y la interfaz ServerResponse<T> del cliente Vue.js).
//
// Dart también generaliza con corchetes angulares (<T>), exactamente como
// TypeScript - la gran diferencia es que aquí un simple "as T" no
// basta para convertir el campo [data]: hay que proporcionar la función que sabe cómo
// construir un T a partir del JSON sin procesar (el parámetro [parseData]
// más abajo), porque Dart no conoce T en tiempo de ejecución
// (el borrado de tipos impide escribir "T.fromJson(...)"
// directamente).
// -------------------------------------------------------------------------
class ServerResponse<T> {
  final int status; // 0 = éxito, cualquier otro valor = fallo (ver ResponseStatus en el lado del servidor)
  final T? data;

  ServerResponse({required this.status, required this.data});

  factory ServerResponse.fromJson(
    Map<String, dynamic> json,
    T Function(dynamic rawData) parseData,
  ) {
    final rawData = json['data'];
    return ServerResponse<T>(
      status: json['status'] as int,
      data: rawData == null ? null : parseData(rawData),
    );
  }
}

class Doctor {
  final int id;
  final String title;
  final String lastName;
  final String firstName;

  Doctor({required this.id, required this.title, required this.lastName, required this.firstName});

  factory Doctor.fromJson(Map<String, dynamic> json) => Doctor(
        id: json['id'] as int,
        title: json['title'] as String,
        lastName: json['lastName'] as String,
        firstName: json['firstName'] as String,
      );
}

// [Client] aquí significa un PACIENTE del consultorio médico (vocabulario del
// dominio de negocio, heredado del documento original) - ¡no debe confundirse con
// "cliente HTTP", ni con este propio cliente Flutter!
class Client {
  final int id;
  final String title;
  final String lastName;
  final String firstName;

  Client({required this.id, required this.title, required this.lastName, required this.firstName});

  factory Client.fromJson(Map<String, dynamic> json) => Client(
        id: json['id'] as int,
        title: json['title'] as String,
        lastName: json['lastName'] as String,
        firstName: json['firstName'] as String,
      );
}

// forma "ligera" de un horario, tal como la devuelve el servidor
// (ver getMapForSlot en el lado NestJS): solo los campos útiles para mostrar.
class SlotJson {
  final int id;
  final int startHour;
  final int startMinute;
  final int endHour;
  final int endMinute;

  SlotJson({
    required this.id,
    required this.startHour,
    required this.startMinute,
    required this.endHour,
    required this.endMinute,
  });

  factory SlotJson.fromJson(Map<String, dynamic> json) => SlotJson(
        id: json['id'] as int,
        startHour: json['startHour'] as int,
        startMinute: json['startMinute'] as int,
        endHour: json['endHour'] as int,
        endMinute: json['endMinute'] as int,
      );
}

// forma "ligera" de una cita (ver getMapForAppointment en el lado NestJS)
class AppointmentJson {
  final int id;
  final String day; // formato "yyyy-MM-dd"
  final Client? client;
  final SlotJson? slot;

  AppointmentJson({required this.id, required this.day, required this.client, required this.slot});

  factory AppointmentJson.fromJson(Map<String, dynamic> json) => AppointmentJson(
        id: json['id'] as int,
        day: json['day'] as String,
        client: json['client'] == null ? null : Client.fromJson(json['client'] as Map<String, dynamic>),
        slot: json['slot'] == null ? null : SlotJson.fromJson(json['slot'] as Map<String, dynamic>),
      );
}

// un horario de la agenda de un médico, libre (appointment == null) o reservado
class DoctorDaySlot {
  final SlotJson slot;
  final AppointmentJson? appointment;

  DoctorDaySlot({required this.slot, required this.appointment});

  factory DoctorDaySlot.fromJson(Map<String, dynamic> json) => DoctorDaySlot(
        slot: SlotJson.fromJson(json['slot'] as Map<String, dynamic>),
        appointment: json['appointment'] == null ? null : AppointmentJson.fromJson(json['appointment'] as Map<String, dynamic>),
      );
}

// la agenda completa de un médico para un día dado (ver GET /getDoctorScheduleOfDay/:doctorId/:day)
class DoctorDaySchedule {
  final Doctor doctor;
  final String day;
  final List<DoctorDaySlot> slots;

  DoctorDaySchedule({required this.doctor, required this.day, required this.slots});

  factory DoctorDaySchedule.fromJson(Map<String, dynamic> json) => DoctorDaySchedule(
        doctor: Doctor.fromJson(json['doctor'] as Map<String, dynamic>),
        day: json['day'] as String,
        slots: (json['slots'] as List<dynamic>)
            .map((e) => DoctorDaySlot.fromJson(e as Map<String, dynamic>))
            .toList(),
      );
}

// -------------------------------------------------------------------------
// autenticación (ver servidor: src/auth/, en particular login-result.model.ts)
// -------------------------------------------------------------------------

// los únicos dos roles que maneja la aplicación - copia exacta del tipo
// [Role] del servidor (src/entities/user.entity.ts). Donde TypeScript se conforma
// con una unión de cadenas ('ADMIN' | 'USER'), Dart tiene una
// verdadera noción de enumeración (enum): más segura (es imposible crear por
// error un Role distinto de estos dos valores), a costa de una pequeña conversión
// explícita de ida y vuelta con la cadena JSON ("ADMIN"/"USER") mediante
// fromString(...)/asString() más abajo - un "type Role =
// 'ADMIN' | 'USER'" de TypeScript no necesita ninguna conversión, una cadena JSON YA
// es, para él, un valor válido del tipo.
enum Role {
  admin,
  user;

  static Role fromString(String value) {
    switch (value) {
      case 'ADMIN':
        return Role.admin;
      case 'USER':
        return Role.user;
      default:
        throw ArgumentError('Unknown role: $value');
    }
  }

  String asString() => this == Role.admin ? 'ADMIN' : 'USER';
}

// forma de los datos devueltos por POST /login (en el envoltorio habitual ServerResponse<T>)
class LoginResult {
  final String accessToken;
  final String login;
  final String name;
  final Role role;

  LoginResult({required this.accessToken, required this.login, required this.name, required this.role});

  factory LoginResult.fromJson(Map<String, dynamic> json) => LoginResult(
        accessToken: json['accessToken'] as String,
        login: json['login'] as String,
        name: json['name'] as String,
        role: Role.fromString(json['role'] as String),
      );
}

Comentemos este código:

  • Líneas 11–22: El comentario de encabezado detalla la diferencia estructural clave de este archivo: una [interface] [TypeScript] solo se verifica en tiempo de COMPILACIÓN; [Dart] CONSERVA sus tipos en tiempo de ejecución, de ahí un constructor [fromJson(...)] explícito en cada clase (ausente de [appointment.models.ts]).
  • Líneas 37–53: [class ServerResponse<T>] y su factory [fromJson(json, parseData)]: recibe una FUNCIÓN ([parseData]) en lugar de apoyarse en un simple [as ServerResponse<T>] como del lado de [TypeScript] (véase [appointment.service.ts]): [Dart] no conoce [T] en tiempo de ejecución (borrado de tipos), por lo que no puede escribir [T.fromJson(...)] por sí mismo.
  • Líneas 71–73: El comentario señala que [Client] se refiere a un PACIENTE del consultorio médico (vocabulario del dominio de negocio), que no debe confundirse con “cliente HTTP” ni con este propio cliente [Flutter], una ambigüedad ya señalada en las tres variantes web anteriores.
  • Líneas 176–192: [enum Role { admin, user; ... }] : reemplaza la unión de cadenas de [TypeScript] [type Role = 'ADMIN' | 'USER'] por una enumeración [Dart] REAL, con una conversión explícita de ida y vuelta hacia la cadena JSON ([fromString]/[asString]), lo que es más seguro (es imposible generar un [Role] no válido), a costa de una conversión que una unión de cadenas no necesita realizar.

5.6. La capa core/services

Image

5.6.1. lib/core/services/settings_service.dart

Adaptación de [core/composables/settings.composable.ts]: mantiene en memoria la URL del servidor [NestJS].

// =========================================================================
// core/services/settings_service.dart
// -------------------------------------------------------------------------
// Port de core/composables/settings.composable.ts (cliente Vue.js de este
// curso): un pequeño "store" que mantiene en memoria la URL del servidor
// NestJS.
//
// Vue.js expone este estado compartido mediante el par [provide]/[inject]: un
// objeto [reactive(...)] creado una sola vez, luego leído/modificado en el lugar
// por cualquier componente descendiente. Flutter no tiene ni [reactive] ni
// [provide]/[inject]: el equivalente estándar del ecosistema (y el que se
// usa en este curso) es un ChangeNotifier - una clase Dart ordinaria
// que, además de sus campos, sabe NOTIFICAR a sus oyentes
// cada vez que un cambio debe provocar un nuevo renderizado, mediante
// la llamada explícita a notifyListeners().
//
// La diferencia esencial con Vue.js: [reactive(...)] envuelve el objeto
// en un proxy de JavaScript que detecta AUTOMÁTICAMENTE cada escritura
// de propiedad (store.apiBaseUrl = ... redibuja por sí solo los componentes que
// leen apiBaseUrl). Un ChangeNotifier de Dart, por su parte, no detecta NADA
// por sí mismo: le corresponde al desarrollador llamar a notifyListeners() tras cada
// modificación - un poco más de disciplina manual, a cambio de un mecanismo
// mucho más simple (sin proxy, sin "magia") de
// entender y depurar.
//
// Es el paquete [provider] (ver pubspec.yaml y lib/main.dart) el que luego
// cumple, alrededor de este ChangeNotifier, el papel de app.provide(...) en el lado
// Vue.js: hace disponible esta única instancia para todo el subárbol de widgets,
// mediante context.watch<SettingsService>() (para "leer y
// volver a suscribirse a los cambios", ver lib/app.dart) o context.read<...>()
// (para "leer una vez, sin volver a suscribirse").
// =========================================================================

import 'package:flutter/foundation.dart';

class SettingsService extends ChangeNotifier {
  String _apiBaseUrl = 'http://localhost:8080';

  String get apiBaseUrl => _apiBaseUrl;

  // equivalente de "setApiBaseUrl(url: string)" en el lado Vue.js - a diferencia de
  // store.apiBaseUrl = url (una simple asignación, suficiente gracias al proxy
  // reactivo), aquí hay que notificar explícitamente a los oyentes después de
  // cambiar el campo privado.
  void setApiBaseUrl(String url) {
    if (url == _apiBaseUrl) {
      return; // evita un redibujado inútil si el valor no ha cambiado realmente
    }
    _apiBaseUrl = url;
    notifyListeners();
  }
}

Comentemos este código:

  • Líneas 36–39: [class SettingsService extends ChangeNotifier] con un campo PRIVADO ([_apiBaseUrl]) y un accesor público ([get apiBaseUrl]): un [ChangeNotifier] es una clase [Dart] ORDINARIA, sin un proxy como [reactive(...)] del lado de [Vue.js]: nada detecta automáticamente la lectura o escritura de una propiedad.
  • Líneas 45–51: [setApiBaseUrl(url)] llama explícitamente a [notifyListeners()] DESPUÉS de actualizar el campo: el paso manual que [store.apiBaseUrl = url] no necesitaba realizar del lado de [Vue.js], ya que el proxy reactivo se encarga de ello por sí solo.

5.6.2. lib/core/services/auth_service.dart

Adaptación de [core/composables/auth.composable.ts]: gestiona la conexión (POST [/login]), mantiene el token [JWT] y garantiza que sobreviva a un reinicio mediante [shared_preferences].

// =========================================================================
// core/services/auth_service.dart
// -------------------------------------------------------------------------
// Port de core/composables/auth.composable.ts (cliente Vue.js de este
// curso): gestiona el inicio de sesión del usuario, llama a POST /login, conserva
// el token JWT recibido (y la identidad/rol que lo acompañan), y hace que
// sobreviva a un reinicio de la aplicación gracias a shared_preferences -
// el equivalente multiplataforma de localStorage (ver más abajo).
//
// Como en el lado Vue.js, este es el único otro lugar de la aplicación, junto con
// core/services/appointment_service.dart, que habla HTTP con el servidor - una
// excepción asumida a la regla "un solo lugar que habla HTTP", que
// refleja, en el lado cliente, la separación ya hecha en el lado servidor entre
// RdvMedecinsController (negocio) y AuthController (autenticación).
//
// DIFERENCIA IMPORTANTE con Vue.js: readStoredSession() (en el lado Vue.js)
// es SÍNCRONO - localStorage.getItem(...) devuelve su valor
// inmediatamente, incluso antes del primer renderizado de la aplicación. shared_
// preferences, por su parte, es SIEMPRE asíncrono (SharedPreferences.getInstance()
// devuelve un Future), incluso en las plataformas donde el almacenamiento subyacente
// es en realidad un archivo local que se lee casi al instante: la API de Dart no
// distingue estos casos, por coherencia entre TODAS las plataformas (en
// la web, esta misma llamada se apoya en window.localStorage, pero la API de Dart
// sigue siendo asíncrona para ser idéntica a los demás destinos). Consecuencia
// concreta: ya no se puede, como en el lado Vue.js, leer la sesión ya
// almacenada ANTES de que se monte el árbol de widgets - se necesita un [init()]
// explícitamente asíncrono, llamado (y ESPERADO con await) desde
// lib/main.dart antes de runApp(...), para evitar que la pantalla de inicio de sesión
// "parpadee" durante una fracción de segundo antes de que se restaure la sesión.
// =========================================================================

import 'dart:convert';

import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';

import '../models/appointment_models.dart';
import 'settings_service.dart';

const String _storageKey = 'rdvmedecins.session';

class AuthService extends ChangeNotifier {
  // recibido en el constructor en lugar de obtenido por inyección de Flutter: en este
  // punto (ver lib/main.dart), todavía no existe ningún widget, por lo que nada
  // como context.read<SettingsService>() sería posible - exactamente
  // la misma razón que la documentada en createAuthStore(settings) en el lado
  // Vue.js (src/main.ts), que también recibe settingsStore como parámetro de función
  // en lugar de mediante inject().
  final SettingsService settings;

  AuthService(this.settings);

  bool isLoggedIn = false;
  String? login;
  String? name;
  Role? role;
  String? accessToken;

  bool get isAdmin => role == Role.admin;

  // -----------------------------------------------------------------------
  // se debe llamar UNA SOLA VEZ, en lib/main.dart, ANTES de runApp(...): relee
  // una sesión posiblemente ya almacenada durante un lanzamiento anterior de
  // la aplicación - equivalente de readStoredSession() en el lado Vue.js, pero
  // explícitamente asíncrono (ver el encabezado de este archivo) en lugar de llamado
  // dentro del propio constructor del store.
  // -----------------------------------------------------------------------
  Future<void> init() async {
    try {
      final prefs = await SharedPreferences.getInstance();
      final raw = prefs.getString(_storageKey);
      if (raw == null) {
        return; // no hay sesión almacenada: seguimos "sin sesión iniciada", con los valores por defecto de arriba
      }
      final session = jsonDecode(raw) as Map<String, dynamic>;
      _applyLocalSession(
        accessToken: session['accessToken'] as String,
        login: session['login'] as String,
        name: session['name'] as String,
        role: Role.fromString(session['role'] as String),
      );
    } catch (_) {
      // shared_preferences puede no estar disponible, o contener un valor
      // corrupto - en ese caso, como en el lado Vue.js (try/catch de
      // readStoredSession()), simplemente consideramos que no hay
      // sesión, en lugar de hacer fallar el arranque de la aplicación.
    }
    // aquí no hay notifyListeners(): init() se espera con await antes de
    // runApp(...) en lib/main.dart, así que ningún widget escucha todavía a este
    // ChangeNotifier cuando se ejecuta este método - notificar
    // sería inútil (e incluso lanzaría una excepción, pues en algunas configuraciones
    // de depuración un ChangeNotifier de Flutter prohíbe notifyListeners() antes de tener al menos un
    // oyente).
  }

  // -----------------------------------------------------------------------
  // equivalente de: POST /login   JSON body { login, password }
  // -----------------------------------------------------------------------
  Future<LoginResult> logIn(String login, String password) async {
    final httpResponse = await http.post(
      Uri.parse('${settings.apiBaseUrl}/login'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'login': login, 'password': password}),
    );
    final envelope = ServerResponse<LoginResult>.fromJson(
      jsonDecode(httpResponse.body) as Map<String, dynamic>,
      (data) => LoginResult.fromJson(data as Map<String, dynamic>),
    );
    if (envelope.status != 0 || envelope.data == null) {
      throw Exception('Login failed');
    }
    final result = envelope.data!;
    await _applySessionAndPersist(result);
    return result;
  }

  // -----------------------------------------------------------------------
  // cierre de sesión: puramente local (sin llamada al servidor - un token JWT no
  // se "revoca" en el lado servidor en este port, expira por sí solo tras
  // JWT_EXPIRES_IN, ver .env del servidor). Se llama tanto al hacer clic en
  // "Log out" (ver lib/app.dart) como desde core/http/auth_http_client.dart
  // cuando una solicitud protegida recibe un 401.
  // -----------------------------------------------------------------------
  Future<void> logOut() async {
    login = null;
    name = null;
    role = null;
    accessToken = null;
    isLoggedIn = false;
    notifyListeners();
    try {
      final prefs = await SharedPreferences.getInstance();
      await prefs.remove(_storageKey);
    } catch (_) {
      // también aquí, un fallo al limpiar el almacenamiento no debe impedir el
      // cierre de sesión en el lado de la aplicación, que ya es efectivo arriba.
    }
  }

  // actualiza los campos reactivos SIN tocar el almacenamiento - usado por
  // init() (que acaba de LEER el almacenamiento, sin necesidad de reescribirlo).
  void _applyLocalSession({
    required String accessToken,
    required String login,
    required String name,
    required Role role,
  }) {
    this.accessToken = accessToken;
    this.login = login;
    this.name = name;
    this.role = role;
    isLoggedIn = true;
  }

  // actualiza los campos reactivos Y persiste la sesión - usado por
  // logIn() arriba. Agrupa lo que applySession(...) hacía
  // en un solo bloque en el lado Vue.js (estado reactivo + localStorage escritos
  // juntos); aquí las dos operaciones están separadas porque la escritura
  // es asíncrona (await prefs.setString(...)) mientras que la actualización
  // de los campos debe ocurrir INMEDIATAMENTE y de forma síncrona
  // (notifyListeners() debe seguir a la asignación de los campos sin esperar la
  // E/S de disco) - invertir el orden retrasaría innecesariamente el refresco
  // de la interfaz.
  Future<void> _applySessionAndPersist(LoginResult result) async {
    _applyLocalSession(
      accessToken: result.accessToken,
      login: result.login,
      name: result.name,
      role: result.role,
    );
    notifyListeners();
    try {
      final prefs = await SharedPreferences.getInstance();
      await prefs.setString(
        _storageKey,
        jsonEncode({
          'accessToken': result.accessToken,
          'login': result.login,
          'name': result.name,
          'role': result.role.asString(),
        }),
      );
    } catch (_) {
      // la sesión sigue siendo válida EN MEMORIA durante esta ejecución de
      // la aplicación aunque falle la persistencia (cuota excedida,
      // almacenamiento de solo lectura...) - solo un reinicio futuro de
      // la aplicación saldría perjudicado (el usuario tendría que volver a iniciar sesión).
    }
  }
}

Comentemos este código:

  • Líneas 16–29: El comentario de encabezado detalla la diferencia más significativa de este archivo: [readStoredSession()] del lado de [Vue.js] es SÍNCRONO; [shared_preferences] es SIEMPRE asíncrono, sea cual sea la plataforma, de ahí un [async] [init()] explícito, al que [lib/main.dart] espera con await ANTES de [runApp(...)].
  • Líneas 69–95: [Future<void> init() async { ... }] : lee la sesión almacenada, si existe, protegido por un [try/catch]; la misma precaución que con el [try/catch] de [readStoredSession()] del lado de [Vue.js] (almacenamiento no disponible o valor dañado).
  • Líneas 100–116: [logIn(login, password)] : llama a POST [/login] con el paquete [http] (el equivalente de [fetch]), lanza una excepción estándar de [Dart] ([throw Exception(...)]) en caso de fallo, que luego es interceptada por un [try/catch] [Dart], tal como el [throw new Error(...)] de [auth.composable.ts] era interceptado por un [.catch(...)] [JavaScript].
  • Líneas 165–190: [_applySessionAndPersist(...)] : actualiza los campos Y llama a [notifyListeners()] ANTES de escribir en [shared_preferences]: el orden es deliberado, pues la interfaz debe actualizarse INMEDIATAMENTE sin esperar una escritura asíncrona en disco, mientras que [applySession(...)] del lado de [Vue.js] realizaba ambas operaciones en una sola instrucción síncrona.

5.6.3. lib/core/services/appointment_service.dart

Adaptación de [core/services/appointment.service.ts]: las cinco llamadas de lógica de negocio al servidor, construidas sobre [core/http/auth_http_client.dart] (más abajo) en lugar de directamente sobre el paquete [http].

// =========================================================================
// core/services/appointment_service.dart
// -------------------------------------------------------------------------
// Port de core/services/appointment.service.ts (cliente Vue.js de este curso): la
// capa [Services] del cliente Flutter - el ÚNICO lugar de la aplicación
// (junto con core/services/auth_service.dart para el inicio de sesión en sí) que
// habla HTTP con el servidor NestJS.
//
// Vue.js expone este servicio como un COMPOSABLE (useAppointmentService()), a su vez
// construido sobre otros dos composables (useAuthFetch(), useSettings()).
// Como Flutter/Dart no tiene ni composables ni inyección de dependencias integrada
// en el lenguaje, este archivo vuelve a ser una CLASE ordinaria, construida una sola
// vez en lib/main.dart con sus dos dependencias pasadas al
// constructor - exactamente el mismo principio que core/http/auth_http_client.dart,
// y la forma más directa de portar "un conjunto de funciones que
// dependen de otra cosa" cuando el lenguaje de destino no ofrece composables.
// =========================================================================

import 'dart:convert';

import 'package:http/http.dart' as http;

import '../http/auth_http_client.dart';
import '../models/appointment_models.dart';
import 'settings_service.dart';

class AppointmentService {
  final AuthHttpClient authHttp;
  final SettingsService settings;

  AppointmentService(this.authHttp, this.settings);

  // -----------------------------------------------------------------------
  // función privada común: todas las respuestas del servidor tienen la forma
  // { status, data } (ver core/models/appointment_models.dart). La regla
  // "si status != 0, es un error" se centraliza AQUÍ, una sola vez, en lugar de
  // repetirse en cada uno de los métodos siguientes - exactamente el
  // papel de extract<T>(...) en el lado Vue.js.
  //
  // [parseData] es el mismo tipo de parámetro que el ya visto en
  // ServerResponse.fromJson(...) (ver appointment_models.dart): la función que sabe cómo
  // reconstruir un T a partir del JSON sin procesar del campo [data], ya que Dart
  // no puede hacerlo por sí solo (no existe un "T.fromJson(...)" genérico).
  // -----------------------------------------------------------------------
  T _extract<T>(http.Response httpResponse, T Function(dynamic rawData) parseData) {
    final envelope = ServerResponse<T>.fromJson(
      jsonDecode(httpResponse.body) as Map<String, dynamic>,
      parseData,
    );
    if (envelope.status != 0) {
      // el error de "negocio" del servidor se convierte en una excepción clásica de Dart,
      // que los widgets que llaman pueden capturar con un
      // simple try/catch (ver lib/app.dart) - exactamente como el
      // "throw new Error(...)" de appointment.service.ts, capturado por el
      // .catch(...) de src/app/App.vue.
      throw Exception('The server responded with error status ${envelope.status}');
    }
    return envelope.data as T;
  }

  // -----------------------------------------------------------------------
  // equivalente de: GET /getAllDoctors
  // -----------------------------------------------------------------------
  Future<List<Doctor>> getAllDoctors() async {
    final httpResponse = await authHttp.get(Uri.parse('${settings.apiBaseUrl}/getAllDoctors'));
    return _extract<List<Doctor>>(
      httpResponse,
      (data) => (data as List<dynamic>).map((e) => Doctor.fromJson(e as Map<String, dynamic>)).toList(),
    );
  }

  // -----------------------------------------------------------------------
  // equivalente de: GET /getAllClients
  // -----------------------------------------------------------------------
  Future<List<Client>> getAllClients() async {
    final httpResponse = await authHttp.get(Uri.parse('${settings.apiBaseUrl}/getAllClients'));
    return _extract<List<Client>>(
      httpResponse,
      (data) => (data as List<dynamic>).map((e) => Client.fromJson(e as Map<String, dynamic>)).toList(),
    );
  }

  // -----------------------------------------------------------------------
  // equivalente de: GET /getDoctorScheduleOfDay/{doctorId}/{day}
  // -----------------------------------------------------------------------
  Future<DoctorDaySchedule> getDoctorScheduleOfDay(int doctorId, String day) async {
    final httpResponse = await authHttp.get(
      Uri.parse('${settings.apiBaseUrl}/getDoctorScheduleOfDay/$doctorId/$day'),
    );
    return _extract<DoctorDaySchedule>(
      httpResponse,
      (data) => DoctorDaySchedule.fromJson(data as Map<String, dynamic>),
    );
  }

  // -----------------------------------------------------------------------
  // equivalente de: POST /addAppointment   JSON body { day, clientId, slotId }
  // -----------------------------------------------------------------------
  Future<AppointmentJson> addAppointment(String day, int clientId, int slotId) async {
    final httpResponse = await authHttp.post(
      Uri.parse('${settings.apiBaseUrl}/addAppointment'),
      body: jsonEncode({'day': day, 'clientId': clientId, 'slotId': slotId}),
    );
    return _extract<AppointmentJson>(httpResponse, (data) => AppointmentJson.fromJson(data as Map<String, dynamic>));
  }

  // -----------------------------------------------------------------------
  // equivalente de: POST /deleteAppointment   JSON body { appointmentId }
  // -----------------------------------------------------------------------
  Future<void> deleteAppointment(int appointmentId) async {
    final httpResponse = await authHttp.post(
      Uri.parse('${settings.apiBaseUrl}/deleteAppointment'),
      body: jsonEncode({'appointmentId': appointmentId}),
    );
    _extract<Object?>(httpResponse, (data) => data);
  }
}

Comentemos este código:

  • Líneas 27–31: [class AppointmentService { final AuthHttpClient authHttp; final SettingsService settings; AppointmentService(this.authHttp, this.settings); }] : vuelve a ser una CLASE ORDINARIA, construida una sola vez en [lib/main.dart] con sus dependencias pasadas al constructor, mientras que [Vue.js] usaba un COMPOSABLE, [useAppointmentService()], que a su vez se construía a partir de otros dos composables.
  • Líneas 45–59: [T _extract<T>(httpResponse, parseData)]: centraliza, una sola vez, la regla “si [status != 0], es un error”, exactamente el papel de [extract<T>(...)] del lado de [Vue.js]; el parámetro [parseData] es el mismo tipo de función que ya se encontró en [ServerResponse.fromJson(...)].
  • Líneas 99–105: [addAppointment(day, clientId, slotId)] : [jsonEncode({...})] construye el cuerpo JSON de la solicitud POST, el equivalente en [Dart] de [JSON.stringify({...})] del lado de [Vue.js].
  • Líneas 110–116: [Future<void> deleteAppointment(int appointmentId) async { ... }] : llama a [_extract<Object?>(...)] sin usar su resultado: el servidor devuelve [ServerResponse.ok(null)] para esta ruta, por lo que no hay nada más específico que indicar; la misma elección que [extract<null>(httpResponse)] del lado de [Vue.js].

5.7. La capa core/http

Image

5.7.1. lib/core/http/auth_http_client.dart

Adaptación de [core/interceptors/auth.interceptor.ts]: agrega el token [JWT] a cada solicitud protegida y cierra la sesión del usuario ante una respuesta 401.

// =========================================================================
// core/http/auth_http_client.dart
// -------------------------------------------------------------------------
// Port de core/interceptors/auth.interceptor.ts (cliente Vue.js de este
// curso). Este archivo hace dos cosas, exactamente como su
// equivalente de Vue.js (a su vez un port de los clientes Angular y React):
//   1. añade el encabezado "Authorization: Bearer <token>" a cada solicitud, si
//      el usuario ha iniciado sesión (ver AuthService.accessToken);
//   2. si el servidor responde 401 (token ausente, inválido o expirado),
//      cierra limpiamente la sesión del usuario en el lado cliente.
//
// [fetch] (usado en el lado Vue.js y React) y [HttpClient] de Angular no
// tienen un equivalente DIRECTO en Dart: el paquete [http] (ver pubspec.yaml)
// ofrece funciones libres (http.get(...), http.post(...)) en lugar de
// un objeto que se pueda interceptar globalmente. El port sigue siendo, sin embargo, fiel
// en ESPÍRITU a useAuthFetch(): en lugar de una función composable que devuelve
// un "fetch mejorado", aquí se escribe una CLASE REAL, [AuthHttpClient],
// cuyos métodos get(...)/post(...) cumplen exactamente el mismo papel -
// cualquier código que quiera hablar con el servidor (aquí, solo
// core/services/appointment_service.dart) llama a ESTOS métodos en lugar de al
// paquete http directamente.
//
// Escribir una clase en lugar de una función composable es una elección natural
// en Dart/Flutter: a diferencia de un <script setup> de Vue.js (que
// se ejecuta una sola vez por instancia de componente, ver el comentario de
// auth.interceptor.ts), un ChangeNotifier o una clase de servicio de Dart
// no tiene un "cuerpo ejecutado en cada renderizado" del que desconfiar -
// por lo tanto tampoco se necesita un equivalente de useCallback(), pero por una razón
// distinta: simplemente no existe ninguna
// función "recreada en cada renderizado", pues la clase se construye una sola vez
// en lib/main.dart (ver más abajo).
// =========================================================================

import 'dart:async' show unawaited;

import 'package:http/http.dart' as http;

import '../services/auth_service.dart';

class AuthHttpClient {
  final AuthService auth;
  final http.Client _client = http.Client();

  AuthHttpClient(this.auth);

  Future<http.Response> get(Uri url) => _send(() => _client.get(url, headers: _headers()));

  Future<http.Response> post(Uri url, {required Object body}) => _send(
        () => _client.post(
          url,
          headers: {..._headers(), 'Content-Type': 'application/json'},
          body: body,
        ),
      );

  // construye los encabezados comunes a toda solicitud protegida - el equivalente
  // de "new Headers(options.headers); if (auth.accessToken) {...}" en el lado
  // Vue.js, pero como un simple Map<String, String> (el tipo
  // que espera el paquete http, más simple aquí que una clase Headers).
  Map<String, String> _headers() {
    final accessToken = auth.accessToken;
    return accessToken == null ? {} : {'Authorization': 'Bearer $accessToken'};
  }

  // factoriza lo que get(...) y post(...) tienen en común: ejecutar la llamada
  // HTTP y luego, si la respuesta es 401, cerrar la sesión del usuario - la
  // función [call] recibida como parámetro cumple el papel de las "...options"
  // pasadas por fetch(path, { ...options, headers }) en el lado
  // Vue.js: en este punto aún no sabemos si es un GET
  // o un POST, solo que hay que ejecutarla y examinar su respuesta.
  Future<http.Response> _send(Future<http.Response> Function() call) async {
    final response = await call();
    // un 401 durante una sesión significa que el token ya no es válido
    // (expirado, o servidor reiniciado): se cierra limpiamente la sesión del cliente
    // en lugar de dejar la aplicación en un estado incoherente (con sesión iniciada
    // en apariencia, pero sin que ninguna solicitud tenga éxito). No hay
    // ningún "await" sobre logOut(): la respuesta HTTP (incluso una de error)
    // debe devolverse a quien llama sin esperar a que termine la limpieza del
    // almacenamiento local, que se completa por su lado en segundo plano.
    if (response.statusCode == 401) {
      unawaited(auth.logOut());
    }
    return response;
  }
}

Comentemos este código:

  • Líneas 12–31: El comentario de encabezado explica la elección de una CLASE ([AuthHttpClient]) en lugar de un composable: [fetch] ([Vue.js]/[React]) y [HttpClient] ([Angular]) no tienen un equivalente directo en [Dart]; el paquete [http] ofrece funciones independientes en lugar de un único objeto que se pueda interceptar globalmente.
  • Líneas 46–54: [get(...)]/[post(...)]: los únicos dos métodos a los que llama [appointment_service.dart] ; nunca llama directamente al paquete [http].
  • Líneas 60–63: [_headers()]: construye [{'Authorization': 'Bearer $accessToken'}] si el usuario ha iniciado sesión; es el equivalente de [new Headers(options.headers); if (auth.accessToken) {...}] del lado de [Vue.js], pero en forma de un simple [Map<String, String>].
  • Líneas 71–84: [_send(call)] : extrae lo que [get(...)] y [post(...)] tienen en común; [unawaited(auth.logOut())] documenta EXPLÍCITAMENTE que se decide no esperar a [Future]: la respuesta HTTP (incluso si contiene un error) debe devolverse al llamador sin esperar a que termine la purga del almacenamiento local.

5.8. La capa core/i18n

Image

5.8.1. lib/core/i18n/translations_service.dart

Adaptación FUSIONADA de [src/i18n.ts] Y de [core/composables/language.composable.ts]: el cambio de interfaz entre francés e inglés, reimplementado sin una biblioteca de terceros (véase el comentario de encabezado del archivo para conocer el motivo de esta elección).

// =========================================================================
// core/i18n/translations_service.dart
// -------------------------------------------------------------------------
// Port FUSIONADO de src/i18n.ts (configuración de vue-i18n) Y de
// core/composables/language.composable.ts (cliente Vue.js de este curso).
// Vue.js separa ambos porque vue-i18n, una biblioteca de terceros ya
// rica en funciones (pluralización, formatos de fecha/número...),
// hace todo el trabajo real de traducción; language.composable.ts
// solo le añade el almacenamiento de la elección de idioma en
// localStorage. Flutter no tiene un equivalente directo de vue-i18n/react-
// i18next/@ngx-translate/core instalado por defecto: en lugar de añadir
// una dependencia adicional, este archivo reimplementa en unas pocas
// líneas exactamente el subconjunto que usa este curso - un
// diccionario con claves con puntos ("LOGIN.TITLE") y una función t(key).
//
// DIFERENCIA IMPORTANTE ENTRE PLATAFORMAS (ver también el Capítulo "Portar
// la aplicación a móvil, escritorio y web"): src/i18n.ts obtiene
// cada diccionario con un fetch("/i18n/{language}.json") - una URL
// relativa, que supone un SERVIDOR WEB que sirve los archivos del cliente
// (Vite en desarrollo, un servidor estático una vez compilado). Una
// aplicación Flutter móvil o de escritorio NO tiene NINGÚN SERVIDOR WEB que la sirva
// : el código Y sus recursos estáticos (aquí, los archivos JSON) están
// INCLUIDOS juntos en un único paquete instalado en el dispositivo (.apk,
// .app, .exe...). Por eso este archivo usa rootBundle.loadString(...)
// - la API de Flutter que lee un archivo declarado en la sección [assets] de
// pubspec.yaml directamente desde este paquete - en lugar de una llamada de red.
// En el destino web, rootBundle se apoya internamente en una solicitud HTTP real
// a los archivos publicados junto a la aplicación, pero este detalle
// permanece invisible aquí: el MISMO código Dart funciona, sin ninguna condición
// de plataforma, en los 3 entornos - exactamente el argumento central de
// este capítulo.
// =========================================================================

import 'dart:convert';

import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart' show rootBundle, ServicesBinding;
import 'package:shared_preferences/shared_preferences.dart';

const String _storageKey = 'rdvmedecins.language';
final String _defaultLanguage = ServicesBinding.instance.platformDispatcher.locale.languageCode == 'fr' ? 'fr' : 'en';

class TranslationsService extends ChangeNotifier {
  String currentLanguage = _defaultLanguage;

  // diccionarios ya cargados (evita releer un archivo de recursos ya visto
  // durante la sesión) - misma optimización que loadedDictionaries en el lado
  // Vue.js (src/i18n.ts), pero aquí se conserva el propio diccionario decodificado
  // en lugar de un simple Set de idiomas ya vistos: Vue.js podía conformarse con
  // un Set porque vue-i18n MISMO mantiene los diccionarios cargados
  // en memoria (setLocaleMessage); al no tener una biblioteca equivalente
  // aquí, este papel de caché debe asumirlo directamente este
  // archivo.
  final Map<String, Map<String, dynamic>> _dictionaries = {};

  // -----------------------------------------------------------------------
  // se debe llamar UNA SOLA VEZ, en lib/main.dart, ANTES de runApp(...):
  // restaura el idioma almacenado durante un lanzamiento anterior (si lo
  // hay) y carga su diccionario - equivalente del bloque final de
  // createLanguageStore() en el lado Vue.js (la lectura de savedLanguage en
  // localStorage), pero hecho explícitamente asíncrono por las mismas
  // razones ya documentadas en core/services/auth_service.dart
  // (shared_preferences es SIEMPRE asíncrono, a diferencia de
  // localStorage).
  // -----------------------------------------------------------------------
  Future<void> init() async {
    String startLanguage = _defaultLanguage;
    try {
      final prefs = await SharedPreferences.getInstance();
      startLanguage = prefs.getString(_storageKey) ?? _defaultLanguage;
    } catch (_) {
      // no hay preferencia legible: se inicia en el idioma por defecto (inglés, o
      // francés en un dispositivo en francés), como en el lado Vue.js.
    }
    await _loadDictionary(startLanguage);
    currentLanguage = startLanguage;
    // aquí no hay notifyListeners(), por la misma razón que en
    // AuthService.init(): este método se espera con await antes de
    // runApp(...), así que ningún widget escucha todavía a este ChangeNotifier.
  }

  // -----------------------------------------------------------------------
  // equivalente de: changeLanguage(language) en el lado Vue.js (disparado por los
  // botones FR/EN de lib/app.dart, ver más adelante en este capítulo).
  // -----------------------------------------------------------------------
  Future<void> changeLanguage(String language) async {
    if (language == currentLanguage) {
      return;
    }
    await _loadDictionary(language);
    currentLanguage = language;
    notifyListeners(); // aquí, en cambio, la aplicación ya está en ejecución: sí notificamos
    try {
      final prefs = await SharedPreferences.getInstance();
      await prefs.setString(_storageKey, language);
    } catch (_) {
      // el cambio de idioma sigue siendo efectivo durante esta ejecución aunque falle
      // su almacenamiento - solo un reinicio futuro saldría perjudicado.
    }
  }

  // -----------------------------------------------------------------------
  // equivalente de: loadDictionary(language) en el lado Vue.js - mismo
  // principio de caché (loadedDictionaries), pero leyendo un recurso incluido
  // en lugar de un fetch() de red (ver el encabezado de este archivo).
  // -----------------------------------------------------------------------
  Future<void> _loadDictionary(String language) async {
    if (_dictionaries.containsKey(language)) {
      return; // ya cargado durante un cambio de idioma anterior
    }
    final content = await rootBundle.loadString('assets/i18n/$language.json');
    _dictionaries[language] = jsonDecode(content) as Map<String, dynamic>;
  }

  // -----------------------------------------------------------------------
  // la propia función de traducción - llamada t('LOGIN.TITLE') desde
  // los widgets (ver lib/features/...), exactamente como t('LOGIN.TITLE')
  // en el lado Vue.js (useI18n().t). La clave tiene "puntos" (un punto separa
  // cada nivel): por eso descendemos por el diccionario JSON anidado un
  // segmento a la vez, en lugar de aplanar el diccionario de una vez por
  // todas como hace vue-i18n internamente - una elección que sigue siendo
  // más que suficiente para el tamaño de estos dos diccionarios.
  // -----------------------------------------------------------------------
  String t(String key) {
    final dictionary = _dictionaries[currentLanguage];
    if (dictionary == null) {
      return key; // diccionario aún no cargado: se muestra la propia clave, como último recurso
    }
    dynamic currentValue = dictionary;
    for (final segment in key.split('.')) {
      if (currentValue is Map<String, dynamic> && currentValue.containsKey(segment)) {
        currentValue = currentValue[segment];
      } else {
        return key; // clave no encontrada: mismo comportamiento de respaldo que arriba
      }
    }
    return currentValue is String ? currentValue : key;
  }
}

Comentemos este código:

  • Líneas 16–31: El comentario de encabezado detalla la DIFERENCIA DE PLATAFORMA más importante de todo este cliente: [src/i18n.ts] obtiene cada diccionario mediante [fetch("/i18n/{language}.json")], una URL que depende de un SERVIDOR WEB; una aplicación móvil o de escritorio no dispone de uno, de ahí el uso de [rootBundle.loadString(...)] en lugar de una llamada de red; el mismo código funciona, sea cual sea la plataforma, en los tres entornos (véase el Capítulo 5).
  • Líneas 66–80: [init()] : restaura el idioma guardado (o el idioma predeterminado: inglés, o francés en un dispositivo en francés) y carga su diccionario; al igual que [AuthService.init()], aquí no hay [notifyListeners()] (ningún widget está escuchando este [ChangeNotifier] en esta etapa).
  • Líneas 107–113: [_loadDictionary(language)] : el mismo principio de almacenamiento en caché que [loadedDictionaries] del lado de [Vue.js], pero almacena directamente el diccionario decodificado en lugar de un simple [Set] de idiomas vistos previamente: [vue-i18n] mantenía los diccionarios en memoria ([setLocaleMessage]); aquí, este papel de caché debe ser asumido directamente por este archivo.
  • Líneas 124–138: [String t(String key) { ... }] : recorre el diccionario JSON anidado un segmento a la vez ([key.split('.')]), en lugar de aplanar el diccionario de una vez por todas como lo hace internamente [vue-i18n]; una elección más que suficiente para el tamaño de estos dos diccionarios.

5.8.2. assets/i18n/fr.json y assets/i18n/en.json

Tomados tal cual de [public/i18n/fr.json]/[en.json] (cliente [Vue.js]), con un único cambio: la clave [APP.TITLE] ahora hace referencia a “[Flutter]” en lugar de “[Vue.js]”. Ambos archivos deben seguir siendo estructuralmente idénticos (las mismas claves, en ambos idiomas); esto garantiza que una clave exista en los dos diccionarios.

5.9. La capa features

Image

Un widget por funcionalidad: la pantalla de inicio de sesión, la selección de un médico y un día, la visualización del calendario y el cuadro de diálogo de reserva de citas.

5.9.1. lib/features/login/login_page.dart

Adaptación de [src/app/features/login/Login.vue]: la pantalla de inicio de sesión.

// =========================================================================
// features/login/login_page.dart
// -------------------------------------------------------------------------
// Port de src/app/features/login/Login.vue (cliente Vue.js de este curso):
// la pantalla de inicio de sesión. Como su equivalente de Vue.js, este widget no sabe
// nada de la agenda ni de las citas: se limita a recoger un par
// (login, password), pasarlo a AuthService.logIn(...),
// y mostrar un posible error.
//
// DIFERENCIA ESTRUCTURAL con Vue.js: Login.vue declara su estado local
// (login, password, submitting, error) con simples ref(...) - Vue.js
// "redibuja" entonces automáticamente el <template> cuando uno de estos ref
// cambia, SIN ninguna noción de "widget con o sin estado". Flutter distingue
// explícitamente dos tipos de widgets: StatelessWidget (nada cambia jamás
// después de la construcción) y StatefulWidget (posee un estado mutable
// y sabe redibujarse mediante setState(...)). Este componente necesita
// recordar lo que escribe el usuario Y saber redibujarse cuando
// submitting/error cambian: por eso es un StatefulWidget - la
// clase LoginPage de abajo SOLO declara createState(), todo el estado y
// toda la lógica viven en _LoginPageState, la clase "gemela"
// asociada.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import '../../core/i18n/translations_service.dart';
import '../../core/services/auth_service.dart';

class LoginPage extends StatelessWidget {
  const LoginPage({super.key});

  @override
  Widget build(BuildContext context) {
    return const _LoginForm();
  }
}

class _LoginForm extends StatefulWidget {
  const _LoginForm();

  @override
  State<_LoginForm> createState() => _LoginFormState();
}

class _LoginFormState extends State<_LoginForm> {
  // TextEditingController: a diferencia de v-model="login" en el lado Vue.js
  // (que enlaza directamente un campo con un ref, en ambos sentidos, con
  // un solo atributo), Flutter no tiene enlace bidireccional integrado en
  // el widget TextField - hay que poseer explícitamente un controlador,
  // leerlo (controller.text) y LIBERARLO (dispose()) una vez destruido el widget,
  // ver dispose() más abajo. Es más verboso de escribir una vez,
  // pero hace explícito un ciclo de vida (creación -> lectura -> liberación
  // de recursos) que Vue.js gestiona por sí mismo entre bastidores para un ref.
  final TextEditingController _loginController = TextEditingController();
  final TextEditingController _passwordController = TextEditingController();

  bool _submitting = false;
  String? _error;

  @override
  void dispose() {
    // libera los recursos asociados a los controladores - olvidar esto
    // provocaría una fuga de memoria cada vez que se recreara esta pantalla.
    // Vue.js, cuyos ref() son simples objetos JavaScript
    // recolectados por el recolector de basura como cualquier otro objeto,
    // no tiene ningún paso de este tipo que prever.
    _loginController.dispose();
    _passwordController.dispose();
    super.dispose();
  }

  Future<void> _onSubmit() async {
    final login = _loginController.text.trim();
    final password = _passwordController.text;
    if (login.isEmpty || password.isEmpty) {
      return;
    }
    setState(() {
      _error = null;
      _submitting = true;
    });
    try {
      // context.read<AuthService>(): una lectura "única", SIN volver a suscribirse
      // a los cambios futuros (a diferencia de context.watch<...>(), ver
      // lib/app.dart) - exactamente adecuada para una llamada puntual disparada por
      // una acción del usuario, en lugar de para una visualización que debe
      // mantenerse actualizada. Es el equivalente en Flutter/provider de
      // "const auth = useAuth();" en el lado Vue.js, donde auth.logIn(...) se
      // llama simplemente sin ninguna distinción particular (Vue.js no tiene
      // esta distinción entre lectura única y resuscripción: useAuth() siempre devuelve
      // el mismo objeto reactivo, sea cual sea el uso que se le dé).
      await context.read<AuthService>().logIn(login, password);
      if (!mounted) return; // el widget pudo haber sido destruido mientras se esperaba al servidor
      setState(() => _submitting = false);
    } catch (_) {
      if (!mounted) return;
      setState(() {
        _submitting = false;
        _error = 'LOGIN.ERROR';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    // context.watch<TranslationsService>(): a diferencia de
    // context.read<AuthService>() usado en _onSubmit() arriba,
    // AQUÍ queremos que este widget se redibuje automáticamente si el idioma
    // cambia (botones FR/EN de lib/app.dart) - watch() se suscribe a los
    // cambios futuros, mientras que read() solo hace una lectura puntual.
    final t = context.watch<TranslationsService>().t;

    return Center(
      child: ConstrainedBox(
        constraints: const BoxConstraints(maxWidth: 420),
        child: Card(
          child: Padding(
            padding: const EdgeInsets.all(24),
            // Form agrupa los campos y permite enviar pulsando
            // "Enter" desde cualquiera de ellos (onFieldSubmitted
            // más abajo) - el equivalente del <form @submit.prevent="onSubmit">
            // de Login.vue: Enter en un campo Y un clic en el botón
            // disparan ambos el mismo onSubmit().
            child: Column(
              mainAxisSize: MainAxisSize.min,
              crossAxisAlignment: CrossAxisAlignment.stretch,
              children: [
                Text(t('LOGIN.TITLE'), style: Theme.of(context).textTheme.titleLarge),
                const SizedBox(height: 16),
                if (_error != null) ...[
                  Container(
                    padding: const EdgeInsets.all(8),
                    decoration: BoxDecoration(
                      color: Theme.of(context).colorScheme.errorContainer,
                      borderRadius: BorderRadius.circular(4),
                    ),
                    child: Text(
                      t(_error!),
                      style: TextStyle(color: Theme.of(context).colorScheme.onErrorContainer),
                    ),
                  ),
                  const SizedBox(height: 16),
                ],
                TextField(
                  controller: _loginController,
                  decoration: InputDecoration(labelText: t('LOGIN.LOGIN_LABEL')),
                  textInputAction: TextInputAction.next,
                ),
                const SizedBox(height: 12),
                TextField(
                  controller: _passwordController,
                  decoration: InputDecoration(labelText: t('LOGIN.PASSWORD_LABEL')),
                  obscureText: true,
                  textInputAction: TextInputAction.done,
                  // onSubmitted: disparado por la tecla "Enter" (o su equivalente en el
                  // teclado virtual móvil) - la contraparte de
                  // @submit.prevent colocado en la etiqueta <form> en el lado Vue.js,
                  // aquí colocado directamente en el ÚLTIMO campo del formulario.
                  onSubmitted: (_) => _onSubmit(),
                ),
                const SizedBox(height: 20),
                FilledButton(
                  onPressed: _submitting ? null : _onSubmit,
                  child: Text(_submitting ? t('LOGIN.SUBMITTING') : t('LOGIN.SUBMIT')),
                ),
                const SizedBox(height: 16),
                Text(
                  '${t('LOGIN.DEMO_ACCOUNTS_PREFIX')} admin / admin ${t('LOGIN.DEMO_ACCOUNTS_ADMIN')} '
                  '${t('LOGIN.DEMO_ACCOUNTS_OR')} user / user ${t('LOGIN.DEMO_ACCOUNTS_USER')}.',
                  style: Theme.of(context).textTheme.bodySmall,
                ),
              ],
            ),
          ),
        ),
      ),
    );
  }
}

Comentemos este código:

  • Líneas 39–44: [LoginPage] (un simple front-end [StatelessWidget]) delega TODO en [_LoginForm]/[_LoginFormState] : el comentario de encabezado explica por qué esta pantalla, que debe almacenar lo que escribe el usuario Y redibujarse cuando cambian [_submitting]/[_error], NO PUEDE ser simplemente un [StatelessWidget], a diferencia de [Login.vue], donde [ref(...)] no hace tal distinción.
  • Líneas 55–56: [final TextEditingController _loginController = TextEditingController();] : reemplaza a [v-model="login"]: no hay enlace bidireccional integrado en [TextField]; se debe especificar explícitamente un controlador.
  • Líneas 61–71: [dispose() { _loginController.dispose(); _passwordController.dispose(); ... }] : libera ambos controladores; una omisión aquí provocaría una fuga de memoria cada vez que se recrea esta pantalla, un paso que [Vue.js] no necesita tener en cuenta (sus objetos [ref()] simplemente son recolectados por el recolector de basura).
  • Líneas 93–102: [await context.read<AuthService>().logIn(login, password);] dentro de un [try/catch] : [context.read<...>()] (lectura única, SIN volver a suscribirse) en lugar de [context.watch<...>()] (véase [lib/app.dart]), que es adecuado para una llamada única desencadenada por una acción del usuario.
  • Línea 160: [onSubmitted: (_) => _onSubmit(),] colocado en el ÚLTIMO campo (contraseña): el equivalente de [@submit.prevent="onSubmit"], que se define en la etiqueta [<form>] del lado de [Vue.js]: presionar Enter en el campo Y hacer clic en el botón activan el mismo [_onSubmit()].

5.9.2. lib/features/doctor_day_picker/doctor_day_picker.dart

Adaptación de [src/app/features/doctor-day-picker/DoctorDayPicker.vue]: seleccionar un médico y una fecha, y luego solicitar ver su agenda.

// =========================================================================
// features/doctor_day_picker/doctor_day_picker.dart
// -------------------------------------------------------------------------
// Port de src/app/features/doctor-day-picker/DoctorDayPicker.vue (cliente Vue.js
// de este curso): el widget usado para elegir un médico y un
// día, y luego pedir ver su agenda.
//
// Un [defineProps]/[defineEmits] de Vue.js (props como entradas, eventos como
// salidas) se convierte aquí, muy directamente, en un CONSTRUCTOR de Dart: las
// props son los parámetros con nombre del constructor (doctors, onSearch), y
// "emitir un evento" pasa a ser simplemente LLAMAR a la función recibida como
// parámetro - exactamente la elección ya hecha por el cliente React de este
// curso (una prop de función, onSearch), en lugar de la declaración explícita
// [defineEmits] propia de Vue.js. Flutter, como React, no hace NINGUNA
// distinción sintáctica entre "prop normal" y "prop usada para
// notificar al padre": es una función como cualquier otra, pasada por el
// padre (ver lib/app.dart) al construir este widget.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:intl/intl.dart';
import 'package:provider/provider.dart';

import '../../core/i18n/translations_service.dart';
import '../../core/models/appointment_models.dart';

// formato "yyyy-MM-dd" - el mismo formato de fecha que en el lado Vue.js
// (new Date().toISOString().slice(0, 10)), pero construido aquí explícitamente con el paquete intl
// en lugar de recortar una cadena: el DateTime de Dart
// no tiene un método toISOString() integrado.
final DateFormat _dayFormat = DateFormat('yyyy-MM-dd');

class DoctorDayPicker extends StatefulWidget {
  final List<Doctor> doctors;

  // onSearch(doctorId, day): el equivalente directo de
  // "search: [criteria: { doctorId: number; day: string }]" en el lado
  // Vue.js - aquí, dos parámetros posicionales en lugar de un único objeto
  // {doctorId, day}, una elección tan válida como la otra en Dart.
  final void Function(int doctorId, String day) onSearch;

  const DoctorDayPicker({super.key, required this.doctors, required this.onSearch});

  @override
  State<DoctorDayPicker> createState() => _DoctorDayPickerState();
}

class _DoctorDayPickerState extends State<DoctorDayPicker> {
  // estado puramente local de este widget (lo que está seleccionado en los menús,
  // mientras el usuario no haya hecho clic en el botón) - el equivalente
  // directo de selectedDoctorId/selectedDay en el lado Vue.js, como
  // simples campos de _DoctorDayPickerState en lugar de ref(...): un
  // StatefulWidget de Flutter no necesita ningún "envoltorio" particular para
  // un campo local, basta setState(...) (ver _onDoctorChoice más abajo) para
  // señalar que hace falta un redibujado.
  int? _selectedDoctorId;
  DateTime _selectedDay = DateTime.now();

  Future<void> _pickDay() async {
    // Flutter no tiene un equivalente directo de <input type="date"> (un
    // widget de entrada de fecha NATIVO DEL NAVEGADOR, del que Vue.js podía
    // beneficiarse en la web): en los 3 entornos a los que apunta este cliente
    // (móvil, escritorio, web), es Flutter MISMO quien dibuja el
    // selector de fecha (showDatePicker(...) más abajo) - un widget
    // Material, idéntico en apariencia en los 3 destinos. Es una ilustración
    // muy concreta de la promesa "una sola base de código para 3
    // entornos": donde Vue.js se apoyaba en un bloque de construcción del
    // navegador (ausente en móvil y escritorio), Flutter aporta su
    // propio bloque de construcción, disponible EN TODAS PARTES.
    final picked = await showDatePicker(
      context: context,
      initialDate: _selectedDay,
      firstDate: DateTime(2020),
      lastDate: DateTime(2100),
    );
    if (picked != null) {
      setState(() => _selectedDay = picked);
    }
  }

  void _onSearchClick() {
    final doctorId = _selectedDoctorId;
    if (doctorId == null) {
      return; // de todos modos el botón está deshabilitado en este caso (ver build() más abajo)
    }
    // widget.onSearch(...): se llama a la función recibida del padre -
    // exactamente el equivalente de emit('search', ...) en el lado Vue.js, o de
    // la llamada a la prop onSearch(...) en el lado React. El prefijo "widget."
    // es necesario aquí porque _DoctorDayPickerState es una clase
    // SEPARADA de DoctorDayPicker (ver el encabezado de lib/features/login/login_page.dart
    // para conocer el motivo de esta separación State/Widget propia de Flutter):
    // así es como, desde el estado, se accede a los parámetros del widget que
    // lo posee.
    widget.onSearch(doctorId, _dayFormat.format(_selectedDay));
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<TranslationsService>().t;

    // Los tres campos se construyen UNA SOLA VEZ aquí y luego se disponen mediante
    // el LayoutBuilder más abajo: uno al lado del otro (Row) en una pantalla ancha,
    // apilados (Column) en una pantalla estrecha. Un teléfono en modo vertical mide
    // solo unos 360 píxeles de ancho: tres campos en fila tendrían cada uno
    // apenas un centenar de píxeles y se desbordarían.
    //
    // DropdownButtonFormField<int>: el equivalente en Flutter de un
    // <select> de HTML - a diferencia de v-model="selectedDoctorId"
    // en el lado Vue.js (un único enlace bidireccional), Flutter
    // separa explícitamente el "valor mostrado" (value:) y la "reacción
    // a un cambio" (onChanged:), a la manera de React
    // (:value + @change) ya comparada en el archivo
    // .vue original.
    final doctorField = DropdownButtonFormField<int>(
      // isExpanded: la etiqueta ocupa todo el ancho disponible (y se trunca
      // limpiamente si es demasiado larga) en lugar de desbordarse.
      isExpanded: true,
      decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')),
      value: _selectedDoctorId,
      hint: Text(t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')),
      // .map(...).toList(): el equivalente en Flutter de
      // v-for="doctor in doctors" :key="doctor.id" - aquí,
      // el identificador "estable" (:key en el lado Vue.js) es simplemente
      // el [value:] de cada DropdownMenuItem (doctor.id), que
      // el propio Flutter usa para saber cuál está
      // seleccionado actualmente.
      items: widget.doctors
          .map(
            (doctor) => DropdownMenuItem(
              value: doctor.id,
              child: Text('${doctor.title} ${doctor.firstName} ${doctor.lastName}'),
            ),
          )
          .toList(),
      onChanged: (id) => setState(() => _selectedDoctorId = id),
    );

    // InkWell: hace que toda el área sea "clicable" - un toque
    // en cualquier parte de ella abre el selector de fecha
    // (_pickDay arriba). Es una reconstrucción, a
    // mano, de lo que el navegador ofrecía "gratis" con
    // <input type="date" v-model="selectedDay"> en el lado Vue.js.
    // InputDecorator (en lugar de un TextField "disfrazado") muestra
    // la fecha sin poseer un TextEditingController - aquí no hay
    // NADA que escribir con el teclado, solo un valor que
    // mostrar y un toque que interceptar: no se necesita el
    // ciclo de vida de creación/dispose ya visto en
    // lib/features/login/login_page.dart para un campo realmente editable.
    final dayField = InkWell(
      onTap: _pickDay,
      child: InputDecorator(
        decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DAY_LABEL')),
        child: Text(_dayFormat.format(_selectedDay)),
      ),
    );

    final scheduleButton = FilledButton(
      onPressed: _selectedDoctorId == null ? null : _onSearchClick,
      child: Text(t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')),
    );

    return Card(
      child: Padding(
        padding: const EdgeInsets.all(16),
        // LayoutBuilder: llama a su builder con el ancho REALMENTE
        // disponible en este lugar del árbol (constraints.maxWidth), y
        // lo vuelve a llamar si cambia (rotación de pantalla, cambio de tamaño
        // de la ventana) - así el diseño se adapta por sí solo.
        child: LayoutBuilder(
          builder: (context, constraints) {
            if (constraints.maxWidth < 600) {
              return Column(
                crossAxisAlignment: CrossAxisAlignment.stretch,
                children: [
                  doctorField,
                  const SizedBox(height: 12),
                  dayField,
                  const SizedBox(height: 12),
                  scheduleButton,
                ],
              );
            }
            return Row(
              crossAxisAlignment: CrossAxisAlignment.end,
              children: [
                Expanded(flex: 5, child: doctorField),
                const SizedBox(width: 12),
                Expanded(flex: 4, child: dayField),
                const SizedBox(width: 12),
                Expanded(flex: 3, child: scheduleButton),
              ],
            );
          },
        ),
      ),
    );
  }
}

Comentemos este código:

  • Líneas 59–79: [_pickDay()] llama a [showDatePicker(...)]: una ilustración muy concreta de la promesa “un único código para tres entornos”: mientras que [Vue.js] se apoyaba en [<input type="date">], un componente NATIVO del NAVEGADOR (ausente en móvil y escritorio), [Flutter] dibuja ÉL MISMO un selector que es un widget [Material] estrictamente idéntico en los tres destinos.
  • Líneas 114–136: [DropdownButtonFormField<int>(value: _selectedDoctorId, ..., onChanged: (id) => setState(() => _selectedDoctorId = id))] : reemplaza a [v-model="selectedDoctorId"] con un par explícito [value:]/[onChanged:], similar al par [:value]/[@change] ya encontrado a propósito de [React] en este curso.
  • Líneas 149–155: [InkWell(onTap: _pickDay, child: InputDecorator(...))] : reconstruido manualmente a partir de lo que el navegador proporcionaba “gratis” con [<input type="date">]; [InputDecorator] (en lugar de un [TextField] “disfrazado”) muestra la fecha SIN un [TextEditingController].
  • Líneas 169–194: [LayoutBuilder(builder: (context, constraints) { ... })] : la respuesta de [Flutter] a una pantalla de ancho desconocido: [builder] recibe el ancho realmente disponible en ese lugar ([constraints.maxWidth]) y se vuelve a llamar si este cambia (rotación de la pantalla, cambio de tamaño de la ventana). Por debajo de 600 píxeles (un teléfono en modo vertical mide solo unos 360 píxeles de ancho), los tres campos se APILAN dentro de una [Column]; por encima de ese valor, permanecen uno al lado del otro dentro de una [Row]. Los tres campos se construyen una sola vez, antes, en las variables [doctorField], [dayField] y [scheduleButton]: solo cambia su disposición. Con únicamente la [Row] de la primera versión, cada campo habría dispuesto de solo unos cien píxeles en un teléfono en modo vertical, y el contenido se habría desbordado (la franja amarilla y negra “RIGHT OVERFLOWED BY … PIXELS” en modo de depuración); [isExpanded: true] en la lista desplegable evita el mismo desbordamiento con el nombre largo de un médico.

5.9.3. lib/features/schedule/schedule_view.dart

Adaptación de [src/app/features/schedule/Schedule.vue]: la agenda de un médico para un día determinado: horarios disponibles (botón “Reservar”) u horarios reservados (paciente + botón “Cancelar”).

// =========================================================================
// features/schedule/schedule_view.dart
// -------------------------------------------------------------------------
// Port de src/app/features/schedule/Schedule.vue (cliente Vue.js de este
// curso): muestra la agenda de un médico para un día dado - la lista de
// sus horarios, cada uno libre (botón "Book") o reservado
// (nombre del paciente + botón "Cancel").
//
// Desde que se añadió la autenticación, este widget también recibe
// canEdit: cuando es false (rol USER), los botones "Book"/"Cancel"
// desaparecen - la agenda aún se puede consultar, pero en solo lectura (el
// servidor de todos modos rechazaría estas acciones para un USER, 403 Forbidden,
// ver RolesGuard en el lado servidor).
//
// [v-if]/[v-else] y [v-for] (Vue.js) se convierten aquí en expresiones
// ORDINARIAS de Dart: Flutter, como React antes que él (ver el comentario de
// Schedule.vue), NO conoce ningún "lenguaje de plantillas" separado del
// lenguaje de programación - const/if/for y los operadores ?./?? del Dart
// normal bastan para expresar condiciones y listas, directamente en el
// método build(...) de abajo.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import '../../core/i18n/translations_service.dart';
import '../../core/models/appointment_models.dart';

class ScheduleView extends StatelessWidget {
  final DoctorDaySchedule? schedule;
  final bool canEdit;
  final void Function(SlotJson slot) onBook;
  final void Function(AppointmentJson appointment) onCancel;

  const ScheduleView({
    super.key,
    required this.schedule,
    required this.canEdit,
    required this.onBook,
    required this.onCancel,
  });

  // pequeña función utilitaria de formato, "8:05" en lugar de "8:5" -
  // idéntica en espíritu a formatTime(...) en el lado Vue.js.
  static String _formatTime(int h, int m) => '$h:${m.toString().padLeft(2, '0')}';

  void _onSlotClick(DoctorDaySlot daySlot) {
    if (!canEdit) {
      return; // de todos modos el botón no se muestra en este caso (ver build() más abajo)
    }
    final appointment = daySlot.appointment;
    if (appointment == null) {
      onBook(daySlot.slot); // horario libre: se ofrece reservarlo
    } else {
      onCancel(appointment); // horario ya reservado: se ofrece cancelar la cita existente
    }
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<TranslationsService>().t;
    final schedule = this.schedule;

    if (schedule == null) {
      return Padding(
        padding: const EdgeInsets.symmetric(vertical: 24),
        child: Text(
          t('SCHEDULE.EMPTY_STATE'),
          style: TextStyle(color: Theme.of(context).colorScheme.outline),
        ),
      );
    }

    return Card(
      child: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(
              '${t('SCHEDULE.TITLE_PREFIX')} ${schedule.day} - ${schedule.doctor.title} '
              '${schedule.doctor.firstName} ${schedule.doctor.lastName}',
              style: Theme.of(context).textTheme.titleMedium,
            ),
            const SizedBox(height: 12),
            // DataTable: el equivalente Material de Flutter de la <table> de HTML de
            // Schedule.vue - a diferencia de HTML, sus filas deben
            // construirse explícitamente en Dart mediante .map(...).toList()
            // (el equivalente, también aquí, de v-for="daySlot in
            // schedule.slots" :key="daySlot.slot.id" - el DataRow
            // no necesita una "key" explícita como en Vue.js/React: la
            // lista se reconstruye por completo en cada renderizado, ya que Flutter no
            // intenta aquí reutilizar las filas existentes).
            SingleChildScrollView(
              scrollDirection: Axis.horizontal,
              child: DataTable(
                columns: [
                  DataColumn(label: Text(t('SCHEDULE.COLUMN_SLOT'))),
                  DataColumn(label: Text(t('SCHEDULE.COLUMN_STATUS'))),
                  const DataColumn(label: Text('')),
                ],
                rows: schedule.slots.map((daySlot) {
                  final appointment = daySlot.appointment;
                  final slot = daySlot.slot;
                  return DataRow(
                    // fondo ligeramente teñido para un horario libre - la
                    // contraparte de la clase CSS "free-slot" en el lado Vue.js.
                    color: appointment == null
                        ? WidgetStateProperty.all(Theme.of(context).colorScheme.surfaceContainerLow)
                        : null,
                    cells: [
                      DataCell(Text(
                        '${_formatTime(slot.startHour, slot.startMinute)} - '
                        '${_formatTime(slot.endHour, slot.endMinute)}',
                      )),
                      DataCell(
                        appointment == null
                            ? Chip(
                                label: Text(t('SCHEDULE.FREE')),
                                backgroundColor: Colors.green.shade100,
                              )
                            : Chip(
                                label: Text('${appointment.client?.title ?? ''} ${appointment.client?.firstName ?? ''} ${appointment.client?.lastName ?? ''}'),
                              ),
                      ),
                      DataCell(
                        // canEdit: false para un rol USER (solo lectura)
                        canEdit
                            ? OutlinedButton(
                                onPressed: () => _onSlotClick(daySlot),
                                child: Text(appointment == null ? t('SCHEDULE.BOOK') : t('SCHEDULE.CANCEL_APPOINTMENT')),
                              )
                            : const SizedBox.shrink(),
                      ),
                    ],
                  );
                }).toList(),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Comentemos este código:

  • Líneas 43–57: [_formatTime(h, m)] y [_onSlotClick(daySlot)]: este último distingue entre un horario disponible ([onBook(...)]) y un horario reservado ([onCancel(...)]) según si [daySlot.appointment] es [null] o no, exactamente la misma lógica que del lado de [Vue.js], pero expresada puramente en [Dart] en lugar de en [<template>].
  • Líneas 96–137: [DataTable(columns: [...], rows: schedule.slots.map((daySlot) { ... }).toList())] : el equivalente [Material] de [<table>] [HTML] de [Schedule.vue]: sus filas deben construirse explícitamente mediante [.map(...).toList()].
  • Líneas 108–110: [color: appointment == null ? WidgetStateProperty.all(Theme.of(context).colorScheme.surfaceContainerLow) : null,] : el equivalente de la clase [CSS] ["free-slot"] del lado de [Vue.js]: un color de fondo aplicado condicionalmente a toda la fila, aquí mediante una función en lugar de una clase [CSS] con nombre.

5.9.4. lib/features/booking_dialog/booking_dialog.dart

Adaptación de [src/app/features/booking-dialog/BookingDialog.vue]: la selección de un paciente para reservar un horario disponible; el archivo donde la diferencia estructural con [Vue.js] es más pronunciada en todo este cliente.

// =========================================================================
// features/booking_dialog/booking_dialog.dart
// -------------------------------------------------------------------------
// Port de src/app/features/booking-dialog/BookingDialog.vue (cliente Vue.js
// de este curso): la ventana (modal) usada para elegir un
// paciente al que reservar un horario libre.
//
// DIFERENCIA ESTRUCTURAL IMPORTANTE con Vue.js (y con los otros tres
// widgets de lib/features/): BookingDialog.vue es un componente SIEMPRE
// PRESENTE en el árbol, cuya prop [open] (un booleano mantenido por
// App.vue) se limita a controlar la visualización (v-if="open") - EXACTAMENTE la misma
// elección que los clientes Angular y React de este curso, motivada por el deseo
// de evitar que Vue.js y el JavaScript de Bootstrap se disputen la
// misma información ("¿está abierto el modal?").
//
// Flutter no tiene este problema: un cuadro de diálogo NO ES un widget
// que se muestra u oculta condicionalmente en el árbol, sino una VERDADERA
// PÁGINA, apilada en la pila de navegación (el Navigator) al abrirse
// con showDialog(...) - y extraída automáticamente al
// cerrarse. Así que aquí no hay NI un estado "open: bool" que mantener en el
// widget padre (ver lib/app.dart, que no tiene un campo equivalente a
// slotBeingBooked del lado Vue.js), NI eventos "confirm"/"close" que
// emitir: showDialog(...) devuelve un Future que se completa con el
// valor pasado a Navigator.pop(...) - null si el usuario cerró
// sin elegir, el id del paciente elegido en caso contrario. Es el
// widget QUE LLAMA (lib/app.dart) quien espera con await este Future para saber qué
// hacer a continuación - una inversión completa de la dirección de la comunicación
// respecto a los dos eventos de Vue.js.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import '../../core/i18n/translations_service.dart';
import '../../core/models/appointment_models.dart';

// -----------------------------------------------------------------------
// función auxiliar: abre el cuadro de diálogo y devuelve el id del
// paciente elegido (o null si el usuario canceló o cerró sin elegir).
// Es ESTA función la que llama lib/app.dart - nunca directamente el
// constructor de _BookingDialogContent de abajo.
// -----------------------------------------------------------------------
Future<int?> openBookingDialog({
  required BuildContext context,
  required SlotJson slot,
  required List<Client> clients,
}) {
  return showDialog<int>(
    context: context,
    builder: (_) => _BookingDialogContent(slot: slot, clients: clients),
  );
}

class _BookingDialogContent extends StatefulWidget {
  final SlotJson slot;
  final List<Client> clients;

  const _BookingDialogContent({required this.slot, required this.clients});

  @override
  State<_BookingDialogContent> createState() => _BookingDialogContentState();
}

class _BookingDialogContentState extends State<_BookingDialogContent> {
  int? _selectedClientId;

  void _onConfirmClick() {
    final clientId = _selectedClientId;
    if (clientId == null) {
      return;
    }
    // Navigator.pop(context, clientId): cierra el cuadro de diálogo Y
    // pasa clientId como resultado del Future devuelto por
    // openBookingDialog(...) - el equivalente, en una sola llamada, de
    // emit('confirm', { clientId }) SEGUIDO del cierre (implícito,
    // controlado por el padre mediante [open]) en el lado Vue.js.
    Navigator.pop(context, clientId);
  }

  void _onCloseClick() {
    // Navigator.pop(context) sin segundo argumento: el Future devuelto por
    // openBookingDialog(...) se completa con null - el equivalente de
    // emit('close') en el lado Vue.js.
    Navigator.pop(context);
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<TranslationsService>().t;
    final slot = widget.slot;

    // AlertDialog: el widget Material dedicado a los cuadros de diálogo -
    // ya proporciona por sí solo el fondo oscurecido (el equivalente del
    // .modal-backdrop colocado "a mano" en el lado Vue.js) y el
    // comportamiento de cierre estándar (toque fuera del cuadro, tecla Escape
    // en escritorio/web) - un comportamiento que el cliente Vue.js tuvo que
    // recrear por sí mismo, ya que Bootstrap solo gestiona una parte de forma automática.
    return AlertDialog(
      title: Text(t('BOOKING_DIALOG.TITLE')),
      content: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            '${t('BOOKING_DIALOG.SLOT_FROM')} ${slot.startHour}:${slot.startMinute.toString().padLeft(2, '0')} '
            '${t('BOOKING_DIALOG.SLOT_TO')} ${slot.endHour}:${slot.endMinute.toString().padLeft(2, '0')}',
          ),
          const SizedBox(height: 16),
          DropdownButtonFormField<int>(
            decoration: InputDecoration(labelText: t('BOOKING_DIALOG.PATIENT_LABEL')),
            value: _selectedClientId,
            hint: Text(t('BOOKING_DIALOG.CHOOSE_PATIENT')),
            items: widget.clients
                .map(
                  (client) => DropdownMenuItem(
                    value: client.id,
                    child: Text('${client.title} ${client.firstName} ${client.lastName}'),
                  ),
                )
                .toList(),
            onChanged: (id) => setState(() => _selectedClientId = id),
          ),
        ],
      ),
      actions: [
        TextButton(onPressed: _onCloseClick, child: Text(t('BOOKING_DIALOG.CANCEL'))),
        FilledButton(
          onPressed: _selectedClientId == null ? null : _onConfirmClick,
          child: Text(t('BOOKING_DIALOG.CONFIRM')),
        ),
      ],
    );
  }
}

Comentemos este código:

  • Líneas 16–28: El comentario de encabezado resume la diferencia estructural más significativa de este archivo: [BookingDialog.vue] es un componente SIEMPRE PRESENTE en el árbol, cuya visualización se controla únicamente mediante una propiedad booleana ([open], mantenida por [App.vue]); un cuadro de diálogo de [Flutter], en cambio, NUNCA está presente hasta que se abre explícitamente con [showDialog(...)]: una verdadera página apilada en la pila de navegación, que se desapila automáticamente al cerrarse.
  • Líneas 43–52: [Future<int?> openBookingDialog({...}) { return showDialog<int>(context: context, builder: (_) => _BookingDialogContent(...)); }]: la función a la que llama [lib/app.dart]; su tipo de retorno ([Future<int?>]) ya indica que ELLA devolverá finalmente el ID del paciente seleccionado o [null].
  • Líneas 67–77: [Navigator.pop(context, clientId);] : cierra el cuadro de diálogo Y devuelve [clientId] como resultado del [Future], que fue devuelto por [openBookingDialog(...)]; el equivalente, en una sola llamada, de lo que [emit('confirm', { clientId })] SEGUIDO de un cierre dirigido por el padre hacían JUNTOS en el lado de [Vue.js].
  • Líneas 80–84: [Navigator.pop(context);] sin un segundo argumento: [Future] termina entonces con [null], lo que equivale a [emit('close')] del lado de [Vue.js]. Es [lib/app.dart] ([_onBookingRequest(...)]) quien espera con [await] el [Future] y decide qué hacer según si el resultado es [null] o no: una inversión completa de la dirección de la comunicación en comparación con los dos eventos de Vue.js.

5.10. Guía paso a paso del uso de la aplicación Flutter Web

5.10.1. 1. Pantalla de inicio de sesión

En la primera carga, no hay ninguna sesión almacenada en [shared_preferences]: [AuthService.isLoggedIn] es igual a [false], y [AppRoot] muestra [LoginPage]. Un intento con una combinación de usuario y contraseña no válida muestra el mensaje de error almacenado por [_LoginFormState] (clave [LOGIN.ERROR]). El selector FR/EN, que permanece visible, también traduce esta pantalla.

PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices                 
Found 4 connected devices:                     
  sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64    • Android 17 (API 37) (emulator)
  Windows (desktop)             • windows       • windows-x64    • Microsoft Windows [version
  10.0.26200.9457]
  Chrome (web)                  • chrome        • web-javascript • Google Chrome 153.0.8010.48
  Edge (web)                    • edge          • web-javascript • Microsoft Edge 153.0.4234.48

Run "flutter emulators" to list and start any available device emulators.

If you expected another device to be detected, please run "flutter doctor" to diagnose potential issues. You
may also try increasing the time to wait for connected devices with the "--device-timeout" flag. Visit
https://flutter.dev/setup/ for troubleshooting tips.
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d edge

Image

5.10.2. 2. Inicio de sesión como administrador (rol ADMIN, acceso completo)

Una vez iniciada la sesión con [admin]/[admin], [AppRoot] deja de mostrar [LoginPage] y carga las listas de médicos y clientes ([_loadInitialLists()]). Después de seleccionar un médico y una fecha en [DoctorDayPicker], se muestra el calendario con los botones “Reservar”/“Cancelar” visibles ([canEdit] equivale a [true] para este rol). Al hacer clic en “Reservar” se abre el cuadro de diálogo de selección de paciente ([openBookingDialog(...)]); tras la confirmación ([AppointmentService.addAppointment(...)]), el calendario se recarga y el horario aparece reservado. Al hacer clic en “Cancelar” (en un horario reservado) se llama directamente a [AppointmentService.deleteAppointment(...)] y el horario vuelve a quedar disponible.

Image

  • en [1], la URL del servidor NestJS (debe estar iniciado);
  • en [2-3], las credenciales del administrador: admin / admin;
  • en [4]: iniciar sesión en el servidor;

Image

  • En [1], seleccione un médico;
  • en [2], seleccione un día;
  • En [3], consulte la agenda del médico seleccionado para el día elegido;
  • En [1], se hace una reserva;

Image

  • En [1-2], seleccione un paciente y confirme;

Image

  • En [1], el horario de la cita queda reservado;
  • En [2], cierre la sesión. Esto lo lleva de vuelta a la pantalla de inicio de sesión;

5.10.3. 3. Inicio de sesión como usuario (rol USER, solo lectura)

Tras cerrar la sesión, al iniciar sesión con [user]/[user] se muestra una insignia “USER”. El calendario sigue siendo visible, pero no aparecen los botones “Reservar”/“Cancelar” ([canEdit] equivale a [false]); de todos modos, el servidor denegaría estas dos acciones a este rol (403 Forbidden, véase el Capítulo 2).

Image

No es posible agregar ni eliminar una cita.

5.11. Lo que queda fuera del alcance o pospuesto

  • Al igual que los clientes [Angular], [React] y [Vue.js] de este curso, no existe un modo de demostración o depuración específico (ningún interruptor de “modo sin conexión”).
  • No se introducen retrasos de red artificiales del lado del cliente con fines didácticos; los tiempos de respuesta observados son los tiempos de respuesta reales del servidor [NestJS].
  • Sin enrutador: al igual que las cuatro variantes anteriores, la aplicación cabe en una sola pantalla (sin contar el cuadro de diálogo de reserva).
  • Los proyectos nativos generados por [flutter create] ([android/], [ios/], [macos/], [windows/], [linux/], [web/]) no se incluyen con este documento (véase el Capítulo 1); se regeneran localmente y son idénticos para cualquier proyecto fuente de [Flutter].