azure/vue-desktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1

Browse Source
This commit is contained in:
Azure
2025-09-25 12:48:29 +08:00
parent 9dbc054483
commit d042520b14
7 changed files with 1358 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

338
.qoder/quests/api-field-chinese-annotation.md Normal file
View File

@@ -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<string, string> (可选) | 请求头信息 |
| body | any (可选) | 请求体数据 |
| timeout | number (可选) | 请求超时时间(毫秒) |
| responseType | 'json' \| 'text' \| 'blob' \| 'arrayBuffer' (可选) | 响应数据类型 |
#### NetworkResponse接口
| 字段名 | 类型 | 中文注释 |
| ---------- | ---------------------- | ------------ |
| data | T | 响应数据内容 |
| status | number | HTTP状态码 |
| statusText | string | HTTP状态文本 |
| headers | Record<string, string> | 响应头信息 |
| 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. 在添加注释时注意不要影响代码的可读性

461
.qoder/quests/api-unified-interface-design.md Normal file
View File

@@ -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 {
<<interface>>
+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 {
<<interface>>
+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 {
<<interface>>
+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 {
<<interface>>
+emit(channel: string, data: any) Promise~APIResponse~string~~
+on(channel: string, callback: Function) Promise~APIResponse~string~~
+off(subscriptionId: string) Promise~APIResponse~boolean~~
}
class UISDK {
<<interface>>
+showDialog(options: DialogOptions) Promise~APIResponse~object~~
+showNotification(options: NotificationOptions) Promise~APIResponse~string~~
+showToast(message: string, type: string) Promise~APIResponse~string~~
}
class SystemSDK {
<<interface>>
+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<APIResponse<boolean>> |
| resize(width, height) | 调整窗口尺寸 | width: number, height: number | Promise<APIResponse<boolean>> |
| move(x, y) | 移动窗口位置 | 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>> |
#### 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<APIResponse<boolean>> |
| get(key) | 获取数据 | key: string | Promise<APIResponse<any>> |
| remove(key) | 删除数据 | key: string | Promise<APIResponse<boolean>> |
| clear() | 清空所有数据 | 无 | Promise<APIResponse<boolean>> |
| keys() | 获取所有键名 | 无 | Promise<APIResponse<string[]>> |
| has(key) | 检查键是否存在 | key: string | Promise<APIResponse<boolean>> |
#### 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<APIResponse<NetworkResponse>> |
| get(url, config) | GET请求 | url: string, config: object | Promise<APIResponse<NetworkResponse>> |
| post(url, data, config) | POST请求 | url: string, data: any, config: object | Promise<APIResponse<NetworkResponse>> |
| upload(url, file) | 上传文件 | url: string, file: File/Blob | Promise<APIResponse<NetworkResponse>> |
| download(url, filename) | 下载文件 | url: string, filename: string | Promise<APIResponse<Blob>> |
#### 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<APIResponse<string>> |
| on(channel, callback) | 订阅事件频道 | channel: string, callback: Function | Promise<APIResponse<string>> |
| off(subscriptionId) | 取消订阅 | subscriptionId: string | Promise<APIResponse<boolean>> |
| broadcast(channel, data) | 广播消息 | channel: string, data: any | Promise<APIResponse<string>> |
| sendTo(targetAppId, data) | 发送点对点消息 | targetAppId: string, data: any | Promise<APIResponse<string>> |
#### 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<APIResponse<object>> |
| showNotification(options) | 显示通知 | options: NotificationOptions | Promise<APIResponse<string>> |
| showFilePicker(options) | 显示文件选择器 | options: FilePickerOptions | Promise<APIResponse<FileList>> |
| showToast(message, type) | 显示Toast消息 | message: string, type: string | Promise<APIResponse<string>> |
#### 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<APIResponse<SystemInfo>> |
| getAppInfo() | 获取当前应用信息 | 无 | Promise<APIResponse<AppInfo>> |
| requestPermission(permission) | 请求权限 | permission: string | Promise<APIResponse<PermissionStatus>> |
| getClipboard() | 获取剪贴板内容 | 无 | Promise<APIResponse<string>> |
| setClipboard(text) | 设置剪贴板内容 | text: string | Promise<APIResponse<boolean>> |
| openExternal(url) | 打开外部链接 | url: string | Promise<APIResponse<boolean>> |
## 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<T> {
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)
})
```

228
.qoder/quests/third-party-sdk-integration.md Normal file
View File

@@ -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<T> {
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. 设置监控和告警机制

75
src/apps/types/AppManifest.ts
View File

@@ -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
}

3
src/events/IEventBuilder.ts
View File

@@ -5,6 +5,9 @@ import type { IDestroyable } from '@/core/common/types/IDestroyable.ts'
* @interface IEventMap 事件定义 键是事件名称，值是事件处理函数
*/
export interface IEventMap {
/**
* 事件处理函数映射
*/
[key: string]: (...args: any[]) => void
}

173
src/sdk/types.ts
View File

@@ -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<string, string>
/**
* 请求体数据
*/
body?: any
/**
* 请求超时时间(毫秒)
*/
timeout?: number
/**
* 响应数据类型
*/
responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer'
}
/**
* 网络响应
*/
/**
* 网络响应
*/
export interface NetworkResponse<T = any> {
/**
* 响应数据内容
*/
data: T
/**
* HTTP状态码
*/
status: number
/**
* HTTP状态文本
*/
statusText: string
/**
* 响应头信息
*/
headers: Record<string, string>
/**
* 请求URL
*/
url: string
}
@@ -305,22 +356,49 @@ export interface NetworkSDK {
// 事件SDK接口
// =============================================================================
/**
* 事件消息
*/
/**
* 事件消息
*/
export interface EventMessage<T = any> {
/**
* 消息唯一标识符
*/
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
}

81
src/services/WindowService.ts
View File

@@ -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
}