# 实施路线图

## 总览

```
Phase 0  ████████████  基础设施骨架
Phase 1  ████          Draw.io 验证插件
Phase 2  █████████████  预览系统重构
Phase 3  █████████████  Tab 插件化 + 设置面板
Phase 4  ██████        外部插件支持
Phase 5  ░░░░░░░░░░░░░  插件市场（远景）
```

每个 Phase 可独立交付验证。

---

## Phase 0：基础设施骨架

**目标**：建好管道，不改现有功能。验证编译通过 + API 可调用。

详细步骤见 [Phase0-基础设施.md](./Phase0-基础设施.md)

---

## Phase 1：首个内置插件验证（Draw.io）

**目标**：用第一个真实插件验证整条链路端到端打通。

| 步骤 | 文件 | 操作 |
|------|------|------|
| 1 | `internal/plugin/builtin/drawio_plugin.go` | 新建 DrawIoPlugin 实现 |
| 2 | `frontend/src/plugin/built-in/drawio-handler.ts` | 新建前端 handler 注册 |
| 3 | `app.go` | 在 ServiceStartup 中 Register(DrawIoPlugin) |
| 4 | `FileEditorPanel.vue` | 在 v-if 链末尾追加 drawio 分支 |

**验证标准**：打开 `.drawio` 文件 → 显示 iframe 预览 → 其他文件不受影响。

---

## Phase 2：文件预览系统重构

**目标**：将全部 10 种内置预览迁移到插件注册表，消除 v-if 链。

| 步骤 | 文件 | 操作 |
|------|------|------|
| 1 | `frontend/src/plugin/built-in/preview-handlers.ts` | 新建，注册 image/video/audio/pdf/html/md/excel/word/csv/text/code 共 12 个处理器 |
| 2 | `FileEditorPanel.vue` | 模板重写为 `<component :is>` + `<iframe>` 双分支 |
| 3 | `registry.ts` | 被 FileEditorPanel 实际导入使用 |

**收益**：新增文件类型只需写一个 TS 文件（~20 行），零改动核心组件。

---

## Phase 3：Tab 系统插件化 + 设置面板 + UI 插槽

**目标**：App.vue 不再硬编码，设置面板支持插件管理，建立 UI 插槽体系。

| 步骤 | 文件 | 操作 |
|------|------|------|
| 1 | `frontend/src/plugin/built-in/tabs.ts` | 注册 file-system / markdown-editor 等内置 Tab |
| 2 | `frontend/src/plugin/built-in/index.ts` | 统一副作用入口 |
| 3 | `frontend/src/plugin/slots.ts` | UISlotRegistry 实现（插槽注册/查询） |
| 4 | `App.vue` | getComponent 改为查 registry；KeepAlive 动态化；接入 slot: titlebar-extra / sidebar-left / toolbar-extra 等 |
| 5 | `stores/config.ts` | loadConfig 合并插件 Tab（修复前后端断层） |
| 6 | `SettingsPanel.vue` | 新增「插件管理」Tab 页（列表 + 启用/禁用） |
| 7 | `app.go` | 新增 SetPluginEnabled 绑定方法；PluginMetadata 新增 UISlots 字段 |
| 8 | `service/config_service.go` | defaultTabConfig 改为动态合并插件 Tab |
| 9 | SQLite | 写入 plugin_state 初始数据 |

> UI 插槽详细设计见 `设计文档/架构设计.md` 第四章

---

## Phase 4：外部插件支持

**目标**：用户可安装 .zip 格式的外部插件包。

### 插件包格式 (.uplugin)

```
my-plugin-v1.0.0.uplugin (ZIP)
├── manifest.json          # 插件清单（必须）
├── plugin.wasm            # WASM 入口（跨平台首选）
├── assets/                # 静态资源
└── frontend/              # 前端组件（可选）
```

### manifest.json 结构

```json
{
  "id": "com.example.my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "entry": "plugin.wasm",
  "capabilities": ["file-preview"],
  "file_extensions": [".xyz"],
  "min_app_version": "0.4.0",
  "permissions": ["filesystem:read"],
  "checksum_sha256": "..."
}
```

### Manager 新增能力

```go
InstallPlugin(packagePath string) error   // 解压 + 校验 + 注册
UninstallPlugin(id PluginID) error       // 停止 + 删除 + 清理
SetPluginEnabled(id, enabled) error     // 启用/停用
ScanInstalledPlugins() error            // 扫描恢复
```

### 安全模型

| 层级 | 措施 | Phase |
|------|------|-------|
| 签名校验 | checksum_sha256 安装时验证 | Phase 4 |
| 权限声明 | permissions 列表安装时展示确认 | Phase 4 |
| 沙箱执行 | WASM 沙箱 / 子进程隔离 | Phase 5 |
| 版本兼容 | min_app_version 检查 | Phase 4 |

---

## Phase 5：插件市场（远景）

### 整体架构

```
┌──────────────────┐         ┌──────────────────┐
│   插件市场服务端   │         │   u-desk 客户端   │
│                  │◄───────►│                  │
│  · 插件仓库 CRUD  │  HTTPS  │  · 浏览/搜索      │
│  · 元数据 API     │         │  · 一键安装       │
│  · 包文件分发     │         │  · 自动更新检查   │
│  · 签名 & 信誉    │         │  · 评分/评论(预留) │
└──────────────────┘         └──────────────────┘
```

### 服务端职责（优先级排序）

| P0 | P1 | P2 | P3 |
|----|----|----|----|
| 插件仓库 CRUD | 搜索过滤 | 开发者门户 | 评分评论 |
| 包分发 CDN | 自动更新通知 | 审核流程 | |
| 版本管理 | | | |
| 签名验证 | | | |

### 客户端 MarketplaceClient API

```typescript
interface MarketplaceClient {
  searchPlugins(query, category?): Promise<MarketplacePlugin[]>
  getPluginDetail(id): Promise<MarketplacePluginDetail>
  installPlugin(id): Promise<InstallProgress>
  uninstallPlugin(id): Promise<void>
  checkUpdates(): Promise<PluginUpdateInfo[]>
  updatePlugin(id): Promise<InstallProgress>
}
```

### 更新机制（复用现有 UpdateAPI）

```
应用更新（已有）：CheckUpdate → DownloadUpdate → VerifyUpdateFile → InstallUpdateWithHash
插件更新（新增）：CheckPluginUpdates → DownloadPlugin → VerifyPlugin → InstallPlugin
```