classhelper-island-refactor-prompt/parts-r/05-data-migration.md

5. 数据契约、schema v2 与配置迁移

5.0 总则（必须遵守）

1. 本章定义重构后的唯一数据契约。所有读写岛配置的代码（主进程 config.ts、岛渲染进程、编辑器、设置页、冒烟）必须只经过 packages/shared/src/island/schema.ts 的类型与 normalize.ts/migrate.ts 的函数，不得各自解析 JSON。
2. 旧配置必须无损升级：config.json 现有的 islandLayout（fixed/custom、schemes、nodes、expandedRows、residentEnabled、pointerFade、lessonReminders）与 island（appearance 全字段）一个都不许丢；升级失败必须可回滚。
3. 新增 appearance.family：取值 'classisland' | 'winisland'。新装默认 classisland；已存在配置的老用户升级默认 winisland。fixed 的语义随 family 分叉：classisland 下 fixed = ClassIsland 信息行（默认 1 行 = 日期 + 课程表，行高 40、圆角 8、不透明度 0.5、3px 进度条、消息行内气泡）；winisland 下 fixed = 原胶囊 + 详情卡。
4. islandLayout.version 必须写入；当前版本 2。版本号是唯一迁移判据，不得用"字段是否存在"猜版本（字段判断只作为迁移内部的兜底）。
5. 写入必须沿用现有 config.json 的"内存缓存 + 120ms 合并写 + 退出前 flush"语义（packages/desktop-client/src/main/config.ts:235-346），不得为迁移新增同步写盘路径；迁移本身例外（必须一次写成功并立即 flush）。
6. 客户端不得把 v2 数据写回给旧版本可见的字段后又不写版本号；写 v2 必须同时写 version:2，保证降级/回滚可判断。

5.1 落点与版本治理

数据	位置	版本字段	说明
运行期配置	<userData>/config.json	无独立文件版本	版本只在 islandLayout.version 上表达（唯一版本字段）
岛布局	config.json.islandLayout	version（新增，当前 2）	方案/行/节点/外观的结构版本；唯一迁移判据
岛外观	config.json.island	无独立版本	增加 family、theme、effectEnabled、effectScale、progressBar、fontSizes；style 保留为 surface 层
迁移前备份	<userData>/config.json.v1.bak	—	迁移前完整拷贝，只保留一份（覆盖式）
迁移标记	<userData>/config.island-migration.json	{from,to,at,appVersion}	仅诊断用，不参与版本判断、不是第二套版本字段

1. 只保留 islandLayout.version 一个落盘版本字段：不得新增 config.schemaVersion 或其它文件级版本号；迁移判定只看 islandLayout.version（缺失=v1）。
2. 迁移必须在 app.whenReady() 后、island.init() 之前完成一次；不得由渲染进程触发，也不得在岛窗口创建后再迁移（否则窗口会先按旧数据渲染一帧）。
3. 迁移成功后必须立即 flushConfigSync()；失败时不得写回半成品：保留原 config.json，删除 .tmp，应用以内存默认 v2 运行并在设置页显示"迁移失败，已保留原配置"。
4. 读到 islandLayout.version > 2 时应用必须只读（不写回），并在设置页提示"配置来自更高版本"。

5.2 appearance v2（config.json.island）

在现有 IslandAppearance 基础上只增不改，旧字段全部保留（packages/shared/src/types.ts:1145-1195）。新增/语义变化如下：

字段	类型	默认值（新装）	说明与依据
family	'classisland' | 'winisland'	'classisland'（老用户迁移为 'winisland'）	风格族字段的唯一落点；作用域只限 fixed（classisland=信息行；winisland=旧胶囊+详情）；custom 始终 ClassIsland 规格、不受影响
colorScheme	'light' | 'dark' | 'system'	'system'	岛配色模式：跟随应用主题（system，默认）/强制浅色/强制深色；只影响岛自身渲染，不改主窗口主题
theme	'fluent' | 'classic'	'fluent'	仅 family='classisland' 的 fixed 使用；对应 ClassIsland Fluent/Classic 两套主题；具体 token 由 06 定义
effectEnabled	boolean	true	强提醒特效总开关（对应 ClassIsland 的提醒特效 Topmost/Effect 是否启用）；关闭后只保留行内气泡/普通提醒
effectScale	1 | 0.75 | 0.5	1	强提醒特效渲染缩放（对应 ClassIsland NotificationEffectRenderingScale，默认 1.0）；只允许三档
progressBar	{height:number, show:boolean}	{height:3, show:true}	岛内进度条统一配置：高度默认 3px，总开关默认显示；语义见 5.3 行级进度条说明
fontSize	number	classisland=16（正文基准，派生 14/18/20 阶梯）；winisland=13（旧语义）	family='classisland' 时它是正文基准字号，fontSizes 由它派生；family='winisland' 保持旧语义；迁移时旧配置保留原值，新安装默认 16
fontSizes	{secondary:number, body:number, emphasized:number, large:number}	由 fontSize 派生：classisland 14/16/18/20；winisland ≈14/16/18/20（按 fontSize/13 比例）	ClassIsland 四档字号；显式配置优先于派生（见 5.4）
height / width	number	44 / 268	仅 family='winisland' 的胶囊尺寸；classisland 下不作为信息行尺寸
radius	number	20（winisland）/8（classisland 行为默认）	classisland 下作为行默认圆角；解析时取 family 对应默认
opacity	number	1	岛整体不透明度；classisland 下行背景不透明度另见行设置（默认 0.5）
winislandStyle	'black' | 'glass' | 'tinted'	'black'	winisland 调色板字段的 canonical 名：纯黑/半透明/主题色渐变；仅 family='winisland' 的 fixed 使用
style	'black' | 'glass' | 'tinted'	镜像 winislandStyle	兼容镜像字段（不删除）：旧配置读入时若没有 winislandStyle 则用它；写出时同时写 winislandStyle 与 style，保持旧版本可读；建议 v3 再评估废弃
position/alwaysOnTop/animations/speed/idleSliver/marginX/marginY/followCursorDisplay/accent	不变	不变	fixed（两种 family）与 custom 共用；classisland fixed 也用停靠与边距

1. 字段职责必须严格区分：family 只决定 fixed 用哪套渲染器（ClassIsland 信息行 / WinIsland 胶囊）；winislandStyle（兼容镜像 style）只决定 winisland 的调色板；theme 只决定 classisland fixed 的 Fluent/Classic；colorScheme 只决定浅色/深色/跟随。四者不得互相覆盖、不得合并。custom 不使用 family/theme/winislandStyle（始终 ClassIsland 规格），但仍读取 colorScheme 决定明暗。
2. family 归一化：只接受两个值，非法值回落 'classisland'（新装默认）；迁移函数负责把老用户写成 'winisland'（见 5.4）。
3. colorScheme 归一化：只接受 light/dark/system，非法回落 system；缺失补 system。
4. fontSize 归一化：8–96；classisland 下作为正文基准，fontSizes 缺失时由它派生（body=fontSize，secondary=round(fontSize*14/16)，emphasized=round(fontSize*18/16)，large=round(fontSize*20/16)）；winisland 下保持旧语义（fontSizes 缺失时按 fontSize/13 × 14/16/18/20 推导）。迁移时旧 fontSize 原值保留，不强行改成 16。
5. fontSizes 归一化：每项 8–96；显式值优先于派生；缺失项按第 4 条补齐。
6. theme 仅 classisland fixed 生效；非法值回落 'fluent'；winisland 下忽略但不删除该字段。
7. effectEnabled 必须为 boolean（缺省 true）；effectScale 必须夹取到 [1, 0.75, 0.5]（缺省 1，非法值取 1）；progressBar.height 夹取 1–8、progressBar.show 缺省 true；progressBar 缺失时整对象补默认。
8. winislandStyle 归一化：仅 black/glass/tinted 合法，非法回落 black；style 作为镜像字段同步写；读入优先 winislandStyle，回退 style。切换 family 时保留用户 winislandStyle 原值，不重置（UI 默认值提示归 09）。

5.3 islandLayout v2（config.json.islandLayout）

v2 顶层（IslandLayoutV2）：

字段	类型	默认值	说明
version	number	2	必须存在
layout	'fixed' | 'custom'	'fixed'	布局模式（沿用旧字段）
fixed	FixedSchemeV2	见下	classisland fixed 信息行配置；winisland 下忽略
schemes	IslandLayoutSchemeV2[]	1 个默认方案	自定义方案（沿用旧结构并扩展）
activeSchemeId	string	'default'	当前方案
residentEnabled	boolean	layout==='custom'	兼容字段；不得再作为独立开关
pointerFadeEnabled / pointerFadeReversed	boolean	true / false	鼠标避让淡化（沿用）
lessonReminders	LessonReminderSettings	沿用旧默认	准备/上课/课间/结束/课中进度开关与秒数
updatedAt	number	0	最近保存时间（仅诊断）

FixedSchemeV2（classisland fixed 的信息行）：

字段	类型	默认值	说明
rows	IslandRowV2[]	1 行 = 日期 + 课程表	信息行；默认只有一行
mainRowId	string	首行 id	主行（承载消息气泡/课程提醒）
rowHeight	number	40	ClassIsland 行高（32–64 夹取）
rowSpacing	number	5	行间距（0–150）
backgroundOpacity	number	0.5	行背景不透明度
cornerRadius	number	8	行圆角（0–20）
progressBarHeight	number	3	行内进度条高度（3px）
messageBubble	'inline' | 'card'	'inline'	fixed 下消息表现：inline=行内气泡，card=老式详情卡（仅回退用）
maxRows	number	3	信息行最多行数（自动换行/溢出策略由 07 定义）

IslandLayoutSchemeV2（在 v1 方案上扩展）：

字段	类型	默认值	变化
id/name/rows/expandedRows	沿用	沿用	结构不变；行内容升级为 IslandRowV2
scale	number	1	0.75–2.5（沿用于 CLASSISLAND_ISLAND_METRICS.scaleMin/Max）
color/foreground/opacity/radius/separated/spacing	沿用	沿用	radius 0–20；spacing 0–150
rowHeight	number	40	新增：行高 32–64
rowSpacing	number	5	新增：与 spacing 同步；spacing 保留兼容
theme	'fluent' | 'classic'	继承 appearance.theme	新增：方案级主题覆盖
fontSizes	{secondary,body,emphasized,large}	继承 appearance.fontSizes	新增：方案级字号覆盖
progressBarHeight	number	3	新增：行内进度条高度
unrecognizedNodes	object[]	[]	新增：未知 kind 的原始节点（不得丢弃，见 5.5 第 6 条）

IslandRowV2（行）：

字段	类型	默认值	说明
id/name/main/allowNotifications/gap/nodes	沿用	沿用	main 行唯一；gap 0–64
appearance	RowAppearance	见下	行级外观（新增）
hideRules	RowHideRules	全 false	行级隐藏规则（新增）
progress	RowProgress	见下	行级进度条（新增）

RowAppearance：backgroundEnabled=false、backgroundColor='#000000'、backgroundOpacity=0.5、foregroundColor='#ffffff'、cornerRadius=8、opacity=1、fontSizes（继承方案/外观）。

RowHideRules：inClass=false、noMessage=false、noClass=false、fullscreen=false；全部为 false 表示不隐藏。语义对应 ClassIsland 的行隐藏规则（repos/ClassIsland/ClassIsland.Core/Models/Components/MainWindowLineSettings.cs 的 HideOnRule/HidingRules）。

RowProgress：enabled=true、style='line'、height=3、color='accent'、showRemaining=true。

行内 3px 进度条的语义（数据来源不在本层实现）：进度条表示"当前显示内容的时间进度"——消息气泡显示时 = 该消息剩余显示时间；否则 = 当前课程进度。具体数据来源与取值规则由 07/08 定义，本 schema 只保证 progress（行级）与 appearance.progressBar（全局）提供 height/show 两个开关；行设置抽屉的完整字段由 09 定义，本章只登记字段名（appearance/hideRules/progress）并要求与 09 对齐，不得在 05 里发明抽屉字段。

IslandNodeV2（节点，在 v1 IslandComponentNode 上扩展，字段名不变）：

字段	变化
id/kind/appearance/advanced/children	沿用（appearance 四档字号默认改为继承行/方案）
settings.schedule.display	沿用 `'current'
settings.schedule.progressStyle	新增：`'bar'
settings.schedule.showProgress	沿用；默认 true
settings.schedule.showPeriod/count	沿用
settings.mode（仅 kind='rolling'）	新增：`'continuous'
advanced.hideRules	沿用 in-class/no-message/no-class；新增 fullscreen（与行级一致）
advanced.rowSpan	新增：仅容器组件使用，默认 1

默认方案（新装/重置）：layout:'fixed'、family:'classisland'、fixed.rows=[{main:true, allowNotifications:true, gap:12, nodes:[date, schedule]}]，schemes=[默认方案：main 行含 date/clock/schedule/notification]。数值依据：packages/shared/src/island-layout.ts:217-255（现有默认方案）+ CLASSISLAND_ISLAND_METRICS（:19-36）。注意：schemes 是 custom 布局数据，描述 ClassIsland 规格且不随 family 改变；fixed 配置只在 family='classisland' 时由 fixed 渲染器读取。

5.4 v1 → v2 迁移算法（必须逐步实现，可重入）

输入判定：

1. 读取 config.json（不存在 → 全新安装：直接构造 v2 默认，family='classisland'，不写迁移标记）。
2. 文件存在但 islandLayout.version 缺失：视为 v1（唯一版本判据；不得再引入 schemaVersion 作为第二套版本号）。
3. 老用户判定：islandLayout.version 缺失 或 文件里存在 islandLayout/island 任一字段 → 迁移时 family='winisland'（保持原外观，不惊吓用户）。
4. 全新安装判定：文件不存在、或既无 islandLayout 又无 island → family='classisland'。

步骤（必须按序、每步失败可中止）：

step 0 备份：把 config.json 原样复制到 config.json.v1.bak（存在则覆盖）；写 config.island-migration.json {from,to,at}（仅诊断，不是版本字段）
step 1 外观迁移（appearance）：
       - family := 'winisland'（老用户）| 'classisland'（新装）
       - colorScheme := 'system'（缺失补默认；已有值原样保留）
       - winislandStyle := 旧 style（缺省 'black'）；style := winislandStyle（兼容镜像）
       - theme := 'fluent'（新装默认；老用户也写 'fluent'，仅 classisland fixed 生效）
       - effectEnabled := true（缺失补默认）
       - effectScale := 1（缺失补默认；只允许 1/0.75/0.5）
       - progressBar := { height:3, show:true }（缺失补默认）
       - fontSize：迁移保留旧值（classisland 新装写 16；老用户写原值）
       - fontSizes := 由 fontSize 派生：
           老用户（winisland）：secondary=round(fontSize*14/13), body=round(fontSize*16/13),
                      emphasized=round(fontSize*18/13), large=round(fontSize*20/13)
           新装（classisland）：14/16/18/20（fontSize=16 为正文基准）
       - 所有旧字段原样保留（height/width/radius/opacity/accent/fontSize/style/...）
step 2 布局迁移（islandLayout）：
       - version := 2（唯一落盘版本字段）
       - layout := 旧 layout（缺省 'fixed'）
       - residentEnabled := (layout==='custom')（覆盖旧的独立值，保证一致）
       - pointerFadeEnabled/pointerFadeReversed/lessonReminders 原样保留
       - fixed := 若旧文件无 fixed 字段 → 生成 FixedSchemeV2 默认（1 行 date+schedule；progressBar 继承 appearance.progressBar）
       - schemes := 旧 schemes 逐个升级：
           rowHeight := 40；rowSpacing := 旧 spacing；theme := 'fluent'；
           fontSizes := 继承 appearance.fontSizes；progressBarHeight := appearance.progressBar.height；unrecognizedNodes := []
           每行补 appearance/hideRules/progress 默认；
           每节点补 settings.schedule.progressStyle='line'、advanced.rowSpan=1；
           若节点 kind='rolling' 补 settings.mode='continuous'（pause 保留旧 interval 语义）
       - 未知 kind 的原节点移入该方案的 unrecognizedNodes（保留原始 JSON，不参与渲染）
step 3 校验与夹取：调用 normalizeIslandLayoutV2 / normalizeAppearanceV2（见 5.5）；
       校验失败项收集成 warnings，不得中止；结构性错误（schemes 为空等）用默认方案兜底
step 4 写回：saveConfig({ islandLayout, island }) 后立即 flushConfigSync()（**不写 schemaVersion**）
step 5 读回校验：重新读取并 deep-equal 比较关键字段（islandLayout.version/family/layout/方案数/节点数）；
       不一致 → 从 config.json.v1.bak 恢复、删除迁移标记、报错并降级为"只读默认 v2"

1. 可重入/幂等：若 islandLayout.version===2，迁移函数必须直接返回原对象（不写盘、不改字段）；重复执行不得产生二次修改。
2. 老用户 fixed 不变：迁移后 family='winisland'，fixed 仍渲染原胶囊+详情卡（ClassicIsland.vue），因此老用户升级后视觉 0 变化；只有用户主动在设置页切到 classisland 或新装用户才看到信息行。
3. custom 老用户：custom 始终按 ClassIsland 规格渲染、不受 family 影响；迁移只升级数据（补行级默认、滚动 mode 等），不改 schema 结构。老 custom 用户升级后视觉会变为 ClassIsland 行规格（这是定稿行为），发布说明与设置页必须提示；fixed 用户（默认 winisland）不受影响。
4. 编辑器打开时必须先读迁移后的 v2；若 islandLayout.version 不匹配（例如用户用旧版应用改过文件），必须触发一次"再迁移"而不是把 v1 当 v2 解析。
5. 迁移必须记录 warning 列表到内存并在设置页"存储/诊断"可查看（哪几项被夹取、哪几个未知组件被保留）。

5.5 校验与夹取（normalizeIslandLayoutV2 / normalizeAppearanceV2）

必须在 shared 中实现，主进程保存前、编辑器加载后、IPC 存入前三处共用同一个函数。规则：

1. version：仅接受 2；缺失/非法按迁移处理，不得静默改成 2 后继续用旧结构。
2. layout：'fixed'|'custom'，非法回落 'fixed'。
3. family：'classisland'|'winisland'，非法回落 'classisland'。
4. 数量上限：行 ≤12/方案、节点 ≤200/全部方案、嵌套深度 ≤6、方案 ≤20；main 行唯一（多余取消）。
5. 数值夹取：rowHeight 32–64、rowSpacing 0–150、gap 0–64、radius 0–20、opacity 0–1、backgroundOpacity 0–1、fontSizes 8–96、scale 0.75–2.5、rowSpan 1–6、progressBarHeight 1–8；非法/NaN 回落默认值（禁止 Math.max(min, NaN) 这种写法，参考 src/main/island.ts:2225-2241 的 fallback 说明）。
6. 未知 kind：不得丢弃。把原始节点 JSON 放入 scheme.unrecognizedNodes（最多 200 条），渲染时忽略并显示"未知组件（已保留）"；这样用旧版应用打开再保存也不会丢数据。
7. 颜色：统一 #rrggbb 小写；非法回落默认；透明度字段独立，不把 #rrggbbaa 塞进颜色字段。
8. id：空/非字符串/重复 → 重新生成（node-<n>/row-<n>/scheme-<n>）；id 最长 100 字符。
9. 文本：settings.text ≤2000 字符、locationName/countdownTitle ≤64；超长截断并记 warning。
10. 经纬度：latitude -90..90、longitude -180..180，可空；空表示未配置（组件显示"请设置天气地点"）。
11. 未知字段：v2 对象里出现但类型未定义的字段必须原样保留在对象上（不删除），以便前向兼容。
12. lessonReminders：prepareSeconds 5–1800、endingSeconds 5–600（依据现有 packages/shared/src/island-layout.ts:390-398）。
13. winislandStyle / style：两者都只接受 black/glass/tinted，非法回落 black；读入优先 winislandStyle、回退 style，写出两者同步（兼容镜像）；不得因 family 迁移而删除 style；family 与调色板相互独立（family 决定 fixed 用哪套渲染，winislandStyle 决定 winisland 的调色板）。
14. theme：只接受 fluent/classic，非法回落 fluent；具体色板/圆角/阴影 token 由 06 定义，05 只登记字段与默认值。
15. colorScheme：只接受 light/dark/system，非法回落 system；system 时跟随应用 html.dark 状态决定岛明暗（映射逻辑由渲染层实现，数据层只存枚举）。
16. fontSize：8–96，缺省按 family 取（classisland=16 正文基准、winisland=13 旧基线）；fontSizes 缺失时按 5.2 第 4 条派生；显式 fontSizes 优先；迁移不得覆盖旧 fontSize。
17. effectEnabled：boolean，缺省 true；effectScale：只接受 1/0.75/0.5，缺省 1，非法取 1；progressBar：{height:1–8, show:boolean}，缺省 {3,true}。
18. 进度条高度优先级：行 progress.height > 方案 progressBarHeight > appearance.progressBar.height；任一缺失沿上一级回落，最终默认 3。progressBar.show=false 时所有行都不显示（行级 enabled=false 只关该行）。
19. 滚动组件：settings.mode 只接受 continuous/pause，缺省 continuous；pause 时停顿秒数复用 settings.interval（夹取 1–300）；continuous 时 speed 夹取 1–200（沿用现有范围）。
20. 渲染/样式命名空间只由 layout（fixed 的 family）决定，不写入数据：fixed + family='winisland' → winisland 命名空间；fixed + family='classisland' → classisland 命名空间；custom 始终 classisland 命名空间、不受 family 影响；normalize 不得改写样式类名/选择器相关字段。
21. IslandNotification.level、IslandLessonReminder.progress/leftSeconds、IslandState.family/pendingStaged/bubblePhase/bubbleDeadline 均为运行期派生字段，normalize 不处理、不落盘。

5.6 DTO 映射（ClassHelper 数据 → ClassIsland 语义）

fixed（classisland）行内气泡规则：同一时刻只显示 1 条 active 气泡；点击展开详情/操作；有多条未处理消息时不并列显示，而是折叠为「还有 N 条」，点击打开应用内通知中心（沿用 ClassHelper 现有通知中心路由）；消息队列、去重、上课暂存、已读回执规则完全不变（02 §2.5/§2.12）。

IslandState → ClassIsland 主界面状态：

ClassHelper 字段	ClassIsland 语义	渲染映射（classisland fixed）
mode:'hidden'	岛不可见（仅提醒特效时临时显示）	信息行隐藏/仅保留细缝
mode:'pill'	紧凑态	行内气泡/铃铛提示
mode:'expanded'	展开态	行展开 + 消息面板
active/queued	提醒队列（当前播放/待播）	行内气泡列表，按 PRIORITY_RANK 排序
inClass	TimeState=OnClass	行隐藏规则 inClass 生效、提醒遮罩可用
currentPeriodEnd	当前时间点结束	进度条/倒计时取值
reason	提醒来源（新消息/课后补发/紧急/叫人/收回中）	气泡入场动画与角标
listExpanded	列表是否展开更多	行内"展开更多"
lessonReminder	课级提醒（本地）	行覆盖层（遮罩/秒数徽标）
coursewareTransfer	课件提示（覆盖态）	最高优先级覆盖全部行

IslandNotification → ClassIsland 提醒语义：

ClassHelper 字段	ClassIsland 对应	规则
priority: LOW/NORMAL/HIGH/URGENT	提醒队列优先级（NotificationPriority）	URGENT=插队立即播放；HIGH/NORMAL/LOW 按排序入队
kind:'notification'	普通提醒（Mask+Overlay 两阶段）	两阶段时长取 5s/5s（repos/ClassIsland/...NotificationRequest.cs:17-20）
kind:'homework'	作业提醒（本地合成 id homework-<id>）	不进入已读回执；不可"标为已读"
kind:'call'	叫人（Call）	上课时保持可点、不自动展开；紧急叫人按 URGENT
title/content/teacherName/courseName/createdAt	提醒标题/正文/来源/时间	气泡第一行标题、第二行来源+时间
id	去重键	双链路（通知/叫人）合并时 id 相同即合并（见 02 §2.5 第 3 条）

ScheduleDto → ClassIsland 课表语义（仅映射，不落 Profile 文件）：

ClassHelper 字段	ClassIsland 概念	映射规则
id	ClassInfo/条目标识	仅内部使用
course.courseName	Subject.Name	直接展示；null 显示"—"
dayOfWeek（1–7）	TimeRule.WeekDay	1=周一…7=周日
startTime/endTime（HH:mm）	TimeLayoutItem.StartTime/EndTime	转 HH:mm:00；只用于显示与进度计算
weekStart/weekEnd	周次范围	用于"本周是否有课"
weekParity: ALL/ODD/EVEN	TimeRule.WeekCountDiv（0/1/2）+ WeekCountDivTotal=2	ALL→0；ODD→1；EVEN→2
location	附加信息	仅在气泡/详情展示，不参与时间点

IslandTimePointDto → TimeLayoutItem：

ClassHelper	ClassIsland	规则
timeType: LESSON/BREAK/DIVIDER/ACTION	TimeType: 0/1/2/3	一一对应（repos/ClassIsland/...TimeLayoutItem.cs:119-138）
name（课间名/时间点名）	BreakName/名称	课间空时显示"课间休息"
courseName	默认课程	null 等价 Guid.Empty（无课）
startTime/endTime	开始/结束	用于行内课程表折叠与进度
isHideDefault	IsHideDefault	折叠时隐藏、轮到时展开

1. 上述映射只用于渲染语义对齐，不得把 ScheduleDto 落盘成 ClassIsland 档案；数据仍以服务端解析结果为准（02 §2.12）。
2. CoursewareTransfer 映射为"最高优先级覆盖态"，不进入提醒队列、不参与已读；映射字段 name/category/teacherName/receivedBytes/totalBytes/progress/stage/error 直接使用（packages/shared/src/courseware.ts、src/island/CoursewareTransfer.vue:12-65）。

运行期状态扩展（IslandState，不落盘，必须随状态推送）：

字段	类型	默认值	语义
family	'classisland' | 'winisland'	当前 appearance.family	当前生效风格；渲染进程据此切换 CSS 命名空间
pendingStaged	number	0	上课期间被暂存、下课后待补弹的消息数（对应现有 queued 中因上课被压住的数量；queued.length 不变）
bubblePhase	'idle' | 'mask-in' | 'content-in' | 'out'	'idle'	行内气泡/提醒的两阶段播放阶段（固定 5s/5s 时长的可视化映射）
bubbleDeadline	number	0	当前气泡自动收起的时间戳（毫秒）；0 表示无

1. IslandState 的新字段只存在于运行期推送（island:state），不得写进 config.json、不得被编辑器保存；旧渲染进程缺字段时必须按默认值渲染（前向兼容）。
2. pendingStaged 必须由主进程根据现有上课暂存逻辑计算（02 §2.5 第 2 条），不得让渲染进程自行推断。

IslandNotification.level（展示层级，派生字段）：

priority	level	用途
URGENT	'emergency'	紧急气泡/强提醒特效可触发
HIGH	'high'	高亮气泡/角标
NORMAL	'normal'	普通气泡
LOW	'low'	弱化展示

level 由 priority 派生，不落库、不持久化；通知进入岛队列时在 main/island/messages.ts 统一计算，渲染层只读取。

IslandLessonReminder 扩展字段（运行期，不落盘）：

字段	类型	语义
progress	number (0–1)	当前提醒/课程进度：ending/in-class = (now-lessonStartsAt)/(lessonEndsAt-lessonStartsAt)；其余 = (endsAt-now)/(endsAt-startedAt)（与现有 LessonReminderContent.vue:36-50 计算一致）
leftSeconds	number	下课前剩余秒（ceil((lessonEndsAt-now)/1000)，clamp ≥0），供蓝色圆形秒数徽标与遮罩标题使用；现有 LessonReminderContent.vue:24-35 已有同义计算
kind	不变	仍为 prepare/on-class/break/ending/in-class

fixed（classisland）下的提醒叠加口径：prepare/on-class/break 以行内容接管呈现（临时替换课程表内容，动画由 08/10 定义）；ending 不接管行内容，只在课程名右侧显示蓝色圆形秒数徽标（leftSeconds 驱动）；custom 模式不接管，保持课程组件 + 秒数徽标。该口径只影响渲染，不改变 02 §2.8 的五类提醒计算与开关语义。

5.7 IPC payload 版本与兼容

1. IPC payload 可以携带 schemaVersion:2 仅用于运行时校验/调试，不得落盘、不得作为配置版本判据；配置版本只认 islandLayout.version。island:state/island:appearance/island:get-layout 三个高频 payload 建议带上该字段（旧字段保留，新增字段可选）。
2. 接收方规则：未知字段忽略、缺字段回落默认；不得因为缺 family 就拒绝渲染（老渲染进程遇到新主进程时应按 winisland 降级，反之按 classisland）。
3. island:save-layout 必须返回归一化后的 v2 结果（编辑器以返回值为准，避免"本地看着对、主进程夹取后不一致"）。
4. 主进程 getConfig() 返回给渲染进程的 islandLayout 必须是 v2；island 必须含 family 与新增外观字段（theme/effectEnabled/effectScale/progressBar）。
5. 旧通道名全部保留（见 04 §4.4）；新增通道必须同时在 shared/island/ipc.ts 与 preload 中登记，不得字符串散落。
6. 作业指纹相关 payload（见 04 §4.3.13）必须带 source（realtime/homework-local/replay/call）与 dedupeKey；主进程按 key 去重，渲染进程保留现有"本机刚录作业免上岛"快速路径。

5.8 编辑器预览与临时状态（不持久化）

1. 编辑器的内嵌预览、缩放、选中项、拖拽态属于临时状态，不得写入 config.json；只有"应用/保存"才写 v2。
2. "无消息展开内容（expandedRows）"与常态 rows 分开编辑、分开保存；activeSchemeId 只在切换方案时写。
3. 设置页"测试灵动岛"仍走 islandPush + context.preview=true（30 秒预览、失焦不收起，见 02 §2.15），预览消息 id 必须带前缀（如 appearance-test-）以便清理；预览不写历史、不改已读。
4. 编辑器打开时若检测到迁移 warning，必须在顶部显示"部分旧设置已按新格式调整（可查看详情）"，不得静默。

5.9 回滚与降级

1. 回滚入口：设置页"灵动岛 → 恢复升级前布局"必须存在；回滚步骤：先备份当前 config.json → 把 config.json.v1.bak 覆盖回去（该文件天然没有 islandLayout.version，即 v1）→ 提示重启 → 重启后旧版本行为恢复（family=winisland/fixed=胶囊）。
2. 迁移失败降级：应用不得崩溃；以内存默认 v2 启动（不写盘），岛显示默认信息行，设置页显示错误与"恢复备份"按钮。
3. 前向兼容：读到 islandLayout.version>2 时，应用只读该配置（不覆盖写），在设置页提示"配置由更高版本创建"；不存在其他版本字段可用于判断。
4. 文件损坏：config.json 非法 JSON 时沿用现有 .bak 回退逻辑（config.ts 现状：读取失败回落默认），回滚后仍必须按 islandLayout.version 缺失执行一次迁移判定；不得用损坏文件覆盖 .bak。
5. 旧版应用打开新文件：不可避免（旧版不认识 v2 字段），因此 v2 必须保持"未知字段保留"原则（5.5 第 11 条）并把关键新数据放在旧版会忽略而不是报错的位置；旧版保存后新字段可能丢失，需在文档提示用户不要跨版本反复切换。

5.10 版本变更记录与兼容矩阵

必须维护一张可追溯的变更表（代码里以常量数组或文档形式存在），用于判断"某个字段从哪版开始有、哪版废弃"：

变更	版本	兼容策略
islandLayout.version 新增（唯一落盘版本字段）	v2	缺失=1，按 5.4 迁移
appearance.family 新增	v2	缺失时：老配置迁移=winisland；新装=classisland
appearance.theme（fluent/classic）新增	v2	缺失=fluent；仅 classisland 生效；具体 token 由 06 定义
appearance.effectEnabled / effectScale 新增	v2	缺失 true/1；effectScale 只允许 1/0.75/0.5
appearance.progressBar {height,show} 新增	v2	缺失 {3,true}；高度优先级 行 > 方案 > 外观
appearance.fontSizes 新增	v2	缺失时按旧 fontSize 比例推导（5.4 step1）
fixed（信息行）新增	v2	缺失时生成默认 1 行（date+schedule）；仅 classisland fixed 使用
行级 appearance/hideRules/progress 新增	v2	缺失时补默认；字段名与 09 对齐；winisland fixed 下保留数据但忽略（custom 始终使用）
方案级 rowHeight/rowSpacing/theme/fontSizes/progressBarHeight 新增	v2	缺失时继承 appearance 默认
appearance.colorScheme 新增	v2	缺失=system；非法回落 system
appearance.fontSize 语义按 family 分叉	v2	classisland=正文基准（新装 16，派生 14/18/20）；winisland=旧语义（13）；迁移保留旧值
appearance.winislandStyle 新增，style 转兼容镜像	v2	读优先 winislandStyle、回退 style；写两者同步；style 不删除；切换 family 保留原值
滚动组件 settings.mode 新增	v2	缺失=continuous；非法回落 continuous；pause 复用 settings.interval
residentEnabled 转纯兼容	v2	读出后与 layout==='custom' 对齐；不再作为独立开关
family 作用域	v2	只影响 fixed；custom 始终 ClassIsland 规格、不受 family 影响
旧 style 字段	保留镜像	本轮不删除；与 family/winislandStyle 独立；建议 v3 再评估废弃
迁移标记文件 config.island-migration.json	2	仅诊断用途；不是版本字段、不参与运行逻辑
回滚文件 config.json.v1.bak	2	迁移前覆盖写；回滚后仍保留，供二次回滚

兼容矩阵（读写方向必须明确）：

1. 新读旧（v2 代码读 v1 文件）：允许，走 5.4 迁移；迁移后内存中只存在 v2。
2. 新读新：允许，走 normalize；islandLayout.version 更高时只读。
3. 旧读新（旧代码读 v2 文件）：旧代码会忽略未知字段继续运行（因为 v2 把新字段放在其不认识的键上），但旧代码保存后会丢新字段；因此必须在文档与发布说明中写明"不要用旧版应用反复编辑新配置"。
4. 新写旧：禁止。v2 代码写盘必须带 islandLayout.version:2，不得输出 v1 结构，也不得写任何文件级版本号。
5. 迁移与编辑器并发：编辑器打开时若检测到 config.json 被迁移，必须重新加载（比较 updatedAt/mtime 或读取返回值），不得用旧草稿覆盖迁移结果；保存前再次 getConfig 核对 islandLayout.version。

兼容性红线（不得违反）：

• 不得删除任何仍被旧配置使用的字段名（如 style、residentEnabled、spacing、expandedRows、pointerFadeEnabled）。
• 不得把对象结构从"方案数组"改成"对象字典"或反之（旧编辑器/旧冒烟会解析失败）。
• 不得改变 ISLAND_LIST_METRICS 与 ISLAND_SIZE_DELTA 的语义（可以新增 classisland 专用 metrics，但旧常量必须继续导出且数值不变），因为大量冒烟断言按旧值计算（packages/shared/src/constants.ts:344-351,379-402）。
• 不得让 v2 的 rows 与 v1 的 rows 在同一键上结构不兼容：v2 行只增加字段，不重命名已有字段。

5.11 验收标准（第 5 部分）

1. 新装启动后 config.json 不含任何 schemaVersion；含 island.family:'classisland'、island.colorScheme:'system'、island.fontSize:16、island.theme:'fluent'、island.effectEnabled:true、island.effectScale:1、island.progressBar:{height:3,show:true}、islandLayout.version:2、fixed.rows 默认 1 行（日期+课程表）；layout:'fixed'，界面呈现 ClassIsland 信息行。
2. 用一份旧 v1 配置（fixed、custom 各一份，含 schemes/nodes/appearance/residentEnabled）启动：迁移成功、无字段丢失、family:'winisland'、旧胶囊外观不变、fontSize 保留原值、style/winislandStyle 一致；config.json.v1.bak 存在。
3. 迁移后再次启动：不重复迁移、不重复写盘（可用文件 mtime/内容哈希断言幂等）。
4. 迁移失败模拟（把 config.json 改坏/只读）时：原文件不被破坏、应用以默认 v2 启动、设置页显示错误与恢复入口。
5. "恢复升级前布局"可把 v1 备份恢复回来并重启生效；恢复前自动再备份当前配置。
6. normalizeIslandLayoutV2 对行数>12、节点>200、深度>6、方案>20、非法颜色/数值/kind 全部夹取或保留到 unrecognizedNodes；不崩溃、不丢未知组件。
7. 老用户切到 classisland 后 fixed 变信息行、切回 winisland 恢复胶囊；family 切换时 style/winislandStyle 与 fontSize 保持用户原值不变；custom 始终 ClassIsland 规格、切换 family 不改变 custom 渲染。
8. 编辑器中常态行/展开行分开保存；应用后 islandLayout 为 v2 且 island:save-layout 返回值与本地一致。
9. IslandState/IslandNotification/ScheduleDto/IslandTimePointDto 的映射表逐项实现：优先级、上课态、时间点类型、单双周、作业/叫人特殊语义均可按 5.6 追踪。
10. IPC 兼容：旧通道全部可用；payload 可选带 schemaVersion 仅作校验（不落盘）；缺字段时按 family 降级渲染而不是报错。
11. 编辑器/设置页不把预览、缩放、选中项写入配置；预览消息不写历史、不改已读。
12. 读到 islandLayout.version>2 时应用只读并提示，不得覆盖用户文件。
13. 外观新字段：关闭 effectEnabled 后强提醒特效不再渲染（行内气泡/普通提醒仍工作）；effectScale 只接受 1/0.75/0.5 并实际改变特效尺寸；progressBar.show=false 时所有行进度条隐藏，行级高度覆盖方案/外观。
14. 运行期状态：IslandState 含 family/pendingStaged/bubblePhase/bubbleDeadline 且不写入 config.json；上课暂存时 pendingStaged 与队列数一致；气泡阶段按 idle→mask-in→content-in→out 推进。
15. 派生字段：IslandNotification.level 按 URGENT→emergency/HIGH→high/NORMAL→normal/LOW→low 生成且不落盘；IslandLessonReminder.progress 在 0–1、leftSeconds 与蓝色圆形徽标一致（剩余 1 秒显示 -1）。
16. fixed（classisland）下 prepare/on-class/break 以行内容接管呈现、ending 只显示秒数徽标；custom 下不接管（课程组件 + 徽标）；两种 family 的提醒开关语义一致。
17. fixed 行内气泡同一时刻只显示 1 条 active；多条折叠为「还有 N 条」并可打开应用内通知中心；队列/去重/暂存规则不变。
18. family='winisland' 只影响 fixed（保持现有胶囊观感）；custom 始终按 ClassIsland 规格渲染、不受 family 影响、不引用 winisland 样式命名空间；family='classisland' 的 fixed 使用 classisland 命名空间。
19. 经 pnpm verify:desktop（默认无头 quick）验证时，所有既有冒烟注入点仍可用：setTestInputPassthrough/setHitTestCursor/getWindowBounds/getHitRect/getInteractive/setBlurCollapseEnabled/setTouchMode/getTouchMode/isRecovering 等名称与语义不变（改造归属 part 11 测试基线）。
20. colorScheme 三种取值均生效：system 跟随应用深浅色（html.dark）、light/dark 强制；非法值回落 system；切换后岛即时重渲染且不改主窗口主题。
21. fontSize 语义按 family：classisland 下改 fontSize 会派生 14/18/20 阶梯并整体缩放行文字；winisland 下保持旧"基准字号"行为；迁移用户旧值不被覆盖。
22. 滚动组件 settings.mode：continuous 持续滚动、pause 到边界停顿 settings.interval 秒；normalize 后取值合法，旧配置缺失补 continuous。