diff --git a/.gitignore b/.gitignore index 8ee54e8..8884860 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,4 @@ coverage *.sw? *.tsbuildinfo +.qoder/* diff --git a/.qoder/quests/api-field-chinese-annotation.md b/.qoder/quests/api-field-chinese-annotation.md deleted file mode 100644 index 6f5f87d..0000000 --- a/.qoder/quests/api-field-chinese-annotation.md +++ /dev/null @@ -1,338 +0,0 @@ -# API接口字段中文注释设计文档 - -## 1. 概述 - -本文档旨在为项目中所有API接口的字段添加中文注释，以提高代码的可读性和可维护性。通过对SDK、服务层、事件系统等模块中的接口定义进行中文注释，使开发人员能够更快速地理解和使用这些接口。 - -## 2. 设计原则 - -- 保持原有代码结构不变，仅添加中文注释 -- 注释内容准确描述字段的含义和用途 -- 统一注释风格，确保文档一致性 -- 重点注释复杂或容易误解的字段 - -## 3. 接口字段注释规范 - -### 3.1 基本注释格式 - -```typescript -/** - * 字段中文描述 - */ -fieldName: fieldType -``` - -### 3.2 枚举类型注释格式 - -```typescript -/** - * 枚举类型中文描述 - */ -export enum EnumName { - /** - * 枚举值中文描述 - */ - VALUE1 = 'value1', - - /** - * 枚举值中文描述 - */ - VALUE2 = 'value2', -} -``` - -## 4. SDK接口字段注释 - -### 4.1 核心类型定义 - -#### SDKConfig接口 - -| 字段名 | 类型 | 中文注释 | -| ----------- | -------------- | ---------------- | -| appId | string | 应用唯一标识符 | -| appName | string | 应用名称 | -| version | string | 应用版本号 | -| permissions | string[] | 应用所需权限列表 | -| debug | boolean (可选) | 是否开启调试模式 | - -#### APIResponse接口 - -| 字段名 | 类型 | 中文注释 | -| ------- | ------------- | -------------- | -| success | boolean | 请求是否成功 | -| data | T (可选) | 返回的数据内容 | -| error | string (可选) | 错误信息 | -| code | number (可选) | 错误码 | - -### 4.2 窗体SDK接口字段注释 - -#### WindowState枚举 - -| 枚举值 | 中文注释 | -| ---------- | ---------- | -| NORMAL | 正常状态 | -| MINIMIZED | 最小化状态 | -| MAXIMIZED | 最大化状态 | -| FULLSCREEN | 全屏状态 | - -#### WindowEvents接口 - -| 字段名 | 类型 | 中文注释 | -| ------------- | --------------------------------------- | -------------------- | -| onResize | (width: number, height: number) => void | 窗体尺寸变化事件回调 | -| onMove | (x: number, y: number) => void | 窗体位置移动事件回调 | -| onStateChange | (state: WindowState) => void | 窗体状态变化事件回调 | -| onFocus | () => void | 窗体获得焦点事件回调 | -| onBlur | () => void | 窗体失去焦点事件回调 | -| onClose | () => void | 窗体关闭事件回调 | - -### 4.3 存储SDK接口字段注释 - -#### StorageStats接口 - -| 字段名 | 类型 | 中文注释 | -| ------------ | ------ | ------------------ | -| usedSpace | number | 已使用存储空间(MB) | -| maxSpace | number | 最大存储空间(MB) | -| keysCount | number | 存储键数量 | -| lastAccessed | Date | 最后访问时间 | - -### 4.4 网络SDK接口字段注释 - -#### NetworkRequestConfig接口 - -| 字段名 | 类型 | 中文注释 | -| ------------ | -------------------------------------------------- | ------------------ | -| method | HTTPMethod (可选) | HTTP请求方法 | -| headers | Record (可选) | 请求头信息 | -| body | any (可选) | 请求体数据 | -| timeout | number (可选) | 请求超时时间(毫秒) | -| responseType | 'json' \| 'text' \| 'blob' \| 'arrayBuffer' (可选) | 响应数据类型 | - -#### NetworkResponse接口 - -| 字段名 | 类型 | 中文注释 | -| ---------- | ---------------------- | ------------ | -| data | T | 响应数据内容 | -| status | number | HTTP状态码 | -| statusText | string | HTTP状态文本 | -| headers | Record | 响应头信息 | -| url | string | 请求URL | - -### 4.5 事件SDK接口字段注释 - -#### EventMessage接口 - -| 字段名 | 类型 | 中文注释 | -| --------- | ------ | -------------- | -| id | string | 消息唯一标识符 | -| channel | string | 事件频道名称 | -| data | T | 消息数据内容 | -| senderId | string | 发送方标识符 | -| timestamp | Date | 消息发送时间戳 | - -#### EventSubscriptionConfig接口 - -| 字段名 | 类型 | 中文注释 | -| ------ | ----------------------------------------- | -------------- | -| filter | (message: EventMessage) => boolean (可选) | 消息过滤器函数 | -| once | boolean (可选) | 是否只监听一次 | - -### 4.6 UI SDK接口字段注释 - -#### DialogOptions接口 - -| 字段名 | 类型 | 中文注释 | -| ------------- | ----------------- | ------------------ | -| title | string (可选) | 对话框标题 | -| message | string | 对话框消息内容 | -| type | DialogType (可选) | 对话框类型 | -| buttons | string[] (可选) | 自定义按钮文本数组 | -| defaultButton | number (可选) | 默认按钮索引 | -| cancelButton | number (可选) | 取消按钮索引 | - -#### NotificationOptions接口 - -| 字段名 | 类型 | 中文注释 | -| -------- | ----------------------------------------------- | -------------- | -| title | string | 通知标题 | -| body | string | 通知正文内容 | -| icon | string (可选) | 通知图标URL | -| duration | number (可选) | 显示时长(毫秒) | -| actions | Array<{ title: string; action: string }> (可选) | 通知操作按钮 | - -### 4.7 系统SDK接口字段注释 - -#### SystemInfo接口 - -| 字段名 | 类型 | 中文注释 | -| ---------------- | --------------------------------- | -------------- | -| platform | string | 运行平台信息 | -| userAgent | string | 用户代理字符串 | -| language | string | 系统语言设置 | -| timezone | string | 时区信息 | -| screenResolution | { width: number; height: number } | 屏幕分辨率 | -| colorDepth | number | 颜色深度 | -| pixelRatio | number | 像素比率 | - -#### AppInfo接口 - -| 字段名 | 类型 | 中文注释 | -| ------------ | -------- | ---------------- | -| id | string | 应用唯一标识符 | -| name | string | 应用名称 | -| version | string | 应用版本号 | -| permissions | string[] | 应用权限列表 | -| createdAt | Date | 应用创建时间 | -| lastActiveAt | Date | 应用最后活跃时间 | - -## 5. 服务层接口字段注释 - -### 5.1 窗体服务接口字段注释 - -#### WindowConfig接口 - -| 字段名 | 类型 | 中文注释 | -| ----------- | -------------- | ------------------ | -| title | string | 窗体标题 | -| width | number | 窗体宽度(像素) | -| height | number | 窗体高度(像素) | -| minWidth | number (可选) | 窗体最小宽度(像素) | -| minHeight | number (可选) | 窗体最小高度(像素) | -| maxWidth | number (可选) | 窗体最大宽度(像素) | -| maxHeight | number (可选) | 窗体最大高度(像素) | -| resizable | boolean (可选) | 是否可调整大小 | -| movable | boolean (可选) | 是否可移动 | -| closable | boolean (可选) | 是否可关闭 | -| minimizable | boolean (可选) | 是否可最小化 | -| maximizable | boolean (可选) | 是否可最大化 | -| modal | boolean (可选) | 是否为模态窗体 | -| alwaysOnTop | boolean (可选) | 是否始终置顶 | -| x | number (可选) | 窗体X坐标位置 | -| y | number (可选) | 窗体Y坐标位置 | - -#### WindowInstance接口 - -| 字段名 | 类型 | 中文注释 | -| --------- | ------------------------ | ------------------ | -| id | string | 窗体唯一标识符 | -| appId | string | 关联应用标识符 | -| config | WindowConfig | 窗体配置信息 | -| state | WindowState | 窗体当前状态 | -| element | HTMLElement (可选) | 窗体DOM元素 | -| iframe | HTMLIFrameElement (可选) | 窗体内嵌iframe元素 | -| zIndex | number | 窗体层级索引 | -| createdAt | Date | 窗体创建时间 | -| updatedAt | Date | 窗体更新时间 | - -## 6. 事件系统接口字段注释 - -### 6.1 事件管理器接口字段注释 - -#### IEventMap接口 - -| 字段名 | 类型 | 中文注释 | -| ------------- | ------------------------ | ---------------- | -| [key: string] | (...args: any[]) => void | 事件处理函数映射 | - -#### IEventBuilder接口 - -该接口定义了事件管理器的基本方法，无需额外字段注释。 - -### 6.2 窗口事件接口字段注释 - -#### IWindowFormEvent接口 - -| 字段名 | 类型 | 中文注释 | -| -------------------- | ------------------------------------------- | ---------------- | -| windowFormMinimize | (id: string) => void | 窗口最小化事件 | -| windowFormMaximize | (id: string) => void | 窗口最大化事件 | -| windowFormRestore | (id: string) => void | 窗口还原事件 | -| windowFormClose | (id: string) => void | 窗口关闭事件 | -| windowFormFocus | (id: string) => void | 窗口聚焦事件 | -| windowFormDataUpdate | (data: IWindowFormDataUpdateParams) => void | 窗口数据更新事件 | -| windowFormCreated | () => void | 窗口创建完成事件 | - -#### IWindowFormDataUpdateParams接口 - -| 字段名 | 类型 | 中文注释 | -| ------ | ---------------- | ----------------- | -| id | string | 窗口唯一标识符 | -| state | TWindowFormState | 窗口状态 | -| width | number | 窗口宽度 | -| height | number | 窗口高度 | -| x | number | 窗口X坐标(左上角) | -| y | number | 窗口Y坐标(左上角) | - -## 7. 应用管理接口字段注释 - -### 7.1 应用清单接口字段注释 - -#### InternalAppManifest接口 - -| 字段名 | 类型 | 中文注释 | -| ----------- | -------------------------------------- | ---------------- | -| id | string | 应用唯一标识符 | -| name | string | 应用名称 | -| version | string | 应用版本号 | -| description | string | 应用描述信息 | -| author | string | 应用作者 | -| icon | string | 应用图标 | -| permissions | string[] | 应用所需权限列表 | -| window | { width: number; height: number; ... } | 窗体配置信息 | -| category | string (可选) | 应用分类 | -| keywords | string[] (可选) | 应用关键字列表 | - -#### AppRegistration接口 - -| 字段名 | 类型 | 中文注释 | -| --------- | ------------------- | -------------- | -| manifest | InternalAppManifest | 应用清单信息 | -| component | any | Vue组件 | -| isBuiltIn | boolean | 是否为内置应用 | - -## 8. UI组件接口字段注释 - -### 8.1 桌面图标接口字段注释 - -#### IDesktopAppIcon接口 - -| 字段名 | 类型 | 中文注释 | -| ------ | ------ | -------------------- | -| name | string | 图标名称 | -| icon | string | 图标内容 | -| path | string | 图标路径 | -| x | number | 图标在grid布局中的列 | -| y | number | 图标在grid布局中的行 | - -### 8.2 网格模板参数接口字段注释 - -#### IGridTemplateParams接口 - -| 字段名 | 类型 | 中文注释 | -| ---------------- | ------ | -------------- | -| cellExpectWidth | number | 单元格预设宽度 | -| cellExpectHeight | number | 单元格预设高度 | -| cellRealWidth | number | 单元格实际宽度 | -| cellRealHeight | number | 单元格实际高度 | -| gapX | number | 列间距 | -| gapY | number | 行间距 | -| colCount | number | 总列数 | -| rowCount | number | 总行数 | - -## 9. 实施计划 - -1. 对SDK模块中的所有接口字段添加中文注释 -2. 对服务层模块中的接口字段添加中文注释 -3. 对事件系统模块中的接口字段添加中文注释 -4. 对应用管理模块中的接口字段添加中文注释 -5. 对UI组件模块中的接口字段添加中文注释 -6. 审查和验证所有注释的准确性和完整性 - -## 10. 注意事项 - -1. 保持原有代码逻辑不变，仅添加注释 -2. 确保注释内容准确反映字段的实际用途 -3. 统一注释风格，避免表述不一致 -4. 对于已有注释的字段，检查并完善注释内容 -5. 在添加注释时注意不要影响代码的可读性 diff --git a/.qoder/quests/api-unified-interface-design.md b/.qoder/quests/api-unified-interface-design.md deleted file mode 100644 index 4b2526a..0000000 --- a/.qoder/quests/api-unified-interface-design.md +++ /dev/null @@ -1,461 +0,0 @@ -# 统一API接口设计文档 - -## 1. 概述 - -### 1.1 目标 - -为iframe中的第三方应用提供一套统一、简洁、类型安全的系统服务访问接口，使应用开发者无需关注底层通信机制，即可直接调用系统功能。 - -### 1.2 核心价值 - -- **简化开发**：封装复杂的跨域通信逻辑，提供类似本地函数调用的体验 -- **类型安全**：完整的TypeScript类型定义，提供编译时检查和IDE智能提示 -- **模块化设计**：按功能划分子模块，便于按需使用和维护 -- **权限控制**：内置权限验证机制，确保系统安全 -- **事件驱动**：支持双向通信，实现系统与应用间的实时交互 - -### 1.3 设计原则 - -1. **透明性**：隐藏底层postMessage通信细节 -2. **一致性**：统一的API响应格式和错误处理机制 -3. **可扩展性**：模块化架构支持功能扩展 -4. **安全性**：严格的权限控制和数据验证 - -## 2. 系统架构 - -### 2.1 整体架构图 - -```mermaid -graph TB - subgraph "主应用(系统)" - A[主应用UI] --> B[沙箱引擎] - B --> C[事件通信服务] - C --> D[系统服务层] - D --> E[窗口管理] - D --> F[存储服务] - D --> G[网络服务] - D --> H[系统服务] - end - - subgraph "子应用(沙箱)" - I[子应用UI] --> J[SDK客户端] - K[业务逻辑] --> J - end - - J --"postMessage"--> B - B --"postMessage"--> J - - style A fill:#e1f5fe - style I fill:#f3e5f5 - style J fill:#f3e5f5 - style B fill:#fff3e0 - style C fill:#fff3e0 - style D fill:#f1f8e9 -``` - -### 2.2 SDK架构 - -```mermaid -classDiagram - class SystemDesktopSDK { - +version: string - +appId: string - +initialized: boolean - +window: WindowSDK - +storage: StorageSDK - +network: NetworkSDK - +events: EventSDK - +ui: UISDK - +system: SystemSDK - +init(config: SDKConfig) Promise~APIResponse~boolean~~ - +destroy() Promise~APIResponse~boolean~~ - +getStatus() Promise~APIResponse~object~~ - } - - class SDKBase { - #appId: string - #initialized: boolean - #sendToSystem(type: string, data: any) Promise~T~ - #wrapResponse(promise: Promise~T~) Promise~APIResponse~T~~ - } - - class WindowSDK { - <> - +setTitle(title: string) Promise~APIResponse~boolean~~ - +resize(width: number, height: number) Promise~APIResponse~boolean~~ - +move(x: number, y: number) Promise~APIResponse~boolean~~ - +minimize() Promise~APIResponse~boolean~~ - +maximize() Promise~APIResponse~boolean~~ - +restore() Promise~APIResponse~boolean~~ - +close() Promise~APIResponse~boolean~~ - +getState() Promise~APIResponse~WindowState~~ - +on(event: string, callback: Function) void - } - - class StorageSDK { - <> - +set(key: string, value: any) Promise~APIResponse~boolean~~ - +get(key: string) Promise~APIResponse~any~~ - +remove(key: string) Promise~APIResponse~boolean~~ - +clear() Promise~APIResponse~boolean~~ - } - - class NetworkSDK { - <> - +request(url: string, config: NetworkRequestConfig) Promise~APIResponse~any~~ - +get(url: string, config: any) Promise~APIResponse~any~~ - +post(url: string, data: any, config: any) Promise~APIResponse~any~~ - } - - class EventSDK { - <> - +emit(channel: string, data: any) Promise~APIResponse~string~~ - +on(channel: string, callback: Function) Promise~APIResponse~string~~ - +off(subscriptionId: string) Promise~APIResponse~boolean~~ - } - - class UISDK { - <> - +showDialog(options: DialogOptions) Promise~APIResponse~object~~ - +showNotification(options: NotificationOptions) Promise~APIResponse~string~~ - +showToast(message: string, type: string) Promise~APIResponse~string~~ - } - - class SystemSDK { - <> - +getSystemInfo() Promise~APIResponse~SystemInfo~~ - +getAppInfo() Promise~APIResponse~AppInfo~~ - +requestPermission(permission: string) Promise~APIResponse~PermissionStatus~~ - } - - SDKBase <|-- SystemDesktopSDK - SystemDesktopSDK --> WindowSDK - SystemDesktopSDK --> StorageSDK - SystemDesktopSDK --> NetworkSDK - SystemDesktopSDK --> EventSDK - SystemDesktopSDK --> UISDK - SystemDesktopSDK --> SystemSDK -``` - -## 3. 核心模块设计 - -### 3.1 窗口管理模块(WindowSDK) - -#### 3.1.1 功能概述 - -提供对应用窗口的控制能力，包括窗口尺寸调整、位置移动、状态切换等。 - -#### 3.1.2 接口定义 - -| 方法 | 描述 | 参数 | 返回值 | -| --------------------- | ------------ | ----------------------------- | --------------------------------- | -| setTitle(title) | 设置窗口标题 | title: string | Promise> | -| resize(width, height) | 调整窗口尺寸 | width: number, height: number | Promise> | -| move(x, y) | 移动窗口位置 | x: number, y: number | Promise> | -| minimize() | 最小化窗口 | 无 | Promise> | -| maximize() | 最大化窗口 | 无 | Promise> | -| restore() | 还原窗口 | 无 | Promise> | -| close() | 关闭窗口 | 无 | Promise> | -| getState() | 获取窗口状态 | 无 | Promise> | - -#### 3.1.3 事件监听 - -```typescript -// 监听窗口变化事件 -SystemSDK.window.on('resize', (width, height) => { - console.log(`窗口尺寸变化: ${width}x${height}`) -}) - -// 移除事件监听 -SystemSDK.window.off('resize') -``` - -### 3.2 存储模块(StorageSDK) - -#### 3.2.1 功能概述 - -提供应用数据的持久化存储能力，支持键值对存储、数据查询、删除等操作。 - -#### 3.2.2 接口定义 - -| 方法 | 描述 | 参数 | 返回值 | -| --------------- | -------------- | ----------------------- | ------------------------------ | -| set(key, value) | 存储数据 | key: string, value: any | Promise> | -| get(key) | 获取数据 | key: string | Promise> | -| remove(key) | 删除数据 | key: string | Promise> | -| clear() | 清空所有数据 | 无 | Promise> | -| keys() | 获取所有键名 | 无 | Promise> | -| has(key) | 检查键是否存在 | key: string | Promise> | - -#### 3.2.3 使用示例 - -```typescript -// 存储数据 -await SystemSDK.storage.set('userSettings', { theme: 'dark', lang: 'zh' }) - -// 获取数据 -const settings = await SystemSDK.storage.get('userSettings') - -// 监听存储变化 -SystemSDK.storage.on('onChange', (key, newValue, oldValue) => { - console.log(`存储变更: ${key} 从 ${oldValue} 变为 ${newValue}`) -}) -``` - -### 3.3 网络模块(NetworkSDK) - -#### 3.3.1 功能概述 - -提供网络请求能力，支持HTTP请求、文件上传下载等操作。 - -#### 3.3.2 接口定义 - -| 方法 | 描述 | 参数 | 返回值 | -| ----------------------- | ------------ | ----------------------------------------- | ------------------------------------- | -| request(url, config) | 发送HTTP请求 | url: string, config: NetworkRequestConfig | Promise> | -| get(url, config) | GET请求 | url: string, config: object | Promise> | -| post(url, data, config) | POST请求 | url: string, data: any, config: object | Promise> | -| upload(url, file) | 上传文件 | url: string, file: File/Blob | Promise> | -| download(url, filename) | 下载文件 | url: string, filename: string | Promise> | - -#### 3.3.3 使用示例 - -```typescript -// 发送GET请求 -const response = await SystemSDK.network.get('https://api.example.com/users') - -// 发送POST请求 -const result = await SystemSDK.network.post('https://api.example.com/users', { - name: '张三', - email: 'zhangsan@example.com', -}) - -// 上传文件 -const fileInput = document.querySelector('input[type="file"]') -if (fileInput.files.length > 0) { - await SystemSDK.network.upload('https://api.example.com/upload', fileInput.files[0]) -} -``` - -### 3.4 事件通信模块(EventSDK) - -#### 3.4.1 功能概述 - -提供应用间以及应用与系统间的事件通信机制，支持广播、点对点通信等模式。 - -#### 3.4.2 接口定义 - -| 方法 | 描述 | 参数 | 返回值 | -| ------------------------- | -------------- | ----------------------------------- | ----------------------------- | -| emit(channel, data) | 发送事件消息 | channel: string, data: any | Promise> | -| on(channel, callback) | 订阅事件频道 | channel: string, callback: Function | Promise> | -| off(subscriptionId) | 取消订阅 | subscriptionId: string | Promise> | -| broadcast(channel, data) | 广播消息 | channel: string, data: any | Promise> | -| sendTo(targetAppId, data) | 发送点对点消息 | targetAppId: string, data: any | Promise> | - -#### 3.4.3 使用示例 - -```typescript -// 订阅事件 -const subscriptionId = await SystemSDK.events.on('user-login', (message) => { - console.log('用户登录:', message.data) -}) - -// 发送事件 -await SystemSDK.events.emit('user-action', { action: 'click', target: 'button1' }) - -// 取消订阅 -await SystemSDK.events.off(subscriptionId) -``` - -### 3.5 UI交互模块(UISDK) - -#### 3.5.1 功能概述 - -提供系统级UI交互能力，如对话框、通知、文件选择器等。 - -#### 3.5.2 接口定义 - -| 方法 | 描述 | 参数 | 返回值 | -| ------------------------- | -------------- | ----------------------------- | ------------------------------ | -| showDialog(options) | 显示对话框 | options: DialogOptions | Promise> | -| showNotification(options) | 显示通知 | options: NotificationOptions | Promise> | -| showFilePicker(options) | 显示文件选择器 | options: FilePickerOptions | Promise> | -| showToast(message, type) | 显示Toast消息 | message: string, type: string | Promise> | - -#### 3.5.3 使用示例 - -```typescript -// 显示确认对话框 -const result = await SystemSDK.ui.showDialog({ - title: '确认操作', - message: '确定要删除这个文件吗？', - type: 'confirm', - buttons: ['取消', '确定'], -}) - -if (result.data.buttonIndex === 1) { - // 用户点击了确定 - console.log('用户确认删除') -} - -// 显示通知 -await SystemSDK.ui.showNotification({ - title: '操作完成', - body: '文件已成功上传', - icon: '/icons/success.png', -}) -``` - -### 3.6 系统信息模块(SystemSDK) - -#### 3.6.1 功能概述 - -提供系统信息查询和基础系统操作能力。 - -#### 3.6.2 接口定义 - -| 方法 | 描述 | 参数 | 返回值 | -| ----------------------------- | ---------------- | ------------------ | -------------------------------------- | -| getSystemInfo() | 获取系统信息 | 无 | Promise> | -| getAppInfo() | 获取当前应用信息 | 无 | Promise> | -| requestPermission(permission) | 请求权限 | permission: string | Promise> | -| getClipboard() | 获取剪贴板内容 | 无 | Promise> | -| setClipboard(text) | 设置剪贴板内容 | text: string | Promise> | -| openExternal(url) | 打开外部链接 | url: string | Promise> | - -## 4. 通信机制设计 - -### 4.1 消息协议 - -```mermaid -sequenceDiagram - participant A as 子应用SDK - participant B as 主应用沙箱引擎 - participant C as 系统服务 - - A->>B: postMessage(sdk:call, method, data) - B->>C: 调用相应系统服务 - C-->>B: 返回处理结果 - B-->>A: postMessage(system:response, data) -``` - -### 4.2 消息格式 - -```typescript -// SDK调用消息格式 -{ - type: 'sdk:call', - requestId: string, // 唯一请求ID - method: string, // 调用方法路径，如 "window.setTitle" - data: any, // 传递的数据 - appId: string // 应用ID -} - -// 系统响应消息格式 -{ - type: 'system:response', - requestId: string, // 对应的请求ID - success: boolean, // 是否成功 - data: any, // 成功时的数据 - error: string // 失败时的错误信息 -} -``` - -### 4.3 错误处理机制 - -```typescript -// 统一响应格式 -interface APIResponse { - success: boolean // 是否成功 - data?: T // 成功时的数据 - error?: string // 错误信息 - code?: number // 错误码 -} -``` - -## 5. 权限控制设计 - -### 5.1 权限模型 - -系统采用基于功能的权限控制模型，应用需要在初始化时声明所需权限。 - -### 5.2 权限类型 - -| 权限名称 | 描述 | 敏感级别 | -| ------------------- | -------------- | -------- | -| window.control | 窗口控制权限 | 中 | -| storage.read | 存储读取权限 | 低 | -| storage.write | 存储写入权限 | 中 | -| network.request | 网络请求权限 | 中 | -| event.broadcast | 事件广播权限 | 中 | -| system.clipboard | 剪贴板访问权限 | 高 | -| system.notification | 通知权限 | 低 | - -### 5.3 权限申请流程 - -```mermaid -flowchart TD - A[应用初始化] --> B{权限检查} - B -->|权限已授予| C[正常运行] - B -->|权限未授予| D[请求权限] - D --> E[用户授权] - E -->|允许| C - E -->|拒绝| F[限制功能] -``` - -## 6. 使用指南 - -### 6.1 SDK初始化 - -```typescript -// 初始化SDK -const result = await SystemSDK.init({ - appId: 'com.example.myapp', - appName: '我的应用', - version: '1.0.0', - permissions: ['storage.read', 'storage.write', 'network.request'], -}) - -if (result.success) { - console.log('SDK初始化成功') -} else { - console.error('SDK初始化失败:', result.error) -} -``` - -### 6.2 功能调用示例 - -```typescript -// 设置窗口标题 -await SystemSDK.window.setTitle('我的应用 - 主界面') - -// 存储用户数据 -await SystemSDK.storage.set('userData', { name: '张三', age: 25 }) - -// 发送网络请求 -const response = await SystemSDK.network.get('/api/user/profile') - -// 显示通知 -await SystemSDK.ui.showNotification({ - title: '数据加载完成', - body: '用户信息已更新', -}) -``` - -### 6.3 事件监听示例 - -```typescript -// 监听窗口关闭事件 -SystemSDK.window.on('close', async () => { - // 保存应用状态 - await SystemSDK.storage.set('appState', getCurrentState()) - console.log('应用状态已保存') -}) - -// 监听系统主题变化 -SystemSDK.system.on('themeChange', (theme) => { - // 更新应用主题 - updateAppTheme(theme) -}) -``` diff --git a/.qoder/quests/module-dependency-analysis.md b/.qoder/quests/module-dependency-analysis.md deleted file mode 100644 index 55f9397..0000000 --- a/.qoder/quests/module-dependency-analysis.md +++ /dev/null @@ -1,144 +0,0 @@ -# 模块依赖分析：EventCommunicationService 与 EventBuilderImpl 关系 - -## 概述 - -本文档旨在分析 Vue Desktop 项目中 [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 与 [EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 的关系，明确它们各自的职责以及是否需要同时存在这两个组件。 - -## 系统架构概览 - -Vue Desktop 使用分层的事件管理系统： - -1. 内部事件总线 ([EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95)) - 处理组件间的直接通信 -2. 应用间通信服务 ([EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638)) - 处理跨应用/模块的复杂消息传递 - -## 模块详细分析 - -### EventBuilderImpl 分析 - -[EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 是一个通用的事件管理器实现，提供了基础的发布/订阅模式功能： - -#### 主要职责 - -- 提供简单的事件监听(addEventListener)和触发(notifyEvent)机制 -- 支持一次性事件监听(once选项) -- 支持立即执行(immediate选项) -- 实现 [IEventBuilder](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\IEventBuilder.ts#L1-L28) 接口 - -#### 特点 - -- 轻量级，适用于组件内部通信 -- 不涉及消息队列、优先级、过期时间等复杂概念 -- 基于回调函数直接调用 - -### EventCommunicationService 分析 - -[EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 是一个高级消息通信系统，用于处理复杂的跨应用通信场景： - -#### 主要职责 - -- 管理应用间的事件订阅和消息传递 -- 实现消息优先级、过期时间、重试机制等功能 -- 提供频道管理和权限控制 -- 支持广播和点对点消息 -- 维护消息历史和统计数据 - -#### 特点 - -- 功能丰富，支持复杂的消息路由和处理 -- 异步处理消息队列 -- 提供消息持久化和统计功能 -- 支持权限验证和消息过滤 - -## 依赖关系分析 - -### 架构层级 - -```mermaid -graph TD - A[SystemServiceIntegration] --> B[EventCommunicationService] - A --> C[WindowFormService] - A --> D[ResourceService] - - B --> E[IEventBuilder] - C --> E - - F[EventBuilderImpl] -.-> E -``` - -### 依赖说明 - -1. [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 依赖 [IEventBuilder](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\IEventBuilder.ts#L1-L28) 接口，但不直接依赖具体实现 -2. [EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 是 [IEventBuilder](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\IEventBuilder.ts#L1-L28) 的具体实现之一 -3. [SystemServiceIntegration](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\SystemServiceIntegration.ts#L36-L597) 同时使用 [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 和其他服务，并传入 [EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 实例 - -## 是否需要 EventBuilderImpl？ - -### 结论 - -**是的，项目仍然需要 [EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95)**。 - -### 原因分析 - -1. **职责分离**： - - [EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 处理组件内简单事件通信 - - [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 处理跨应用复杂消息传递 - -2. **性能考虑**： - - 内部组件通信不需要 [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 的复杂特性 - - [EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 提供轻量级解决方案 - -3. **架构清晰性**： - - 保持两种不同层次的事件通信机制有助于维护架构清晰性 - - 避免将所有事件都通过复杂的消息系统传递 - -## 正确的类型使用 - -### EventCommunicationService 中的类型 - -在 [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 构造函数中，应该使用接口而不是具体实现： - -```typescript -constructor(eventBus: IEventBuilder) -``` - -### SystemServiceIntegration 中的类型 - -在 [SystemServiceIntegration](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\SystemServiceIntegration.ts#L36-L597) 中，需要创建 [EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 实例并将其注入到依赖它的服务中： - -```typescript -private eventBus: IEventBuilder - -constructor(config: SystemServiceConfig = {}) { - // 使用具体实现创建实例 - this.eventBus = new EventBuilderImpl() - - // 注入到依赖的服务中 - // EventCommunicationService 需要 IEventBuilder 接口 - // WindowFormService 也需要 IEventBuilder 接口 -} -``` - -## 推荐实践 - -### 类型声明建议 - -对于 [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 和其他服务： - -```typescript -// 接受接口而非具体实现 -constructor(eventBus: IEventBuilder) -``` - -### 实例化建议 - -在 [SystemServiceIntegration](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\SystemServiceIntegration.ts#L36-L597) 中： - -```typescript -// 创建具体实例 -private eventBus: IEventBuilder -this.eventBus = new EventBuilderImpl() -``` - -## 总结 - -[EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 和 [EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 在系统中有不同的职责，两者都是必要的。[EventBuilderImpl](file://c:\Users\98354\Desktop\develop\vue-desktop\src\events\impl\EventBuilderImpl.ts#L7-L95) 提供基础事件机制，[EventCommunicationService](file://c:\Users\98354\Desktop\develop\vue-desktop\src\services\EventCommunicationService.ts#L95-L638) 提供高级消息通信功能。在类型使用上，应遵循依赖倒置原则，服务依赖接口而非具体实现。 diff --git a/.qoder/quests/music-player-error-handling.md b/.qoder/quests/music-player-error-handling.md deleted file mode 100644 index e69de29..0000000 diff --git a/.qoder/quests/project-code-optimization.md b/.qoder/quests/project-code-optimization.md deleted file mode 100644 index 8aa8e21..0000000 --- a/.qoder/quests/project-code-optimization.md +++ /dev/null @@ -1,244 +0,0 @@ -# Vue Desktop 项目代码优化设计文档 - -## 1. 概述 - -本文档旨在分析 Vue Desktop 项目的现有代码结构，识别无用或冗余的代码，并提出优化方案。通过去除无用代码，提高项目可维护性、减少包体积、提升性能。 - -## 2. 项目架构分析 - -### 2.1 当前架构概览 - -Vue Desktop 采用模块化架构，主要包含以下核心模块： - -```mermaid -graph TD - A[主应用] --> B[服务层] - A --> C[UI层] - A --> D[事件系统] - A --> E[应用注册中心] - - B --> B1[WindowFormService] - B --> B2[ResourceService] - B --> B3[EventCommunicationService] - B --> B4[ApplicationSandboxEngine] - B --> B5[ApplicationLifecycleManager] - B --> B6[ExternalAppDiscovery] - - C --> C1[DesktopContainer] - C --> C2[AppIcon] - C --> C3[AppRenderer] - - D --> D1[EventManager] - D --> D2[WindowFormEventManager] - - E --> E1[内置应用] - E --> E2[外部应用] -``` - -### 2.2 核心模块职责 - -| 模块 | 职责 | -| --------------------------- | ---------------------------------- | -| WindowFormService | 管理应用窗体的创建、销毁、状态控制 | -| ResourceService | 管理应用资源访问权限和存储 | -| EventCommunicationService | 处理应用间通信 | -| ApplicationSandboxEngine | 为外部应用创建安全沙箱环境 | -| ApplicationLifecycleManager | 管理应用的完整生命周期 | -| ExternalAppDiscovery | 自动发现和注册外部应用 | -| DesktopContainer | 桌面容器，管理应用图标布局 | -| AppIcon | 应用图标组件，支持拖拽和双击启动 | -| AppRenderer | 渲染内置应用的组件 | - -## 3. 无用代码识别与分析 - -### 3.1 重复导入和未使用导入 - -在多个文件中存在重复导入或未使用的导入语句，增加了不必要的代码体积。 - -### 3.2 冗余功能实现 - -1. **重复的应用发现机制**： - - `ExternalAppDiscovery` 和 `AppRegistry` 都负责应用注册，但职责不清晰 - - 外部应用发现服务中存在多种扫描策略，但实际只使用一种 - -2. **重复的状态管理**： - - 多个服务中维护了相似的状态管理逻辑 - - 事件系统存在多层封装但使用不一致 - -### 3.3 未使用的组件和方法 - -1. **未使用的UI组件**： - - `SystemStatus` 组件在桌面容器中定义但使用有限 - - 部分样式和功能未被实际使用 - -2. **未使用的服务方法**： - - `ApplicationLifecycleManager` 中的部分生命周期方法未被调用 - - `ExternalAppDiscovery` 中的测试和调试方法可以移除 - -### 3.4 过度工程化 - -1. **复杂的沙箱实现**： - - 对于内置应用不需要沙箱，但代码中仍存在相关处理逻辑 - - 沙箱安全级别设置过于复杂，实际使用中只用到部分配置 - -2. **冗余的事件系统**： - - 存在多套事件管理机制，增加了复杂性 - - 部分事件监听器未正确清理，可能导致内存泄漏 - -## 4. 优化方案设计 - -### 4.1 代码清理策略 - -#### 4.1.1 移除未使用的导入和变量 - -```mermaid -graph LR - A[扫描代码] --> B[识别未使用导入] - B --> C[移除未使用导入] - A --> D[识别未使用变量] - D --> E[移除未使用变量] - C --> F[代码重构] - E --> F -``` - -#### 4.1.2 清理冗余功能 - -1. **统一应用注册机制**： - - 明确区分内置应用和外部应用的注册方式 - - 移除重复的应用发现逻辑 - -2. **简化沙箱实现**： - - 仅对外部应用创建沙箱 - - 移除内置应用的沙箱相关代码 - -### 4.2 模块重构方案 - -#### 4.2.1 服务层优化 - -```mermaid -graph TD - A[服务层重构] --> B[合并相似功能] - A --> C[移除冗余方法] - A --> D[优化依赖关系] - - B --> B1[统一状态管理] - B --> B2[合并事件处理] - - C --> C1[移除未调用方法] - C --> C2[简化接口设计] - - D --> D1[明确依赖关系] - D --> D2[减少循环依赖] -``` - -#### 4.2.2 UI层优化 - -1. **组件精简**： - - 移除未使用的系统状态组件 - - 合并功能相似的UI组件 - -2. **样式优化**： - - 移除未使用的CSS类和样式 - - 统一设计风格和组件样式 - -### 4.3 性能优化措施 - -#### 4.3.1 减少内存占用 - -1. **优化事件监听器**： - - 确保所有事件监听器在组件销毁时正确移除 - - 使用弱引用避免循环引用 - -2. **优化数据结构**： - - 使用更高效的数据结构存储应用信息 - - 减少不必要的响应式数据 - -#### 4.3.2 提升加载性能 - -1. **懒加载优化**： - - 对非核心功能采用懒加载 - - 优化应用启动流程 - -2. **资源优化**： - - 压缩和合并静态资源 - - 移除未使用的资源文件 - -## 5. 详细优化实施计划 - -### 5.1 第一阶段：代码清理 (1-2天) - -| 任务 | 描述 | 预期效果 | -| -------------- | --------------------------------- | ---------------- | -| 移除未使用导入 | 扫描并移除所有未使用的导入语句 | 减少代码体积 | -| 清理未使用变量 | 识别并移除未使用的变量和方法 | 提高代码可读性 | -| 移除调试代码 | 清理所有console.log和调试相关代码 | 减少生产环境代码 | - -### 5.2 第二阶段：功能重构 (3-5天) - -| 任务 | 描述 | 预期效果 | -| ------------ | -------------------------- | ---------------- | -| 统一应用注册 | 明确内置和外部应用注册机制 | 简化应用管理 | -| 简化沙箱实现 | 仅对外部应用创建沙箱 | 减少复杂性 | -| 优化事件系统 | 合并冗余事件处理逻辑 | 提高事件处理效率 | - -### 5.3 第三阶段：性能优化 (2-3天) - -| 任务 | 描述 | 预期效果 | -| ------------ | ---------------------- | ---------------- | -| 内存泄漏修复 | 确保事件监听器正确清理 | 减少内存占用 | -| 加载性能优化 | 优化应用启动和资源加载 | 提升用户体验 | -| 打包优化 | 配置代码分割和懒加载 | 减少初始加载时间 | - -## 6. 风险评估与缓解措施 - -### 6.1 潜在风险 - -1. **功能丢失风险**： - - 移除代码时可能误删仍在使用的功能 - - 解决方案：建立完整的测试用例，确保核心功能不受影响 - -2. **兼容性问题**： - - 重构可能影响现有外部应用的兼容性 - - 解决方案：保持API接口稳定，提供迁移指南 - -3. **性能回退**： - - 优化过程中可能引入新的性能问题 - - 解决方案：进行充分的性能测试和监控 - -### 6.2 缓解措施 - -1. **建立测试保障**： - - 完善单元测试和集成测试 - - 建立回归测试机制 - -2. **渐进式重构**： - - 采用小步快跑的方式进行重构 - - 每次重构后进行充分测试 - -3. **文档更新**： - - 及时更新相关技术文档 - - 记录重要的设计变更 - -## 7. 验证标准 - -### 7.1 代码质量指标 - -| 指标 | 优化前 | 优化后目标 | -| -------- | --------- | ---------- | -| 代码行数 | 约15000行 | 减少15-20% | -| 包体积 | 约5MB | 减少10-15% | -| 内存占用 | 约200MB | 减少10-20% | - -### 7.2 性能指标 - -| 指标 | 优化前 | 优化后目标 | -| ------------ | ------ | ---------- | -| 初始加载时间 | 3-5秒 | 减少20-30% | -| 应用启动时间 | 1-2秒 | 减少15-25% | -| 内存泄漏 | 存在 | 完全消除 | - -## 8. 总结 - -通过对 Vue Desktop 项目的全面分析，我们识别出多个可以优化的方面，包括代码清理、功能重构和性能优化。实施这些优化措施将显著提高项目的可维护性、减少包体积、提升运行性能，同时保持功能完整性。 - -优化工作将分阶段进行，确保在提升代码质量的同时不影响现有功能。通过建立完善的测试和验证机制，我们可以有效控制风险，确保优化工作的成功实施。 diff --git a/.qoder/quests/system-business-decoupling-design.md b/.qoder/quests/system-business-decoupling-design.md deleted file mode 100644 index b4cea10..0000000 --- a/.qoder/quests/system-business-decoupling-design.md +++ /dev/null @@ -1,623 +0,0 @@ -# 系统与业务解耦架构设计 - -## 概述 - -本设计旨在构建一个高性能的类Windows桌面前端系统，实现系统框架与业务应用的完全解耦。系统提供统一的桌面环境、窗体管理和资源访问控制，而业务应用通过标准化的SDK接口进行开发，确保双方独立演进且相互不影响。 - -### 核心设计原则 - -- **完全隔离**：系统与应用在运行时完全隔离，应用无法直接访问系统资源 -- **标准化接口**：通过统一的SDK提供标准化的系统服务接口 -- **性能优先**：采用微前端沙箱、虚拟化渲染等技术确保高性能 -- **框架无关**：支持任意前端框架开发的第三方应用 -- **安全可控**：严格的权限控制和安全沙箱机制 - -## 整体架构 - -### 系统分层架构 - -```mermaid -graph TB - subgraph "用户界面层" - Desktop[桌面容器] - WindowManager[窗体管理器] - TaskBar[任务栏] - SystemUI[系统UI组件] - end - - subgraph "系统服务层" - WindowFormService[窗体服务] - ResourceService[资源服务] - EventService[事件服务] - SecurityService[安全服务] - StorageService[存储服务] - end - - subgraph "应用运行时层" - AppContainer[应用容器] - SandboxEngine[沙箱引擎] - SDKBridge[SDK桥接层] - AppLifecycle[应用生命周期] - end - - subgraph "第三方应用" - App1[业务应用A] - App2[业务应用B] - App3[业务应用C] - end - - Desktop --> WindowManager - WindowManager --> WindowFormService - AppContainer --> SandboxEngine - SDKBridge --> SystemService[系统服务层] - App1 --> AppContainer - App2 --> AppContainer - App3 --> AppContainer -``` - -### 核心组件职责 - -| 组件 | 职责 | 接口类型 | -| ---------- | -------------------------- | -------- | -| 桌面容器 | 管理应用图标、布局和交互 | 系统内部 | -| 窗体管理器 | 窗体创建、管理、切换和销毁 | 系统内部 | -| 应用容器 | 第三方应用运行环境隔离 | 对外SDK | -| 沙箱引擎 | 安全隔离和权限控制 | 系统内部 | -| SDK桥接层 | 系统服务的标准化接口 | 对外SDK | - -## 系统核心服务 - -### 窗体管理服务 - -窗体管理服务负责所有窗体的生命周期管理，提供统一的窗体操作接口。 - -#### 窗体生命周期 - -```mermaid -stateDiagram-v2 - [*] --> Creating: 创建窗体 - Creating --> Loading: 加载应用 - Loading --> Active: 激活显示 - Active --> Minimized: 最小化 - Minimized --> Active: 恢复显示 - Active --> Maximized: 最大化 - Maximized --> Active: 还原 - Active --> Closing: 关闭请求 - Closing --> Destroyed: 销毁完成 - Destroyed --> [*] - - Loading --> Error: 加载失败 - Error --> Destroyed: 错误处理 -``` - -#### 窗体服务接口规范 - -| 服务方法 | 参数 | 返回值 | 描述 | -| -------------- | ----------------------- | -------------- | ------------ | -| createWindow | appId, config | WindowFormInstance | 创建新窗体 | -| destroyWindow | windowId | boolean | 销毁指定窗体 | -| minimizeWindow | windowId | boolean | 最小化窗体 | -| maximizeWindow | windowId | boolean | 最大化窗体 | -| restoreWindow | windowId | boolean | 还原窗体 | -| setWindowTitle | windowId, title | boolean | 设置窗体标题 | -| setWindowSize | windowId, width, height | boolean | 设置窗体尺寸 | - -### 资源管理服务 - -资源管理服务提供统一的系统资源访问控制，确保应用只能通过授权访问系统资源。 - -#### 资源访问控制矩阵 - -| 资源类型 | 默认权限 | 申请方式 | 审批流程 | -| ------------ | ------------ | -------- | -------- | -| 本地存储 | 应用独立空间 | 配置声明 | 自动授权 | -| 网络请求 | 白名单域名 | 动态申请 | 用户确认 | -| 文件系统 | 禁止访问 | 动态申请 | 用户确认 | -| 系统通知 | 禁止发送 | 动态申请 | 用户确认 | -| 剪贴板 | 禁止访问 | 动态申请 | 用户确认 | -| 摄像头麦克风 | 禁止访问 | 动态申请 | 用户确认 | - -### 事件通信服务 - -提供系统级别的事件通信机制，支持应用间消息传递和系统事件监听。 - -#### 事件分类与权限 - -```mermaid -graph LR - subgraph "系统事件" - SE1[窗体状态变化] - SE2[主题切换] - SE3[网络状态变化] - SE4[系统资源变化] - end - - subgraph "应用事件" - AE1[应用间消息] - AE2[应用状态同步] - AE3[数据共享请求] - end - - subgraph "用户事件" - UE1[用户交互] - UE2[快捷键触发] - UE3[拖拽操作] - end - - SE1 --> 只读监听 - SE2 --> 只读监听 - AE1 --> 权限验证 - AE2 --> 权限验证 - UE1 --> 应用内处理 -``` - -## 应用沙箱机制 - -### 沙箱隔离策略 - -应用运行在完全隔离的沙箱环境中，通过多重隔离机制确保安全性。 - -#### 沙箱隔离层次 - -```mermaid -graph TD - subgraph "物理隔离层" - IFrame[IFrame容器] - ShadowDOM[Shadow DOM] - CSP[内容安全策略] - end - - subgraph "逻辑隔离层" - Namespace[命名空间隔离] - Memory[内存隔离] - Storage[存储隔离] - end - - subgraph "网络隔离层" - CORS[跨域限制] - Proxy[代理拦截] - Whitelist[白名单过滤] - end - - subgraph "API隔离层" - SDKProxy[SDK代理] - Permission[权限验证] - Audit[审计日志] - end - - IFrame --> Namespace - ShadowDOM --> Memory - CSP --> Storage - Namespace --> SDKProxy - Memory --> Permission - Storage --> Audit -``` - -### 沙箱性能优化 - -#### 虚拟化渲染机制 - -```mermaid -flowchart TD - Start[应用启动] --> CheckCache{检查缓存} - CheckCache -->|存在| LoadCache[加载缓存实例] - CheckCache -->|不存在| CreateSandbox[创建沙箱] - - CreateSandbox --> PreloadResources[预加载资源] - PreloadResources --> InitSDK[初始化SDK] - InitSDK --> MountApp[挂载应用] - - LoadCache --> ValidateCache{验证缓存有效性} - ValidateCache -->|有效| RestoreApp[恢复应用状态] - ValidateCache -->|无效| CreateSandbox - - MountApp --> AppReady[应用就绪] - RestoreApp --> AppReady - - AppReady --> Monitor[性能监控] - Monitor --> OptimizeMemory[内存优化] - OptimizeMemory --> CheckIdle{检查空闲状态} - CheckIdle -->|空闲| SuspendApp[挂起应用] - CheckIdle -->|活跃| Monitor - - SuspendApp --> CheckActivate{检查激活请求} - CheckActivate -->|激活| RestoreApp - CheckActivate -->|继续空闲| SuspendApp -``` - -## SDK接口设计 - -### SDK架构组成 - -SDK作为应用与系统间的唯一通信桥梁，提供完整的系统服务接口。 - -#### SDK模块划分 - -| 模块名称 | 功能描述 | 主要接口 | -| ----------- | -------- | --------------------------------------- | -| WindowSDK | 窗体操作 | setTitle, resize, minimize, maximize | -| StorageSDK | 数据存储 | get, set, remove, clear | -| EventSDK | 事件通信 | emit, on, off, broadcast | -| UISDK | UI组件 | showDialog, showNotification, showToast | -| NetworkSDK | 网络请求 | request, upload, download | -| ResourceSDK | 资源访问 | getFile, saveFile, getClipboard | - -### SDK使用示例 - -#### 窗体操作SDK - -```typescript -// 应用中使用窗体SDK的示例 -interface WindowSDK { - // 设置窗体标题 - setTitle(title: string): Promise - - // 调整窗体尺寸 - resize(width: number, height: number): Promise - - // 最小化窗体 - minimize(): Promise - - // 最大化窗体 - maximize(): Promise - - // 监听窗体状态变化 - onStateChange(callback: (state: WindowState) => void): void -} -``` - -#### 存储服务SDK - -```typescript -// 应用存储SDK接口定义 -interface StorageSDK { - // 存储数据 - set(key: string, value: any): Promise - - // 获取数据 - get(key: string): Promise - - // 删除数据 - remove(key: string): Promise - - // 清空存储 - clear(): Promise - - // 监听存储变化 - onChanged(callback: (key: string, newValue: any, oldValue: any) => void): void -} -``` - -### SDK权限控制机制 - -#### 权限申请流程 - -```mermaid -sequenceDiagram - participant App as 第三方应用 - participant SDK as SDK桥接层 - participant Security as 安全服务 - participant User as 用户界面 - participant System as 系统服务 - - App->>SDK: 调用需权限的API - SDK->>Security: 检查权限状态 - - alt 已授权 - Security->>SDK: 返回已授权 - SDK->>System: 调用系统服务 - System->>SDK: 返回执行结果 - SDK->>App: 返回结果 - else 未授权 - Security->>User: 显示权限申请弹窗 - User->>Security: 用户确认/拒绝 - alt 用户同意 - Security->>SDK: 授权通过 - SDK->>System: 调用系统服务 - System->>SDK: 返回执行结果 - SDK->>App: 返回结果 - else 用户拒绝 - Security->>SDK: 权限被拒绝 - SDK->>App: 返回权限错误 - end - end -``` - -## 应用生命周期管理 - -### 应用状态管理 - -应用在系统中具有完整的生命周期管理，确保资源的合理分配和回收。 - -#### 应用状态转换图 - -```mermaid -stateDiagram-v2 - [*] --> Installing: 安装应用 - Installing --> Installed: 安装完成 - Installing --> InstallFailed: 安装失败 - InstallFailed --> [*] - - Installed --> Starting: 启动应用 - Starting --> Running: 运行中 - Starting --> StartFailed: 启动失败 - StartFailed --> Installed - - Running --> Suspended: 挂起 - Suspended --> Running: 恢复 - Running --> Stopping: 停止 - Stopping --> Installed: 已停止 - - Installed --> Uninstalling: 卸载应用 - Uninstalling --> [*]: 卸载完成 -``` - -### 应用资源管理 - -#### 内存管理策略 - -| 应用状态 | 内存策略 | 清理时机 | 恢复方式 | -| ---------- | -------------- | -------- | ---------- | -| Running | 完整内存保持 | 不清理 | 无需恢复 | -| Suspended | 压缩非关键数据 | 5分钟后 | 延迟加载 | -| Background | 最小化内存占用 | 立即清理 | 重新初始化 | -| Stopped | 完全释放内存 | 立即清理 | 完整重启 | - -#### 性能监控指标 - -```mermaid -graph LR - subgraph "性能指标" - CPU[CPU使用率] - Memory[内存占用] - Network[网络请求] - Render[渲染性能] - end - - subgraph "监控阈值" - CPULimit[CPU < 30%] - MemoryLimit[内存 < 100MB] - NetworkLimit[请求 < 10/s] - RenderLimit[FPS > 30] - end - - subgraph "优化策略" - Throttle[请求节流] - Cache[智能缓存] - Lazy[懒加载] - Virtual[虚拟滚动] - end - - CPU --> CPULimit - Memory --> MemoryLimit - Network --> NetworkLimit - Render --> RenderLimit - - CPULimit --> Throttle - MemoryLimit --> Cache - NetworkLimit --> Throttle - RenderLimit --> Virtual -``` - -## 数据流架构 - -### 系统数据流 - -系统采用单向数据流架构，确保数据的一致性和可追踪性。 - -#### 数据流向图 - -```mermaid -flowchart TD - subgraph "系统层" - SystemStore[系统状态存储] - SystemEvents[系统事件总线] - SystemServices[系统服务] - end - - subgraph "应用层" - AppState[应用状态] - AppEvents[应用事件] - AppSDK[应用SDK] - end - - subgraph "界面层" - SystemUI[系统界面] - AppUI[应用界面] - end - - SystemStore --> SystemUI - SystemEvents --> SystemUI - SystemServices --> AppSDK - AppSDK --> AppState - AppState --> AppUI - AppEvents --> SystemEvents - - SystemUI --> SystemEvents - AppUI --> AppEvents -``` - -### 跨应用数据共享 - -#### 数据共享权限模型 - -```mermaid -graph TB - subgraph "数据提供者" - ProviderApp[应用A] - DataExport[导出数据接口] - Permission[权限配置] - end - - subgraph "系统中介" - DataBroker[数据代理服务] - PermissionCheck[权限验证] - DataTransform[数据转换] - end - - subgraph "数据消费者" - ConsumerApp[应用B] - DataImport[导入数据接口] - DataValidation[数据验证] - end - - ProviderApp --> DataExport - DataExport --> DataBroker - Permission --> PermissionCheck - DataBroker --> PermissionCheck - PermissionCheck --> DataTransform - DataTransform --> DataImport - DataImport --> ConsumerApp - DataImport --> DataValidation -``` - -## 部署与运维 - -### 应用分发机制 - -系统支持多种应用分发方式，确保第三方应用的便捷接入。 - -#### 应用打包规范 - -| 文件类型 | 必需性 | 描述 | 示例 | -| ------------- | ------ | ------------ | -------------------------- | -| manifest.json | 必需 | 应用清单文件 | 包含应用基本信息、权限需求 | -| index.html | 必需 | 应用入口文件 | 应用主页面 | -| assets/ | 可选 | 静态资源目录 | CSS、图片、字体等 | -| sdk/ | 可选 | SDK依赖文件 | 如需离线使用SDK | - -#### 应用安装流程 - -```mermaid -flowchart TD - Upload[上传应用包] --> Validate[验证应用包] - Validate --> Extract[解压应用文件] - Extract --> ScanSecurity[安全扫描] - ScanSecurity --> CheckPermission[权限检查] - CheckPermission --> RegisterApp[注册应用] - RegisterApp --> CreateSandbox[创建沙箱环境] - CreateSandbox --> InstallComplete[安装完成] - - Validate -->|验证失败| InstallFailed[安装失败] - ScanSecurity -->|安全风险| InstallFailed - CheckPermission -->|权限过度| UserConfirm[用户确认] - UserConfirm -->|同意| RegisterApp - UserConfirm -->|拒绝| InstallFailed -``` - -### 系统监控与日志 - -#### 监控体系架构 - -```mermaid -graph TB - subgraph "数据采集层" - AppMetrics[应用性能指标] - SystemMetrics[系统性能指标] - UserActions[用户行为数据] - ErrorLogs[错误日志] - end - - subgraph "数据处理层" - DataAggregator[数据聚合器] - AlertEngine[告警引擎] - Analytics[分析引擎] - end - - subgraph "展示层" - Dashboard[监控面板] - Reports[性能报告] - Alerts[告警通知] - end - - AppMetrics --> DataAggregator - SystemMetrics --> DataAggregator - UserActions --> Analytics - ErrorLogs --> AlertEngine - - DataAggregator --> Dashboard - Analytics --> Reports - AlertEngine --> Alerts -``` - -## 安全机制 - -### 多层安全防护 - -系统采用多层安全防护机制，确保系统和应用的安全运行。 - -#### 安全防护体系 - -| 防护层级 | 防护措施 | 防护目标 | -| -------- | ------------------ | -------- | -| 网络层 | HTTPS强制、CSP策略 | 传输安全 | -| 应用层 | 沙箱隔离、权限控制 | 运行安全 | -| 数据层 | 加密存储、访问控制 | 数据安全 | -| 用户层 | 身份验证、操作审计 | 使用安全 | - -### 权限管理系统 - -#### 权限分级模型 - -```mermaid -graph TD - subgraph "系统权限" - SysAdmin[系统管理员] - SysOperator[系统操作员] - SysUser[系统用户] - end - - subgraph "应用权限" - AppOwner[应用所有者] - AppUser[应用用户] - AppGuest[应用访客] - end - - subgraph "资源权限" - ReadOnly[只读权限] - ReadWrite[读写权限] - FullControl[完全控制] - end - - SysAdmin --> FullControl - SysOperator --> ReadWrite - SysUser --> ReadOnly - - AppOwner --> FullControl - AppUser --> ReadWrite - AppGuest --> ReadOnly -``` - -## 性能优化策略 - -### 渲染性能优化 - -#### 虚拟化渲染机制 - -```mermaid -flowchart TD - ViewportDetection[视口检测] --> VisibilityCheck{可见性检查} - VisibilityCheck -->|可见| RenderApp[渲染应用] - VisibilityCheck -->|不可见| SuspendRender[暂停渲染] - - RenderApp --> FrameOptimization[帧率优化] - FrameOptimization --> RequestAnimationFrame[RAF调度] - RequestAnimationFrame --> RenderComplete[渲染完成] - - SuspendRender --> MemoryCleanup[内存清理] - MemoryCleanup --> LowPowerMode[低功耗模式] - - RenderComplete --> ViewportDetection - LowPowerMode --> ViewportDetection -``` - -### 内存管理优化 - -#### 智能内存回收策略 - -| 回收时机 | 回收对象 | 回收策略 | 恢复方式 | -| ---------- | ------------- | ----------- | ------------ | -| 应用切换时 | 非活跃应用DOM | 延迟5秒回收 | 重新渲染 | -| 内存告警时 | 缓存数据 | LRU算法清理 | 重新请求 | -| 长时间空闲 | 应用实例 | 序列化存储 | 反序列化恢复 | -| 系统重启时 | 所有临时数据 | 立即清理 | 重新初始化 | diff --git a/.qoder/quests/third-party-sdk-integration.md b/.qoder/quests/third-party-sdk-integration.md deleted file mode 100644 index bb7b267..0000000 --- a/.qoder/quests/third-party-sdk-integration.md +++ /dev/null @@ -1,228 +0,0 @@ -# 第三方SDK集成方案设计 - -## 概述 - -本文档旨在设计一种新的第三方SDK集成方案，使第三方应用无需通过iframe注入的方式即可直接调用系统服务。当前系统采用iframe注入SDK的方式为第三方应用提供系统服务访问接口，这种方式虽然有效，但在安全性、性能和开发体验方面存在一些限制。 - -新方案将采用全局对象共享的方式实现SDK功能，避免网络通信开销，同时保持与现有系统的兼容性。 - -## 设计目标 - -1. **安全性提升**：减少iframe注入带来的安全风险 -2. **性能优化**：降低SDK注入的开销 -3. **开发体验改善**：提供更简洁的SDK使用方式 -4. **零网络通信**：完全避免网络请求，提升响应速度 -5. **向后兼容**：保持现有应用的正常运行 - -## 当前实现分析 - -### 现有架构 - -当前系统通过在iframe中注入SDK脚本的方式为第三方应用提供服务访问接口： - -```mermaid -graph TD - A[第三方应用] --> B[iframe沙箱] - B --> C[注入SDK脚本] - C --> D[postMessage通信] - D --> E[系统服务] - E --> D - D --> C - C --> B - B --> A -``` - -### 通信机制 - -系统使用`postMessage` API实现跨域通信： - -1. **请求发送**：SDK通过`window.parent.postMessage`发送请求到系统 -2. **请求处理**：系统监听`message`事件处理SDK调用 -3. **响应返回**：系统通过`iframe.contentWindow.postMessage`发送响应 - -### 安全机制 - -1. **沙箱隔离**：使用iframe的`sandbox`属性限制应用权限 -2. **权限控制**：基于应用ID的权限验证机制 -3. **CSP策略**：内容安全策略限制脚本执行 - -## 新方案设计 - -### 架构设计 - -新方案将采用全局对象预定义的方式，通过系统预置接口实现系统服务访问： - -```mermaid -graph TD - A[第三方应用] --> B[全局对象接口] - B --> C[系统服务] - C --> B - B --> A -``` - -### 核心组件 - -1. **全局对象接口**：在应用上下文中预置系统服务接口 -2. **系统服务适配器**：将接口调用转换为内部服务调用 -3. **权限验证模块**：负责应用权限控制 -4. **上下文管理器**：管理系统与应用间的上下文隔离 - -### 接口设计 - -#### 全局对象结构 - -```javascript -// 第三方应用中直接使用预置对象 -window.SystemSDK.window.setTitle('新标题') -window.SystemSDK.storage.set('key', 'value') -``` - -#### 可用接口 - -- `window.SystemSDK.window` - 窗体管理接口 -- `window.SystemSDK.storage` - 存储接口 -- `window.SystemSDK.network` - 网络接口 -- `window.SystemSDK.events` - 事件接口 -- `window.SystemSDK.ui` - UI接口 -- `window.SystemSDK.system` - 系统接口 - -### 安全机制 - -1. **上下文隔离**：确保应用只能访问预置接口 -2. **权限验证**：基于应用ID的权限控制 -3. **接口限制**：只暴露必要的系统服务接口 -4. **调用审计**：记录所有SDK接口调用 - -## 实施步骤 - -### 第一阶段：全局对象接口开发 - -1. 提取现有SDK功能到全局对象接口 -2. 实现全局对象接口替代postMessage通信 -3. 添加权限验证和错误处理机制 -4. 编写使用文档和示例 - -### 第二阶段：沙箱环境改造 - -1. 修改应用沙箱创建逻辑 -2. 实现全局对象预置机制 -3. 创建系统服务适配器 -4. 实现权限验证模块 - -### 第三阶段：兼容性处理 - -1. 保持iframe注入机制向后兼容 -2. 提供迁移工具和文档 -3. 逐步引导第三方应用迁移到新方案 - -## API接口设计 - -### 全局对象接口 - -| 接口 | 说明 | -| ------------------ | --------------- | -| `window.SystemSDK` | 系统SDK全局对象 | - -### 窗体管理接口 - -| 接口 | 说明 | -| --------------------------- | ------------ | -| `SystemSDK.window.setTitle` | 设置窗体标题 | -| `SystemSDK.window.resize` | 调整窗体尺寸 | -| `SystemSDK.window.move` | 移动窗体位置 | -| `SystemSDK.window.minimize` | 最小化窗体 | -| `SystemSDK.window.maximize` | 最大化窗体 | -| `SystemSDK.window.restore` | 还原窗体 | -| `SystemSDK.window.close` | 关闭窗体 | - -### 存储接口 - -| 接口 | 说明 | -| -------------------------- | -------- | -| `SystemSDK.storage.set` | 存储数据 | -| `SystemSDK.storage.get` | 获取数据 | -| `SystemSDK.storage.remove` | 删除数据 | -| `SystemSDK.storage.clear` | 清空数据 | - -### 网络接口 - -| 接口 | 说明 | -| ---------------------------- | ------------ | -| `SystemSDK.network.request` | 发送HTTP请求 | -| `SystemSDK.network.upload` | 上传文件 | -| `SystemSDK.network.download` | 下载文件 | - -## 错误处理 - -### 错误类型定义 - -| 错误类型 | 说明 | -| --------------------- | ------------ | -| UnauthorizedError | 未授权访问 | -| PermissionDeniedError | 权限不足 | -| TimeoutError | 调用超时 | -| InternalError | 系统内部错误 | - -### 错误响应格式 - -```typescript -interface APIResponse { - success: boolean - data?: T - error?: string - code?: number -} -``` - -## 性能考量 - -1. **零网络延迟**：完全避免网络通信延迟 -2. **直接调用**：通过全局对象直接访问系统服务 -3. **内存共享**：在沙箱环境中共享内存数据 -4. **异步处理**：非阻塞的接口调用机制 - -## 安全考虑 - -1. **沙箱隔离**：在受控环境中暴露SDK接口 -2. **权限控制**：基于应用ID的细粒度权限管理 -3. **接口限制**：只暴露必要的系统服务接口 -4. **调用审计**：记录所有SDK接口调用 -5. **输入验证**：严格验证所有输入参数 - -## 向后兼容性 - -1. 保留现有的iframe注入机制 -2. 提供迁移指南和工具 -3. 逐步废弃旧机制而非立即移除 -4. 监控两种机制的使用情况 - -## 测试策略 - -### 单元测试 - -1. SDK库功能测试 -2. 认证服务测试 -3. API网关测试 -4. 权限验证测试 - -### 集成测试 - -1. 端到端通信测试 -2. 安全机制测试 -3. 性能基准测试 -4. 兼容性测试 - -## 部署方案 - -### 开发环境 - -1. 全局对象接口开发 -2. Mock服务模拟系统接口 -3. 单元测试覆盖 - -### 生产环境 - -1. 系统集成全局对象接口 -2. API服务部署到云服务器 -3. 配置负载均衡和SSL证书 -4. 设置监控和告警机制 diff --git a/.qoder/quests/ui-modularization.md b/.qoder/quests/ui-modularization.md deleted file mode 100644 index 0a91daf..0000000 --- a/.qoder/quests/ui-modularization.md +++ /dev/null @@ -1,370 +0,0 @@ -# UI模块化设计方案 - -## 1. 概述 - -本方案旨在将当前项目中的UI组件与核心业务逻辑进行彻底分离，实现UI层只负责数据渲染，核心层专注于数据处理的架构模式。通过模块化重构，提高代码的可维护性、可测试性和可扩展性。 - -### 1.1 设计目标 - -- 实现UI层与核心业务逻辑的完全解耦 -- UI组件只负责接收数据并渲染，不包含任何业务逻辑 -- 核心服务层提供统一的数据接口和状态管理 -- 通过响应式数据绑定实现UI与数据的自动同步 - -### 1.2 核心原则 - -- **数据驱动**: UI组件通过props接收数据，通过事件触发操作 -- **单一职责**: UI组件只负责渲染，核心服务只负责数据处理 -- **响应式更新**: 数据变化自动触发UI更新 -- **模块化设计**: 各模块职责清晰，依赖关系明确 - -### 1.3 项目现状分析 - -当前项目已经具备良好的分层架构： - -- 使用Pinia进行状态管理 -- 通过依赖注入提供系统服务 -- UI组件与核心服务之间通过明确定义的接口交互 -- 采用Vue 3 Composition API实现逻辑复用 - -## 2. 架构设计 - -### 2.1 整体架构图 - -```mermaid -graph TD - A[UI层] --> B[状态管理层] - B --> C[核心服务层] - C --> D[数据源] - C --> E[外部API] - B --> A - - subgraph UI层 - A - end - - subgraph 核心层 - B - C - D - E - end -``` - -### 2.2 现有架构分析 - -项目当前已具备良好的分层架构，但存在部分逻辑混合的情况： - -1. **UI层**：包含Vue组件和部分业务逻辑 -2. **状态管理层**：使用Pinia管理全局状态 -3. **核心服务层**：SystemServiceIntegration统一管理系统服务 -4. **依赖注入**：通过Vue的provide/inject机制传递系统服务 - -### 2.3 模块划分优化 - -| 模块 | 职责 | 包含内容 | -| ------------ | ---------------------- | ------------------------------ | -| UI组件模块 | 负责界面展示和用户交互 | 所有Vue组件、样式文件 | -| 状态管理模块 | 管理应用状态和数据流 | Pinia stores、响应式数据 | -| 核心服务模块 | 处理业务逻辑和数据操作 | 系统服务、应用管理、窗体管理等 | -| 工具模块 | 提供通用工具函数 | 工具函数、类型定义 | - -## 3. UI模块重构方案 - -### 3.1 当前结构分析 - -当前项目UI相关代码分散在以下目录中： - -- `src/ui/`: 主要UI组件 -- `src/apps/`: 内置应用组件 -- `src/common/`: 通用UI工具和组件 - -### 3.2 重构后的UI模块结构 - -``` -src/ -├── ui/ -│ ├── components/ # 通用UI组件 -│ ├── containers/ # 容器组件 -│ ├── views/ # 页面视图组件 -│ ├── composables/ # UI专用组合式函数 -│ ├── styles/ # 样式文件 -│ └── types/ # UI相关类型定义 -├── core/ # 核心业务逻辑（从UI中抽离） -├── stores/ # 状态管理 -└── services/ # 核心服务层 -``` - -### 3.3 UI组件分类 - -#### 3.3.1 展示组件（Pure Components） - -展示组件只负责接收数据并渲染，不包含任何业务逻辑： - -| 组件名称 | 职责 | 输入数据 | 输出事件 | -| ----------- | ------------ | ---------------------- | ------------------------------- | -| AppIcon | 应用图标展示 | iconInfo, gridTemplate | dragStart, dragEnd, doubleClick | -| AppRenderer | 应用渲染器 | appId, windowId | loaded, error | - -#### 3.3.2 容器组件（Container Components） - -容器组件负责连接展示组件与状态管理： - -| 组件名称 | 职责 | 连接状态 | 业务逻辑 | -| ---------------- | ---------- | ----------------------- | ------------------ | -| DesktopContainer | 桌面容器 | appIcons, systemStatus | 应用启动、状态更新 | -| WindowManager | 窗口管理器 | windows | 窗口创建、销毁 | -| AppRenderer | 应用渲染器 | appComponent, iframeUrl | 应用加载、错误处理 | - -## 4. 数据流设计 - -### 4.1 数据流向图 - -```mermaid -graph LR - A[核心服务] --> B[状态管理] - B --> C[UI组件] - C --> D[用户操作] - D --> E[事件处理] - E --> A - - style A fill:#cde4ff - style B fill:#ffd7c1 - style C fill:#d3f8d3 - style D fill:#fff2c1 - style E fill:#e6d7ff -``` - -### 4.2 状态管理设计 - -项目已使用Pinia进行状态管理，建议继续沿用并扩展： - -#### 4.2.1 桌面状态 - -```typescript -interface DesktopState { - appIcons: IDesktopAppIcon[] - gridTemplate: IGridTemplateParams - systemStatus: SystemStatus - showSystemStatus: boolean -} -``` - -#### 4.2.2 窗口状态 - -```typescript -interface WindowState { - windows: BuiltInWindow[] - activeWindowId: string | null -} -``` - -### 4.3 数据获取与更新流程 - -```mermaid -sequenceDiagram - participant U as UI组件 - participant S as 状态管理 - participant C as 核心服务 - - U->>S: 读取状态数据 - S-->>U: 返回响应式数据 - U->>U: 渲染界面 - - U->>C: 触发用户操作 - C->>S: 更新状态 - S->>U: 自动更新界面 -``` - -### 4.4 依赖注入机制 - -项目通过Vue的provide/inject机制实现服务注入： - -1. 在main.ts中创建并提供SystemServiceIntegration实例 -2. UI组件通过inject获取系统服务 -3. 系统服务提供统一的API访问核心功能 - -## 5. 接口设计 - -### 5.1 UI组件接口规范 - -#### 5.1.1 展示组件接口 - -```typescript -// AppIcon组件接口 -interface AppIconProps { - iconInfo: IDesktopAppIcon - gridTemplate: IGridTemplateParams -} - -interface AppIconEvents { - (e: 'dragStart', event: DragEvent): void - (e: 'dragEnd', event: DragEvent): void - (e: 'doubleClick'): void -} - -// AppRenderer组件接口 -interface AppRendererProps { - appId: string - windowId?: string -} - -interface AppRendererEvents { - (e: 'loaded'): void - (e: 'error', error: Error): void -} -``` - -#### 5.1.2 容器组件接口 - -```typescript -// DesktopContainer组件接口 -interface DesktopContainerProps { - // 无需props，直接从状态管理获取数据 -} - -interface DesktopContainerMethods { - refreshApps(): Promise - runApp(appId: string): Promise -} -``` - -### 5.2 状态管理接口 - -#### 5.2.1 桌面状态接口 - -```typescript -interface DesktopStore { - // 状态 - appIcons: Ref - gridTemplate: Ref - systemStatus: Ref - showSystemStatus: Ref - - // Getters - gridStyle: ComputedRef - - // Actions - updateAppIcons(icons: IDesktopAppIcon[]): void - updateSystemStatus(status: SystemStatus): void - toggleSystemStatus(show: boolean): void - saveIconPositions(): void -} -``` - -## 6. 实现方案 - -### 6.1 UI模块独立化步骤 - -1. **创建独立的UI模块目录结构** - - 将现有的UI组件按功能重新组织 - - 分离展示组件和容器组件 - -2. **抽离业务逻辑到核心服务** - - 将应用启动逻辑移至SystemServiceIntegration - - 将状态管理移至Pinia stores - -3. **重构组件数据流** - - 使用props传递数据 - - 使用emit触发事件 - - 通过状态管理实现响应式更新 - -### 6.2 现有组件优化 - -1. **DesktopContainer组件** - - 保持现有的inject机制获取系统服务 - - 将应用启动逻辑完全委托给系统服务 - - 通过响应式数据驱动UI更新 - -2. **AppIcon组件** - - 保持纯展示组件特性 - - 通过事件与父组件通信 - -3. **WindowManager组件** - - 保持现有的窗口管理逻辑 - - 通过inject获取系统服务 - -4. **AppRenderer组件** - - 负责应用渲染逻辑 - - 支持内置应用和外部应用渲染 - - 内置应用使用Vue组件直接渲染 - - 外部应用使用iframe加载渲染 - -### 6.3 核心改造点 - -#### 6.3.1 DesktopContainer组件改造 - -当前的DesktopContainer组件包含了太多业务逻辑，需要进行以下优化： - -1. **保持组件结构**：无需拆分为多个组件，但需明确职责划分 -2. **业务逻辑委托**：将应用启动等业务逻辑完全委托给系统服务 -3. **状态管理优化**：通过响应式数据驱动UI更新 - -#### 6.3.2 应用启动流程优化 - -```mermaid -graph TD - A[用户双击图标] --> B[DesktopContainer组件] - B --> C[调用系统服务] - C --> D[SystemServiceIntegration] - D --> E[ApplicationLifecycleManager] - E --> F[创建应用实例] -``` - -#### 6.3.3 子应用加载机制 - -项目需要支持两种类型的应用加载： - -1. **内置应用加载**： - - 直接使用Vue 3组件加载机制 - - 通过AppRegistry获取应用组件 - - 无需异步加载，立即渲染 - -2. **外部应用加载**： - - 使用iframe沙箱环境加载 - - 通过ExternalAppDiscovery发现应用 - - 异步加载应用资源 - - 外部加载逻辑可暂时留空，后期实现 - -### 6.4 依赖注入优化 - -项目已通过Vue的provide/inject机制实现服务注入，建议保持现有模式并进行优化： - -```typescript -// main.ts - 保持现有实现 -app.provide('systemService', systemService) - -// UI组件中使用 - 保持现有实现 -const systemService = inject('systemService') - -// 建议添加类型安全检查 -const systemService = inject('systemService') -if (!systemService) { - throw new Error('系统服务未正确注入') -} -``` - -## 7. 测试策略 - -### 7.1 UI组件测试 - -- 展示组件：测试不同props输入下的渲染结果 -- 容器组件：测试与状态管理和服务的交互 - -### 7.2 状态管理测试 - -- 测试状态更新的正确性 -- 测试响应式数据的自动更新 - -### 7.3 集成测试 - -- 测试完整的数据流和用户操作流程 -- 验证UI与核心服务的交互正确性 - -### 7.4 现有测试策略优化 - -项目已具备基本的测试框架，建议： - -1. 增加对展示组件的单元测试 -2. 完善容器组件与服务的集成测试 -3. 建立端到端测试覆盖核心用户场景 diff --git a/.qoder/quests/window-drag-resize-control.md b/.qoder/quests/window-drag-resize-control.md deleted file mode 100644 index c6f8c92..0000000 --- a/.qoder/quests/window-drag-resize-control.md +++ /dev/null @@ -1,314 +0,0 @@ -# 窗体功能增强设计文档 - -## 1. 概述 - -### 1.1 功能目标 - -1. 为项目中的窗体组件添加8个方向的拖拽调整尺寸功能，增强用户交互体验 -2. 修复窗体最大化、最小化、还原功能存在的问题 -3. 完善窗体状态管理和事件通知机制 - -### 1.2 当前系统分析 - -通过代码分析发现，当前系统已具备以下基础功能： - -- 窗体创建、销毁、移动功能 -- 窗体最大化、最小化、还原功能 -- 基本的事件管理系统 -- 窗体状态管理和配置 - -但现有功能存在以下问题： - -1. 缺少用户通过鼠标拖拽调整窗体尺寸的功能 -2. 窗体最大化、最小化、还原功能实现不完整，缺少与事件系统的完整集成 -3. 窗体状态变更时未正确触发`windowFormDataUpdate`事件通知 - -## 2. 架构设计 - -### 2.1 整体架构 - -```mermaid -graph TD - A[用户操作] --> B[窗体功能处理器] - B --> C[窗体状态管理] - C --> D[UI更新引擎] - D --> E[界面重渲染] - C --> F[事件通知系统] - - G[窗体服务] --> C - H[事件管理器] --> F -``` - -### 2.2 核心组件 - -| 组件名称 | 职责 | 说明 | -| --------------------- | ------------------ | -------------------------------------- | -| WindowOperationHandler | 窗体操作处理核心 | 处理最大化、最小化、还原和拖拽调整尺寸操作 | -| WindowManager | 窗体状态管理 | 管理窗体状态变更和配置更新 | -| WindowRenderer | UI更新引擎 | 应用新状态到窗体界面 | -| WindowEventManager | 事件管理器 | 发布窗体状态变更事件 | - -## 3. 功能设计 - -### 3.1 窗体状态操作 - -窗体支持以下状态操作： - -| 操作 | 状态变更 | 事件触发 | 说明 | -| ------ | ---------------------------- | ------------------------------------------ | ------------------------------------------ | -| 最大化 | default/minimized → maximized | windowFormMaximize, windowFormDataUpdate | 窗体占据除任务栏外的整个屏幕空间 | -| 最小化 | default/maximized → minimized | windowFormMinimize | 窗体隐藏，仅在任务栏保留图标 | -| 还原 | minimized/maximized → default | windowFormRestore, windowFormDataUpdate | 窗体恢复到正常尺寸和位置 | - -### 3.2 拖拽调整尺寸方向定义 - -窗体支持8个方向的拖拽调整尺寸，具体如下： - -```mermaid -graph TD - subgraph 窗体 - direction LR - A[↖] --- B[↑] --- C[↗] - D[←] --- E[窗体内容] --- F[→] - G[↙] --- H[↓] --- I[↘] - end - - classDef corner fill:#f9f,stroke:#333; - classDef edge fill:#bbf,stroke:#333; - - class A,C,G,I,corner - class B,D,F,H,edge -``` - -| 方向 | 标识符 | 影响属性 | 说明 | -| ------ | ----------- | ------------------- | ------------------ | -| 左上角 | topLeft | width, height, x, y | 同时调整宽高和位置 | -| 上边缘 | top | height, y | 调整高度和垂直位置 | -| 右上角 | topRight | width, height, y | 调整宽高和垂直位置 | -| 右边缘 | right | width | 仅调整宽度 | -| 右下角 | bottomRight | width, height | 仅调整宽高 | -| 下边缘 | bottom | height | 仅调整高度 | -| 左下角 | bottomLeft | width, height, x | 调整宽高和水平位置 | -| 左边缘 | left | width, x | 调整宽度和水平位置 | - -### 3.3 交互流程 - -```mermaid -sequenceDiagram - participant U as 用户 - participant WH as 窗体句柄 - participant WOH as 操作处理器 - participant WM as 窗体管理器 - participant WR as 窗体渲染器 - participant EM as 事件管理器 - - U->>WH: 执行操作(最大化/最小化/还原/拖拽) - WH->>WOH: 处理操作请求 - WOH->>WM: 更新窗体状态 - WM->>WR: 应用新状态 - WM->>EM: 发布状态变更事件 - EM->>EM: 发布windowFormDataUpdate事件 - WR->>U: 更新界面显示 -``` - -## 4. 数据模型 - -### 4.1 窗体状态数据结构 - -```typescript -interface IWindowFormDataUpdateParams { - /** 窗口id */ - id: string; - /** 窗口状态 */ - state: TWindowFormState; - /** 窗口宽度 */ - width: number; - /** 窗口高度 */ - height: number; - /** 窗口x坐标(左上角) */ - x: number; - /** 窗口y坐标(左上角) */ - y: number; -} - -type TWindowFormState = 'default' | 'minimized' | 'maximized'; -``` - -### 4.2 窗体尺寸配置扩展 - -在现有`WindowConfig`接口基础上增加最小/最大尺寸限制： - -| 字段 | 类型 | 必填 | 说明 | -| --------- | ------- | ---- | -------------------------- | -| minWidth | number | 可选 | 窗体最小宽度(像素) | -| minHeight | number | 可选 | 窗体最小高度(像素) | -| maxWidth | number | 可选 | 窗体最大宽度(像素) | -| maxHeight | number | 可选 | 窗体最大高度(像素) | -| resizable | boolean | 可选 | 是否可调整尺寸，默认为true | - -### 4.3 拖拽状态数据结构 - -```typescript -interface ResizeState { - /** 是否正在调整尺寸 */ - isResizing: boolean; - /** 调整方向 */ - direction: ResizeDirection; - /** 起始鼠标位置 */ - startX: number; - /** 起始鼠标位置 */ - startY: number; - /** 起始窗体宽度 */ - startWidth: number; - /** 起始窗体高度 */ - startHeight: number; - /** 起始窗体X坐标 */ - startXPosition: number; - /** 起始窗体Y坐标 */ - startYPosition: number; -} - -type ResizeDirection = - 'topLeft' | 'top' | 'topRight' | - 'right' | 'bottomRight' | 'bottom' | - 'bottomLeft' | 'left' | 'none'; -``` - -## 5. 事件系统设计 - -### 5.1 修复事件触发问题 - -当前窗体状态变更时未正确触发`windowFormDataUpdate`事件，需要修复以下问题： - -1. 在最大化操作完成后，应触发`windowFormDataUpdate`事件，携带窗体新状态和尺寸信息 -2. 在最小化操作完成后，应触发`windowFormDataUpdate`事件，携带窗体新状态信息 -3. 在还原操作完成后，应触发`windowFormDataUpdate`事件，携带窗体新状态和尺寸信息 - -### 5.2 新增事件定义 - -在现有`IWindowFormEvent`接口中添加以下事件： - -| 事件名称 | 参数类型 | 触发时机 | -| --------------------- | --------------------------- | ---------------- | -| windowFormResizeStart | string | 开始调整窗体尺寸 | -| windowFormResizing | IWindowFormDataUpdateParams | 调整尺寸过程中 | -| windowFormResizeEnd | string | 完成窗体尺寸调整 | - -### 5.3 事件触发流程 - -```mermaid -graph TD - A[窗体状态变更] --> B{是否需要更新数据?} - B -->|是| C[构造更新数据] - C --> D[触发windowFormDataUpdate事件] - B -->|否| E[直接触发状态事件] - D --> F[通知监听组件] - E --> F -``` - -## 6. 核心逻辑设计 - -### 6.1 窗体状态变更逻辑修复 - -当前窗体状态变更逻辑存在以下问题需要修复： - -1. **最大化逻辑问题**： - - 未正确保存原始窗体尺寸和位置信息 - - 未触发`windowFormDataUpdate`事件通知 - -2. **最小化逻辑问题**： - - 未触发`windowFormDataUpdate`事件通知 - -3. **还原逻辑问题**： - - 未正确恢复窗体尺寸和位置 - - 未触发`windowFormDataUpdate`事件通知 - -### 6.2 边缘检测算法 - -窗体边缘需要划分8个可拖拽区域，每个区域宽度为8px： - -```mermaid -graph TD - subgraph 边缘区域划分 - direction LR - A[8px↖] --- B[8px↑] --- C[8px↗] - D[8px←] --- E[窗体内容] --- F[8px→] - G[8px↙] --- H[8px↓] --- I[8px↘] - end -``` - -### 6.3 尺寸计算规则 - -1. **最小尺寸限制**：窗体宽度不能小于minWidth，高度不能小于minHeight -2. **最大尺寸限制**：窗体宽度不能大于maxWidth，高度不能大于maxHeight -3. **位置边界**：窗体不能被拖拽到屏幕外 - -### 6.4 拖拽处理流程 - -1. 鼠标按下时检测是否在边缘区域 -2. 根据鼠标位置确定拖拽方向 -3. 记录初始状态数据 -4. 鼠标移动时实时计算新尺寸 -5. 应用新尺寸并触发重渲染 -6. 鼠标释放时结束拖拽状态 - -## 7. UI/UX设计 - -### 7.1 视觉反馈 - -- 鼠标悬停在可拖拽边缘时，光标应变为对应方向的调整光标 -- 拖拽过程中窗体应有半透明遮罩效果 -- 拖拽完成后应有平滑的过渡动画 - -### 7.2 响应式适配 - -- 在不同屏幕分辨率下保持边缘区域的可点击性 -- 支持触屏设备的拖拽操作 -- 在窗体尺寸接近最小/最大限制时提供视觉提示 - -## 8. 性能优化 - -### 8.1 事件处理优化 - -- 使用防抖机制减少高频事件触发 -- 在拖拽过程中暂停不必要的重渲染 -- 使用requestAnimationFrame优化动画性能 - -### 8.2 内存管理 - -- 及时清理事件监听器 -- 复用计算对象避免频繁创建 -- 在窗体销毁时清理所有相关资源 - -## 9. 安全考虑 - -### 9.1 边界检查 - -- 确保窗体不能被调整到超出屏幕边界 -- 验证尺寸参数的有效性 -- 防止负值或异常大值的输入 - -### 9.2 权限控制 - -- 只有具有调整权限的窗体才能被调整尺寸 -- 外部应用的窗体尺寸调整需通过SDK接口 - -## 10. 测试策略 - -### 10.1 单元测试 - -- 边缘检测算法准确性测试 -- 尺寸计算边界条件测试 -- 事件发布/订阅机制测试 - -### 10.2 集成测试 - -- 不同方向拖拽功能测试 -- 尺寸限制功能测试 -- 与现有窗体功能集成测试 - -### 10.3 用户体验测试 - -- 拖拽流畅性测试 -- 视觉反馈效果测试 -- 不同设备兼容性测试 diff --git a/.qoder/repowiki/zh/content/UI组件体系/AppIcon组件.md b/.qoder/repowiki/zh/content/UI组件体系/AppIcon组件.md deleted file mode 100644 index b66c385..0000000 --- a/.qoder/repowiki/zh/content/UI组件体系/AppIcon组件.md +++ /dev/null @@ -1,204 +0,0 @@ -# AppIcon组件 - - -**Referenced Files in This Document ** -- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue) -- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts) -- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts) -- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts) - - -## 目录 -1. [简介](#简介) -2. [核心数据结构](#核心数据结构) -3. [拖拽交互机制](#拖拽交互机制) -4. [网格定位原理](#网格定位原理) -5. [事件过滤逻辑](#事件过滤逻辑) -6. [容器响应式布局](#容器响应式布局) -7. [图标重排策略](#图标重排策略) -8. [持久化存储](#持久化存储) -9. [扩展与最佳实践](#扩展与最佳实践) - -## 简介 -`AppIcon` 组件是桌面应用系统中的可交互图标单元，实现了基于HTML5 Drag API的拖拽功能。该组件通过精确的坐标计算和网格系统集成，允许用户将图标重新定位到桌面容器的任意有效网格位置。本文档深入解析其技术实现细节，涵盖从拖拽事件处理、坐标换算、网格定位到状态持久化的完整流程。 - -**Section sources** -- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52) - -## 核心数据结构 - -### IDesktopAppIcon 接口 -定义了桌面图标的元数据结构，包含名称、图标资源、启动路径及在网格布局中的位置坐标。 - -```typescript -export interface IDesktopAppIcon { - name: string; // 图标显示名称 - icon: string; // 图标资源路径或标识符 - path: string; // 关联的应用程序启动路径 - x: number; // 在grid布局中的列索引（从1开始） - y: number; // 在grid布局中的行索引（从1开始） -} -``` - -该设计意图明确：`x` 和 `y` 字段直接映射到CSS Grid的`grid-column`和`grid-row`属性，实现了数据驱动的UI布局。 - -**Section sources** -- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts#L3-L14) - -## 拖拽交互机制 - -`AppIcon` 组件利用原生HTML5 Drag API实现拖拽功能： - -1. **启用拖拽**：通过设置 `draggable="true"` 属性激活元素的拖拽能力。 -2. **事件监听**： - - `@dragstart`：拖拽开始时触发，当前实现为空函数，保留未来扩展空间。 - - `@dragend`：拖拽结束时触发，执行核心的坐标计算与位置更新逻辑。 - -此机制无需依赖第三方库，轻量且兼容性好。 - -**Section sources** -- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L2-L8) - -## 网格定位原理 - -### 动态样式绑定 -组件通过内联样式动态设置其在CSS Grid中的位置： -```vue -:style="`grid-column: ${iconInfo.x}/${iconInfo.x + 1}; grid-row: ${iconInfo.y}/${iconInfo.y + 1};`" -``` -此表达式将 `iconInfo.x` 和 `iconInfo.y` 的值转换为Grid的列/行跨度声明，确保图标精准占据一个网格单元。 - -### 坐标换算过程 -`onDragEnd` 事件处理器的核心任务是将鼠标绝对坐标转换为相对网格坐标： - -1. **获取容器边界**：使用 `getBoundingClientRect()` 获取父容器的绝对位置和尺寸。 -2. **计算相对坐标**：通过 `e.clientX - rect.left` 和 `e.clientY - rect.top` 得到鼠标相对于容器左上角的偏移量。 -3. **确定目标网格**：利用 `cellRealWidth` 和 `cellRealHeight` 进行除法运算并向上取整（`Math.ceil`），得到目标网格的行列索引。 - -```mermaid -flowchart TD -A[拖拽结束] --> B{获取鼠标
clientX/clientY} -B --> C{获取容器
getBoundingClientRect} -C --> D[计算鼠标相对
容器坐标] -D --> E[用cellRealWidth/Height
计算网格索引] -E --> F[更新iconInfo.x/y] -F --> G[触发UI重渲染] -``` - -**Diagram sources ** -- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L10-L38) - -**Section sources** -- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L10-L38) - -## 事件过滤逻辑 - -为了防止图标被错误地放置在其他图标之上，`onDragEnd` 方法实现了关键的事件过滤： - -1. 使用 `document.elementFromPoint(e.clientX, e.clientY)` 检测鼠标终点位置的DOM元素。 -2. 如果该元素是另一个 `.icon-container`，则立即返回，不执行任何位置更新。 - -此逻辑确保了“空位投放”原则，提升了用户体验，避免了图标的视觉重叠。 - -**Section sources** -- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L13-L17) - -## 容器响应式布局 - -### IGridTemplateParams 接口 -该接口定义了网格系统的动态参数，是实现响应式布局的关键。 - -```typescript -export interface IGridTemplateParams { - cellExpectWidth: number; // 单元格预设宽度 - cellExpectHeight: number; // 单元格预设高度 - cellRealWidth: number; // 单元格实际宽度 - cellRealHeight: number; // 单元格实际高度 - gapX: number; // 列间距 - gapY: number; // 行间距 - colCount: number; // 总列数 - rowCount: number; // 总行数 -} -``` - -### 实际尺寸计算 -`useDesktopContainerInit` 函数通过 `ResizeObserver` 监听容器尺寸变化，并动态计算 `cellRealWidth` 和 `cellRealHeight`： - -```javascript -const w = containerRect.width - (gridTemplate.gapX * (gridTemplate.colCount - 1)); -gridTemplate.cellRealWidth = Number((w / gridTemplate.colCount).toFixed(2)); -``` - -此计算考虑了所有列间距的总和，确保了网格单元的实际尺寸能完美填充容器，无边距误差。 - -**Section sources** -- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L3-L20) -- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L30-L38) - -## 图标重排策略 - -当网格的行列数发生变化时，`rearrangeIcons` 函数负责智能地重新分配图标位置： - -1. **优先保留原位**：遍历所有图标，若其原位置在新网格范围内且未被占用，则保留在原位。 -2. **寻找空位**：对于超出范围或位置冲突的图标，从 `(1,1)` 开始扫描，为其寻找第一个可用的空网格。 -3. **隐藏溢出图标**：如果所有网格均被占用，则将无法安置的图标放入 `hideAppIcons` 数组。 - -此策略保证了用户自定义布局的最大程度保留，同时优雅地处理了空间不足的情况。 - -```mermaid -sequenceDiagram -participant DC as DesktopContainer -participant UDCI as useDesktopContainerInit -participant RI as rearrangeIcons -DC->>UDCI : 监听gridTemplate变化 -UDCI->>RI : 调用rearrangeIcons() -loop 遍历每个图标 -RI->>RI : 检查是否在新网格内且位置空闲 -alt 是 -RI->>RI : 保留在原位 -else 否 -RI->>RI : 加入临时队列 -end -end -loop 处理临时队列 -RI->>RI : 扫描网格寻找空位 -alt 找到空位 -RI->>RI : 分配新位置 -else 无空位 -RI->>RI : 加入hideAppIcons -end -end -RI-->>UDCI : 返回appIcons和hideAppIcons -UDCI->>DC : 更新appIconsRef -``` - -**Diagram sources ** -- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L77-L80) -- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156) - -**Section sources** -- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L77-L80) -- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156) - -## 持久化存储 - -用户的图标布局偏好通过 `localStorage` 实现持久化： - -1. **写入**：使用 `watch` 监听 `appIconsRef.value` 的变化，一旦有更新，立即将整个数组序列化为JSON字符串并存入 `localStorage` 键名为 `'desktopAppIconInfo'` 的条目中。 -2. **读取**：在初始化时，尝试从 `localStorage` 中读取 `'desktopAppIconInfo'`，若存在则使用存储的位置信息覆盖默认布局。 - -这确保了用户关闭页面后再次打开时，仍能看到上次调整好的桌面布局。 - -**Section sources** -- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L88-L90) - -## 扩展与最佳实践 - -### 自定义图标样式 -可通过修改 `