[new] new project

This commit is contained in:
2026-09-20 13:33:09 +08:00
commit ca6a52fb2d
997 changed files with 140250 additions and 0 deletions
+270
View File
@@ -0,0 +1,270 @@
# 星课表开发文档
本文说明如何搭建环境、读懂代码、以及按现有约定改功能。架构总览见 [架构设计](架构设计.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)
文档必须跟代码一致,不要写未实现的能力。