Files
2026-09-20 13:33:09 +08:00

7.5 KiB
Raw Permalink Blame History

星课表数据模型

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:

  • 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

学校作息不同时,应在「自定义时间段」改这些时刻。正方导入不会覆盖这张表。