classhelper-island-refactor-prompt/parts/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 | 插件沙箱/更新安全 | 打包安装可用 |