classhelper-island-refactor-prompt/analysis/refactor-current-state.md

# ClassHelper 灵动岛重构调研笔记（Part 02/04/05 支撑）

> 本文件是队友 `stack` 在 Round 2 的静态分析记录，供 Lead 汇总审校时核对"读了什么、依据哪一行、还剩什么没定"。
> 全程只用 read/grep/glob 与纯文本统计命令；**未构建、未安装、未运行 Electron、未截图、未冒烟/verify**；未修改 `repos/` 下任何文件。

## 1. 已读文件清单（Round 2）

### 1.1 ClassHelper（`repos/ClassHelper-master`，全部为只读）

| 文件 | 行数 | 本轮用途 |
|---|---|---|
| `docs/app/island.md` | 79 | 产品口径：fixed/custom、消息展示矩阵、编辑器、课程与课件、验证纪律 |
| `docs/dev/implementation.md` | 54 | 实现契约：方案存 `config.json.islandLayout`、单窗口、编辑页子路由 |
| `docs/dev/winisland-design-tokens.md` | 59 | 几何/度量/动画入口（已在上一轮读过，本轮复核） |
| `docs/dev/testing.md` | 79 | 验证命令与"默认无头、--visual 才做桌面验收"纪律 |
| `packages/shared/src/types.ts`（1050-1230 等片段） | 1874 总 | `IslandMode/IslandNotificationKind/IslandLessonReminder/IslandNotification/IslandAppearance/IslandState`、`ScheduleDto`、`WeekParity` |
| `packages/shared/src/island-layout.ts` | 404 | 组件枚举、`CLASSISLAND_ISLAND_METRICS`、方案/行/节点 schema、默认值、`normalizeIslandLayouts` |
| `packages/shared/src/constants.ts`（多段） | 680 总 | `DEFAULT_ISLAND_APPEARANCE`、范围、停靠、风格、`ISLAND_SIZE_DELTA`、`SHADOW_PAD`、`ISLAND_TYPE_SCALE`、`ISLAND_LIST_METRICS`、`PRIORITY_RANK/LABELS`、`CLIENT_UPDATE_IDLE_MS` |
| `packages/shared/src/class-plan.ts`（1-100） | 119 | `TIME_POINT_TYPES`、`IslandTimePointDto`、`ActiveClassPlanWeekDto` |
| `packages/shared/src/courseware.ts`（grep） | — | `COURSEWARE_ISLAND_SIZE={424,132}` |
| `src/core?: packages/desktop-client/src/island/main.ts` | 30 | 岛渲染入口、二次注入动效令牌 |
| `src/island/LayoutIslandApp.vue` | 76 | 布局选择/课件覆盖/订阅初始化 |
| `src/island/IslandApp.vue` | 683 | 经典岛全部逻辑（弹簧、圆角、胶囊、展开、命中、停靠、内容淡入） |
| `src/island/CustomIslandRuntime.vue` | 528 | 自定义常驻：测量/三页淡入/铃铛/行渲染/命中 |
| `src/island/ComponentNode.vue` | 456 | 14 类组件渲染、课程表折叠、进度/徽标、编辑手柄、样式 |
| `src/island/IslandEditorNode.vue` | 124 | 编辑器标签节点 + 拖拽落点样式（属 `renderer/components`） |
| `src/island/ClassicNotifications.vue` | 234 | 单条详情卡/多条列表卡/按钮行 |
| `src/island/LessonReminderContent.vue` | 318 | 课程提醒条、5 区斜切遮罩、进度条、徽标 |
| `src/island/CoursewareTransfer.vue` | 132 | 课件传输覆盖卡（尺寸/样式/进度） |
| `src/island/WeatherBrief.vue` | 91 | 天气简报组件与码表映射 |
| `src/island/spring.ts` / `squircle.ts` | 115 / 81 | 弹簧参数、连续圆角路径 |
| `src/island/classic-island.css` | 757 | 经典岛根变量、形状/投影、胶囊/展开/列表/按钮/状态色 |
| `src/island/custom-island.css` / `custom-runtime.css` / `lesson-ending.css` | 205 / 255 / 16 | 自定义组件样式、常驻三页样式、秒数徽标 |
| `src/main/island.ts` | 2445 | 主进程岛控制器全文（分区间阅读 + 末段 IPC/尺寸函数） |
| `src/main/lesson-reminder.ts` | 110 | 五类课程提醒计算 |
| `src/main/island-weather.ts` | 73 | Open-Meteo 抓取/缓存/退避 |
| `src/main/index.ts`（岛相关） | 347 总 | 启动装配、岛初始化、打开应用/编辑器/已读回调、退出清理 |
| `src/main/tray.ts`（岛相关） | 78 | 托盘"编辑灵动岛布局"入口 |
| `src/main/courseware.ts`（grep） | — | `island.setCoursewareTransfer(value)` |
| `src/preload/island.ts` | 123 | 岛窗口 contextBridge 白名单 |
| `src/preload/index.ts` | 101 | 主窗口桥（含 island push/class state/mark-read 订阅） |
| `src/renderer/island/bridge.ts` | 473 | 课表/上课状态/通知/作业/叫人/补弹/已读/生命周期 |
| `src/renderer/views/settings/IslandSettingsView.vue` | 512 | 设置页脚本 + 模板结构（family 入口需新增） |
| `src/renderer/views/settings/IslandEditorView.vue`（多段） | 861 | 编辑器：保存队列/上限/方案/拖拽/应用/加载 |
| `src/renderer/components/IslandComponentSettings.vue` | 307 | 内容/外观/高级三页字段 |
| `src/renderer/components/IslandEditorNode.vue` | 124 | 编辑器节点 chip/容器/落点 |
| `src/renderer/styles/island-editor.css`（选择器） | 417 | 编辑器布局/预览画布/组件库/检查器样式 |
| `src/renderer/styles/index.css`（grep 关键字） | 892 总 | 与岛相关的全局 token（未逐行引用） |
| `src/types/desktop.d.ts` | 294 | 桥接契约与配置形状（上一轮已读，本轮复核 island 部分） |
| `src/main/config.ts` | 555 | `islandLayout/island` 归一化、合并写、退出 flush（迁移接入点） |
| `src/renderer/App.vue` / `layouts/ClientLayout.vue`（岛相关） | — | 桥接生命周期、编辑页路由入口 |
| `AGENTS.md`（自动注入） | — | §4 灵动岛硬约束、验证纪律 |

### 1.2 ClassIsland（本轮仅少量回查，复用上一轮 parts）

- 上一轮产出的 `parts/03,04,05,07,10,11,14` 与 `analysis/40-baseline.md`（Lead 已整理），本轮引用其行高 40/行距 5/圆角 8/字号 14/16/18/20/进度条 3px/斜切遮罩权重等规格。
- 直接回查：`repos/ClassIsland/ClassIsland.Core/Models/Components/MainWindowLineSettings.cs`（行隐藏规则语义）、`ClassIsland.Shared/Models/Profile/TimeLayoutItem.cs:119-138`（TimeType 0-3）、`ClassIsland.Core/Models/Notification/NotificationRequest.cs:14-20`（Mask/Overlay 5s 默认）。

### 1.3 团队上下文

- `analysis/50-refactor-brief.md`（Round 2 总简报，含 8 条裁决与 §2.3 的 family/fixed 补充口径）
- 共享任务 `task-6`（已认领/完成）
- 上一轮本人产出：`parts/02-tech-stack.md`、`parts/12-plugins-ipc.md`、`parts/13-data-storage.md`、`analysis/classhelper-stack.md`（仅作技术栈与工程约定参考）

## 2. 关键行号表（本轮引用最频繁，供 Lead 复核）

| 主题 | 文件:行 | 事实 |
|---|---|---|
| 岛窗口创建 | `src/main/island.ts:480-512` | 透明/无边框/置顶/不占任务栏/独立 preload/sandbox |
| 窗口导航白名单 | `src/main/island.ts:32-50,516-522` | 生产按精确 file URL、拒绝新开窗口 |
| 默认鼠标穿透 | `src/main/island.ts:527` | `setIgnoreMouseEvents(true,{forward:true})` |
| 固定包围盒 | `src/main/island.ts:1514-1648` | `windowBox/windowBounds`，触摸贴合、自定义夹取 |
| 尺寸基线/增量 | `src/main/island.ts:72-112`、`packages/shared/src/constants.ts:344-351` | 胶囊 216×34；展开/紧急/叫人增量 |
| 收回动画 | `src/main/island.ts:1106-1164` | `CLOSE_ANIMATION_MS=360`，先切胶囊再淡出 |
| 超时表 | `src/main/island.ts:121-132` | pill 15s/展开 20s/紧急 45s/叫人 90s 等 |
| 消息分流 | `src/main/island.ts:794-867` | 紧急立即、上课暂存、普通叫人可点、预览展开 |
| 上课态迁移/课后补弹 | `src/main/island.ts:870-927` | 进入上课隐藏、下课恢复/补弹 |
| 动作状态机 | `src/main/island.ts:929-1077` | expand/collapse/expand-list/dismiss(-all)/mark-read(-all)/open-app |
| 双播合并 | `src/main/island.ts:704-724` | 同 id 合并，call/URGENT 不被降级 |
| 列表布局 | `src/main/island.ts:755-765`、`packages/shared/src/constants.ts:379-471` | 默认 3 行、hint more/app、safetyPad 6 |
| 命中轮询 | `src/main/island.ts:2049-2078` | 60ms 读光标，先换屏再命中 |
| 命中开关 | `src/main/island.ts:1795-1822` | 只由主进程关闭；触摸/编辑/自定义强制 true |
| 岛体矩形 | `src/main/island.ts:1825-1836,1973-1997` | 渲染上报 50ms 限流；兜底 expectedHitRect |
| 失焦宽限 | `src/main/island.ts:557-578,2287-2297` | 指针在岛上不收起；鼠标 500ms/触摸 1200ms |
| 触摸模式 | `src/main/island.ts:245-316,1891-1902` | 贴合岛体+始终接收输入；setShape 仅 win32 |
| 窗口自愈 | `src/main/island.ts:2106-2152` | 心跳 20s 超时、10 分钟最多 3 次 |
| 外观归一化 | `src/main/island.ts:2225-2264` | 夹取+NaN fallback；范围与 shared 一致 |
| IPC 注册 | `src/main/island.ts:2338-2438` | 全部 `island:*` handler 与发送方校验 |
| 渲染桥 | `src/preload/island.ts:14-121` | `window.island` 白名单 |
| 数据桥 | `src/renderer/island/bridge.ts:148-172,416-473` | 每秒复算上课态、课表刷新、生命周期 |
| 经典渲染 | `src/island/IslandApp.vue:188-212,266-332,346-383,420-516` | 目标尺寸/圆角、弹簧帧循环、透明度、命中上报 |
| 自定义渲染 | `src/island/CustomIslandRuntime.vue:52-124,238-323` | 测量/适配/三页淡入/命中 |
| 组件渲染 | `src/island/ComponentNode.vue:29-210,212-293,294-454` | 折叠规则/条件渲染/组件样式 |
| 消息面板 | `src/island/ClassicNotifications.vue:104-233` | 列表/详情/按钮语义 |
| 课程提醒条 | `src/island/LessonReminderContent.vue:59-123,195-317` | 5 区遮罩 360ms/错峰、文字 260/250/750ms |
| 课程提醒算法 | `src/main/lesson-reminder.ts:14-110` | 五类提醒窗口与 mask/ends 计算 |
| 天气 | `src/main/island-weather.ts:1-73` | Open-Meteo、8s、64KB、15min 缓存、退避 |
| 课件覆盖 | `src/main/island.ts:661-676,1420-1429`、`CoursewareTransfer.vue:12-65` | 最高优先级覆盖；424×132 |
| 配置读写 | `src/main/config.ts:26-84,198-233,235-346` | 默认值/归一化/合并写/flush |
| 布局 schema | `packages/shared/src/island-layout.ts:3-158,256-403` | 组件枚举/方案/行/节点/归一化上限 |
| 度量常量 | `packages/shared/src/island-layout.ts:19-36` | ClassIsland：40/12/8/0.5/14-20/5/0.05 |
| 消息常量 | `packages/shared/src/constants.ts:183-209,344-402` | 优先级、尺寸增量、排版系数、列表度量 |
| 设置页 | `src/renderer/views/settings/IslandSettingsView.vue:26-160` | 外观/布局/预览逻辑 |
| 编辑器 | `src/renderer/views/settings/IslandEditorView.vue:81-105,290-337,338-540` | 保存队列/应用/拖拽/上限 |
| 组件设置 | `src/renderer/components/IslandComponentSettings.vue:26-307` | 内容/外观/高级字段与范围 |

## 3. 与 Lead 口径的对齐（family / fixed 重新定义）

Lead 补充口径已并入 04/05：

1. `appearance.family: 'classisland' | 'winisland'` 新增，**新装默认 classisland**；**老用户升级默认 winisland**。落点：04 §4.0 第 5-6 条、§4.2 表、§4.3.1/4.3.2/4.3.3/4.3.4；05 §5.2/§5.4。
2. `fixed` 重新定义：classisland 下 fixed = ClassIsland 风格信息行（默认 1 行 = 日期 + 课程表、行高 40、圆角 8、不透明度 0.5、3px 进度条、消息行内气泡）；原胶囊+详情卡只在 winisland 保留。落点：04 §4.3.2/4.3.3/4.3.4、05 §5.3 `FixedSchemeV2`。
3. 文件级改造已覆盖 `IslandApp.vue` 的大改：迁为 `family/winisland/ClassicIsland.vue`（winisland 行为不变），新增 `family/classisland/FixedInfoRow.vue` + `InlineMessageBubble.vue`，`LayoutIslandApp.vue` 四象限分发；`ClassicNotifications.vue` → `shell/MessagePanel.vue`（detail/list/inline 三形态），`LessonReminderContent.vue` → `shell/LessonBar.vue`。
4. 老 `style(black/glass/tinted)` 处理为兼容字段：新 canonical 字段 `appearance.winislandStyle`，读入优先新字段、回退旧字段，写出保留旧字段一个版本周期（05 §5.2/§5.10），避免旧配置文件解析断裂。

## 4. 未决项（需 Lead 或对应 part 拍板）

1. **fixed 信息行的默认行数与内容**：我按"1 行 = 日期 + 课程表"写入 05；03/07 若无异议需保持一致。是否允许默认再加"当前课程进度/倒计时"由 07 定。
2. **消息行内气泡的交互细节**：行内气泡点击后是"展开行内详情"还是"打开应用通知中心"，以及多条气泡叠放/横向滚动规则，属 07/08 范围；04 只规定"业务状态机不变，只换表现"。
3. **classisland 的 Fluent/Classic 主题映射**：04 用 `appearance.theme: 'fluent'|'classic'` 占位；具体颜色/圆角/阴影 token 归 06/03，需确认是否与 ClassIsland XAML 资源字典逐值对应。
4. **行设置抽屉字段清单**：04/05 定义了行级 appearance/hideRules/progress 的最小集；抽屉的完整分组与控件归 09，需与 05 schema 对齐后再定稿。
5. **`style` 字段的移除时间**：建议 v3 移除；若 Lead 要求长期保留则改为永久兼容字段。
6. **smoke 断言改造归属**：现状大量断言依赖旧 DOM/几何（如"固定包围盒全程不变"）；本轮未改 smoke，改造清单只列"需按 family 分套"，具体断言列表需 Lead 安排给验收负责人或在 11 部分细化。
7. **自定义方案在 winisland family 下的视觉**：04 §4.3.1 规定 custom 共用一套运行时、由 family 切样式变量；若希望 winisland 下有独立 custom 外观，需要再拆一套 CSS（当前判断为不必要）。
8. **classisland 信息行与"课程提醒"的叠加方式**：我规定提醒条作为行覆盖层出现、不替换常态行（02 §2.8 现状语义）；07/08 若希望"提醒整行替换"需同步 05 的 fixed metrics。
9. **天气组件是否保留 Open-Meteo**：本轮只做岛重构，天气继续用现状实现（02 §2.9）；ClassIsland 天气服务仅作语义参考，不引入其服务端数据模型。
10. **`schemaVersion` 与 `islandLayout.version` 的关系**：我定义为文件级 + 子结构级双版本；若 Lead 希望只保留一个版本号，需同步修改 05 §5.1 与 04 §4.3.12。
11. **编辑器 855 行拆分节奏**：04 要求先抽 composables 再改逻辑；若本轮排期紧，允许先抽 `useIslandDraft`，其余留到 M7。
12. **family 切换是否自动写 `winislandStyle`**：当前迁移会写；新装用户从 classisland 切到 winisland 时是否保留 `black` 默认由 09 的 UI 决定。

## 5. 静态分析纪律声明

- 全程只读：`read` 读文本、`grep`/`glob` 找文件、`Select-String`/`Get-Content` 做文本统计与结构梳理、`[regex]` 统计中文字符数。
- 未执行 `pnpm install/dev/build`、`electron`、`npm`、`verify:*`、截图、冒烟或任何会弹窗/占用屏幕的命令。
- 未修改 `repos/ClassIsland` 与 `repos/ClassHelper-master` 下任何文件；只写入了 `parts-r/02-current-state.md`、`parts-r/04-file-plan.md`、`parts-r/05-data-migration.md`、`analysis/refactor-current-state.md`。
- 证据标注口径：`packages/...:行号`（ClassHelper）与 `repos/ClassIsland/...:行号`；无法从源码直接确认的工程设计一律标【推断】。