[new] new project
This commit is contained in:
@@ -0,0 +1,189 @@
|
||||
# 星课表架构设计
|
||||
|
||||
## 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 | 已移除 |
|
||||
| 学校选择 / 适配器选择 / 更新仓库 | 已移除 |
|
||||
| 系统日历同步 | 已移除 |
|
||||
Reference in New Issue
Block a user