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

package/docs/06-/346/236/266/346/236/204/345/233/276/351/233/206.md

@@ -0,0 +1,738 @@
+# JSBridge SDK 架构图集（生产级 v2）
+
+> **当前版本**：生产级 v2 - 完整架构图集
+
+## 1. 整体架构图
+
+### 1.1 三层架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   子应用层                           │
+│                                                     │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐│
+│  │   SOA 项目   │  │ MPA-Mini-V3 │  │  其他项目    ││
+│  └─────────────┘  └─────────────┘  └─────────────┘│
+│                                                     │
+│  使用方式（由子应用决定）：                          │
+│  1. 直接使用 SDK API                                │
+│  2. 调用 JSBridge.log.info(...)                    │
+│  3. 可选封装适配层                                  │
+└─────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│                   SDK 层                            │
+│                                                     │
+│  ┌───────────────────────────────────────────────┐ │
+│  │          核心通信（Bridge）                     │ │
+│  │  - 平台检测（Android/iOS/Unknown）            │ │
+│  │  - 平台特定初始化                             │ │
+│  │  - 统一的 call/register 接口                  │ │
+│  │  - 超时处理                                   │ │
+│  └───────────────────────────────────────────────┘ │
+│                          ↓                          │
+│  ┌───────────────────────────────────────────────┐ │
+│  │          API 层                                │ │
+│  │  ├── device   - 扫码、振动、设备信息           │ │
+│  │  ├── media    - 选择媒体、上传、预览           │ │
+│  │  ├── router   - 标题、关闭、路由回调           │ │
+│  │  ├── storage  - 获取/设置存储                 │ │
+│  │  ├── system   - 打电话、PDA 扫码              │ │
+│  │  └── log      - 日志上传  ← 新增              │ │
+│  └───────────────────────────────────────────────┘ │
+│                          ↓                          │
+│  ┌───────────────────────────────────────────────┐ │
+│  │          监控层（Monitor）                     │ │
+│  │  - 自动记录 API 调用性能                      │ │
+│  │  - 自动记录错误信息                           │ │
+│  │  - 定时通过 log API 上报                      │ │
+│  │  - 错误立即通过 log API 上报                  │ │
+│  └───────────────────────────────────────────────┘ │
+│                          ↓                          │
+│  ┌───────────────────────────────────────────────┐ │
+│  │          Debug 层（Debug）                     │ │
+│  │  - vconsole 集成（移动端调试）                │ │
+│  │  - 调用追踪（查看调用栈）                     │ │
+│  │  - 日志记录（分级记录）                       │ │
+│  └───────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│                   原生层                             │
+│                                                     │
+│  ┌───────────────────────────────────────────────┐ │
+│  │          Android                               │ │
+│  │  - InjectJavascript.init() 触发初始化         │ │
+│  │  - LogUtil (SLF4J + Logback)                  │ │
+│  │  - 写入日志文件到 logs 目录                    │ │
+│  └───────────────────────────────────────────────┘ │
+│                                                     │
+│  ┌───────────────────────────────────────────────┐ │
+│  │          iOS                                   │ │
+│  │  - iframe 触发初始化                           │ │
+│  │  - LogUtil (OSLog)                            │ │
+│  │  - 写入日志文件                                │ │
+│  └───────────────────────────────────────────────┘ │
+│                                                     │
+│  ┌───────────────────────────────────────────────┐ │
+│  │          统一日志管理                          │ │
+│  │  - 收集日志文件                                │ │
+│  │  - 压缩、加密                                  │ │
+│  │  - 批量上传到服务器                            │ │
+│  └───────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+```
+
+## 2. 核心流程图
+
+### 2.1 初始化流程
+
+```
+开始
+  ↓
+平台检测
+  ├─ Android → 设置 Platform.Android
+  ├─ iOS → 设置 Platform.iOS
+  └─ 其他 → 设置 Platform.Unknown
+  ↓
+检查是否在 App 中？
+  ├─ 否 → 返回 false（结束）
+  └─ 是 ↓
+配置 Debug
+  ├─ enabled? → 启用 debug
+  └─ useVConsole? → 加载 vconsole
+  ↓
+配置 Monitor
+  ├─ enabled? → 启用监控
+  └─ autoReport? → 启动定时上报
+  ↓
+初始化 Bridge
+  ├─ Android → InjectJavascript.init()
+  └─ iOS → 创建 iframe 触发
+  ↓
+等待 Bridge 注入
+  ├─ 成功 → isInitialized = true
+  └─ 超时(10s) → 抛出异常
+  ↓
+记录初始化日志
+  └─ JSBridge.log.info('初始化成功')
+  ↓
+返回 true（成功）
+```
+
+### 2.2 API 调用流程
+
+```
+子应用调用 JSBridge.scan()
+  ↓
+API 层（device.ts）
+  ↓
+Monitor 记录开始
+  └─ recordStart(api, platform, params)
+  ↓
+Debug 追踪
+  └─ trace(api, params)
+  ↓
+Bridge 调用
+  └─ bridge.call('scan', data)
+  ↓
+原生处理
+  └─ 扫码、选择媒体等
+  ↓
+原生返回结果
+  ↓
+Monitor 记录结束
+  └─ recordEnd(record, success, result, error)
+  ↓
+Debug 记录日志
+  └─ debug.log('info', message)
+  ↓
+返回给子应用
+```
+
+### 2.3 监控上报流程
+
+```
+SDK API 调用
+  ↓
+Monitor 自动记录
+  ├─ 记录性能数据
+  ├─ 记录成功/失败
+  └─ 缓存到 records[]
+  ↓
+定时任务触发（1 分钟）
+  ↓
+Monitor.report()
+  ├─ 汇总 records 和 stats
+  └─ 构造 JSON 数据
+  ↓
+调用 bridge.call('log', {...})
+  ├─ tag: 'JSBridge-Monitor'
+  ├─ level: 'INFO'
+  └─ message: '[MONITOR] {...}'
+  ↓
+原生 LogUtil 处理
+  ├─ 写入日志文件
+  └─ 标记为待上传
+  ↓
+原生统一上传
+  ├─ 压缩日志文件
+  ├─ 加密（可选）
+  └─ 批量上传到服务器
+  ↓
+服务器接收和分析
+```
+
+### 2.4 日志上传流程
+
+```
+子应用调用 JSBridge.log.info('用户行为', 'UserBehavior')
+  ↓
+Log API 层（log.ts）
+  ├─ 构造 LogRequest
+  └─ tag: 'UserBehavior'
+  └─ level: 'INFO'
+  └─ message: '用户行为'
+  ↓
+Monitor 记录（可选）
+  └─ recordStart('log', platform)
+  ↓
+调用 bridge.call('log', {...})
+  ↓
+原生 log handler
+  ├─ 解析 LogRequest
+  └─ 根据 level 调用 LogUtil
+  ↓
+LogUtil 写入日志文件
+  ├─ Android: SLF4J + Logback
+  └─ iOS: OSLog
+  ↓
+Monitor 记录结束（可选）
+  └─ recordEnd(record, success)
+  ↓
+原生统一上传到服务器
+```
+
+### 2.5 错误上报流程（立即）
+
+```
+API 调用失败
+  ↓
+Bridge 捕获错误
+  ↓
+Monitor 记录失败
+  └─ recordEnd(record, false, undefined, error)
+  ↓
+Monitor 立即上报错误
+  └─ reportError(api, error, detail)
+  ↓
+调用 bridge.call('log', {...})
+  ├─ tag: 'JSBridge-Monitor'
+  ├─ level: 'ERROR'  ← 错误级别
+  └─ message: '[ERROR] {...}'
+  ↓
+原生 LogUtil 写入（ERROR 级别）
+  ↓
+原生可以立即上传 ERROR 日志
+  └─ 不等待定时任务，立即处理
+```
+
+## 3. 模块交互图
+
+### 3.1 模块依赖关系
+
+```
+┌─────────────┐
+│   index.ts  │  统一导出
+└──────┬──────┘
+       │
+       ├─────────────────────────────┐
+       ↓                             ↓
+┌─────────────┐              ┌─────────────┐
+│  Bridge.ts  │              │  Monitor.ts │
+│  核心通信    │◄─────────────│  监控       │
+└──────┬──────┘              └──────┬──────┘
+       │                            │
+       │                            ↓
+       │                     ┌─────────────┐
+       │                     │  Debug.ts   │
+       │                     │  调试       │
+       │                     └─────────────┘
+       │
+       ├────────────┬────────────┬────────────┐
+       ↓            ↓            ↓            ↓
+┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
+│device.ts │ │ media.ts │ │router.ts │ │  log.ts  │
+│设备 API  │ │媒体 API  │ │路由 API  │ │日志 API  │
+└──────────┘ └──────────┘ └──────────┘ └──────────┘
+```
+
+### 3.2 调用链路图
+
+```
+子应用
+  ↓
+JSBridge.scan()
+  ↓
+device.scan()
+  ↓
+┌─────────────────────────────────┐
+│ Monitor.recordStart()           │ → 记录开始
+└─────────────────────────────────┘
+  ↓
+┌─────────────────────────────────┐
+│ Debug.trace()                   │ → 追踪调用
+└─────────────────────────────────┘
+  ↓
+bridge.call('scan', data)
+  ↓
+WKWebViewJavascriptBridge
+  ↓
+原生处理
+  ↓
+返回结果
+  ↓
+┌─────────────────────────────────┐
+│ Monitor.recordEnd()             │ → 记录结束
+└─────────────────────────────────┘
+  ↓
+┌─────────────────────────────────┐
+│ Debug.log()                     │ → 记录日志
+└─────────────────────────────────┘
+  ↓
+返回给子应用
+```
+
+## 4. 日志管理架构
+
+### 4.1 统一日志流
+
+```
+┌─────────────────────────────────────┐
+│         日志来源                     │
+│                                     │
+│  ┌─────────────┐  ┌─────────────┐  │
+│  │ SDK 监控日志 │  │子应用业务日志│  │
+│  │             │  │             │  │
+│  │- 性能数据   │  │- 用户行为   │  │
+│  │- 调用统计   │  │- 业务错误   │  │
+│  │- 错误信息   │  │- 性能数据   │  │
+│  └──────┬──────┘  └──────┬──────┘  │
+│         │                │         │
+│         └────────┬───────┘         │
+└──────────────────┼─────────────────┘
+                   ↓
+         ┌─────────────────┐
+         │   log API       │
+         │  bridge.call()  │
+         └────────┬────────┘
+                  ↓
+┌─────────────────────────────────────┐
+│         原生日志系统                 │
+│                                     │
+│  ┌─────────────┐  ┌─────────────┐  │
+│  │  Android    │  │    iOS      │  │
+│  │             │  │             │  │
+│  │ LogUtil     │  │  LogUtil    │  │
+│  │ (SLF4J)     │  │  (OSLog)    │  │
+│  └──────┬──────┘  └──────┬──────┘  │
+│         │                │         │
+│         └────────┬───────┘         │
+│                  ↓                  │
+│         ┌─────────────────┐        │
+│         │  日志文件        │        │
+│         │  logs/*.log      │        │
+│         └────────┬────────┘        │
+│                  ↓                  │
+│         ┌─────────────────┐        │
+│         │  统一上传        │        │
+│         │  - 压缩          │        │
+│         │  - 加密（可选）  │        │
+│         │  - 批量上传      │        │
+│         └────────┬────────┘        │
+└──────────────────┼─────────────────┘
+                   ↓
+          ┌─────────────────┐
+          │     服务器       │
+          │  - 接收日志      │
+          │  - 分析数据      │
+          │  - 监控告警      │
+          └─────────────────┘
+```
+
+### 4.2 日志分类
+
+```
+日志类型
+├── SDK 监控日志
+│   ├── 性能数据
+│   │   ├── API 调用次数
+│   │   ├── 成功/失败次数
+│   │   └── 平均/最大/最小耗时
+│   │
+│   ├── 调用记录
+│   │   ├── api 名称
+│   │   ├── 平台
+│   │   ├── 耗时
+│   │   └── 成功/失败
+│   │
+│   └── 错误信息
+│       ├── 错误 API
+│       ├── 错误消息
+│       └── 错误详情
+│
+└── 子应用业务日志
+    ├── 用户行为
+    │   ├── 页面访问
+    │   ├── 按钮点击
+    │   └── 操作完成
+    │
+    ├── 业务错误
+    │   ├── 订单失败
+    │   ├── 支付失败
+    │   └── 其他错误
+    │
+    ├── 性能数据
+    │   ├── 页面加载
+    │   ├── API 响应
+    │   └── 资源加载
+    │
+    └── API 调用
+        ├── 请求开始
+        ├── 请求成功
+        └── 请求失败
+```
+
+## 5. 平台兼容架构
+
+### 5.1 双平台统一接口
+
+```
+子应用调用
+  ↓
+JSBridge.scan()  ← 统一接口
+  ↓
+┌─────────────────────────────────┐
+│        Bridge 层                 │
+│                                 │
+│  检测平台：getPlatform()         │
+│    ├─ Android                   │
+│    └─ iOS                       │
+│                                 │
+│  平台特定初始化                  │
+│    ├─ Android: InjectJavascript│
+│    └─ iOS: iframe 触发          │
+│                                 │
+│  统一调用接口                    │
+│    └─ callHandler(method, data)│
+└─────────────────────────────────┘
+  ↓
+原生处理（平台特定）
+  ├─ Android: Java/Kotlin 实现
+  └─ iOS: Swift/ObjC 实现
+  ↓
+返回统一格式
+```
+
+## 6. 监控数据流
+
+### 6.1 监控数据收集
+
+```
+API 调用
+  ↓
+自动记录
+  ├─ api: 'scan'
+  ├─ platform: 'android'
+  ├─ startTime: 1706859600000
+  ├─ duration: 1234
+  ├─ success: true
+  └─ error: null
+  ↓
+缓存到内存
+  └─ records[] (最多 100 条)
+  ↓
+定时任务（1 分钟）
+  ↓
+汇总统计
+  ├─ totalCalls
+  ├─ successCalls
+  ├─ failedCalls
+  ├─ avgDuration
+  ├─ maxDuration
+  └─ minDuration
+  ↓
+通过 log API 上报
+  └─ bridge.call('log', {
+      tag: 'JSBridge-Monitor',
+      level: 'INFO',
+      message: '[MONITOR] {...}'
+    })
+  ↓
+原生写入日志文件
+  ↓
+原生上传到服务器
+```
+
+### 6.2 错误上报（立即）
+
+```
+API 调用失败
+  ↓
+捕获错误
+  ↓
+Monitor.reportError()
+  ↓
+立即调用 log API
+  └─ bridge.call('log', {
+      tag: 'JSBridge-Monitor',
+      level: 'ERROR',
+      message: '[ERROR] {...}'
+    })
+  ↓
+原生写入日志文件（ERROR 级别）
+  ↓
+原生立即上传
+  └─ 不等待定时任务
+```
+
+## 7. Debug 模式架构
+
+### 7.1 Debug 流程
+
+```
+开发环境
+  ↓
+配置 debug: { enabled: true, useVConsole: true }
+  ↓
+初始化时
+  ├─ 动态加载 vconsole
+  └─ 创建 Debug 实例
+  ↓
+API 调用时
+  ├─ Debug.trace() → 显示调用栈
+  └─ Debug.log() → 记录到 logs[]
+  ↓
+vconsole 显示
+  ├─ console.log
+  ├─ console.error
+  └─ 调用栈信息
+  ↓
+可以查看
+  ├─ Debug.getLogs('error')
+  └─ Debug.getLogs(undefined, 10)
+```
+
+## 8. 代码组织架构
+
+### 8.1 目录结构
+
+```
+src/
+├── core/
+│   └── Bridge.ts
+│       ├─ class Bridge
+│       ├─ detectPlatform()
+│       ├─ init()
+│       ├─ call()
+│       └─ register()
+│
+├── monitor/
+│   └── Monitor.ts
+│       ├─ class Monitor
+│       ├─ recordStart()
+│       ├─ recordEnd()
+│       ├─ report()  ← 通过 log
+│       └─ reportError()  ← 通过 log
+│
+├── debug/
+│   └── Debug.ts
+│       ├─ class Debug
+│       ├─ initVConsole()
+│       ├─ log()
+│       └─ trace()
+│
+├── api/
+│   ├── device.ts
+│   │   ├─ scan()
+│   │   ├─ vibrate()
+│   │   ├─ getDeviceInfo()
+│   │   └─ getNetworkType()
+│   │
+│   ├── media.ts
+│   │   ├─ chooseMedia()
+│   │   ├─ uploadFile()
+│   │   ├─ previewImage()
+│   │   └─ getImageInfo()
+│   │
+│   ├── log.ts  ← 新增
+│   │   ├─ writeLog()
+│   │   └─ log { debug, info, warn, error }
+│   │
+│   └── ...
+│
+├── types/
+│   └── index.ts
+│       ├─ interface ScanOptions
+│       ├─ interface ScanResult
+│       ├─ interface LogRequest  ← 新增
+│       └─ ...
+│
+└── index.ts
+    ├─ init()
+    ├─ JSBridge { scan, log, ... }
+    ├─ Monitor { getStats, report, ... }
+    └─ Debug { trace, getLogs, ... }
+```
+
+## 9. 数据格式图
+
+### 9.1 监控数据格式
+
+```json
+{
+  "records": [
+    {
+      "api": "scan",
+      "platform": "android",
+      "startTime": 1706859600000,
+      "endTime": 1706859601234,
+      "duration": 1234,
+      "success": true,
+      "params": { "scanType": ["qrCode"] },
+      "result": { "resp_code": 1000, "resp_result": "xxx" }
+    }
+  ],
+  "stats": [
+    {
+      "api": "scan",
+      "totalCalls": 150,
+      "successCalls": 145,
+      "failedCalls": 5,
+      "avgDuration": 1234,
+      "maxDuration": 3000,
+      "minDuration": 500
+    }
+  ],
+  "timestamp": 1706859601234
+}
+```
+
+### 9.2 日志数据格式
+
+```json
+{
+  "tag": "UserBehavior",
+  "level": "INFO",
+  "message": "用户点击了购买按钮"
+}
+```
+
+### 9.3 错误数据格式
+
+```json
+{
+  "type": "error",
+  "api": "scan",
+  "error": "扫码失败",
+  "detail": {
+    "errorCode": "E001",
+    "reason": "相机权限被拒绝"
+  },
+  "platform": "android",
+  "timestamp": 1706859601234
+}
+```
+
+## 10. 扩展架构
+
+### 10.1 新增 API 流程
+
+```
+1. 在 api/ 目录创建新文件
+   └─ src/api/newFeature.ts
+
+2. 实现 API 函数
+   └─ export async function newFeature(options) {...}
+
+3. 在 types/index.ts 添加类型
+   └─ export interface NewFeatureOptions {...}
+
+4. 在 index.ts 导出
+   └─ export const JSBridge = { ..., newFeature }
+
+5. 原生端实现
+   └─ webView.registerHandler("newFeature") {...}
+```
+
+### 10.2 新增监控指标
+
+```
+1. 在 Monitor.ts 添加新指标
+   └─ interface PerformanceStats { ..., newMetric }
+
+2. 在 updateStats() 中计算
+   └─ stats.newMetric = calculate(...)
+
+3. 在 report() 中上报
+   └─ 自动包含在 JSON 中
+```
+
+## 11. 部署架构
+
+### 11.1 npm 发布流程
+
+```
+开发
+  ↓
+构建
+  ├─ rollup -c
+  └─ 生成 dist/
+  ↓
+测试
+  ├─ npm test
+  └─ 手动测试
+  ↓
+发布
+  ├─ npm version patch/minor/major
+  └─ npm publish
+  ↓
+子应用更新
+  └─ npm install @hd-front-end/jsbridge-sdk@latest
+```
+
+### 11.2 子应用集成流程
+
+```
+子应用
+  ↓
+安装 SDK
+  └─ npm install @hd-front-end/jsbridge-sdk
+  ↓
+修改代码
+  ├─ 修改 App.vue 初始化
+  ├─ 修改业务组件调用
+  └─ 添加日志记录
+  ↓
+测试验证
+  ├─ 功能测试
+  ├─ 日志测试
+  └─ 平台测试
+  ↓
+上线
+  └─ 发布到生产环境
+```
+
+## 12. 文档导航
+
+- **[00-项目概览.md](./00-项目概览.md)** - 项目概述
+- **[01-架构设计.md](./01-架构设计.md)** - 架构设计
+- **[02-技术实现.md](./02-技术实现.md)** - 技术实现
+- **[03-API使用文档.md](./03-API使用文档.md)** - API 文档
+- **[04-测试方案.md](./04-测试方案.md)** - 测试方案
+- **[05-迁移指南.md](./05-迁移指南.md)** - 迁移指南
+
+---
+
+**完整的架构图集，清晰易懂** 🎯
+