1 Fork 0

Files

T

LoveChengke 19c2aa07b2 feat(docs,scripts,build): 用 docfx 搭文档站并发布到 GitHub Pages，版本号收口成脚本迭代

文档站（`docs/` 就是 docfx 项目，发布在 https://lovechengke.github.io/ClassHelper/）：

- 四章 + 常见问题 + 完整参考，共 44 页：快速上手（8 页）/ 应用帮助（10 页）/
  管理运维（6 页）/ 开发文档（11 页）。信息架构照 ClassIsland 文档站来：
  顶栏分章、左侧章节导航、右侧本页目录、上一页 / 下一页、站内搜索、深色主题跟随系统；
- 自定义模板覆盖（`templates/classhelper/`）：把 docfx modern 模板那套英文 UI 文案
  （In this article / Improve this doc / Next…）换成中文，补 GitHub 入口与版本徽标，
  并加一层只调排版与配色的 `public/main.css`（不动 DOM 结构）；
- 站点顶栏的版本徽标取自根 `package.json`（`docs/build.mjs` 用 `--metadata` 注入），
  不在文档里写第二份 —— 否则一定漂；
- 404 页单独生成：GitHub Pages 的项目页挂在 `/<仓库名>/` 子路径下，而浏览器是按**被请求的路径**
  解析页面里的相对链接的，所以 `<base>` 必须钉到站点根，由 `build.mjs`（本地 `./`）与
  workflow（CI 传 `/<仓库名>/`）分别注入；
- 构建前清空 `_site`：docfx 只覆盖不清理，删掉或改名的页面会以旧文件留在目录里，
  而 Pages 上传的是整个目录。

版本迭代（**每一次 releases，不是每一次提交**）：

- 新增 `scripts/version.mjs`。这个仓库里同一个版本号散在 **10 个文件**里（5 份 `package.json`、
  `deploy/package.runtime.json`、两个 compose 的镜像 tag、插件 `manifest.yml`、以及插件 C# 里的
  `PluginVersion` 常量），手工改必然漏一处，而漏掉的那处**不会报错**，只在某个不常走的分支上
  表现为"版本号对不上"。现在收口成两条命令：`pnpm version:check`（逐处比对，不一致 exit 1）
  与 `pnpm version:bump patch|minor|major`（一次改写全部 10 处，任何一处匹配不到或匹配到多处
  就直接失败退出，不做尽力而为的部分改写）；
- `AGENTS.md` 新增 §4.4「版本迭代（每一次 releases，不是每一次提交）」：写清版本号落在哪 10 处、
  完整发布命令序列（体检 → 验收 → `dist:all` → 哈希清单 → 推 master → `gh release create` →
  Linux 包由 CI 合并哈希行），以及"已发布的版本号不要复用"的理由。

其它：

- `.github/workflows/docs.yml`：推 master（`docs/**` / `package.json` / workflow 自身有变）即构建并
  部署到 Pages；构建带 `--check`，把 docfx 的警告当错误 —— 最常见的警告是"某个 `.md` 没被任何
  `toc.yml` 引用"，那种页面有内容但没有侧边栏，属于必须修掉的疏漏；
- docs 目录重组后的引用同步：`production` / `mysql` / `linux-deploy` / `winisland-design-tokens`
  移到新位置后，AGENTS.md、`deploy/`、`scripts/`、客户端源码注释里的路径引用一并更新；
- 文档站只发布 `docs/` 这一棵树，页面里指向树外的相对链接（`../AGENTS.md` 等）改成 GitHub 绝对 URL，
  否则上线全是 404；
- 图标派生清单补上文档站模板里的 `logo.png` 与 `favicon.png`（`pnpm icons` 一并生成，
  仍然只有一个图形源 `build/classhelper.{png,ico}`）；
- `docs/_site` 进 `.gitignore` / `.prettierignore` 与 ESLint ignores；
- 根脚本补 `version:check` / `version:bump` / `docs:build` / `docs:serve` / `docs:check`。

2026-10-06 16:27:44 +08:00

6.2 KiB

Raw Blame History

title, description

title	description
数据模型	14 张表的职责、跨库通用约定、迁移历史与启动时自动迁移。

数据模型

模型定义只有一份：packages/server/prisma/schema.prisma。

跨库通用约定

默认是 SQLite（Prisma 7 的 libSQL driver adapter，数据文件 packages/server/prisma/dev.db）；
字段只用 String / Int / Float / Boolean / DateTime，不用 Prisma enum、不用 @db.* 原生类型；角色与优先级存字符串，在 API 层用 zod 校验 —— 这样 SQLite 与 MySQL 行为完全一致；
因此切库只需改 provider 与连接串（pnpm db:switch:mysql 就地改写它，没有第二份 schema）；
主键统一用 cuid 字符串，便于多端离线生成与合并。

14 张表

表	职责	值得注意的字段
`User`	教师 / 管理员 / 学生统一存储	`role`、`classId`；学生 `passwordHash` 是空串占位，不能登录
`Class`	班级	`code` + `passwordHash`（班级账号）、`termWeeks`、`notificationChannel`
`ClassTeacher`	教师-班级分配关系（协作教师）	`@@unique([classId, teacherId])`
`Enrollment`	学生-班级归属记录	与 `User.classId` 同步，为将来多班预留
`Course`	课程（班级维度）	`@@unique([classId, name])`
`Schedule`	课表条目	`weekStart` / `weekEnd` / `weekParity`（单双周）/ `source`（manual｜classisland）
`Homework`	作业	`assignDate`（所属日期）、`attachmentUrl`；`dueAt` 是已下线的遗留列
`HomeworkStatus`	学生作业完成状态	`@@unique([homeworkId, userId])`
`Notification`	通知	`priority`
`NotificationRead`	已读记录	`@@unique([notificationId, userId])`
`TimeLayout`	节次时间配置（ClassIsland 同款 JSON 导入得到）	`items` 是 JSON 字符串：`[{ index, name, startTime, endTime, type, skipped }]`
`Grade`	成绩	`score` / `totalScore` / `examName`
`IntegrationDevice`	ClassIsland 联动设备	`tokenHash`（只存 sha256）、`tokenHint`、两个开关、最后一次上报的快照字段
`ClassIslandPush`	下发给 ClassIsland 的提醒	`kind`（notification｜call）、`ackedAt`、`expiresAt`

三个容易忽略的设计

ClassIslandPush 与 IntegrationDevice —— 提醒是落库的，不是"发出去就算"。设备离线时通知不丢：插件重连后拉取未确认的那条立即弹出，弹完回执（ackedAt）。 expiresAt 防止学生几天后突然弹出旧提醒。

Schedule.source —— 决定插件全量上报时能清理哪些行：只清 classisland 来源且本次未再上报的行。 source 只在 create 时确定，update 一律保持原值（否则手排的课会被"收养"后又被清掉）。

Homework.dueAt —— 截止时间功能已下线，UI 与接口都不再读写它。保留列是为了不对已安装的库做破坏性迁移；新库里它恒为 null。

迁移历史（10 个）

init → add_time_layout → add_class_account → add_schedule_week_parity →
add_class_term_weeks → add_classisland_integration → add_class_notification_channel →
add_homework_assign_date → add_push_kind → add_schedule_source

启动时自动迁移

src/lib/db-bootstrap.ts 用一张账本表 _ch_migrations 记录已执行的迁移目录名：

情况	行为
全新安装	依次执行全部迁移并创建初始管理员
覆盖安装	只补跑账本里没有的迁移（已存在的表 / 索引自动跳过）
已是最新	不做任何写操作

日志会写明「全新安装 / 升级安装」、应用了几个迁移、跳过了几个已存在对象。用户因此不需要手动执行 prisma migrate deploy。

备份格式就是这份模型的拓扑序导出

「数据库管理」里的备份 / 导出导入 / 跨库迁移共用一种 JSON 快照：14 张表按拓扑序导出，恢复时临时关闭外键检查 —— 因为 User.classId → Class 与 Class.teacherId → User 互相引用，任何排序都会被其中一侧卡死。见数据库管理。

开发时的模型改动

改 schema.prisma；
在 prisma/migrations/ 下加一个迁移目录（本机用 pnpm --filter @classhelper/server db:deploy 应用，别用 pnpm db:migrate —— 它在 Windows 上不可靠）；
改 schema 时先看哪些外键指向 User 且是 Cascade，再回来核对 deleteTeacher 的护栏清单（它必须覆盖 Class.teacherId / Course.teacherId / ClassTeacher.teacherId / Homework.createdBy / Notification.createdBy 五项）。

模型总数与迁移个数会随版本增长，以 schema.prisma 与 prisma/migrations/ 的实际内容为准；本文里的数字标注的是当前版本（1.1.2）的状态。

6.2 KiB Raw Blame History Unescape Escape