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

package/docs/00-/351/241/271/347/233/256/346/246/202/350/247/210.md

@@ -0,0 +1,282 @@
+# JSBridge SDK 项目概览（生产级 v2）
+
+> **10 分钟快速了解项目**
+
+## 1. 项目简介
+
+### 1.1 项目背景
+
+基于 `soa`、`mpa-mini-v3` 和 `soa-android-demo` 项目的 JSBridge 实现经验，我们开发了生产可用的 JSBridge SDK，解决：
+
+- ❌ 代码重复：多项目相同实现
+- ❌ 维护困难：同步修改多个项目
+- ❌ 功能不统一：实现细节差异
+- ❌ 监控缺失：无法了解运行状况
+- ❌ 日志困难：缺少统一日志能力
+
+### 1.2 项目目标
+
+✅ **职责单一** - 只封装原生 API  
+✅ **双平台** - 兼容 Android/iOS  
+✅ **统一日志** - 监控和业务日志通过原生 log  
+✅ **稳定可观测** - 完善的错误处理和监控  
+
+### 1.3 两个目的
+
+1. **监控 SDK 稳定性** - 自动记录性能和错误
+2. **提供日志能力** - 子应用可上传业务日志
+
+## 2. 核心特性
+
+### 2.1 纯粹的 API 封装
+
+```typescript
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+// 简单直接
+const result = await JSBridge.scan()
+const media = await JSBridge.chooseMedia({ count: 1 })
+```
+
+**不包含**：适配层、框架封装、业务逻辑
+
+### 2.2 统一日志管理
+
+```typescript
+// SDK 自动监控
+await init({
+  monitor: { enabled: true, autoReport: true }
+})
+
+// 子应用上传日志
+await JSBridge.log.info('用户点击购买', 'UserBehavior')
+await JSBridge.log.error('支付失败', 'Payment')
+```
+
+**日志流程**：
+```
+SDK监控/子应用 → log API → 原生LogUtil → 日志文件 → 服务器
+```
+
+### 2.3 双平台兼容
+
+```typescript
+import { getPlatform, Platform } from '@hd-front-end/jsbridge-sdk'
+
+const platform = getPlatform()  // 'android' | 'ios'
+```
+
+- ✅ Android：`InjectJavascript.init()`
+- ✅ iOS：iframe 触发
+- ✅ 统一API接口
+
+### 2.4 TypeScript 支持
+
+```typescript
+interface ScanResult {
+  resp_code: number
+  resp_result: string
+  resp_message: string
+}
+
+const result: ScanResult = await JSBridge.scan()
+```
+
+## 3. 快速开始
+
+### 3.1 安装
+
+```bash
+npm install @hd-front-end/jsbridge-sdk
+```
+
+### 3.2 初始化
+
+```typescript
+import { init, JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+await init({
+  debug: { enabled: isDev, useVConsole: isDev },
+  monitor: { enabled: !isDev, autoReport: !isDev }
+})
+```
+
+### 3.3 使用 API
+
+```typescript
+// 设备能力
+await JSBridge.scan()
+await JSBridge.chooseMedia({ count: 1 })
+await JSBridge.getDeviceInfo()
+
+// 日志能力（新增）
+await JSBridge.log.info('用户行为', 'UserBehavior')
+await JSBridge.log.error('业务错误', 'Error')
+
+// 监控能力
+import { Monitor } from '@hd-front-end/jsbridge-sdk'
+const stats = Monitor.getStats('scan')
+await Monitor.report()
+```
+
+## 4. 核心能力概览
+
+| 分类 | 能力 |
+|------|------|
+| **设备** | 扫码、振动、设备信息、网络类型 |
+| **媒体** | 选择媒体、上传文件、预览图片、蓝牙打印 |
+| **路由** | 设置标题、关闭WebView、路由回调 |
+| **存储** | 获取/设置存储、App信息、刷新Store |
+| **系统** | 打电话、PDA扫码 |
+| **日志** | debug/info/warn/error ← 新增 |
+| **监控** | 性能统计、调用记录、错误上报 |
+
+## 5. 技术指标
+
+| 指标 | 数值 |
+|------|------|
+| **代码行数** | ~1150 行 |
+| **文件数量** | 11 个 |
+| **打包体积** | ~7KB (gzip) |
+| **初始化时间** | < 100ms |
+| **平台支持** | Android/iOS |
+
+## 6. 对比优势
+
+### vs 直接使用原生 Bridge
+
+| 维度 | 原生 | SDK |
+|------|------|-----|
+| **易用性** | ⚠️ 复杂 | ✅ 简单 |
+| **类型支持** | ❌ 无 | ✅ 完整 |
+| **监控** | ❌ 无 | ✅ 自动 |
+| **日志** | ❌ 无 | ✅ 有 |
+
+### vs uni-app 内置
+
+| 维度 | uni-app | SDK |
+|------|---------|-----|
+| **职责** | ⚠️ 框架绑定 | ✅ 纯API |
+| **灵活性** | ⚠️ 受限 | ✅ 灵活 |
+| **监控** | ❌ 无 | ✅ 有 |
+| **日志** | ❌ 无 | ✅ 有 |
+
+## 7. 项目价值
+
+### 7.1 统一日志管理
+
+✅ SDK监控日志自动上报  
+✅ 子应用可主动上传日志  
+✅ 原生统一管理和上传  
+
+### 7.2 两个目的实现
+
+**监控 SDK 稳定性**：
+- 自动记录性能数据
+- 自动记录错误信息
+- 定时/立即通过log上报
+
+**提供日志能力**：
+- 简单API：`JSBridge.log.info(...)`
+- 自动写入原生日志
+- 原生统一管理
+
+### 7.3 开发效率提升
+
+✅ 减少重复代码  
+✅ 降低维护成本  
+✅ 提升开发体验  
+✅ npm安装即用  
+
+## 8. 使用场景
+
+### 直接使用（推荐）
+
+```typescript
+// 简单直接
+const result = await JSBridge.scan()
+```
+
+**适合**：新项目、不需要uni API兼容
+
+### 封装适配层（可选）
+
+```typescript
+// 子应用自己封装
+export function setupUniAdapter() {
+  uni.scanCode = (options) => JSBridge.scan({...})
+}
+```
+
+**适合**：已有uni API代码、需要兼容
+
+## 9. 完整示例
+
+```typescript
+// App.vue
+import { init, JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+export default {
+  async onLaunch() {
+    // 初始化
+    await init({
+      debug: { enabled: isDev, useVConsole: isDev },
+      monitor: { enabled: !isDev, autoReport: !isDev }
+    })
+    
+    // 记录启动
+    await JSBridge.log.info('App启动', 'AppLifeCycle')
+    
+    // 注册回调
+    JSBridge.onRoute((data) => this.$Router.replaceAll(data))
+    
+    // 获取初始数据
+    const appInfo = await JSBridge.getAppInfo()
+    this.refreshStore(JSON.parse(appInfo))
+  }
+}
+
+// 业务组件
+export default {
+  methods: {
+    async handleScan() {
+      // 记录用户行为
+      await JSBridge.log.info('点击扫码', 'UserBehavior')
+      
+      try {
+        const result = await JSBridge.scan()
+        await JSBridge.log.info('扫码成功', 'ScanResult')
+      } catch (error) {
+        await JSBridge.log.error('扫码失败', 'ScanError')
+      }
+    }
+  }
+}
+```
+
+## 10. 版本说明
+
+### 当前：生产级 v2
+
+**核心特性**：
+- ✅ 监控通过原生log上报
+- ✅ 提供log API给子应用
+- ✅ 统一日志管理
+
+**vs v1**：
+- ❌ v1：HTTP上报（错误）
+- ✅ v2：log上报（正确）
+- ✅ v2：新增log API
+
+## 11. 深入学习
+
+- **[01-架构设计.md](./01-架构设计.md)** - 详细架构设计
+- **[02-技术实现.md](./02-技术实现.md)** - 完整代码实现
+- **[03-API使用文档.md](./03-API使用文档.md)** - API详细文档
+- **[生产级-架构设计-v2.md](./生产级-架构设计-v2.md)** - 完整架构
+- **[生产级-快速开始-v2.md](./生产级-快速开始-v2.md)** - 快速上手
+
+---
+
+**简洁高效，统一管理** 🎯
+