新增：文档体系重构+CHANGELOG补充+发布产物清理

docs/04-功能迭代/GO-DESK-8.Wails-v3迁移.md

@@ -0,0 +1,126 @@
+# 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/ 下，如不再使用应清理