# 星课表开发文档 本文说明如何搭建环境、读懂代码、以及按现有约定改功能。架构总览见 [架构设计](架构设计.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`。 常见注入: | 注解 | 用途 | |---|---| | `@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`(`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 ; } ``` ## 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) 文档必须跟代码一致,不要写未实现的能力。