LoveChengke
19c2aa07b2
文档站（`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`。
82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
---
|
||
title: 实时事件（Socket.IO）
|
||
description: 事件清单、房间规则，以及新增一个实时事件要同时改哪三处。
|
||
---
|
||
|
||
# 实时事件（Socket.IO）
|
||
|
||
## 连接
|
||
|
||
```ts
|
||
io(url, { auth: { token } }); // 握手阶段用 JWT 鉴权
|
||
```
|
||
|
||
客户端断线由 Socket.IO 自动重连。教室机器断线期间的变更，重连后靠各页重新拉取补齐
|
||
（客户端在检测到服务器恢复时会触发 `onServerRecovered`）；**灵动岛的上课时段暂存通知**由服务端保留、
|
||
下课后补发，不依赖重连。
|
||
|
||
## 事件清单
|
||
|
||
事件名定义在 `@classhelper/shared` 的 `SOCKET_EVENTS` —— **不要手写字符串**。
|
||
|
||
| 事件 | 方向 | 载荷 |
|
||
| ------------------------------------- | --------------- | ------------------------------------------------ |
|
||
| `connected` | 服务端 → 客户端 | `{ userId, role, rooms }` |
|
||
| `notification:new` | 服务端 → 客户端 | `NotificationDto` |
|
||
| `homework:new` | 服务端 → 客户端 | `HomeworkDto` |
|
||
| `homework:updated` | 服务端 → 客户端 | `HomeworkDto & { deleted?: boolean }` |
|
||
| `homework:status` | 服务端 → 客户端 | `HomeworkStatusDto & { classId }` |
|
||
| `grade:updated` | 服务端 → 客户端 | `GradeDto` |
|
||
| `schedule:updated` | 服务端 → 客户端 | `{ classId, action, schedule? }` |
|
||
| `class:updated` | 服务端 → 客户端 | `{ classId, action }` |
|
||
| `call:new` | 服务端 → 客户端 | 叫人消息（定向到 `user:{studentId}` / 班级设备） |
|
||
| `classisland:state` | 服务端 → 客户端 | `ClassIslandStateEvent`（教室现在上什么课） |
|
||
| `classisland:notification` | 服务端 → 客户端 | `ClassIslandNotificationEvent`（提醒已下发） |
|
||
| `class:join` / `class:leave` / `ping` | 客户端 → 服务端 | 手动订阅班级（服务端二次校验权限） |
|
||
|
||
## 房间规则
|
||
|
||
房间名定义在 `SOCKET_ROOMS`：
|
||
|
||
| 房间 | 谁在里面 |
|
||
| --------------------- | --------------------------------- |
|
||
| `class:{classId}` | 这个班的所有在线端 |
|
||
| `user:{userId}` | 某个用户自己的连接 |
|
||
| `teacher:{teacherId}` | 某个教师 |
|
||
| `role:{role}` | 某一角色（`ADMIN` / `TEACHER` …） |
|
||
| `students` | 全部学生端连接 |
|
||
| `teachers` | 全部教师端连接 |
|
||
|
||
服务端通过 `realtime/bus.ts` 的 `emitToClass` / `emitToUser` 发事件 ——
|
||
**业务模块不直接依赖 Socket.IO 实例**，只依赖事件总线。
|
||
|
||
## 新增一个实时事件要改三处
|
||
|
||
```
|
||
① 服务端 shared/src/constants.ts 的 SOCKET_EVENTS 加常量
|
||
→ business service 调 bus.emitToXxx(...)
|
||
→ realtime/socket.ts 房间映射（如果需要新房间）
|
||
② Web 端 web-admin/src/stores/realtime.ts 订阅
|
||
③ 客户端 desktop-client/src/renderer/stores/realtime.ts 订阅
|
||
→ 灵动岛也依赖它（renderer/island/bridge.ts）
|
||
```
|
||
|
||
**只改服务端不会报错**，只是前端静静地不更新 —— 所以这三处必须一起改。
|
||
事件名一律取自共享常量，不要手写字符串（拼错一个字就是一个静默失效）。
|
||
|
||
## 事件到达之后发生什么
|
||
|
||
以通知为例：
|
||
|
||
```
|
||
服务端写库 → bus.emitToClass(classId, notification:new)
|
||
├─► Web 端 stores/realtime.ts → 通知列表刷新
|
||
└─► 客户端 stores/realtime.ts → 更新内存状态 + 写回 IndexedDB
|
||
└─► island/bridge.ts → pushNotificationToIsland()
|
||
└─► 主进程 IslandController 决定：隐藏 / 胶囊 / 详情
|
||
└─► 灵动岛渲染进程 IslandApp.vue
|
||
```
|
||
|
||
上课时段的取舍（隐藏还是立即展开）由主进程的 `IslandController` 按当前上课状态决定，
|
||
见[通知与提醒](../app/notifications.md)与[灵动岛](../app/island.md)。
|