feat(courseware,docs): 完善课件传输与岛编辑并统一全仓文档

- 增加课件上传、班级可见范围、设备补收与传输进度 - 整合自定义灵动岛编辑器和相关客户端交互 - 同步三端契约、数据库迁移、部署配置与隔离回归 - 按源码统一文档与官网说明，移除过时任务书和审查记录 - 保持产品版本为 1.4.0
2026-10-18 11:53:37 +08:00
1 parent 536379036a
commit c7f215a09c
@@ -12,10 +12,10 @@ description: 在教室机器上安装 ClassHelper桌面客户端，用班级码

 从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取：

-| 产物                                  | 用途                                       |
-| ------------------------------------- | ------------------------------------------ |
-| `ClassHelper-<版本>-x64-setup.exe`    | 安装包（约 98 MB），装到本机并建快捷方式   |
-| `ClassHelper-<版本>-x64-portable.exe` | 单文件便携版，双击即用，适合不改动机房机器 |
+| 产物                                                                  | 用途                                       |
+| --------------------------------------------------------------------- | ------------------------------------------ |
+| `ClassHelper-<版本>-x64-client-setup.exe`（本地构建名不带 client）    | 安装包（约 98 MB），装到本机并建快捷方式   |
+| `ClassHelper-<版本>-x64-client-portable.exe`（本地构建名不带 client） | 单文件便携版，双击即用，适合不改动机房机器 |

 要自己打：

@@ -50,15 +50,16 @@ pnpm dist:win     # 安装包 + 便携版（两个都是成品，没有中间的

 ## 4. 认一认主界面

-左侧是四个一级项（**课表 / 作业 / 通知 / 成绩**）加上一个可展开的**设置**分组，
+左侧是业务项（**课表 / 作业 / 通知 / 课件 / 成绩**）加上一个可展开的**设置**分组，
 顶部汉堡按钮把整栏收成 64px 的图标导轨（折叠状态会记住）。「通知」项上有未读红点。

 | 页面 | 一句话                                                         |
 | ---- | -------------------------------------------------------------- |
 | 课表 | 周视图 + 「今天」时间轴（大时钟 / 正在上什么 / 下一节）        |
 | 作业 | 看板模式（按科目卡片、可全屏）/ 列表模式；教室机器还能录入作业 |
+| 课件 | 查看本班可见文件、下载和打开本地文件夹                         |
 | 通知 | 未读红点、优先级标签、点开自动标为已读                         |
-| 成绩 | 班级账号看到的是全班总览（表格 + 柱状图 + 等级分布）           |
+| 成绩 | 个人查询开启时看本班成绩，关闭后只看服务端集体分析             |
 | 设置 | 通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，六个子页            |

 细节见[应用帮助](../app/index.md)。
@@ -71,15 +72,15 @@ pnpm dist:win     # 安装包 + 便携版（两个都是成品，没有中间的
 2. **调灵动岛** —— 设置 → 灵动岛：高度、宽度、字号、主题色、停靠位置、视觉风格。
   讲台机器上通常把字号调大一点、位置放到顶部居中。
   触摸屏（希沃白板等）走的是另一套命中逻辑，客户端会自动识别，不用手动开。
-3. **查看提醒规则** —— 设置 → 提醒：普通通知下课显示，紧急提醒立即显示。
-   这个选择会同步到班级记录，服务端据此决定要不要广播到客户端。
+3. **查看提醒规则** —— 设置 → 提醒维护本机课程等提醒设置；经典通知模式上课暂存普通消息，
+   自定义常驻模式提示铃铛并主动查看。规则保存在本机，服务端仍即时广播。

 ## 6. 确认实时链路是通的

-在 Web 管理端给这个班发一条普通通知，教室机器上应该几秒内出现灵动岛胶囊。如果没有：
+在隔离测试服务中给临时验证班级发一条普通通知，经典岛课间应出现胶囊，自定义常驻岛应出现铃铛数量提示。如果没有：

 - 客户端顶栏的实时通道状态是不是"已连接"？
- 现在是上课时段吗？上课时段的普通通知**只进队列、下课才弹**，这是设计行为，不是故障。
+- 现在是上课时段吗？经典模式普通通知上课暂存；自定义常驻模式看铃铛并主动展开。
 - 服务器与教室机器之间能互相 ping 通吗？防火墙放行 4000 了吗？

 排查清单见[常见问题](../faq.md)。
@@ -1,60 +1,36 @@
 ---
 title: 发布第一条内容
-description: 发通知、布置作业、叫人、录成绩——把 ClassHelper真正用起来的第一轮操作。
+description: 通知、作业、叫人、成绩与课件的首次操作。
 ---

 # 发布第一条内容

-前面几步做完，系统就完整了。这一页走一遍四件最常用的事，每件都点出**它会不会弹、弹在哪个端**。
+先完成班级、学生与任课关系配置。页面是否可见及能否发布，由实际功能权限、班级范围和科目关系共同决定。

-## 发一条通知
+## 通知与叫人

-**通知发布** → 选班级 → 填标题和内容 → 选优先级 → 发布。
+在“通知发布”选班、填写标题/内容、选择优先级后发布；叫人使用该页叫人入口，选择学生和事由。
+通知有低/普通/重要/紧急四档，叫人分普通 HIGH 与紧急 URGENT。
+经典岛普通通知上课暂存，普通叫人保留可点击胶囊，紧急消息立即展开；自定义常驻岛先提示铃铛，主动查看。
+上课发布紧急通知需服务端二次确认，Web 确认框倒计时结束后才能再次提交。
+完整行为见[通知](../app/notifications.md)和[叫人](../app/calls.md)。

-| 优先级 | ClassHelper 班级端表现                                                     |
-| ------ | -------------------------------------------------------------------------- |
-| 普通   | 课间弹胶囊，点击展开；**上课时段只进队列**，下课自动补弹                   |
-| 重要   | 同上，卡片上带优先级标签                                                   |
-| 紧急   | **无论是否上课都立即展开**（卡片内部红色呼吸光晕 + 紧急角标），45 秒后收起 |
+## 作业

-**上课时段发紧急通知会被拦一次。** 服务端返回 `409 URGENT_DURING_CLASS`，前端弹一个全屏二次确认，
-上面写着"现在为上课时间段……"、正在上的那节课，还有待发布的标题；确认按钮带 **3 秒倒计时**，
-倒计时结束前点不动。确认之后才真的发出去。
+在“作业发布”选班、科目、所属日期，填写标题与要求；附件为受校验的 http(s) 或站内链接。
+作业按所属日期展示，可补录历史日期；科目写权限以本人任课关系为准。
+教室客户端可录作业和维护未交名单；本机录入的内容不会再提醒自己。
+可选全屏看板与字号/日期等偏好，详见[作业](../app/homeworks.md)。

-这个拦截是**服务端做的**，绕过界面直接调接口一样会被拦 —— 它是产品行为，不是前端提醒。
+## 成绩

-## 布置一份作业
+在“成绩录入”选择班级、考试，单条/批量录入或导入表格。
+具备功能权限后，仍只能写自己任教科目；表格导入还要求管理员/本班班主任，按行返回错误和警告，文件上限 8 MB。
+班级端个人查询开关开启时可看本班明细与排名，关闭后只看服务端集体分析。
+见[成绩](../app/grades.md)和[导入](../app/imports.md)。

-**作业发布** → 选班级 / 科目 → 填标题与要求 → 选**所属日期** → 发布。
+## 课件

-> 作业按**所属日期**归类，不是按录入时间。晚上 8 点留的作业算今天。
-> 老师可以给今天、明天甚至上周补录一份作业，客户端按日期查得到。
-
-附件支持站内相对路径或 `http(s)://` 链接（其他 scheme 服务端会拒，避免被当成脚本执行）。
-
-ClassHelper 班级端那边默认是**看板模式**：按科目分卡片、每条作业完整显示要求、整个看板缩放到刚好铺满屏幕；
-老师也可以在教室机器上直接**录入作业**、勾选**未交名单**（教室机器用的是班级账号）。
-
-## 叫一位同学
-
-**通知发布 → 叫人**（或管理员在**学生管理 → 叫人**）→ 选学生 → 点一个快捷短语或自己写一句 → 发送。
-
-| 级别     | ClassHelper 班级端                                                 |
-| -------- | ------------------------------------------------------------------ |
-| 普通叫人 | 课间显示「叫人」胶囊，点击展开；**上课时段只进队列**，下课自动弹出 |
-| 紧急叫人 | **无视上课时段立即展开**，上课时被收起后仍保留胶囊、可再次点开     |
-
-文案是「请 XXX 同学找 XXX 老师」，卡片上是「收到」按钮（复用通知的已读机制）。
-
-> 学生管理页是管理员专属，但班主任与科任老师同样需要叫人，所以给老师留的入口在「通知发布 → 叫人」。
-
-## 录一次成绩
-
-**成绩录入** → 选班级与考试名称 → 单条录入 / 批量录入 / 导入表格。
-
- **科目**下拉同样是全校统一目录，选一个该班还没有的科目会自动建课。
- 导入表格支持 `.xlsx / .xls / .csv / .tsv`，列名按同义词自动映射（「用户名→学号」「得分→分数」），
-  也可以手动改。**文件上限 8MB**，超了会返回明确的 413 而不是一句英文的内部错误。
- 导入结果会给逐行的错误与警告，`errors[].row` 是 **Excel 视角的行号**（含表头），改完可以再导。
-
-ClassHelper 班级端看到的是**全班总览**：表格（分数 / 得分率 / 等级）+ 柱状图 + 等级分布 + 最近更新。
+在“教学事务 → 课件”上传文件，选择本人授课班级并设置“仅保存”或“保存后推送”。
+文件先保存到服务端，班级端按可见范围下载；推送离线补领、逐设备回执，客户端不自动运行文件。
+单文件上限 512 MB，详见[课件上传与传输](../app/courseware.md)。
@@ -7,17 +7,17 @@ description: ClassHelper 服务端、Web 管理端、桌面客户端的运行环

 ## 服务端

-服务端的安装包**自带 Node 运行时**，目标机器不需要另外装 Node.js，也不需要数据库软件
-（默认用内嵌的 SQLite）。
+Windows 服务端安装包自带 Node；Linux 包不内置 Node，一键安装器检测或安装兼容运行时。
+默认使用内嵌 SQLite，无需另装数据库服务；MySQL 形态需可用数据库。

-| 项目     | 要求                                                                        |
-| -------- | --------------------------------------------------------------------------- |
-| 操作系统 | Windows 10 / 11 / Server 2016+（x64）；Linux（glibc 2.28+，见下）；Docker   |
-| 内存     | 512 MB 起步，2 GB 以上更稳（Node + SQLite 常驻约 120–200 MB）               |
-| 磁盘     | 程序约 340 MB（免安装目录）/ 安装后约 400 MB；数据按班级量增长，通常几十 MB |
-| CPU      | 任意 x64；不需要独显                                                        |
+| 项目     | 要求                                                                       |
+| -------- | -------------------------------------------------------------------------- |
+| 操作系统 | Windows 10 / 11 / Server 2016+（x64）；Linux（glibc 2.28+，见下）；Docker  |
+| 内存     | 512 MB 起步，2 GB 以上更稳（Node + SQLite 常驻约 120–200 MB）              |
+| 磁盘     | 预留程序、数据库、备份和课件文件空间；课件最多 512 MB/文件，按实际使用增长 |
+| CPU      | 任意 x64；不需要独显                                                       |

-**Linux 的 glibc 要求**：内置的 Node 官方 linux-x64 构建要求 glibc ≥ 2.28。
+**Linux 的运行时要求**：安装器下载的官方 Node linux-x64 运行时通常要求 glibc ≥ 2.28。
 CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体（尽力而为，未做长期验证）。
 判据：

@@ -25,8 +25,8 @@ CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体
 ldd --version | head -1
 ```

-**外网**：服务端只在「检查更新」时访问 GitHub，且失败是设计内的结果（返回"查不到"，不报错）。
-内网机器可以完全不连通外网。
+**外网**：更新检查/下载安装包、假日建议和配置的在线 AI 服务等功能可能访问外网。
+基础教学业务可在内网运行；使用离线包、手工周次和 mock/关闭在线 AI，相关联网失败按接口返回原因处理。

 ## Web 管理端

@@ -1,71 +1,37 @@
 ---
 title: 建班级、排课表
-description: 建第一个班级、配班级账号、加学生与老师、排课表——后面所有功能的前提。
+description: 班级、名单、任课关系与日课表的首次配置。
 ---

 # 建班级、排课表

-后面所有功能（发通知、布置作业、录成绩）都挂在**班级**上，所以先把班级建出来。
+## 创建班级

-## 1. 建班级（仅管理员）
+管理员在“班级管理”填写入学年份、班号、年级等资料；班级名称按年份和班号生成，如“2026级1班”。
+设置班主任、学期周数及班级凭据；班主任可暂空，但发布依赖教师归属的内容前需先完成配置。
+班级周数默认 20，受全校可配置上限限制，全校默认上限 30、范围 1–60。
+保存班级码与密码，教室客户端用它登录；已读和作业状态操作代表全班。

-Web 管理端 → **班级管理** → 「新建班级」：
+## 录入学生与教师

-| 字段     | 说明                                                                    |
-| -------- | ----------------------------------------------------------------------- |
-| 班级名称 | 例如「高二(3)班」                                                       |
-| 年级     | 用于分组与统计                                                          |
-| 班主任   | 从教师账号里选，默认是自己；之后随时可在班级详情顶部「更换班主任」改    |
-| 学期周数 | 默认 20，**上限 30**。课表的周次选择与周次范围都以它为准                |
-| 班级码   | 保存时自动生成（字母数字 4–16 位，存大写），可以改成好记的，例如 `G203` |
-| 班级密码 | 新建班级时的初始密码就是它 —— 学生在教室机器上要用这个登录              |
+学生是名单，填写学号和姓名，不创建账号、密码或自动登录名。
+学号 1–32 位字母/数字/._-，不能复用；支持管理员表格导入，班主任有名单管理权限时可维护本班。
+教师使用工号账号，管理员在教师管理录入或导入。
+在班级详情按科目配置任课老师：任课关系只存 Course，决定该科作业/成绩写权限。
+班主任不任教某科就不能改该科内容，详见[班级与人员](../app/classes.md)。

-> **班级码 + 班级密码 = ClassHelper 班级端的登录凭据。** ClassHelper 班级端没有个人账号，一台教室机器用班级账号登录后，
-> 那台机器上的「已读 / 完成」是**代全班**操作的。
->
-> 学期周数只有管理员能改：它决定"现在是第几教学周"，乱改会让课表的周次过滤和上课时段判定错位。
+## 配置作息与日课表

-## 2. 加学生（仅管理员）
+先在“时间表与课表编辑”维护时间表的上课/课间等时间点，再创建班级日课表并为时间点选择课程。
+按星期、周次范围和 1–9 周轮换设置启用规则，也可复制、临时换课或预定某天。
+时间表写入需 timetable:manage；日课表写入需 schedule:write 并通过本班班主任/管理员检查。
+可以从 ClassIsland 完整 JSON 离线导入作息、日课表、群组与预定，见[导入](../app/imports.md)。

-**学生管理** → 「新建」或「导入名单」：
+## 校对周次与提醒

- **单个新建**：填姓名即可，登录名会自动生成。
- **导入名单**：下载模板（列是 `学号 / 姓名 / 班级 / 性别 / 家长手机号`，学生**不是账号**，没有密码列），填好上传。
-  用户名要匹配 `^[A-Za-z0-9_.-]{3,32}$`；重复用户名在 `append` 模式下跳过、`upsert` 模式下更新姓名。
-  用户名已经属于某个教师 / 管理员账号时，这一行会进错误列表，不会覆盖别人的账号。
+管理员在“学期周次”设置开学日、全校上限和逐周日期，班级可以有独立区间。
+在周视图和客户端今天时间轴核对当前课程、下一节、上下课时刻。
+经典岛普通通知上课暂存、普通叫人保留可点胶囊、紧急消息立即展开；自定义常驻岛先提示铃铛，主动点击查看。
+验证应使用独立测试班级，详见[验收](../dev/testing.md)，不要给业务班级发送测试通知。

-学生的用途是：**成绩、未交名单、叫人、已读记录都按名单记录**。所以名单不全，这几项就不准。
-
-## 3. 加科任老师
-
-教师的**录入**只有管理员能做（**教师管理**页，支持单个录入与导入名单）。班级层面的**分配**在班级详情里：
-在「班级详情 → 任课老师」里给某位老师配一门课，他就能看到这个班，并**只能改自己任教科目**的作业与成绩。
-
-角色与可见范围见[班级、学生与教师](../app/classes.md)与[角色与权限](../dev/permissions.md)。
-
-## 4. 排课表
-
-**课表管理** → 选中班级 → 「新增课表」：
-
- **科目**下拉直接列出全校统一的 18 科目录（语文 / 数学 / 英语 / 政治 / 历史 / 物理 / 化学 / 地理 /
-  生物 / 信息技术 / 体育 / 美术 / 音乐 / 班会 / 早读 / 晚读 / 通用技术 / 听力）。
-  选中一个该班还没有的科目时，前端会**自动为该班建同名课程**，不用先去把科目的建一遍。
- 填星期、开始 / 结束时间、周次范围（第几周到第几周）、单双周（每周 / 单周 / 双周）。
- 一节课**必须同时有开始时间和结束时间** —— 「上课时段」的判定就是拿这两个时间比对的。
-
-排完在**课表管理**里能看到周视图（7 列），客户端那边则多一个「今天」时间轴视图。
-
-### 从 ClassIsland 导入更省事
-
-如果教室里已经在用 ClassIsland，直接导入它的档案 JSON 就行：课表、节次时间、单双周都会一起进来，
-不用排两遍。见[表格与课表导入](../app/imports.md)。
-
-## 5. 确认「上课时段」判定是对的
-
-ClassHelper有一整套「上课时段策略」：普通通知在上课时段只进队列、下课自动补弹，紧急通知与叫人则立刻弹。
-这套判定完全基于课表，所以**课表排错，提醒就会在该弹的时候不弹**。
-
-排完课之后建议立刻验一下：在**通知发布**页选这个班，随便发一条普通通知，
-看客户端是不是在课间弹出来、上课时是不是安静地收着。规则详见[通知与提醒](../app/notifications.md)。
-
-下一步：[装 ClassHelper 班级端](client.md)。
+下一步：[装班级端](client.md)。
@@ -1,58 +1,34 @@
 ---
 title: 认识 Web 管理端
-description: 登录 ClassHelper Web 管理端，认一认 12 个页面、新手引导与手机端布局。
+description: 登录、菜单分组、权限与移动布局。
 ---

 # 认识 Web 管理端

-Web 管理端不用装：服务端起来之后，浏览器打开 `http://<服务器地址>:4000/` 就是它。
+服务端启动后，用浏览器打开 http://<服务器地址>:4000/，教师或管理员以工号和密码登录。
+学生无个人账号，教室客户端使用[班级登录](client.md)。新安装按部署配置创建初始管理员，首次使用后修改初始密码。

-## 登录
+## 菜单与权限

-用**教师 / 管理员账号**登录（用户名 + 密码）。学生没有个人账号，学生那一端走
-[班级码 + 班级密码](client.md)，见[班级、学生与教师](../app/classes.md)。
+侧栏按以下分组组织，具体页面由路由权限筛选，并支持浅色/深色和关怀模式。

- 新装的服务端只有安装时创建的那一个管理员账号。**第一次登录后请立刻在顶栏头像菜单 → 修改密码里改掉它。**
- 登录页**不含任何演示内容**（没有"点击填充示例账号"之类的按钮），也不会提示种子口令。
- 连不上服务器时页面会直接失败，不会静默重试 —— 先确认服务端在跑、端口对、没走代理。
+| 分组       | 主要页面                                           |
+| ---------- | -------------------------------------------------- |
+| 工作台     | 仪表盘、AI 助手                                    |
+| 教学事务   | 课表、时间表与日课表编辑、作业、通知、课件、成绩   |
+| 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、毕业归档 |
+| 设备运维   | 客户端在线状态、命令、更新与安装策略               |
+| 系统管理   | 权限组、系统设置、大模型设置、数据库管理           |

-## 界面
+班级/学生/教师管理、学期周次、归档和数据库页面还有管理员角色门槛；
+教师只读名单、教学页与设备页按权限键和数据范围开放。
+每次操作服务端继续校验，不是显示菜单就能改所有班和科目。详见[角色与权限](../dev/permissions.md)。
+顶栏提供本人密码、使用引导、检查更新与退出等入口。

-布局沿用 1Panel 那一套：左边固定深色侧边栏，右边浅灰底 + 白色圆角卡片。
+## 引导与手机

-| 页面       | 干什么                                         | 谁能进                 |
-| ---------- | ---------------------------------------------- | ---------------------- |
-| 仪表盘     | 全校 / 本班的汇总数字与最近动态                | 所有登录用户           |
-| 课表管理   | 排课、导入 ClassIsland 课表、节次时间          | 管理员、本班班主任     |
-| 作业发布   | 发作业、按天查看、看未交名单                   | 教师、管理员、班级账号 |
-| 通知发布   | 发通知、发叫人                                 | 教师、管理员           |
-| 成绩录入   | 单条 / 批量录成绩、导入表格、看统计            | 管理员、本班班主任     |
-| 客户端管理 | 看设备状态、下发远控与更新                     | 管理员、教师           |
-| 班级管理   | 建班级、换班主任、改班级账号                   | **仅管理员**           |
-| 学生管理   | 学生名单增删、导入                             | **仅管理员**           |
-| 教师管理   | 教师账号增删改、导入名单、重置密码             | **仅管理员**           |
-| 数据库管理 | 备份 / 恢复、导出导入、一键切换 SQLite ⇄ MySQL | **仅管理员**           |
-| 检查更新   | 顶栏头像菜单里，查 GitHub 上有没有新版本       | 所有登录用户           |
-
-> **前端隐藏 ≠ 权限**。上面这张表只是"入口藏不藏"，每一条写入请求服务端都会再判一次
-> （见[角色与权限](../dev/permissions.md)）。直接输网址绕过菜单，一样会被挡回仪表盘。
-
-## 第一次登录的引导
-
-首次登录进入主布局后会自动弹一次聚焦式引导，依次指出：侧边菜单 → 实时通道状态 → 账号菜单 → 完成。
-走完或跳过（右上角 × 或 Esc）都记作"已看过"，之后不再自动弹。
-
-想重看：**右上角头像菜单 →「使用引导」**。
-
-## 手机 / 平板
-
-| 屏幕宽度  | 布局                                                   |
-| --------- | ------------------------------------------------------ |
-| > 992px   | 常驻 210px 深色侧边栏 + 顶栏显示连接状态与实时事件计数 |
-| 769–992px | 保留侧边栏，内容区内边距压缩                           |
-| ≤ 768px   | 侧边栏收进抽屉，顶栏汉堡按钮唤出；表格在卡片内横向滚动 |
-
-手机上（与电脑同一局域网）用 `http://<主机IP>:4000` 打开，可以「添加到主屏幕」当 App 用（PWA）。
-做成 HTTPS 之后 PWA 才能完全离线化，见[生产部署指南](../management/production.md)。
+首次登录展示使用引导，完成/跳过后记住；可从顶栏“使用引导”重看。
+小屏侧栏收进抽屉，表格在卡片内横向滚动；支持安装 PWA，需要 HTTPS 或 localhost 安全上下文。
+同局域网手机填写服务器局域网地址，不用 localhost；公网反代见[生产部署](../management/production.md)。

 下一步：[建班级、排课表](setup-class.md)。