# GO-DESK-8: Wails v3 迁移变更分析

> 范围: `44847e0`(v0.4.0) → `f54bf1c`(fs-only-v3) | 提交数: 1 | 日期: 2026-05-01

## 变更总览

| 类别 | 数量 | 说明 |
|------|------|------|
| 重命名 | 77 | web/ → frontend/（git rename，历史保留） |
| 新增 | 94 | v3 构建模板 + bindings + 新文件 |
| 删除 | 4 | 旧文件（clipboard png、md5、v2 transport/types） |
| 修改 | 10 | 核心代码适配 v3 API |
| **合计** | **185** | **+7,772 / -918 行** |

---

## 一、框架升级（核心）

### Wails v2 → v3 API 映射

| v2 (旧) | v3 (新) | 文件 |
|---------|---------|------|
| `wails.Run(&options.App{...})` | `application.New()` + `Window.NewWithOptions()` | main.go |
| `options.App.Bind: []interface{}{app}` | `Services: []application.Service{application.NewService(app)}` | main.go |
| `AssetServer: &assetserver.Options{}` | `Assets: application.AssetOptions{Handler, Middleware}` | main.go |
| `app.Startup(ctx)` / `app.Shutdown(ctx)` | `app.ServiceStartup(ctx, opts)` / `app.ServiceShutdown()` | app.go |
| `runtime.Window(ctx)` | `a.mainWindow`（手动注入） | app.go |
| `runtime.*` 函数调用 | `window.*` 方法 + v3-bindings 自动生成 | 前端 |
| `//go:embed all:web/dist` | `//go:embed all:frontend/dist` | main.go |

### main.go 实质性变更
- **Middleware 中间件**: 拦截 `/wails/custom.js` 返回空 200，消除控制台 404
- **DevTools**: 延迟 2s 调用 `window.OpenDevTools()`（production + devtools build tag）
- **窗口主题**: Windows CustomTheme 配置亮/暗模式标题栏颜色

### app.go 实质性变更
- **新增** `SetMainWindow()` — v3 需要手动注入窗口引用
- **新增** `SetWindowTitleBarColor()` — v3 窗口主题色动态切换
- **新增** `sync.Mutex` — 并发安全保护 mainWindow
- **生命周期**: `Startup/Shutdown` → `ServiceStartup/ServiceShutdown`（返回 error）
- **错误处理**: panic → return error（符合 Go 惯例）

---

## 二、前端代码修改（有业务逻辑变化的）

### App.vue (+375/-60 行)
- Tabs padding-top 覆盖（Arco Design 默认 16px → 0）
- import 路径更新：`@/wailsjs/v3-bindings/u-desk/app`
- 窗口控制方法改用 v3 binding 导入

### Sidebar.vue (+406 行)
- **新架构**: 双区块折叠（收藏夹 + 帮助文档），各自独立 header + content
- **滚动优化**: `.sidebar overflow:hidden` + 收藏内容区 `overflow-y:auto` 内部滚动
- **帮助区块**: 固定底部 `flex-shrink:0`，默认展开
- 折叠动画: max-height + opacity CSS transition

### useFavorites.ts (+259 行)
- **修复**: `longPressTimer` const → let（解决 Assignment to constant variable TypeError）

### stores/ (config/theme/update)
- **config.ts**: Wails v3 绑定加载方式调整
- **theme.ts**: 窗口主题色通过 v3 API 设置
- **update.ts**: 更新检查逻辑适配 v3 事件系统

### wails-transport.ts (+121 行)
- **全新**: v3 transport 层实现（替代 v2 的 runtime 调用）

### UpdateNotification.vue / UpdatePanel.vue
- 事件监听从 v2 runtime 改为 v3 OffAll/events 模式

---

## 三、依赖变更

```diff
- github.com/wailsapp/wails/v2 v2.12.0
+ github.com/wailsapp/wails/v3 v3.0.0-alpha.80

- go 1.25.6
+ go 1.26

+ github.com/wailsapp/wails/v3/pkg/w32     # Win32 直接调用
+ dario.cat/mergo v1.0.2                    # 结构体合并
```

移除: `go-toast/v2`（v3 自带通知）、`gosod`/`slicer`（v2 工具库）

---

## 四、新增构建基础设施（94 个文件，均为 Wails v3 标准模板）

以下由 `wails3 task generate` 自动生成，无自定义逻辑：

| 目录 | 用途 |
|------|------|
| `build/config.yml` | 项目配置（dev mode executes 流水线） |
| `Taskfile.yml` | 根级任务定义（dev/build/run） |
| `build/android/` | Android 构建模板（Gradle + Java Bridge） |
| `build/darwin/` | macOS 构建（Info.plist + Icons） |
| `build/ios/` | iOS 构建（Xcode project） |
| `build/linux/` | Linux 构建（AppImage + nfpm） |
| `build/docker/` | Docker 交叉编译 |
| `build/windows/nsis/` | NSIS 安装包脚本 |
| `build/windows/msix/` | MSIX 打包配置 |
| `frontend/src/wailsjs/v3-bindings/` | v3 TypeScript 绑定（自动生成） |
| `frontend/bindings/` | v3 绑定副本（备用路径） |

---

## 五、删除项（4 个文件）

| 文件 | 原因 |
|------|------|
| `cmd/agent/clipboard_*.png` | 截图残留，已归档到 `.archive/` |
| `web/package.json.md5` | 旧完整性校验文件 |
| `web/src/api/wails-transport.ts` | v2 版本，已被 frontend 下新版替代 |
| `web/src/types/window.d.ts` | v2 类型声明，已被 frontend 下新版替代 |

---

## 六、风险点

1. **alpha.80 稳定性**: Wails v3 仍为 alpha，部分 API 可能后续 breaking change
2. **OpenDevTools sleep hack**: 2s 硬编码延迟不够可靠，待 OnDomReady 稳定后替换
3. **v2 bindings 残留**: `frontend/src/wailsjs/wailsjs/`（v2）仍随重命名保留在 frontend/ 下，如不再使用应清理