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

package/docs/01-/346/236/266/346/236/204/350/256/276/350/256/241.md

@@ -0,0 +1,623 @@
+# JSBridge SDK 架构设计（生产级 v2）
+
+> **架构设计思路和接口定义（不含完整代码）**
+
+## 1. 设计目标
+
+设计一个**生产可用**的 JSBridge SDK，实现 H5 与原生应用的高效通信。
+
+### 核心原则
+
+- **职责单一**：SDK 聚焦于 bridge API
+- **统一日志**：监控和业务日志都通过原生 log
+- **双平台兼容**：自动兼容 Android 和 iOS
+- **稳定可观测**：完善的错误处理和监控
+
+### 两个目的
+
+1. ✅ **监控 SDK 稳定性** - SDK 自动记录并上报
+2. ✅ **提供日志能力** - 子应用可上传日志
+
+## 2. 整体架构
+
+### 2.1 三层架构
+
+```
+┌─────────────────────────────────────┐
+│         子应用层                     │
+│  - 直接使用 SDK API                  │
+│  - 调用 JSBridge.log.info(...)      │
+│  - 可选封装适配层（自己决定）         │
+└─────────────────────────────────────┘
+            ↓
+┌─────────────────────────────────────┐
+│         SDK 层                       │
+│                                     │
+│  ┌─────────────────────────────┐   │
+│  │   核心通信（Bridge）         │   │
+│  │   - 平台检测                 │   │
+│  │   - Android/iOS 兼容         │   │
+│  │   - 超时处理                 │   │
+│  └─────────────────────────────┘   │
+│                                     │
+│  ┌─────────────────────────────┐   │
+│  │   API 层                    │   │
+│  │   - device/media/router     │   │
+│  │   - storage/system          │   │
+│  │   - log ← 新增              │   │
+│  └─────────────────────────────┘   │
+│                                     │
+│  ┌─────────────────────────────┐   │
+│  │   监控层（Monitor）          │   │
+│  │   - 性能监控                 │   │
+│  │   - 通过 log 上报 ← v2      │   │
+│  └─────────────────────────────┘   │
+│                                     │
+│  ┌─────────────────────────────┐   │
+│  │   Debug 层                  │   │
+│  │   - vconsole 集成            │   │
+│  │   - 调用追踪                 │   │
+│  └─────────────────────────────┘   │
+└─────────────────────────────────────┘
+            ↓
+┌─────────────────────────────────────┐
+│         原生层                       │
+│  - Android: InjectJavascript        │
+│  - iOS: iframe 触发                 │
+│  - 统一 log handler                 │
+│  - LogUtil 写入日志文件              │
+│  - 统一上传到服务器                  │
+└─────────────────────────────────────┘
+```
+
+### 2.2 核心模块
+
+| 模块 | 职责 | 代码量 |
+|------|------|--------|
+| **Bridge** | 核心通信、平台兼容 | 200 行 |
+| **Monitor** | 性能监控、通过 log 上报 | 180 行 |
+| **Debug** | vconsole、调用追踪 | 150 行 |
+| **Log API** | 提供日志上传能力 | 80 行 |
+| **device/media/router等** | 各类 API | 320 行 |
+| **types** | 类型定义 | 120 行 |
+| **index** | 统一导出 | 100 行 |
+| **总计** | | **~1150 行** |
+
+## 3. 核心模块设计
+
+### 3.1 Bridge 核心通信层
+
+#### 设计职责
+
+- 平台检测：Android/iOS/Unknown
+- 平台特定初始化
+- 统一的 call/register 接口
+- 超时处理
+
+#### 关键接口
+
+```typescript
+enum Platform {
+  Android = 'android',
+  iOS = 'ios',
+  Unknown = 'unknown'
+}
+
+class Bridge {
+  // 初始化（平台特定）
+  async init(): Promise<boolean>
+  
+  // 调用原生方法
+  call<T>(method: string, data?: any): Promise<T>
+  
+  // 注册方法供原生调用
+  register(method: string, handler: Function): void
+  
+  // 获取平台
+  getPlatform(): Platform
+  
+  // 是否在原生 App 中
+  inApp(): boolean
+}
+```
+
+#### 平台检测逻辑
+
+```typescript
+private detectPlatform(): void {
+  const ua = navigator.userAgent
+  // Android: /SoaAndroid|HDApp.*Android/i
+  // iOS: /iPhone|iPad|iPod/i && /HDApp/i
+  // Unknown: 其他
+}
+```
+
+#### 初始化逻辑
+
+```typescript
+// Android: window.InjectJavascript.init()
+// iOS: 创建 iframe，src = 'https://__bridge_loaded__'
+// 超时: 10 秒
+```
+
+### 3.2 Monitor 监控层
+
+#### 设计职责
+
+- 自动记录 API 调用性能
+- 自动记录错误信息
+- 定时通过 log API 上报
+- 错误立即通过 log API 上报
+
+#### 关键接口
+
+```typescript
+interface ApiCallRecord {
+  api: string
+  platform: string
+  startTime: number
+  duration?: number
+  success: boolean
+  error?: string
+}
+
+interface PerformanceStats {
+  totalCalls: number
+  successCalls: number
+  failedCalls: number
+  avgDuration: number
+  maxDuration: number
+  minDuration: number
+}
+
+class Monitor {
+  // 记录调用
+  recordStart(api: string, platform: string, params?: any): ApiCallRecord
+  recordEnd(record: ApiCallRecord, success: boolean, result?, error?): void
+  
+  // 上报（通过 log API）
+  async report(): Promise<void>
+  
+  // 立即上报错误
+  async reportError(api: string, error: string, detail?): Promise<void>
+  
+  // 查询统计
+  getStats(api?: string): PerformanceStats | Map<string, PerformanceStats>
+  getRecords(limit?: number): ApiCallRecord[]
+}
+```
+
+#### 上报机制
+
+**v2 版本（正确）**：
+```typescript
+// 定时上报
+await bridge.call('log', {
+  tag: 'JSBridge-Monitor',
+  level: 'INFO',
+  message: `[MONITOR] ${JSON.stringify(data)}`
+})
+
+// 错误立即上报
+await bridge.call('log', {
+  tag: 'JSBridge-Monitor',
+  level: 'ERROR',
+  message: `[ERROR] ${JSON.stringify(errorData)}`
+})
+```
+
+### 3.3 Debug 调试层
+
+#### 设计职责
+
+- vconsole 集成
+- 调用追踪
+- 日志记录
+- 开发/生产分离
+
+#### 关键接口
+
+```typescript
+interface DebugConfig {
+  enabled: boolean
+  useVConsole?: boolean
+  logLevel?: 'debug' | 'info' | 'warn' | 'error'
+}
+
+class Debug {
+  // 初始化 vconsole
+  async initVConsole(): Promise<void>
+  
+  // 记录日志
+  log(level: string, message: string, data?: any): void
+  
+  // 追踪 API 调用
+  trace(api: string, params?: any): void
+  
+  // 查询日志
+  getLogs(level?: string, limit?: number): any[]
+}
+```
+
+### 3.4 Log API 层（新增）
+
+#### 设计职责
+
+- 提供简单的日志 API
+- 将日志写入原生
+- 支持不同级别
+
+#### 关键接口
+
+```typescript
+enum LogLevel {
+  DEBUG = 'DEBUG',
+  INFO = 'INFO',
+  WARN = 'WARN',
+  ERROR = 'ERROR'
+}
+
+interface LogRequest {
+  tag?: string
+  level: LogLevel
+  message: string
+}
+
+// 通用方法
+async function writeLog(request: LogRequest): Promise<void>
+
+// 便捷方法
+const log = {
+  debug: (message: string, tag?: string) => Promise<void>
+  info: (message: string, tag?: string) => Promise<void>
+  warn: (message: string, tag?: string) => Promise<void>
+  error: (message: string, tag?: string) => Promise<void>
+}
+```
+
+## 4. 数据流设计
+
+### 4.1 API 调用流程
+
+```
+子应用调用
+    ↓
+SDK API 层
+    ↓
+Monitor 记录开始
+    ↓
+Debug 追踪
+    ↓
+Bridge 调用
+    ↓
+原生处理
+    ↓
+Bridge 返回
+    ↓
+Monitor 记录结束
+    ↓
+Debug 记录日志
+    ↓
+返回给子应用
+```
+
+### 4.2 监控上报流程
+
+```
+API 调用（自动记录）
+    ↓
+Monitor 记录性能数据
+    ↓
+定时任务（1 分钟）
+    ↓
+Monitor.report()
+    ↓
+调用 bridge.call('log', {...})
+    ↓
+原生 LogUtil 写入日志文件
+    ↓
+原生统一上传到服务器
+```
+
+### 4.3 日志上传流程
+
+```
+子应用调用 JSBridge.log.info(...)
+    ↓
+SDK log API
+    ↓
+调用 bridge.call('log', {...})
+    ↓
+原生 LogUtil 写入日志文件
+    ↓
+原生统一上传到服务器
+```
+
+### 4.4 错误上报流程（立即）
+
+```
+API 调用失败
+    ↓
+Monitor 捕获错误
+    ↓
+Monitor.reportError()
+    ↓
+立即调用 bridge.call('log', {level: 'ERROR', ...})
+    ↓
+原生 LogUtil 写入（ERROR 级别）
+    ↓
+原生立即上传 ERROR 日志
+```
+
+## 5. 接口设计
+
+### 5.1 初始化接口
+
+```typescript
+interface JSBridgeConfig {
+  debug?: Partial<DebugConfig>
+  monitor?: Partial<MonitorConfig>
+}
+
+interface MonitorConfig {
+  enabled: boolean
+  autoReport?: boolean        // 自动上报
+  reportInterval?: number     // 上报间隔（ms）
+  maxCacheSize?: number       // 最大缓存条数
+  logTag?: string             // 日志 TAG
+}
+
+// 使用示例
+await init({
+  debug: {
+    enabled: isDev,
+    useVConsole: isDev
+  },
+  monitor: {
+    enabled: !isDev,
+    autoReport: !isDev,
+    reportInterval: 60000,
+    logTag: 'JSBridge-Monitor'
+  }
+})
+```
+
+### 5.2 Bridge API 接口
+
+```typescript
+// 设备能力
+JSBridge.scan(options?: ScanOptions): Promise<ScanResult>
+JSBridge.vibrate(duration?: number): Promise<void>
+JSBridge.getDeviceInfo(): Promise<DeviceInfo>
+JSBridge.getNetworkType(): Promise<string>
+
+// 媒体能力
+JSBridge.chooseMedia(options: MediaOptions): Promise<MediaResult>
+JSBridge.uploadFile(options: UploadOptions): Promise<UploadResult>
+JSBridge.previewImage(options: PreviewOptions): Promise<void>
+JSBridge.getImageInfo(options: ImageInfoOptions): Promise<ImageInfo>
+JSBridge.bluetoothPrint(options: PrintOptions): Promise<PrintResult>
+
+// 路由能力
+JSBridge.setNavigationBar(options: NavBarOptions): Promise<void>
+JSBridge.closeWebView(): Promise<void>
+JSBridge.onRoute(handler: RouteHandler): void
+JSBridge.onGetRouteInfo(handler: RouteInfoHandler): void
+JSBridge.notifyRouteChange(data: RouteChangeData): Promise<void>
+
+// 存储能力
+JSBridge.getStorage(key?: string): Promise<any>
+JSBridge.setStorage(data: any): Promise<void>
+JSBridge.getAppInfo(): Promise<AppInfo>
+JSBridge.onRefreshStore(handler: RefreshHandler): void
+JSBridge.notifyAppOnload(data: any): Promise<void>
+
+// 系统能力
+JSBridge.makePhoneCall(options: PhoneCallOptions): Promise<void>
+JSBridge.onPdaScan(handler: PdaScanHandler): void
+```
+
+### 5.3 Log API 接口（新增）
+
+```typescript
+// Log API
+JSBridge.log.debug(message: string, tag?: string): Promise<void>
+JSBridge.log.info(message: string, tag?: string): Promise<void>
+JSBridge.log.warn(message: string, tag?: string): Promise<void>
+JSBridge.log.error(message: string, tag?: string): Promise<void>
+
+// 通用方法
+JSBridge.writeLog(request: LogRequest): Promise<void>
+```
+
+### 5.4 Monitor API 接口
+
+```typescript
+Monitor.getStats(api?: string): PerformanceStats | Map<string, PerformanceStats>
+Monitor.getRecords(limit?: number): ApiCallRecord[]
+Monitor.clear(): void
+Monitor.report(): Promise<void>                  // 手动上报（通过 log）
+Monitor.reportError(api, error, detail?): Promise<void>  // 错误上报
+```
+
+### 5.5 Debug API 接口
+
+```typescript
+Debug.trace(api: string, params?: any): void
+Debug.getLogs(level?: string, limit?: number): any[]
+Debug.clearLogs(): void
+```
+
+## 6. 原生端接口设计
+
+### 6.1 Android 端
+
+```kotlin
+// 注册 log handler
+webView.registerHandler("log") { data, callback ->
+    val request = Gson().fromJson(data, UniLog::class.java)
+    // request.tag, request.level, request.message
+    
+    LogUtil.info(request.tag, request.message)
+    callback?.invoke(null)
+}
+```
+
+### 6.2 iOS 端
+
+```swift
+// 注册 log handler
+bridge.registerHandler("log") { data, callback in
+    let tag = request["tag"] as? String ?? "JSBridge"
+    let level = request["level"] as? String
+    let message = request["message"] as? String
+    
+    os_log(.info, log: OSLog(...), "%{public}@", message)
+    callback?(nil)
+}
+```
+
+## 7. 安全性设计
+
+### 7.1 超时机制
+
+```typescript
+call<T>(method: string, data?: any): Promise<T> {
+  return Promise.race([
+    this.callBridge(method, data),
+    this.timeout(10000)  // 10 秒超时
+  ])
+}
+```
+
+### 7.2 错误处理
+
+```typescript
+try {
+  const result = await bridge.call(method, data)
+  monitor.recordEnd(record, true, result)
+  return result
+} catch (error) {
+  monitor.recordEnd(record, false, undefined, error.message)
+  monitor.reportError(method, error.message)  // 立即上报
+  throw error
+}
+```
+
+## 8. 性能优化
+
+### 8.1 代码体积
+
+- ✅ 核心代码 ~1150 行
+- ✅ 打包体积 ~20KB
+- ✅ gzip 后 ~7KB
+
+### 8.2 运行性能
+
+- ✅ 初始化 < 100ms
+- ✅ API 调用 < 50ms
+- ✅ 日志写入 < 10ms（异步）
+
+### 8.3 内存优化
+
+- ✅ 监控缓存限制（默认 100 条）
+- ✅ Debug 日志限制
+- ✅ 定时清理
+
+## 9. 扩展性设计
+
+### 9.1 新增 API
+
+```typescript
+// 1. 新建 src/api/newFeature.ts
+export async function newFeature(options): Promise<Result> {
+  return bridge.call('newFeature', options)
+}
+
+// 2. 在 index.ts 中导出
+export const JSBridge = {
+  // ... 现有 API
+  newFeature
+}
+
+// 3. 原生端实现
+webView.registerHandler("newFeature") { data, callback ->
+  // 处理逻辑
+  callback?.invoke(result)
+}
+```
+
+### 9.2 新增监控指标
+
+```typescript
+interface PerformanceStats {
+  // ... 现有指标
+  newMetric: number  // 新增指标
+}
+```
+
+## 10. 部署架构
+
+### 10.1 npm 发布
+
+```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"
+}
+```
+
+### 10.2 子应用集成
+
+```typescript
+// 1. 安装
+npm install @hd-front-end/jsbridge-sdk
+
+// 2. 初始化
+import { init } from '@hd-front-end/jsbridge-sdk'
+await init({...})
+
+// 3. 使用
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+await JSBridge.scan()
+```
+
+## 11. 设计特点总结
+
+### 11.1 v2 关键改进
+
+**监控上报机制**：
+- ❌ v1：直接发送 HTTP（错误）
+- ✅ v2：通过 log API 上报（正确）
+
+**日志能力**：
+- ❌ v1：没有 log API
+- ✅ v2：提供 log API
+
+**统一日志管理**：
+- SDK 监控 + 子应用日志
+- 都通过原生 log handler
+- 原生统一写入和上传
+
+### 11.2 设计亮点
+
+✅ **职责单一** - SDK 只做原生 API 封装  
+✅ **统一日志** - 监控和业务日志统一管理  
+✅ **双平台兼容** - 自动兼容 Android/iOS  
+✅ **自动监控** - 无感知性能监控  
+✅ **易于扩展** - 新增 API 简单  
+
+## 12. 相关文档
+
+- **[00-项目概览.md](./00-项目概览.md)** - 项目概览
+- **[02-技术实现.md](./02-技术实现.md)** - **完整代码实现**
+- **[03-API使用文档.md](./03-API使用文档.md)** - API 详细文档
+- **[06-架构图集.md](./06-架构图集.md)** - 更多架构图
+
+---
+
+**清晰的架构设计，完整代码见02** 🎯
+