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

190 lines
7.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 星课表架构设计
## 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 | 已移除 |
| 学校选择 / 适配器选择 / 更新仓库 | 已移除 |
| 系统日历同步 | 已移除 |