概述¶

2026-05-13

本文档对应用程序的主要集成点进行了高层次概述——介绍 WebView、原生 Android 层、BLE 协议栈和后端 API 之间的协作方式。

目标是解释各组件之间的通信关系，以及涉及哪些契约（回调、处理器、端点），而不深入底层实现细节。

从整体来看，主要分为三个层次：

WebView（前端 JS）
- 负责渲染 UI。
- 通过 bridgeWebView 与原生 Android 层通信。
原生 Android 层
- 在 BaseWebViewActivity 及相关类中实现。
- 暴露一组桥接处理器（如 startBleScan、connBleByMacAddress、initBleData 等）。
- 与 Android BLE 协议栈及网络/API 客户端集成。
后端 / 外部服务
- 应用程序调用的 HTTP/REST 或 GraphQL 端点，用于获取配置、设备元数据、用户数据等。
- 可选的第三方服务（日志、分析、身份验证），如已配置。

每一层都有明确的契约，以便各层能够独立演进。

1. WebView ↔ 原生桥接集成¶

目的：允许在 WebView 中运行的 JavaScript 调用原生函数并接收回调。

bridgeWebView.callHandler(name, payload, callback)
- JS → 原生调用（如 startBleScan、connBleByMacAddress、initBleData）。
- payload 通常是序列化的 JSON 对象字符串。
- callback 接收来自原生的 JSON 字符串响应。
bridgeWebView.registerHandler(name, callback)
- 原生 → JS 调用（事件通知）。
- JS 注册如下处理器：
  - findDeviceCallback（扫描过程中发现设备时触发）
  - connectSuccess（设备连接成功时触发）
  - connectFail（连接失败或超时时触发）
  - onCompleteCallback（BLE 数据初始化完成时触发）
  - 以及其他应用特定事件。

可以将其视为暴露给前端的迷你"内部 API"。

目的：将所有 BLE 操作封装在一组稳定的 Java ↔ JS 桥接方法之后。

典型职责包括： - 检查手机 BLE 状态 - getPhoneBleStatus() 暴露给 JS，使用 Android API 检查：

    - 蓝牙硬件支持情况
    - 蓝牙是否已开启
    - 所需权限是否已授予

扫描设备
- startBleScan() / stopBleScan() 映射到 Android 的 BLE 扫描 API。
- 发现设备时，原生层将设备信息序列化为 JSON 并在 JS 中触发 findDeviceCallback。
连接设备
- connBleByMacAddress(macAddress) 封装连接逻辑。
- 成功/失败/超时时，在 JS 侧触发 connectSuccess 或 connectFail。
数据初始化
- initBleData() 封装了以下操作：
  - 服务和特征的发现
  - 可选的初始读取
  - 为后续的读/写/通知操作准备内部映射。
初始化完成后，触发 JS 中的 onCompleteCallback。

该集成将所有 BLE 复杂性保留在原生代码中，同时向 WebView 暴露简单的高级 API。

目的：将设备状态和用户操作与后端同步。

具体位置取决于架构设计：

典型集成点：

这些 API 通常在 API 与端点章节中单独说明（路径、请求/响应格式、版本管理）。

由于存在多个层次，版本控制至关重要：

桥接 API 版本
- 处理器集合（如 startBleScan、connBleByMacAddress）构成 WebView 与原生层之间的契约。
- 任何重大变更都应升级桥接版本，并在各应用版本之间协调发布。
BLE 协议版本
- 设备的 GATT 结构（服务、特征、负载格式）应进行版本管理，尤其是固件随时间演进时。

集成文档应明确说明哪些版本可以协同工作。

集成层往往是大多数故障的发生地，因此我们将错误处理视为一等关注点：

WebView ↔ 原生
- 所有 callHandler 的响应都应包含成功标志和错误消息或错误码。
- JS 应显示用户友好的错误提示，并提供重试选项。
原生 ↔ BLE
- 处理常见的 BLE 问题：超时、断连、权限、不支持的功能。
- 将底层错误码映射为简单结果（connectFail、timeout 等），供 JS 消费。
应用 ↔ 后端
- 网络故障和 HTTP 错误应以结构化错误响应的形式呈现，而非崩溃。
- 在适当的地方实现安全的重试策略（幂等操作）。

本集成概述旨在作为入口点。各集成的详细行为记录在专属页面中：