LoveChengke
66be3a63b1
拆分能力、分配范围和业务关系，固定管理员能力并收紧组织级写入口。 补齐内容、课表、设备会话和实时通道授权，兼容旧库分配及历史快照。 重写权限分配预览，按实际可操作范围展示维护入口，合并学生入口并独立学年升级页。 增加授权攻击矩阵及静态门禁，更新隔离回归与开发契约。 验证：授权矩阵 23 段通过，Node 24 下 Web 63/63，类型检查、lint 与文档严格构建通过。
96 lines
7.5 KiB
Markdown
96 lines
7.5 KiB
Markdown
---
|
||
title: 数据模型
|
||
description: 现行模型职责、迁移与快照边界。
|
||
---
|
||
|
||
# 数据模型
|
||
|
||
模型定义以 `packages/server/prisma/schema.prisma` 为准，迁移以 `prisma/migrations/` 为准。
|
||
仅维护一份 schema，SQLite/MySQL 切换改 provider；不使用 Prisma enum 和 `@db.*`。
|
||
|
||
## 模型职责
|
||
|
||
| 模型 | 职责 |
|
||
| ---------------------- | --------------------------------------------------- |
|
||
| `User` | 教师与管理员账号；学生不在此表，班级凭据在 Class |
|
||
| `Student` | 学生名单、学号、在读/转出/毕业状态，无密码和角色 |
|
||
| `StudentClassTransfer` | 生命周期历史，kind/batchId/学年/班级年级及学校快照 |
|
||
| `ArchivedYear` | 毕业届别与统计快照 |
|
||
| `TermWeek` | 逐周日期区间，classId 空串为全校默认 |
|
||
| `Class` | 班级、班级码/密码、班主任、周数与成绩查询开关 |
|
||
| `Course` | 班级+科目+教师任课关系，含简称和室外标记 |
|
||
| `Schedule` | 旧课表迁移审计来源，现行接口不再以它为业务真值 |
|
||
| `Homework` | 作业与本地 assignDate；dueAt 为遗留列 |
|
||
| `HomeworkStatus` | 按 studentId 记录作业完成状态 |
|
||
| `Notification` | 通知/叫人记录、优先级与本地 assignDate |
|
||
| `NotificationRead` | 按 studentId 记录已读 |
|
||
| `TimeLayout` | 共享或班级自有时间表；旧 items JSON 保留迁移审计 |
|
||
| `Grade` | studentId、课程、考试、分数和等级 |
|
||
| `PermissionAudit` | 权限与人工升级审计，操作人和前后 JSON，不建账号外键 |
|
||
| `PermissionGroup` | 岗位模板与建议 scope/scopeValue |
|
||
| `PermissionGroupItem` | 组内权限键 |
|
||
| `UserPermissionGroup` | 账号与模板的分配及实际 scope/scopeValue |
|
||
| `AppSetting` | 周次、升级、AI 和系统设置 |
|
||
| `ClientDevice` | deviceKey、心跳、更新目标与状态 |
|
||
| `ClientCommand` | 白名单远控、有效期与执行回执 |
|
||
| `ClientRelease` | 服务端缓存安装包、SHA256 与大小 |
|
||
| `AiAudit` | 助手解析审计，不保存 API Key |
|
||
| `Exam` | 考试名称与是否计入总分 |
|
||
| `TimeLayoutItem` | 有序时间点及类型，被课程显式引用 |
|
||
| `ClassPlanGroup` | 班级课表群组、全局/默认标记 |
|
||
| `ClassPlan` | 日课表、时间表、轮换、启用与临时层规则 |
|
||
| `ClassPlanEntry` | 日课表与时间点、课程的外键关联、空课/停用/换课标记 |
|
||
| `ScheduledClassPlan` | 按本地日期预定日课表 |
|
||
| `PromotionRun` | 年度升级幂等与审计 |
|
||
| `Courseware` | 文件元数据、上传教师、存储路径与 SHA256 |
|
||
| `CoursewareFolder` | 教师自建分类目录，按上传者隔离 |
|
||
| `CoursewareVisibility` | 课件可见班级 |
|
||
| `CoursewarePush` | 按班级的推送任务 |
|
||
| `CoursewareReceipt` | 按设备的课件接收回执 |
|
||
|
||
学生和账号分离：Student 没有密码/角色；教师/管理员存 User，CLASS_DEVICE 只是 Class 登录形成的会话。
|
||
任课关系只在 Course；班主任关系在 Class.teacherId，可以与任课关系指向同一账号。
|
||
课表真值是 ClassPlan/ClassPlanEntry/TimeLayoutItem，旧 Schedule 与 TimeLayout.items 不再参与现行业务写入。
|
||
周次口径见[课表](../app/schedules.md)，成绩限制见[成绩](../app/grades.md)。
|
||
|
||
## 迁移与启动
|
||
|
||
不要删除或重写已应用的 SQLite 迁移目录。源码开发使用 `pnpm --filter @classhelper/server db:deploy`。
|
||
安装形态由 `lib/db-bootstrap.ts` 执行启动迁移，账本 `_ch_migrations` 记录已执行目录。
|
||
升级迁移包含学生表拆分、联动退役、关系化课表、权限范围、年度升级和课件表；具体顺序读取 migrations。
|
||
历史学生迁移中的 STUDENT 只用于搬运旧数据，不是现行账号角色。
|
||
MySQL 建模走受支持的换库流程，不能直接执行 SQLite SQL，详见[MySQL](../management/mysql.md)。
|
||
|
||
## 快照与文件
|
||
|
||
`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 是备份/导入/跨库迁移表清单，按依赖顺序导出，恢复阶段临时关闭外键检查并分批写入。
|
||
模型新增或删除必须同步此清单；不要在文档复制固定表数。
|
||
JSON 快照包含课件元数据、可见范围、推送与回执，**不含文件实体**；完整备份需带上课件目录。
|
||
User.careMode 是预留列；当前 Web 偏好在 localStorage，客户端偏好在本机 config.json，不宣称已有跨设备同步。
|
||
|
||
## 修改模型时
|
||
|
||
1. 同步 schema、迁移、shared 契约、服务层、相关前端与快照清单。
|
||
2. 核对外键级联与删除护栏，特别是教师的班级、课程、作业、通知和课件。
|
||
3. 在临时库验证新建和旧库升级；不对真实业务库运行 seed/reset。
|
||
4. 重新生成 Prisma Client，并按修改范围执行[验收](testing.md)。
|
||
|
||
## 权限与生命周期迁移
|
||
|
||
`20261023000000_promotion_permission` 为已初始化的 ADMIN 默认组补 promotion:manage；默认组尚未创建时允许不插入，由运行时模板创建。
|
||
`20261023010000_student_lifecycle_audit` 增加 PermissionAudit、StudentClassTransfer 的批次/学年/班级年级/学校快照、ArchivedYear.inactiveCount、PromotionRun 的操作人/明细/摘要/错误。
|
||
旧 mode 按 single/batch → class-change、transfer-out → transfer-out、restore-transfer → restore 迁移后删除该列，避免双事实源。
|
||
旧行的新字符串为空，学年为空，统计默认零；不臆造无法恢复的历史年级或批次。
|
||
|
||
SNAPSHOT_TABLES 已加入 PermissionAudit，新增字段随模型导出。旧快照没有审计表可恢复为空，旧历史 mode 在恢复时转为 kind；
|
||
没有新增列的旧行使用 schema 默认值。执行记录与升级快照不自动清理。
|
||
升级计划存 AppSetting.term.promotionPlan，时间存 term.promotionAt，无需新增学校或学生账号模型。
|
||
|
||
## 授权分配迁移
|
||
|
||
`20261031000000_authz_assignments` 为 UserPermissionGroup 增加 scope（默认 TEACHING）与 scopeValue。先按旧模板范围回填分配，再将模板 SELF_CLASS/空值和 SELF_CLASS/HEAD 规范为 TEACHING/HEAD。教师默认模板建议范围固定 TEACHING；旧 ADMIN 默认模板与旧管理员专用键保留在库中，由运行时忽略。
|
||
|
||
同一成员可将同一模板分配到多个范围，唯一约束为 userId/groupId/scope/scopeValue。PermissionGroup 的范围列仅作建议，不参与已有分配求值。
|
||
|
||
快照表集合和版本 1 保持兼容。恢复旧模板时映射 SELF_CLASS；旧 UserPermissionGroup 没有范围列时按快照内对应模板推导，缺组回落 TEACHING。新快照按实际分配列恢复。真实库升级前先备份快照，隔离回归不替代真实库升级演练。
|