classhelper-island-refactor-prompt/out/sections/17-milestones.md

17. 开发里程碑与实现顺序

必须按 M0→M8 顺序推进；每个里程碑结束都要能「无头启动 + 通过该阶段验收」。禁止先堆功能再补架构。

M0 工程脚手架与进程骨架（0.5–1 天）

• 交付：
  • pnpm monorepo：pnpm-workspace.yaml（packages/*）、根 package.json（packageManager: pnpm@11.8.0）、tsconfig.base.json、Prettier/ESLint。
  • packages/desktop-client：Electron 主进程入口、island.html 与 index.html 两个 Vite 入口、preload 白名单、单实例锁、托盘、日志、config.json 原子读写、默认 settings.json。
  • packages/shared：类型定义、常量、schema、时间工具；packages/ui：tokens.css、基础控件。
• 验证（无头）：pnpm typecheck、pnpm lint、pnpm build 通过；主进程以 --headless 启动后不创建任何可见窗口，5 秒内输出 app-ready 并自动退出；配置文件按 schema 生成且二次启动可读回。
• 完成标准：config.json 字段完整、原子写、损坏时自动回退默认值并记录日志；窗口/托盘代码有开关（headless 模式全部跳过）。

M1 岛窗口 + 时钟引擎 + 基础显示（1–2 天）

• 交付：
  • 独立岛 BrowserWindow：透明、无边框、置顶、不抢焦点、默认不显示在任务栏、按 WindowDockingLocation 6 个位置停靠、多显示器选择、缩放、DPI 处理、关闭/隐藏动画。
  • 岛结构：多行容器（Lines）、行背景、连续圆角、背景不透明度、毛玻璃/纯色、进度条、遮罩层宿主。
  • 时间引擎：NTP 对时（可关闭）、手动偏移、倍速调试、休眠唤醒后重算。
  • 默认组件：日期 + 时钟 + 欢迎文本；右键原生菜单（完整项，见 4.7）。
• 验证：1920×1080@100% 下离屏截图与第 4 部分基准逐项比对；切换 6 个停靠位置、125%/150% 缩放截图无模糊/偏移；岛空闲 CPU < 1%。
• 完成标准：无边框、透明、点击穿透可切换、圆角与阴影正确、菜单可用、时钟跨分钟无跳变。

M2 组件系统（2–3 天）

• 交付：
  • 组件注册表、Component 数据模型（Id/Name/Type/Settings/Children/IsVisible/HidingRules）、组件设置面板、组件的添加/删除/拖拽排序/嵌套。
  • 内置组件按第 5 部分顺序实现：分隔线 → 文本 → 日期 → 时钟 → 倒计时 → 课程表 → 天气 → 滚动 → 滑动 → 堆叠 → 分组 → 容器。
  • 编辑模式：选中框、拖动把手、行设置抽屉、添加组件面板、组件设置弹层。
• 验证：每个组件在编辑模式可增删改、保存后重载不丢失；空数据/超长文本/多语言/深色主题截图验收；拖拽排序有动画且不闪烁。
• 完成标准：组件配置 JSON 与第 13 部分 schema 一致；关闭编辑模式无选中框残留。

M3 课程表与档案系统（3–4 天）

• 交付：
  • 时间表编辑器（时间点增删、上课/课间/分割线/行动、分钟级拖拽、快速录入、跨天）。
  • 课表编辑器（周模板、单日覆盖、多周轮换 1–9 周、群组、预定/临时课表、单日/跨天换课）。
  • 档案管理（新建/复制/删除/导入/导出/切换、默认档案、档案校验）。
  • Excel 导入（模板下载、表头映射、预览、错误定位）、Excel 导出、CSES JSON 导入。
  • 课程状态机：当前/下一节、课间、放学、跨天、提前上课/拖堂、时间点行动。
• 验证：构造 3 周轮换课表 + 临时换课 + 跨天场景，无头单元测试断言当前课程/剩余时间/下一节；Excel 往返导入导出数据一致；损坏档案提示可恢复。
• 完成标准：课程计算函数覆盖率 ≥ 90%；所有档案操作有备份。

M4 提醒系统（2–3 天）

• 交付：
  • 提醒队列与优先级、去重、排队/插队、提醒历史、清除全部提醒。
  • 内置提醒提供者：上课、下课、课前准备（提前 N 秒）、放学、天气预警、天气预报、管理通知、自定义（行动触发）。
  • 提醒 UI：气泡（行内展开/胶囊）、强提醒全屏特效；音效、TTS（系统 TTS/Edge TTS）、音量；-q/--quiet 静默启动后 10 秒内丢弃提醒（无独立静音时段，不得虚构）。
  • 提醒设置页与各提供者设置。
• 验证：无头注入假时间，断言 6:00–23:00 全时间点提醒触发一次且仅一次；队列优先级符合第 7 部分；气泡/强提醒动画时长与曲线与第 14 部分一致；关闭音效后不播放。
• 完成标准：重复提醒按 id 去重；上课期间普通提醒按规则暂存/延后；不阻塞主线程。

M5 设置中心 + OOBE（2–3 天）

• 交付：
  • 设置窗口：左侧导航（分组 + 图标 + 搜索）、右侧页面、面包屑/返回、即时保存、重启提示、恢复默认。
  • 全部设置页与控件、默认值、禁用条件（见第 10 部分）。
  • OOBE（8 页）：欢迎 → 许可证 → 翻新/迎新 → 基本 → 颜色 → 外观 → 系统 → 完成；支持跳过与再次打开。
• 验证：设置项与第 10 部分清单逐项对照；改变关键设置（圆角/透明度/字号/停靠/主题）后岛即时生效；重启后保持；搜索命中正确。
• 完成标准：设置写入防抖 ≤ 300ms；连续修改不产生大量磁盘写（合并写入）。

M6 主题系统（+ 可选壁纸取色 P2）（1–2 天）

• 交付：
  • 内置 Fluent/Classic 主题的完整 CSS 变量与组件样式差异。
  • 主题包格式（theme.json + theme.css + preview.png）、安装/卸载/启用、冲突处理。
  • 自定义背景色/前景色；系统深浅色跟随。
  • P2（可选，默认关闭）：壁纸取色——屏幕/壁纸采样、主色提取、深浅色适配、调色板候选（ClassIsland 2.1 已停用该功能，只给算法与数据结构，不纳入 P1 验收）。
• 验证：切换主题后主界面/设置/弹窗全部生效且无闪烁；非法主题包不崩溃；若实现 P2 取色，则抽查取色结果与壁纸截图的视觉一致性。
• 完成标准：主题变量覆盖第 3 部分全部 token；主题预览图自动生成或提供占位。

M7 自动化 + 天气 + 高级窗口（2–3 天）

• 交付：
  • 自动化引擎：触发器轮询/事件、行动执行、规则集求值、执行日志、失败重试/限流、危险行动二次确认。
  • 内置触发器与行动完整清单（见第 8 部分）；规则类型与嵌套。
  • 天气服务：定位/城市、当前/逐小时/3 天、预警、降水提醒、缓存与失败回退、图标主题。
  • 次级窗口：换课、ClassPlanDetails、Excel 导入/导出向导、崩溃/恢复、更新进度、时间调整、数据迁移、教程、关于、日志、调试。
• 验证：构造自动化场景（时间点触发提醒、窗口全屏时隐藏岛、下雨提醒）无头断言；断网时天气显示缓存并提示；危险行动（关机/睡眠）在测试模式下不得真正执行。
• 完成标准：自动化配置可导出/导入；执行记录可查；异常不会导致应用退出。

M8 插件、更新、恢复与打磨（2–4 天）

• 交付：
  • 插件宿主（P1）：清单、权限、启用/禁用、生命周期、扩展点（组件/提醒提供者/触发器/行动/设置页）、示例插件。
  • 更新：检查/通道/镜像/下载/哈希校验/静默安装/失败回滚；UpdateService 对应 update.ts。
  • 崩溃守卫与恢复模式：渲染进程崩溃自动重建（限流）、GPU 崩溃降级软件渲染、配置损坏恢复、安全模式。
  • 教程系统、文案集中（zh-CN；en-US 为 P2 可选）、无障碍、性能优化、打包脚本、文档、示例主题。
• 验证：打包产物在干净系统安装运行；断网/拔电源模拟崩溃后数据不丢；更新流程灰度与回滚；插件启用后无卡顿。
• 完成标准：全部 P0/P1 验收项通过；安装包体积与内存占用达标（见 16.6）。

里程碑总览表

里程碑	核心风险	完成标志
M0	进程模型/透明窗口/配置原子写	headless 启动 < 5s，无可见窗口
M1	透明置顶窗口跨平台差异、DPI	6 停靠位置像素级正确
M2	组件递归模型与编辑模式	组件配置闭环
M3	课表状态机/周次/导入	单元测试覆盖核心算法
M4	提醒去重与音视频调度	全时间点场景通过
M5	设置项数量庞大	设置清单 100% 对照
M6	主题变量覆盖与取色	切换无残留
M7	自动化安全/天气容错	危险行动有保护
M8	插件沙箱/更新安全	打包安装可用