12 KiB
星课表开发文档
本文说明如何搭建环境、读懂代码、以及按现有约定改功能。架构总览见 架构设计,表结构见 数据模型。
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 |
首次构建:
cd starschedule
gradlew.bat :app:assembleDebug
Unix:
./gradlew :app:assembleDebug
仓库与依赖解析优先走腾讯云 Maven 镜像,找不到时回落到 Google Maven 与 Maven Central。详见 构建与发布。
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"),并 includeDatabaseModule、DataStoreModule。 - Android:
AppModuleincludeSharedModule,再扫一遍同包名(闹钟、小组件更新等 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()。
带参数示例:
@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 会对不齐:
- 星期
Course.day:1 = 周一…7 = 周日(ISO,不是 JavaCalendar的周日=1)。 - 节次 从 1 连续编号。导入 JSON 时编号不连续会抛错。
- 时间字符串 必须
HH:mm,24 小时,正则^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$。 - 开学日期 是「教务第一周」的锚定日;
firstDayOfWeek为 1 或 7。计算周次前先把开学日期回齐到该周的起始日。 - 正方导入 / JSON 导入 对目标课表是覆盖式:先删该表全部课程再写入。
- 同名课程 导入时尽量复用同一
colorInt(颜色池下标,不是 ARGB)。 - 自定义时间课
isCustomTime = true时startSection/endSection可空,必须有customStartTime/customEndTime。 - 备注 限制 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 对照见 页面与导航。
改 Room 实体:
- 主库升
MainAppDatabase.version,能 AutoMigration 就写autoMigrations,否则在DatabaseMigrations.kt写Migration并注册。 - 更新
shared/schemas/.../N.json(构建时 Room 会导出,提交 schema)。
9. Android 应用模块要点
MainActivity 只 setContent { App() },业务不要往 Activity 堆。launchMode 为 singleTask。
启动顺序(MyApplication.onCreate):
startKoin<ScheduleAppConfig>(workManagerFactory()+androidContext)- Koin
createdAtStart:WidgetDataSynchronizer、ResourceInitializerManager(清share_temp)、SyncManager 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
详见 正方教务导入。开发时注意:
- Bridge 对象名是
shiguangBridge/shiguangBridgePromise(兼容旧名AndroidBridge)。 - 注入脚本在每次
evaluateJavascript时若未检测到_shiguangBridgeInjected会先注入JS_BRIDGE_INIT。 - 正方脚本是页面加载后由用户点「执行导入」才
executeScript,不是打开网页就跑。
11. 测试与手动验收
目前以手动验证为主。shared 有 commonTest 依赖 kotlin-test,app 有 JUnit / Espresso 依赖,但核心课表逻辑缺少现成单测。
建议优先补:
- 周次对齐(开学日期、周日作为一周起始、改当前周反推开学日期)
- JSON 导入校验(节次不连续、时间重叠、自定义时间缺字段)
IcsExportTool的日期展开与跳过日期importCoursesFromList覆盖语义(旧课被删)
发版前手动清单见 需求文档 · 验收要点 与 构建与发布 · 发布检查清单。至少覆盖:冷启动、正方导入、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 节作息(见 数据模型 第 10 节)。
- 当前课表 ID 为空时回落到库中第一张表。
- 导出分享写在
cacheDir/share_temp/,下次启动由ResourceInitializerManager删除。
15. 文档维护
改功能时同步改:
文档必须跟代码一致,不要写未实现的能力。