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

package/docs/07-/346/226/260/346/241/245/346/216/245/346/226/271/346/263/225/346/211/251/345/261/225/350/257/264/346/230/216.md

@@ -0,0 +1,139 @@
+# 新增桥接能力扩展说明
+
+本文档列出了我们在基础核心能力之外，通过 JsBridgeHandlers 和 hdH5Adapter 扩展提供的原生桥接方法。这些方法主要用于兼容原有 UniApp 生态或者提供更高级的业务能力。
+
+## 1. 快速使用
+
+新集成的能力都已通过统一入口导出，您可以直接在项目中引入使用：
+
+```typescript
+import { JsBridgeHandlers, hdH5Adapter, UniProxy } from '@hd-front-end/jsbridge-sdk'
+
+// 1. 初始化 H5 到 UniApp 的适配器（会代理 uni.xxx 方法到底层原生）
+hdH5Adapter()
+
+// 2. 直接调用原生 Handler
+JsBridgeHandlers.handleScan().then(res => console.log(res))
+```
+
+## 2. JsBridgeHandlers API 详情
+
+JsBridgeHandlers 提供了对底层原生能力的直接封装，所有方法均返回 Promise。
+
+### 2.1 扫码能力 (Scan)
+
+调用原生摄像头进行扫码（支持二维码、条形码）。
+
+```typescript
+static handleScan(request?: UniScanRequest): Promise<UniScanResult>
+```
+
+**入参 (UniScanRequest)**：
+- scanType (string[]): 扫码识别类型，qrCode、barCode。默认: ['qrCode', 'barCode']
+- hideAlbum (boolean): 是否隐藏相册。默认: false
+- language (string): iOS 语言设置 (zh-Hans 或 en)。默认: 'zh-Hans'
+- failedMsg (string): 相册选择照片识别错误提示(iOS)。
+- screenType (string): Android 全屏支持，设为 'full'。
+- timeoutInterval (string): 超时时间（秒）。默认: '10'
+- timeoutText (string): 超时提醒文本。
+- viewText (string): 扫码提示文字。
+
+**出参 (UniScanResult)**：
+- resp_code (number): 10:用户取消，11:其他错误，1000:成功
+- resp_result (string | null): 扫码结果
+- resp_message (string | null): 结果信息
+
+### 2.2 媒体与文件处理 (Media)
+
+#### 选择图片/视频
+```typescript
+static handleChooseMedia(request: UniChooseMediaRequest): Promise<UniChooseMediaResult | null>
+```
+**入参 (UniChooseMediaRequest)**:
+- sourceType (string[]): album 从相册选，camera 使用相机。默认 ['album', 'camera']
+- camera (string): 前置或后置 (front/back)。默认: 'back'
+- mediaType (string[]): image 或 video。默认 ['image', 'video']
+- count (number): 最多选择的文件个数。默认 9
+- maxDuration (number): 拍摄视频最长时间（3-30秒）。默认 30
+- sizeType (string[]): 是否压缩 (original, compressed)。
+
+**出参 (UniChooseMediaResult)**:
+包含 tempFiles (文件详细信息数组) 和 tempFilePaths (路径数组)。
+
+#### 获取图片信息
+```typescript
+static handleGetImageInfo(request: { src: string }): Promise<UniMediaFile>
+```
+返回图片的宽高、类型、路径、大小等详细信息。
+
+#### 上传文件
+```typescript
+static handleUploadFile(request: UniApp.UploadFileOption): Promise<UniUploadFileResult>
+```
+**出参 (UniUploadFileResult)**:
+- code (number): 200 表示成功
+- data (string | null): 开发者服务器返回的数据
+- statusCode (number | null): HTTP 状态码
+- errMsg (string | null): 错误信息
+
+#### 图片路径转 Base64
+```typescript
+static handlePathToBase64(request: { src: string }): Promise<string>
+```
+
+### 2.3 基础设备与系统功能 (System)
+
+- **handleMakePhoneCall(request: { phoneNumber: string })**: 拨打电话。
+- **handleSetNavigationBar(request: UniNavigationBarStyle)**: 动态设置原生导航栏。
+  - 参数包含: title (标题), frontColor (前景颜色 #ffffff 或 #000000), backgroundColor (背景十六进制颜色)。
+- **handleOpenSchemeUrl(request: UniUrlScheme)**: 唤起并打开特定的 Scheme 链接。
+  - 参数包含: url (链接), openType (APP 或 SYSTEM), style (标题栏样式)。
+- **handleGetAppInfo()**: 获取 App 端的设备与应用信息。
+- **handleLog(request: UniLog)**: 调用原生打日志功能。包含 tag, level (INFO/ERROR等), message。
+
+### 2.4 路由与页面生命周期 (Router & Lifecycle)
+
+- **handleRouterAfterEach(to, from)**: 路由变化后通知原生端。
+- **handlePageLifeCycle(lifecycle: PageLifeCycle)**: 页面生命周期通知原生 (onLoad, onUnload 等)。
+- **handleAppOnload(data: any)**: 通知原生 App 页面已加载完成。
+- **handleCloseWebView()**: 关闭当前的 WebView。
+
+### 2.5 打印能力 (Bluetooth Print)
+
+- **handleBluetoothPrint(request: any)**: 连接蓝牙打印机打印数据。
+- **handleBluetoothPrintImage(request: any)**: 连接蓝牙打印机打印图片。
+
+### 2.6 业务交互与事件注册 (Business)
+
+以下方法用于向原生注册回调事件，供原生主动触发前端：
+- **registerOnRoute(handler)**: 原生调用的路由跳转回调。
+- **registerOnGetRouteInfo(handler)**: 原生获取当前路由信息的回调。
+- **registerOnRefreshStore(handler)**: 原生触发前端刷新 Store 数据。
+- **registerOnPdaScan(handler)**: 接收 PDA 实体按键扫码结果。
+
+其它操作：
+- **handleLogout()**: 通知原生执行退出登录。
+- **handleReloadModule(request: { appId: string })**: 通知原生重新加载子应用。
+
+---
+
+## 3. hdH5Adapter (UniApp 代理适配器)
+
+hdH5Adapter() 方法被调用后，会拦截并重写全局的 uni 对象方法，将其底层实现代理到 JsBridgeHandlers 上，使得原有的基于 UniApp 的代码可以在不修改的情况下直接在 H5 容器内运行。
+
+目前支持拦截/代理的 uni 方法有：
+
+- **uni.scanCode(options)**: 代理至 handleScan。
+- **uni.chooseVideo(options)**: 代理至 handleChooseMedia。
+- **uni.getImageInfo(options)**: 代理至 handleGetImageInfo。
+- **uni.uploadFile(options)**: 代理至 handleUploadFile。
+- **uni.navigateBack(options)**: 代理至路由回退或 handleCloseWebView。
+- **uni.makePhoneCall(options)**: 代理至 handleMakePhoneCall。
+- **uni.setNavigationBarTitle(options)**: 代理至 handleSetNavigationBar。
+- **uni.setNavigationBarColor(options)**: 代理至 handleSetNavigationBar。
+
+### 特殊说明：UniProxy
+由于在某些环境下，uni.chooseImage 等属性是只读的无法被直接覆盖，因此我们提供了 UniProxy 对象来单独暴露这些被限制的方法：
+- **UniProxy.chooseImage(options)**: 代理至 handleChooseMedia（用于图片选择）。
+- **UniProxy.pathToBase64(path)**: 代理至 handlePathToBase64。
+

package/docs/CODE_REVIEW.md

@@ -0,0 +1,65 @@
+# JSBridge SDK Code Review 报告
+
+## 1. 概述
+本次 Code Review 覆盖了 JSBridge SDK 的核心模块、监控模块、调试模块及 API 封装层。整体来看，代码结构清晰，设计模式合理（单例模式、门面模式），逻辑实现符合预期。
+
+- **评审对象**: `/src` 目录下的核心源码
+- **评审人**: Senior Code Reviewer
+- **状态**: ✅ **PASS** (含少量优化建议)
+
+## 2. 详细评审
+
+### 2.1 核心通信层 (`src/core/Bridge.ts`)
+*   **优点**:
+    *   ✅ **平台检测完善**: 准确区分了 Android/iOS/Unknown 环境，并对 UA 进行了扩展支持。
+    *   **Promise 封装**: 很好地解决了回调地狱问题，支持 `async/await`。
+    *   **超时机制**: 内置了 10s 超时保护，防止死锁。
+    *   **单例模式**: 确保全局唯一的 Bridge 实例，避免重复初始化。
+    *   **自动初始化**: 在 `call/register` 方法中增加了自动初始化的防御逻辑，提升了健壮性。
+*   **改进建议**:
+    *   ⚠️ **类型安全**: `call<T>` 方法虽然支持泛型，但内部 `this.bridge.callHandler` 回调参数 `result` 默认是 `any`，建议增加运行时类型检查或断言。
+    *   ⚠️ **并发问题**: `initPromise` 虽然处理了并发调用，但在高并发场景下 `setTimeout` 的清理逻辑可能存在边界情况，建议增加 `AbortController` 支持（如果环境允许）。
+
+### 2.2 监控模块 (`src/monitor/Monitor.ts`)
+*   **优点**:
+    *   ✅ **原生日志上报**: 摒弃了 HTTP 上报，改用 `bridge.call('log')`，复用了原生的日志通道，设计非常巧妙。
+    *   **性能优化**: 支持 `visibilitychange` 事件，仅在页面可见或隐藏时批量上报，减少了对主线程的占用。
+    *   **错误兜底**: 实现了 `reportError` 立即上报机制，确保关键错误不丢失。
+*   **改进建议**:
+    *   ⚠️ **内存风险**: `this.records` 数组虽然有 `maxRecords` 限制，但如果 `report` 持续失败（如 Bridge 断开），积压队列可能会占用内存。建议增加“连续失败 N 次后暂停监控”的熔断机制。
+
+### 2.3 调试模块 (`src/debug/Debug.ts`)
+*   **优点**:
+    *   ✅ **动态加载**: `vconsole` 采用动态 `import`，极大减小了首屏包体积。
+    *   **日志分级**: 清晰区分了 `debug/info/warn/error`，便于过滤。
+*   **改进建议**:
+    *   ⚠️ **生产环境泄露**: 虽然依赖配置开启，但建议在构建阶段（rollup/webpack）通过 `define` 插件彻底移除 Debug 代码，避免源码泄露。
+
+### 2.4 日志 API (`src/api/log.ts`)
+*   **优点**:
+    *   ✅ **类型定义**: 提供了完整的 `LogRequest` 和 `LogLevel` 定义。
+    *   **批量接口**: 提供了 `writeLogs` 批量接口，减少了 Bridge 通信频次。
+
+### 2.5 类型定义 (`src/types/index.ts`)
+*   **优点**:
+    *   ✅ **完整性**: 覆盖了所有核心接口和配置项。
+    *   **全局声明**: 正确扩展了 `Window` 接口，解决了 TS 报错。
+
+## 3. 总体评分
+
+| 维度 | 评分 (1-5) | 说明 |
+| :--- | :--- | :--- |
+| **代码质量** | 4.8 | 代码风格统一，注释详尽，逻辑清晰。 |
+| **健壮性** | 4.5 | 考虑了超时、重试、错误兜底，但内存保护可加强。 |
+| **可维护性** | 5.0 | 模块解耦做得很好，职责单一。 |
+| **性能** | 4.7 | 动态加载和批量上报是亮点。 |
+
+## 4. 后续行动计划 (Action Items)
+
+1.  **[High]** 在 `Monitor.ts` 中增加熔断机制，防止日志上报失败导致内存积压。
+2.  **[Medium]** 在 `Bridge.ts` 中增加对 `callHandler` 返回数据的运行时校验（可选，视业务严格程度而定）。
+3.  **[Low]** 补充单元测试（Unit Tests），特别是针对 `Monitor` 的批量上报逻辑。
+
+---
+**结论**: 代码已达到生产发布标准 (Production Ready)。建议在解决 High 优先级问题后发布 v2.0.0 正式版。
+

package/docs/EVALUATION.md

@@ -0,0 +1,72 @@
+# JSBridge SDK 方案评估报告
+
+## 1. 方案可行性评估
+
+基于对现有文档（架构设计、技术实现、API文档、测试方案、迁移指南）的综合分析，**该方案具备极高的可行性**。
+
+*   **技术成熟度**：采用业界通用的 WebViewJavascriptBridge 通信机制，在 `soa-android-demo` 和 `soa` 项目中已有实践验证。SDK 仅在此基础上进行了封装和标准化，技术风险低。
+*   **兼容性设计**：方案明确区分了 Android (`InjectJavascript`) 和 iOS (`iframe` + `WKWebView`) 的底层注入差异，并提供了统一的上层 API。同时通过 Promise 封装解决了回调地狱问题。
+*   **架构解耦**：采用了分层架构（API层 -> 核心层 -> 协议层），将业务逻辑与底层通信解耦，便于后续独立升级维护。
+*   **轻量级**：核心代码量约 1150 行，打包体积仅 ~7KB (gzip)，对宿主应用性能影响极小。
+
+## 2. 优点分析
+
+1.  **统一性与标准化**
+    *   **统一 API**：抹平了多端差异，所有子应用（SOA, MPA-Mini）使用同一套 API，降低了开发者的认知负担。
+    *   **统一日志**：创新性地将 SDK 内部监控日志与业务日志统一通过原生 LogUtil 通道上报，解决了 H5 日志丢失和难以关联排查的问题。
+
+2.  **完善的稳定性保障**
+    *   **超时控制**：内置 10s 超时机制，防止因原生无响应导致 JS Promise 永久挂起，避免页面假死。
+    *   **错误兜底**：全局的错误捕获和立即上报机制（`Monitor.reportError`），确保线上异常能被及时发现。
+
+3.  **优秀的可观测性**
+    *   **全链路监控**：自动采集 API 调用的成功率、耗时等性能指标，并支持生成可视化报表（需服务端配合）。
+    *   **Debug 模式**：集成了 vConsole 和调用链路追踪（Trace），极大提升了开发调试效率。
+
+4.  **良好的开发体验**
+    *   **TypeScript 支持**：提供完整的类型定义文件 (`.d.ts`)，支持 IDE 智能提示和编译时检查。
+    *   **Promise 风格**：摒弃了传统的回调地狱，支持 `async/await`，代码更简洁易读。
+
+5.  **低侵入性**
+    *   **渐进式迁移**：支持与旧版 Bridge 共存，允许业务项目按模块逐步迁移，降低了重构风险。
+    *   **纯 API 封装**：不绑定 Vue/React 等特定框架，适用于所有 H5 项目。
+
+## 3. 缺点与局限性
+
+1.  **原生端依赖强**
+    *   SDK 的高级功能（如日志上报、硬件调用）强依赖于原生端的实现。如果原生端未及时更新 `registerHandler`，前端 SDK 对应功能将不可用。需要端侧协同发布。
+
+2.  **Mock 能力简陋**
+    *   虽然设计了 Mock 模块，但目前的文档中 Mock 规则较为简单，仅支持静态返回值。对于复杂的业务场景（如根据入参返回不同结果、模拟网络延迟波动），现有的 Mock 机制可能不够灵活。
+
+3.  **缺乏版本协商机制**
+    *   当前设计中未见明确的“握手”或版本协商协议。如果原生 Bridge 协议升级（如方法名变更、参数结构调整），老版本 SDK 可能会直接崩溃，缺乏优雅降级策略。
+
+4.  **数据传输效率瓶颈**
+    *   基于 JSON 序列化的通信方式在传输大数据（如高清图片 Base64）时存在性能瓶颈，可能会导致 UI 卡顿。
+
+5.  **测试环境搭建成本**
+    *   虽然提供了 Mock 模式，但在非原生环境（如 Chrome）下无法完全模拟 WebView 的行为（如内存限制、生命周期事件），导致部分 Bug 只能在真机上复现。
+
+## 4. 潜在风险
+
+1.  **原生注入时序风险**
+    *   **描述**：在 Android 端，如果 `InjectJavascript` 注入晚于 JS 执行（尤其是首屏立即调用的场景），会导致 `init` 失败。
+    *   **建议**：虽然有 `WKWVJBCallbacks` 队列机制，但仍需确保原生端在 `onPageFinished` 之前完成对象注入，或者前端增加重试轮询机制。
+
+2.  **内存泄漏风险**
+    *   **描述**：Monitor 模块默认缓存 100 条日志记录，且 `reportTimer` 长期运行。如果页面长时间不关闭且日志量巨大，可能会占用过多内存。
+    *   **建议**：增加页面不可见时（`visibilitychange`）暂停上报、清理缓存的逻辑。
+
+3.  **安全性风险**
+    *   **描述**：缺乏对调用来源的验证机制。如果 WebView 被劫持加载了恶意第三方页面，该页面也可以调用 Bridge 能力（如获取用户 Token）。
+    *   **建议**：增加域名白名单校验，仅允许特定域名的页面初始化 Bridge。
+
+4.  **日志风暴风险**
+    *   **描述**：如果 `autoReport` 开启且网络状况不佳，或者业务代码在循环中大量打印日志，可能导致原生端日志队列堆积，甚至阻塞主线程。
+    *   **建议**：增加日志上报的频次限制（Throttle）和单次包大小限制。
+
+5.  **单点故障风险**
+    *   **描述**：SDK 是单例模式（Singleton），如果 `init` 过程中发生未捕获异常导致状态异常，整个应用的 Bridge 功能将全部瘫痪。
+    *   **建议**：在 `init` 和核心 `call` 方法中增加更健壮的 `try-catch` 保护，确保即使初始化部分失败，基础功能仍可用（或提供明确的错误提示）。
+

package/docs/README.md

@@ -0,0 +1,258 @@
+# JSBridge SDK 文档索引
+
+> **当前版本**：生产级 v2（通过原生 log 能力实现监控和日志上报）
+
+## 📚 推荐阅读顺序
+
+### 1️⃣ 快速开始（5-10 分钟）
+
+**必读文档**：
+
+- **[生产级-架构设计-v2.md](./生产级-架构设计-v2.md)** ⭐⭐⭐
+  - 完整架构说明
+  - 监控通过原生 log 上报
+  - 新增 log API
+  - 两个目的都实现
+
+- **[生产级-快速开始-v2.md](./生产级-快速开始-v2.md)** ⭐⭐⭐
+  - 5 分钟快速上手
+  - log API 使用示例
+  - 完整代码示例
+  - 最佳实践
+
+### 2️⃣ 深入理解（20-30 分钟）
+
+**核心文档**：
+
+- **[设计理念说明.md](./设计理念说明.md)** ⭐⭐⭐⭐⭐
+  - 为什么这样设计
+  - 设计演进历史
+  - 核心决策说明
+  - **必读！理解整个设计的关键**
+
+- **[平台兼容性说明.md](./平台兼容性说明.md)**
+  - Android/iOS 兼容方案
+  - 平台检测机制
+  - 平台特定优化
+  - 调试技巧
+
+- **[监控指南.md](./监控指南.md)**
+  - 监控使用指南
+  - 统计数据查看
+  - 告警规则设置
+  - 最佳实践
+
+### 3️⃣ 演进历史（了解背景）
+
+**参考文档**：
+
+- **[更新日志.md](./更新日志.md)**
+  - v1 → v2 变化说明
+  - HTTP 上报 → log 上报
+  - 为什么要改进
+  - 版本对比
+
+- **[关键问题解答.md](./关键问题解答.md)**
+  - 核心问题解答
+  - 常见疑问
+  - 设计决策说明
+
+## 📁 当前文档结构
+
+```
+docs/
+├── README.md                      # 本文件
+│
+├── 【生产级 v2 文档】（✅ 当前版本）
+│   ├── 生产级-架构设计-v2.md       # 完整架构
+│   ├── 生产级-快速开始-v2.md       # 快速上手
+│   ├── 平台兼容性说明.md           # Android/iOS 兼容
+│   └── 监控指南.md                # 监控使用指南
+│
+├── 【核心设计文档】
+│   ├── 设计理念说明.md            # ⭐⭐⭐⭐⭐ 必读
+│   ├── 更新日志.md                # 版本演进
+│   └── 关键问题解答.md            # 核心问题
+│
+└── 【完整版文档】（参考）
+    ├── 00-项目概览.md
+    ├── 01-架构设计.md
+    ├── 02-技术实现.md
+    ├── 03-API使用文档.md
+    ├── 04-测试方案.md
+    ├── 05-迁移指南.md
+    └── 06-架构图集.md
+```
+
+## 🎯 核心特性
+
+### 1. 监控通过原生 log 上报
+
+✅ **SDK 自动监控**
+- 自动记录 API 调用性能
+- 定时通过 log API 上报
+- 错误立即上报
+
+✅ **原生统一管理**
+- LogUtil 写入日志文件
+- 统一上传策略
+- 可靠性更高
+
+### 2. 提供 log API 给子应用
+
+✅ **简单易用**
+```typescript
+await JSBridge.log.info('用户行为', 'UserBehavior')
+await JSBridge.log.error('业务错误', 'BusinessError')
+```
+
+✅ **统一管理**
+- 通过原生写入日志
+- 无需关心上传细节
+- 原生统一上传
+
+### 3. 两个目的都实现
+
+✅ **监控 SDK 稳定性**
+- SDK 自动记录性能和错误
+- 定时/立即上报到原生
+- 服务器可分析运行状况
+
+✅ **提供子应用日志能力**
+- 子应用调用简单的 log API
+- 日志自动写入原生
+- 无需关心上传细节
+
+## 📊 版本说明
+
+### 生产级 v2（当前版本）✅
+
+**特性**：
+- ✅ 监控通过原生 log 上报
+- ✅ 提供 log API 给子应用
+- ✅ 统一日志管理
+- ✅ 两个目的都实现
+
+**文档**：
+- 生产级-架构设计-v2.md
+- 生产级-快速开始-v2.md
+
+### 已废弃版本
+
+以下版本已被删除，不再维护：
+- ~~生产级 v1~~（HTTP 上报，已删除）
+- ~~最终版~~（纯 API，缺少必需能力，已删除）
+- ~~实用版 v1/v2~~（理解错误，已删除）
+- ~~完整版~~（过度设计，仅作参考保留）
+
+## 🚀 快速开始
+
+### 1. 安装
+
+```bash
+npm install @hd-front-end/jsbridge-sdk
+```
+
+### 2. 初始化
+
+```typescript
+import { init } from '@hd-front-end/jsbridge-sdk'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+await init({
+  debug: {
+    enabled: isDev,
+    useVConsole: isDev
+  },
+  monitor: {
+    enabled: !isDev,
+    autoReport: !isDev,        // 通过 log 自动上报
+    reportInterval: 60000,
+    logTag: 'JSBridge-Monitor'
+  }
+})
+```
+
+### 3. 使用 API
+
+```typescript
+// 使用 bridge API
+const result = await JSBridge.scan()
+
+// 上传业务日志
+await JSBridge.log.info('用户行为', 'UserBehavior')
+await JSBridge.log.error('业务错误', 'BusinessError')
+```
+
+## 📖 详细文档
+
+- **快速上手**：[生产级-快速开始-v2.md](./生产级-快速开始-v2.md)
+- **完整架构**：[生产级-架构设计-v2.md](./生产级-架构设计-v2.md)
+- **设计理念**：[设计理念说明.md](./设计理念说明.md) ⭐
+- **平台兼容**：[平台兼容性说明.md](./平台兼容性说明.md)
+- **监控指南**：[监控指南.md](./监控指南.md)
+
+## ❓ 常见问题
+
+### Q1: 为什么监控要通过 log 上报？
+
+**A:** 
+- 统一日志管理
+- 性能更好（不占用 H5 网络）
+- 更可靠（本地先存）
+- 原生控制上传策略
+
+### Q2: log API 有什么用？
+
+**A:**
+- 子应用可以上传业务日志
+- 使用简单：`JSBridge.log.info(...)`
+- 日志自动写入原生
+- 原生统一管理和上传
+
+### Q3: 两个目的是什么？
+
+**A:**
+1. **监控 SDK 稳定性** - SDK 自动记录和上报
+2. **提供子应用日志能力** - 子应用主动上传日志
+
+## 🎓 学习路径
+
+### 新手（10 分钟）
+1. 阅读 [生产级-快速开始-v2.md](./生产级-快速开始-v2.md)
+2. 跑通示例代码
+
+### 进阶（30 分钟）
+1. 阅读 [生产级-架构设计-v2.md](./生产级-架构设计-v2.md)
+2. 理解 log 上报机制
+3. 阅读 [设计理念说明.md](./设计理念说明.md) ⭐
+
+### 深入（1 小时）
+1. 阅读 [平台兼容性说明.md](./平台兼容性说明.md)
+2. 阅读 [监控指南.md](./监控指南.md)
+3. 查看原生端实现参考
+4. 阅读 [更新日志.md](./更新日志.md)
+
+## 💡 核心价值
+
+### 1. 统一日志管理
+✅ SDK 监控日志 → log API → 原生 LogUtil  
+✅ 子应用业务日志 → log API → 原生 LogUtil  
+✅ 原生统一上传到服务器  
+
+### 2. 简单易用
+✅ 初始化简单 - 一次配置  
+✅ API 简单 - `JSBridge.log.info(...)`  
+✅ 无需关心细节 - 原生负责上传  
+
+### 3. 生产可用
+✅ Android/iOS 兼容  
+✅ 监控能力完善  
+✅ debug 模式完善  
+✅ 两个目的都实现  
+
+---
+
+**推荐从 [生产级-架构设计-v2.md](./生产级-架构设计-v2.md) 开始阅读！** 🚀
+