7.5 KiB
星课表架构设计
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. 运行时分层
从上到下:
- 界面
ui/:Screen + 少量无状态组件。不直接碰 DAO。 - ViewModel
ui/**/*ViewModel.kt、AppSettingsViewModel:组合多个 Repository,暴露StateFlow。 - Repository
data/repository/:课表、转换、备份、样式、设置、小组件。 - 持久化
- Room 主库:课表、课程、周次、节次、课表配置
- Room Widget 库:预计算的近 7 天课程
- DataStore Preferences:应用设置、WebDAV 配置
- DataStore Proto(Wire):课表网格样式
- 平台
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 后:
- 刷新四种 AppWidget(
updateAllWidgets()) - 入队
CourseNotificationWorker(重排上课提醒闹钟) - 入队
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 | 已移除 |
| 学校选择 / 适配器选择 / 更新仓库 | 已移除 |
| 系统日历同步 | 已移除 |