@hd-front-end/jsbridge-sdk 1.0.2 → 1.0.4

package/docs//347/224/237/344/272/247/347/272/247-/346/236/266/346/236/204/350/256/276/350/256/241-v2.md

@@ -0,0 +1,730 @@
+# JSBridge SDK 生产级架构设计 v2
+
+> **核心理念**：SDK 聚焦于 bridge API，通过原生 log 能力实现监控和日志上报
+
+## 🎯 设计原则
+
+### SDK 的核心职责
+
+✅ **必须做的**：
+1. 封装原生 WebView 通信（核心）
+2. **兼容 Android 和 iOS**（必需）
+3. **通过原生 log 能力实现监控**（生产必需）
+4. **提供 log API 给子应用**（功能必需）
+5. **提供 debug 模式**（开发必需）
+6. 完整的类型定义
+
+❌ **不做的**：
+1. uni API 适配层（子应用决定）
+2. 框架特定封装（Vue/React）
+3. 业务逻辑
+
+## 🏗️ 架构设计
+
+### 1. 整体架构
+
+```
+┌─────────────────────────────────────┐
+│  子应用                              │
+│  - 直接使用 SDK API                  │
+│  - 可选封装适配层                     │
+│  - 调用 log API 上传业务日志          │
+└─────────────────────────────────────┘
+            ↓
+┌─────────────────────────────────────┐
+│  @hd-front-end/jsbridge-sdk                   │
+│                                     │
+│  ├── 核心通信层（Bridge）            │
+│  │   ├── Android 兼容               │
+│  │   └── iOS 兼容                   │
+│  │                                  │
+│  ├── API 层                         │
+│  │   ├── device.ts                 │
+│  │   ├── media.ts                  │
+│  │   ├── log.ts      ← 新增         │
+│  │   └── ...                       │
+│  │                                  │
+│  ├── 监控层（Monitor）              │
+│  │   ├── 性能监控                   │
+│  │   ├── 错误监控                   │
+│  │   ├── 调用统计                   │
+│  │   └── 通过原生 log 上报  ← 修改   │
+│  │                                  │
+│  └── 调试层（Debug）                │
+│      ├── vconsole 集成              │
+│      ├── 日志输出                   │
+│      └── 调用追踪                   │
+└─────────────────────────────────────┘
+            ↓
+┌─────────────────────────────────────┐
+│  原生 WebView                        │
+│  ├── Android (InjectJavascript)     │
+│  │   └── LogUtil (SLF4J+Logback)   │
+│  │       └── 写入日志文件            │
+│  │                                  │
+│  └── iOS (WKWebView)                │
+│      └── LogUtil (OSLog)            │
+│          └── 写入日志文件            │
+└─────────────────────────────────────┘
+```
+
+## 💻 核心实现
+
+### 1. Log API（新增）
+
+```typescript
+// src/api/log.ts
+import { bridge } from '../core/Bridge'
+import { monitor } from '../monitor/Monitor'
+import { debug } from '../debug/Debug'
+
+/**
+ * 日志级别
+ */
+export enum LogLevel {
+  DEBUG = 'DEBUG',
+  INFO = 'INFO',
+  WARN = 'WARN',
+  ERROR = 'ERROR'
+}
+
+/**
+ * 日志请求参数
+ */
+export interface LogRequest {
+  tag?: string           // TAG 标识（可选）
+  level: LogLevel        // 日志等级
+  message: string        // 日志内容
+}
+
+/**
+ * 写日志到原生
+ * 日志会通过原生的 LogUtil 写入文件
+ */
+export async function writeLog(request: LogRequest): Promise<void> {
+  // 记录监控
+  const record = monitor.recordStart('log', bridge.getPlatform(), request)
+  
+  try {
+    // 调用原生 log handler
+    await bridge.call('log', {
+      tag: request.tag || 'JSBridge',
+      level: request.level,
+      message: request.message
+    })
+    
+    // 记录成功
+    monitor.recordEnd(record, true)
+    debug.log('debug', `日志已写入: [${request.level}] ${request.message}`)
+    
+  } catch (error) {
+    // 记录失败
+    monitor.recordEnd(record, false, undefined, (error as Error).message)
+    debug.log('error', `写入日志失败: ${(error as Error).message}`)
+    throw error
+  }
+}
+
+/**
+ * 便捷方法
+ */
+export const log = {
+  debug: (message: string, tag?: string) => 
+    writeLog({ level: LogLevel.DEBUG, message, tag }),
+    
+  info: (message: string, tag?: string) => 
+    writeLog({ level: LogLevel.INFO, message, tag }),
+    
+  warn: (message: string, tag?: string) => 
+    writeLog({ level: LogLevel.WARN, message, tag }),
+    
+  error: (message: string, tag?: string) => 
+    writeLog({ level: LogLevel.ERROR, message, tag })
+}
+```
+
+### 2. 监控层（改为通过 log 上报）
+
+```typescript
+// src/monitor/Monitor.ts
+/**
+ * 监控配置
+ */
+export interface MonitorConfig {
+  enabled: boolean
+  autoReport?: boolean           // 自动上报
+  reportInterval?: number        // 上报间隔（ms）
+  maxCacheSize?: number          // 最大缓存条数
+  logTag?: string                // 日志 TAG，默认 'JSBridge-Monitor'
+}
+
+/**
+ * 监控类
+ * 通过原生 log 能力上报监控数据
+ */
+class Monitor {
+  private config: MonitorConfig
+  private records: ApiCallRecord[] = []
+  private stats: Map<string, PerformanceStats> = new Map()
+  private reportTimer?: NodeJS.Timeout
+  
+  constructor(config: Partial<MonitorConfig> = {}) {
+    this.config = {
+      enabled: true,
+      reportInterval: 60000,     // 默认 1 分钟
+      maxCacheSize: 100,         // 默认缓存 100 条
+      autoReport: false,         // 默认不自动上报
+      logTag: 'JSBridge-Monitor',
+      ...config
+    }
+    
+    if (this.config.autoReport) {
+      this.startAutoReport()
+    }
+  }
+  
+  /**
+   * 上报监控数据
+   * 通过原生 log 能力写入日志文件
+   */
+  async report(): Promise<void> {
+    if (this.records.length === 0) {
+      return
+    }
+    
+    try {
+      const data = {
+        records: this.records,
+        stats: Array.from(this.stats.entries()).map(([api, stats]) => ({
+          api,
+          ...stats
+        })),
+        timestamp: Date.now()
+      }
+      
+      // 通过原生 log 能力上报
+      await bridge.call('log', {
+        tag: this.config.logTag,
+        level: 'INFO',
+        message: `[MONITOR] ${JSON.stringify(data)}`
+      })
+      
+      console.log('[Monitor] 监控数据已上报到原生日志')
+      this.clear()
+    } catch (error) {
+      console.error('[Monitor] 上报失败', error)
+    }
+  }
+  
+  /**
+   * 上报错误信息
+   * 立即上报，不等待定时任务
+   */
+  async reportError(api: string, error: string, detail?: any): Promise<void> {
+    if (!this.config.enabled) {
+      return
+    }
+    
+    try {
+      const errorData = {
+        type: 'error',
+        api,
+        error,
+        detail,
+        platform: bridge.getPlatform(),
+        timestamp: Date.now()
+      }
+      
+      // 立即通过原生 log 能力上报错误
+      await bridge.call('log', {
+        tag: this.config.logTag,
+        level: 'ERROR',
+        message: `[ERROR] ${JSON.stringify(errorData)}`
+      })
+      
+      console.error('[Monitor] 错误已上报:', errorData)
+    } catch (e) {
+      console.error('[Monitor] 上报错误失败', e)
+    }
+  }
+  
+  // ... 其他方法保持不变
+}
+
+export const monitor = new Monitor()
+```
+
+### 3. Bridge 层集成 Log
+
+```typescript
+// src/core/Bridge.ts
+class Bridge {
+  // ... 其他代码
+  
+  /**
+   * 调用原生方法（增强版）
+   */
+  async call<T = any>(method: string, data?: any): Promise<T> {
+    if (this.platform === Platform.Unknown) {
+      return Promise.reject(new Error('不在原生 App 环境中'))
+    }
+    
+    if (!this.isInitialized) {
+      return Promise.reject(new Error('JSBridge 未初始化'))
+    }
+    
+    // Debug: 追踪调用
+    debug.trace(method, data)
+    
+    // Monitor: 开始记录
+    const record = monitor.recordStart(method, this.platform, data)
+    
+    console.log(`[JSBridge] [${this.platform}] 调用: ${method}`, data)
+    
+    return new Promise((resolve, reject) => {
+      try {
+        this.bridge.callHandler(method, data, (result: any) => {
+          console.log(`[JSBridge] [${this.platform}] 返回: ${method}`, result)
+          
+          // Monitor: 记录成功
+          monitor.recordEnd(record, true, result)
+          
+          // Debug: 记录日志
+          debug.log('info', `API 调用成功: ${method}`, { params: data, result })
+          
+          resolve(result)
+        })
+      } catch (error) {
+        console.error(`[JSBridge] [${this.platform}] 调用失败: ${method}`, error)
+        
+        // Monitor: 记录失败
+        monitor.recordEnd(record, false, undefined, (error as Error).message)
+        
+        // Monitor: 立即上报错误（通过 log）
+        monitor.reportError(method, (error as Error).message, { params: data })
+        
+        // Debug: 记录错误
+        debug.log('error', `API 调用失败: ${method}`, { params: data, error })
+        
+        reject(error)
+      }
+    })
+  }
+}
+```
+
+### 4. 统一导出
+
+```typescript
+// src/index.ts
+import { bridge, Platform } from './core/Bridge'
+import { monitor, MonitorConfig } from './monitor/Monitor'
+import { debug, DebugConfig } from './debug/Debug'
+import * as device from './api/device'
+import * as media from './api/media'
+import * as router from './api/router'
+import * as storage from './api/storage'
+import * as system from './api/system'
+import { writeLog, log, LogLevel, LogRequest } from './api/log'  // 新增
+
+/**
+ * SDK 配置
+ */
+export interface JSBridgeConfig {
+  debug?: Partial<DebugConfig>
+  monitor?: Partial<MonitorConfig>
+}
+
+/**
+ * 初始化 JSBridge
+ */
+export async function init(config?: JSBridgeConfig): Promise<boolean> {
+  try {
+    // 配置 debug
+    if (config?.debug) {
+      debug.updateConfig(config.debug)
+      if (config.debug.useVConsole) {
+        await debug.initVConsole()
+      }
+    }
+    
+    // 配置 monitor
+    if (config?.monitor) {
+      monitor.updateConfig(config.monitor)
+    }
+    
+    // 初始化 bridge
+    const success = await bridge.init()
+    
+    // 保存平台信息
+    (window as any).__jsbridgePlatform = bridge.getPlatform()
+    
+    // 通过 log API 记录初始化成功
+    if (success) {
+      await writeLog({
+        level: LogLevel.INFO,
+        message: `JSBridge 初始化成功 [${bridge.getPlatform()}]`
+      })
+    }
+    
+    return success
+  } catch (error) {
+    console.error('[JSBridge] 初始化失败', error)
+    debug.log('error', '初始化失败', error)
+    
+    // 尝试上报错误
+    try {
+      await writeLog({
+        level: LogLevel.ERROR,
+        message: `JSBridge 初始化失败: ${(error as Error).message}`
+      })
+    } catch (e) {
+      // 忽略上报失败
+    }
+    
+    return false
+  }
+}
+
+/**
+ * JSBridge API
+ */
+export const JSBridge = {
+  // 设备相关
+  scan: device.scan,
+  vibrate: device.vibrate,
+  getDeviceInfo: device.getDeviceInfo,
+  getNetworkType: device.getNetworkType,
+  
+  // 媒体相关
+  chooseMedia: media.chooseMedia,
+  uploadFile: media.uploadFile,
+  previewImage: media.previewImage,
+  getImageInfo: media.getImageInfo,
+  bluetoothPrint: media.bluetoothPrint,
+  
+  // 路由相关
+  setNavigationBar: router.setNavigationBar,
+  closeWebView: router.closeWebView,
+  onRoute: router.onRoute,
+  onGetRouteInfo: router.onGetRouteInfo,
+  notifyRouteChange: router.notifyRouteChange,
+  
+  // 存储相关
+  getStorage: storage.getStorage,
+  setStorage: storage.setStorage,
+  getAppInfo: storage.getAppInfo,
+  onRefreshStore: storage.onRefreshStore,
+  notifyAppOnload: storage.notifyAppOnload,
+  
+  // 系统相关
+  makePhoneCall: system.makePhoneCall,
+  onPdaScan: system.onPdaScan,
+  
+  // 日志相关（新增）
+  writeLog,      // 通用 log 方法
+  log            // 便捷方法 { debug, info, warn, error }
+}
+
+/**
+ * 监控 API
+ */
+export const Monitor = {
+  getStats: monitor.getStats.bind(monitor),
+  getRecords: monitor.getRecords.bind(monitor),
+  clear: monitor.clear.bind(monitor),
+  report: monitor.report.bind(monitor),             // 手动上报（通过 log）
+  reportError: monitor.reportError.bind(monitor)    // 上报错误（通过 log）
+}
+
+/**
+ * Debug API
+ */
+export const Debug = {
+  trace: debug.trace.bind(debug),
+  getLogs: debug.getLogs.bind(debug),
+  clearLogs: debug.clearLogs.bind(debug)
+}
+
+// 导出类型
+export * from './types'
+export { Platform, MonitorConfig, DebugConfig, LogLevel, LogRequest }
+```
+
+## 📚 使用示例
+
+### 1. 子应用使用 log API
+
+```typescript
+import { JSBridge, LogLevel } from '@hd-front-end/jsbridge-sdk'
+
+// 方式 1：使用通用方法
+await JSBridge.writeLog({
+  level: LogLevel.INFO,
+  message: '用户点击了购买按钮',
+  tag: 'ShoppingCart'
+})
+
+// 方式 2：使用便捷方法
+await JSBridge.log.info('用户点击了购买按钮', 'ShoppingCart')
+await JSBridge.log.error('支付失败', 'Payment')
+await JSBridge.log.warn('库存不足', 'Inventory')
+await JSBridge.log.debug('调试信息', 'Debug')
+```
+
+### 2. 监控数据通过 log 上报
+
+```typescript
+import { init, Monitor } from '@hd-front-end/jsbridge-sdk'
+
+// 初始化时配置监控
+await init({
+  monitor: {
+    enabled: true,
+    autoReport: true,         // 自动上报
+    reportInterval: 60000,    // 1 分钟上报一次
+    logTag: 'JSBridge-Monitor'  // 日志 TAG
+  }
+})
+
+// 使用 API（自动监控）
+await JSBridge.scan()
+
+// 监控数据会自动通过原生 log 能力写入日志文件
+// 原生端可以统一收集这些日志文件上传到服务器
+```
+
+### 3. 错误立即上报
+
+```typescript
+import { JSBridge, Monitor } from '@hd-front-end/jsbridge-sdk'
+
+try {
+  await JSBridge.scan()
+} catch (error) {
+  // SDK 会自动上报错误
+  // 也可以手动上报额外信息
+  await Monitor.reportError('scan', error.message, {
+    userAction: '用户尝试扫码',
+    currentPage: '/product-detail'
+  })
+}
+```
+
+### 4. 业务日志上报
+
+```typescript
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+// 记录用户行为
+await JSBridge.log.info('用户进入商品详情页', 'UserBehavior')
+
+// 记录业务错误
+await JSBridge.log.error('订单创建失败: 库存不足', 'OrderService')
+
+// 记录性能数据
+await JSBridge.log.info(`页面加载耗时: ${loadTime}ms`, 'Performance')
+
+// 记录调试信息
+await JSBridge.log.debug(`API 响应: ${JSON.stringify(response)}`, 'API')
+```
+
+## 🔄 日志流程
+
+### 1. SDK 监控日志流程
+
+```
+SDK API 调用
+    ↓
+Monitor 记录性能数据
+    ↓
+定时任务触发（1 分钟）
+    ↓
+Monitor.report()
+    ↓
+调用 bridge.call('log', {...})
+    ↓
+原生 LogUtil 写入日志文件
+    ↓
+原生统一收集上传到服务器
+```
+
+### 2. 子应用业务日志流程
+
+```
+子应用调用 JSBridge.log.info(...)
+    ↓
+SDK log API
+    ↓
+调用 bridge.call('log', {...})
+    ↓
+原生 LogUtil 写入日志文件
+    ↓
+原生统一收集上传到服务器
+```
+
+### 3. 错误日志流程（立即上报）
+
+```
+API 调用失败
+    ↓
+Monitor.reportError()
+    ↓
+立即调用 bridge.call('log', {level: 'ERROR', ...})
+    ↓
+原生 LogUtil 写入日志文件（ERROR 级别）
+    ↓
+原生可以立即上传 ERROR 日志
+```
+
+## 📊 原生端实现参考
+
+### Android (Kotlin)
+
+```kotlin
+// 原生端 log handler 注册
+webView.registerHandler("log") { data, callback ->
+    val request = Gson().fromJson(data, UniLog::class.java)
+    
+    // 使用 LogUtil 写入日志
+    when (request.level) {
+        "DEBUG" -> LogUtil.debug(request.tag, request.message)
+        "INFO" -> LogUtil.info(request.tag, request.message)
+        "WARN" -> LogUtil.warn(request.tag, request.message)
+        "ERROR" -> LogUtil.error(request.tag, request.message)
+    }
+    
+    callback?.invoke(null)
+}
+
+// LogUtil 会通过 SLF4J + Logback 写入文件
+// 配置在 logback.xml 中
+```
+
+### iOS (Swift)
+
+```swift
+// 原生端 log handler 注册
+bridge.registerHandler("log") { data, callback in
+    guard let request = data as? [String: Any],
+          let level = request["level"] as? String,
+          let message = request["message"] as? String else {
+        callback?(nil)
+        return
+    }
+    
+    let tag = request["tag"] as? String ?? "JSBridge"
+    
+    // 使用 OSLog 写入日志
+    switch level {
+    case "DEBUG":
+        os_log(.debug, log: OSLog(subsystem: "JSBridge", category: tag), "%{public}@", message)
+    case "INFO":
+        os_log(.info, log: OSLog(subsystem: "JSBridge", category: tag), "%{public}@", message)
+    case "WARN":
+        os_log(.error, log: OSLog(subsystem: "JSBridge", category: tag), "[WARN] %{public}@", message)
+    case "ERROR":
+        os_log(.fault, log: OSLog(subsystem: "JSBridge", category: tag), "%{public}@", message)
+    default:
+        break
+    }
+    
+    callback?(nil)
+}
+```
+
+## 📊 目录结构
+
+```
+@hd-front-end/jsbridge-sdk/
+├── src/
+│   ├── core/
+│   │   └── Bridge.ts              # 核心通信（200 行）
+│   │
+│   ├── monitor/
+│   │   └── Monitor.ts             # 监控（改用 log 上报）
+│   │
+│   ├── debug/
+│   │   └── Debug.ts               # Debug 模式
+│   │
+│   ├── api/
+│   │   ├── device.ts
+│   │   ├── media.ts
+│   │   ├── router.ts
+│   │   ├── storage.ts
+│   │   ├── system.ts
+│   │   └── log.ts                 # ← 新增 log API
+│   │
+│   ├── types/
+│   │   └── index.ts
+│   │
+│   └── index.ts                   # 统一导出
+│
+└── package.json
+```
+
+## 💡 核心价值
+
+### 1. 统一日志管理
+
+✅ **SDK 监控日志** - 通过 log 写入原生  
+✅ **子应用业务日志** - 通过 log API 写入原生  
+✅ **统一收集** - 原生统一管理日志文件  
+✅ **统一上传** - 原生统一上传到服务器  
+
+### 2. 两个目的都实现
+
+✅ **监控 SDK 稳定性**
+- SDK 内部自动记录性能数据
+- 定时通过 log 上报
+- 错误立即通过 log 上报
+- 原生收集后可分析 SDK 调用情况
+
+✅ **提供子应用上传日志能力**
+- 子应用调用 `JSBridge.log.*` 方法
+- 日志通过 bridge 写入原生
+- 原生统一管理和上传
+- 子应用无需关心上传细节
+
+### 3. 优势
+
+✅ **统一管理** - 所有日志都通过原生 LogUtil  
+✅ **性能更好** - 不需要 H5 端发起 HTTP 请求  
+✅ **更可靠** - 原生端控制上传时机和策略  
+✅ **易于扩展** - 原生可以灵活处理日志（压缩、加密、批量上传等）  
+
+## 📊 代码统计
+
+| 模块 | 文件 | 代码行数 |
+|------|------|---------|
+| 核心通信（兼容） | Bridge.ts | 200 行 |
+| 监控（改用 log） | Monitor.ts | 180 行 |
+| Debug | Debug.ts | 150 行 |
+| Log API（新增） | log.ts | 80 行 |
+| 其他 API | 5 个文件 | 320 行 |
+| 类型定义 | types/index.ts | 120 行 |
+| 统一导出 | index.ts | 100 行 |
+| **总计** | **11 个文件** | **~1150 行** |
+
+打包体积：~20KB（gzip: ~7KB）
+
+## 🎯 总结
+
+### 核心改进
+
+1. ✅ **监控数据通过 log 上报** - 不再使用 HTTP
+2. ✅ **提供 log API** - 子应用可以上传日志
+3. ✅ **统一日志管理** - 原生端统一处理
+4. ✅ **两个目的都实现** - 监控 SDK + 子应用日志
+
+### 设计理念不变
+
+- SDK 聚焦于 bridge API
+- 不包含适配层
+- 兼容 Android/iOS
+- 简洁实用
+
+---
+
+**统一日志，统一管理，简洁高效** 🎯
+