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

package/docs/04-/346/265/213/350/257/225/346/226/271/346/241/210.md

@@ -0,0 +1,360 @@
+# JSBridge SDK 测试方案（生产级 v2）
+
+> **当前版本**：生产级 v2 - 测试方案
+
+## 1. 测试目标
+
+- ✅ **功能完整性**：确保所有 API 正常工作
+- ✅ **平台兼容性**：Android 和 iOS 双平台测试
+- ✅ **监控准确性**：验证监控数据正确性
+- ✅ **日志功能**：验证 log API 正常工作
+- ✅ **稳定性**：错误处理、超时机制
+
+## 2. 测试矩阵
+
+### 2.1 平台测试矩阵
+
+| 功能 | Android | iOS | 说明 |
+|------|---------|-----|------|
+| **核心通信** | ✅ | ✅ | Bridge 初始化 |
+| **扫码** | ✅ | ✅ | scan() |
+| **选择媒体** | ✅ | ✅ | chooseMedia() |
+| **上传文件** | ✅ | ✅ | uploadFile() |
+| **设备信息** | ✅ | ✅ | getDeviceInfo() |
+| **日志上传** | ✅ | ✅ | log API |
+| **监控上报** | ✅ | ✅ | 通过 log 上报 |
+| **Debug 模式** | ✅ | ✅ | vconsole |
+
+### 2.2 设备测试矩阵
+
+| 平台 | 设备 | 系统版本 | 测试项 |
+|------|------|---------|--------|
+| Android | 小米 | Android 11+ | 全功能 |
+| Android | 华为 | Android 10+ | 全功能 |
+| Android | OPPO | Android 11+ | 全功能 |
+| iOS | iPhone 12+ | iOS 14+ | 全功能 |
+| iOS | iPad | iOS 14+ | 全功能 |
+
+## 3. 测试用例
+
+### 3.1 初始化测试
+
+```typescript
+describe('初始化测试', () => {
+  test('默认配置初始化成功', async () => {
+    const success = await init()
+    expect(success).toBe(true)
+    expect(inApp()).toBe(true)
+  })
+  
+  test('完整配置初始化成功', async () => {
+    const success = await init({
+      debug: { enabled: true, useVConsole: true },
+      monitor: { enabled: true, autoReport: true }
+    })
+    expect(success).toBe(true)
+  })
+  
+  test('平台检测正确', () => {
+    const platform = getPlatform()
+    expect(['android', 'ios']).toContain(platform)
+  })
+})
+```
+
+### 3.2 API 功能测试
+
+```typescript
+describe('API 功能测试', () => {
+  test('扫码功能', async () => {
+    const result = await JSBridge.scan()
+    expect(result.resp_code).toBe(1000)
+    expect(result.resp_result).toBeDefined()
+  })
+  
+  test('选择媒体', async () => {
+    const result = await JSBridge.chooseMedia({ count: 1 })
+    expect(result.tempFilePaths).toBeDefined()
+    expect(result.tempFilePaths.length).toBeGreaterThan(0)
+  })
+  
+  test('获取设备信息', async () => {
+    const info = await JSBridge.getDeviceInfo()
+    expect(info.brand).toBeDefined()
+    expect(info.model).toBeDefined()
+  })
+})
+```
+
+### 3.3 日志功能测试
+
+```typescript
+describe('日志功能测试', () => {
+  test('info 日志', async () => {
+    await expect(
+      JSBridge.log.info('测试日志', 'Test')
+    ).resolves.toBeUndefined()
+  })
+  
+  test('error 日志', async () => {
+    await expect(
+      JSBridge.log.error('错误日志', 'Test')
+    ).resolves.toBeUndefined()
+  })
+  
+  test('通用 writeLog', async () => {
+    await expect(
+      JSBridge.writeLog({
+        level: LogLevel.INFO,
+        message: '测试',
+        tag: 'Test'
+      })
+    ).resolves.toBeUndefined()
+  })
+})
+```
+
+### 3.4 监控功能测试
+
+```typescript
+describe('监控功能测试', () => {
+  test('记录 API 调用', async () => {
+    await JSBridge.scan()
+    
+    const stats = Monitor.getStats('scan')
+    expect(stats.totalCalls).toBeGreaterThan(0)
+  })
+  
+  test('获取调用记录', async () => {
+    const records = Monitor.getRecords(10)
+    expect(records.length).toBeGreaterThan(0)
+    expect(records[0].api).toBeDefined()
+  })
+  
+  test('手动上报', async () => {
+    await expect(Monitor.report()).resolves.toBeUndefined()
+  })
+})
+```
+
+### 3.5 错误处理测试
+
+```typescript
+describe('错误处理测试', () => {
+  test('API 调用失败', async () => {
+    // 模拟失败场景
+    await expect(
+      JSBridge.call('invalidMethod')
+    ).rejects.toThrow()
+  })
+  
+  test('未初始化调用', async () => {
+    // 重置初始化状态
+    await expect(
+      JSBridge.scan()
+    ).rejects.toThrow('JSBridge 未初始化')
+  })
+})
+```
+
+## 4. 测试执行
+
+### 4.1 单元测试
+
+```bash
+# 运行所有测试
+npm test
+
+# 运行特定测试
+npm test -- --grep "初始化测试"
+
+# 生成覆盖率报告
+npm test -- --coverage
+```
+
+### 4.2 集成测试
+
+```bash
+# Android 真机测试
+npm run test:android
+
+# iOS 真机测试
+npm run test:ios
+```
+
+### 4.3 手动测试清单
+
+**扫码测试**：
+- [ ] 扫码成功
+- [ ] 用户取消
+- [ ] 相机权限拒绝
+- [ ] 超时处理
+
+**媒体测试**：
+- [ ] 选择图片成功
+- [ ] 选择多张图片
+- [ ] 选择视频
+- [ ] 上传文件成功
+
+**日志测试**：
+- [ ] info 日志写入
+- [ ] error 日志写入
+- [ ] 监控数据上报
+- [ ] 原生日志文件存在
+
+**平台测试**：
+- [ ] Android 平台正常
+- [ ] iOS 平台正常
+- [ ] 平台检测正确
+
+## 5. 性能测试
+
+### 5.1 性能指标
+
+| 指标 | 目标 | 实际 | 说明 |
+|------|------|------|------|
+| 初始化时间 | < 100ms | | 首次初始化 |
+| API 调用延迟 | < 50ms | | 不含原生处理 |
+| 日志写入延迟 | < 10ms | | 异步写入 |
+| 包体积 | < 10KB | | gzip 后 |
+
+### 5.2 性能测试用例
+
+```typescript
+describe('性能测试', () => {
+  test('初始化性能', async () => {
+    const start = Date.now()
+    await init()
+    const duration = Date.now() - start
+    
+    expect(duration).toBeLessThan(100)
+  })
+  
+  test('API 调用性能', async () => {
+    const start = Date.now()
+    await JSBridge.getDeviceInfo()
+    const duration = Date.now() - start
+    
+    expect(duration).toBeLessThan(50)
+  })
+})
+```
+
+## 6. 兼容性测试
+
+### 6.1 Android 兼容性
+
+- [ ] Android 9.0
+- [ ] Android 10
+- [ ] Android 11
+- [ ] Android 12+
+
+### 6.2 iOS 兼容性
+
+- [ ] iOS 13
+- [ ] iOS 14
+- [ ] iOS 15
+- [ ] iOS 16+
+
+## 7. 监控数据验证
+
+### 7.1 验证监控数据格式
+
+```typescript
+test('监控数据格式正确', async () => {
+  await JSBridge.scan()
+  
+  const stats = Monitor.getStats('scan')
+  
+  expect(stats).toMatchObject({
+    totalCalls: expect.any(Number),
+    successCalls: expect.any(Number),
+    failedCalls: expect.any(Number),
+    avgDuration: expect.any(Number),
+    maxDuration: expect.any(Number),
+    minDuration: expect.any(Number)
+  })
+})
+```
+
+### 7.2 验证日志上报
+
+```typescript
+test('监控数据通过 log 上报', async () => {
+  const spy = jest.spyOn(bridge, 'call')
+  
+  await Monitor.report()
+  
+  expect(spy).toHaveBeenCalledWith('log', {
+    tag: 'JSBridge-Monitor',
+    level: 'INFO',
+    message: expect.stringContaining('[MONITOR]')
+  })
+})
+```
+
+## 8. 测试报告模板
+
+```markdown
+# JSBridge SDK 测试报告
+
+## 测试信息
+- 测试日期：2026-02-02
+- 测试版本：v2.0.0
+- 测试人员：XXX
+
+## 测试结果
+
+### 功能测试
+- 通过：50 / 50
+- 失败：0 / 50
+
+### 性能测试
+- 初始化时间：85ms ✅
+- API 调用延迟：35ms ✅
+- 包体积：6.5KB (gzip) ✅
+
+### 兼容性测试
+- Android：✅ (测试 4 个版本)
+- iOS：✅ (测试 4 个版本)
+
+### 问题列表
+无
+
+## 结论
+所有测试通过，可以发布。
+```
+
+## 9. 持续集成
+
+### 9.1 CI 配置
+
+```yaml
+# .github/workflows/test.yml
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm install
+      - run: npm test
+      - run: npm run build
+```
+
+## 10. 文档导航
+
+- **[00-项目概览.md](./00-项目概览.md)** - 项目概述
+- **[01-架构设计.md](./01-架构设计.md)** - 架构设计
+- **[02-技术实现.md](./02-技术实现.md)** - 技术实现
+- **[03-API使用文档.md](./03-API使用文档.md)** - API 文档
+- **[05-迁移指南.md](./05-迁移指南.md)** - 迁移指南
+
+---
+
+**完善的测试方案，保证质量** 🎯
+

package/docs/05-/350/277/201/347/247/273/346/214/207/345/215/227.md

@@ -0,0 +1,181 @@
+# JSBridge SDK 迁移指南（生产级 v2）
+
+> **当前版本**：生产级 v2 - 如何从现有项目迁移到 SDK
+
+## 1. 迁移概述
+
+### 1.1 迁移目标
+
+将现有项目（SOA、MPA-Mini-V3）中的 JSBridge 代码迁移到使用 `@hd-front-end/jsbridge-sdk`。
+
+### 1.2 迁移收益
+
+✅ **代码更简洁** - 移除项目中的 JSBridge 实现  
+✅ **统一维护** - SDK 统一维护和升级  
+✅ **新增能力** - 监控、debug、log API  
+✅ **类型安全** - TypeScript 完整支持  
+✅ **高性能** - 内置初始化竞态处理，消除 10s 延迟
+
+## 2. 集成指南
+
+### 2.1 Vue 2 + UniApp (如 SOA)
+
+**步骤 1：安装 SDK**
+
+```bash
+npm install @hd-front-end/jsbridge-sdk
+```
+
+**步骤 2：全局挂载 (main.js)**
+
+```javascript
+import Vue from 'vue'
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+// 挂载到 Vue 原型，方便页面通过 this.$bridge 调用
+Vue.prototype.$bridge = JSBridge
+```
+
+**步骤 3：初始化 (App.vue)**
+
+```javascript
+import { init } from '@hd-front-end/jsbridge-sdk'
+
+export default {
+  onLaunch() {
+    // 建议尽早初始化
+    init({
+      debug: { enabled: process.env.NODE_ENV === 'development' },
+      monitor: { enabled: true, autoReport: true }
+    })
+  }
+}
+```
+
+**步骤 4：页面调用**
+
+```javascript
+methods: {
+  async handleScan() {
+    try {
+      // 直接调用，无需手动检查初始化状态
+      const res = await this.$bridge.scan()
+      console.log('扫码结果', res)
+    } catch (e) {
+      console.error('扫码失败', e)
+    }
+  }
+}
+```
+
+---
+
+### 2.2 Vue 3 + UniApp (如 MPA-Mini-V3)
+
+**步骤 1：创建插件 (src/plugins/jsbridge.ts)**
+
+```typescript
+import { init, JSBridge } from '@hd-front-end/jsbridge-sdk'
+import type { App } from 'vue'
+
+export default {
+  install: async (app: App) => {
+    // 1. Provide (推荐，配合 Composition API)
+    app.provide('jsbridge', JSBridge)
+    
+    // 2. 全局挂载 (可选，兼容 Options API)
+    app.config.globalProperties.$bridge = JSBridge
+
+    // 3. 初始化 SDK
+    const isDev = process.env.NODE_ENV === 'development'
+    
+    // 异步初始化，不阻塞应用启动
+    init({
+      debug: { enabled: isDev },
+      monitor: { enabled: !isDev, autoReport: true }
+    }).then(() => {
+      console.log('✅ JSBridge Ready')
+    })
+  }
+}
+```
+
+**步骤 2：注册插件 (main.ts)**
+
+```typescript
+import { createSSRApp } from 'vue'
+import App from './App.vue'
+import JsBridgePlugin from './plugins/jsbridge'
+
+export function createApp() {
+  const app = createSSRApp(App)
+  app.use(JsBridgePlugin)
+  return { app }
+}
+```
+
+**步骤 3：页面调用 (Composition API)**
+
+```vue
+<script setup lang="ts">
+import { JSBridge } from '@hd-front-end/jsbridge-sdk' // 推荐：直接引入，Tree-shaking 友好
+
+const handleScan = async () => {
+  const res = await JSBridge.scan()
+  console.log(res)
+}
+</script>
+```
+
+---
+
+### 2.3 纯 Vue 3 项目 (如 Report-Mobile)
+
+**步骤 1：直接引入使用**
+
+无需复杂的插件封装，直接在需要的地方引入即可。
+
+```typescript
+// main.ts
+import { init } from '@hd-front-end/jsbridge-sdk'
+
+init({ monitor: { enabled: true } })
+```
+
+```vue
+<!-- Component.vue -->
+<script setup>
+import { JSBridge } from '@hd-front-end/jsbridge-sdk'
+
+const call = () => {
+  JSBridge.makePhoneCall({ phoneNumber: '10086' })
+}
+</script>
+```
+
+## 3. 常见问题 (FAQ)
+
+### Q1: 需要手动安装 vConsole 吗？
+**需要**。SDK 为了保持轻量和纯净，不再内置 vConsole。如果你需要在开发环境调试，请在你的项目中自行安装 `vconsole` npm 包。
+
+### Q2: 初始化需要 await 吗？
+**不需要**。SDK 内部实现了 `waitForReady` 机制。你可以调用 `init()` 而不等待它完成，立即调用 `JSBridge.scan()` 等 API，SDK 会自动挂起请求直到 Bridge 就绪。
+
+### Q3: 为什么扫码等接口不需要传 callback 了？
+SDK 将所有异步 API 封装成了 **Promise**。你可以使用 `await` 语法，避免回调地狱。
+
+```typescript
+// ✅ 推荐
+try {
+  const res = await JSBridge.scan()
+} catch (e) {
+  // 处理错误
+}
+
+// ❌ 旧方式
+JsBridge.scan({
+  success: (res) => {},
+  fail: (err) => {}
+})
+```
+