out/refactor-sections/01-objective.md

## 1. 重构目标与范围

### 1.1 为什么重构、以什么为基准

ClassHelper 的灵动岛已经具备完整的工程骨架：独立透明窗口、`fixed`/`custom` 两种布局、多方案组件编辑器、消息队列、课程提醒、天气、课件覆盖。但它的视觉语言来自 WinIsland（连续圆角、小胶囊、弹簧形变、纯黑/毛玻璃），与 ClassIsland 的「Fluent 信息行 + 组件化 + 提醒气泡 + 强提醒特效 + 精细过渡」存在系统性差距。本次重构以 **ClassIsland v2.1 的灵动岛（MainWindow / MainWindowLine / Components / Notification / TopmostEffect）为行为与视觉基准**，把 ClassHelper 的岛升级为同等精细度，同时保留 ClassHelper 的工程结构、数据来源与业务规则。

你必须记住三条基准优先级：

1. **ClassHelper 业务语义优先**：消息去重、优先级、上课暂存、紧急展开、叫人胶囊、已读回执、班级设备、课件传输优先等规则不得改变；
2. **ClassIsland 视觉与动画优先**：像素、字号、圆角、间距、颜色、动画时长与曲线以本提示词第 6、7、10 部分为准；
3. **ClassHelper 既有工程与配置不得推翻**：pnpm monorepo、独立岛渲染进程、`config.json.islandLayout`、`IslandComponentNode`/`IslandLayoutScheme` 数据模型、编辑器入口、无头验证纪律继续有效。

### 1.2 目标状态（重构完成后用户看到什么）

1. **fixed（经典）默认变成 ClassIsland 风格的课表信息行**：屏幕顶部/底部悬浮一条或多条信息行（默认 1 行：日期 + 课程表；行高 40、圆角 8、背景不透明度 0.5、字号 14/16/18/20、底部 3px 进度条），显示当天课程、当前课程、剩余分钟/倒计时；不再是 268×44 的小胶囊。
2. **消息到来时的表现**：普通通知/作业在岛内展开为 ClassIsland 风格的气泡（行内遮罩 + 内容两阶段：遮罩扫入 360ms + 错峰 120ms，文字延迟 260ms 淡入并 1.1→1.0 缩放 750ms），紧急消息立即展开；保留 ClassHelper 的上课暂存、普通叫人可点胶囊、紧急立即展开等规则。
3. **强提醒**：可配置的 ClassIsland 强提醒（Topmost 特效）在岛所在显示器全屏/大区域显示，超时自动关闭，不抢焦点、不阻塞操作；默认仅对"强调提醒"启用。
4. **custom（自定义常驻）**：保留现有方案/行/组件/编辑器，但渲染与交互升级为 ClassIsland 规格：行高 40、行间距 5、组件外边距 6/6、行设置抽屉、选中框 1.5px 虚线、拖拽把手、隐藏规则、行/组件外观覆盖、进入编辑模式（实际内容预览）、退出保存。
5. **winisland 兼容风格（只作用于 fixed）**：`appearance.family = 'winisland'` 时保留现有经典 fixed 观感（连续圆角、胶囊 268×44、纯黑/毛玻璃/主题色渐变、弹簧形变）；`custom` 不随 family 变化，始终使用 ClassIsland 规格（其编辑器/行/组件结构保持不变，只按 07 细化像素）。默认新装 `classisland`，老用户升级迁移为 `winisland`。
6. **设置与编辑器**：灵动岛设置页新增风格选择、ClassIsland 外观参数（字号阶梯、行间距、进度条、强提醒开关、主题 Fluent/Classic 选择）；自定义方案编辑器增加"编辑模式"与行设置抽屉；所有改动即时保存、失败可重试、退出不丢改动。
7. **数据与兼容**：旧 `config.json.islandLayout` 无损迁移；用户的 schemes/rows/nodes、外观值、编辑器习惯全部保留；迁移失败可回滚；旧版本客户端读到新配置时按"忽略未知字段 + 默认值"处理（或明确拒绝并提示升级）。

### 1.3 范围（In / Out）

**必须做（In）**：
- 岛窗口与渲染层：`island.html`、`LayoutIslandApp.vue`、`IslandApp.vue`、`CustomIslandRuntime.vue`、`ComponentNode.vue`、`ClassicNotifications.vue`、`LessonReminderContent.vue`、`CoursewareTransfer.vue`、`spring.ts`、`squircle.ts`、各 CSS。
- 主进程岛控制器：`src/main/island.ts`（窗口几何、命中、触摸、消息队列、课程提醒、天气、课件、编辑预览、保存配置、预览/应用）。
- preload 与 bridge：`src/preload/island.ts`、`src/renderer/island/bridge.ts`、`src/types/desktop.d.ts` 的岛契约。
- 共享层：`packages/shared/src/{island-layout,constants,motion}.ts` 的 schema、常量、归一化、迁移。
- 设置/编辑器：`IslandSettingsView.vue`、`IslandEditorView.vue`、`IslandComponentSettings.vue`、`IslandEditorNode.vue`、`island-editor.css`，以及 `router` 中岛编辑路由的入口。
- 配置：`config.json.islandLayout` 版本化迁移、原子写、回滚。
- 文档与无头测试。

**不做（Out，最多在交付说明中标注为后续）**：
- 不重写服务端/数据库/Web 管理端；不改变服务端接口字段与权限。
- 不引入 ClassIsland 的 Profile/TimeLayout 本地档案、插件系统、自动化系统、管理端、主题市场、Excel 导入、更新器。
- 不引入新框架/新 UI 库/新状态库；不更换构建管线。
- 不把岛改成多窗口；仍只有一个原生岛窗口 + 一个可选的强提醒特效窗口。
- 不改动主窗口（设置/作业/成绩/通知中心）布局，除编辑器入口与预览联动外。

### 1.4 模块级 Keep / Change / Add / Remove

| 模块 | 处理 | 说明 |
|---|---|---|
| 岛窗口创建/几何/命中/触摸/失焦宽限 | **Keep + Change** | 保留固定包围盒与透明窗口护栏；按 ClassIsland 行高/宽度/停靠语义重算几何；fixed 从胶囊尺寸改为信息行尺寸；custom 保持测量适配但按 ClassIsland 行模型约束 |
| `IslandApp.vue`（经典） | **Change（大改）** | 从"胶囊+详情卡"重构为"ClassIsland 信息行 + 通知气泡 + 进度条"；保留消息状态机与紧急/上课规则 |
| `CustomIslandRuntime.vue`（自定义） | **Change** | 保留测量/缩放/行渲染；行高、行距、组件边距、背景、圆角、进度条、选中框、拖拽按 ClassIsland 规格；编辑模式重做 |
| `ComponentNode.vue` / 组件库 | **Change + Add** | 11 类组件的默认样式/尺寸/字号/空数据按 ClassIsland 规格；新增进度条/倒计时徽标/课程时间点展开等子结构 |
| `ClassicNotifications.vue` | **Change** | 气泡两阶段（斜切遮罩/文字/缩放）与 ClassIsland 参数对齐；保留 ClassHelper 消息类型/排序/回执 |
| `LessonReminderContent.vue` | **Change** | 课程提醒条/倒计时徽标按 ClassIsland 布局与字号；下课前蓝色圆形秒数徽标（含 `-1`） |
| `CoursewareTransfer.vue` | **Keep** | 覆盖优先逻辑不变，只按新视觉加外壳/动画 |
| `spring.ts` / `squircle.ts` | **Keep（条件使用）** | ClassIsland 风格默认用 CSS transition + 标准圆角；winisland 风格继续用弹簧/连续圆角；不得把弹簧用于 ClassIsland 规格动画 |
| `main/island.ts` | **Change** | 窗口几何、状态模式、消息队列、课程提醒、天气、编辑预览按新交互调整；新增强提醒窗口控制、编辑模式、迁移调用；保留单实例/恢复/限流 |
| `shared/island-layout.ts` | **Change（v2）** | 新增 `version`、风格/主题/强提醒/进度条等字段；新增 ClassIsland 组件设置字段；normalize/migrate；旧配置无损升级 |
| 设置页/编辑器 | **Change + Add** | 新增风格切换、ClassIsland 外观项、编辑模式、行设置抽屉；保留方案/行/组件/导入导出 |
| 文档/测试 | **Change + Add** | 更新 docs；新增无头测试；`--visual` 保持可选 |

### 1.5 关键设计裁决（必须逐条执行）

1. **固定形态风格双轨、默认 ClassIsland**：`appearance.family: 'classisland' | 'winisland'` 只决定 **fixed** 的形态（信息行 vs 旧胶囊）；`custom` 始终 ClassIsland 规格。新装默认 `classisland`；旧用户升级保持 `winisland`（避免 fixed 观感突变）；设置页在 fixed 下提供切换并即时预览。
2. **fixed 重定义**：fixed 不再是"小胶囊消息岛"，而是 ClassIsland 风格信息行（默认 1 行，日期+课程表；消息时行内气泡）。原胶囊形态只在 `winisland` 风格下保留。
3. **custom 保留数据模型**：schemes/rows/nodes/expandedRows 不变，只扩展字段与渲染；已有用户方案无需重做即可获得新视觉。
4. **数据不迁移**：继续消费 ClassHelper 的课表/通知/作业/叫人/课件数据；ClassIsland 的 Lesson/Notification 语义只作为行为参考。
5. **强提醒是新增窗口而非替换岛**：ClassIsland 的 TopmostEffect 以独立透明窗口实现（无边框、置顶、不抢焦点、超时关闭）；只在消息的"强调提醒"开关开启时出现；编辑/预览模式不创建。
6. **配置版本化**：`islandLayout.version`（整数，当前 2）；`normalizeIslandLayouts()` 先迁移再归一化；迁移前备份 `config.json`，失败回滚并提示。
7. **验证无头**：所有自动验证必须后台执行；`--visual` 才允许可见岛、动画、截图验收；不得为验收创建真实班级/发送测试通知/重置密码。

### 1.6 成功标准（重构完成的定义）

- **视觉**：第 6/7 部分的像素值在 1920×1080@100%、1080p@125%/150%、深/浅色、ClassIsland Fluent/Classic 两套主题、ClassHelper winisland 风格下逐项对齐（容差：颜色 ±2/255，尺寸/位置 ±1px，透明度 ±1%）。
- **动画**：第 10 部分动画表逐项实现（时长误差 ≤ 16ms、曲线一致）；60fps；减少动画/失焦/隐藏页暂停生效。
- **功能**：消息/课程提醒/天气/课件/编辑器/设置/迁移全部可用；无回归（见第 12 部分）。
- **兼容**：旧配置升级成功率 100%（本仓库 fixtures 内）；回滚可用；旧字段 `residentEnabled` 继续兼容。
- **性能**：岛渲染进程启动 ≤ 500ms；空闲 CPU ≤ 1%；主+岛进程内存 ≤ 250MB；消息风暴 20 条/分钟无卡顿/丢失/重复。
- **纪律**：`verify:desktop` 默认不创建可见岛/托盘；无 GUI 打扰。

### 1.7 主要风险与对策

| 风险 | 对策 |
|---|---|
| 透明窗口改尺寸导致闪烁 | 固定包围盒 + 窗内形变（保留现有策略）；`setBounds` 仅模式/设置/显示器变化且节流 ≥100ms |
| fixed 重定义导致老用户不习惯 | `winisland` 风格保留 + 升级默认沿用旧风格 + 设置页可切换 |
| 消息状态机重构引入竞态 | 先写状态机单测（去重/优先级/暂存/紧急/回执），再改 UI；所有状态变更走单一入口 |
| 编辑模式拖拽与触摸冲突 | 编辑模式暂停指针避让/消息展开；触摸与鼠标分别走命中/宽限路径 |
| 配置迁移破坏用户方案 | 迁移前备份；schema 校验 + 归一化；失败回滚；fixtures 覆盖 fixed/custom/旧版字段 |
| 多显示器/DPI 偏差 | 全部使用 DIP；屏幕变化事件驱动重算；截图验收用 devicePixelRatio 换算 |
| 动画掉帧 | 只用 transform/opacity；弹簧仅限 winisland；长任务移出主线程；帧率监控 |

### 1.8 阅读顺序提示

- 先读第 2 部分（ClassHelper 现状）与第 3 部分（ClassIsland 行为基准），确认"保留什么、改什么"。
- 第 4/5 部分是施工图与数据迁移，必须在写代码前读完。
- 第 6/7/10 部分是像素与动画的硬规格，逐条落实。
- 第 8/9 部分处理消息、课程、强提醒与编辑器。
- 第 11/12/13 部分是兼容、验收与里程碑，按顺序执行。