feat(courseware,docs): 完善课件传输与岛编辑并统一全仓文档
- 增加课件上传、班级可见范围、设备补收与传输进度 - 整合自定义灵动岛编辑器和相关客户端交互 - 同步三端契约、数据库迁移、部署配置与隔离回归 - 按源码统一文档与官网说明，移除过时任务书和审查记录 - 保持产品版本为 1.4.0
This commit is contained in:
LoveChengke committed
1 parent
536379036a
commit
c7f215a09c
127 files changed
+4334
-8482
No files matched your search
@@ -1,210 +0,0 @@
|
||||
# 2026-10-17 实施与验收记录
|
||||
|
||||
## 阶段
|
||||
|
||||
1. 数据与共享契约：关系化时间点、日课表、群组、预定层；权限范围与内置组；周数设置。
|
||||
2. 服务端：唯一课表解析器与兼容门面、事务编辑；转出过滤、聚合成绩、自动升级、下载状态。
|
||||
3. Web：时间表/日课表编辑、只读名单、日期归档、设置与进度。
|
||||
4. 客户端：心跳重置、立即远控（冒烟假执行）、更新进度、本机组件方案与编辑器。
|
||||
5. 验证与文档：临时数据库验证、静态检查、后台冒烟；明确记录未通过与未执行项目。
|
||||
|
||||
## 架构选择
|
||||
|
||||
- 不引入 Profile：共享时间表与班级日课表替代单机档案。
|
||||
- 旧 Schedule 保留迁移来源，通过兼容门面投影新模型；迁移保留起止周、单双周与地点，无法从旧数据恢复原来的群组、临时层或时间点名称。
|
||||
- 范围保存在 PermissionGroup，多个分组取范围并集；部用逗号分隔的年级字符串，空范围不放行。
|
||||
- 周次上限取 AppSetting，默认 30、允许 1–60；离线取默认。
|
||||
- 岛方案保存在本机 config.json；天气无离线数据源，本轮不做。
|
||||
- 自动升级以年份作事务幂等键，升级前存全库快照；新学年保留周数上限、开学日重置为当年 9 月 1 日，清除旧逐周区间。新班不复制任课关系。
|
||||
|
||||
## 实测记录
|
||||
|
||||
- `pnpm lint`：0 error、0 warning；全仓类型检查、完整构建、图标门禁与客户端产物凭据检查通过。
|
||||
- `pnpm verify:e2e`：243/243。根入口改为全新临时 SQLite 库与带前缀账号，禁止外网；不会连到本机真实服务。
|
||||
- `pnpm verify:v14`：35/35。覆盖四周轮换、四种时间点、外键排序与下一节时间、跨班课程、换课不改原表、预定优先级、集体成绩与实时隐私、转出学生的名单/成绩/叫人/未交入口、四岗位越权、41 周生成、兼容 CRUD、上游导入幂等、自启动假适配器。年度升级另在专用临时库并发运行两次，确认同年幂等、快照存在、其余班只升一级、新班无班主任与任课关系。
|
||||
- `pnpm verify:web`：43/43。包含新增日课表整表保存、时间表编辑入口、自启动不可用原因、升级设置与转出分区；全程隐藏、无焦点。
|
||||
- 桌面快速检查 24/24；视觉检查 99/99，并通过退出后的第二次快速启动 24/24。均使用独立 userData，远控与安装器不会执行系统操作。
|
||||
- 文档站严格构建通过，0 warning、0 error。
|
||||
- 原库迁移前备份：`.cache/dev-before-v14-20261017092353.db`。先在副本验证，再应用本机迁移。用户 3、班级 5、学生 18、课程 53、旧课表 89、成绩 98、作业 16、通知 23 的行数全部保留；89 条旧课表均有关系化映射，生成 450 张按周日课表，外键检查 0 异常。历史 JSON 时间表的 3 个时间点也全部补齐。
|
||||
- 视觉截图：`.cache/v14-island-shots/`（固定模式各形态、窗口全图、`custom-editor.png`、`custom-alert.png`）；Web 手机截图：`.cache/v14-web-shots/`。它们是本次验收留档，不作为官网素材。
|
||||
- 未打包、未改版本、未改 releases；未真实修改注册表/systemd，未在业务库或演示库执行年度升级，未真实执行关机/重启/注销/锁屏。自启动安装形态使用可注入的系统适配器检查开关与重建控制器后回读。
|
||||
|
||||
## 两处 bug 的定位
|
||||
|
||||
### 换服务端后迟迟不上报
|
||||
|
||||
旧 `client-agent.ts` 在收到 401/403 后把唯一计时器排到五分钟后，配置保存/登录成功没有事件重排，旧 token 又可能继续保留。用两个本机假服务端复现：第一个明确返回 401，切换第二个后必须清空旧 token，登录新 token 后自动恢复心跳。修复为四个显式配置事件、状态清空与 epoch 隔离；迟到响应不能覆盖新实例状态。设备 key 不重建，命令回执固定发回接收命令时的地址。
|
||||
|
||||
### 自启动入口与状态不一致
|
||||
|
||||
旧 Web 没有调用现有自启动 API 的可达设置页。Windows 服务端还从 `dirname(process.execPath)` 找 `start.cmd`，安装包里的 Node 在 runtime 子目录，而安装器把脚本放在安装根，导致错误地识别为开发环境。旧状态只检查 Run 项存在，没有核对值。现在从服务端目录定位安装根，并校验安装器的 InstallDir，比较完整 Run 值；写入后重新读取并校验。开发/免安装/容器环境明确返回不可用原因。Web 实测开发环境按钮禁用且原因可见，安装形态开关与回读由假系统适配器验证。
|
||||
|
||||
## 迁移与兼容的取舍
|
||||
|
||||
- 采用新模型投影的兼容门面，不双写业务表。旧 Schedule 与 TimeLayout.items 只作迁移审计来源，后续编辑不会再读取它们复活被删除的课程。种子初始化另有一次物化过程。
|
||||
- 旧行按实际教学周展开，因此不同周次范围可以共存；同班同日、同周、完全相同起止时间的旧冲突记录只取最小 id。旧数据没有的群组/临时层/时间点名称无法恢复；冲突原行保留可追溯。
|
||||
- 老时间配置导入同样写关系化时间点，并要求 timetable:manage；同起点但不同类型的课间和课程保留独立外键。整套 ClassIsland 课表导入仍可由本班班主任使用，只建立班级自有作息，不把 TeacherName 当成任课授权。
|
||||
- 上游导入直接保留 1–9 周三元组、四种时间点、空课、停用、换课标记、群组、预定和临时选择，不经单双周中间格式。稳定导入 id 使 merge 重复导入不复制整套课表。
|
||||
- 全校周数默认 30、上限 60，由 shared 取值函数统一归一化；旧 MAX_TERM_WEEK 仅保留为弃用的外部兼容导出，内部不再使用。
|
||||
- 不引入 Profile、天气、.NET 或插件依赖；部使用 PermissionGroup.scopeValue 的逗号分隔年级，空范围不放行。范围并集不会替代 Course.teacherId 的科目写权限。
|
||||
|
||||
## 对两项架构判断的答复
|
||||
|
||||
本机方案存 config.json 的决定予以保留：这是设备个体偏好，不增加服务端配置或同步通道。通知/作业/叫人使用同一个 IslandApp.vue 实例及原状态机，custom 模式仅通过 Teleport 把它放到组件槽；不是固定层盖在自定义层上，也没有第二个岛窗口。主要行禁用提醒时回落到允许提醒的第一行；全部禁用时不展示提醒槽。多种内容仍服从原队列/列表规则，不会在多个位置重复投递。
|
||||
|
||||
## 自定义灵动岛界面重写
|
||||
|
||||
按后续反馈，将组件栏明确收进同一个岛体：普通组件和提醒共用外层背景、圆角与阴影，嵌入提醒只保留原渲染器的内容、动画与操作，去掉原卡片的第二层背景形状。每行的普通组件与提醒上下排布，岛宽取两者中较宽的一项，避免横向累加造成留白。没有消息的通知、作业、叫人组件不占位。固定模式继续使用原有完整卡片。
|
||||
|
||||
编辑界面重写为左侧组件库、中央岛内预览、右侧当前对象设置。组件库按日常信息、消息提醒、组合容器分组，采用统一 SVG 线性图标；组件设置分为内容、外观、高级三个标签，独立外观关闭时禁用覆盖项。行名称、间距、主要行和通知开关放在行设置中，整体配色、缩放和多行选项放在整体外观中；方案复制与导入导出收在顶部菜单。
|
||||
|
||||
主设置页以两个选项选择经典或自定义灵动岛，自定义模式直接进入「编辑岛内组件」，隐藏不适用的固定宽高等选项。退出全屏编辑时，先在隐藏期间等待常态组件重新测量，避免保留行工具栏的空白高度；自然宽度测量也不再被上一轮获准窗口宽度撑住。分离多行时按实际外层留白计算尺寸。
|
||||
|
||||
新增回归检查设置标签隔离、共用岛体且无第二层形状、无消息不占位，以及退出编辑后的自然内容尺寸；关闭提醒通过原渲染器的「知道了」按钮验证。最终截图留档在 `.cache/island-rewrite-final-shots/`。
|
||||
|
||||
本轮视觉回归通过 102/102，随后补充的岛宽修正与展开可见性检查通过后台 28/28，并通过二次启动。后台最终几何检查先等待原渲染器的形变兜底和尺寸防抖完成，避免在隐藏窗口的中间动画帧判断最终尺寸。客户端构建、类型检查、lint、改动文件格式检查及文档严格构建均通过。
|
||||
|
||||
## 可选常驻岛
|
||||
|
||||
本机 `islandLayout.residentEnabled` 默认关闭，仅在 custom 模式生效。开启后，现有方案 rows 作为收起内容，新增 expandedRows 保存没有通知时点击展开的内容；两套内容在同一编辑器中切换编辑，随方案复制、导入导出和本机配置一起保存。旧配置自动补齐展开布局，不改变原来的常驻选择。
|
||||
|
||||
按本次产品要求，常驻模式中普通、紧急和叫人消息都先提示右侧铃铛及去重后的数量，点击常驻内容、铃铛或按 Enter/空格才展开通知列表；上课时允许主动查看。没有消息时展开自定义内容，收起、处理完成及通知撤回后保留常驻岛。经典模式与关闭常驻的自定义模式继续使用原提醒规则。
|
||||
|
||||
铃铛固定占位，避免收消息时内容横移。普通组件默认继承行的垂直居中对齐；原先无条件 align-self:stretch 会使不同字号文字从顶部排版，现只在父容器有宽度且明确配置时应用覆盖对齐。时钟采用等宽数字，分隔符保持固定线高，展开页标题与收起按钮在同一基准线上。设置页重新获得焦点时读回本机配置，避免编辑器内改常驻选项后主设置页显示旧值。
|
||||
|
||||
新增隔离检查覆盖旧配置兼容、空闲常驻、铃铛与文本对齐、无消息展开/收起、普通与紧急消息点击展示、同 id 去重、课堂中查看、键盘展开、处理完成后的窗口几何、空闲展开时新消息提示、两套内容独立编辑和关闭常驻恢复经典模式。截图留档于 `.cache/resident-island-shots/`。
|
||||
|
||||
### 再次核对 ClassIsland 尺寸与避让设置
|
||||
|
||||
2026-10-17 重新从 GitHub master 读取 [经典主题](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/XamlThemes/ClassicTheme/Styles.axaml)、[Fluent 主题](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/XamlThemes/FluentTheme/Styles.axaml)、[默认设置](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Models/Settings.cs)、[窗口设置页](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Views/SettingPages/WindowSettingsPage.axaml)、[外观设置页](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Views/SettingPages/AppearanceSettingsPage.axaml)及 [行样式](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Controls/MainWindowLine.axaml)。主题行高为 40、内容左右留白 12；四档字体为 14/16/18/20，时钟用强调字号 18；默认圆角 8、背景不透明度 0.5、缩放 1、行距 5。共享 CLASSISLAND_ISLAND_METRICS 作为唯一尺寸与默认值表，常驻行移除上下 12px 留白。缩放、圆角与背景透明度范围也与上游一致。
|
||||
|
||||
原生窗口复用现有光标轮询，在常驻背景移入时降低到 5% 不透明度并开启点击穿透，移出恢复；支持反转及关闭。保留独立的右侧交互入口：无消息时是小展开箭头，有消息时显示铃铛与数量。它不触发避让，避免和此前点击查看通知的要求冲突；编辑、展开和触笔/触摸后 1 秒内暂停避让。这是为本产品保留交互入口的明确适配，上游原始主界面默认整体穿透。未引入 RawInput/.NET 依赖，轮询方式对应上游默认 UseRawInput=false。窗口隐藏或淡化不清空消息队列。
|
||||
|
||||
补充后台检查实测常驻行 40px、原生 setOpacity 的 5% 比例、点击穿透状态、移出恢复、反转/关闭淡化、右侧入口与触摸宽限期。源码缓存和截图分别留在 `.cache/classisland-current/`、`.cache/resident-island-ci-shots/`。
|
||||
|
||||
最终构建视觉验收 118/118，随后后台重启检查 43/43、单实例锁和配置句柄释放通过；全仓类型、lint、构建与产物凭据门禁、格式及文档严格检查通过。最终截图为 `.cache/resident-island-ci-final-shots/`，验收日志为 `.cache/resident-island-ci-visual-final.log`。本次不修改业务数据库、不打包或推送发布。
|
||||
|
||||
## 常驻岛界面与动画重写
|
||||
|
||||
按用户反馈重新读取上游 `ClassicTheme/Styles.axaml`、`Controls/MainWindowLine.cs` 与 `Controls/MainWindowLine.axaml`。
|
||||
上游背景宽度过渡为 550ms、`cubic-bezier(0,1,.5,1.1)`，内容使用 200ms 的 SineEaseIn 淡入；行高 40、左右留白 12。
|
||||
本产品需要可交互的通知列表和独立空闲展开页，沿用这些度量、背景曲线与内容淡入，展开页高度也使用同一背景曲线。
|
||||
|
||||
旧问题由三个因素叠加：内嵌提醒仍播放 WinIsland 胶囊弹簧，外层 ResizeObserver 把动画中间帧当成自然尺寸，渲染端与主进程各延迟 120ms 调整窗口；外壳 `overflow:auto` 在两端不同步时出现滚动条。
|
||||
新 `ResidentIsland.vue` 独立渲染常驻内容、空闲页和通知列表，保留既有的消息去重、排序、读回执及按钮动作。
|
||||
经典渲染器保留挂载和心跳，但在常驻模式停止弹簧循环、兜底定时器和命中上报，不再内嵌到常驻岛。
|
||||
|
||||
常驻窗口使用受工作区限制的固定画布，开合不调用逐帧 setBounds，也不再隐藏 320ms 后重新显示。
|
||||
两页内容按各自未变形的 offsetWidth/offsetHeight 测量，保持自己的排版和缩放；只让一个岛壳过渡尺寸。
|
||||
内容自然尺寸、配置缩放、字体加载和窗口 resize 决定目标尺寸。长文字先限制宽度并省略，时间、分隔线和文字成组对齐；多行布局整体适配可用宽高。
|
||||
消息正文限制可见行数，按高度限制列表数量，剩余内容由应用内入口承接；底部动作不被正文挤出，运行界面没有滚动容器。
|
||||
|
||||
原生窗口的 show/hide 通过专用白名单桥同步到渲染器；不可见时直接应用目标几何，避免后台 CSS 动画冻结在中间帧。
|
||||
命中矩形仅在动画期间每 60ms 限流上报，结束时补报；静止时没有动画采样循环。
|
||||
开合期间暂停指针淡化，避免鼠标留在旧展开区域时因过期命中矩形误触发 5% 透明度，造成收起闪烁。
|
||||
Windows 触摸模式使用 Electron setShape：动画开始放开绘制区域，完成后只保留岛体及 8px 投影留白的原生区域，透明画布不再长期吞掉周围桌面输入。进入编辑、关闭常驻或关闭触摸模式时清除区域。
|
||||
|
||||
新增回归覆盖开合窗口矩形恒定、动画帧间隔、所有运行节点无滚动容器、360×260 窄画布与 2.5 倍缩放、底部右侧停靠、长正文及多通知底部动作、触摸输入区域收敛。测试保持隔离配置与本地通知，不连接真实班级。
|
||||
|
||||
本轮视觉验收 123/123，通过连续快速开合与停靠命中检查；1.8 秒取得 109 个动画采样，帧间隔 P95 为 16.8ms，原生窗口矩形只有 1 个。
|
||||
最终补充收起期间错误淡化的回归后，后台检查 49/49；桌面类型检查、全仓 lint、构建及产物凭据门禁、格式和文档严格构建通过。
|
||||
视觉记录与截图为 `.cache/resident-rewrite-final-visual.json`、`.cache/resident-rewrite-final-shots/`，最终构建后台记录为 `.cache/resident-rewrite-delivery-quick.json`。
|
||||
|
||||
## 十项自检
|
||||
|
||||
1. 第三周周三第二节：ClassPlan 的规则与 ClassPlanEntry 的 timeLayoutItemId → `resolveActiveClassPlan` → `loadTermContext/resolveCurrentWeek` → `projectPlan` → `/schedules/active-week` → `refreshIslandSchedule` 的整周 IndexedDB 缓存 → `recomputeClassState` 发送当天课程 → `ComponentNode.vue` 课程表组件。
|
||||
2. 编辑时间点起止时，所有引用该 TimeLayoutItem 外键的课随之改变；只排序改变 position，不改变外键。旧单节时间编辑会先克隆班级日作息，避免误改共享时间表。
|
||||
3. 拖到第二行后，保存到 `<userData>/config.json` 的 `islandLayout.schemes[].rows[].nodes`；仍由 config.ts 的内存缓存、120ms 合并写盘和退出 flush 管理，重启经 getConfig/白名单桥读回。
|
||||
4. 新提醒优先进入 main 且 allowNotifications 的行，否则第一条允许提醒的行；在该行对应内容组件的槽展示，没有对应组件时使用该行默认提醒槽。
|
||||
5. fixed 不挂载 CustomIsland，主进程 reportCustomSize 也先检查 customLayout；原固定窗口、形变路径和默认外观值保留。
|
||||
6. 关闭个人查询后 overview 直接返回聚合 DTO：没有学号、姓名、个人 id、排名或极值；个人明细/排名接口被服务端拒绝。实时成绩广播同样只发 classId 与 collective 刷新标记，避免经 Socket.IO 绕过 HTTP 闸门。少于五人隐藏均值，均值取整，小于三条的分段及可反推补集的比率不披露；前端也清空已有个人数据。
|
||||
7. 8 月 3 日启动时识别最近应执行学年缺记录，写警告并在学期周次页显示预览/补跑；不会静默升级业务库。运行中的服务跨过计划时间才自动执行。年份唯一键与事务保证重入只提交一次，执行前先完成快照。
|
||||
8. 一处 activeStudentWhere/isActiveStudent 规则，应用于名单/班级详情/成绩/作业状态/叫人/通知已读/导入匹配/班级会话与 AI 叫人选择。历史归档/转出专页显式读取历史状态。漏一个入口会造成历史身份重新被选中或历史个人成绩外露，因此回归有服务端负断言。
|
||||
9. 级长的班级列表与接口断言先经 access.ts → permission-scope.ts 取 GRADE/DIVISION 范围，越界接口返回 403；前端菜单和班级筛选只用于展示。科目内容仍由任课关系独立裁决。
|
||||
10. 地址变化 → server-changed 清 token/失败/退避与待排计时器 → token-changed/login 立即排心跳 → 新服务器鉴权成功后按稳定 deviceKey 登记 → lastHeartbeatAt 写入并进入在线列表。epoch 丢弃旧请求的迟到结果。
|
||||
|
||||
## 验收中修复的边界
|
||||
|
||||
- 兼容投影保留单双周元数据；清理测试导入时删除整张测试日课表，空课表不会被隐式回退。
|
||||
- Windows libsql 同库连接探测复用当前活跃连接；此前完整回归在跨适配器探测处出现 0xC0000005，修复后完整离线回归通过。临时库目录额外带时间戳，避免进程号复用撞到此前的验收库。
|
||||
- 新旧课表界面与岛桥接共用的缓存仍保存整周数据，岛组件只接收当天投影，避免当天响应覆盖整周离线缓存。
|
||||
- 最终复跑曾遇到本机冷启动超时：桌面第一次界面无响应，原样重跑在已通过的检查之后被旧 45 秒总限时中止；临时后端也超过了原 10 秒就绪等待。外层预算分别调整为 90 秒与 60 秒，心跳 30 秒等单项业务断言不变。
|
||||
调整后最终复跑通过后端 243/243 与桌面 24/24（含二次启动），桌面整套实际耗时 20.6 秒。
|
||||
|
||||
## 常驻岛并入自定义灵动岛（最新行为）
|
||||
|
||||
后续产品要求统一两种自定义显示方式，本节取代上文关于可选常驻、铃铛优先与独立通知卡的历史行为。
|
||||
`layout` 仍为 fixed/custom；custom 直接显示常态组件，`residentEnabled` 只保留为旧配置兼容字段，归一化为 custom 时开启。
|
||||
设置页不再提供独立的常驻开关。编辑器保留常态 rows 与无通知展开 expandedRows，两套内容随本机方案保存。
|
||||
|
||||
自定义运行时统一为 `CustomIslandRuntime.vue`，不再将旧卡片嵌入组件行。
|
||||
经典岛与自定义岛共同使用 `ClassicNotifications.vue` 和 `classic-island.css`，通知类型、排序、徽标、正文、按钮与已读动作只有一份实现。
|
||||
纯黑、玻璃、主题色、透明度、字号、圆角、动画开关与速度均来自同一份 island 外观设置；方案保留组件缩放、行距和布局。
|
||||
自定义组件行、消息正文与通知操作区居中对齐。无通知展开时显示 expandedRows，有通知时显示共用经典通知内容。
|
||||
|
||||
自定义模式不再提前截获所有消息并只亮铃铛：与经典岛走相同的 pushNotification/setClassState 状态机。
|
||||
紧急通知和紧急叫人立即展开，课中普通通知排队、下课后展开；主动点击铃铛仍可查看待处理消息。
|
||||
收起和处理完通知后恢复自定义常态内容。铃铛固定占位，收到消息不横移。空白桌面输入穿透与触摸区域裁剪继续保留。
|
||||
外壳使用经典岛同源的 SpringValue 与 squirclePath；宽高和圆角每帧同时推进，保留零过冲钳制、动画速度与后台吸附兜底。
|
||||
原生画布固定，隐藏渲染器不运行旧形变；统一心跳不随布局切换重复注册。
|
||||
|
||||
内容过渡与外壳采用同参数弹簧同步推进：常态透明度为 max(0, 1-1.5p)，展开透明度为 p²，收起时反向播放。
|
||||
不再使用独立的 200ms 内容淡入，避免内容已经切完、外壳还在展开的割裂；等尺寸页面也有完整过渡。
|
||||
动画开关和速度同时作用于外壳、内容与铃铛提示，快速反向时保留当前进度；后台窗口仍直接落位。
|
||||
视觉验收逐帧断言展开与收起都有多帧尺寸变化和中间透明度，可用 ISLAND_MOTION_CAPTURE=1 留档真实合成帧。
|
||||
本机 Electron 实测 prefers-reduced-motion=true；合并版自定义岛额外检查此系统偏好，造成应用内开着动画仍直接吸附。
|
||||
现统一以应用内动画开关为准，与经典岛一致；不再由第二套系统判据覆盖已开启的动画。
|
||||
|
||||
课表更新链路做了以下修正：
|
||||
|
||||
- 课表变更事件立即取 active-week，学期接口在旁路校正，避免慢学期请求串行挡住新课表。
|
||||
- 网络结果先同步到岛，再异步完成缓存写入；请求序号在请求开始前分配，迟到响应和已切换账号的结果不会覆盖当前内容。
|
||||
- 实时连接建立及重连时立即刷新；周期补偿从五分钟缩至三十秒，课程边界每秒复算。跨午夜即使上课状态未改变，也同步新一天的课程。
|
||||
- 主进程保留最新日课表快照；窗口启动、重建时补发，渲染器通过受限 getSchedules IPC 读回，登出时清空。
|
||||
- 自适应同时接收原生窗口尺寸通知，防止隐藏窗口的浏览器 resize 延迟而沿用旧宽度；订阅在组件退出时释放。
|
||||
|
||||
验证使用隔离配置、本地消息和替换的本地 API，覆盖慢学期接口、变更事件、重连刷新、迟到请求隔离、课表 IPC 即时更新及窗口重新加载恢复。
|
||||
桌面视觉回归覆盖经典岛原有状态，以及自定义岛单通知、多通知、常态、空闲展开、窄屏、长文本、触摸和固定原生窗口动画。
|
||||
|
||||
## ClassIsland 课前与上下课提醒（后续最新要求）
|
||||
|
||||
现场重新读取了上游 master 的以下实现：
|
||||
|
||||
- [ClassNotificationProvider](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Services/NotificationProviders/ClassNotificationProvider.cs)：准备上课、上课、下课的独立提醒链。
|
||||
- [ClassNotificationSettings](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Models/NotificationProviderSettings/ClassNotificationSettings.cs)：室内课程默认提前 60 秒。
|
||||
- [ClassNotificationProviderControl](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Controls/NotificationProviders/ClassNotificationProviderControl.axaml)：倒计时、下节科目及右侧起止时间。
|
||||
- [FluentTheme](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/XamlThemes/FluentTheme/Styles.axaml) 与 [SlantedMaskControl](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Controls/SlantedMaskControl.cs)：40px 横条、五段斜切遮罩、360ms 区域动画与 120ms 错峰、标题延迟 260ms 淡入和缩放。
|
||||
|
||||
自定义岛的常态外观按上述 ClassIsland 横条恢复半透明深色底、1px 描边、8px 默认圆角和 14/16/18/20 四档字体，内容居中。
|
||||
通知继续共用经典操作组件，使用同一半透明岛壳。课程组件按「课程名 起始时间–结束时间」横向排列，时间位于名称右侧，开关文案改为「显示课程时间」。
|
||||
|
||||
LessonReminderTracker 只读取服务端已解析的当天 ScheduleDto 投影，不参与 ClassPlan 在线启用与轮换选择。
|
||||
课前 60 秒开始：3 秒强调遮罩后显示实时秒数和课程时间，持续到上课；上课遮罩 5 秒后退出。
|
||||
下课先提示 2 秒，再预告下节课程 10 秒；当天最后一课下课只提示 5 秒。不补弹已经过去的上下课事件。
|
||||
刷新同一课表不会重置遮罩，临时换课立即更新名称，移除课程或退出账号会取消提醒。
|
||||
提醒是独立本机状态，不写入教师通知、未读计数或通知队列；用户主动打开的通知详情和紧急提示优先展示，自动补弹的普通通知不再挡住上下课提醒。
|
||||
经典与自定义两种布局使用同一个 LessonReminderContent；原生窗口仍为固定画布，自定义岛用自然尺寸缩放适配。
|
||||
本次只移植课表可见提醒和动画，不自动启用语音与音效。
|
||||
|
||||
## 课程进度、即将下课与主窗口编辑（本批补齐）
|
||||
|
||||
- 对照上游 `LessonControlExpanded.axaml` 的 `LeftSeconds` 和 `ProgressPercent`，课程组件增加持续的本节进度条与距下课时间，课间自动显示下一课；起止时间保持在课程名右侧，按秒更新。
|
||||
- 倒计时组件支持自动上下课、本节下课、下一节课、放学四种目标，按当天课表排序，排除其它日期。已有配置缺少新字段时自动补齐。
|
||||
- 默认最后 60 秒显示即将下课倒数；经典岛在上课遮罩后持续显示本节课程、剩余时间与进度，自定义岛平时由组件显示进度，时间点提醒接管同一个岛体。
|
||||
- 设置→提醒提供课前、上课、即将下课、下课独立开关，以及经典岛课中进度开关；课前提前 5–1800 秒，下课倒数提前 5–600 秒，保存后即刻生效。
|
||||
- 自定义编辑器移到主窗口 `/settings/island/editor`；设置和兼容 IPC 入口都导航到主窗口，浮岛不再被扩大成全屏编辑窗口。主窗口保留侧栏，画布按内容与可用空间自动缩放，支持触摸跨行拖动、容器和独立常态/展开内容。
|
||||
- 编辑使用独立预览，不上报桌面岛尺寸；配置保存按顺序执行。关闭编辑返回灵动岛设置。
|
||||
|
||||
## 管理后台界面与二级菜单
|
||||
|
||||
按用户确认，本批“重写后端”指 Web 管理后台界面与导航。参考 art-design-pro 的 sidebar-menu、breadcrumb、header-bar，重写工作区框架，服务端接口、鉴权和既有业务页面保留。
|
||||
|
||||
- 工作台、教学事务、班级与人员、设备运维、系统管理五个一级分组；原有全部业务入口位于二级菜单。
|
||||
- 菜单直接读取路由的标题、图标、角色与生效权限；空分组隐藏，搜索结果和页签也按相同权限过滤，深链继续经过路由守卫。
|
||||
- 增加面包屑、最多 20 个可关闭页签、关闭其它页签、Ctrl+K 功能搜索；页签保留该页面的完整查询参数。
|
||||
- 统一浅/深主题下的侧栏、顶栏、卡片、表格和页面留白；仪表盘增加真实账号欢迎区与按权限显示的快捷入口。手机端使用同一棵二级菜单的抽屉。
|
||||
- 回归使用独立临时 SQLite、临时教师和班级；不读取或改写真实班级业务数据。
|
||||
|
||||
### 老师消息阅读背景
|
||||
|
||||
通知、作业、叫人内容展示时，两种布局统一使用 `#202020` 不透明背景，原生窗口透明度临时为 1，玻璃风格和用户设置的透明度不会降低消息可读性。常驻组件、空闲展开和课程提醒仍按原有透明度显示，收起消息后恢复本机透明度偏好。
|
||||
+61
-116
@@ -1,129 +1,74 @@
|
||||
---
|
||||
title: REST API
|
||||
description: ClassHelper后端全部接口一览：方法、路径、权限与说明。
|
||||
description: 现行接口分组、关键路径和权限边界。
|
||||
---
|
||||
|
||||
# REST API
|
||||
|
||||
## 通用约定
|
||||
API 前缀 /api，JWT 使用 Authorization: Bearer。成功/失败结构以 `lib/http.ts` 为准，
|
||||
校验错误映射 422 VALIDATION_ERROR，表格体积超限为 413 IMPORT_TOO_LARGE。
|
||||
全部挂载入口以 `modules/registry.ts` 为准；完整参数、返回类型、权限和枚举以模块的 module/schemas/service 与 shared 契约为准。
|
||||
本页列常用入口，不重复复制每条路由实现。
|
||||
|
||||
- 所有接口前缀 `/api`（设备接口也一样）；
|
||||
- 统一响应体：`{ "success": true, "data": {}, "message": "" }`，错误为 `success: false` + `code`；
|
||||
- 除登录、健康检查与设备接口外，都需要 `Authorization: Bearer <token>`；
|
||||
- 请求体校验走 zod（`middleware/validate.ts`），错误由 `middleware/error.ts` 统一映射。
|
||||
## 身份与班级
|
||||
|
||||
## 接口一览
|
||||
| 方法与路径（省略 /api） | 行为及边界 |
|
||||
| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
|
||||
| POST /auth/login、/auth/class-login | 员工/班级登录，共享登录限流；学生无账号 |
|
||||
| GET /auth/me；POST /auth/logout；PATCH /auth/password | 当前身份、退出、员工本人改密码 |
|
||||
| GET/POST /classes；GET/PATCH/DELETE /classes/:id | 班级查询/管理，写入需 class:manage 与管理员业务断言 |
|
||||
| PATCH /classes/:id/class-account、/classes/:id/head-teacher | 班级凭据/班主任维护 |
|
||||
| PUT /classes/:id/subject-teachers | 任课关系设置，Course 为唯一来源 |
|
||||
| GET/PATCH /classes/:id/student-grade-query | 查看/修改班级个人成绩查询开关，班级端不能修改 |
|
||||
| GET/POST /classes/:id/students；DELETE /classes/:id/students/:studentId | 本班名单及维护，受名单功能权限和班级关系约束 |
|
||||
| /students、/teachers | 名单与账号 CRUD；读/写使用不同权限键，具体角色限制读取对应模块 |
|
||||
| POST /teachers/:id/reset-password | 指定新密码或默认重置；学生无对应接口 |
|
||||
| /permissions/me、/catalog、/groups、/users | 当前有效权限、目录、组与账号分组 |
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
| --------------------------- | ------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------- |
|
||||
| POST | `/auth/login` | 公开 | 登录（教师 / 管理员的**工号** + 密码）；学生不是账号，拿学号登录只会得到 401 |
|
||||
| POST | `/auth/class-login` | 公开 | **班级账号登录**：班级码 + 班级密码 → 班级会话 |
|
||||
| GET | `/auth/me` | 登录 | 当前用户（学生附带班级 / 年级） |
|
||||
| PATCH | `/auth/password` | 登录 | 修改自己的密码（班级会话 → 班级密码） |
|
||||
| POST | `/auth/logout` | 登录 | 退出（无状态，客户端丢弃 token） |
|
||||
| GET | `/permissions/me` | 登录 | 当前账号的生效权限（**无权限键**；班级端会话返回空集） |
|
||||
| GET | `/permissions/catalog` | `permission:manage` | 权限键目录（权限页整棵勾选树的唯一来源） |
|
||||
| GET / POST | `/permissions/groups` | `permission:manage` | 权限组列表 / 新建 |
|
||||
| PATCH / DELETE | `/permissions/groups/:id` | `permission:manage` | 改名 / 改描述 / 整体替换权限键；内置组不可删 |
|
||||
| GET | `/permissions/users` | `permission:manage` | 成员列表（所属权限组 + 生效权限数量） |
|
||||
| PUT | `/permissions/users/:id/groups` | `permission:manage` | 整体替换某账号的权限组（空数组 = 回落角色默认模板） |
|
||||
| GET | `/classes` | 登录 | 班级列表（按权限收敛） |
|
||||
| GET | `/classes/:id` | 班级可见 | 班级详情（学生 / 课程 / 班主任 / 各科任课老师） |
|
||||
| POST | `/classes` | 管理员 | 创建班级（自动生成班级码，可指定班主任） |
|
||||
| PATCH / DELETE | `/classes/:id` | 管理员 / 教师 | 编辑 / 删除班级 |
|
||||
| PATCH | `/classes/:id/class-account` | 管理员 | 设置 / 重置班级账号（班级码 + 班级密码） |
|
||||
| PATCH | `/classes/:id/head-teacher` | 管理员 | 设置 / 更换班主任 |
|
||||
| GET / POST | `/classes/:id/students` | 班级可见 / ADMIN·TEACHER | 学生名单 / 添加学生 |
|
||||
| DELETE | `/classes/:id/students/:userId` | ADMIN·TEACHER | 移出学生 |
|
||||
| PUT | `/classes/:id/subject-teachers` | ADMIN | 设置各科任课老师（班级 + 科目 + 教师） |
|
||||
| GET / POST / PATCH / DELETE | `/courses` | 登录（写：班主任 / 管理员） | 课程管理 |
|
||||
| GET | `/schedules?classId=&week=&dayOfWeek=` | 登录 | 课表列表（`week` 过滤周次范围） |
|
||||
| GET | `/schedules/grid?classId=&week=` | 登录 | 周视图（7 列结构，供客户端直接渲染） |
|
||||
| GET | `/schedules/current?classId=&at=` | 登录 | 当前上课状态（`inClass` / `current` / `next`；`at` 为诊断用时间覆盖） |
|
||||
| POST / PATCH / DELETE | `/schedules[/:id]` | 班主任 / 管理员 | 课表增删改（广播 `schedule:updated`） |
|
||||
| GET | `/homeworks?classId=&courseId=&date=&pendingOnly=&keyword=` | 登录 | 作业列表（支持按所属日期；学生带完成状态，教师带完成人数） |
|
||||
| GET | `/homeworks/days?classId=&from=&to=` | 登录 | 哪些天有作业（日期高亮） |
|
||||
| GET | `/homeworks/:id` | 班级可见 | 作业详情 |
|
||||
| POST | `/homeworks` | 教师 / 管理员 / **班级账号** | 发布作业（附 `assignDate`；班级账号用于教室机器录入，归属班主任） |
|
||||
| PATCH / DELETE | `/homeworks/:id` | 教师 / 管理员 | 修改 / 删除（广播 `homework:new` / `homework:updated`） |
|
||||
| PATCH | `/homeworks/:id/status` | 登录 | 标记完成 / 取消（广播 `homework:status`） |
|
||||
| GET / PATCH | `/homeworks/:id/submissions` | 登录 | 未交名单：读名单 / 回写全班完成状态 |
|
||||
| POST | `/homeworks/bulk` | `homework:write` | 一次给多个班级布置同一份作业（`subjectName` 跨班按名匹配科目；逐班结果） |
|
||||
| GET | `/notifications?classId=&priority=&unreadOnly=&keyword=` | 登录 | 通知列表（带已读状态；另支持 `date` / `from` / `to` / `createdBy`） |
|
||||
| GET | `/notifications/unread-count` | 登录 | 未读数（红点） |
|
||||
| POST | `/notifications` | 教师 / 管理员 | 发布通知（广播 `notification:new`）；上课时段发紧急通知需 `confirmDuringClass` |
|
||||
| POST | `/notifications/:id/read`、`/notifications/read-all` | 登录 | 标记已读（班级设备会写全班） |
|
||||
| DELETE | `/notifications/:id` | 教师 / 管理员 | 删除通知 |
|
||||
| GET | `/notifications/days?classId=&from=&to=&createdBy=` | 登录 | 通知按天归档（日期 + 条数，日期取 `assignDate`） |
|
||||
| GET | `/notifications/creators?classId=&from=&to=&date=` | 登录 | 通知按发布人归档 |
|
||||
| POST | `/notifications/bulk` | `notification:publish` | 一次给多个班级发同一条通知（逐班结果，**单班失败不影响整批**） |
|
||||
| POST | `/calls` | 教师 / 管理员 | **叫人**（`urgent` 决定 URGENT / HIGH；广播 `notification:new` 与 `call:new`） |
|
||||
| GET | `/grades/my` | 登录 | 个人成绩（班级会话 → 全班总览） |
|
||||
| GET | `/grades?classId=&courseId=&userId=&examName=` | 教师 / 管理员 | 班级成绩 |
|
||||
| GET | `/grades/stats?classId=&courseId=&examName=` | 教师 / 管理员 | 等级分布 + 各课程平均得分率 |
|
||||
| POST | `/grades`、`/grades/bulk` | 班主任 / 管理员 | 单条 / 批量录入（广播 `grade:updated`） |
|
||||
| PATCH / DELETE | `/grades/:id` | 班主任 / 管理员 | 修改 / 删除成绩 |
|
||||
| GET | `/students?classId=&keyword=` | **管理员** | 学生名单 |
|
||||
| POST / PATCH / DELETE | `/students[/:id]` | **管理员** | 学生名单增删改（无密码概念；重置密码接口已下线 → 404） |
|
||||
| GET | `/teachers?keyword=` | **管理员** | 教师列表 |
|
||||
| POST / PATCH / DELETE | `/teachers[/:id]` | **管理员** | 新建 / 编辑 / 删除教师账号 |
|
||||
| POST | `/teachers/:id/reset-password` | **管理员** | 修改 / 重置教师密码（`newPassword` 可选，留空 = 默认初始密码） |
|
||||
| GET | `/dashboard/summary`、`/dashboard/term` | 登录 | 仪表盘汇总 / 学期周次 |
|
||||
| GET | `/imports/template?kind=&format=` | 管理员 / 班主任 | 导入模板下载（`csv` 走 JSON，`xlsx` 走二进制） |
|
||||
| POST | `/imports/table/preview` | 管理员 / 班主任 | 上传表格（base64）解析预览：列名 + 前 20 行 + 校验问题 + 建议映射 |
|
||||
| POST | `/imports/table/commit` | 管理员 / 班主任 | 按字段映射与写入模式导入（成绩 / 学生名单 / 教师名单） |
|
||||
| POST | `/imports/time-layout/preview` | 管理员 / 本班班主任 | 解析 ClassIsland 时间配置 JSON（只解析不落库） |
|
||||
| GET / POST / DELETE | `/imports/time-layout[/:id]` | 管理员 / 本班班主任 | 时间配置列表 / 导入（`replace` 覆盖、`merge` 合并）/ 删除 |
|
||||
| POST | `/imports/class-plan/preview`、`/imports/class-plan` | 管理员 / 本班班主任 | ClassIsland 课程表解析预览 / 导入（支持单双周） |
|
||||
| GET | `/database/status` | **管理员** | 数据库状态（连接 / 版本 / 体积 / 23 张表行数 / 备份列表 / 定时配置） |
|
||||
| POST | `/database/test-connection` | **管理员** | 测试任意目标库连通性（provider 仅 sqlite / mysql） |
|
||||
| GET / POST | `/database/backups` | **管理员** | 备份列表 / 立即备份（gzip JSON 快照，存 `<数据目录>/backups/`） |
|
||||
| POST / DELETE | `/database/backups/:name/restore` · `/database/backups/:name` | **管理员** | 从备份恢复（整库覆盖）/ 删除备份 |
|
||||
| GET | `/database/export`、`/database/sqlite-file` | **管理员** | 下载 JSON 快照 / 下载数据库文件（后者仅 SQLite） |
|
||||
| POST | `/database/import` | **管理员** | 导入快照（base64，整库覆盖；可在 SQLite / MySQL 之间互迁） |
|
||||
| GET / PUT | `/database/backup-schedule` | **管理员** | 定时备份配置（enabled / intervalHours / keepCount） |
|
||||
| POST / GET | `/database/switch`、`/database/switch/jobs/:id` | **管理员** | **一键切换数据库**（异步任务）/ 轮询进度 |
|
||||
| GET | `/update/check` | 登录 | 更新检查（服务端代查 GitHub 最新 Release；`?force=1` 绕过缓存仅管理员生效） |
|
||||
| POST | `/clients/heartbeat` | 登录 | 客户端每 30 秒上报（**无权限键**）；返回更新目标 + 安装包信息 + 一条待执行命令 |
|
||||
| POST | `/clients/commands/:id/ack` | 登录 | 命令执行回执（**无权限键**，靠 body 的 `deviceKey` 校验归属，幂等） |
|
||||
| POST | `/clients/commands` | `remote:control` | 下发远控命令（关机 / 重启 / 注销 / 锁屏；自动撤销该机更早的未回执命令） |
|
||||
| GET | `/clients/devices?classId=` | `client:manage` | 客户端设备列表（版本 / 在线 / 待执行命令） |
|
||||
| POST | `/clients/updates` | `client:update-push` | 统一下发客户端更新（按设备 / 班级 / 全部） |
|
||||
| DELETE | `/clients/devices/:id` | `client:manage` | 移除设备记录（换机 / 旧机器清理） |
|
||||
| GET | `/update/client/releases` | `client:manage` | 服务端已缓存了哪些客户端安装包 |
|
||||
| POST | `/update/client/fetch` | `client:update-push` | 服务端代教室机器从 GitHub 下载安装包并登记 sha256 + size |
|
||||
| POST | `/update/client/releases` | `client:update-push` | 手工登记已放进磁盘的安装包（内网 / U 盘分发兜底） |
|
||||
| DELETE | `/update/client/releases/:version` | `client:update-push` | 删除缓存的安装包（元数据 + 磁盘文件） |
|
||||
| GET | `/update/client/download/:version` | 登录 | 下载安装包（**故意不挂权限键**，班级端要能下；`res.download`） |
|
||||
| GET / PUT | `/ai/settings` | `ai:manage` | 大模型设置（API Key 加密存储、**只进不出**，只回 `hasApiKey` / `keyHint`） |
|
||||
| POST | `/ai/interpret` | `ai:use` | 一句话解析（**只解析不落库**）；回 `action` / `params` / `preview` / `confidence` |
|
||||
| GET | `/ai/audit?limit=` | `ai:manage` | 助手使用记录（每次解析写一条 `AiAudit`） |
|
||||
| GET / PUT | `/system/settings` | `system:manage` | 系统设置（`developerMode`：开启后 500 响应带 `error.stack`） |
|
||||
| GET / PUT | `/system/autostart` | `system:manage` | 开机自启状态 / 开关（Windows 注册表 Run 项，Linux systemd 单元） |
|
||||
| GET | `/system/diagnostics` | `system:manage` | 运行诊断（版本 / Node / 运行时长 / 数据目录 / 在线客户端数 / 已加载模块） |
|
||||
| GET | `/health` | 公开 | 健康检查（含版本号与已挂载模块） |
|
||||
## 教学与文件
|
||||
|
||||
另有三个探针（不带 `/api` 前缀）：`/healthz`（存活）、`/readyz`（就绪）、以及 `/api/health`（详情）。
|
||||
| 路径/动作 | 行为及边界 |
|
||||
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| /courses | 班级科目与任课关系 |
|
||||
| GET /schedules、/grid、/current、/active-week | 新关系模型的兼容投影，按班级范围读取 |
|
||||
| POST/PATCH/DELETE /schedules[/:id] | 兼容 CRUD，写新模型，不双写旧 Schedule |
|
||||
| POST /schedules/swap、/overlay、/scheduled；GET /schedules/scheduled；DELETE /schedules/scheduled/:id | 换课、临时层、预定 |
|
||||
| /time-layouts；POST /time-layouts/:id/clone、/:id/import | 时间表 CRUD/克隆/导入，写入 timetable:manage |
|
||||
| /class-plans；PUT /class-plans/:id/entries；PATCH /class-plans/:id/enabled | 日课表 CRUD、整表保存、启用，写入 schedule:write + 班主任/管理员 |
|
||||
| POST /class-plans/:id/clone、/class-plans/import、/class-plans/import/profile；GET /class-plans/:id/export | 复制、导入导出及完整档案导入 |
|
||||
| /class-plan-groups；GET /class-plan-groups/selection；POST /class-plan-groups/select | 群组及当前/临时选择 |
|
||||
| /homeworks、/homeworks/bulk、/:id/status、/:id/submissions | 作业、批量、完成与未交；员工功能键+科目检查，班级端可录作业 |
|
||||
| /notifications、/notifications/bulk、/days、/creators、/unread-count、/:id/read、/read-all | 通知、归档和已读；发布需 notification:publish，课堂紧急须确认 |
|
||||
| POST /calls | 叫人，call:create + 范围检查 |
|
||||
| /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | [成绩与隐私](../app/grades.md)，查询列表参数用 studentId，写入仍按科目 |
|
||||
| /imports/template、/table/preview、/table/commit | 表格导入，按 kind 再检查角色、导入权限、班级和科目 |
|
||||
| /imports/class-plan/preview、/imports/class-plan | 旧预览与完整档案提交；提交走关系化导入 |
|
||||
| /imports/time-layout[/:id]、/time-layout/preview | 时间配置兼容入口，写入/删除需 timetable:manage |
|
||||
| GET /courseware、/courseware/:id、/:id/download | 课件目录/详情/下载；员工需 courseware:read，班级端按可见范围 |
|
||||
| POST /courseware/upload、/:id/push；PATCH /courseware/:id/visibility；DELETE /courseware/:id | 写入 courseware:write + 员工身份；本人文件、任课班级与可见范围限制 |
|
||||
| GET /courseware/transfers；POST /courseware/transfers/:id/ack | 班级端补领、逐设备回执 |
|
||||
|
||||
## 几条容易踩的接口约定
|
||||
## 设备、系统与运维
|
||||
|
||||
| 约定 | 说明 |
|
||||
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`POST /homeworks` 故意不加 `requireRole`** | 权限判在 `homeworks.service.createHomework` 里（staff 或本班班级账号），因为教室机器也要能录作业 |
|
||||
| **班级账号的 `sub` 是班级 id** | 写 `createdBy` 前要换成该班班主任，否则撞 `User` 外键 |
|
||||
| **登录限流挂在两个入口上** | `/auth/login` 与 `/auth/class-login` 都挂 `loginRateLimiter()` |
|
||||
| **角色判定在密码校验之前** | 否则"密码错 / 密码对但账号停用"的差异会把学生账号密码变成可离线验证的预言机 |
|
||||
| **会渲染成链接的字段要校验 scheme** | `Homework.attachmentUrl` 只允许 `http(s)://` 或站内相对路径 |
|
||||
| **表格导入 8MB ↔ 请求体 12MB** | 文件以 base64 放进 JSON（约 4/3 倍），超限映射成 413 `IMPORT_TOO_LARGE` |
|
||||
| **三个接口故意不挂权限键** | `/permissions/me`、`/clients/heartbeat`、`/update/client/download/:version` —— 前两者由班级端（`CLASS_DEVICE`，权限集为空）调用，下载接口要能装包；保护只有"已登录 + 限流" |
|
||||
| **查询参数校验失败是 422** | `middleware/validate.ts` 的 zod 解析错误由错误中间件映射成 422 `VALIDATION_ERROR`（不是 400） |
|
||||
| **批量发布逐班判定、不整批回滚** | `/notifications/bulk` 与 `/homeworks/bulk` 的单班失败（403 越权 / `URGENT_DURING_CLASS`）不影响其它班，成功班照常落库并实时推送 |
|
||||
| **`/ai/interpret` 只解析不落库** | 助手只回结构化参数与中文预览；落库由前端确认后调既有端点 —— 权限与上课时段保护都在那条路径上 |
|
||||
| 路径/动作 | 行为及边界 |
|
||||
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
||||
| POST /clients/heartbeat、/clients/commands/:id/ack | 登录设备心跳/回执，校验 deviceKey 和归属 |
|
||||
| GET /clients/devices；DELETE /clients/devices/:id | 设备读取/维护，分别检查功能键和范围 |
|
||||
| POST /clients/commands | remote:control + 对应范围，白名单动作 |
|
||||
| POST /clients/updates | client:update，安装策略 immediate/after-school/idle |
|
||||
| GET /update/check | 员工需 update:check；强制刷新另检查 update:force |
|
||||
| GET /update/client/releases | 缓存版本读取，按路由允许的读取权限 |
|
||||
| POST /update/client/fetch、/update/client/releases；DELETE /update/client/releases/:version | 安装包写入口统一 client:update |
|
||||
| GET /update/client/download/:version | 已登录下载，不挂员工权限键，供班级端更新 |
|
||||
| /term；POST /term/auto；GET /term/holidays | 学期读取/编辑/假日建议，term:read/term:write |
|
||||
| GET/PUT /term/promotion；POST /term/promotion/run | 升级计划、预览和执行，system:manage，执行还做业务校验 |
|
||||
| /archives、/archives/transferred、/archives/transferred/:id/restore | 历史归档与撤回转出，archive:manage；不提供创建归档代替年度升级的入口 |
|
||||
| /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage；目标空库、快照及换库子进程保护 |
|
||||
| /system/settings、/autostart、/diagnostics | system:manage，非安装形态自启动返回不可用原因 |
|
||||
| /ai/settings、/interpret、/audit | ai:manage/ai:use；只解析待确认动作，密钥只进不出 |
|
||||
| /dashboard/summary、/dashboard/term | 按范围读取看板与周次 |
|
||||
|
||||
## 相关
|
||||
|
||||
- 实时事件见[实时事件（Socket.IO）](realtime.md)；
|
||||
- 权限矩阵见[角色与权限](permissions.md)；
|
||||
- 数据模型见[数据模型](data-model.md)。
|
||||
|
||||
客户端心跳可携带 `agentProtocol: 2`，业务数据读取统一响应的 `data`。未带此标记时额外返回旧版需要的顶层字段；放学后更新在到时前不向旧客户端提供安装包。推送更新支持 `mode: immediate | after-school | idle`，`afterSchoolTime` 为服务端本地时区的 `HH:mm`。
|
||||
探针 /healthz 和 /readyz 不带 API 前缀；/api/health 提供版本与模块详情。
|
||||
课件上传是原始文件流，512 MB 限制独立于表格 JSON 的 12 MB 限制；metadata 走上传查询 schema。
|
||||
心跳 agentProtocol:2 使用统一响应 data，旧协议兼容字段只用于升级过渡。
|
||||
更多说明见[权限](permissions.md)、[实时事件](realtime.md)、[数据模型](data-model.md)。
|
||||
+46
-145
@@ -1,165 +1,66 @@
|
||||
---
|
||||
title: 架构总览
|
||||
description: 目录结构、技术栈、模块化设计与几条贯穿全局的工程约定。
|
||||
description: 工作区结构、模块注册、共享契约与数据流。
|
||||
---
|
||||
|
||||
# 架构总览
|
||||
|
||||
## 技术栈
|
||||
ClassHelper 是 pnpm workspace：Express/Prisma/Socket.IO 服务端、Vue Web 管理端、Electron 桌面客户端与共享包。
|
||||
依赖版本以根和各包的 `package.json`、`pnpm-lock.yaml` 为准。文档站和纯静态官网不在 workspace 内。
|
||||
|
||||
| 层 | 选型 | 版本（`package.json` 实际声明） |
|
||||
| ------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| 包管理 | pnpm workspace | 11.8.0 |
|
||||
| 语言 | TypeScript | 5.9.3（`typescript-eslint` 要求 < 6.1，因此未用 7.x） |
|
||||
| 后端 | Node.js + Express | ≥ 20.19 / 5.2 |
|
||||
| ORM | Prisma + driver adapter | 7.10（+ `@prisma/adapter-libsql`，切 MySQL 用 `-mariadb`） |
|
||||
| 实时 | Socket.IO | 4.8 |
|
||||
| 认证 | jsonwebtoken + bcryptjs | 9.0 / 3.0 |
|
||||
| 校验 | zod | 4.6 |
|
||||
| Web 端 | Vue + Vite + Element Plus + Pinia + Vue Router + Axios | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20 |
|
||||
| 客户端 | Electron + Vue + Element Plus + Pinia + Socket.IO Client + IndexedDB | 44.3 / 3.5 / 2.14 / 4.0 / 4.8 |
|
||||
| 打包 | electron-builder（nsis / portable）+ NSIS | 26.15 |
|
||||
| 文档站 | docfx | 2.81 |
|
||||
## 目录与入口
|
||||
|
||||
## 目录结构
|
||||
| 路径 | 职责 |
|
||||
| --------------------------------------------- | ------------------------------------------- |
|
||||
| `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 构建时拼接 |
|
||||
|
||||
```
|
||||
class-helper/
|
||||
├── package.json # 根脚本（dev / build / db:* / verify:* / dist:* / docs:* / icons）
|
||||
├── pnpm-workspace.yaml # workspace 定义 + allowBuilds（pnpm 11 依赖构建白名单）
|
||||
├── tsconfig.base.json # 共享 TS 基础配置（ESM + NodeNext + strict）
|
||||
├── eslint.config.mjs # ESLint 扁平配置（TS + Vue）
|
||||
├── .prettierrc.json # 单引号 / 110 列 / LF / 尾逗号
|
||||
├── build/classhelper.{png,ico} # **图标源**（设计导出、手工放入）；pnpm icons 从它派生其余全部图标
|
||||
├── scripts/
|
||||
│ ├── use-database.mjs # SQLite ⇄ MySQL provider 切换助手
|
||||
│ ├── generate-icons.mjs # 启动 Electron 跑 icons/render.cjs（= pnpm icons）
|
||||
│ ├── icons/render.cjs # 把 classhelper.png 重采样成各端图标（CommonJS）
|
||||
│ ├── version.mjs # 版本号单一来源的读写与一致性校验（= pnpm version:*）
|
||||
│ ├── dist-server.mjs # 服务端 + Web 管理端打包（组装运行时 → NSIS 安装程序）
|
||||
│ ├── verify-packaged.mjs # 对打包后 / 已安装的客户端 EXE 复跑冒烟
|
||||
│ ├── lib/ # electron-env / node-runtime / smoke-class
|
||||
│ ├── nsis/server-installer.nsi# 安装程序脚本模板（版本号由 dist-server 注入）
|
||||
│ └── ui-smoke/ # Web 管理端 UI 真实点击回归（Electron 驱动）
|
||||
├── deploy/ # 生产部署：Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf
|
||||
│ ├── install.sh # Linux 一键安装器（TUI；native/docker 双形态；自带 --check 体检）
|
||||
│ ├── classhelper # 运维命令本体（软链 /usr/local/bin/classhelper）
|
||||
│ ├── verify-linux.sh # Linux 安装/改密/备份/升级/回滚验收（自统计 N/N 项）
|
||||
│ ├── tools/admin-cli.mjs # 离线账号工具（改密、列账号、SQLite 一致性快照）
|
||||
│ ├── classhelper.service # systemd 单元模板
|
||||
│ └── package.runtime.json # 运行时依赖清单（安装包 / 容器 / Linux 部署共用）
|
||||
├── docs/ # **文档站**（docfx 项目，发布到 GitHub Pages）
|
||||
│ ├── docfx.json # docfx 配置
|
||||
│ ├── toc.yml # 顶栏导航；各子目录各有一份 toc.yml 作为侧栏
|
||||
│ ├── index.md # 首页
|
||||
│ ├── get-started/ app/ management/ dev/ # 四个章节
|
||||
│ ├── templates/classhelper/ # docfx 模板覆盖（_master.tmpl + public/main.css + 图标）
|
||||
│ ├── images/ # 展示图：文档站 / README / 官网共用的同一份（1× 逻辑像素）
|
||||
│ ├── screenshots/ # 回归测试留档的截图（island / client / web-mobile），页面不展示
|
||||
│ ├── build.mjs # 构建入口（注入版本号与 404 的 base）
|
||||
│ ├── serve.mjs # 本地预览（:5181）
|
||||
│ └── _site/ # 构建产物（gitignore）
|
||||
├── website/ # 产品官网（纯静态，无构建；node website/serve.mjs 本地预览）
|
||||
│ └── assets/{styles.css,motion.js,main.js,icon.png,shots/}
|
||||
└── packages/
|
||||
├── shared/ # 三端共享：类型契约、常量、权限矩阵、动效令牌、工具函数
|
||||
│ └── src/{types,constants,permissions,motion,island-layout,utils,index}.ts
|
||||
├── server/ # 后端服务
|
||||
│ ├── prisma/schema.prisma # 数据模型（24 个 model，只有一份，切库改 provider）
|
||||
│ ├── prisma/migrations/ # 迁移历史（10 个）
|
||||
│ ├── prisma/seed.ts # 种子数据（会清空业务表后重建演示数据）
|
||||
│ ├── scripts/ # verify-e2e.mjs / apply-column-migrations.cjs
|
||||
│ └── src/
|
||||
│ ├── app.ts # Express 装配（探针 + 限流 + 模块挂载 + 静态托管 + 兜底）
|
||||
│ ├── index.ts # 启动入口（自检 + HTTP + Socket.IO + 优雅退出）
|
||||
│ ├── config/env.ts # 环境变量校验（zod）+ 生产配置自检
|
||||
│ ├── lib/ # access(RBAC) / snapshot(全库 JSON 快照) / db / db-bootstrap /
|
||||
│ │ # session / web-static / http / jwt / logger / mappers / version …
|
||||
│ ├── tools/apply-snapshot.ts # 跨库迁移的子进程入口
|
||||
│ ├── middleware/ # auth / error / validate / security(helmet + 限流 + 耗时日志)
|
||||
│ ├── realtime/ # socket.ts（房间）+ bus.ts（事件总线）
|
||||
│ └── modules/ # 15 个功能模块 + registry.ts（模块注册表）
|
||||
│ ├── manifest.yml
|
||||
│ ├── src/Plugin.cs
|
||||
│ ├── src/Services/ # BridgeService / ScheduleMapper / ClassPlanWriter /
|
||||
│ │ # ClassHelperNotificationProvider
|
||||
│ ├── src/Views/ # BridgeSettingsPage.axaml（Avalonia 设置页）
|
||||
│ └── src/Interop/ClassHelperClient.cs # HTTP 客户端 + 逐字段对齐服务端 zod 的 DTO
|
||||
├── web-admin/ # Web 管理端（Vue 3 + Vite + Element Plus + PWA）
|
||||
│ └── src/{api,stores,router,layouts,views,components,composables,styles}
|
||||
└── desktop-client/ # 桌面客户端（Electron + Vue 3）
|
||||
├── electron-builder.yml
|
||||
├── scripts/{build-main,dev,smoke,dist-win,check-bundle-secrets}.mjs
|
||||
└── src/
|
||||
├── main/ # 主进程：窗口 / 单实例 / 配置持久化 / 托盘 / 灵动岛 / 冒烟
|
||||
├── preload/ # contextBridge 安全桥（index.ts + island.ts）
|
||||
├── island/ # 灵动岛渲染进程（独立透明置顶窗口）
|
||||
├── types/desktop.d.ts # 主进程 ↔ 渲染进程契约
|
||||
└── renderer/ # 渲染进程：api / stores / cache / router / views / island
|
||||
```
|
||||
## 模块与数据流
|
||||
|
||||
## 模块化设计
|
||||
功能模块使用 `*.module.ts` 路由、`*.schemas.ts` 校验、`*.service.ts` 业务；新增/下线改 `registry.ts`。
|
||||
注册表包含教学业务、课件、日课表/时间表/群组、权限、客户端、系统、AI、升级和数据管理模块。
|
||||
路由与模块总数直接读取注册表，不在文档复制另一份数组。
|
||||
|
||||
后端每个功能是一个独立目录，统一契约：
|
||||
教师在 Web 提交 → 服务端校验权限、班级和科目范围 → 写数据库 → 事件总线按房间广播 → Web/客户端刷新。
|
||||
客户端先维护 IndexedDB 缓存，断网读取缓存；主窗口通过 preload 与主进程通信，主进程管理唯一原生岛窗口。
|
||||
课件先流式上传到服务端文件目录，再由客户端下载、验摘要并独立回执。
|
||||
|
||||
```ts
|
||||
// packages/server/src/modules/registry.ts（当前 20 个模块）
|
||||
export const apiModules: ApiModule[] = [
|
||||
authModule,
|
||||
aiModule, // 大模型助手（只解析不落库，见 docs/dev/api.md）
|
||||
classesModule,
|
||||
coursesModule,
|
||||
schedulesModule,
|
||||
homeworksModule,
|
||||
notificationsModule,
|
||||
callsModule,
|
||||
importsModule,
|
||||
gradesModule,
|
||||
studentsModule,
|
||||
teachersModule,
|
||||
archivesModule,
|
||||
termModule,
|
||||
dashboardModule,
|
||||
databaseModule, // 数据库管理（仅管理员）
|
||||
updateModule, // 更新检查 + 客户端安装包缓存与统一下发
|
||||
permissionsModule, // 权限组管理
|
||||
clientsModule, // 客户端设备心跳 / 远控命令
|
||||
systemModule, // 开发者模式 / 开机自启 / 运行诊断
|
||||
].filter((module) => module.enabled !== false);
|
||||
```
|
||||
## 工程边界
|
||||
|
||||
- **新增功能**：新建 `modules/<name>/`（`*.schemas.ts` 校验、`*.service.ts` 业务、`*.module.ts` 路由），
|
||||
在 registry 里加一行即可，`app.ts` 不用改；
|
||||
- **下线功能**：删掉那一行，或把 `enabled` 置为 `false`，接口立即从路由表消失；
|
||||
- **实时推送解耦**：业务模块只调 `realtime/bus.ts` 的 `emitToClass/emitToUser`，不直接依赖 Socket.IO 实例；
|
||||
- **共享契约**：所有 DTO 与类型集中在 `@classhelper/shared`（改完要 `pnpm build:shared`），三端共用。
|
||||
- 三端契约只放 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](https://github.com/LoveChengke/ClassHelper/blob/master/AGENTS.md)。
|
||||
|
||||
这些都是长期演进中固化下来的，改代码前值得先看（完整版在 `AGENTS.md`）：
|
||||
|
||||
| 约定 | 为什么 |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **统一响应与校验** | 用 `lib/http.ts` 的 `sendOk/sendCreated`，用 `middleware/validate.ts` 挂 zod，错误交给 `middleware/error.ts` |
|
||||
| **功能级准入看权限键** | 路由挂 `requirePermission('…')` / `requireAnyPermission(…)`，角色只是默认模板（`ROLE_DEFAULT_PERMISSIONS`）—— 见 `docs/dev/permissions.md` |
|
||||
| **权限判在服务层** | 权限组只管功能级；班级维度与科目维度仍用 `lib/access.ts` 的断言（`assertCanManageSubjectContent` 等），**权限组不可覆盖** —— 前端隐藏 ≠ 权限 |
|
||||
| **周一为新一周的第一天** | 周次口径唯一：`resolveCurrentWeek(TERM_START_DATE, now, MAX_TERM_WEEK)` |
|
||||
| **作业按 `assignDate` 归类** | 用 `createdAt`（UTC）会在晚上把作业算到第二天 |
|
||||
| **新增实时事件要改三处** | 服务端 bus/socket、Web 端订阅、客户端订阅（灵动岛也依赖） |
|
||||
| **跨桥接只传纯数据** | 传 Vue 的 `ref.value` 会在进入 preload 之前就抛 `could not be cloned` |
|
||||
| **桌面端产物里不得有凭据** | asar 可直接解包；构建有 `check-bundle-secrets` 门禁 |
|
||||
| **图标只有一个图形源** | 别改 `scripts/icons/` 的派生逻辑，换图标就换 `build/classhelper.{png,ico}` |
|
||||
| **前端不写死颜色** | 深色主题靠语义令牌，写死的颜色在深色下会露馅 |
|
||||
|
||||
## 本地开发
|
||||
## 开发启动
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
|
||||
pnpm db:generate && pnpm --filter @classhelper/server db:deploy
|
||||
pnpm build:shared # 必须先构建 shared，否则后续全部 ERR_MODULE_NOT_FOUND
|
||||
pnpm db:seed # 演示数据（会清空业务表）
|
||||
pnpm dev # shared watch + 后端 4000 + Web 端 5173
|
||||
# 复制 packages/server/.env.example 为 .env，并配置独立 JWT_SECRET 与数据库
|
||||
pnpm db:generate
|
||||
pnpm --filter @classhelper/server db:deploy
|
||||
pnpm build:shared
|
||||
# 只有明确需要重建演示数据时才运行 pnpm db:seed（会清空业务表）
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
常用命令与端口见[安装服务端](../get-started/server.md)；验收脚本见[验收与测试](testing.md)。
|
||||
后端 4000、Web dev 5173、桌面 dev 5174、官网 5180、文档预览 5181。
|
||||
生产服务端托管已构建的 Web 管理端；详见[安装服务端](../get-started/server.md)和[验收](testing.md)。
|
||||
+59
-118
@@ -1,133 +1,74 @@
|
||||
---
|
||||
title: 数据模型
|
||||
description: 24 张表的职责、跨库通用约定、迁移历史与启动时自动迁移。
|
||||
description: 现行模型职责、迁移与快照边界。
|
||||
---
|
||||
|
||||
# 数据模型
|
||||
|
||||
模型定义只有一份：`packages/server/prisma/schema.prisma`。
|
||||
模型定义以 `packages/server/prisma/schema.prisma` 为准，迁移以 `prisma/migrations/` 为准。
|
||||
仅维护一份 schema，SQLite/MySQL 切换改 provider；不使用 Prisma enum 和 `@db.*`。
|
||||
|
||||
## 跨库通用约定
|
||||
## 模型职责
|
||||
|
||||
- 默认是 **SQLite**（Prisma 7 的 libSQL driver adapter，数据文件 `packages/server/prisma/dev.db`）；
|
||||
- 字段**只用** `String / Int / Float / Boolean / DateTime`，**不用 Prisma enum、不用 `@db.*` 原生类型**；
|
||||
角色与优先级存字符串，在 API 层用 zod 校验 —— 这样 SQLite 与 MySQL 行为完全一致；
|
||||
- 因此切库只需改 `provider` 与连接串（`pnpm db:switch:mysql` 就地改写它，没有第二份 schema）；
|
||||
- 主键统一用 cuid 字符串，便于多端离线生成与合并。
|
||||
| 模型 | 职责 |
|
||||
| ---------------------- | -------------------------------------------------- |
|
||||
| `User` | 教师与管理员账号；学生不在此表，班级凭据在 Class |
|
||||
| `Student` | 学生名单、学号、在读/转出/毕业状态，无密码和角色 |
|
||||
| `StudentClassTransfer` | 调班与转出历史，保留班级/姓名快照 |
|
||||
| `ArchivedYear` | 毕业届别与统计快照 |
|
||||
| `TermWeek` | 逐周日期区间，classId 空串为全校默认 |
|
||||
| `Class` | 班级、班级码/密码、班主任、周数与成绩查询开关 |
|
||||
| `Course` | 班级+科目+教师任课关系，含简称和室外标记 |
|
||||
| `Schedule` | 旧课表迁移审计来源，现行接口不再以它为业务真值 |
|
||||
| `Homework` | 作业与本地 assignDate；dueAt 为遗留列 |
|
||||
| `HomeworkStatus` | 按 studentId 记录作业完成状态 |
|
||||
| `Notification` | 通知/叫人记录、优先级与本地 assignDate |
|
||||
| `NotificationRead` | 按 studentId 记录已读 |
|
||||
| `TimeLayout` | 共享或班级自有时间表；旧 items JSON 保留迁移审计 |
|
||||
| `Grade` | studentId、课程、考试、分数和等级 |
|
||||
| `PermissionGroup` | 默认/自定义/岗位组及 scope/scopeValue |
|
||||
| `PermissionGroupItem` | 组内权限键 |
|
||||
| `UserPermissionGroup` | 账号与组的多对多分配 |
|
||||
| `AppSetting` | 周次、升级、AI 和系统设置 |
|
||||
| `ClientDevice` | deviceKey、心跳、更新目标与状态 |
|
||||
| `ClientCommand` | 白名单远控、有效期与执行回执 |
|
||||
| `ClientRelease` | 服务端缓存安装包、SHA256 与大小 |
|
||||
| `AiAudit` | 助手解析审计，不保存 API Key |
|
||||
| `Exam` | 考试名称与是否计入总分 |
|
||||
| `TimeLayoutItem` | 有序时间点及类型，被课程显式引用 |
|
||||
| `ClassPlanGroup` | 班级课表群组、全局/默认标记 |
|
||||
| `ClassPlan` | 日课表、时间表、轮换、启用与临时层规则 |
|
||||
| `ClassPlanEntry` | 日课表与时间点、课程的外键关联、空课/停用/换课标记 |
|
||||
| `ScheduledClassPlan` | 按本地日期预定日课表 |
|
||||
| `PromotionRun` | 年度升级幂等与审计 |
|
||||
| `Courseware` | 文件元数据、上传教师、存储路径与 SHA256 |
|
||||
| `CoursewareVisibility` | 课件可见班级 |
|
||||
| `CoursewarePush` | 按班级的推送任务 |
|
||||
| `CoursewareReceipt` | 按设备的课件接收回执 |
|
||||
|
||||
## 两条核心不变量
|
||||
学生和账号分离：Student 没有密码/角色；教师/管理员存 User，CLASS_DEVICE 只是 Class 登录形成的会话。
|
||||
任课关系只在 Course；班主任关系在 Class.teacherId，可以与任课关系指向同一账号。
|
||||
课表真值是 ClassPlan/ClassPlanEntry/TimeLayoutItem，旧 Schedule 与 TimeLayout.items 不再参与现行业务写入。
|
||||
周次口径见[课表](../app/schedules.md)，成绩限制见[成绩](../app/grades.md)。
|
||||
|
||||
这两条是 2026-10-06 那次重构立下的，后面所有表都围着它们转：
|
||||
## 迁移与启动
|
||||
|
||||
**① 学生不是账号。** `Student` 是独立的一张表，只有学号 / 姓名 / 班级 / 性别 / 家长手机号 /
|
||||
状态，**没有 `passwordHash`、没有 `role`、没有登录字段** —— 「学生不能登录」由表结构保证，
|
||||
不再靠"登录前先判 role === 'STUDENT' 并 403"这类代码分支维持。
|
||||
`User` 因此收缩为**纯账号表**（管理员 / 教师 / ClassHelper 班级端）。
|
||||
不要删除或重写已应用的 SQLite 迁移目录。源码开发使用 `pnpm --filter @classhelper/server db:deploy`。
|
||||
安装形态由 `lib/db-bootstrap.ts` 执行启动迁移，账本 `_ch_migrations` 记录已执行目录。
|
||||
升级迁移包含学生表拆分、联动退役、关系化课表、权限范围、年度升级和课件表；具体顺序读取 migrations。
|
||||
历史学生迁移中的 STUDENT 只用于搬运旧数据，不是现行账号角色。
|
||||
MySQL 建模走受支持的换库流程，不能直接执行 SQLite SQL，详见[MySQL](../management/mysql.md)。
|
||||
|
||||
**② 任课关系的唯一来源是 `Course`。** `Course(classId, name, teacherId)` 就是
|
||||
「班级 + 科目 + 教师」这条关系本身，作业与成绩都挂在它上面；班主任另由 `Class.teacherId` 表示
|
||||
（每班 1 人）。历史上那张**没有科目**的 `ClassTeacher` 协作表已删除 —— 两套关系并存必然漂移。
|
||||
同一位教师可以在同一个班同时是班主任和某科科任老师：两处指向同一个 `User`，不重复建号，
|
||||
权限在 `@classhelper/shared` 的 `resolveClassRole()` 里合并。
|
||||
## 快照与文件
|
||||
|
||||
## 24 张表
|
||||
`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 是备份/导入/跨库迁移表清单，按依赖顺序导出，恢复阶段临时关闭外键检查并分批写入。
|
||||
模型新增或删除必须同步此清单；不要在文档复制固定表数。
|
||||
JSON 快照包含课件元数据、可见范围、推送与回执，**不含文件实体**；完整备份需带上课件目录。
|
||||
User.careMode 是预留列；当前 Web 偏好在 localStorage，客户端偏好在本机 config.json，不宣称已有跨设备同步。
|
||||
|
||||
| 表 | 职责 | 值得注意的字段 |
|
||||
| ------------------------------------------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `User` | **纯账号表**：管理员 / 教师 / ClassHelper 班级端 | `username`（教师即**工号**，班级端即班级码）、`role`、`phone`、`careMode`（关怀模式偏好，目前只由本机界面读写）；**学生不在这里** |
|
||||
| `Student` | 学生名单记录（**没有账号**） | `studentNo`（学号，唯一，唯一标识与查询键）、`classId`、`status`、`archivedYearId` |
|
||||
| `StudentClassTransfer` | 调班 / 转出历史 | 班级 id 与班级名**都存快照且不建外键**（班级删了历史仍要能读）、`mode`（single｜batch｜transfer-out） |
|
||||
| `ArchivedYear` | 毕业归档的届别档案 | `enrollmentYear`（届别，唯一）、`graduationYear`、归档时的统计快照 |
|
||||
| `Class` | 班级 | `name`（**「2026级1班」**，由 `enrollmentYear` + `classIndex` 生成）、`code` + `passwordHash`（班级端账号）、`termWeeks`、`termStartDate`、`studentGradeQueryEnabled`、`archivedYearId` |
|
||||
| `TermWeek` | 学期逐周日期区间 | `classId`（**空串 = 全校默认**）、`weekNumber`、`startDate` / `endDate` |
|
||||
| `Course` | 课程 = **「班级 + 科目 + 教师」任课关系** | `teacherId` 就是该班该科的任课老师；`@@unique([classId, name])` |
|
||||
| `Schedule` | 课表条目 | `weekStart` / `weekEnd` / `weekParity`（单双周）/ `source`（manual） |
|
||||
| `Homework` | 作业 | `assignDate`（所属日期）、`attachmentUrl`；`dueAt` 是已下线的遗留列 |
|
||||
| `HomeworkStatus` | 学生作业完成状态 | `@@unique([homeworkId, studentId])` |
|
||||
| `Notification` | 通知 | `priority`、`assignDate`（所属本地日期，禁止 UTC 切片）；`@@index([classId, assignDate])` 供按天归档 |
|
||||
| `NotificationRead` | 已读记录 | `@@unique([notificationId, studentId])` |
|
||||
| `TimeLayout` | 节次时间配置（ClassIsland 同款 JSON 导入得到） | `items` 是 JSON 字符串：`[{ index, name, startTime, endTime, type, skipped }]` |
|
||||
| `Grade` | 成绩 | `studentId`、`score` / `totalScore`、`levelType`（percent｜letter｜custom）与 `level` |
|
||||
| `PermissionGroup` | 权限组（角色之上的**默认模板**） | `name`（唯一）、`builtin`（内置组不可删）；生效集合见 [角色与权限](permissions.md) |
|
||||
| `PermissionGroupItem` | 权限组里的一个权限键（一行一个键） | `@@unique([groupId, key])`；键取值必须是 shared 的 `PERMISSION_KEYS` 之一 |
|
||||
| `UserPermissionGroup` | 账号 ←→ 权限组 的分配关系（可属多个组） | `@@unique([userId, groupId])`；**没有任何行 = 回落角色默认模板** |
|
||||
| `AppSetting` | 全局键值设置（大模型配置 / 开发者模式） | `key` 即主键、`value` 存字符串（复杂结构存 JSON）；密钥类值做 AES-256-GCM 加密后存这里（**只进不出**） |
|
||||
| `ClientDevice` | ClassHelper 客户端设备（教室 / 学生机） | `deviceKey`（唯一，客户端生成）、`classId`、`clientVersion`、`updateTargetVersion`、`lastHeartbeatAt`（**客户端在线判定看 `ClientDevice.lastHeartbeatAt`**：每 30 秒心跳，90 秒内有成功上报即在线。 |
|
||||
| 更新目标、安装策略与最早安装时间持久化在设备记录中，离线设备下次上线继续领取。 |
|
||||
## 修改模型时
|
||||
|
||||
**`Schedule.source`** —— 联动退役后历史同步课表统一归为 `manual`，保留排课数据。
|
||||
|
||||
**`Homework.dueAt`** —— 截止时间功能已下线，UI 与接口都不再读写它。
|
||||
保留列是为了**不对已安装的库做破坏性迁移**；新库里它恒为 `null`。
|
||||
|
||||
**`Notification.assignDate`** —— 与 `Homework.assignDate` 同口径：**本地日期**（`YYYY-MM-DD`），
|
||||
创建时用 `dayKeyLocal()` 写入，按天 / 区间归档都读它。**不要用 `createdAt` 切 UTC 当"哪一天"** ——
|
||||
晚上发的通知会被算到第二天。`@@index([classId, assignDate])` 是归档查询的支撑。
|
||||
|
||||
**`User.careMode`** —— 关怀模式的账号级偏好列（放大正文与控件）。**目前服务端没有任何接口读写它**：
|
||||
Web 端存在 `localStorage`（`classhelper.admin.careMode` + `careScale`），客户端存在本机 `config.json`。
|
||||
列先建好是为了将来跨设备同步偏好时不必再迁移；别把它当成"已有服务端开关"。
|
||||
|
||||
**`TermWeek.classId` 用空串而不是 null 表示"全校默认"** —— SQLite 与 MySQL 的唯一约束都把
|
||||
NULL 视作互不相同，`@@unique([classId, weekNumber])` 用 null 就形同虚设。
|
||||
|
||||
## 迁移历史（17 个）
|
||||
|
||||
```
|
||||
init → add_time_layout → add_class_account → add_schedule_week_parity →
|
||||
add_class_term_weeks → add_classisland_integration → add_class_notification_channel →
|
||||
add_homework_assign_date → add_push_kind → add_schedule_source →
|
||||
add_student_table → add_student_grade_query → add_grade_level →
|
||||
add_classhelper_heartbeat → add_archives → add_term_weeks →
|
||||
add_permission_groups_and_clients
|
||||
```
|
||||
|
||||
`add_student_table` 是一次真正的表重构（不是加列）：新建 `Student` / `StudentClassTransfer`、
|
||||
把 `User` 里 `role='STUDENT'` 的行**按 id 原样搬过去**、把 `Grade` / `HomeworkStatus` /
|
||||
`NotificationRead` 的外键从 `userId` 换到 `studentId`、删掉 `Enrollment` 与 `ClassTeacher`。
|
||||
因为学生行的 id 保持不变，三张个人数据表的 `userId` 可以直接当 `studentId` 用，历史一条不丢。
|
||||
|
||||
`add_permission_groups_and_clients` 是纯加表 / 加列：新建 `PermissionGroup` /
|
||||
`PermissionGroupItem` / `UserPermissionGroup`（权限组）、`AppSetting`（全局键值设置）、
|
||||
`ClientDevice` / `ClientCommand`（客户端设备与远控）、`ClientRelease`（安装包缓存）、
|
||||
`AiAudit`（大模型审计），并给 `Notification` 加 `assignDate` + `[classId, assignDate]` 索引、
|
||||
给 `User` 加 `careMode`。没有数据搬运，旧库直接补跑即可。
|
||||
|
||||
### 启动时自动迁移
|
||||
|
||||
`src/lib/db-bootstrap.ts` 用一张账本表 `_ch_migrations` 记录已执行的迁移目录名：
|
||||
|
||||
| 情况 | 行为 |
|
||||
| -------- | --------------------------------------------------- |
|
||||
| 全新安装 | 依次执行全部迁移并创建初始管理员 |
|
||||
| 覆盖安装 | 只补跑账本里没有的迁移（已存在的表 / 索引自动跳过） |
|
||||
| 已是最新 | **不做任何写操作** |
|
||||
|
||||
日志会写明「全新安装 / 升级安装」、应用了几个迁移、跳过了几个已存在对象。
|
||||
用户因此**不需要手动执行 `prisma migrate deploy`**。
|
||||
|
||||
## 备份格式就是这份模型的拓扑序导出
|
||||
|
||||
「数据库管理」里的备份 / 导出导入 / 跨库迁移共用一种 JSON 快照：**23 张表按拓扑序导出**
|
||||
（见 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES`，现在共 23 项，顺序为
|
||||
`User` → `PermissionGroup` → `PermissionGroupItem` → `UserPermissionGroup` → `AppSetting` →
|
||||
`ArchivedYear` → `Class` → `Student` → … → `AiAudit`），恢复时**临时关闭外键检查** ——
|
||||
因为 `Class.teacherId → User` 与 `Student.classId → Class` 是一条链、
|
||||
`Class/Student.archivedYearId → ArchivedYear` 又是一条，任何排序都会被其中一侧卡死。
|
||||
见[数据库管理](../management/database.md)。
|
||||
|
||||
## 开发时的模型改动
|
||||
|
||||
1. 改 `schema.prisma`；
|
||||
2. 在 `prisma/migrations/` 下加一个迁移目录（用
|
||||
`pnpm --filter @classhelper/server db:deploy` 应用，**别用 `pnpm db:migrate`** ——
|
||||
它在 Windows 上不可靠）。要改已有表结构而不只是加列时，可以先用
|
||||
`pnpm exec prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script`
|
||||
生成骨架，再手工补数据搬运语句；
|
||||
3. 改完核对 **`SNAPSHOT_TABLES`**（新增 / 删除表要同步）与 `deleteTeacher` 的护栏清单
|
||||
（它必须覆盖 `Class.teacherId` / `Course.teacherId` / `Homework.createdBy` /
|
||||
`Notification.createdBy` 四项）；
|
||||
再回到 `packages/server/scripts/apply-column-migrations.cjs` 补上可 `ALTER TABLE` 的简单列。
|
||||
|
||||
模型总数与迁移个数会随版本增长，以 `schema.prisma` 与 `prisma/migrations/` 的实际内容为准；
|
||||
本文里的数字标注的是**当前代码库**的状态。
|
||||
1. 同步 schema、迁移、shared 契约、服务层、相关前端与快照清单。
|
||||
2. 核对外键级联与删除护栏，特别是教师的班级、课程、作业、通知和课件。
|
||||
3. 在临时库验证新建和旧库升级；不对真实业务库运行 seed/reset。
|
||||
4. 重新生成 Prisma Client，并按修改范围执行[验收](testing.md)。
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: 当前实现约定
|
||||
description: 课表、周次、学年、岛、设备与课件的现行实现入口。
|
||||
---
|
||||
|
||||
# 当前实现约定
|
||||
|
||||
本页维护当前工作区的实现契约，不汇总多批构建的验收数字。验证命令与实际范围见[验收与测试](testing.md)。
|
||||
|
||||
## 关系化课表
|
||||
|
||||
`ClassPlan/ClassPlanEntry/TimeLayoutItem` 是业务真值。时间点外键独立于排序，`Schedule` 与旧 JSON 列仅保留迁移审计来源。
|
||||
兼容 `/schedules` 写入新模型，日课表、周视图和上课状态共用 `lib/class-plan.ts`。
|
||||
解析顺序是预定、当日临时课表、同日临时层、有效临时群/选定或默认群的规则匹配、全局群、无群默认。
|
||||
轮换使用 weekday/weekCountDiv/weekCountDivTotal 与周次范围，支持 1–9 周；没有新增 Profile 实体。
|
||||
完整档案导入直接保留轮换、空课、停用、时间类型、群组与预定，不经过单双周中间格式。
|
||||
旧数据同班同日同周同时间冲突仅最小 id 进入新表，旧行保留；缺失的历史群组、临时层与时间点名称无法恢复。
|
||||
|
||||
## 权限、成绩与年度升级
|
||||
|
||||
默认权限组、岗位范围、科目写权限分别由 permissions/permission-scope/access 维护，范围并集不授予任课权。
|
||||
全校周数上限在 `term.maxWeeks`，默认 30、允许 1–60；开学日和逐周区间支持全校与班级设置。
|
||||
个人成绩查询关闭后只返回服务端集体聚合，个人明细、原始全班成绩与排名拒绝读取；样本不足或稀疏分段抑制。
|
||||
年度升级由 `term.promotionAt` 和 `PromotionRun.year` 管理，先存快照；运行期到点执行，启动漏跑需管理员预览补跑。
|
||||
毕业班归档，其余升一级，新班不复制任课关系。转出学生由 `lib/students.ts` 统一过滤。
|
||||
|
||||
## 岛与本机配置
|
||||
|
||||
方案存 `config.json.islandLayout`，默认 fixed。当前 custom 即常驻，归一化将兼容字段 residentEnabled 与 custom 对齐。
|
||||
`LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`，只有一个原生岛窗口。
|
||||
自定义常态行与无消息展开行独立编辑，通知列表复用 `ClassicNotifications.vue`；编辑页是主窗口设置子路由。
|
||||
自定义模式通过铃铛提示新消息，点击查看；经典模式普通通知上课暂存、普通叫人可点开胶囊、紧急消息自动展开。
|
||||
课程提醒配置独立保存，课件传输期间由 `CoursewareTransfer.vue` 显示进度。
|
||||
|
||||
## 设备维护与文件
|
||||
|
||||
设备心跳和命令只走 `/api/clients/*`。切服务端或登录状态变化要重置代理计时，并隔离迟到响应；deviceKey 不变。
|
||||
更新从服务端缓存下载，客户端验 SHA256，按下发策略安装；远控白名单动作执行后回执，测试只用假执行器。
|
||||
课件上限 512 MB，服务端流式落盘后创建元数据和推送，客户端逐设备验摘要并回执，不自动运行文件。
|
||||
JSON 快照含课件表，完整恢复还必须带文件实体目录。细节见[课件](../app/courseware.md)。
|
||||
+5
-6
@@ -34,19 +34,18 @@ ClassHelper是一个 **pnpm monorepo**，一份代码产出四个交付物：
|
||||
| 页面 | 内容 |
|
||||
| -------------------------------------------- | ------------------------------------------------ |
|
||||
| [架构总览](architecture.md) | 目录结构、技术栈、模块化设计、几条贯穿全局的约定 |
|
||||
| [REST API](api.md) | 全部接口一览（方法 / 路径 / 权限） |
|
||||
| [REST API](api.md) | 接口分组、常用路径与权限边界 |
|
||||
| [实时事件（Socket.IO）](realtime.md) | 事件清单、房间规则、新增事件要改哪三处 |
|
||||
| [数据模型](data-model.md) | 24 张表、迁移历史、跨库约定 |
|
||||
| [数据模型](data-model.md) | 模型职责、迁移与快照边界 |
|
||||
| [角色与权限](permissions.md) | 权限矩阵与实现位置 |
|
||||
| [动效层与主题](motion.md) | beUI 令牌、CSS `linear()` 弹簧、深色主题 |
|
||||
| [灵动岛设计令牌](winisland-design-tokens.md) | 岛逐项的几何 / 配色 / 排版 token |
|
||||
| [验收与测试](testing.md) | 五套验收脚本怎么跑、哪些用例是脆弱的 |
|
||||
| [验收与测试](testing.md) | 隔离验收、后台冒烟与显式视觉模式 |
|
||||
| [版本迭代与发布](release.md) | 改版本号、出安装包、发 Release 的完整流程 |
|
||||
|
||||
## 仓库里另外两份文档
|
||||
|
||||
- **[完整参考](../reference.md)** —— 产品说明书（原 README 全文），功能行为的**权威来源**；
|
||||
仓库首页那份 README 是精简后的门面页，细节都在这里。
|
||||
- **[功能与源码索引](../reference.md)** —— 各帮助章节与源码入口的统一索引；功能行为在对应章节维护，按源码核验。
|
||||
- **[`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md)** ——
|
||||
工程约定与开发环境注意事项，**改代码前必读**。里面每一条硬约定都对应一处容易踩空的地方，
|
||||
比代码注释更值得先看一遍。
|
||||
规则与实际实现冲突时应查源码并同步修正。
|
||||
+5
-7
@@ -69,15 +69,13 @@ DOM 注入与 Vue 组合式函数在两端各自的 `composables/motion.ts` 里
|
||||
| 页面内容 | `.page > *` 按块错峰浮现（30ms 一档，封顶 180ms） |
|
||||
| 统计数字 | 0 → 实际值滚动（`useCountUp`） |
|
||||
| 主题切换（两端） | View Transition API：从点击位置扩散的圆整页换肤 |
|
||||
| 灵动岛 | **刻意只有单调缓动，不用弹簧** |
|
||||
| 灵动岛 | 独立 SpringValue 帧积分与过冲钳制，见设计令牌 |
|
||||
|
||||
### 灵动岛为什么不用弹簧
|
||||
### 灵动岛使用独立弹簧
|
||||
|
||||
岛的形变由**主进程**缓动窗口尺寸，而冒烟断言「展开过程不震动」「收回过程不抖动」
|
||||
是**逐帧采样岛体几何**并要求单调的 —— 任何带过冲的弹簧都会直接判红。
|
||||
|
||||
所以岛用 `--ch-ease-out` 这类单调曲线，壳的物理仍归它自己的 `src/island/spring.ts`（WinIsland 移植）。
|
||||
**不要拿 beUI 的 `SPRING_*` 去换**。
|
||||
经典与自定义岛的形变使用 `src/island/spring.ts` 的 SpringValue，渲染层驱动岛体几何，主进程管理原生窗口与命中。
|
||||
它与 shared/motion.ts 的 CSS 弹簧是不同实现，不能互相替换参数。默认阻尼、换向与过冲钳制见[设计令牌](winisland-design-tokens.md)。
|
||||
岛动画由应用开关及可见性控制，主窗口 prefers-reduced-motion 规则不直接替代岛自身设置。
|
||||
|
||||
另外岛的 `:hover` 规则必须关在 `@media (hover: hover) and (pointer: fine)` 里 ——
|
||||
教室触摸屏的"幽灵 hover"会让点过「知道了」的按钮永远高亮。
|
||||
|
||||
+50
-191
@@ -1,210 +1,69 @@
|
||||
---
|
||||
title: 角色与权限
|
||||
description: 权限矩阵、科目维度的收口规则，以及"前端隐藏 ≠ 权限"这条纪律。
|
||||
description: 功能权限、岗位范围与班级科目边界。
|
||||
---
|
||||
|
||||
# 角色与权限
|
||||
|
||||
## 矩阵在哪
|
||||
授权分为功能权限、数据范围和业务关系三层，任何一层拒绝都不能操作。
|
||||
shared 的 `permissions.ts` 定义键、标签、默认模板与班级关系规则；服务端 `lib/permissions.ts`、
|
||||
`lib/permission-scope.ts`、`lib/access.ts` 分别计算生效键、查询范围和具体业务断言。
|
||||
|
||||
**唯一一份**在 `packages/shared/src/permissions.ts`：
|
||||
## 身份与权限组
|
||||
|
||||
- 后端 `lib/access.ts` 复用它做断言；
|
||||
- 两端前端用它隐藏入口；
|
||||
- 验收脚本按它逐条断言。
|
||||
账号角色为 ADMIN、TEACHER；班级登录形成 CLASS_DEVICE 会话。学生是 Student 名单，不是账号。
|
||||
HEAD/SUBJECT 是班级关系，级长/部长是岗位组，均不新增 User.role。
|
||||
|
||||
所以不存在"前端一套后端一套"。改权限就改这一个文件（改完记得 `pnpm build:shared`）。
|
||||
| 情况 | 有效功能权限 |
|
||||
| ------------ | ----------------------------------------------------- |
|
||||
| 已分配权限组 | 所有分组键的并集，可以比角色默认更少 |
|
||||
| 没有分组 | 数据库对应角色的可编辑默认组 |
|
||||
| ADMIN | 同上，始终额外保留 permission:manage 与 system:manage |
|
||||
| CLASS_DEVICE | 空集；通过明确允许班级会话的接口与业务断言操作 |
|
||||
|
||||
## 角色判定
|
||||
每请求读取生效权限，编辑后无需等待令牌过期。内置组可改不可删，默认组不是写死的全权限快捷方式。
|
||||
路由使用 requirePermission（AND）、requireAnyPermission（OR），员工与班级端共享读取入口按 requireStaffPermission 等规则检查。
|
||||
具体 API 的额外角色限制以模块路由和服务断言为准，不能把“默认只分配给管理员”写成所有接口硬编码 ADMIN。
|
||||
|
||||
角色只有三种，**没有 `STUDENT`** —— 学生不是账号（见[数据模型](data-model.md)）。
|
||||
班级内的角色由「账号角色 + 与该班级的关系」共同决定：
|
||||
## 数据范围与科目
|
||||
|
||||
| 角色 | 判定方式 | 可见范围 |
|
||||
| --------------------- | ---------------------------------------- | -------------------------- |
|
||||
| `ADMIN` 管理员 | `User.role = ADMIN` | 全部班级 |
|
||||
| 班主任 `HEAD` | `Class.teacherId === 当前用户` | 本班 |
|
||||
| 科任老师 `SUBJECT` | 该班存在 `Course.teacherId === 当前用户` | 被任课的班级 |
|
||||
| `CLASS_DEVICE` 班级端 | 班级码 + 班级密码登录（`classSession`） | 本班（代全班读写个人数据） |
|
||||
| `NONE` | 与这个班没有任何关系 | 什么都看不到 |
|
||||
| 岗位/身份 | 范围 |
|
||||
| ----------- | --------------------------------------------- |
|
||||
| 管理员 | 全部班级；仍须功能键 |
|
||||
| 班主任/教师 | 自己担任班主任或任课的班级，按分组 scope 收敛 |
|
||||
| 级长 | 配置年级 |
|
||||
| 部长 | 配置的一组年级，scopeValue 用逗号分隔 |
|
||||
| 班级端 | 登录绑定班级 |
|
||||
|
||||
判定函数是 `resolveClassRole()`。「科任」的判定源是 **`Course`**（班级 + 科目 + 教师），
|
||||
不是那张已经没有的 `ClassTeacher` 协作表。
|
||||
空年级/部配置不放行。设备写操作只合并含对应功能键的分组范围，不能借只读组扩权。
|
||||
科目编辑再由 `assertCanManageSubjectContent` 检查：管理员可管理，教师仅自己任课科目，无科目内容归班主任。
|
||||
班主任不任教某科就不能改该科的作业或成绩；班级端只允许作业写入，不能写成绩。
|
||||
|
||||
## 权限矩阵
|
||||
| 业务 | 主要功能键与额外边界 |
|
||||
| ---------------- | ---------------------------------------------------------------------------- |
|
||||
| 名单读取/管理 | roster:read / roster:manage；管理仍须管理员或本班班主任断言 |
|
||||
| 教师列表/维护 | teacher:read / teacher:manage；导入名单另检查导入权限和角色 |
|
||||
| 日课表写入 | schedule:write + 管理员/本班班主任 |
|
||||
| 全校时间表写入 | timetable:manage；默认给 ADMIN |
|
||||
| 作业/成绩 | homework:write / grade:write 或 grade:import，再按班级科目收口 |
|
||||
| 通知/叫人 | notification:publish / call:create，再检查班级范围 |
|
||||
| 课件 | courseware:read / courseware:write，上传和推送自己的文件还受本人授课班级约束 |
|
||||
| 客户端维护/远控 | client:read、client:manage、remote:control，写操作按对应键范围 |
|
||||
| 版本与安装包写入 | client:update；旧 client:update-push 不再作为写入口要求 |
|
||||
| 数据库/系统/权限 | database:manage / system:manage / permission:manage |
|
||||
|
||||
下表描述角色与班级关系允许的范围；员工还必须拥有对应功能权限，管理员也不例外。
|
||||
名单读取使用 `roster:read` / `teacher:read`，管理使用独立的 `roster:manage` / `teacher:manage`。
|
||||
日志与客户端开发者模式不再单列无效权限键，服务端系统设置由 `system:manage` 控制。
|
||||
完整键目录读取 `PERMISSION_KEYS`，不在文档维护固定键数。
|
||||
|
||||
| 操作 | 管理员 | 班主任 | 科任老师 | 班级端 |
|
||||
| ----------------------------------------------------------- | :----: | :----------: | :------: | :--------: |
|
||||
| 班级创建 / 修改 / 删除 | ✅ | ❌ | ❌ | ❌ |
|
||||
| 分配班主任与各科任课老师 | ✅ | ❌ | ❌ | ❌ |
|
||||
| 学生名单管理（增删 / 导入 / 调班 / 转出） | ✅ | ✅（仅本班） | ❌ | ❌ |
|
||||
| 教师录入（新建 / 导入名单 / 修改密码） | ✅ | ❌ | ❌ | ❌ |
|
||||
| 毕业归档 / 学年升级 / 学期周次 | ✅ | ❌ | ❌ | ❌ |
|
||||
| 数据库管理（备份 / 导入导出 / 一键切换） | ✅ | ❌ | ❌ | ❌ |
|
||||
| 课表管理（增删改 / 时间配置导入） | ✅ | ✅（仅本班） | ❌ | ❌ |
|
||||
| 布置作业（**自己任教的科目**） | ✅ | ✅（本班） | ✅ | ✅ |
|
||||
| 叫人 / 发布通知 | ✅ | ✅ | ✅ | ✅ |
|
||||
| 成绩录入 / 修改 / 导入（**自己任教的科目**） | ✅ | ✅（本班） | ✅ | ❌ |
|
||||
| 查看本班成绩汇总 | ✅ | ✅ | ✅ | ✅ |
|
||||
| 按学号查询学生成绩明细 | ✅ | ✅ | ✅ | 需班级开关 |
|
||||
| 查看 ClassHelper 班级端在线状态 | ✅ | ✅ | ✅ | ❌ |
|
||||
| 班级密码 / 班级码维护（`PATCH /classes/:id/class-account`） | ✅ | ❌ | ❌ | ❌ |
|
||||
## 前端门控与成绩隐私
|
||||
|
||||
## 科目维度的收口（本次重构的核心规则）
|
||||
Web 菜单属性来自路由，`meta.roles` 粗筛、`meta.permission` 细筛；先 ensurePermissions 再按生效集合判断。
|
||||
服务端仍检查功能、范围与业务关系，直接构造请求不能绕过。
|
||||
岗位范围可以扩大读范围，不能自动扩大科目写权限，也不能替代课件的本人任课关系。
|
||||
班级成绩查询开关仅员工按业务权限修改；关闭后班级端仍看集体聚合，个人明细、原始全班成绩和排名返回拒绝。
|
||||
稀疏分段与补集抑制，服务端不向客户端下发个人原始成绩再聚合。
|
||||
|
||||
作业与成绩不是"凡是能进这个班就能改"，而是**再按科目收一道**：
|
||||
## 设备维护
|
||||
|
||||
| 情形 | 谁可以写 |
|
||||
| --------------------------- | ------------------------------------------------------ |
|
||||
| 管理员 | 全部 |
|
||||
| 挂了科目（`courseId` 有值） | **该科的任课老师**（`Course.teacherId`） |
|
||||
| 没挂科目（`courseId` 为空） | 本班**班主任** |
|
||||
| ClassHelper 班级端 | 只有**作业**可以（老师在教室随手录一条）；**成绩不给** |
|
||||
|
||||
于是：班主任若不教这一科，就改不了这一科的作业与成绩 —— 这正是需求
|
||||
「班主任不自动拥有所有科目作业成绩编辑权，只有同时是该科科任老师时才有该科权限」。
|
||||
|
||||
实现在 `lib/access.ts` 的 **`assertCanManageSubjectContent(user, classId, courseId, action, { allowClassDevice })`**，
|
||||
作业 / 成绩 / 叫人三处写入统一走它。
|
||||
|
||||
## 权限键与权限组（2026-10 起：权限组驱动，角色只是默认模板）
|
||||
|
||||
从权限组重构开始，**功能级准入不再看角色，而看权限键**：键目录同样是
|
||||
`packages/shared/src/permissions.ts` 的 `PERMISSION_KEYS`（形如 `domain:action`，
|
||||
中文名在 `PERMISSION_LABELS`、分组在 `PERMISSION_CATEGORIES`）。路由上挂的是
|
||||
|
||||
```ts
|
||||
requirePermission('notification:publish'); // 需要全部列出的键
|
||||
requireAnyPermission('grade:write', 'grade:import'); // 有任意一个即可
|
||||
```
|
||||
|
||||
**生效规则（四句话）**：
|
||||
|
||||
| 账号 | 有效权限 |
|
||||
| ------------------------ | ----------------------------------------------------------------------- |
|
||||
| `ADMIN` | 按权限组计算；其中 `permission:manage` / `system:manage` **不可被剥夺** |
|
||||
| `CLASS_DEVICE`（班级端） | 空集，**不受任何分组影响**（它的能力来自班级维度断言） |
|
||||
| 被分配了权限分组 | 分组键的**并集**（可以比角色默认更少 —— 这就是"能收权"） |
|
||||
| 没有被分配任何分组 | 使用可编辑的角色默认权限组 |
|
||||
|
||||
默认模板逐条镜像重构前的 `requireRole`，所以"不动分组"= 行为与以前完全一致。
|
||||
实现见 `packages/server/src/lib/permissions.ts` 的 `loadEffectivePermissions()`：它**每个请求实时查库**
|
||||
（不缓存），因此管理员改完分组**立刻生效**，不需要等令牌过期 —— 与下面「鉴权中间件会回查数据库」是同一个理由。
|
||||
|
||||
**管理接口**（`packages/server/src/modules/permissions/`）：
|
||||
|
||||
| 方法与路径 | 权限要求 | 说明 |
|
||||
| --------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------- |
|
||||
| `GET /api/permissions/me` | 登录即可 | 当前账号的有效权限与来源（前端据此显示/隐藏入口） |
|
||||
| `GET /api/permissions/catalog` | `permission:manage` | 全部权限键（含中文名、分类、默认角色、不可移除标记） |
|
||||
| `GET/POST /api/permissions/groups`、`PATCH/DELETE /groups/:id` | `permission:manage` | 分组 CRUD；内置分组（`builtin=true`）可改不可删 |
|
||||
| `GET /api/permissions/users`、`PUT /api/permissions/users/:id/groups` | `permission:manage` | 成员列表与「整组替换」式分配；管理员与教师可分配；班级端不参与 |
|
||||
|
||||
**一条不能松的边界**：权限组只管**功能/路由级**准入；**班级维度的科目规则不可被权限组覆盖**。
|
||||
换句话说，给某人授了 `homework:write` 只代表"他能进布置作业这条路由"，
|
||||
**具体到哪个班、哪个科目**仍然由 `assertCanManageSubjectContent` 判（下一节）。
|
||||
否则「班主任能布置别人科目的作业」这个老 bug 会从权限组这条新路重新长出来。
|
||||
|
||||
## 实现要点
|
||||
|
||||
**路由级只做权限过滤**：`requirePermission('…')`（需要列出的键全有）或
|
||||
`requireAnyPermission('…')`（任意一个即可）。改造前这里是 `requireRole('ADMIN','TEACHER')`，
|
||||
按键目录里的 `PERMISSION_DEFAULT_ROLES` 逐条映射过来，因此**默认行为没有变化**。
|
||||
403 的文案会直接点名缺哪个键：「当前账号缺少「X」权限，请联系管理员在「权限组」里分配」。
|
||||
|
||||
**班级维度的判断在服务层**：`src/lib/access.ts` 提供
|
||||
|
||||
```
|
||||
assertCanManageClasses / assertCanAssignTeachers / assertCanManageRoster
|
||||
assertCanManageSchedule / assertCanPublishNotification
|
||||
assertCanManageGrades / assertCanManageSubjectContent
|
||||
```
|
||||
|
||||
**列表数据用 `resolveClassScope()` 收敛**（`classId in [...]`），单条接口直接断言；
|
||||
越权一律 403。
|
||||
|
||||
**鉴权中间件会回查数据库**（`middleware/auth.ts`）：JWT 校验之后重新读一次账号，
|
||||
所以改了角色 / 班级关系会**立即生效**，不用等令牌过期。班级端会话则回查 `Class` 表。
|
||||
|
||||
**班级端的成绩查询开关**：`Class.studentGradeQueryEnabled`（默认开启）。
|
||||
关闭后班级端调 `GET /grades/student/:studentNo` 一律 403，教师端不受影响 ——
|
||||
这就是需求「是否允许学生通过班级端查看本人明细，由教师或管理员开关控制」。
|
||||
|
||||
## 前端隐藏 ≠ 权限
|
||||
|
||||
前端的隐藏只是"别让人看见入口"：
|
||||
|
||||
- 教师登录时侧边栏不显示「班级管理 / 学生管理 / 教师管理 / 毕业归档 / 学期周次 / 数据库管理 / 权限组 / 客户端设备」；
|
||||
- 课表页的增删改按钮只对「管理员或本班班主任」显示；
|
||||
- 成绩页的录入 / 删除按钮对教师显示（科任也能用，**具体到某一条由后端按科目判定**）。
|
||||
|
||||
**门控怎么写的**：路由 `meta.roles` 做粗筛（角色），`meta.permission` 做细筛（权限键）——
|
||||
`packages/web-admin/src/router/index.ts` 的 `beforeEach` 会 `await auth.ensurePermissions()`
|
||||
再问 `auth.can(key)`（管理员同样按生效集合判断，仅保留权限和系统管理入口），不通过就 **fail-closed** 回仪表盘；
|
||||
侧栏菜单项同理带 `permission` 字段（`AdminLayout.vue` 的 `visibleMenuItems`）。
|
||||
`auth.ensurePermissions()` 读的就是 `GET /api/permissions/me`。
|
||||
|
||||
但这些页面**直接输网址也进不去**（路由 `meta.roles` 会把非管理员挡回仪表盘），
|
||||
而且**所有写入请求服务端都会再断言一次**。绕过菜单、绕过前端，一样 403。
|
||||
|
||||
> 新增视图时别忘了两处：路由的 `meta.roles` + 服务层对应 service 里的 `assertCanXxx`。
|
||||
> 只做其中一个都等于没做。
|
||||
|
||||
## 学生没有账号的两个反向约束
|
||||
|
||||
1. **学生不能登录，而且根本不存在可以登录的学生账号**。`User` 表里没有学生行，
|
||||
拿学号当账号登录只会得到 401（"工号或密码错误"），连"这个学号存在吗"都探测不出来。
|
||||
2. **学生没有任何密码接口**。`POST /students/:id/reset-password` 已删除（调用返回 404），
|
||||
新建学生也不设密码 —— `Student` 表里压根没有那一列。
|
||||
|
||||
## 默认权限组与客户端维护（2026-10-16）
|
||||
|
||||
管理员和教师各有一个默认权限组；未分配其他组时使用对应默认组，编辑后立即生效。
|
||||
默认组可以改名、增减权限，但不能删除。分配多个组时取并集。
|
||||
管理员始终保留 `permission:manage` 和 `system:manage`，防止失去管理入口。
|
||||
班级端不参与账号权限组，班级与科目范围的检查保持生效。
|
||||
|
||||
「客户端」页统一显示设备心跳、版本、是否接受自动更新、最近指令结果和安装时机。
|
||||
更新先从本服务器下载并校验 SHA256，再按所选时机安装：
|
||||
|
||||
- 立即更新：下载完成后安装并重启客户端，会中断当前客户端界面。
|
||||
- 放学后更新：按服务器当天日期，等待所选最早时间与本班最后一节课结束时间的较晚者；上课中继续等待。
|
||||
- 空闲时更新：不上课且主窗口隐藏满五分钟后安装。
|
||||
|
||||
离线设备上线后补领更新；取消下发后，已下载的安装包不再自动安装。
|
||||
客户端关闭自动更新时，任何下发策略都不会强制安装。
|
||||
远控由管理端确认下发；客户端立即执行白名单动作并回传真实执行结果。
|
||||
|
||||
联动插件及相关接口已下线；升级迁移会删除旧联动设备和推送记录，保留业务课表、通知及离线 JSON 导入。
|
||||
服务端兼容旧客户端的心跳字段读取，旧设备可领取修复版；第一次升级仍遵循旧版空闲安装条件，新策略需修复版客户端。
|
||||
|
||||
## 日课表与岗位范围（2026-10-17）
|
||||
|
||||
| 能力 | 新权限键 | 默认角色 |
|
||||
| -------------------------- | ------------------ | -------- |
|
||||
| 全校时间表与时间点管理 | `timetable:manage` | ADMIN |
|
||||
| 安装包、目标版本与安装策略 | `client:update` | ADMIN |
|
||||
|
||||
`client:update-push` 只保留旧配置兼容标识；下发与安装包写入口统一检查 `client:update`。
|
||||
新增权限同步出现在 shared 的键目录、标签、类别与默认角色表；升级迁移为管理员默认组补齐新键。
|
||||
|
||||
| 内置教师岗位组 | 默认功能 | 数据范围 |
|
||||
| -------------- | ---------------------------------------- | -------------------------------- |
|
||||
| 班主任 | 教学内容 + 查看/管理设备，不含版本下发 | 自己担任班主任的班级 |
|
||||
| 教师 | 作业、成绩、通知、叫人、课表与名单读取 | 班主任与任教班级 |
|
||||
| 级长 | 设备、远控、名单/班级/课表/成绩/看板读取 | 管理员配置的年级 |
|
||||
| 部长 | 同级长 | 管理员配置的一组年级（逗号分隔） |
|
||||
|
||||
四组 `builtin=true`、`defaultRole=null`；账号仍是 TEACHER。实际范围来自分组并集，
|
||||
空年级/部范围不授权。通用查询通过 `teacherScopeWhere/resolveClassScope`，
|
||||
设备写入还只合并含对应功能键的分组范围。管理员的 `permission:manage/system:manage` 不可剥夺。
|
||||
范围从不赋予科目编辑权，仍须 `assertCanManageSubjectContent` 检查 Course 任课关系。
|
||||
|
||||
教师名单页复用学生管理视图与导出，路由 `roster:read`，隐藏编辑/调班/导入操作；服务端过滤范围和转出学生。
|
||||
成绩关闭个人查询时只返回服务端聚合；班级端无个人明细、排名或极值，稀疏样本抑制，教师/管理员不受该个人查询开关影响。
|
||||
|
||||
旧时间表导入接口的写入/删除也要求 `timetable:manage`，避免绕过统一时间表权限；离线整套课表导入仍可由本班班主任使用，创建班级自有时间点。
|
||||
`/api/clients/heartbeat` 和命令回执供已登录设备使用，不依赖班级端的空权限集合；服务端校验 deviceKey 与班级归属。
|
||||
远控从管理端确认下发，客户端执行后回传真实结果。更新文件由服务端缓存，教室机验 SHA256，
|
||||
按立即、放学后、空闲策略安装；关闭自动更新不会强制安装。详见[更新与升级](../management/upgrade.md)。
|
||||
+35
-65
@@ -1,79 +1,49 @@
|
||||
---
|
||||
title: 实时事件（Socket.IO）
|
||||
description: 事件清单、房间规则，以及新增一个实时事件要同时改哪三处。
|
||||
description: 实际事件与房间、断线恢复和客户端提醒分工。
|
||||
---
|
||||
|
||||
# 实时事件（Socket.IO）
|
||||
|
||||
## 连接
|
||||
连接使用 `io(url, { auth: { token } })`，服务端在握手校验 JWT。
|
||||
事件与房间定义在 shared 的 `constants.ts`，载荷类型在 shared 的 `types.ts`，以这些契约和发送点为准。
|
||||
|
||||
```ts
|
||||
io(url, { auth: { token } }); // 握手阶段用 JWT 鉴权
|
||||
```
|
||||
## 房间与定向推送
|
||||
|
||||
客户端断线由 Socket.IO 自动重连。教室机器断线期间的变更，重连后靠各页重新拉取补齐
|
||||
（客户端在检测到服务器恢复时会触发 `onServerRecovered`）；**灵动岛的上课时段暂存通知**由服务端保留、
|
||||
下课后补发，不依赖重连。
|
||||
| 房间 | 作用 |
|
||||
| --------------- | -------------------------------------------------- |
|
||||
| class:{classId} | 某班级的业务广播 |
|
||||
| session:{id} | 会话定向名；员工 id 为账号 id，班级端 id 为班级 id |
|
||||
| role:{role} | 角色房间名，定义在共享常量 |
|
||||
| teacher:{id} | 教师房间名，定义在共享常量 |
|
||||
| students | 班级端连接的广播房间，代表全班，不是个人学生账号 |
|
||||
| teachers | 教师和管理员连接的广播房间 |
|
||||
|
||||
## 事件清单
|
||||
`realtime/socket.ts` 当前显式 join 可访问的 class 房间与 students/teachers 广播房间；
|
||||
同时在 connected 载荷列出 session/role 名。不能把共享常量或该列表当成所有房间均已成功 join 的证明，实际订阅以 join 调用为准。
|
||||
业务经 `realtime/bus.ts` 的 emitToClass/emitToSession/emitToRooms 推送。
|
||||
叫人记录属于班级通知，并发送班级广播与班级会话定向事件；学生本身没有连接和个人房间。
|
||||
|
||||
事件名定义在 `@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}` / 班级设备） |
|
||||
| `class:join` / `class:leave` / `ping` | 客户端 → 服务端 | 手动订阅班级（服务端二次校验权限） |
|
||||
| 事件 | 内容 |
|
||||
| ------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| connected | `{ sessionId, role, rooms }` |
|
||||
| notification:new / notification:deleted | 通知新增/撤回；客户端同步列表、缓存和岛队列 |
|
||||
| homework:new / homework:updated / homework:status | 作业新增、修改/删除与完成状态 |
|
||||
| grade:updated | 成绩变化通知；载荷按范围与隐私规则发送，客户端按需重新读取 |
|
||||
| schedule:updated / class:updated | 课表/班级变化，重新加载对应数据 |
|
||||
| courseware:changed | 课件列表/可见范围/推送变化，触发客户端检查 |
|
||||
| client:release-progress | 服务端缓存客户端安装包的进度 |
|
||||
| call:new | 叫人内容，与 notification:new 按同 id 合并去重 |
|
||||
| class:join / class:leave / ping | 客户端订阅/离开班级、探活；join 重新校验范围 |
|
||||
|
||||
## 房间规则
|
||||
事件没有持久离线消息队列保证。重连后由页面和恢复钩子重新拉取业务数据。
|
||||
普通通知上课暂存是客户端岛控制器的本机行为，服务端仍即时落库广播；
|
||||
断线通知补弹由客户端未读读取逻辑处理，课件未收任务由服务端保存、客户端心跳补领。
|
||||
经典/自定义模式的展示差异见[通知与提醒](../app/notifications.md)。
|
||||
|
||||
房间名定义在 `SOCKET_ROOMS`：
|
||||
## 修改事件
|
||||
|
||||
| 房间 | 谁在里面 |
|
||||
| --------------------- | --------------------------------- |
|
||||
| `class:{classId}` | 这个班的所有在线端 |
|
||||
| `user:{userId}` | 某个用户自己的连接 |
|
||||
| `teacher:{teacherId}` | 某个教师 |
|
||||
| `role:{role}` | 某一角色（`ADMIN` / `TEACHER` …） |
|
||||
| `students` | 全部 ClassHelper 班级端连接 |
|
||||
| `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)。
|
||||
同步修改共享事件名与载荷、服务端发送点、Web `stores/realtime.ts`、客户端 `stores/realtime.ts` 及相关缓存/岛逻辑。
|
||||
不要手写事件名；只改服务端会导致前端静默不刷新。涉及成绩时另检查隐私载荷和班级范围。
|
||||
+57
-211
@@ -1,235 +1,81 @@
|
||||
---
|
||||
title: 版本迭代与发布
|
||||
description: 改版本号、跑验收、打安装包、发 GitHub Release、发布文档站——一次完整发布的命令清单。
|
||||
description: 版本单一来源、本地与发布文件名、验证和发布同步。
|
||||
---
|
||||
|
||||
# 版本迭代与发布
|
||||
|
||||
## 一条总原则
|
||||
日常文档/代码维护不自动改版本。版本唯一修改入口是 scripts/version.mjs；先执行 pnpm version:check。
|
||||
正式新发布执行 pnpm version:bump patch|minor|major，指定固定版本的本地重构建保持版本不变。
|
||||
版本落点由脚本清单决定，不另维护“文件数/落点数”。
|
||||
|
||||
> **版本号按「发布」迭代，不按「提交」迭代。**
|
||||
|
||||
日常的 `feat` / `fix` 提交**不动版本号**。只有当你要产出一批安装包、在 GitHub 上开一个 Release 时，
|
||||
更新检查接口全都按版本号对齐；每次提交都动它，等于每天都在发版，用户那边的「检查更新」就废了。
|
||||
|
||||
| 算一次发布 | 不算 |
|
||||
| --------------------------------------- | ---------------------------- |
|
||||
| 攒够一批功能 / 修好一个用户能感知的 bug | 改注释、改文档、重构、加测试 |
|
||||
| 要给别人一份新安装包 | 只在自己机器上跑 |
|
||||
|
||||
## 每次发版必须一起交付的四样东西
|
||||
|
||||
打安装包只是其中一件。**少一样都算「发到一半」**：
|
||||
|
||||
| # | 交付物 | 落在哪 | 怎么做 |
|
||||
| --- | ------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| ① | **更新日志** | GitHub Release 的正文 | 手写，草稿放 `releases/ReleaseNotes-<版本>.md`，用 `--notes-file` 发布。别只挂自动生成的列表 |
|
||||
| ② | **Linux 服务端包** | Release 上的 `classhelper-server-linux-x64-<版本>.tar.gz` | tag 推上去由 CI 构建；**推完去 Actions 确认没红**（见第 7 步） |
|
||||
| ③ | **文档** | `docs/reference.md`（功能说明 + 验收对照表）与相关章节 | 新增功能补对应小节；改交付形态一并改第 2 章 / 第 7 章 |
|
||||
| ④ | **官网与 README** | `website/index.html`、`website/download.html`、`README.md` | 新功能补进官网功能块与 README 功能清单；版本号由脚本覆盖 |
|
||||
|
||||
更新日志的骨架（照 1.2.0 / 1.3.0 那两份写）：
|
||||
**一句话定位 → 分节讲功能 → ⚠️ 升级须知（含会自动应用的迁移）→ 验收表 → 产物表**。
|
||||
验收表里**只写真跑过的数字**，没跑就直说没跑，不要照抄上一版的。
|
||||
|
||||
## 版本号写在哪（12 处 / 12 个文件）
|
||||
|
||||
同一个版本号分散在 12 个落点上，**手工改必然漏一处**，而漏掉的那处不会报错：
|
||||
|
||||
| 文件 | 内容 |
|
||||
| ---------------------------------------------------------------- | ---------------------------------- |
|
||||
| `package.json` | 单一来源（服务端运行时读它） |
|
||||
| `packages/{shared,server,web-admin,desktop-client}/package.json` | 各包的版本 |
|
||||
| `deploy/package.runtime.json` | 安装包 / 容器里的运行时依赖清单 |
|
||||
| `deploy/docker-compose.yml`、`docker-compose.sqlite.yml` | 镜像 tag 的默认值 |
|
||||
| `website/index.html` × 3 | 官网顶栏徽标 / 首屏芯片 / 页脚 |
|
||||
| `website/download.html`（`<meta name="ch-version">`） | 下载页读不到版本清单时的兜底版本号 |
|
||||
|
||||
最后两行值得单独说：官网是**纯静态站、没有构建步骤**，没有哪段代码会去读 `package.json`，
|
||||
所以那几处只能靠脚本一起改 —— 漏了的话首页会一直挂着旧版本号（而那是别人看到的第一眼），
|
||||
下载页则会给离线访客一串指向**不存在版本**的直链。
|
||||
|
||||
所以**改版本号的唯一入口是脚本**：
|
||||
|
||||
```bash
|
||||
pnpm version:check # 逐处列出并比对，不一致 exit 1
|
||||
pnpm version:bump patch # 1.1.2 → 1.1.3
|
||||
pnpm version:bump minor # 1.1.2 → 1.2.0
|
||||
pnpm version:bump major # 1.1.2 → 2.0.0
|
||||
pnpm version:check # 再确认一次
|
||||
```
|
||||
|
||||
脚本按表逐个改写，**任何一处没匹配到或匹配到多处就直接失败退出**，不做"尽力而为"的部分改写。
|
||||
|
||||
## 一次完整的发布
|
||||
|
||||
下面这一串命令就是全部流程，逐条照抄即可。
|
||||
|
||||
### 1. 改版本号
|
||||
## 构建与验证
|
||||
|
||||
```bash
|
||||
pnpm version:check
|
||||
pnpm version:bump patch
|
||||
```
|
||||
|
||||
### 2. 本地体检
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm check:icons
|
||||
pnpm docs:check # 文档站构建（警告即失败）
|
||||
```
|
||||
|
||||
### 3. 跑验收
|
||||
|
||||
```bash
|
||||
pnpm dev:server # 另开一个终端跑着
|
||||
|
||||
pnpm docs:check
|
||||
pnpm verify:e2e
|
||||
|
||||
pnpm build:desktop && pnpm verify:desktop
|
||||
pnpm build && pnpm verify:web
|
||||
pnpm verify:v14
|
||||
pnpm verify:courseware
|
||||
pnpm build:desktop
|
||||
pnpm verify:desktop
|
||||
pnpm --filter @classhelper/web-admin build
|
||||
pnpm verify:web:isolated
|
||||
pnpm dist:all
|
||||
pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe" --offline
|
||||
```
|
||||
|
||||
哪一项红了先看[验收与测试](testing.md)的「失败时先别改代码」——
|
||||
里面列了几个已知脆弱的用例，它们红不代表代码坏了。
|
||||
以上按发布改动范围执行；显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。
|
||||
完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本，最新包核验完成后按用户要求清理旧归档。
|
||||
2026-10-18 工作区清理后，1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。
|
||||
|
||||
### 4. 打安装包
|
||||
## 产物与文件名
|
||||
|
||||
| 本地构建产物 | GitHub Release 上传名 |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------ |
|
||||
| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-setup.exe | ClassHelper-<版本>-x64-client-setup.exe |
|
||||
| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe | ClassHelper-<版本>-x64-client-portable.exe |
|
||||
| releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe | ClassHelper-<版本>-x64-server-setup.exe |
|
||||
| releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz | 同名 |
|
||||
|
||||
Linux 还需同名 .tar.gz.sha256。正式 Linux 包在 Linux runner 运行 pnpm dist:server:linux；
|
||||
Windows 上的交叉构建仅作验证，可能缺目标平台的 Prisma engine。
|
||||
构建中间物可再生成，不将 win-unpacked、server staging 或解包副本当交付物保留。
|
||||
|
||||
## 更新日志与校验
|
||||
|
||||
releases/ReleaseNotes-<版本>.md 维护本批包的功能、升级须知、实际验证范围与文件清单。
|
||||
它描述该构建批次，不能把之后的源码功能写成旧包已经包含。
|
||||
SHA256SUMS-<版本>.txt 用上传名记录各文件哈希；本地查验必须先按上表映射，不能因为本地文件没带 client/server 后缀就判断丢包。
|
||||
可在 PowerShell 对 client/server 安装包运行 Get-FileHash -Algorithm SHA256，将三项实际结果按上传名写入清单。
|
||||
不要仅对客户端目录做重定向而漏掉服务端；Linux 行待 CI 完成后同步。
|
||||
|
||||
## 发布同步
|
||||
|
||||
完成验证和本地更新日志后，检查 diff，按用户授权提交和推送 master；不要把其他未完成改动一并提交。
|
||||
将三个 Windows 包复制到独立的 .cache/release-staging/<版本>/，使用上传名，避免通配符混入别的版本。
|
||||
先准备当前 Windows SHA256 清单并随 Release 上传。创建 Release 时显式 --target master 或明确提交，说明用 --notes-file。
|
||||
ClassIsland 插件已退役，不再上传插件资产。
|
||||
|
||||
```bash
|
||||
|
||||
# <版本> 和提交均替换为本次实际值
|
||||
gh release create v<版本> --target master --title "ClassHelper v<版本>" --notes-file releases/ReleaseNotes-<版本>.md
|
||||
gh release upload v<版本> <三个已按上传名暂存的EXE> releases/SHA256SUMS-<版本>.txt
|
||||
```
|
||||
|
||||
产物落在 `releases/<组件>/<版本>/`：`安装包/`（交付物）、`构建中间/`（可重新生成）。
|
||||
**没有免安装目录** —— 组装/解包出来的那一份是中间物，打包脚本用完就删（见仓库根 `AGENTS.md` §4
|
||||
「交付产物归集」）。
|
||||
推送 v* tag 触发 release-linux-server.yml，按 tag 检出，在 Ubuntu 构建并上传 Linux 包、独立 .sha256，合并跨组件清单。
|
||||
等待 Actions 成功，再下载 Linux 文件和最终 SHA256SUMS 同步回本地；检查清单的 Windows 行仍与本次文件一致。
|
||||
如需重跑，可手动运行该 workflow，指定准确 tag 和 attach=true。master 修复不会自动改变旧 tag 指向。
|
||||
|
||||
打完之后**对打包副本再验一次**（开发产物通过 ≠ 用户机器上的副本通过）：
|
||||
官网和文档站由 pages.yml 拼装同一个站点：官网根、文档 /docs/。文档版本徽标读根 package.json，
|
||||
官网和下载页兜底版本由 version 脚本维护。Linux workflow 与 Pages 是独立流水线，分别确认结果。
|
||||
官网行为变化同步 README 与相应帮助章节，功能索引放[源码索引](../reference.md)。
|
||||
|
||||
```bash
|
||||
# 默认指向装好的客户端；推荐直接拿刚打出来的便携版单文件当被测副本
|
||||
pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe"
|
||||
```
|
||||
## 已发布版本与回滚
|
||||
|
||||
> Linux 包**只能在 Linux 上构建**（依赖是平台相关的），所以不在这条命令里 ——
|
||||
> 它由 GitHub Actions 出，见第 7 步。
|
||||
|
||||
### 5. 生成跨组件哈希清单
|
||||
|
||||
`releases/SHA256SUMS-<版本>.txt` 是**人读的**（表头 + 体积 + 说明），由发布流程维护，
|
||||
本地只写 Windows那几行：
|
||||
|
||||
```bash
|
||||
cd releases/client/<版本>/安装包 && sha256sum *.exe > ../../../SHA256SUMS-<版本>.txt # 按实际文件名整理
|
||||
```
|
||||
|
||||
（Linux 那一行由 CI 在第 7 步里**合并**进去，不要手工写。）
|
||||
|
||||
### 6. 提交并推上去
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "chore(release): 1.1.3"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
提交信息用 Conventional Commits + 模块 scope，描述写中文，可多 scope，例如
|
||||
`fix(island): 胶囊"点不动"的根因——窗口必须始终可激活`。
|
||||
|
||||
### 7. 开 Release
|
||||
|
||||
上传前先把产物改成 ASCII 名 —— 构建产物是中文名，Release 上的名字是给别人看、要贴进脚本的：
|
||||
|
||||
```bash
|
||||
V=1.1.3
|
||||
mkdir -p .cache/release-staging
|
||||
cp "releases/client/$V/安装包/"*-x64-setup.exe ".cache/release-staging/ClassHelper-$V-x64-client-setup.exe"
|
||||
cp "releases/client/$V/安装包/"*-x64-portable.exe ".cache/release-staging/ClassHelper-$V-x64-client-portable.exe"
|
||||
cp "releases/server/$V/安装包/"*-x64-setup.exe ".cache/release-staging/ClassHelper-$V-x64-server-setup.exe"
|
||||
|
||||
gh release create v$V --title "ClassHelper v$V（<一句话定位>）" --notes-file "releases/ReleaseNotes-$V.md"
|
||||
gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --clobber
|
||||
```
|
||||
|
||||
| 构建产物 | Release 上的名字 |
|
||||
| --------------------------- | -------------------------------------------- |
|
||||
| `<客户端>-x64-setup.exe` | `ClassHelper-<版本>-x64-client-setup.exe` |
|
||||
| `<客户端>-x64-portable.exe` | `ClassHelper-<版本>-x64-client-portable.exe` |
|
||||
| `<服务端>-x64-setup.exe` | `ClassHelper-<版本>-x64-server-setup.exe` |
|
||||
|
||||
这三个名字是**外部契约**：README 的「开始使用」表、官网下载页读不到版本清单时拼的兜底直链，
|
||||
都按它们写；改名要三处一起改。
|
||||
|
||||
`gh release create` 会**创建 tag 并推送**，这一步会自动触发
|
||||
[`release-linux-server.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/release-linux-server.yml)
|
||||
构建 Linux 包（ubuntu runner）。它跑完之后会：
|
||||
|
||||
1. 把 `classhelper-server-linux-x64-<版本>.tar.gz` 与 `.sha256` 挂到 Release 上；
|
||||
2. **把 Linux 那一行合并进** `SHA256SUMS-<版本>.txt`（保留 Windows那几行）。
|
||||
|
||||
> **顺序很重要**：Linux workflow 是在最后一步才去合并 SHA256SUMS 的，
|
||||
> 所以第 5 步那份清单必须**先上传**。万一手速反了（workflow 先跑完、你后上传），
|
||||
> 重新跑一次 `gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true` 就能把那一行补回来。
|
||||
|
||||
想手动触发（比如只需要重出 Linux 包）：
|
||||
|
||||
```bash
|
||||
gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true
|
||||
```
|
||||
|
||||
> **CI 是按 tag 的 ref 检出源码的。** 发完版又发现构建脚本（或任何影响出包的代码）要修时，
|
||||
> **光推 master 不够** —— CI 仍会拿旧 tag 的源码跑，得把 tag 挪到修复后的提交：
|
||||
> `git tag -f v<版本> <提交> && git push --force origin v<版本>`，tag 一变会自动重跑。
|
||||
> 别拿「Windows 侧绿不绿」当判据：`pnpm dist:server` 走的是另一条分支，
|
||||
> Linux 那一步红的时候本地完全看不出来。
|
||||
>
|
||||
> 另外，本页第 8 步的「官网与文档站」是**另一条**流水线（master 推送触发）——
|
||||
> 它绿不代表 Linux 包出来了，推完 tag 要去 `gh run list --limit 5` 看一眼。
|
||||
|
||||
### 8. 官网与文档站
|
||||
|
||||
**不用做任何事。** 推送 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
|
||||
`package.json` 变过，
|
||||
[`pages.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/pages.yml)
|
||||
就会把两者构建成**同一个** GitHub Pages 站点发出去：
|
||||
|
||||
```
|
||||
https://lovechengke.github.io/ClassHelper/ ← 官网
|
||||
https://lovechengke.github.io/ClassHelper/docs/ ← 文档站
|
||||
```
|
||||
|
||||
（一个仓库在 Pages 上只有一个站点，所以是拼在一起发的 —— 官网在根、文档站在 `/docs/` 下。）
|
||||
|
||||
文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了；
|
||||
官网首屏那排芯片、顶栏徽标与页脚里的版本号，以及下载页那个兜底版本号，
|
||||
也都是**由 `pnpm version:bump` 一起改的**（它们是那 12 个落点里的四个）。
|
||||
|
||||
> 官网的「立即下载」会跳到 `/download.html`，那一页的版本清单是**当场**从 GitHub Releases 读的
|
||||
> （读不到才退回上面那个兜底版本号），所以发完 Release 不用重新部署那一页 —— 但**兜底值要跟着发版一起改**，
|
||||
> 不然离线访客点到的就是旧版本的直链。
|
||||
|
||||
### 9. 检查
|
||||
|
||||
- [ ] Release 页面上三个组件都在，`SHA256SUMS-<版本>.txt` 里 Windows / Linux 三种行齐全；
|
||||
- [ ] 文档站能打开，顶栏版本号是新版；
|
||||
- [ ] 装一台机器试一遍（或至少跑 `pnpm verify:packaged`）。
|
||||
|
||||
## 回滚
|
||||
|
||||
发布出去之后发现严重问题：
|
||||
|
||||
| 情形 | 做法 |
|
||||
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| 只是文档 / Release 说明写错 | 直接改 Release 说明或重发文档站（`gh workflow run docs.yml`） |
|
||||
| 二进制有问题 | 删掉 Release 与 tag（`gh release delete v1.1.3 --cleanup-tag`），修完重新发；**不要**拿同一个版本号发第二次内容不同的包 |
|
||||
| 用户已经装了 | 发一个**新版本号**（`pnpm version:bump patch`）修复，不要原地改 |
|
||||
|
||||
> 已经发出去的版本号**不要复用**：客户端把它记进「忽略此版本」，服务端与 Web 端各有 30 分钟缓存，
|
||||
> 同号换内容会让"检查更新"永久失灵。
|
||||
|
||||
## 相关
|
||||
|
||||
- 文档站本身怎么写的 → [架构总览的目录结构](architecture.md)
|
||||
- 验收脚本与脆弱用例 → [验收与测试](testing.md)
|
||||
- 各形态升级的**用户侧**步骤 → [更新与升级](../management/upgrade.md)
|
||||
已公开且用户安装的版本建议发补丁版本修复，避免同号不同内容使更新缓存/忽略版本与摘要失配。
|
||||
用户明确要求固定版本重构建时，按要求保持版本，并清楚区分本地包和远端资产；不自动改远端 tag/Release。
|
||||
仅说明或文档错误直接修改说明/文档；线上故障按对应部署形态从完整备份恢复。
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: 2026-10-17 审查修复记录
|
||||
description: 按审查报告核对缺陷、修复行为与验收方式。
|
||||
---
|
||||
|
||||
# 2026-10-17 审查修复记录
|
||||
|
||||
本次按仓库根的代码审查报告逐项核对，保留此前联动退役与更新策略改动。
|
||||
|
||||
| 报告条目 | 处理结果 |
|
||||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 0.1 | 环境文档补充 PATH 与 Git Bash 启动方式；变更文档统一格式化。 |
|
||||
| 1.1 | 恢复学期周次、毕业归档、权限组菜单，开发期检查路由是否遗漏菜单。 |
|
||||
| 1.2 | 叫人通知写本地所属日期；启动时分批幂等回填旧通知，兼容 SQLite / MySQL。 |
|
||||
| 1.3、2.14、3.10、3.14、4.5 | 每次建窗挂关闭隐藏处理；捕获加载失败；仅主窗口触发恢复，恢复期间等待异步加载；普通 Promise 拒绝不再重启进程，移除 activate 重复加载。 |
|
||||
| 1.4、1.5 | 缓存按服务端和班级隔离，个人资料按服务端和登录名隔离；忽略跨会话的迟到响应，打开失败和版本切换后可重试 IndexedDB。旧无命名空间缓存不再直接作为新会话数据读取。 |
|
||||
| 1.6 | 学期周统一加载后再取灵动岛课表，教学周变化触发重取；失败且无缓存时保留已知课表；主窗口禁用后台节流。 |
|
||||
| 1.7、3.11 | IPC 拒绝渲染端改安装记录；安装只接受更新专用目录中的文件，拒绝目录外及软链接目标；取消、更换目标和更新完成后清理旧包。 |
|
||||
| 2.1 | 空角色原本已保留旧值；现在未识别的非空值也保留原角色，只有明确的教师/管理员值才变更。 |
|
||||
| 2.2、2.9 | 员工的成绩明细、看板、更新检查与强制检查落实权限；班级端仍由本班边界授权。增加学生/教师名单只读权限，旧管理组继承对应读取能力；下线没有独立服务端能力的日志与开发者模式权限键，系统设置仍由系统管理权限控制。 |
|
||||
| 2.3 | 当前班级范围已由 CLASS_DEVICE 角色正确解析，不存在报告描述的必然拒绝，也不会查询全班学生。补齐 Socket 身份中的 classSession，保持元数据完整。 |
|
||||
| 2.4、2.5 | 课表导入读取本班学期长度，创建课表按实际兜底周数做区间交叉校验。 |
|
||||
| 2.6 | 姓名重复时要求正确学号，不能静默绑定到同名学生。 |
|
||||
| 2.7 | 增加共享删除事件与两端订阅，并移除通知中心及灵动岛中的已删通知。 |
|
||||
| 2.8 | 批量录入接口本身只接收单个 classId；真正缺口在跨班批量改等级，现已逐班广播。 |
|
||||
| 2.10 | 调班历史按学生当前班级及显式班级过滤条件校验权限；未分班学生仅管理员可读。 |
|
||||
| 2.11—2.13 | 引导使用主题文字变量，仅可见时响应 Esc；成绩明细优先展示保存的等级。 |
|
||||
| 2.15—2.17 | 助手叫人校验非空消息；周次草稿提交前校验日期；通知日期改变后清除不再可选的发布人。发布人选择本身已有 change 处理，未重复添加。 |
|
||||
| 3.1、3.4、3.9 | 列表丢弃过期响应；考试口径读写固定同一个班级/考试快照并禁用加载中的开关；切班立即清空课程候选。 |
|
||||
| 3.2 | 提交函数增加互斥与 finally 释放，按钮同步显示 loading，快速双击不会重复发请求。 |
|
||||
| 3.3 | 考试下拉从独立考试列表生成，不再由筛选后的成绩反推。 |
|
||||
| 3.5—3.8 | 不回退到已归档届别；使用主题语义色、清理死样式；拒绝协议相对和反斜线附件地址；人数加载失败显示不可用。 |
|
||||
| 3.12、3.13 | 取消确认框正常返回；列表加载与实时新增、删除、已读合并，防止快照抹掉飞行中的变更。 |
|
||||
| 3.15 | 核对并修正登录、班级开关、设备权限、菜单数量、Socket 房间注释。登录限流当前已经一次挂载到两个入口并共享计数器，该条报告不成立。 |
|
||||
| 4.1 | 百分制/字母制批量重算使用分数计算等级；自定义等级没有通用换算规则，禁止整批猜算，保留逐条编辑。 |
|
||||
| 4.2 | 审计明确记录解析结果 interpreted / unrecognized，不再写成永远等待执行的 pending；它不宣称前端业务发布已成功。 |
|
||||
| 4.3、4.4 | 助手上下文与预览参数均校验班级、科目范围；缺失通知优先级按普通通知展示。 |
|
||||
| 4.6 | 外观 IPC 在一帧内合并滑块事件，读取时先刷新最后一帧，避免丢失最终值。 |
|
||||
| 5 | 清理无调用的名单/课程封装和事件标签等；班级页接通既有任课关系导入。旧时间配置弹窗仍直接调用四个 API，按报告的保留要求保留组件及依赖，不盲目删除。 |
|
||||
|
||||
管理员的 Web 权限判断已移除全权限短路，与服务端保持一致；默认组收回的功能入口会隐藏。
|
||||
日常冒烟采用后台快速模式，视觉验收显式执行；具体命令和验证范围见[验收与测试](testing.md)。
|
||||
|
||||
## 本次验证
|
||||
|
||||
- 全仓类型检查、ESLint、构建、变更格式检查通过，文档构建无警告。
|
||||
- 隔离测试库端到端 243/243；审查接口回归 31/31；客户端维护接口 28/28。
|
||||
- 无窗口逻辑回归 18/18；模拟远控及更新代理 15/15；旧库升级回归通过。
|
||||
- 后台 Web 回归 37/37，约 38 秒；客户端联网冒烟 10/10，二次启动 9/9，总计约 15 秒。
|
||||
- 本次使用独立 SQLite 测试库，没有执行真实关机或安装；未运行会占用桌面的完整视觉验收。
|
||||
+51
-113
@@ -1,131 +1,69 @@
|
||||
---
|
||||
title: 验收与测试
|
||||
description: 验收验收脚本怎么跑、覆盖什么、哪些用例是脆弱的，以及怎么判断失败是不是真回归。
|
||||
description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。
|
||||
---
|
||||
|
||||
# 验收与测试
|
||||
|
||||
验收分为后台快速冒烟、隔离的接口与逻辑回归、显式视觉验收。日常默认不显示窗口、不占用前台；
|
||||
涉及动画、桌面像素和灵动岛几何时，再单独运行视觉验收。
|
||||
按改动范围选择验证；数量和结果读取本次输出，不沿用历史报告数字。
|
||||
默认客户端冒烟为后台快速模式；动画、透明度、桌面截图必须显式视觉模式。
|
||||
|
||||
## 验收脚本
|
||||
## 命令与前置条件
|
||||
|
||||
| 命令 | 覆盖 | 需要什么 |
|
||||
| ---------------------- | -------------------------------------------------------------------------------- | --------------------------- |
|
||||
| `pnpm verify:e2e` | 后端 + 实时推送 + RBAC 越权 + 上课时段 + 导入 + 班级账号 + 数据库管理 + 更新检查 | **后端已启动** |
|
||||
| `pnpm verify:web` | Web 管理端真实点击回归（Electron 驱动） | 后端已启动 + Web 产物已构建 |
|
||||
| `pnpm verify:desktop` | 客户端冒烟（Electron，无人工点击） | 已构建的客户端产物 |
|
||||
| `pnpm verify:packaged` | 对**打包后 / 已安装**的客户端 EXE 复跑同一套冒烟（`--exe` 指定路径） | 打包产物 |
|
||||
| 命令 | 覆盖/前置条件 |
|
||||
| ------------------------------------------------ | ----------------------------------------------------------------- |
|
||||
| pnpm lint / pnpm typecheck / pnpm check:icons | 静态检查；typecheck 会先构建 shared |
|
||||
| pnpm docs:check | docfx 严格构建，需 .NET SDK 与 docfx |
|
||||
| pnpm verify:e2e | 自动临时 SQLite、种子和带前缀账号，启动随机端口服务；无需真实服务 |
|
||||
| pnpm verify:web:isolated | 同上隔离服务，隐藏 Electron UI 回归；先构建 Web 产物 |
|
||||
| pnpm verify:web | 连接已准备测试服务，需 Web 产物和测试管理员；不应指向业务服务 |
|
||||
| pnpm verify:v14 | 临时库验证关系课表、周次、范围、隐私与升级等 |
|
||||
| pnpm verify:courseware | 临时库和文件目录的课件专项，不向真实班级推送 |
|
||||
| pnpm verify:client-agent | 假系统适配器验证命令、回执和更新策略 |
|
||||
| pnpm verify:client-migrations | 临时旧库验证迁移、联动退役与默认组持久化 |
|
||||
| pnpm verify:review-client | 无窗口逻辑回归 |
|
||||
| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务，使用 VERIFY_BASE_URL 等脚本参数 |
|
||||
| pnpm verify:desktop | 先 pnpm build:desktop；隐藏快速检查，独立 userData |
|
||||
| pnpm verify:desktop:online | 显式联网，需要测试管理员并创建临时教师/班级 |
|
||||
| pnpm verify:desktop:visual | 显式使用桌面，完整岛几何/动画/透明度/截图检查 |
|
||||
| pnpm verify:packaged --exe <客户端EXE> | 默认快速离线，两次启动、packaged=true；--visual 才使用桌面 |
|
||||
|
||||
条目数由脚本自行统计并打印（`=== 结果：N/N 项通过 ===`），**文档里不写死容易过期的总数** ——
|
||||
每次跑完看脚本输出。
|
||||
联网 packaged 使用 --online；调用方须预先准备隔离服务、临时教师和班级并显式注入凭据，该启动器不会自动创建它们。
|
||||
开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。
|
||||
不得回退到真实班级、重置真实密码或向真实班级发测试通知；远控与安装器使用假执行器。
|
||||
桌面进程超时和失败日志先定位，不能因为一个历史脆弱用例名称就断言当前失败必然正常。
|
||||
|
||||
客户端维护专项回归：
|
||||
|
||||
- `pnpm verify:client-agent`：模拟操作系统验证远控、回执重试与安装策略，不执行真实关机或安装器。
|
||||
- `pnpm verify:client-migrations`：创建临时旧库验证升级、联动移除与默认组编辑持久化。
|
||||
- `pnpm verify:clients-api`：面向 `http://127.0.0.1:4199` 的演示测试库（可用 `VERIFY_BASE_URL` 指定），验证权限、远控与更新接口。会创建并清理测试记录，请使用隔离测试服务。
|
||||
- `pnpm verify:review-client`：无窗口验证缓存故障恢复、通知竞态、教学周同步、管理员界面权限与崩溃恢复。
|
||||
- `pnpm verify:review-api`：针对审查缺陷验证接口权限、导入边界和实时删除等，必须连接隔离测试服务。
|
||||
|
||||
另外三套是"门禁"而不是验收：`pnpm typecheck`、`pnpm lint`、`pnpm check:icons`。
|
||||
|
||||
### 一次完整的交付前检查
|
||||
## 常用检查顺序
|
||||
|
||||
```bash
|
||||
pnpm lint # ESLint，0 error 是底线
|
||||
pnpm typecheck # 全仓库类型检查（含 vue-tsc）
|
||||
|
||||
pnpm verify:e2e # 自建全新隔离库与临时账号，不依赖真实服务
|
||||
pnpm verify:v14 # 新课表/权限/年度升级专项隔离验收
|
||||
|
||||
pnpm build:desktop && pnpm verify:desktop
|
||||
pnpm build && pnpm verify:web
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm check:icons
|
||||
pnpm docs:check
|
||||
pnpm verify:e2e
|
||||
pnpm verify:v14
|
||||
pnpm verify:courseware
|
||||
pnpm build:desktop
|
||||
pnpm verify:desktop
|
||||
pnpm --filter @classhelper/web-admin build
|
||||
pnpm verify:web:isolated
|
||||
```
|
||||
|
||||
改动涉及打包/交付形态时，再加 `pnpm dist:all` 与
|
||||
`pnpm verify:packaged --exe "<客户端路径>"`（**开发产物通过不等于用户机器上的副本通过**）。
|
||||
仅文档修改只需格式、链接与 docs:check；不因此重打包或占用桌面。
|
||||
改打包/运行时裁剪还要构建实际副本并跑 packaged；Linux 交付修改需 Linux 真机/CI 验证和 bash 语法检查。
|
||||
|
||||
## 失败时先别改代码
|
||||
## 故障定位
|
||||
|
||||
下面这些用例**不是回归**，遇到时先看条件。完整清单在 `AGENTS.md` 的「已知脆弱用例」表。
|
||||
- 临时服务失败查 .cache/v14-verification 下本次日志；不要改业务 .env 或密码迁就测试。
|
||||
- 显式联网管理员变量：桌面 ELECTRON_SMOKE_ADMIN/ELECTRON_SMOKE_ADMIN_PASSWORD，Web UI_SMOKE_ADMIN/UI_SMOKE_ADMIN_PASS。
|
||||
- 视觉用例需要真实桌面与稳定帧，先区分状态未稳定、窗口遮挡和实际回归，再针对原因重跑。
|
||||
- Element Plus dialog 关闭后 DOM 仍保留，应检查 overlay 的可见状态。
|
||||
- 本地 HTTP 探测绕过代理；Prisma 生成物和 shared/dist 缺失时先补前置构建。
|
||||
|
||||
| 用例 | 触发条件 |
|
||||
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `verify:desktop:visual`「真实通知链路」「灵动岛标为已读」等 3 项 | 要求**当前不在上课时段**。种子课表恰有课正在进行时，客户端会**正确地**把普通通知暂存到下课 —— 这三项就会红（日志里会写 `客户端判定上课中=true`） |
|
||||
| `verify:e2e`「上课状态接口（at=周一 08:10）」 | 种子把周一第 1 节限制在第 1 周，且用例把 `2026-09-07` 当第 1 周。`.env` 的 `TERM_START_DATE` 对齐即可全绿 |
|
||||
| `verify:web`「课表科目为全校统一目录」 | 种子给每个班建满了全部科目，下拉里就没有可自动建课的「统一科目」分组 |
|
||||
| `verify:desktop:visual`「课表今天时间轴」 | 凌晨约 00:00–03:00 时「已结束」探针被夹紧成 0 长度而被过滤 |
|
||||
| `verify:desktop:visual`「作业看板全屏自适应」 | 演示数据某天有 6 条长作业、而冒烟窗口只有约 543px 高时，缩放被下限 0.45 钳住 → 必然溢出 |
|
||||
| 岛交互 / 岛动画 / 岛截图留档 | 窗口被遮挡或跑在远程会话里时会间歇性失败：置顶透明小窗的 rAF 被限流、形变采样抓不到帧。**先原样重跑一次再动手改** |
|
||||
## 截图
|
||||
|
||||
## 大面积报「登录失败 / 401」时
|
||||
|
||||
先检查隔离服务是否启动，以及测试管理员的当前口令。不要修改真实班级密码来迁就测试。
|
||||
联网客户端和 Web 回归会自行创建临时教师与班级；下面的环境变量只配置测试管理员：
|
||||
|
||||
| 脚本 | 管理员凭据 |
|
||||
| ------------------- | -------------------------------------------------------- |
|
||||
| 客户端联网/打包冒烟 | `ELECTRON_SMOKE_ADMIN` / `ELECTRON_SMOKE_ADMIN_PASSWORD` |
|
||||
| Web 回归 | `UI_SMOKE_ADMIN` / `UI_SMOKE_ADMIN_PASS` |
|
||||
| 后端端到端回归 | 使用隔离种子库，口令由种子脚本与验收脚本约定 |
|
||||
|
||||
默认离线快速冒烟不需要服务端凭据。
|
||||
|
||||
## 默认后台运行，视觉验收单独执行
|
||||
|
||||
`pnpm verify:desktop` 默认运行隐藏、不可聚焦的离屏窗口，仅检查启动、桥接白名单、缓存读写、
|
||||
跨服务端/跨班级缓存隔离和关闭隐藏。二次启动也只跑快速检查，不再重复整套动画。
|
||||
|
||||
需要联网时运行 `pnpm verify:desktop:online`，创建临时教师与临时班级，结束后删除。
|
||||
不再自动探测并复用真实班级，也不会重置真实班级密码。Web 回归同样使用隔离的验证教师与班级。
|
||||
|
||||
`pnpm verify:desktop:visual`（或客户端启动器 `--visual`）才运行灵动岛动画、透明度、桌面截图等完整验收，
|
||||
这类用例确实需要使用桌面。`verify:packaged` 也默认快速模式，显式传 `--visual` 才跑视觉验收。
|
||||
视觉验收不适合在用户操作屏幕时自动运行。截图采集命令需要传入 `--visual`（或设置 `ELECTRON_SMOKE_MODE=visual`）。
|
||||
结果记录模式和耗时；启动器设置超时，避免验证进程无限等待。
|
||||
|
||||
## 截图留档
|
||||
|
||||
截图分两套，各管一件事：
|
||||
|
||||
| 目录 | 谁在用 | 谁产出 |
|
||||
| ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| `docs/images/` | **文档站、README、官网用的是同一份图**，页面上展示的都是它 | `capture-shots.mjs`（Web / 手机）+ 客户端冒烟（客户端 / 灵动岛） |
|
||||
| `docs/screenshots/` | 回归留档，页面不展示；`verify:*` 的像素级断言比对的就是它们 | 各冒烟脚本自动写入（island / client / web-mobile 三组） |
|
||||
|
||||
**展示图重新采集**（保证文档站与 README、官网用的是同一份图）：
|
||||
|
||||
```bash
|
||||
pnpm dev:server # 后端同时托管 Web 管理端
|
||||
CAPTURE_OUT=docs/images,website/assets/shots node website/tools/capture-shots.mjs # → web-*.jpg / mobile-*.jpg
|
||||
|
||||
# 客户端与灵动岛走的是冒烟脚本。它除了正片，还会顺手落一份「岛外留白对照图」
|
||||
# （*-window.png / *-backdrop.png），所以先落到临时目录，再挑要用的拷进去。
|
||||
ISLAND_SHOTS_DIR="$PWD/.cache/shots" ELECTRON_CLIENT_SHOTS_DIR="$PWD/.cache/shots" \
|
||||
ELECTRON_SMOKE_ISLAND_ACCENT='#0a84ff' ELECTRON_SMOKE_ISLAND_STYLE=black \
|
||||
node packages/desktop-client/scripts/smoke.mjs --visual --online
|
||||
cp .cache/shots/{island-*,client-*}.png docs/images/
|
||||
rm -f docs/images/*-window.png docs/images/*-backdrop.png
|
||||
cp docs/images/{island-*,client-*}.png website/assets/shots/ # 官网那份保持同步
|
||||
```
|
||||
|
||||
**回归留档重新采集**（同一套冒烟，把输出指到留档目录）：
|
||||
|
||||
```bash
|
||||
pnpm dev:server
|
||||
ISLAND_SHOTS_DIR="$PWD/.cache/island-shots" \
|
||||
ELECTRON_CLIENT_SHOTS_DIR="$PWD/.cache/client-shots" \
|
||||
ELECTRON_SMOKE_ISLAND_ACCENT='#0a84ff' ELECTRON_SMOKE_ISLAND_STYLE=black \
|
||||
node packages/desktop-client/scripts/smoke.mjs --visual --online
|
||||
```
|
||||
|
||||
> 展示图都是**逻辑像素 1×**（灵动岛的 268×44、424×230 就是这个数，不再乘 2），
|
||||
> 页面按原始尺寸显示即可 —— 换图时别顺手放大，否则整页的尺寸对不上。
|
||||
> 采集脚本会把窗口真的弹在屏幕上。客户端留档会**临时停掉 CSS 动画**再截图 ——
|
||||
> 窗口被遮挡时 Chromium 冻结动画，而页面入场动画的起始帧是 `opacity: 0`，
|
||||
> 不停掉的话截出来是**整片空白**（DOM 里文本齐全，只有图是空的）。
|
||||
|
||||
## V1.4 专项验收
|
||||
|
||||
`verify:e2e` 由根启动器创建独立数据库、带前缀的临时账号与服务；服务禁止外网，请勿改回真实班级。`verify:v14` 在专用临时库验证新模型与自动升级幂等。详细结果、迁移保留情况和十项自检见 [实施记录](20261017-implementation.md)。
|
||||
docs/images 为 README/文档展示图；docs/screenshots 为回归留档；website/assets/shots 为官网素材。
|
||||
只把显式视觉验收采集、人工确认过的正片用作展示，不把窗口对照图或旧失败截图直接发布。
|
||||
Web 采集入口 `website/tools/capture-shots.mjs`，先准备隔离测试服务和数据。
|
||||
岛/客户端采集使用 smoke.mjs --visual，并按需 --online；ISLAND_SHOTS_DIR 与 ELECTRON_CLIENT_SHOTS_DIR 指向临时目录。
|
||||
日常 quick 模式不会生成完整视觉截图，不能把 quick 通过表述为动画/透明度已验证。
|
||||
+2
-4
@@ -16,10 +16,8 @@
|
||||
href: winisland-design-tokens.md
|
||||
- name: 验收与测试
|
||||
href: testing.md
|
||||
- name: 2026-10-17 审查修复记录
|
||||
href: review-2026-10-17.md
|
||||
- name: 版本迭代与发布
|
||||
href: release.md
|
||||
|
||||
- name: 2026-10-17 实施与验收
|
||||
href: 20261017-implementation.md
|
||||
- name: 当前实现约定
|
||||
href: implementation.md
|
||||
@@ -1,593 +1,59 @@
|
||||
# WinIsland 视觉设计系统（Design Token 规格）
|
||||
|
||||
来源：[WinIsland](https://github.com/WinIslandProject/WinIsland) 的源码（`WinIsland-master`，只读 checkout）。
|
||||
所有数值均取自代码常量，标注了「常量名 = 值 @ 文件」。未在代码中找到的项明确写「未找到」。
|
||||
|
||||
关键前提：**岛内所有几何尺寸都乘以 `compact_scale`（默认 1.0）或 `expanded_scale`（默认 1.0）**，
|
||||
下文数值默认 scale = 1.0。文字颜色在渲染入口被硬编码为 `Color::WHITE`（`src/core/render.rs`
|
||||
`draw_expanded_layer` / `draw_compact_layer` 传 `text_color: Color::WHITE`, `text_color_sec: Color::WHITE`），
|
||||
所有"次级/次要"文字靠 **alpha** 或 **灰度通道值** 表达，而不是换颜色。
|
||||
|
||||
---
|
||||
title: 灵动岛设计令牌
|
||||
description: 本地经典/自定义岛的几何、外观与动画入口。
|
||||
---
|
||||
|
||||
## 1. 几何（几何 token）
|
||||
# 灵动岛设计令牌
|
||||
|
||||
### 1.1 两个状态的尺寸
|
||||
经典岛以 WinIsland 的连续圆角和形变为设计参考，自定义组件行以 ClassIsland 为参考。
|
||||
当前数值与行为以本仓库 shared 常量和渲染实现为准；本页不把上游音乐/歌词/媒体功能列为 ClassHelper 功能。
|
||||
|
||||
| 项 | compact / mini | expanded | 来源 |
|
||||
| -------- | ------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
|
||||
| 宽 | `base_width = 120.0` | `expanded_width = 360.0` | `src/core/config.rs` `AppConfig::default()` |
|
||||
| 高 | `base_height = 27.0` | `expanded_height = 200.0` | 同上 |
|
||||
| 圆角 r | `h / 2`（=13.5）→ 胶囊/体育场形 | `min(48*scale, w/2, h/2)` = **48.0** | `src/window/app/frame.rs` `default_target_r`；`src/utils/shape.rs` `expanded_island_radius()` |
|
||||
| 全局缩放 | `compact_scale = 1.0` | `expanded_scale = 1.0` | `src/core/config.rs` |
|
||||
## 经典几何与外观
|
||||
|
||||
圆角函数原文（`src/utils/shape.rs`）：
|
||||
| 来源 | 内容 |
|
||||
| ---------------------------------------------------- | ----------------------------------------------------- |
|
||||
| shared/src/constants.ts 的 DEFAULT_ISLAND_APPEARANCE | 默认宽 268、高 44、圆角 20、字号 13、边距 8，顶部居中 |
|
||||
| ISLAND_APPEARANCE_RANGES | 滑块与主进程归一化共用的范围 |
|
||||
| ISLAND_SIZE_DELTA | 展开、紧急与叫人相对尺寸 |
|
||||
| ISLAND_SHADOW_PAD | 窗口边界的透明留白 |
|
||||
| ISLAND_LIST_METRICS / islandListLayout | 主进程和渲染层共用列表度量，控制行数与工作区高度 |
|
||||
| desktop-client/src/island/squircle.ts | 超椭圆路径 |
|
||||
| desktop-client/src/island/classic-island.css | 经典底色、文字、图形与状态样式 |
|
||||
|
||||
```rust
|
||||
pub(crate) fn expanded_island_radius(w: f32, h: f32, scale: f32) -> f32 {
|
||||
(48.0 * scale).min(w / 2.0).min(h / 2.0).max(0.0)
|
||||
}
|
||||
```
|
||||
classic 的 black/glass/tinted 是本地 CSS 外观；glass 使用半透明色，不采样桌面模糊。
|
||||
不要对透明岛调用 setBackgroundMaterial：系统材质作用于整窗矩形，可能破坏逐像素透明。
|
||||
投影常驻，只随形态改参数，避免切换 filter 创建合成表面的闪帧。
|
||||
默认停靠中线不受左右边距影响，只有左/右停靠使用水平边距。
|
||||
|
||||
compact 圆角：`IslandSprings::new` 里 `r = (base_height * compact_scale) / 2.0`（`src/window/app.rs`）；
|
||||
展开时 `default_target_r = compact_content_h / 2.0`（`src/window/app/frame.rs` `update_spring_targets`）。
|
||||
## 自定义常驻行
|
||||
|
||||
### 1.2 compact 宽度的动态规则（不是固定 120）
|
||||
CLASSISLAND_ISLAND_METRICS 位于 shared/src/island-layout.ts：
|
||||
|
||||
`src/window/app/layout.rs` `compute_lyric_target_width()`：
|
||||
| 参数 | 本地值 |
|
||||
| ----------------------- | -------------------- |
|
||||
| 单行基准高度 / 水平留白 | 40 / 12 px |
|
||||
| 次要/正文/强调/大字号 | 14 / 16 / 18 / 20 px |
|
||||
| 默认缩放 / 范围 | 1 / 0.75–2.5 |
|
||||
| 默认圆角 / 最大 | 8 / 20 px |
|
||||
| 默认不透明度 / 行距 | 0.5 / 5 px |
|
||||
| 鼠标避让淡化比例 | 0.05 |
|
||||
|
||||
- 无媒体 / 不在播放态：宽 = `base_width` = **120**
|
||||
- 有媒体但无歌词：宽 = `base_width + 35.0` = **155**
|
||||
- 有歌词（不滚动）：`w = 60.0 + 文本宽`，再 `clamp(base_width+35, MAX_LYRIC_WIDTH)`
|
||||
- `min_w = base_width + 35.0`、`MAX_LYRIC_WIDTH = 700.0`（`src/core/config.rs`）
|
||||
- 有歌词（滚动模式，`lyrics_scroll = true`）：`natural_w = 60.0 + text_w`，超过 `lyrics_scroll_max_width`（默认
|
||||
`300.0`，`default_lyrics_scroll_max_width`）则固定为该上限；内部可用文本宽 = `(fixed_w - 59.0) * compact_scale`
|
||||
- 二级歌词存在时：高度 = `max(base_height*scale, mini_lyric_pair_height)`，
|
||||
其中 `lyric_pair_height = 主字号*(1 + 0.85 + 0.18) + 8*scale`
|
||||
（`SECONDARY_LYRIC_SCALE = 0.85`、`LYRIC_PAIR_GAP_SCALE = 0.18` @ `src/core/render/mini.rs`）
|
||||
→ 默认字号 12 时 = 12×2.03 + 8 = **32.36 px 高**，r ≈ 16.18
|
||||
方案有常态 rows 和无通知展开 expandedRows，运行时由 CustomIslandRuntime.vue 测量自然内容，
|
||||
再按屏幕工作区与方案缩放适配。字体与外观覆盖按组件契约生效，不能拿经典固定宽高解释自定义内容尺寸。
|
||||
|
||||
### 1.3 挂件（compact widget）导致的最小宽度
|
||||
## 动画与命中
|
||||
|
||||
`src/ui/widget/compact/mod.rs`：
|
||||
经典与自定义岛的形变都使用 src/island/spring.ts 的 SpringValue；默认 stiffness=0.10、damping=0.68，
|
||||
换向保留部分动量，按剩余距离限速并钳制过冲。不同用途可能覆盖 snapThreshold 等参数，以调用点为准。
|
||||
这是独立的帧积分，不等同于主窗口 shared/motion.ts 的 CSS 弹簧。
|
||||
应用内动画开关、原生窗口可见性与文档可见性控制运行时动画和静止落定。
|
||||
|
||||
- `CONTENT_EDGE_INSET = 9.0`、`CONTENT_GAP = 7.0`
|
||||
- `widget_width()`：`Time = 48.0`、`ResourceUsage = 132.0`
|
||||
- 三组对齐宽度：`aligned_layout_width = 9*2 + left + center + right + 7*(占用组数-1)`
|
||||
- 单侧扩展宽：`extension_width = CONTENT_EDGE_INSET + strip_width + CONTENT_GAP`
|
||||
（例：左 Time → 9+48+7 = **64**；ResourceUsage → 9+132+7 = **148**）
|
||||
- 最终 compact 宽 = `max(布局宽, base_width)`
|
||||
鼠标模式按光标命中控制穿透；触摸模式处理贴合、输入区域与失焦宽限，自定义常驻模式还维护独立交互入口和窗口形状。
|
||||
几何改变时同步实际窗口、命中矩形和测量，不在动画中反推自然尺寸。
|
||||
视觉验收必须显式 --visual；本页数值不代表本次已完成像素验收。
|
||||
|
||||
### 1.4 compact overlay（通知 / 音量）会替换 base 尺寸
|
||||
## 修改入口
|
||||
|
||||
| overlay | 宽 | 高 | 圆角 | 来源 |
|
||||
| ------- | ------------------------------------------ | ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| 通知 | `max(base_width, 330.0) * scale` = **330** | `max(base_height, 82.0) * scale` = **82** | `h/2` = **41** | `src/ui/compact/notification.rs` `target_size()`；r 取自 `src/window/app/frame.rs`（`size.height/2.0`） |
|
||||
| 音量 | `(base_width + 72.0) * scale` = **192** | `(base_height + 10.0) * scale` = **37** | `h/2` = **18.5** | `src/ui/compact/volume.rs` `target_size()` |
|
||||
|
||||
### 1.5 隐藏态尺寸
|
||||
|
||||
- `hidden_width` 默认 `5.0`（`default_hidden_width` @ `src/core/config.rs`），
|
||||
- `MIN_HIDDEN_WIDTH = 0.0`、`MAX_HIDDEN_WIDTH = 400.0`
|
||||
- 隐藏时高度收缩到 `hidden_width * compact_scale`，并保留 `hidden_reveal_h = 1.0`（1px 可点击边）；
|
||||
位移距离 `hide_distance = concealed_height + TOP_OFFSET`（`src/window/app/layout.rs`）
|
||||
|
||||
### 1.6 锚点（两种状态之间什么不动）
|
||||
|
||||
定位全部来自 `src/window/app/layout.rs` `compute_island_layout()` / `compute_window_position()`：
|
||||
|
||||
- **顶部居中停靠（默认）**：`island_y = TOP_OFFSET = 10.0`（**顶边固定**），
|
||||
`offset_x = (os_w - w) / 2.0`（**水平中心固定**）
|
||||
- **底部停靠**：`island_y = os_h - TOP_OFFSET - h`（**底边固定**，向上生长）
|
||||
- **左/右停靠**：`offset_x = TOP_OFFSET` 或 `os_w - TOP_OFFSET - w`（对应侧边固定）
|
||||
- `TOP_OFFSET: i32 = 10`（`src/core/config.rs`）＝ 岛顶边距屏幕顶 10 px
|
||||
- 状态切换由三个弹簧同时插值：`w/h/r` 参数为 `stiffness = 0.10, damping = 0.68`（`src/window/app/frame.rs`），
|
||||
页面横移 `view` 用 `0.12 / 0.68`；隐藏用 `(0.12, 0.70)` 隐藏 / `(0.08, 0.78)` 显示
|
||||
- **compact 内容不跟随变大的岛做垂直居中重排**：mini 内容画在 `stable_island_y`（= 顶边）加上 `base_h` 带内居中
|
||||
（`src/core/render/mini.rs`：封面 `y = stable_offset_y + (base_h - size)/2`，歌词 `center_y = stable_offset_y + base_h/2`）。
|
||||
效果＝岛向下长大，胶囊内容始终贴在顶部那条带里。
|
||||
- 交叉淡出：`expanded_alpha = expansion_progress² * (1-hide_progress)`，
|
||||
`mini_alpha = clamp(1 - expansion_progress*1.5, 0, 1) * (1-hide_progress)`
|
||||
（`MINI_FADE_RATE = 1.5` @ `src/core/render.rs`）→ 即进度 0~0.667 之间完成交叉淡出
|
||||
|
||||
### 1.7 有没有"挖孔/刘海"造型？
|
||||
|
||||
**没有。** 代码里没有 `SetWindowRgn` / `CreateRoundRectRgn` / notch / cutout 相关调用（已全仓 grep 确认），
|
||||
也没有"顶部贴边 + 上方两角变直角"的特例分支。造型是：
|
||||
|
||||
- 一个**悬浮胶囊**（compact，r = h/2），**距屏幕顶 10 px**；
|
||||
- 展开后是**四角一致的连续超椭圆**（squircle），r 最大 48。
|
||||
|
||||
圆角实现不是普通圆弧，而是 Flutter `RoundedSuperellipse` 的移植（`src/utils/shape.rs`，
|
||||
注释标明 "Rounded-superellipse geometry adapted from Flutter under the BSD-3-Clause license"）：
|
||||
|
||||
- `superellipse_parameters()`：11 项查表 `PARAMETERS`（如 `(2.0, 1.13276676) … (6.43023796, 2.98020421)`），
|
||||
ratio > 5 时线性外推 `exponent = 6.43023796 + 1.559599389*(ratio-5.0)`、`factor = 2.98020421 + 0.522807185*(ratio-5.0)`
|
||||
- `Octant::new()`：13 项 `BEZIER_FACTORS`（`(0.7078, 8.3194) … (0.9705, 1.2880)`），用 conic + cubic 拼四分之一角
|
||||
- 路径缓存 `PATH_CACHE_CAPACITY = 64`
|
||||
- **Web 复刻提示**：CSS `border-radius` 是正圆角，观感会偏"软"；要还原请用 SVG path 或
|
||||
`corner-shape: squircle`（若可用）/ `clip-path` 近似。**未找到**等价的简单圆角公式——真实几何就是上面那张表。
|
||||
- **本仓库的落地实现**（`packages/desktop-client/src/island/squircle.ts`）：不查表，用单参数超椭圆近似
|
||||
`point = center + r·(sign(cos a)·|cos a|^p, sign(sin a)·|sin a|^p)`，`p = 2/n`、`n = 4.2`，
|
||||
四角分别以 `TR(w-r,r) → BR(w-r,h-r) → BL(r,h-r) → TL(r,r)`、起始角 `-π/2, 0, π/2, π` 各扫 `π/2`，
|
||||
每角 14 段。**四个角必须各用自己的圆心 + 角度参数**：早期版本四个角共用同一个"偏移向量"，
|
||||
左上/右下被切成缺一块（用户反馈的"左上角和右下角怎么缺一块 / 圆角边缘割裂"），
|
||||
现已由 `verify:desktop` 的「连续圆角四角一致」断言（四角沿对角线边界步进两两一致 + 路径绕行 \|winding\|≈2π）长期守住。
|
||||
|
||||
### 1.8 窗口留白 / 裁切
|
||||
|
||||
- `PADDING: f32 = 80.0`（`src/core/config.rs`）；窗口尺寸 = `(岛宽 + 80, 岛高 + 80)`
|
||||
（`src/window/app/layout.rs` `required_window_size()`）→ **岛四周各 40 px 透明留白**，供阴影/动画使用
|
||||
- 绘制时 `canvas.clip_path(island_path, ClipOp::Intersect)`，所有内容裁在岛形内；
|
||||
1px 描边在 `canvas.restore()` **之后**绘制（`src/core/render.rs` `draw_island()`）
|
||||
- 挂件网格额外内缩，避免内容进圆角（`src/ui/widget/expanded/mod.rs` `widget_grid_layout`）：
|
||||
```rust
|
||||
corner_inset = radius * (1.0 - FRAC_1_SQRT_2); // 48 * 0.29289 = 14.06
|
||||
inset = (corner_inset + 8.0*scale).max(24.0*scale); // = 24.0（scale=1）
|
||||
gap = 7.0 * scale;
|
||||
```
|
||||
|
||||
### 1.9 expanded 内容网格
|
||||
|
||||
- `WIDGET_GRID_COLS = 6`、`WIDGET_GRID_ROWS = 3`、`WIDGET_GRID_SLOTS = 18`（`src/core/config.rs`）
|
||||
- 槽位宽 = `(inner_w - 7*5) / 6`，高 = `(inner_h - 7*2) / 3`；
|
||||
用 360×200、inset 24 计算：inner = 312×152 → **slot ≈ 46.17 × 46.0**（`src/ui/widget/expanded/mod.rs`）
|
||||
- 组件占格 `WidgetKind::span()`：`Clock = (2,1)`、`ResourceUsage = (2,1)`、`Calendar = (2,2)`、`Settings = (1,1)`
|
||||
（`src/core/config.rs`）
|
||||
|
||||
---
|
||||
|
||||
## 2. 配色（颜色 token）
|
||||
|
||||
### 2.1 岛背景（`src/core/render/background.rs` `draw_background()`）
|
||||
|
||||
| 样式 | 颜色值 | 说明 |
|
||||
| --------------------------- | -------------------------------------------------------------- | -------------------- |
|
||||
| `default`（`SOLID_STYLE`） | `Color::BLACK` = **#000000**，完全不透明 | `bg_color` |
|
||||
| `glass` + host backdrop | `Color::from_argb(150, 10, 10, 14)` = **rgba(10,10,14,0.588)** | `draw_host_glass()` |
|
||||
| `glass` 无 backdrop（回退） | `Color::from_argb(205, 32, 32, 36)` = **rgba(32,32,36,0.804)** | `fallback_color` |
|
||||
| `dynamic` 底色 | `Color::from_rgb(32, 32, 36)` = **#202024**，不透明 | `draw_effect_base()` |
|
||||
| `dynamic` 叠加层 | `Color::from_argb(120, 20, 20, 24)` = **rgba(20,20,24,0.471)** | 盖在旋转模糊封面之上 |
|
||||
| `dynamic` 无封面回退 | 同 glass 分支（150/10,10,14 或 205/32,32,36） | |
|
||||
|
||||
`dynamic` 封面动效参数（同一函数）：
|
||||
|
||||
- 集显：`rotate_speed = 0.015 rad/s, drift_speed_x = 0.075, drift_speed_y = 0.06, drift_amp_x = 10.0, drift_amp_y = 7.5`
|
||||
- 独显：`rotate_speed = 0.03, drift_speed_x = 0.15, drift_speed_y = 0.12, drift_amp_x = 20.0, drift_amp_y = 15.0`
|
||||
- 旋转矩形边长 `side_len = diagonal * 1.3`
|
||||
|
||||
**亚克力/backdrop 真实实现**（`src/window/d3d.rs` + `src/utils/win32.rs`）：
|
||||
Windows 11 `DWMWA_USE_HOSTBACKDROPBRUSH`，失败时退回 `SetWindowCompositionAttribute`
|
||||
（`AccentPolicy { state: 5, flags: 0, gradient_color: 0 }`，state 5 = host backdrop）；
|
||||
再用 `Compositor::CreateHostBackdropBrush()` + `RoundedRectangleGeometry` 裁圆角
|
||||
（`HOST_BACKDROP_INSET = 1.0`，几何 = `w-2, h-2, radius-1`）。
|
||||
**未找到**任何模糊半径数值——模糊由系统 HostBackdropBrush 决定。
|
||||
|
||||
### 2.2 描边（`src/core/render.rs` `draw_island_border()`）
|
||||
|
||||
```rust
|
||||
BORDER_WIDTH = 1.0; BORDER_INSET = BORDER_WIDTH / 2.0; // 0.5
|
||||
SOLID_STYLE = "default"; SOLID_BORDER_ALPHA = 30; EFFECT_BORDER_ALPHA = 40;
|
||||
```
|
||||
|
||||
- 颜色 = **纯白**，alpha：
|
||||
- `default` 样式：`rgba(255,255,255, 30/255=0.118)`，**并再乘 `(1 - expansion_progress)`**（展开后描边消失）
|
||||
- `glass` / `dynamic`：`rgba(255,255,255, 40/255=0.157)`，不随展开衰减
|
||||
- 描边矩形 = `(x+0.5, y+0.5, w-1, h-1)`，圆角 `r-0.5`
|
||||
|
||||
### 2.3 阴影（`src/core/render.rs` `draw_expanded_shadow()`，仅展开时）
|
||||
|
||||
- 颜色 `Color::from_argb((28.0 * opacity) as u8, 0,0,0)` = **rgba(0,0,0,0.11)**
|
||||
- `opacity = expansion_progress² * (1 - hide_progress)`，`opacity <= 0.01` 直接跳过
|
||||
- 偏移 `offset_y = 2.0 * scale`；模糊 `sigma = min(3.0*scale, margin/3.0)`（margin = 到画布边界的余量）
|
||||
- 用 `ClipOp::Difference` 只画在岛形之外
|
||||
- **未找到内阴影**（没有任何 inner shadow 实现）
|
||||
|
||||
### 2.4 分隔线
|
||||
|
||||
| 位置 | 颜色 | 尺寸 | 来源 |
|
||||
| -------------------- | -------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
|
||||
| compact 挂件之间 | `rgba(255,255,255, 0.14*alpha)` | 宽 `max(scale,1)`，从 `top+25%h` 到 `bottom-25%h` | `src/ui/widget/compact/mod.rs` `draw_separator()` |
|
||||
| compact 资源占用内部 | `rgba(255,255,255, 0.10*alpha)` | 宽 `max(0.75*scale, 0.75)`，半高 `DIVIDER_HALF_HEIGHT = 6.0*scale` | `src/ui/widget/compact/resource_usage.rs` |
|
||||
| expanded 资源环分隔 | `rgba(白, 0.09*alpha)` | 宽 `scale.max(0.75)`，从 `y+0.2h` 到 `y+0.8h` | `src/ui/widget/expanded/resource_usage.rs` |
|
||||
| 设置窗口分隔线 | `rgba(255,255,255,26)` 暗 / `rgba(20,28,40,18)` 亮 | — | `src/utils/color.rs` |
|
||||
|
||||
### 2.5 文字颜色与不透明度分层
|
||||
|
||||
主文字一律 **#FFFFFF**；次级用 alpha：
|
||||
|
||||
| 元素 | 有效颜色 | 来源 |
|
||||
| ------------------ | ------------------------------------------------------------ | ---------------------------------------------------- |
|
||||
| 通知 app 名 | `rgba(255,255,255, 0.65*alpha)` | `src/ui/compact/notification.rs` |
|
||||
| 通知标题 | `rgba(255,255,255, alpha)` | 同上 |
|
||||
| 通知详情 | `rgba(255,255,255, 0.72*alpha)` | 同上 |
|
||||
| 音量标签 | `rgba(255,255,255, 0.9*alpha)` | `src/ui/compact/volume.rs` |
|
||||
| expanded 歌手 | `rgba(白, alpha*0.6)` | `src/ui/expanded/music_view.rs` `draw_track_text()` |
|
||||
| 迷你歌词主行 | 白 alpha | `src/core/render/mini.rs` |
|
||||
| 迷你歌词次行 | `rgb(176,176,176)`（`SECONDARY_LYRIC_CHANNEL = 176`） | 同上 |
|
||||
| 逐字歌词"未唱"部分 | `rgb(190,190,190)`（`PENDING_LYRIC_CHANNEL = 190`） | 同上 |
|
||||
| 进度条时间 | 白，`PROGRESS_TIME_IDLE_ALPHA = 0.5` → hover 1.0（线性插值） | `src/ui/expanded/music_view.rs` |
|
||||
| 挂件时钟 | 白 alpha（bold） | `src/ui/widget/expanded/time.rs` |
|
||||
| 挂件日历 月 | `0.78*alpha` | `src/ui/widget/expanded/calendar.rs` |
|
||||
| 挂件日历 日 | `1.0*alpha` | 同上 |
|
||||
| 挂件日历 星期 | `0.62*alpha` | 同上 |
|
||||
| 挂件资源 数值 | `1.0*alpha`（bold） | `src/ui/widget/expanded/resource_usage.rs` |
|
||||
| 挂件资源 标签 | `0.58*alpha` | 同上 |
|
||||
| 封面占位块 | `rgba(白, 0.15*alpha)` | `src/ui/expanded/music_view.rs` `draw_placeholder()` |
|
||||
|
||||
### 2.6 强调色 / 状态色
|
||||
|
||||
岛内（`src/ui/widget/resource_usage.rs`）：
|
||||
|
||||
```rust
|
||||
CPU_COLOR = rgb(50, 190, 246) // #32BEF6
|
||||
RAM_COLOR = rgb(175, 82, 222) // #AF52DE
|
||||
WARNING_COLOR = rgb(255, 159, 10) // #FF9F0A
|
||||
CRITICAL_COLOR = rgb(255, 69, 58) // #FF453A
|
||||
```
|
||||
|
||||
阈值曲线 `usage_color(base, usage)`：
|
||||
|
||||
- `usage <= 0.75` → base
|
||||
- `0.75 < usage <= 0.9` → base ↔ WARNING 线性混合，`t = (usage-0.75)/0.15`
|
||||
- `0.9 < usage` → WARNING ↔ CRITICAL 线性混合，`t = (usage-0.9)/0.1`
|
||||
采样间隔 `SAMPLE_INTERVAL = 1s`；无数值时显示 `—`。
|
||||
|
||||
进度条/音量条（`src/ui/expanded/music_view.rs`、`src/ui/compact/volume.rs`）：
|
||||
|
||||
```rust
|
||||
PROGRESS_TRACK_ALPHA = 0.15; // 轨道 rgba(白, 0.15*alpha)
|
||||
PROGRESS_TIME_IDLE_ALPHA = 0.5; // 时间文字静止透明度
|
||||
// 音量轨道 rgba(255,255,255, 0.28*alpha)，填充纯白 alpha
|
||||
```
|
||||
|
||||
音量的"填充"就是**白色**（不是强调色），图标仍是白色。
|
||||
|
||||
可视化条颜色**来自专辑封面**（`src/ui/expanded/music_view/palette.rs`）：
|
||||
|
||||
- 把封面画到 8×8 的 GPU surface（`PALETTE_SAMPLE_SIZE = 8`）读回求平均 RGB
|
||||
- `primary = brighten(avg, 1.3)`、`secondary = brighten(avg, 1.5)`
|
||||
- `brighten` 用 BT.601 亮度 `0.299R + 0.587G + 0.114B`；若 < 80 则整体加 `80 - brightness`（抬到最低亮度 80）
|
||||
- 调色板 = `[primary, secondary, primary]`，缓存上限 50 条
|
||||
- 无封面默认值（`default_media_palette`）：`rgb(180,180,180)` + `rgb(100,100,100)`
|
||||
- 采样完全失败的兜底：`rgb(200,200,200)`
|
||||
|
||||
### 2.7 不同状态是否不同配色？
|
||||
|
||||
- **同一套**：底 + 白字 + alpha 分层；通知 / 音量 / 音乐 / 挂件没有各自的独立配色，
|
||||
视觉区分靠 **尺寸（330×82 / 192×37 / 120×27）** 与 **内容排版**，而不是换色。
|
||||
- 差异只在两处：**可视化条用封面取色**（2.6），**资源占用用 CPU/RAM/警告/危险四色**（2.6）。
|
||||
- 岛背景三样式（default/glass/dynamic）才是真正的配色分支（2.1）。
|
||||
|
||||
### 2.8 设置窗口色板（另一套，`src/utils/color.rs`，供参考）
|
||||
|
||||
暗色主题 `dark_settings_theme()`：
|
||||
|
||||
```
|
||||
win_bg #1C1C1E sidebar_bg #242426 group_bg #2C2C2E card_highlight #48484A
|
||||
accent #0A84FF text_pri #F5F5F7 text_sec #AEAEB2 disabled #636366
|
||||
danger #E6372D toggle_on #30D158 toggle_off #636366
|
||||
sidebar_hover rgba(255,255,255,20) separator rgba(255,255,255,26)
|
||||
popup_bg #323234 popup_border rgba(255,255,255,40) popup_shadow rgba(0,0,0,60)
|
||||
popup_separator rgba(255,255,255,30) control_bg #3A3A3C control_hover #48484A
|
||||
control_disabled #303032 control_border rgba(255,255,255,36)
|
||||
group_border rgba(255,255,255,24) shadow rgba(0,0,0,45) scrollbar rgba(255,255,255,60)
|
||||
```
|
||||
|
||||
亮色主题 `light_settings_theme()`：
|
||||
|
||||
```
|
||||
win_bg #F4F5F7 sidebar_bg #FAFAFC group_bg #FFFFFF card_highlight #EFF2F7
|
||||
text_pri #1F2228 text_sec #5B626E disabled #9297A1 accent #0067C0
|
||||
danger #C42B1C toggle_on #0078D4 toggle_off #B0B5BE
|
||||
selection_bg #E0EEFA selection_text #005599
|
||||
sidebar_hover rgba(20,32,48,14) separator rgba(24,32,44,18)
|
||||
popup_bg #FFFFFF popup_border rgba(20,28,40,24) popup_shadow rgba(20,28,40,20)
|
||||
control_bg #F7F8FA control_hover #EBEFF4 control_disabled #F1F2F5
|
||||
control_border rgba(20,28,40,24) group_border rgba(20,28,40,14)
|
||||
shadow rgba(20,28,40,20) scrollbar rgba(52,58,68,52)
|
||||
```
|
||||
|
||||
设置窗口另有"岛预览"配色（与真实渲染略有差异，`src/utils/settings_ui/renderer/widget_preview.rs`）：
|
||||
glass 预览 `rgba(24,24,28,220)`；dynamic 预览为线性渐变 **`rgb(18,12,36)` → `rgb(8,24,48)`**（左上→右下）；
|
||||
default 预览 `rgb(10,10,10)`；预览描边 alpha `52`(glass) / `38`(其他)；预览阴影 `rgba(0,0,0,72)`，偏移 +4。
|
||||
→ 若前端需要一张**静态渐变**替代 `dynamic`，这两个色值就是现成可抄的。
|
||||
|
||||
---
|
||||
|
||||
## 3. 排版（字体 token）
|
||||
|
||||
### 3.1 字体族（`src/utils/font.rs`）
|
||||
|
||||
1. 用户自定义字体：`config.custom_font_path` → `FontMgr::new_from_data()`（优先于全部）
|
||||
2. ASCII 文本：`"Microsoft YaHei"` → `"Segoe UI"` → 系统默认（`legacy_make_typeface`）
|
||||
3. 非 ASCII：逐字符匹配 `match_family_style_character("", style, &["zh-CN","ja-JP","en-US"], ch)`，
|
||||
再依次尝试 `"Segoe UI Emoji"` → `"Microsoft YaHei"` → `"Segoe UI Symbol"` → `"Segoe UI"`
|
||||
4. 合成粗体：`needs_synthetic_bold()` = 请求 `weight >= 600` 且字体本身 `weight < 600` → `font.set_embolden(true)`
|
||||
5. 亚像素渲染始终开启 `font.set_subpixel(true)`
|
||||
|
||||
字重只有两档：`FontStyle::bold()`（700）与 `FontStyle::normal()`（400）；
|
||||
滚动文本判定粗体用 `style.weight() >= 700`（`src/utils/scroll.rs`）。
|
||||
|
||||
**字距 / 行高**：代码里**未找到** letter-spacing 或 line-height 参数；
|
||||
行距全部通过显式 y 偏移实现（见下表）。文本绘制走 Skia `draw_str`，
|
||||
大字文本（标题/歌手）`render_as_paths = true`（`src/utils/scroll.rs` 调用点）。
|
||||
|
||||
### 3.2 字号表（默认 `config.font_size = 0.0` 时用内置值；>0 时用户值参与计算）
|
||||
|
||||
| 用途 | 字号 | 字重 | 说明 / 来源 |
|
||||
| -------------------- | -------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| mini 歌词主行 | `font_size*0.8*scale` 或 **12.0\*scale** | normal | `src/core/render/mini.rs` `lyric_font_size()` |
|
||||
| mini 歌词次行 | 主字号 × `SECONDARY_LYRIC_SCALE = 0.85` | normal | 同上 |
|
||||
| mini 歌词对高度 | `主*(1+0.85+0.18) + 8*scale` | — | `lyric_pair_height()` |
|
||||
| mini 插件文字（主） | `font_size*0.7*scale` 或 **11.0\*scale** | **bold** | `PLUGIN_FONT_SCALE = 0.7`、`DEFAULT_PLUGIN_FONT_SIZE = 11.0` |
|
||||
| mini 插件文字（次） | 主 × `0.8` | normal | `PLUGIN_SECONDARY_FONT_SCALE = 0.8`，行距 `font_size*1.3`（`PLUGIN_SECONDARY_LINE_SPACING = 1.3`） |
|
||||
| expanded 曲名 | `font_size*scale` 或 **15.0\*scale** | **bold** | `src/ui/expanded/music_view.rs` |
|
||||
| expanded 歌手 | 同上 **15.0\*scale** | normal | 基线 = 曲名基线 + `22.0*scale` |
|
||||
| 进度时间 | `font_size*0.67*scale` 或 **10.0\*scale** | normal | `PROGRESS_TIME_FONT_SCALE = 0.67`、`DEFAULT_PROGRESS_TIME_FONT_SIZE = 10.0` |
|
||||
| 通知 app 名 | **11.0\*scale** | normal | `src/ui/compact/notification.rs` |
|
||||
| 通知标题 | **13.0\*scale** | **bold** | 同上 |
|
||||
| 通知详情 | **11.0\*scale** | normal | 行间距 `DETAIL_LINE_GAP = 21.0*scale` |
|
||||
| 音量标签 | **12.0\*scale** | normal | `src/ui/compact/volume.rs` |
|
||||
| compact 时钟挂件 | `clamp(h*0.43, 10, 12)` | **bold** | `src/ui/widget/compact/time.rs` |
|
||||
| compact 资源—标签 | `METRIC_LABEL_SIZE = 7.0*scale` | **bold** | `src/ui/widget/compact/resource_usage.rs` |
|
||||
| compact 资源—数值 | `METRIC_VALUE_SIZE = 10.0*scale` | **bold** | 同上 |
|
||||
| expanded 时钟挂件 | `min(h*0.60, w*0.31)`，最小 `13.0*scale` | **bold** | `src/ui/widget/expanded/time.rs` |
|
||||
| expanded 日历—月 | `clamp(h*0.14, 9, 15)*scale` | **bold** | `src/ui/widget/expanded/calendar.rs` |
|
||||
| expanded 日历—日 | `min(h*0.53, w*0.70)`，最小 `26.0*scale` | **bold** | 同上 |
|
||||
| expanded 日历—星期 | `clamp(h*0.12, 8, 12)*scale` | normal | 同上 |
|
||||
| expanded 资源—圆环值 | `clamp(d*0.27, 7, 10.5*scale)`，d = 圆环直径 | **bold** | `src/ui/widget/expanded/resource_usage.rs` |
|
||||
| expanded 资源—标签 | `clamp(h*0.12, 6, 8*scale)` | **bold** | 同上 |
|
||||
| 设置窗口—行标签/值 | **13.0** | normal | `src/utils/settings_ui/renderer/items.rs` |
|
||||
| 设置窗口—页签标签 | **11.5** | normal（选中为 bold） | `src/window/settings/renderer.rs` |
|
||||
| 设置窗口—弹窗项 | **12.0** | normal | 同上 |
|
||||
| 设置窗口—Markdown | `BODY_SIZE = 12.0`，`LINE_HEIGHT = 18.0` | — | `src/window/settings/pages/plugins/markdown.rs` |
|
||||
|
||||
字体基线规则（值得照抄）：
|
||||
|
||||
- 居中对齐用 **字形包围盒** 居中：`baseline_y = bounds.top + (bounds.h - glyph.h)/2 - glyph.top`
|
||||
（`src/ui/widget/expanded/mod.rs` `draw_widget_text_centered()`）
|
||||
- 时间文字基线 = 进度条中心 + `0.35*字号`（`PROGRESS_TIME_BASELINE_SCALE = 0.35`）
|
||||
- 迷你歌词单行时 `primary_y = center_y + size/3`；双行时按堆叠高度对齐（见 5.1）
|
||||
|
||||
### 3.3 是否随窗口尺寸 / 用户设置缩放
|
||||
|
||||
- 随 `compact_scale` / `expanded_scale` 缩放（乘在所有尺寸上）
|
||||
- 字号受 `config.font_size`（默认 0 = 用内置值）影响：只有 mini 歌词、mini 插件、expanded 曲名/歌手、进度时间用它
|
||||
- 挂件字号是**几何驱动**的（按自身矩形宽高 clamp），与 `font_size` 无关
|
||||
- 设置窗口有自己的 `settings_theme`（`system` / 暗 / 亮）
|
||||
|
||||
---
|
||||
|
||||
## 4. 层级与效果
|
||||
|
||||
### 4.1 圆角
|
||||
|
||||
见 1.7。总结：连续超椭圆（squircle），compact 满圆角（h/2），expanded 最大 48。
|
||||
挂件卡片 `widget_corner_radius = min(12.0*scale, min(w,h)/2)`（`src/ui/widget/expanded/mod.rs`）。
|
||||
迷你封面 `MINI_COVER_RADIUS = 5.0`，expanded 封面 `16.0*scale`，通知图标 `11.0*scale`。
|
||||
|
||||
### 4.2 阴影 / 发光
|
||||
|
||||
- **外阴影**：仅 expanded，`rgba(0,0,0,0.11)`，y+2，blur σ = `min(3*scale, margin/3)`（见 2.3）
|
||||
- **内阴影**：**未找到**
|
||||
- **发光**：只出现在资源占用圆环——`glow` 圆半径 `diameter*0.57`，颜色 `accent`，alpha `0.07*alpha`
|
||||
（`src/ui/widget/expanded/resource_usage.rs`）
|
||||
- 设置窗口：窗口阴影 `rgba(0,0,0,90)`、弹出菜单阴影 `theme.popup_shadow` + 偏移 +2（`src/window/settings/renderer.rs`）；
|
||||
拖拽幽灵阴影 `rgba(0,0,0,90)`，偏移 +4
|
||||
|
||||
### 4.3 模糊半径（全部数值）
|
||||
|
||||
| 场景 | 参数 | 来源 |
|
||||
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------- |
|
||||
| 运动模糊（整体） | 横向 = ` | w速度 | *0.3 + | view速度 | *w*0.4`，纵向 = ` | h速度 | *0.3`；上限集显 `(4.0, 3.5)`、独显 `(12.0, 10.0)`；仅在 σ>0.1 时 `saveLayer` | `src/utils/blur.rs` `calculate_blur_sigmas()`、`src/core/render.rs` `MIN_BLUR_SIGMA = 0.1` |
|
||||
| 封面翻转 | `σ = (1- | cos | )^0.6 * 8.0 * scale`，x 方向再 ×0.3 | `src/ui/expanded/music_view.rs` |
|
||||
| 暂停按钮速度模糊 | ` | 弹簧速度 | * 16.0 * scale`，上限 `2.5*scale` | `PAUSE_CONTROL_BLUR_SCALE = 16.0`、`PAUSE_CONTROL_MAX_BLUR = 2.5` |
|
||||
| 快进/快退按钮 | `(1 - t/0.3).max(0) * 6.0 * scale`，x×0.3 | 同文件 `draw_skip_button()` |
|
||||
| 歌词切换（Blur 模式） | `σ = 6.0*scale`，x 压缩 `LYRIC_TRANSITION_BLUR_X_SCALE = 0.25`，位移 `LYRIC_TRANSITION_OFFSET = 10.0*scale` | `src/core/render/mini.rs` |
|
||||
| dynamic 背景封面 | 先降采样到 **64×64**，再 `image_filters::blur((8.0, 8.0), TileMode::Clamp)` | `src/utils/backdrop.rs` |
|
||||
| host backdrop（亚克力） | **未找到数值**（由系统 HostBackdropBrush 决定，仅 `HOST_BACKDROP_INSET = 1.0`） | `src/window/d3d.rs` |
|
||||
|
||||
### 4.4 不透明度分层与可见性阈值
|
||||
|
||||
```
|
||||
MIN_VISIBLE_OPACITY = 0.01 // 低于此不绘制
|
||||
MIN_BLUR_SIGMA = 0.1
|
||||
MINI_FADE_RATE = 1.5 // mini 淡出速率
|
||||
COLLAPSED_VISUALIZER_HEIGHT_SCALE = 0.45 // 收起时可视化高度 = 45%
|
||||
```
|
||||
|
||||
- `expanded_alpha = expansion_progress² * (1 - hide_progress)`（平方 → 展开"迟入场"）
|
||||
- `mini_alpha = clamp(1 - expansion_progress*1.5, 0, 1) * (1 - hide_progress)`
|
||||
- 可视化高度比例 `visualizer_height_scale = 0.45 + 0.55 * expansion_progress`
|
||||
- 歌词额外淡出 `LYRIC_EXPANSION_FADE_RATE = 2.5`（`src/core/render/mini.rs`）
|
||||
- 展开页横向滑动：`page_shift = view_offset * current_w`；
|
||||
音乐页 `translate(-page_shift)`，挂件页 `translate(current_w - page_shift)`
|
||||
（`src/core/render/expanded.rs`）；`view` 弹簧 `0.12/0.68`
|
||||
|
||||
### 4.5 卡片四周留白 / 裁切
|
||||
|
||||
见 1.8：窗口 = 岛 + 80（每侧 40 透明）；内容 `clip_path(Intersect)`；
|
||||
描边在裁切外画；挂件网格 inset 24。
|
||||
|
||||
---
|
||||
|
||||
## 5. 布局骨架
|
||||
|
||||
### 5.1 compact（mini）120×27
|
||||
|
||||
`src/core/render/mini.rs`：
|
||||
|
||||
```
|
||||
MIN_MINI_CONTENT_WIDTH = 45.0 // 可用宽小于此不画内容
|
||||
MINI_COVER_SIZE = 18.0 // 封面尺寸
|
||||
MINI_COVER_LEFT_INSET = 10.0 // 封面左边距
|
||||
MINI_COVER_RADIUS = 5.0 // 封面圆角
|
||||
MINI_VISUALIZER_RIGHT_INSET = 17.0
|
||||
MINI_VISUALIZER_WIDTH_SCALE = 0.55
|
||||
MINI_VISUALIZER_SMOOTHING = (0.6, 0.08) // (上升, 下降)
|
||||
LYRIC_LEFT_INSET = 30.0
|
||||
LYRIC_RIGHT_INSET = 29.0
|
||||
```
|
||||
|
||||
- **左**：18×18 封面，x = 10，y 垂直居中（`(base_h - 18)/2 = 4.5`），圆角 5，中心裁剪
|
||||
- **中**：歌词，可用区 x ∈ [30, w-29]，垂直居中；主行居中（滚动模式改为左对齐并从 x=30 起滚动），
|
||||
次行始终水平居中；主行单行时 `y = center_y + size/3`，双行时
|
||||
`stack_h = size + size*0.85 + size*0.18`，主行 `y = center_y - stack_h/2 + size*0.8`，
|
||||
次行 `y = center_y + stack_h/2 - secondary*0.2`
|
||||
- **右**：可视化条，中心 x = `w - 17`，中心 y = `base_h/2`
|
||||
- 无媒体时改由 compact 挂件条接管：Left / Center / Right 三组；
|
||||
有 mini 内容时只画 Left 与（Center+Right）两组并贴两端，并在内容两侧画竖分隔线
|
||||
（`src/ui/widget/compact/mod.rs` `draw()`）
|
||||
- 挂件宽：时间 **48**、资源 **132**；边缘 inset **9**；组内间距 **7**
|
||||
|
||||
### 5.2 expanded 音乐页 360×200
|
||||
|
||||
`src/ui/expanded/music_view.rs` 常量全表：
|
||||
|
||||
```
|
||||
CONTENT_PADDING = 24.0 // 四周内边距
|
||||
COVER_SIZE = 64.0 // 封面 64×64，圆角 16.0*scale，位置 (24,24)
|
||||
TRACK_TEXT_GAP = 18.0 // 封面右到文字左
|
||||
TRACK_TEXT_RIGHT_INSET = 70.0 // 文字右侧预留（给可视化条）
|
||||
TRACK_TITLE_BASELINE_OFFSET= 26.0 // 曲名基线 y = 24 + 26 = 50
|
||||
PROGRESS_TOP_GAP = 24.0 // 进度条中心 y = 24 + 64 + 24 = 112
|
||||
PROGRESS_TIME_WIDTH = 28.0 // 两端时间文字预留宽
|
||||
PROGRESS_TIME_GAP = 4.0
|
||||
PROGRESS_BAR_HEIGHT = 6.5 // 常态条高
|
||||
PROGRESS_BAR_HOVER_GROWTH = 3.5 // hover 增至 10.0
|
||||
PLAYBACK_CONTROLS_TOP_GAP = 42.0 // 控制行中心 y = 112 + bar_h/2 + 42 ≈ 157.25
|
||||
SKIP_BUTTON_GAP = 75.0 // 上一首/下一首中心距播放键 75
|
||||
PAGE_ARROW_RIGHT_INSET = 7.5 // 右侧翻页条 x = w - 7.5，y = h/2
|
||||
PAGE_ARROW_FADE_RATE = 5.0
|
||||
COLLAPSED_VISUALIZER_INSET = 17.0 // 视觉条右侧 inset 随展开 17 → 37
|
||||
EXPANDED_VISUALIZER_INSET = 37.0
|
||||
VISUALIZER_TITLE_OFFSET = 4.0 // 视觉条中心 y = 曲名基线 - 4
|
||||
```
|
||||
|
||||
- **左**：64 封面；**中**：曲名(15 bold)/歌手(15, α0.6) 两行，x = 24+64+18 = **106**；**右**：可视化条
|
||||
- 进度条：左右各内缩 24，两端 28 宽时间 + 4 间距；条圆角 = bar_h/2；
|
||||
填充宽度 `max(bar_total_w*progress, bar_h)`；填充只圆左端（RRect 左上/左下半径 = bar_h/2，右侧 0）
|
||||
- 控制行中心 x = 180；播放键在中心、上一首 105、下一首 255
|
||||
- 点击热区（`src/ui/expanded/music_view/controls.rs`）：播放 **40×40**，上/下一首 **36×36**，
|
||||
进度条热区高 **16.0\*scale**，封面整块可双击（激活媒体 App）
|
||||
- 动画参数：`PROGRESS_SMOOTHING = 0.15`、`PROGRESS_HOVER_SMOOTHING = 0.18`、
|
||||
`PROGRESS_HOVER_SNAP_THRESHOLD = 0.005`、`PROGRESS_START_THRESHOLD = 0.02`、`PROGRESS_JUMP_THRESHOLD = 0.3`、
|
||||
`PLAY_STATE_RESPONSE = 0.18`、`SKIP_ANIMATION_DURATION_SECS = 0.5`、封面翻转 0.6s、
|
||||
`PAUSE_CONTROL_STIFFNESS = 0.18`、`PAUSE_CONTROL_DAMPING = 0.64`、`PAUSE_CONTROL_MIN_SCALE = 0.8`、
|
||||
`PAUSE_CONTROL_MAX_SCALE = 1.03`、`PAUSE_CONTROL_PRESS_VELOCITY = -0.18`
|
||||
- 播放/暂停过渡：`cover_scale = 0.85 + 0.15*pause_t`、`cover_brightness = 0.75 + 0.25*pause_t`
|
||||
（即暂停时封面缩小到 85% 并压暗到 75%），图标用 `smoothstep` 交叉淡出
|
||||
|
||||
### 5.3 expanded 挂件页（同 360×200）
|
||||
|
||||
- 6×3 网格，inset 24，gap 7（见 1.9）
|
||||
- 卡片：背景 `rgba(28,28,30, 0.05*alpha)`，描边 `1px rgba(255,255,255, 0.16*alpha)`，圆角 `min(12*scale, min(w,h)/2)`
|
||||
- 左侧翻页条 x = **7.5**，y = `h/2`（3×14 圆角矩形，α0.4）；右侧同（x = w-7.5）
|
||||
- 内置挂件各视图排布：
|
||||
- **时钟**：整卡居中，字号 `min(h*0.6, w*0.31)`（≥13），bold，`HH:MM` 格式
|
||||
- **日历**：月 `y+0.08h..0.26h`（bold，α0.78）／日 `y+0.27h..0.75h`（bold，字号 `min(0.53h,0.70w)`，≥26）／
|
||||
星期 `y+0.78h..0.92h`（normal，α0.62）
|
||||
- **资源占用（2×1）**：中间竖分隔（α0.09，`y+0.2h..0.8h`）；两个圆环各占一半：
|
||||
环心 `(center_x, top+0.43h)`，直径 `min(0.58h, 0.62w)`（≥20），描边 `min(3*scale, d*0.12)` 圆头，
|
||||
底环 α0.13，进度弧从 **-90°** 起扫 `usage*360°`（α0.92），值文字 bold 居中，标签在 `top+0.76h`（α0.58）
|
||||
- **设置（1×1）**：整卡居中齿轮图标，`icon_scale = min(w,h)*0.38/24`，α0.72
|
||||
|
||||
### 5.4 compact 各业务视图差异
|
||||
|
||||
| 视图 | 尺寸 | 排布 |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 时间挂件 | 48×27 | 居中 `HH:MM`，字号 `clamp(0.43h, 10..12)` bold，基线 `center_y + size*0.36` |
|
||||
| 资源挂件 | 132×27 | 两个 metric 各 `(w-8)/2` 宽；标签 7px bold 在左（accent α0.78），数值 10px bold 在右（白）； |
|
||||
| 文字基线 `center_y + scale`；下方 2px 进度轨（y = 基线+5），轨 α0.13，填充 accent α0.9；中间分隔 α0.1，半高 6 |
|
||||
| 通知 | 330×82 | 图标 42×42 圆角 11 @ x+18 垂直居中；文本左 = 有图标 `x+72` / 无图标 `x+20`；右内缩 18； |
|
||||
| app 名基线 `top+22`（11px α0.65）；标题 13px bold，基线 `top+34`（无 app 名）/ `top+43`（有 app 名）/ 垂直居中 `top+(h+13)/2`（两者皆无）；详情 11px α0.72 在标题下 21px |
|
||||
| 音量 | 192×37 | 喇叭图标 20px，中心 `x = left+21`；标签 12px @ `left+37`（α0.9）；轨道从 `label_x + label_w + 26` 到 `right-14`，高 4 圆角 2，轨 α0.28，填充白 α1.0 |
|
||||
|
||||
### 5.5 动画时长（通知 / 音量）
|
||||
|
||||
- 通知：`DISPLAY_DURATION = 5s`，`ENTER_DURATION = 220ms`（`ease_out_cubic = 1-(1-t)³`），
|
||||
`FADE_DURATION = 280ms`；入场位移 `(1-enter)*7.0*scale`（从上滑下 7px）
|
||||
- 音量：`DISPLAY_DURATION = 1600ms`，`FADE_DURATION = 240ms`，
|
||||
`VOLUME_CHANGE_THRESHOLD = 0.002`（音量变化阈值，低于此不显示）
|
||||
- 歌词切换进度用 `smoothstep`：`p*p*(3-2p)`（`src/core/render/mini.rs`）
|
||||
- 长文本跑马灯（`src/utils/scroll.rs`）：先停 **2.0s**，再以 **35.0\*scale px/s** 滚动，
|
||||
循环间隔 `full_w + 50*scale`，裁剪区 `(x, y-size*1.2, max_w, size*1.5)`
|
||||
|
||||
---
|
||||
|
||||
## 6. 图标
|
||||
|
||||
**体系**：全部是 Skia 内的 **SVG path 数据 + 填充（`PaintStyle::Fill`）**，没有线性描边图标体系，
|
||||
也没有 icon font。颜色一律单色：由 `text_color`（= 白）+ alpha 决定；只有资源环用 accent 色。
|
||||
**未找到**线宽（stroke-width）概念——唯一的描边图标是设置窗口的翻页箭头（`1.8px`, round cap/join）。
|
||||
|
||||
| 图标 | 路径坐标系 | 缩放 | 实际视觉尺寸 | 来源 |
|
||||
| ---------------- | ------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| 播放 ▶ | 640 单位（128..544） | `0.083 * scale` | ≈ 34.5 × 37 px | `src/icons/controls.rs` `draw_play_button` |
|
||||
| 暂停 ⏸ | 640 单位 | `0.083 * scale` | ≈ 34.5 × 37 px | `draw_pause_button` |
|
||||
| 快退/快进三角 | 640 单位（中心 336,320） | `path_scale * global_scale`，静止 `0.050`（左）与 `0.055`（右）；动画中 `0.050~0.055` | 约 21 × 22 px | `draw_control_triangle`，`src/ui/expanded/music_view.rs` `draw_skip_button`（中心 ±10.92*scale） |
|
||||
| 音乐（封面占位） | 1024 单位 | `scale*1.8`，内部 `0.024` | 随卡片 | `src/icons/music.rs` |
|
||||
| 设置齿轮 | 1024 单位 | `min(w,h)*0.38/24`，内部 `0.024` | 卡片 38% 短边 | `src/icons/settings.rs` |
|
||||
| 音量（4 档） | 25.75 单位 | `size / 25.75`，偏移 `(-11.089286, -7.883929)` | 传 20.0*scale | `src/icons/volume.rs`；档位 `level<=0→静音, <=1/3→低, <=2/3→中, else→高` |
|
||||
| 翻页指示条 | 不是 path | — | `3.0*scale × 14.0*scale` 圆角矩形，圆角 `2.0*scale`，α×0.4 | `src/icons/arrows.rs` |
|
||||
|
||||
其他图标使用点：
|
||||
|
||||
- 通知 App 图标：`AppDisplayInfo::GetLogo(Size{64,64})`，按 alpha>8 计算可见包围盒，等比缩放塞进 42×42，圆角 11 裁切
|
||||
- 封面：64×64（expanded）与 18×18（mini），中心裁剪，`FilterMode::Linear + MipmapMode::Linear`
|
||||
- 迷你封面圆角 5、expanded 封面圆角 16（连续超椭圆路径，不是普通 `clip_rrect`）
|
||||
|
||||
---
|
||||
|
||||
## 7. 明确「未找到」的项
|
||||
|
||||
1. **刘海/挖孔造型**：不存在（无 `SetWindowRgn`、无顶部直角特例）
|
||||
2. **内阴影 / inset shadow**：代码中无任何实现
|
||||
3. **字距（letter-spacing）与行高倍数**：无；行距全靠显式 y 偏移
|
||||
4. **亚克力的模糊半径/透明度数值**：由 Windows `HostBackdropBrush` 系统决定，代码只给 `HOST_BACKDROP_INSET = 1.0`
|
||||
→ Electron 侧**没有**等价物：`setBackgroundMaterial('acrylic')` 是整窗系统材质（跟随应用主题、覆盖窗口矩形），
|
||||
不能像 `DWMWA_USE_HOSTBACKDROPBRUSH` 那样只画在圆角形状里；本项目因此改用无 backdrop 的降级色（见 §8）
|
||||
5. **强调色用于岛内 UI**：岛内几乎没有强调色（只有资源占用的 CPU/RAM/警告/危险色）；
|
||||
统一强调色 `#0A84FF` 仅存在于**设置窗口**（`COLOR_ACCENT`）
|
||||
6. **岛自身的亮/暗主题**：岛屿永远是深底白字；明暗主题只在设置窗口
|
||||
7. **固定渐变色背景**：真实 `dynamic` 背景是封面图，没有固定渐变；
|
||||
仅设置页预览用 `rgb(18,12,36) → rgb(8,24,48)`（可当静态替代）
|
||||
8. **CSS 等价的超椭圆圆角公式**：真实实现是 Flutter 超椭圆查表（`src/utils/shape.rs`），没有简单的 border-radius 参数
|
||||
|
||||
---
|
||||
|
||||
## 8. 给 Web/Electron 复刻的映射速查
|
||||
|
||||
- 岛容器：定位在屏幕顶上 `top: 10px`、水平居中，尺寸与圆角用 spring 插值
|
||||
（`cubic-bezier` 或 JS 弹簧，参考 `stiffness 0.10 / damping 0.68`）；`overflow: hidden` 做裁切
|
||||
- compact：`120×27`（有歌词时宽度跟着文本走，上限 700；只有媒体无歌词时 155），`border-radius: 13.5px`（胶囊）
|
||||
- expanded：`360×200`，`border-radius: 48px`（想要 iOS 味请用 SVG 超椭圆路径）
|
||||
- 背景：`#000` 不透明；"glass" **不要**照搬 WinIsland 的 host backdrop —— Electron 的
|
||||
`setBackgroundMaterial()` 是"整窗系统材质"，覆盖范围是窗口矩形而不是卡片形状，且明暗跟随应用主题，
|
||||
在浅色主题下会给卡片垫出一圈浅色面板（详见 `packages/desktop-client/src/main/island.ts`）；
|
||||
我们改用 WinIsland 自己的**无 backdrop 降级色** `rgba(32,32,36,.804)` 画在卡片上；
|
||||
"dynamic" 用封面模糊层 + `rgba(20,20,24,.471)` 叠加
|
||||
- 描边：`1px solid rgba(255,255,255,.118)`（纯色样式，展开时淡出）/ `.157`（glass、dynamic）
|
||||
- 阴影：仅展开 `0 2px σ rgba(0,0,0,.11)`（σ ≈ 3px）
|
||||
- 文字：`-apple-system / "Microsoft YaHei" / "Segoe UI"`，白 + alpha 分层（.65 / .72 / .9 / .6 / .5 / .58 / .62）
|
||||
- 图标：内联 SVG，`fill: currentColor`，播放/暂停按 640 坐标系、尺寸 ≈ 34.5×37
|
||||
|
||||
---
|
||||
|
||||
## 附：ClassHelper实际采纳了哪些（本次重写对照表）
|
||||
|
||||
| WinIsland 做法 | 出处 | 我们的落地 | 验证 |
|
||||
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
||||
| **窗口一次建大包围盒，形变发生在窗口内** | `window/app/layout.rs` `required_window_size()` + `PADDING=80` | 窗口固定为「最大形态 + `ISLAND_SHADOW_PAD(10)`」，开合期间**一帧都不 setBounds** | 逐帧窗口签名恒为 `476x282@482,-2`（只有 1 种） |
|
||||
| 尺寸/圆角由弹簧驱动 | `utils/physics.rs` + `app.rs` `IslandSprings`（w/h/r = `0.10/0.68`） | `src/island/spring.ts` 同参数同更新式（dt 以帧计、`damping^dt`、换向保留 35% 动量 + 20% 距离上限），并加**零过冲钳制** | 岛中心/边缘波动 0.00px、无过冲 |
|
||||
| 连续圆角（超椭圆） | `utils/shape.rs` `continuous_rounded_rect_path` / `expanded_island_radius = min(48*scale, w/2, h/2)` | `src/island/squircle.ts` 超椭圆角路径；展开半径 `min(48×圆角/20, w/2, h/2)` | 形状 bbox 与卡片框一致（±2px） |
|
||||
| 内容交叉淡入 `expanded=progress²`、`mini=1-1.5×progress` | `core/render.rs`（`MINI_FADE_RATE=1.5`） | 两层常驻、透明度按同一公式 | 截图与 DOM 断言 |
|
||||
| 描边 1px 白 alpha 30（纯色）/ 40（glass） | `core/render.rs` `BORDER_*_ALPHA` | `--wn-border` 取同值（`.118` / `.157`） | 计算样式断言 |
|
||||
| 展开投影 `rgba(0,0,0,.11)`、y+2、σ=3 | `draw_expanded_shadow` | `drop-shadow(0 2px 3px rgba(0,0,0,.11))` | 截图 |
|
||||
| 纯黑底 / 亚克力（HostBackdropBrush） | `background.rs` + `win32.rs` `DWMWA_USE_HOSTBACKDROPBRUSH` | 纯黑底 / **glass 用 CSS 半透明深色卡**（WinIsland 无 backdrop 降级色 `rgba(32,32,36,.804)`）；**不调用** `setBackgroundMaterial()` | 计算样式 + 「卡片外圈透出桌面」整屏截图像素断言 |
|
||||
| `set_cursor_hittest` 命中控制 | `frame.rs`（`set_cursor_hittest`） | 默认 `setIgnoreMouseEvents(true,{forward:true})`，渲染层命中测试后切换 | 岛内 true / 岛外 false |
|
||||
| 空闲细缝 `hidden_width = 5` | `core/config.rs` | 6px 宽竖条（窗口固定，不再受 Windows 最小窗口高度限制） | 空闲 `6x22` → 来消息 `268x44` |
|
||||
| 6 个停靠位 `DockPosition` | `core/config.rs` | 顶/底 × 左/中/右 6 锚点，岛（而非窗口）精确落在锚点 | 6 锚点坐标断言 |
|
||||
| `font_size` = 基础字号 × 各文本系数 | `core/render/mini.rs`、`ui/expanded/music_view.rs` | 基础字号 11–20px × 系数表（标题 1.08/正文 0.95/次要 0.78/徽标与按钮 0.76/胶囊 0.92、0.74） | 13→19px 全部文本倍率 1.462 |
|
||||
| 未采纳：音乐/歌词/小组件/音量浮窗 | `ui/expanded/**`、`ui/widget/**` | 业务不同（我们做通知/作业/叫人/紧急） | — |
|
||||
外观范围改 shared，经典样式改 classic-island.css，自定义样式改 custom-runtime.css 和 custom-island.css，
|
||||
原生窗口与命中改 main/island.ts。组件结构/设置改 shared/island-layout.ts 并同步编辑器和运行时。
|
||||
展示行为见[灵动岛](../app/island.md)，测试见[验收与测试](testing.md)。
|
||||
Reference in new issue
Block a user