ClassIsland Prompt Kit
22c1784bab
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构） - ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本） - 投喂指南、分卷、逐节文件 - 调研记录、一致性基线、生成与质检脚本
140 lines
13 KiB
Markdown
140 lines
13 KiB
Markdown
## 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，附截图路径与测试输出摘要；未通过项必须列出原因与修复计划。
|