diff --git a/.qoder/quests/api-field-chinese-annotation.md b/.qoder/quests/api-field-chinese-annotation.md new file mode 100644 index 0000000..6f5f87d --- /dev/null +++ b/.qoder/quests/api-field-chinese-annotation.md @@ -0,0 +1,338 @@ +# 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 new file mode 100644 index 0000000..4b2526a --- /dev/null +++ b/.qoder/quests/api-unified-interface-design.md @@ -0,0 +1,461 @@ +# 统一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/third-party-sdk-integration.md b/.qoder/quests/third-party-sdk-integration.md new file mode 100644 index 0000000..bb7b267 --- /dev/null +++ b/.qoder/quests/third-party-sdk-integration.md @@ -0,0 +1,228 @@ +# 第三方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/src/apps/types/AppManifest.ts b/src/apps/types/AppManifest.ts index 480fe6a..0763c2d 100644 --- a/src/apps/types/AppManifest.ts +++ b/src/apps/types/AppManifest.ts @@ -1,35 +1,110 @@ +/** + * 内置应用清单接口 + */ /** * 内置应用清单接口 */ export interface InternalAppManifest { + /** + * 应用唯一标识符 + */ id: string + /** + * 应用名称 + */ name: string + /** + * 应用版本号 + */ version: string + /** + * 应用描述信息 + */ description: string + /** + * 应用作者 + */ author: string + /** + * 应用图标 + */ icon: string + /** + * 应用所需权限列表 + */ permissions: string[] + /** + * 窗体配置信息 + */ window: { + /** + * 窗体宽度 + */ width: number + /** + * 窗体高度 + */ height: number + /** + * 窗体最小宽度 + */ minWidth?: number + /** + * 窗体最小高度 + */ minHeight?: number + /** + * 窗体最大宽度 + */ maxWidth?: number + /** + * 窗体最大高度 + */ maxHeight?: number + /** + * 是否可调整大小 + */ resizable?: boolean + /** + * 是否可最小化 + */ minimizable?: boolean + /** + * 是否可最大化 + */ maximizable?: boolean + /** + * 是否可关闭 + */ closable?: boolean } + /** + * 应用分类 + */ category?: string + /** + * 应用关键字列表 + */ keywords?: string[] } +/** + * 应用注册信息 + */ /** * 应用注册信息 */ export interface AppRegistration { + /** + * 应用清单信息 + */ manifest: InternalAppManifest + /** + * Vue组件 + */ component: any // Vue组件 + /** + * 是否为内置应用 + */ isBuiltIn: boolean } \ No newline at end of file diff --git a/src/events/IEventBuilder.ts b/src/events/IEventBuilder.ts index f29cbe0..debc5b6 100644 --- a/src/events/IEventBuilder.ts +++ b/src/events/IEventBuilder.ts @@ -5,6 +5,9 @@ import type { IDestroyable } from '@/core/common/types/IDestroyable.ts' * @interface IEventMap 事件定义 键是事件名称，值是事件处理函数 */ export interface IEventMap { + /** + * 事件处理函数映射 + */ [key: string]: (...args: any[]) => void } diff --git a/src/sdk/types.ts b/src/sdk/types.ts index 89b8284..338be89 100644 --- a/src/sdk/types.ts +++ b/src/sdk/types.ts @@ -150,13 +150,28 @@ export interface StorageEvents { onQuotaExceeded: (usedSpace: number, maxSpace: number) => void } +/** + * 存储使用统计 + */ /** * 存储使用统计 */ export interface StorageStats { + /** + * 已使用存储空间(MB) + */ usedSpace: number // 已使用空间(MB) + /** + * 最大存储空间(MB) + */ maxSpace: number // 最大空间(MB) + /** + * 存储键数量 + */ keysCount: number // 键数量 + /** + * 最后访问时间 + */ lastAccessed: Date } @@ -219,25 +234,61 @@ export interface StorageSDK { */ export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' +/** + * 网络请求配置 + */ /** * 网络请求配置 */ export interface NetworkRequestConfig { + /** + * HTTP请求方法 + */ method?: HTTPMethod + /** + * 请求头信息 + */ headers?: Record + /** + * 请求体数据 + */ body?: any + /** + * 请求超时时间(毫秒) + */ timeout?: number + /** + * 响应数据类型 + */ responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer' } +/** + * 网络响应 + */ /** * 网络响应 */ export interface NetworkResponse { + /** + * 响应数据内容 + */ data: T + /** + * HTTP状态码 + */ status: number + /** + * HTTP状态文本 + */ statusText: string + /** + * 响应头信息 + */ headers: Record + /** + * 请求URL + */ url: string } @@ -305,22 +356,49 @@ export interface NetworkSDK { // 事件SDK接口 // ============================================================================= +/** + * 事件消息 + */ /** * 事件消息 */ export interface EventMessage { + /** + * 消息唯一标识符 + */ id: string + /** + * 事件频道名称 + */ channel: string + /** + * 消息数据内容 + */ data: T + /** + * 发送方标识符 + */ senderId: string + /** + * 消息发送时间戳 + */ timestamp: Date } +/** + * 事件订阅配置 + */ /** * 事件订阅配置 */ export interface EventSubscriptionConfig { + /** + * 消息过滤器函数 + */ filter?: (message: EventMessage) => boolean + /** + * 是否只监听一次 + */ once?: boolean // 只监听一次 } @@ -383,26 +461,65 @@ export enum DialogType { CONFIRM = 'confirm' } +/** + * 对话框选项 + */ /** * 对话框选项 */ export interface DialogOptions { + /** + * 对话框标题 + */ title?: string + /** + * 对话框消息内容 + */ message: string + /** + * 对话框类型 + */ type?: DialogType + /** + * 自定义按钮文本数组 + */ buttons?: string[] + /** + * 默认按钮索引 + */ defaultButton?: number + /** + * 取消按钮索引 + */ cancelButton?: number } +/** + * 通知选项 + */ /** * 通知选项 */ export interface NotificationOptions { + /** + * 通知标题 + */ title: string + /** + * 通知正文内容 + */ body: string + /** + * 通知图标URL + */ icon?: string + /** + * 显示时长(毫秒) + */ duration?: number // 显示时长(毫秒) + /** + * 通知操作按钮 + */ actions?: Array<{ title: string; action: string }> } @@ -474,28 +591,82 @@ export interface UISDK { // 系统SDK接口 // ============================================================================= +/** + * 系统信息 + */ /** * 系统信息 */ export interface SystemInfo { + /** + * 运行平台信息 + */ platform: string + /** + * 用户代理字符串 + */ userAgent: string + /** + * 系统语言设置 + */ language: string + /** + * 时区信息 + */ timezone: string - screenResolution: { width: number; height: number } + /** + * 屏幕分辨率 + */ + screenResolution: { + /** + * 屏幕宽度 + */ + width: number; + /** + * 屏幕高度 + */ + height: number + } + /** + * 颜色深度 + */ colorDepth: number + /** + * 像素比率 + */ pixelRatio: number } +/** + * 应用信息 + */ /** * 应用信息 */ export interface AppInfo { + /** + * 应用唯一标识符 + */ id: string + /** + * 应用名称 + */ name: string + /** + * 应用版本号 + */ version: string + /** + * 应用权限列表 + */ permissions: string[] + /** + * 应用创建时间 + */ createdAt: Date + /** + * 应用最后活跃时间 + */ lastActiveAt: Date } diff --git a/src/services/WindowService.ts b/src/services/WindowService.ts index 509fe6f..b9a6b2a 100644 --- a/src/services/WindowService.ts +++ b/src/services/WindowService.ts @@ -16,40 +16,121 @@ export enum WindowState { ERROR = 'error', } +/** + * 窗体配置接口 + */ /** * 窗体配置接口 */ export interface 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坐标位置 + */ x?: number + /** + * 窗体Y坐标位置 + */ y?: number } +/** + * 窗体实例接口 + */ /** * 窗体实例接口 */ export interface WindowInstance { + /** + * 窗体唯一标识符 + */ id: string + /** + * 关联应用标识符 + */ appId: string + /** + * 窗体配置信息 + */ config: WindowConfig + /** + * 窗体当前状态 + */ state: WindowState + /** + * 窗体DOM元素 + */ element?: HTMLElement + /** + * 窗体内嵌iframe元素 + */ iframe?: HTMLIFrameElement + /** + * 窗体层级索引 + */ zIndex: number + /** + * 窗体创建时间 + */ createdAt: Date + /** + * 窗体更新时间 + */ updatedAt: Date }