Skip to content

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

11.1. O problema

A aplicação [RdvMedecins] permite marcar consultas em um consultório médico. O curso [NestJS] a desenvolveu como uma aplicação HTML, na qual o servidor gerava as páginas; os cursos [Vue.js], [Angular] e [React] desenvolveram clientes web para ela, e o curso [Flutter] criou um cliente mobile, que gera as MESMAS telas a partir dos dados JSON fornecidos pelo servidor descrito no capítulo “O servidor RdvMedecins : uma caixa-preta”. Este capítulo descreve como escrever um cliente [Android] nativo, em [Kotlin] e [Jetpack Compose].

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 reserva de consultas (janela de seleção de paciente) e cancelamento;
  • para o administrador, o gerenciamento de médicos e clientes (listar, adicionar, editar, excluir);
  • para o paciente, um painel pessoal (mostrando as consultas futuras, que ele pode cancelar) e o gerenciamento da conta;
  • dois idiomas: francês e inglês;
  • as mesmas telas dos clientes web ([/login], [/schedule], [/doctors], [/my-area]...), que aqui se tornam telas de navegação por ROTAS.

Um aplicativo mobile traz seus próprios requisitos: uma tela estreita (sem tabelas de cinco colunas), um teclado que esconde metade da tela, um botão Voltar, rotação da tela e troca de idioma que afetam a activity (eles a RECRIAM), 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”). O modo de teste do CAPTCHA não é necessário: você pode deixar [CAPTCHA_TEST] vazio no arquivo [.env] do servidor.

No [Android Studio], [File / Open] abre a pasta [rdvmedecins_kotlin]; o [Gradle] baixa as bibliotecas (na primeira vez, isso leva alguns minutos). Com o emulador em execução, uma janela de comando conecta a porta 8080 dele à porta do computador:

adb reverse tcp:8080 tcp:8080

em seguida, o botão [Run] instala e inicia o aplicativo. Você também pode fazer tudo em uma janela de comando aberta na pasta [rdvmedecins_kotlin]:

1
2
3
gradlew installDebug
gradlew installDebug -Pserver=http://10.0.2.2:8080
gradlew installDebug -Pserver=http://192.168.1.20:8080
  • a primeira linha compila e instala o aplicativo no dispositivo conectado (emulador ou celular), que se conecta ao servidor no endereço [http://localhost:8080] por meio de [adb reverse];
  • a segunda, para o emulador, sem [adb reverse]: o emulador enxerga o computador no endereço [10.0.2.2];
  • a terceira, para um celular real conectado por Wi-Fi à mesma rede do computador: informamos o endereço do computador nessa rede ([ipconfig] no [Windows]); o firewall do [Windows] deve permitir conexões de entrada na porta 8080. Um celular conectado por USB (com a “depuração USB” ativada em suas opções do desenvolvedor) também pode usar [adb reverse].

As contas de demonstração são listadas na tela de login (senha = login).

11.3. Usando o aplicativo

As capturas de tela desta seção são de um emulador Pixel 8 (1080 × 2400 pixels, 412 × 915 dp). Elas foram geradas automaticamente por um teste instrumentado ([app/src/androidTest/.../CaseStudyCaptures.kt], veja os apêndices) que navega pelo aplicativo como um usuário faria.

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):

Image

Image

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

Logado como [admin], você chega à agenda. Selecione um médico e um dia (o dia, a partir de um calendário) e depois “Ver agenda”:

Image

Image

Image

“Reservar” abre a janela de reserva, com um caminho de navegação exibido sobre a agenda; a consulta é salva; “Cancelar” pede confirmação:

Image

Image

Image

Um médico ([pelissier]) é levado diretamente à SUA agenda do dia:

Image

11.3.3. A área do paciente

Um paciente ([martin]) acessa “Minha área”. Em uma agenda, ele marca uma consulta para si mesmo sem selecionar um paciente:

Image

Image

Image

Sua consulta aparece sob o seu nome; o botão “Reservar” não está mais disponível (apenas uma consulta futura) e uma mensagem explica o motivo. Sua conta mostra a consulta. “Gerenciar minha conta”: qualquer alteração exige a senha atual; os erros vêm do servidor:

Image

Image

Image

O menu de um paciente não tem a entrada “Médicos”. Se ele abrisse essa tela mesmo assim (por meio de um link), a navegação exibiria uma página de erro 403 (veja [navigation/Navigation.kt]).

11.3.4. Gerenciamento de médicos e clientes

A lista de médicos; uma inclusão preenchida incorretamente; uma inclusão bem-sucedida:

Image

Image

Image

Uma duplicata; uma exclusão bem-sucedida:

Image

Image

11.3.5. Criação de uma conta

Na tela de login, informe o CAPTCHA e depois toque em “Criar uma conta de paciente”. O formulário é rejeitado pelo servidor; depois que a conta é criada, volte à tela de login, onde as informações de login já vêm preenchidas:

Image

Image

11.3.6. Em francês e, depois, em uma tela grande

O menu FR / EN na barra superior muda o idioma do aplicativo: a activity é recriada e TUDO é traduzido novamente, inclusive o calendário e as datas. Em uma tela larga (um tablet ou um celular na horizontal), o menu permanece exibido à esquerda:

Image

Image

11.3.7. Sessão expirada

Se o token expirar (ou se o cookie for excluído), a requisição seguinte retorna um 401; a aplicação redireciona para a tela de login. Depois do login, ela redirecionará o usuário de volta à tela que ele queria ver:

Image

11.4. Arquitetura do cliente

rdvmedecins_kotlin/
├── settings.gradle.kts, build.gradle.kts    the Gradle project
├── gradle/libs.versions.toml               the versions of the libraries
└── app/
    ├── build.gradle.kts                    the module of the application
    └── src/
        ├── androidTest/                    the test that makes the screenshots
        └── main/
            ├── AndroidManifest.xml
            ├── assets/i18n/                the dictionaries fr.json, en.json
            ├── res/                        icon, name, theme, languages
            └── java/fr/stahe/rdvmedecins/
                ├── RdvMedecinsApplication.kt  the shared objects
                ├── MainActivity.kt         the single activity
                ├── Config.kt               the address of the server
                ├── Formatting.kt           hours and days
                ├── api/                    the API access layer
                ├── state/                  session, messages, cache
                ├── i18n/                   the languages
                ├── navigation/             the screens, their routes, their access rights
                ├── widgets/                the layout and the reusable components
                └── pages/                  the screens

Esta é a arquitetura recomendada pelo guia do [Android] (“Guide to App Architecture”), simplificada da seguinte forma:

  • uma camada de dados ([api/]): a única camada que conhece o [OkHttp], os objetos URL e o objeto JSON;
  • uma camada de estado ([state/]): objetos cujas propriedades são estados do [Compose], criados uma única vez pelo objeto [Application] e fornecidos a todas as telas ([LocalDependencies]);
  • uma camada de interface ([pages/], [widgets/]): funções [@Composable], que exibem o estado e transmitem as ações do usuário.

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

Aplicação HTML (NestJS)
Cliente Flutter
Cliente Kotlin
O servidor renderiza cada página ([res.render])
Widgets renderizam as telas
Funções [@Composable] geram as telas
[views/layout.hbs] e suas views parciais
[layout.dart] (uma [ShellRoute])
[AppLayout.kt], em torno do [NavHost]
as rotas do controller
[go_router]
[navigation-compose], rotas [@Serializable]
[JwtAuthGuard], [RolesGuard]
A função [redirect] do roteador
[Protected] e um efeito que observa a sessão
o cookie do token, armazenado pelo navegador
um cliente HTTP que gerencia cookies
o [CookieJar] do [OkHttp]
Mensagem flash em um cookie
um [ChangeNotifier], [Messages]
uma classe com estado do [Compose], [Messages]
Dicionários lidos pelo servidor
[Translations] (JSON)
[Translations] (os MESMOS arquivos JSON)
idioma armazenado em um cookie
em [shared_preferences]
pelo [Android] ([setApplicationLocales])
dados já lidos
[Cache] (poucas linhas)
[Cache] (poucas linhas, a partir de [Deferred])
Formulário rejeitado: o servidor recarrega a página
resposta 400/409, erros abaixo dos campos
o mesmo

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

11.5. Configuração do projeto

11.5.1. settings.gradle.kts, build.gradle.kts

// =========================================================================
// settings.gradle.kts - a configuração GLOBAL do projeto Gradle
// (gerado pelo Android Studio; apenas rootProject.name foi alterado)
// =========================================================================

// onde o Gradle procura seus PLUGINS (o plugin Android, o plugin Compose...)
pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}
// onde o Gradle procura as BIBLIOTECAS: google() para AndroidX e Compose,
// mavenCentral() para OkHttp, kotlinx.serialization, AndroidSVG
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "rdvmedecins_kotlin"
// um único módulo: o aplicativo, na pasta app/
include(":app")
// =========================================================================
// build.gradle.kts (root) - declara os plugins Gradle usados pelos
// módulos do projeto, sem aplicá-los aqui ("apply false"): é
// app/build.gradle.kts que os aplica.
// =========================================================================
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.kotlin.serialization) apply false
}

Os arquivos dos exemplos (veja o Exemplo 01).

11.5.2. gradle/libs.versions.toml

# =========================================================================
# gradle/libs.versions.toml - o "version catalog" do projeto
# -------------------------------------------------------------------------
# TODAS as versões dos plugins e das bibliotecas, em um único lugar.
# Os arquivos build.gradle.kts se referem a elas por nome
# (libs.okhttp, libs.plugins.kotlin.compose...). É o equivalente da seção
# dependencies do pubspec.yaml do Flutter.
# =========================================================================

[versions]
agp = "9.4.1"
kotlin = "2.2.10"
coreKtx = "1.17.0"
lifecycle = "2.9.4"
activityCompose = "1.11.0"
composeBom = "2026.02.01"
appcompat = "1.7.1"
navigation = "2.9.5"
okhttp = "4.12.0"
kotlinxSerializationJson = "1.9.0"
androidsvg = "1.4"
junit = "4.13.2"
junitVersion = "1.3.0"
espressoCore = "3.7.0"
testRunner = "1.7.0"

[libraries]
# — gerado pelo Android Studio (template "Empty Activity") —
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycle" }
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-compose-ui = { group = "androidx.compose.ui", name = "ui" }
androidx-compose-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
androidx-compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
androidx-compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
androidx-compose-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
androidx-test-runner = { group = "androidx.test", name = "runner", version.ref = "testRunner" }
# --- adicionado para o RdvMedecins ---
# os ícones básicos do Material (Add, Delete, Search...)
androidx-compose-material-icons-core = { group = "androidx.compose.material", name = "material-icons-core" }
# o ciclo de vida da activity visto a partir do Compose 
androidx-lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
# viewModel() em uma função @Composable 
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
# o idioma PRÓPRIO da aplicação 
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
# o roteador 
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }
# o cliente HTTP 
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
# (des)serialização JSON 
kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
# desenhar uma imagem SVG (o captcha)
androidsvg = { group = "com.caverock", name = "androidsvg-aar", version.ref = "androidsvg" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
# gera o código de (de)serialização das classes @Serializable
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

As bibliotecas dos exemplos, exceto o [DataStore]: o idioma é armazenado pelo próprio [Android] e o token é armazenado no cookie jar.

11.5.3. app/build.gradle.kts

// =========================================================================
// app/build.gradle.kts - a configuração do módulo "app": o cliente
// Android do RdvMedecins. Gerado pelo Android Studio (template "Empty
// Activity"), depois completado (linhas marcadas "added").
// =========================================================================
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.compose)
    // added: o plugin kotlinx.serialization (classes @Serializable)
    alias(libs.plugins.kotlin.serialization)
}

android {
    namespace = "fr.stahe.rdvmedecins"
    compileSdk {
        version = release(37)
    }

    defaultConfig {
        applicationId = "fr.stahe.rdvmedecins"
        minSdk = 26
        targetSdk = 37
        versionCode = 1
        versionName = "1.0"
        // added: o endereço do servidor JSON, pode ser alterado em tempo de compilação:
        //     gradlew installDebug -Pserver=http://192.168.1.20:8080
        val server = providers.gradleProperty("server").getOrElse("http://localhost:8080")
        buildConfigField("String", "SERVER_URL", "\"$server\"")

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            optimization {
                enable = false
            }
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    buildFeatures {
        compose = true
        // added: a classe BuildConfig (BuildConfig.SERVER_URL)
        buildConfig = true
    }
}

dependencies {
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.activity.compose)
    implementation(libs.androidx.compose.material3)
    implementation(libs.androidx.compose.ui)
    implementation(libs.androidx.compose.ui.graphics)
    implementation(libs.androidx.compose.ui.tooling.preview)
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.lifecycle.runtime.ktx)
    // adicionado para o RdvMedecins
    implementation(libs.androidx.compose.material.icons.core)
    implementation(libs.androidx.lifecycle.runtime.compose)
    implementation(libs.androidx.lifecycle.viewmodel.compose)
    implementation(libs.androidx.appcompat)
    implementation(libs.androidx.navigation.compose)
    implementation(libs.okhttp)
    implementation(libs.kotlinx.serialization.json)
    implementation(libs.androidsvg)
    // os testes: gerar as capturas de tela do curso (pasta androidTest)
    testImplementation(libs.junit)
    androidTestImplementation(platform(libs.androidx.compose.bom))
    androidTestImplementation(libs.androidx.compose.ui.test.junit4)
    androidTestImplementation(libs.androidx.espresso.core)
    androidTestImplementation(libs.androidx.junit)
    androidTestImplementation(libs.androidx.test.runner)
    debugImplementation(libs.androidx.compose.ui.test.manifest)
    debugImplementation(libs.androidx.compose.ui.tooling)
}

O dos exemplos, com um ID de aplicativo diferente ([fr.stahe.rdvmedecins]): os dois aplicativos podem ser instalados lado a lado. O bloco [buildTypes] descreve a versão de PRODUÇÃO (veja o capítulo “Implantação”).

11.5.4. AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- ═════════════════════════════════════════════════════════════════════
     AndroidManifest.xml - o "documento de identidade" da aplicação
     ═════════════════════════════════════════════════════════════════════ -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- acesso à rede (o servidor JSON) -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- android:name: a classe Application (RdvMedecinsApplication.kt).
         usesCleartextTraffic: o HTTP "em texto claro" do servidor de desenvolvimento
         (a remover para um servidor de produção em https, veja Implantação).
         localeConfig: os idiomas oferecidos pela aplicação -->
    <application
        android:name=".RdvMedecinsApplication"
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:localeConfig="@xml/locales_config"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.RdvMedecins"
        android:usesCleartextTraffic="true"
        tools:targetApi="33">

        <!-- a única activity. windowSoftInputMode="adjustResize": o
             teclado reduz a tela em vez de escondê-la -->
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:windowSoftInputMode="adjustResize">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- antes do Android 13: o AppCompat memoriza o idioma escolhido -->
        <service
            android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
            android:enabled="false"
            android:exported="false">
            <meta-data
                android:name="autoStoreLocales"
                android:value="true" />
        </service>
    </application>

</manifest>
  • uma única activity, [MainActivity]: todas as telas são funções [@Composable];
  • [windowSoftInputMode="adjustResize"]: quando o teclado aparece, a tela encolhe (em vez de ficar escondida atrás do teclado);
  • [android:localeConfig] e o serviço do [AppCompat]: o idioma específico do aplicativo (veja o Exemplo 21).

11.5.5. Recursos

<?xml version="1.0" encoding="utf-8"?>
<!-- o nome do aplicativo (sob seu ícone). Os textos da interface,
     por sua vez, estão nos dicionários assets/i18n/fr.json e en.json -->
<resources>
    <string name="app_name">RdvMedecins</string>
</resources>
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- o tema "Android", visível apenas durante a inicialização; um
         tema AppCompat, exigido por AppCompatActivity (veja MainActivity.kt) -->
    <style name="Theme.RdvMedecins" parent="Theme.AppCompat.DayNight.NoActionBar" />
</resources>
<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/xml/locales_config.xml - os idiomas do aplicativo (exemplo 21)
     ............................................................................
     Declarado em AndroidManifest.xml (android:localeConfig). Desde o
     Android 13, o usuário também pode escolher o idioma de CADA
     aplicativo nas configurações do celular: Configurações > Sistema >
     Idiomas > Idiomas dos aplicativos.
     ===================================================================== -->
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
    <locale android:name="fr" />
    <locale android:name="en" />
</locale-config>

Os textos do aplicativo NÃO estão incluídos ali (apenas o nome do aplicativo está presente): eles estão nos dicionários JSON, [assets/i18n/fr.json] e [en.json], e nos dicionários dos clientes [Vue.js], [Angular], [React], e [Flutter]. Um trecho:

{
  "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"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",

11.6. Inicialização do aplicativo

11.6.1. Config.kt

// =========================================================================
// Config.kt - ONDE está o servidor JSON?
// -------------------------------------------------------------------------
// Uma aplicação mobile não tem "origem": é preciso fornecer a ela o endereço
// completo do servidor (veja o exemplo 22 e common/Config.kt dos exemplos):
//   - por padrão http://localhost:8080, com o comando
//         adb reverse tcp:8080 tcp:8080
//     que conecta a porta 8080 do celular (ou do emulador) à do
//     computador;
//   - ou outro endereço, definido em tempo de compilação:
//         gradlew installDebug -Pserver=http://10.0.2.2:8080        (emulador)
//         gradlew installDebug -Pserver=http://192.168.1.20:8080    (celular no Wi-Fi)
// =========================================================================
package fr.stahe.rdvmedecins

object Config {
    val serverUrl: String = BuildConfig.SERVER_URL
}

O endereço do servidor, definido em tempo de compilação (veja o Exemplo 22).

11.6.2. RdvMedecinsApplication.kt

// =========================================================================
// RdvMedecinsApplication.kt - os objetos compartilhados por toda a aplicação
// -------------------------------------------------------------------------
// O Android cria UM objeto Application na inicialização, antes de qualquer
// activity, e o mantém até a aplicação parar. Nele construímos, uma vez
// por todas, os objetos compartilhados por todas as telas:
//   - o cliente HTTP (e seu cookie jar), a camada de acesso à API;
//   - a sessão (quem está logado?), as mensagens, o cache de dados.
// Assim eles sobrevivem à recriação da activity (rotação, mudança
// de idioma). As telas os obtêm por LocalDependencies (veja
// MainActivity.kt): é uma "injeção de dependência" feita à mão.
// Dois mecanismos conectam esses objetos entre si:
//   1. a resposta 401 a uma requisição protegida (sessão expirada): o usuário
//      é esquecido e a mensagem é preparada; a navegação, que observa
//      a sessão, volta então para a tela de login;
//   2. uma mudança de usuário: os dados lidos para o usuário anterior
//      não valem mais nada, o cache é limpo.
// =========================================================================
package fr.stahe.rdvmedecins

import android.app.Application
import androidx.compose.runtime.snapshotFlow
import androidx.compose.runtime.staticCompositionLocalOf
import fr.stahe.rdvmedecins.api.ApiClient
import fr.stahe.rdvmedecins.api.RdvMedecinsApi
import fr.stahe.rdvmedecins.api.createHttpClient
import fr.stahe.rdvmedecins.state.Cache
import fr.stahe.rdvmedecins.state.Messages
import fr.stahe.rdvmedecins.state.Session
import kotlinx.coroutines.MainScope
import kotlinx.coroutines.launch

class RdvMedecinsApplication : Application() {
    // um escopo de corrotinas que vive enquanto a aplicação viver
    val scope = MainScope()
    lateinit var api: RdvMedecinsApi
        private set
    lateinit var session: Session
        private set
    val messages = Messages()
    val cache = Cache(scope)

    override fun onCreate() {
        super.onCreate()
        val client = ApiClient(createHttpClient(this))
        api = RdvMedecinsApi(client)
        session = Session(api)
        // 1. a sessão expirada
        client.onSessionExpired = {
            session.forget()
            messages.flash("ERRORS.SESSION_EXPIRED", success = false)
        }
        // 2. o usuário muda: snapshotFlow transforma um state do Compose em um Flow
        scope.launch {
            snapshotFlow { session.user }.collect { cache.clear() }
        }
    }
}

// o objeto Application, fornecido a todas as telas
val LocalDependencies = staticCompositionLocalOf<RdvMedecinsApplication> { error("no dependencies provided") }
  • Linhas 35–41: objetos compartilhados, criados uma única vez. [lateinit var]: uma propriedade não [null], inicializada mais tarde (em [onCreate]); [MainScope()]: um escopo de corrotinas que vive tanto quanto o aplicativo;
  • linhas 49–51: a sessão expirou: a função confiada ao cliente da API (que não sabe de mais nada) esquece o usuário e prepara a mensagem;
  • linha 55: [snapshotFlow] transforma um estado do [Compose] em um [Flow] de estados (veja o Exemplo 19): a cada vez que o usuário muda, o cache é limpo;
  • linha 61: o objeto [Application], fornecido a todas as telas por um [CompositionLocal] (veja o Exemplo 14): uma “injeção de dependência” feita à mão.

11.6.3. MainActivity.kt

// =========================================================================
// MainActivity.kt - a única activity da aplicação
// -------------------------------------------------------------------------
// Todas as telas são funções @Composable, exibidas pelo NavHost
// (veja navigation/Navigation.kt) NESTA activity. Ela fornece a todas
// as telas (CompositionLocalProvider):
//   - os objetos compartilhados da aplicação (LocalDependencies);
//   - as traduções do idioma atual (LocalTranslations).
// É uma AppCompatActivity: ela sabe aplicar o idioma escolhido pelo
// usuário (veja o exemplo 21), mesmo antes do Android 13.
// =========================================================================
package fr.stahe.rdvmedecins

import android.os.Bundle
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.appcompat.app.AppCompatActivity
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.ui.graphics.Color
import fr.stahe.rdvmedecins.i18n.LocalTranslations
import fr.stahe.rdvmedecins.i18n.rememberTranslations
import fr.stahe.rdvmedecins.navigation.Navigation

// as cores: o azul dos outros clientes RdvMedecins (Bootstrap)
private val colors = lightColorScheme(
    primary = Color(0xFF0D6EFD),
    onPrimary = Color.White,
    primaryContainer = Color(0xFFD8E2FF),
    onPrimaryContainer = Color(0xFF001A41),
    secondaryContainer = Color(0xFFDAE2F9),
    onSecondaryContainer = Color(0xFF131C2B),
    surface = Color(0xFFFAF9FD),
)

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        val dependencies = application as RdvMedecinsApplication
        setContent {
            MaterialTheme(colorScheme = colors) {
                CompositionLocalProvider(
                    LocalDependencies provides dependencies,
                    LocalTranslations provides rememberTranslations(),
                ) {
                    Navigation()
                }
            }
        }
    }
}
  • linhas 27–34: as cores do tema, o azul usado pelos outros clientes;
  • linhas 37–48: uma [AppCompatActivity] (o idioma, veja o Exemplo 21), que fornece objetos compartilhados e traduções a todas as telas e depois exibe a navegação.

11.6.4. Formatting.kt

// =========================================================================
// Formatting.kt - 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).
// =========================================================================
package fr.stahe.rdvmedecins

import fr.stahe.rdvmedecins.api.Slot
import fr.stahe.rdvmedecins.api.ScheduleSlot
import java.time.Instant
import java.time.LocalDate
import java.time.ZoneOffset
import java.time.format.DateTimeFormatter
import java.time.format.FormatStyle
import java.util.Locale

// "8:05" em vez de "8:5"
fun time(h: Int, m: Int) = "$h:${m.toString().padStart(2, '0')}"

// "8:00 - 8:20"
fun timeRange(c: Slot) = "${time(c.startHour, c.startMinute)} - ${time(c.endHour, c.endMinute)}"
fun timeRange(c: ScheduleSlot) = "${time(c.startHour, c.startMinute)} - ${time(c.endHour, c.endMinute)}"

fun today(): String = LocalDate.now().toString() // "yyyy-MM-dd", o formato da API

// true se day for uma data que existe, no formato yyyy-MM-dd ("2026-02-30": não)
fun isValidDate(day: String): Boolean =
    Regex("^\\d{4}-\\d{2}-\\d{2}$").matches(day) && runCatching { LocalDate.parse(day) }.isSuccess

// "lundi 5 octobre 2026" / "Monday, October 5, 2026"
fun longDate(day: String, language: String): String =
    LocalDate.parse(day).format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(Locale.forLanguageTag(language)))

// o calendário Material trabalha em milissegundos (UTC)
fun toMillis(day: String): Long = LocalDate.parse(day).atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli()
fun fromMillis(ms: Long): String = Instant.ofEpochMilli(ms).atZone(ZoneOffset.UTC).toLocalDate().toString()

O servidor envia dados BRUTOS ([startHour: 8], [day: "2026-10-05"]): sua formatação, que depende do idioma, é responsabilidade do cliente (veja o Exemplo 09).

11.7. A camada de acesso à API

11.7.1. api/HttpClient.kt

// =========================================================================
// api/HttpClient.kt - um cliente HTTP que gerencia COOKIES
// -------------------------------------------------------------------------
// Tirado do exemplo 23 (common/HttpClient.kt). O servidor RdvMedecins
// coloca o token JWT em um cookie httpOnly. Em um celular, não há
// navegador para guardá-lo: é o "cookie jar" (CookieJar) do
// cliente OkHttp que o armazena e o devolve a cada requisição. Os
// cookies também são armazenados no dispositivo (SharedPreferences): continuamos
// logados quando paramos e reiniciamos a aplicação.
// Dois cookies circulam: o token (rdvmedecins_jwt, path /api) e o
// passe de criação de conta (path /api/register).
// =========================================================================
package fr.stahe.rdvmedecins.api

import android.content.Context
import android.content.SharedPreferences
import androidx.core.content.edit
import fr.stahe.rdvmedecins.Config
import okhttp3.Cookie
import okhttp3.CookieJar
import okhttp3.HttpUrl
import okhttp3.HttpUrl.Companion.toHttpUrl
import okhttp3.OkHttpClient
import java.util.concurrent.TimeUnit

class DeviceCookieJar(private val storage: SharedPreferences) : CookieJar {
    // nome do cookie -> o cookie
    private val cookies = mutableMapOf<String, Cookie>()

    init {
        // os cookies memorizados durante um uso anterior
        val base = Config.serverUrl.toHttpUrl()
        for (text in storage.getStringSet(KEY, emptySet()).orEmpty()) {
            Cookie.parse(base, text)?.let { cookies[it.name] = it }
        }
    }

    // a resposta traz cookies: nós os armazenamos; um cookie expirado (é
    // assim que o servidor apaga o token no logout) é removido
    @Synchronized
    override fun saveFromResponse(url: HttpUrl, cookies: List<Cookie>) {
        for (c in cookies) {
            if (c.expiresAt < System.currentTimeMillis() || c.value.isEmpty()) {
                this.cookies.remove(c.name)
            } else {
                this.cookies[c.name] = c
            }
        }
        storage.edit { putStringSet(KEY, this@DeviceCookieJar.cookies.values.map { it.toString() }.toSet()) }
    }

    // uma requisição sai: os cookies que a ela dizem respeito, não expirados
    @Synchronized
    override fun loadForRequest(url: HttpUrl): List<Cookie> =
        cookies.values.filter { it.expiresAt >= System.currentTimeMillis() && it.matches(url) }

    companion object {
        private const val KEY = "rdvmedecins.cookies"
    }
}

fun createHttpClient(context: Context): OkHttpClient = OkHttpClient.Builder()
    .cookieJar(DeviceCookieJar(context.getSharedPreferences("rdvmedecins", Context.MODE_PRIVATE)))
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(10, TimeUnit.SECONDS)
    .build()

O cliente HTTP do Exemplo 23 e seu cookie jar. Dois cookies estão em circulação: o token ([rdvmedecins_jwt]) e o passe de criação de conta.

11.7.2. api/ApiError.kt

// =========================================================================
// api/ApiError.kt - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Tirado do exemplo 24 (common/ApiError.kt). Todas as respostas de erro
// do servidor têm a mesma forma:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Uma requisição sem resposta (rede, servidor parado) ou uma resposta que
// não vem do nosso servidor também se tornam um ApiError.
// =========================================================================
package fr.stahe.rdvmedecins.api

import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.jsonObject

class ApiError(
    val statusCode: Int, // 0: o servidor não respondeu
    val key: String, // ex.: "ERRORS.LOGIN_TAKEN"
    val params: Map<String, String> = emptyMap(),
    val fields: Map<String, String> = emptyMap(),
) : Exception("$statusCode $key") {

    override fun toString() = "$statusCode $key"

    companion object {
        fun fromResponse(statusCode: Int, body: String): ApiError {
            val json = runCatching { Json.parseToJsonElement(body).jsonObject }.getOrNull()
            val key = (json?.get("key") as? JsonPrimitive)?.content
            if (json == null || key == null) {
                // sem chave: o proxy ou a rede respondeu no lugar do servidor
                return ApiError(statusCode, if (statusCode >= 500) "ERRORS.SERVER_UNREACHABLE" else "ERRORS.SERVER_ERROR")
            }
            return ApiError(statusCode, key, strings(json["params"]), strings(json["fields"]))
        }

        private fun strings(json: Any?): Map<String, String> =
            (json as? JsonObject)?.mapValues { (_, v) -> (v as? JsonPrimitive)?.content ?: v.toString() } ?: emptyMap()
    }
}

11.7.3. api/ApiClient.kt

// =========================================================================
// api/ApiClient.kt - TODAS as requisições à API passam por aqui
// -------------------------------------------------------------------------
// Tirado do exemplo 24 (common/Api.kt), com uma novidade: o tratamento
// centralizado da resposta 401.
//
// Um 401 pode chegar a qualquer momento: o token expirou (2 horas), a
// conta foi excluída, o servidor reiniciou com outra chave
// secreta... Em vez de tratar esse caso em cada tela, nós o tratamos
// AQUI, uma única vez. Mas este arquivo não conhece nem a navegação nem as
// mensagens (ele não depende de nada): ele chama uma função que lhe foi
// entregue na inicialização (onSessionExpired, veja RdvMedecinsApplication.kt),
// que esquece o usuário; a navegação, que observa a sessão, volta então
// para a tela de login.
//
// Algumas requisições tratam seu 401 elas mesmas (o login, GET
// /api/auth/me...): são "públicas" (veja RdvMedecinsApi.kt).
// =========================================================================
package fr.stahe.rdvmedecins.api

import fr.stahe.rdvmedecins.Config
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import java.io.IOException

class ApiClient(private val client: OkHttpClient) {
    // o que fazer quando o servidor responde 401 a uma requisição protegida
    var onSessionExpired: () -> Unit = {}

    // isPublic: true para as rotas que tratam o 401 elas mesmas.
    // withContext(Dispatchers.Main.immediate): a função SEMPRE termina
    // na thread principal, a thread da tela, qualquer que seja a thread
    // do chamador (em uma aplicação, isso já é o caso: nada
    // muda; em um teste instrumentado, o chamador pode estar em outro lugar). Podemos
    // portanto, ao retornar, navegar ou mexer no estado sem cuidado
    suspend fun request(method: String, url: String, body: JsonElement? = null, isPublic: Boolean = false): JsonElement? =
        withContext(Dispatchers.Main.immediate) { execute(method, url, body, isPublic) }

    private suspend fun execute(method: String, url: String, body: JsonElement?, isPublic: Boolean): JsonElement? {
        val response = withContext(Dispatchers.IO) {
            val httpBody = body?.toString()?.toRequestBody("application/json".toMediaType())
            val request = Request.Builder().url("${Config.serverUrl}/api$url").method(method, httpBody).build()
            try {
                client.newCall(request).execute().use { it.code to it.body?.string().orEmpty() }
            } catch (e: IOException) {
                // nenhuma resposta: rede fora do ar, servidor parado, endereço errado
                throw ApiError(0, "ERRORS.SERVER_UNREACHABLE")
            }
        }
        // desestruturação do par (code, text)
        val (code, text) = response
        if (code >= 400) {
            val error = ApiError.fromResponse(code, text)
            if (error.statusCode == 401 && !isPublic) {
                // de volta à thread da tela: podemos mexer no estado
                onSessionExpired()
                // a tela que esperava a resposta exibirá TAMBÉM esta mensagem
                throw ApiError(401, "ERRORS.SESSION_EXPIRED")
            }
            throw error
        }
        return if (text.isEmpty()) null else Json.parseToJsonElement(text)
    }
}
  • linhas 42–43: a função sai SEMPRE na thread principal, a thread da tela ([Dispatchers.Main.immediate]): ao retornar, você pode navegar ou interagir com o estado sem cuidados especiais;
  • linhas 46–53: a requisição, na thread de E/S (veja o Exemplo 24);
  • linhas 60–64: a novidade: um 401 em uma rota protegida indica uma sessão expirada. Tratamos isso AQUI, uma vez para todas as requisições: [onSessionExpired()] e, em seguida, um [ApiError] cuja chave é a mensagem a ser exibida.

11.7.4. api/Types.kt

// =========================================================================
// api/Types.kt - os objetos JSON trocados com o servidor
// -------------------------------------------------------------------------
// A tradução, em classes Kotlin @Serializable, da API descrita no
// capítulo "O servidor, uma caixa-preta" (veja common/Types.kt dos
// exemplos). A leitura de um JSON que não tem a forma esperada falha
// assim que ele é recebido.
// =========================================================================
package fr.stahe.rdvmedecins.api

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.serializer

enum class Role { ADMIN, DOCTOR, USER }

// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
@Serializable
data class User(val login: String, val name: String, val role: Role)

// GET /api/captcha
@Serializable
data class Captcha(val id: String, val svg: String)

// um título, um nome, um sobrenome
@Serializable
data class Identity(val title: String, val firstName: String, val lastName: String) {
    val label get() = "$title $firstName $lastName" // "Mme Alice DURAND"
}

// um médico ou um cliente: GET /api/doctors, GET /api/clients/:id...
@Serializable
data class Person(
    val id: Int,
    val version: Int, // bloqueio otimista: a ser devolvido em uma atualização
    val title: String,
    val firstName: String,
    val lastName: String,
    val login: String? = null, // somente para o ADMIN
) {
    val label get() = "$title $firstName $lastName"
}

// um horário
@Serializable
data class Slot(val id: Int, val startHour: Int, val startMinute: Int, val endHour: Int, val endMinute: Int)

// uma linha da agenda, com os DIREITOS do usuário logado
@Serializable
data class ScheduleSlot(
    val id: Int,
    val startHour: Int,
    val startMinute: Int,
    val endHour: Int,
    val endMinute: Int,
    val free: Boolean,
    val patient: Identity?, // null: livre, ou ocupado por outro paciente
    val mine: Boolean, // a consulta do paciente logado
    val bookable: Boolean,
    val appointmentId: Int?, // definido se o usuário pode cancelar
)

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

// uma consulta de GET /api/my-area
@Serializable
data class Appointment(val id: Int, val day: String, val slot: Slot, val doctor: Person)

// GET /api/my-area
@Serializable
data class MyArea(val patient: Identity, val appointments: List<Appointment>)

// GET /api/my-account
@Serializable
data class MyAccount(val title: String, val firstName: String, val lastName: String, val login: String, val version: Int)

val apiJson = Json { ignoreUnknownKeys = true }

// JsonElement -> objeto Kotlin
inline fun <reified T> JsonElement?.read(): T =
    apiJson.decodeFromJsonElement(serializer<T>(), this ?: throw IllegalStateException("empty response"))

11.7.5. api/RdvMedecinsApi.kt

// =========================================================================
// api/RdvMedecinsApi.kt - uma função por rota da API
// -------------------------------------------------------------------------
// A "camada de acesso a dados" do cliente (um "repository"): as telas
// chamam essas funções tipadas, sem saber nada sobre as URLs, o OkHttp ou
// o JSON. Se a API mudar, só este arquivo muda.
// Cada função é suspensa; em caso de falha, lança um ApiError.
// Os dados dos formulários são simples Map<String, Any?>: suas
// chaves são os nomes dos campos esperados pelo servidor - e os dos
// erros que ele devolve (ApiError.fields).
// =========================================================================
package fr.stahe.rdvmedecins.api

import android.net.Uri
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonNull
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.boolean
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive

// /api/doctors ou /api/clients: ambos são tratados da mesma forma
enum class PersonType(val path: String) { DOCTORS("doctors"), CLIENTS("clients") }

typealias FormData = Map<String, Any?>

// dados do formulário -> um objeto JSON
fun FormData.toJson(): JsonObject = JsonObject(
    mapValues { (_, v) ->
        when (v) {
            null -> JsonNull
            is Number -> JsonPrimitive(v)
            is Boolean -> JsonPrimitive(v)
            else -> JsonPrimitive(v.toString())
        }
    },
)

class RdvMedecinsApi(private val client: ApiClient) {
    private suspend fun get(url: String, isPublic: Boolean = false) = client.request("GET", url, isPublic = isPublic)

    private suspend fun post(url: String, body: JsonElement, isPublic: Boolean = false) =
        client.request("POST", url, body, isPublic)

    // ------------------------------------------------ login (rotas públicas)
    suspend fun captcha(): Captcha = get("/captcha", isPublic = true).read()

    suspend fun me(): User = get("/auth/me", isPublic = true).read()

    suspend fun login(login: String, password: String, captchaId: String, captcha: String): User =
        post(
            "/auth/login",
            mapOf("login" to login, "password" to password, "captchaId" to captchaId, "captcha" to captcha).toJson(),
            isPublic = true,
        ).read()

    suspend fun logout() {
        post("/auth/logout", JsonObject(emptyMap()), isPublic = true)
    }

    // ------------------------------------------------ criação de conta (público)
    suspend fun registrationAccess(captchaId: String, captcha: String) {
        post("/register/access", mapOf("captchaId" to captchaId, "captcha" to captcha).toJson(), isPublic = true)
    }

    suspend fun registrationAccessStatus(): Boolean =
        get("/register/access", isPublic = true)?.jsonObject?.get("valid")?.jsonPrimitive?.boolean ?: false

    // devolve o login da conta criada
    suspend fun register(data: FormData): String =
        post("/register", data.toJson(), isPublic = true)!!.jsonObject["login"]!!.jsonPrimitive.content

    // ------------------------------------------------ agenda e consultas
    // doctorId null: para um médico logado, a agenda DELE
    suspend fun schedule(doctorId: Int?, day: String): Schedule {
        val params = Uri.Builder().appendQueryParameter("day", day).apply {
            if (doctorId != null) appendQueryParameter("doctorId", "$doctorId")
        }.build().encodedQuery
        return get("/schedule?$params").read()
    }

    suspend fun book(day: String, slotId: Int, clientId: Int?) {
        post("/appointments", buildMap { put("day", day); put("slotId", slotId); if (clientId != null) put("clientId", clientId) }.toJson())
    }

    suspend fun cancelAppointment(appointmentId: Int) {
        client.request("DELETE", "/appointments/$appointmentId")
    }

    // ------------------------------------------------ médicos e clientes
    suspend fun list(type: PersonType): List<Person> = get("/${type.path}").read()

    suspend fun read(type: PersonType, id: Int): Person = get("/${type.path}/$id").read()

    suspend fun add(type: PersonType, data: FormData): Person = post("/${type.path}", data.toJson()).read()

    suspend fun update(type: PersonType, id: Int, data: FormData): Person =
        client.request("PUT", "/${type.path}/$id", data.toJson()).read()

    suspend fun delete(type: PersonType, id: Int) {
        client.request("DELETE", "/${type.path}/$id")
    }

    // ------------------------------------------------ a área do paciente
    suspend fun myArea(): MyArea = get("/my-area").read()

    suspend fun myAccount(): MyAccount = get("/my-account").read()

    suspend fun updateMyAccount(data: FormData): User = client.request("PUT", "/my-account", data.toJson()).read()

    suspend fun deleteMyAccount(currentPassword: String) {
        client.request("DELETE", "/my-account", mapOf("currentPassword" to currentPassword).toJson())
    }
}
  • linha 24: médicos ou clientes: uma enumeração, com o caminho da API para cada um;
  • linhas 26–29: dados de formulário: um [Map] cujas chaves são os nomes dos campos esperados pelo servidor, convertido em JSON;
  • linhas 40–110: uma função por rota da API, agrupadas por tema; as rotas que tratam o 401 por conta própria são “públicas”.

11.8. Idiomas

11.8.1. i18n/Translations.kt

// =========================================================================
// i18n/Translations.kt - os dicionários, o idioma atual
// -------------------------------------------------------------------------
// Tirado do exemplo 25 (Dictionary.kt). Os dicionários
// (assets/i18n/fr.json, en.json) são os dos clientes Vue.js, Angular,
// React e Flutter: mesmas chaves, mesmas convenções ({{param}}). O servidor
// só devolve CHAVES ("ERRORS.LOGIN_TAKEN"): é aqui que elas
// viram texto.
//   - t("KEY", mapOf("param" to value)): o texto do idioma atual;
//   - changeLanguage("fr"): o idioma PRÓPRIO da aplicação (veja o exemplo
//     21), memorizado pelo Android; a activity é recriada no novo
//     idioma: nossos textos, mas também os do Android (o calendário), as
//     datas e os números.
// =========================================================================
package fr.stahe.rdvmedecins.i18n

import android.content.Context
import androidx.appcompat.app.AppCompatDelegate
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.runtime.staticCompositionLocalOf
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.platform.LocalContext
import androidx.core.os.LocaleListCompat
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive

val languages = listOf("fr", "en")

class Translations(context: Context, val language: String) {
    private val root: JsonObject = context.assets.open("i18n/$language.json").bufferedReader().use {
        Json.parseToJsonElement(it.readText()) as JsonObject
    }

    // "LOGIN.TITLE" -> root["LOGIN"]["TITLE"]; null se ausente
    private fun find(key: String): String? {
        var node: JsonElement? = root
        for (part in key.split('.')) node = (node as? JsonObject)?.get(part)
        return (node as? JsonPrimitive)?.takeIf { it.isString }?.content
    }

    // uma chave desconhecida é exibida como está: vemos imediatamente o que falta
    fun t(key: String, params: Map<String, String> = emptyMap()): String {
        val text = find(key) ?: return key
        return Regex("\\{\\{(\\w+)\\}\\}").replace(text) { m -> params[m.groupValues[1]] ?: m.value }
    }
}

// o idioma da aplicação: o Android o memoriza e recria a activity
fun changeLanguage(language: String) {
    AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(language))
}

// as traduções, fornecidas a todas as telas (veja MainActivity.kt)
val LocalTranslations = staticCompositionLocalOf<Translations> { error("no translations provided") }

// as traduções do idioma da configuração atual
@Composable
fun rememberTranslations(): Translations {
    val context = LocalContext.current
    val language = LocalConfiguration.current.locales[0].language.let { if (it in languages) it else "en" }
    return remember(language) { Translations(context, language) }
}

// um atalho, em uma função @Composable: t("LOGIN.TITLE")
@Composable
fun t(key: String, params: Map<String, String> = emptyMap()): String = LocalTranslations.current.t(key, params)
  • linhas 32–45: o dicionário do Exemplo 25, com os mesmos arquivos dos outros clientes;
  • linhas 57–64: as traduções para o idioma atual, fornecidas a todas as telas (veja [MainActivity.kt]); o dicionário é relido somente se o idioma mudar;
  • linha 69: um atalho [@Composable], [t("LOGIN.TITLE")]. Como qualquer função [@Composable], ele só pode ser chamado de dentro de outra: em uma lambda comum (um [onClick], o [text] de uma lista suspensa), é preciso traduzir antes, ou usar [LocalTranslations.current.t(...)].

11.9. O estado compartilhado

11.9.1. state/Session.kt

// =========================================================================
// state/Session.kt - QUEM está logado?
// -------------------------------------------------------------------------
// O usuário logado (ou null), em um state observado pelo Compose
// (mutableStateOf): as telas que o leem são recompostas quando ele
// muda, e a navegação (veja navigation/Navigation.kt) o observa para
// sair de uma tela que deixou de ser permitida.
//
// O token JWT em si NÃO está aqui: ele está em um cookie, armazenado pelo
// cliente HTTP. A sessão só guarda a DESCRIÇÃO do usuário
// ({ login, name, role }).
//
// Quando a aplicação inicia, a sessão está vazia: check() pergunta
// ao servidor, uma única vez, quem está logado (GET /api/auth/me).
// =========================================================================
package fr.stahe.rdvmedecins.state

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import fr.stahe.rdvmedecins.api.RdvMedecinsApi
import fr.stahe.rdvmedecins.api.Role
import fr.stahe.rdvmedecins.api.User

class Session(private val api: RdvMedecinsApi) {
    var user by mutableStateOf<User?>(null)
        private set

    // true após um logout DESEJADO (botão, exclusão da conta);
    // false após uma sessão expirada. A navegação leva isso em conta
    var leftVoluntarily = false
        private set

    // a tela que queríamos ver quando a sessão expirou (uma rota):
    // voltaremos a ela após o login
    var requestedScreen: Any? = null

    // a tela exibida (uma rota), registrada por cada tela protegida
    var currentScreen: Any? = null

    // a pergunta "quem está logado?" já foi feita?
    var checked by mutableStateOf(false)
        private set

    // só pergunta ao servidor na primeira vez
    suspend fun check() {
        if (checked) return
        user = try {
            api.me()
        } catch (e: Exception) {
            null // 401: ninguém; ou servidor inacessível
        }
        checked = true
    }

    suspend fun login(login: String, password: String, captchaId: String, captcha: String) {
        change(api.login(login, password, captchaId, captcha))
    }

    // o usuário mudou seu nome ou login (PUT /api/my-account)
    fun update(u: User) = change(u)

    suspend fun logout() {
        try {
            api.logout()
        } finally {
            forget(voluntary = true) // mesmo que o servidor não responda
        }
    }

    // sem perguntar nada ao servidor: sessão expirada, conta excluída
    fun forget(voluntary: Boolean = false) = change(null, voluntary)

    private fun change(u: User?, voluntary: Boolean = false) {
        leftVoluntarily = voluntary
        user = u
    }
}

// o que se deduz do usuário: propriedades de EXTENSÃO do tipo
// User? (elas também se aplicam a null)
val User?.isAdmin get() = this?.role == Role.ADMIN
val User?.isPatient get() = this?.role == Role.USER

// ADMIN e DOCTOR: marcam e cancelam as consultas de qualquer paciente
val User?.isManager get() = this?.role == Role.ADMIN || this?.role == Role.DOCTOR
  • linhas 26–27: o usuário, um estado observado: a barra superior, o menu e a navegação o leem;
  • linhas 31–39: o que é necessário para voltar, depois de uma sessão expirada, à tela que você queria ver;
  • linhas 82–86: propriedades de EXTENSÃO do tipo [User?]: elas também se aplicam a [null] ([this?.role]).

11.9.2. state/Messages.kt

// =========================================================================
// state/Messages.kt - as mensagens exibidas ao usuário
// -------------------------------------------------------------------------
// Mesma apresentação dos outros clientes RdvMedecins:
//   - um SUCESSO é exibido no TOPO da tela (faixa verde);
//   - um ERRO na PARTE INFERIOR (faixa 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 o 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 desaparecerá na
// navegação seguinte. É a navegação que chama newPage() a
// cada mudança de tela (veja navigation/Navigation.kt).
// =========================================================================
package fr.stahe.rdvmedecins.state

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import fr.stahe.rdvmedecins.api.ApiError

data class Message(val key: String, val params: Map<String, String> = emptyMap())

class Messages {
    var success by mutableStateOf<Message?>(null)
        private set
    var error by mutableStateOf<Message?>(null)
        private set

    // as mensagens a exibir na próxima tela
    private var pendingSuccess: Message? = null
    private var pendingError: Message? = null

    fun showSuccess(key: String, params: Map<String, String> = emptyMap()) {
        success = Message(key, params)
        error = null
    }

    fun showError(key: String, params: Map<String, String> = emptyMap()) {
        error = Message(key, params)
        success = null
    }

    fun showApiError(e: ApiError) = showError(e.key, e.params)

    fun clear() {
        success = null
        error = null
    }

    // para a PRÓXIMA tela
    fun flash(key: String, params: Map<String, String> = emptyMap(), success: Boolean = true) {
        if (success) pendingSuccess = Message(key, params) else pendingError = Message(key, params)
    }

    // uma nova tela: as mensagens da anterior desaparecem, as
    // mensagens flash aparecem
    fun newPage() {
        success = pendingSuccess
        error = pendingError
        pendingSuccess = null
        pendingError = null
    }
}

11.9.3. state/Cache.kt

// =========================================================================
// state/Cache.kt - os dados já lidos do servidor
// -------------------------------------------------------------------------
// A lista de médicos quase nunca muda: não é preciso lê-la de novo a
// cada visita à agenda. O cache guarda o resultado de cada leitura,
// sob uma CHAVE ("doctors", "schedule/1/2026-10-05"...):
//
//     val doctors = cache.read("doctors") { api.list(PersonType.DOCTORS) }
//
// devolve o resultado já guardado, ou lança a leitura e guarda seu
// resultado. Duas requisições simultâneas para a mesma chave compartilham a mesma
// leitura (um Deferred: um resultado por vir). Uma leitura que falhou não é
// guardada: a próxima tentará de novo.
// Após uma atualização, as chaves afetadas são INVALIDADAS:
// cache.invalidate("schedule"). A propriedade version, um state observado,
// então muda: as telas que a leem (mesmo escondidas sob um diálogo)
// leem seus dados de novo. É, em poucas linhas, o que a
// biblioteca TanStack Query do cliente React faz.
// =========================================================================
package fr.stahe.rdvmedecins.state

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.setValue
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.async

class Cache(private val scope: CoroutineScope) {
    private val reads = mutableMapOf<String, Deferred<Any?>>()

    var version by mutableIntStateOf(0)
        private set

    @Suppress("UNCHECKED_CAST")
    suspend fun <T> read(key: String, load: suspend () -> T): T {
        val reading = reads.getOrPut(key) { scope.async { load() } }
        try {
            return reading.await() as T
        } catch (e: Exception) {
            // em caso de falha, esta leitura é esquecida (a próxima requisição tentará de novo)
            if (reads[key] === reading) reads.remove(key)
            throw e
        }
    }

    // esquece todas as chaves que começam com prefix e notifica as telas
    fun invalidate(prefix: String) {
        reads.keys.removeAll { it.startsWith(prefix) }
        version++
    }

    // mudança de usuário: tudo é esquecido, SEM notificar (as telas do
    // usuário anterior estão prestes a desaparecer, não devem ler nada de novo)
    fun clear() = reads.clear()
}
  • Linhas 36–39: [getOrPut]: se uma leitura já foi iniciada para esta chave, continue com ela; caso contrário, inicie uma nova. [async] inicia uma corrotina que produz um [Deferred], um resultado futuro: duas requisições simultâneas esperam ([await]) pela MESMA leitura;
  • Linhas 48–50: [invalidate]: as telas que leem [version] na chave de um [LaunchedEffect] relêem seus dados.

11.10. Navegação

11.10.1. navigation/Screens.kt

// =========================================================================
// navigation/Screens.kt - as ROTAS da aplicação (veja o exemplo 17)
// -------------------------------------------------------------------------
// As mesmas telas dos outros clientes (/login, /schedule, /doctors,
// /my-area...), descritas por objetos Kotlin @Serializable, reunidos
// em um objeto Screens: Screens.Schedule(doctorId = 1, day = "2026-10-05").
// TODO o estado de uma tela está em sua rota (o médico, o dia...): o
// botão Voltar do celular o restaura como está.
// O diálogo de agendamento também é uma rota (Screens.Booking):
// um destino do tipo "dialog", exibido POR CIMA da agenda; o
// botão Voltar o fecha.
// =========================================================================
package fr.stahe.rdvmedecins.navigation

import fr.stahe.rdvmedecins.api.Role
import fr.stahe.rdvmedecins.api.PersonType
import fr.stahe.rdvmedecins.api.User
import kotlinx.serialization.Serializable

object Screens {
    // a primeira tela: o tempo de perguntar ao servidor quem está logado
    @Serializable
    object Startup

    // login: preenchido previamente logo após a criação de uma conta
    @Serializable
    data class Login(val login: String = "")

    // day: como está, talvez inválido (é verificado pela tela)
    @Serializable
    data class Schedule(val doctorId: Int? = null, val day: String? = null)

    @Serializable
    data class Booking(val doctorId: Int?, val day: String, val slotId: Int)

    // as telas de gerenciamento dos médicos OU dos clientes (ADMIN)
    @Serializable
    data class Persons(val type: PersonType)

    // id null: criação; caso contrário, atualização
    @Serializable
    data class Person(val type: PersonType, val id: Int? = null)

    @Serializable
    object Register

    @Serializable
    object MyArea

    @Serializable
    object MyAccount
}

// os papéis permitidos para uma tela protegida (null: todos os papéis logados)
val adminRoles = setOf(Role.ADMIN)
val patientRoles = setOf(Role.USER)

// a página inicial de cada papel, logo após o login
fun home(u: User): Any = if (u.role == Role.USER) Screens.MyArea else Screens.Schedule()

Os caminhos de navegação da aplicação, organizados em um objeto [Screens]. TODO o estado de uma tela é armazenado em seu caminho de navegação; o botão Voltar do celular o restaura exatamente como estava. A janela de reserva também é um caminho de navegação.

11.10.2. navigation/Navigation.kt

// =========================================================================
// navigation/Navigation.kt - as telas da aplicação e seus direitos
// -------------------------------------------------------------------------
// O NavHost (veja o exemplo 17) exibe a tela da rota atual, no
// AppLayout (barra superior, menu, mensagens).
//
// Os GUARDS (veja o exemplo 18):
//   - uma tela protegida é envolvida por Protected(route, roles): ela só é
//     exibida para um usuário logado, com o papel correto (caso contrário,
//     a tela de erro 403);
//   - um efeito observa a SESSÃO: um usuário que desaparece (logout,
//     sessão expirada) volta para a tela de login; um usuário que
//     aparece (login) sai da tela de login para a tela solicitada
//     antes da expiração, ou então para a página inicial de seu papel.
// LEMBRETE: essas verificações são apenas uma COMODIDADE (não exibir uma tela
// inútil). A proteção dos dados é garantida pelo servidor, que
// verifica o token e o papel de novo a CADA requisição.
//
// As mensagens "flash": a cada nova tela, Messages.newPage().
// =========================================================================
package fr.stahe.rdvmedecins.navigation

import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.navigation.NavDestination
import androidx.navigation.NavDestination.Companion.hasRoute
import androidx.navigation.NavHostController
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.dialog
import androidx.navigation.compose.rememberNavController
import androidx.navigation.toRoute
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.Role
import fr.stahe.rdvmedecins.pages.SchedulePage
import fr.stahe.rdvmedecins.pages.LoginPage
import fr.stahe.rdvmedecins.pages.StartupPage
import fr.stahe.rdvmedecins.pages.ErrorPage
import fr.stahe.rdvmedecins.pages.PatientAreaPage
import fr.stahe.rdvmedecins.pages.RegisterPage
import fr.stahe.rdvmedecins.pages.MyAccountPage
import fr.stahe.rdvmedecins.pages.PersonFormPage
import fr.stahe.rdvmedecins.pages.PersonsPage
import fr.stahe.rdvmedecins.widgets.BookingDialog
import fr.stahe.rdvmedecins.widgets.AppLayout
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.flow.map

// as telas públicas (sem login)
fun isPublic(d: NavDestination) =
    d.hasRoute<Screens.Login>() || d.hasRoute<Screens.Register>() || d.hasRoute<Screens.Startup>()

// ir para uma tela ESVAZIANDO a pilha: Voltar não levará de volta à tela anterior
fun NavHostController.goTo(route: Any) {
    navigate(route) {
        popUpTo(graph.id) { inclusive = true }
        launchSingleTop = true
    }
}

@Composable
fun Navigation() {
    val nav = rememberNavController()
    val d = LocalDependencies.current
    val session = d.session
    val user = session.user

    // as mensagens flash: a cada nova tela (uma nova entrada da pilha)
    LaunchedEffect(nav) {
        nav.currentBackStackEntryFlow.map { it.id }.distinctUntilChanged().collect { d.messages.newPage() }
    }

    // a sessão muda: relançado a cada mudança de usuário
    LaunchedEffect(user, session.checked) {
        if (!session.checked) return@LaunchedEffect
        val here = nav.currentBackStackEntry?.destination ?: return@LaunchedEffect
        if (user == null && !isPublic(here)) {
            // sessão expirada: a tela atual é memorizada, para voltar a ela
            session.requestedScreen = if (session.leftVoluntarily) null else session.currentScreen
            nav.goTo(Screens.Login())
        } else if (user != null && (here.hasRoute<Screens.Login>() || here.hasRoute<Screens.Startup>())) {
            // logado: a tela de login deixa de fazer sentido
            val target = session.requestedScreen ?: home(user)
            session.requestedScreen = null
            nav.goTo(target)
        }
    }

    AppLayout(nav) {
        NavHost(navController = nav, startDestination = Screens.Startup) {
            composable<Screens.Startup> { StartupPage(onNobody = { nav.goTo(Screens.Login()) }) }
            composable<Screens.Login> { e ->
                LoginPage(login = e.toRoute<Screens.Login>().login.take(30), onRegister = { nav.navigate(Screens.Register) })
            }
            composable<Screens.Schedule> { e ->
                val route = e.toRoute<Screens.Schedule>()
                Protected(route) {
                    SchedulePage(
                        doctorId = route.doctorId,
                        day = route.day,
                        // ver outra agenda: a rota atual é SUBSTITUÍDA
                        onView = { id, day ->
                            nav.navigate(Screens.Schedule(id, day)) { popUpTo<Screens.Schedule> { inclusive = true } }
                        },
                        // marcar consulta: o diálogo é EMPILHADO sobre a agenda
                        onBook = { id, day, slotId -> nav.navigate(Screens.Booking(id, day, slotId)) },
                        onMyArea = { nav.goTo(Screens.MyArea) },
                    )
                }
            }
            dialog<Screens.Booking> { e ->
                val route = e.toRoute<Screens.Booking>()
                Protected(route) { BookingDialog(route, onClose = { nav.popBackStack() }) }
            }
            composable<Screens.Persons> { e ->
                val route = e.toRoute<Screens.Persons>()
                Protected(route, adminRoles) {
                    PersonsPage(
                        type = route.type,
                        onAdd = { nav.navigate(Screens.Person(route.type)) },
                        onEdit = { id -> nav.navigate(Screens.Person(route.type, id)) },
                    )
                }
            }
            composable<Screens.Person> { e ->
                val route = e.toRoute<Screens.Person>()
                Protected(route, adminRoles) {
                    // volta para a lista: o formulário é desempilhado
                    PersonFormPage(type = route.type, id = route.id, onList = {
                        if (!nav.popBackStack()) nav.goTo(Screens.Persons(route.type))
                    })
                }
            }
            composable<Screens.Register> {
                RegisterPage(onLogin = { login -> nav.goTo(Screens.Login(login)) })
            }
            composable<Screens.MyArea> {
                Protected(Screens.MyArea, patientRoles) {
                    PatientAreaPage(
                        onMyAccount = { nav.navigate(Screens.MyAccount) },
                        onSchedule = { id, day -> nav.navigate(Screens.Schedule(id, day)) },
                    )
                }
            }
            composable<Screens.MyAccount> {
                Protected(Screens.MyAccount, patientRoles) {
                    MyAccountPage(onMyArea = { nav.goTo(Screens.MyArea) })
                }
            }
        }
    }
}

// uma tela protegida: logado e, se roles não for null, com um destes papéis
@Composable
fun Protected(route: Any, roles: Set<Role>? = null, content: @Composable () -> Unit) {
    val session = LocalDependencies.current.session
    val u = session.user ?: return // não logado: a navegação volta para o login
    // a tela exibida, memorizada para voltar a ela após uma sessão expirada
    LaunchedEffect(route) { session.currentScreen = route }
    if (roles != null && u.role !in roles) {
        ErrorPage(code = 403)
    } else {
        content()
    }
}
  • linhas 54–57: ir para uma tela LIMPANDO a pilha: o Voltar não retornará à tela anterior (você não volta à tela de login depois de fazer login);
  • linhas 69–70: mensagens flash: [currentBackStackEntryFlow], [Flow] para as telas sucessivas;
  • linhas 74–85: O guard da aplicação: um efeito disparado a cada mudança de usuário. Se ninguém estiver em uma tela protegida: para o login (mantendo a tela atual se a sessão tiver expirado); se alguém estiver na tela de login: para a tela solicitada ou, caso contrário, para a tela inicial do seu papel;
  • linhas 89–113: o grafo de navegação, no layout; [dialog<Screens.Booking>]: um destino exibido POR CIMA da tela anterior, que o botão Voltar fecha;
  • linhas 156–164: [Protected]: não logado, nada (o efeito acima remete ao login); papel incorreto, a tela de erro 403.

11.11. Componentes reutilizáveis

11.11.1. widgets/AppLayout.kt

// =========================================================================
// widgets/AppLayout.kt - o LAYOUT comum a todas as telas
// -------------------------------------------------------------------------
// Ele envolve o NavHost (veja navigation/Navigation.kt):
//   - a barra superior: título, idioma (FR / EN), logout;
//   - o menu lateral ("drawer", ModalNavigationDrawer), aberto pelo
//     botão ☰: as telas permitidas ao papel do usuário. "Doctors" e
//     "Patients" só aparecem para o ADMIN: uma simples comodidade de
//     exibição, pois a proteção real é a do servidor;
//   - uma mensagem de sucesso no TOPO;
//   - a tela atual (conteúdo);
//   - o painel de erro na PARTE INFERIOR.
// Em uma tela grande (tablet, celular na horizontal), o menu é
// exibido permanentemente à esquerda: um NavigationRail no lugar do drawer.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.rdvmedecins.widgets

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ExitToApp
import androidx.compose.material.icons.filled.AccountCircle
import androidx.compose.material.icons.filled.CheckCircle
import androidx.compose.material.icons.filled.Close
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material.icons.filled.Face
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Menu
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.filled.Warning
import androidx.compose.material3.DrawerValue
import androidx.compose.material3.DropdownMenu
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.ListItemDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.ModalDrawerSheet
import androidx.compose.material3.ModalNavigationDrawer
import androidx.compose.material3.NavigationDrawerItem
import androidx.compose.material3.NavigationRail
import androidx.compose.material3.NavigationRailItem
import androidx.compose.material3.Scaffold
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.TopAppBar
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.material3.VerticalDivider
import androidx.compose.material3.rememberDrawerState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.navigation.NavDestination
import androidx.navigation.NavDestination.Companion.hasRoute
import androidx.navigation.NavHostController
import androidx.navigation.compose.currentBackStackEntryAsState
import androidx.navigation.toRoute
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.PersonType
import fr.stahe.rdvmedecins.api.User
import fr.stahe.rdvmedecins.state.isAdmin
import fr.stahe.rdvmedecins.state.isPatient
import fr.stahe.rdvmedecins.i18n.LocalTranslations
import fr.stahe.rdvmedecins.i18n.changeLanguage
import fr.stahe.rdvmedecins.i18n.languages
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.navigation.Screens
import fr.stahe.rdvmedecins.navigation.goTo
import kotlinx.coroutines.launch

// uma entrada de menu: a rota para a qual leva, a chave de seu rótulo, seu
// ícone, e o teste que diz se está ativa para uma dada tela
class MenuEntry(val route: Any, val key: String, val icon: ImageVector, val active: (NavDestination, Any?) -> Boolean)

fun menuEntries(u: User?): List<MenuEntry> {
    if (u == null) return emptyList()
    // buildList: preenchemos uma lista, com ifs
    return buildList {
        if (u.isPatient) add(MenuEntry(Screens.MyArea, "APP.MENU_MY_AREA", Icons.Default.Home) { d, _ -> d.hasRoute<Screens.MyArea>() })
        add(MenuEntry(Screens.Schedule(), "APP.MENU_SCHEDULE", Icons.Default.DateRange) { d, _ -> d.hasRoute<Screens.Schedule>() })
        if (u.isAdmin) {
            add(MenuEntry(Screens.Persons(PersonType.DOCTORS), "APP.MENU_DOCTORS", Icons.Default.Face) { _, type -> type == PersonType.DOCTORS })
            add(MenuEntry(Screens.Persons(PersonType.CLIENTS), "APP.MENU_PATIENTS", Icons.Default.Person) { _, type -> type == PersonType.CLIENTS })
        }
        if (u.isPatient) add(MenuEntry(Screens.MyAccount, "APP.MENU_ACCOUNT", Icons.Default.AccountCircle) { d, _ -> d.hasRoute<Screens.MyAccount>() })
    }
}

@Composable
fun AppLayout(nav: NavHostController, content: @Composable () -> Unit) {
    val d = LocalDependencies.current
    val u = d.session.user
    val language = LocalTranslations.current.language
    val scope = rememberCoroutineScope()
    val entries = menuEntries(u)
    // a tela atual, e o tipo de pessoas se for uma lista ou um formulário
    val entry by nav.currentBackStackEntryAsState()
    val destination = entry?.destination
    val type: PersonType? = when {
        destination?.hasRoute<Screens.Persons>() == true -> entry?.toRoute<Screens.Persons>()?.type
        destination?.hasRoute<Screens.Person>() == true -> entry?.toRoute<Screens.Person>()?.type
        else -> null
    }
    fun isActive(e: MenuEntry) = destination != null && e.active(destination, type)
    // uma tela grande: pelo menos 800 dp de largura
    val largeScreen = LocalConfiguration.current.screenWidthDp >= 800
    val drawer = rememberDrawerState(DrawerValue.Closed)
    var languageMenu by remember { mutableStateOf(false) }

    val page = @Composable {
        Scaffold(
            topBar = {
                TopAppBar(
                    title = { Text(t("APP.TITLE")) },
                    navigationIcon = {
                        if (u != null && !largeScreen) {
                            IconButton(onClick = { scope.launch { drawer.open() } }) { Icon(Icons.Default.Menu, contentDescription = "menu") }
                        }
                    },
                    colors = TopAppBarDefaults.topAppBarColors(
                        containerColor = MaterialTheme.colorScheme.primary,
                        titleContentColor = MaterialTheme.colorScheme.onPrimary,
                        navigationIconContentColor = MaterialTheme.colorScheme.onPrimary,
                        actionIconContentColor = MaterialTheme.colorScheme.onPrimary,
                    ),
                    actions = {
                        // FR / EN: um menu; a activity é recriada no novo idioma
                        TextButton(onClick = { languageMenu = true }) {
                            Text(language.uppercase(), color = MaterialTheme.colorScheme.onPrimary, fontWeight = FontWeight.Bold)
                        }
                        DropdownMenu(expanded = languageMenu, onDismissRequest = { languageMenu = false }) {
                            for (l in languages) {
                                DropdownMenuItem(text = { Text(l.uppercase()) }, onClick = {
                                    languageMenu = false
                                    changeLanguage(l)
                                })
                            }
                        }
                        if (u != null) {
                            // a sessão é esvaziada; a navegação, que a observa, exibe a tela de login
                            IconButton(onClick = { scope.launch { runCatching { d.session.logout() } } }) {
                                Icon(Icons.AutoMirrored.Filled.ExitToApp, contentDescription = t("APP.LOGOUT"))
                            }
                        }
                    },
                )
            },
        ) { innerPadding ->
            Row(Modifier.padding(innerPadding).consumeWindowInsets(innerPadding).fillMaxSize()) {
                // em uma tela grande: o menu, permanentemente
                if (u != null && largeScreen) {
                    NavigationRail {
                        for (e in entries) {
                            NavigationRailItem(
                                selected = isActive(e),
                                onClick = { nav.goTo(e.route) },
                                icon = { Icon(e.icon, contentDescription = null) },
                                label = { Text(t(e.key)) },
                            )
                        }
                    }
                    VerticalDivider()
                }
                Column(Modifier.weight(1f).fillMaxSize().imePadding()) {
                    SuccessMessage()
                    Column(Modifier.weight(1f)) { content() }
                    ErrorPanel()
                }
            }
        }
    }

    if (u == null || largeScreen) {
        page()
    } else {
        // o drawer: somente quando logado, e somente em uma tela pequena
        ModalNavigationDrawer(
            drawerState = drawer,
            drawerContent = {
                ModalDrawerSheet {
                    // o cabeçalho: quem está logado
                    Column(Modifier.padding(start = 28.dp, top = 16.dp, end = 16.dp, bottom = 10.dp)) {
                        Text(u.name, style = MaterialTheme.typography.titleMedium)
                        SuggestionChip(onClick = {}, label = { Text(u.role.name) })
                    }
                    for (e in entries) {
                        NavigationDrawerItem(
                            label = { Text(t(e.key)) },
                            icon = { Icon(e.icon, contentDescription = null) },
                            selected = isActive(e),
                            onClick = {
                                scope.launch { drawer.close() }
                                nav.goTo(e.route)
                            },
                            modifier = Modifier.padding(horizontal = 12.dp),
                        )
                    }
                }
            },
        ) { page() }
    }
}

// a mensagem de sucesso, no topo
@Composable
private fun SuccessMessage() {
    val messages = LocalDependencies.current.messages
    val success = messages.success ?: return
    ListItem(
        colors = ListItemDefaults.colors(containerColor = Color(0xFFE8F5E9)),
        leadingContent = { Icon(Icons.Default.CheckCircle, contentDescription = null, tint = Color(0xFF2E7D32)) },
        headlineContent = { Text(t(success.key, success.params), color = Color(0xFF1B5E20)) },
        trailingContent = { IconButton(onClick = { messages.clear() }) { Icon(Icons.Default.Close, contentDescription = null) } },
    )
}

// o painel de erro, na parte inferior: sempre visível, mesmo que a tela role
@Composable
private fun ErrorPanel() {
    val messages = LocalDependencies.current.messages
    val error = messages.error ?: return
    ListItem(
        colors = ListItemDefaults.colors(containerColor = Color(0xFFF8D7DA)),
        leadingContent = { Icon(Icons.Default.Warning, contentDescription = null, tint = Color(0xFFC62828)) },
        headlineContent = { Text(t(error.key, error.params), color = Color(0xFFB71C1C)) },
        trailingContent = { IconButton(onClick = { messages.clear() }) { Icon(Icons.Default.Close, contentDescription = null) } },
    )
}
  • linhas 95–97: entradas do menu, conforme o papel ([buildList]: preenche uma lista com [if]);
  • linhas 13–174: uma tela grande, com pelo menos 800 dp de largura: o menu é a [NavigationRail], exibida permanentemente; em um celular na orientação vertical, uma gaveta ([ModalNavigationDrawer]) aberta pelo botão ☰;
  • linhas 228–241: mensagens: sucesso na parte superior, erro na parte inferior.

11.11.2. widgets/InputField.kt

// =========================================================================
// widgets/InputField.kt - um campo de formulário completo
// -------------------------------------------------------------------------
// Rótulo + campo + mensagem de ajuda OU mensagem de erro. Todos os
// formulários da aplicação o usam:
//
//   InputField(label = "PERSONS.LASTNAME_LABEL", maxLength = 20,
//              value = input["lastName"], onChange = { update("lastName", it) },
//              error = submit.errors["lastName"])
//
// É um componente CONTROLADO (veja o exemplo 11): o valor pertence ao
// formulário pai. label, help e error são CHAVES de tradução;
// params, os parâmetros de suas mensagens ({{min}}...).
// =========================================================================
package fr.stahe.rdvmedecins.widgets

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.autofill.ContentType
import androidx.compose.ui.semantics.contentType
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.i18n.t

@Composable
fun InputField(
    label: String,
    value: String,
    onChange: (String) -> Unit,
    error: String? = null,
    help: String? = null,
    params: Map<String, String> = emptyMap(),
    secret: Boolean = false, // uma senha: caracteres ocultos
    maxLength: Int? = null,
    // para o gerenciador de senhas do celular (username, password...)
    autofillType: ContentType? = null,
) {
    val errorMessage = error?.let { t(it, params) }
    val helpMessage = help?.let { t(it, params) }
    OutlinedTextField(
        value = value,
        // o campo recusa os caracteres excedentes
        onValueChange = { v -> if (maxLength == null || v.length <= maxLength) onChange(v) },
        label = { Text(t(label)) },
        singleLine = true,
        isError = errorMessage != null,
        // o erro, caso contrário a ajuda
        supportingText = (errorMessage ?: helpMessage)?.let { m -> { Text(m) } },
        visualTransformation = if (secret) PasswordVisualTransformation() else VisualTransformation.None,
        keyboardOptions = KeyboardOptions(keyboardType = if (secret) KeyboardType.Password else KeyboardType.Text),
        modifier = Modifier
            .fillMaxWidth()
            .padding(bottom = 4.dp)
            .semantics { if (autofillType != null) contentType = autofillType },
    )
}

11.11.3. widgets/PersonFields.kt

// =========================================================================
// widgets/PersonFields.kt - título, nome, sobrenome
// -------------------------------------------------------------------------
// Os campos de identidade, comuns a três formulários: o 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 atualiza um campo:
//     PersonFields(values = input, errors = submit.errors, onChange = ::update)
// =========================================================================
package fr.stahe.rdvmedecins.widgets

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.width
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.i18n.t

val titles = listOf("Mr", "Mme", "Melle")

@Composable
fun PersonFields(values: Map<String, Any?>, errors: Map<String, String>, onChange: (String, String) -> Unit) {
    Column {
        DropdownList(
            label = t("PERSONS.TITLE_LABEL"),
            value = values["title"] as String,
            choices = titles,
            onChange = { onChange("title", it) },
            error = errors["title"]?.let { t(it) },
            modifier = Modifier.width(180.dp),
        )
        InputField(
            label = "PERSONS.FIRSTNAME_LABEL",
            maxLength = 20,
            value = values["firstName"] as String,
            onChange = { onChange("firstName", it) },
            error = errors["firstName"],
        )
        InputField(
            label = "PERSONS.LASTNAME_LABEL",
            maxLength = 20,
            value = values["lastName"] as String,
            onChange = { onChange("lastName", it) },
            error = errors["lastName"],
        )
    }
}

11.11.4. widgets/FormSubmit.kt

// =========================================================================
// widgets/FormSubmit.kt - enviando um formulário ao servidor
// -------------------------------------------------------------------------
// Todos os formulários da aplicação seguem o mesmo padrão do
// exemplo 25: nenhuma regra é verificada no celular (elas vivem
// em UM único 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 essas ações (é o Command do exemplo 23,
// completado com os erros dos campos). Uma tela cria uma por formulário:
//
//     val submit = remember { FormSubmit(messages) }
//     if (submit.send { api.register(input) }) { ... }
//     InputField(..., error = submit.errors["lastName"])
// =========================================================================
package fr.stahe.rdvmedecins.widgets

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import fr.stahe.rdvmedecins.api.ApiError
import fr.stahe.rdvmedecins.state.Messages

class FormSubmit(private val messages: Messages) {
    // o erro de cada campo: uma CHAVE de tradução
    var errors by mutableStateOf(mapOf<String, String>())
        private set

    // os parâmetros das mensagens de erro ({{min}}...), devolvidos pelo servidor
    var params by mutableStateOf(mapOf<String, String>())
        private set
    var inProgress by mutableStateOf(false)
        private set

    // executa o envio; devolve true se foi bem-sucedido. Em caso de ApiError, os
    // erros são exibidos e false é devolvido
    suspend fun send(action: suspend () -> Unit): Boolean {
        if (inProgress) return false // sem envio duplo
        errors = emptyMap()
        params = emptyMap()
        inProgress = true
        try {
            action()
            return true
        } catch (e: ApiError) {
            messages.showApiError(e)
            errors = e.fields
            params = e.params
            return false
        } finally {
            inProgress = false
        }
    }

    // o usuário muda um campo: seu erro desaparece
    fun clearError(field: String) {
        if (field in errors) errors = errors - field
    }
}

O [Command] do Exemplo 23, com os erros de campo adicionados: todos os formulários da aplicação o utilizam.

11.11.5. widgets/Confirmation.kt

// =========================================================================
// widgets/Confirmation.kt - "Are you sure?"
// -------------------------------------------------------------------------
// Tirado do exemplo 16. A mensagem é uma CHAVE de tradução:
//     if (confirmation.confirm("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 nesse caso.
// Uma nova pergunta apaga as mensagens da ação anterior.
// =========================================================================
package fr.stahe.rdvmedecins.widgets

import androidx.compose.material3.AlertDialog
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.graphics.Color
import fr.stahe.rdvmedecins.state.Messages
import fr.stahe.rdvmedecins.i18n.t
import kotlinx.coroutines.CompletableDeferred

class Confirmation(private val messages: Messages) {
    var question by mutableStateOf<String?>(null)
        private set
    private var pending: CompletableDeferred<Boolean>? = null

    suspend fun confirm(key: String): Boolean {
        messages.clear()
        val waiting = CompletableDeferred<Boolean>()
        pending = waiting
        question = key
        try {
            return waiting.await()
        } finally {
            question = null
        }
    }

    fun answer(yes: Boolean) {
        pending?.complete(yes)
    }
}

@Composable
fun rememberConfirmation(messages: Messages): Confirmation = remember { Confirmation(messages) }

@Composable
fun ConfirmDialog(confirmation: Confirmation) {
    val key = confirmation.question ?: return
    AlertDialog(
        onDismissRequest = { confirmation.answer(false) },
        title = { Text(t("CONFIRMATION.TITLE")) },
        text = { Text(t(key)) },
        dismissButton = { TextButton(onClick = { confirmation.answer(false) }) { Text(t("CONFIRMATION.NO")) } },
        confirmButton = {
            Button(
                onClick = { confirmation.answer(true) },
                colors = ButtonDefaults.buttonColors(containerColor = Color(0xFFC62828)),
            ) { Text(t("CONFIRMATION.YES")) }
        },
    )
}

11.11.6. widgets/CaptchaField.kt

// =========================================================================
// widgets/CaptchaField.kt - a imagem do captcha e o campo de entrada
// -------------------------------------------------------------------------
// Um componente de exibição: a imagem (svg), o botão "Another image"
// (onReload), e o campo, CONTROLADO pelo formulário pai (value,
// onChange). A imagem e seu identificador são solicitados ao servidor pela
// tela de login, que precisa deles para enviar a resposta.
// =========================================================================
package fr.stahe.rdvmedecins.widgets

import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Refresh
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.i18n.t

@Composable
fun CaptchaField(svg: String?, value: String, onChange: (String) -> Unit, onReload: () -> Unit, error: String? = null) {
    Column {
        Text(t("CAPTCHA.LABEL"), style = MaterialTheme.typography.bodySmall)
        Row(verticalAlignment = Alignment.CenterVertically) {
            Box(
                contentAlignment = Alignment.Center,
                modifier = Modifier
                    .size(160.dp, 54.dp)
                    .background(Color(0xFFF5F7FA), RoundedCornerShape(6.dp))
                    .border(1.dp, Color(0xFFE0E0E0), RoundedCornerShape(6.dp)),
            ) {
                // description: o que um leitor de tela lê no lugar da imagem
                if (svg != null) SvgImage(svg, height = 50.dp, description = t("CAPTCHA.IMAGE_ALT"))
            }
            TextButton(onClick = onReload) {
                Icon(Icons.Default.Refresh, contentDescription = null)
                Text(t("CAPTCHA.NEW_IMAGE"))
            }
        }
        InputField(label = "CAPTCHA.LABEL", help = "CAPTCHA.HELP", maxLength = 10, value = value, onChange = onChange, error = error)
    }
}

11.11.7. widgets/SvgImage.kt

// =========================================================================
// widgets/SvgImage.kt (tirado dos exemplos, common/SvgImage.kt) - desenhar uma imagem SVG fornecida como texto
// -------------------------------------------------------------------------
// A imagem do captcha é construída pelo servidor, no formato SVG (um texto
// que descreve um desenho). O Android não consegue exibi-la sozinho: a
// biblioteca AndroidSVG a desenha em uma imagem (um Bitmap), que o
// Compose exibe com o componente Image.
// =========================================================================
package fr.stahe.rdvmedecins.widgets

import android.graphics.Bitmap
import android.graphics.Canvas
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.asImageBitmap
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import com.caverock.androidsvg.SVG

@Composable
fun SvgImage(svg: String, modifier: Modifier = Modifier, height: Dp = 50.dp, description: String? = null) {
    // o desenho só é refeito se o texto SVG mudar (remember(svg))
    val image = remember(svg) {
        val document = SVG.getFromString(svg)
        // desenhado 3 vezes maior que seu tamanho "natural": uma imagem nítida
        val scale = 3f
        val docWidth = (document.documentWidth.takeIf { it > 0 } ?: 150f)
        val docHeight = (document.documentHeight.takeIf { it > 0 } ?: 50f)
        val bitmap = Bitmap.createBitmap((docWidth * scale).toInt(), (docHeight * scale).toInt(), Bitmap.Config.ARGB_8888)
        val canvas = Canvas(bitmap)
        canvas.scale(scale, scale)
        document.renderToCanvas(canvas)
        bitmap.asImageBitmap()
    }
    Image(image, contentDescription = description, contentScale = ContentScale.Fit, modifier = modifier.height(height))
}

11.11.8. widgets/DropdownList.kt

// =========================================================================
// widgets/DropdownList.kt (tirado dos exemplos, common/DropdownList.kt) - uma lista suspensa pronta para uso
// -------------------------------------------------------------------------
// O Material 3 para Compose não tem um componente "lista suspensa"
// tudo-em-um: ela é montada a partir de três elementos - ExposedDropdownMenuBox,
// um campo de texto somente leitura e o menu ExposedDropdownMenu. Nós
// a fazemos aqui uma vez por todas (exemplos 05 a 08, 24, 25):
//
//     DropdownList("Country", value = country, choices = listOf("fr", "be", "ch"),
//                  text = { countryNames[it] }, onChange = { country = it })
//
// A função é GENÉRICA (<T>): as opções podem ser strings,
// números, médicos... text diz como EXIBIR uma opção. Uma opção
// pode ser null ("— choose —") se T for um tipo "anulável" (Int?).
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.rdvmedecins.widgets

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.ExposedDropdownMenuAnchorType
import androidx.compose.material3.ExposedDropdownMenuBox
import androidx.compose.material3.ExposedDropdownMenuDefaults
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier

@Composable
fun <T> DropdownList(
    label: String,
    value: T,
    choices: List<T>,
    onChange: (T) -> Unit,
    modifier: Modifier = Modifier,
    text: (T) -> String = { it.toString() },
    // uma mensagem de erro sob o campo (veja os exemplos 07 e 25)
    error: String? = null,
) {
    // o menu está aberto? um state ESPECÍFICO de cada lista suspensa
    var expanded by remember { mutableStateOf(false) }
    ExposedDropdownMenuBox(expanded = expanded, onExpandedChange = { expanded = it }, modifier = modifier) {
        // o campo que exibe a opção atual; menuAnchor o transforma no
        // ponto de ancoragem do menu (tocar nele abre o menu)
        OutlinedTextField(
            value = text(value),
            onValueChange = {},
            readOnly = true,
            singleLine = true,
            label = { Text(label) },
            trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
            isError = error != null,
            supportingText = if (error == null) null else { { Text(error) } },
            modifier = Modifier.menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable).fillMaxWidth(),
        )
        // o menu: uma linha por opção
        ExposedDropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
            for (c in choices) {
                DropdownMenuItem(
                    text = { Text(text(c)) },
                    onClick = {
                        onChange(c)
                        expanded = false
                    },
                )
            }
        }
    }
}

11.11.9. widgets/Tag.kt

// widgets/Tag.kt - uma tag colorida (o "badge" dos outros clientes)
package fr.stahe.rdvmedecins.widgets

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

@Composable
fun Tag(text: String, color: Color) {
    Text(
        text,
        color = Color.White,
        fontSize = 12.sp,
        fontWeight = FontWeight.Bold,
        modifier = Modifier.background(color, RoundedCornerShape(6.dp)).padding(horizontal = 8.dp, vertical = 3.dp),
    )
}

11.11.10. widgets/BookingDialog.kt

// =========================================================================
// widgets/BookingDialog.kt - o diálogo de agendamento de um horário
// -------------------------------------------------------------------------
// Um destino do tipo "dialog" da navegação (Screens.Booking):
// ele é exibido POR CIMA da agenda, fundo acinzentado incluído, e o botão
// Voltar do celular o fecha. Sua rota contém tudo de que ele precisa:
// o médico, o dia, o horário.
// Ele lê a agenda de novo a partir do CACHE (sem requisição: a agenda acabou de ser
// lida) para encontrar o horário nela e verificar se pode ser agendado.
// Após o agendamento: uma mensagem flash, o fechamento e a invalidação
// do cache; a agenda, ainda viva sob o diálogo, lê-se de novo.
// =========================================================================
package fr.stahe.rdvmedecins.widgets

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.ScheduleSlot
import fr.stahe.rdvmedecins.api.ApiError
import fr.stahe.rdvmedecins.api.Person
import fr.stahe.rdvmedecins.api.PersonType
import fr.stahe.rdvmedecins.state.isManager
import fr.stahe.rdvmedecins.state.isPatient
import fr.stahe.rdvmedecins.timeRange
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.navigation.Screens
import fr.stahe.rdvmedecins.pages.scheduleKey
import kotlinx.coroutines.launch

@Composable
fun BookingDialog(route: Screens.Booking, onClose: () -> Unit) {
    val d = LocalDependencies.current
    val u = d.session.user
    var slot by remember { mutableStateOf<ScheduleSlot?>(null) }
    // ADMIN / DOCTOR: os pacientes entre os quais escolher
    var clients by remember { mutableStateOf(listOf<Person>()) }
    var clientId by remember { mutableStateOf<Int?>(null) }
    var sending by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope()

    LaunchedEffect(Unit) {
        try {
            val schedule = d.cache.read(scheduleKey(route.doctorId, route.day)) { d.api.schedule(route.doctorId, route.day) }
            // somente se este horário puder ser agendado por este usuário
            slot = schedule.slots.find { it.id == route.slotId && it.bookable }
            if (slot == null) onClose()
            if (u.isManager) clients = d.cache.read("clients") { d.api.list(PersonType.CLIENTS) }
        } catch (e: ApiError) {
            d.messages.showApiError(e)
        }
    }

    fun confirm() {
        val c = slot ?: return
        scope.launch {
            sending = true
            try {
                d.api.book(route.day, c.id, if (u.isManager) clientId else null)
                d.messages.flash("SCHEDULE.BOOKED")
            } catch (e: ApiError) {
                if (e.key == "ERRORS.CHOOSE_PATIENT") {
                    // nenhum paciente escolhido: o diálogo permanece aberto
                    d.messages.showError(e.key)
                    sending = false
                    return@launch
                }
                // horário ocupado nesse meio tempo, paciente que já tem uma consulta...:
                // a mensagem será exibida na agenda, com o diálogo fechado
                d.messages.flash(e.key, e.params, success = false)
            }
            sending = false
            onClose()
            // o servidor é a referência: a agenda (e a área do paciente) serão lidas de novo
            d.cache.invalidate("my-area")
            d.cache.invalidate("schedule")
        }
    }

    val c = slot ?: return
    Card(Modifier.fillMaxWidth()) {
        Column(Modifier.padding(20.dp)) {
            Text(t("BOOKING_DIALOG.TITLE"), style = MaterialTheme.typography.titleLarge)
            Spacer(Modifier.height(12.dp))
            Text(t("BOOKING_DIALOG.SLOT", mapOf("time" to timeRange(c))))
            Spacer(Modifier.height(12.dp))
            if (u.isPatient) {
                // um paciente marca para si mesmo: sem lista (e o servidor
                // ignoraria de qualquer forma um eventual clientId)
                Text(
                    buildAnnotatedString {
                        append("${t("BOOKING_DIALOG.PATIENT_LABEL")}: ")
                        withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append(u?.name ?: "") }
                    },
                )
            } else {
                val prompt = t("BOOKING_DIALOG.CHOOSE_PATIENT")
                DropdownList(
                    label = t("BOOKING_DIALOG.PATIENT_LABEL"),
                    value = clientId,
                    choices = listOf<Int?>(null) + clients.map { it.id },
                    text = { i -> clients.find { it.id == i }?.label ?: prompt },
                    onChange = { clientId = it },
                    modifier = Modifier.fillMaxWidth(),
                )
            }
            // um erro (nenhum paciente escolhido): o painel de erro da tela está
            // escondido sob o diálogo, nós o repetimos aqui
            d.messages.error?.let { m ->
                Text(t(m.key, m.params), color = androidx.compose.ui.graphics.Color(0xFFC62828), modifier = Modifier.padding(top = 8.dp))
            }
            Spacer(Modifier.height(20.dp))
            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(8.dp, androidx.compose.ui.Alignment.End)) {
                TextButton(onClick = onClose) { Text(t("BOOKING_DIALOG.CANCEL")) }
                Button(onClick = { confirm() }, enabled = !sending) { Text(t("BOOKING_DIALOG.CONFIRM")) }
            }
        }
    }
}
  • linhas 64–70: a agenda, relida no CACHE (sem requisição: ela acabou de ser lida), para encontrar o horário; os pacientes, para um administrador;
  • linhas 76–98: a reserva: uma mensagem pop-up, fechamento da janela e invalidação do cache; a agenda, que permanece ativa sob a janela, é recarregada automaticamente.

11.12. As telas

11.12.1. pages/StartupPage.kt

// =========================================================================
// pages/StartupPage.kt - a primeira tela
// -------------------------------------------------------------------------
// O tempo de perguntar ao servidor, uma única vez, quem está logado (GET
// /api/auth/me: o cookie do token pode ter sido mantido de um uso
// anterior). Logado: a navegação (que observa a sessão) leva à
// página inicial do papel; ninguém: onNobody, a tela de login.
// =========================================================================
package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import fr.stahe.rdvmedecins.LocalDependencies

@Composable
fun StartupPage(onNobody: () -> Unit) {
    val session = LocalDependencies.current.session
    LaunchedEffect(Unit) {
        session.check()
        if (session.user == null) onNobody()
    }
    Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { CircularProgressIndicator() }
}

11.12.2. pages/ErrorPage.kt

// =========================================================================
// pages/ErrorPage.kt - a tela de erro: 403 (papel insuficiente, veja
// navigation/Navigation.kt) ou 404
// =========================================================================
package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.i18n.t

@Composable
fun ErrorPage(code: Int) {
    Column(Modifier.padding(24.dp)) {
        Text("${t("ERROR_PAGE.TITLE")} $code", style = MaterialTheme.typography.headlineMedium, color = Color(0xFFC62828))
        Spacer(Modifier.height(8.dp))
        Text(t(if (code == 403) "ERRORS.FORBIDDEN" else "ERRORS.NOT_FOUND"))
    }
}

11.12.3. pages/LoginPage.kt

// =========================================================================
// pages/LoginPage.kt - a tela de 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: o campo é preenchido previamente (logo após a criação de uma conta).
// Após um login bem-sucedido, esta tela NÃO navega por conta própria: a
// sessão muda, e é a navegação que sai da tela de login
// (veja navigation/Navigation.kt).
// =========================================================================
package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.autofill.ContentType
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.Captcha
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.widgets.CaptchaField
import fr.stahe.rdvmedecins.widgets.InputField
import fr.stahe.rdvmedecins.widgets.FormSubmit
import kotlinx.coroutines.launch

@Composable
fun LoginPage(login: String, onRegister: () -> Unit) {
    val d = LocalDependencies.current
    val submit = remember { FormSubmit(d.messages) }
    // a entrada: um Map, campo -> valor; rememberSaveable: ela sobrevive a uma
    // mudança de idioma (a activity é recriada)
    var input by rememberSaveable { mutableStateOf(mapOf("login" to login, "password" to "", "captcha" to "")) }
    var captcha by remember { mutableStateOf<Captcha?>(null) }
    val scope = rememberCoroutineScope()

    // 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 verifica)
    suspend fun reloadCaptcha() {
        captcha = try {
            d.api.captcha()
        } catch (e: Exception) {
            null // servidor inacessível: o login falhará com uma mensagem clara
        }
    }
    LaunchedEffect(Unit) { reloadCaptcha() }

    fun update(field: String, value: String) {
        input = input + (field to value)
        submit.clearError(field)
    }

    // os dois botões compartilham esta sequência: envio e, em caso
    // de falha, mensagem de erro e NOVA imagem
    fun attempt(action: suspend () -> Unit) {
        scope.launch {
            d.messages.clear()
            if (!submit.send(action)) {
                input = input + ("captcha" to "")
                reloadCaptcha()
            }
        }
    }

    // em caso de sucesso, nada mais a fazer aqui: a navegação muda a tela
    fun logIn() = attempt {
        d.session.login(input.getValue("login").trim(), input.getValue("password"), captcha?.id ?: "", input.getValue("captcha"))
    }

    fun createAccount() = attempt {
        d.api.registrationAccess(captcha?.id ?: "", input.getValue("captcha"))
        onRegister()
    }

    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(16.dp)) {
        Text(t("LOGIN.TITLE"), style = MaterialTheme.typography.headlineSmall)
        Spacer(Modifier.height(12.dp))
        // autofillType: o gerenciador de senhas do celular pode preencher o formulário
        InputField(
            label = "LOGIN.LOGIN_LABEL",
            value = input.getValue("login"),
            onChange = { update("login", it) },
            error = submit.errors["login"],
            autofillType = ContentType.Username,
        )
        InputField(
            label = "LOGIN.PASSWORD_LABEL",
            secret = true,
            value = input.getValue("password"),
            onChange = { update("password", it) },
            error = submit.errors["password"],
            autofillType = ContentType.Password,
        )
        CaptchaField(
            svg = captcha?.svg,
            value = input.getValue("captcha"),
            onChange = { update("captcha", it) },
            onReload = { scope.launch { reloadCaptcha() } },
            error = submit.errors["captcha"],
        )
        Spacer(Modifier.height(8.dp))
        Button(onClick = { logIn() }, enabled = !submit.inProgress, modifier = Modifier.fillMaxWidth()) { Text(t("LOGIN.SUBMIT")) }
        Spacer(Modifier.height(12.dp))
        OutlinedButton(onClick = { createAccount() }, enabled = !submit.inProgress, modifier = Modifier.fillMaxWidth()) {
            Text(t("LOGIN.CREATE_ACCOUNT"))
        }
        Text(
            t("LOGIN.CREATE_ACCOUNT_HELP"),
            textAlign = TextAlign.Center,
            style = MaterialTheme.typography.bodySmall,
            modifier = Modifier.fillMaxWidth().padding(top = 4.dp),
        )
        Spacer(Modifier.height(16.dp))
        DemoAccounts()
    }
}

// as contas de demonstração
@Composable
private fun DemoAccounts() {
    val style = MaterialTheme.typography.bodySmall
    Text(t("LOGIN.DEMO_ACCOUNTS"), style = style, color = Color.DarkGray)
    for ((accounts, key) in listOf(
        "admin" to "LOGIN.DEMO_ADMIN",
        "pelissier, tatou, dupont" to "LOGIN.DEMO_DOCTOR",
        "martin, durand, bistrou, german" to "LOGIN.DEMO_USER",
    )) {
        Text(
            buildAnnotatedString {
                append("• ")
                withStyle(SpanStyle(fontFamily = FontFamily.Monospace)) { append(accounts) }
                append(" - ${t(key)}")
            },
            style = style,
            color = Color.DarkGray,
        )
    }
}
  • linha 32: a entrada, um campo [Map] campo → valor, armazenado por [rememberSaveable]: ela sobrevive a uma troca de idioma;
  • linhas 61–70: uma nova imagem após TODA tentativa: uma imagem é usada apenas uma vez;
  • linha 89: em caso de sucesso, nada mais a fazer: a sessão muda e a navegação sai da tela de login.

11.12.4. pages/SchedulePage.kt

// =========================================================================
// pages/SchedulePage.kt - a tela da agenda
// -------------------------------------------------------------------------
// Três blocos, como nos outros clientes:
//   1. a escolha do médico e do dia;
//   2. a agenda desse médico nesse dia;
//   3. o diálogo de agendamento de um horário: outra rota,
//      Screens.Booking, exibida por cima (veja BookingDialog.kt).
//
// TODO o estado da tela está em sua ROTA: Screens.Schedule(doctorId, day).
// A tela DEDUZ dela o que exibe, e as ações do usuário
// mudam a rota (onView, onBook); o botão Voltar do celular
// fecha o diálogo de agendamento.
//
// O que cada um vê e pode fazer é decidido pelo SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada horário): a tela apenas
// o exibe. Um paciente nem sequer recebe o nome dos outros pacientes.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.background
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDialog
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.Schedule
import fr.stahe.rdvmedecins.api.ScheduleSlot
import fr.stahe.rdvmedecins.api.ApiError
import fr.stahe.rdvmedecins.api.Person
import fr.stahe.rdvmedecins.api.Role
import fr.stahe.rdvmedecins.api.PersonType
import fr.stahe.rdvmedecins.today
import fr.stahe.rdvmedecins.fromMillis
import fr.stahe.rdvmedecins.isValidDate
import fr.stahe.rdvmedecins.timeRange
import fr.stahe.rdvmedecins.i18n.LocalTranslations
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.longDate
import fr.stahe.rdvmedecins.toMillis
import fr.stahe.rdvmedecins.widgets.Tag
import fr.stahe.rdvmedecins.widgets.ConfirmDialog
import fr.stahe.rdvmedecins.widgets.DropdownList
import fr.stahe.rdvmedecins.widgets.rememberConfirmation
import kotlinx.coroutines.launch

// a chave da agenda de um médico em um dado dia, no cache
fun scheduleKey(doctorId: Int?, day: String) = "schedule/$doctorId/$day"

@Composable
fun SchedulePage(
    doctorId: Int?,
    day: String?, // como está na rota: talvez inválido
    onView: (Int?, String) -> Unit,
    onBook: (Int?, String, Int) -> Unit,
    onMyArea: () -> Unit,
) {
    val d = LocalDependencies.current
    val user = d.session.user
    val confirmation = rememberConfirmation(d.messages)
    val scope = rememberCoroutineScope()
    // o dia: o da rota se for válido, caso contrário hoje
    val invalidDay = day != null && !isValidDate(day)
    val theDay = if (day != null && !invalidDay) day else today()

    var doctors by remember { mutableStateOf(listOf<Person>()) }
    // a agenda (null enquanto não chegou, ou se não existir)
    var schedule by remember { mutableStateOf<Schedule?>(null) }
    var loading by remember { mutableStateOf(false) }

    // os médicos: lidos uma vez (cache); um erro é exibido na parte inferior da tela
    LaunchedEffect(Unit) {
        try {
            doctors = d.cache.read("doctors") { d.api.list(PersonType.DOCTORS) }
        } catch (e: ApiError) {
            d.messages.showApiError(e)
        }
        if (invalidDay) d.messages.showError("ERRORS.INVALID_DATE")
    }

    // a agenda: lida de novo se a rota mudar (outro médico, outro dia) ou se o
    // cache for invalidado (agendamento, cancelamento: d.cache.version muda).
    // Sem médico na rota, um DOCTOR vê a agenda DELE (o servidor a
    // encontra a partir do token); os outros não veem nada
    val hasSchedule = !invalidDay && (doctorId != null || user?.role == Role.DOCTOR)
    LaunchedEffect(doctorId, theDay, d.cache.version) {
        if (!hasSchedule) {
            schedule = null
            return@LaunchedEffect
        }
        loading = true
        try {
            schedule = d.cache.read(scheduleKey(doctorId, theDay)) { d.api.schedule(doctorId, theDay) }
        } catch (e: ApiError) {
            schedule = null
            d.messages.showApiError(e)
        }
        loading = false
    }

    // o servidor é a referência: após um cancelamento, a agenda é lida de novo
    // (e a área do paciente, que mostra sua consulta)
    fun cancel(c: ScheduleSlot) {
        val appointmentId = c.appointmentId ?: return
        scope.launch {
            if (!confirmation.confirm("SCHEDULE.CANCEL_CONFIRM")) return@launch
            try {
                d.api.cancelAppointment(appointmentId)
                d.messages.showSuccess("SCHEDULE.CANCELLED")
            } catch (e: ApiError) {
                d.messages.showApiError(e)
            }
            d.cache.invalidate("my-area")
            d.cache.invalidate("schedule")
        }
    }

    val a = schedule
    // o médico exibido: o da rota, ou o da agenda recebida (DOCTOR)
    val shownId = doctorId ?: a?.doctor?.id
    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(12.dp)) {
        // 1. a escolha do médico e do dia. key: se a rota mudar, o
        // formulário é recriado e recomeça a partir dos novos valores
        androidx.compose.runtime.key(shownId, theDay) {
            DoctorDayPicker(doctors = doctors, doctorId = shownId, day = theDay, onView = onView)
        }
        // paciente que já tem uma consulta futura: por que não há botão "Book"
        a?.info?.let { info ->
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFE1F5FE)), modifier = Modifier.padding(top = 8.dp)) {
                ListItem(
                    colors = androidx.compose.material3.ListItemDefaults.colors(containerColor = Color.Transparent),
                    headlineContent = { Text(t(info)) },
                    trailingContent = { TextButton(onClick = onMyArea) { Text(t("APP.MENU_MY_AREA")) } },
                )
            }
        }
        Spacer(Modifier.height(8.dp))
        when {
            loading && a == null -> Box(Modifier.fillMaxWidth().padding(24.dp), contentAlignment = Alignment.Center) { CircularProgressIndicator() }
            a != null -> ScheduleView(
                schedule = a,
                // "Book" muda a ROTA: o diálogo de agendamento abre
                onBook = { c -> onBook(shownId, theDay, c.id) },
                onCancel = ::cancel,
            )
            else -> Text(t("SCHEDULE.EMPTY_STATE"), Modifier.padding(16.dp))
        }
    }
    ConfirmDialog(confirmation)
}

// -------------------------------------------------------------------------
// 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 da rota.
// -------------------------------------------------------------------------
@Composable
private fun DoctorDayPicker(doctors: List<Person>, doctorId: Int?, day: String, onView: (Int?, String) -> Unit) {
    var id by rememberSaveable { mutableStateOf(doctorId) }
    var theDay by rememberSaveable { mutableStateOf(day) }
    var calendar by remember { mutableStateOf(false) }
    val language = LocalTranslations.current.language
    // o médico escolhido deve estar na lista (caso contrário: nenhum)
    val knownId = id.takeIf { i -> doctors.any { it.id == i } }
    // t() é uma função @Composable: traduzimos ANTES do lambda de texto, que não é uma
    val prompt = t("DOCTOR_DAY_PICKER.CHOOSE_DOCTOR")
    Card(Modifier.fillMaxWidth()) {
        Column(Modifier.padding(12.dp)) {
            DropdownList(
                label = t("DOCTOR_DAY_PICKER.DOCTOR_LABEL"),
                value = knownId,
                choices = listOf<Int?>(null) + doctors.map { it.id },
                text = { i -> doctors.find { it.id == i }?.label ?: prompt },
                onChange = { id = it },
                modifier = Modifier.fillMaxWidth(),
            )
            Spacer(Modifier.height(8.dp))
            // o dia: um campo somente leitura; tocá-lo abre o calendário
            Box {
                OutlinedTextField(
                    value = longDate(theDay, language),
                    onValueChange = {},
                    readOnly = true,
                    label = { Text(t("DOCTOR_DAY_PICKER.DAY_LABEL")) },
                    trailingIcon = { Icon(Icons.Default.DateRange, contentDescription = t("DOCTOR_DAY_PICKER.CHOOSE_DAY")) },
                    modifier = Modifier.fillMaxWidth(),
                )
                // uma superfície transparente, sobre o campo, que recebe o toque
                Box(Modifier.matchParentSize().clickable { calendar = true })
            }
            Spacer(Modifier.height(12.dp))
            Button(onClick = { onView(knownId, theDay) }, enabled = knownId != null, modifier = Modifier.fillMaxWidth()) {
                Text(t("DOCTOR_DAY_PICKER.VIEW_SCHEDULE"))
            }
        }
    }
    if (calendar) {
        val state = rememberDatePickerState(initialSelectedDateMillis = toMillis(theDay))
        DatePickerDialog(
            onDismissRequest = { calendar = false },
            // os textos OK / Cancelar do Android, no idioma da aplicação
            confirmButton = {
                TextButton(onClick = {
                    state.selectedDateMillis?.let { theDay = fromMillis(it) }
                    calendar = false
                }) { Text(stringResource(android.R.string.ok)) }
            },
            dismissButton = { TextButton(onClick = { calendar = false }) { Text(stringResource(android.R.string.cancel)) } },
        ) { DatePicker(state = state) }
    }
}

// -------------------------------------------------------------------------
// 2. a agenda
// -------------------------------------------------------------------------
@Composable
private fun ScheduleView(schedule: Schedule, onBook: (ScheduleSlot) -> Unit, onCancel: (ScheduleSlot) -> Unit) {
    val language = LocalTranslations.current.language
    Card(Modifier.fillMaxWidth()) {
        Column(Modifier.padding(vertical = 8.dp)) {
            ListItem(
                headlineContent = { Text("${t("SCHEDULE.TITLE_PREFIX")} ${longDate(schedule.day, language)}", style = MaterialTheme.typography.titleMedium) },
                supportingContent = { Text(schedule.doctor.label) },
            )
            if (schedule.slots.isEmpty()) Text(t("SCHEDULE.NO_SLOTS"), Modifier.padding(16.dp))
            for (c in schedule.slots) {
                HorizontalDivider()
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    modifier = Modifier
                        .fillMaxWidth()
                        // os horários disponíveis para agendamento são levemente coloridos
                        .background(if (c.bookable) Color(0xFFE8F5E9) else Color.Transparent)
                        .padding(horizontal = 12.dp, vertical = 6.dp),
                ) {
                    Text(timeRange(c), fontWeight = FontWeight.Medium, modifier = Modifier.width(96.dp))
                    Box(Modifier.weight(1f)) {
                        when {
                            c.free -> Tag(t("SCHEDULE.FREE"), Color(0xFF2E7D32))
                            c.patient != null -> Tag(c.patient.label, if (c.mine) Color(0xFF3F51B5) else Color(0xFF757575))
                            else -> Tag(t("SCHEDULE.BOOKED_BY_OTHER"), Color(0xFF757575))
                        }
                    }
                    when {
                        c.bookable -> OutlinedButton(onClick = { onBook(c) }) { Text(t("SCHEDULE.BOOK")) }
                        c.appointmentId != null -> OutlinedButton(
                            onClick = { onCancel(c) },
                            colors = ButtonDefaults.outlinedButtonColors(contentColor = Color(0xFFC62828)),
                        ) { Text(t("SCHEDULE.CANCEL_APPOINTMENT")) }
                    }
                }
            }
        }
    }
}
  • linha 91: a chave da agenda no cache;
  • linhas 115–117: médicos, lidos uma única vez (cache);
  • linhas 129–136: a agenda, relida se a rota mudar ou se o cache for invalidado;
  • linhas 149–157: cancelamento: confirmação, requisição, invalidação do cache;
  • linhas 200–230: seleção do médico e do dia; o dia é um campo somente leitura, coberto por uma sobreposição transparente que abre o calendário;
  • linhas 259–274: a agenda: o que cada usuário vê e pode fazer é determinado pelo SERVIDOR.

11.12.5. pages/PatientAreaPage.kt

// =========================================================================
// pages/PatientAreaPage.kt - "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 tiver uma, com o meio de cancelá-la.
// =========================================================================
@file:OptIn(ExperimentalLayoutApi::class)

package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.KeyboardArrowRight
import androidx.compose.material.icons.filled.AccountCircle
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Card
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.ApiError
import fr.stahe.rdvmedecins.api.MyArea
import fr.stahe.rdvmedecins.timeRange
import fr.stahe.rdvmedecins.i18n.LocalTranslations
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.longDate
import fr.stahe.rdvmedecins.widgets.ConfirmDialog
import fr.stahe.rdvmedecins.widgets.rememberConfirmation
import kotlinx.coroutines.launch

@Composable
fun PatientAreaPage(onMyAccount: () -> Unit, onSchedule: (Int?, String?) -> Unit) {
    val d = LocalDependencies.current
    val language = LocalTranslations.current.language
    val confirmation = rememberConfirmation(d.messages)
    val scope = rememberCoroutineScope()
    var area by remember { mutableStateOf<MyArea?>(null) }

    LaunchedEffect(d.cache.version) {
        try {
            area = d.cache.read("my-area") { d.api.myArea() }
        } catch (e: ApiError) {
            d.messages.showApiError(e)
        }
    }

    fun cancel(appointmentId: Int) {
        scope.launch {
            if (!confirmation.confirm("SCHEDULE.CANCEL_CONFIRM")) return@launch
            try {
                d.api.cancelAppointment(appointmentId)
                d.messages.showSuccess("SCHEDULE.CANCELLED")
            } catch (e: ApiError) {
                d.messages.showApiError(e)
            }
            // a área E as agendas mudaram
            d.cache.invalidate("my-area")
            d.cache.invalidate("schedule")
        }
    }

    val e = area
    if (e == null) {
        Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { CircularProgressIndicator() }
        return
    }
    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(12.dp)) {
        Text(t("AREA.HELLO", mapOf("name" to e.patient.label)), style = MaterialTheme.typography.headlineSmall, modifier = Modifier.padding(4.dp))
        Option(Icons.Default.AccountCircle, t("AREA.MANAGE_ACCOUNT"), t("AREA.MANAGE_ACCOUNT_HELP"), onMyAccount)
        Option(Icons.Default.DateRange, t("AREA.VIEW_SCHEDULE"), t("AREA.VIEW_SCHEDULE_HELP")) { onSchedule(null, null) }
        Spacer(Modifier.height(8.dp))
        Card(Modifier.fillMaxWidth()) {
            Column(Modifier.padding(12.dp)) {
                Text(t("AREA.MY_APPOINTMENT"), style = MaterialTheme.typography.titleMedium)
                // normalmente apenas uma (regra "uma consulta futura por vez"),
                // mas a tela pode exibir várias
                for (appt in e.appointments) {
                    Spacer(Modifier.height(8.dp))
                    Text("${longDate(appt.day, language)}, ${timeRange(appt.slot)}", fontWeight = FontWeight.SemiBold)
                    Text(appt.doctor.label)
                    FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
                        // a agenda do médico nesse dia: o paciente vê seu nome nela
                        TextButton(onClick = { onSchedule(appt.doctor.id, appt.day) }) { Text(t("AREA.SEE_IN_SCHEDULE")) }
                        OutlinedButton(
                            onClick = { cancel(appt.id) },
                            colors = ButtonDefaults.outlinedButtonColors(contentColor = Color(0xFFC62828)),
                        ) { Text(t("AREA.CANCEL_APPOINTMENT")) }
                    }
                }
                if (e.appointments.isEmpty()) Text(t("AREA.NO_APPOINTMENT"), color = Color.Gray, modifier = Modifier.padding(top = 8.dp))
            }
        }
    }
    ConfirmDialog(confirmation)
}

// um "card" de opção, em que se toca para abrir uma tela
@Composable
private fun Option(icon: ImageVector, title: String, help: String, onClick: () -> Unit) {
    Card(Modifier.fillMaxWidth().padding(vertical = 4.dp).clickable(onClick = onClick)) {
        ListItem(
            leadingContent = { Icon(icon, contentDescription = null, tint = MaterialTheme.colorScheme.primary, modifier = Modifier.size(32.dp)) },
            headlineContent = { Text(title, style = MaterialTheme.typography.titleMedium) },
            supportingContent = { Text(help) },
            trailingContent = { Icon(Icons.AutoMirrored.Filled.KeyboardArrowRight, contentDescription = null) },
        )
    }
}

11.12.6. pages/PersonsConfig.kt

// =========================================================================
// pages/PersonsConfig.kt - médicos ou clientes?
// -------------------------------------------------------------------------
// As telas de gerenciamento dos médicos e dos clientes são IDÊNTICAS: mesma
// lista, mesmo formulário. Nós as escrevemos UMA VEZ (PersonsPage.kt,
// PersonFormPage.kt); só mudam o endereço da API e as
// chaves dos rótulos, descritos aqui. A rota passa o tipo a cada tela.
// =========================================================================
package fr.stahe.rdvmedecins.pages

import fr.stahe.rdvmedecins.api.Person
import fr.stahe.rdvmedecins.api.PersonType

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

// as chaves de um tipo: escritas uma só vez, graças ao prefixo "DOCTORS." ou "CLIENTS."
fun keys(type: PersonType): PersonKeys {
    val p = if (type == PersonType.DOCTORS) "DOCTORS" else "CLIENTS"
    return PersonKeys(
        title = "$p.TITLE",
        add = "$p.ADD",
        edit = "$p.EDIT",
        empty = "$p.EMPTY",
        confirmDelete = "$p.DELETE_CONFIRM",
        added = "$p.ADDED",
        updated = "$p.UPDATED",
        deleted = "$p.DELETED",
        notFound = if (type == PersonType.DOCTORS) "ERRORS.DOCTOR_NOT_FOUND" else "ERRORS.PATIENT_NOT_FOUND",
    )
}

// {{name}} e {{login}} das mensagens "added / updated / deleted"
fun messageParams(p: Person) = mapOf("name" to "${p.firstName} ${p.lastName}", "login" to (p.login ?: ""))

11.12.7. pages/PersonsPage.kt

// =========================================================================
// pages/PersonsPage.kt - a lista dos médicos OU dos clientes (ADMIN)
// -------------------------------------------------------------------------
// Uma única tela para ambos: o tipo (médicos ou clientes) chega pela
// rota; os rótulos específicos de cada um estão em PersonsConfig.kt.
// 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.
// A lista é uma LazyColumn: apenas as linhas visíveis são construídas.
// =========================================================================
package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.material.icons.filled.Edit
import androidx.compose.material.icons.outlined.Delete
import androidx.compose.material3.Card
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.ExtendedFloatingActionButton
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.ApiError
import fr.stahe.rdvmedecins.api.Person
import fr.stahe.rdvmedecins.api.PersonType
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.widgets.ConfirmDialog
import fr.stahe.rdvmedecins.widgets.rememberConfirmation
import kotlinx.coroutines.launch

@Composable
fun PersonsPage(type: PersonType, onAdd: () -> Unit, onEdit: (Int) -> Unit) {
    val d = LocalDependencies.current
    val c = keys(type)
    val confirmation = rememberConfirmation(d.messages)
    val scope = rememberCoroutineScope()
    // null: ainda não carregado
    var list by remember(type) { mutableStateOf<List<Person>?>(null) }
    var failed by remember(type) { mutableStateOf(false) }

    // lido de novo se o tipo mudar ou se o cache for invalidado
    LaunchedEffect(type, d.cache.version) {
        try {
            list = d.cache.read(type.path) { d.api.list(type) }
        } catch (e: ApiError) {
            failed = true
            d.messages.showApiError(e)
        }
    }

    fun delete(p: Person) {
        scope.launch {
            if (!confirmation.confirm(c.confirmDelete)) return@launch
            try {
                d.api.delete(type, p.id)
                d.messages.showSuccess(c.deleted, messageParams(p))
            } catch (e: ApiError) {
                // um médico que ainda tem consultas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
                d.messages.showApiError(e)
            }
            d.cache.invalidate(type.path)
        }
    }

    Box(Modifier.fillMaxSize()) {
        val l = list
        if (l == null) {
            // ainda não carregado (ou o carregamento falhou: a mensagem está na parte inferior da tela)
            if (!failed) CircularProgressIndicator(Modifier.align(Alignment.Center))
        } else {
            // um espaço na parte inferior, para não esconder a última linha sob o botão flutuante
            LazyColumn(contentPadding = PaddingValues(start = 8.dp, top = 8.dp, end = 8.dp, bottom = 88.dp)) {
                item { Text(t(c.title), style = MaterialTheme.typography.headlineSmall, modifier = Modifier.padding(8.dp)) }
                if (l.isEmpty()) item { ListItem(headlineContent = { Text(t(c.empty)) }) }
                // uma linha por pessoa; key: a identidade da linha
                items(l, key = { it.id }) { p ->
                    Card(Modifier.padding(vertical = 4.dp)) {
                        ListItem(
                            leadingContent = {
                                Box(Modifier.size(40.dp).background(MaterialTheme.colorScheme.primaryContainer, CircleShape), contentAlignment = Alignment.Center) {
                                    Text("${p.firstName.first()}${p.lastName.first()}")
                                }
                            },
                            headlineContent = { Text(p.label) },
                            supportingContent = { Text(p.login ?: "", fontFamily = FontFamily.Monospace) },
                            trailingContent = {
                                Row {
                                    IconButton(onClick = { onEdit(p.id) }) { Icon(Icons.Default.Edit, contentDescription = t("PERSONS.EDIT")) }
                                    IconButton(onClick = { delete(p) }) {
                                        Icon(Icons.Outlined.Delete, contentDescription = t("PERSONS.DELETE"), tint = Color(0xFFC62828))
                                    }
                                }
                            },
                        )
                    }
                }
            }
        }
        ExtendedFloatingActionButton(
            onClick = onAdd,
            icon = { Icon(Icons.Default.Add, contentDescription = null) },
            text = { Text(t(c.add)) },
            modifier = Modifier.align(Alignment.BottomEnd).padding(16.dp),
        )
    }
    ConfirmDialog(confirmation)
}
  • linha 97: uma [LazyColumn]: somente as linhas visíveis são geradas (equivalente ao [ListView.builder] do [Flutter]); [contentPadding] deixa espaço abaixo da última linha para o botão flutuante;
  • linha 124: o botão flutuante ([ExtendedFloatingActionButton]) que adiciona uma pessoa.

11.12.8. pages/PersonFormPage.kt

// =========================================================================
// pages/PersonFormPage.kt - criação OU atualização de um médico
// ou de um cliente (ADMIN)
// -------------------------------------------------------------------------
//     Screens.Person(DOCTORS)          -> criação (sem id)
//     Screens.Person(DOCTORS, id = 3)  -> atualização
// Dois componentes:
//   - 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/FormSubmit.kt).
// A VERSÃO lida com o registro volta com a atualização: se outro
// ADMIN o atualizou nesse meio tempo, o servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================
@file:OptIn(ExperimentalLayoutApi::class)

package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Button
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.FormData
import fr.stahe.rdvmedecins.api.ApiError
import fr.stahe.rdvmedecins.api.PersonType
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.widgets.InputField
import fr.stahe.rdvmedecins.widgets.PersonFields
import fr.stahe.rdvmedecins.widgets.FormSubmit
import kotlinx.coroutines.launch

private val empty = mapOf("title" to "Mr", "firstName" to "", "lastName" to "", "login" to "", "password" to "")

@Composable
fun PersonFormPage(type: PersonType, id: Int?, onList: () -> Unit) {
    val d = LocalDependencies.current
    // os valores iniciais: vazios (criação), ou os do registro lido
    var initial by remember { mutableStateOf<FormData?>(if (id == null) empty else null) }

    if (id != null) {
        LaunchedEffect(id) {
            try {
                // SEM cache: o registro deve estar atualizado (caso contrário o formulário
                // começaria com uma versão desatualizada: 409 CONCURRENT_UPDATE)
                val p = d.api.read(type, id)
                initial = mapOf("title" to p.title, "firstName" to p.firstName, "lastName" to p.lastName, "login" to (p.login ?: ""), "password" to "", "version" to p.version)
            } catch (e: ApiError) {
                // registro que não existe (excluído nesse meio tempo...): volta para a lista
                d.messages.flash(e.key, e.params, success = false)
                onList()
            }
        }
    }
    val start = initial
    if (start == null) {
        Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { CircularProgressIndicator() }
    } else {
        Form(type, id, start, onList)
    }
}

// o formulário em si
@Composable
private fun Form(type: PersonType, id: Int?, initial: FormData, onList: () -> Unit) {
    val d = LocalDependencies.current
    val c = keys(type)
    val creating = id == null
    val submit = remember { FormSubmit(d.messages) }
    // uma CÓPIA editável dos valores iniciais
    var input by rememberSaveable { mutableStateOf(initial) }
    val scope = rememberCoroutineScope()

    fun update(field: String, value: String) {
        input = input + (field to value)
        submit.clearError(field)
    }

    fun save() {
        scope.launch {
            val succeeded = submit.send {
                val p = if (id == null) d.api.add(type, input) else d.api.update(type, id, input)
                d.messages.flash(if (creating) c.added else c.updated, messageParams(p))
            }
            val key = d.messages.error?.key
            if (succeeded) {
                d.cache.invalidate(type.path) // a lista mudou
                onList()
            } else if (key == c.notFound) {
                // excluído nesse meio tempo por outro ADMIN: volta para a lista
                d.messages.flash(key, success = false)
                onList()
            }
        }
    }

    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(16.dp)) {
        Text(t(if (creating) c.add else c.edit), style = MaterialTheme.typography.headlineSmall)
        Spacer(Modifier.height(8.dp))
        PersonFields(values = input, errors = submit.errors, onChange = ::update)
        Spacer(Modifier.height(16.dp))
        Text(t("PERSONS.ACCOUNT_SECTION"), style = MaterialTheme.typography.titleSmall)
        InputField(
            label = "PERSONS.LOGIN_LABEL",
            maxLength = 30,
            value = input["login"] as String,
            onChange = { update("login", it) },
            error = submit.errors["login"],
            help = if (creating) "PERSONS.LOGIN_HELP_CREATE" else "PERSONS.LOGIN_HELP_EDIT",
        )
        // nunca preenchido previamente: a senha nunca volta do servidor
        InputField(
            label = "PERSONS.PASSWORD_LABEL",
            secret = true,
            maxLength = 72,
            value = input["password"] as String,
            onChange = { update("password", it) },
            error = submit.errors["password"],
            params = submit.params,
            help = if (creating) "PERSONS.PASSWORD_HELP_CREATE" else "PERSONS.PASSWORD_HELP_EDIT",
        )
        Spacer(Modifier.height(16.dp))
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            Button(onClick = { save() }, enabled = !submit.inProgress) { Text(t("PERSONS.SAVE")) }
            OutlinedButton(onClick = onList) { Text(t("PERSONS.BACK")) }
        }
    }
}

11.12.9. pages/RegisterPage.kt

// =========================================================================
// pages/RegisterPage.kt - "Create a patient account"
// -------------------------------------------------------------------------
// 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). A tela o verifica assim que abre (GET
// /api/register/access): sem passe, volta para o login.
// Mesmos campos do formulário do ADMIN, mas o login e a
// senha são obrigatórios, com confirmação.
// =========================================================================
@file:OptIn(ExperimentalLayoutApi::class)

package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.autofill.ContentType
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.widgets.InputField
import fr.stahe.rdvmedecins.widgets.PersonFields
import fr.stahe.rdvmedecins.widgets.FormSubmit
import kotlinx.coroutines.launch

// tamanho mínimo de uma senha escolhida por um paciente: mesmo valor
// do servidor (que também envia {min} com o erro PASSWORD_TOO_SHORT)
const val PASSWORD_MIN = "6"

@Composable
fun RegisterPage(onLogin: (String) -> Unit) {
    val d = LocalDependencies.current
    val submit = remember { FormSubmit(d.messages) }
    var input by rememberSaveable {
        mutableStateOf(mapOf("title" to "Mr", "firstName" to "", "lastName" to "", "login" to "", "password" to "", "confirmation" to ""))
    }
    val scope = rememberCoroutineScope()

    // o guard ESPECÍFICO desta tela: sem passe, volta para o login
    LaunchedEffect(Unit) {
        val valid = runCatching { d.api.registrationAccessStatus() }.getOrDefault(false)
        if (!valid) {
            d.messages.flash("ERRORS.CAPTCHA_BEFORE_ACCOUNT", success = false)
            onLogin("")
        }
    }

    fun update(field: String, value: String) {
        input = input + (field to value)
        submit.clearError(field)
    }

    fun create() {
        scope.launch {
            var login = ""
            val succeeded = submit.send { login = d.api.register(input) }
            if (succeeded) {
                // volta para a tela de login, login preenchido previamente
                d.messages.flash("REGISTRATION.DONE", mapOf("login" to login))
                onLogin(login)
            } else if (d.messages.error?.key == "ERRORS.CAPTCHA_BEFORE_ACCOUNT") {
                // passe expirado (15 minutos): volta para o captcha
                d.messages.flash("ERRORS.CAPTCHA_BEFORE_ACCOUNT", success = false)
                onLogin("")
            }
        }
    }

    // os parâmetros da mensagem de ajuda E dos erros de senha
    val passwordParams = mapOf("min" to PASSWORD_MIN) + submit.params
    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(16.dp)) {
        Text(t("REGISTRATION.TITLE"), style = MaterialTheme.typography.headlineSmall)
        Text(t("REGISTRATION.INTRO"), color = Color.Gray)
        Spacer(Modifier.height(8.dp))
        PersonFields(values = input, errors = submit.errors, onChange = ::update)
        Spacer(Modifier.height(16.dp))
        Text(t("PERSONS.ACCOUNT_SECTION"), style = MaterialTheme.typography.titleSmall)
        InputField(
            label = "PERSONS.LOGIN_LABEL",
            maxLength = 30,
            value = input.getValue("login"),
            onChange = { update("login", it) },
            error = submit.errors["login"],
            help = "REGISTRATION.LOGIN_HELP",
            autofillType = ContentType.NewUsername,
        )
        InputField(
            label = "PERSONS.PASSWORD_LABEL",
            secret = true,
            maxLength = 72,
            value = input.getValue("password"),
            onChange = { update("password", it) },
            error = submit.errors["password"],
            params = passwordParams,
            help = "REGISTRATION.PASSWORD_HELP",
            autofillType = ContentType.NewPassword,
        )
        InputField(
            label = "ACCOUNT.CONFIRMATION_LABEL",
            secret = true,
            maxLength = 72,
            value = input.getValue("confirmation"),
            onChange = { update("confirmation", it) },
            error = submit.errors["confirmation"],
        )
        Spacer(Modifier.height(16.dp))
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            Button(onClick = { create() }, enabled = !submit.inProgress) { Text(t("REGISTRATION.SUBMIT")) }
            OutlinedButton(onClick = { onLogin("") }) { Text(t("REGISTRATION.BACK_TO_LOGIN")) }
        }
    }
}

11.12.10. pages/MyAccountPage.kt

// =========================================================================
// pages/MyAccountPage.kt - "Manage 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.
// =========================================================================
@file:OptIn(ExperimentalLayoutApi::class)

package fr.stahe.rdvmedecins.pages

import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Card
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedCard
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.rdvmedecins.LocalDependencies
import fr.stahe.rdvmedecins.api.ApiError
import fr.stahe.rdvmedecins.api.MyAccount
import fr.stahe.rdvmedecins.i18n.t
import fr.stahe.rdvmedecins.widgets.InputField
import fr.stahe.rdvmedecins.widgets.PersonFields
import fr.stahe.rdvmedecins.widgets.FormSubmit
import fr.stahe.rdvmedecins.widgets.ConfirmDialog
import fr.stahe.rdvmedecins.widgets.rememberConfirmation
import kotlinx.coroutines.launch

@Composable
fun MyAccountPage(onMyArea: () -> Unit) {
    val d = LocalDependencies.current
    // lida de novo a cada visita, sem cache: sua versão deve estar atualizada
    var account by remember { mutableStateOf<MyAccount?>(null) }
    LaunchedEffect(Unit) {
        try {
            account = d.api.myAccount()
        } catch (e: ApiError) {
            d.messages.showApiError(e)
        }
    }
    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(12.dp)) {
        val c = account
        if (c == null) {
            Box(Modifier.fillMaxWidth().padding(24.dp), contentAlignment = Alignment.Center) { CircularProgressIndicator() }
        } else {
            EditAccount(c, onMyArea)
        }
        Spacer(Modifier.height(12.dp))
        DeleteAccount()
    }
}

// -------------------------------------------------------------------------
// 1. a atualização
// -------------------------------------------------------------------------
@Composable
private fun EditAccount(account: MyAccount, onMyArea: () -> Unit) {
    val d = LocalDependencies.current
    val submit = remember { FormSubmit(d.messages) }
    val scope = rememberCoroutineScope()
    var input by rememberSaveable {
        mutableStateOf(
            mapOf<String, Any?>(
                "title" to account.title,
                "firstName" to account.firstName,
                "lastName" to account.lastName,
                "login" to account.login,
                "password" to "",
                "confirmation" to "",
                "currentPassword" to "",
                "version" to account.version,
            ),
        )
    }

    fun update(field: String, value: String) {
        input = input + (field to value)
        submit.clearError(field)
    }

    fun save() {
        scope.launch {
            val succeeded = submit.send {
                // o servidor emitiu um NOVO token (nome, login): a barra superior deve acompanhar
                d.session.update(d.api.updateMyAccount(input))
                d.messages.flash("MY_ACCOUNT.UPDATED")
            }
            if (succeeded) {
                d.cache.invalidate("my-area")
                onMyArea()
            } else {
                // nunca uma senha deixada no campo após um envio recusado;
                // o valor é alterado SEM passar por update(), para não
                // apagar o erro que o servidor acabou de associar a ele
                input = input + ("currentPassword" to "")
            }
        }
    }

    Card(Modifier.fillMaxWidth()) {
        Column(Modifier.padding(16.dp)) {
            Text(t("MY_ACCOUNT.TITLE"), style = MaterialTheme.typography.titleLarge)
            PersonFields(values = input, errors = submit.errors, onChange = ::update)
            Spacer(Modifier.height(12.dp))
            Text(t("PERSONS.ACCOUNT_SECTION"), style = MaterialTheme.typography.titleSmall)
            InputField("PERSONS.LOGIN_LABEL", input["login"] as String, { update("login", it) }, submit.errors["login"], maxLength = 30)
            InputField(
                label = "MY_ACCOUNT.NEW_PASSWORD_LABEL",
                secret = true,
                maxLength = 72,
                value = input["password"] as String,
                onChange = { update("password", it) },
                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,
                onChange = { update("confirmation", it) },
                error = submit.errors["confirmation"],
            )
            InputField(
                label = "MY_ACCOUNT.CURRENT_PASSWORD_LABEL",
                secret = true,
                maxLength = 72,
                value = input["currentPassword"] as String,
                onChange = { update("currentPassword", it) },
                error = submit.errors["currentPassword"],
                help = "MY_ACCOUNT.CURRENT_PASSWORD_HELP",
            )
            Spacer(Modifier.height(8.dp))
            FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
                Button(onClick = { save() }, enabled = !submit.inProgress) { Text(t("PERSONS.SAVE")) }
                OutlinedButton(onClick = onMyArea) { Text(t("MY_ACCOUNT.BACK")) }
            }
        }
    }
}

// -------------------------------------------------------------------------
// 2. a exclusão: um formulário com um único campo
// -------------------------------------------------------------------------
@Composable
private fun DeleteAccount() {
    val d = LocalDependencies.current
    val submit = remember { FormSubmit(d.messages) }
    val confirmation = rememberConfirmation(d.messages)
    val scope = rememberCoroutineScope()
    var currentPassword by remember { mutableStateOf("") }

    fun delete() {
        scope.launch {
            if (!confirmation.confirm("MY_ACCOUNT.DELETE_CONFIRM")) return@launch
            val succeeded = submit.send { d.api.deleteMyAccount(currentPassword) }
            if (succeeded) {
                // a mensagem primeiro: ela será exibida na tela de login,
                // para onde a navegação nos leva assim que a sessão estiver vazia
                d.messages.flash("MY_ACCOUNT.DELETED")
                d.session.forget(voluntary = true) // o servidor apagou o cookie do token
            }
        }
    }

    OutlinedCard(Modifier.fillMaxWidth(), border = BorderStroke(1.dp, Color(0xFFEF9A9A))) {
        Column(Modifier.padding(16.dp)) {
            Text(t("MY_ACCOUNT.DELETE_TITLE"), style = MaterialTheme.typography.titleLarge, color = Color(0xFFC62828))
            Text(t("MY_ACCOUNT.DELETE_HELP"), color = Color.Gray)
            InputField(
                label = "MY_ACCOUNT.CURRENT_PASSWORD_LABEL",
                secret = true,
                maxLength = 72,
                value = currentPassword,
                onChange = {
                    currentPassword = it
                    submit.clearError("currentPassword")
                },
                error = submit.errors["currentPassword"],
            )
            Button(
                onClick = { delete() },
                enabled = !submit.inProgress,
                colors = ButtonDefaults.buttonColors(containerColor = Color(0xFFC62828)),
            ) { Text(t("MY_ACCOUNT.DELETE_SUBMIT")) }
        }
    }
    ConfirmDialog(confirmation)
}