# 星课表架构设计 ## 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 | 已移除 | | 学校选择 / 适配器选择 / 更新仓库 | 已移除 | | 系统日历同步 | 已移除 |