# 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
```bash
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 到应用：
```javascript
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 的引用

## 迁移清单

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

## 影响范围

### 修改的文件
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 测试（更新流程）
- [ ] 性能监控（事件监听开销）

### 长期
- [x] 迁移 theme 管理到 Pinia（useTheme → stores/theme）✅
- [x] 迁移 config 管理到 Pinia ✅
- [ ] 统一所有全局状态管理

## 参考

- [Pinia 官方文档](https://pinia.vuejs.org/)
- [Vue 3 Composition API](https://vuejs.org/api/composition-api-setup.html)
- [Agent 分析报告](../.claude/projects/E--wk-lab-go-desk/)

## 作者

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