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

package/docs/02-/346/212/200/346/234/257/345/256/236/347/216/260.md

@@ -0,0 +1,867 @@
+# JSBridge SDK 技术实现（生产级 v2）
+
+> **完整代码实现（代码级文档）**
+
+## 📁 目录结构
+
+```
+src/
+├── core/
+│   └── Bridge.ts              # 200 行
+├── monitor/
+│   └── Monitor.ts             # 180 行
+├── debug/
+│   └── Debug.ts               # 150 行
+├── api/
+│   ├── device.ts              # 80 行
+│   ├── media.ts               # 90 行
+│   ├── router.ts              # 60 行
+│   ├── storage.ts             # 50 行
+│   ├── system.ts              # 40 行
+│   └── log.ts                 # 80 行 ← 新增
+├── types/
+│   └── index.ts               # 120 行
+└── index.ts                   # 100 行
+
+总计：~1150 行
+```
+
+## 1. Bridge.ts - 核心通信（200行）
+
+```typescript
+// src/core/Bridge.ts
+/**
+ * 平台类型
+ */
+export enum Platform {
+  Android = 'android',
+  iOS = 'ios',
+  Unknown = 'unknown'
+}
+
+/**
+ * JSBridge 核心通信类
+ * 兼容 Android 和 iOS
+ */
+class Bridge {
+  private bridge: any = null
+  private isInitialized: boolean = false
+  private platform: Platform = Platform.Unknown
+  
+  constructor() {
+    this.detectPlatform()
+  }
+  
+  /**
+   * 检测平台
+   */
+  private detectPlatform(): void {
+    const ua = navigator.userAgent
+    
+    if (/SoaAndroid|HDApp.*Android/i.test(ua)) {
+      this.platform = Platform.Android
+      console.log('[JSBridge] 检测到 Android 平台')
+      return
+    }
+    
+    if (/iPhone|iPad|iPod/i.test(ua) && /HDApp/i.test(ua)) {
+      this.platform = Platform.iOS
+      console.log('[JSBridge] 检测到 iOS 平台')
+      return
+    }
+    
+    this.platform = Platform.Unknown
+    console.log('[JSBridge] 未检测到原生环境')
+  }
+  
+  /**
+   * 初始化 JSBridge
+   */
+  async init(): Promise<boolean> {
+    if (this.isInitialized) return true
+    if (this.platform === Platform.Unknown) {
+      console.warn('[JSBridge] 不在原生 App 环境中')
+      return false
+    }
+    
+    return new Promise((resolve, reject) => {
+      // 检查是否已有 Bridge 实例
+      if (window.WKWebViewJavascriptBridge) {
+        this.bridge = window.WKWebViewJavascriptBridge
+        this.isInitialized = true
+        console.log(`[JSBridge] ${this.platform} 初始化成功（已存在）`)
+        resolve(true)
+        return
+      }
+      
+      // 等待 Bridge 注入
+      window.WKWVJBCallbacks = window.WKWVJBCallbacks || []
+      window.WKWVJBCallbacks.push((bridge: any) => {
+        this.bridge = bridge
+        this.isInitialized = true
+        console.log(`[JSBridge] ${this.platform} 初始化成功`)
+        resolve(true)
+      })
+      
+      // Android 特定初始化
+      if (this.platform === Platform.Android) {
+        if (window.InjectJavascript) {
+          window.InjectJavascript.init()
+          console.log('[JSBridge] Android 触发初始化')
+        } else {
+          console.error('[JSBridge] Android InjectJavascript 不存在')
+          reject(new Error('Android InjectJavascript 不存在'))
+        }
+      }
+      
+      // iOS 特定初始化
+      if (this.platform === Platform.iOS) {
+        const iframe = document.createElement('iframe')
+        iframe.style.display = 'none'
+        iframe.src = 'https://__bridge_loaded__'
+        document.documentElement.appendChild(iframe)
+        setTimeout(() => document.documentElement.removeChild(iframe), 0)
+        console.log('[JSBridge] iOS 触发初始化')
+      }
+      
+      // 超时处理（10 秒）
+      setTimeout(() => {
+        if (!this.isInitialized) {
+          console.error(`[JSBridge] ${this.platform} 初始化超时`)
+          reject(new Error(`${this.platform} 初始化超时`))
+        }
+      }, 10000)
+    })
+  }
+  
+  /**
+   * 调用原生方法
+   */
+  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 未初始化'))
+    }
+    
+    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)
+          resolve(result)
+        })
+      } catch (error) {
+        console.error(`[JSBridge] [${this.platform}] 调用失败: ${method}`, error)
+        reject(error)
+      }
+    })
+  }
+  
+  /**
+   * 注册方法供原生调用
+   */
+  register(method: string, handler: (data: any, callback: any) => void): void {
+    if (this.platform === Platform.Unknown || !this.isInitialized) {
+      console.warn(`[JSBridge] 无法注册方法: ${method}`)
+      return
+    }
+    
+    console.log(`[JSBridge] [${this.platform}] 注册方法: ${method}`)
+    
+    this.bridge.registerHandler(method, (data: any, responseCallback: any) => {
+      console.log(`[JSBridge] [${this.platform}] 原生调用: ${method}`, data)
+      try {
+        handler(data, responseCallback)
+      } catch (error) {
+        console.error(`[JSBridge] [${this.platform}] 处理失败: ${method}`, error)
+        responseCallback?.({ error: (error as Error).message })
+      }
+    })
+  }
+  
+  getPlatform(): Platform {
+    return this.platform
+  }
+  
+  inApp(): boolean {
+    return this.platform !== Platform.Unknown
+  }
+  
+  isReady(): boolean {
+    return this.isInitialized
+  }
+}
+
+export const bridge = new Bridge()
+```
+
+## 2. log.ts - 日志API（80行）← 新增
+
+```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
+  level: LogLevel
+  message: string
+}
+
+/**
+ * 写日志到原生
+ */
+export async function writeLog(request: LogRequest): Promise<void> {
+  const record = monitor.recordStart('log', bridge.getPlatform(), request)
+  
+  try {
+    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 })
+}
+```
+
+## 3. Monitor.ts - 监控（180行）
+
+```typescript
+// src/monitor/Monitor.ts
+import { bridge } from '../core/Bridge'
+
+export interface MonitorConfig {
+  enabled: boolean
+  autoReport?: boolean
+  reportInterval?: number
+  maxCacheSize?: number
+  logTag?: string
+}
+
+export interface ApiCallRecord {
+  api: string
+  platform: string
+  startTime: number
+  endTime?: number
+  duration?: number
+  success: boolean
+  error?: string
+  params?: any
+  result?: any
+}
+
+export interface PerformanceStats {
+  totalCalls: number
+  successCalls: number
+  failedCalls: number
+  avgDuration: number
+  maxDuration: number
+  minDuration: number
+}
+
+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,
+      maxCacheSize: 100,
+      autoReport: false,
+      logTag: 'JSBridge-Monitor',
+      ...config
+    }
+    
+    if (this.config.autoReport) {
+      this.startAutoReport()
+    }
+  }
+  
+  recordStart(api: string, platform: string, params?: any): ApiCallRecord {
+    if (!this.config.enabled) {
+      return {} as ApiCallRecord
+    }
+    
+    return {
+      api,
+      platform,
+      startTime: Date.now(),
+      success: false,
+      params
+    }
+  }
+  
+  recordEnd(record: ApiCallRecord, success: boolean, result?: any, error?: string): void {
+    if (!this.config.enabled) {
+      return
+    }
+    
+    record.endTime = Date.now()
+    record.duration = record.endTime - record.startTime
+    record.success = success
+    record.result = result
+    record.error = error
+    
+    this.records.push(record)
+    
+    if (this.records.length > this.config.maxCacheSize!) {
+      this.records.shift()
+    }
+    
+    this.updateStats(record)
+  }
+  
+  private updateStats(record: ApiCallRecord): void {
+    if (!record.api) return
+    
+    let stats = this.stats.get(record.api)
+    if (!stats) {
+      stats = {
+        totalCalls: 0,
+        successCalls: 0,
+        failedCalls: 0,
+        avgDuration: 0,
+        maxDuration: 0,
+        minDuration: Infinity
+      }
+      this.stats.set(record.api, stats)
+    }
+    
+    stats.totalCalls++
+    if (record.success) {
+      stats.successCalls++
+    } else {
+      stats.failedCalls++
+    }
+    
+    if (record.duration) {
+      stats.maxDuration = Math.max(stats.maxDuration, record.duration)
+      stats.minDuration = Math.min(stats.minDuration, record.duration)
+      stats.avgDuration = ((stats.avgDuration * (stats.totalCalls - 1)) + record.duration) / stats.totalCalls
+    }
+  }
+  
+  /**
+   * 上报监控数据
+   * ✅ v2: 通过原生 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)
+    }
+  }
+  
+  private startAutoReport(): void {
+    this.reportTimer = setInterval(() => {
+      this.report()
+    }, this.config.reportInterval)
+  }
+  
+  updateConfig(config: Partial<MonitorConfig>): void {
+    this.config = { ...this.config, ...config }
+    
+    if (this.config.autoReport && !this.reportTimer) {
+      this.startAutoReport()
+    } else if (!this.config.autoReport && this.reportTimer) {
+      clearInterval(this.reportTimer)
+      this.reportTimer = undefined
+    }
+  }
+  
+  getStats(api?: string): any {
+    if (api) {
+      return this.stats.get(api) || null
+    }
+    return this.stats
+  }
+  
+  getRecords(limit?: number): ApiCallRecord[] {
+    if (limit) {
+      return this.records.slice(-limit)
+    }
+    return [...this.records]
+  }
+  
+  clear(): void {
+    this.records = []
+    this.stats.clear()
+  }
+}
+
+export const monitor = new Monitor()
+```
+
+## 4. index.ts - 统一导出（100行）
+
+```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'  // ← 新增
+
+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
+  }
+}
+
+export function inApp(): boolean {
+  return bridge.inApp()
+}
+
+export function getPlatform(): Platform {
+  return bridge.getPlatform()
+}
+
+/**
+ * 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
+}
+
+/**
+ * 监控 API
+ */
+export const Monitor = {
+  getStats: monitor.getStats.bind(monitor),
+  getRecords: monitor.getRecords.bind(monitor),
+  clear: monitor.clear.bind(monitor),
+  report: monitor.report.bind(monitor),
+  reportError: monitor.reportError.bind(monitor)
+}
+
+/**
+ * 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 }
+```
+
+## 5. 原生端实现
+
+### 5.1 Android 端
+
+```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)
+}
+```
+
+### 5.2 iOS 端
+
+```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)
+}
+```
+
+## 6. 构建配置
+
+### package.json
+
+```json
+{
+  "name": "@hd-front-end/jsbridge-sdk",
+  "version": "2.0.0",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/types/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "test": "jest"
+  },
+  "peerDependencies": {
+    "vconsole": "^3.15.0"
+  },
+  "peerDependenciesMeta": {
+    "vconsole": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.0.0",
+    "rollup": "^3.0.0",
+    "typescript": "^5.0.0",
+    "vconsole": "^3.15.0"
+  }
+}
+```
+
+### rollup.config.js
+
+```javascript
+import typescript from '@rollup/plugin-typescript'
+
+export default {
+  input: 'src/index.ts',
+  output: [
+    {
+      file: 'dist/index.cjs.js',
+      format: 'cjs'
+    },
+    {
+      file: 'dist/index.esm.js',
+      format: 'esm'
+    }
+  ],
+  plugins: [
+    typescript({
+      declaration: true,
+      declarationDir: 'dist/types'
+    })
+  ],
+  external: ['vconsole']
+}
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2015",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## 7. 完整使用示例
+
+```typescript
+// App.vue
+import { init, JSBridge, getPlatform, Monitor } from '@hd-front-end/jsbridge-sdk'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+export default {
+  async onLaunch() {
+    // #ifdef H5-HD
+    // 1. 初始化
+    await init({
+      debug: {
+        enabled: isDev,
+        useVConsole: isDev && /vconsole=true/.test(location.search),
+        logLevel: isDev ? 'debug' : 'error'
+      },
+      monitor: {
+        enabled: !isDev,
+        autoReport: !isDev,
+        reportInterval: 60000,
+        logTag: 'JSBridge-Monitor'
+      }
+    })
+    
+    console.log('平台:', getPlatform())
+    
+    // 2. 记录启动日志
+    await JSBridge.log.info('App 启动成功', 'AppLifeCycle')
+    
+    // 3. 注册原生回调
+    JSBridge.onRoute((data) => this.$Router.replaceAll(data))
+    JSBridge.onRefreshStore((data) => this.refreshStore(data))
+    
+    // 4. 获取初始数据
+    const appInfo = await JSBridge.getAppInfo()
+    this.refreshStore(JSON.parse(appInfo), true)
+    
+    // 5. 通知加载完成
+    await JSBridge.notifyAppOnload({ name: 'MyApp' })
+    // #endif
+  }
+}
+
+// 业务组件
+export default {
+  methods: {
+    async handleScan() {
+      // 记录用户行为
+      await JSBridge.log.info('用户点击扫码', 'UserBehavior')
+      
+      try {
+        const result = await JSBridge.scan()
+        
+        // 记录成功
+        await JSBridge.log.info(
+          `扫码成功: ${result.resp_result}`,
+          'ScanResult'
+        )
+      } catch (error) {
+        // 记录错误
+        await JSBridge.log.error(
+          `扫码失败: ${error.message}`,
+          'ScanError'
+        )
+      }
+    }
+  }
+}
+```
+
+## 8. 代码统计
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| Bridge.ts | 200 | 核心通信 |
+| Monitor.ts | 180 | 监控（改用log） |
+| Debug.ts | 150 | Debug模式 |
+| log.ts | 80 | Log API ← 新增 |
+| device.ts | 80 | 设备API |
+| media.ts | 90 | 媒体API |
+| router.ts | 60 | 路由API |
+| storage.ts | 50 | 存储API |
+| system.ts | 40 | 系统API |
+| types/index.ts | 120 | 类型定义 |
+| index.ts | 100 | 统一导出 |
+| **总计** | **~1150** | |
+
+## 9. 相关文档
+
+- **[00-项目概览.md](./00-项目概览.md)** - 项目概览
+- **[01-架构设计.md](./01-架构设计.md)** - **架构设计思路**
+- **[03-API使用文档.md](./03-API使用文档.md)** - API 详细文档
+- **[生产级-架构设计-v2.md](./生产级-架构设计-v2.md)** - 完整架构
+
+---
+
+**完整的代码实现，可直接使用** 🎯
+