7.5 KiB
星课表数据模型
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:
{
"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:
backupTimestampappVersionCode(此处实际承载 schema 版本)currentCourseTableIdallTables: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 |
学校作息不同时,应在「自定义时间段」改这些时刻。正方导入不会覆盖这张表。