271 lines
12 KiB
Markdown
271 lines
12 KiB
Markdown
# 星课表开发文档
|
||
|
||
本文说明如何搭建环境、读懂代码、以及按现有约定改功能。架构总览见 [架构设计](架构设计.md),表结构见 [数据模型](数据模型.md)。
|
||
|
||
## 1. 环境
|
||
|
||
| 项 | 版本 / 要求 |
|
||
|---|---|
|
||
| JDK | 21(`jvmToolchain(21)`) |
|
||
| Gradle | 9.7.1(Wrapper,腾讯云镜像) |
|
||
| Android Gradle Plugin | 9.3.1 |
|
||
| Kotlin | 2.4.0 |
|
||
| Compose Multiplatform | 1.11.1 |
|
||
| compileSdk / targetSdk | 37 |
|
||
| minSdk | 26 |
|
||
| IDE | Android Studio 或带 Android 插件的 IntelliJ |
|
||
|
||
首次构建:
|
||
|
||
```bat
|
||
cd starschedule
|
||
gradlew.bat :app:assembleDebug
|
||
```
|
||
|
||
Unix:
|
||
|
||
```bash
|
||
./gradlew :app:assembleDebug
|
||
```
|
||
|
||
仓库与依赖解析优先走腾讯云 Maven 镜像,找不到时回落到 Google Maven 与 Maven Central。详见 [构建与发布](构建与发布.md)。
|
||
|
||
## 2. 工程模块
|
||
|
||
```
|
||
starschedule/
|
||
├── app/ # Android 应用
|
||
│ └── src/main/kotlin/com/xingheyuzhuan/shiguangschedule/
|
||
│ ├── MainActivity.kt
|
||
│ ├── MyApplication.kt
|
||
│ ├── data/sync/SyncManager.kt
|
||
│ ├── service/ # AlarmReceiver + Notification/Dnd Worker
|
||
│ └── widget/ # tiny / compact / double_days / list_vertical
|
||
├── shared/
|
||
│ ├── schemas/ # Room 主库 schema(版本 3/4/5)
|
||
│ └── src/
|
||
│ ├── commonMain/
|
||
│ │ ├── composeResources/
|
||
│ │ ├── kotlin/.../shiguangschedule/
|
||
│ │ └── proto/ # schedule_style.proto, widget_snapshot.proto
|
||
│ └── androidMain/kotlin/...
|
||
├── gradle/libs.versions.toml
|
||
└── docs/
|
||
```
|
||
|
||
Gradle 模块名:`:app`、`:shared`。
|
||
|
||
Kotlin 包名未改成 `com.starschedule`,避免全量 rename。新文件继续放在 `com.xingheyuzhuan.shiguangschedule` 下。
|
||
|
||
## 3. shared 源码地图
|
||
|
||
```
|
||
com.xingheyuzhuan.shiguangschedule
|
||
├── App.kt # 主题、导航宿主、页面分发
|
||
├── Navigation.kt # Destination 定义
|
||
├── data/
|
||
│ ├── api/date/ # 节假日 HTTP
|
||
│ ├── api/webdav/ # WebDAV 客户端与配置
|
||
│ ├── db/main/ # 主库实体、DAO、迁移
|
||
│ ├── db/widget/ # 小组件库
|
||
│ ├── di/ # Koin 模块、AppStorage
|
||
│ ├── model/ # 设置、导入导出 JSON、样式
|
||
│ ├── repository/
|
||
│ └── sync/ # WidgetDataSynchronizer(展开近 7 天)
|
||
├── navigation/ # AppChannels 等
|
||
├── tool/ # 文件、ICS、ZIP、加密、启动清缓存
|
||
└── ui/
|
||
├── components/
|
||
├── schedule/ # 周课表
|
||
├── today/
|
||
├── settings/ # 我的及子页
|
||
├── schoolselection/web/ # 正方 WebView(目录名沿用历史)
|
||
└── theme/
|
||
```
|
||
|
||
`ui/schoolselection` 不再包含选学校,只保留 WebView 导入。
|
||
|
||
## 4. 依赖注入
|
||
|
||
- 共享:`SharedModule` `@ComponentScan("com.xingheyuzhuan.shiguangschedule")`,并 include `DatabaseModule`、`DataStoreModule`。
|
||
- Android:`AppModule` include `SharedModule`,再扫一遍同包名(闹钟、小组件更新等 Android 类)。
|
||
- 启动:`MyApplication` 里 `startKoin<ScheduleAppConfig>`。
|
||
|
||
常见注入:
|
||
|
||
| 注解 | 用途 |
|
||
|---|---|
|
||
| `@Single` | Repository、数据库、Synchronizer |
|
||
| `@Factory` | DAO |
|
||
| `@Named("AppSettings")` 等 | 多个 DataStore |
|
||
| `@Named("FilesDir")` / `CacheDir` | 路径 |
|
||
| `@Named("AppVersionName")` | 关于页版本号 |
|
||
|
||
新增 Repository:打 `@Single`,保证在扫描包内即可,不必改模块列表。
|
||
|
||
`WidgetDataSynchronizer` 与 `ResourceInitializerManager` 使用 `createdAtStart = true`,进程起来就会跑。
|
||
|
||
## 5. 导航约定
|
||
|
||
`Destination` 全部 `@Serializable`,并在 `navSerializersModule` 注册,否则进程被杀后无法还原返回栈。
|
||
|
||
主 Tab 实现 `MainDestination`。`App.kt` 里切主 Tab 会 `backStack.clear()`。
|
||
|
||
带参数示例:
|
||
|
||
```kotlin
|
||
@Serializable
|
||
data class AddEditCourse(val courseId: String? = null) : Destination
|
||
```
|
||
|
||
`courseId == null` 表示新建。
|
||
|
||
## 6. UI 约定
|
||
|
||
- 界面用 Compose Material 3。
|
||
- 文案一律 `stringResource(Res.string.xxx)`,写在 `composeResources/values/strings.xml`,不要在 Kotlin 里硬编码用户可见中文(Toast 里少数历史硬编码除外,新代码不要再加)。
|
||
- 图标用 `composeResources/drawable` 的 vector,`vectorResource(Res.drawable.xxx)`。
|
||
- ViewModel 用 `koinViewModel()`。
|
||
- 需要系统文件框时用 `rememberFileManager`,不要直接写 Activity Result。
|
||
|
||
一级页用 `AdaptiveNavigationScaffold` 包底部导航。子页用普通 `Scaffold` + 返回箭头。
|
||
|
||
## 7. 课表领域规则
|
||
|
||
实现时必须遵守,否则周次、提醒、ICS 会对不齐:
|
||
|
||
1. **星期** `Course.day`:`1 = 周一` … `7 = 周日`(ISO,不是 Java `Calendar` 的周日=1)。
|
||
2. **节次** 从 1 连续编号。导入 JSON 时编号不连续会抛错。
|
||
3. **时间字符串** 必须 `HH:mm`,24 小时,正则 `^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$`。
|
||
4. **开学日期** 是「教务第一周」的锚定日;`firstDayOfWeek` 为 1 或 7。计算周次前先把开学日期回齐到该周的起始日。
|
||
5. **正方导入 / JSON 导入** 对目标课表是覆盖式:先删该表全部课程再写入。
|
||
6. **同名课程** 导入时尽量复用同一 `colorInt`(颜色池下标,不是 ARGB)。
|
||
7. **自定义时间课** `isCustomTime = true` 时 `startSection`/`endSection` 可空,必须有 `customStartTime`/`customEndTime`。
|
||
8. **备注** 限制 300 字(编辑页校验)。
|
||
|
||
颜色下标对应 `ScheduleGridStyle.courseColorMaps`。改颜色池大小时,旧课的下标可能越界,显示侧需要按列表长度取模或回落。
|
||
|
||
## 8. 改功能时改哪里
|
||
|
||
| 需求 | 主要位置 |
|
||
|---|---|
|
||
| 新设置项(全局) | `AppSettingsModel` Key + `AppSettingsRepository` + 对应 Screen |
|
||
| 新设置项(按课表) | `CourseTableConfig` + DAO + 可能需要 Room 迁移 |
|
||
| 新页面 | `Destination` + `App.kt` + `ui/...` |
|
||
| 导入格式 | `CourseImportExport` + `CourseConversionRepository` |
|
||
| 正方抓取 | `composeResources/files/zhengfang.js` |
|
||
| Bridge 新 action | `WebBridgeProtocol.kt` 的 `JS_BRIDGE_INIT` + `WebBridgeHandler` |
|
||
| 小组件外观 | `app/.../widget/<规格>/` 的 layout xml 与 Renderer |
|
||
| 小组件数据字段 | `WidgetCourse` + `WidgetDataSynchronizer`(改实体要升 Widget 库版本) |
|
||
| 样式字段 | `schedule_style.proto` + `ScheduleGridStyle` 转换 + 样式页 |
|
||
| 用户文案 | `composeResources/values/strings.xml`;系统通知/小组件还要改 `app/.../res/values/strings.xml` |
|
||
| 提醒 / 勿扰调度 | `app/.../service/CourseNotificationWorker.kt`、`DndSchedulerWorker.kt` |
|
||
| 小组件定期刷新 | `app/.../widget/WorkManagerHelper.kt`、`WidgetSyncWorkers.kt` |
|
||
|
||
页面与 Destination 对照见 [页面与导航](页面与导航.md)。
|
||
|
||
改 Room 实体:
|
||
|
||
- 主库升 `MainAppDatabase.version`,能 AutoMigration 就写 `autoMigrations`,否则在 `DatabaseMigrations.kt` 写 `Migration` 并注册。
|
||
- 更新 `shared/schemas/.../N.json`(构建时 Room 会导出,提交 schema)。
|
||
|
||
## 9. Android 应用模块要点
|
||
|
||
`MainActivity` 只 `setContent { App() }`,业务不要往 Activity 堆。`launchMode` 为 `singleTask`。
|
||
|
||
启动顺序(`MyApplication.onCreate`):
|
||
|
||
1. `startKoin<ScheduleAppConfig>`(`workManagerFactory()` + `androidContext`)
|
||
2. Koin `createdAtStart`:`WidgetDataSynchronizer`、`ResourceInitializerManager`(清 `share_temp`)、`SyncManager`
|
||
3. `App()` 读 DataStore 决定启动页(周课表或今日课表)
|
||
|
||
### 9.1 闹钟与 Worker
|
||
|
||
| 类 | 职责 |
|
||
|---|---|
|
||
| `CourseNotificationWorker` | 根据 Widget 库近 7 天课程,向 `AlarmManager` 写入提醒闹钟(槽 `50010`–`50110`) |
|
||
| `DndSchedulerWorker` | 上课开始/结束切换勿扰或静音的闹钟 |
|
||
| `CourseAlarmReceiver` | 闹钟触发:发通知、切模式、点关闭 |
|
||
| `SyncManager` | 订阅同步完成与样式变更,入队上述 Worker 并 `updateAllWidgets` |
|
||
| `WidgetUiUpdateWorker` | 约 15 分钟刷新小组件 UI |
|
||
| `FullDataSyncWorker` | 约每天 `syncNow()` |
|
||
|
||
`CourseAlarmReceiver` 通过 `KoinComponent` 取 `AppSettingsRepository`。改槽位 ID 时核对两个 Worker 与 Receiver 的常量,避免覆盖。
|
||
|
||
### 9.2 小组件
|
||
|
||
四种规格各自一个 `AppWidgetProvider` + `*NativeRenderer`:
|
||
|
||
| Provider | 布局 xml |
|
||
|---|---|
|
||
| `widget.tiny.TinyNativeProvider` | `shiguangschedule_tiny_widget` |
|
||
| `widget.compact.CompactNativeProvider` | `shiguangschedule_compact_widget` |
|
||
| `widget.double_days.DoubleDaysNativeProvider` | `shiguangschedule_double_days_widget` |
|
||
| `widget.list_vertical.ListVerticalNativeProvider` | `shiguangschedule_list_vertical_widget` |
|
||
|
||
刷新入口集中在 `widget.updateAllWidgets`。`onEnabled` 调用 `WorkManagerHelper.schedulePeriodicWork`;某个规格的最后一个实例被移除时 `onDisabled` 会 `cancelAllWork`(会取消全局定期任务,其他规格仍可通过打开应用由 `SyncManager` 刷新)。
|
||
|
||
### 9.3 Release
|
||
|
||
`isMinifyEnabled = true`。`proguard-rules.pro` 已 keep Koin 注解、Worker、AppWidget、Serialization、Room 实体。
|
||
`NativeBridge.postMessage` 与 `WebPostService` 带 `@JavascriptInterface`,包名在 `com.xingheyuzhuan.shiguangschedule.ui.schoolselection.web`,**当前规则没有按注解单独 keep 该方法**。改 Bridge 或打正式包后,必须用 Release 包在真机跑一遍正方导入,确认 JS 能调到 Native。必要时增加:
|
||
|
||
```
|
||
-keepclassmembers class * {
|
||
@android.webkit.JavascriptInterface <methods>;
|
||
}
|
||
```
|
||
|
||
## 10. WebView 与 JS
|
||
|
||
详见 [正方教务导入](正方教务导入.md)。开发时注意:
|
||
|
||
- Bridge 对象名是 `shiguangBridge` / `shiguangBridgePromise`(兼容旧名 `AndroidBridge`)。
|
||
- 注入脚本在每次 `evaluateJavascript` 时若未检测到 `_shiguangBridgeInjected` 会先注入 `JS_BRIDGE_INIT`。
|
||
- 正方脚本是页面加载后由用户点「执行导入」才 `executeScript`,不是打开网页就跑。
|
||
|
||
## 11. 测试与手动验收
|
||
|
||
目前以手动验证为主。`shared` 有 `commonTest` 依赖 `kotlin-test`,`app` 有 JUnit / Espresso 依赖,但核心课表逻辑缺少现成单测。
|
||
|
||
建议优先补:
|
||
|
||
- 周次对齐(开学日期、周日作为一周起始、改当前周反推开学日期)
|
||
- JSON 导入校验(节次不连续、时间重叠、自定义时间缺字段)
|
||
- `IcsExportTool` 的日期展开与跳过日期
|
||
- `importCoursesFromList` 覆盖语义(旧课被删)
|
||
|
||
发版前手动清单见 [需求文档 · 验收要点](需求文档.md) 与 [构建与发布 · 发布检查清单](构建与发布.md)。至少覆盖:冷启动、正方导入、JSON 往返、ZIP 恢复、提醒、四种小组件、中文界面无语言切换。
|
||
|
||
## 12. 编码风格
|
||
|
||
- Kotlin official code style(`gradle.properties`)。
|
||
- 注释只写非显而易见的约束(例如星期从周一开始、覆盖导入)。
|
||
- 不要为了「以后可能用」加回学校仓库、i18n、iOS 源集。
|
||
- 不要把用户可见文案做成英文。
|
||
- 新设置项优先进 DataStore(全局)或 `CourseTableConfig`(按课表),不要把全局开关写回 Room。
|
||
|
||
## 13. 本地配置
|
||
|
||
`local.properties` 由本机 Android SDK 路径生成,不要提交。WebDAV 密码只存在用户设备 DataStore 中。
|
||
|
||
不要把 `local.properties`、keystore、用户课表数据库提交进 Git。
|
||
|
||
## 14. 启动时序与默认数据
|
||
|
||
- 无课表时 Repository 会创建默认课表并写入默认 13 节作息(见 [数据模型](数据模型.md) 第 10 节)。
|
||
- 当前课表 ID 为空时回落到库中第一张表。
|
||
- 导出分享写在 `cacheDir/share_temp/`,下次启动由 `ResourceInitializerManager` 删除。
|
||
|
||
## 15. 文档维护
|
||
|
||
改功能时同步改:
|
||
|
||
1. [需求文档](需求文档.md) 的范围 / FR(若用户可见行为变了)
|
||
2. [用户使用说明](用户使用说明.md) 与 [常见问题](常见问题.md)
|
||
3. [页面与导航](页面与导航.md)(若增删 Destination)
|
||
4. [数据模型](数据模型.md)(若改表或 JSON)
|
||
5. [变更记录](变更记录.md)
|
||
|
||
文档必须跟代码一致,不要写未实现的能力。
|