vue-desktop/.qoder/quests/third-party-sdk-integration.md

第三方SDK集成方案设计

概述

本文档旨在设计一种新的第三方SDK集成方案，使第三方应用无需通过iframe注入的方式即可直接调用系统服务。当前系统采用iframe注入SDK的方式为第三方应用提供系统服务访问接口，这种方式虽然有效，但在安全性、性能和开发体验方面存在一些限制。

新方案将采用全局对象共享的方式实现SDK功能，避免网络通信开销，同时保持与现有系统的兼容性。

设计目标

1. 安全性提升：减少iframe注入带来的安全风险
2. 性能优化：降低SDK注入的开销
3. 开发体验改善：提供更简洁的SDK使用方式
4. 零网络通信：完全避免网络请求，提升响应速度
5. 向后兼容：保持现有应用的正常运行

当前实现分析

现有架构

当前系统通过在iframe中注入SDK脚本的方式为第三方应用提供服务访问接口：

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策略：内容安全策略限制脚本执行

新方案设计

架构设计

新方案将采用全局对象预定义的方式，通过系统预置接口实现系统服务访问：

graph TD
    A[第三方应用] --> B[全局对象接口]
    B --> C[系统服务]
    C --> B
    B --> A

核心组件

1. 全局对象接口：在应用上下文中预置系统服务接口
2. 系统服务适配器：将接口调用转换为内部服务调用
3. 权限验证模块：负责应用权限控制
4. 上下文管理器：管理系统与应用间的上下文隔离

接口设计

全局对象结构

// 第三方应用中直接使用预置对象
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	系统内部错误

错误响应格式

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