# 星课表数据模型 ## 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 | 学校作息不同时,应在「自定义时间段」改这些时刻。正方导入不会覆盖这张表。