Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
83 Commits 1 Branch 15 Tags
227117ccb3926aa4ccd720fddb9821bd910524a9
Commit Graph
11 Commits
Author SHA1 Message Date
LoveChengke 817af02357 feat(permissions,clients,ai,system,server,web,client,shared)!: 权限组 + 客户端设备远控与自动更新 + 大模型助手 + 系统诊断（1.3.0） 
功能级准入改为「权限键」，`requireRole` 退成默认模板。

权限组
- 权限目录（39 键：键 / 中文名 / 分类 / 默认角色）收口到 shared，路由挂 requirePermission / requireAnyPermission
- 有效权限每请求实时算，改完分组立刻生效：ADMIN 全集且 permission:manage、system:manage 不可剥夺；
  CLASS_DEVICE 空集（不受分组影响）；有分组 = 并集（因此也能用来**收回**权限）；无分组 = 角色默认模板
- 新增「权限组」页：组增删改、成员分配、生效权限预览
- 班级维度的科目规则（assertCanManageSubjectContent）故意不可被权限组覆盖

客户端设备（ClassHelper 桌面端）
- 设备身份是 deviceKey（首次启动生成的 UUID，saveConfig 拒绝改写、退出登录也保留）
- 心跳走「DB 记状态 + 客户端定时拉」，不引入新的长连接：30 秒一次，在线窗口 90 秒
- 远控命令 shutdown / restart / logoff / lock：服务端有效期 10 分钟，客户端弹默认选中「取消」的对话框、
  60 秒未确认按取消处理，执行后必须回执（重复回执幂等），同一台机器同一条命令只弹一次
- 新增「客户端设备」页：版本一览、一键推送更新、下发远控

客户端安装包由服务端下载并缓存（教室机常常没有外网，浏览器也受 CSP 限制）
- POST /api/update/client/fetch 由服务端下载到 data/client-releases/<版本>/ 并登记 sha256 + size
- 自动安装三条护栏：没有 sha256 就拒收、必须等到非上课且主窗口隐藏满 5 分钟、冒烟模式永不安装

大模型助手：只解析、不落库
- POST /api/ai/interpret 返回**待确认**的结构化动作（建作业 / 发通知 / 叫人），
  真正落库仍调既有端点 —— 权限断言、上课时段紧急通知保护、ClassIsland 推送全部自动复用
- 模型给的 params 用与手动入口**同一份** zod 再校验（模型输出不可信）
- API Key 走 AES-256-GCM（密钥由 JWT_SECRET 经 scrypt 派生）加密存 AppSetting，只进不出
- provider=mock 是离线确定性解析，自动化验收一律用它；每次解析写一条 AiAudit（不含密钥）

系统与运维
- 开发者模式（服务端内存缓存开关，热路径不查库；开启后 500 才附 error.stack）、运行诊断（绝不回传密钥）
- 开机自启动运行期可改：Windows 改 HKCU\...\Run、Linux systemctl enable/disable，
  **非安装形态一律返回 supported:false**，不往开发机的注册表里写自启项
- 服务端侧栏折叠只用 CSS 收拢（不重建 DOM），关怀模式只放大字号与控件、不动任何几何令牌

客户端
- 崩溃自愈：渲染进程挂掉 / 超 10 秒无响应先静默重建主窗口（10 分钟最多 3 次），
  未捕获异常只在「没在上课、没人看着」时才重启进程；冒烟模式绝不重启（会杀掉验证实例）
- 上线补弹离线期间收到的消息只做一次：起点只在「可达 → 不可达」的边界写，恢复时取最近 5 条按时间升序推

发布内容批量
- POST /notifications/bulk、POST /homeworks/bulk：**单班失败不影响整批**，逐班返回结果
- 作业的科目名跨班**按名匹配**已有课程，找不到就整班记失败，绝不自动建课
  （自动建课会把创建者写成任课老师，等于越权改任教关系）
- 通知与作业同口径按「所属日期」归档，新增 /notifications/days 与 /notifications/creators

BREAKING CHANGE: 能不能做某件事不再看角色名，而是看权限键（GET /api/permissions/me）。
未分组的账号按角色默认模板生效，行为与 1.2.0 一致；分组之后生效集合只由组的并集决定。
服务端首次启动会自动应用 1 个数据库迁移（权限组 3 表 / AppSetting / 客户端设备·命令·安装包 /
AiAudit / Notification.assignDate / User.careMode，历史通知按本地日期回填），升级前请先备份。
 2026-10-11 11:49:32 +08:00
LoveChengke 9a38f86cd3 feat(server,web,desktop,shared,deploy,docs): Linux 一键安装与 classhelper 运维命令、更新检查、图表去 echarts，版本统一 1.1.0 
Linux 交付链（新增）
- deploy/install.sh：一键安装器（CLASSHELPER 大字 TUI、native/docker 双形态、向导选安装目录/
  端口/数据库/初始管理员密码）；识别 apt/yum/dnf 只补缺的依赖、建独立系统用户、下载内置 Node
  运行时（glibc < 2.28 的 CentOS 7 自动改用 unofficial-builds 的 glibc-217 构建）、幂等覆盖安装
  （保留 config.env 与 data/，不重置密钥）、全程写 /var/log/classhelper/install.log；
  `--check` 只体检（不需要 root）、`--yes` 无人值守、`--package` 支持内网离线分发。
- deploy/classhelper：运维命令 —— status / doctor / password / backup(list,restore,schedule) /
  upgrade / rollback / start|stop|restart|reload / logs / config / port / key rotate / uninstall /
  completion / help。特权操作一律校验 EUID，关键动作写 /var/log/classhelper/audit.log。
- deploy/tools/admin-cli.mjs：离线账号工具（改密、列账号、VACUUM INTO 一致性快照、哈希回滚），
  直连数据库 —— 服务停机也能救急，不需要先有一个能登录的账号。
- deploy/{classhelper.service,profile.d,logrotate.d,systemd}/ 模板 + Dockerfile.linux-package。
- scripts/dist-server.mjs 增加 --platform linux（根脚本 `pnpm dist:server:linux`），产物
  classhelper-server-linux-x64-<版本>.tar.gz + 同名 .sha256；新增 GitHub Actions workflow 在
  ubuntu runner 上构建并挂 Release（@libsql/linux-* 这类平台相关依赖只能在 Linux 上装）。
- docs/linux-deploy.md：安装 / 运维命令 / 升级回滚 / 备份恢复 / 排障 / 安全清单 /
  Ubuntu 22.04 与 Rocky 9 的验收清单。deploy/install-linux.sh 改为转发壳，不留两份实现。

三处必须知道的取舍（已写进 AGENTS.md §5 第 59 条）
- 配置真身在 /etc/classhelper/config.env，安装目录里的 .env 是指向它的软链：Web 端
  「数据库管理 → 一键切换」改写的是 <安装目录>/.env，而 systemd 注入的是同一份配置 ——
  两处不是同一个文件时，切换会「看起来成功、重启后又连回旧库」。classhelper doctor 有专门断言。
- 升级/回滚替换程序文件用「改名 + 就位」而不是 rm+cp：升级时正在运行的就是 bin/classhelper
  自己，直接删掉同名文件会让 bash 读到半个脚本。
- 交叉构建（在非 Linux 机器上打 Linux 包）会在包内写 .cross-built 标记、doctor 据此提示：
  已核对 @libsql/linux-x64-gnu 与 -musl 就位且无 win32 残留，但 prisma CLI 的原生 schema engine
  是宿主平台的，Web 端「数据库一键切换」那一步存疑；正式产物一律走 CI。

更新检查（此前只在工作区，本次一并提交）
- 服务端 modules/update：由服务端转发 GitHub Releases（Web 端 CSP 不允许直连），离线/限流/超时
  一律收敛成 ok:false + 一句人话，失败结果同样进缓存；?force=1 只对管理员生效（避免刷爆匿名限流）。
- 版本比较放 @classhelper/shared（compareVersions / isNewerVersion），三端共用；服务端版本号
  改由 lib/version.ts 读 package.json，不再在 app.ts 里写字面量。
- Web 端顶栏「检查更新」弹窗、客户端「关于」页的检查更新与诊断信息。

Web 端 / 客户端
- 成绩图表改用自包含的轻量组件（ScoreBarChart / ScoreLineChart），不再全量引入 echarts
  （原先 echarts 占桌面端渲染产物 1.12MB、Web 端 1.13MB）；柱状图是纯 HTML/CSS，折线图是
  viewBox SVG，均无 resize 监听。
- Element Plus 图标改为按需注册（两端各一份 icons.ts），新增 scripts/check-icons.mjs 静态门禁
  并挂进两端 build —— 漏注册的后果是界面静默渲染空白，只在控制台一条 warning。

版本号统一 1.1.0
- 5 份 package.json、deploy/package.runtime.json、.env.example 的 APP_VERSION、
  docker-compose 与两个 Dockerfile 的镜像标签、Linux 安装包名示例、README 首页版本；
- ClassIsland 插件 manifest.yml 与 BridgeService.PluginVersion 同步（verify:classisland-plugin
  有 manifest ↔ code 的一致性断言）；
- 刻意保持不变的是**历史性表述与举例**：docs/mysql.md 的「自 v1.0.0 起内置 MySQL 适配器」、
  shared/utils.ts 讲版本比较用的 1.0.0 / 1.0.0-fix、README 验收表里的实测记录。
 2026-10-05 16:39:38 +08:00
LoveChengke 572295c297 feat(server,web,desktop,shared,deploy,plugin): 数据库管理模块 + 客户端深色模式/设置拆子路由/首启引导，版本统一 1.0.0 
- 服务端新增 database 模块（/api/database/*，仅 ADMIN）：全库 JSON 快照（备份 / 恢复 / 导入导出 / 定时备份
  共用同一格式，14 张表按拓扑序导出、恢复时关外键检查）、连接测试与目标库校验、一键 SQLite ⇄ MySQL 切换
  （备份 → 导出 → 测试连接 → 校验空库 → 改 schema → 子进程 generate / tsc / db push → 写数据，全部成功才改写
  .env，中途失败回滚 schema）；XML 快照与 SQLite 数据文件均可下载；打包形态随包带上 prisma CLI 与 typescript
  （prisma-client 生成物是 .ts，需再编进 dist/generated，安装包因之变大）
- Web 管理端新增「数据库管理」页（仅管理员），并加首次登录新手引导（el-tour，可跳过、可随时重看，版本号写
  localStorage，改版后老用户会再收到一次）
- 客户端设置改版：侧边栏改为分组折叠菜单，设置拆成 6 个子路由
  （/settings/{general,appearance,island,reminder,account,about}），新增深色模式（主题持久化到主进程配置，
  主窗口底色跟主题走，避免"先白后黑"闪一下），新增「关于」页（应用信息 / 诊断信息）
- 客户端新增首启六步引导（OnboardingWelcome，状态存主进程配置 onboardingDone）
- 客户端主窗口初始尺寸与 ClassIsland 对齐（1242x582 / minHeight 540 / 居中）
- 版本号统一提升到 1.0.0：5 个 package.json、部署配置与镜像标签（.env.example / docker-compose / Dockerfile）、
  服务端 /health 与首页、插件 manifest.yml 与 BridgeService.PluginVersion、文档里的安装包名
- 文档与验收同步：AGENTS.md 补第 37~51 条约定（深色主题实现边界、设置子路由、数据库管理三件事、侧栏与窗口
  尺寸、引导在自动化里的判据等），README 补「数据库管理 / 新手引导 / 设置改版」三节；verify:e2e 增补 13 条
  数据库管理用例，客户端冒烟与 Web UI 冒烟跟进子路由、深色主题、侧栏与引导

验证：pnpm lint 0 error；pnpm typecheck 全过；verify:e2e 186/186；verify:classisland-plugin 68/68；
build:desktop 通过（含产物凭据门禁）；verify:desktop 99/102（3 项为上课时段下的"真实通知链路"用例，
客户端按产品规则暂存普通通知所致，见下）；插件 dotnet 编译 0 错误。

注：verify:desktop 的「真实通知链路 / 标记已读」三项要求当前不在上课时段——本次运行时种子课表恰有
「周五 10:55-11:40 生物」正在进行，客户端正确地暂存了普通通知（AGENTS.md 第 18 条），属时间相关用例，
与本次改动无关。
 2026-10-02 11:18:47 +08:00
LoveChengke 3880eee08e feat(desktop,island,shared): 灵动岛支持多条通知竖排列表 + 触摸模式 + 收回动画，产物加凭据门禁 
灵动岛列表：多条通知时展开为竖排列表，默认显示 3 条，点「展开更多」铺到屏幕容纳
上限，放不下的收进「更多请前往应用内操作」。卡片高度由主进程与渲染进程各算一次
同一个数 —— 度量表 ISLAND_LIST_METRICS 与排序权重 PRIORITY_RANK 放在 shared，
窗口包围盒随之长高（不够高会把底部按钮裁掉）。

触摸模式：触摸屏上手指既不产生 mousemove、也不移动系统光标，原先两条命中链路都会
让窗口永远停在穿透态、手指点不开岛。现按 navigator.maxTouchPoints 上报后，主进程把
窗口贴合岛体并始终接收输入；非触摸屏机器完全不走这条路。

收回动画：main 先发 island:closing，渲染进程形变收敛后回 closing-done 才淡出，
不再靠猜时长（rAF 被节流时会把卡片缩到一半窗口就没了）。

安全门禁：新增 scripts/check-bundle-secrets.mjs 并接进 build:desktop ——
dist 产物会被打进 app.asar 发到每台学生机、且可解包，冒烟凭据一律改由环境变量注入，
产物里出现种子口令即构建失败。
 2026-10-02 00:25:10 +08:00
LoveChengke 7536abfc95 feat(homeworks,island,classisland,desktop,web,server): 作业按天查看与教室机器录入 + 提醒上课时段暂存规则 + 灵动岛边距/跟随鼠标屏幕 
- 作业：新增 Homework.assignDate（本地日期 YYYY-MM-DD；UTC 切片在晚上会把今天的作业算成明天），列表按天过滤与排序，新增 GET /homeworks?date= 与 GET /homeworks/days（日期高亮）供客户端与 Web 共用；客户端作业页改为"看作业 + 录作业"（不再显示完成状态），支持快捷短语（存本机配置，「设置 → 作业录入」可增删/恢复默认）
- 教室机器录入：POST /homeworks 去掉 requireRole，权限下沉到 homeworks.service（staff 或本班班级账号）；班级账号的 sub 是班级 id，写 createdBy 前换成该班班主任，避免撞 User 外键
- 提醒类型：ClassIslandPush.kind（notification / call）。通知类上课时段暂存、下课补弹，叫人/紧急立即弹；客户端灵动岛与 ClassIsland 插件共用同一套规则
- 灵动岛：新增 marginX / marginY（默认仍 8px，不动老外观）与「跟随鼠标屏幕」；文案统一成"灵动岛 / ClassIsland"
- 设置页：新增「ClassIsland 联动」（联动状态 + 通知模式）与「作业录入」分区
- 校验：verify:e2e 增补 assignDate 默认当天 / ?date= 过滤 / days / 非法日期 422 / 班级账号录入 201 与跨班 403；verify:classisland 与插件静态契约增补上课时段暂存断言（57/57）
- 文档：README 与 AGENTS.md 同步（作业按天、上课时段策略、两个方向的开关表、新增踩坑）

门禁：pnpm lint 0 error、pnpm typecheck 四包通过、verify:classisland-plugin 57/57 通过。
未跑：verify:e2e / verify:classisland（需后端启动）、verify:web / verify:desktop（需先构建产物）。
 2026-09-27 16:34:01 +08:00
LoveChengke d0830f6830 feat(integrations,classisland,server,web,desktop): ClassIsland 联动插件——上报课表与上课状态、下发提醒并回执、教室端推送通道 
教室机器上的 ClassIsland 现在可以直接和班级小助手互通：插件走 /api/integrations/classisland/*，用设备令牌（X-ClassIsland-Token，库里只存 sha256）独立鉴权，不占用 JWT 通道。

- 服务端：新增 integrations 模块（上报 / 待弹出 / 回执 / 课表镜像 / 回写），两个迁移（设备令牌表、Class.notificationChannel）；通知、叫人、联动页下发统一复用 pushToClassIsland，避免"某个页面发的通知不联动"
- 插件：packages/classisland-plugin（.NET 8，独立于 pnpm workspace）——BridgeService 上报与提醒轮询、ScheduleMapper/ClassPlanWriter 课表镜像、Avalonia 设置页、ClassHelperNotificationProvider 在 ClassIsland 上弹出提醒；本地/内网地址强制直连，躲开系统代理返回的假 404
- 客户端：设置页可选提醒通道（both / client / classisland），并订阅相应实时事件
- Web 端：新增「ClassIsland 联动」页（设备管理与提醒下发）
- 校验与打包：verify:classisland（需后端）、verify:classisland-plugin（静态契约 54 项）、build/dist:classisland-plugin 产出 .cipx
- 文档：README 与 AGENTS.md 同步新增联动说明，docs/screenshots/classisland 留三张真机截图

门禁：pnpm lint 0 error、pnpm typecheck 四包通过、verify:classisland-plugin 54/54 通过。运行期仍需在装了 ClassIsland 的机器上实测（步骤见 AGENTS.md §8）。
 2026-09-27 14:59:12 +08:00
LoveChengke 11008928a1 fix(island,homework,schedule,web): 16 项反馈修复（联合通知点不开 / 设置不生效 / 红点位置 / 看板当天且铺满 / 单双周与周数可调 / Web 手机端与批量通知等） 
一、灵动岛
- ①「紧急通知后来了新作业，收起再点开不了新作业」根因有二，都已修：
  (a) active 仍是紧急那条，点击只会反复打开它 —— 现在点击胶囊优先打开**最新**那条未处理消息（队列里更晚的）；
  (b) 上课时段 syncWindow 会把普通通知立刻隐藏（表现为点了没反应）—— 新增 explicitShowId，
      "用户主动点开"的那条守卫放行（岛完全隐藏时仍严格不打扰）。
  冒烟新增「紧急通知后来了新作业：收起再点击打开的是新作业（联合通知回归）」。
- ② 设置实时预览/保存：补「设置页真实链路」断言（window.desktop.islandSetAppearance → IPC → 主进程 →
  渲染进程 CSS 变量 + 窗口尺寸），并断言"岛显示中改尺寸立即生效"（实测均通过）。
- ③ 未读红点移到「通知」图标右上角（此前在文字后面），并加 DOM 几何断言（dx>0 且 dy<0，
  没有未读时自动造一条未读通知再断言、断言后删除）。
- 冒烟稳定性：新增 island.setBlurCollapseEnabled()（默认开），测试期间关掉"失焦收起"，
  避免系统抢焦点导致展开态被收回的随机失败；专门验证失焦的用例仍临时打开。

二、作业看板（学生端）
- ⑥ 只看当天：新增「只看今天」开关（默认开），按 createdAt 的本地日期过滤，昨天的过期作业不再混入。
- ⑧ 完整显示：卡片同时渲染标题 + 作业要求全文（列表模式也加「作业要求」列）。
- ⑨ 铺满不滚动：看板外层高度固定 + overflow hidden，按内容/可用高度算缩放系数用 transform: scale 适配
  （工具栏显示当前缩放比例），页面本身不出现滚动条。
- ⑦ 全屏看板标题栏用 #header 插槽：标题左对齐、当天日期时间绝对居中（受「显示时间」开关控制，每分钟刷新）。

三、课表与周数
- ⑤ 学期周数可调：新增 Class.termWeeks（默认 20，迁移 + 维护脚本），班主任在班级管理里改；
  GET /api/dashboard/term?classId= 返回该班 maxWeek，课表周次下拉与新建课表的默认 weekEnd 都按它来
  （不再固定 30 周）。
- ⑩ 课表管理只保留「导入 ClassIsland 课程表」入口（时间表由课程表 JSON 的 TimeLayouts 一并带入），
  「导入时间配置」按钮下线；ui-smoke 第 7.7 段改为断言新弹窗（解析 4 行 + 单双周标签 + 旧入口已下线）。

四、以班级为单位（⑬）与 Web 端
- 个人学生账号登录停用：POST /api/auth/login 对 role=STUDENT 返回 403（改用班级码 + 班级密码）；
  学生行仍作为个人数据记录键由班级会话代全班读写；e2e 全面切换到班级会话并新增该断言。
- ④ 作业科目过少：新增共享 SUBJECT_CATALOG（16 个常见科目）+ 种子课程扩到全科目；
  Web 作业发布弹窗可选「其他科目（新建）」，提交前自动建课（同名复用）。
- ⑪ 通知支持多班批量发布（多选 + 逐班发布 + 汇总结果 + 二次确认覆盖所有选中班）；
  ⑫ 单班只显示已读情况、跨班才显示已读率；⑭ 手机端课表可横向滚动看全 7 天；
  ⑮ 手机端已连接不再显示孤立绿点（仅未连接时显示文字标签）；⑯ 手机端「叫人/发布通知」按钮同宽左对齐；
  ⑬ Web 学生管理去掉「用户名」列（新建自动生成学号式用户名，导入仍支持显式指定）。

验证：verify:e2e 149/149、verify:web 20/20、verify:desktop 75/75（复跑 68/68，打包便携版 75/75 packaged=true）、
typecheck / lint / format 全绿；服务端与 Web 已重新打包并部署到本机安装目录。
 2026-09-13 08:39:11 +08:00
LoveChengke b8ef5d8dbb feat(island,homework,schedule): 灵动岛点开修复+胶囊类型汇总 · 作业看板与未交名单 · 单双周课表与 ClassIsland 课程表导入 
一、灵动岛（用户反馈的三处"点不开"全部修复）
- 非紧急叫人：上课时段仍以胶囊保持可见、可点开（不再只进队列导致屏幕上什么都没有）；
  新增 isOpenable()：紧急消息 + 任何"叫人"都允许点开，但普通叫人不会自动展开打断课堂。
- 紧急叫人收起后再点：命中改为"主进程按光标位置兜底校正"（上一轮的 island:set-hit-rect 轮询），
  本轮补齐叫人类专项回归（展开 → 收起 → 再次点开）。
- 设置页预览：新增 preview 通道 —— 示例岛直接展开、失焦不收起、30 秒自行消失、关掉不残留。
- 收起态胶囊汇总消息类型：多条时显示「新消息：叫人/作业/通知（共 3 条）」+「点击查看」+ 类型小标签。
- 顺带修掉两个真问题：胶囊态收到新消息会把上一条静默顶掉（现在一律回队）；
  syncWindow 的上课时段守卫只认"紧急"导致普通叫人被藏掉。
- 性能：岛体矩形上报限流（~10 次/秒 + 尾随补发），修掉每帧 IPC 导致的开合采样骤降。

二、作业（学生端 + Web 教师端）
- 新增**看板模式**：按科目分卡片、点卡片放大全屏、工具栏可切「看板/列表」、
  开关「显示时间」、拖「看板字号」（11–28px），偏好持久化到客户端配置 homeworkBoard。
- 去掉「全班标记完成」，改为**未交名单**：勾选没交的同学，其余自动标记已交；
  新增 GET/PATCH /api/homeworks/:id/submissions（教师与班级设备可用，普通学生 403）。

三、课表单双周 + ClassIsland 课程表导入
- Schedule 新增 weekParity（ALL/ODD/EVEN）+ 迁移；周视图与上课判定按「第 1 周=单周」过滤，
  历史数据默认 ALL 行为不变；Web 手动新增/编辑课表可选单双周，学生端课表打「单周/双周」标签。
- 修复既有 P0 bug：ClassIsland 真实档案里 TimeLayouts 是 "Guid → { Name, Layouts }" 字典，
  旧解析器只认数组/.items，导致**真实导出完全导不进来**；现已按真实形态解析（并兼容旧写法），
  同时补上 TimeType=3（行动）映射。
- 新增 ClassIsland 课程表（ClassPlan）导入：解析 TimeRule.WeekCountDiv/WeekCountDivTotal → 单双周，
  Classes[i] 对齐第 i 个 TimeType=0 的时间点，Subjects 映射科目（缺失自动补建课程），
  星期 0=周日 换算为 1=周一 … 7=周日；replace/merge 两种模式，预览只解析不写库。
- 新增维护脚本 packages/server/scripts/apply-parity-column.cjs（手工覆盖 dist 部署时补列用）。

验证：verify:e2e 148/148（新增单双周 12 项 + 课程表导入 5 项）、verify:desktop 71/71（复跑 65/65）、
verify:web 20/20、typecheck / lint / format 全绿；服务端与 Web 已重新打包并部署到本机安装目录。
 2026-09-12 23:48:59 +08:00
LoveChengke 3f2b135211 feat(island): 参考 WinIsland 重写灵动岛（squircle + 三种底 + 字号系数排版 + 空闲细缝） 
参考: 工作目录 WinIsland-master.zip（Rust/Direct2D 的 Windows 动态岛），
     逐项提取的设计 token 归档在 docs/winisland-design-tokens.md。

视觉与造型:
- 连续圆角 squircle（新增 island/squircle.ts，超椭圆角，对齐 WinIsland utils/shape.rs），
  胶囊半径 = min(圆角, h/2)（满圆角），展开卡 = min(48*圆角/20, w/2, h/2)（WinIsland expanded_island_radius）
- 三种底: 纯黑（WinIsland default）/ 毛玻璃（win.setBackgroundMaterial('acrylic')，等价 HostBackdropBrush）/
  主题色渐变；描边 1px 白 alpha .118（纯黑）/.157（玻璃），展开投影 0 2px 3px rgba(0,0,0,.11)
- Apple 系统色: 强调蓝 #0a84ff、警告橙 #ff9f0a、危险红 #ff453a；白字 alpha 分级 .92/.72/.58
- 状态色只做"内层微染 + 描边 + 徽标"，不外溢（保持外圈偏红 = 0）

排版（本次重点）:
- 基础字号 11–20px，岛内**所有文本** = 基础字号 × 排版系数
  （标题 1.08 / 正文 0.95 / 次要 0.78 / 徽标与按钮 0.76 / 胶囊标题 0.92 / 胶囊副题 0.74），
  与 WinIsland 的 font_size 模型一致；实测 13→19px 全部文本倍率 1.462（=19/13）
- 图标、按钮高度、间距也由字号推导，改字号不会溢出

形态与设置:
- 尺寸基准对齐 WinIsland 比例（胶囊 216x34 基准、展开 +156/+186 等），卡片 = 窗口 - 2*5px 且水平居中
- 6 个停靠位（顶/底 × 左/中/右，对齐 WinIsland DockPosition）
- 新增"空闲细缝"（WinIsland hidden_width）：空闲留一条 6px 宽竖条，来消息自动展开
- 所有设置依旧"改即生效"；顺带修掉 hide() 用 skipWindow 绕过 syncWindow 导致细缝不生效的问题

验证（verify:desktop 49 → 53 项，全绿）:
- 字号即时生效: 13px→19px 五项文本倍率全部 1.462
- 风格即时生效: 纯黑 fill=rgb(0,0,0)/材质 none；毛玻璃 fill=rgba(10,10,14,.59)/材质 acrylic；主题色 fill=rgb(11,11,15)
- 空闲细缝: 16x36 → 来消息 268x44；关闭后完全隐藏
- 6 锚点、开合不震动（0.00px / 无过冲）、截图 6 张（比例偏差 0.000、外圈偏红 0）全部保持
- verify:e2e 133/133、verify:web 19/19 不受影响；截图归档到 docs/screenshots/island/

工程发现: Windows 对透明窗口有约 36px 最小高度（请求 32px 实际 36px），
空闲细缝高度据此设下限并写入注释与 README。
 2026-09-12 17:41:05 +08:00
LoveChengke 0dcab6f369 feat(client): 灵动岛个性化设置（需求 2）、形变抖动修复（需求 4）、关闭到系统托盘与退出清理（需求 5） 
## 需求 2：设置页个性化（实时生效 + 持久化）

- 新增 `IslandAppearance`（shared 类型）+ `DEFAULT_ISLAND_APPEARANCE` / `ISLAND_APPEARANCE_RANGES` /
  `ISLAND_POSITIONS`：高度 36–72、宽度 220–420、圆角 8–32、不透明度 0.4–1、字号 11–18、
  动画速度 0.5–2、主题色、显示位置（顶部居中/左上/右上/底部居中）、动画开关、始终置顶。
- 客户端 `config.json` 增加 `island` 字段（`normalizeIslandAppearance` 夹紧越界值；
  旧配置无该字段时自动补默认值，向后兼容）；`SettingsView` 新增「灵动岛 · 个性化」面板：
  滑块/取色器/开关/位置选择 + 「保存设置 / 预览效果 / 恢复默认」，拖动即实时预览。
- 主进程 `island.setAppearance()`：窗口尺寸按外观联动（展开卡按差值同步放大，内容用 flex + 溢出滚动承载）、
  透明度、置顶、动画开关与速度、停靠位置实时生效，并把外观通过 `island:appearance` 下发给灵动岛渲染进程；
  渲染进程用 CSS 变量（`--island-w/-h/-radius/-font/-accent`）驱动卡片尺寸、圆角、字号与强调色。

## 需求 4：形变抖动修复

- 窗口尺寸动画改为**单条帧循环**（优先 `requestAnimationFrame`，主进程无该全局时退化为 ~60fps 定时器）；
  新动画取消上一条并作废令牌；结束对齐最终尺寸（消除 1px 累积误差）；**展开动画结束后才取焦点**。
- 卡片保持固定尺寸 + 顶部居中锚定（此前已修），只让窗口露出/裁切，形变时内容不参与重排。
- 冒烟新增断言：收回过程窗口宽度**单调收缩**（实测 362→330→305→288→274→270→268…）、
  卡片上边缘波动 **0px**、卡片布局宽度只取 `396/260` 两个固定值；连续 5 次快速开合后状态与尺寸稳定。

## 需求 5：关闭到系统托盘 + 退出清理

- 新增 `main/tray.ts`：托盘图标（`public/tray.png`，`pnpm icons` 会自动同步）、右键菜单
  「显示主窗口 / 隐藏到托盘 / 退出班级小助手」、左键单击/双击恢复窗口。
- `main/index.ts`：`close` → `preventDefault + hide`（关闭窗口不退出，后台继续接收通知，日志留痕）；
  `window-all-closed` 不再退出；`quitApp()` 与 `before-quit`/`will-quit` 统一走
  `shutdownResources()`：销毁托盘 → 销毁灵动岛（帧循环/定时器）→ 销毁全部窗口
  （渲染进程随之释放 Socket.IO 连接与 IndexedDB 句柄）→ `app.quit()` + `app.exit(0)` 兜底。
- 冒烟新增断言：关闭后 `visible=false / destroyed=false / 进程存活=true`；清理后 `托盘=false / 灵动岛=false`。

## 验证

- `pnpm verify:desktop` **40/40** ✅（新增 6 项：个性化外观生效、调整尺寸后内容不溢出、收回不抖动、
  快速开合稳定、关闭到托盘、退出前资源清理）
- `pnpm verify:e2e` **82/82** ✅、`pnpm verify:web` **17/17** ✅（回归无破坏）
- `pnpm lint` / `format:check` / `typecheck` 全绿
- 顺带修复：托盘/关闭处理器此前挂在冒烟验证之后，导致冒烟模式关闭窗口会真的销毁窗口
  （现已调整为在冒烟前挂载）；`smoke.mjs` 配置目录按进程号隔离，避免上次异常退出的目录占用导致启动失败。
 2026-09-12 15:19:13 +08:00
LoveChengke 6e4c7c1050 feat(desktop-client): 阶段4-6 Electron EXE 客户端（登录/课表/作业/通知/成绩/设置 + Socket.IO 实时 + IndexedDB 离线缓存与自动同步 + electron-builder 打包） 2026-09-11 22:46:31 +08:00