新增: SFTP直连+网站预览+OSS区域嗅探+热键+BGM播放

docs/04-功能迭代/GO-DESK-9.插件系统/任务规划/Phase0-基础设施.md

@@ -0,0 +1,149 @@
+# Phase 0：基础设施骨架
+
+## 目标
+
+建好管道，不改现有功能。验证编译通过 + API 可调用。
+
+**不包含**：无 UI 变化、无真实插件注册、无设置面板。
+
+---
+
+## 文件清单与实施顺序
+
+### Step 1：核心接口定义
+
+**新建** `internal/plugin/plugin.go`
+
+内容：PluginID、PluginSource、PluginMetadata、PluginCapability、Plugin 接口、TabProvider、FilePreviewHandler、PreviewInfo、TabDef、CoreServices 接口定义。
+
+依赖：无
+
+---
+
+### Step 2：适配器（避免方法泄漏）
+
+**新建** `internal/plugin/adapter.go`
+
+内容：`adapter` 结构体实现 `CoreServices` 接口的 6 个方法。构造函数 `NewAdapter(app *App) CoreServices`。
+
+关键设计：不在 App 上直接实现 CoreServices（会导致 6 个内部方法被 Wails v3 自动暴露为前端 API），而是通过独立 adapter 封装。
+
+依赖：Step 1
+
+---
+
+### Step 3：Tab 注册表
+
+**新建** `internal/plugin/tab_registry.go`
+
+内容：
+- `TabRegistry` struct（mu + entries map）
+- Register（冲突检测）、GetByTabKey、GetAllDefinitions（按 Order 排序）、GetAllProviders、Count
+
+依赖：Step 1
+
+---
+
+### Step 4：预览注册表
+
+**新建** `internal/plugin/preview_registry.go`
+
+内容：
+- `PreviewRegistry` struct（mu + handlers 切片，按 priority 降序）
+- Register（自动排序）、Resolve（遍历匹配第一个 canHandle）、GetAllHandlers、Count
+
+依赖：Step 1
+
+---
+
+### Step 5：PluginManager
+
+**新建** `internal/plugin/manager.go`
+
+内容：
+- `Manager` struct（plugins map + core + tabReg + previewReg + ctx + initialized）
+- NewManager、Register（自动分发到子注册表 + 回滚）、InitAll、StartByTabKey
+- GetPluginInfos、ResolvePreview（附加 PluginID 到响应）、GetTabDefinitions、Shutdown
+
+依赖：Step 1 ~ 4 全部
+
+---
+
+### Step 6：前端类型定义
+
+**新建** `frontend/src/plugin/types.ts`
+
+内容：PluginCapability enum、PluginMetadata、TabPluginDefinition、FilePreviewHandlerDefinition、RenderConfig 接口。
+
+依赖：无
+
+---
+
+### Step 7：前端注册中心
+
+**新建** `frontend/src/plugin/registry.ts`
+
+内容：
+- Vue reactive state（tabPlugins Map + previewHandlers 数组）
+- Tab API：registerTabPlugin / getTabComponent / getAllTabDefinitions / hasTabPlugin
+- Preview API：registerPreviewHandler（按 priority 插入）/ resolvePreviewHandler / getAllPreviewHandlers
+- 调试工具：getRegistryStats
+
+依赖：Step 6
+
+---
+
+### Step 8：集成到 App
+
+**修改** `app.go`
+
+改动点：
+
+1. **新增字段**：`pluginMgr *plugin.Manager`（在 `mu` 字段之后）
+2. **ServiceStartup 中**（步骤 4 之后）：初始化 pluginMgr
+   ```go
+   fmt.Println("[启动] 初始化插件管理器...")
+   a.pluginMgr = plugin.NewManager(plugin.NewAdapter(a))
+   ```
+3. **ServiceShutdown 末尾**：关闭 pluginMgr
+   ```go
+   if a.pluginMgr != nil { a.pluginMgr.Shutdown() }
+   ```
+4. **新增绑定方法**（Wails v3 自动暴露前端）：
+   - `GetPluginInfos() ([]map[string]interface{}, error)` — 返回空数组或插件列表
+   - `ResolvePreview(req ResolvePreviewRequest) (map[string]interface{}, error)` — 解析文件预览处理器
+   - `ResolvePreviewRequest{Filename string}` 请求结构体
+
+依赖：Step 5
+
+---
+
+## 验证方案
+
+### 编译验证
+
+```bash
+go build ./internal/plugin/
+go build .
+cd frontend && npx vue-tsc --noEmit
+```
+
+### 运行时验证
+
+| # | 操作 | 预期结果 |
+|---|------|---------|
+| V1 | 运行应用 | 日志出现 `[启动] 初始化插件管理器...` |
+| V2 | 关闭应用 | 日志出现 `[插件管理器] 已关闭` |
+| V3 | DevTools: `GetPluginInfos()` | 返回 `{success:true, data:[]}` |
+| V4 | DevTools: `ResolvePreview({filename:'test'})` | 返回 `{success:false, message:"no preview handler..."}` |
+| V5 | 前端 import registry | 无 TS 错误 |
+
+### 边界情况
+
+| 场景 | 预期行为 |
+|------|---------|
+| pluginMgr 为 nil 调用 GetPluginInfos | 返回空数组，不 panic |
+| pluginMgr 为 nil 调用 ResolvePreview | 返回 success:false，不 panic |
+| TabRegistry.Register 同一 TabKey 两次 | 返回冲突错误 |
+| PreviewRegistry.Resolve 无匹配文件 | 返回 nil, "" |
+| Manager.Shutdown 无插件注册 | 正常返回 nil |