Skip to content

5. 第 4 章 - RdvMedecins 应用的 Kotlin 客户端

5.1. 架构概览

Image

该客户端通过相同的路由与课程中的 [rdvmedecins-nestjs-server] 服务器通信——该服务器完全保持不变——使用 HTTP(POST [/login]、GET [/getAllDoctors]、GET [/getAllClients]、GET [/getDoctorScheduleOfDay/:doctorId/:day]、POST [/addAppointment]、POST [/deleteAppointment]),使用相同的 JSON 信封 [{ status, data }] 和相同的令牌身份验证 [JWT](请求头 [Authorization: Bearer <token>])。

5.2. 项目目录树

rdvmedecins-kotlin-client/
├── settings.gradle.kts, build.gradle.kts, gradle/      Gradle configuration
└── app/
    ├── build.gradle.kts                    Android configuration + dependencies
    └── src/main/
        ├── AndroidManifest.xml             permissions, Application class, activity
        ├── assets/i18n/                    translation dictionaries (fr.json, en.json)
        ├── res/                            app icon, name and theme
        └── java/fr/rdvmedecins/client/
            ├── RdvMedecinsApplication.kt   builds the services (once)
            ├── MainActivity.kt             the screen: provides the services, displays App
            ├── App.kt                      the root screen (conductor + guard)
            ├── AppViewModel.kt             the state and logic of the root screen
            ├── core/
            │   ├── Locals.kt               the CompositionLocals (equivalent of provider)
            │   ├── models/                 data classes (mirror of the server's JSON)
            │   ├── services/               SettingsService, AuthService, AppointmentService
            │   ├── http/                   AuthInterceptor (JWT token + logout on 401)
            │   ├── i18n/                   TranslationsService (French/English)
            │   └── ui/                     DropdownList (reusable component)
            └── features/                   one component per feature

该目录结构逐个文件夹地对应 Flutter 客户端的结构([lib/core/models]、[lib/core/services]、[lib/core/http]、[lib/core/i18n]、[lib/features]),而后者又基于 Vue.js 客户端。Android 特有的两处新增:Application 类([RdvMedecinsApplication.kt])和屏幕的 ViewModel([AppViewModel.kt]),其用途已在第 3 章中说明;以及一个名为 [core/ui] 的小文件夹,用于放置可复用的下拉列表。Kotlin 的文件夹名称为小写且不含连字符([doctordaypicker]、[bookingdialog]):它们是包名。

5.3. 项目配置文件

5.3.1. gradle/libs.versions.toml

版本目录:项目的所有库和 Gradle 插件及其版本,集中在一处。这相当于 Flutter 版本的 [dependencies] 部分,位于 [pubspec.yaml] 文件中。该文件由 Android Studio 生成,然后经过补充。

# =========================================================================
# libs.versions.toml - 项目的“版本目录”:所有
# 插件和库的版本,集中在一处。
# build.gradle.kts 文件通过名称引用它们(libs.okhttp、
# libs.plugins.kotlin.compose……)- 相当于 Flutter 版本中 pubspec.yaml 的版本号,
# 或 Node.js 的 package.json。
# =========================================================================

[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"
okhttp = "4.12.0"
kotlinxSerializationJson = "1.9.0"
junit = "4.13.2"
junitVersion = "1.1.5"
espressoCore = "3.5.1"

[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" }
# === 为本客户端添加 ===
# 在 @Composable 函数中使用 viewModel { ... }(见 App.kt)
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
# 基本的 Material 图标(登出、日历)
androidx-compose-material-icons-core = { group = "androidx.compose.material", name = "material-icons-core" }
# 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" }

[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" }

下面对这段代码进行说明:

  • 第 10 行:[agp = "9.4.1"]——Android Gradle Plugin([AGP])的版本,这是构建 Android 应用的 Gradle 插件。从第 9 版开始,它自己编译 Kotlin 代码:不再需要声明单独的 Kotlin 插件;
  • 第 11 行:[kotlin = "2.2.10"]——下面声明的两个 Kotlin 编译插件(Compose 和序列化)的版本;
  • 第 15 行:[composeBom]——Compose “BOM”(Bill of Materials,物料清单)的版本,它一次性为所有 Compose 库设定相互兼容的版本(见 [app/build.gradle.kts]);
  • 第 38–46 行:为该客户端添加的四个库:[lifecycle-viewmodel-compose] ([viewModel { ... }] 函数)、[material-icons-core] (登出和日历图标)、[OkHttp](HTTP 客户端,相当于 Flutter 的 [http] 包)以及 [kotlinx-serialization-json] (JSON <-> Kotlin 对象的转换)。前两个没有版本号;其版本由 Compose BOM 插件决定;
  • 第 52 行:[kotlinx.serialization] 编译插件,它为带有 [@Serializable] 注解的类生成 JSON 转换代码(见 [core/models])。

5.3.2. app/build.gradle.kts

[app] 模块(即应用本身)的配置,包括所应用的插件、Android 设置和依赖项。

// =========================================================================
// app/build.gradle.kts - “app”模块的配置:即 Android
// 应用本身。由 Android Studio 生成(“Empty Activity”模板),
// 然后为本客户端补充完整(标有“added”的行)。
// =========================================================================
plugins {
    // Android 插件:编译 Kotlin 代码(Android Gradle Plugin 9
    // 本身已包含对 Kotlin 的支持)并生成 .apk
    alias(libs.plugins.android.application)
    // Compose 编译器:转换 @Composable 函数
    alias(libs.plugins.kotlin.compose)
    // 新增:kotlinx.serialization 插件(@Serializable 类)
    alias(libs.plugins.kotlin.serialization)
}

android {
    // 源代码的 Kotlin 基础“包”(R 类、BuildConfig……)
    namespace = "fr.rdvmedecins.client"
    // 用于编译(COMPILE)的 Android API 版本
    compileSdk {
        version = release(37)
    }

    defaultConfig {
        // 应用在手机(以及
        // Play 商店)上的唯一(UNIQUE)标识符
        applicationId = "fr.rdvmedecins.client"
        // 所接受的最低 Android 版本:Android 8.0(API 26),
        // 它是第一个提供 java.time 的版本(LocalDate,见 DoctorDayPicker)
        minSdk = 26
        // 应用经过测试所针对的 Android 版本
        targetSdk = 37
        versionCode = 1
        versionName = "1.0"

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

    buildTypes {
        release {
            optimization {
                enable = false
            }
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    buildFeatures {
        compose = true
    }
}

dependencies {
    // Compose 的“BOM”(Bill Of Materials,物料清单):一次性为所有 Compose 库设定相互兼容的
    // 版本,因此这些库
    // 在下面声明时不带(WITHOUT)版本号
    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)
    // 为本客户端添加
    implementation(libs.androidx.lifecycle.viewmodel.compose)
    implementation(libs.androidx.compose.material.icons.core)
    implementation(libs.okhttp)
    implementation(libs.kotlinx.serialization.json)
    // 测试(由 Android Studio 生成,本文档中未使用)
    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)
    debugImplementation(libs.androidx.compose.ui.test.manifest)
    debugImplementation(libs.androidx.compose.ui.tooling)
}

下面对这段代码进行说明:

  • 第 6–13 行:应用于该模块的三个插件:Android 插件、Compose 编译器(它转换 [@Composable] 函数)和 kotlinx.serialization 插件;
  • 第 18 行:[namespace]——Kotlin 代码的基础包;
  • 第 20–21 行:[compileSdk]——用于编译的 Android API 版本(37 = Android 17)。[targetSdk] (第 32 行)是应用经过测试的版本:Android 会对其应用该版本的行为;
  • 第 27 行:[applicationId] - 应用在手机和 Play 商店中的唯一标识符;
  • 第 30 行:[minSdk = 26] - Android 8.0 或更高版本,这是第一个提供 [java.time] API([LocalDate])的版本,[DoctorDayPicker] 会用到它;
  • 第 51 行:[compose = true]——为该模块启用 Compose;
  • 第 59 行:BOM Compose,声明为“platform”:后面的 Compose 库声明时不带版本号;
  • 第 67–71 行:为该客户端添加的四个依赖项(见 [libs.versions.toml])。[libs.okhttp] 语法引用的是版本目录:Gradle 会为目录中的每个条目生成一个 Kotlin getter,从而在 Android Studio 中启用自动补全。

5.3.3. app/src/main/AndroidManifest.xml

应用的清单。Flutter 版本没有这一部分:包含清单的 [android/] 文件夹由 [flutter create] 生成,且未作研究。而在这里,它是应用代码的一部分。

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     AndroidManifest.xml
     ............................................................................
     The application's "identity card" for the Android system: its
     permissions, its Application class, its activities (screens).
     ===================================================================== -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- network access: without this permission, any HTTP request to
         the NestJS server fails (no dialog is shown to
         the user for this permission: it is granted automatically) -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- android:name: the Application class that builds the services
         (see RdvMedecinsApplication.kt).
         android:usesCleartextTraffic="true": allows "cleartext" HTTP
         (http:// and not https://), blocked by default since Android 9.
         Essential with the NestJS server of this course, which listens over
         plain HTTP - to be removed for a production server over https
         (see chapter 5). -->
    <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:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.RdvMedecins"
        android:usesCleartextTraffic="true"
        tools:targetApi="31">

        <!-- the application's only screen. exported="true" + the
             MAIN/LAUNCHER filter: it is the activity launched by the
             application's icon. windowSoftInputMode="adjustResize": when the
             keyboard appears, the screen is shrunk (and stays scrollable) instead
             of being hidden by the keyboard. -->
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:windowSoftInputMode="adjustResize"
            android:theme="@style/Theme.RdvMedecins">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

下面对这段代码进行说明:

  • 第 14 行:[android.permission.INTERNET]——没有这个权限,任何到服务器的连接都会失败。这是一个“普通”权限:安装时直接授予,不会提示用户;
  • 第 24 行:[android:name=".RdvMedecinsApplication"]——应用的 Application 类(开头的 [.] 会被 [namespace] 替换);
  • 第 33 行:[android:usesCleartextTraffic="true"]——允许“明文”HTTP([http://],而不是 [https://]),自 Android 9 起默认会阻止明文 HTTP。由于本课程中的 NestJS 服务器监听的是普通 HTTP 端口,这个设置必不可少(见第 5 章);
  • 第 41–50 行:唯一的 Activity,[MainActivity]。[MAIN]/[LAUNCHER] 过滤器使它成为由应用图标启动的 Activity;[exported="true"] 允许它被另一个应用启动——在这里就是手机的应用启动器;
  • 第 44 行:[windowSoftInputMode="adjustResize"]——键盘出现时,屏幕会缩放以适应剩余空间(并保持可滚动),而不是被键盘部分遮挡。

[res/] 文件夹的其余部分来自 Android Studio 模板:应用图标([mipmap-*]、[drawable/])、应用名称([values/strings.xml])、其“Android”主题——仅在启动期间使用,直到 Compose 用自己的主题显示第一个屏幕为止([values/themes.xml])——以及数据备份规则([xml/])。

5.4. 应用启动

Flutter 版本中的 [lib/main.dart] 做了两件事:构建服务,然后显示第一个屏幕。在 Android 上,这两项职责由 Application 类和 Activity 分担。

5.4.1. RdvMedecinsApplication.kt

在应用启动时一次性初始化四个客户端服务。

// =========================================================================
// RdvMedecinsApplication.kt
// -------------------------------------------------------------------------
// Flutter 版本 lib/main.dart 的前半部分:只构建
// 一次(ONCE AND ONLY ONCE)应用的服务。
//
// 为什么要用 Application 类?在 Android 上,屏幕(Activity,见
// MainActivity)会在每次手机旋转、
// 每次系统语言更改等情况下被销毁(DESTROYED)然后重新创建(RECREATED)。因此在
// Activity 中构建的服务会在每次旋转时被重建。而
// Application 对象在进程启动时创建,
// 并与进程同生命周期:它是存放必须
// 在应用整个生命周期内存在的对象的合适位置。它在
// AndroidManifest.xml 中声明(<application> 标签的 android:name 属性)。
//
// 构建的顺序(ORDER)很重要,与 Flutter 版本一样:
// AuthService 需要 SettingsService(服务器 URL);经过身份验证的
// HTTP 客户端需要 AuthService(令牌);AppointmentService 需要
// 经过身份验证的 HTTP 客户端和 SettingsService。
// =========================================================================

package fr.rdvmedecins.client

import android.app.Application
import android.content.Context
import fr.rdvmedecins.client.core.http.AuthInterceptor
import fr.rdvmedecins.client.core.i18n.TranslationsService
import fr.rdvmedecins.client.core.services.AuthService
import fr.rdvmedecins.client.core.services.AppointmentService
import fr.rdvmedecins.client.core.services.SettingsService
import okhttp3.OkHttpClient
import java.util.concurrent.TimeUnit

class RdvMedecinsApplication : Application() {

    // lateinit:这些非空属性将在
    // onCreate() 中而不是在构造函数中初始化(见 Kotlin 课程)
    lateinit var settings: SettingsService
        private set
    lateinit var auth: AuthService
        private set
    lateinit var api: AppointmentService
        private set
    lateinit var translations: TranslationsService
        private set

    // 应用启动时由 Android 调用,先于任何屏幕
    override fun onCreate() {
        super.onCreate()

        // 应用的偏好设置:一个小型的私有键/值
        // 文件,在应用停止后仍然保留 - 相当于
        // 浏览器的 localStorage
        val prefs = getSharedPreferences("rdvmedecins", Context.MODE_PRIVATE)

        // 1. 先创建 SettingsService:其他服务都需要它
        settings = SettingsService(prefs)

        // 2. 一个“普通”的 OkHttp HTTP 客户端,由 AuthService 用于
        //    POST /login。超时时间较短:在移动端,如果服务器
        //    不可达(URL 错误、Wi-Fi 关闭……),快速给出错误消息
        //    比无休止的等待更好。
        val plainHttp = OkHttpClient.Builder()
            .connectTimeout(10, TimeUnit.SECONDS)
            .readTimeout(15, TimeUnit.SECONDS)
            .build()
        auth = AuthService(settings, prefs, plainHttp)

        // 3. 经过身份验证的 HTTP 客户端:上一个客户端的副本(COPY)
        //    (newBuilder() 会复用其配置和连接),
        //    外加添加 JWT 令牌的拦截器
        val authHttp = plainHttp.newBuilder()
            .addInterceptor(AuthInterceptor(auth))
            .build()
        api = AppointmentService(authHttp, settings)

        // 4. 翻译:不依赖其他服务
        translations = TranslationsService(assets, prefs)
    }
}

下面对这段代码进行说明:

  • 第 34 行:该类继承 [android.app.Application]。Android 在应用进程启动时创建它的唯一实例——先于任何 Activity——并一直保留到进程结束;
  • 第 38–44 行:四个服务,声明为 [lateinit var ... private set]:非空,稍后初始化(在 [onCreate] 中),并且只能由该类修改;
  • 第 54 行:[getSharedPreferences(...)]——应用的偏好设置,一个小型的私有键/值文件,在应用关闭后仍然保留:相当于浏览器的 [localStorage] 和 Flutter 的 [shared_preferences] 包;
  • 第 63–66 行:一个“简单”的 [OkHttp] 客户端,超时时间较短。OkHttp 客户端的设计初衷就是被共享(SHARED):它自己管理可复用连接的连接池;
  • 第 67 行:[AuthService] 接收这个简单客户端:[/login] 路由是服务器唯一的公开路由;它不需要令牌;
  • 第 72–75 行:经过身份验证的客户端,通过 [newBuilder()] 创建第一个客户端的副本(与第一个客户端共享连接),并增加拦截器 [AuthInterceptor],它会在每个请求中添加 JWT 令牌(见 [core/http])。[AppointmentService] 接收它:其所有方法都无需关心令牌;
  • 第 78 行:[assets]——访问应用 [assets/] 文件夹中的文件,并传递给 [TranslationsService]。

与 Flutter 版本的一个显著区别:在显示第一个屏幕之前不需要任何异步初始化。[SharedPreferences] 对象是同步读取的(首次访问时加载到内存中):[AuthService] 和 [TranslationsService] 在创建时就读取所存储的会话和语言,而 [lib/main.dart] 必须等待 [await auth.init()] 和 [await translations.init()]。

5.4.2. MainActivity.kt

应用唯一的 Activity:它让所有 @Composable 函数都能使用这些服务,然后显示根屏幕。

// =========================================================================
// MainActivity.kt
// -------------------------------------------------------------------------
// Flutter 版本 lib/main.dart 的后半部分:显示
// 第一个屏幕。
//
// Android 应用由“Activity”组成:一个
// Activity 就是一个由系统启动的屏幕。这个 Activity 在
// AndroidManifest.xml 中被声明为启动 Activity(LAUNCHER):当用户点按应用图标时,
// Android 启动的就是它。
//
// ComponentActivity 是专为 Jetpack Compose 设计的基础 Activity:
// setContent { ... } 用 @Composable 函数取代了旧的 Android 视图系统(XML 布局
// 文件)- 对应于 Flutter 的
// runApp(...)。
// =========================================================================

package fr.rdvmedecins.client

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.runtime.CompositionLocalProvider
import fr.rdvmedecins.client.core.LocalAuth
import fr.rdvmedecins.client.core.LocalApi
import fr.rdvmedecins.client.core.LocalSettings
import fr.rdvmedecins.client.core.LocalTranslations

class MainActivity : ComponentActivity() {

    // 每次创建 Activity 时调用:启动时如此,
    // 每次屏幕旋转之后也是如此(见 RdvMedecinsApplication)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 应用在系统状态栏和
        // 导航栏之下绘制;Scaffold(见 App.kt)负责
        // 为这些栏留出所需的空间
        enableEdgeToEdge()

        // 这些服务由
        // RdvMedecinsApplication 一次性构建完成 - 而不在这里构建,否则它们会在
        // 每次旋转时被重建
        val app = application as RdvMedecinsApplication

        setContent {
            // CompositionLocalProvider:让代码块中调用的每个 @Composable 函数
            // 都能使用这四个服务 - 相当于 Flutter 版本的
            // MultiProvider(见 core/Locals.kt)
            CompositionLocalProvider(
                LocalSettings provides app.settings,
                LocalAuth provides app.auth,
                LocalApi provides app.api,
                LocalTranslations provides app.translations,
            ) {
                RdvMedecinsApp()
            }
        }
    }
}

下面对这段代码进行说明:

  • 第 34 行:[onCreate(...)] 在每次创建 Activity 时都会被调用——启动时如此,每次屏幕旋转之后也是如此。这就是服务由 Application 类创建而不在这里创建的原因;
  • 第 39 行:[enableEdgeToEdge()]——应用在整个屏幕上绘制,包括系统状态栏(顶部)和导航栏(底部)之下。[Scaffold] (见 [App.kt])提供必要的边距,使内容不会被这些栏遮挡;
  • 第 44 行:[application as RdvMedecinsApplication]——Activity 的 [application] 属性返回 Application 对象:将其转换为实际类型,以便访问这些服务;
  • 第 46 行:[setContent { ... }]——对应于 [runApp(...)]:Activity 的界面现在由代码块中的 @Composable 函数描述;
  • 第 50–56 行:[CompositionLocalProvider(LocalSettings provides app.settings, ...)]——把四个服务提供给在代码块内调用的整棵 @Composable 函数树:相当于 Flutter 版本的 [MultiProvider] 。[provides] 是一个“中缀”函数:[a provides b] 的写法不带点号和括号(参见 Kotlin 课程)。

5.4.3. core/Locals.kt

由 [MainActivity] 提供的四个服务的“键”。

// =========================================================================
// Locals.kt
// -------------------------------------------------------------------------
// 应用的“CompositionLocal”:Jetpack Compose 的机制,
// 用于让一个对象对整个(WHOLE)@Composable 函数子树可用,
// 而不必逐层作为参数传递。
// 它相当于 Flutter 版本的 provider 包
// (MultiProvider / context.read<...>())、Vue.js 中的 provide/inject,
// 或 React 的 Context。
//
//   - MainActivity 提供(PROVIDES)这些实例:
//         CompositionLocalProvider(LocalAuth provides auth, ...) { ... }
//   - 任何后代 @Composable 函数都读取(READS)它们:
//         val auth = LocalAuth.current
//
// staticCompositionLocalOf(而不是 compositionLocalOf):这些服务
// 在应用的整个生命周期内从不会被其他实例替换(REPLACED),
// 只有它们的内容(CONTENT)会变化 - 而该内容已经
// 通过每个服务的 mutableStateOf 被 Compose 观察。
// { error(...) } 代码块给出默认值:这里是在显示屏幕时
// 若没有提供该服务就抛出的显式异常。
// =========================================================================

package fr.rdvmedecins.client.core

import androidx.compose.runtime.staticCompositionLocalOf
import fr.rdvmedecins.client.core.i18n.TranslationsService
import fr.rdvmedecins.client.core.services.AuthService
import fr.rdvmedecins.client.core.services.AppointmentService
import fr.rdvmedecins.client.core.services.SettingsService

val LocalSettings = staticCompositionLocalOf<SettingsService> { error("SettingsService not provided") }
val LocalAuth = staticCompositionLocalOf<AuthService> { error("AuthService not provided") }
val LocalApi = staticCompositionLocalOf<AppointmentService> { error("AppointmentService not provided") }
val LocalTranslations = staticCompositionLocalOf<TranslationsService> { error("TranslationsService not provided") }

下面对这段代码进行说明:

  • 第 33 行:[staticCompositionLocalOf<AuthService> { ... }]——声明一个类型为 [AuthService] 的 CompositionLocal。代码块指定默认值,在没有提供值时使用:这里是一个显式异常([error(...)]),这比后面出现的含糊错误更清晰;
  • [static...] 而不是 [compositionLocalOf]:“静态”CompositionLocal 不会跟踪所提供实例的替换(那样代价更高)。这在这里行得通:服务从不会被其他实例替换;只有其内容会变化,而该内容已经通过它们的 [mutableStateOf] 属性被观察了。

5.4.4. App.kt

移植自 [lib/app.dart]:根屏幕。它组装 [features/] 中的组件,把它们的操作转发给 ViewModel,并充当“守卫”:只要用户尚未登录,就只显示登录屏幕。它的状态和逻辑定义在 [AppViewModel] 中:这个文件只负责显示(DISPLAYS)。

// =========================================================================
// App.kt
// -------------------------------------------------------------------------
// 移植自 lib/app.dart(Flutter 客户端):应用的根(ROOT)屏幕。
// 与本课程的所有版本一样,它扮演
// “指挥者”的角色 - 组装 lib/features/
// (这里是 features/)中的各个屏幕并转发它们的操作 - 同时扮演“守卫”的角色:只要
// 用户尚未登录,就只显示登录屏幕。
//
// 它的状态和逻辑已移到 AppViewModel(原因见该
// 文件):这个文件只负责显示(DISPLAYS)。
//
// 三个 @Composable 函数:
//   - RdvMedecinsApp:应用的主题(Flutter 一侧的 MaterialApp);
//   - AppRoot:屏幕本身(标题栏 + 内容);
//   - ServerUrlField 和 LanguageSelector:屏幕的两个小元素。
// =========================================================================

package fr.rdvmedecins.client

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.layout.width
import androidx.compose.foundation.layout.widthIn
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ExitToApp
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.TopAppBar
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import fr.rdvmedecins.client.core.LocalAuth
import fr.rdvmedecins.client.core.LocalApi
import fr.rdvmedecins.client.core.LocalSettings
import fr.rdvmedecins.client.core.LocalTranslations
import fr.rdvmedecins.client.core.i18n.TranslationsService
import fr.rdvmedecins.client.features.schedule.ScheduleView
import fr.rdvmedecins.client.features.bookingdialog.BookingDialog
import fr.rdvmedecins.client.features.doctordaypicker.DoctorDayPicker
import fr.rdvmedecins.client.features.login.LoginPage

// -------------------------------------------------------------------------
// 主题:标题栏和按钮使用“主”蓝色,就像
// 本课程 Web 版本的蓝色横幅(navbar bg-primary)
// -------------------------------------------------------------------------
private val appColors = lightColorScheme(
    primary = Color(0xFF1565C0),
    onPrimary = Color.White,
)

@Composable
fun RdvMedecinsApp() {
    MaterialTheme(colorScheme = appColors) {
        AppRoot()
    }
}

// -------------------------------------------------------------------------
// 主屏幕
// -------------------------------------------------------------------------
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppRoot() {
    // 这些服务由 MainActivity 提供(见 core/Locals.kt)
    val auth = LocalAuth.current
    val api = LocalApi.current
    val translations = LocalTranslations.current
    // 对 t(...) 方法的引用:这样 t("APP.TITLE") 的读法
    // 就与课程的其他版本一样
    val t = translations::t

    // viewModel { ... }:如果此屏幕的 ViewModel 已存在
    // (旋转之后),则取回(RETRIEVES)它;首次则用给定的代码块
    // 创建(CREATES)它。因此绝不能写
    // "val vm = AppViewModel(auth, api)":那样每次显示都会
    // 构建一个新的空 ViewModel。
    val vm = viewModel { AppViewModel(auth, api) }

    // 窄屏幕(竖屏的手机):简化标题栏
    val narrow = LocalConfiguration.current.screenWidthDp < 600

    // Scaffold:Material 屏幕的标准结构(标题栏、
    // 内容……)- 与 Flutter 中是同一个组件、同一个名称
    Scaffold(
        topBar = {
            TopAppBar(
                // 在窄屏幕上使用短标题:在 FR/EN 按钮、角色和
                // 登出按钮旁边,
                // 没有足够的空间显示完整标题
                title = {
                    Text(
                        text = if (narrow) "RdvMedecins" else t("APP.TITLE"),
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis,
                    )
                },
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primary,
                    titleContentColor = MaterialTheme.colorScheme.onPrimary,
                    actionIconContentColor = MaterialTheme.colorScheme.onPrimary,
                ),
                // actions:排列在标题栏右侧的元素
                actions = {
                    // FR/EN 选择器:始终(ALWAYS)可见,即使在登录之前
                    LanguageSelector(translations)
                    // 一个简单的 Kotlin if:角色徽章、姓名和
                    // 登出按钮只有在登录后才存在
                    if (auth.isLoggedIn) {
                        Surface(
                            shape = RoundedCornerShape(8.dp),
                            color = Color.White.copy(alpha = 0.2f),
                            contentColor = MaterialTheme.colorScheme.onPrimary,
                        ) {
                            Text(
                                text = auth.role?.name ?: "",
                                style = MaterialTheme.typography.labelMedium,
                                modifier = Modifier.padding(horizontal = 8.dp, vertical = 4.dp),
                            )
                        }
                        // 在窄屏幕上,由于空间不足,姓名被隐藏
                        if (!narrow) {
                            Spacer(Modifier.width(8.dp))
                            Text(auth.name ?: "", color = MaterialTheme.colorScheme.onPrimary)
                        }
                        IconButton(onClick = vm::logOut) {
                            Icon(Icons.AutoMirrored.Filled.ExitToApp, contentDescription = t("APP.LOGOUT"))
                        }
                    }
                },
            )
        },
    ) { systemInsets ->
        // systemInsets:标题栏和系统栏
        // 所占的空间,需要留出(见 enableEdgeToEdge())
        Column(
            modifier = Modifier
                .padding(systemInsets)
                .fillMaxSize()
                // 相当于 Flutter 版本的 SingleChildScrollView
                .verticalScroll(rememberScrollState())
                .padding(16.dp),
        ) {
            // 服务器 URL,登录之前和之后都可编辑
            ServerUrlField(label = t("APP.SERVER_URL_LABEL"))
            Spacer(Modifier.height(16.dp))

            // 错误消息(如果有的话)
            vm.error?.let { message ->
                Surface(
                    color = MaterialTheme.colorScheme.errorContainer,
                    contentColor = MaterialTheme.colorScheme.onErrorContainer,
                    shape = RoundedCornerShape(4.dp),
                    modifier = Modifier.fillMaxWidth(),
                ) {
                    Text(message, modifier = Modifier.padding(12.dp))
                }
                Spacer(Modifier.height(16.dp))
            }

            // “守卫”:未登录 -> 只显示登录屏幕
            if (!auth.isLoggedIn) {
                LoginPage()
            } else {
                // 1. 选择医生和日期
                DoctorDayPicker(doctors = vm.doctors, onSearch = vm::searchSchedule)
                Spacer(Modifier.height(16.dp))
                // 2. 日程;canEdit 对 USER 角色
                //    隐藏“Book”/“Cancel”
                ScheduleView(
                    schedule = vm.schedule,
                    canEdit = auth.isAdmin,
                    onBook = vm::requestBooking,
                    onCancel = vm::cancelAppointment,
                )
            }
        }

        // 3. 预订对话框:只要
        //    有时段正在被预订就显示(见 AppViewModel)
        vm.slotBeingBooked?.let { slot ->
            BookingDialog(
                slot = slot,
                clients = vm.clients,
                onConfirm = vm::confirmBooking,
                onClose = vm::closeBooking,
            )
        }
    }
}

// -------------------------------------------------------------------------
// “Server URL”字段。Flutter 版本需要一个专门的
// StatefulWidget 来创建并随后释放 TextEditingController。
// 在 Compose 中,文本框没有隐藏的状态:它显示(DISPLAYS)value,并
// 通过 onValueChange 报告(REPORTS)每一次按键 - 更新状态由我们负责,
// 这会使字段用新值重新显示。
// 这就是 Vue.js 的“v-model”拆成两个显式的部分来写。
// -------------------------------------------------------------------------
@Composable
private fun ServerUrlField(label: String) {
    val settings = LocalSettings.current
    OutlinedTextField(
        value = settings.apiBaseUrl,
        onValueChange = settings::changeUrl,
        label = { Text(label) },
        singleLine = true,
        // 适合输入 URL 的键盘(“/”、“.”、“:”键……)
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Uri),
        modifier = Modifier.widthIn(max = 360.dp).fillMaxWidth(),
    )
}

// -------------------------------------------------------------------------
// 标题栏的两个 FR / EN 按钮:当前语言
// 以粗体白色显示,另一个以暗淡的白色显示
// -------------------------------------------------------------------------
@Composable
private fun LanguageSelector(translations: TranslationsService) {
    listOf("fr", "en").forEach { language ->
        val current = language == translations.currentLanguage
        TextButton(onClick = { translations.changeLanguage(language) }) {
            Text(
                text = language.uppercase(),
                fontWeight = if (current) FontWeight.Bold else FontWeight.Normal,
                color = MaterialTheme.colorScheme.onPrimary.copy(alpha = if (current) 1f else 0.6f),
            )
        }
    }
}

下面对这段代码进行说明:

  • 第 70–72 行:配色方案:蓝色作为主色([primary]),其上的文字为白色([onPrimary])。其他颜色是 Material 3 的默认颜色;
  • 第 76–78 行:[RdvMedecinsApp] 把主题应用到整个屏幕([MaterialTheme]),类似于 Flutter 的 [MaterialApp];
  • 第 85 行:[@OptIn(ExperimentalMaterial3Api::class)]——[TopAppBar] 在 Material 3 中仍被标记为“实验性”:该注解表示使用时已充分知晓风险(没有它,编译器会拒绝这段代码);
  • 第 89–91 行:这些服务以 CompositionLocal 的方式读取——相当于 [context.read<...>()] / [context.watch<...>()];
  • 第 94 行:[val t = translations::t]——对 [t] 方法的引用(REFERENCE),该方法属于 [translations] 对象:随后我们就可以写 [t("APP.TITLE")],与课程的其他版本一样;
  • 第 101 行:[viewModel { AppViewModel(auth, api) }] - 如果此屏幕的 ViewModel 已存在(旋转之后),则取回(RETRIEVES)它;首次则用所提供的代码块创建(CREATES)它。因此 ViewModel 在 Activity 被重建时仍然存在;
  • 第 104 行:屏幕宽度(以 dp 为单位),从当前配置中读取:小于 600 dp(竖屏的手机)时,标题栏会被简化——使用短标题(第 116 行)并隐藏用户名(第 145 行);
  • 第 108 行:[Scaffold(topBar = { ... }) { systemInsets -> ... }]——Material 屏幕的标准结构,与 Flutter 中一样。最后一个参数是一个 lambda,即屏幕的内容;它接收必须遵守的边距(标题栏和系统栏);
  • 第 110 行:[TopAppBar] – 标题栏,使用主题的主色着色;
  • 第 127–132 行:[actions = { ... }]——排列在栏右侧的元素:语言选择器,始终可见;然后通过一个简单的 [if] 显示角色徽章、姓名和登出按钮,它们只在登录后才出现。由于 [auth.isLoggedIn] 是一个可观察状态,栏会在登录和登出时自动重组;
  • 第 149 行:[onClick = vm::logOut]——作为点击处理程序传递的方法引用;
  • 第 159–165 行:内容:一个可滚动的 [Column] ([verticalScroll],相当于 Flutter 的 [SingleChildScrollView]);
  • 第 172 行:ViewModel 的错误消息(如果有):[vm.error?.let { message -> ... }] 只有当 [error] 不为 [null] 时才输出该代码块;
  • 第 185–197 行:“守卫”:未登录时显示登录屏幕;已登录时显示医生和日期的选择,然后是日历。[canEdit = auth.isAdmin] 会对 USER 角色隐藏预约预订按钮;
  • 第 204–209 行:预订对话框,只要 [vm.slotBeingBooked] 不为 [null] 就会显示(见 [AppViewModel] 和 [BookingDialog]);
  • 第 224–232 行:[ServerUrlField]——“Server URL”字段。在 Compose 中,输入框没有隐藏的状态:它显示(DISPLAYS)[value],并报告每一次按键(通过 [onValueChange])。这里,每次按键都会发送给 [settings.changeUrl(...)],由它更新被观察的状态——然后字段用新值重新绘制。Flutter 版本需要一个 [TextEditingController],因此需要一个专门的 [StatefulWidget] 来创建和释放它;
  • 第 242–245 行:[LanguageSelector]——两个 [TextButton] 实例,“FR”和“EN”,由遍历语言列表的循环生成;当前语言以粗体显示。

5.4.5. AppViewModel.kt

根屏幕的状态和逻辑:[_AppRootState] 部分,来自 [lib/app.dart]。

// =========================================================================
// AppViewModel.kt
// -------------------------------------------------------------------------
// 主屏幕的状态(STATE)和逻辑(LOGIC):Flutter 版本 lib/app.dart 中
// “_AppRootState”的部分(医生、患者、显示的
// 日程、错误、最近一次搜索……)以及对用户
// 操作的响应(搜索日程、预订、取消)。
//
// 为什么用 ViewModel,而不是在 @Composable
// 函数 AppRoot 中使用局部状态(见 App.kt)?因为 Activity 会在每次屏幕旋转时被销毁并
// 重新创建(见 RdvMedecinsApplication):局部
// 状态会丢失 - 只要手机稍微一倾斜,显示的日程就会消失。
// ViewModel(Android Jetpack 的“lifecycle”
// 库)能在这些重建中存活(SURVIVES):Android 会保留它,
// 并把它交给新的 Activity。只有当屏幕被永久离开时它才会被销毁。
// Flutter 没有这个问题:那里旋转
// 不会销毁任何东西,只是屏幕尺寸改变。
//
// 由此形成的划分在 Android 上很经典:App.kt 负责显示(DISPLAYS),这个
// ViewModel 负责决定(DECIDES)并调用服务。
// =========================================================================

package fr.rdvmedecins.client

import android.util.Log
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.compose.runtime.snapshotFlow
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import fr.rdvmedecins.client.core.models.DoctorDaySchedule
import fr.rdvmedecins.client.core.models.Client
import fr.rdvmedecins.client.core.models.SlotJson
import fr.rdvmedecins.client.core.models.Doctor
import fr.rdvmedecins.client.core.models.AppointmentJson
import fr.rdvmedecins.client.core.services.AuthService
import fr.rdvmedecins.client.core.services.AppointmentService
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.launch

class AppViewModel(
    private val auth: AuthService,
    private val api: AppointmentService,
) : ViewModel() {

    // === 由 App.kt 显示的状态(公开读取,私有写入)===
    var doctors by mutableStateOf<List<Doctor>>(emptyList())
        private set
    var clients by mutableStateOf<List<Client>>(emptyList())
        private set
    var schedule by mutableStateOf<DoctorDaySchedule?>(null)
        private set
    var error by mutableStateOf<String?>(null)
        private set

    // 正在预订的时段:非空 = 预订对话框
    // 处于打开状态(见 App.kt 和 BookingDialog.kt)
    var slotBeingBooked by mutableStateOf<SlotJson?>(null)
        private set

    // 最近一次搜索(医生 + 日期),用于在预订或取消之后
    // 刷新日程。从不显示:普通
    // 属性就足够了,无需把它们做成 Compose 状态。
    private var lastDoctorId: Int? = null
    private var lastDay: String? = null

    init {
        // snapshotFlow { ... } 把对 Compose 状态的读取转换为
        // 值的流(FLOW):它立即发出 auth.isLoggedIn 的当前值,
        // 然后是每个新值。它完全等价于
        // Vue.js 的 "watch(() => auth.isLoggedIn, ..., { immediate: true })"
        // - 也等价于 Flutter 版本必须手写的 addListener(...) 订阅 + 初始调用。
        // viewModelScope:在此作用域中启动的协程会在
        // ViewModel 被销毁时自动取消
        // (Flutter 一侧 dispose() 中的
        // removeListener(...) 也就不再需要了)。
        viewModelScope.launch {
            snapshotFlow { auth.isLoggedIn }.collect { loggedIn ->
                if (loggedIn) {
                    loadInitialLists()
                } else {
                    reset()
                }
            }
        }
    }

    // -----------------------------------------------------------------------
    // 登录时(或恢复已记住的会话时):我们
    // 一次性加载医生和患者。两个
    // 独立的协程:两个请求并行(IN PARALLEL)发送。
    // -----------------------------------------------------------------------
    private fun loadInitialLists() {
        runSafely { doctors = api.getAllDoctors() }
        runSafely { clients = api.getAllClients() }
    }

    // -----------------------------------------------------------------------
    // 登出时(点击按钮,或令牌被服务器拒绝):我们清除
    // 业务状态,使新用户哪怕片刻也看不到
    // 上一个用户的日程
    // -----------------------------------------------------------------------
    private fun reset() {
        doctors = emptyList()
        clients = emptyList()
        schedule = null
        error = null
        slotBeingBooked = null
        lastDoctorId = null
        lastDay = null
    }

    // “Log out”按钮:让 AuthService 登出就足够了 -
    // 随后 snapshotFlow(见 init)会触发 reset()
    fun logOut() {
        auth.logOut()
    }

    // -----------------------------------------------------------------------
    // DoctorDayPicker 的“View schedule”按钮
    // -----------------------------------------------------------------------
    fun searchSchedule(doctorId: Int, day: String) {
        error = null
        lastDoctorId = doctorId
        lastDay = day
        loadSchedule()
    }

    // -----------------------------------------------------------------------
    // ScheduleView 的“Book”按钮:我们只是打开(OPEN)对话框,
    // 并记住相关的时段。在 Compose 中,对话框
    // 与其他内容一样属于显示的一部分:
    // 只要 slotBeingBooked 不为 null 它就会
    // 显示(见 App.kt)- 这与 Vue.js 版本中 BookingDialog.vue 的
    // "open" 属性原理相同,而与 Flutter 的 showDialog(...) 相反。
    // -----------------------------------------------------------------------
    fun requestBooking(slot: SlotJson) {
        slotBeingBooked = slot
    }

    // 对话框的“Cancel”按钮(或点击对话框之外)
    fun closeBooking() {
        slotBeingBooked = null
    }

    // 对话框的“Confirm”按钮
    fun confirmBooking(clientId: Int) {
        val slot = slotBeingBooked ?: return
        val day = lastDay ?: return
        slotBeingBooked = null // 关闭对话框
        runSafely {
            api.addAppointment(day, clientId, slot.id)
            loadSchedule() // 该时段现在显示为已被占用
        }
    }

    // -----------------------------------------------------------------------
    // ScheduleView 中已占用时段的“Cancel”按钮
    // -----------------------------------------------------------------------
    fun cancelAppointment(appointment: AppointmentJson) {
        runSafely {
            api.deleteAppointment(appointment.id)
            loadSchedule() // 该时段重新变为空闲
        }
    }

    private fun loadSchedule() {
        val doctorId = lastDoctorId ?: return
        val day = lastDay ?: return
        runSafely { schedule = api.getDoctorScheduleOfDay(doctorId, day) }
    }

    // -----------------------------------------------------------------------
    // 在 ViewModel 协程中运行 [action],并把任何
    // 异常转换为屏幕上显示的错误消息。把这个
    // try/catch 提取出来,避免在上面的每个方法中重复。
    // CancellationException 不是(NOT)错误:它是协程的取消
    // 信号(ViewModel 被销毁),必须让它
    // 继续传播。
    // -----------------------------------------------------------------------
    private fun runSafely(action: suspend () -> Unit) {
        viewModelScope.launch {
            try {
                action()
            } catch (e: CancellationException) {
                throw e
            } catch (e: Exception) {
                Log.w("RdvMedecins", "a server call failed", e) // 见 Logcat
                error = e.message ?: e.toString()
            }
        }
    }
}

下面对这段代码进行说明:

  • 第 45 行:该类继承 [ViewModel];它通过构造函数接收所需的两个服务;
  • 第 48–54 行:由 [App.kt] 显示的状态:[by mutableStateOf(...)] 属性,所有人都可读([App.kt] 会读取它们),但只有 ViewModel 可以修改([private set]);
  • 第 59 行:[slotBeingBooked]——当前正在预订的时段。如果不为 [null],就显示预订对话框;
  • 第 65–66 行:最近一次的搜索(医生和日期),用于在预订或取消之后刷新日历。它们是简单的私有属性:从不显示;
  • 第 78–83 行:[snapshotFlow { auth.isLoggedIn }] 把对 Compose 状态的读取转换为一个流(FLOW),即一个值序列:先立即给出当前值,然后是每个新值。[collect { ... }] 处理其中的每一个:连接时加载医生和患者;断开时清除状态。这相当于 Vue.js 的 [watch(..., { immediate: true })] ,而 Flutter 版本必须用 [addListener(...)] 加上手写的初始调用来复现它;
  • 第 94–96 行:[loadInitialLists()]——两个独立的协程:两个请求并行(IN PARALLEL)发送;
  • 第 116–117 行:[logOut()] 只是让 [AuthService] 断开;随后触发状态清除的是 [snapshotFlow]。当 [AuthInterceptor] 让用户断开连接时(令牌被服务器拒绝),情况也一样:ViewModel 无需知道断开的原因;
  • 第 138–139 行:[requestBooking(...)] 并不打开对话框;它只是保存该时段。显示跟随状态——由 [App.kt] 在 [slotBeingBooked] 不为 [null] 期间发出 [BookingDialog]。因此这个对话框在屏幕旋转后也依然存在(见第 5 章);
  • 第 148–154 行:[confirmBooking(...)]——关闭对话框,然后调用服务器并刷新日历:该时段显示为已预订;
  • 第 182–190 行:[runSafely(action)]——在 ViewModel 的协程中启动 [action] (一个 [suspend] 函数),并把任何异常转换为显示的错误消息。[CancellationException] 会被重新抛出:这不是错误,而是协程取消信号(ViewModel 被销毁),必须允许它继续传播。[Log.w(...)] 把完整的错误写入 Android 日志,可在 Android Studio 的 [Logcat] 选项卡中查看。

5.5. core/models 层

5.5.1. core/models/AppointmentModels.kt

移植自 [lib/core/models/appointment_models.dart]:与服务器交换的数据类。

// =========================================================================
// AppointmentModels.kt
// -------------------------------------------------------------------------
// 与 NestJS 服务器交换的数据类:它们在 Kotlin 中镜像了
// 服务器路由返回的 JSON。移植自
// lib/core/models/appointment_models.dart(本课程的 Flutter 客户端)。
//
// 与 Flutter 版本的主要区别:没有手写的
// fromJson(...) 构造函数。@Serializable 注解要求
// kotlinx.serialization 编译器插件(见 app/build.gradle.kts)
// 在编译时生成(GENERATE)把每个类读写为
// JSON 的代码。与 Dart 一样(而与 TypeScript 不同),类型会
// 在运行时检查:缺少必需的键,或某个键的类型
// 不符合预期,都会立即抛出异常(SerializationException)。
//
// Kotlin 的“数据类”(见 Kotlin 课程)还无需写一行
// 代码就带来:equals/hashCode(按值比较)、toString 和
// copy(...)。所有属性都是只读的(val):这些
// 对象是不可变的(IMMUTABLE),这与 Jetpack Compose 完美契合,
// 因为 Compose 通过比较旧状态和新状态来判断需要重绘什么。
// =========================================================================

package fr.rdvmedecins.client.core.models

import kotlinx.serialization.Serializable

// 一名医生,如 GET /getAllDoctors 所返回(服务器还会发送
// 一个“version”字段,这里借助 ignoreUnknownKeys 将其忽略,见
// Response.kt)
@Serializable
data class Doctor(
    val id: Int,
    val title: String,
    val lastName: String,
    val firstName: String,
)

// 一名患者(医疗诊所的客户),由 GET /getAllClients 返回
@Serializable
data class Client(
    val id: Int,
    val title: String,
    val lastName: String,
    val firstName: String,
)

// 一个就诊时段:startHour/startMinute -> endHour/endMinute
@Serializable
data class SlotJson(
    val id: Int,
    val startHour: Int,
    val startMinute: Int,
    val endHour: Int,
    val endMinute: Int,
)

// 一个预约:一个日期、一名患者、一个时段。默认值“= null”
// 使这些键在收到的 JSON 中成为可选。
@Serializable
data class AppointmentJson(
    val id: Int,
    val day: String, // “yyyy-MM-dd”格式
    val client: Client? = null,
    val slot: SlotJson? = null,
)

// 日程的一行:一个时段,以及(如果已被占用)它的预约
@Serializable
data class DoctorDaySlot(
    val slot: SlotJson,
    val appointment: AppointmentJson? = null, // null = 空闲时段
)

// 某位医生某一天的日程,由
// GET /getDoctorScheduleOfDay/{doctorId}/{day} 返回
@Serializable
data class DoctorDaySchedule(
    val doctor: Doctor,
    val day: String,
    val slots: List<DoctorDaySlot>,
)

// -------------------------------------------------------------------------
// 身份验证
// -------------------------------------------------------------------------

// 应用的两个角色。常量名称
// 恰好(EXACTLY)就是服务器发送的字符串("ADMIN"、"USER"):
// 因此 kotlinx.serialization 直接把 JSON 字符串转换为
// 枚举常量,而 Flutter 版本需要手写
// Role.fromString(...) 和 asString()。
@Serializable
enum class Role { ADMIN, USER }

// 发送到 POST /login 的 JSON 请求体
@Serializable
data class LoginRequest(
    val login: String,
    val password: String,
)

// POST /login 响应中“data”的内容
@Serializable
data class LoginResult(
    val accessToken: String, // 在之后的每个请求中都要出示的 JWT 令牌
    val login: String,
    val name: String,
    val role: Role,
)

// 发送到 POST /addAppointment 和 POST /deleteAppointment 的 JSON 请求体
@Serializable
data class AddAppointmentRequest(
    val day: String,
    val clientId: Int,
    val slotId: Int,
)

@Serializable
data class DeleteAppointmentRequest(
    val appointmentId: Int,
)

下面对这段代码进行说明:

  • 第 30–31 行:[@Serializable data class Doctor(...)]——一个“数据类”(参见 Kotlin 课程):[equals]/[hashCode] 按值比较,[toString]、[copy(...)],无需写一行代码。注解 [@Serializable] 指示 kotlinx.serialization 插件在编译时生成读写该类 JSON 的代码——而 Flutter 版本需要为每个类手写一个 [fromJson(...)] 构造函数;
  • 第 63 行:[val client: Client? = null]——带默认值的可空类型:键 [client] 可能不出现在收到的 JSON 中,也可能为 [null];
  • 第 71 行:[val appointment: AppointmentJson? = null] - [null] 表示该时段可用;
  • 第 93 行:[enum class Role { ADMIN, USER }]——常量名称恰好就是服务器发送的字符串:kotlinx.serialization 直接把 ["ADMIN"] 转换为 [Role.ADMIN],而 Flutter 版本需要写 [Role.fromString(...)] 和 [asString()];
  • 第 97、113 和 120 行:发送(SENT)给服务器的 JSON 请求体所用的类([LoginRequest]、[AddAppointmentRequest]、[DeleteAppointmentRequest]):同一个注解 [@Serializable],也用于编码。Flutter 版本则使用字面量 [Map] 值来构造这些请求体。

5.5.2. core/models/Response.kt

解码服务器所有业务响应共有的 [{ status, data }] 封装。

// =========================================================================
// Response.kt
// -------------------------------------------------------------------------
// NestJS 服务器所有的业务响应都具有相同的形状:
//
//     { "status": 0, "data": ... }
//
// 其中 status 在成功时为 0(见服务器端的 ResponseStatus)。
// Flutter 版本用泛型类
// ServerResponse<T> 解码这个信封。这里我们分两步(TWO steps)进行,原因特殊:出错时,
// 服务器在“data”中放入的是消息列表
// (List<String>),而成功时我们预期得到的是例如一个日程。
// 如果立即把 {status, data} 解码为 ServerResponse<DoctorDaySchedule>,
// 那么遇到错误响应时就会失败,甚至来不及读取 status。
//   1. 我们把信封读取为通用的 JSON 树(JsonObject);
//   2. 我们检查 status;只有当它为 0 时,才把“data”解码为
//      预期的类型。
// =========================================================================

package fr.rdvmedecins.client.core.models

import kotlinx.serialization.DeserializationStrategy
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonNull
import kotlinx.serialization.json.int
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive

// 整个客户端共享的 JSON 配置:
// - ignoreUnknownKeys:服务器会发送本客户端
//   不使用的字段(例如医生的“version”)- 我们忽略它们,而不是
//   抛出异常;
// - explicitNulls = false:编码时不写入值为 null 的属性
//   (对本客户端的类没有影响,但更接近
//   JavaScript 一侧 JSON.stringify 的行为)。
val ApiJson = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
}

// 当服务器返回的业务状态不是
// 0 时抛出的异常(资源未找到、日期无效、服务器错误)
class ResponseException(val status: Int) :
    Exception("The server responded with error status $status")

// 解码 {status, data} 响应的响应体,并以 [deserializer] 所描述的
// 类型 T 返回“data”(例如 Doctor.serializer(),或用于医生列表的
// ListSerializer(Doctor.serializer()))
fun <T> decodeResponse(body: String, deserializer: DeserializationStrategy<T>): T {
    // 1. 信封,作为通用的 JSON 树
    val envelope = ApiJson.parseToJsonElement(body).jsonObject
    // 2. 业务状态
    val status = envelope.getValue("status").jsonPrimitive.int
    if (status != 0) {
        throw ResponseException(status)
    }
    // 3. “data”,直到此时才解码为预期的类型
    val data = envelope["data"] ?: JsonNull
    return ApiJson.decodeFromJsonElement(deserializer, data)
}

下面对这段代码进行说明:

  • 第 36–38 行:[ApiJson]——整个客户端共享的 JSON 配置。[ignoreUnknownKeys = true]:服务器会发送客户端不使用的字段(例如医生的 [version] );没有这个设置,kotlinx.serialization 在遇到第一个未知键时就会抛出异常;
  • 第 43 行:[ResponseException]——当服务器返回的业务状态不是 0 时抛出的异常;
  • 第 49 行:[decodeResponse(body, deserializer)] - 一个泛型函数:参数 [deserializer] (例如由插件生成的 [Doctor.serializer()])指定 [T] 类型,用于解码 [data];
  • 第 51–59 行:解码分两步进行。首先,把信封读取为通用的 JSON 树([JsonObject]);然后,只有当 [status] 为 0 时,才把 [data] 解码为预期的类型。原因:出错时,服务器在 [data] 中放入的是消息列表,而成功时预期得到的则是例如一个日历。如果立即把整个信封解码为成功类型,那么在遇到错误响应时会失败,甚至来不及读取状态。

5.6. core/services 层

5.6.1. core/services/SettingsService.kt

移植自 [lib/core/services/settings_service.dart]:服务器的 URL。

// =========================================================================
// SettingsService.kt
// -------------------------------------------------------------------------
// 移植自 lib/core/services/settings_service.dart:保存
// NestJS 服务器的 URL,可在屏幕上编辑(“Server URL”字段)。
//
// Flutter 版本继承 ChangeNotifier,必须在每次更改后调用
// notifyListeners()。这里,该属性使用
// "by mutableStateOf(...)" 声明:它是 Jetpack Compose 的
// 可观察状态(OBSERVABLE STATE)。任何在显示期间读取(READS)apiBaseUrl 的
// @Composable 函数都会在值变化时自动重新显示 -
// 无需 notifyListeners(),也无需 context.watch<...>():Compose 自己记录
// 每一次读取(与 Vue.js 一侧的 reactive(...) / ref(...)
// 原理相同)。
//
// 相对于 Flutter 版本的小改进:URL 保存在
// 手机的 SharedPreferences 中,这样就不必在每次启动应用时
// 重新输入
// (在移动端,它几乎总是与默认值不同,见第 5 章)。
// =========================================================================

package fr.rdvmedecins.client.core.services

import android.content.SharedPreferences
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.core.content.edit

class SettingsService(private val prefs: SharedPreferences) {

    // 初始值从偏好设置中同步(SYNCHRONOUSLY)读回:
    // getString(...) 立即返回(偏好设置在首次访问时
    // 加载到内存中)。“private set”:只有这个类
    // 能通过 changeUrl(...) 修改 URL。
    var apiBaseUrl: String by mutableStateOf(prefs.getString(URL_KEY, null) ?: DEFAULT_URL)
        private set

    fun changeUrl(url: String) {
        if (url == apiBaseUrl) {
            return // 避免无谓的重新显示和写入
        }
        apiBaseUrl = url
        // edit { ... }:来自 androidx.core(core-ktx)的扩展函数;
        // 它打开一个编辑器,运行代码块,然后调用 apply(),后者
        // 在后台写入磁盘,不会阻塞 UI。
        prefs.edit { putString(URL_KEY, url) }
    }

    companion object {
        // 10.0.2.2:在 Android 模拟器中,这个特殊地址
        // 指代宿主机,即运行 NestJS 服务器的那台机器
        // (localhost 则指代模拟器本身,见第 5 章)
        const val DEFAULT_URL = "http://10.0.2.2:8080"
        private const val URL_KEY = "rdvmedecins.apiBaseUrl"
    }
}

下面对这段代码进行说明:

  • 第 36–37 行:[var apiBaseUrl: String by mutableStateOf(...)]——一个可观察状态,用偏好设置中保存的值或默认值初始化。[private set]:只有这个类可以修改它;
  • 第 39 行:[changeUrl(...)]——该方法不能命名为 [setApiBaseUrl]:这个名称已被 Kotlin 为属性 [apiBaseUrl] 生成的私有“setter”使用(两者在 JVM 上会有相同的签名);
  • 第 47 行:[prefs.edit { putString(...) }]——来自 [core-ktx] 库的扩展函数:它打开一个编辑器,执行代码块,然后调用 [apply()],在后台写入磁盘。因此 URL 会在下次启动时保留(相对于 Flutter 版本的一个小改进,在手机上很有用,因为那里的 URL 几乎总是与默认值不同);
  • 第 54 行:[DEFAULT_URL = "http://10.0.2.2:8080"]——从 Android 模拟器看到的服务器地址(见第 5 章)。同时面向 Web 和桌面的 Flutter 版本使用的是 [localhost]。

5.6.2. core/services/AuthService.kt

移植自 [lib/core/services/auth_service.dart]:已登录用户的会话、登录和登出。

// =========================================================================
// AuthService.kt
// -------------------------------------------------------------------------
// 移植自 lib/core/services/auth_service.dart:已登录用户
// (JWT 令牌、登录名、姓名、角色)的会话、登录
// (POST /login)和登出。
//
// 与 SettingsService 一样,UI 显示的属性是
// Compose 状态(mutableStateOf):一旦 isLoggedIn 变为 true,显示就会自动(AUTOMATICALLY)从
// 登录屏幕切换到日程。
//
// 会话保存在 SharedPreferences 中:重启应用的用户
// 无需重新登录就能恢复会话(只要令牌
// 尚未过期 - 令牌过期的情况见 AuthInterceptor)。
// 与 Flutter 的区别:SharedPreferences(原始的 Android API,
// Flutter 的 shared_preferences 包就借用了它的名称)是
// 同步(SYNCHRONOUSLY)读取的。因此会话直接在构造函数(init
// 块)中恢复,无需在显示
// 第一个屏幕之前等待异步的 init() 方法。
// =========================================================================

package fr.rdvmedecins.client.core.services

import android.content.SharedPreferences
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.core.content.edit
import fr.rdvmedecins.client.core.models.ApiJson
import fr.rdvmedecins.client.core.models.LoginRequest
import fr.rdvmedecins.client.core.models.LoginResult
import fr.rdvmedecins.client.core.models.Role
import fr.rdvmedecins.client.core.models.decodeResponse
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import java.io.IOException

class AuthService(
    private val settings: SettingsService,
    private val prefs: SharedPreferences,
    // 不带身份验证拦截器的 HTTP 客户端:POST /login
    // 是服务器唯一的公开路由,没有令牌
    // 可发送(见 RdvMedecinsApplication)
    private val http: OkHttpClient,
) {
    // === 会话状态,由 UI 观察 ===
    var isLoggedIn by mutableStateOf(false)
        private set
    var login by mutableStateOf<String?>(null)
        private set
    var name by mutableStateOf<String?>(null)
        private set
    var role by mutableStateOf<Role?>(null)
        private set

    // 令牌从不显示(DISPLAYED):无需把它做成 Compose 状态。
    // 不过 AuthInterceptor 会在网络线程上读取它:
    // @Volatile 保证该线程总能看到
    // 主线程写入的最新值。
    @Volatile
    var accessToken: String? = null
        private set

    // 计算属性:每次访问时都重新读取 role(并且当在
    // 显示期间读取时,使该显示订阅 role 的变化)
    val isAdmin: Boolean
        get() = role == Role.ADMIN

    init {
        restoreSession()
    }

    // -----------------------------------------------------------------------
    // 重新读取可能在上次启动时保存的会话
    // -----------------------------------------------------------------------
    private fun restoreSession() {
        val raw = prefs.getString(SESSION_KEY, null) ?: return // 没有已保存的会话
        try {
            // 会话是以序列化为 JSON 的 LoginResult
            // 形式保存的(见 logIn):我们原样读回
            applySession(ApiJson.decodeFromString(LoginResult.serializer(), raw))
        } catch (e: Exception) {
            // 内容不可读(例如应用旧版本的格式):
            // 我们将其丢弃,用户需要重新登录
            prefs.edit { remove(SESSION_KEY) }
        }
    }

    // -----------------------------------------------------------------------
    // POST /login。“suspend”:该函数可以在服务器响应所需的
    // 时间内暂停,而不阻塞调用线程 -
    // 相当于 Dart 一侧返回 Future<LoginResult> 的
    // async 函数。如果登录失败,它会抛出异常。
    // -----------------------------------------------------------------------
    suspend fun logIn(login: String, password: String): LoginResult {
        // withContext(Dispatchers.IO):代码块在专为输入/输出保留的
        // 线程上运行。Android 禁止(FORBIDS)从主线程进行任何网络访问
        // (NetworkOnMainThreadException):主线程
        // 负责绘制 UI,绝不能等待。
        val result = withContext(Dispatchers.IO) {
            val body = ApiJson.encodeToString(LoginRequest.serializer(), LoginRequest(login, password))
            val request = Request.Builder()
                .url("${settings.apiBaseUrl}/login")
                .post(body.toRequestBody(JSON_TYPE))
                .build()
            // execute():阻塞(BLOCKING)调用 - 在这里没有危害,因为我们处在
            // 输入/输出线程上。use { } 会在代码块结束时关闭响应,
            // 无论发生什么(相当于 Java 的
            // try-with-resources,见 Kotlin 课程)。
            http.newCall(request).execute().use { response ->
                // 凭据错误:服务器返回 401 Unauthorized
                if (!response.isSuccessful) {
                    throw IOException("Login failed (HTTP ${response.code})")
                }
                decodeResponse(response.body!!.string(), LoginResult.serializer())
            }
        }
        // 回到调用方的线程(主线程):
        // 正是在这里,而不是在输入/输出线程上,我们修改
        // UI 所观察的状态
        applySession(result)
        prefs.edit { putString(SESSION_KEY, ApiJson.encodeToString(LoginResult.serializer(), result)) }
        return result
    }

    // -----------------------------------------------------------------------
    // 登出:我们丢弃会话,包括内存中和偏好设置中的会话。
    // 必须在主线程上调用(见 AuthInterceptor)。
    // -----------------------------------------------------------------------
    fun logOut() {
        accessToken = null
        login = null
        name = null
        role = null
        isLoggedIn = false
        prefs.edit { remove(SESSION_KEY) }
    }

    private fun applySession(session: LoginResult) {
        accessToken = session.accessToken
        login = session.login
        name = session.name
        role = session.role
        isLoggedIn = true
    }

    companion object {
        private const val SESSION_KEY = "rdvmedecins.session"
        private val JSON_TYPE = "application/json; charset=utf-8".toMediaType()
    }
}

下面对这段代码进行说明:

  • 第 51–57 行:界面所观察的会话状态:[isLoggedIn]、[login]、[name]、[role];
  • 第 64–65 行:[accessToken] 从不显示:无需把它做成 Compose 状态。不过,[AuthInterceptor] 会在网络线程上读取它:[@Volatile] 确保该线程总能看到主线程写入的最新值;
  • 第 70–71 行:[isAdmin]——一个计算属性([get() = ...]),每次访问时都会重新读取;
  • 第 73–85 行:[init] 块在服务初始化时立即恢复任何已缓存的会话:偏好设置是同步读取的。会话以序列化为 JSON 的 [LoginResult] 形式存储,随后用 [decodeFromString(LoginResult.serializer(), raw)] 读回;
  • 第 99 行:[suspend fun logIn(...)]——一个挂起函数:它在等待服务器响应时暂停,而不阻塞调用线程;
  • 第 104 行:[withContext(Dispatchers.IO) { ... }]——请求在 I/O 线程上执行;代码块中最后一个表达式的值(解码得到的 [LoginResult])就是结果;
  • 第 106–109 行:OkHttp 请求:[Request.Builder()]、URL,然后是 [.post(body.toRequestBody(JSON_TYPE))]——JSON 请求体及其 MIME 类型;
  • 第 114 行:[execute()] 以阻塞方式执行请求——在 I/O 线程上这样做是安全的。[use { response -> ... }] 无论发生什么,都会在代码块结束时关闭响应:相当于 Java 的 `try-with-resources`;
  • 第 116–117 行:凭据不正确:服务器返回 401 Unauthorized 响应;抛出一个异常,[LoginPage] 将其转换为错误消息;
  • 第 125–126 行:回到调用线程(主线程)后,应用会话——这会改变被观察的状态:屏幕自动切换到日历——然后把它保存到偏好设置中;
  • 第 134–140 行:[logOut()]——丢弃会话,包括内存中和偏好设置中的会话。

5.6.3. core/services/AppointmentService.kt

移植自 [lib/core/services/appointment_service.dart]:客户端使用的每个业务路由对应一个方法。

// =========================================================================
// AppointmentService.kt
// -------------------------------------------------------------------------
// 移植自 lib/core/services/appointment_service.dart:本客户端使用的 NestJS 服务器的每个业务
// 路由对应一个方法。每个方法都是一个
// “suspend”函数(见 AuthService.logIn),直接返回
// 有用的数据({status, data} 信封中的“data”),或者
// 抛出异常。
//
// 构造函数中接收的 HTTP 客户端包含 AuthInterceptor(见
// RdvMedecinsApplication):因此下面的任何方法都无需
// 关心 JWT 令牌。
//
// 这个服务没有可观察状态(构建之后其中没有任何东西会变化):
// 它是一个普通类,不使用 mutableStateOf -
// 相当于 Flutter 版本中
// 简单的 Provider.value(value: api)(而不是 ChangeNotifierProvider)。
// =========================================================================

package fr.rdvmedecins.client.core.services

import fr.rdvmedecins.client.core.models.DoctorDaySchedule
import fr.rdvmedecins.client.core.models.AddAppointmentRequest
import fr.rdvmedecins.client.core.models.Client
import fr.rdvmedecins.client.core.models.ApiJson
import fr.rdvmedecins.client.core.models.Doctor
import fr.rdvmedecins.client.core.models.AppointmentJson
import fr.rdvmedecins.client.core.models.DeleteAppointmentRequest
import fr.rdvmedecins.client.core.models.decodeResponse
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.DeserializationStrategy
import kotlinx.serialization.builtins.ListSerializer
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 AppointmentService(
    private val http: OkHttpClient,
    private val settings: SettingsService,
) {
    // -----------------------------------------------------------------------
    // GET 路由
    // -----------------------------------------------------------------------
    suspend fun getAllDoctors(): List<Doctor> =
        call(getRequest("/getAllDoctors"), ListSerializer(Doctor.serializer()))

    suspend fun getAllClients(): List<Client> =
        call(getRequest("/getAllClients"), ListSerializer(Client.serializer()))

    suspend fun getDoctorScheduleOfDay(doctorId: Int, day: String): DoctorDaySchedule =
        call(getRequest("/getDoctorScheduleOfDay/$doctorId/$day"), DoctorDaySchedule.serializer())

    // -----------------------------------------------------------------------
    // POST 路由(服务器将其保留给 ADMIN 角色)
    // -----------------------------------------------------------------------
    suspend fun addAppointment(day: String, clientId: Int, slotId: Int): AppointmentJson {
        val body = ApiJson.encodeToString(
            AddAppointmentRequest.serializer(),
            AddAppointmentRequest(day, clientId, slotId),
        )
        return call(postRequest("/addAppointment", body), AppointmentJson.serializer())
    }

    suspend fun deleteAppointment(appointmentId: Int) {
        val body = ApiJson.encodeToString(DeleteAppointmentRequest.serializer(), DeleteAppointmentRequest(appointmentId))
        // 成功时“data”为 null:我们把它解码为任意 JSON
        // 元素,并忽略它
        call(postRequest("/deleteAppointment", body), JsonElement.serializer())
    }

    // -----------------------------------------------------------------------
    // 构建请求
    // -----------------------------------------------------------------------
    private fun getRequest(path: String): Request =
        Request.Builder().url(settings.apiBaseUrl + path).get().build()

    private fun postRequest(path: String, jsonBody: String): Request =
        Request.Builder()
            .url(settings.apiBaseUrl + path)
            .post(jsonBody.toRequestBody(JSON_TYPE))
            .build()

    // -----------------------------------------------------------------------
    // 在输入/输出线程上运行请求并解码
    // {status, data} 响应。泛型参数 <T> 以及与之配套的
    // [deserializer] 指明把“data”解码为
    // 哪种类型 - 相当于 Flutter 版本中 parseData 参数的作用。
    // -----------------------------------------------------------------------
    private suspend fun <T> call(request: Request, deserializer: DeserializationStrategy<T>): T =
        withContext(Dispatchers.IO) {
            http.newCall(request).execute().use { response ->
                // 401(令牌被拒绝)、403(角色不足)、404……:响应
                // 体不是 {status, data} 信封
                if (!response.isSuccessful) {
                    throw IOException("HTTP error ${response.code}")
                }
                decodeResponse(response.body!!.string(), deserializer)
            }
        }

    companion object {
        private val JSON_TYPE = "application/json; charset=utf-8".toMediaType()
    }
}

下面对这段代码进行说明:

  • 第 48–55 行:三个 GET 路由。每个方法都是写成表达式的 [suspend] 函数:它构造请求并指定 [data] 的预期类型。[ListSerializer(Doctor.serializer())] 描述一个 [List<Doctor>];
  • 第 60–72 行:两个 POST 路由:JSON 请求体由 [AddAppointmentRequest] 和 [DeleteAppointmentRequest] 类编码而来。对于 [/deleteAppointment],成功时 [data] 等于 [null] :它被解码为任意 JSON 元素([JsonElement.serializer()])并被忽略;
  • 第 93–101 行:[call(...)]——标准方法:在 I/O 线程上执行,检查 HTTP 状态码(401 令牌被拒绝,403 角色不足:因此响应体不是 [{status, data}] 封装),然后用 [decodeResponse(...)] 解码。

该服务没有可观察状态:构造之后不会发生任何变化。它是一个普通类——相当于 Flutter 版本中简单的 [Provider.value(value: api)] (而不是 [ChangeNotifierProvider])。

5.7. core/http

5.7.1. core/http/AuthInterceptor.kt

移植自 [lib/core/http/auth_http_client.dart]:向每个请求添加 JWT 令牌,并在收到 401 响应时登出。

// =========================================================================
// AuthInterceptor.kt
// -------------------------------------------------------------------------
// 移植自 lib/core/http/auth_http_client.dart。两项职责,
// 与本课程所有版本中的相同:
//   1. 在每个请求中添加“Authorization: Bearer <token>”请求头;
//   2. 如果服务器返回 401 Unauthorized(令牌已过期或无效),
//      就让用户登出。
//
// Flutter 版本把 HTTP 客户端包装在自己的类中,
// 因为 http 包缺少拦截机制。而 OkHttp
// 提供了拦截器(INTERCEPTORS):每个请求在发送之前、
// 每个响应在返回给
// 调用方之前都要经过的对象 - 这正是 Angular 的 HTTP 拦截器的概念
// (本课程 Angular 版本中的 auth.interceptor.ts)。
// =========================================================================

package fr.rdvmedecins.client.core.http

import android.os.Handler
import android.os.Looper
import fr.rdvmedecins.client.core.services.AuthService
import okhttp3.Interceptor
import okhttp3.Response

class AuthInterceptor(private val auth: AuthService) : Interceptor {

    // 与主线程绑定的 Handler:它让我们可以从另一个线程
    // 把工作交给它(见下面的 intercept)
    private val mainThread = Handler(Looper.getMainLooper())

    // OkHttp 为每个(EACH)请求在网络线程上调用
    override fun intercept(chain: Interceptor.Chain): Response {
        // 1. 原始请求,如果有令牌则加上令牌。
        //    OkHttp 请求是不可变的:newBuilder() 会创建它的
        //    可修改副本。
        val token = auth.accessToken
        val request = if (token == null) {
            chain.request()
        } else {
            chain.request().newBuilder()
                .header("Authorization", "Bearer $token")
                .build()
        }
        // 2. 让请求继续发往服务器
        val response = chain.proceed(request)
        // 3. 令牌被拒绝:我们让用户登出。该方法
        //    在网络线程上运行;而 logOut() 会修改
        //    UI 显示的状态:因此我们把这个调用交给
        //    主线程(post),不等待它运行 - 相当于
        //    Flutter 版本中的 unawaited(auth.logOut())。
        if (response.code == 401) {
            mainThread.post { auth.logOut() }
        }
        return response
    }
}

下面对这段代码进行说明:

  • 第 26 行:该类实现 [okhttp3.Interceptor] 接口。OkHttp 在发送每个请求之前,以及在把每个响应返回给调用方之前,都会让它们经过客户端的拦截器:这就是 Angular 的 HTTP 拦截器的概念。Flutter 版本由于 [http] 包中缺少这种机制,只能把 HTTP 客户端包装在自己的类中;
  • 第 30 行:与主线程关联的 [Handler] ([Looper.getMainLooper()]):这使得可以从另一个线程把工作委托给它;
  • 第 41–43 行:OkHttp 请求是不可变的(IMMUTABLE);[newBuilder()] 创建它的一个可修改副本,并添加请求头 [Authorization];
  • 第 46 行:[chain.proceed(request)]——请求继续发往服务器;该方法返回响应;
  • 第 52–53 行:令牌被拒绝(401):[intercept] 在网络线程上运行,但 [logOut()] 会修改显示的状态。因此该调用被委托给主线程([post { ... }]),不等待其执行——相当于 Flutter 版本中的 [unawaited(auth.logOut())] 。

5.8. core/i18n

5.8.1. core/i18n/TranslationsService.kt

移植自 [lib/core/i18n/translations_service.dart]:在法语和英语之间动态切换界面。

// =========================================================================
// TranslationsService.kt
// -------------------------------------------------------------------------
// 移植自 lib/core/i18n/translations_service.dart:在法语和英语之间
// 动态切换 UI,无需重启
// 应用。这些字典与本课程 Flutter 和 Vue.js 客户端使用的是相同(SAME)的 JSON 文件
// (fr.json、en.json),这里放在
// app/src/main/assets/i18n/ 中:Android 项目的 assets/ 文件夹
// 会原样嵌入应用(.apk 文件),
// 就像 Flutter 版本的 pubspec.yaml 中声明的资源一样。
//
// 注意:Android 翻译应用的“官方”方式
// 依赖资源文件 res/values/strings.xml
// (英语)和 res/values-fr/strings.xml(法语),由系统
// 根据手机(PHONE)的语言选择正确的文件。本文档
// 保留了课程所有版本共用的 JSON 字典,
// 以及应用内部的 FR/EN 切换,就像
// 原始应用(2014 年)那样。
// =========================================================================

package fr.rdvmedecins.client.core.i18n

import android.content.SharedPreferences
import android.content.res.AssetManager
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.core.content.edit
import fr.rdvmedecins.client.core.models.ApiJson
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.jsonObject

class TranslationsService(
    private val assets: AssetManager,
    private val prefs: SharedPreferences,
) {
    // 显示的语言:一个 Compose 状态。由于下面的 t(...) 会读取(READS)
    // 这个属性,任何用 t(...) 显示的文本都会在语言变化时
    // 自动重新显示 - 与 Flutter 版本不同,无需编写
    // context.watch<...>()。
    var currentLanguage by mutableStateOf(prefs.getString(LANGUAGE_KEY, null) ?: DEFAULT_LANGUAGE)
        private set

    // 已加载的字典,按语言区分(“fr” -> {...})
    private val dictionaries = mutableMapOf<String, JsonObject>()

    fun changeLanguage(language: String) {
        if (language == currentLanguage) {
            return
        }
        dictionary(language) // 在更改语言之前(BEFORE)先加载字典
        currentLanguage = language
        prefs.edit { putString(LANGUAGE_KEY, language) }
    }

    // -----------------------------------------------------------------------
    // t("LOGIN.TITLE"):逐段遍历当前语言的字典
    // (“LOGIN”,然后是“TITLE”)。如果找不到该键,
    // 就返回键本身:这样缺失的文本会保留在屏幕上
    // 可见,而不会导致应用崩溃。
    // -----------------------------------------------------------------------
    fun t(key: String): String {
        var currentValue: JsonElement = dictionary(currentLanguage)
        for (segment in key.split('.')) {
            currentValue = (currentValue as? JsonObject)?.get(segment) ?: return key
        }
        val primitive = currentValue as? JsonPrimitive
        return if (primitive != null && primitive.isString) primitive.content else key
    }

    // -----------------------------------------------------------------------
    // 某种语言的字典,在首次需要时加载,然后保存在
    // 内存中。getOrPut:返回与该键关联的值,或者运行
    // 代码块,保存其结果并返回。读取是
    // 同步的:这两个文件只有几百
    // 字节,读取是瞬时完成的。
    // -----------------------------------------------------------------------
    private fun dictionary(language: String): JsonObject =
        dictionaries.getOrPut(language) {
            assets.open("i18n/$language.json").bufferedReader().use { reader ->
                ApiJson.parseToJsonElement(reader.readText()).jsonObject
            }
        }

    companion object {
        private const val LANGUAGE_KEY = "rdvmedecins.language"
        private val DEFAULT_LANGUAGE = if (java.util.Locale.getDefault().language == "fr") "fr" else "en"
    }
}

下面对这段代码进行说明:

  • 第 43–44 行:[currentLanguage]——一个可观察状态。由于 [t(...)] 会读取(READS)这个属性,因此任何使用 [t(...)] 显示文本的 @Composable 函数都会在语言变化时自动重组:无需编写任何 [context.watch<...>()];
  • 第 49–55 行:[changeLanguage(...)]——在切换语言之前先加载字典,然后把所选语言保存到偏好设置中;
  • 第 64–70 行:[t("LOGIN.TITLE")]——逐段遍历字典。[as?] 是 Kotlin 的“安全”类型转换:如果对象不是所请求的类型,它返回 [null] (而不是抛出异常);与 [?: return key] 结合使用时,一旦某一段找不到,就会直接返回键本身——缺失的文本会保留在屏幕上;
  • 第 80–83 行:[dictionary(language)] – [getOrPut] 返回已加载的字典,或者执行代码块(读取 [assets/i18n/<language>.json]),保存其结果并返回。读取是同步的:这两个文件都只有几百字节大小。

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

这些字典来自 Flutter 和 Vue.js 客户端,只做了四处小调整:应用标题、日期选择器的标签([DOCTOR_DAY_PICKER.PICK_DAY]、[OK]、[CANCEL])、日历提示消息(用“tap”(点按)代替“click”(点击)),以及删除一个不再需要的键。摘自 [fr.json] 的节选:

{
  "APP": {
    "TITLE": "RdvMedecins - Kotlin / Android",
    "SERVER_URL_LABEL": "URL du serveur",
    "LOGOUT": "Se déconnecter"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "SUBMITTING": "Connexion...",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS_PREFIX": "Comptes de démonstration :",
    "DEMO_ACCOUNTS_ADMIN": "(rôle ADMIN, accès complet)",
    "DEMO_ACCOUNTS_OR": "ou",
    "DEMO_ACCOUNTS_USER": "(rôle USER, lecture seule)"
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda",
    "PICK_DAY": "Choisir le jour",
    "OK": "OK",
    "CANCEL": "Annuler"
  },

注意:Android 翻译应用的“官方”方法依赖资源文件 [res/values/strings.xml](英语)和 [res/values-fr/strings.xml](法语),由系统根据手机的语言选择正确的文件。本文档保留了课程所有版本共用的 JSON 字典,以及应用内部的 FR/EN 语言切换,与原始应用(2014 年)一样。一个明显的后果是:系统提供的组件(例如日期选择器)遵循手机的语言设置,而不是应用内选择的语言。

5.9. core/ui 层

5.9.1. core/ui/DropdownList.kt

一个通用的下拉列表,使用两次:用于选择医生和选择患者。Flutter 为此提供了现成的组件 [DropdownButtonFormField];Compose 的 Material 3 则提供三个元素的组合,这里把它们一次性地封装在一起。

// =========================================================================
// DropdownList.kt
// -------------------------------------------------------------------------
// 一个通用的下拉列表(相当于 HTML 的 <select>),在本客户端中
// 使用两次:选择医生(DoctorDayPicker)和选择患者
// (BookingDialog)。Flutter 版本为此提供了现成的组件
// DropdownButtonFormField;Compose 的 Material 3 则提供
// 三个元素的组合 - ExposedDropdownMenuBox、一个只读
// 文本框和 ExposedDropdownMenu 菜单 - 我们在这里
// 一次性地把它们封装在一起。
//
// 该函数是泛型(GENERIC)的(<T>):它既可以显示医生列表
// 也可以显示患者列表。[itemLabel] 说明如何显示一项,
// [idOf] 说明如何标识它。
// =========================================================================

package fr.rdvmedecins.client.core.ui

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.ExposedDropdownMenuBox
import androidx.compose.material3.ExposedDropdownMenuDefaults
import androidx.compose.material3.ExposedDropdownMenuAnchorType
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

// ExposedDropdownMenu* 这些 API 在 Material 3 中仍被标记为“实验性”:
// @OptIn 表示我们是在知情的情况下使用它们
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun <T> DropdownList(
    label: String,
    placeholder: String,     // 在尚未选择任何内容时显示的文本
    items: List<T>,
    selectedId: Int?,        // 所选项的 id,或 null
    idOf: (T) -> Int,
    itemLabel: (T) -> String,
    onSelect: (Int) -> Unit,
    modifier: Modifier = Modifier,
) {
    // 菜单打开或关闭:这个函数的局部(LOCAL)状态,由 remember 在
    // 多次显示之间保存(见第 3 章)
    var menuOpen by remember { mutableStateOf(false) }
    val selected = items.firstOrNull { idOf(it) == selectedId }

    ExposedDropdownMenuBox(
        expanded = menuOpen,
        onExpandedChange = { menuOpen = it },
        modifier = modifier,
    ) {
        // 显示当前选择的字段;menuAnchor(...) 使其成为
        // 菜单的锚点(点击它会打开菜单)
        OutlinedTextField(
            value = selected?.let(itemLabel) ?: "",
            onValueChange = {},
            readOnly = true,
            singleLine = true,
            label = { Text(label) },
            placeholder = { Text(placeholder) },
            trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = menuOpen) },
            modifier = Modifier
                .menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable)
                .fillMaxWidth(),
        )
        // 菜单本身:每一项对应一个 DropdownMenuItem
        ExposedDropdownMenu(expanded = menuOpen, onDismissRequest = { menuOpen = false }) {
            items.forEach { item ->
                DropdownMenuItem(
                    text = { Text(itemLabel(item)) },
                    onClick = {
                        onSelect(idOf(item))
                        menuOpen = false
                    },
                )
            }
        }
    }
}

下面逐段分析这段代码:

  • 第 38–46 行:[fun <T> DropdownList(...)]——一个泛型(GENERIC)@Composable 函数:它既显示医生也显示患者。[idOf] 指定如何标识一个元素,[itemLabel] 指定如何显示它,[onSelect] 则给出所选的标识符;
  • 第 46 行:[modifier: Modifier = Modifier]——Compose 的约定:每个可复用组件都接受一个 modifier,并应用于其根元素,以便调用方调整其大小或边距;
  • 第 50 行:[var menuOpen by remember { mutableStateOf(false) }]——组件的局部状态:菜单打开或关闭;
  • 第 53 行:[ExposedDropdownMenuBox]——容器,负责管理菜单的打开和关闭;
  • 第 60–69 行:显示当前所选项的只读字段。[menuAnchor(...)] 用作菜单的锚点:点按它即可打开菜单;
  • 第 73–79 行:菜单本身:每一项对应一个 [DropdownMenuItem] ,由 [forEach] 循环生成。

5.10. features 层

与课程的所有版本一样,屏幕上的每个功能都是一个组件:它通过参数(输入)接收数据,并通过函数(输出)发出用户操作的信号。只有 [LoginPage] 会直接调用服务([AuthService])。

5.10.1. features/login/LoginPage.kt

移植自 [lib/features/login/login_page.dart]:登录屏幕。

// =========================================================================
// LoginPage.kt
// -------------------------------------------------------------------------
// 移植自 lib/features/login/login_page.dart:登录屏幕
// (登录名、密码、“Log in”按钮、错误消息)。
//
// Flutter 版本需要两个(TWO)类(_LoginForm 和
// _LoginFormState)以及两个需要在
// dispose() 中释放的 TextEditingController。这里一个 @Composable 函数就够了:它的局部状态
// 直接在函数中声明,使用 remember / rememberSaveable。
// =========================================================================

package fr.rdvmedecins.client.features.login

import android.util.Log
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
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.foundation.layout.widthIn
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Surface
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.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.text.input.ImeAction
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.unit.dp
import fr.rdvmedecins.client.core.LocalAuth
import fr.rdvmedecins.client.core.LocalTranslations
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.launch

@Composable
fun LoginPage() {
    val auth = LocalAuth.current
    val t = LocalTranslations.current::t

    // === 屏幕的局部状态 ===
    // rememberSaveable:该值在多次显示之间被保存,
    // 并且在 Activity 重建(屏幕旋转)后仍然存在(SURVIVES)- 输入了一半的
    // 登录名不会因为手机旋转而丢失。
    var login by rememberSaveable { mutableStateOf("") }
    var password by rememberSaveable { mutableStateOf("") }
    // 错误消息的翻译键(而不是翻译后的消息:
    // 这样它会随语言变化而变化),或 null
    var error by rememberSaveable { mutableStateOf<String?>(null) }
    // 仅用 remember:正在进行的登录无需在旋转后保留
    var inProgress by remember { mutableStateOf(false) }

    // 与此屏幕绑定的协程作用域:在其中
    // 启动的协程会在屏幕消失时被取消
    val scope = rememberCoroutineScope()

    // 一个局部函数(见 Kotlin 课程):表单的验证,
    // 由按钮和键盘的“Done”键共同调用
    fun submit() {
        if (login.isBlank() || password.isEmpty() || inProgress) {
            return
        }
        error = null
        inProgress = true
        scope.launch {
            try {
                // 成功时,AuthService 把 isLoggedIn 设为 true:
                // 随后 App.kt 会自动(AUTOMATICALLY)用
                // 日程替换这个屏幕 - 这里无需再做任何事
                auth.logIn(login.trim(), password)
            } catch (e: CancellationException) {
                throw e
            } catch (e: Exception) {
                // 确切原因(服务器不可达、凭据错误……)
                // 会写入 Android 日志(Android
                // Studio 的 Logcat 选项卡);用户看到的只是一条简单的消息
                Log.w("RdvMedecins", "login failed", e)
                error = "LOGIN.ERROR"
            } finally {
                inProgress = false
            }
        }
    }

    // Box + Alignment.TopCenter:卡片水平居中
    Box(modifier = Modifier.fillMaxWidth(), contentAlignment = Alignment.TopCenter) {
        Card(modifier = Modifier.widthIn(max = 420.dp).fillMaxWidth()) {
            Column(
                modifier = Modifier.padding(24.dp),
                verticalArrangement = Arrangement.spacedBy(12.dp),
            ) {
                Text(t("LOGIN.TITLE"), style = MaterialTheme.typography.titleLarge)

                error?.let { key ->
                    Surface(
                        color = MaterialTheme.colorScheme.errorContainer,
                        contentColor = MaterialTheme.colorScheme.onErrorContainer,
                        shape = RoundedCornerShape(4.dp),
                        modifier = Modifier.fillMaxWidth(),
                    ) {
                        Text(t(key), modifier = Modifier.padding(8.dp))
                    }
                }

                OutlinedTextField(
                    value = login,
                    onValueChange = { login = it },
                    label = { Text(t("LOGIN.LOGIN_LABEL")) },
                    singleLine = true,
                    // 键盘的“Next”键:跳到下一个字段
                    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
                    modifier = Modifier.fillMaxWidth(),
                )

                OutlinedTextField(
                    value = password,
                    onValueChange = { password = it },
                    label = { Text(t("LOGIN.PASSWORD_LABEL")) },
                    singleLine = true,
                    // 用圆点代替字符显示
                    visualTransformation = PasswordVisualTransformation(),
                    keyboardOptions = KeyboardOptions(
                        keyboardType = KeyboardType.Password,
                        imeAction = ImeAction.Done,
                    ),
                    // 键盘的“Done”键:提交表单
                    keyboardActions = KeyboardActions(onDone = { submit() }),
                    modifier = Modifier.fillMaxWidth(),
                )

                Spacer(Modifier.height(4.dp))
                Button(
                    onClick = { submit() },
                    enabled = !inProgress,
                    modifier = Modifier.fillMaxWidth(),
                ) {
                    Text(if (inProgress) t("LOGIN.SUBMITTING") else t("LOGIN.SUBMIT"))
                }

                Text(
                    text = "${t("LOGIN.DEMO_ACCOUNTS_PREFIX")} admin / admin ${t("LOGIN.DEMO_ACCOUNTS_ADMIN")} " +
                        "${t("LOGIN.DEMO_ACCOUNTS_OR")} user / user ${t("LOGIN.DEMO_ACCOUNTS_USER")}.",
                    style = MaterialTheme.typography.bodySmall,
                )
            }
        }
    }
}

下面对这段代码进行说明:

  • 第 60–66 行:屏幕的局部状态。[rememberSaveable] 用于用户名、密码和错误消息:这些状态在屏幕旋转后仍然保留。[remember] 只用于 [inProgress]:正在进行的连接无需在旋转后保留;
  • 第 70 行:[rememberCoroutineScope()]——与该屏幕关联的协程作用域:在其中启动的协程会在屏幕消失时被取消;
  • 第 74 行:[fun submit()]——一个局部(LOCAL)函数(声明在另一个函数内部;参见 Kotlin 课程),由按钮和键盘上的“Done”键调用;
  • 第 80–93 行:[scope.launch { ... }] 在协程中发起连接。如果成功,就无需再做任何事情:[AuthService] 会把 [isLoggedIn] 设为 [true],而 [App.kt] 会自动(AUTOMATICALLY)用日程替换这个屏幕。如果操作失败,则保存错误消息的键(KEY)(而不是翻译后的消息:这样在语言变化时能保持一致);
  • 第 92 行:[Log.w(...)]——失败的确切原因(服务器不可达、凭据不正确等)会记录到 Android 日志中,具体来说是 Android Studio 的 [Logcat] 选项卡。正是借助这条日志,才诊断出第 5 章所述的地址 [10.0.2.2] 的问题;
  • 第 120–122 行:[OutlinedTextField(value = login, onValueChange = { login = it }, ...)]——该字段显示状态,并在每次按键时更新它:这就是 Vue.js 的 [v-model] 拆成两部分来写;
  • 第 126 行:[ImeAction.Next]——虚拟键盘上的“Next”键会跳到下一个字段;
  • 第 136–142 行:密码:[PasswordVisualTransformation()] 用圆点代替字符显示;[KeyboardType.Password] 禁用键盘建议;[onDone] 提交表单;
  • 第 147–152 行:按钮,在登录过程中被禁用([enabled = !inProgress]),并显示标签“Signing in...”。

5.10.2. features/doctordaypicker/DoctorDayPicker.kt

移植自 [lib/features/doctor_day_picker/doctor_day_picker.dart]:选择医生和日期。

// =========================================================================
// DoctorDayPicker.kt
// -------------------------------------------------------------------------
// 移植自 lib/features/doctor_day_picker/doctor_day_picker.dart:
// 选择医生(下拉列表)和日期(日历),然后是
// “View schedule”按钮。
//
// 这个组件既不了解服务器,也不了解 AppointmentService:它把医生列表
// 作为参数(PARAMETER)(输入)接收,并通过
// onSearch 函数(输出)报告用户的选择 - 与课程所有版本中的契约相同
// (Vue.js 中的 props/emit,Flutter 中的构造函数
// 参数)。
// =========================================================================

package fr.rdvmedecins.client.features.doctordaypicker

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.BoxWithConstraints
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDialog
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
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.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
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.rdvmedecins.client.core.LocalTranslations
import fr.rdvmedecins.client.core.models.Doctor
import fr.rdvmedecins.client.core.ui.DropdownList
import java.time.Instant
import java.time.LocalDate
import java.time.ZoneOffset

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun DoctorDayPicker(
    doctors: List<Doctor>,
    onSearch: (doctorId: Int, day: String) -> Unit,
) {
    val t = LocalTranslations.current::t

    // === 局部状态,在屏幕旋转后仍然保留 ===
    var doctorId by rememberSaveable { mutableStateOf<Int?>(null) }
    // 所选日期,格式为“yyyy-MM-dd”:LocalDate.toString() 恰好生成
    // 这种格式(ISO 8601),也是服务器所期望的格式 - 不再
    // 需要 Flutter 版本的 intl 包
    var day by rememberSaveable { mutableStateOf(LocalDate.now().toString()) }
    var calendarOpen by remember { mutableStateOf(false) }

    // 组件的三个元素,一次性准备好,然后根据可用宽度
    // 以不同方式布局(见下文)。它们是
    // @Composable lambda:只有在被调用时才会显示(DISPLAYED)。
    val doctorField = @Composable { modifier: Modifier ->
        DropdownList(
            label = t("DOCTOR_DAY_PICKER.DOCTOR_LABEL"),
            placeholder = t("DOCTOR_DAY_PICKER.CHOOSE_DOCTOR"),
            items = doctors,
            selectedId = doctorId,
            idOf = { it.id },
            itemLabel = { "${it.title} ${it.firstName} ${it.lastName}" },
            onSelect = { doctorId = it },
            modifier = modifier,
        )
    }
    val dayField = @Composable { modifier: Modifier ->
        OutlinedTextField(
            value = day,
            onValueChange = {},
            readOnly = true,
            singleLine = true,
            label = { Text(t("DOCTOR_DAY_PICKER.DAY_LABEL")) },
            // 日历图标用于打开日期选择器
            trailingIcon = {
                IconButton(onClick = { calendarOpen = true }) {
                    Icon(Icons.Filled.DateRange, contentDescription = t("DOCTOR_DAY_PICKER.PICK_DAY"))
                }
            },
            modifier = modifier,
        )
    }
    val scheduleButton = @Composable { modifier: Modifier ->
        Button(
            // 在尚未选择医生时,按钮处于禁用状态
            enabled = doctorId != null,
            onClick = { doctorId?.let { onSearch(it, day) } },
            modifier = modifier,
        ) {
            Text(t("DOCTOR_DAY_PICKER.VIEW_SCHEDULE"))
        }
    }

    Card(modifier = Modifier.fillMaxWidth()) {
        // BoxWithConstraints:提供对实际(ACTUALLY)可用宽度(maxWidth)的访问
        // - 即 Flutter 版本的 LayoutBuilder。
        // 窄屏幕(竖屏的手机):三个元素上下
        // 堆叠;宽屏幕:排成一行。
        BoxWithConstraints(modifier = Modifier.padding(16.dp)) {
            if (maxWidth < 600.dp) {
                Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
                    doctorField(Modifier.fillMaxWidth())
                    dayField(Modifier.fillMaxWidth())
                    scheduleButton(Modifier.fillMaxWidth())
                }
            } else {
                Row(
                    horizontalArrangement = Arrangement.spacedBy(12.dp),
                    verticalAlignment = Alignment.CenterVertically,
                ) {
                    // weight(...):在三个元素之间分配宽度
                    // (5/12、4/12、3/12)- 即 Flutter 版本中 Expanded 的
                    // flex: 5、4、3
                    doctorField(Modifier.weight(5f))
                    dayField(Modifier.weight(4f))
                    scheduleButton(Modifier.weight(3f))
                }
            }
        }
    }

    // 日历:只要 calendarOpen 为 true 就
    // 显示的对话框(与 BookingDialog 原理相同)
    if (calendarOpen) {
        // DatePicker 以自 1970 年 1 月 1 日 UTC 午夜起的毫秒数工作:
        // 我们用 java.time 进行双向转换
        val state = rememberDatePickerState(
            initialSelectedDateMillis = LocalDate.parse(day)
                .atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli(),
        )
        DatePickerDialog(
            onDismissRequest = { calendarOpen = false },
            confirmButton = {
                TextButton(onClick = {
                    state.selectedDateMillis?.let { millis ->
                        day = Instant.ofEpochMilli(millis).atZone(ZoneOffset.UTC).toLocalDate().toString()
                    }
                    calendarOpen = false
                }) { Text(t("DOCTOR_DAY_PICKER.OK")) }
            },
            dismissButton = {
                TextButton(onClick = { calendarOpen = false }) {
                    Text(t("DOCTOR_DAY_PICKER.CANCEL"))
                }
            },
        ) {
            DatePicker(state = state)
        }
    }
}

下面对这段代码进行说明:

  • 第 54–56 行:组件的输入和输出:医生列表,以及函数 [onSearch(doctorId, day)]。函数类型参数所带的名称([doctorId: Int, day: String])仅用于文档说明;
  • 第 65 行:所选日期,以 [yyyy-MM-dd] 格式存储:[LocalDate.now().toString()] 恰好生成这种格式(ISO 8601),也是服务器所期望的格式。Flutter 版本中的 [intl] 包不再需要;
  • 第 71–99 行:组件的三个元素,被准备为 @Composable lambda([@Composable { modifier: Modifier -> ... }]):只有在被调用时才会显示,并带上所需的 modifier。这使得它们可以用两种不同的方式排列,而无需把代码写两遍;
  • 第 91–93 行:日期字段,为只读;右侧的日历图标用于打开日期选择器;
  • 第 115–132 行:[BoxWithConstraints] 提供对可用宽度([maxWidth])的访问——即 Flutter 版本的 [LayoutBuilder]。小于 600 dp 时:三个元素上下堆叠([Column]);否则排成一行([Row]),权重为 5/4/3([Modifier.weight(...)],Flutter 版本中的 [Expanded(flex: ...)]);
  • 第 140–163 行:日期选择器:只要 [DatePickerDialog] 所对应的 [calendarOpen] 等于 [true] 就会显示。Material 3 的 [DatePicker] 以自 1970 年 1 月 1 日午夜(UTC)起的毫秒数工作:与 [java.time] 之间可以双向转换([atStartOfDay(ZoneOffset.UTC)] 和 [Instant.ofEpochMilli(...)])。

5.10.3. features/schedule/ScheduleView.kt

移植自 [lib/features/schedule/schedule_view.dart]:医生的每日日程。

// =========================================================================
// ScheduleView.kt
// -------------------------------------------------------------------------
// 移植自 lib/features/schedule/schedule_view.dart:显示
// 某位医生某一天的日程 - 每个时段一行,空闲或
// 已被占用,对 ADMIN 角色带有“Book”按钮(空闲时段)或“Cancel”按钮(已占用
// 时段)。
//
// 与 DoctorDayPicker 一样,这个组件是“无状态”的:它显示的一切
// 都作为参数传给它,并通过
// onBook / onCancel 报告点击。调用服务器的是 AppViewModel。
// =========================================================================

package fr.rdvmedecins.client.features.schedule

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.widthIn
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Card
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
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.text.font.FontWeight
import androidx.compose.ui.unit.dp
import fr.rdvmedecins.client.core.LocalTranslations
import fr.rdvmedecins.client.core.models.DoctorDaySchedule
import fr.rdvmedecins.client.core.models.DoctorDaySlot
import fr.rdvmedecins.client.core.models.SlotJson
import fr.rdvmedecins.client.core.models.AppointmentJson

// 时间列的宽度(“10:40 - 11:00”)
private val TIME_COLUMN_WIDTH = 116.dp

// “8:00”、“8:20”……:分钟始终为两位数
private fun formatTime(h: Int, m: Int): String = "$h:${m.toString().padStart(2, '0')}"

@Composable
fun ScheduleView(
    schedule: DoctorDaySchedule?,
    canEdit: Boolean,
    onBook: (SlotJson) -> Unit,
    onCancel: (AppointmentJson) -> Unit,
) {
    val t = LocalTranslations.current::t

    // 尚无日程:一条简单的提示消息
    if (schedule == null) {
        Text(
            text = t("SCHEDULE.EMPTY_STATE"),
            color = MaterialTheme.colorScheme.outline,
            modifier = Modifier.padding(vertical = 24.dp),
        )
        return // @Composable 函数可以在此停止:不会再显示任何其他内容
    }

    Card(modifier = Modifier.fillMaxWidth()) {
        Column(modifier = Modifier.padding(16.dp)) {
            val doctor = schedule.doctor
            Text(
                text = "${t("SCHEDULE.TITLE_PREFIX")} ${schedule.day} - ${doctor.title} ${doctor.firstName} ${doctor.lastName}",
                style = MaterialTheme.typography.titleMedium,
            )
            // 列标题:第一列的宽度与
            // 每一行中的相同(TIME_COLUMN_WIDTH),以使各列
            // 对齐
            Row(modifier = Modifier.fillMaxWidth().padding(top = 12.dp, bottom = 4.dp)) {
                Text(t("SCHEDULE.COLUMN_SLOT"), fontWeight = FontWeight.Bold, modifier = Modifier.width(TIME_COLUMN_WIDTH))
                Spacer(Modifier.width(8.dp)) // 各行的列间距
                Text(t("SCHEDULE.COLUMN_STATUS"), fontWeight = FontWeight.Bold)
            }
            HorizontalDivider()
            // 每个时段一行。在 Column 中使用简单的 forEach 循环:
            // 这里不用 LazyColumn(Compose 的“惰性”列表,
            // 只构建可见的行),因为这个
            // 日程已经放在一个可滚动的 Column 中(见 App.kt),
            // 而十几行并不值得做这种优化。
            schedule.slots.forEach { daySlot ->
                SlotRow(daySlot, canEdit, onBook, onCancel)
                HorizontalDivider()
            }
        }
    }
}

// -------------------------------------------------------------------------
// 日程的一行:时间 | 状态(空闲或患者)| 按钮
// -------------------------------------------------------------------------
@Composable
private fun SlotRow(
    daySlot: DoctorDaySlot,
    canEdit: Boolean,
    onBook: (SlotJson) -> Unit,
    onCancel: (AppointmentJson) -> Unit,
) {
    val t = LocalTranslations.current::t
    val slot = daySlot.slot
    val appointment = daySlot.appointment

    Row(
        modifier = Modifier.fillMaxWidth().padding(vertical = 6.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.spacedBy(8.dp),
    ) {
        // 时间:固定宽度,与标题的宽度相同
        Text(
            text = "${formatTime(slot.startHour, slot.startMinute)} - ${formatTime(slot.endHour, slot.endMinute)}",
            modifier = Modifier.width(TIME_COLUMN_WIDTH),
        )
        // 状态:绿色的“Free”徽章,或患者的姓名
        Surface(
            shape = RoundedCornerShape(8.dp),
            color = if (appointment == null) Color(0xFFC8E6C9) else MaterialTheme.colorScheme.secondaryContainer,
            // weight(1f):状态占据时间和按钮
            // 之外剩余的全部宽度
            modifier = Modifier.weight(1f),
        ) {
            val client = appointment?.client
            Text(
                text = if (appointment == null) t("SCHEDULE.FREE") else "${client?.title ?: ""} ${client?.firstName ?: ""} ${client?.lastName ?: ""}",
                style = MaterialTheme.typography.bodyMedium,
                modifier = Modifier.padding(horizontal = 8.dp, vertical = 4.dp),
            )
        }
        // 按钮只对 ADMIN 角色存在;它预订空闲
        // 时段,或取消已占用时段的预约
        if (canEdit) {
            // 这里没有(NO)weight(...):按钮占据其文本的宽度。
            // 第一个版本强制它占一行的四分之一
            // (weight(0.25f)):在竖屏的手机上,标签
            // “Réserver”(法语 UI)因此被截断为“Rése”(见第 5 章)。
            OutlinedButton(
                onClick = { if (appointment == null) onBook(slot) else onCancel(appointment) },
                // 缩小内边距(每侧默认 24 dp)
                contentPadding = PaddingValues(horizontal = 12.dp),
                // 统一的最小宽度:“Book”和
                // “Cancel”按钮因此具有相同的宽度,并且各列
                // 在各行之间保持对齐
                modifier = Modifier.widthIn(min = 96.dp),
            ) {
                Text(if (appointment == null) t("SCHEDULE.BOOK") else t("SCHEDULE.CANCEL_APPOINTMENT"), maxLines = 1)
            }
        }
    }
}

下面对这段代码进行说明:

  • 第 60–66 行:尚无日程——显示一条提示消息,然后是 [return]。@Composable 函数可以在此结束:不会再发出任何其他内容;
  • 第 79–82 行:列标题:第一列与每行中的时间具有相同的固定宽度([TIME_COLUMN_WIDTH]),以使各列对齐。Compose 没有与 Flutter 的 [DataTable] 对应的组件:表格是用 [Row] 构建的;
  • 第 90–91 行:每个时段一行,在 [Column] 内使用简单的 [forEach] 循环。不使用 [LazyColumn] (Compose 的“惰性”列表,只构建可见的行):日程已经放在一个可滚动的列中(见 [App.kt])——在可滚动列中放置 [LazyColumn] 实际上会导致运行时错误——而且十几行也不值得做这种优化;
  • 第 122–128 行:状态:绿色的“Free”徽章,或患者的姓名。[Modifier.weight(1f)]:状态占据时间和按钮之外剩余的全部宽度;
  • 第 139–151 行:按钮,仅对角色 ADMIN 显示([if (canEdit)]):在可用时段上显示“Book”,在已预订时段上显示“Cancel”。它没有固定宽度:占据其文本的宽度,并带有统一的最小宽度。早先的版本把它限制为一行的四分之一:在竖屏的手机上,标签因此被截断(见第 5 章)。

5.10.4. features/bookingdialog/BookingDialog.kt

移植自 [lib/features/booking_dialog/booking_dialog.dart]:预订对话框。

// =========================================================================
// BookingDialog.kt
// -------------------------------------------------------------------------
// 移植自 lib/features/booking_dialog/booking_dialog.dart:时段的预订
// 对话框(选择患者,然后
// “Confirm”或“Cancel”)。
//
// 与 Flutter 版本在结构上的差异:Flutter 用 showDialog(...) 打开(OPENED)
// 对话框并等待(AWAITED)其结果(一个 Future<int?>)。
// 在 Compose 中,对话框与其他任何显示元素一样:
// 只要调用 AlertDialog 的函数继续
// 调用它(见 App.kt:只要 vm.slotBeingBooked 不为
// null),它就会显示。它不会“返回”任何东西:它通过两个
// 函数 onConfirm 和 onClose 报告选择 - 恰好对应 Vue.js 版本中 BookingDialog.vue 的
// 两个事件“confirm” / “close”。
// =========================================================================

package fr.rdvmedecins.client.features.bookingdialog

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.AlertDialog
import androidx.compose.material3.Button
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.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import fr.rdvmedecins.client.core.LocalTranslations
import fr.rdvmedecins.client.core.models.Client
import fr.rdvmedecins.client.core.models.SlotJson
import fr.rdvmedecins.client.core.ui.DropdownList

@Composable
fun BookingDialog(
    slot: SlotJson,
    clients: List<Client>,
    onConfirm: (clientId: Int) -> Unit,
    onClose: () -> Unit,
) {
    val t = LocalTranslations.current::t
    // 所选患者(其 id),在尚未选择时为 null
    var clientId by rememberSaveable { mutableStateOf<Int?>(null) }

    AlertDialog(
        // 点击对话框之外,或手机的“back”键
        onDismissRequest = onClose,
        title = { Text(t("BOOKING_DIALOG.TITLE")) },
        text = {
            Column(verticalArrangement = Arrangement.spacedBy(16.dp)) {
                Text(
                    "${t("BOOKING_DIALOG.SLOT_FROM")} ${slot.startHour}:${slot.startMinute.toString().padStart(2, '0')} " +
                        "${t("BOOKING_DIALOG.SLOT_TO")} ${slot.endHour}:${slot.endMinute.toString().padStart(2, '0')}",
                )
                DropdownList(
                    label = t("BOOKING_DIALOG.PATIENT_LABEL"),
                    placeholder = t("BOOKING_DIALOG.CHOOSE_PATIENT"),
                    items = clients,
                    selectedId = clientId,
                    idOf = { it.id },
                    itemLabel = { "${it.title} ${it.firstName} ${it.lastName}" },
                    onSelect = { clientId = it },
                    modifier = Modifier.fillMaxWidth(),
                )
            }
        },
        // “Confirm”:在尚未选择患者时处于禁用状态
        confirmButton = {
            Button(
                enabled = clientId != null,
                onClick = { clientId?.let(onConfirm) },
            ) { Text(t("BOOKING_DIALOG.CONFIRM")) }
        },
        dismissButton = {
            TextButton(onClick = onClose) { Text(t("BOOKING_DIALOG.CANCEL")) }
        },
    )
}

下面对这段代码进行说明:

  • 第 8–15 行:头部注释概括了与 Flutter 版本在结构上的差异。Flutter 用 [showDialog(...)] 打开(OPENED)对话框并等待(AWAITED)其结果(一个 [Future<int?>])。在 Compose 中,对话框与任何其他视图元素一样:只要调用它的函数继续调用它,它就一直显示。它不会“返回”任何东西:它通过两个函数来发出选择的信号,即 [onConfirm] 和 [onClose]——恰好对应 Vue.js 版本中 [BookingDialog.vue] 组件的两个事件 [confirm] / [close];
  • 第 48 行:所选患者:[rememberSaveable];即使在对话框打开时屏幕旋转,该患者仍保持被选中;
  • 第 50–52 行:[AlertDialog(...)]——Material 3 对话框,带有标题、内容([text])和两个按钮。[onDismissRequest] 在用户点按对话框之外或按下手机的“Back”按钮时被调用;
  • 第 73–76 行:“Confirm”按钮,在选中患者之前处于禁用状态。[clientId?.let(onConfirm)]:如果 [clientId] 不为 [null],则调用 [onConfirm],并传入它的值。

5.11. 应用使用分步指南

以下截图是在第 1 章中的 Pixel 8(Android 17)模拟器上截取的,应用通过 [adb reverse] (见第 5 章)连接到服务器,因此 URL 为 [http://localhost:8080]。

5.11.1. 1. 登录屏幕

首次启动时,没有存储任何会话:[AuthService.isLoggedIn] 等于 [false],于是 [App.kt] 显示 [LoginPage]。如果尝试使用无效的用户名/密码组合——或者服务器不可达——就会显示错误消息(键 [LOGIN.ERROR]):

Image

Image

5.11.2. 2. 以管理员身份登录(角色 ADMIN,完全访问)

使用 [admin]/[admin] 登录后,登录屏幕让位于医生和日期的选择;标题栏显示角色徽章和登出按钮。在后台,[AppViewModel] 已经加载了医生和患者:

Image

Image

  • 左侧是刚登录之后的屏幕:在选择医生之前,“View schedule”按钮处于禁用状态;
  • 右侧是已展开的医生下拉列表。

日历图标用于打开日期选择器;“View schedule”显示该医生在所选日期的日程:

Image

Image

“Book”打开患者选择对话框;“Confirm”把预订发送到服务器,然后日程重新加载:该时段显示为已预订,并带有“Cancel”按钮:

Image

Image

Image

在已预订时段上点按“Cancel”会删除该预约,该时段重新变为可用。“FR”按钮把整个屏幕切换为法语,包括日程的标签;登出按钮则返回登录屏幕:

Image

Image

5.11.3. 3. 以普通用户身份登录(角色 USER,只读)

使用 [user]/[user] 登录会显示徽章“USER”。日程仍然可以查看,但不会出现“Book”/“Cancel”按钮([canEdit] 等于 [false])——反正服务器也会拒绝该角色执行这两个操作(403 Forbidden,见第 2 章)。

Image

5.12. 仍不在范围内或推迟的内容

  • 与本课程的其他客户端一样,没有专门的演示/调试模式。
  • 客户端没有为教学目的而引入人为的网络延迟。
  • 没有屏幕之间的导航:应用只在一个屏幕上(不含对话框)。功能更丰富的 Android 应用会使用 [Navigation Compose] 库。
  • 没有自动化测试:Android Studio 生成的 [src/test] 和 [src/androidTest] 文件夹已从项目中删除。