Skip to content

11. 案例研究:RdvMedecins 应用的 Kotlin 客户端

11.1. 问题

[RdvMedecins] 应用允许用户在诊所预约。[NestJS] 课程把它开发成一个 HTML 应用,由服务器生成页面;课程 [Vue.js]、[Angular] 和 [React] 为它开发了 Web 客户端,而 [Flutter] 课程创建了一个移动客户端,它根据“RdvMedecins 服务器:一个黑盒”一章中描述的服务器所提供的 JSON 数据生成相同的屏幕。本章描述如何使用 [Android] 原生方式编写客户端,使用 [Kotlin] 和 [Jetpack Compose]。

客户端必须提供其他客户端所提供的一切:

  • 一个由验证码保护的登录屏幕,并可创建患者账户;
  • 某位医生在指定日期的日程,可预约(患者选择窗口)和取消预约;
  • 对管理员而言,管理医生和客户(列表、添加、编辑、删除);
  • 对患者而言,一个个人仪表板(显示可以取消的未来预约)和账户管理;
  • 两种语言:法语和英语;
  • 与 Web 客户端相同的屏幕([/login]、[/schedule]、[/doctors]、[/my-area] 等),在这里它们变成了导航的路由屏幕。

移动应用还有它自己的要求:窄屏幕(没有五列的表格)、会遮住半个屏幕的键盘、返回按钮、会影响 Activity 的屏幕旋转和语言切换(它们会重新创建 Activity)、密码管理器,以及没有用来存储令牌 Cookie 的浏览器。

11.2. 安装与运行

必须已安装并运行 JSON 服务器(见“RdvMedecins 服务器:一个黑盒”一章)。不需要验证码测试模式:你可以让服务器 [.env] 文件中的 [CAPTCHA_TEST] 保持为空。

在 [Android Studio] 中,[File / Open] 打开 [rdvmedecins_kotlin] 文件夹;[Gradle] 会下载所需的库(第一次需要几分钟)。模拟器运行起来之后,用一个命令窗口把它的 8080 端口连接到电脑的端口:

adb reverse tcp:8080 tcp:8080

然后 [Run] 按钮会安装并启动应用。你也可以在打开到 [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
  • 第一行编译应用并将其安装到已连接的设备(模拟器或手机)上,它使用 [adb reverse] 连接到地址为 [http://localhost:8080] 的服务器;
  • 第二行适用于模拟器,不使用 [adb reverse]:模拟器通过地址 [10.0.2.2] 看到电脑;
  • 第三行适用于通过 Wi-Fi 连接到与电脑同一网络的真实手机:我们提供电脑在该网络上的地址(在 [Windows] 下使用 [ipconfig]);[Windows] 上的防火墙必须允许 8080 端口的传入连接。通过 USB 连接的手机(在其开发者选项中启用了“USB 调试”)也可以使用 [adb reverse]。

演示账户列在登录屏幕上(密码 = 登录名)。

11.3. 使用应用

本节的截图来自一个 Pixel 8 模拟器(1080 × 2400 像素,412 × 915 dp)。它们由一个插桩测试([app/src/androidTest/.../CaseStudyCaptures.kt],见附录)自动生成,该测试像用户一样浏览应用。

11.3.1. 登录屏幕

登录屏幕;密码错误:消息出现在屏幕底部,并显示一张新图像(每张图像只使用一次):

Image

Image

11.3.2. 管理员和医生所看到的日程

以 [admin] 身份登录后,你会进入日程。选择一位医生和一天(日期通过日历选择),然后点击“View schedule”:

Image

Image

Image

“Book”会打开预约窗口,并在日程上方显示一条导航路径;预约被保存;“Cancel”会提示确认:

Image

Image

Image

医生([pelissier])会被直接带到他自己的每日日程:

Image

11.3.3. 患者区域

患者([martin])进入“My area”。在日程中,他为自己预约,而无需选择患者:

Image

Image

Image

他的预约出现在他的名字下;“Book”按钮不再可用(只能有一个未来的预约),并有一条消息解释原因。他的账户显示该预约。“Manage my account”:任何修改都需要当前密码;错误来自服务器:

Image

Image

Image

患者的菜单中没有“Doctors”条目。如果他仍然(通过链接)打开这个屏幕,导航会显示一个 403 错误页面(见 [navigation/Navigation.kt])。

11.3.4. 管理医生和客户

医生列表;一次填写有误的添加;一次成功的添加:

Image

Image

Image

一条重复的条目;一次成功的删除:

Image

Image

11.3.5. 创建账户

在登录屏幕上,输入验证码,然后点按“Create a patient account”。表单被服务器拒绝;账户创建成功后,返回登录屏幕,其中的登录信息已预先填好:

Image

Image

11.3.6. 法语版,然后是大屏幕

顶部栏中的 FR / EN 菜单会切换应用的语言:Activity 被重新创建,一切都被重新翻译,包括日程和日期。在宽屏上(平板,或横握的手机),菜单会一直显示在左侧:

Image

Image

11.3.7. 会话已过期

如果令牌过期(或 Cookie 被删除),下一个请求会返回 401;应用会重定向到登录屏幕。登录之后,它会把用户重定向回他想要查看的屏幕:

Image

11.4. 客户端架构

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

这是 [Android] 指南(“Guide to App Architecture”)所推荐的架构,作了如下简化:

  • 数据层([api/]):唯一了解 [OkHttp]、URL 对象和 JSON 对象的层;
  • 状态层([state/]):其属性是 [Compose] 状态的对象,由 [Application] 对象一次性创建,并提供给所有屏幕([LocalDependencies]);
  • 界面层([pages/]、[widgets/]):[@Composable] 函数,负责显示状态并传递用户的操作。

下表比较了 [NestJS] 课程中的 HTML 应用、[Flutter] 客户端以及本客户端:

HTML 应用 (NestJS)
Flutter 客户端
Kotlin 客户端
服务器渲染每个页面([res.render])
由 widget 渲染屏幕
由 [@Composable] 函数生成屏幕
[views/layout.hbs] 及其局部视图
[layout.dart](一个 [ShellRoute])
[AppLayout.kt],围绕 [NavHost]
控制器路由
[go_router]
[navigation-compose],[@Serializable] 路由
[JwtAuthGuard]、[RolesGuard]
路由器的 [redirect] 函数
[Protected] 以及一个观察会话的副作用
由浏览器存储的令牌 Cookie
一个管理 Cookie 的 HTTP 客户端
[OkHttp] 的 [CookieJar]
Cookie 中的闪现消息
一个 [ChangeNotifier],[Messages]
一个有状态的 [Compose] 类,[Messages]
由服务器读取的字典
[Translations](JSON)
[Translations](相同的 JSON 文件)
存储在 Cookie 中的语言
存储在 [shared_preferences] 中
由 [Android] ([setApplicationLocales])管理
已经读取过的数据
[Cache](几行代码)
[Cache](几行代码,来自 [Deferred])
表单被拒绝:服务器重新加载页面
400/409 响应,错误显示在字段下方
相同

客户端的所有文件都显示在下面。它们都有大量注释;它们的注释是课程的一部分。

11.5. 项目配置

11.5.1. settings.gradle.kts、build.gradle.kts

// =========================================================================
// settings.gradle.kts - Gradle 项目的全局配置
// (由 Android Studio 生成;只修改了 rootProject.name)
// =========================================================================

// Gradle 查找插件的位置(Android 插件、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"
}
// Gradle 查找库的位置:google() 提供 AndroidX 和 Compose,
// mavenCentral() 提供 OkHttp、kotlinx.serialization、AndroidSVG
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "rdvmedecins_kotlin"
// 只有一个模块:位于 app/ 文件夹中的应用
include(":app")
// =========================================================================
// build.gradle.kts(根目录)- 声明项目各模块使用的
// Gradle 插件,但不在这里应用它们(“apply false”):
// 由 app/build.gradle.kts 来应用它们。
// =========================================================================
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.kotlin.serialization) apply false
}

示例中的文件(见示例 01)。

11.5.2. gradle/libs.versions.toml

# =========================================================================
# gradle/libs.versions.toml - 项目的“版本目录”
# -------------------------------------------------------------------------
# 所有插件和库的版本,集中在同一个地方。
# build.gradle.kts 文件通过名称引用它们
# (libs.okhttp、libs.plugins.kotlin.compose 等)。它相当于
# Flutter 的 pubspec.yaml 中的 dependencies 部分。
# =========================================================================

[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]
# 由 Android Studio 生成(“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" }
# 为 RdvMedecins 添加
# 基本的 Material 图标(Add、Delete、Search 等)
androidx-compose-material-icons-core = { group = "androidx.compose.material", name = "material-icons-core" }
# 从 Compose 角度看到的 Activity 生命周期 
androidx-lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
# 在 @Composable 函数中使用 viewModel() 
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
# 应用自己的语言 
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
# 路由器 
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }
# HTTP 客户端 
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
# JSON(反)序列化 
kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
# 绘制 SVG 图像(验证码)
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" }
# 生成 @Serializable 类的(反)序列化代码
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

与示例中相同的库,但 [DataStore] 除外:语言由 [Android] 自己存储,令牌则存储在 Cookie 罐中。

11.5.3. app/build.gradle.kts

// =========================================================================
// app/build.gradle.kts - “app”模块的配置:RdvMedecins
// Android 客户端。由 Android Studio 生成(“Empty
// Activity”模板),然后补全(标有“added”的行)。
// =========================================================================
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.compose)
    // 新增:kotlinx.serialization 插件(@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"
        // 新增:JSON 服务器的地址,可以在编译时更改:
        //     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
        // 新增: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)
    // 为 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)
    // 测试:制作课程的截图(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)
}

与示例中相同,但应用 ID 不同([fr.stahe.rdvmedecins]):这两个应用可以并排安装。[buildTypes] 块描述了生产版本(见“部署”一章)。

11.5.4. AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     AndroidManifest.xml - the "identity card" of the application
     ===================================================================== -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- 网络访问(JSON 服务器) -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- android:name: the Application class (RdvMedecinsApplication.kt).
         usesCleartextTraffic: the "cleartext" HTTP of the development server
         (to be removed for a production server in https, see Deployment).
         localeConfig: the languages offered by the application -->
    <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">

        <!-- the only activity. windowSoftInputMode="adjustResize": the
             keyboard shrinks the screen instead of hiding it -->
        <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>

        <!-- Android 13 之前:AppCompat 会记住所选的语言 -->
        <service
            android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
            android:enabled="false"
            android:exported="false">
            <meta-data
                android:name="autoStoreLocales"
                android:value="true" />
        </service>
    </application>

</manifest>
  • 只有一个 Activity,[MainActivity]:所有屏幕都是 [@Composable] 函数;
  • [windowSoftInputMode="adjustResize"]:键盘出现时,屏幕会缩小(而不是被键盘遮住);
  • [android:localeConfig] 以及 [AppCompat] 的服务:应用专属的语言(见示例 21)。

11.5.5. 资源

<?xml version="1.0" encoding="utf-8"?>
<!-- the name of the application (under its icon). The texts of the interface,
     for their part, are in the dictionaries assets/i18n/fr.json and en.json -->
<resources>
    <string name="app_name">RdvMedecins</string>
</resources>
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- the "Android" theme, only visible during the launch; an
         AppCompat theme, required by AppCompatActivity (see MainActivity.kt) -->
    <style name="Theme.RdvMedecins" parent="Theme.AppCompat.DayNight.NoActionBar" />
</resources>
<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/xml/locales_config.xml - the languages of the application (example 21)
     ............................................................................
     Declared in AndroidManifest.xml (android:localeConfig). Since
     Android 13, the user can also choose the language of EACH
     application in the phone's settings: Settings > System >
     Languages > App languages.
     ===================================================================== -->
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
    <locale android:name="fr" />
    <locale android:name="en" />
</locale-config>

应用的文本并不包含在这里(只有应用名称):它们位于 JSON 字典 [assets/i18n/fr.json] 和 [en.json] 中,也位于 [Vue.js]、[Angular]、[React] 和 [Flutter] 客户端的字典中。节选:

{
  "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. 启动应用

11.6.1. Config.kt

// =========================================================================
// Config.kt - JSON 服务器在哪里?
// -------------------------------------------------------------------------
// 移动应用没有“源”:必须告诉它服务器的完整地址
// (参见示例 22 和示例的 common/Config.kt):
//   - 默认为 http://localhost:8080,使用命令
//         adb reverse tcp:8080 tcp:8080
//     把手机(或模拟器)的 8080 端口连接到电脑的
//     8080 端口;
//   - 或者使用另一个地址,在编译时设置:
//         gradlew installDebug -Pserver=http://10.0.2.2:8080        (模拟器)
//         gradlew installDebug -Pserver=http://192.168.1.20:8080    (通过 Wi-Fi 的手机)
// =========================================================================
package fr.stahe.rdvmedecins

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

服务器地址,在编译时设置(见示例 22)。

11.6.2. RdvMedecinsApplication.kt

// =========================================================================
// RdvMedecinsApplication.kt - 整个应用共享的对象
// -------------------------------------------------------------------------
// Android 在启动时、任何 Activity 之前创建一个 Application 对象,并
// 一直保留到应用停止。我们在这里一次性构建
// 所有屏幕共享的对象:
//   - HTTP 客户端(及其 Cookie 罐)、API 访问层;
//   - 会话(谁已登录?)、消息、数据缓存。
// 因此它们在 Activity 重新创建(旋转、更改
// 语言)后依然存在。屏幕通过 LocalDependencies 获取它们(参见
// MainActivity.kt):这是一种手写的“依赖注入”。
// 有两种机制把这些对象连接在一起:
//   1. 受保护请求收到 401 响应(会话已过期):用户
//      被遗忘,并准备好消息;观察会话的导航
//      随后回到登录屏幕;
//   2. 用户变更:为上一位用户读取的数据
//      不再有任何价值,缓存被清空。
// =========================================================================
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() {
    // 一个与应用同寿命的协程作用域
    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. 会话过期
        client.onSessionExpired = {
            session.forget()
            messages.flash("ERRORS.SESSION_EXPIRED", success = false)
        }
        // 2. 用户变更:snapshotFlow 把 Compose 状态转换为 Flow
        scope.launch {
            snapshotFlow { session.user }.collect { cache.clear() }
        }
    }
}

// Application 对象,提供给所有屏幕
val LocalDependencies = staticCompositionLocalOf<RdvMedecinsApplication> { error("no dependencies provided") }
  • 第 35–41 行:共享对象,只创建一次。[lateinit var]:一个非 [null] 属性,稍后初始化(在 [onCreate] 中);[MainScope()]:一个与应用同寿命的协程作用域;
  • 第 49–51 行:会话已过期:委托给 API 客户端(它对其他一切一无所知)的函数会忘记该用户并准备好消息;
  • 第 55 行:[snapshotFlow] 把 [Compose] 状态转换为 [Flow](见示例 19):每当用户变化时,缓存都会被清空;
  • 第 61 行:[Application] 对象,通过 [CompositionLocal] 提供给所有屏幕(见示例 14):一种手写的“依赖注入”。

11.6.3. MainActivity.kt

// =========================================================================
// MainActivity.kt - 应用唯一的 Activity
// -------------------------------------------------------------------------
// 所有屏幕都是 @Composable 函数,由 NavHost
// (参见 navigation/Navigation.kt)在这个 Activity 中显示。它向所有
// 屏幕提供(CompositionLocalProvider):
//   - 应用的共享对象(LocalDependencies);
//   - 当前语言的翻译(LocalTranslations)。
// 它是一个 AppCompatActivity:它知道如何应用用户选择的语言
// (参见示例 21),即使在 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

// 颜色:其他 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()
                }
            }
        }
    }
}
  • 第 27–34 行:主题颜色,即其他客户端所使用的蓝色;
  • 第 37–48 行:一个 [AppCompatActivity](语言,见示例 21),它向所有屏幕提供共享对象和翻译,然后显示导航。

11.6.4. Formatting.kt

// =========================================================================
// Formatting.kt - 时间和日期的显示
// -------------------------------------------------------------------------
// 服务器发送的是原始数据(startHour: 8, startMinute: 0; day:
// “2026-10-05”);取决于语言的格式化是
// 客户端的事(参见示例 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”而不是“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”,API 的格式

// 如果 day 是一个真实存在的 yyyy-MM-dd 格式日期则为 true(“2026-02-30”:不是)
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)))

// Material 日历以毫秒为单位工作(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()

服务器发送的是原始数据([startHour: 8]、[day: "2026-10-05"]):它们的格式化取决于语言,由客户端负责(见示例 09)。

11.7. API 访问层

11.7.1. api/HttpClient.kt

// =========================================================================
// api/HttpClient.kt - 一个处理 Cookie 的 HTTP 客户端
// -------------------------------------------------------------------------
// 取自示例 23(common/HttpClient.kt)。RdvMedecins 服务器
// 把 JWT 令牌放在一个 httpOnly Cookie 中。在手机上没有
// 浏览器来保存它:存储它并在每个请求中把它发回的,是
// OkHttp 客户端的“Cookie 罐”(CookieJar)。
// Cookie 也存储在设备上(SharedPreferences):停止后重新启动
// 应用,我们仍然保持登录状态。
// 有两个 Cookie 在传递:令牌(rdvmedecins_jwt,路径 /api)和
// 账户创建通行证(路径 /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 {
    // Cookie 名称 -> Cookie
    private val cookies = mutableMapOf<String, Cookie>()

    init {
        // 上一次使用期间记住的 Cookie
        val base = Config.serverUrl.toHttpUrl()
        for (text in storage.getStringSet(KEY, emptySet()).orEmpty()) {
            Cookie.parse(base, text)?.let { cookies[it.name] = it }
        }
    }

    // 响应带来了 Cookie:我们存储它们;已过期的 Cookie(服务器就是这样
    // 在退出登录时清除令牌的)会被移除
    @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()) }
    }

    // 请求发出:取出与它相关且未过期的 Cookie
    @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()

示例 23 中的 HTTP 客户端及其 Cookie 罐。有两个 Cookie 在流通:令牌([rdvmedecins_jwt])和账户创建通行证。

11.7.2. api/ApiError.kt

// =========================================================================
// api/ApiError.kt - 所有 API 错误共用一个类
// -------------------------------------------------------------------------
// 取自示例 24(common/ApiError.kt)。服务器的所有错误响应
// 都有相同的形状:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// 没有响应的请求(网络、服务器已停止)或并非来自
// 我们服务器的响应,同样会变成 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:服务器没有应答
    val key: String, // 例如 "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) {
                // 没有键:是代理或网络代替服务器作出了应答
                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 - 所有发往 API 的请求都经过这里
// -------------------------------------------------------------------------
// 取自示例 24(common/Api.kt),有一项新特性:对 401 响应的
// 集中处理。
//
// 401 可能在任何时候到来:令牌已过期(2 小时),
// 账户已被删除,服务器已用另一个密钥
// 重启……与其在每个屏幕中处理这种情况,不如
// 在这里统一处理一次。但这个文件既不知道导航,也不知道
// 消息(它不依赖任何东西):它调用启动时交给它的
// 一个函数(onSessionExpired,参见 RdvMedecinsApplication.kt),
// 该函数会忘记用户;观察会话的导航随后
// 回到登录屏幕。
//
// 有些请求自己处理它们的 401(登录、GET
// /api/auth/me 等):它们是“公开”的(参见 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) {
    // 当服务器对受保护的请求返回 401 时要做什么
    var onSessionExpired: () -> Unit = {}

    // isPublic:对于自己处理 401 的路由为 true。
    // withContext(Dispatchers.Main.immediate):函数总是在主线程,
    // 即屏幕的线程上结束,无论调用者所在的
    // 线程是什么(在应用中本来就是如此:没有任何
    // 变化;在插桩测试中,调用者可能在别处)。因此我们
    // 在返回之后可以放心地导航或操作状态
    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) {
                // 没有响应:网络中断、服务器已停止、地址错误
                throw ApiError(0, "ERRORS.SERVER_UNREACHABLE")
            }
        }
        // 对(code, text)这个对进行解构
        val (code, text) = response
        if (code >= 400) {
            val error = ApiError.fromResponse(code, text)
            if (error.statusCode == 401 && !isPublic) {
                // 回到屏幕的线程:我们可以操作状态
                onSessionExpired()
                // 一直在等待响应的屏幕也会显示这条消息
                throw ApiError(401, "ERRORS.SESSION_EXPIRED")
            }
            throw error
        }
        return if (text.isEmpty()) null else Json.parseToJsonElement(text)
    }
}
  • 第 42–43 行:函数总是在主线程,即屏幕线程([Dispatchers.Main.immediate])上退出:返回之后,你可以放心地导航或与状态交互;
  • 第 46–53 行:请求,在 I/O 线程上执行(见示例 24);
  • 第 60–64 行:新增的特性:受保护路由上的 401 表示会话已过期。我们在这里集中处理一次,覆盖所有请求:[onSessionExpired()],然后抛出一个 [ApiError],其键就是要显示的消息。

11.7.4. api/Types.kt

// =========================================================================
// api/Types.kt - 与服务器交换的 JSON 对象
// -------------------------------------------------------------------------
// 将“服务器,一个黑盒”一章中描述的 API 翻译成 Kotlin
// @Serializable 类(参见示例的 common/Types.kt)。
// 读取形状不符合预期的 JSON 时,
// 一收到就会失败。
// =========================================================================
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)

// 称谓、名、姓
@Serializable
data class Identity(val title: String, val firstName: String, val lastName: String) {
    val label get() = "$title $firstName $lastName" // “Mme Alice DURAND”
}

// 一位医生或一位客户:GET /api/doctors、GET /api/clients/:id 等
@Serializable
data class Person(
    val id: Int,
    val version: Int, // 乐观锁:更新时需要一并发回
    val title: String,
    val firstName: String,
    val lastName: String,
    val login: String? = null, // 仅限 ADMIN
) {
    val label get() = "$title $firstName $lastName"
}

// 一个时间段
@Serializable
data class Slot(val id: Int, val startHour: Int, val startMinute: Int, val endHour: Int, val endMinute: Int)

// 日程的一行,带有已登录用户的权限
@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:空闲,或被另一位患者占用
    val mine: Boolean, // 已登录患者自己的预约
    val bookable: Boolean,
    val appointmentId: Int?, // 如果用户可以取消,则会设置
)

// 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?, // 翻译键(已经有预约的患者)
)

// 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 -> 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 - API 的每个路由一个函数
// -------------------------------------------------------------------------
// 客户端的“数据访问层”(一个“仓库”):屏幕
// 调用这些类型化的函数,而对 URL、OkHttp 或
// JSON 一无所知。如果 API 变化,只有这个文件需要修改。
// 每个函数都是挂起函数;失败时,它抛出 ApiError。
// 表单数据是简单的 Map<String, Any?>:它们的
// 键是服务器期望的字段名称,也是它发回的
// 错误(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 或 /api/clients:两者的处理方式相同
enum class PersonType(val path: String) { DOCTORS("doctors"), CLIENTS("clients") }

typealias FormData = Map<String, Any?>

// 表单数据 -> 一个 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)

    // 登录(公开路由)
    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)
    }

    // 账户创建(公开)
    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

    // 返回所创建账户的登录名
    suspend fun register(data: FormData): String =
        post("/register", data.toJson(), isPublic = true)!!.jsonObject["login"]!!.jsonPrimitive.content

    // 日程和预约
    // doctorId 为 null:对已登录的医生,返回他自己的日程
    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")
    }

    // 医生和客户
    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")
    }

    // 患者区域
    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())
    }
}
  • 第 24 行:医生或客户:一个枚举,每个值带有对应的 API 路径;
  • 第 26–29 行:表单数据:一个 [Map],其键是服务器期望的字段名称,并被转换为 JSON;
  • 第 40–110 行:API 的每个路由一个函数,按主题分组;自己处理 401 的路由是“公开”路由。

11.8. 语言

11.8.1. i18n/Translations.kt

// =========================================================================
// i18n/Translations.kt - 字典,当前语言
// -------------------------------------------------------------------------
// 取自示例 25(Dictionary.kt)。这些字典
// (assets/i18n/fr.json、en.json)与 Vue.js、Angular、
// React 和 Flutter 客户端的相同:键相同,约定相同({{param}})。服务器
// 只发回键(“ERRORS.LOGIN_TAKEN”):键在这里
// 变成文本。
//   - t("KEY", mapOf("param" to value)):当前语言的文本;
//   - changeLanguage("fr"):应用自己的语言(参见示例
//     21),由 Android 记住;Activity 会用新
//     语言重新创建:我们的文本,还有 Android 的文本(日历)、
//     日期和数字。
// =========================================================================
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
    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
    }

    // 未知的键会原样显示:我们立刻就能看到缺少了什么
    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 }
    }
}

// 应用的语言:Android 会记住它,并重新创建 Activity
fun changeLanguage(language: String) {
    AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(language))
}

// 翻译,提供给所有屏幕(参见 MainActivity.kt)
val LocalTranslations = staticCompositionLocalOf<Translations> { error("no translations provided") }

// 当前配置所用语言的翻译
@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) }
}

// 一个快捷方式,在 @Composable 函数中:t("LOGIN.TITLE")
@Composable
fun t(key: String, params: Map<String, String> = emptyMap()): String = LocalTranslations.current.t(key, params)
  • 第 32–45 行:示例 25 中的字典,与其他客户端使用相同的文件;
  • 第 57–64 行:当前语言的翻译,提供给所有屏幕(见 [MainActivity.kt]);只有语言改变时才会重新读取字典;
  • 第 69 行:一个快捷的 [@Composable] 函数,[t("LOGIN.TITLE")]。与任何 [@Composable] 函数一样,它只能在另一个 [@Composable] 函数内部调用:在普通 lambda([onClick]、下拉列表的 [text])中,必须先把它翻译好,或者使用 [LocalTranslations.current.t(...)]。

11.9. 共享状态

11.9.1. state/Session.kt

// =========================================================================
// state/Session.kt - 谁已登录?
// -------------------------------------------------------------------------
// 已登录的用户(或 null),存放在 Compose 观察的状态中
// (mutableStateOf):读取它的屏幕在它变化时会被重组,
// 导航(参见 navigation/Navigation.kt)也观察它,以便
// 离开不再被允许的屏幕。
//
// JWT 令牌本身不在这里:它在一个 Cookie 中,由
// HTTP 客户端存储。会话只保存用户的描述
// ({ login, name, role })。
//
// 应用启动时,会话是空的:check() 只询问一次
// 服务器,看谁已登录(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;
    // 在会话过期之后为 false。导航会考虑这一点
    var leftVoluntarily = false
        private set

    // 会话过期时我们原本想查看的屏幕(一个路由):
    // 登录之后我们会回到它
    var requestedScreen: Any? = null

    // 当前显示的屏幕(一个路由),由每个受保护的屏幕记录
    var currentScreen: Any? = null

    // “谁已登录?”这个问题是否已经问过?
    var checked by mutableStateOf(false)
        private set

    // 只在第一次询问服务器
    suspend fun check() {
        if (checked) return
        user = try {
            api.me()
        } catch (e: Exception) {
            null // 401:没有人;或服务器无法访问
        }
        checked = true
    }

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

    // 用户更改了姓名或登录名(PUT /api/my-account)
    fun update(u: User) = change(u)

    suspend fun logout() {
        try {
            api.logout()
        } finally {
            forget(voluntary = true) // 即使服务器没有应答
        }
    }

    // 不询问服务器任何内容:会话过期、账户被删除
    fun forget(voluntary: Boolean = false) = change(null, voluntary)

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

// 由用户推导出的内容:类型 User? 的扩展属性
// (它们同样适用于 null)
val User?.isAdmin get() = this?.role == Role.ADMIN
val User?.isPatient get() = this?.role == Role.USER

// ADMIN 和 DOCTOR:可以为任何患者预约和取消预约
val User?.isManager get() = this?.role == Role.ADMIN || this?.role == Role.DOCTOR
  • 第 26–27 行:用户,一个被观察的状态:顶部栏、菜单和导航都会读取它;
  • 第 31–39 行:会话过期之后,返回到你原本想查看的屏幕所需的内容;
  • 第 82–86 行:类型 [User?] 的扩展属性:它们同样适用于 [null]([this?.role])。

11.9.2. state/Messages.kt

// =========================================================================
// state/Messages.kt - 显示给用户的消息
// -------------------------------------------------------------------------
// 与其他 RdvMedecins 客户端的呈现方式相同:
//   - 成功消息显示在屏幕顶部(绿色横幅);
//   - 错误消息显示在底部(粉色横幅),始终可见。
// 消息是一个翻译键(加上它的参数):因此如果用户更改语言,
// 它会自行重新翻译。
//
// “闪现”消息:以屏幕切换结束的动作(预约、添加医生等)
// 通过 flash() 留下它的消息;它会显示在下一个屏幕上,
// 然后在
// 再下一次导航时消失。每次屏幕切换时,由导航调用 newPage()
// (参见 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

    // 要在下一个屏幕上显示的消息
    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
    }

    // 用于下一个屏幕
    fun flash(key: String, params: Map<String, String> = emptyMap(), success: Boolean = true) {
        if (success) pendingSuccess = Message(key, params) else pendingError = Message(key, params)
    }

    // 一个新屏幕:上一个屏幕的消息消失,
    // 闪现消息出现
    fun newPage() {
        success = pendingSuccess
        error = pendingError
        pendingSuccess = null
        pendingError = null
    }
}

11.9.3. state/Cache.kt

// =========================================================================
// state/Cache.kt - 已经从服务器读取的数据
// -------------------------------------------------------------------------
// 医生列表几乎从不变化:没有必要在每次访问日程时
// 都重新读取。缓存保存每次读取的结果,
// 以一个键保存(“doctors”、“schedule/1/2026-10-05”等):
//
//     val doctors = cache.read("doctors") { api.list(PersonType.DOCTORS) }
//
// 返回已经保存的结果,或者启动读取并保存它的
// 结果。对同一个键的两个同时发出的请求共享同一次
// 读取(一个 Deferred:即将到来的结果)。失败的读取不会
// 被保存:下一次会重试。
// 更新之后,受影响的键会被置为失效:
// cache.invalidate("schedule")。于是 version 属性(一个被观察的状态)
// 发生变化:读取它的屏幕(即使被对话框遮住)
// 会重新读取它们的数据。这用几行代码实现了
// React 客户端的 TanStack Query 库所做的事情。
// =========================================================================
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) {
            // 失败时,这次读取会被遗忘(下一次请求会重试)
            if (reads[key] === reading) reads.remove(key)
            throw e
        }
    }

    // 忘记所有以 prefix 开头的键,并通知各个屏幕
    fun invalidate(prefix: String) {
        reads.keys.removeAll { it.startsWith(prefix) }
        version++
    }

    // 用户变更:一切都被遗忘,但不通知(上一位用户的屏幕
    // 即将消失,它们不能再读取任何东西)
    fun clear() = reads.clear()
}
  • 第 36–39 行:[getOrPut]:如果已经为这个键启动了读取操作,就继续使用那个操作;否则启动一个新的。[async] 启动一个产生 [Deferred](即将到来的结果)的协程:两个同时发出的请求都在等待([await])同一次读取;
  • 第 48–50 行:[invalidate]:把 [version] 作为 [LaunchedEffect] 的键来读取的屏幕会重新读取它们的数据。

11.10. 导航

11.10.1. navigation/Screens.kt

// =========================================================================
// navigation/Screens.kt - 应用的路由(参见示例 17)
// -------------------------------------------------------------------------
// 与其他客户端相同的屏幕(/login、/schedule、/doctors、
// /my-area 等),由 Kotlin @Serializable 对象描述,汇集
// 在一个 Screens 对象中:Screens.Schedule(doctorId = 1, day = "2026-10-05")。
// 屏幕的全部状态都在它的路由中(医生、日期等):
// 手机的返回按钮会原样恢复它。
// 预约对话框也是一个路由(Screens.Booking):
// 一个“dialog”类型的目的地,显示在日程之上;
// 返回按钮会将其关闭。
// =========================================================================
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 {
    // 第一个屏幕:用来询问服务器谁已登录的时间
    @Serializable
    object Startup

    // login:在创建账户之后预先填好
    @Serializable
    data class Login(val login: String = "")

    // day:原样保存,可能无效(由屏幕检查)
    @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)

    // 医生或客户的管理屏幕(ADMIN)
    @Serializable
    data class Persons(val type: PersonType)

    // id 为 null:创建;否则为更新
    @Serializable
    data class Person(val type: PersonType, val id: Int? = null)

    @Serializable
    object Register

    @Serializable
    object MyArea

    @Serializable
    object MyAccount
}

// 受保护屏幕允许的角色(null:所有已登录的角色)
val adminRoles = setOf(Role.ADMIN)
val patientRoles = setOf(Role.USER)

// 每个角色登录之后的主页
fun home(u: User): Any = if (u.role == Role.USER) Screens.MyArea else Screens.Schedule()

应用的导航路径,组织在一个 [Screens] 对象中。屏幕的全部状态都保存在它的导航路径中;手机的返回按钮会把它恢复成原来的样子。预约窗口同样是一个导航路径。

11.10.2. navigation/Navigation.kt

// =========================================================================
// navigation/Navigation.kt - 应用的屏幕及其权限
// -------------------------------------------------------------------------
// NavHost(参见示例 17)在 AppLayout(顶部栏、菜单、消息)中
// 显示当前路由的屏幕。
//
// 守卫(参见示例 18):
//   - 受保护的屏幕由 Protected(route, roles) 包裹:只有
//     已登录且角色正确的用户才能看到它(否则显示
//     403 错误屏幕);
//   - 一个副作用观察会话:消失的用户(退出登录、
//     会话过期)会回到登录屏幕;出现的用户
//     (登录)会离开登录屏幕,转到过期之前请求的屏幕,
//     否则转到其角色的主页。
// 提醒:这些检查只是一种便利(不显示无用的
// 屏幕)。数据的保护由服务器保证,它在每个请求中
// 都会再次检查令牌和角色。
//
// “闪现”消息:每个新屏幕上调用 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

// 公开屏幕(无需登录)
fun isPublic(d: NavDestination) =
    d.hasRoute<Screens.Login>() || d.hasRoute<Screens.Register>() || d.hasRoute<Screens.Startup>()

// 通过清空栈转到某个屏幕:返回不会回到上一个屏幕
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

    // 闪现消息:在每个新屏幕上(栈中的一个新条目)
    LaunchedEffect(nav) {
        nav.currentBackStackEntryFlow.map { it.id }.distinctUntilChanged().collect { d.messages.newPage() }
    }

    // 会话变化:在每次用户变更时重新启动
    LaunchedEffect(user, session.checked) {
        if (!session.checked) return@LaunchedEffect
        val here = nav.currentBackStackEntry?.destination ?: return@LaunchedEffect
        if (user == null && !isPublic(here)) {
            // 会话过期:记住当前屏幕,以便回到它
            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>())) {
            // 已登录:登录屏幕不再有意义
            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,
                        // 查看另一份日程:当前路由被替换
                        onView = { id, day ->
                            nav.navigate(Screens.Schedule(id, day)) { popUpTo<Screens.Schedule> { inclusive = true } }
                        },
                        // 预约:对话框被压入日程之上
                        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) {
                    // 返回列表:表单被弹出
                    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) })
                }
            }
        }
    }
}

// 受保护的屏幕:已登录,并且如果 roles 不为 null,则具有其中一个角色
@Composable
fun Protected(route: Any, roles: Set<Role>? = null, content: @Composable () -> Unit) {
    val session = LocalDependencies.current.session
    val u = session.user ?: return // 未登录:导航回到登录
    // 当前显示的屏幕,记住它以便在会话过期之后回到它
    LaunchedEffect(route) { session.currentScreen = route }
    if (roles != null && u.role !in roles) {
        ErrorPage(code = 403)
    } else {
        content()
    }
}
  • 第 54–57 行:通过清空栈来转到某个屏幕:返回不会回到上一个屏幕(登录之后你不会回到登录屏幕);
  • 第 69–70 行:闪现消息:[currentBackStackEntryFlow],用于相继出现的屏幕的 [Flow];
  • 第 74–85 行:应用的守卫:一个在用户每次变化时触发的副作用。如果没有人位于受保护的屏幕上:登录时(会话已过期则保留当前屏幕);如果有人位于登录屏幕上:转到所请求的屏幕,否则转到其角色的主页;
  • 第 89–113 行:导航图,位于布局中;[dialog<Screens.Booking>]:显示在上一个屏幕之上的目的地,返回按钮会将其关闭;
  • 第 156–164 行:[Protected]:未登录,则什么都不显示(上面的副作用会引导到登录);角色不正确,则显示 403 错误屏幕。

11.11. 可复用组件

11.11.1. widgets/AppLayout.kt

// =========================================================================
// widgets/AppLayout.kt - 所有屏幕共用的布局
// -------------------------------------------------------------------------
// 它包裹着 NavHost(参见 navigation/Navigation.kt):
//   - 顶部栏:标题、语言(FR / EN)、退出登录;
//   - 侧边菜单(“抽屉”,ModalNavigationDrawer),由 ☰
//     按钮打开:用户角色被允许访问的屏幕。“Doctors”和
//     “Patients”只对 ADMIN 显示:这只是为了显示上的
//     便利,真正的保护来自服务器;
//   - 顶部的成功消息;
//   - 当前屏幕(content);
//   - 底部的错误面板。
// 在大屏幕上(平板、横握的手机),菜单会
// 永久显示在左侧:用 NavigationRail 取代抽屉。
// =========================================================================
@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

// 一个菜单条目:它通往的路由、它的标签的键、它的
// 图标,以及用于判断它对给定屏幕是否处于激活状态的测试
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:我们用 if 填充列表
    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)
    // 当前屏幕,以及它是列表或表单时的人员类型
    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)
    // 大屏幕:宽度至少 800 dp
    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:一个菜单;Activity 会用新语言重新创建
                        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) {
                            // 会话被清空;观察它的导航会显示登录屏幕
                            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()) {
                // 在大屏幕上:菜单永久显示
                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 {
        // 抽屉:只在已登录时、并且只在小屏幕上显示
        ModalNavigationDrawer(
            drawerState = drawer,
            drawerContent = {
                ModalDrawerSheet {
                    // 页眉:谁已登录
                    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() }
    }
}

// 成功消息,位于顶部
@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) } },
    )
}

// 错误面板,位于底部:始终可见,即使屏幕在滚动
@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) } },
    )
}
  • 第 95–97 行:菜单条目,取决于角色([buildList]:用 [if] 填充列表);
  • 第 13–174 行:大屏幕,宽度至少 800 dp:菜单是 [NavigationRail],永久显示;在竖屏手机上,则是由 ☰ 按钮打开的抽屉([ModalNavigationDrawer]);
  • 第 228–241 行:消息:成功消息在顶部,错误消息在底部。

11.11.2. widgets/InputField.kt

// =========================================================================
// widgets/InputField.kt - 一个完整的表单字段
// -------------------------------------------------------------------------
// 标签 + 字段 + 帮助消息或错误消息。应用中的所有
// 表单都使用它:
//
//   InputField(label = "PERSONS.LASTNAME_LABEL", maxLength = 20,
//              value = input["lastName"], onChange = { update("lastName", it) },
//              error = submit.errors["lastName"])
//
// 这是一个受控组件(参见示例 11):值属于父表单。
// label、help 和 error 是翻译键;params 是
// 它们消息的参数({{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, // 密码:字符被隐藏
    maxLength: Int? = null,
    // 供手机的密码管理器使用(用户名、密码等)
    autofillType: ContentType? = null,
) {
    val errorMessage = error?.let { t(it, params) }
    val helpMessage = help?.let { t(it, params) }
    OutlinedTextField(
        value = value,
        // 字段拒绝多余的字符
        onValueChange = { v -> if (maxLength == null || v.length <= maxLength) onChange(v) },
        label = { Text(t(label)) },
        singleLine = true,
        isError = errorMessage != null,
        // 显示错误,否则显示帮助
        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 - 称谓、名、姓
// -------------------------------------------------------------------------
// 身份字段,供三个表单共用:ADMIN 的医生 / 客户表单、
// “Create a patient account”和“Manage my account”。父组件向它传入
// 各个值、各个错误,以及更新字段的函数:
//     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 - 向服务器发送表单
// -------------------------------------------------------------------------
// 应用中的所有表单都遵循与示例 25 相同的模式:
// 不在手机上检查任何规则(规则只存在
// 于服务器这一个地方),在被拒绝时:
//   - 每个字段的错误(ApiError.fields)显示在该字段下方;
//   - 总体消息(ApiError.key)显示在屏幕底部。
// 这个类把这些动作归并在一起(它是示例 23 的 Command,
// 加上了字段的错误)。每个表单的屏幕创建一个:
//
//     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) {
    // 每个字段的错误:一个翻译键
    var errors by mutableStateOf(mapOf<String, String>())
        private set

    // 错误消息的参数({{min}} 等),由服务器发回
    var params by mutableStateOf(mapOf<String, String>())
        private set
    var inProgress by mutableStateOf(false)
        private set

    // 执行提交;如果成功则返回 true。出现 ApiError 时,
    // 会显示错误并返回 false
    suspend fun send(action: suspend () -> Unit): Boolean {
        if (inProgress) return false // 禁止重复提交
        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
        }
    }

    // 用户修改字段:它的错误消失
    fun clearError(field: String) {
        if (field in errors) errors = errors - field
    }
}

示例 23 中的 [Command],并加上了字段错误:应用中的所有表单都使用它。

11.11.5. widgets/Confirmation.kt

// =========================================================================
// widgets/Confirmation.kt - “你确定吗?”
// -------------------------------------------------------------------------
// 取自示例 16。消息是一个翻译键:
//     if (confirmation.confirm("SCHEDULE.CANCEL_CONFIRM")) { ... }
// 用“No, go back”而不是“Cancel”:问题有时是“Cancel this
// appointment?”,而在那里“Cancel”按钮会有歧义。
// 新的问题会清除上一个动作的消息。
// =========================================================================
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 - 验证码图像和输入字段
// -------------------------------------------------------------------------
// 一个显示组件:图像(svg)、“Another image”按钮
// (onReload),以及由父表单控制的字段(value、
// onChange)。图像及其标识符由登录屏幕向服务器请求,
// 因为登录屏幕需要它们来发送答案。
// =========================================================================
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:屏幕阅读器代替图像朗读的内容
                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(取自示例的 common/SvgImage.kt)- 绘制以文本形式给出的 SVG 图像
// -------------------------------------------------------------------------
// 验证码图像由服务器构建,采用 SVG 格式(一段描述
// 图形的文本)。Android 本身无法显示它:由
// AndroidSVG 库把它绘制成图像(Bitmap),再由
// Compose 用 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) {
    // 只有当 SVG 文本变化时才会重新绘制(remember(svg))
    val image = remember(svg) {
        val document = SVG.getFromString(svg)
        // 绘制成“自然”尺寸的 3 倍大:得到清晰的图像
        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(取自示例的 common/DropdownList.kt)- 一个开箱即用的下拉列表
// -------------------------------------------------------------------------
// 用于 Compose 的 Material 3 没有一体化的“下拉列表”
// 组件:它由三个元素组装而成:ExposedDropdownMenuBox、
// 一个只读文本字段,以及 ExposedDropdownMenu 菜单。我们
// 在这里一次性完成(示例 05 到 08、24、25):
//
//     DropdownList("Country", value = country, choices = listOf("fr", "be", "ch"),
//                  text = { countryNames[it] }, onChange = { country = it })
//
// 这个函数是泛型的(<T>):选项可以是字符串、
// 数字、医生等等。text 说明如何显示一个选项。如果 T 是“可空”类型(Int?),
// 则选项可以是 null(“请选择”)。
// =========================================================================
@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() },
    // 字段下方的错误消息(参见示例 07 和 25)
    error: String? = null,
) {
    // 菜单是否展开?每个下拉列表特有的状态
    var expanded by remember { mutableStateOf(false) }
    ExposedDropdownMenuBox(expanded = expanded, onExpandedChange = { expanded = it }, modifier = modifier) {
        // 显示当前选项的字段;menuAnchor 使它成为菜单的
        // 锚点(触摸它即可打开菜单)
        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(),
        )
        // 菜单:每个选项一行
        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 - 一个彩色标签(其他客户端的“徽章”)
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 - 时间段的预约对话框
// -------------------------------------------------------------------------
// 导航的一个“dialog”类型的目的地(Screens.Booking):
// 它显示在日程之上,包括变灰的背景,手机的
// 返回按钮会将其关闭。它的路由包含它所需要的一切:
// 医生、日期、时间段。
// 它从缓存中重新读取日程(不发起请求:日程刚刚被
// 读取过),在其中找到该时间段并检查它是否可预约。
// 预约之后:一条闪现消息、关闭对话框,以及使缓存
// 失效;仍在对话框下方保持活跃的日程会重新读取自己。
// =========================================================================
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:供选择的患者
    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) }
            // 仅当该用户可以预约这个时间段时
            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") {
                    // 没有选择患者:对话框保持打开
                    d.messages.showError(e.key)
                    sending = false
                    return@launch
                }
                // 时间段在此期间被占用、患者已经有预约等:消息会
                // 显示在日程上,对话框关闭
                d.messages.flash(e.key, e.params, success = false)
            }
            sending = false
            onClose()
            // 服务器才是权威:日程(以及患者区域)会被重新读取
            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) {
                // 患者为自己预约:没有列表(并且服务器
                // 无论如何都会忽略可能存在的 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(),
                )
            }
            // 一个错误(没有选择患者):屏幕的错误面板
            // 被对话框遮住,我们在这里重复显示
            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")) }
            }
        }
    }
}
  • 第 64–70 行:日程,从缓存中重新读取(不发起查询:它刚刚被读取过),用来找到时间段;以及管理员所需的患者列表;
  • 第 76–98 行:预约:一条弹出消息、关闭窗口,并使缓存失效;仍在窗口下方保持活跃的日程会自动重新加载。

11.12. 各个屏幕

11.12.1. pages/StartupPage.kt

// =========================================================================
// pages/StartupPage.kt - 第一个屏幕
// -------------------------------------------------------------------------
// 用来向服务器询问一次谁已登录的时间(GET
// /api/auth/me:令牌 Cookie 可能是在上一次使用时保留下来的)。
// 已登录:导航(它观察会话)会通往
// 该角色的主页;没有人:onNobody,登录屏幕。
// =========================================================================
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 - 错误屏幕:403(角色不足,参见
// navigation/Navigation.kt)或 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 - 登录屏幕
// -------------------------------------------------------------------------
// 与其他客户端相同的屏幕:登录名、密码、验证码,以及
// 第二个按钮“Create a patient account”,它会先检查相同的验证码,
// 然后再打开账户创建页面。
// login:该字段已预先填好(在创建账户之后)。
// 登录成功之后,这个屏幕自己不会导航:会话
// 发生变化,是导航离开登录屏幕
// (参见 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) }
    // 输入:一个 Map,字段 -> 值;rememberSaveable:它在更改
    // 语言(Activity 被重新创建)后依然保留
    var input by rememberSaveable { mutableStateOf(mapOf("login" to login, "password" to "", "captcha" to "")) }
    var captcha by remember { mutableStateOf<Captcha?>(null) }
    val scope = rememberCoroutineScope()

    // 一张新图像:每次尝试之后都需要,因为一张图像只能
    // 使用一次(服务器在检查之后就会忘记它)
    suspend fun reloadCaptcha() {
        captcha = try {
            d.api.captcha()
        } catch (e: Exception) {
            null // 服务器无法访问:登录会失败,并给出明确的消息
        }
    }
    LaunchedEffect(Unit) { reloadCaptcha() }

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

    // 两个按钮共用这个流程:发送,然后在
    // 失败时显示错误消息和新图像
    fun attempt(action: suspend () -> Unit) {
        scope.launch {
            d.messages.clear()
            if (!submit.send(action)) {
                input = input + ("captcha" to "")
                reloadCaptcha()
            }
        }
    }

    // 成功时,这里无需再做其他事情:导航会切换屏幕
    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:手机的密码管理器可以填写表单
        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()
    }
}

// 演示账户
@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,
        )
    }
}
  • 第 32 行:输入,一个字段 → 值的 [Map],由 [rememberSaveable] 保存:它在语言切换后依然保留;
  • 第 61–70 行:每次尝试之后都会换一张新图像:一张图像只使用一次;
  • 第 89 行:如果成功,则无需再做其他事情:会话发生变化,导航会离开登录屏幕。

11.12.4. pages/SchedulePage.kt

// =========================================================================
// pages/SchedulePage.kt - 日程屏幕
// -------------------------------------------------------------------------
// 三个部分,和其他客户端一样:
//   1. 选择医生和日期;
//   2. 该医生在那一天的日程;
//   3. 时间段的预约对话框:另一个路由
//      Screens.Booking,显示在上方(参见 BookingDialog.kt)。
//
// 屏幕的全部状态都在它的路由中:Screens.Schedule(doctorId, day)。
// 屏幕从中推导出要显示的内容,而用户的操作
// 会改变路由(onView、onBook);手机的返回按钮
// 会关闭预约对话框。
//
// 每个人能看到什么、能做什么,由服务器决定(每个时间段的
// patient、mine、bookable、appointmentId 字段):屏幕只是
// 显示它。患者甚至收不到其他患者的姓名。
// =========================================================================
@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

// 某位医生在某一天的日程在缓存中的键
fun scheduleKey(doctorId: Int?, day: String) = "schedule/$doctorId/$day"

@Composable
fun SchedulePage(
    doctorId: Int?,
    day: String?, // 原样取自路由:可能无效
    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()
    // 日期:如果路由中的日期有效则用它,否则用今天
    val invalidDay = day != null && !isValidDate(day)
    val theDay = if (day != null && !invalidDay) day else today()

    var doctors by remember { mutableStateOf(listOf<Person>()) }
    // 日程(在它到来之前、或没有日程时为 null)
    var schedule by remember { mutableStateOf<Schedule?>(null) }
    var loading by remember { mutableStateOf(false) }

    // 医生:只读取一次(缓存);错误显示在屏幕底部
    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")
    }

    // 日程:如果路由变化(另一位医生、另一天)或缓存
    // 失效(预约、取消:d.cache.version 变化)则重新读取。
    // 路由中没有医生时,DOCTOR 看到他自己的日程(服务器
    // 通过令牌找到它);其他人什么都看不到
    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
    }

    // 服务器才是权威:取消之后,会重新读取日程
    // (以及显示他的预约的患者区域)
    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
    // 显示的医生:路由中的那位,或者收到的日程中的那位(DOCTOR)
    val shownId = doctorId ?: a?.doctor?.id
    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(12.dp)) {
        // 1. 选择医生和日期。key:如果路由变化,表单
        // 会被重新创建,并从新的值重新开始
        androidx.compose.runtime.key(shownId, theDay) {
            DoctorDayPicker(doctors = doctors, doctorId = shownId, day = theDay, onView = onView)
        }
        // 已经有未来预约的患者:为什么没有“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”会改变路由:预约对话框随之打开
                onBook = { c -> onBook(shownId, theDay, c.id) },
                onCancel = ::cancel,
            )
            else -> Text(t("SCHEDULE.EMPTY_STATE"), Modifier.padding(16.dp))
        }
    }
    ConfirmDialog(confirmation)
}

// -------------------------------------------------------------------------
// 1. 选择医生和日期:一个小表单,其状态
// 只在发送之前有用。它以路由的值作为起始。
// -------------------------------------------------------------------------
@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
    // 所选的医生必须在列表中(否则:无)
    val knownId = id.takeIf { i -> doctors.any { it.id == i } }
    // t() 是一个 @Composable 函数:我们在文本 lambda 之前翻译,因为 lambda 不是 @Composable
    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))
            // 日期:一个只读字段;触摸它会打开日历
            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(),
                )
                // 一个透明的表面,位于字段之上,用于接收触摸
                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 },
            // Android 的 OK / Cancel 文本,使用应用的语言
            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. 日程
// -------------------------------------------------------------------------
@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()
                        // 可预约的时间段带有淡淡的颜色
                        .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")) }
                    }
                }
            }
        }
    }
}
  • 第 91 行:缓存中的日程键;
  • 第 115–117 行:医生,只读取一次(缓存);
  • 第 129–136 行:日程,如果路由变化或缓存失效则重新读取;
  • 第 149–157 行:取消:确认、请求、使缓存失效;
  • 第 200–230 行:选择医生和日期;日期是一个只读字段,上面覆盖着一层透明的覆盖层,用于打开日历;
  • 第 259–274 行:日程:每位用户能看到什么、能做什么,都由服务器决定。

11.12.5. pages/PatientAreaPage.kt

// =========================================================================
// pages/PatientAreaPage.kt - “My area”(USER 角色)
// -------------------------------------------------------------------------
// 患者的主屏幕,在登录之后:
//   - 两个选项:[Manage my account] 和 [View a schedule];
//   - 他未来的预约(如果有的话),并提供取消它的途径。
// =========================================================================
@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)
            }
            // 区域和日程都已变化
            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)
                // 通常只有一个(规则“同一时间只能有一个未来的预约”),
                // 但屏幕可以显示多个
                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)) {
                        // 该医生在那一天的日程:患者在其中能看到自己的姓名
                        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)
}

// 一张选项“卡片”,触摸它即可打开一个屏幕
@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 - 医生还是客户?
// -------------------------------------------------------------------------
// 医生和客户的管理屏幕是相同的:同样的
// 列表,同样的表单。我们只写一次(PersonsPage.kt、
// PersonFormPage.kt);只有 API 的地址和
// 标签的键会变化,在这里描述。路由把类型传给每个屏幕。
// =========================================================================
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, // 该记录在此期间已被删除
)

// 一种类型的键:借助“DOCTORS.”或“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",
    )
}

// “added / updated / deleted”消息中的 {{name}} 和 {{login}}
fun messageParams(p: Person) = mapOf("name" to "${p.firstName} ${p.lastName}", "login" to (p.login ?: ""))

11.12.7. pages/PersonsPage.kt

// =========================================================================
// pages/PersonsPage.kt - 医生或客户的列表(ADMIN)
// -------------------------------------------------------------------------
// 两者共用一个屏幕:类型(医生或客户)通过
// 路由传入;各自特有的标签在 PersonsConfig.kt 中。
// 在手机上,五列的表格放不下:每个人
// 一个列表行(姓名、登录名),带有两个按钮;圆形按钮
// “+”(FloatingActionButton)用于添加人员。
// 列表是一个 LazyColumn:只构建可见的行。
// =========================================================================
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:尚未加载
    var list by remember(type) { mutableStateOf<List<Person>?>(null) }
    var failed by remember(type) { mutableStateOf(false) }

    // 如果类型变化或缓存失效,则重新读取
    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) {
                // 仍有预约的医生:409 ERRORS.DOCTOR_HAS_APPOINTMENTS
                d.messages.showApiError(e)
            }
            d.cache.invalidate(type.path)
        }
    }

    Box(Modifier.fillMaxSize()) {
        val l = list
        if (l == null) {
            // 尚未加载(或加载失败:消息显示在屏幕底部)
            if (!failed) CircularProgressIndicator(Modifier.align(Alignment.Center))
        } else {
            // 底部留出一些空间,以免最后一行被悬浮按钮遮住
            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)) }) }
                // 每个人一行;key:该行的标识
                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)
}
  • 第 97 行:一个 [LazyColumn]:只生成可见的行(相当于 [Flutter] 的 [ListView.builder]);[contentPadding] 在最后一行下方留出空间给悬浮按钮;
  • 第 124 行:添加人员的悬浮按钮([ExtendedFloatingActionButton])。

11.12.8. pages/PersonFormPage.kt

// =========================================================================
// pages/PersonFormPage.kt - 创建或更新医生
// 或客户(ADMIN)
// -------------------------------------------------------------------------
//     Screens.Person(DOCTORS)          -> 创建(没有 id)
//     Screens.Person(DOCTORS, id = 3)  -> 更新
// 两个组件:
//   - PersonFormPage 读取要更新的记录(如果有的话);
//   - Form 只有在记录读取完成之后才显示:它以
//     记录的值作为起始(初始状态),之后无需再复制它们。
// 这里不检查任何规则:服务器验证一切,它的错误
// 显示在字段下方(参见 widgets/FormSubmit.kt)。
// 随记录一起读取的版本(VERSION)会随更新一起发回:如果另一位
// ADMIN 在此期间更新了它,服务器会返回 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
    // 起始值:为空(创建),或取自所读取的记录
    var initial by remember { mutableStateOf<FormData?>(if (id == null) empty else null) }

    if (id != null) {
        LaunchedEffect(id) {
            try {
                // 不使用缓存:记录必须是最新的(否则表单
                // 会以过时的版本开始: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) {
                // 不存在的记录(在此期间已被删除等):返回列表
                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)
    }
}

// 表单本身
@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) }
    // 起始值的可编辑副本
    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) // 列表已变化
                onList()
            } else if (key == c.notFound) {
                // 在此期间已被另一位 ADMIN 删除:返回列表
                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",
        )
        // 从不预先填入:密码绝不会从服务器返回
        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”
// -------------------------------------------------------------------------
// 只有在复制了登录屏幕的验证码(按钮“Create a patient account”)之后
// 才会来到这里:服务器随后会签发一个
// 通行证(一个 Cookie)。屏幕在打开时立即检查它(GET
// /api/register/access):没有通行证,就返回登录。
// 字段与 ADMIN 的表单相同,但登录名和
// 密码是必填的,并带有确认。
// =========================================================================
@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

// 患者所选密码的最小长度:与服务器相同的值
// (服务器在 PASSWORD_TOO_SHORT 错误中也会发送 {min})
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()

    // 这个屏幕特有的守卫:没有通行证,就返回登录
    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) {
                // 返回登录屏幕,登录名已预先填好
                d.messages.flash("REGISTRATION.DONE", mapOf("login" to login))
                onLogin(login)
            } else if (d.messages.error?.key == "ERRORS.CAPTCHA_BEFORE_ACCOUNT") {
                // 通行证已过期(15 分钟):返回验证码
                d.messages.flash("ERRORS.CAPTCHA_BEFORE_ACCOUNT", success = false)
                onLogin("")
            }
        }
    }

    // 帮助消息和密码错误的参数
    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”(USER 角色)
// -------------------------------------------------------------------------
// 两个独立的表单:
//   1. 更新(身份、登录名、可选的新密码);
//   2. 删除账户,同时也会取消它的预约。
// 两者都需要当前密码(由服务器检查)。
// 两个表单,因此有两个 FormSubmit(两套错误)。与
// 人员表单一样,更新表单只有在账户
// 读取完成之后才显示,并以账户的值作为起始。
// =========================================================================
@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
    // 每次访问都重新读取,不使用缓存:它的版本必须是最新的
    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. 更新
// -------------------------------------------------------------------------
@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 {
                // 服务器签发了新的令牌(姓名、登录名):顶部栏必须随之更新
                d.session.update(d.api.updateMyAccount(input))
                d.messages.flash("MY_ACCOUNT.UPDATED")
            }
            if (succeeded) {
                d.cache.invalidate("my-area")
                onMyArea()
            } else {
                // 在提交被拒绝之后,字段中绝不留下密码;
                // 该值的修改不经过 update(),以免
                // 清除服务器刚刚附加到它上面的错误
                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. 删除:一个只有单个字段的表单
// -------------------------------------------------------------------------
@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) {
                // 先处理消息:它会显示在登录屏幕上,
                // 一旦会话被清空,导航就会带我们到那里
                d.messages.flash("MY_ACCOUNT.DELETED")
                d.session.forget(voluntary = true) // 服务器已清除令牌 Cookie
            }
        }
    }

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