vue-desktop/src/sdk/types.ts

/**
 * 系统SDK主接口
 * 为第三方应用提供统一的系统服务访问接口
 */

// =============================================================================
// 核心类型定义
// =============================================================================

/**
 * SDK初始化配置
 */
export interface SDKConfig {
  appId: string
  appName: string
  version: string
  permissions: string[]
  debug?: boolean
}

/**
 * API响应结果包装器
 */
export interface APIResponse<T = any> {
  success: boolean
  data?: T
  error?: string
  code?: number
}

/**
 * 事件回调函数类型
 */
export type EventCallback<T = any> = (data: T) => void | Promise<void>

/**
 * 权限状态枚举
 */
export enum PermissionStatus {
  GRANTED = 'granted',
  DENIED = 'denied',
  PROMPT = 'prompt'
}

// =============================================================================
// 窗体SDK接口
// =============================================================================

/**
 * 窗体状态
 */
export enum WindowState {
  NORMAL = 'normal',
  MINIMIZED = 'minimized',
  MAXIMIZED = 'maximized',
  FULLSCREEN = 'fullscreen'
}

/**
 * 窗体事件类型
 */
export interface WindowEvents {
  onResize: (width: number, height: number) => void
  onMove: (x: number, y: number) => void
  onStateChange: (state: WindowState) => void
  onFocus: () => void
  onBlur: () => void
  onClose: () => void
}

/**
 * 窗体SDK接口
 */
export interface 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>>

  /**
   * 全屏显示
   */
  fullscreen(): Promise<APIResponse<boolean>>

  /**
   * 关闭窗体
   */
  close(): Promise<APIResponse<boolean>>

  /**
   * 获取当前窗体状态
   */
  getState(): Promise<APIResponse<WindowState>>

  /**
   * 获取窗体尺寸
   */
  getSize(): Promise<APIResponse<{ width: number; height: number }>>

  /**
   * 获取窗体位置
   */
  getPosition(): Promise<APIResponse<{ x: number; y: number }>>

  /**
   * 监听窗体事件
   */
  on<K extends keyof WindowEvents>(event: K, callback: WindowEvents[K]): void

  /**
   * 移除事件监听器
   */
  off<K extends keyof WindowEvents>(event: K, callback?: WindowEvents[K]): void
}

// =============================================================================
// 存储SDK接口
// =============================================================================

/**
 * 存储事件类型
 */
export interface StorageEvents {
  onChange: (key: string, newValue: any, oldValue: any) => void
  onQuotaExceeded: (usedSpace: number, maxSpace: number) => void
}

/**
 * 存储使用统计
 */
export interface StorageStats {
  usedSpace: number // 已使用空间(MB)
  maxSpace: number // 最大空间(MB)
  keysCount: number // 键数量
  lastAccessed: Date
}

/**
 * 存储SDK接口
 */
export interface StorageSDK {
  /**
   * 存储数据
   */
  set(key: string, value: any): Promise<APIResponse<boolean>>

  /**
   * 获取数据
   */
  get<T = any>(key: string): Promise<APIResponse<T | null>>

  /**
   * 删除数据
   */
  remove(key: string): Promise<APIResponse<boolean>>

  /**
   * 清空所有数据
   */
  clear(): Promise<APIResponse<boolean>>

  /**
   * 获取所有键名
   */
  keys(): Promise<APIResponse<string[]>>

  /**
   * 检查键是否存在
   */
  has(key: string): Promise<APIResponse<boolean>>

  /**
   * 获取存储使用统计
   */
  getStats(): Promise<APIResponse<StorageStats>>

  /**
   * 监听存储变化
   */
  on<K extends keyof StorageEvents>(event: K, callback: StorageEvents[K]): void

  /**
   * 移除事件监听器
   */
  off<K extends keyof StorageEvents>(event: K, callback?: StorageEvents[K]): void
}

// =============================================================================
// 网络SDK接口
// =============================================================================

/**
 * HTTP方法
 */
export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'

/**
 * 网络请求配置
 */
export interface NetworkRequestConfig {
  method?: HTTPMethod
  headers?: Record<string, string>
  body?: any
  timeout?: number
  responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer'
}

/**
 * 网络响应
 */
export interface NetworkResponse<T = any> {
  data: T
  status: number
  statusText: string
  headers: Record<string, string>
  url: string
}

/**
 * 上传进度回调
 */
export type UploadProgressCallback = (loaded: number, total: number) => void

/**
 * 下载进度回调
 */
export type DownloadProgressCallback = (loaded: number, total: number) => void

/**
 * 网络SDK接口
 */
export interface NetworkSDK {
  /**
   * 发送HTTP请求
   */
  request<T = any>(url: string, config?: NetworkRequestConfig): Promise<APIResponse<NetworkResponse<T>>>

  /**
   * GET请求
   */
  get<T = any>(url: string, config?: Omit<NetworkRequestConfig, 'method'>): Promise<APIResponse<NetworkResponse<T>>>

  /**
   * POST请求
   */
  post<T = any>(url: string, data?: any, config?: Omit<NetworkRequestConfig, 'method' | 'body'>): Promise<APIResponse<NetworkResponse<T>>>

  /**
   * PUT请求
   */
  put<T = any>(url: string, data?: any, config?: Omit<NetworkRequestConfig, 'method' | 'body'>): Promise<APIResponse<NetworkResponse<T>>>

  /**
   * DELETE请求
   */
  delete<T = any>(url: string, config?: Omit<NetworkRequestConfig, 'method'>): Promise<APIResponse<NetworkResponse<T>>>

  /**
   * 上传文件
   */
  upload(url: string, file: File | Blob, onProgress?: UploadProgressCallback): Promise<APIResponse<NetworkResponse>>

  /**
   * 下载文件
   */
  download(url: string, filename?: string, onProgress?: DownloadProgressCallback): Promise<APIResponse<Blob>>

  /**
   * 检查网络状态
   */
  isOnline(): Promise<APIResponse<boolean>>

  /**
   * 获取网络请求统计
   */
  getStats(): Promise<APIResponse<{ requestCount: number; failureCount: number; averageTime: number }>>
}

// =============================================================================
// 事件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 // 只监听一次
}

/**
 * 事件SDK接口
 */
export interface EventSDK {
  /**
   * 发送事件消息
   */
  emit<T = any>(channel: string, data: T): Promise<APIResponse<string>>

  /**
   * 订阅事件频道
   */
  on<T = any>(
    channel: string, 
    callback: (message: EventMessage<T>) => void, 
    config?: EventSubscriptionConfig
  ): Promise<APIResponse<string>>

  /**
   * 取消订阅
   */
  off(subscriptionId: string): Promise<APIResponse<boolean>>

  /**
   * 广播消息
   */
  broadcast<T = any>(channel: string, data: T): Promise<APIResponse<string>>

  /**
   * 发送点对点消息
   */
  sendTo<T = any>(targetAppId: string, data: T): Promise<APIResponse<string>>

  /**
   * 获取频道订阅者数量
   */
  getSubscriberCount(channel: string): Promise<APIResponse<number>>

  /**
   * 获取可用频道列表
   */
  getChannels(): Promise<APIResponse<string[]>>
}

// =============================================================================
// UI SDK接口
// =============================================================================

/**
 * 对话框类型
 */
export enum DialogType {
  INFO = 'info',
  SUCCESS = 'success',
  WARNING = 'warning',
  ERROR = 'error',
  CONFIRM = 'confirm'
}

/**
 * 对话框选项
 */
export interface DialogOptions {
  title?: string
  message: string
  type?: DialogType
  buttons?: string[]
  defaultButton?: number
  cancelButton?: number
}

/**
 * 通知选项
 */
export interface NotificationOptions {
  title: string
  body: string
  icon?: string
  duration?: number // 显示时长(毫秒)
  actions?: Array<{ title: string; action: string }>
}

/**
 * 文件选择选项
 */
export interface FilePickerOptions {
  accept?: string // 文件类型过滤
  multiple?: boolean // 是否多选
  directory?: boolean // 是否选择目录
}

/**
 * UI SDK接口
 */
export interface UISDK {
  /**
   * 显示对话框
   */
  showDialog(options: DialogOptions): Promise<APIResponse<{ buttonIndex: number; inputValue?: string }>>

  /**
   * 显示通知
   */
  showNotification(options: NotificationOptions): Promise<APIResponse<string>>

  /**
   * 显示文件选择器
   */
  showFilePicker(options?: FilePickerOptions): Promise<APIResponse<FileList | null>>

  /**
   * 显示保存文件对话框
   */
  showSaveDialog(defaultName?: string, accept?: string): Promise<APIResponse<string | null>>

  /**
   * 显示Toast消息
   */
  showToast(message: string, type?: 'info' | 'success' | 'warning' | 'error', duration?: number): Promise<APIResponse<string>>

  /**
   * 显示加载指示器
   */
  showLoading(message?: string): Promise<APIResponse<string>>

  /**
   * 隐藏加载指示器
   */
  hideLoading(id: string): Promise<APIResponse<boolean>>

  /**
   * 显示进度条
   */
  showProgress(options: { title?: string; message?: string; progress: number }): Promise<APIResponse<string>>

  /**
   * 更新进度条
   */
  updateProgress(id: string, progress: number, message?: string): Promise<APIResponse<boolean>>

  /**
   * 隐藏进度条
   */
  hideProgress(id: string): Promise<APIResponse<boolean>>
}

// =============================================================================
// 系统SDK接口
// =============================================================================

/**
 * 系统信息
 */
export interface SystemInfo {
  platform: string
  userAgent: string
  language: string
  timezone: string
  screenResolution: { width: number; height: number }
  colorDepth: number
  pixelRatio: number
}

/**
 * 应用信息
 */
export interface AppInfo {
  id: string
  name: string
  version: string
  permissions: string[]
  createdAt: Date
  lastActiveAt: Date
}

/**
 * 系统SDK接口
 */
export interface SystemSDK {
  /**
   * 获取系统信息
   */
  getSystemInfo(): Promise<APIResponse<SystemInfo>>

  /**
   * 获取当前应用信息
   */
  getAppInfo(): Promise<APIResponse<AppInfo>>

  /**
   * 请求权限
   */
  requestPermission(permission: string, reason?: string): Promise<APIResponse<PermissionStatus>>

  /**
   * 检查权限状态
   */
  checkPermission(permission: string): Promise<APIResponse<PermissionStatus>>

  /**
   * 获取剪贴板内容
   */
  getClipboard(): Promise<APIResponse<string>>

  /**
   * 设置剪贴板内容
   */
  setClipboard(text: string): Promise<APIResponse<boolean>>

  /**
   * 打开外部链接
   */
  openExternal(url: string): Promise<APIResponse<boolean>>

  /**
   * 获取当前时间
   */
  getCurrentTime(): Promise<APIResponse<Date>>

  /**
   * 生成UUID
   */
  generateUUID(): Promise<APIResponse<string>>

  /**
   * 退出应用
   */
  exit(): Promise<APIResponse<boolean>>
}

// =============================================================================
// 主SDK接口
// =============================================================================

/**
 * 系统SDK主接口
 * 整合所有子模块SDK
 */
export interface SystemDesktopSDK {
  /**
   * SDK版本
   */
  readonly version: string

  /**
   * 当前应用ID
   */
  readonly appId: string

  /**
   * 是否已初始化
   */
  readonly initialized: boolean

  /**
   * 窗体操作SDK
   */
  readonly window: WindowSDK

  /**
   * 存储操作SDK
   */
  readonly storage: StorageSDK

  /**
   * 网络请求SDK
   */
  readonly network: NetworkSDK

  /**
   * 事件通信SDK
   */
  readonly events: EventSDK

  /**
   * UI操作SDK
   */
  readonly ui: UISDK

  /**
   * 系统操作SDK
   */
  readonly system: SystemSDK

  /**
   * 初始化SDK
   */
  init(config: SDKConfig): Promise<APIResponse<boolean>>

  /**
   * 销毁SDK
   */
  destroy(): Promise<APIResponse<boolean>>

  /**
   * 获取SDK状态
   */
  getStatus(): Promise<APIResponse<{ initialized: boolean; connected: boolean; permissions: string[] }>>
}

// =============================================================================
// 全局类型声明
// =============================================================================

declare global {
  interface Window {
    /**
     * 系统桌面SDK全局实例
     */
    SystemSDK: SystemDesktopSDK
  }
}