[new] new project
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# 星课表文档
|
||||
|
||||
本文档按 **当前代码** 编写,描述星课表(starschedule)的需求、使用方式与实现。不要把已删除的拾光能力(多学校仓库、iOS、系统日历同步等)当成现网功能。
|
||||
|
||||
当前版本:`1.0.0`(versionCode `1`)。
|
||||
应用包名:`com.starschedule`。
|
||||
Kotlin 包名:`com.xingheyuzhuan.shiguangschedule`。
|
||||
界面语言:仅简体中文。
|
||||
|
||||
## 读哪一份
|
||||
|
||||
| 文档 | 读者 | 内容 |
|
||||
|---|---|---|
|
||||
| [需求文档](需求文档.md) | 产品、开发、测试 | 目标、范围、功能与非功能需求、验收 |
|
||||
| [用户使用说明](用户使用说明.md) | 最终用户 | 各功能操作步骤 |
|
||||
| [常见问题](常见问题.md) | 用户、测试 | 导入失败、提醒不响、小组件不刷新等 |
|
||||
| [隐私与数据](隐私与数据.md) | 用户、发布 | 权限、本地存储、网络去向 |
|
||||
| [架构设计](架构设计.md) | 开发 | 模块划分、分层、关键流程 |
|
||||
| [开发文档](开发文档.md) | 开发 | 环境、目录、约定与扩展方式 |
|
||||
| [页面与导航](页面与导航.md) | 开发 | Destination、页面、入口路径 |
|
||||
| [数据模型](数据模型.md) | 开发 | Room / DataStore / JSON / 备份协议 |
|
||||
| [正方教务导入](正方教务导入.md) | 开发 | WebView、JS Bridge、正方脚本 |
|
||||
| [构建与发布](构建与发布.md) | 开发、发布 | Gradle、镜像、打包、版本 |
|
||||
| [术语表](术语表.md) | 所有人 | 课表领域与工程用语 |
|
||||
| [变更记录](变更记录.md) | 所有人 | 版本说明 |
|
||||
|
||||
## 快速对照
|
||||
|
||||
- 改界面文案:`shared/src/commonMain/composeResources/values/strings.xml`
|
||||
- 改正方抓取:`shared/src/commonMain/composeResources/files/zhengfang.js`
|
||||
- 改课表存储:`shared/.../data/db/main/`,升 `MainAppDatabase` 版本
|
||||
- 改全局设置:`AppSettingsModel` + `AppSettingsRepository`
|
||||
- 打 Debug 包:在仓库根目录执行 `gradlew.bat :app:assembleDebug`(模块名是 `:app`,不是 `:androidApp`)
|
||||
@@ -0,0 +1,34 @@
|
||||
# 变更记录
|
||||
|
||||
## 1.0.0(versionCode 1)
|
||||
|
||||
首个星课表版本。从拾光课程表精简而来。
|
||||
|
||||
**保留**
|
||||
|
||||
- 今日课表、周课表、多课表、课程增删改
|
||||
- 自定义节次与学期配置
|
||||
- 正方教务导入(脚本内置于 `files/zhengfang.js`)
|
||||
- JSON / ICS / ZIP / WebDAV
|
||||
- 上课提醒、勿扰/静音、跳过日期
|
||||
- 课表样式、主题
|
||||
- 四种 Android 小组件
|
||||
|
||||
**相对拾光移除**
|
||||
|
||||
- iOS、桌面端源集与模块
|
||||
- 学校列表、远程适配仓库、kgit
|
||||
- 非正方教务脚本
|
||||
- 系统日历写入同步
|
||||
- 多语言与语言切换
|
||||
- 开源许可证页、贡献者列表、开发者模式 UI、应用内检查更新
|
||||
- aboutlibraries
|
||||
|
||||
**标识**
|
||||
|
||||
- 显示名:星课表
|
||||
- `applicationId`:`com.starschedule`
|
||||
- Kotlin 包名未改,仍为 `com.xingheyuzhuan.shiguangschedule`
|
||||
- Android 模块目录:`app/`(不再使用 `androidApp/`)
|
||||
- 导出文件名前缀:`starschedule_`
|
||||
- WebDAV 默认根路径字符串仍为历史值 `ShiguangSchedule`
|
||||
@@ -0,0 +1,68 @@
|
||||
# 常见问题
|
||||
|
||||
## 正方导入
|
||||
|
||||
**导入按钮点了没反应或提示不在课表页**
|
||||
脚本会检查当前页 HTML 是否包含「课表查询」,并读取 `#shcPDF` 的 `data-type`。必须已经登录,进入「学生课表查询」,选学年学期并点过查询,页面上能看到课。
|
||||
|
||||
**提示没有 jQuery**
|
||||
正方课表页一般自带 jQuery。若学校改过前端、或当前不是标准课表查询页,脚本会失败。可试网页右上角切到「电脑模式」再查询。
|
||||
|
||||
**导入成功但时间不准**
|
||||
正方脚本只写入课程名、星期、节次、周次、教师、地点,**不写入节次钟点和开学日期**。请到「自定义时间段」「设置开学日期」按本校作息补全,否则提醒和小组件的钟点会对不上。
|
||||
|
||||
**导入后原来的课没了**
|
||||
这是覆盖语义:会先删除目标课表的全部课程再插入。导入前先选对课表,或先做 ZIP / JSON 备份。
|
||||
|
||||
**学校不是正方 / 页面结构不同**
|
||||
本应用不维护多学校适配仓库。只适配常见正方 HTML 列表(`#kblist_table`)与网格(`#kbgrid_table_0`)。其他教务请用 JSON 导入或手动排课。
|
||||
|
||||
## 周次与显示
|
||||
|
||||
**今日课表一直提示设置开学日期**
|
||||
「我的 → 设置开学日期」,选教务第一周对应的那一天(再配合每周起始日对齐)。未设置时无法计算当前周。
|
||||
|
||||
**当前周和教务差一周**
|
||||
开学日期必须是「第一周」的锚定日,且「每周起始日」与教务一致(周一或周日)。改「当前周数」会反推开学日期。
|
||||
|
||||
**周末没有格子**
|
||||
打开「我的 → 是否显示周末」。这是按课表保存的,换课表可能不一样。
|
||||
|
||||
## 提醒
|
||||
|
||||
**到点没有通知**
|
||||
1. 打开「课程提醒」,授予通知权限。
|
||||
2. Android 12+ 打开精确闹钟权限。
|
||||
3. 国产系统允许自启动、忽略电池优化。
|
||||
4. 确认已设开学日期和节次时间,且当天不在跳过日期里。
|
||||
5. 提醒依赖近 7 天已展开的小组件库数据;改课后打开一次应用,让同步跑完。
|
||||
|
||||
**上课没有自动勿扰**
|
||||
必须先开课程提醒,再选勿扰,并授予系统「勿扰模式」权限。静音模式改的是铃声音量,部分机型会被系统策略拦住。
|
||||
|
||||
**手环收不到通知**
|
||||
打开「兼容穿戴设备同步通知」,关闭实时(Ongoing)通知属性,方便部分同步软件抓取。
|
||||
|
||||
## 小组件
|
||||
|
||||
**桌面搜不到或名字不对**
|
||||
系统桌面长按 → 小组件 → 搜索「星课表」。四种名称:超小课程2x1、紧凑课程2x2、近日课程4x2、垂直列表课表4xN。
|
||||
|
||||
**内容不更新**
|
||||
小组件读独立 Widget 库。打开一次应用触发同步;或移走再添加。定期还有 15 分钟 UI 刷新与每天一次全量同步(WorkManager,系统可能推迟)。
|
||||
|
||||
## 备份
|
||||
|
||||
**WebDAV 连不上**
|
||||
检查地址是否含协议(`https://` 或 `http://`)、账号密码、远端目录是否有权限。密码只存在本机加密存储。默认根目录名仍是历史字符串 `ShiguangSchedule`,备份文件在其下的 `Backup/`。
|
||||
|
||||
**恢复失败,提示版本过新**
|
||||
备份模块的 schema 比当前应用新。先升级应用再恢复。
|
||||
|
||||
**恢复后壁纸没了**
|
||||
样式备份会尽量带上本地壁纸路径;换机后原路径无效,需在个性化里重新选图。
|
||||
|
||||
## 构建
|
||||
|
||||
**找不到 `gradlew` / `:androidApp`**
|
||||
在 `starschedule/` 目录执行。模块已改名为 `:app`:`gradlew.bat :app:assembleDebug`。
|
||||
@@ -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)
|
||||
|
||||
文档必须跟代码一致,不要写未实现的能力。
|
||||
@@ -0,0 +1,224 @@
|
||||
# 星课表数据模型
|
||||
|
||||
## 1. 存储一览
|
||||
|
||||
| 介质 | 路径 / 名称 | 内容 |
|
||||
|---|---|---|
|
||||
| Room 主库 | 应用数据库目录 | 课表、课程、周次、节次、课表配置 |
|
||||
| Room Widget 库 | 应用数据库目录 | 近 7 天已展开课程 + 小组件用设置 |
|
||||
| DataStore Preferences | `files/datastore/app_settings.preferences_pb` | 当前课表、提醒、主题、启动页等 |
|
||||
| DataStore Preferences | `files/datastore/api_config.preferences_pb` | WebDAV(密码密文) |
|
||||
| DataStore Proto | `filesDir/schedule_style_settings.pb` | 课表网格样式 |
|
||||
| 私有文件 | filesDir 下壁纸等 | 课表背景图 |
|
||||
| 缓存 | cacheDir/`share_temp` | 导出分享用临时文件,启动时清理 |
|
||||
|
||||
主库当前版本 **5**。从更早版本升级时:1→2 手写迁移(拆出 `course_table_config`),3→4、4→5 为 AutoMigration(5 删除旧 `app_settings` 表)。
|
||||
|
||||
## 2. 主库实体
|
||||
|
||||
### 2.1 course_tables
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| id | String PK | UUID |
|
||||
| name | String | 显示名 |
|
||||
| createdAt | Long | 创建时间戳 |
|
||||
|
||||
### 2.2 course_table_config
|
||||
|
||||
与课表 1:1,`courseTableId` PK + FK CASCADE。
|
||||
|
||||
| 字段 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| showWeekends | false | 周课表是否显示六日 |
|
||||
| semesterStartDate | null | `yyyy-MM-dd` |
|
||||
| semesterTotalWeeks | 20 | |
|
||||
| defaultClassDuration | 45 | 新增节次默认课时(分钟) |
|
||||
| defaultBreakDuration | 10 | 默认课间 |
|
||||
| firstDayOfWeek | 1 | 1=周一,7=周日 |
|
||||
|
||||
### 2.3 courses
|
||||
|
||||
FK `courseTableId` → course_tables CASCADE。
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| id | UUID |
|
||||
| name / teacher / position | 文本 |
|
||||
| day | 1–7,周一到周日 |
|
||||
| startSection / endSection | 节次,自定义时间时可空 |
|
||||
| isCustomTime | 是否用 customStartTime/EndTime |
|
||||
| customStartTime / customEndTime | `HH:mm` |
|
||||
| colorInt | 颜色池下标 |
|
||||
| remark | 可空 |
|
||||
|
||||
### 2.4 course_weeks
|
||||
|
||||
联合主键 `(courseId, weekNumber)`。FK courseId CASCADE。一门课上哪些教学周。
|
||||
|
||||
### 2.5 time_slots
|
||||
|
||||
联合主键 `(number, courseTableId)`。
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| number | 节次号,从 1 连续 |
|
||||
| startTime / endTime | `HH:mm` |
|
||||
| alias | 可空,有则 UI 可显示别名 |
|
||||
|
||||
新建课表时写入默认 13 节(见第 10 节)。
|
||||
|
||||
## 3. Widget 库
|
||||
|
||||
实体类在 `data/db/widget/`。库版本 **3**,`exportSchema = false`。
|
||||
|
||||
### widget_courses(`WidgetCourse`)
|
||||
|
||||
已按自然日展开的实例,不再存周次。同步窗口:今天起 **7 天**。提醒 Worker 也读这张表排闹钟。
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| id | 主键 |
|
||||
| name / teacher / position | 文本 |
|
||||
| startTime / endTime | 当天该节的钟点 `HH:mm` |
|
||||
| isSkipped | 是否落在跳过日期 |
|
||||
| date | `yyyy-MM-dd` |
|
||||
| colorInt | 与主库相同下标 |
|
||||
|
||||
### widget_semester_start_date(`WidgetAppSettings`)
|
||||
|
||||
表名是历史名,实体叫 `WidgetAppSettings`。单行,`id = 1`。
|
||||
|
||||
| 字段 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| semesterStartDate | null | 当前课表开学日期 |
|
||||
| semesterTotalWeeks | 20 | |
|
||||
| firstDayOfWeek | 1 | 1=周一,7=周日 |
|
||||
|
||||
## 4. 应用设置 DataStore
|
||||
|
||||
`AppSettingsModel`:
|
||||
|
||||
| Key | 含义 | 默认 |
|
||||
|---|---|---|
|
||||
| current_course_table_id | 当前课表 | 空则回落到库里第一张表 |
|
||||
| reminder_enabled | 上课提醒 | false |
|
||||
| remind_before_minutes | 提前分钟 | 15 |
|
||||
| skipped_dates | `yyyy-MM-dd` 集合 | 空 |
|
||||
| auto_mode_enabled | 上课自动模式总开关 | false |
|
||||
| auto_control_mode | `DND` / `SILENT` | DND |
|
||||
| compat_wearable_sync | 穿戴兼容 | false |
|
||||
| show_non_current_week_courses | 周课表显示非本周课 | false |
|
||||
| start_screen | `COURSE_SCHEDULE` / `TODAY_SCHEDULE` | 周课表 |
|
||||
| theme_mode | `FOLLOW_SYSTEM` / `LIGHT` / `DARK` | 跟随系统 |
|
||||
| use_dynamic_color | Material You | true |
|
||||
| custom_light_primary / custom_dark_primary | 种子色 ARGB long | 内置默认蓝 |
|
||||
|
||||
## 5. 课表样式 Proto
|
||||
|
||||
`schedule_style.proto` → `ScheduleGridStyleProto`,业务层转为 `ScheduleGridStyle`。
|
||||
|
||||
主要字段:侧栏宽、表头高、节次格高、圆角、内外边距、透明度、颜色池(浅/深成对)、字体缩放、若干 hide/show 开关、边框类型、节次模式或 24h 模式、页面/课程文字色、背景图路径。
|
||||
|
||||
边框:`BORDER_TYPE_NONE` / `SOLID` / `DASHED`。
|
||||
模式:`SECTION_MODE` / `TIME_24H_MODE`。
|
||||
|
||||
## 6. 单表 JSON(导入导出)
|
||||
|
||||
导出模型 `CourseTableExportModel`:
|
||||
|
||||
```json
|
||||
{
|
||||
"courses": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "大学物理",
|
||||
"teacher": "张三",
|
||||
"position": "A101",
|
||||
"day": 1,
|
||||
"startSection": 1,
|
||||
"endSection": 2,
|
||||
"color": 0,
|
||||
"weeks": [1, 2, 3, 4],
|
||||
"isCustomTime": false,
|
||||
"customStartTime": null,
|
||||
"customEndTime": null,
|
||||
"remark": null
|
||||
}
|
||||
],
|
||||
"timeSlots": [
|
||||
{ "number": 1, "startTime": "08:00", "endTime": "08:45", "alias": null }
|
||||
],
|
||||
"config": {
|
||||
"semesterStartDate": "2026-02-23",
|
||||
"semesterTotalWeeks": 20,
|
||||
"defaultClassDuration": 45,
|
||||
"defaultBreakDuration": 10,
|
||||
"firstDayOfWeek": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
导入 `CourseTableImportModel` 更宽松:`id`、`color` 可缺省;`timeSlots`、`config` 可缺省。未知字段忽略(`ignoreUnknownKeys`)。
|
||||
|
||||
校验:
|
||||
|
||||
- 有 timeSlots 时 number 必须从 1 连续,时间合法且不重叠。
|
||||
- 自定义时间课程必须有合法起止且开始早于结束。
|
||||
|
||||
**覆盖语义:** `importCoursesFromList` 先 `deleteCoursesByTableId`。
|
||||
|
||||
正方脚本提交的是 `ImportCourseJsonModel` 列表(无 id),经同一导入函数写入。
|
||||
|
||||
## 7. 全量备份
|
||||
|
||||
`COURSE_SCHEMA_VERSION = 1`。
|
||||
|
||||
内存结构 `TotalAppBackupEnvelope`:
|
||||
|
||||
- `backupTimestamp`
|
||||
- `appVersionCode`(此处实际承载 schema 版本)
|
||||
- `currentCourseTableId`
|
||||
- `allTables`: `SingleTablePack` 列表(tableId、tableName、createdAt、tableData)
|
||||
|
||||
物理 ZIP / WebDAV 由 `BackupViewModel` 按模块打包,文件布局:
|
||||
|
||||
| 条目 | 内容 |
|
||||
|---|---|
|
||||
| `meta.json` | `BackupMeta`:时间戳、应用 versionName/versionCode、模块列表 |
|
||||
| `course.cbor` | 全课表 `TotalAppBackupEnvelope`(schema 1) |
|
||||
| `style.cbor` | 样式快照(`STYLE_SCHEMA_VERSION = 1`) |
|
||||
|
||||
`BackupModule` key:`course`、`style`。恢复时若备份模块 schema 比当前新,失败并提示升级 App。
|
||||
|
||||
WebDAV 上传到 `{rootPath}/Backup/`(`FIXED_BACKUP_DIR = "Backup"`)。默认 `rootPath` 字符串为 `ShiguangSchedule`(历史目录名,不是「星课表」)。
|
||||
|
||||
## 8. ICS
|
||||
|
||||
`IcsExportTool` 按开学日期、总周数、每周起始日,把每门课的每个教学周展开成一次 `VEVENT`。自定义时间课用 custom 时刻,否则用节次表。可带 VALARM。跳过日期集合若传入则那些天不生成事件。
|
||||
|
||||
## 9. WidgetSnapshot Proto
|
||||
|
||||
`widget_snapshot.proto` 定义过 `WidgetSnapshot`(课程列表 + 当前周 + 样式)。现网小组件主路径走 Room Widget 库;该 proto 保留给序列化/跨进程快照类用途,改字段时两边都要看。
|
||||
|
||||
## 10. 新建课表的默认节次
|
||||
|
||||
`CourseTableRepository` 在创建课表时插入 13 节(时长 45 分钟,课间 5 或 10 分钟,含午晚休间隔):
|
||||
|
||||
| 节次 | 开始 | 结束 |
|
||||
|---|---|---|
|
||||
| 1 | 08:00 | 08:45 |
|
||||
| 2 | 08:50 | 09:35 |
|
||||
| 3 | 09:50 | 10:35 |
|
||||
| 4 | 10:40 | 11:25 |
|
||||
| 5 | 11:30 | 12:15 |
|
||||
| 6 | 14:00 | 14:45 |
|
||||
| 7 | 14:50 | 15:35 |
|
||||
| 8 | 15:45 | 16:30 |
|
||||
| 9 | 16:35 | 17:20 |
|
||||
| 10 | 18:30 | 19:15 |
|
||||
| 11 | 19:20 | 20:05 |
|
||||
| 12 | 20:10 | 20:55 |
|
||||
| 13 | 21:10 | 21:55 |
|
||||
|
||||
学校作息不同时,应在「自定义时间段」改这些时刻。正方导入不会覆盖这张表。
|
||||
@@ -0,0 +1,23 @@
|
||||
# 术语表
|
||||
|
||||
| 用语 | 含义 |
|
||||
|---|---|
|
||||
| 星课表 / starschedule | 本应用的显示名与工程名 |
|
||||
| 课表(CourseTable) | 一份独立课表,有自己的课程、节次、学期配置。用户可同时有多份 |
|
||||
| 当前课表 | DataStore 里的 `current_course_table_id`,周课表、今日课表、小组件都读它 |
|
||||
| 课程(Course) | 一条上课安排:名称、星期、节次或自定义时刻、周次、地点、教师等 |
|
||||
| 课程实例 | 一门课在某个教学周的一次上课。小组件库按自然日展开后的记录 |
|
||||
| 节次(TimeSlot) | 第 n 节课的起止钟点,按课表独立。编号从 1 连续 |
|
||||
| 自定义时间课 | `isCustomTime = true`,用 `HH:mm` 起止,节次可空 |
|
||||
| 开学日期 | 学期第一周的锚定日(`yyyy-MM-dd`)。计算当前周前会先对齐到 `firstDayOfWeek` |
|
||||
| 每周起始日 | `firstDayOfWeek`:`1` 周一,`7` 周日 |
|
||||
| 跳过日期 | 不提醒、小组件标记跳过的日期集合,可从节假日接口写入 |
|
||||
| 颜色池下标 | `colorInt`,对应样式里 `courseColorMaps` 的序号,不是 ARGB |
|
||||
| 正方 | 正方教务系统。本应用只内置这一套 HTML 抓取脚本 |
|
||||
| JS Bridge | WebView 里 JS 调 Native 的通道:`shiguangBridge` / `shiguangBridgePromise` |
|
||||
| 覆盖导入 | `importCoursesFromList` 先删该表全部课程再插入 |
|
||||
| 主库 | `MainAppDatabase`,用户课表真相源,当前版本 5 |
|
||||
| Widget 库 | `WidgetDatabase`,近 7 天快照,当前版本 3 |
|
||||
| applicationId | 安装包名 `com.starschedule`,与 Kotlin 包名不是同一个东西 |
|
||||
| Kotlin 包名 | 源码仍为 `com.xingheyuzhuan.shiguangschedule` |
|
||||
| Destination | Navigation3 页面键,必须 `@Serializable` 并注册 serializer |
|
||||
@@ -0,0 +1,96 @@
|
||||
# 构建与发布
|
||||
|
||||
## 1. 版本
|
||||
|
||||
定义在 `app/build.gradle.kts`:
|
||||
|
||||
```kotlin
|
||||
versionCode = 1
|
||||
versionName = "1.0.0"
|
||||
applicationId = "com.starschedule"
|
||||
namespace = "com.xingheyuzhuan.shiguangschedule"
|
||||
```
|
||||
|
||||
升版本时两处一起改。`versionCode` 必须递增才能覆盖安装。
|
||||
|
||||
## 2. 常用命令
|
||||
|
||||
在 `starschedule/` 目录:
|
||||
|
||||
```bat
|
||||
gradlew.bat :app:assembleDebug
|
||||
gradlew.bat :app:assembleRelease
|
||||
gradlew.bat :app:installDebug
|
||||
```
|
||||
|
||||
Debug / Release APK 文件名:
|
||||
|
||||
```
|
||||
starschedule-v{versionName}-{abi}-{buildType}.apk
|
||||
```
|
||||
|
||||
ABI:`armeabi-v7a`、`arm64-v8a`、`x86_64`。未打 universal 包。
|
||||
|
||||
输出目录:`app/build/outputs/apk/<buildType>/`。
|
||||
|
||||
## 3. 镜像
|
||||
|
||||
`settings.gradle.kts`:
|
||||
|
||||
1. 腾讯云 `https://mirrors.cloud.tencent.com/nexus/repository/maven-public/`(优先)
|
||||
2. `google()`(仅 androidx / com.android / com.google)
|
||||
3. `mavenCentral()`
|
||||
4. 插件仓库额外还有 `gradlePluginPortal()`
|
||||
|
||||
`gradle/wrapper/gradle-wrapper.properties`:
|
||||
|
||||
```
|
||||
distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-9.7.1-bin.zip
|
||||
```
|
||||
|
||||
模块内禁止再声明仓库(`FAIL_ON_PROJECT_REPOS`)。
|
||||
|
||||
## 4. 关键 Gradle 开关
|
||||
|
||||
`gradle.properties`:
|
||||
|
||||
- 配置缓存、构建缓存、并行
|
||||
- JVM 堆 4096M
|
||||
- `android.nonTransitiveRClass=true`
|
||||
- `kotlin.native.ignoreDisabledTargets=true`(即使当前无 native 目标也无妨)
|
||||
|
||||
`app`:
|
||||
|
||||
- `localeFilters`: `zh`, `zh-rCN`
|
||||
- `generateLocaleConfig = false`
|
||||
- Release:minify + shrinkResources,当前 `signingConfig` 暂用 debug 签名,**正式上架前必须换成正式 keystore**。
|
||||
|
||||
## 5. 依赖版本目录
|
||||
|
||||
统一写在 `gradle/libs.versions.toml`。不要在子模块写死版本号。
|
||||
|
||||
主要库(版本以 `libs.versions.toml` 为准):Compose Multiplatform 1.11.1、Material 3、Navigation3、Room 3.0.1、DataStore 1.2.1、Koin 4.2.2、Ktor 3.5.2、Wire 6.4.5、Okio、Coil 3、kotlinx-serialization / datetime、WorkManager 2.11.2。
|
||||
|
||||
## 6. ProGuard
|
||||
|
||||
Release 开启混淆。`app/proguard-rules.pro` 已 keep:
|
||||
|
||||
- Koin 模块、`@Single` / `@Factory` / `@KoinViewModel` 构造
|
||||
- `ListenableWorker` 子类、`AppWidgetProvider`
|
||||
- Kotlinx Serialization、Wire
|
||||
- `data.db`、`data.model`、`shared` 命名空间下部分类
|
||||
|
||||
WebView 的 `NativeBridge.postMessage`(`@JavascriptInterface`)包名不在上述 keep 前缀里。打正式包后必须真机验证正方导入;若 JS 调不通,在 ProGuard 中 keep `@JavascriptInterface` 方法。修改 Bridge 或序列化模型后用 `assembleRelease` 再跑:正方导入、JSON 往返、ZIP 恢复。
|
||||
|
||||
## 7. 发布检查清单
|
||||
|
||||
- [ ] versionName / versionCode 已升
|
||||
- [ ] 使用正式签名而非 debug
|
||||
- [ ] `assembleRelease` 三个 ABI 均成功
|
||||
- [ ] 冷启动、导入正方、JSON 往返、ZIP 恢复、提醒、四种小组件
|
||||
- [ ] 无英文界面入口
|
||||
- [ ] 隐私:不采集账号;网络权限仅网页、WebDAV、节假日
|
||||
|
||||
## 8. 许可证
|
||||
|
||||
根目录 `LICENSE` 为 Apache 2.0,版权声明沿用原项目 XingHeYuZhuan。对外分发时保留许可证与 NOTICE 要求。
|
||||
@@ -0,0 +1,189 @@
|
||||
# 星课表架构设计
|
||||
|
||||
## 1. 总体结构
|
||||
|
||||
星课表是 **Android 专用的 Kotlin Multiplatform** 工程:共享模块用 Compose Multiplatform 写 UI 和业务,Android 应用模块承载入口、通知、小组件。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ app(Android Application) │
|
||||
│ MainActivity / MyApplication │
|
||||
│ 上课闹钟 CourseAlarmReceiver │
|
||||
│ 四种 AppWidget Provider + 渲染 │
|
||||
└─────────────────┬───────────────────────┘
|
||||
│ implementation
|
||||
┌─────────────────▼───────────────────────┐
|
||||
│ shared(KMP Android Library) │
|
||||
│ Compose UI · Navigation3 · ViewModel │
|
||||
│ Repository · Room · DataStore · Wire │
|
||||
│ 正方 JS · WebView expect/actual │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
源码包名仍为 `com.xingheyuzhuan.shiguangschedule`(沿用原工程,减少改动面)。
|
||||
安装包 `applicationId` 为 `com.starschedule`。
|
||||
|
||||
## 2. 运行时分层
|
||||
|
||||
从上到下:
|
||||
|
||||
1. **界面** `ui/`:Screen + 少量无状态组件。不直接碰 DAO。
|
||||
2. **ViewModel** `ui/**/*ViewModel.kt`、`AppSettingsViewModel`:组合多个 Repository,暴露 `StateFlow`。
|
||||
3. **Repository** `data/repository/`:课表、转换、备份、样式、设置、小组件。
|
||||
4. **持久化**
|
||||
- Room 主库:课表、课程、周次、节次、课表配置
|
||||
- Room Widget 库:预计算的近 7 天课程
|
||||
- DataStore Preferences:应用设置、WebDAV 配置
|
||||
- DataStore Proto(Wire):课表网格样式
|
||||
5. **平台** `androidMain`:WebView、文件选择器、加密、通知设置卡片、主题动态色。
|
||||
|
||||
依赖注入用 **Koin 注解**:`@Single` / `@Factory` / `@ComponentScan`。`MyApplication` 启动 `ScheduleAppConfig`。
|
||||
|
||||
## 3. 导航
|
||||
|
||||
使用 **Navigation3** 的 `NavBackStack`,目的地是 `@Serializable` 的 `Destination`。
|
||||
|
||||
- 三个 `MainDestination`(今日课表、周课表、我的):切换时清空栈再压入,底部栏无滑动动画。
|
||||
- 其余页面压栈,横向滑入;返回滑出。
|
||||
- `WebView`、`AddEditCourse`、`CourseManagementDetail` 带参数。
|
||||
|
||||
入口在 `App.kt` 的 `ScreenContent`。新增页面需要:定义 Destination、注册 serializer、在 `ScreenContent` 里分支。
|
||||
|
||||
## 4. 数据流
|
||||
|
||||
### 4.1 课表显示
|
||||
|
||||
```
|
||||
AppSettings(currentCourseTableId)
|
||||
│
|
||||
▼
|
||||
CourseTableRepository.getCoursesWithWeeksByTableId
|
||||
TimeSlotRepository / CourseTableConfig
|
||||
│
|
||||
▼
|
||||
WeeklyScheduleViewModel / TodayScheduleViewModel
|
||||
│
|
||||
▼
|
||||
Compose 网格 / 列表
|
||||
```
|
||||
|
||||
周次计算:用课表的 `semesterStartDate` 与 `firstDayOfWeek` 把「今天」对齐到学期第几周。
|
||||
|
||||
### 4.2 正方导入
|
||||
|
||||
```
|
||||
用户打开 WebView → 登录正方 → 课表查询页
|
||||
│
|
||||
执行导入 → 选择目标课表 ID
|
||||
│
|
||||
注入 files/zhengfang.js
|
||||
│
|
||||
JS 抓 DOM → shiguangBridgePromise.saveImportedCourses(json)
|
||||
│
|
||||
Android JavascriptInterface → WebBridgeHandler
|
||||
│
|
||||
CourseConversionRepository.importCoursesFromList(覆盖该表课程)
|
||||
│
|
||||
notifyTaskCompletion → 回到周课表
|
||||
```
|
||||
|
||||
### 4.3 小组件
|
||||
|
||||
`WidgetDataSynchronizer`(`createdAtStart = true`)监听当前课表、课程、节次、设置;把未来 7 天展开成 `WidgetCourse` 写入独立数据库。Android 的 `SyncManager`(同样 `createdAtStart`)订阅 `syncCompletedFlow` 后:
|
||||
|
||||
1. 刷新四种 AppWidget(`updateAllWidgets()`)
|
||||
2. 入队 `CourseNotificationWorker`(重排上课提醒闹钟)
|
||||
3. 入队 `DndSchedulerWorker`(重排勿扰/静音闹钟)
|
||||
|
||||
小组件进程只读 Widget 库,避免在 RemoteViews 里跑完整学期计算。
|
||||
|
||||
另外 `WorkManagerHelper` 在有小组件时调度:
|
||||
|
||||
- `WidgetUiUpdateWorker`:约每 15 分钟刷新 UI(系统可推迟)
|
||||
- `FullDataSyncWorker`:约每天一次调用 `syncNow()`
|
||||
|
||||
### 4.4 上课提醒与上课自动模式
|
||||
|
||||
不是 UI 线程直接 `setAlarm`,而是:
|
||||
|
||||
```
|
||||
主库变化 → WidgetDataSynchronizer 展开近 7 天
|
||||
→ SyncManager
|
||||
→ CourseNotificationWorker / DndSchedulerWorker
|
||||
→ AlarmManager 精确闹钟
|
||||
→ CourseAlarmReceiver
|
||||
```
|
||||
|
||||
闹钟槽位(见各 Worker 常量,改时不要互相覆盖):
|
||||
|
||||
| 范围 | 用途 |
|
||||
|---|---|
|
||||
| `50001`–`50002` 一带 | 勿扰/静音开、关(`DndSchedulerWorker`) |
|
||||
| `50010`–`50110` | 课程提醒(`CourseNotificationWorker`,共 101 个槽) |
|
||||
|
||||
`CourseAlarmReceiver` 处理通知展示、点击关闭、以及勿扰/静音切换。跳过日期来自 DataStore,展开进 Widget 库时带 `isSkipped`。
|
||||
|
||||
## 5. 双数据库
|
||||
|
||||
| 库 | 用途 | 版本 |
|
||||
|---|---|---|
|
||||
| `MainAppDatabase` | 用户课表真相源 | 5(schema 导出在 `shared/schemas`) |
|
||||
| `WidgetDatabase` | 小组件只读快照 | 3(不导出 schema) |
|
||||
|
||||
主库实体之间用外键 `CASCADE`:删课表会删课程、周次、节次、配置。
|
||||
|
||||
应用设置曾存在 Room `app_settings` 表,现已迁到 DataStore;库版本 4→5 用 AutoMigration 删该表。
|
||||
|
||||
`MyApplication` 实现 `Configuration.Provider`,Koin 里调用 `workManagerFactory()`,Worker 用 `@KoinWorker` 注入 Repository。
|
||||
|
||||
## 6. 平台抽象
|
||||
|
||||
| expect | Android actual | 作用 |
|
||||
|---|---|---|
|
||||
| `AppStorage` | `AndroidAppStorage` | filesDir / cacheDir / 数据库路径 |
|
||||
| `createMainDatabase` | Room builder | 主库 |
|
||||
| `PlatformWebView` | `android.webkit.WebView` | 教务页 |
|
||||
| `rememberFileManager` | SAF / 图片选择 | 导入导出、壁纸 |
|
||||
| `SecureCrypto` | AES + 系统密钥 | WebDAV 密码 |
|
||||
| `ShareManager` | FileProvider + Intent | 分享导出文件 |
|
||||
| 通知设置部分 UI | 权限跳转、勿扰、精确闹钟 | 仅 Android 有意义 |
|
||||
| WorkManager / AlarmManager | `SyncManager`、各类 Worker、`CourseAlarmReceiver` | 提醒、勿扰、小组件定期刷新 |
|
||||
|
||||
## 7. 资源与文案
|
||||
|
||||
Compose Multiplatform Resources:
|
||||
|
||||
- 字符串:`shared/src/commonMain/composeResources/values/strings.xml`
|
||||
- 图标:同目录 `drawable/`
|
||||
- 正方脚本:`files/zhengfang.js`
|
||||
|
||||
生成类包名固定为 `shiguangschedule.shared.generated.resources`。
|
||||
|
||||
`app` 模块自己的 `res/values/strings.xml` 只保留小组件、通知、应用名等系统框架会读的条目。
|
||||
|
||||
`androidResources.localeFilters` 限制为 `zh`、`zh-rCN`。
|
||||
|
||||
## 8. 网络
|
||||
|
||||
- **正方**:WebView 加载用户输入的教务 URL,Cookie 留在 WebView。
|
||||
- **WebDAV**:Ktor CIO 客户端,Basic 认证。
|
||||
- **节假日**:Ktor 请求 `https://timor.tech/api/holiday/year`。
|
||||
|
||||
`network_security_config` 允许用户访问校园 HTTP 教务(明文站点仍常见)。
|
||||
|
||||
## 9. 安全注意
|
||||
|
||||
- 无用户账号。课表在本机 SQLite。
|
||||
- WebDAV 密码加密后写入 DataStore,IV 一并保存。
|
||||
- 正方账号只在 WebView 会话中,应用不采集、不上传。
|
||||
- 导入脚本在 WebView 里跑,只通过 Bridge 把课程 JSON 交给 Native。脚本不能直接写数据库。
|
||||
|
||||
## 10. 与原拾光工程的差异(架构层)
|
||||
|
||||
| 原拾光 | 星课表 |
|
||||
|---|---|
|
||||
| androidApp + iosApp + desktopApp | 仅 `app` + `shared` |
|
||||
| Git 拉取 180+ 适配脚本 | 内置一份 `zhengfang.js` |
|
||||
| kgit、aboutlibraries、多 locale | 已移除 |
|
||||
| 学校选择 / 适配器选择 / 更新仓库 | 已移除 |
|
||||
| 系统日历同步 | 已移除 |
|
||||
@@ -0,0 +1,116 @@
|
||||
# 正方教务导入说明
|
||||
|
||||
星课表只内置一份正方适配脚本,不连接外部学校仓库。
|
||||
|
||||
脚本路径:
|
||||
|
||||
```
|
||||
shared/src/commonMain/composeResources/files/zhengfang.js
|
||||
```
|
||||
|
||||
运行时通过 Compose Resources 读取:
|
||||
|
||||
```kotlin
|
||||
Res.readBytes("files/zhengfang.js").decodeToString()
|
||||
```
|
||||
|
||||
## 1. 用户路径
|
||||
|
||||
1. 我的 → 课表导入/导出 → 正方教务导入(`Destination.WebView()`)。
|
||||
2. 地址栏输入正方登录 URL(或从空白页开始输入)。
|
||||
3. 登录后进入 **学生课表查询**,选择学年学期并查询。
|
||||
4. 点「执行导入」,选择目标课表。
|
||||
5. 脚本确认对话框 → 抓取 → `saveImportedCourses` → 覆盖写入 → `notifyTaskCompletion` 回到周课表。
|
||||
|
||||
## 2. 页面要求
|
||||
|
||||
脚本会:
|
||||
|
||||
1. `fetch` 当前页 HTML,内容需包含「课表查询」。
|
||||
2. 读取 `#shcPDF` 的 `data-type`:`list` 或网格。
|
||||
3. 列表找 `#kblist_table`,网格找 `#kbgrid_table_0`。
|
||||
4. 使用 **jQuery**(`window.jQuery`)。没有 jQuery 会直接失败。
|
||||
|
||||
网格解析 `parserTbale()`(函数名沿用历史拼写):遍历 `#kbgrid_table_0 td.td_wrap` 下的 `.timetable_con`。
|
||||
列表解析 `parserList()`:按星期 `tbody` 扫行。
|
||||
|
||||
能解析的字段:课程名、星期、节次区间、周次(含 `1-16`、`1-16(单)`、逗号分隔)、教师、地点(取空白分隔的最后一段)。课程名会去掉 `●★○`。
|
||||
|
||||
周次规则:
|
||||
|
||||
- `n-m` 闭区间
|
||||
- `(单)` 只保留奇数周,`(双)` 只保留偶数周
|
||||
- 多段用逗号
|
||||
|
||||
## 3. JS Bridge
|
||||
|
||||
页面注入后可用:
|
||||
|
||||
| 对象 | 方法 | 行为 |
|
||||
|---|---|---|
|
||||
| `shiguangBridge` | `showToast(message)` | 短提示 |
|
||||
| `shiguangBridge` | `notifyTaskCompletion()` | Native 结束导入并返回课表 |
|
||||
| `shiguangBridgePromise` | `showAlert(title, content, confirm)` | 确认框,Promise\<boolean\> |
|
||||
| `shiguangBridgePromise` | `showPrompt(...)` | 输入框,可带 JS 校验函数名 |
|
||||
| `shiguangBridgePromise` | `showSingleSelection(title, items, defaultIndex)` | 单选 |
|
||||
| `shiguangBridgePromise` | `saveImportedCourses(coursesJsonString)` | 保存课程数组 |
|
||||
| `shiguangBridgePromise` | `saveCourseConfig(configJsonString)` | 保存学期配置(正方脚本目前未调用) |
|
||||
| `shiguangBridgePromise` | `savePresetTimeSlots(timeSlotsJsonString)` | 保存节次(正方脚本目前未调用) |
|
||||
|
||||
兼容别名:`AndroidBridge`、`AndroidBridgePromise`。
|
||||
|
||||
Native 回调:
|
||||
|
||||
```javascript
|
||||
window._shiguangNativeCallback(callbackId, isSuccess, result)
|
||||
```
|
||||
|
||||
消息 JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "saveImportedCourses",
|
||||
"callbackId": "cb_1_...",
|
||||
"payload": "{\"coursesJsonString\":\"[...]\"}"
|
||||
}
|
||||
```
|
||||
|
||||
`payload` 本身是再包一层的 JSON 字符串。Android 用 `JavascriptInterface` 的 `postMessage` 收到后交给 `WebBridgeHandler.onMessageReceived`。
|
||||
|
||||
## 4. 写入规则
|
||||
|
||||
`saveImportedCourses` 解析为 `List<ImportCourseJsonModel>`,调用:
|
||||
|
||||
```kotlin
|
||||
courseConversionRepository.importCoursesFromList(tableId, list)
|
||||
```
|
||||
|
||||
- 必须已经选过目标课表,否则失败。
|
||||
- **删除该课表全部旧课程** 再插入。
|
||||
- 每条生成新 UUID。
|
||||
- 按课程名分配颜色池下标。
|
||||
- 正方脚本 **不导入节次时刻和开学日期**。导入后请在「自定义时间段」「设置开学日期」里按学校作息补全,否则小组件和提醒的钟点可能不准。
|
||||
|
||||
## 5. 改脚本时注意
|
||||
|
||||
- 正方不同学校皮肤可能改 class 名。改选择器前用真机打开该校课表查询页看 DOM。
|
||||
- 脚本末尾直接 `runImportFlow()`,每次 `executeScript` 都会跑完整流程。
|
||||
- 不要在脚本里写死学校 URL;URL 由用户输入。
|
||||
- 解析结果必须是 Bridge 能 decode 的数组:至少含 `name, day, weeks, teacher, position, startSection, endSection`。
|
||||
- 保持依赖 jQuery 的前提,或同时改成原生 DOM——当前实现明确检查 jQuery。
|
||||
|
||||
## 6. Native 侧相关文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|---|---|
|
||||
| `ui/schoolselection/web/WebViewScreen.kt` | 地址栏、导入按钮、读 js、选课表 |
|
||||
| `WebBridgeProtocol.kt` | 注入脚本、消息数据类 |
|
||||
| `WebBridgeHandler.kt` | action 路由、写库 |
|
||||
| `WebDialogHost.kt` | Alert / Prompt / 单选 Compose 弹窗 |
|
||||
| `WebView.android.kt` | WebView 创建、JS 接口、桌面 UA |
|
||||
| `AndroidWebConstants.kt` | 桌面 UA 等 |
|
||||
| `WebViewRequestInterceptor.kt` | 请求拦截(如有) |
|
||||
|
||||
`isDesktopMode` 切换 UA,部分正方在「电脑模式」才能看到完整课表。
|
||||
|
||||
Release 混淆注意:`NativeBridge.postMessage` 必须能被 JS 调到,见 [构建与发布 · ProGuard](构建与发布.md)。
|
||||
@@ -0,0 +1,150 @@
|
||||
# 星课表用户使用说明
|
||||
|
||||
星课表是给高校师生用的 Android 课程表。可以看今天和本周的课、从正方教务导入、改课、上课提醒。界面只有简体中文。
|
||||
|
||||
最低系统:Android 8.0。
|
||||
|
||||
## 1. 主界面
|
||||
|
||||
底部三个入口:
|
||||
|
||||
- **今日课表**:当天课程列表
|
||||
- **课表**:周网格
|
||||
- **我的**:学期设置、导入导出、提醒、样式等
|
||||
|
||||
启动时进入哪一页,可在「我的 → 更多 → 启动页面设置」里改。
|
||||
|
||||
## 2. 第一次使用
|
||||
|
||||
1. 打开应用后进入「我的」。
|
||||
2. 点「设置开学日期」,选本学期第一周对应的周一(以教务为准)。
|
||||
3. 按学校情况改「本学期总周数」(默认 20)。
|
||||
4. 需要周末课则打开「是否显示周末」。
|
||||
5. 导入或手动添加课程。
|
||||
|
||||
未设开学日期时,今日课表会提示设置,周课表无法按真实周次对齐。
|
||||
|
||||
## 3. 看课
|
||||
|
||||
### 今日课表
|
||||
|
||||
按时间列出当天课程。假期中会显示距开学还有几天。点课程可看地点、教师、备注。
|
||||
|
||||
### 周课表
|
||||
|
||||
- 左右滑或点顶部周次,切换周。
|
||||
- 点顶部课表名,切换当前使用的课表。
|
||||
- 点课程块看详情,可编辑。
|
||||
- 「显示非本周课程」打开后,本周不上的课会以较淡样式出现在格子里。
|
||||
- 可把课程挂起,滑到其他周或点空白格放下(仅在学期周次范围内)。
|
||||
|
||||
## 4. 管理课表和课程
|
||||
|
||||
### 多份课表
|
||||
|
||||
「我的 → 管理课表」:
|
||||
|
||||
- 添加、改名、删除
|
||||
- 点选即切换为当前课表
|
||||
- 不能删除最后一份
|
||||
|
||||
每份课表的课程、节次、开学日期互相独立。
|
||||
|
||||
### 添加 / 改课
|
||||
|
||||
周课表点空白格,或「课程管理」里添加:
|
||||
|
||||
- 名称必填
|
||||
- 时间可以是「第几节到第几节」,也可以是自定义起止时刻
|
||||
- 周次可点单周 / 双周,或逐周勾选
|
||||
|
||||
### 课程管理
|
||||
|
||||
「我的 → 课程管理」按名称分组。点进某一门可看所有上课实例,可批量删除。
|
||||
|
||||
## 5. 正方教务导入
|
||||
|
||||
路径:**我的 → 课表导入/导出 → 正方教务导入**
|
||||
|
||||
1. 在打开的网页里输入学校正方地址并登录。
|
||||
2. 进入 **学生课表查询**,选学年学期,点查询,等到课表显示出来。
|
||||
3. 点底部「执行导入」,选要写入的课表。
|
||||
4. 按提示确认。导入会 **覆盖** 该课表已有课程。
|
||||
|
||||
注意:
|
||||
|
||||
- 只支持正方系统常见的列表课表、网格课表。
|
||||
- 页面需要有 jQuery(正方一般自带)。
|
||||
- 必须已经点过查询且页面上能看到课。
|
||||
- 网页右上角可刷新、切换手机/电脑模式。电脑模式有时能打开手机模式打不开的页面。
|
||||
|
||||
导入失败时,确认:已登录、在课表查询页、已查询、学年学期正确。更细的排障见 [常见问题](常见问题.md)。
|
||||
|
||||
导入 **不会** 改节次钟点和开学日期。导入后请到「自定义时间段」「设置开学日期」按学校作息补全。
|
||||
|
||||
## 6. 文件导入导出
|
||||
|
||||
同一页「课表导入/导出」:
|
||||
|
||||
| 功能 | 说明 |
|
||||
|---|---|
|
||||
| 课程文件导入 | 选择 JSON,写入指定课表(覆盖该表课程) |
|
||||
| 课程文件导出 | 导出 JSON,含课程、节次、学期配置 |
|
||||
| 日历文件导出 | 导出 ICS,可设提醒分钟数,可用系统日历或其他日历软件打开 |
|
||||
|
||||
导出后可选择分享文件。
|
||||
|
||||
## 7. 备份与恢复
|
||||
|
||||
路径:课表导入/导出页的「备份与恢复」,或从导入导出进入。
|
||||
|
||||
- **本地 ZIP**:整包备份课表和样式,换机或重装前先导出。
|
||||
- **WebDAV**:填服务器地址、账号、密码、云端目录。密码只存在本机加密存储里。默认目录名是 `ShiguangSchedule`(历史值),备份文件在该目录下的 `Backup` 中。
|
||||
|
||||
恢复会覆盖当前应用内数据,操作前确认备份是自己需要的那份。
|
||||
|
||||
## 8. 上课提醒
|
||||
|
||||
「我的 → 课程提醒设置」:
|
||||
|
||||
1. 打开「课程提醒」,按系统提示给通知权限。
|
||||
2. Android 12 及以上请打开「精确闹钟权限」。
|
||||
3. 国产系统建议允许自启动、忽略电池优化,否则定时提醒可能被杀。
|
||||
4. 设置提前提醒分钟数。
|
||||
|
||||
上课自动模式:
|
||||
|
||||
- 关闭 / 勿扰 / 静音
|
||||
- 必须先开课程提醒
|
||||
- 勿扰需要系统勿扰权限
|
||||
|
||||
跳过日期:可尝试「更新节假日信息」(依赖外部接口,年末才较全),也可清空或查看已跳过日期。节假日当天默认不提醒。
|
||||
|
||||
若手环收不到通知,可打开「兼容穿戴设备同步通知」。
|
||||
|
||||
## 9. 样式与主题
|
||||
|
||||
- **个性化配置**:改格子大小、圆角、颜色池、是否显示地点教师、课表壁纸、节次模式或 24 小时时间轴。长按壁纸可清除。
|
||||
- **更多 → 主题设置**:浅色 / 深色 / 跟随系统;Android 12+ 可开动态取色;可自定义主色。
|
||||
|
||||
## 10. 调课和批量删除
|
||||
|
||||
「我的 → 快捷操作」:
|
||||
|
||||
- **调课**:选课表、被调日期、目标日期,再选合并 / 覆盖 / 交换。
|
||||
- **快速删除课程**:按周次和星期,或按具体日期,清掉对应上课记录。
|
||||
|
||||
## 11. 桌面小组件
|
||||
|
||||
在系统桌面长按空白处添加小组件,搜索「星课表」:
|
||||
|
||||
- 超小课程2x1
|
||||
- 紧凑课程2x2
|
||||
- 近日课程4x2
|
||||
- 垂直列表课表4xN
|
||||
|
||||
小组件跟随当前课表。改课或改开学日期后会自动刷新;若未刷新,可移走再添加,或打开一次应用。
|
||||
|
||||
## 12. 自定义上课节次
|
||||
|
||||
「我的 → 自定义时间段」:改第 1 节、第 2 节……的起止时间。学校作息与默认 45 分钟/10 分钟课间不同时,应先改这里再导入或排课,否则节次对得上、钟点对不上。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 隐私与数据
|
||||
|
||||
星课表没有账号体系,不提供云端用户服务。课表默认只存在本机。
|
||||
|
||||
## 1. 本机存储
|
||||
|
||||
| 位置 | 内容 |
|
||||
|---|---|
|
||||
| Room 主库 | 课表、课程、周次、节次、每表学期配置 |
|
||||
| Room Widget 库 | 近 7 天已展开课程,供小组件和提醒使用 |
|
||||
| DataStore `app_settings.preferences_pb` | 当前课表、提醒、主题、跳过日期等 |
|
||||
| DataStore `api_config.preferences_pb` | WebDAV 地址、账号、加密后的密码 |
|
||||
| DataStore `schedule_style_settings.pb` | 课表网格样式 |
|
||||
| 应用私有目录 | 课表背景图 |
|
||||
| 缓存 `share_temp/` | 导出分享用临时文件,启动时删除 |
|
||||
|
||||
卸载应用会删除上述数据(除非系统备份另行保存)。`AndroidManifest` 中 `allowBackup` 为 true,系统备份规则见 `app/src/main/res/xml/backup_rules.xml` 与 `data_extraction_rules.xml`。
|
||||
|
||||
## 2. 网络去向
|
||||
|
||||
应用主动访问的网络只有三类:
|
||||
|
||||
1. **正方教务**:用户在 WebView 中输入的学校地址。Cookie 留在 WebView 会话,应用不采集、不上传教务账号。
|
||||
2. **WebDAV**:用户自己配置的服务器。上传/下载备份包(`meta.json`、`course.cbor`、`style.cbor`)。
|
||||
3. **节假日**:`https://timor.tech/api/holiday/year`,用于更新跳过日期。第三方接口,不保证可用。
|
||||
|
||||
`network_security_config` 允许明文 HTTP,因为部分校园教务仍是 HTTP。
|
||||
|
||||
## 3. 权限
|
||||
|
||||
| 权限 | 用途 | 不用于 |
|
||||
|---|---|---|
|
||||
| INTERNET / ACCESS_NETWORK_STATE | 上述三类网络 | 广告、统计 SDK(工程内无此类依赖) |
|
||||
| SCHEDULE_EXACT_ALARM | 上课提醒与勿扰开关闹钟 | |
|
||||
| POST_NOTIFICATIONS | 上课通知 | |
|
||||
| ACCESS_NOTIFICATION_POLICY | 上课勿扰 | |
|
||||
| RECEIVE_BOOT_COMPLETED | 重启后由同步链路重新调度闹钟 | |
|
||||
| POST_PROMOTED_NOTIFICATIONS | 实时通知相关 | |
|
||||
|
||||
不申请读写系统日历、不申请精确位置、不申请通讯录。ICS 导出是用户主动保存/分享文件,由用户自行导入其他日历软件。
|
||||
|
||||
## 4. 密码与导入脚本
|
||||
|
||||
- WebDAV 密码经 `SecureCrypto`(Android 系统密钥 + AES)加密后写入 DataStore,IV 一并保存。
|
||||
- 正方脚本只通过 JS Bridge 提交课程 JSON。脚本不能直接写数据库。Bridge 对象名为 `shiguangBridge` / `shiguangBridgePromise`。
|
||||
|
||||
## 5. 对外分发时建议说明
|
||||
|
||||
- 数据默认仅本机;WebDAV 与教务网页由用户自行决定是否使用。
|
||||
- 节假日接口为第三方,可能失败或数据不全。
|
||||
- 无应用内检查更新、无远程配置下发。
|
||||
@@ -0,0 +1,197 @@
|
||||
# 星课表需求文档
|
||||
|
||||
**产品名称:** 星课表
|
||||
**工程名称:** starschedule
|
||||
**平台:** Android 8.0(API 26)及以上
|
||||
**界面语言:** 简体中文(不提供多语言切换)
|
||||
**当前版本:** 1.0.0
|
||||
|
||||
配套文档:[用户使用说明](用户使用说明.md)、[架构设计](架构设计.md)、[开发文档](开发文档.md)。
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
高校师生需要一份能长期使用的课表:看今天上什么、看本周怎么排、能从学校教务把课导进来、能改课、能提醒。
|
||||
|
||||
星课表由拾光课程表精简而来,目标是:
|
||||
|
||||
1. 把课表相关的核心能力做完整、做稳定。
|
||||
2. 教务导入只适配 **正方教务**,不再维护多学校适配仓库。
|
||||
3. 去掉 iOS / 桌面、多语言、开源许可证页、贡献者页、系统日历同步等与核心课表无关的能力。
|
||||
4. 仅提供中文界面,降低维护成本。
|
||||
|
||||
## 2. 用户与使用场景
|
||||
|
||||
| 角色 | 典型场景 |
|
||||
|---|---|
|
||||
| 本科 / 专科学生 | 从正方教务导入本学期课表,日常看今日课表和周课表 |
|
||||
| 研究生 / 教师 | 手动维护多份课表,或导入后微调 |
|
||||
| 需要提醒的用户 | 上课前提醒,上课时自动勿扰或静音 |
|
||||
| 换机用户 | 用 JSON / ZIP / WebDAV 备份恢复 |
|
||||
|
||||
不作为目标的能力:其他教务系统(超星、强智、青果等)一键导入、多语言、iOS / 桌面客户端。
|
||||
|
||||
## 3. 范围
|
||||
|
||||
### 3.1 包含
|
||||
|
||||
- 今日课表、周课表
|
||||
- 多课表、课程增删改、按名称管理课程
|
||||
- 自定义节次时间、学期起止、周末显示
|
||||
- 课表网格样式与应用主题
|
||||
- 上课提醒、上课自动勿扰 / 静音、节假日跳过
|
||||
- 正方教务导入
|
||||
- JSON 课程文件导入导出、ICS 导出
|
||||
- 本地 ZIP 备份与 WebDAV 云备份
|
||||
- 调课、按周次 / 日期批量删除
|
||||
- Android 桌面小组件(4 种规格)
|
||||
|
||||
### 3.2 不包含
|
||||
|
||||
- 非正方教务适配、学校列表、远程适配仓库
|
||||
- 系统日历写入同步
|
||||
- iOS、桌面端
|
||||
- 英文 / 繁体界面与语言切换
|
||||
- 应用内检查更新、开源许可证页、贡献者列表、开发者模式 UI
|
||||
|
||||
## 4. 功能需求
|
||||
|
||||
### 4.1 课表浏览
|
||||
|
||||
**FR-01 今日课表**
|
||||
按当天日期展示课程。未设置开学日期时提示设置;假期中显示距开学天数;学期结束后显示已过天数。可查看地点、教师、备注。
|
||||
|
||||
**FR-02 周课表**
|
||||
按周展示网格。支持左右滑切换周次、选择周次、切换当前课表。可显示非本周课程(半透明显示)。点击课程块查看详情,可进入编辑。支持把课程“挂起”后放到另一格。
|
||||
|
||||
**FR-03 启动页**
|
||||
用户可选择启动进入周课表或今日课表。底部三个一级入口:今日课表、课表、我的。
|
||||
|
||||
### 4.2 课表与课程管理
|
||||
|
||||
**FR-04 多课表**
|
||||
可添加、重命名、删除、切换课表。至少保留一份课表,不能删光。每份课表有独立的课程、节次和学期配置。
|
||||
|
||||
**FR-05 添加 / 编辑课程**
|
||||
必填课程名称。可选教师、地点、备注。上课时间支持:
|
||||
|
||||
- 节次模式:星期 + 开始/结束节次 + 周次
|
||||
- 自定义时间:星期 + `HH:mm` 起止 + 周次
|
||||
|
||||
周次支持单周、双周、连续区间。同名课程尽量使用同一颜色。备注长度限制 300 字。
|
||||
|
||||
**FR-06 课程管理**
|
||||
按课程名称列出当前课表全部课程,可进入实例列表批量删除或新增同名课程。
|
||||
|
||||
### 4.3 学期与作息
|
||||
|
||||
**FR-07 学期配置(按课表)**
|
||||
|
||||
- 开学日期:学期第一周所参考的周一(或用户设定的每周起始日)
|
||||
- 总周数,默认 20
|
||||
- 当前周数可手动改,会反推开学日期
|
||||
- 每周起始日:周一或周日
|
||||
- 是否显示周末
|
||||
|
||||
**FR-08 节次时间**
|
||||
可增删改每节课的开始/结束时间及别名。可设置默认课时长与课间休息,用于新增节次。节次编号从 1 连续递增,时间不得重叠。新建课表带 13 节默认作息(08:00 起,详见数据模型)。正方导入不覆盖节次表。
|
||||
|
||||
### 4.4 导入导出
|
||||
|
||||
**FR-09 正方教务导入**
|
||||
用户在内置 WebView 中打开正方登录页,进入「学生课表查询」并查出课表后,选择目标课表,执行内置脚本抓取并写入。覆盖目标课表已有课程。只适配正方 HTML 课表(列表视图与网格视图),依赖页面 jQuery。
|
||||
|
||||
**FR-10 JSON 导入导出**
|
||||
导入 JSON 课程文件到指定课表(覆盖该表课程,并可带时间段与学期配置)。导出当前或指定课表为 JSON,文件名形如 `starschedule_<时间戳>.json`。
|
||||
|
||||
**FR-11 ICS 导出**
|
||||
按学期实例展开课程,生成 `.ics`,可设置提前提醒分钟数。
|
||||
|
||||
### 4.5 备份
|
||||
|
||||
**FR-12 本地 ZIP**
|
||||
将全部课表与样式打包为 ZIP,可恢复覆盖本地数据。
|
||||
|
||||
**FR-13 WebDAV**
|
||||
可配置服务器地址、账号、密码、远端目录。密码加密存储。备份上传到配置目录下的 Backup 文件夹,也可从云端恢复。
|
||||
|
||||
备份协议版本过新时拒绝恢复,提示升级应用。
|
||||
|
||||
### 4.6 提醒与自动化
|
||||
|
||||
**FR-14 上课提醒**
|
||||
可开关。提前提醒分钟数由用户输入(默认 15)。使用精确闹钟,数据来自近 7 天已展开的 Widget 库。Android 13+ 需要通知权限。ICS 导出的提醒可选 1–60 分钟。
|
||||
|
||||
**FR-15 上课自动模式**
|
||||
依赖提醒开启。可选关闭、勿扰、静音。勿扰需要系统「勿扰模式」权限。
|
||||
|
||||
**FR-16 跳过日期**
|
||||
可从节假日接口更新跳过日期,可查看、清空。被跳过日期不提醒、小组件标记跳过。接口来源为 `https://timor.tech/api/holiday/year`,不保证稳定。
|
||||
|
||||
**FR-17 穿戴设备兼容**
|
||||
可关闭实时通知属性,以便部分手环同步软件抓取通知。
|
||||
|
||||
### 4.7 个性化
|
||||
|
||||
**FR-18 课表样式**
|
||||
格子高度、侧栏宽度、表头高度、圆角、内外边距、透明度、文字缩放、对齐、边框(无/实线/虚线)、隐藏地点/教师/节次时间/日期/网格线、课程块开始时间、地点前 `@`、页面文字色、课程文字色、浅色/深色颜色池、课表背景图、节次模式或 24 小时时间轴模式。可恢复默认。
|
||||
|
||||
**FR-19 应用主题**
|
||||
跟随系统 / 浅色 / 深色。Android 12+ 可开动态取色。可自定义浅色、深色主色种子。
|
||||
|
||||
### 4.8 快捷操作
|
||||
|
||||
**FR-20 调课**
|
||||
将某日课程合并到另一日、覆盖另一日、或与另一日交换。两日不能相同。需已设开学日期。
|
||||
|
||||
**FR-21 快速删除**
|
||||
按周次+星期,或按具体日期,批量从课表中移除课程实例(不删课程名称本身的基础信息以外的实例记录)。
|
||||
|
||||
### 4.9 桌面小组件
|
||||
|
||||
**FR-22** 四种原生小组件:
|
||||
|
||||
| 名称 | 规格 | 内容 |
|
||||
|---|---|---|
|
||||
| 超小课程2x1 | 2x1 | 当前/下一节课 |
|
||||
| 紧凑课程2x2 | 2x2 | 今日剩余或明日预告 |
|
||||
| 近日课程4x2 | 4x2 | 今天 + 明天 |
|
||||
| 垂直列表课表4xN | 4xN | 列表展示今日或明日 |
|
||||
|
||||
小组件数据来自独立 Widget 库,由主库同步未来 7 天实例,不在小组件进程里算完整课表。
|
||||
|
||||
## 5. 非功能需求
|
||||
|
||||
| 编号 | 要求 |
|
||||
|---|---|
|
||||
| NFR-01 | 最低 Android 8.0;编译 SDK / 目标 SDK 37 |
|
||||
| NFR-02 | 界面仅简体中文,资源 locale 限制为 `zh` / `zh-rCN` |
|
||||
| NFR-03 | 课表、设置读写在本地完成;正方导入与 WebDAV、节假日更新需要网络 |
|
||||
| NFR-04 | WebDAV 密码使用平台加密存储,不以明文写入 DataStore |
|
||||
| NFR-05 | 导入正方时覆盖所选课表课程,需用户先选目标课表 |
|
||||
| NFR-06 | Release 开启 minify 与 shrinkResources |
|
||||
| NFR-07 | 按 ABI 分包:`armeabi-v7a`、`arm64-v8a`、`x86_64` |
|
||||
| NFR-08 | 不提供账号体系,数据全在本机(及用户配置的 WebDAV) |
|
||||
|
||||
## 6. 权限
|
||||
|
||||
| 权限 | 用途 |
|
||||
|---|---|
|
||||
| INTERNET / ACCESS_NETWORK_STATE | 正方网页、WebDAV、节假日接口 |
|
||||
| SCHEDULE_EXACT_ALARM | 上课提醒 |
|
||||
| POST_NOTIFICATIONS | 通知 |
|
||||
| ACCESS_NOTIFICATION_POLICY | 上课勿扰 |
|
||||
| RECEIVE_BOOT_COMPLETED | 重启后恢复提醒调度 |
|
||||
| POST_PROMOTED_NOTIFICATIONS | 实时通知相关 |
|
||||
|
||||
不申请读写系统日历。权限与数据去向见 [隐私与数据](隐私与数据.md)。
|
||||
|
||||
## 7. 验收要点
|
||||
|
||||
1. 新安装可创建课表、添加课程,今日课表与周课表显示正确。
|
||||
2. 设置开学日期后,当前周数与日期对齐正确;改当前周会改开学日期。
|
||||
3. 正方课表查询页(列表或网格)可导入课程到指定课表。
|
||||
4. JSON 导出后再导入,课程、周次、时间段、学期配置可恢复。
|
||||
5. 本地 ZIP 备份恢复后,多课表与样式仍在。
|
||||
6. 开启提醒后,在提前提醒时间能收到通知(需授予精确闹钟与通知权限)。
|
||||
7. 应用内无语言切换入口,无学校列表、无适配仓库更新入口。
|
||||
8. 界面文案为简体中文。
|
||||
@@ -0,0 +1,68 @@
|
||||
# 页面与导航
|
||||
|
||||
导航使用 Navigation3 的 `NavBackStack`。目的地定义在 `Navigation.kt` 的 `Destination`,分发在 `App.kt` 的 `ScreenContent`。所有 Destination 必须在 `navSerializersModule` 注册,否则进程被杀后无法还原返回栈。
|
||||
|
||||
三个 `MainDestination`(今日课表、周课表、我的)切换时会 `backStack.clear()` 再压入,底部栏无横向滑动动画。其余页面压栈,横向滑入/滑出。
|
||||
|
||||
## 1. 目的地一览
|
||||
|
||||
| Destination | 类型 | 界面 | 用户入口 |
|
||||
|---|---|---|---|
|
||||
| `TodaySchedule` | 主 Tab | `TodayScheduleScreen` | 底部「今日课表」;启动页可设为它 |
|
||||
| `CourseSchedule` | 主 Tab | `WeeklyScheduleScreen` | 底部「课表」;默认启动页 |
|
||||
| `Settings` | 主 Tab | `SettingsScreen` | 底部「我的」 |
|
||||
| `TimeSlotSettings` | 子页 | `TimeSlotManagementScreen` | 我的 → 自定义时间段 |
|
||||
| `ManageCourseTables` | 子页 | `ManageCourseTablesScreen` | 我的 → 管理课表 |
|
||||
| `CourseTableConversion` | 子页 | `CourseTableConversionScreen` | 我的 → 课表导入/导出 |
|
||||
| `NotificationSettings` | 子页 | `NotificationSettingsScreen` | 我的 → 课程提醒设置 |
|
||||
| `MoreOptions` | 子页 | `MoreOptionsScreen` | 我的 → 更多 |
|
||||
| `QuickActions` | 子页 | `QuickActionsScreen` | 我的 → 快捷操作 |
|
||||
| `TweakSchedule` | 子页 | `TweakScheduleScreen` | 快捷操作 → 调课 |
|
||||
| `QuickDelete` | 子页 | `QuickDeleteScreen` | 快捷操作 → 快速删除课程 |
|
||||
| `CourseManagementList` | 子页 | `CourseNameListScreen` | 我的 → 课程管理 |
|
||||
| `CourseManagementDetail(courseName)` | 子页 | `CourseInstanceListScreen` | 课程管理 → 点某一门 |
|
||||
| `StyleSettings` | 子页 | `StyleSettingsScreen` | 我的 → 个性化配置 |
|
||||
| `ThemeSettings` | 子页 | `ThemeSettingsScreen` | 更多 → 主题设置 |
|
||||
| `BackupAndRestore` | 子页 | `BackupScreen` | 课表导入/导出 → 备份与恢复 |
|
||||
| `WebView(initialUrl)` | 子页 | `WebViewScreen` | 课表导入/导出 → 正方教务导入;默认 `about:blank` |
|
||||
| `AddEditCourse(courseId)` | 子页 | `AddEditCourseScreen` | 周课表点空白格/课程;课程管理添加。`courseId == null` 为新建 |
|
||||
|
||||
## 2. 「我的」页结构
|
||||
|
||||
**常规设置**
|
||||
|
||||
- 显示非本周课程(开关,写入全局 DataStore)
|
||||
- 是否显示周末(写入当前课表 `CourseTableConfig`)
|
||||
- 设置开学日期
|
||||
- 本学期总周数(默认 20)
|
||||
- 当前周数(手动改会反推开学日期;可选「假期中」)
|
||||
- 每周起始日(周一或周日)
|
||||
- 快捷操作
|
||||
|
||||
**高级功能**
|
||||
|
||||
- 课表导入/导出
|
||||
- 课程提醒设置
|
||||
- 管理课表
|
||||
- 课程管理
|
||||
- 自定义时间段
|
||||
- 个性化配置
|
||||
- 更多(关于、启动页面、主题)
|
||||
|
||||
## 3. 导入导出页结构
|
||||
|
||||
- 正方教务导入 → `Destination.WebView()`
|
||||
- 课程文件导入(JSON,覆盖指定课表)
|
||||
- 课程文件导出(`starschedule_<时间戳>.json`)
|
||||
- 日历文件导出(`starschedule_<时间戳>.ics`,可选 1–60 分钟提醒)
|
||||
- 备份与恢复 → `BackupAndRestore`
|
||||
|
||||
## 4. 新增页面步骤
|
||||
|
||||
1. 在 `Destination` 增加 `@Serializable` 类型(带参数用 `data class`)。
|
||||
2. 在 `navSerializersModule` 的 `polymorphic` 里 `subclass(...)`。
|
||||
3. 在 `App.kt` 的 `ScreenContent` 增加 `when` 分支。
|
||||
4. 从已有 Screen 用 `onNavigate(Destination.Xxx)` 跳转。
|
||||
5. 用户可见标题、说明写进 `composeResources/values/strings.xml`。
|
||||
|
||||
主 Tab 必须实现 `MainDestination`,并在 `AdaptiveNavigationScaffold` 的 Tab 列表里出现,否则底部栏对不上。
|
||||
Reference in New Issue
Block a user