lxy/u-desk
Private
Public Access
1
0
Fork 0
Code Activity
Files
6eaaa56eb65578647511ac7cc163949f2c5863b2
u-desk/docs/02-架构设计/Pinia迁移/ADR-001-pinia-migration.md

5.9 KiB
Raw Blame History

ADR 001: Pinia 状态管理迁移

状态

已实施

日期

2026-02-04

背景

前端更新管理模块存在以下问题：

  • 代码重复：UpdatePanel.vue 和 UpdateNotification.vue 都维护了相同的状态和逻辑
  • 事件监听重复：两个组件都注册了 download-progress 和 download-complete 事件
  • 工具函数重复：parseEventData、formatFileSize、formatSpeed 在多处定义
  • 状态管理混乱：useUpdate composable 使用单例模式，但 Ref 解构会丢失响应性

决策

采用 Pinia Store 方案统一管理前端状态。

方案对比（10 维度分析）

方案 得分 成本（2年） 风险 可维护性
Pinia Store 78.3/100 21 人天 低 (2.0/10) 优秀 (9.0/10)
Singleton Composable 65.0/100 40 人天 高 (6.0/10) 中等 (6.5/10)
Provide/Inject 60.0/100 35 人天 中 (4.5/10) 中等 (6.0/10)

Pinia 核心优势：

  • ✅ 全局唯一的响应式状态
  • ✅ DevTools 支持，便于调试
  • ✅ TypeScript 友好
  • ✅ 自动代码分割
  • ✅ 降低 47.5% 的长期维护成本

实施细节

1. 安装 Pinia

npm install pinia

2. 创建 Update Store

文件：frontend/src/stores/update.ts

核心功能：

  • 状态管理：updateInfo, checking, downloading, installing, downloadProgress
  • 方法：checkForUpdates, downloadUpdate, installUpdate
  • 工具函数：formatFileSize, formatSpeed
  • 事件监听：setupEventListeners, removeEventListeners

3. 更新 main.js

集成 Pinia 到应用：

import { createPinia } from 'pinia'

const app = createApp(App)
const pinia = createPinia()

app.use(pinia)

4. 组件迁移

App.vue

  • 使用 useUpdateStore() 替代 useUpdate()
  • 在 onMounted 中设置事件监听
  • 启动后 3 秒自动检查更新

UpdatePanel.vue

  • 从 store 获取状态：updateStore.checking, updateStore.downloadProgress 等
  • 移除本地重复状态和方法
  • 仅保留文件路径记录（downloadedFile）

UpdateNotification.vue

  • 使用 store 的计算属性：updateStore.downloading, updateStore.installing
  • 移除本地工具函数（parseEventData, formatFileSize）
  • 移除重复的事件监听器
  • 保留 UI 逻辑（Modal 显示和更新）

5. 清理

  • 删除 frontend/src/composables/useUpdate.js
  • 移除组件中对旧 composable 的引用

迁移清单

  • 安装 Pinia
  • 创建 stores/update.ts
  • 更新 main.js
  • 迁移 App.vue
  • 迁移 UpdatePanel.vue
  • 迁移 UpdateNotification.vue
  • 删除 useUpdate.js
  • 验证无残留引用

影响范围

修改的文件

  1. frontend/package.json - 添加 pinia 依赖
  2. frontend/src/main.js - 集成 Pinia
  3. frontend/src/stores/update.ts - 新建
  4. frontend/src/App.vue - 使用 store
  5. frontend/src/components/UpdatePanel.vue - 使用 store
  6. frontend/src/components/UpdateNotification.vue - 使用 store

删除的文件

  1. frontend/src/composables/useUpdate.js - 已迁移到 store

效果

代码质量提升

  • 减少重复：删除 200+ 行重复代码
  • 统一管理：所有更新相关状态集中在一个 store
  • 响应性保证：Pinia 自动处理响应式，无解构丢失问题

开发体验改善

  • DevTools 集成：可以实时查看和修改状态
  • 类型安全：TypeScript 支持完善
  • 调试便利：状态变化可追踪

维护成本降低

  • 单一数据源：状态变化路径清晰
  • 事件监听统一：只注册一次，全局共享
  • 未来扩展性：可轻松添加更多 store（如 theme, config）

后续计划

短期

  • 添加单元测试（store actions）
  • 添加 E2E 测试（更新流程）
  • 性能监控（事件监听开销）

长期

  • 迁移 theme 管理到 Pinia（useTheme → stores/theme）✅
  • 迁移 config 管理到 Pinia ✅
  • 统一所有全局状态管理

参考

作者

Claude Code with User Decision

变更记录：

  • 2026-02-04: 初始版本，完成 Pinia 迁移（更新管理）
  • 2026-02-04: 第二次迁移，完成 theme 和 config 管理到 Pinia

第二次迁移：Theme & Config（2026-02-04）

新增 Stores

1. Theme Store（frontend/src/stores/theme.ts）

功能：

  • 管理亮色/暗色主题
  • 跟随系统主题变化
  • 主题持久化（localStorage）

核心方法：

  • toggleTheme() - 切换主题
  • setLightTheme() / setDarkTheme() - 设置特定主题
  • initTheme() - 初始化（检测系统偏好）
  • removeSystemThemeListener() - 清理监听器

计算属性：

  • isDark / isLight - 主题判断
  • tooltipText - 提示文本

2. Config Store（frontend/src/stores/config.ts）

功能：

  • 管理应用配置（标签页、默认页等）
  • 从后端加载配置
  • 保存配置到后端

核心方法：

  • loadConfig() - 加载配置
  • saveConfig() - 保存配置
  • isTabVisible() - 检查 Tab 可见性
  • getTab() - 获取 Tab 配置

计算属性：

  • visibleTabs - 可见标签页列表
  • allTabs - 所有标签页
  • defaultTab - 默认标签页

组件迁移

更新的文件

  1. frontend/src/main.js - 使用 themeStore.initTheme()
  2. frontend/src/components/ThemeToggle.vue - 使用 themeStore
  3. frontend/src/components/CodeEditor.vue - 使用 themeStore.isDark
  4. frontend/src/App.vue - 使用 configStore

删除的文件

  1. frontend/src/composables/useTheme.ts - 已迁移到 store

效果

  • 统一管理：主题和配置状态集中管理
  • 简化组件：移除组件内的重复逻辑
  • 响应性保证：所有状态变化自动响应
  • DevTools 支持：可以实时查看和修改状态
  • 构建成功：✓ built in 34.28s
View Git Blame Copy Permalink