classhelper-island-refactor-prompt/parts/16-acceptance.md

16. 质量门禁与验收清单

本部分是硬性验收标准。你必须逐条执行并报告结果；任何一项未通过都不得声称「已完成」。所有自动验证必须在无头/离屏模式下执行，禁止弹出可见窗口、禁止播放声音、禁止操作真实课表数据。

16.1 工程与构建门禁

• pnpm install --frozen-lockfile 在 Node 20.19+ 下成功；pnpm-lock.yaml 已提交。
• pnpm -r typecheck 0 错误；pnpm lint 0 错误（warning 允许但需在报告中列出）。
• pnpm build 产出：主进程 dist/main、preload dist/preload、两个渲染入口（index.html、island.html）以及静态资源；island.html 与 index.html 分别可独立加载。
• 打包产物：Windows NSIS/portable 安装后能启动；卸载不残留用户配置（或按需保留并提示）；macOS/Linux 至少构建成功。
• 依赖清单固定版本并说明用途；无重复的同类库（例如不得同时使用两个日期库、两个状态库）。
• 仓库内无 node_modules、无构建产物、无日志、无密钥；.gitignore 完整。
• README 包含：环境要求、开发命令、构建命令、打包命令、目录说明、数据目录位置、插件/主题开发入口。

16.2 像素级视觉验收（主界面）

在 1920×1080、缩放 100% 的无头离屏截图（--headless --screenshot 或 Playwright Electron）下，与下列基准逐项比对（容差：颜色 ±2/255，位置/尺寸 ±1px，透明度 ±1%）：

• 岛默认位置：屏幕中上侧；上边距 = WindowDockingOffsetY（默认 0）+ 系统工作区顶部安全区；水平居中误差 0px。
• 默认行宽：内容自适应（Width=auto）；编辑模式下 MinWidth = ActualClientBound.Width；圆角 8px（RadiusX=RadiusY=8，可用设置改）。
• 背景不透明度 0.5（Opacity=0.5）；默认深色背景（BackgroundColor 默认黑，未启用自定义背景色时使用主题背景）；背景模糊/毛玻璃在支持的平台上启用，不支持时降级为半透明纯色且视觉不突变。
• 行垂直间距 5px（MainWindowLineVerticalMargin=5）；组件水平外边距 6px（Margin="6 0"）。
• 字号：次要 14、主体 16、强调 18、超大 20（可由设置覆盖）；默认字重 Medium（MainWindowFontWeight2=500）；字体为系统字体回退链。
• 进度条：位于当前课程行底部，宽度=行宽，高度见 4.4（建议 3px），颜色=强调色；进度精度默认降低（ReduceProgressAccuracy=true，即按整秒/整分更新，不逐帧抖动）。
• 隐藏/显示、编辑模式进入退出、上下文菜单弹出均无白屏、无黑边、无窗口阴影残影。
• 深色/浅色主题各截一张、Fluent/Classic 主题各截一张、125%/150%/200% 缩放各一张，全部与第 3、4、9 部分的规格一致。

16.3 功能行为验收（按模块）

主界面与窗口

• 6 个停靠位置、X/Y 偏移、多显示器索引生效；切换显示器后岛跟随。
• 不抢焦点：显示/切换页面时，当前前台应用（记事本/浏览器）不失去焦点，Alt+Tab 不出现岛。
• 任务栏：默认不显示；仅当「窗口模式」或「录屏模式」开启时显示。
• 鼠标穿透：开启后点击岛不触发任何事件；右键菜单仍可通过托盘打开；触摸设备长按可打开菜单。
• 隐藏规则：HideOnClass 上课隐藏、HideOnMaxWindow 前台最大窗口隐藏、HideOnFullscreen 全屏隐藏（排除进程名单生效）、高级规则集命中隐藏；任何隐藏后进入编辑模式必须强制显示。
• 临时显示：通过托盘/右键/自动化「显示主界面」在隐藏期间强制显示，并保持到超时或手动隐藏（行为与第 4.5 节一致）。
• 关闭再启动：位置/尺寸/缩放/透明度/主题/静默状态全部保持。
• 单实例：重复启动时旧实例收到信号并显示主界面（或按设置行为），新进程 1s 内退出。
• 开机自启开关生效（注册表/LaunchAgent/autostart 三平台），关闭后删除启动项。

组件

• 全部内置组件可添加、设置、删除、拖拽排序、嵌套；配置重新加载后视觉与行为一致。
• 每个组件的默认值、空数据兜底、超长文本截断/滚动、隐藏规则、显示优先级符合第 5 部分。
• 组件动画（时钟、倒计时、滚动、滑动、天气图标）在 60fps 下无抖动；浏览器 DevTools 无 layout thrash 警告。
• 组件在编辑模式下可被选中并显示虚线框（1.5px、虚线 1,1.5、圆角描边、Opacity 0.75）；退出编辑后完全消失。

课表/档案

• 时间点类型：上课/课间/分割线/行动；时间点可拖拽改时间、可快速录入、可跨天；校验不允许重叠/倒序。
• 周次轮换：单周、双周、1–9 周自定义轮换、偏移、起始周日期；跨学期/跨年正确。
• 临时课表：单日、跨天、按日期区间；预定课表到点自动启用、结束自动恢复；临时课表与正式课表优先级符合第 6 部分。
• 换课：同日/跨日、按节次交换、恢复；影响提醒与当前课程。
• Excel 导入：支持 xlsx/xls/csv；模板列映射；错误单元格定位到行列；导入前预览；取消不落库。
• Excel 导出：导出当前档案课表，格式可再导入（往返一致）。
• CSES JSON 导入：字段映射与失败提示。
• 多档案：新建/复制/重命名/删除/切换；删除有二次确认与备份；默认档案在无课时兜底。
• 档案损坏/版本过旧：提示可恢复，不允许静默清空。

提醒

• 队列：高优先级插队、同级先进先出、同 id 去重、最长显示时长、可手动清除。
• 上课提醒：根据时间表在上课时间点触发；课前 N 秒（默认 60s）触发准备提醒；下课前倒计时（默认 60s）显示；下课提醒；放学提醒。
• 提醒内容：学科名、教师名、课间名、下一节课程、天气预警、自定义文本；布局与字号符合第 7 部分。
• 强提醒（Topmost）：全屏/大区域遮罩、超时自动关闭、点击/按键关闭、在岛所在的显示器上显示；不抢焦点。
• 音效：内置音效播放、音量、单次/循环；无音频设备时降级不报错；-q/--quiet 静默启动后 10 秒内丢弃提醒（ClassIsland 2.1 无独立「静音时段」，不得虚构该功能；如实现 P2 免打扰需默认关闭并标【推断】）。
• TTS：系统语音/Edge TTS 可切换、语速/音量/音色、失败回退；不阻塞 UI。
• 提醒设置：按提供者启用/排序/参数；修改后立即生效。
• 提醒历史：最近 N 条可查、可清空。

自动化

• 触发器全部可用（时间点/CRON/信号/URI/托盘菜单/窗口状态/当前课程/天气/日出日落）。
• 行动全部可用（提醒/运行程序/打开文件/打开网页/关机/睡眠/重启/修改设置/广播信号/切换课表/发通知）；危险行动有二次确认与超时保护；测试模式禁止真实关机。
• 规则集：AND/OR/NOT、嵌套、比较运算、空值处理；求值结果与第 8 部分一致。
• 执行日志：时间、触发源、行动、结果、耗时；失败重试有上限；不会无限循环。
• 自动化关闭时不执行任何行动。

设置与窗口

• 每个设置页与控件、默认值、枚举项与第 10 部分清单一致；搜索可命中设置标题/关键词。
• 设置即时生效（防抖 300ms 内）；需要重启的项明确提示并提供重启按钮。
• 设置导入/导出、恢复默认、覆盖层（SettingsOverlay）按预期工作。
• OOBE 可完整走通、可跳过、可从设置再次打开；OOBE 未完成时主窗口不出现或被引导遮罩。
• 所有次级窗口的尺寸/标题/按钮/关闭行为符合第 11 部分；Esc 关闭；关闭设置不退出应用。
• 崩溃窗口、恢复模式、更新进度、数据迁移、教程、授权、日志窗口可正常打开/关闭，无内存泄漏（关闭后窗口对象被释放）。

主题/资源/本地化

• 内置主题切换全覆盖、无残留样式、无闪烁；非法主题包被拒绝且不崩溃。
• 若实现 P2 壁纸取色（ClassIsland 2.1 已停用、默认关闭），取色结果稳定且浅色/深色下前景对比度 ≥ 4.5:1（WCAG AA）；色盲安全抽查；未实现时不得在设置页露出可用的取色入口（按源码禁用隐藏）。
• 图标/字体/音效资源齐全，缺失时使用兜底资源；无 404。
• 中文文案 100% 覆盖；文案集中在常量文件；ClassIsland 2.1 只有 3 种语言且仅覆盖设置页与托盘菜单（其余硬编码中文），因此本实现交付「完整 zh-CN + 文案集中」，不得宣称全量多语言；若要加 en-US 只能作为 P2 增量且不得遗漏中文兜底。

16.4 动画验收

• 第 14 部分动画总表中的每一项都实现，时长误差 ≤ 16ms，曲线一致（用 DevTools Animations 面板或离屏逐帧截图验证关键帧）。
• 岛出现/隐藏、行展开/折叠、提醒进出、强提醒、OOBE 转场、主题切换、设置页切换全部流畅；长任务不阻塞动画（用 Performance 面板确认帧率 ≥ 55fps）。
• prefers-reduced-motion / 设置中的「减少动画」（AnimationLevel=0）生效：仅保留必要的透明度变化，位移与缩放归零。
• 动画结束后无残留 will-change、无未清理的 requestAnimationFrame/定时器。
• 弹簧动画参数与 spring.ts 一致（stiffness 0.10、damping 0.68、snap 0.05px、换向保留 35%），不得用 CSS 过渡近似替代（行高/尺寸变化场景）。

16.5 数据完整性与容错

• 所有写入原子化（临时文件 + rename）；断电/强杀后配置仍可读。
• 自动备份：默认开启、每 7 天一次、最多保留 16 份（IsAutoBackupEnabled=true、AutoBackupIntervalDays=7、AutoBackupLimit=16），可从备份恢复。
• 配置版本迁移：旧版本字段兼容，迁移前备份，迁移失败自动回滚并提示。
• 配置校验：非法 JSON、未知字段、越界数值（如半径 -1、透明度 >1）被修正或拒绝，不崩溃。
• 崩溃恢复：渲染进程崩溃后自动重建（限流：1 分钟内最多 3 次，超过则进入安全模式）；GPU 崩溃降级软件渲染；安全模式下禁用插件/主题并提示。
• 数据目录可配置；卸载/重置时不误删用户手动备份。

16.6 性能与资源

• 冷启动到岛可见 ≤ 3s（SSD，不联网）。
• 空闲 CPU 平均 ≤ 1%（岛可见、时钟每秒刷新）；内存（主进程+两个渲染进程）≤ 300MB。
• 连续运行 24h 无内存增长（增长 ≤ 10%）、无句柄泄漏、无崩溃。
• 提醒密集场景（1 分钟 20 条）不卡顿、不丢提醒、不重复。
• 打包体积：Windows 安装包 ≤ 150MB（不含可选模型/音色资源）。
• 首屏构建资源 ≤ 2MB（gzip）；岛渲染进程启动 ≤ 500ms。

16.7 平台与兼容性

• Windows 10 21H2+、Windows 11：透明/置顶/点击穿透/多显示器/DPI 125%/150%/200% 正常。
• macOS 12+：透明窗口、置顶、全屏隐藏、通知权限（如使用系统通知）。
• Linux X11：透明窗口、置顶、点击穿透；Wayland 明确提示不支持并给出降级说明。
• 触摸设备：单击/长按/滑动不冲突；编辑模式可拖拽。
• 屏幕阅读器可读出设置控件；键盘 Tab 顺序合理；所有按钮有 aria-label 或可见文本。

16.8 安全验收

• nodeIntegration: false、contextIsolation: true、sandbox: true（或提供等效隔离）；preload 仅暴露白名单 API。
• 所有 IPC 通道校验参数类型与来源窗口；渲染层不能任意读写文件/执行命令。
• CSP 严格（default-src 'self'；connect-src 仅允许天气/更新/插件市场域名）；无 unsafe-eval（Vue 生产构建）。
• 更新包必须校验哈希/签名；拒绝非 HTTPS 下载（本地镜像可通过设置允许但需明确警告）。
• 自动化行动执行命令有白名单/确认；日志脱敏（不含完整路径中的用户名/令牌）。
• 插件默认无 Node 权限；插件权限声明在清单中，安装时展示。
• 本地数据不上传；崩溃上报默认关闭/需同意（IsReportingEnabled 默认 true 但仅上报匿名崩溃，需在隐私页说明）。

16.9 交付物清单

• 源码 + pnpm-lock.yaml + 构建脚本。
• README.md、docs/architecture.md、docs/data-schema.md、docs/plugin-api.md、docs/theme-api.md。
• 示例档案（含 3 周轮换）、示例主题、示例插件（P1）。
• 无头测试：单元测试（时间/课表/规则/配置校验）+ 组件测试（岛渲染快照）+ 端到端测试（启动、开设置、切主题、导入课表）。
• 验收报告：逐条勾选 16.1–16.9，附截图路径与测试输出摘要；未通过项必须列出原因与修复计划。