Files
2026-09-20 13:33:09 +08:00

7.5 KiB
Raw Permalink Blame History

星课表架构设计

1. 总体结构

星课表是 Android 专用的 Kotlin Multiplatform 工程:共享模块用 Compose Multiplatform 写 UI 和业务,Android 应用模块承载入口、通知、小组件。

┌─────────────────────────────────────────┐
│  app(Android Application)             │
│  MainActivity / MyApplication           │
│  上课闹钟 CourseAlarmReceiver           │
│  四种 AppWidget Provider + 渲染         │
└─────────────────┬───────────────────────┘
                  │ implementation
┌─────────────────▼───────────────────────┐
│  shared(KMP Android Library)          │
│  Compose UI · Navigation3 · ViewModel   │
│  Repository · Room · DataStore · Wire   │
│  正方 JS · WebView expect/actual        │
└─────────────────────────────────────────┘

源码包名仍为 com.xingheyuzhuan.shiguangschedule(沿用原工程,减少改动面)。
安装包 applicationId 为 com.starschedule。

2. 运行时分层

从上到下:

  1. 界面 ui/:Screen + 少量无状态组件。不直接碰 DAO。
  2. ViewModel ui/**/*ViewModel.kt、AppSettingsViewModel:组合多个 Repository,暴露 StateFlow。
  3. Repository data/repository/:课表、转换、备份、样式、设置、小组件。
  4. 持久化
    • Room 主库:课表、课程、周次、节次、课表配置
    • Room Widget 库:预计算的近 7 天课程
    • DataStore Preferences:应用设置、WebDAV 配置
    • DataStore Proto(Wire):课表网格样式
  5. 平台 androidMain:WebView、文件选择器、加密、通知设置卡片、主题动态色。

依赖注入用 Koin 注解:@Single / @Factory / @ComponentScan。MyApplication 启动 ScheduleAppConfig。

3. 导航

使用 Navigation3 的 NavBackStack,目的地是 @Serializable 的 Destination。

  • 三个 MainDestination(今日课表、周课表、我的):切换时清空栈再压入,底部栏无滑动动画。
  • 其余页面压栈,横向滑入;返回滑出。
  • WebView、AddEditCourse、CourseManagementDetail 带参数。

入口在 App.kt 的 ScreenContent。新增页面需要:定义 Destination、注册 serializer、在 ScreenContent 里分支。

4. 数据流

4.1 课表显示

AppSettings(currentCourseTableId)
        │
        ▼
CourseTableRepository.getCoursesWithWeeksByTableId
TimeSlotRepository / CourseTableConfig
        │
        ▼
WeeklyScheduleViewModel / TodayScheduleViewModel
        │
        ▼
Compose 网格 / 列表

周次计算:用课表的 semesterStartDate 与 firstDayOfWeek 把「今天」对齐到学期第几周。

4.2 正方导入

用户打开 WebView → 登录正方 → 课表查询页
        │
执行导入 → 选择目标课表 ID
        │
注入 files/zhengfang.js
        │
JS 抓 DOM → shiguangBridgePromise.saveImportedCourses(json)
        │
Android JavascriptInterface → WebBridgeHandler
        │
CourseConversionRepository.importCoursesFromList(覆盖该表课程)
        │
notifyTaskCompletion → 回到周课表

4.3 小组件

WidgetDataSynchronizer(createdAtStart = true)监听当前课表、课程、节次、设置;把未来 7 天展开成 WidgetCourse 写入独立数据库。Android 的 SyncManager(同样 createdAtStart)订阅 syncCompletedFlow 后:

  1. 刷新四种 AppWidget(updateAllWidgets())
  2. 入队 CourseNotificationWorker(重排上课提醒闹钟)
  3. 入队 DndSchedulerWorker(重排勿扰/静音闹钟)

小组件进程只读 Widget 库,避免在 RemoteViews 里跑完整学期计算。

另外 WorkManagerHelper 在有小组件时调度:

  • WidgetUiUpdateWorker:约每 15 分钟刷新 UI(系统可推迟)
  • FullDataSyncWorker:约每天一次调用 syncNow()

4.4 上课提醒与上课自动模式

不是 UI 线程直接 setAlarm,而是:

主库变化 → WidgetDataSynchronizer 展开近 7 天
        → SyncManager
        → CourseNotificationWorker / DndSchedulerWorker
        → AlarmManager 精确闹钟
        → CourseAlarmReceiver

闹钟槽位(见各 Worker 常量,改时不要互相覆盖):

范围 用途
50001–50002 一带 勿扰/静音开、关(DndSchedulerWorker)
50010–50110 课程提醒(CourseNotificationWorker,共 101 个槽)

CourseAlarmReceiver 处理通知展示、点击关闭、以及勿扰/静音切换。跳过日期来自 DataStore,展开进 Widget 库时带 isSkipped。

5. 双数据库

库 用途 版本
MainAppDatabase 用户课表真相源 5(schema 导出在 shared/schemas)
WidgetDatabase 小组件只读快照 3(不导出 schema)

主库实体之间用外键 CASCADE:删课表会删课程、周次、节次、配置。

应用设置曾存在 Room app_settings 表,现已迁到 DataStore;库版本 4→5 用 AutoMigration 删该表。

MyApplication 实现 Configuration.Provider,Koin 里调用 workManagerFactory(),Worker 用 @KoinWorker 注入 Repository。

6. 平台抽象

expect Android actual 作用
AppStorage AndroidAppStorage filesDir / cacheDir / 数据库路径
createMainDatabase Room builder 主库
PlatformWebView android.webkit.WebView 教务页
rememberFileManager SAF / 图片选择 导入导出、壁纸
SecureCrypto AES + 系统密钥 WebDAV 密码
ShareManager FileProvider + Intent 分享导出文件
通知设置部分 UI 权限跳转、勿扰、精确闹钟 仅 Android 有意义
WorkManager / AlarmManager SyncManager、各类 Worker、CourseAlarmReceiver 提醒、勿扰、小组件定期刷新

7. 资源与文案

Compose Multiplatform Resources:

  • 字符串:shared/src/commonMain/composeResources/values/strings.xml
  • 图标:同目录 drawable/
  • 正方脚本:files/zhengfang.js

生成类包名固定为 shiguangschedule.shared.generated.resources。

app 模块自己的 res/values/strings.xml 只保留小组件、通知、应用名等系统框架会读的条目。

androidResources.localeFilters 限制为 zh、zh-rCN。

8. 网络

  • 正方:WebView 加载用户输入的教务 URL,Cookie 留在 WebView。
  • WebDAV:Ktor CIO 客户端,Basic 认证。
  • 节假日:Ktor 请求 https://timor.tech/api/holiday/year。

network_security_config 允许用户访问校园 HTTP 教务(明文站点仍常见)。

9. 安全注意

  • 无用户账号。课表在本机 SQLite。
  • WebDAV 密码加密后写入 DataStore,IV 一并保存。
  • 正方账号只在 WebView 会话中,应用不采集、不上传。
  • 导入脚本在 WebView 里跑,只通过 Bridge 把课程 JSON 交给 Native。脚本不能直接写数据库。

10. 与原拾光工程的差异(架构层)

原拾光 星课表
androidApp + iosApp + desktopApp 仅 app + shared
Git 拉取 180+ 适配脚本 内置一份 zhengfang.js
kgit、aboutlibraries、多 locale 已移除
学校选择 / 适配器选择 / 更新仓库 已移除
系统日历同步 已移除