Files
class-schedule/starschedule/docs/开发文档.md
T
2026-09-20 13:33:09 +08:00

271 lines
12 KiB
Markdown
Raw 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.
# 星课表开发文档
本文说明如何搭建环境、读懂代码、以及按现有约定改功能。架构总览见 [架构设计](架构设计.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)
文档必须跟代码一致,不要写未实现的能力。