@hd-front-end/jsbridge-sdk 1.0.1

package/README.md

@@ -0,0 +1,143 @@
+# JSBridge SDK
+
+> 生产级 JSBridge SDK - 通过原生 log 能力实现监控和日志上报
+
+## ✨ 核心特性
+
+- 🎯 **职责单一** - 只封装原生 API，不包含适配层
+- 📱 **双平台支持** - 兼容 Android 和 iOS
+- 📊 **统一日志管理** - 监控和业务日志都通过原生 log 上报
+- 📝 **提供 log API** - 子应用可以上传业务日志
+- 🔍 **Debug 模式** - 支持开启调试模式和调用追踪
+- 💪 **类型安全** - 完整的 TypeScript 类型定义
+- ⚡ **高性能** - 毫秒级初始化，内置竞态处理机制
+- 📦 **体积小** - 20KB（gzip: 7KB）
+
+## 🎯 两个目的
+
+1. ✅ **监控 SDK 稳定性** - SDK 自动记录性能和错误，通过原生 log 上报
+2. ✅ **提供子应用日志能力** - 子应用调用 `JSBridge.log.*` 上传业务日志
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+npm install @hd-front-end/jsbridge-sdk
+```
+
+### 基础使用
+
+```typescript
+import { init, JSBridge } from '@hd/jsbridge-sdk'
+
+// 初始化
+await init({
+  monitor: {
+    enabled: true,
+    autoReport: true,        // 通过 log 自动上报
+    logTag: 'JSBridge-Monitor'
+  }
+})
+
+// 使用 bridge API
+// SDK 会自动处理初始化等待，无需手动 check
+const result = await JSBridge.scan()
+
+// 上传业务日志
+await JSBridge.log.info('用户点击了购买按钮', 'UserBehavior')
+await JSBridge.log.error('支付失败', 'Payment')
+```
+
+### 调试模式
+
+SDK 不再内置 vConsole，以减少包体积和避免依赖冲突。如果需要 vConsole，请在业务项目中自行安装。
+
+```typescript
+// 业务代码中
+import VConsole from 'vconsole'
+
+if (process.env.NODE_ENV === 'development') {
+  new VConsole()
+  
+  // 开启 SDK 调试模式
+  init({
+    debug: {
+      enabled: true, // 开启后会在控制台输出详细的调用日志
+      logLevel: 'debug'
+    }
+  })
+}
+```
+
+## 📚 文档
+
+### 快速入口
+
+- **[docs/README.md](./docs/README.md)** - 📖 文档索引（从这里开始）
+- **[docs/05-迁移指南.md](./docs/05-迁移指南.md)** - 🔄 Vue2/Vue3 集成指南
+- **[docs/生产级-架构设计-v2.md](./docs/生产级-架构设计-v2.md)** - 🏗️ 完整架构
+- **[docs/设计理念说明.md](./docs/设计理念说明.md)** - 💡 设计理念（⭐ 必读）
+
+### 详细文档
+
+- [平台兼容性说明.md](./docs/平台兼容性说明.md) - Android/iOS 兼容
+- [监控指南.md](./docs/监控指南.md) - 监控使用指南
+- [更新日志.md](./docs/更新日志.md) - 版本演进历史
+- [关键问题解答.md](./docs/关键问题解答.md) - 核心问题解答
+
+### 工作总结
+
+- [最终工作报告-v2.md](./最终工作报告-v2.md) - 完整工作总结
+- [阶段3-总结.md](./阶段3-总结.md) - 集成测试与性能攻坚总结
+
+## 🏗️ 架构设计
+
+```
+┌─────────────────────────────────────┐
+│  子应用                              │
+│  - 调用 JSBridge.log.info(...)      │
+│  - 上传业务日志                      │
+└─────────────────────────────────────┘
+            ↓
+┌─────────────────────────────────────┐
+│  @hd/jsbridge-sdk                   │
+│  ├── 核心通信（Android/iOS）         │
+│  ├── API 层（device/media/log...）  │
+│  ├── 监控层（通过 log 上报）         │
+│  └── Debug 层（调用追踪）           │
+└─────────────────────────────────────┘
+            ↓
+┌─────────────────────────────────────┐
+│  原生 WebView                        │
+│  ├── log handler                    │
+│  ├── LogUtil 写入日志文件            │
+│  └── 统一上传到服务器                │
+└─────────────────────────────────────┘
+```
+
+## 💻 核心 API
+
+### Bridge API
+
+```typescript
+// 扫码
+const result = await JSBridge.scan()
+
+// 拨打电话
+await JSBridge.makePhoneCall({ phoneNumber: '10086' })
+
+// 震动
+await JSBridge.vibrate()
+
+// 获取设备信息
+const info = await JSBridge.getDeviceInfo()
+```
+
+### Log API
+
+```typescript
+// 记录日志
+await JSBridge.log.info('操作成功', 'Business')
+await JSBridge.log.error('接口异常', 'Network', { status: 500 })
+```