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

12 KiB
Raw Blame History

星课表开发文档

本文说明如何搭建环境、读懂代码、以及按现有约定改功能。架构总览见 架构设计,表结构见 数据模型。

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"),并 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()。

带参数示例:

@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 对照见 页面与导航。

改 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

详见 正方教务导入。开发时注意:

  • 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. 文档维护

改功能时同步改:

  1. 需求文档 的范围 / FR(若用户可见行为变了)
  2. 用户使用说明 与 常见问题
  3. 页面与导航(若增删 Destination)
  4. 数据模型(若改表或 JSON)
  5. 变更记录

文档必须跟代码一致,不要写未实现的能力。