ClassHelper/docs/app/courseware.md

课件上传与传输

教师可在 Web 管理端的「教学事务 → 课件」上传演示文稿、文档、表格、图片、音视频、压缩包等文件，单文件上限为 512 MB。

上传与可见范围

1. 选择本地文件。
2. 选择可以查看课件的班级。候选项只包含本人担任任课教师的在读班级；仅担任班主任、级长或部长不会额外获得上传到这些班级的权限。
3. 可新建分类文件夹，使用 / 分隔多层目录，例如 地理/必修一；不选文件夹时直接按日期归档。
4. 选择「仅保存云端」或「保存后推送所选班级」，点击上传。

不选择班级时，课件仅自己可见。仅保存云端并指定可见班级后，这些班级可在客户端自主下载。推送模式会先把文件完整保存到服务端，再给所选班级创建下载任务；不会从教师电脑直接传到教室电脑。

教师可在列表中按文件名、教师、归档日期和文件类型筛选，修改自己课件的可见范围，或再次推送。再次推送时只能选择「本人授课班级」与「该文件可见范围」的交集。管理员可查看归档列表，但上传和推送自己的文件同样遵守任课关系。

「查看与下载课件」和「上传、设置可见范围与推送自己的课件」为独立权限，可在权限组中分配。默认教师与管理员、内置教师与班主任岗位包含这两项权限；升级时自定义权限组需管理员按需授权。

「日期归档」按教师、年、月、日和上传时间选择目录；「文件夹分类」按自建目录筛选，已有文件可随时调整分类。文件夹按教师隔离，分类本身不授予班级下载权限。

班级客户端

客户端侧栏新增「课件」，仅列出本班可见的文件，显示文件名、类型、上传教师、日期与大小。点击「下载」将课件保存到本机，点击「打开文件夹」定位已下载文件。客户端不会自动运行文件。

「本机归档」独立列出已经接收的课件，离线时也可按教师和日期目录查找。每个服务端与班级会话有独立归档根目录，文件路径采用 Teachers\老师名字\上传年份\上传月\上传日\上传时间\文件名，例如 Teachers\Wanghong\2026\10\18\15-30-42\大气环流.pptx。目录时间取上传时间，重复推送会复用已校验的文件；同秒同名的不同课件会添加编号，避免覆盖。

收到教师推送后，客户端自动下载；离线时任务保留在服务端，上线后的心跳会补拉，每台设备独立回执。实时通道正常时会立即触发检查；断线时通过心跳继续补收。传输失败会显示原因，推送任务在后续心跳中重试，不会影响远控和在线状态上报。

下载期间，固定岛和自定义常驻岛都会显示文件名、文件类型、传输教师、接收字节数和进度条。下载完成后校验 SHA256，再保存正式文件并回执。断网时可以查看已缓存的课件目录与已经下载的本地文件；重新联网后同步当前可见范围。

修改可见范围后，被移除班级无法再获取文件，尚未完成的推送任务同步取消。已经下载到教室电脑的文件无法远程撤回，需要在本机自行删除。

服务端归档与备份

默认文件实体目录为 <服务端根目录的上一级>/data/courseware/<随机编号>/Teachers/<教师>/<年>/<月>/<日>/<时间>/<文件名>，随机编号隔离同名教师和同秒上传，旧课件保留原存储位置。可通过环境变量 COURSEWARE_DIR 指定文件目录。上传使用流式写入，未完成文件使用 .part 临时文件；失败或上传中断时清理。只有完整收到文件并完成摘要计算后才记录元数据和创建推送任务。

数据库迁移新增课件、可见班级、推送、设备回执和分类目录，并记录上传归档路径。SQLite 安装部署按现有自动迁移流程更新；源码开发部署执行 pnpm --filter @classhelper/server db:deploy。MySQL 按现有换库流程基于更新后的 schema 建模。

数据库 JSON 备份包含课件元数据和分类目录，但不包含二进制文件本身。完整备份必须同时备份 data/courseware（自定义目录时备份对应目录）。SQLite Docker 的现有数据卷覆盖此目录；MySQL Docker 配置增加 server-data:/app/data 数据卷。复制到新机器时需同时恢复数据库和文件目录。

使用反向代理时，需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 /api/courseware/ 配置 512 MB 和 1800 秒超时，其他接口维持原有大小限制。

开发验收：pnpm verify:courseware 自动使用隔离数据库和临时文件目录，不读取或向真实班级发送课件。