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

225 lines
7.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 星课表数据模型
## 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 |
学校作息不同时,应在「自定义时间段」改这些时刻。正方导入不会覆盖这张表。