1 Fork 0

Files

T

LoveChengke 71cc8eb605 fix(update): 修复云端安装交接并完善发布验收

修复隐藏缓存目录下载和响应收尾，使用原生助手校验安装包并确认交接。
补齐真实静默升级、便携版及中文路径验收，并按现行设备和科目授权契约更新回归。
服务端安装时生成独立密钥，覆盖升级保留既有配置；补齐安装包副本验证说明。

2026-10-31 17:07:17 +08:00

5.4 KiB

Raw Permalink Blame History

title, description

title	description
架构总览	工作区结构、模块注册、共享契约与数据流。

架构总览

ClassHelper 是 pnpm workspace：Express/Prisma/Socket.IO 服务端、Vue Web 管理端、Electron 桌面客户端与共享包。依赖版本以根和各包的 package.json、pnpm-lock.yaml 为准。文档站和纯静态官网不在 workspace 内。

目录与入口

路径	职责
`packages/shared/src/`	类型、权限目录、动效、课表/岛/课件契约
`packages/server/src/app.ts`	探针、限流、中间件、模块挂载、静态 Web 托管
`packages/server/src/index.ts`	启动、自检、HTTP、Socket.IO 与退出清理
`packages/server/src/modules/registry.ts`	全部启用模块的唯一注册表
`packages/server/src/lib/`	鉴权范围、日课表解析、周次、快照与系统设置
`packages/server/prisma/`	单一 schema、SQLite 迁移、演示 seed
`packages/web-admin/src/router/`	Web 路由、标题、图标、权限
`packages/web-admin/src/config/navigation.ts`	菜单分组，页面属性读取路由
`packages/desktop-client/src/main/`	窗口、配置、岛、设备代理、更新、课件下载
`packages/desktop-client/src/preload/`	contextBridge 白名单
`packages/desktop-client/src/island/`	经典岛、自定义运行时、课程与课件提醒
`packages/desktop-client/src/renderer/`	主窗口页面、状态、IndexedDB 与岛桥接
`scripts/` / `deploy/`	验证、版本、打包、部署与运维
`docs/` / `website/`	文档站与官网，Pages 构建时拼接

模块与数据流

功能模块使用 *.module.ts 路由、*.schemas.ts 校验、*.service.ts 业务；新增/下线改 registry.ts。注册表包含教学业务、课件、日课表/时间表/群组、权限、客户端、系统、AI、升级和数据管理模块。路由与模块总数直接读取注册表，不在文档复制另一份数组。

教师在 Web 提交 → 服务端校验权限、班级和科目范围 → 写数据库 → 事件总线按房间广播 → Web/客户端刷新。客户端先维护 IndexedDB 缓存，断网读取缓存；主窗口通过 preload 与主进程通信，主进程管理唯一原生岛窗口。课件先流式上传到服务端文件目录，再由客户端下载、验摘要并独立回执。

客户端统一更新由服务端缓存安装包、校验设备权限并通过心跳下发。客户端下载并校验 SHA256 后，把安装交给独立的 Windows 原生助手；助手从本机 updates 目录运行，再次验包并确认就绪，主进程复核更新策略后才退出。助手等待旧进程结束、执行安装并检查安装版的新版本及启动状态，失败写入 install-result.json 并尝试恢复客户端；成功仍以新版心跳为最终回执。排障日志为同目录下的 install-helper.log。Windows 构建使用系统 .NET Framework 编译器生成助手，教室机运行时不需要安装开发工具；助手与安装包均随客户端构建，不能只替换主进程 JS。

更新专项验证使用 pnpm verify:update-download、Windows 下的 pnpm verify:update-installer。显式执行 pnpm verify:client-update:real 会创建临时数据库、班级和独立应用标识，真实安装并升级测试副本，再卸载测试安装，报告保存在 .cache/client-update-real/；它不属于普通冒烟，不会使用真实班级或桌面自动化，也不修改根版本号。传入 --portable --unicode-paths --prefix-version 可覆盖便携运行转安装版、中文空格路径和带 v 的目标版本号。

工程边界

三端契约只放 shared，改后先 pnpm build:shared。
学生不是账号；班级会话读取 Class，教师/管理员读取 User。
功能权限在路由判定，范围与科目权限在 service 判定；前端同规则隐藏入口。
课表以关系模型为真值，所有在线启用选择走 lib/class-plan.ts；周次走 lib/term.ts。
作业/通知使用本地 assignDate；实时使用 SOCKET_EVENTS/SOCKET_ROOMS 和 emitToClass/emitToSession。
数据库备份清单随模型维护，课件文件另行备份。
Electron 保留 CSP 与导航限制，桥接只传纯数据；打包凭据门禁不能取消。
ClassIsland 在线联动已退役，仅保留离线 JSON 导入与设计参考。

完整规则见 AGENTS.md。

开发启动

pnpm install
# 复制 packages/server/.env.example 为 .env，并配置独立 JWT_SECRET 与数据库
pnpm db:generate
pnpm --filter @classhelper/server db:deploy
pnpm build:shared
# 只有明确需要重建演示数据时才运行 pnpm db:seed（会清空业务表）
pnpm dev

后端 4000、Web dev 5173、桌面 dev 5174、官网 5180、文档预览 5181。生产服务端托管已构建的 Web 管理端；详见安装服务端和验收。

5.4 KiB Raw Permalink Blame History Unescape Escape