ClassIsland Prompt Kit
22c1784bab
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构） - ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本） - 投喂指南、分卷、逐节文件 - 调研记录、一致性基线、生成与质检脚本
11 KiB
11 KiB
11. 兼容性、性能、平台与测试基线
本部分规定「重构不能把原来能用的东西弄坏」，以及如何在不打扰用户的前提下验证。所有验证默认必须无头/离屏执行。
11.1 兼容矩阵（必须逐项通过）
| 维度 | 必须保持兼容的内容 | 验证方式 |
|---|---|---|
| 配置 | 旧 config.json.islandLayout（fixed/custom、residentEnabled、schemes/rows/nodes/expandedRows/appearance/lessonReminders/pointerFade*）无损升级 |
迁移单测 + fixtures 回放 |
| 布局模式 | fixed 与 custom 均可切换、可保存、可重启恢复；两布局共用一个原生岛窗口，切布局不新开窗口 |
无头集成测试 + 主进程单测 |
| 风格 | family 只影响 fixed：winisland 保持旧胶囊观感，classisland 为默认信息行；custom 始终 ClassIsland 规格；切换即时生效、可回退 |
截图（仅 --visual）+ 视觉回归 |
| 消息 | 通知/作业/叫人的类型、优先级、id 去重、排序、上课暂存、紧急展开、叫人可点胶囊、已读回执、安静模式、教师/班级端差异不变 | 状态机单测 + 无头消息场景 |
| 课程 | 课表解析结果（ScheduleDto/IslandTimePointDto）、准备/上课/课间/下课前/课中进度提醒、下课前秒数徽标、当前/下一节/今日时间点显示；行为变更：custom 不再临时接管岛显示课程提醒（仅保留 ending 徽标，进度由课程组件显示），fixed 按 ClassIsland 接管 |
时间状态机单测 + 假时钟无头场景 |
| 天气 | Open-Meteo 数据、15 分钟刷新、断网缓存标记"缓存"、无官方预警提示 | 无头 mock 网络 + 快照 |
| 课件 | 课件传输状态优先覆盖岛内容、SHA256 校验、回执、不自动运行文件 | 无头课件场景 |
| 编辑器 | 方案/行/组件/导入导出/预览/重置/新建/复制/删除、12 行/200 节点/6 层/20 方案边界 | 单测 + 组件测试 |
| 窗口/输入 | 透明、置顶、不占任务栏、点击穿透、触摸模式、失焦宽限、固定几何护栏、单实例 | 无头窗口参数断言 + 手工触摸说明 |
| 平台 | Windows 10/11（主目标）、macOS、Linux X11；DPI 100/125/150/200；多显示器与热插拔 | 平台矩阵 + 无头几何断言 |
| 性能 | 启动、空闲 CPU、内存、消息风暴、动画帧率 | 性能脚本 + 采样 |
11.2 配置迁移与回滚（硬要求）
- 版本化：
IslandLayoutSettings.version从1（旧配置缺失视为 1）升级到2；迁移函数必须幂等（重复执行结果一致）。 - 迁移顺序：读取原始 JSON → 备份到
config.json.bak.<时间戳>（或配置目录backups/）→ 应用迁移（只补齐/转换，不删除用户数据）→normalizeIslandLayouts()校验与夹取 → 原子写（临时文件 + rename）。 - 必须迁移的字段：
- 顶层新增
version、appearance.family（老用户默认'winisland'，新安装'classisland'）、appearance.theme（'fluent'/'classic'）、strongNotification开关与参数、progressBar参数、rowStyle（行背景/分隔/圆角覆盖）； - scheme 新增
rowHeight（默认 40）、componentGap（默认 12，对应单侧 6）、showProgress（默认 true）、hideRules扩展（保留旧in-class/no-message/no-class，新增full-screen/max-window需按 12 部分验收）； - 组件新增字段（如 schedule 的
display扩展、countdown 的showProgress、clock 的showSeconds），旧值必须原样保留。
- 顶层新增
- 回滚：迁移失败或新版启动检测到配置不可用时，必须能恢复备份并启动旧结构（主进程启动早期读
config.json的islandLayout失败时使用默认值 + 保留原文件为.corrupt），不得清空用户方案。 - 降级兼容：若旧版本客户端读到新配置，必须忽略未知字段并使用默认值；禁止因未知字段崩溃。版本号高于当前可识别值时，主进程写日志并走只读模式（不自动覆盖新配置）。
- fixtures：
packages/shared测试中必须包含：fixed 默认、custom 多方案/多行/嵌套容器/旧 residentEnabled、极端值（超 12 行/200 节点/6 层/颜色非法/坐标为 null）、旧字段缺失、迁移幂等、迁移失败回滚。
11.3 IPC 与契约兼容
- 保留现有通道：
island:get-schedules、island:get-time-points、island:get-layout、island:save-layout、island:edit-layout、island:get-editing、island:get-visible、island:resident-control、island:resident-touch、island:set-editing、island:content-size、island:remove-notification、island:push、island:class-state、island:alive、island:get-state、island:set-appearance、island:get-appearance、island:set-interactive、island:set-hit-rect、island:set-touch-mode、island:action。 - 新增通道必须遵守：
ipcMain.handle/on前校验event.sender === island.getWindow()?.webContents（或主窗口 webContents），payload 必须是纯数据且做类型/范围校验；preload 白名单同步更新src/preload/island.ts与src/types/desktop.d.ts。 - 新增通道建议（如需要）：
island:strong-notification（主进程→岛/强提醒窗口）、island:get-metrics（渲染层上报行/组件度量）、island:preview-mode（编辑器预览）。不得把 Vue Proxy/函数/类实例跨 contextBridge 传递。 - 渲染进程心跳、幽灵窗口检测、渲染崩溃自愈（限流 3 次/10 分钟）与恢复逻辑保持不变。
11.4 性能预算（超预算必须优化）
- 岛渲染进程启动 ≤ 500ms（从窗口创建到首帧可见）；冷启动到岛可见 ≤ 3s（不含网络）。
- 空闲 CPU 平均 ≤ 1%（岛可见、时钟/课程正常刷新）；消息到达/展开瞬间峰值 ≤ 15% 且 ≤ 500ms。
- 主进程 + 岛渲染进程内存 ≤ 250MB（不含可选强提醒窗口）；连续运行 24h 增长 ≤ 10%。
- 消息风暴：1 分钟 20 条不丢、不重复、不卡顿；队列长度上限与丢弃策略必须有日志。
- 动画：主界面过渡 ≥ 55fps；消息气泡/强提醒 ≥ 50fps；不得因背景页（主窗口隐藏）继续动画。
- 包体：本次重构不得新增 > 200KB 的运行时依赖；不得引入新 UI 库/图标库（图标仍用现有方案）。
11.5 平台差异与窗口护栏
- Windows：透明/置顶/点击穿透/
setShape（若用）只在 Windows 分支；Windows 10 不支持 Mica 时退回纯色；高 DPI 下窗口 bounds 用 DIP。 - macOS：透明窗口、置顶、全屏空间行为；不使用
setBackgroundMaterial；点击穿透退化为整窗setIgnoreMouseEvents(true,{forward:true})+ 命中通道。 - Linux X11：透明窗口与置顶可用；Wayland 明确不支持并给提示（与 ClassHelper 既有说明一致）。
- 多显示器：
position/followCursorDisplay/停靠偏移语义保持不变；显示器热插拔/DPI 变化必须重算包围盒与锚点，节流 ≥100ms。 - 触摸：触摸模式仍以"窗口贴合岛体 + 始终接收输入"为原则；编辑模式与触摸手势不能互相抢占；失焦宽限（鼠标 500ms / 触摸 1200ms）保持不变。
- 强提醒窗口：无边框、置顶、不抢焦点、
skipTaskbar、独立渲染入口或复用岛窗口的独立层；关闭后释放；不得在编辑器/预览中创建。
11.6 测试基线（无头优先）
- 单元测试（shared）：
normalizeIslandLayouts边界、迁移幂等、版本识别、颜色/数值夹取、组件树限制（12 行/200 节点/6 层/20 方案）、消息排序/去重、课程状态机（准备/上课/课间/下课前/放学/跨天/跨周）。 - 主进程测试：窗口几何计算（6 停靠 × DPI × 多屏）、hit rect/触摸模式切换、消息队列与暂存、课程提醒调度、天气缓存、课件覆盖优先级、配置写入原子性与回滚。
- 组件测试：固定数据下
IslandApp.vue/CustomIslandRuntime.vue的渲染快照（DOM 结构 + 关键 computed 样式），不创建真实窗口（可用 happy-dom/离屏渲染）。 - 集成（无头）：
pnpm verify:desktop默认后台快速检查——不得创建可见岛/托盘；覆盖启动、布局切换、消息推送、课程提醒、编辑器保存/读取、迁移。 - 视觉（显式）：只有
pnpm verify:desktop:visual/--visual才允许真实桌面、动画采样、截图；截图输出目录用临时路径；不得把窗口对照图发布为展示图。 - 数据纪律：测试使用临时 SQLite/夹具，禁止使用真实班级、真实密码、真实通知；远控/安装器使用假执行器。
- 证据：每次汇报附实际命令输出摘要（通过/失败数量），不得沿用历史数字。
11.7 观测与诊断
- 主进程日志必须记录：配置迁移（旧→新字段、备份路径、结果）、窗口几何重算原因、消息队列变化（入队/出队/丢弃/去重）、课程状态切换、天气刷新/失败、强提醒创建/销毁、渲染崩溃/重建（限流计数）。
- 岛渲染进程必须上报心跳与度量（行/组件尺寸、可见性）；主进程对"幽灵窗口"（渲染卡死但窗口在）执行重建（限流）。
- 诊断页/日志中不得包含用户密码、令牌、完整数据库路径；日志轮转与大小上限沿用现有 logger。
- 提供
docs/dev/island-refactor.md的排障章节：黑屏/透明失效/点击穿透/闪烁/动画卡顿/消息不弹/课程不刷新/迁移失败的症状 → 排查步骤 → 回滚方法。
11.8 文档与交付说明
- 更新
docs/app/island.md：新默认观感、风格切换、editor 编辑模式、强提醒、行为表（含 fixed 重定义）。 - 更新
docs/dev/implementation.md：岛的新架构入口、schema v2、迁移函数位置。 - 新增
docs/dev/island-refactor.md：架构图、文件职责、数据契约、动画表、迁移与回滚、测试命令。 docs/中的展示截图必须来自显式视觉验收且人工确认；不得使用重构中的对照图/失败截图。- 交付说明必须包含：与 ClassIsland 的差异清单（技术栈/能力取舍）、未实现项及原因、性能数据、回滚步骤。
11.9 本部分验收标准
- fixtures 覆盖 11.2 全部场景，迁移全部通过且幂等。
- 旧配置在重构版启动后方案、组件、外观、课程提醒开关全部保留，且可切回
winisland观感。 - 所有既有 IPC 通道仍可用，新增通道有 sender 校验与类型校验。
pnpm verify:desktop无参数运行时不创建可见岛/托盘/声音；--visual才创建。- 多显示器/DPI 切换后岛位置与尺寸正确，无 1px 抖动。
- 24h 无内存增长 > 10%、无崩溃、无幽灵窗口。
- 文档更新完成，含迁移/回滚/差异说明。