Skip to content

11. Estudo de caso: o cliente Flutter da aplicação RdvMedecins

11.1. O problema

A aplicação [RdvMedecins] permite marcar consultas em um consultório médico. O curso de [NestJS] a desenvolveu como uma aplicação HTML, na qual o servidor gerava as páginas; os cursos de [Vue.js], [Angular] e [React] escreveram clientes web para ela, que geram as MESMAS páginas no navegador, a partir dos dados JSON do servidor apresentados no capítulo “O servidor RdvMedecins, uma caixa-preta”. Aqui descrevemos o cliente [Flutter]: uma aplicação mobile ([Android]), que também pode ser compilada para a web.

O cliente deve oferecer tudo o que os outros ofereciam:

  • uma tela de login, protegida por um CAPTCHA, com a opção de criar uma conta de paciente;
  • a agenda de um médico em um determinado dia, com marcação de consultas (janela de seleção do paciente) e cancelamento;
  • para o administrador, o gerenciamento de médicos e clientes (listar, incluir, editar, excluir);
  • para o paciente, um painel pessoal (que mostra as consultas futuras, que ele pode cancelar) e o gerenciamento da conta;
  • dois idiomas: francês e inglês;
  • os mesmos endereços dos clientes web ([/schedule?doctorId=1&day=...]). No celular, eles são invisíveis, mas organizam a aplicação; na web, os usuários podem recarregá-los, salvá-los nos favoritos e navegar pela aplicação com os botões Voltar/Avançar do navegador.

Uma aplicação mobile traz suas próprias exigências: uma tela estreita (sem tabelas de cinco colunas), um teclado que esconde metade da tela, um botão Voltar, um gerenciador de senhas e a ausência de um navegador para armazenar o cookie do token.

11.2. Instalação e execução

O servidor JSON deve estar instalado e em execução (veja o capítulo “O servidor RdvMedecins: uma caixa-preta”). Você não precisa do modo de teste do CAPTCHA: pode deixar o campo [CAPTCHA_TEST] em branco no arquivo [.env] do servidor.

Em uma janela de console aberta na pasta [rdvmedecins_flutter]:

flutter create --platforms=android,web --org fr.stahe --project-name rdvmedecins_flutter .
flutter pub get

O primeiro comando adiciona ao projeto as pastas específicas de cada plataforma ([android/], [web/]), como nos exemplos; ele não modifica nenhum arquivo existente, e o arquivo [android/app/src/main/AndroidManifest.xml] fornecido (o do exemplo 22) é mantido. Depois, escolha uma das opções a seguir:

1
2
3
flutter run -d emulator-5554
flutter run -d R58N12ABCDE --dart-define=SERVER=http://192.168.1.20:8080
flutter run -d chrome
  • A primeira linha inicia a aplicação no emulador [Android] (o comando [flutter devices] lista os dispositivos disponíveis). O emulador se conecta ao servidor no endereço [10.0.2.2:8080] (veja o exemplo 22);
  • a segunda linha executa a aplicação em um celular real conectado por USB (com a “depuração USB” habilitada nas opções do desenvolvedor) ou conectado por Wi-Fi. O celular e o computador devem estar na mesma rede; informe o endereço do computador nessa rede ([ipconfig] no [Windows]). O firewall do [Windows] deve permitir conexões de entrada na porta 8080;
  • a terceira, no [Chrome], no endereço http://localhost:5173: o servidor de desenvolvimento web do [Flutter] encaminha as requisições /api ao servidor JSON (arquivo [web_dev_config.yaml]).

As contas de demonstração são listadas na tela de login (senha = login). Enquanto a aplicação está em execução, a tecla [r] no console faz um "hot reload" após uma alteração no código; [R] a reinicia; [q] a encerra.

11.3. Usando a aplicação

As capturas de tela desta seção foram feitas em um celular com resolução de 1080 × 2340 pixels (412 × 891 pontos).

11.3.1. A tela de login

A tela de login; senha incorreta: a mensagem aparece na parte inferior da tela e uma nova imagem é exibida (cada imagem é usada apenas uma vez):

11.3.2. A agenda, vista pelo administrador e pelos médicos

Logado como [admin], você chega à agenda. O botão ☰ abre o menu: as telas acessíveis ao administrador e, no topo, quem está logado:

Selecione um médico e uma data (a data em um calendário) e, em seguida, clique em “Ver agenda”. A URL muda para [/schedule?doctorId=1&day=2026-10-05]. Ao clicar em “Reservar”, abre-se a janela de reserva; a URL muda para [/schedule?doctorId=1&day=2026-10-05&book=3]:

A consulta é salva; “Cancelar” pede confirmação:

Um médico chega diretamente à SUA agenda de hoje:

Image

11.3.3. O portal do paciente

Um paciente ([martin]) acessa “Minha área”. Em uma agenda, ele vê “Reservado” ao lado dos horários de outros pacientes e marca uma consulta para si mesmo sem selecionar um paciente específico:

A consulta dele aparece sob o seu nome; o botão “Reservar” deixa de estar disponível (apenas uma consulta futura). Na agenda de outro médico, onde a consulta dele não aparece, uma mensagem explica por que ele não pode reservar. A sua área (“Minha área”) mostra a consulta:

“Gerenciar minha conta”: qualquer alteração exige a senha atual; os erros vêm do servidor:

Image

O menu de um paciente não inclui a entrada “Médicos”. Na web, se o paciente digitar por conta própria o endereço /doctors, o roteador exibe uma página de erro 403 (veja [router.dart]).

11.3.4. Gerenciando médicos e clientes

A lista de médicos; uma entrada preenchida incorretamente:

Uma inclusão bem-sucedida; um homônimo; a exclusão de um médico que tem consultas é negada:

11.3.5. Criando uma conta

Na tela de login, digite o CAPTCHA e toque em “Criar uma conta de paciente”. O formulário é rejeitado pelo servidor; quando a conta é criada, você volta à tela de login com as informações de login já preenchidas:

11.3.6. Em francês; em uma tela grande

O menu FR / EN na barra superior renderiza a tela novamente de forma local, sem fazer nenhuma requisição ao servidor. Em uma tela larga (a web, um tablet), o menu permanece exibido à esquerda:

11.3.7. Sessão expirada

Se o token expirar (ou se o cookie for excluído), a requisição seguinte recebe uma resposta 401; a aplicação redireciona para a tela de login:

Image

11.4. Arquitetura do cliente

rdvmedecins_flutter/
├── pubspec.yaml               the libraries, the resources
├── analysis_options.yaml      the rules of the code analyzer
├── web_dev_config.yaml        the web development server (proxy /api)
├── android/                   the Android project (including AndroidManifest.xml)
├── web/                       the HTML page of the web version
├── assets/
│   ├── i18n/                  the dictionaries fr.json, en.json
│   └── fonts/                 the RobotoMono font
├── test/                      unit tests; making of the screenshots
└── lib/
    ├── main.dart              the startup
    ├── config.dart            the server address
    ├── router.dart            the screens, their addresses, their access rights
    ├── formatting.dart        the formatting of times and days
    ├── api/                   the API access layer
    ├── i18n/                  the languages
    ├── state/                 session, messages, cache (ChangeNotifier)
    ├── widgets/               the layout and the reusable widgets
    └── pages/                 the screens

Esta é a arquitetura recomendada pelo guia do [Flutter] (“App architecture”), explicada de forma mais simples:

  • uma camada de dados ([api/]): a única que conhece o pacote [http], as URLs e o JSON;
  • uma camada de estado ([state/]): objetos [ChangeNotifier] fornecidos a toda a aplicação ([provider]), que as telas monitoram;
  • uma camada de interface ([pages/], [widgets/]): widgets que exibem o estado e transmitem as ações do usuário.

A tabela a seguir compara a aplicação HTML do curso de [NestJS], o cliente [React] e este cliente:

Aplicação HTML (NestJS)
Cliente React
Cliente Flutter
O servidor renderiza cada página ([res.render])
Os componentes renderizam as páginas no navegador
Os widgets renderizam as telas no celular
[views/layout.hbs] e suas views parciais
[Layout.tsx] e os componentes
[layout.dart] (uma [ShellRoute]) e os widgets
rotas dos controllers
[React Router]
[go_router]
[JwtAuthGuard], [RolesGuard]
guards do roteador (middleware)
A função [redirect] do roteador
o cookie do token, armazenado pelo navegador
o mesmo que acima
Um cliente HTTP que gerencia cookies (no celular)
mensagem flash em um cookie
um store chamado [Zustand]
um [ChangeNotifier], [Messages]
dicionários lidos pelo servidor
[i18next]
[Translations] (exemplo 21)
idioma armazenado em um cookie
no [localStorage]
no [shared_preferences]
dados já lidos
[TanStack Query]
[Cache] (algumas linhas)
Formulário rejeitado: o servidor recarrega a página
resposta 400/409, erros abaixo dos campos
o mesmo que acima

Todos os arquivos do cliente são apresentados a seguir. Eles são amplamente comentados; seus comentários fazem parte do curso.

11.5. Configuração do projeto

11.5.1. pubspec.yaml

# ==========================================================================
# pubspec.yaml - o cliente Flutter do aplicativo RdvMedecins
# ==========================================================================

name: rdvmedecins_flutter
description: The Flutter client (Android, web) of the RdvMedecins appointment booking application.
publish_to: none
version: 1.0.0

environment:
  sdk: ^3.12.0

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  flutter_web_plugins:
    sdk: flutter
  intl: any
  go_router: ^16.2.0
  provider: ^6.1.5
  shared_preferences: ^2.5.3
  http: ^1.5.0
  flutter_svg: ^2.2.1

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^6.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/i18n/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: assets/fonts/RobotoMono-Regular.ttf
        - asset: assets/fonts/RobotoMono-Bold.ttf
          weight: 700

As bibliotecas dos exemplos, exceto [flutter_svg]..., que permanece: o CAPTCHA é uma imagem (SVG). Os únicos recursos são os dicionários e a fonte monoespaçada das contas de demonstração.

11.5.2. analysis_options.yaml

# ==========================================================================
# analysis_options.yaml - as regras do analisador de código Dart
# --------------------------------------------------------------------------
# O analisador verifica o código enquanto ele é digitado (o VS Code sublinha os
# erros) e com o comando flutter analyze. Partimos das regras
# recomendadas pela equipe do Flutter (pacote flutter_lints)...
# ==========================================================================

include: package:flutter_lints/flutter.yaml

analyzer:
  language:
    # ... tornadas mais rígidas: nenhuma conversão implícita de um tipo dynamic
    strict-casts: true
    strict-raw-types: true

linter:
  rules:
    # aspas simples em todo lugar, como nos exemplos do curso
    prefer_single_quotes: true
    # "final" para uma variável local que nunca é reatribuída
    prefer_final_locals: true
    # strings longas demais são permitidas (textos da UI)
    lines_longer_than_80_chars: false

As regras do analisador, como nos exemplos:

  • linha 9: as regras recomendadas pela equipe do [Flutter];
  • linhas 14–15: verificação de tipos mais rigorosa: um [dynamic] (como os devolvidos por [jsonDecode]) não pode ser usado como [String] sem conversão explícita ([as String], ou filtragem por padrões do [Dart] 3);
  • linhas 20–24: três regras de formatação.

O comando [flutter analyze] aplica essas regras a todo o projeto; o [VS Code] as aplica enquanto você digita.

11.5.3. web_dev_config.yaml

# ==========================================================================
# web_dev_config.yaml - o servidor de desenvolvimento WEB do Flutter
# --------------------------------------------------------------------------
# flutter run -d chrome serve o aplicativo em http://localhost:5173 e
# encaminha qualquer requisição /api/... ao servidor JSON RdvMedecins (porta 8080):
# para o navegador, o aplicativo e a API têm a MESMA origem (sem
# CORS, e o cookie do token trafega).
# ==========================================================================

server:
  host: localhost
  port: 5173
  proxy:
    - target: "http://localhost:8080/"
      prefix: "/api/"

O do exemplo 22: no desenvolvimento web, as requisições /api são enviadas ao servidor JSON.

11.6. Inicialização da aplicação

11.6.1. lib/config.dart

// =========================================================================
// lib/config.dart - ONDE está o servidor JSON?
// -------------------------------------------------------------------------
// A questão não se coloca para uma aplicação web servida pelo próprio
// servidor: as requisições vão para a MESMA origem da página
// (um endereço relativo, /api/...). Mas um aplicativo MOBILE não tem
// origem: é preciso fornecer-lhe o endereço completo do servidor.
//   - o emulador Android enxerga o computador que o executa no
//     endereço 10.0.2.2 (localhost, para ele, é o próprio emulador);
//   - um celular real, conectado à mesma rede Wi-Fi do computador, deve
//     usar o endereço do computador nesta rede (192.168.1.20...):
//     ele é informado quando o aplicativo é iniciado:
//         flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...
//   - no desenvolvimento web (flutter run -d chrome), o servidor de
//     desenvolvimento do Flutter encaminha as requisições /api para o servidor JSON
//     (arquivo web_dev_config.yaml): um endereço relativo basta;
//   - em um computador (Windows, macOS, Linux): localhost.
// =========================================================================

import 'package:flutter/foundation.dart';

// o valor dado por --dart-define=SERVER=..., '' por padrão.
// String.fromEnvironment é avaliado em tempo de COMPILAÇÃO: é uma constante
const _forcedServer = String.fromEnvironment('SERVER');

class Config {
  // kIsWeb: true se o aplicativo roda em um navegador;
  // defaultTargetPlatform: o sistema (android, iOS, windows...)
  static String serverUrl = _forcedServer.isNotEmpty
      ? _forcedServer
      : kIsWeb
      ? '' // mesma origem: endereços relativos
      : defaultTargetPlatform == TargetPlatform.android
      ? 'http://10.0.2.2:8080'
      : 'http://localhost:8080';
}

O endereço do servidor, dependendo da plataforma (veja o exemplo 22):

  • linha 24: o valor informado na inicialização por [--dart-define=SERVER=...]. [String.fromEnvironment] é avaliado em tempo de compilação: o endereço fica embutido na aplicação compilada;
  • linhas 29–35: caso contrário, um endereço relativo na web (o servidor de desenvolvimento e, em produção, o próprio servidor JSON, servem a página E a API), [10.0.2.2] no [Android] (o computador, visto do emulador), [localhost] nos demais casos. [static]: uma variável de classe, não de objeto; não é [final], para que os testes possam modificá-la.

11.6.2. lib/main.dart

// =========================================================================
// lib/main.dart - a inicialização do aplicativo
// -------------------------------------------------------------------------
// Construímos, de uma vez por todas, os objetos compartilhados por todo o
// aplicativo, e depois os FORNECEMOS a todas as telas (provider):
//   - o cliente HTTP (que trata o cookie do token no celular) e a camada
//     de acesso à API;
//   - a sessão (quem está logado?), as mensagens, o cache de dados;
//   - as traduções (francês, inglês);
//   - o roteador, que exibe a tela do endereço atual.
// Dois mecanismos ligam estes objetos entre si:
//   1. a resposta 401 de uma requisição protegida (sessão expirada): esquecemos
//      o usuário e preparamos a mensagem; o roteador, que escuta a
//      sessão, volta então para a tela de login (veja api/api_client.dart);
//   2. as mensagens "flash": ao fim de CADA navegação, as mensagens
//      da tela anterior desaparecem, as deixadas para a próxima
//      tela aparecem (veja state/messages.dart).
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_web_plugins/url_strategy.dart';
import 'package:go_router/go_router.dart';
import 'package:intl/date_symbol_data_local.dart';
import 'package:provider/provider.dart';
import 'package:shared_preferences/shared_preferences.dart';

import 'api/api_client.dart';
import 'api/http_client.dart';
import 'api/rdvmedecins_api.dart';
import 'state/cache.dart';
import 'state/messages.dart';
import 'state/session.dart';
import 'i18n/translations.dart';
import 'router.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  usePathUrlStrategy(); // na web: /schedule em vez de /#/schedule
  await initializeDateFormatting();
  final storage = await SharedPreferences.getInstance();
  final translations = Translations(storage);
  await translations.start();
  runApp(Application(storage: storage, translations: translations));
}

class Application extends StatefulWidget {
  final SharedPreferences storage;
  final Translations translations;

  const Application({super.key, required this.storage, required this.translations});

  @override
  State<Application> createState() => _ApplicationState();
}

class _ApplicationState extends State<Application> {
  late final ApiClient _client = ApiClient(CookieClient(widget.storage));
  late final RdvMedecinsApi _api = RdvMedecinsApi(_client);
  late final Session _session = Session(_api);
  final Messages _messages = Messages();
  final Cache _cache = Cache();
  late final GoRouter _router = createRouter(_session, _messages, _api);
  String? _address;

  @override
  void initState() {
    super.initState();
    // 1. a sessão expirada
    _client.onSessionExpired = () {
      _session.forget();
      _cache.clear();
      _messages.flash(success: false, key: 'ERRORS.SESSION_EXPIRED');
      // nada de _router.go('/login'): o guard do roteador cuida disso, e
      // lembra a tela atual (?redirect=...) para voltar a ela
    };
    // a sessão muda (login, logout): os dados lidos para
    // o usuário anterior não valem mais nada
    _session.addListener(_cache.clear);
    // 2. a cada navegação concluída (o endereço mudou): nova página
    _router.routerDelegate.addListener(() {
      // estado: a tela no TOPO da pilha (inclusive uma tela empilhada por push)
      final address = _router.state.uri.toString();
      if (address != _address) {
        _address = address;
        _messages.newPage();
      }
    });
  }

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

  @override
  Widget build(BuildContext context) {
    return MultiProvider(
      providers: [
        // objetos comuns...
        Provider.value(value: _api),
        // ... e objetos que notificam suas mudanças
        ChangeNotifierProvider.value(value: _cache),
        ChangeNotifierProvider.value(value: _session),
        ChangeNotifierProvider.value(value: _messages),
        ChangeNotifierProvider.value(value: widget.translations),
      ],
      child: Consumer<Translations>(
        builder: (context, translations, _) => MaterialApp.router(
          debugShowCheckedModeBanner: false,
          onGenerateTitle: (context) => translations.t('APP.TITLE'),
          theme: ThemeData(colorSchemeSeed: const Color(0xFF0D6EFD)),
          // os textos do próprio Flutter (calendário...) no idioma escolhido
          locale: Locale(translations.language),
          supportedLocales: [for (final l in languages) Locale(l)],
          localizationsDelegates: GlobalMaterialLocalizations.delegates,
          routerConfig: _router,
        ),
      ),
    );
  }
}
  • linhas 37–44: antes de exibir qualquer coisa, preparamos o que precisa ser preparado: endereços web sem [#] (exemplo 17), os nomes dos dias e dos meses em todos os idiomas ([intl], exemplo 09), o armazenamento do dispositivo e o dicionário do idioma inicial. [WidgetsFlutterBinding.ensureInitialized()]: essas operações exigem o engine do [Flutter], por isso o iniciamos antes de [runApp];
  • linhas 58–63: os objetos compartilhados, criados UMA ÚNICA VEZ, no estado do widget raiz. Cada um recebe, na criação, os que lhe são necessários: isso é injeção de dependência, feita manualmente. [late]: a inicialização ocorre no primeiro uso, quando [widget] já existe;
  • linhas 70–76: 1. a sessão expirada. A camada de acesso à API desconhece tanto a sessão quanto as mensagens; entregamos a ela esta função, que será chamada a cada resposta 401. O usuário é esquecido, o cache é limpo e a mensagem para a próxima tela é preparada. A transição de tela em si fica a cargo do roteador, que monitora a sessão;
  • linha 79: a cada mudança de usuário, o cache é limpo: os dados lidos para o usuário anterior não servem ao seguinte (um paciente não deve ver a agenda consultada pelo administrador);
  • Linhas 81–88: 2. Mensagens flash. O [routerDelegate] do roteador avisa seus listeners a cada transmissão; o endereço é comparado ao anterior ([_router.state]: a tela no TOPO da pilha, incluindo uma tela empilhada por [push], como a janela de reserva) e, se ele mudou, o sistema passa para uma “nova página”: as mensagens da tela anterior desaparecem e as colocadas nesta aparecem (veja [messages.dart]);
  • linhas 99–107: os objetos compartilhados são fornecidos a todas as telas (exemplo 20). [.value]: o objeto já existe; o provider não o cria (e não o destruirá);
  • linhas 109–118: a aplicação em si, reconstruída a cada mudança de idioma ([Consumer], veja o exemplo 20): o título ([onGenerateTitle]) e o idioma dos textos do próprio [Flutter] (o calendário, as dicas). [colorSchemeSeed]: uma cor a partir da qual o [Material] deriva toda a paleta; é o azul do [Bootstrap], a cor usada pelos clientes web.

11.7. A camada de acesso à API

11.7.1. lib/api/http_client.dart

// =========================================================================
// lib/api/http_client.dart - um cliente HTTP que trata COOKIES
// -------------------------------------------------------------------------
// O servidor RdvMedecins coloca o token JWT em um COOKIE (httpOnly).
// Em um navegador, é o navegador que guarda os cookies e os envia
// de volta a cada requisição: o código do aplicativo não tem nada a fazer.
// Em um celular, NÃO há navegador: cabe ao aplicativo
// desempenhar seu papel, ou seja:
//   1. ler o cabeçalho "Set-Cookie" de cada resposta e guardar os cookies;
//   2. enviá-los de volta no cabeçalho "Cookie" de cada requisição.
// Este cliente HTTP faz isso, ENVOLVENDO o cliente do pacote http
// (http.BaseClient: basta escrever o método send). Os cookies são
// também guardados no dispositivo (shared_preferences): continuamos logados
// quando paramos e reiniciamos o aplicativo.
// Na web, ele não faz nada além do cliente comum: o
// navegador proíbe o aplicativo de ler ou escrever esses cabeçalhos.
// =========================================================================

import 'dart:convert';

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

class CookieClient extends http.BaseClient {
  static const _key = 'rdvmedecins.cookies';

  final http.Client _inner = http.Client();
  final SharedPreferences? _storage;
  // nome do cookie -> seu valor
  final Map<String, String> _cookies = {};

  CookieClient([this._storage]) {
    // os cookies guardados durante um uso anterior
    final stored = _storage?.getString(_key);
    if (stored != null) {
      _cookies.addAll((jsonDecode(stored) as Map<String, Object?>).cast<String, String>());
    }
  }

  @override
  Future<http.StreamedResponse> send(http.BaseRequest request) async {
    if (!kIsWeb && _cookies.isNotEmpty) {
      // "rdvmedecins_jwt=eyJhbGci...; other=value"
      request.headers['cookie'] = [for (final MapEntry(:key, :value) in _cookies.entries) '$key=$value'].join('; ');
    }
    final response = await _inner.send(request);
    final setCookie = response.headers['set-cookie'];
    if (!kIsWeb && setCookie != null) {
      _store(setCookie);
    }
    return response;
  }

  // Set-Cookie: rdvmedecins_jwt=eyJ...; Max-Age=7200; Path=/api; Expires=Tue, 29 Sep 2026 ...; HttpOnly
  // (vários cookies são separados por vírgulas). Guardamos apenas o
  // nome e o valor de cada cookie; um valor vazio (logout) o apaga
  void _store(String setCookie) {
    // um nome seguido de "=", no início do cabeçalho ou após uma vírgula
    for (final m in RegExp(r'(?:^|,)\s*([^=;,\s]+)=([^;]*)').allMatches(setCookie)) {
      final name = m[1]!;
      final value = m[2]!.trim();
      if (value.isEmpty) {
        _cookies.remove(name);
      } else {
        _cookies[name] = value;
      }
    }
    _storage?.setString(_key, jsonEncode(_cookies));
  }

  @override
  void close() => _inner.close();
}

O cliente HTTP do exemplo 23, sem alterações: ele armazena os cookies recebidos (cabeçalho [Set-Cookie]) e os reenvia (cabeçalho [Cookie]) no celular; na web, deixa que o navegador cuide disso.

11.7.2. lib/api/api_client.dart

// =========================================================================
// lib/api/api_client.dart - TODAS as requisições à API passam por aqui
// -------------------------------------------------------------------------
// Extraído de common/api.dart dos exemplos, com uma novidade: o
// tratamento centralizado da resposta 401.
//
// Um 401 pode acontecer a qualquer momento: o token expirou (2 horas), a
// conta foi excluída, o servidor reiniciou com outra chave
// secreta... Em vez de tratar este caso em cada tela, nós o tratamos
// AQUI, uma só vez. Mas este arquivo não conhece nem o roteador nem as mensagens
// (ele não depende de nada): chama uma função que lhe foi dada na
// inicialização (onSessionExpired, veja main.dart), que esquece o usuário e
// volta para a página de login.
//
// Algumas requisições tratam elas mesmas o seu 401 (o login, GET
// /api/auth/me...): são "públicas" (veja rdvmedecins_api.dart).
// =========================================================================

import 'dart:convert';

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

import '../config.dart';
import 'api_error.dart';

class ApiClient {
  final http.Client _client;
  // o que fazer quando o servidor responde 401 a uma requisição protegida
  void Function() onSessionExpired = () {};

  ApiClient(this._client);

  // isPublic: true para as rotas que tratam elas mesmas o 401
  Future<Object?> request(String method, String url, {Object? body, bool isPublic = false}) async {
    final request = http.Request(method, Uri.parse('${Config.serverUrl}/api$url'));
    if (body != null) {
      request.headers['content-type'] = 'application/json';
      request.body = jsonEncode(body);
    }
    final http.Response response;
    try {
      response = await http.Response.fromStream(await _client.send(request));
    } catch (_) {
      // sem resposta: rede fora do ar, servidor parado, endereço errado
      throw const ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
    }
    if (response.statusCode >= 400) {
      final error = ApiError.fromResponse(response);
      if (error.statusCode == 401 && !isPublic) {
        onSessionExpired();
        // a tela que esperava a resposta exibirá ESTA mensagem também
        throw const ApiError(401, 'ERRORS.SESSION_EXPIRED');
      }
      throw error;
    }
    return response.bodyBytes.isEmpty ? null : jsonDecode(utf8.decode(response.bodyBytes));
  }
}

O arquivo [common/api.dart] dos exemplos, com uma novidade: a resposta 401.

  • Linha 29: uma função a ser chamada em caso de erro 401, especificada na inicialização (veja [main.dart]). Por padrão, não faz nada;
  • linha 34: [isPublic] é um parâmetro nomeado e opcional (entre chaves): [request('GET', '/captcha', isPublic: true)];
  • linhas 35–38: a requisição, construída peça por peça: método, endereço, cabeçalho e corpo JSON;
  • linhas 40–45: a requisição é enviada. Uma exceção aqui significa que nenhuma resposta foi recebida (rede fora do ar, servidor fora do ar, endereço incorreto). [final http.Response response;]: uma variável [final] declarada sem valor; o [Dart] verifica se ela recebe um valor, uma única vez, antes de ser lida;
  • linhas 47–54: uma resposta de erro se torna um [ApiError]. Um 401 em uma requisição protegida significa que a sessão expirou: [onSessionExpired] é chamada e, mesmo assim, um erro é disparado (a tela que esperava a resposta precisa saber que ela não chegou), usando a chave [ERRORS.SESSION_EXPIRED]: se esta tela exibir o erro, será a mesma mensagem;
  • linha 56: uma resposta sem corpo (204) resulta em [null]. Decodificamos os bytes em UTF-8: sem o cabeçalho [charset], o pacote [http] decodificaria [response.body] em Latin-1, e os acentos ficariam corrompidos.

11.7.3. lib/api/api_error.dart

// =========================================================================
// lib/api/api_error.dart - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Todas as respostas de erro do servidor RdvMedecins têm o mesmo formato:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Mas uma requisição também pode falhar de OUTRO modo: nenhuma resposta
// (rede fora do ar, servidor parado, endereço errado), ou uma resposta que não
// vem do nosso servidor (uma página de erro de um proxy). Convertemos
// tudo isso em UMA só classe, ApiError, que carrega a chave de tradução
// enviada pelo servidor (e, se houver, seus parâmetros e o erro de
// cada campo).
// =========================================================================

import 'dart:convert';

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

// "implements Exception": um objeto que pode ser lançado (throw) e capturado (catch)
class ApiError implements Exception {
  final int statusCode; // 0: o servidor não respondeu
  final String key; // p. ex. 'ERRORS.LOGIN_TAKEN'
  final Map<String, String> params;
  final Map<String, String> fields;

  const ApiError(this.statusCode, this.key, {this.params = const {}, this.fields = const {}});

  // uma resposta de erro (4xx, 5xx) -> um ApiError
  factory ApiError.fromResponse(http.Response response) {
    Object? body;
    try {
      body = jsonDecode(utf8.decode(response.bodyBytes));
    } on FormatException {
      body = null; // não é JSON: não foi o nosso servidor que respondeu
    }
    // o "pattern matching" de um Map: se o corpo tem uma chave
    // "key" do tipo String, ela é armazenada na variável key
    if (body case {'key': final String key}) {
      final json = body as Map<String, Object?>;
      return ApiError(response.statusCode, key, params: _strings(json['params']), fields: _strings(json['fields']));
    }
    // sem key: foi o proxy ou a rede que respondeu no lugar
    return ApiError(
      response.statusCode,
      response.statusCode >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }

  // um objeto JSON { "name": "ERRORS..." } -> Map<String, String> (vazio caso contrário)
  static Map<String, String> _strings(Object? json) =>
      json is Map<String, Object?> ? {for (final e in json.entries) e.key: '${e.value}'} : const {};

  @override
  String toString() => '$statusCode $key';
}

O do exemplo 24: qualquer requisição que falha termina com um [ApiError], que contém a chave de tradução da mensagem, seus parâmetros e o erro de cada campo.

11.7.4. lib/api/types.dart

// =========================================================================
// lib/api/types.dart - os objetos JSON trocados com o servidor
// -------------------------------------------------------------------------
// A tradução, em classes Dart, da API descrita no capítulo "O
// servidor, uma caixa-preta" (veja common/types.dart dos exemplos). Cada
// classe lê o seu JSON com pattern matching do Dart 3: uma resposta que não
// tem o formato esperado é detectada assim que é recebida.
// =========================================================================

enum Role { admin, doctor, user }

Role _role(String name) => Role.values.byName(name.toLowerCase());

Never _unexpected(String what, Object? json) => throw FormatException('unexpected $what: $json');

// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
class User {
  final String login;
  final String name; // nome exibido: "Marie PELISSIER"
  final Role role;

  const User(this.login, this.name, this.role);

  factory User.fromJson(Object? json) => switch (json) {
    {'login': final String login, 'name': final String name, 'role': final String role} => User(
      login,
      name,
      _role(role),
    ),
    _ => _unexpected('User', json),
  };
}

// GET /api/captcha
class Captcha {
  final String id;
  final String svg;

  const Captcha(this.id, this.svg);

  factory Captcha.fromJson(Object? json) => switch (json) {
    {'id': final String id, 'svg': final String svg} => Captcha(id, svg),
    _ => _unexpected('Captcha', json),
  };
}

// um título, um nome, um sobrenome
class Identity {
  final String title;
  final String firstName;
  final String lastName;

  const Identity(this.title, this.firstName, this.lastName);

  factory Identity.fromJson(Object? json) => switch (json) {
    {'title': final String title, 'firstName': final String firstName, 'lastName': final String lastName} => Identity(
      title,
      firstName,
      lastName,
    ),
    _ => _unexpected('Identity', json),
  };

  // "Mme Alice DURAND"
  String get label => '$title $firstName $lastName';
}

// um médico ou um cliente: GET /api/doctors, GET /api/clients/:id...
class Person extends Identity {
  final int id;
  final int version; // bloqueio otimista: deve ser reenviado com uma atualização
  final String? login; // somente para o ADMIN

  const Person(this.id, this.version, super.title, super.firstName, super.lastName, [this.login]);

  factory Person.fromJson(Object? json) => switch (json) {
    {
      'id': final int id,
      'version': final int version,
      'title': final String title,
      'firstName': final String firstName,
      'lastName': final String lastName,
    } =>
      Person(id, version, title, firstName, lastName, (json as Map<String, Object?>)['login'] as String?),
    _ => _unexpected('Person', json),
  };

  static List<Person> list(Object? json) => [for (final p in json as List<Object?>) Person.fromJson(p)];
}

// um horário
class Slot {
  final int id;
  final int startHour;
  final int startMinute;
  final int endHour;
  final int endMinute;

  const Slot(this.id, this.startHour, this.startMinute, this.endHour, this.endMinute);

  factory Slot.fromJson(Object? json) => switch (json) {
    {'id': final int id, 'startHour': final int sh, 'startMinute': final int sm, 'endHour': final int eh, 'endMinute': final int em} =>
      Slot(id, sh, sm, eh, em),
    _ => _unexpected('Slot', json),
  };
}

// uma linha da agenda, com os DIREITOS do usuário logado
class ScheduleSlot extends Slot {
  final bool free;
  final Identity? patient; // null: livre, ou ocupado por outro paciente
  final bool mine; // a consulta do paciente logado
  final bool bookable;
  final int? appointmentId; // definido se o usuário pode cancelar

  const ScheduleSlot(
    super.id,
    super.startHour,
    super.startMinute,
    super.endHour,
    super.endMinute,
    this.free,
    this.patient,
    this.mine,
    this.bookable,
    this.appointmentId,
  );

  factory ScheduleSlot.fromJson(Object? json) {
    final s = Slot.fromJson(json);
    return switch (json) {
      {
        'free': final bool free,
        'patient': final Object? patient,
        'mine': final bool mine,
        'bookable': final bool bookable,
        'appointmentId': final int? appointmentId,
      } =>
        ScheduleSlot(
          s.id,
          s.startHour,
          s.startMinute,
          s.endHour,
          s.endMinute,
          free,
          patient == null ? null : Identity.fromJson(patient),
          mine,
          bookable,
          appointmentId,
        ),
      _ => _unexpected('Slot', json),
    };
  }
}

// GET /api/schedule?doctorId=...&day=...
class Schedule {
  final Person doctor;
  final String day; // "yyyy-MM-dd"
  final List<ScheduleSlot> slots;
  final String? info; // chave de tradução (paciente que já tem uma consulta)

  const Schedule(this.doctor, this.day, this.slots, this.info);

  factory Schedule.fromJson(Object? json) => switch (json) {
    {
      'doctor': final Object doctor,
      'day': final String day,
      'slots': final List<Object?> slots,
      'info': final String? info,
    } =>
      Schedule(Person.fromJson(doctor), day, [for (final s in slots) ScheduleSlot.fromJson(s)], info),
    _ => _unexpected('Schedule', json),
  };
}

// uma consulta de GET /api/my-area
class Appointment {
  final int id;
  final String day;
  final Slot slot;
  final Person doctor;

  const Appointment(this.id, this.day, this.slot, this.doctor);

  factory Appointment.fromJson(Object? json) => switch (json) {
    {'id': final int id, 'day': final String day, 'slot': final Object slot, 'doctor': final Object doctor} =>
      Appointment(id, day, Slot.fromJson(slot), Person.fromJson(doctor)),
    _ => _unexpected('Appointment', json),
  };
}

// GET /api/my-area
class MyArea {
  final Identity patient;
  final List<Appointment> appointments;

  const MyArea(this.patient, this.appointments);

  factory MyArea.fromJson(Object? json) => switch (json) {
    {'patient': final Object patient, 'appointments': final List<Object?> a} => MyArea(Identity.fromJson(patient), [
      for (final r in a) Appointment.fromJson(r),
    ]),
    _ => _unexpected('Area', json),
  };
}

// GET /api/my-account
class MyAccount extends Identity {
  final String login;
  final int version;

  const MyAccount(super.title, super.firstName, super.lastName, this.login, this.version);

  factory MyAccount.fromJson(Object? json) {
    final i = Identity.fromJson(json);
    return switch (json) {
      {'login': final String login, 'version': final int version} => MyAccount(
        i.title,
        i.firstName,
        i.lastName,
        login,
        version,
      ),
      _ => _unexpected('Account', json),
    };
  }
}

Os objetos JSON da API, em classes [Dart] (veja o exemplo 24):

  • linha 14: uma função que nunca termina normalmente (lança uma exceção): seu tipo de retorno é [Never]. Ela pode, portanto, servir como caso final de um [switch] de qualquer tipo;
  • linhas 24–30: filtragem de um [Map]: este caso se aplica se o JSON tiver (pelo menos) essas três chaves, com valores desses tipos, que são armazenados em variáveis no processo;
  • linhas 69–88: um médico ou um cliente: uma [Identity], mais um identificador, uma versão (o bloqueio otimista: ela é reenviada com uma modificação) e um login, que só o ADMIN recebe (daí o parâmetro opcional entre colchetes);
  • Linhas 109–114: uma entrada da agenda, mostrando os DIREITOS do usuário logado, calculados pelo servidor: [patient] só é mostrado a quem tem permissão para vê-lo, [bookable] indica se o usuário pode fazer uma reserva; [appointmentId] só é fornecido a quem pode cancelar;
  • linhas 129–151: primeiro, lê-se o próprio horário ([Slot.fromJson]), seguido de seus campos específicos;
  • linhas 209–213: a conta do paciente logado: sua identidade, login e versão. [super.title]: o parâmetro é passado tal como está ao construtor da classe pai.

11.7.5. lib/api/rdvmedecins_api.dart

// =========================================================================
// lib/api/rdvmedecins_api.dart - um método por rota da API
// -------------------------------------------------------------------------
// A "camada de acesso a dados" do cliente (um "repository", no
// vocabulário do guia de arquitetura do Flutter): as telas chamam
// estes métodos tipados, sem saber nada sobre as URLs, o pacote http ou o
// JSON. Se a API mudar, só este arquivo muda.
// Cada método retorna um Future; em caso de falha, ele é concluído com um
// ApiError (veja api_client.dart).
// Os dados enviados (formulários) são Map<String, Object?> simples:
// suas chaves são os nomes dos campos esperados pelo servidor - e os
// dos erros que ele devolve (ApiError.fields).
// =========================================================================

import 'api_client.dart';
import 'types.dart';

// /api/doctors ou /api/clients: ambos são tratados do mesmo modo
enum PersonType { doctors, clients }

typedef Data = Map<String, Object?>;

class RdvMedecinsApi {
  final ApiClient _client;

  RdvMedecinsApi(this._client);

  Future<Object?> _get(String url, {bool isPublic = false}) => _client.request('GET', url, isPublic: isPublic);
  Future<Object?> _post(String url, Object body, {bool isPublic = false}) =>
      _client.request('POST', url, body: body, isPublic: isPublic);

  // login (rotas públicas)
  Future<Captcha> captcha() async => Captcha.fromJson(await _get('/captcha', isPublic: true));

  Future<User> me() async => User.fromJson(await _get('/auth/me', isPublic: true));

  Future<User> logIn(String login, String password, String captchaId, String captcha) async =>
      User.fromJson(
        await _post('/auth/login', {
          'login': login,
          'password': password,
          'captchaId': captchaId,
          'captcha': captcha,
        }, isPublic: true),
      );

  Future<void> logOut() => _post('/auth/logout', {}, isPublic: true);

  // criação de conta (público)
  Future<void> registrationAccess(String captchaId, String captcha) =>
      _post('/register/access', {'captchaId': captchaId, 'captcha': captcha}, isPublic: true);

  Future<bool> registrationAccessStatus() async => switch (await _get('/register/access', isPublic: true)) {
    {'valid': true} => true,
    _ => false,
  };

  Future<String> register(Data data) async => switch (await _post('/register', data, isPublic: true)) {
    {'login': final String login} => login,
    final other => throw FormatException('Unexpected response: $other'),
  };

  // agenda e consultas
  // doctorId null: para um médico logado, a SUA agenda
  Future<Schedule> schedule(int? doctorId, String day) async {
    final params = Uri(queryParameters: {'day': day, 'doctorId': ?doctorId?.toString()}).query;
    return Schedule.fromJson(await _get('/schedule?$params'));
  }

  Future<void> book(String day, int slotId, int? clientId) =>
      _post('/appointments', {'day': day, 'slotId': slotId, 'clientId': ?clientId});

  Future<void> cancelAppointment(int appointmentId) => _client.request('DELETE', '/appointments/$appointmentId');

  // médicos e clientes
  Future<List<Person>> list(PersonType type) async => Person.list(await _get('/${type.name}'));

  Future<Person> read(PersonType type, int id) async => Person.fromJson(await _get('/${type.name}/$id'));

  Future<Person> add(PersonType type, Data data) async =>
      Person.fromJson(await _post('/${type.name}', data));

  Future<Person> edit(PersonType type, int id, Data data) async =>
      Person.fromJson(await _client.request('PUT', '/${type.name}/$id', body: data));

  Future<void> remove(PersonType type, int id) => _client.request('DELETE', '/${type.name}/$id');

  // a área do paciente
  Future<MyArea> myArea() async => MyArea.fromJson(await _get('/my-area'));

  Future<MyAccount> myAccount() async => MyAccount.fromJson(await _get('/my-account'));

  Future<User> editMyAccount(Data data) async =>
      User.fromJson(await _client.request('PUT', '/my-account', body: data));

  Future<void> deleteMyAccount(String currentPassword) =>
      _client.request('DELETE', '/my-account', body: {'currentPassword': currentPassword});
}

Um método por rota da API: esta é a classe [RdvMedecins] do exemplo 24, ampliada.

  • Linha 19: [/api/doctors] e [/api/clients] são tratados da mesma maneira: uma enumeração, em que o nome de cada valor ([PersonType.doctors.name], “doctors”) é o da rota;
  • Linha 21: um alias de tipo: um nome mais descritivo para um tipo existente;
  • linhas 33–47: as rotas de conexão, que são públicas: um 401 tem aqui um significado específico (“ninguém está logado”, “senha incorreta”) e não significa que a sessão expirou;
  • linha 53: o token de criação de conta é válido? Uma [switch] expressão sobre a resposta: [true] somente para [{"valid": true}];
  • Linhas 65–67: os parâmetros do endereço, construídos por [Uri] (que os codifica). ['doctorId': ?doctorId?.toString()]: um elemento opcional de [Map] ([Dart] 3.8): a chave só é adicionada se o valor não for [null]. Um médico logado solicita a agenda sem [doctorId]: o servidor devolve a agenda do próprio médico;
  • linha 71: da mesma forma, [clientId] só é enviado se for conhecido (um paciente está fazendo uma reserva para si mesmo);
  • linhas 76–86: as cinco operações envolvendo médicos ou clientes: [/api/${type.name}];
  • linhas 89–97: a área do paciente. Excluir a conta envia um corpo de mensagem com uma requisição [DELETE] (a senha atual): isso é permitido pelo HTTP, e o pacote [http] também o permite, por meio de um [http.Request] construído manualmente (veja [api_client.dart]).

11.8. Idiomas

11.8.1. lib/i18n/translations.dart

// =========================================================================
// lib/i18n/translations.dart - os dicionários, o idioma atual
// -------------------------------------------------------------------------
// Extraído do exemplo 21. Os dicionários (assets/i18n/fr.json, en.json)
// são os dos clientes Vue.js, Angular e React: mesmas chaves, mesmas
// convenções ({{param}}, plurais _one / _other). O servidor só devolve
// CHAVES ("ERRORS.LOGIN_TAKEN"): é aqui que elas viram
// texto, no idioma escolhido pelo usuário.
//   - t('KEY', {'param': value}) : o texto do idioma atual;
//   - changeLanguage('fr')       : carrega o outro dicionário, notifica
//                                  as telas (ChangeNotifier), armazena
//                                  a escolha no dispositivo.
// =========================================================================

import 'dart:convert';

import 'package:flutter/services.dart';
import 'package:flutter/widgets.dart';
import 'package:intl/intl.dart';
import 'package:shared_preferences/shared_preferences.dart';

const languages = ['fr', 'en'];

class Translations extends ChangeNotifier {
  final SharedPreferences? _storage;
  String _language = 'en';
  Map<String, Object?> _dictionary = {};

  Translations([this._storage]);

  String get language => _language;

  // o idioma inicial: o guardado no dispositivo, senão o do
  // celular (se for conhecido), senão o inglês
  Future<void> start() async {
    final stored = _storage?.getString('rdvmedecins.language');
    final device = WidgetsBinding.instance.platformDispatcher.locale.languageCode;
    await changeLanguage(stored ?? (languages.contains(device) ? device : 'en'));
  }

  Future<void> changeLanguage(String language) async {
    // rootBundle: os arquivos distribuídos com o aplicativo (seção assets do pubspec)
    final json = await rootBundle.loadString('assets/i18n/$language.json');
    _dictionary = jsonDecode(json) as Map<String, Object?>;
    _language = language;
    await _storage?.setString('rdvmedecins.language', language);
    notifyListeners();
  }

  // "HOME.HELLO" -> dictionary['HOME']['HELLO']; null se ausente
  String? _find(String key) {
    Object? node = _dictionary;
    for (final part in key.split('.')) {
      node = node is Map<String, Object?> ? node[part] : null;
    }
    return node is String ? node : null;
  }

  String t(String key, [Map<String, Object?> params = const {}]) {
    String? text;
    final count = params['count'];
    if (count is int) {
      // Intl.pluralLogic: a forma plural, de acordo com as regras do idioma
      text = Intl.pluralLogic(
        count,
        locale: _language,
        zero: _find('${key}_zero'),
        one: _find('${key}_one'),
        other: _find('${key}_other'),
      );
    }
    text ??= _find(key);
    // uma chave desconhecida é exibida como está: vemos imediatamente o que falta
    if (text == null) return key;
    // {{name}} -> o valor do parâmetro name
    return text.replaceAllMapped(RegExp(r'\{\{(\w+)\}\}'), (m) => '${params[m[1]] ?? m[0]}');
  }
}

A classe [Translations] do exemplo 21, simplificada: os dicionários sempre têm o mesmo nome ([assets/i18n/fr.json]).

  • linhas 35–38: o idioma inicial: o selecionado durante um uso anterior; caso contrário, o idioma do celular, se a aplicação o conhecer; caso contrário, inglês. [platformDispatcher.locale]: o idioma do sistema;
  • linhas 59–76: a tradução de uma chave, incluindo plurais ([_zero], [_one], [_other]) e parâmetros ([{{name}}]), segundo as convenções do [i18next], que são as mesmas usadas nos dicionários dos outros clientes.

11.8.2. Os dicionários

Os dicionários são os do cliente [React], complementados com algumas chaves específicas da aplicação mobile (o menu “Minha conta”, “Escolha o dia” etc.). O início do dicionário em francês:

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace",
    "LOADING": "Chargement...",
    "LANGUAGE": "Langue",
    "MENU_ACCOUNT": "Mon compte",
    "CONNECTED_AS": "Connecté : {{name}}",
    "RETRY": "Réessayer"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda",
    "CHOOSE_DAY": "Choisir le jour"
  },

Um arquivo por idioma, com as mesmas chaves em cada um; um grupo de chaves por tela; as chaves [ERRORS.*] são as devolvidas pelo servidor.

11.9. O estado compartilhado

Três [ChangeNotifier] entradas, fornecidas a toda a aplicação por [main.dart].

11.9.1. lib/state/session.dart

// =========================================================================
// lib/state/session.dart - QUEM está logado?
// -------------------------------------------------------------------------
// O usuário logado (ou null), em um ChangeNotifier fornecido a todo o
// aplicativo (provider, veja o exemplo 20): legível pelas telas E pelo
// roteador, que o escuta para reavaliar seus guards (refreshListenable).
//
// O próprio token JWT NÃO está aqui: está em um cookie (tratado pelo
// navegador na web, pelo CookieClient no celular). A
// sessão guarda apenas a DESCRIÇÃO do usuário ({ login, name, role }).
//
// Quando o aplicativo inicia, a sessão está vazia: check() pergunta
// ao servidor, uma só vez, quem está logado (GET /api/auth/me).
// =========================================================================

import 'package:flutter/foundation.dart';

import '../api/rdvmedecins_api.dart';
import '../api/types.dart';

class Session extends ChangeNotifier {
  final RdvMedecinsApi _api;
  User? _user;
  // true depois de um logout DESEJADO (botão, exclusão da conta); false
  // depois de uma sessão expirada. O roteador leva isso em conta (veja router.dart)
  bool _voluntaryLogout = false;
  // a pergunta "quem está logado?" já foi feita ao servidor?
  Future<void>? _checking;

  Session(this._api);

  User? get user => _user;
  bool get voluntaryLogout => _voluntaryLogout;

  // só pergunta ao servidor na primeira vez (o Future é mantido)
  Future<void> check() => _checking ??= _api.me().then(
    (u) => _change(u),
    onError: (Object _) => _change(null), // 401: ninguém; ou servidor inacessível
  );

  Future<void> logIn(String login, String password, String captchaId, String captcha) async {
    _change(await _api.logIn(login, password, captchaId, captcha));
  }

  // o usuário mudou de nome ou de login (PUT /api/my-account)
  void update(User u) => _change(u);

  Future<void> logOut() async {
    try {
      await _api.logOut();
    } finally {
      forget(voluntary: true);
    }
  }

  // sem perguntar nada ao servidor: sessão expirada, conta excluída
  void forget({bool voluntary = false}) => _change(null, voluntary: voluntary);

  // notifyListeners: o roteador (refreshListenable) reavalia seus guards, e
  // sai sozinho de uma tela que o novo usuário não tem permissão para ver
  void _change(User? u, {bool voluntary = false}) {
    _user = u;
    _voluntaryLogout = voluntary;
    notifyListeners();
  }
}

// o que deduzimos do usuário: extensions ("getters" adicionados a User?)
extension Rights on User? {
  bool get isAdmin => this?.role == Role.admin;
  bool get isPatient => this?.role == Role.user;
  // ADMIN e DOCTOR: marcam e cancelam as consultas de qualquer paciente
  bool get isManager => this?.role == Role.admin || this?.role == Role.doctor;
  // a página inicial de cada papel, logo após o login
  String get homePage => isPatient ? '/my-area' : '/schedule';
}

Quem está logado? A sessão armazena a DESCRIÇÃO do usuário (login, nome, papel), não o token, que permanece no cookie do usuário.

  • Linhas 36–38: a pergunta “Quem está logado?” é enviada ao servidor ([GET /api/auth/me]) apenas UMA VEZ, na inicialização: [??=] só atribui o [Future] se [_checking] for [null]. As chamadas seguintes devolvem o mesmo [Future], já concluído: o roteador pode chamar [check()] antes de cada navegação sem nenhum custo. Na inicialização, se o cookie armazenado contiver um token ainda válido, o usuário continua logado;
  • linhas 41–42: o login: se o servidor recusar, [_api.logIn] lança um [ApiError], e [_change] não é chamado;
  • linhas 48–52: o logout: o usuário é esquecido mesmo que o servidor não responda ([finally]);
  • linhas 61–64: todas as mudanças passam por aqui e notificam os listeners: as telas que exibem o usuário (o layout), o cache (que é limpo) e o roteador (que reavalia seus guards). [_voluntaryLogout] distingue um logout intencional de uma sessão expirada (veja [router.dart]);
  • linhas 69–75: uma extensão adiciona getters a um tipo existente, neste caso [User?]: [session.user.isAdmin] é [false] se ninguém estiver logado, sem verificar antes se é [null] ([this?.role]).

11.9.2. lib/state/messages.dart

// =========================================================================
// lib/state/messages.dart - as mensagens exibidas ao usuário
// -------------------------------------------------------------------------
// Mesma apresentação dos outros clientes RdvMedecins:
//   - um SUCESSO é exibido no TOPO da tela (banner verde);
//   - um ERRO na PARTE INFERIOR (banner rosa), sempre visível.
// Uma mensagem é uma CHAVE de tradução (+ seus parâmetros): ela é, portanto,
// traduzida de novo por conta própria se o usuário mudar de idioma.
//
// As mensagens "flash": uma ação que termina com uma mudança de
// tela (marcar consulta, adicionar um médico...) deixa sua mensagem com
// flash(); ela será exibida na PRÓXIMA tela, e depois desaparece na
// navegação seguinte. É o roteador que chama newPage() ao
// fim de cada navegação (veja router.dart).
// =========================================================================

import 'package:flutter/foundation.dart';

import '../api/api_error.dart';

typedef Message = ({String key, Map<String, String> params});

class Messages extends ChangeNotifier {
  Message? success;
  Message? error;
  // as mensagens a exibir na próxima tela
  Message? _pendingSuccess;
  Message? _pendingError;

  void showSuccess(String key, [Map<String, String> params = const {}]) {
    success = (key: key, params: params);
    error = null;
    notifyListeners();
  }

  void showError(String key, [Map<String, String> params = const {}]) {
    error = (key: key, params: params);
    success = null;
    notifyListeners();
  }

  // um ApiError -> a mensagem da tela; qualquer outro erro é um
  // bug do cliente, que deixamos propagar
  void showApiError(Object e) {
    if (e is! ApiError) throw e;
    showError(e.key, e.params);
  }

  void clear() {
    success = null;
    error = null;
    notifyListeners();
  }

  // para a PRÓXIMA tela
  void flash({bool success = true, required String key, Map<String, String> params = const {}}) {
    if (success) {
      _pendingSuccess = (key: key, params: params);
    } else {
      _pendingError = (key: key, params: params);
    }
  }

  // uma nova tela: as mensagens da anterior desaparecem, as mensagens
  // flash aparecem
  void newPage() {
    success = _pendingSuccess;
    error = _pendingError;
    _pendingSuccess = null;
    _pendingError = null;
    notifyListeners();
  }
}

Mensagens da aplicação: uma mensagem de sucesso no topo da tela, uma mensagem de erro na parte inferior (veja [layout.dart]).

  • linha 21: uma mensagem é uma CHAVE de tradução e seus parâmetros (um único record). Ela só é traduzida quando é exibida: mudar o idioma retraduz as mensagens exibidas;
  • Linhas 44–46: um [ApiError] se torna a mensagem de erro da tela. Qualquer outra exceção é um problema do lado do cliente: nós a relançamos para que apareça no console durante o desenvolvimento, em vez de escondê-la;
  • linhas 56–60: uma mensagem para a PRÓXIMA tela: uma ação que termina com uma mudança de tela (uma reserva, uma inclusão etc.) coloca sua mensagem aqui;
  • linhas 66–71: chamado toda vez que o endereço muda (veja [main.dart]): as mensagens da tela anterior desaparecem e as mensagens flash aparecem.

11.9.3. lib/state/cache.dart

// =========================================================================
// lib/state/cache.dart - os dados já lidos do servidor
// -------------------------------------------------------------------------
// A lista de médicos quase nunca muda: não há necessidade de lê-la de novo a
// cada visita à agenda. O cache mantém o Future de cada leitura,
// sob uma CHAVE ('doctors', 'schedule/1/2026-10-05'...):
//
//     cache.read('doctors', () => api.list(PersonType.doctors))
//
// retorna o Future já mantido, ou inicia a leitura e o mantém.
// Após uma alteração, INVALIDAMOS as chaves envolvidas (elas serão
// lidas de novo na próxima requisição): cache.invalidate('schedule').
// Uma leitura que falhou não é mantida: a próxima tentará de novo.
// O cache é um ChangeNotifier: invalidate() notifica seus ouvintes. Uma
// tela ainda viva (mesmo escondida sob outra na pilha, como
// a agenda sob seu diálogo de marcação) pode assim ler seus dados de novo.
// É, em poucas linhas, o que a biblioteca TanStack Query do
// cliente React faz.
// =========================================================================

import 'package:flutter/foundation.dart';

class Cache extends ChangeNotifier {
  final Map<String, Future<Object?>> _futures = {};

  Future<T> read<T>(String key, Future<T> Function() load) {
    final future = _futures.putIfAbsent(key, () {
      final f = load();
      // em caso de falha, esquecemos este Future (a próxima requisição tentará de novo)
      f.then((_) {}, onError: (Object _) => _futures.remove(key));
      return f;
    });
    return future.then((v) => v as T);
  }

  // esquece todas as chaves que começam com prefix, e notifica as telas
  void invalidate(String prefix) {
    _futures.removeWhere((key, _) => key.startsWith(prefix));
    notifyListeners();
  }

  // troca de usuário: esquecemos tudo, SEM notificar (as telas do
  // usuário anterior vão desaparecer, elas não devem ler nada de novo)
  void clear() => _futures.clear();
}

Dados já lidos do servidor: o equivalente, em poucas linhas, ao [TanStack Query] do cliente [React].

  • Linha 24: o cache armazena [Future], e não valores reais: duas telas que solicitam os mesmos dados enquanto eles estão em trânsito recebem o MESMO [Future], e apenas uma requisição é enviada;
  • Linhas 26–33: um método genérico: [read<List<Person>>(...)] devolve um [Future<List<Person>>] (o tipo [T] é, na maioria das vezes, inferido a partir da função [load]). [putIfAbsent]: o valor da chave ou, se a chave não existir, o resultado da função, armazenado sob essa chave. Uma leitura que falhou é ignorada: a próxima requisição tentará novamente;
  • linhas 37–39: após uma modificação, as chaves afetadas são descartadas e as telas são notificadas. A tela da agenda escuta isso: após uma reserva, ela se recarrega, mesmo que esteja escondida atrás da janela de reserva;
  • linha 44: quando o usuário muda, tudo é limpo sem notificar ninguém: as telas do usuário anterior desaparecerão; não têm nada a recarregar.

11.10. Formatação

11.10.1. lib/formatting.dart

// =========================================================================
// lib/formatting.dart - a exibição de horários e dias
// -------------------------------------------------------------------------
// O servidor envia dados BRUTOS (startHour: 8, startMinute: 0; day:
// "2026-10-05"); a formatação, que depende do idioma, é assunto
// do cliente (veja o exemplo 09).
// =========================================================================

import 'package:intl/intl.dart';

import 'api/types.dart';

String _twoDigits(int n) => n.toString().padLeft(2, '0');

// "8:05" em vez de "8:5"
String time(int h, int m) => '$h:${_twoDigits(m)}';

// "8:00 - 8:20"
String timeRange(Slot s) => '${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}';

// uma data -> "yyyy-MM-dd" (o formato da API)
String toDay(DateTime d) => '${d.year}-${_twoDigits(d.month)}-${_twoDigits(d.day)}';

String today() => toDay(DateTime.now());

// true se day for uma data que existe, no formato yyyy-MM-dd
bool isValidDate(String day) {
  if (!RegExp(r'^\d{4}-\d{2}-\d{2}$').hasMatch(day)) return false;
  final d = DateTime.tryParse(day);
  return d != null && toDay(d) == day; // 2026-02-30 -> 2026-03-02: recusado
}

// "Monday, October 5, 2026" / "lundi 5 octobre 2026"
String longDate(String day, String language) => DateFormat.yMMMMEEEEd(language).format(DateTime.parse(day));

Formatação dos dados brutos do servidor (veja o exemplo 09):

  • linha 22: um [DateTime] no formato da API (“2026-10-05”);
  • linhas 27–30: a data do endereço é válida? [DateTime.tryParse] aceita “2026-02-30” (2 de março): verificamos que a mesma string está presente;
  • linha 34: “Monday, October 5, 2026” ou “lundi 5 octobre 2026”, conforme o idioma ([DateFormat.yMMMMEEEEd] derivado de [intl]).

11.11. O roteador

11.11.1. lib/router.dart

// =========================================================================
// lib/router.dart - as telas do aplicativo e seus direitos de acesso
// -------------------------------------------------------------------------
// Os MESMOS endereços dos outros clientes (/login, /schedule, /doctors,
// /my-area...). Na web, eles são exibidos na barra de endereço;
// no celular, permanecem invisíveis, mas organizam o aplicativo
// da mesma forma (e a pilha de telas do botão Voltar).
//
// Todas as telas estão em uma ShellRoute, cujo widget, AppLayout, as exibe
// entre a barra superior e o painel de erros.
//
// Os GUARDS: a função redirect do GoRouter é chamada antes de CADA
// navegação. Ela pode ser assíncrona: na primeira vez (inicialização do
// aplicativo, F5 na web), espera a resposta do servidor à
// pergunta "quem está logado?" (session.check()). Depois verifica os
// direitos da tela solicitada (rightsOf), e redireciona se necessário.
// LEMBRETE: estas verificações são apenas uma COMODIDADE (não exibir uma tela
// inútil). A proteção dos dados é garantida pelo servidor, que
// verifica de novo o token e o papel a CADA requisição.
// =========================================================================

import 'package:go_router/go_router.dart';

import 'api/rdvmedecins_api.dart';
import 'api/types.dart';
import 'state/messages.dart';
import 'state/session.dart';
import 'pages/schedule.dart';
import 'pages/login.dart';
import 'pages/patient_area.dart';
import 'pages/register.dart';
import 'pages/my_account.dart';
import 'pages/error_page.dart';
import 'pages/person_form.dart';
import 'pages/persons.dart';
import 'widgets/layout.dart';

// os direitos de acesso de uma tela: pública (sem login), ou reservada a
// alguns papéis (null: todos os papéis logados)
typedef Rights = ({bool public, Set<Role>? roles});

Rights rightsOf(String path) => switch (path) {
  '/login' || '/register' => (public: true, roles: null),
  _ when path.startsWith('/doctors') || path.startsWith('/clients') => (public: false, roles: {Role.admin}),
  '/my-area' || '/my-account' => (public: false, roles: {Role.user}),
  '/schedule' || '/forbidden' || '/' => (public: false, roles: null),
  _ => (public: true, roles: null), // endereço desconhecido: a página 404, para todos
};

// somente um caminho INTERNO ("/doctors"): nunca "//other-site.com"
String? internalPath(String? r) => r != null && r.startsWith('/') && !r.startsWith('//') ? r : null;

// "3" -> 3; "", "abc", "-2", ausente (null) -> null
int? positiveInteger(String? value) {
  final n = int.tryParse(value ?? '');
  return n != null && n > 0 ? n : null;
}

GoRouter createRouter(Session session, Messages messages, RdvMedecinsApi api) {
  // as três telas de gestão dos médicos OU dos clientes (ADMIN)
  List<GoRoute> personRoutes(PersonType type) => [
    GoRoute(
      path: '/${type.name}',
      builder: (_, _) => PersonsPage(type: type),
    ),
    GoRoute(
      path: '/${type.name}/add',
      builder: (_, _) => PersonFormPage(type: type),
    ),
    GoRoute(
      path: '/${type.name}/:id/edit',
      builder: (_, state) {
        final id = positiveInteger(state.pathParameters['id']);
        // /doctors/abc/edit: este endereço não existe
        return id == null ? const ErrorPage(code: 404) : PersonFormPage(type: type, id: id);
      },
    ),
  ];

  return GoRouter(
    initialLocation: '/login',
    // a sessão muda (login, logout, expiração): os guards
    // são reavaliados para a tela atual
    refreshListenable: session,
    redirect: (context, state) async {
      await session.check();
      final user = session.user;
      final path = state.uri.path;
      final rights = rightsOf(path);
      if (rights.public) {
        // logado: a tela de login deixa de fazer sentido. É AQUI que saímos
        // dela, logo após o login: a sessão mudou, o roteador
        // (que a escuta) reavalia seus guards. Vamos para a tela solicitada antes do
        // login (?redirect=...), caso contrário para a página inicial do papel
        if (path == '/login' && user != null) {
          return internalPath(state.uri.queryParameters['redirect']) ?? user.homePage;
        }
        return null;
      }
      if (user == null) {
        // logout desejado: a tela de login, simplesmente
        if (session.voluntaryLogout) return '/login';
        // sessão expirada, endereço aberto sem estar logado: lembramos a
        // tela solicitada, para voltar a ela após o login
        return Uri(path: '/login', queryParameters: {'redirect': state.uri.toString()}).toString();
      }
      if (path == '/') return user.homePage;
      if (rights.roles != null && !rights.roles!.contains(user.role)) return '/forbidden';
      return null;
    },
    routes: [
      ShellRoute(
        builder: (context, state, child) => AppLayout(child: child),
        routes: [
          GoRoute(path: '/', builder: (_, _) => const ErrorPage(code: 404)), // (redirecionado acima)
          GoRoute(
            path: '/login',
            builder: (_, state) {
              // o login do endereço: 30 caracteres no máximo
              final login = state.uri.queryParameters['login'] ?? '';
              return LoginPage(login: login.length > 30 ? login.substring(0, 30) : login);
            },
          ),
          GoRoute(
            path: '/schedule',
            builder: (_, state) => SchedulePage(
              doctorId: positiveInteger(state.uri.queryParameters['doctorId']),
              day: state.uri.queryParameters['day'],
              book: positiveInteger(state.uri.queryParameters['book']),
            ),
          ),
          ...personRoutes(PersonType.doctors),
          ...personRoutes(PersonType.clients),
          GoRoute(
            path: '/register',
            // um guard ESPECÍFICO desta rota: sem um passe (captcha
            // resolvido na tela de login), volta para a tela de login
            redirect: (context, state) async {
              final valid = await api.registrationAccessStatus().catchError((_) => false);
              if (valid) return null;
              messages.flash(success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
              return '/login';
            },
            builder: (_, _) => const RegisterPage(),
          ),
          GoRoute(path: '/my-area', builder: (_, _) => const PatientAreaPage()),
          GoRoute(path: '/my-account', builder: (_, _) => const MyAccountPage()),
          GoRoute(path: '/forbidden', builder: (_, _) => const ErrorPage(code: 403)),
        ],
      ),
    ],
    // um endereço que nenhuma rota descreve: a página 404, no layout
    errorBuilder: (context, state) => const AppLayout(child: ErrorPage(code: 404)),
  );
}

As telas da aplicação, seus endereços e seus direitos de acesso (veja os exemplos 17 e 18).

  • Linha 40: os direitos de acesso de uma tela: pública ou restrita a certos papéis ([null]: todos os papéis);
  • Linhas 42–47: as permissões de cada endereço, em um ÚNICO lugar: uma expressão [switch] sobre strings. ['/login' || '/register']: um padrão “ou”; [_ when ...]: um padrão “qualquer”, com uma condição (um guard);
  • linha 51: o endereço [?redirect=] só é seguido se for um caminho INTERNO: na web, um endereço [/login?redirect=//pirate-site.com] enviado por e-mail não deve levar o usuário para outro lugar depois do login;
  • linhas 54–56: os parâmetros de um endereço são strings, escritas por qualquer pessoa (na web): “abc” ou “-2” viram [null];
  • linhas 61–78: uma função local que gera as três rotas dos médicos OU dos clientes: [/doctors], [/doctors/add], [/doctors/:id/edit]. [:id]: um parâmetro de caminho, lido por [state.pathParameters['id']];
  • linha 81: a tela inicial no celular (na web, é o endereço digitado);
  • linha 84: o roteador acompanha a sessão: a cada mudança (login, logout, expiração), reavalia seus guards para a tela atual e troca de tela se necessário;
  • linhas 85–109: O guard, chamado antes de cada navegação:
    • linha 86: na primeira vez, esperamos a resposta do servidor à pergunta “quem está conectado?”; depois disso, essa chamada não custa nada;
    • linhas 90–98: uma tela pública é acessível a todos; porém, um usuário já conectado não tem o que fazer na tela de login: ele vai para a tela que havia solicitado antes de se conectar ou para a tela inicial do seu papel. É assim que a aplicação sai da tela de login após um login bem-sucedido: a própria tela de login não precisa navegar;
    • linhas 100–105: ninguém está conectado: vá para a tela de login. Depois que uma sessão expirou, ou se uma URL protegida (na web) foi aberta diretamente, a tela solicitada ([?redirect=]) é guardada para que o usuário possa voltar a ela depois do login; após um logout voluntário, ela não é guardada;
    • linhas 107–108: [/] leva à página inicial do papel; um papel insuficiente leva a uma página 403;
  • linhas 112–113: todas as telas são exibidas dentro do layout (a barra superior, o menu, as mensagens);
  • linhas 117–121: [/login?login=jbernard] (após a criação de uma conta) preenche previamente o campo de login;
  • linhas 125–129: os três parâmetros da agenda, lidos da URL; todo o estado da tela está presente ali (veja [schedule.dart]);
  • linhas 135–142: um guard ESPECÍFICO de uma rota: a criação de conta exige um passe, que o servidor emite depois que o CAPTCHA é digitado ([POST /api/register/access], veja a tela de login). Sem ele, o usuário é redirecionado para a tela de login com uma mensagem;
  • linha 153: um endereço não associado a nenhuma rota: a página 404, dentro do layout.

Essas proteções são apenas uma formalidade: evitam que uma tela inútil seja exibida. A proteção dos dados é garantida pelo servidor, que verifica novamente o token e o papel a cada requisição.

11.12. Os widgets

11.12.1. lib/widgets/layout.dart

// =========================================================================
// lib/widgets/layout.dart - o LAYOUT comum a todas as telas
// -------------------------------------------------------------------------
// O widget da ShellRoute do roteador (veja router.dart):
//   - a barra superior: título, idioma (FR / EN), logout;
//   - o menu lateral ("drawer", Drawer), aberto pelo botão ☰: as
//     telas permitidas ao papel do usuário. "Doctors" e "Patients"
//     só aparecem para o ADMIN: uma mera comodidade de exibição, sendo a
//     proteção real a do servidor;
//   - uma mensagem de sucesso no TOPO;
//   - a tela atual (child);
//   - o painel de erros na PARTE INFERIOR.
// Em uma tela grande (web, tablet), o menu é exibido permanentemente
// à esquerda: um NavigationRail no lugar do drawer.
// =========================================================================

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

import '../state/messages.dart';
import '../state/session.dart';
import '../i18n/translations.dart';

// uma entrada de menu: caminho, chave do rótulo, ícone
typedef MenuEntry = ({String path, String key, IconData icon});

List<MenuEntry> menuEntries(Session session) {
  final u = session.user;
  if (u == null) return const [];
  return [
    if (u.isPatient) (path: '/my-area', key: 'APP.MENU_MY_AREA', icon: Icons.home),
    (path: '/schedule', key: 'APP.MENU_SCHEDULE', icon: Icons.calendar_month),
    if (u.isAdmin) ...[
      (path: '/doctors', key: 'APP.MENU_DOCTORS', icon: Icons.medical_services),
      (path: '/clients', key: 'APP.MENU_PATIENTS', icon: Icons.people),
    ],
    if (u.isPatient) (path: '/my-account', key: 'APP.MENU_ACCOUNT', icon: Icons.manage_accounts),
  ];
}

class AppLayout extends StatelessWidget {
  final Widget child;

  const AppLayout({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    final translations = context.watch<Translations>();
    final t = translations.t;
    final session = context.watch<Session>();
    final u = session.user;
    final entries = menuEntries(session);
    // o endereço atual, como o roteador o conhece
    final path = GoRouter.of(context).routerDelegate.currentConfiguration.uri.path;
    final active = entries.indexWhere((e) => path.startsWith(e.path));
    // MediaQuery: as dimensões da tela; a partir de 800 pontos, uma tela grande
    final largeScreen = MediaQuery.sizeOf(context).width >= 800;

    // a sessão fica vazia; o roteador, que a escuta, exibe a tela de login
    Future<void> logOut() => session.logOut().catchError((_) {}); // mesmo que o servidor não responda

    final content = Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        const _SuccessMessage(),
        Expanded(child: child),
        const _ErrorPanel(),
      ],
    );

    return Scaffold(
      appBar: AppBar(
        title: Text(t('APP.TITLE')),
        backgroundColor: Theme.of(context).colorScheme.primary,
        foregroundColor: Theme.of(context).colorScheme.onPrimary,
        actions: [
          // FR / EN: nenhuma requisição ao servidor, a tela é traduzida de novo na hora
          PopupMenuButton<String>(
            tooltip: t('APP.LANGUAGE'),
            // o texto, na cor dos ícones da barra (onPrimary)
            icon: Text(
              translations.language.toUpperCase(),
              style: TextStyle(fontWeight: FontWeight.bold, color: Theme.of(context).colorScheme.onPrimary),
            ),
            onSelected: translations.changeLanguage,
            itemBuilder: (_) => [for (final l in languages) PopupMenuItem(value: l, child: Text(l.toUpperCase()))],
          ),
          if (u != null) IconButton(tooltip: t('APP.LOGOUT'), icon: const Icon(Icons.logout), onPressed: logOut),
        ],
      ),
      // o drawer: somente quando logado, e somente em uma tela pequena
      drawer: u == null || largeScreen
          ? null
          : NavigationDrawer(
              selectedIndex: active < 0 ? null : active,
              onDestinationSelected: (i) {
                Navigator.pop(context); // fecha o drawer
                context.go(entries[i].path);
              },
              children: [
                // o cabeçalho: quem está logado
                Padding(
                  padding: const EdgeInsets.fromLTRB(28, 16, 16, 10),
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.start,
                    children: [
                      Text(u.name, style: Theme.of(context).textTheme.titleMedium),
                      Chip(label: Text(u.role.name.toUpperCase())),
                    ],
                  ),
                ),
                for (final e in entries) NavigationDrawerDestination(icon: Icon(e.icon), label: Text(t(e.key))),
              ],
            ),
      body: u == null || !largeScreen
          ? content
          : Row(
              children: [
                NavigationRail(
                  selectedIndex: active < 0 ? null : active,
                  labelType: NavigationRailLabelType.all,
                  onDestinationSelected: (i) => context.go(entries[i].path),
                  destinations: [
                    for (final e in entries) NavigationRailDestination(icon: Icon(e.icon), label: Text(t(e.key))),
                  ],
                ),
                const VerticalDivider(width: 1),
                Expanded(child: content),
              ],
            ),
    );
  }
}

// a mensagem de sucesso, no topo
class _SuccessMessage extends StatelessWidget {
  const _SuccessMessage();

  @override
  Widget build(BuildContext context) {
    final success = context.watch<Messages>().success;
    if (success == null) return const SizedBox.shrink();
    final t = context.watch<Translations>().t;
    return Material(
      color: Colors.green.shade50,
      child: ListTile(
        leading: Icon(Icons.check_circle, color: Colors.green.shade700),
        title: Text(t(success.key, success.params), style: TextStyle(color: Colors.green.shade900)),
        trailing: IconButton(icon: const Icon(Icons.close), onPressed: context.read<Messages>().clear),
      ),
    );
  }
}

// o painel de erros, na parte inferior: sempre visível, mesmo que a tela role
class _ErrorPanel extends StatelessWidget {
  const _ErrorPanel();

  @override
  Widget build(BuildContext context) {
    final error = context.watch<Messages>().error;
    if (error == null) return const SizedBox.shrink();
    final t = context.watch<Translations>().t;
    return Material(
      color: const Color(0xFFF8D7DA),
      // SafeArea: acima da barra de navegação do celular
      child: SafeArea(
        top: false,
        child: ListTile(
          leading: Icon(Icons.error, color: Colors.red.shade800),
          title: Text(t(error.key, error.params), style: TextStyle(color: Colors.red.shade900)),
          trailing: IconButton(icon: const Icon(Icons.close), onPressed: context.read<Messages>().clear),
        ),
      ),
    );
  }
}

O layout, o widget do [ShellRoute]: o elemento que envolve todas as telas.

  • Linha 26: uma entrada de menu: um record;
  • linhas 28–38: entradas permitidas para o papel do usuário, por meio de um [if] em uma lista (exemplo 03). [...[...]]: o operador spread insere vários elementos de uma só vez;
  • linha 55: o endereço atual, para marcar a entrada de menu ativa;
  • linha 58: a largura da tela, em pontos. Acima de 800 pontos (a web, um tablet na horizontal), o menu é exibido permanentemente;
  • linha 61: logout: a sessão é apagada, e o roteador, que está escutando, exibe a tela de login. [catchError]: mesmo que o servidor não responda, o usuário é considerado desconectado;
  • linhas 63–68: a mensagem de sucesso no alto, a tela no meio ([Expanded]: todo o espaço restante), o erro embaixo;
  • linhas 73–89: a barra superior: o título, o menu de idioma ([PopupMenuButton]: um botão que abre uma lista; seu ícone aqui é um texto, “FR” ou “EN”), o botão de logout;
  • linhas 93–113: em uma tela pequena, um drawer ([NavigationDrawer]), que se abre pelo botão ☰ que o [Scaffold] adiciona automaticamente à barra superior. Tocar em uma entrada fecha o drawer ([Navigator.pop]) e muda a URL;
  • linhas 116–129: em uma tela grande, um [NavigationRail]: o menu, disposto em coluna à esquerda do conteúdo;
  • linhas 137–154: a mensagem de sucesso. [context.watch<Messages>()]: o widget é reconstruído sempre que as mensagens mudam; quando não há mensagens, ele não ocupa espaço ([SizedBox.shrink]);
  • linhas 168–169: a área de erro fica na parte inferior da tela: [SafeArea] a mantém separada da barra de navegação do celular (os botões ou a barra de gestos do [Android]).

11.12.2. lib/widgets/page_title.dart

// =========================================================================
// lib/widgets/page_title.dart - o título da tela, traduzido
// -------------------------------------------------------------------------
// Na web: o título da aba; no Android: o nome do aplicativo
// na lista de aplicativos recentes. "Schedule - RdvMedecins"
// =========================================================================

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

import '../i18n/translations.dart';

class PageTitle extends StatelessWidget {
  final String titleKey;
  final Widget child;

  const PageTitle({super.key, required this.titleKey, required this.child});

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    return Title(title: '${t(titleKey)} - ${t('APP.TITLE')}', color: Theme.of(context).colorScheme.primary, child: child);
  }
}

O título da tela, traduzido ([Title], veja o exemplo 02): o título da aba na web, o nome do aplicativo na lista de aplicativos recentes do [Android].

11.12.3. lib/widgets/form_submit.dart

// =========================================================================
// lib/widgets/form_submit.dart - envio de um formulário ao servidor
// -------------------------------------------------------------------------
// Todos os formulários do aplicativo seguem o mesmo padrão do
// exemplo 25: nenhuma regra é verificada no celular (elas vivem
// em UM só lugar, o servidor), e em caso de recusa:
//   - o erro de cada campo (ApiError.fields) é exibido sob o campo;
//   - a mensagem geral (ApiError.key) é exibida na parte inferior da tela.
// Esta classe agrupa estas etapas (é o Command do exemplo 23,
// completado com os erros dos campos). Uma tela cria um por formulário:
//
//     final _submit = FormSubmit(messages);
//     if (await _submit.submit(() => api.register(input))) { ... }
//     InputField(..., error: _submit.errors['lastName'])
// =========================================================================

import 'package:flutter/foundation.dart';

import '../api/api_error.dart';
import '../state/messages.dart';

class FormSubmit extends ChangeNotifier {
  final Messages _messages;
  // o erro de cada campo: uma CHAVE de tradução
  Map<String, String> errors = {};
  // os parâmetros das mensagens de erro ({{min}}...), devolvidos pelo servidor
  Map<String, String> params = {};
  bool submitting = false;

  FormSubmit(this._messages);

  // executa o envio; retorna true se teve sucesso. Em caso de ApiError, os
  // erros são exibidos e retornamos false
  Future<bool> submit(Future<void> Function() action) async {
    if (submitting) return false; // sem envio duplo
    errors = {};
    params = {};
    submitting = true;
    notifyListeners();
    try {
      await action();
      return true;
    } on ApiError catch (e) {
      _messages.showApiError(e);
      errors = e.fields;
      params = e.params;
      return false;
    } finally {
      submitting = false;
      notifyListeners();
    }
  }

  // o usuário muda um campo: seu erro desaparece
  void clearError(String field) {
    if (errors.containsKey(field)) {
      errors = {...errors}..remove(field);
      notifyListeners();
    }
  }
}

O envio de um formulário ao servidor: o [Command] do exemplo 23, complementado com os erros de campo (exemplo 25).

  • Linhas 34–50: o envio: sem envios duplicados; durante o envio, [submitting] (os botões ficam desabilitados); diante de um [ApiError], a mensagem geral é exibida na parte inferior da tela, junto com o erro de cada campo. [finally] é executado em todos os casos, mesmo após um [return];
  • linhas 55–57: o usuário corrige um campo; o erro desaparece. Substituímos o [Map] por uma cópia, em vez de modificá-lo: o antigo pode ter sido fornecido pelo servidor ([e.fields]), e um [Map] constante ([const {}]) não muda.

11.12.4. lib/widgets/input_field.dart

// =========================================================================
// lib/widgets/input_field.dart - um campo de formulário completo
// -------------------------------------------------------------------------
// Rótulo + campo + mensagem de ajuda OU mensagem de erro. Todos os
// formulários do aplicativo o utilizam:
//
//   InputField(label: 'PERSONS.LASTNAME_LABEL', maxLength: 20,
//              value: _input['lastName'], onChanged: (v) => _edit('lastName', v),
//              error: _submit.errors['lastName'])
//
// É um widget CONTROLADO (veja o exemplo 11): o valor pertence ao
// formulário pai; didUpdateWidget copia para o campo um valor que
// o pai alterou por conta própria. label, help e error são CHAVES
// de tradução; params, os parâmetros de suas mensagens ({{min}}...).
// =========================================================================

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

import '../i18n/translations.dart';

class InputField extends StatefulWidget {
  final String label;
  final String value;
  final ValueChanged<String> onChanged;
  final String? error;
  final String? help;
  final Map<String, String> params;
  final bool secret; // uma senha: caracteres ocultos
  final int? maxLength;
  final bool autofocus;
  final Iterable<String>? autofill; // para o gerenciador de senhas do celular

  const InputField({
    super.key,
    required this.label,
    required this.value,
    required this.onChanged,
    this.error,
    this.help,
    this.params = const {},
    this.secret = false,
    this.maxLength,
    this.autofocus = false,
    this.autofill,
  });

  @override
  State<InputField> createState() => _InputFieldState();
}

class _InputFieldState extends State<InputField> {
  late final _controller = TextEditingController(text: widget.value);

  @override
  void didUpdateWidget(InputField old) {
    super.didUpdateWidget(old);
    if (widget.value != _controller.text) _controller.text = widget.value;
  }

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

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    final error = widget.error;
    return Padding(
      padding: const EdgeInsets.only(bottom: 8),
      child: TextField(
        controller: _controller,
        obscureText: widget.secret,
        autocorrect: !widget.secret,
        autofocus: widget.autofocus,
        maxLength: widget.maxLength,
        autofillHints: widget.autofill,
        decoration: InputDecoration(
          labelText: t(widget.label),
          errorText: error == null ? null : t(error, widget.params),
          helperText: widget.help == null ? null : t(widget.help!, widget.params),
          helperMaxLines: 2,
          errorMaxLines: 3,
          counterText: '', // sem contador "0/20" sob o campo
        ),
        onChanged: widget.onChanged,
      ),
    );
  }
}

Um campo de formulário completo: rótulo, campo, texto de ajuda ou mensagem de erro. Todos os formulários o utilizam.

  • linhas 22–32: os parâmetros. O rótulo, o texto de ajuda e a mensagem de erro são CHAVES de tradução;
  • linhas 53–58: um widget controlado (exemplo 11): o valor pertence ao pai. Se o pai o altera por conta própria (o CAPTCHA apagado após uma falha), [didUpdateWidget] o copia de volta para o campo;
  • linhas 75–79: uma senha é mascarada, e o corretor ortográfico não interfere; [autofillHints] informa ao gerenciador de senhas do celular o que o campo contém (um nome de usuário, uma senha, uma nova senha);
  • linhas 80–86: o rótulo, a mensagem de erro (que substitui o texto de ajuda) e o texto de ajuda. [maxLength] limita a entrada e exibiria um contador (“3/20”) abaixo do campo; [counterText: ''] o oculta.

11.12.5. lib/widgets/person_fields.dart

// =========================================================================
// lib/widgets/person_fields.dart - título, nome, sobrenome
// -------------------------------------------------------------------------
// Os campos de identidade, comuns a três formulários: o formulário de médico / cliente
// do ADMIN, "Create a patient account" e "Manage my account". O pai
// lhe passa os valores, os erros, e a função que altera um campo:
//     PersonFields(values: _input, errors: _submit.errors, onChanged: _edit)
// =========================================================================

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

import '../i18n/translations.dart';
import 'input_field.dart';

const titles = ['Mr', 'Mme', 'Melle'];

class PersonFields extends StatelessWidget {
  final Map<String, Object?> values;
  final Map<String, String> errors;
  final void Function(String field, String value) onChanged;

  const PersonFields({super.key, required this.values, required this.errors, required this.onChanged});

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    final titleError = errors['title'];
    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        // DropdownButtonFormField: uma lista suspensa com rótulo e erro
        DropdownButtonFormField<String>(
          // key: se o valor for alterado pelo código, o campo é recriado com ele
          key: ValueKey(values['title']),
          initialValue: values['title'] as String,
          decoration: InputDecoration(
            labelText: t('PERSONS.TITLE_LABEL'),
            errorText: titleError == null ? null : t(titleError),
          ),
          items: [for (final title in titles) DropdownMenuItem(value: title, child: Text(title))],
          onChanged: (title) => onChanged('title', title!),
        ),
        const SizedBox(height: 8),
        InputField(
          label: 'PERSONS.FIRSTNAME_LABEL',
          maxLength: 20,
          value: values['firstName'] as String,
          onChanged: (v) => onChanged('firstName', v),
          error: errors['firstName'],
        ),
        InputField(
          label: 'PERSONS.LASTNAME_LABEL',
          maxLength: 20,
          value: values['lastName'] as String,
          onChanged: (v) => onChanged('lastName', v),
          error: errors['lastName'],
        ),
      ],
    );
  }
}

Os campos de identidade (título, nome, sobrenome), comuns aos formulários de ADMIN, ao formulário de criação de conta e ao formulário “Gerenciar minha conta”.

  • Linha 21: o pai passa os valores, os erros e UMA função para modificar qualquer campo;
  • Linhas 33–42: o título, em uma lista suspensa, com rótulo e mensagem de erro, como um campo de entrada. [initialValue] só é lido quando o campo é criado; a chave ([ValueKey]) o recria se o valor mudar por meio de código.

11.12.6. lib/widgets/captcha_field.dart

// =========================================================================
// lib/widgets/captcha_field.dart - a imagem do captcha e o campo de entrada
// -------------------------------------------------------------------------
// Um widget de exibição: a imagem (svg), o botão "Another image"
// (onReload), e o campo, CONTROLADO pelo formulário pai (value,
// onChanged). A imagem e seu identificador são solicitados ao servidor pela
// página de login, que precisa deles para enviar a resposta.
// =========================================================================

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

import '../i18n/translations.dart';
import 'input_field.dart';

class CaptchaField extends StatelessWidget {
  final String? svg;
  final String value;
  final ValueChanged<String> onChanged;
  final VoidCallback onReload;
  final String? error;

  const CaptchaField({
    super.key,
    required this.svg,
    required this.value,
    required this.onChanged,
    required this.onReload,
    this.error,
  });

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text(t('CAPTCHA.LABEL'), style: Theme.of(context).textTheme.bodySmall),
        Row(
          children: [
            Container(
              height: 54,
              width: 160,
              decoration: BoxDecoration(
                color: const Color(0xFFF5F7FA),
                border: Border.all(color: Colors.grey.shade300),
                borderRadius: BorderRadius.circular(6),
              ),
              // Semantics: o que um leitor de tela lê no lugar da imagem
              child: svg == null
                  ? null
                  : Semantics(
                      label: t('CAPTCHA.IMAGE_ALT'),
                      child: SvgPicture.string(svg!, fit: BoxFit.contain),
                    ),
            ),
            TextButton.icon(
              onPressed: onReload,
              icon: const Icon(Icons.refresh),
              label: Text(t('CAPTCHA.NEW_IMAGE')),
            ),
          ],
        ),
        InputField(
          label: 'CAPTCHA.LABEL',
          help: 'CAPTCHA.HELP',
          maxLength: 10,
          value: value,
          onChanged: onChanged,
          error: error,
        ),
      ],
    );
  }
}

A imagem do CAPTCHA, o botão “Outra imagem” e o campo. O widget não chama o servidor: a tela de login solicita a imagem porque precisa do identificador dela para enviar a resposta.

  • Linhas 51–53: a imagem SVG, recebida como texto ([SvgPicture.string], exemplo 22). [Semantics]: o que um leitor de tela lê ([TalkBack] do [Android]) no lugar da imagem.

11.12.7. lib/widgets/confirmation.dart

// =========================================================================
// lib/widgets/confirmation.dart - "Are you sure?"
// -------------------------------------------------------------------------
// Extraído do exemplo 16. A mensagem é uma CHAVE de tradução:
//     if (await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) { ... }
// "No, go back" em vez de "Cancel": a pergunta às vezes é "Cancel this
// appointment?", e um botão "Cancel" seria ambíguo ali. O foco está em
// "No": um toque distraído em Enter não exclui nada.
// Uma nova pergunta apaga as mensagens da ação anterior.
// =========================================================================

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

import '../state/messages.dart';
import '../i18n/translations.dart';

Future<bool> confirm(BuildContext context, String key) async {
  context.read<Messages>().clear();
  final t = context.read<Translations>().t;
  final yes = await showDialog<bool>(
    context: context,
    builder: (context) => AlertDialog(
      title: Text(t('CONFIRMATION.TITLE')),
      content: Text(t(key)),
      actions: [
        TextButton(autofocus: true, onPressed: () => Navigator.pop(context, false), child: Text(t('CONFIRMATION.NO'))),
        FilledButton(
          style: FilledButton.styleFrom(backgroundColor: Colors.red.shade700),
          onPressed: () => Navigator.pop(context, true),
          child: Text(t('CONFIRMATION.YES')),
        ),
      ],
    ),
  );
  return yes ?? false;
}

A janela de confirmação do exemplo 16, traduzida: [if (await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) ...]. O foco fica em “Não” ([autofocus]): na web, pressionar Enter por acidente não exclui nada.

11.12.8. lib/widgets/booking_dialog.dart

// =========================================================================
// lib/widgets/booking_dialog.dart - o diálogo de marcação de um horário
// -------------------------------------------------------------------------
// Uma janela sobre a agenda, fundo cinza incluído. Ela NÃO é
// aberta por showDialog: faz parte da tela da agenda, que
// a exibe quando o seu ENDEREÇO a pede (/schedule?...&book=7, veja
// pages/schedule.dart). O endereço descreve assim a tela inteira, diálogo incluído.
//
// O widget não conversa com o servidor: ele chama
//   - onConfirm, com o paciente escolhido (null para um paciente que marca
//     para si mesmo);
//   - onClose.
// É a tela da agenda que decide o que fazer com eles.
// =========================================================================

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

import '../api/types.dart';
import '../i18n/translations.dart';

class BookingDialog extends StatefulWidget {
  final String time; // "8:00 - 8:20"
  final List<Person> clients; // ADMIN / DOCTOR: os pacientes entre os quais escolher
  final String? patient; // USER: o paciente é o próprio usuário
  final bool submitting;
  final ValueChanged<int?> onConfirm;
  final VoidCallback onClose;

  const BookingDialog({
    super.key,
    required this.time,
    required this.clients,
    required this.patient,
    required this.submitting,
    required this.onConfirm,
    required this.onClose,
  });

  @override
  State<BookingDialog> createState() => _BookingDialogState();
}

class _BookingDialogState extends State<BookingDialog> {
  int? _clientId;

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    final patient = widget.patient;
    return Stack(
      children: [
        // ModalBarrier: o fundo cinza; tocar nele fecha o diálogo
        ModalBarrier(color: Colors.black54, onDismiss: widget.onClose),
        Center(
          child: Card(
            margin: const EdgeInsets.all(24),
            child: Padding(
              padding: const EdgeInsets.all(20),
              child: Column(
                mainAxisSize: MainAxisSize.min,
                crossAxisAlignment: CrossAxisAlignment.stretch,
                children: [
                  Text(t('BOOKING_DIALOG.TITLE'), style: Theme.of(context).textTheme.titleLarge),
                  const SizedBox(height: 12),
                  Text(t('BOOKING_DIALOG.SLOT', {'time': widget.time})),
                  const SizedBox(height: 12),
                  // um paciente marca para si mesmo: sem lista (e o servidor
                  // ignoraria de qualquer forma um eventual clientId)
                  if (patient != null)
                    Text.rich(
                      TextSpan(
                        children: [
                          TextSpan(text: '${t('BOOKING_DIALOG.PATIENT_LABEL')}: '),
                          TextSpan(
                            text: patient,
                            style: const TextStyle(fontWeight: FontWeight.bold),
                          ),
                        ],
                      ),
                    )
                  else
                    DropdownButtonFormField<int?>(
                      initialValue: _clientId,
                      isExpanded: true,
                      decoration: InputDecoration(labelText: t('BOOKING_DIALOG.PATIENT_LABEL')),
                      items: [
                        DropdownMenuItem(value: null, child: Text(t('BOOKING_DIALOG.CHOOSE_PATIENT'))),
                        for (final c in widget.clients) DropdownMenuItem(value: c.id, child: Text(c.label)),
                      ],
                      onChanged: (id) => setState(() => _clientId = id),
                    ),
                  const SizedBox(height: 20),
                  // OverflowBar: os botões lado a lado, um sob o outro se não couberem
                  OverflowBar(
                    alignment: MainAxisAlignment.end,
                    spacing: 8,
                    children: [
                      TextButton(onPressed: widget.onClose, child: Text(t('BOOKING_DIALOG.CANCEL'))),
                      FilledButton(
                        onPressed: widget.submitting ? null : () => widget.onConfirm(_clientId),
                        child: Text(t('BOOKING_DIALOG.CONFIRM')),
                      ),
                    ],
                  ),
                ],
              ),
            ),
          ),
        ),
      ],
    );
  }
}

A janela de reserva de horário. Ela NÃO é aberta por [showDialog]: faz parte da tela da agenda, que a exibe quando seu endereço a solicita ([&book=7]).

  • Linhas 23–28: o widget não se comunica com o servidor; ele recebe os dados que exibe, além de duas funções chamadas para confirmar (com o paciente selecionado) ou fechar;
  • linhas 51–54: um [Stack] sobrepõe seus filhos: primeiro, uma [ModalBarrier], com fundo acinzentado, que cobre a tela inteira e bloqueia os toques destinados à agenda (tocar fecha a janela), seguida da própria janela, centralizada;
  • linhas 70–91: um paciente faz a reserva para si mesmo: seu nome, sem lista. O ADMIN ou o médico seleciona o paciente em uma lista suspensa; a seleção determina o estado da janela;
  • linhas 95–102: os botões ([OverflowBar]: lado a lado ou um embaixo do outro, se não couberem); “Confirmar” fica desabilitado durante o envio.

11.13. As telas

11.13.1. lib/pages/login.dart

// =========================================================================
// lib/pages/login.dart - a tela de login (/login)
// -------------------------------------------------------------------------
// Mesma tela dos outros clientes: login, senha, captcha, e
// um segundo botão "Create a patient account" que verifica o MESMO captcha
// antes de abrir a criação de conta.
//
// /login?login=jbernard: o campo login vem preenchido (logo após a
// criação de uma conta).
// Após um login bem-sucedido, esta tela NÃO navega sozinha: a
// sessão muda, e é o roteador que sai da tela de login
// (para /login?redirect=... ou a página inicial do papel, veja router.dart).
// =========================================================================

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

import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/messages.dart';
import '../state/session.dart';
import '../i18n/translations.dart';
import '../widgets/captcha_field.dart';
import '../widgets/input_field.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';

class LoginPage extends StatefulWidget {
  final String login; // o login do endereço (?login=...)

  const LoginPage({super.key, this.login = ''});

  @override
  State<LoginPage> createState() => _LoginPageState();
}

class _LoginPageState extends State<LoginPage> {
  late final _api = context.read<RdvMedecinsApi>();
  late final _messages = context.read<Messages>();
  late final _submit = FormSubmit(_messages);
  late final Map<String, String> _input = {'login': widget.login, 'password': '', 'captcha': ''};
  Captcha? _captcha;

  @override
  void initState() {
    super.initState();
    _reloadCaptcha();
  }

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

  // uma nova imagem: ela é necessária após CADA tentativa, porque uma imagem só pode
  // ser usada UMA vez (o servidor a esquece assim que a verificou)
  Future<void> _reloadCaptcha() async {
    Captcha? captcha;
    try {
      captcha = await _api.captcha();
    } catch (_) {
      captcha = null; // servidor inacessível: o login falhará com uma mensagem clara
    }
    if (mounted) setState(() => _captcha = captcha);
  }

  void _edit(String field, String value) {
    setState(() => _input[field] = value);
    _submit.clearError(field);
  }

  // os dois botões compartilham este fluxo: envio e, em caso de falha,
  // mensagem de erro e uma NOVA imagem
  Future<void> _attempt(Future<void> Function() action) async {
    _messages.clear();
    final succeeded = await _submit.submit(action);
    if (!succeeded && mounted) {
      setState(() => _input['captcha'] = '');
      await _reloadCaptcha();
    }
  }

  // em caso de sucesso, nada mais a fazer aqui: o roteador muda a tela
  Future<void> _logIn() => _attempt(
    () => context.read<Session>().logIn(
      _input['login']!.trim(),
      _input['password']!,
      _captcha?.id ?? '',
      _input['captcha']!,
    ),
  );

  Future<void> _createAccount() => _attempt(() async {
    await _api.registrationAccess(_captcha?.id ?? '', _input['captcha']!);
    if (mounted) context.go('/register');
  });

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    return PageTitle(
      titleKey: 'LOGIN.TITLE',
      child: ListenableBuilder(
        listenable: _submit,
        builder: (context, _) => ListView(
          padding: const EdgeInsets.all(16),
          children: [
            Text(t('LOGIN.TITLE'), style: Theme.of(context).textTheme.headlineSmall),
            const SizedBox(height: 12),
            // AutofillGroup: o gerenciador de senhas do celular pode preencher o formulário
            AutofillGroup(
              child: Column(
                children: [
                  InputField(
                    label: 'LOGIN.LOGIN_LABEL',
                    value: _input['login']!,
                    onChanged: (v) => _edit('login', v),
                    error: _submit.errors['login'],
                    autofill: const [AutofillHints.username],
                  ),
                  InputField(
                    label: 'LOGIN.PASSWORD_LABEL',
                    secret: true,
                    value: _input['password']!,
                    onChanged: (v) => _edit('password', v),
                    error: _submit.errors['password'],
                    autofill: const [AutofillHints.password],
                  ),
                ],
              ),
            ),
            CaptchaField(
              svg: _captcha?.svg,
              value: _input['captcha']!,
              onChanged: (v) => _edit('captcha', v),
              onReload: _reloadCaptcha,
              error: _submit.errors['captcha'],
            ),
            const SizedBox(height: 8),
            FilledButton(onPressed: _submit.submitting ? null : _logIn, child: Text(t('LOGIN.SUBMIT'))),
            const SizedBox(height: 12),
            OutlinedButton(onPressed: _submit.submitting ? null : _createAccount, child: Text(t('LOGIN.CREATE_ACCOUNT'))),
            Padding(
              padding: const EdgeInsets.only(top: 4),
              child: Text(
                t('LOGIN.CREATE_ACCOUNT_HELP'),
                textAlign: TextAlign.center,
                style: Theme.of(context).textTheme.bodySmall,
              ),
            ),
            const SizedBox(height: 16),
            _DemoAccounts(t: t),
          ],
        ),
      ),
    );
  }
}

// as contas de demonstração
class _DemoAccounts extends StatelessWidget {
  final String Function(String, [Map<String, Object?>]) t;

  const _DemoAccounts({required this.t});

  @override
  Widget build(BuildContext context) {
    const code = TextStyle(fontFamily: 'RobotoMono', fontSize: 12);
    final style = Theme.of(context).textTheme.bodySmall!.copyWith(color: Colors.grey.shade700);
    return DefaultTextStyle(
      style: style,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(t('LOGIN.DEMO_ACCOUNTS')),
          for (final (accounts, roleKey) in [
            ('admin', 'LOGIN.DEMO_ADMIN'),
            ('pelissier, tatou, dupont', 'LOGIN.DEMO_DOCTOR'),
            ('martin, durand, bistrou, german', 'LOGIN.DEMO_USER'),
          ])
            Text.rich(
              TextSpan(
                children: [
                  const TextSpan(text: '• '),
                  TextSpan(text: accounts, style: code),
                  TextSpan(text: ' - ${t(roleKey)}'),
                ],
              ),
            ),
        ],
      ),
    );
  }
}

A tela de login.

  • Linhas 39–43: estado: a camada de acesso à API e as mensagens (lidas UMA vez, [late]: no primeiro uso), o envio do formulário, a entrada de dados (um [Map]: nome do campo -> valor) e o CAPTCHA recebido;
  • linhas 59–66: uma nova imagem, quando a tela é aberta, sob demanda e após CADA tentativa (uma imagem é usada uma única vez);
  • linhas 76–81: os dois botões seguem esta sequência: envio e, em caso de falha, o CAPTCHA é apagado e uma nova imagem é exibida;
  • linhas 86–93: login. Se for bem-sucedido, a tela não faz mais nada: a sessão muda, e o roteador, que a está escutando, sai da tela de login (veja [router.dart]);
  • linhas 95–97: “Criar uma conta de paciente”: o servidor verifica o CAPTCHA e emite um token (um cookie); a tela de criação de conta é então aberta;
  • linhas 105–106: a tela é recarregada quando o estado do envio muda (em andamento, erros);
  • linhas 113–129: [AutofillGroup] agrupa o nome de usuário e a senha: o gerenciador de senhas do celular os preenche juntos e se oferece para salvar a conta após o login;
  • linhas 163–195: contas de demonstração. [for (final (accounts, roleKey) in [...])]: um laço sobre uma lista de records, que são desestruturados no processo (exemplo 03).

11.13.2. lib/pages/schedule.dart

  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
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
// =========================================================================
// lib/pages/schedule.dart - a tela da agenda (/schedule)
// -------------------------------------------------------------------------
// Três blocos, como nos outros clientes:
//   1. a escolha do médico e do dia;
//   2. a agenda deste médico neste dia;
//   3. o diálogo de marcação de um horário.
//
// TODO o estado da tela está em seu ENDEREÇO:
//     /schedule?doctorId=1&day=2026-10-05             a agenda
//     /schedule?doctorId=1&day=2026-10-05&book=7      + o diálogo de marcação
// O roteador passa estes três parâmetros ao widget; a tela DEDUZ
// deles o que exibe, e as ações do usuário mudam o endereço
// (context.go, context.push). Na web, podemos portanto recarregar a página,
// salvá-la nos favoritos, usar Voltar / Avançar; no celular, o
// botão Voltar fecha o diálogo de marcação.
//
// O que cada um vê e pode fazer é decidido pelo SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada horário): a tela apenas
// exibe isso. Um paciente nem sequer recebe o nome dos outros pacientes.
// =========================================================================

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

import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../state/session.dart';
import '../formatting.dart';
import '../i18n/translations.dart';
import '../widgets/confirmation.dart';
import '../widgets/booking_dialog.dart';
import '../widgets/page_title.dart';

// o endereço da agenda (sem diálogo de marcação, ou com)
String scheduleAddress(int? doctorId, String day, [int? book]) => Uri(
  path: '/schedule',
  queryParameters: {'doctorId': '${doctorId ?? ''}', 'day': day, 'book': ?book?.toString()},
).toString();

class SchedulePage extends StatefulWidget {
  final int? doctorId;
  final String? day; // como está no endereço: talvez inválido
  final int? book;

  const SchedulePage({super.key, this.doctorId, this.day, this.book});

  @override
  State<SchedulePage> createState() => _SchedulePageState();
}

class _SchedulePageState extends State<SchedulePage> {
  late final _api = context.read<RdvMedecinsApi>();
  late final _cache = context.read<Cache>();
  late final _messages = context.read<Messages>();
  Future<List<Person>>? _doctors;
  List<Person> _clients = [];
  Future<Schedule>? _schedule;
  bool _submitting = false;

  // o dia: o do endereço se for válido, caso contrário hoje
  bool get _invalidDay => widget.day != null && !isValidDate(widget.day!);
  String get _day => widget.day != null && !_invalidDay ? widget.day! : today();

  @override
  void initState() {
    super.initState();
    final user = context.read<Session>().user;
    _doctors = _cache.read('doctors', () => _api.list(PersonType.doctors));
    // os pacientes: somente para quem tem permissão para lê-los (diálogo de marcação)
    if (user.isManager) {
      _cache.read('clients', () => _api.list(PersonType.clients)).then((c) {
        if (mounted) setState(() => _clients = c);
      }, onError: _messages.showApiError);
    }
    if (_invalidDay) {
      // depois que a tela é construída: não alteramos outro estado durante um build
      WidgetsBinding.instance.addPostFrameCallback((_) => _messages.showError('ERRORS.INVALID_DATE'));
    }
    _loadSchedule();
    // dados invalidados (marcação, cancelamento): lemos a agenda de novo.
    // Útil sobretudo para a tela escondida SOB o diálogo de marcação (veja _confirmBooking)
    _cache.addListener(_loadSchedule);
  }

  @override
  void dispose() {
    _cache.removeListener(_loadSchedule);
    super.dispose();
  }

  // o roteador reutiliza a tela com outro endereço (outro médico, outro dia)
  @override
  void didUpdateWidget(SchedulePage old) {
    super.didUpdateWidget(old);
    if (old.doctorId != widget.doctorId || old.day != widget.day) _loadSchedule();
  }

  void _loadSchedule() {
    final user = context.read<Session>().user;
    // sem médico no endereço, um DOCTOR vê a SUA agenda (o servidor a
    // encontra a partir do token); os demais não veem nada
    final withSchedule = !_invalidDay && (widget.doctorId != null || user?.role == Role.doctor);
    setState(() {
      _schedule = withSchedule
          ? _cache.read('schedule/${widget.doctorId}/$_day', () => _api.schedule(widget.doctorId, _day))
          : null;
    });
    // uma leitura que falhou: sua mensagem, na parte inferior da tela
    _schedule?.then((_) {}, onError: (Object e) => _messages.showApiError(e));
  }

  // o servidor é a referência: após cada ação, lemos a agenda de novo
  // (e a área do paciente, que mostra a sua consulta). A invalidação
  // notifica todas as telas de agenda vivas, inclusive esta (_loadSchedule)
  void _reload() {
    _cache.invalidate('my-area');
    _cache.invalidate('schedule');
  }

  void _closeBooking(int? doctorId) {
    if (context.canPop()) {
      context.pop();
    } else {
      context.go(scheduleAddress(doctorId, _day));
    }
  }

  Future<void> _confirmBooking(ScheduleSlot slot, int? doctorId, int? clientId) async {
    final manager = context.read<Session>().user.isManager;
    setState(() => _submitting = true);
    try {
      await _api.book(_day, slot.id, manager ? clientId : null);
      _messages.flash(key: 'SCHEDULE.BOOKED');
    } on ApiError catch (e) {
      if (e.key == 'ERRORS.CHOOSE_PATIENT') {
        // nenhum paciente escolhido: o diálogo permanece aberto
        _messages.showError(e.key);
        return; // (o finally executa mesmo assim)
      }
      // horário ocupado nesse meio tempo, paciente que já tem uma consulta...: a
      // mensagem será exibida na agenda, com o diálogo fechado
      _messages.flash(success: false, key: e.key, params: e.params);
    } finally {
      if (mounted) setState(() => _submitting = false);
    }
    if (!mounted) return;
    _closeBooking(doctorId);
    _reload();
  }

  Future<void> _cancel(ScheduleSlot s) async {
    if (s.appointmentId == null || !await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) return;
    try {
      await _api.cancelAppointment(s.appointmentId!);
      _messages.showSuccess('SCHEDULE.CANCELLED');
    } on ApiError catch (e) {
      _messages.showApiError(e);
    }
    if (mounted) _reload();
  }

  @override
  Widget build(BuildContext context) {
    final translations = context.watch<Translations>();
    final t = translations.t;
    final user = context.watch<Session>().user;

    return PageTitle(
      titleKey: 'SCHEDULE.PAGE_TITLE',
      // FutureBuilder: a agenda (null enquanto não chegou, ou se não há nenhuma)
      child: FutureBuilder<Schedule>(
        future: _schedule,
        builder: (context, state) {
          final s = state.data;
          // o médico exibido: o do endereço, ou o da agenda recebida (DOCTOR)
          final doctorId = widget.doctorId ?? s?.doctor.id;
          // o horário cujo diálogo de marcação está aberto (&book=7),
          // somente se puder ser marcado por este usuário
          final toBook = s?.slots.where((c) => c.id == widget.book && c.bookable).firstOrNull;
          // a mensagem do servidor ao paciente que já tem uma consulta futura
          // ("cancel it to book another one") não explica nada se ESTA
          // consulta estiver na agenda exibida: nós a vemos, sob o seu nome,
          // com o seu botão "Cancel". Ela só é exibida nas OUTRAS agendas
          final info = s != null && !s.slots.any((c) => c.mine) ? s.info : null;

          final Widget content;
          if (state.connectionState == ConnectionState.waiting) {
            content = const Padding(
              padding: EdgeInsets.all(24),
              child: Center(child: CircularProgressIndicator()),
            );
          } else if (s != null) {
            content = _Schedule(
              schedule: s,
              language: translations.language,
              onBook: (c) => context.push(scheduleAddress(doctorId, _day, c.id)),
              onCancel: _cancel,
            );
          } else {
            content = Padding(padding: const EdgeInsets.all(16), child: Text(t('SCHEDULE.EMPTY_STATE')));
          }

          return Stack(
            children: [
              ListView(
                padding: const EdgeInsets.all(12),
                children: [
                  // 1. a escolha do médico e do dia. Sua key muda com o endereço:
                  // o Flutter então a recria, e ela recomeça a partir dos novos valores
                  FutureBuilder<List<Person>>(
                    future: _doctors,
                    builder: (context, doctors) => _DoctorDayPicker(
                      key: ValueKey('$doctorId|$_day'),
                      doctors: doctors.data ?? const [],
                      doctorId: doctorId,
                      day: _day,
                      onView: (id, day) => context.go(scheduleAddress(id, day)),
                    ),
                  ),
                  // paciente que já tem uma consulta futura: por que não há botão "Book"
                  if (info != null)
                    Card(
                      color: Colors.lightBlue.shade50,
                      child: ListTile(
                        title: Text(t(info)),
                        trailing: TextButton(
                          onPressed: () => context.go('/my-area'),
                          child: Text(t('APP.MENU_MY_AREA')),
                        ),
                      ),
                    ),
                  content,
                ],
              ),
              // 3. o diálogo de marcação, somente se o endereço contiver &book=...
              if (toBook != null)
                BookingDialog(
                  time: timeRange(toBook),
                  clients: _clients,
                  patient: user.isPatient ? user!.name : null,
                  submitting: _submitting,
                  onConfirm: (clientId) => _confirmBooking(toBook, doctorId, clientId),
                  onClose: () => _closeBooking(doctorId),
                ),
            ],
          );
        },
      ),
    );
  }
}

// -------------------------------------------------------------------------
// 1. a escolha do médico e do dia: um pequeno formulário, cujo estado só
// é útil antes do envio. Ele COMEÇA com os valores do endereço.
// -------------------------------------------------------------------------
class _DoctorDayPicker extends StatefulWidget {
  final List<Person> doctors;
  final int? doctorId;
  final String day;
  final void Function(int? doctorId, String day) onView;

  const _DoctorDayPicker({
    super.key,
    required this.doctors,
    required this.doctorId,
    required this.day,
    required this.onView,
  });

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

class _DoctorDayPickerState extends State<_DoctorDayPicker> {
  late int? _doctorId = widget.doctorId;
  late String _day = widget.day;

  Future<void> _pickDay() async {
    final choice = await showDatePicker(
      context: context,
      initialDate: DateTime.parse(_day),
      firstDate: DateTime(2020),
      lastDate: DateTime(2035, 12, 31),
    );
    if (choice != null) setState(() => _day = toDay(choice));
  }

  @override
  Widget build(BuildContext context) {
    final translations = context.watch<Translations>();
    final t = translations.t;
    // o médico escolhido deve estar na lista (caso contrário: nenhum)
    final knownId = widget.doctors.any((d) => d.id == _doctorId) ? _doctorId : null;
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            DropdownButtonFormField<int?>(
              key: ValueKey('${widget.doctors.length}/$knownId'),
              initialValue: knownId,
              isExpanded: true,
              decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')),
              items: [
                DropdownMenuItem(value: null, child: Text(t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR'))),
                for (final d in widget.doctors) DropdownMenuItem(value: d.id, child: Text(d.label)),
              ],
              onChanged: (id) => setState(() => _doctorId = id),
            ),
            const SizedBox(height: 8),
            // o dia: um botão que abre o calendário
            InputDecorator(
              decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DAY_LABEL')),
              child: InkWell(
                onTap: _pickDay,
                child: Row(
                  children: [
                    Expanded(child: Text(longDate(_day, translations.language))),
                    const Icon(Icons.calendar_month),
                  ],
                ),
              ),
            ),
            const SizedBox(height: 12),
            FilledButton(
              onPressed: knownId == null ? null : () => widget.onView(knownId, _day),
              child: Text(t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')),
            ),
          ],
        ),
      ),
    );
  }
}

// -------------------------------------------------------------------------
// 2. a agenda
// -------------------------------------------------------------------------
class _Schedule extends StatelessWidget {
  final Schedule schedule;
  final String language;
  final ValueChanged<ScheduleSlot> onBook;
  final ValueChanged<ScheduleSlot> onCancel;

  const _Schedule({required this.schedule, required this.language, required this.onBook, required this.onCancel});

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    final s = schedule;
    return Card(
      child: Padding(
        padding: const EdgeInsets.symmetric(vertical: 8),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            ListTile(
              title: Text(
                '${t('SCHEDULE.TITLE_PREFIX')} ${longDate(s.day, language)}',
                style: Theme.of(context).textTheme.titleMedium,
              ),
              subtitle: Text(s.doctor.label),
            ),
            if (s.slots.isEmpty) Padding(padding: const EdgeInsets.all(16), child: Text(t('SCHEDULE.NO_SLOTS'))),
            for (final c in s.slots) ...[
              const Divider(height: 1),
              ListTile(
                // os horários disponíveis têm uma leve coloração
                tileColor: c.bookable ? Colors.green.shade50 : null,
                leading: SizedBox(
                  width: 96,
                  child: Text(timeRange(c), style: const TextStyle(fontWeight: FontWeight.w500)),
                ),
                title: Align(
                  alignment: Alignment.centerLeft,
                  child: c.free
                      ? _Badge(t('SCHEDULE.FREE'), Colors.green.shade700)
                      : c.patient != null
                      ? _Badge(c.patient!.label, c.mine ? Colors.indigo : Colors.grey.shade600)
                      : _Badge(t('SCHEDULE.BOOKED_BY_OTHER'), Colors.grey.shade600),
                ),
                // "Book" muda o ENDEREÇO (&book=...), o que abre o diálogo de marcação
                trailing: c.bookable
                    ? OutlinedButton(onPressed: () => onBook(c), child: Text(t('SCHEDULE.BOOK')))
                    : c.appointmentId != null
                    ? OutlinedButton(
                        style: OutlinedButton.styleFrom(foregroundColor: Colors.red.shade700),
                        onPressed: () => onCancel(c),
                        child: Text(t('SCHEDULE.CANCEL_APPOINTMENT')),
                      )
                    : null,
              ),
            ],
          ],
        ),
      ),
    );
  }
}

// um rótulo colorido (o "badge" dos outros clientes)
class _Badge extends StatelessWidget {
  final String text;
  final Color color;

  const _Badge(this.text, this.color);

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 3),
      decoration: BoxDecoration(color: color, borderRadius: BorderRadius.circular(6)),
      child: Text(
        text,
        style: const TextStyle(color: Colors.white, fontSize: 12, fontWeight: FontWeight.bold),
      ),
    );
  }
}

A tela mais rica em funcionalidades: seleção de um médico e de um dia, a agenda e a janela de reserva.

  • linhas 40–43: o endereço da agenda. O estado INTEIRO da tela está contido em seu endereço; as ações do usuário o alteram, e a tela determina o que exibir com base nele;
  • Linhas 66–67: o dia do endereço, se for válido; caso contrário, hoje;
  • linhas 70–87: quando a tela é aberta: os médicos (vindos do cache, pois são carregados uma única vez para toda a sessão), os pacientes se o usuário tiver permissão para vê-los (para a janela de reserva) e a agenda. Se a data do endereço for inválida: uma mensagem é exibida DEPOIS que a tela é construída ([addPostFrameCallback]: outro estado não é modificado durante a construção da tela). Por fim, a tela lê do cache;
  • linhas 98–100: “Ver agenda” muda o endereço; o roteador REAPROVEITA a tela (mesma rota) com novos parâmetros: [didUpdateWidget] então lê a agenda novamente;
  • linhas 103–114: o cache lê a agenda. Se não houver médico indicado no endereço, um médico conectado vê a SUA agenda (o servidor a recupera por meio do token);
  • linhas 120–122: após uma reserva ou um cancelamento, os dados do servidor prevalecem: a agenda (e a área do paciente) é invalidada; o cache notifica as telas de agenda, que recarregam;
  • linhas 125–129: fechar a janela: voltar para a URL anterior. “Reservar” EMPILHOU a URL com [&book=] ([context.push]): ela é desempilhada ([context.pop]), exatamente como faz o botão Voltar do celular. Se a tela foi aberta diretamente nesse endereço (na web), não há nada a desempilhar: vai-se para o endereço da agenda;
  • linhas 133–153: a reserva da consulta. Se nenhum paciente estiver selecionado, a janela permanece aberta, exibindo a mensagem. Qualquer outra ação fecha a janela, e a mensagem (de sucesso ou de erro, como um horário ocupado nesse meio-tempo...) aparece como mensagem pop-up para a agenda. A tela de agenda que continha a janela desaparece; a que estava por baixo reaparece, graças ao cache;
  • linhas 156–164: o cancelamento, após confirmação;
  • linhas 176–184: a tela exibe a agenda ([FutureBuilder]). O horário da janela de reserva é o do endereço ([&book=7]), somente se puder ser reservado POR ESTE USUÁRIO (um horário ocupado nesse meio-tempo, um endereço criado manualmente: sem janela);
  • linha 189: o servidor envia esta mensagem ([info]) junto com TODAS as agendas; mas, na agenda que contém a consulta do paciente (um horário [mine]), ela é desnecessária e até enganosa logo após uma reserva: o paciente vê sua consulta, listada sob o seu nome, com um botão “Cancelar”. Por isso, ela só é exibida nas outras agendas. [s.slots.any((c) => c.mine)]: verdadeiro se pelo menos um horário atender à condição;
  • linhas 201–202: “Reservar” empilha o endereço da janela;
  • linhas 215–222: seleção do médico e do dia. Sua chave contém o médico e o dia da URL: quando a URL muda (o botão Voltar do celular, o botão Voltar do navegador), o [Flutter] recria o widget, que recomeça com os novos valores;
  • linhas 226–233: um paciente que já tem uma consulta futura: por que não há botão “Reservar” (veja [info], acima);
  • linhas 241–248: a janela de reserva, acima da agenda (em [Stack]);
  • Linhas 280–291: seleção do médico e do dia: um formulário curto, cujo estado COMEÇA com os valores do endereço. [late int? _doctorId = widget.doctorId;]: um campo inicializado a partir do [widget], possível graças a [late]. [showDatePicker] abre o calendário do [Material] no idioma da aplicação;
  • linhas 319–326: o dia é exibido como um campo de entrada ([InputDecorator]: o rótulo e a borda de um campo, envolvendo qualquer widget), em que você toca para abrir o calendário;
  • linhas 346–406: a agenda. Uma linha por horário: o horário, um rótulo (texto personalizado, o nome do paciente ou “Reservado” para outro paciente) e o botão habilitado pelo SERVIDOR ([bookable], [appointmentId]).

11.13.3. lib/pages/persons_config.dart

// =========================================================================
// lib/pages/persons_config.dart - médicos ou clientes?
// -------------------------------------------------------------------------
// As telas de gestão dos médicos e dos clientes são IDÊNTICAS: mesma
// lista, mesmo formulário. Nós as escrevemos UMA vez (persons.dart,
// person_form.dart); só o endereço da API e as
// chaves dos rótulos mudam, descritos aqui. O roteador passa o tipo a cada tela.
// =========================================================================

import '../api/rdvmedecins_api.dart';
import '../api/types.dart';

typedef PersonKeys = ({
  String title, // "Doctors"
  String add, // "Add a doctor"
  String edit, // "Edit a doctor"
  String empty, // "No doctors."
  String confirmDelete,
  String added, // "Doctor {{name}} has been added (login: {{login}})."
  String edited,
  String deleted,
  String notFound, // o registro foi excluído nesse meio tempo
});

PersonKeys keys(PersonType type) => switch (type) {
  PersonType.doctors => (
    title: 'DOCTORS.TITLE',
    add: 'DOCTORS.ADD',
    edit: 'DOCTORS.EDIT',
    empty: 'DOCTORS.EMPTY',
    confirmDelete: 'DOCTORS.DELETE_CONFIRM',
    added: 'DOCTORS.ADDED',
    edited: 'DOCTORS.UPDATED',
    deleted: 'DOCTORS.DELETED',
    notFound: 'ERRORS.DOCTOR_NOT_FOUND',
  ),
  PersonType.clients => (
    title: 'CLIENTS.TITLE',
    add: 'CLIENTS.ADD',
    edit: 'CLIENTS.EDIT',
    empty: 'CLIENTS.EMPTY',
    confirmDelete: 'CLIENTS.DELETE_CONFIRM',
    added: 'CLIENTS.ADDED',
    edited: 'CLIENTS.UPDATED',
    deleted: 'CLIENTS.DELETED',
    notFound: 'ERRORS.PATIENT_NOT_FOUND',
  ),
};

// {{name}} e {{login}} das mensagens "added / updated / deleted"
Map<String, String> messageParams(Person p) => {'name': '${p.firstName} ${p.lastName}', 'login': p.login ?? ''};

As telas de médicos e de clientes são idênticas; só as chaves de rótulo, descritas aqui, diferem.

  • linhas 13–22: um record com campos nomeados, que contém as chaves de um tipo de pessoa;
  • linhas 25–37: uma expressão sobre uma enumeração: [Dart] garante que todos os casos sejam tratados. Adicionar um valor a [PersonType] causaria um erro de compilação aqui;
  • linha 51: os parâmetros das mensagens “adicionado”, “modificado” e “excluído”.

11.13.4. lib/pages/persons.dart

// =========================================================================
// lib/pages/persons.dart - a lista dos médicos OU dos clientes (ADMIN)
// -------------------------------------------------------------------------
// Uma tela para ambos: o tipo (médicos ou clientes) chega como
// parâmetro (veja router.dart); os rótulos específicos de cada um estão em
// persons_config.dart.
// Em um celular, uma tabela de cinco colunas não cabe: uma linha de lista
// por pessoa (nome, login), com seus dois botões; o botão redondo
// "+" (FloatingActionButton) adiciona uma pessoa.
// =========================================================================

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

import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../i18n/translations.dart';
import '../widgets/confirmation.dart';
import '../widgets/page_title.dart';
import 'persons_config.dart';

class PersonsPage extends StatefulWidget {
  final PersonType type;

  const PersonsPage({super.key, required this.type});

  @override
  State<PersonsPage> createState() => _PersonsPageState();
}

class _PersonsPageState extends State<PersonsPage> {
  late final _api = context.read<RdvMedecinsApi>();
  late final _cache = context.read<Cache>();
  late final _messages = context.read<Messages>();
  Future<List<Person>>? _list;

  @override
  void initState() {
    super.initState();
    _load();
  }

  // o roteador reutiliza a tela para o outro tipo (/doctors -> /clients)
  @override
  void didUpdateWidget(PersonsPage old) {
    super.didUpdateWidget(old);
    if (old.type != widget.type) _load();
  }

  void _load() {
    final type = widget.type;
    setState(() {
      _list = _cache.read(type.name, () => _api.list(type));
    });
    _list!.then((_) {}, onError: (Object e) => _messages.showApiError(e));
  }

  Future<void> _delete(Person p) async {
    final k = keys(widget.type);
    if (!await confirm(context, k.confirmDelete)) return;
    try {
      await _api.remove(widget.type, p.id);
      _messages.showSuccess(k.deleted, messageParams(p));
    } on ApiError catch (e) {
      // um médico que ainda tem consultas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
      _messages.showApiError(e);
    }
    _cache.invalidate(widget.type.name);
    if (mounted) _load();
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    final k = keys(widget.type);
    final type = widget.type.name;
    return PageTitle(
      titleKey: k.title,
      // um Scaffold DENTRO do layout: para o seu botão flutuante
      child: Scaffold(
        floatingActionButton: FloatingActionButton.extended(
          onPressed: () => context.go('/$type/add'),
          icon: const Icon(Icons.add),
          label: Text(t(k.add)),
        ),
        body: FutureBuilder<List<Person>>(
          future: _list,
          builder: (context, state) {
            final list = state.data;
            if (list == null) {
              // ainda não carregado (ou carga que falhou: a mensagem está na parte inferior da tela)
              return state.hasError ? const SizedBox.shrink() : const Center(child: CircularProgressIndicator());
            }
            return ListView(
              // espaço na parte inferior, para não esconder a última linha sob o botão flutuante
              padding: const EdgeInsets.fromLTRB(8, 8, 8, 88),
              children: [
                Padding(
                  padding: const EdgeInsets.all(8),
                  child: Text(t(k.title), style: Theme.of(context).textTheme.headlineSmall),
                ),
                if (list.isEmpty) ListTile(title: Text(t(k.empty))),
                for (final p in list)
                  Card(
                    child: ListTile(
                      leading: CircleAvatar(child: Text('${p.firstName[0]}${p.lastName[0]}')),
                      title: Text(p.label),
                      subtitle: Text(p.login ?? '', style: const TextStyle(fontFamily: 'RobotoMono')),
                      trailing: Row(
                        mainAxisSize: MainAxisSize.min,
                        children: [
                          IconButton(
                            tooltip: t('PERSONS.EDIT'),
                            icon: const Icon(Icons.edit),
                            onPressed: () => context.go('/$type/${p.id}/edit'),
                          ),
                          IconButton(
                            tooltip: t('PERSONS.DELETE'),
                            icon: Icon(Icons.delete_outline, color: Colors.red.shade700),
                            onPressed: () => _delete(p),
                          ),
                        ],
                      ),
                    ),
                  ),
              ],
            );
          },
        ),
      ),
    );
  }
}

A lista de médicos ou de clientes.

  • linhas 54–59: a lista, vinda do cache. Atenção às chaves em [setState(() { ... })]: escrita com seta, [setState(() => _list = ...)], a função RETORNARIA o valor atribuído, neste caso um [Future], e o [setState] rejeita uma função que retorna um [Future] (a atualização do estado deve ser síncrona): o [Flutter] sinaliza isso com um erro;
  • linhas 62–73: exclusão, após confirmação. Um médico com consultas é rejeitado pelo servidor (409 [DOCTOR_HAS_APPOINTMENTS]);
  • linhas 84–88: um [Scaffold] dentro do [Scaffold] do layout, para o seu botão flutuante “+ Adicionar” ([FloatingActionButton]) no canto inferior direito;
  • linhas 107–124: um item de lista por pessoa ([ListTile]): um avatar com as iniciais, nome, nome de usuário e dois botões. Uma tabela de cinco colunas, como a dos clientes web, não caberia em um celular.

11.13.5. lib/pages/person_form.dart

// =========================================================================
// lib/pages/person_form.dart - criação OU atualização de um
// médico ou de um cliente (ADMIN)
// -------------------------------------------------------------------------
//     /doctors/add               -> criação (sem id)
//     /doctors/3/edit            -> atualização (id = 3)
// (e os mesmos endereços sob /clients).
//
// Dois widgets:
//   - PersonFormPage lê o registro a atualizar (se houver);
//   - _Form só é exibido depois que o registro foi lido: ele COMEÇA com
//     seus valores (estado inicial), sem precisar copiá-los depois.
// Nenhuma regra é verificada aqui: o servidor valida tudo, e seus erros
// são exibidos sob os campos (veja widgets/form_submit.dart).
// A VERSÃO lida com o registro volta com a atualização: se outro
// ADMIN o alterou nesse meio tempo, o servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================

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

import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../i18n/translations.dart';
import '../widgets/input_field.dart';
import '../widgets/person_fields.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';
import 'persons_config.dart';

const _empty = <String, Object?>{'title': 'Mr', 'firstName': '', 'lastName': '', 'login': '', 'password': ''};

class PersonFormPage extends StatefulWidget {
  final PersonType type;
  final int? id; // null: criação

  const PersonFormPage({super.key, required this.type, this.id});

  @override
  State<PersonFormPage> createState() => _PersonFormPageState();
}

class _PersonFormPageState extends State<PersonFormPage> {
  Future<Person>? _details;

  @override
  void initState() {
    super.initState();
    final id = widget.id;
    if (id != null) {
      // atualização: lemos o registro (incluindo sua versão), SEM cache: ele
      // deve estar atualizado (caso contrário o formulário começaria com uma
      // versão desatualizada: 409 CONCURRENT_UPDATE)
      _details = context.read<RdvMedecinsApi>().read(widget.type, id);
      // registro que não existe (excluído nesse meio tempo...): volta para a lista
      _details!.then(
        (_) {},
        onError: (Object e) {
          if (e is! ApiError || !mounted) return;
          context.read<Messages>().flash(success: false, key: e.key, params: e.params);
          context.go('/${widget.type.name}');
        },
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    final k = keys(widget.type);
    return PageTitle(
      titleKey: widget.id == null ? k.add : k.edit,
      child: widget.id == null
          ? _Form(type: widget.type, id: null, initial: _empty)
          : FutureBuilder<Person>(
              future: _details,
              builder: (context, state) {
                final p = state.data;
                if (p == null) return const Center(child: CircularProgressIndicator());
                return _Form(
                  type: widget.type,
                  id: p.id,
                  initial: {
                    'title': p.title,
                    'firstName': p.firstName,
                    'lastName': p.lastName,
                    'login': p.login ?? '',
                    'password': '',
                    'version': p.version,
                  },
                );
              },
            ),
    );
  }
}

// o próprio formulário
class _Form extends StatefulWidget {
  final PersonType type;
  final int? id;
  final Map<String, Object?> initial;

  const _Form({required this.type, required this.id, required this.initial});

  @override
  State<_Form> createState() => _FormState();
}

class _FormState extends State<_Form> {
  late final _messages = context.read<Messages>();
  late final _submit = FormSubmit(_messages);
  // uma CÓPIA modificável dos valores iniciais
  late final Map<String, Object?> _input = {...widget.initial};

  bool get _creating => widget.id == null;

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

  void _edit(String field, String value) {
    setState(() => _input[field] = value);
    _submit.clearError(field);
  }

  Future<void> _save() async {
    final api = context.read<RdvMedecinsApi>();
    final cache = context.read<Cache>();
    final k = keys(widget.type);
    final succeeded = await _submit.submit(() async {
      final id = widget.id;
      final p = id == null ? await api.add(widget.type, _input) : await api.edit(widget.type, id, _input);
      _messages.flash(key: _creating ? k.added : k.edited, params: messageParams(p));
    });
    if (!mounted) return;
    final errorKey = _messages.error?.key;
    if (succeeded) {
      cache.invalidate(widget.type.name); // a lista mudou
      context.go('/${widget.type.name}');
    } else if (errorKey == k.notFound) {
      // excluído nesse meio tempo por outro ADMIN: volta para a lista
      _messages.flash(success: false, key: errorKey!);
      context.go('/${widget.type.name}');
    }
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    final k = keys(widget.type);
    return ListenableBuilder(
      listenable: _submit,
      builder: (context, _) => ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Text(t(_creating ? k.add : k.edit), style: Theme.of(context).textTheme.headlineSmall),
          const SizedBox(height: 8),
          PersonFields(values: _input, errors: _submit.errors, onChanged: _edit),
          const SizedBox(height: 16),
          Text(t('PERSONS.ACCOUNT_SECTION'), style: Theme.of(context).textTheme.titleSmall),
          InputField(
            label: 'PERSONS.LOGIN_LABEL',
            maxLength: 30,
            value: _input['login'] as String,
            onChanged: (v) => _edit('login', v),
            error: _submit.errors['login'],
            help: _creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT',
          ),
          // nunca preenchido: a senha nunca volta do servidor
          InputField(
            label: 'PERSONS.PASSWORD_LABEL',
            secret: true,
            maxLength: 72,
            value: _input['password'] as String,
            onChanged: (v) => _edit('password', v),
            error: _submit.errors['password'],
            params: _submit.params,
            help: _creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT',
          ),
          const SizedBox(height: 16),
          Wrap(
            spacing: 8,
            children: [
              FilledButton(onPressed: _submit.submitting ? null : _save, child: Text(t('PERSONS.SAVE'))),
              OutlinedButton(onPressed: () => context.go('/${widget.type.name}'), child: Text(t('PERSONS.BACK'))),
            ],
          ),
        ],
      ),
    );
  }
}

Adição ou modificação de um médico ou de um cliente.

  • linhas 54–65: para fazer uma modificação, o registro é lido; SEM cache: sua versão deve estar atualizada. Se um registro não for encontrado (excluído nesse meio-tempo): volta-se à lista com uma mensagem;
  • linhas 78–92: o formulário só é exibido depois que o registro foi lido e COMEÇA com os valores dele; o usuário nunca precisa digitá-los de novo depois;
  • linha 117: uma CÓPIA modificável dos valores iniciais ([...]: o operador de decomposição, dentro de um [Map]);
  • linhas 132–149: o registro: [POST] ou [PUT], conforme haja ou não um identificador. A mensagem de sucesso é uma mensagem flash: aparecerá na lista. Se um registro foi excluído nesse meio-tempo por outro ADMIN: volta-se à lista;
  • linhas 167–184: o nome de usuário e a senha, com mensagens de ajuda diferentes para a criação e a modificação (deixar o campo de senha em branco não altera a senha). A senha nunca é preenchida previamente: o servidor nunca a devolve.

11.13.6. lib/pages/register.dart

// =========================================================================
// lib/pages/register.dart - "Create a patient account" (/register)
// -------------------------------------------------------------------------
// Só chegamos aqui depois de copiar o captcha da tela de login
// (botão "Create a patient account"): o servidor então emitiu um
// passe (um cookie), que o guard da rota verificou (veja
// router.dart). Mesmos campos do formulário do ADMIN, mas o login
// e a senha são obrigatórios, com confirmação.
// =========================================================================

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

import '../api/rdvmedecins_api.dart';
import '../state/messages.dart';
import '../i18n/translations.dart';
import '../widgets/input_field.dart';
import '../widgets/person_fields.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';

// comprimento mínimo de uma senha escolhida por um paciente: mesmo valor
// do servidor (que também devolve {min} com o erro PASSWORD_TOO_SHORT)
const passwordMin = '6';

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

  @override
  State<RegisterPage> createState() => _RegisterPageState();
}

class _RegisterPageState extends State<RegisterPage> {
  late final _messages = context.read<Messages>();
  late final _submit = FormSubmit(_messages);
  final Map<String, Object?> _input = {
    'title': 'Mr',
    'firstName': '',
    'lastName': '',
    'login': '',
    'password': '',
    'confirmation': '',
  };

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

  void _edit(String field, String value) {
    setState(() => _input[field] = value);
    _submit.clearError(field);
  }

  Future<void> _create() async {
    final api = context.read<RdvMedecinsApi>();
    var login = '';
    final succeeded = await _submit.submit(() async => login = await api.register(_input));
    if (!mounted) return;
    if (succeeded) {
      // volta para a tela de login, com o login preenchido
      _messages.flash(key: 'REGISTRATION.DONE', params: {'login': login});
      context.go(Uri(path: '/login', queryParameters: {'login': login}).toString());
    } else if (_messages.error?.key == 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
      // passe expirado (15 minutos): volta para o captcha
      _messages.flash(success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
      context.go('/login');
    }
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    // os parâmetros da mensagem de ajuda E dos erros de senha
    final passwordParams = {'min': passwordMin, ..._submit.params};
    return PageTitle(
      titleKey: 'REGISTRATION.TITLE',
      child: ListenableBuilder(
        listenable: _submit,
        builder: (context, _) => ListView(
          padding: const EdgeInsets.all(16),
          children: [
            Text(t('REGISTRATION.TITLE'), style: Theme.of(context).textTheme.headlineSmall),
            Text(t('REGISTRATION.INTRO'), style: const TextStyle(color: Colors.grey)),
            const SizedBox(height: 8),
            PersonFields(values: _input, errors: _submit.errors, onChanged: _edit),
            const SizedBox(height: 16),
            Text(t('PERSONS.ACCOUNT_SECTION'), style: Theme.of(context).textTheme.titleSmall),
            InputField(
              label: 'PERSONS.LOGIN_LABEL',
              maxLength: 30,
              value: _input['login'] as String,
              onChanged: (v) => _edit('login', v),
              error: _submit.errors['login'],
              help: 'REGISTRATION.LOGIN_HELP',
              autofill: const [AutofillHints.newUsername],
            ),
            InputField(
              label: 'PERSONS.PASSWORD_LABEL',
              secret: true,
              maxLength: 72,
              value: _input['password'] as String,
              onChanged: (v) => _edit('password', v),
              error: _submit.errors['password'],
              params: passwordParams,
              help: 'REGISTRATION.PASSWORD_HELP',
              autofill: const [AutofillHints.newPassword],
            ),
            InputField(
              label: 'ACCOUNT.CONFIRMATION_LABEL',
              secret: true,
              maxLength: 72,
              value: _input['confirmation'] as String,
              onChanged: (v) => _edit('confirmation', v),
              error: _submit.errors['confirmation'],
            ),
            const SizedBox(height: 16),
            Wrap(
              spacing: 8,
              children: [
                FilledButton(onPressed: _submit.submitting ? null : _create, child: Text(t('REGISTRATION.SUBMIT'))),
                OutlinedButton(onPressed: () => context.go('/login'), child: Text(t('REGISTRATION.BACK_TO_LOGIN'))),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

A criação de uma conta de paciente, acessível com o passe emitido pela tela de login (veja o guard da rota em [router.dart]).

  • linha 25: o tamanho mínimo da senha; para a mensagem de ajuda: o mesmo valor do servidor (que também o devolve com o erro [PASSWORD_TOO_SHORT]);
  • linhas 57–69: a criação. Em caso de sucesso: volta à tela de login, com o nome de usuário preenchido previamente ([/login?login=...]), junto com uma mensagem pop-up. Em caso de falha porque o passe expirou (15 minutos): volta ao CAPTCHA. Qualquer outro erro permanece exibido abaixo dos campos;
  • linha 77: os parâmetros da mensagem de ajuda e do erro de senha ([{{min}}]);
  • linhas 98–109: uma conta NOVA: o gerenciador de senhas pode sugerir uma senha forte e salvá-la.

11.13.7. lib/pages/patient_area.dart

// =========================================================================
// lib/pages/patient_area.dart - "My area" (/my-area, papel USER)
// -------------------------------------------------------------------------
// A tela inicial do paciente, logo após o login:
//   - duas opções: [Manage my account] e [View a schedule];
//   - sua consulta futura, se houver, com o meio de cancelá-la.
// =========================================================================

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

import '../api/api_error.dart';
import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../formatting.dart';
import '../i18n/translations.dart';
import '../widgets/confirmation.dart';
import '../widgets/page_title.dart';
import 'schedule.dart';

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

  @override
  State<PatientAreaPage> createState() => _PatientAreaPageState();
}

class _PatientAreaPageState extends State<PatientAreaPage> {
  late final _api = context.read<RdvMedecinsApi>();
  late final _cache = context.read<Cache>();
  late final _messages = context.read<Messages>();
  Future<MyArea>? _area;

  @override
  void initState() {
    super.initState();
    _load();
  }

  void _load() {
    // chaves: uma arrow function RETORNARIA o Future atribuído, e
    // setState recusa uma função que retorna um Future
    setState(() {
      _area = _cache.read('my-area', _api.myArea);
    });
    _area!.then((_) {}, onError: (Object e) => _messages.showApiError(e));
  }

  Future<void> _cancel(int appointmentId) async {
    if (!await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) return;
    try {
      await _api.cancelAppointment(appointmentId);
      _messages.showSuccess('SCHEDULE.CANCELLED');
    } on ApiError catch (e) {
      _messages.showApiError(e);
    }
    // a área E as agendas mudaram
    _cache.invalidate('my-area');
    _cache.invalidate('schedule');
    if (mounted) _load();
  }

  @override
  Widget build(BuildContext context) {
    final translations = context.watch<Translations>();
    final t = translations.t;
    return PageTitle(
      titleKey: 'AREA.TITLE',
      child: FutureBuilder<MyArea>(
        future: _area,
        builder: (context, state) {
          final a = state.data;
          if (a == null) return const Center(child: CircularProgressIndicator());
          return ListView(
            padding: const EdgeInsets.all(12),
            children: [
              Padding(
                padding: const EdgeInsets.all(4),
                child: Text(
                  t('AREA.HELLO', {'name': a.patient.label}),
                  style: Theme.of(context).textTheme.headlineSmall,
                ),
              ),
              _Option(
                icon: Icons.manage_accounts,
                title: t('AREA.MANAGE_ACCOUNT'),
                help: t('AREA.MANAGE_ACCOUNT_HELP'),
                onTap: () => context.go('/my-account'),
              ),
              _Option(
                icon: Icons.calendar_month,
                title: t('AREA.VIEW_SCHEDULE'),
                help: t('AREA.VIEW_SCHEDULE_HELP'),
                onTap: () => context.go('/schedule'),
              ),
              const SizedBox(height: 8),
              Card(
                child: Padding(
                  padding: const EdgeInsets.all(12),
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.start,
                    children: [
                      Text(t('AREA.MY_APPOINTMENT'), style: Theme.of(context).textTheme.titleMedium),
                      // normalmente apenas uma (regra "uma consulta futura por
                      // vez"), mas a tela pode exibir várias
                      for (final ap in a.appointments) ...[
                        const SizedBox(height: 8),
                        Text(
                          '${longDate(ap.day, translations.language)}, ${timeRange(ap.slot)}',
                          style: const TextStyle(fontWeight: FontWeight.w600),
                        ),
                        Text(ap.doctor.label),
                        Wrap(
                          spacing: 8,
                          children: [
                            // a agenda do médico neste dia: o paciente vê o seu nome nela
                            TextButton(
                              onPressed: () => context.go(scheduleAddress(ap.doctor.id, ap.day)),
                              child: Text(t('AREA.SEE_IN_SCHEDULE')),
                            ),
                            OutlinedButton(
                              style: OutlinedButton.styleFrom(foregroundColor: Colors.red.shade700),
                              onPressed: () => _cancel(ap.id),
                              child: Text(t('AREA.CANCEL_APPOINTMENT')),
                            ),
                          ],
                        ),
                      ],
                      if (a.appointments.isEmpty)
                        Padding(
                          padding: const EdgeInsets.only(top: 8),
                          child: Text(t('AREA.NO_APPOINTMENT'), style: const TextStyle(color: Colors.grey)),
                        ),
                    ],
                  ),
                ),
              ),
            ],
          );
        },
      ),
    );
  }
}

// um "card" de opção, em que se toca para abrir uma tela
class _Option extends StatelessWidget {
  final IconData icon;
  final String title;
  final String help;
  final VoidCallback onTap;

  const _Option({required this.icon, required this.title, required this.help, required this.onTap});

  @override
  Widget build(BuildContext context) {
    return Card(
      child: ListTile(
        leading: Icon(icon, size: 32, color: Theme.of(context).colorScheme.primary),
        title: Text(title, style: Theme.of(context).textTheme.titleMedium),
        subtitle: Text(help),
        trailing: const Icon(Icons.chevron_right),
        onTap: onTap,
      ),
    );
  }
}

A tela inicial do paciente: duas opções e sua próxima consulta.

  • linhas 52–63: cancelamento da consulta: a área E as agendas mudaram;
  • Linhas 109–127: a consulta e dois botões: ver a agenda do médico naquele dia (o paciente vê seu nome ali) e cancelar;
  • linhas 150–166: uma opção: um cartão em que você toca para abrir uma tela.

11.13.8. lib/pages/my_account.dart

// =========================================================================
// lib/pages/my_account.dart - "Manage my account" (/my-account, papel USER)
// -------------------------------------------------------------------------
// Dois formulários independentes:
//   1. a atualização (identidade, login, nova senha opcional);
//   2. a exclusão da conta - que também cancela suas consultas.
// Ambos exigem a senha ATUAL (verificada pelo servidor).
// Dois formulários, portanto dois FormSubmit (dois conjuntos de erros). Como
// no formulário de pessoas, a atualização só é exibida depois que
// a conta foi lida, e começa com seus valores.
// =========================================================================

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

import '../api/rdvmedecins_api.dart';
import '../api/types.dart';
import '../state/cache.dart';
import '../state/messages.dart';
import '../state/session.dart';
import '../i18n/translations.dart';
import '../widgets/input_field.dart';
import '../widgets/person_fields.dart';
import '../widgets/confirmation.dart';
import '../widgets/form_submit.dart';
import '../widgets/page_title.dart';

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

  @override
  State<MyAccountPage> createState() => _MyAccountPageState();
}

class _MyAccountPageState extends State<MyAccountPage> {
  // lida de novo a cada visita, sem cache: sua versão deve estar atualizada
  late final Future<MyAccount> _account = context.read<RdvMedecinsApi>().myAccount();

  @override
  Widget build(BuildContext context) {
    return PageTitle(
      titleKey: 'MY_ACCOUNT.TITLE',
      child: ListView(
        padding: const EdgeInsets.all(12),
        children: [
          FutureBuilder<MyAccount>(
            future: _account,
            builder: (context, state) => state.hasData
                ? _Update(account: state.data!)
                : const Padding(
                    padding: EdgeInsets.all(24),
                    child: Center(child: CircularProgressIndicator()),
                  ),
          ),
          const _Deletion(),
        ],
      ),
    );
  }
}

// -------------------------------------------------------------------------
// 1. a atualização
// -------------------------------------------------------------------------
class _Update extends StatefulWidget {
  final MyAccount account;

  const _Update({required this.account});

  @override
  State<_Update> createState() => _UpdateState();
}

class _UpdateState extends State<_Update> {
  late final _messages = context.read<Messages>();
  late final _submit = FormSubmit(_messages);
  late final Map<String, Object?> _input = {
    'title': widget.account.title,
    'firstName': widget.account.firstName,
    'lastName': widget.account.lastName,
    'login': widget.account.login,
    'password': '',
    'confirmation': '',
    'currentPassword': '',
    'version': widget.account.version,
  };

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

  void _edit(String field, String value) {
    setState(() => _input[field] = value);
    _submit.clearError(field);
  }

  Future<void> _save() async {
    final api = context.read<RdvMedecinsApi>();
    final session = context.read<Session>();
    final cache = context.read<Cache>();
    final succeeded = await _submit.submit(() async {
      // o servidor emitiu um NOVO token (nome, login): a barra superior deve acompanhar
      session.update(await api.editMyAccount(_input));
      _messages.flash(key: 'MY_ACCOUNT.UPDATED');
    });
    if (!mounted) return;
    if (succeeded) {
      cache.invalidate('my-area');
      context.go('/my-area');
    } else {
      // nunca uma senha deixada no campo após um envio recusado;
      // alteramos o valor SEM passar por _edit(), para não apagar
      // o erro que o servidor acabou de associar a ele
      setState(() => _input['currentPassword'] = '');
    }
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    return ListenableBuilder(
      listenable: _submit,
      builder: (context, _) => Card(
        child: Padding(
          padding: const EdgeInsets.all(16),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.stretch,
            children: [
              Text(t('MY_ACCOUNT.TITLE'), style: Theme.of(context).textTheme.titleLarge),
              PersonFields(values: _input, errors: _submit.errors, onChanged: _edit),
              const SizedBox(height: 12),
              Text(t('PERSONS.ACCOUNT_SECTION'), style: Theme.of(context).textTheme.titleSmall),
              InputField(
                label: 'PERSONS.LOGIN_LABEL',
                maxLength: 30,
                value: _input['login'] as String,
                onChanged: (v) => _edit('login', v),
                error: _submit.errors['login'],
              ),
              InputField(
                label: 'MY_ACCOUNT.NEW_PASSWORD_LABEL',
                secret: true,
                maxLength: 72,
                value: _input['password'] as String,
                onChanged: (v) => _edit('password', v),
                error: _submit.errors['password'],
                params: _submit.params,
                help: 'PERSONS.PASSWORD_HELP_EDIT',
              ),
              InputField(
                label: 'ACCOUNT.CONFIRMATION_LABEL',
                secret: true,
                maxLength: 72,
                value: _input['confirmation'] as String,
                onChanged: (v) => _edit('confirmation', v),
                error: _submit.errors['confirmation'],
              ),
              InputField(
                label: 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL',
                secret: true,
                maxLength: 72,
                value: _input['currentPassword'] as String,
                onChanged: (v) => _edit('currentPassword', v),
                error: _submit.errors['currentPassword'],
                help: 'MY_ACCOUNT.CURRENT_PASSWORD_HELP',
              ),
              const SizedBox(height: 8),
              Wrap(
                spacing: 8,
                children: [
                  FilledButton(onPressed: _submit.submitting ? null : _save, child: Text(t('PERSONS.SAVE'))),
                  OutlinedButton(onPressed: () => context.go('/my-area'), child: Text(t('MY_ACCOUNT.BACK'))),
                ],
              ),
            ],
          ),
        ),
      ),
    );
  }
}

// -------------------------------------------------------------------------
// 2. a exclusão: um formulário com um único campo
// -------------------------------------------------------------------------
class _Deletion extends StatefulWidget {
  const _Deletion();

  @override
  State<_Deletion> createState() => _DeletionState();
}

class _DeletionState extends State<_Deletion> {
  late final _messages = context.read<Messages>();
  late final _submit = FormSubmit(_messages);
  String _currentPassword = '';

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

  Future<void> _delete() async {
    final api = context.read<RdvMedecinsApi>();
    final session = context.read<Session>();
    if (!await confirm(context, 'MY_ACCOUNT.DELETE_CONFIRM')) return;
    final succeeded = await _submit.submit(() => api.deleteMyAccount(_currentPassword));
    if (succeeded) {
      // primeiro a mensagem: ela será exibida na tela de login, para onde o
      // roteador nos leva assim que a sessão fica vazia
      _messages.flash(key: 'MY_ACCOUNT.DELETED');
      session.forget(voluntary: true); // o servidor apagou o cookie do token
    }
  }

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    return ListenableBuilder(
      listenable: _submit,
      builder: (context, _) => Card(
        shape: RoundedRectangleBorder(
          side: BorderSide(color: Colors.red.shade300),
          borderRadius: BorderRadius.circular(12),
        ),
        child: Padding(
          padding: const EdgeInsets.all(16),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.stretch,
            children: [
              Text(
                t('MY_ACCOUNT.DELETE_TITLE'),
                style: Theme.of(context).textTheme.titleLarge!.copyWith(color: Colors.red.shade700),
              ),
              Text(t('MY_ACCOUNT.DELETE_HELP'), style: const TextStyle(color: Colors.grey)),
              InputField(
                label: 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL',
                secret: true,
                maxLength: 72,
                value: _currentPassword,
                onChanged: (v) {
                  setState(() => _currentPassword = v);
                  _submit.clearError('currentPassword');
                },
                error: _submit.errors['currentPassword'],
              ),
              Align(
                alignment: Alignment.centerLeft,
                child: FilledButton(
                  style: FilledButton.styleFrom(backgroundColor: Colors.red.shade700),
                  onPressed: _submit.submitting ? null : _delete,
                  child: Text(t('MY_ACCOUNT.DELETE_SUBMIT')),
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

“Gerenciar minha conta”: dois formulários independentes, cada um com seu próprio [FormSubmit].

  • linha 38: a conta, recarregada a cada visita, sem cache (sua versão deve estar atualizada);
  • linhas 100–117: a modificação. O servidor devolve o usuário atualizado (e um novo token em seu cookie): a sessão é atualizada, e o nome exibido no menu é atualizado de acordo. Após uma rejeição, a senha atual é apagada do campo;
  • linhas 207–216: exclusão da conta, após confirmação. Primeiro, a mensagem (uma mensagem pop-up); depois a sessão é apagada, e o roteador exibe a tela de login, junto com a mensagem.

11.13.9. lib/pages/error_page.dart

// =========================================================================
// lib/pages/error_page.dart - a tela de erro: 404 (endereço desconhecido) ou
// 403 (papel insuficiente, veja router.dart)
// =========================================================================

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

import '../i18n/translations.dart';
import '../widgets/page_title.dart';

class ErrorPage extends StatelessWidget {
  final int code; // 403 ou 404

  const ErrorPage({super.key, required this.code});

  @override
  Widget build(BuildContext context) {
    final t = context.watch<Translations>().t;
    return PageTitle(
      titleKey: 'ERROR_PAGE.TITLE',
      child: Padding(
        padding: const EdgeInsets.all(24),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(
              '${t('ERROR_PAGE.TITLE')} $code',
              style: Theme.of(context).textTheme.headlineMedium!.copyWith(color: Colors.red.shade700),
            ),
            const SizedBox(height: 8),
            Text(t(code == 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND')),
            const SizedBox(height: 16),
            FilledButton(onPressed: () => context.go('/'), child: Text(t('ERROR_PAGE.BACK'))),
          ],
        ),
      ),
    );
  }
}

A página de erro: 404 (endereço desconhecido) ou 403 (papel insuficiente). “Voltar à página inicial” leva a [/], que o roteador redireciona para a página inicial do papel.