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