classhelper-island-refactor-prompt/parts/01-overview.md

## 1. 项目总纲：产品定位、总体体验与系统架构

### 1.1 你的角色与最终目标

你是一名资深跨平台桌面应用工程师，精通 Electron、Vue 3、TypeScript 与现代桌面 UI 动效实现。你的任务是从零实现一个**班级多媒体屏幕课表信息显示工具**，本提示词称其为 **ClassIsland（实现代号 `classisland-ts`）**。它常驻在教室大屏/讲台电脑上，以悬浮「岛」的形式显示当天课表、当前课程、倒计时、天气、日期时间等信息，并在上课、下课、课前准备、放学、天气变化等重要时间点发出提醒，同时提供课表编辑、组件自定义、主题、自动化、插件扩展等一整套能力。

最终交付必须是一个**可安装、可离线运行、可长时间无人值守运行**的 Windows / macOS / Linux 桌面应用，而不是网页 Demo。你必须严格按本提示词的数值、交互、动画与数据结构实现；凡本提示词给出确切数值的地方，不得用「差不多」的默认样式替代。

### 1.2 产品定位

- 一句话定位：**给班级多媒体屏幕用的、灵感来自 iOS 灵动岛的课表与班级信息悬浮显示工具。**
- 使用环境：Windows 10+（主目标）、macOS 11+、Linux X11（不支持 Wayland）；屏幕常见 1920×1080、2560×1440、3840×2160，缩放 100%–200%，也可能是希沃等触摸一体机。
- 使用方式：开机自启，常驻桌面最上层；上课时悬浮在课件上方但不遮挡关键内容；教师可通过右键菜单/托盘快速进入编辑、换课、设置；放学后可由自动化或管理策略隐藏。
- 核心价值：**零打扰**（不弹系统级窗口、不抢焦点、可点击穿透）、**秒级准确**（网络对时 + 本地时钟补偿）、**一眼可读**（大字号、强对比、信息分层）、**完全可定制**（组件、主题、课表、提醒、自动化）。
- 明确不是：不是 Web 管理系统、不是手机 App、不是需要登录云服务的 SaaS。除天气、更新、可选管理端外，全部功能必须离线可用。

### 1.3 目标用户与典型场景

1. **班主任/任课老师**：用 Excel 导入课表，设置单双周/多周轮换、临时换课；设置上下课提醒音效与语音；用自动化在午休时关闭屏幕。
2. **电教委员/学生**：日常只看岛，不需要任何操作；断网、重启后应用自动恢复；不误触、不遮挡投影。
3. **学校管理员**：通过主题/配置批量部署；可选管理端下发策略（本提示词的 P2 可选模块，默认不依赖服务器）。
4. **插件开发者**：按插件规范扩展组件、提醒提供者、自动化触发器/行动、设置页。

### 1.4 十条不可妥协的体验原则

1. **像素级还原本提示词的视觉规格**：圆角、透明度、字号阶梯、间距、进度条、阴影必须逐项落实；默认参数见第 3、4 部分。
2. **绝不打扰授课**：主窗口默认不抢焦点（`show: false` 显示、`focusable: false`）、不进入任务栏、可配置鼠标穿透；任何自动验证/冒烟必须无头运行，不得创建可见窗口。
3. **60fps 丝滑动画**：所有过渡优先使用 CSS transform/opacity（合成层），禁止用 JS 逐帧改布局；弹簧动画采用本提示词给定的物理参数。
4. **时间必须准**：所有课程状态以「带补偿的当前时间」计算；支持 NTP 对时、手动时间偏移、时间倍速调试；跨天、跨周、闰秒、系统休眠唤醒都要正确。
5. **离线优先、数据安全**：配置、课表、提醒全部本地存储；写入采用原子替换 + 自动备份；任何迁移前先备份，迁移失败可回滚。
6. **组件化与可组合**：主界面的每一行、每一个显示单元都是组件；组件可嵌套（分组/堆叠/滚动/滑动）、可单独设置、可按规则隐藏。
7. **默认即好看**：首次启动走完 OOBE 后，即使不导入课表也要显示一个可用的岛（日期、时间、欢迎信息），不能白屏。
8. **可恢复**：渲染进程崩溃、GPU 崩溃、配置损坏、误删数据时，应用必须能自愈或进入恢复模式；崩溃后不得反复重启刷屏。
9. **可扩展**：插件/主题/提醒提供者/自动化行动全部通过注册表扩展，核心不写死；公共 API 保持向后兼容。
10. **可访问与本地化**：中文为默认语言（ClassIsland 2.1 的界面文案为硬编码中文）；支持高对比、减少动画（`AnimationLevel`）、键盘操作、触摸操作；文案集中到常量/词条文件，预留 i18n key 体系，不得把字符串散落在组件里。

### 1.5 功能全景（必须实现的模块）

> 优先级：P0 = 首版必须；P1 = 首个稳定版必须；P2 = 可分期但提示词要求预留架构。

| 模块 | 能力清单 | 优先级 |
|---|---|---|
| 主界面（岛） | 多行岛、背景/圆角/透明度/毛玻璃、课程信息行、进度条、倒计时、遮罩/提醒宿主、编辑模式、隐藏规则、点击穿透、多显示器停靠、缩放、窗口置顶 | P0 |
| 组件系统 | 日期、时钟、倒计时、课程表、天气、文本、滚动、滑动、堆叠、分组、分隔线、容器；组件设置、显示/隐藏规则、多行组件、轮播 | P0 |
| 课程表与档案 | 时间表（节次/课间/分割线/行动）、课表（单日/多日/周模板）、多周轮换（1–9 周）、科目与教师、临时课表/预定课表、单日与跨天换课、CSES 导入导出（P0）、Excel 导入导出（P1，用 xlsx 重建；ClassIsland 2.1 源码中该功能被 `#if false` 停用，布局仅作参考）、多档案 | P0/P1 |
| 提醒系统 | 提醒队列与优先级、上/下课/课前/放学提醒、天气类提醒、自定义提醒、气泡与强提醒特效、音效、TTS 语音、提醒历史与清除（ClassIsland 2.1 无独立「静音时段」；只有全局提醒开关与 `-q` 静默启动后 10s 丢弃提醒，不得虚构静音时段，P2 扩展需默认关闭） | P0 |
| 设置中心 | 通用/外观/组件/提醒/自动化/天气/窗口/时钟/主题/更新/存储/插件/管理/隐私/高级/关于/调试，即时保存、设置覆盖层、按注册顺序导航（ClassIsland 2.1 无搜索框，本实现不编造搜索；如需可标 P2 增强） | P0 |
| OOBE 向导 | 8 页：欢迎、许可、翻新/迎新、基本、颜色、外观、系统、完成；可跳过、可重复打开 | P0 |
| 主题系统 | 内置 Fluent/Classic 两套主题、主题包（CSS 变量 + 资源 + 预览图）、自定义强调色/背景色/前景色、深浅色跟随系统；壁纸取色在 ClassIsland 2.1 中已整体停用（`WallpaperPickingService` 全文 `#if false`，设置页对应项禁用隐藏），本实现只作为 P2 实验性能力（默认关闭、给算法与数据结构、不纳入 P1 验收） | P1（壁纸取色 P2） |
| 自动化 | 触发器（时间点/CRON/信号/URI/托盘菜单/窗口状态/当前课程/天气/日出日落）、行动（提醒/运行程序/打开文件网页/关机/睡眠/重启/修改设置/广播信号/切换课表等）、规则集（嵌套条件） | P1 |
| 天气 | 当前天气、逐小时/未来 3 天预报、降水提醒、极端天气预警、定位/城市选择、天气图标主题 | P1 |
| 插件系统 | 插件包格式、清单、权限、生命周期、组件/提醒/触发器/行动/设置页扩展点、插件市场（可选）、启用/禁用/更新 | P1 |
| 调试与诊断 | 日志查看、配置校验、崩溃上报（可选 Sentry）、渲染模式切换、时间调试、动画调试、窗口规则调试、教程系统 | P1 |
| 更新与运维 | 自动检查更新、镜像/通道、断点下载、哈希校验、静默安装、崩溃恢复、单实例、开机自启 | P1 |
| 管理端联动 | 可选远程策略、管理凭据、通知通道（P2，默认关闭且不得成为运行前置依赖） | P2 |

### 1.6 总体技术架构（ClassHelper 栈）

**必须采用 ClassHelper 的技术栈与工程约定**（来源：`repos/ClassHelper-master/package.json`、`pnpm-workspace.yaml`、各 `packages/*/package.json`、`AGENTS.md`）：

- 包管理器：`pnpm@11.8.0`，Node.js >= 20.19；根 `package.json` 为版本单一来源。
- 语言：TypeScript ~5.9.3，开启 `strict`；Vue 3.5 SFC（`<script setup lang="ts">`），禁止 `any` 泛滥。
- 桌面壳：Electron ^44.3.0 + electron-builder ^26.15.3；Windows 目标 NSIS/portable，macOS dmg/zip，Linux AppImage/deb（任选其一即可，但构建脚本必须齐全）。
- 渲染层：Vue ^3.5.42 + Vue Router ^5.3.1 + Pinia ^4.0.3 + Element Plus ^2.14.5（仅设置/管理类界面使用 Element Plus；主界面「岛」使用手写 CSS 与自定义组件，**不得**让 Element Plus 的默认样式污染岛）。
- 构建：Vite ^8.3.0（`@vitejs/plugin-vue` ^6.0.8），多入口构建：`index.html`（设置/主窗口）与 `island.html`（独立岛渲染进程）。
- 进程模型（必须三进程分离）：
  1. **主进程 `src/main`**：窗口管理、托盘、全局快捷键、单实例、配置读写、调度（时间引擎/提醒调度/自动化）、自动更新、系统集成、IPC 服务端。
  2. **岛渲染进程 `island.html` → `src/island`**：只负责画「岛」，常驻内存，通过 contextBridge 暴露的最小 API 接收状态；窗口透明、点击穿透由主进程控制。
  3. **应用窗口渲染进程 `index.html` → `src/renderer`**：设置中心、档案编辑、OOBE 向导、关于、日志、调试、恢复等；按需创建，关闭即销毁（pinia 状态持久化到主进程）。
- 共享包：`packages/shared`（类型、常量、i18n 词条、数据 schema、纯函数业务逻辑：时间/周次/课表解析）、`packages/ui`（CSS tokens、基础 Vue 控件、主题）。
- 目录结构必须为 pnpm monorepo（`packages/*`），至少包含：`packages/desktop-client`（Electron 应用）、`packages/shared`、`packages/ui`。若实现插件宿主，可增加 `packages/plugin-sdk`（P1）。
- 复用 ClassHelper 已验证的桌面岛关键实现（可直接参照其代码组织与参数）：
  - 独立 `island.html` 渲染入口 + 独立透明 BrowserWindow（见 `repos/ClassHelper-master/packages/desktop-client/src/main/island.ts`）。
  - `squircle.ts` 连续圆角（超椭圆指数 4.2，每角 14 段，半径 `min(r, w/2, h/2)`）。
  - `spring.ts` 弹簧动画（`stiffness=0.10`、`damping=0.68`、换向动量保留 35%、单帧位移 ≤ 剩余距离 20%、snap 阈值 0.05px、60fps 帧单位）。
  - `config.json` + `config.ts` 的原子读写、版本迁移、默认值合并（参照 `src/main/config.ts`）。
  - preload 只暴露 contextBridge 白名单，不暴露 `ipcRenderer`；渲染层不得直接访问 `fs`/`child_process`。
  - `renderer/composables/motion.ts` 的统一动效 token；`packages/ui/src/tokens.css` 的颜色/圆角/动效变量体系。
- **不得引入 ClassHelper 的服务端依赖**：本应用是本地单机应用；Express/Prisma/Socket.IO 仅在你选择实现 P2「管理端联动」时才可作为可选子包，且主流程不得依赖网络。
- 允许使用成熟开源库完成非核心能力（如 `xlsx` 解析 Excel、`yaml` 读取插件清单、`adm-zip` 解压插件/主题包）；**更新器必须自研**（参照 ClassHelper 的 `src/main/auto-update.ts` + `update-installer.ts`，禁止引入 electron-updater）；不要引入 `node-pty`、`sharp` 等原生模块。所有依赖必须列明版本并锁定 `pnpm-lock.yaml`。

**逻辑分层（进程内）**：

```
main
├─ config/        配置读写、迁移、备份（Settings/Profiles/Automations/Components/Themes）
├─ windows/       island / app / splash / topmost-effect / class-changing / oobe ...
├─ engine/
│   ├─ clock      NTP 对时 + 偏移 + 倍速；对外只暴露当前时间
│   ├─ lessons    课表解析、当前/下一节、时间点状态机、周次计算
│   ├─ notification 提醒队列、提供者、优先级、去重、TTS/音效
│   ├─ automation 触发器轮询、行动执行、规则集求值
│   ├─ weather    天气拉取、缓存、预警
│   └─ update     更新检查/下载/安装
├─ ipc/           contextBridge 白名单 + 通道校验 + 节流
└─ tray/          托盘菜单、开机自启、单实例
renderer(island)  IslandApp.vue + 组件渲染器 + 动画
renderer(app)     SettingsWindow / ProfileEditor / OOBE / About / Logs / Recovery ...
```

### 1.7 信息架构与导航

- 主界面（岛）是唯一常驻界面，无标题栏、无任务栏图标、无边框。右键（或长按触摸）弹出**原生上下文菜单**：ClassIsland（关于）、教学…、帮助文档…、显示/隐藏主界面、清除全部提醒、更多选项…、编辑档案…、加载临时课表…、换课…、编辑主界面…、应用设置…、重启、退出（调试模式下追加 dev__Debug 子菜单）。菜单项文案、图标、可见条件必须与第 4 部分一致。
- 托盘图标提供左键行为（默认打开主菜单/打开档案编辑/显示隐藏主界面/打开换课/打开设置，见设置项 `TaskBarIconClickBehavior` 默认值：Windows 0，其他平台 4）。
- 应用窗口为 Fluent 风格的单窗口 + 页面栈：设置中心（左侧导航列表 + 面包屑返回；ClassIsland 2.1 **无设置搜索框**，本实现不得编造搜索，如做需明确标 P2 增强）、档案编辑器（左侧档案树 + 右侧编辑区）、OOBE（无侧栏的 8 页步骤向导）、关于、日志、调试、恢复模式；提醒不设独立「通知中心」窗口，由主界面行内气泡 + 强提醒特效承载。
- 所有次级窗口居中显示、可用 Esc 关闭、标题栏使用系统样式（Fluent 主题下自绘标题栏）；关闭设置窗口不退出应用，仅隐藏。
- URL Scheme：`classisland://app/...` 用于深链（关于页、设置页等），由单实例机制转发到已运行实例。

### 1.8 首次启动与默认状态

1. 启动时先显示无边框闪屏（可选，默认关闭；打开时 1.2s 内渐显 Logo 与应用名，可显示加载状态），随后显示 OOBE。
2. OOBE 完成后写 `config.json`（并兼容导出 ClassIsland 的 `Settings.json`）的 `IsWelcomeWindowShowed=true`，主界面以默认参数出现：位置=中上侧（`WindowDockingLocation=1`）、缩放 100%、背景不透明度 0.5、圆角 8px、字体默认系统字体（Windows 为微软雅黑 UI 回退链）、主体字号 16、次要 14、强调 18、超大 20、行间距 5px。
3. 默认组件配置为 1 行 2 组件：日期（DF3F8295-21F6-482E-BADA-FA0E5F14BB66）+ 课程表（1DB2017D-E374-4BC6-9D57-0B4ADF03A6B8，依据 ComponentsService.cs:33-52）。未加载档案时课程表组件显示「今天没有课程。」等占位符，而不是白屏或欢迎文本；加载课表后显示课程信息。
4. 默认设置必须保证：岛可见、不穿透、不抢焦点、不遮挡全屏应用（`HideOnFullscreen=false`，可开启）、提醒开启、音效开启但音量 100%、调试关闭。

### 1.9 本提示词的使用方式与验收总则

- 本提示词按「总纲 → 技术栈 → 设计系统 → 主界面 → 组件 → 课表/提醒/自动化 → 主题/设置/窗口 → 动画/资源 → 插件/数据 → 验收」组织。实现时必须全部通读，再按第 17 部分的里程碑顺序开发。
- 每一部分末尾都有「验收标准」；你必须逐条自测并在交付说明中报告结果。自测必须无头执行（`--headless` / 隐藏窗口 / CI 模式），**不得弹出可见窗口、不得占用用户桌面、不得发出声音**；像素级验收使用 Playwright/`electron` 的离屏截图模式完成。
- 任何你没有把握的数值，优先服从本提示词；本提示词未覆盖的细节，按「Fluent Design + 灵动岛」的直觉补齐，并在代码注释中说明。
- 交付必须包含：完整源码、`README.md`（含运行/构建/打包命令）、`docs/`（数据 schema 与插件 API）、至少 1 个示例主题与 1 个示例插件（P1）、以及一套无头自动化测试（单元测试 + 关键交互的组件测试）。