Module ComposeApp

composeApp 模块指南

composeApp 是跨平台 UI 模块，负责 Desktop / Web / iOS / Android 的共享界面与状态编排。它不直接写后端业务逻辑，而是通过 shared/api 的连接模式分发调用服务端中转或本地直连实现。

这一层负责什么

• 应用启动、连接模式选择、会话恢复、登录页和主界面的切换
• 软件更新检测和更新弹窗
• 自定义导航栈、侧栏、底栏、主页聚合和功能页切换
• 各业务域的 ViewModel + Screen 组合
• 跨平台 UI 基础设施：主题、图片选择器、后退键适配、共用组件

启动流

App.kt 是顶层状态机：

1. 预加载中文字体并应用 UBAATheme。
2. 通过 ConnectionRuntime.resolveSelectedMode() 解析已保存的连接模式。
3. 如果当前平台支持多个模式且尚未选择，展示 ConnectionModeSelectionScreen。
4. 模式确定后执行 UpdateService.checkUpdate() 和 AuthViewModel.initializeApp()。
5. 根据 splash、登录态、自动登录、验证码和错误状态切换到 LoginScreen 或 MainAppScreen。
6. 登录页和主界面都允许切换连接模式；切换会清理会话并重新检查更新。

JS/Wasm 只支持 SERVER_RELAY，通常不会展示多模式选择。Android/iOS/JVM 支持 DIRECT、WEBVPN、SERVER_RELAY。

文件清单

根入口与主题

文件	作用
App.kt	顶层状态机：连接模式、splash、登录恢复、更新检查、主界面进入
TestClock.kt	测试用时钟注入工具
ui/theme/Theme.kt	Material 3 主题入口与字体预加载
ui/theme/Typography.kt	字体与排版配置

导航与壳层

文件	作用
ui/navigation/NavigationController.kt	轻量导航栈封装
ui/navigation/MainAppScreen.kt	主壳层，负责页面注册、侧栏、底栏、弹窗、顶栏操作和功能入口
ui/navigation/HomeBootstrapCoordinator.kt	首页加载协调器；当前按顺序执行 today schedule、signin、SPOC、BYKC、CGYY

MainAppScreen.AppScreen 当前覆盖首页、常用功能、高级功能、个人/设置/关于、课表、考试、成绩、BYKC、签到、CGYY、空教室、评教、SPOC、Judge、YGDK。

公共 UI

文件	作用
ui/common/components/AppTopBar.kt	顶部栏及其操作按钮
ui/common/components/BottomNavigation.kt	底部导航栏
ui/common/components/Sidebar.kt	侧边栏导航
ui/common/util/PlatformImagePicker.kt	平台图片选择 / 拍照抽象
ui/common/util/BackHandlerCompat.kt	expect/actual 返回键兼容
ui/common/util/BackHandlerCompat.notAndroid.kt	非 Android 平台的 no-op 实现

首页与菜单页

文件	作用
ui/screens/menu/HomeScreen.kt	首页仪表盘，展示今日安排、待办和快速入口
ui/screens/menu/HomeTodo.kt	汇总 BYKC、SPOC、Judge、CGYY、签到等待办项
ui/screens/menu/RegularFeaturesScreen.kt	常用功能入口页：课表、考试、成绩、空教室、SPOC、Judge 等
ui/screens/menu/AdvancedFeaturesScreen.kt	高级功能入口页：BYKC、签到、CGYY、评教、YGDK 等
ui/screens/menu/SettingsScreen.kt	设置页
ui/screens/menu/OtherScreens.kt	个人、关于等辅助页面

首页 bootstrap 当前主动加载今日课表、签到、SPOC、BYKC 已选课程和 CGYY 订单。Judge 待办会纳入 HomeTodo 聚合，但不在首页 bootstrap 中主动加载；只有已有 judgeUiState.assignmentsResponse 时才展示 Judge 待办。点击 Judge 待办会加载详情并跳转到详情页。

认证

文件	作用
ui/screens/auth/AuthViewModel.kt	登录状态、验证码、token 恢复、用户信息加载、连接模式切换
ui/screens/auth/ConnectionModeSelectionScreen.kt	首次连接模式选择
ui/screens/auth/LoginScreen.kt	登录表单、验证码、记住密码、自动登录、模式切换
ui/screens/auth/UserInfoScreen.kt	个人信息页和退出登录入口

课表、考试、成绩

文件	作用
ui/screens/schedule/ScheduleViewModel.kt	学期、周次、课表数据状态机
ui/screens/schedule/ScheduleScreen.kt	课表主屏幕和周次切换
ui/screens/schedule/CourseDetailScreen.kt	课程详情页
ui/screens/schedule/ScheduleDateLabels.kt	课表日期标签计算
ui/screens/exam/ExamViewModel.kt	考试数据加载与分组
ui/screens/exam/ExamScreen.kt	考试时间线和未安排考试展示
ui/screens/grade/GradeViewModel.kt	成绩学期选择、加载、刷新和错误状态
ui/screens/grade/GradeScreen.kt	成绩概览和课程成绩列表；展示课程数、总学分、均分，不展示绩点字段

成绩页顶栏由 MainAppScreen 提供学期下拉和刷新入口。

博雅课程 BYKC

文件	作用
ui/screens/bykc/BykcViewModel.kt	选课、退选、签到、统计状态机
ui/screens/bykc/BykcHomeScreen.kt	BYKC 首页
ui/screens/bykc/BykcCoursesScreen.kt	课程列表页
ui/screens/bykc/BykcCourseDetailScreen.kt	课程详情页
ui/screens/bykc/BykcChosenCoursesScreen.kt	已选课程页
ui/screens/bykc/BykcStatisticsScreen.kt	统计页
ui/screens/bykc/BykcCourseFilters.kt	课程筛选状态和持久化模型转换
ui/screens/bykc/BykcTimeFormatters.kt	时间展示、按钮状态、考勤状态推导

课堂签到与空教室

文件	作用
ui/screens/signin/SigninViewModel.kt	今日签到列表和提交状态
ui/screens/signin/SigninScreen.kt	今日课程签到页
ui/screens/classroom/ClassroomViewModel.kt	空教室查询和筛选状态机
ui/screens/classroom/ClassroomQueryScreen.kt	空教室查询页

CGYY 研讨室预约

文件	作用
ui/screens/cgyy/CgyyViewModel.kt	预约列表、表单、取消、锁码状态机
ui/screens/cgyy/CgyyUiCommon.kt	弹窗、状态卡、筛选 chip、通用展示组件
ui/screens/cgyy/CgyyHomeScreen.kt	CGYY 首页
ui/screens/cgyy/CgyyReservePickerScreen.kt	场地/时段选择页
ui/screens/cgyy/CgyyReserveFormScreen.kt	预约表单页
ui/screens/cgyy/CgyyOrdersScreen.kt	订单列表页
ui/screens/cgyy/CgyyLockCodeScreen.kt	锁码输入/展示页

CGYY ViewModel 在首页或进入过 CGYY 后会保留，避免多页面预约流程中状态丢失。

SPOC 与 Judge

文件	作用
ui/screens/spoc/SpocViewModel.kt	作业列表、详情、搜索、排序、筛选和刷新状态机
ui/screens/spoc/SpocAssignmentsScreen.kt	SPOC 作业列表页
ui/screens/spoc/SpocAssignmentDetailScreen.kt	SPOC 作业详情页
ui/screens/judge/JudgeViewModel.kt	希冀作业列表、详情、搜索、排序、筛选和刷新状态机
ui/screens/judge/JudgeAssignmentsScreen.kt	希冀作业列表页，含搜索 FAB、下拉刷新、分课程分组
ui/screens/judge/JudgeAssignmentDetailScreen.kt	希冀作业详情页

Judge 默认 showOnlyUnfinished = true、showExpired = false，默认按截止时间升序排序。顶栏排序/筛选按钮在 MainAppScreen 中挂载。

自动评教与阳光打卡

文件	作用
ui/screens/evaluation/EvaluationViewModel.kt	评教任务加载与提交状态机
ui/screens/evaluation/EvaluationScreen.kt	评教任务页
ui/screens/ygdk/YgdkViewModel.kt	打卡记录、表单、提交状态机
ui/screens/ygdk/YgdkHomeScreen.kt	打卡记录列表页
ui/screens/ygdk/YgdkClockinFormScreen.kt	打卡提交表单页

其他

文件	作用
ui/screens/splash/SplashScreen.kt	启动页
src/webMain/kotlin/cn/edu/ubaa/main.kt	Web/Wasm 入口，使用 ComposeViewport
src/webMain/resources/index.html	Web 资源入口并注册 service worker

页面改动时的落点

• 改登录、会话恢复或连接模式：App.kt + AuthViewModel.kt + LoginScreen.kt + ConnectionModeSelectionScreen.kt
• 改主导航/壳层：MainAppScreen.kt + NavigationController.kt + AppTopBar.kt + BottomNavigation.kt + Sidebar.kt
• 改首页聚合：HomeBootstrapCoordinator.kt + HomeTodo.kt + HomeScreen.kt
• 改某个业务域：对应的 ViewModel + Screen + 相关辅助文件
• 改平台差异能力：优先放在 ui/common/util/，不要散落到业务页面里

Web/Wasm 注意事项

• 当前 Web 主路径是 :composeApp:wasmJsBrowserDevelopmentRun 和 :composeApp:wasmJsBrowserDistribution。
• Wasm 客户端只支持 SERVER_RELAY，需要服务端 CORS 允许对应 dev server origin。
• Compose/Wasm 渲染和部分控件是 canvas/Compose 命中测试路径；Playwright 自动化搜索、排序、下拉菜单时，语义 locator 可能不如坐标点击稳定。

关键测试

• 启动/认证：AuthViewModelInitializeAppTest, AuthViewModelTest
• 首页：HomeTodoTest, HomeBootstrapCoordinatorTest
• 成绩：GradeScreenLogicTest
• Judge：JudgeViewModelTest, JudgeAssignmentDisplayTest
• 其他业务：CgyyViewModelTest, ClassroomViewModelTest, SpocViewModelTest, YgdkViewModelTest, BykcCourseFiltersTest