cc-switch/docs/updater-plan.md

更新功能开发计划（Tauri v2 Updater）

目标：基于 Tauri v2 官方 Updater，完成“检查更新 → 下载 → 安装 → 重启”的完整闭环；提供清晰的前后端接口、配置与测试/发布流程。

范围与目标

• 能力：静态 JSON 与动态接口两种更新源；可选稳定/测试通道；进度反馈与错误处理。
• 平台：macOS .app 优先；Windows 使用安装器（NSIS/MSI）。
• 安全：启用 Ed25519 更新签名校验；上线前建议平台代码签名与公证。

架构与依赖

• 插件：tauri-plugin-updater（更新）、@tauri-apps/plugin-updater（JS）；tauri-plugin-process 与 @tauri-apps/plugin-process（重启）。
• 签名与构建：tauri signer generate 生成密钥；CI/本机注入 TAURI_SIGNING_PRIVATE_KEY；bundle.createUpdaterArtifacts: true 生成签名制品。
• 权限：在 src-tauri/capabilities/default.json 启用 updater:default 与 process:allow-restart。
• 配置（src-tauri/tauri.conf.json）：
  • plugins.updater.pubkey: "<PUBLICKEY.PEM>"
  • plugins.updater.endpoints: ["<更新源 URL 列表>"]
  • Windows（可选）：plugins.updater.windows.installMode: "passive|basicUi|quiet"

前端接口设计（TypeScript）

• 类型
  • type UpdateChannel = 'stable' | 'beta'
  • type UpdaterPhase = 'idle' | 'checking' | 'available' | 'downloading' | 'installing' | 'restarting' | 'upToDate' | 'error'
  • type UpdateInfo = { currentVersion: string; availableVersion: string; notes?: string; pubDate?: string }
  • type UpdateProgressEvent = { event: 'Started' | 'Progress' | 'Finished'; total?: number; downloaded?: number }
  • type UpdateError = { code: string; message: string; cause?: unknown }
  • type CheckOptions = { timeout?: number; channel?: UpdateChannel }
• API（src/lib/updater.ts）
  • getCurrentVersion(): Promise<string> 读取当前版本。
  • checkForUpdate(opts?: CheckOptions) → up-to-date 或 { status: 'available', info, update }。
  • downloadAndInstall(update, onProgress?) 下载并安装，进度回调映射 Started/Progress/Finished。
  • relaunchApp() 调用 @tauri-apps/plugin-process.relaunch()。
  • runUpdateFlow(opts?) 编排：检查 → 下载安装 → 重启；错误统一抛出 UpdateError。
  • setUpdateChannel(channel) 前端记录偏好；实际端点切换见“端点动态化”。
• Hook（可选 useUpdater()）
  • 返回 { phase, info?, progress?, error?, actions: { check, startUpdate, relaunch } }。
• UI（组件建议）
  • UpdateBanner：发现新版本时展示；UpdaterDialog：显示说明、进度与错误/重试。

Rust 集成与权限

• 插件注册（src-tauri/src/main.rs）：
  • app.handle().plugin(tauri_plugin_updater::Builder::new().build())?;
  • .plugin(tauri_plugin_process::init()) 用于重启。
• Windows 清理钩子（可选）：UpdaterExt::on_before_exit(app.cleanup_before_exit)，避免安装器启动前文件占用。
• 端点动态化（可选）：在 setup 根据配置/环境切换 endpoints、超时、代理或 headers。

更新源与格式

• 静态 JSON（latest.json）：字段 version、platforms[target].url、platforms[target].signature（.sig 内容）；可选 notes、pub_date。
• 动态接口：
  • 无更新：HTTP 204
  • 有更新：HTTP 200 → { version, url, signature, notes?, pub_date? }
• 通道组织：/stable/latest.json、/beta/latest.json；CDN 缓存需可控，回滚可强制刷新。

用户流程与 UX

• 流程：检查 → 展示版本/日志 → 下载进度（累计/百分比）→ 安装 → 提示并重启。
• 错误：网络异常（超时/断网/证书）、签名不匹配、权限/文件占用（Win）。提供“重试/稍后更新”。
• 平台提示：
  • macOS：建议安装在 ~/Applications，避免 /Applications 提权导致失败。
  • Windows：优先安装器分发，并选择合适 installMode。

测试计划

• 功能：有更新/无更新（204）/下载中断/重试/安装后重启成功与版本号提升。
• 安全：签名不匹配必须拒绝更新；端点不可用/被劫持有清晰提示。
• 网络：超时/断网/代理场景提示与恢复。
• 平台：
  • macOS：/Applications 与 ~/Applications 的权限差异。
  • Windows：passive|basicUi|quiet 行为差异与成功率。
• 本地自测：以 v1.0.0 运行，构建 v1.0.1 制品+.sig，本地 HTTP 托管 latest.json，验证全链路。

发布与回滚

• 发布（CI 推荐）：注入 TAURI_SIGNING_PRIVATE_KEY → 构建生成各平台制品+签名 → 上传产物与 latest.json 至 Releases/CDN。
• 回滚：撤下问题版本或将 latest.json 指回上一个稳定版本；如需降级，Rust 侧可定制版本比较策略（可选）。

里程碑与验收

• D1：密钥与基础集成（插件/配置/权限）。
• D2：前端入口与进度 UI，静态 JSON 自测通过。
• D3：Releases/CDN 端到端验证，平台专项测试。
• D4：文档完善、回滚与异常流程演练。
• 验收：两平台完成“发现→下载→安装→重启→版本提升”；签名校验生效；异常有明确提示与可行恢复。

待确认

• 更新源托管（GitHub Releases 还是自有 CDN）。
• 是否需要 beta 通道与运行时切换。
• Windows 是否仅支持安装器分发；便携版兼容策略是否需要明确说明。
• UI 文案与样式偏好。

落地步骤（实施顺序）

1. 生成 Ed25519 密钥，将公钥写入 plugins.updater.pubkey，在构建环境配置 TAURI_SIGNING_PRIVATE_KEY。
2. src-tauri 注册 tauri-plugin-updater 与 tauri-plugin-process，补齐 capabilities/default.json 与 tauri.conf.json。
3. 前端新增 src/lib/updater.ts 封装与 UpdateBanner/UpdaterDialog 组件，接入入口按钮。
4. 本地静态 latest.json 自测全链路；完善错误与进度提示。
5. 配置 CI 发布产物与 latest.json；编写发布/回滚操作手册。