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

package/docs//347/224/237/344/272/247/347/272/247-/345/277/253/351/200/237/345/274/200/345/247/213-v2.md

@@ -0,0 +1,673 @@
+# JSBridge SDK 生产级 - 快速开始 v2
+
+> **兼容 Android/iOS，内置监控和 debug 模式，通过原生 log 能力上报数据**
+
+## 📦 安装
+
+```bash
+npm install @hd-front-end/jsbridge-sdk
+
+# 开发环境需要 vconsole
+npm install --save-dev vconsole
+```
+
+## 🚀 快速开始
+
+### 1. 基础使用
+
+```typescript
+import { init, JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+// 初始化
+await init()
+
+// 使用 API
+const result = await JSBridge.scan()
+console.log(result.resp_result)
+```
+
+### 2. 开发环境配置（推荐）
+
+```typescript
+import { init, JSBridge, Debug } from '@hd-front-end/jsbridge-sdk'
+
+// 开发环境：启用 debug 和 vconsole
+await init({
+  debug: {
+    enabled: true,
+    useVConsole: true,
+    logLevel: 'debug'
+  },
+  monitor: {
+    enabled: false  // 开发环境不需要监控
+  }
+})
+```
+
+### 3. 生产环境配置（推荐）
+
+```typescript
+import { init, JSBridge, Monitor } from '@hd-front-end/jsbridge-sdk'
+
+// 生产环境：启用监控（通过原生 log 上报）
+await init({
+  debug: {
+    enabled: false
+  },
+  monitor: {
+    enabled: true,
+    autoReport: true,          // 自动上报到原生 log
+    reportInterval: 60000,     // 1 分钟上报一次
+    logTag: 'JSBridge-Monitor' // 日志 TAG
+  }
+})
+
+// 监控数据会自动通过原生 log 能力写入日志文件
+// 原生端统一收集并上传到服务器
+```
+
+### 4. 根据环境自动配置（最佳实践）
+
+```typescript
+import { init } from '@hd-front-end/jsbridge-sdk'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+await init({
+  debug: {
+    enabled: isDev,
+    useVConsole: isDev,
+    logLevel: isDev ? 'debug' : 'error'
+  },
+  monitor: {
+    enabled: !isDev,           // 生产环境启用
+    autoReport: !isDev,        // 生产环境自动上报
+    reportInterval: 60000,
+    logTag: 'JSBridge-Monitor'
+  }
+})
+```
+
+## 📝 Log API 使用（新增）
+
+### 1. 基础使用
+
+```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. 记录用户行为
+
+```typescript
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+// 进入页面
+await JSBridge.log.info('用户进入商品详情页', 'UserBehavior')
+
+// 点击按钮
+await JSBridge.log.info('用户点击了加入购物车', 'UserBehavior')
+
+// 完成操作
+await JSBridge.log.info('用户完成了支付', 'UserBehavior')
+```
+
+### 3. 记录业务错误
+
+```typescript
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+try {
+  // 业务逻辑
+  await createOrder()
+} catch (error) {
+  // 记录业务错误
+  await JSBridge.log.error(
+    `订单创建失败: ${error.message}`,
+    'OrderService'
+  )
+}
+```
+
+### 4. 记录性能数据
+
+```typescript
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+const startTime = Date.now()
+
+// 执行操作
+await loadData()
+
+const duration = Date.now() - startTime
+
+// 记录性能数据
+await JSBridge.log.info(
+  `页面加载耗时: ${duration}ms`,
+  'Performance'
+)
+```
+
+### 5. 记录 API 调用
+
+```typescript
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+// 请求前
+await JSBridge.log.debug('开始请求商品列表', 'API')
+
+try {
+  const response = await fetch('/api/products')
+  
+  // 请求成功
+  await JSBridge.log.debug(
+    `请求成功: ${response.data.length} 条数据`,
+    'API'
+  )
+} catch (error) {
+  // 请求失败
+  await JSBridge.log.error(
+    `请求失败: ${error.message}`,
+    'API'
+  )
+}
+```
+
+## 📚 核心 API
+
+### 设备能力
+
+```typescript
+// 扫码
+const result = await JSBridge.scan()
+
+// 选择媒体
+const media = await JSBridge.chooseMedia({ count: 1 })
+
+// 上传文件
+const uploadResult = await JSBridge.uploadFile({
+  url: 'https://api.example.com/upload',
+  filePath: media.tempFilePaths[0],
+  name: 'file'
+})
+
+// 获取设备信息
+const deviceInfo = await JSBridge.getDeviceInfo()
+```
+
+### 日志能力（新增）
+
+```typescript
+// 写日志
+await JSBridge.log.info('日志内容', 'TAG')
+await JSBridge.log.error('错误信息', 'TAG')
+await JSBridge.log.warn('警告信息', 'TAG')
+await JSBridge.log.debug('调试信息', 'TAG')
+
+// 通用方法
+await JSBridge.writeLog({
+  level: LogLevel.INFO,
+  message: '日志内容',
+  tag: 'TAG'
+})
+```
+
+### 监控 API
+
+```typescript
+import { Monitor } from '@hd-front-end/jsbridge-sdk'
+
+// 获取统计
+const stats = Monitor.getStats('scan')
+
+// 获取记录
+const records = Monitor.getRecords(10)
+
+// 手动上报（通过 log）
+await Monitor.report()
+
+// 上报错误（立即通过 log）
+await Monitor.reportError('scan', '扫码失败', { detail: '...' })
+```
+
+### Debug API
+
+```typescript
+import { Debug } from '@hd-front-end/jsbridge-sdk'
+
+// 追踪调用
+Debug.trace('scan', { scanType: ['qrCode'] })
+
+// 获取日志
+const logs = Debug.getLogs('error', 10)
+
+// 清空日志
+Debug.clearLogs()
+```
+
+## 📊 监控和日志流程
+
+### 1. SDK 自动监控
+
+```
+SDK API 调用（如 scan）
+    ↓
+自动记录性能数据
+    ↓
+定时任务（1 分钟）
+    ↓
+通过 log API 上报到原生
+    ↓
+原生 LogUtil 写入日志文件
+    ↓
+原生统一收集上传到服务器
+```
+
+### 2. 子应用主动上传日志
+
+```
+子应用调用 JSBridge.log.info(...)
+    ↓
+SDK log API
+    ↓
+通过 bridge 调用原生 log handler
+    ↓
+原生 LogUtil 写入日志文件
+    ↓
+原生统一收集上传到服务器
+```
+
+### 3. 错误立即上报
+
+```
+API 调用失败
+    ↓
+SDK 捕获错误
+    ↓
+立即通过 log API 上报（ERROR 级别）
+    ↓
+原生可以立即上传 ERROR 日志
+```
+
+## 🎯 完整示例
+
+### App.vue
+
+```typescript
+import { init, JSBridge, getPlatform } from '@hd-front-end/jsbridge-sdk'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+export default {
+  async onLaunch() {
+    // #ifdef H5-HD
+    await this.initJSBridge()
+    // #endif
+  },
+  
+  methods: {
+    async initJSBridge() {
+      try {
+        // 初始化配置
+        const success = 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'
+          }
+        })
+        
+        if (!success) {
+          console.warn('JSBridge 初始化失败')
+          return
+        }
+        
+        const platform = getPlatform()
+        console.log(`JSBridge 初始化成功 [${platform}]`)
+        
+        // 记录日志
+        await JSBridge.log.info(
+          `App 启动成功 [${platform}]`,
+          'AppLifeCycle'
+        )
+        
+        // 注册原生回调
+        this.setupBridgeHandlers()
+        
+      } catch (error) {
+        console.error('JSBridge 初始化异常:', error)
+        
+        // 上报错误
+        try {
+          await JSBridge.log.error(
+            `初始化失败: ${error.message}`,
+            'AppLifeCycle'
+          )
+        } catch (e) {
+          // 忽略
+        }
+      }
+    }
+  }
+}
+```
+
+### 业务组件
+
+```vue
+<template>
+  <view class="page">
+    <button @click="handleScan">扫码</button>
+    <button @click="handleUploadLog">上传日志</button>
+  </view>
+</template>
+
+<script>
+import { JSBridge, inApp, Monitor } from '@hd-front-end/jsbridge-sdk'
+
+export default {
+  methods: {
+    async handleScan() {
+      if (!inApp()) {
+        uni.showToast({ title: '请在 App 中使用', icon: 'none' })
+        return
+      }
+      
+      // 记录用户行为
+      await JSBridge.log.info('用户点击扫码按钮', 'UserBehavior')
+      
+      try {
+        const result = await JSBridge.scan({
+          scanType: ['qrCode']
+        })
+        
+        if (result.resp_code === 1000) {
+          // 记录成功
+          await JSBridge.log.info(
+            `扫码成功: ${result.resp_result}`,
+            'ScanResult'
+          )
+          
+          uni.showToast({ title: '扫码成功', icon: 'success' })
+        }
+      } catch (error) {
+        // 记录错误（SDK 会自动上报，这里是业务日志）
+        await JSBridge.log.error(
+          `扫码失败: ${error.message}`,
+          'ScanError'
+        )
+        
+        uni.showToast({ title: '扫码失败', icon: 'error' })
+      }
+    },
+    
+    async handleUploadLog() {
+      try {
+        // 手动触发监控数据上报
+        await Monitor.report()
+        
+        // 也可以上传自定义日志
+        await JSBridge.log.info(
+          '用户手动触发日志上传',
+          'UserAction'
+        )
+        
+        uni.showToast({ title: '日志已上传', icon: 'success' })
+      } catch (error) {
+        uni.showToast({ title: '上传失败', icon: 'error' })
+      }
+    }
+  }
+}
+</script>
+```
+
+### 页面生命周期日志
+
+```typescript
+export default {
+  async onLoad() {
+    // 记录页面加载
+    await JSBridge.log.info('进入商品详情页', 'PageLifeCycle')
+  },
+  
+  async onShow() {
+    const startTime = Date.now()
+    
+    // 加载数据
+    await this.loadData()
+    
+    const duration = Date.now() - startTime
+    
+    // 记录性能
+    await JSBridge.log.info(
+      `页面数据加载耗时: ${duration}ms`,
+      'Performance'
+    )
+  },
+  
+  async onUnload() {
+    // 记录页面卸载
+    await JSBridge.log.info('离开商品详情页', 'PageLifeCycle')
+  }
+}
+```
+
+## 🔧 高级用法
+
+### 1. 封装统一的日志工具
+
+```typescript
+// utils/logger.ts
+import { JSBridge, LogLevel } from '@hd-front-end/jsbridge-sdk'
+
+export const Logger = {
+  // 用户行为
+  behavior(action: string, detail?: any) {
+    return JSBridge.log.info(
+      `[行为] ${action}${detail ? ': ' + JSON.stringify(detail) : ''}`,
+      'UserBehavior'
+    )
+  },
+  
+  // 业务错误
+  businessError(module: string, error: string, detail?: any) {
+    return JSBridge.log.error(
+      `[${module}] ${error}${detail ? ': ' + JSON.stringify(detail) : ''}`,
+      'BusinessError'
+    )
+  },
+  
+  // 性能数据
+  performance(metric: string, duration: number) {
+    return JSBridge.log.info(
+      `[性能] ${metric}: ${duration}ms`,
+      'Performance'
+    )
+  },
+  
+  // API 调用
+  api(method: string, url: string, duration: number, success: boolean) {
+    return JSBridge.log.info(
+      `[API] ${method} ${url} ${duration}ms ${success ? '成功' : '失败'}`,
+      'API'
+    )
+  }
+}
+
+// 使用
+await Logger.behavior('点击购买按钮', { productId: '123' })
+await Logger.businessError('订单', '创建失败', { reason: '库存不足' })
+await Logger.performance('页面加载', 1234)
+await Logger.api('GET', '/api/products', 567, true)
+```
+
+### 2. 监控拦截器
+
+```typescript
+// utils/request.ts
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+// 请求拦截器
+axios.interceptors.request.use(async (config) => {
+  // 记录请求开始
+  config.metadata = { startTime: Date.now() }
+  
+  await JSBridge.log.debug(
+    `请求开始: ${config.method} ${config.url}`,
+    'API'
+  )
+  
+  return config
+})
+
+// 响应拦截器
+axios.interceptors.response.use(
+  async (response) => {
+    const duration = Date.now() - response.config.metadata.startTime
+    
+    // 记录成功
+    await JSBridge.log.info(
+      `请求成功: ${response.config.method} ${response.config.url} ${duration}ms`,
+      'API'
+    )
+    
+    return response
+  },
+  async (error) => {
+    const duration = Date.now() - error.config.metadata.startTime
+    
+    // 记录失败
+    await JSBridge.log.error(
+      `请求失败: ${error.config.method} ${error.config.url} ${duration}ms - ${error.message}`,
+      'API'
+    )
+    
+    return Promise.reject(error)
+  }
+)
+```
+
+### 3. 错误边界
+
+```typescript
+// App.vue
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+export default {
+  onError(err) {
+    // 全局错误捕获
+    console.error('全局错误:', err)
+    
+    // 上报错误
+    JSBridge.log.error(
+      `未捕获的错误: ${err.message}\n${err.stack}`,
+      'GlobalError'
+    )
+  },
+  
+  onUnhandledRejection(reason) {
+    // Promise 未处理的 rejection
+    console.error('Promise rejection:', reason)
+    
+    // 上报错误
+    JSBridge.log.error(
+      `未处理的 Promise rejection: ${reason}`,
+      'GlobalError'
+    )
+  }
+}
+```
+
+## ❓ 常见问题
+
+### Q1: 日志会影响性能吗？
+
+**A:** 不会。日志调用是异步的，不会阻塞主线程。原生端负责日志的写入和上传。
+
+### Q2: 日志什么时候上传？
+
+**A:** 
+- SDK 监控日志：定时上报（默认 1 分钟）
+- 错误日志：立即上报
+- 业务日志：写入后由原生统一管理和上传
+
+### Q3: 如何控制日志量？
+
+**A:** 
+- 生产环境只记录 INFO 及以上级别
+- 使用合适的 TAG 分类
+- 原生端可以配置日志上传策略
+
+### Q4: 如何查看日志？
+
+**A:** 
+- 开发环境：通过 vconsole 查看
+- 原生端：日志文件在 `logDir` 目录
+- 服务器：原生上传后可在服务器查看
+
+### Q5: TAG 怎么命名？
+
+**A:** 建议规范：
+- `UserBehavior` - 用户行为
+- `Performance` - 性能数据
+- `API` - API 调用
+- `BusinessError` - 业务错误
+- `PageLifeCycle` - 页面生命周期
+- 或使用模块名：`ShoppingCart`, `Payment`, `OrderService` 等
+
+## 📚 更多文档
+
+- [架构设计 v2](./生产级-架构设计-v2.md) - 完整架构说明
+- [监控指南](./监控指南.md) - 监控最佳实践
+- [设计理念](./设计理念说明.md) - 为什么这样设计
+
+## 🎯 核心优势
+
+### 1. 统一日志管理
+
+✅ SDK 监控日志自动上报  
+✅ 子应用可以主动上传日志  
+✅ 原生统一管理和上传  
+✅ 服务器统一收集分析  
+
+### 2. 两个目的都实现
+
+✅ **监控 SDK 稳定性**
+- SDK 自动记录性能和错误
+- 定时/立即上报到原生
+- 服务器可分析 SDK 运行状况
+
+✅ **提供子应用日志能力**
+- 子应用调用简单的 log API
+- 日志自动写入原生
+- 无需关心上传细节
+
+### 3. 简单易用
+
+✅ **初始化简单** - 一次配置，自动运行  
+✅ **API 简单** - `JSBridge.log.info(...)` 即可  
+✅ **无需关心细节** - 原生负责日志管理和上传  
+
+---
+
+**统一日志，简单易用** 🎯
+