SDK 库体系与模块划分

杰理健康 SDK（iOS） 以多个 XCFramework 库的形式组成完整的蓝牙穿戴设备功能集成平台，本文档说明其库体系结构、各模块职责划分、依赖关系与集成方式。

Purpose and Scope

本页面向接入或扩展杰理健康 SDK 的 iOS 开发者，系统性地梳理：

• SDK 的整体库体系：JL_BLEKit、JL_OTALib、JLDialUnit、JLAudioUnitKit、JLBmpConvertKit、JLPackageResKit、AIKIT 等 XCFramework 的职责边界；
• 各库所承载的功能模块（蓝牙连接、健康数据、OTA、表盘、音频、图像转码、资源打包、AI 能力）；
• 模块间的依赖关系、核心调用流程（设备连接 → 协议交互 → 功能调用 → 数据回调）以及集成配置要求。

属于其他目录页的主题（如具体 API 使用、数据模型细节、OTA 流程细节、表盘定制流程等）不在本页展开，本文仅给出模块级定位与入口指引。

Overview

iOS-JL_Health 是珠海市杰理科技股份有限公司为杰理蓝牙穿戴类产品提供的功能集成 SDK，支持智能手表（儿童手表、成人智能手表、健康监测手表）、健康手环（运动手环、睡眠监测手环）以及智能徽章、智能戒指等可穿戴设备。SDK 提供完整的健康数据管理、OTA 升级、表盘定制、音频编解码等功能。

从库体系的角度看，SDK 遵循"一个核心连接库 + 多个专项能力库"的分层设计：

• 核心库 JL_BLEKit.xcframework 负责设备扫描连接、RCSP 协议交互以及健康/运动数据模型，是所有上层功能的前提；
• 专项库 各自封装独立能力域：OTA 升级（JL_OTALib）、表盘（JLDialUnit）、音频编解码（JLAudioUnitKit）、图片转码（JLBmpConvertKit）、资源打包（JLPackageResKit）、AI 云服务（AIKIT）；
• 开发者按需选择并链接所需的 XCFramework，通过"设备连接 → 协议交互 → 功能调用 → 数据回调"的标准流程组合使用。

仓库内同时包含完整的 XCFramework 框架库、iOS 示例工程源码（code/JL_Health/，含 Podfile 依赖管理）及开发文档。

Architecture

模块架构总览

flowchart TD
    subgraph sg_App["宿主 App (iOS)"]
        App["示例工程 / 开发者业务代码"]
    end

    subgraph sg_Core["核心协议层"]
        BLEKit["JL_BLEKit.xcframework<br/>扫描/连接/RCSP 协议交互"]
        HealthModel["JL_BLEKit<br/>健康/运动数据模型、睡眠监测"]
    end

    subgraph sg_Func["专项能力库"]
        OTA["JL_OTALib<br/>固件升级/资源传输"]
        Dial["JLDialUnit<br/>表盘切换与自定义"]
        Audio["JLAudioUnitKit<br/>音频编解码"]
        Bmp["JLBmpConvertKit<br/>图像转码"]
        ResKit["JLPackageResKit<br/>res 资源打包"]
        AI["AIKIT<br/>AI 云服务/表盘"]
    end

    subgraph sg_Dev["蓝牙穿戴设备"]
        Device["杰理 RCSP 设备<br/>AC701N / AC707N / AC695N"]
    end

    App --> BLEKit
    BLEKit --> HealthModel
    App --> OTA
    App --> Dial
    App --> Audio
    App --> Bmp
    App --> ResKit
    App --> AI
    BLEKit -->|"BLE 链路"| Device
    OTA -->|"依赖连接"| BLEKit
    Dial -->|"依赖连接"| BLEKit
    Audio -->|"依赖连接"| BLEKit

架构说明：

• JL_BLEKit 是唯一的设备通信入口，其余所有功能库最终都建立在与设备建立的 BLE/RCSP 连接之上（OTA、表盘、音频、文件传输等均需先完成设备连接与协议握手）。
• 专项库按"能力域"划分，每个库只解决一类问题，避免单一框架体积膨胀，也让开发者可以按需裁剪（例如只做健康监测的应用可以只集成 JL_BLEKit）。
• AIKIT 是相对独立的云服务能力库，其公开头文件体系（AIKIT.h、AIKITDataBuilder、AIKITAudioBuilder、AIKITParameters、AIKITInputData、AIKITDataModel 等）体现了"构建器模式 + 数据模型"的接口风格，内部通过私有头文件（AIKITSpark、ILibrary 等）封装实现。

模块划分总表

模块表来源：README.md

SDK 对外暴露的完整功能接口还包括：消息同步、天气信息、联系人、闹钟管理、文件传输、跌倒/久坐提醒、音乐控制（文件传输、播放控制、ID3 信息显示）、设备查找、支付宝激活与支付、AI 表盘、自定义命令等，详见 README.md 功能清单。

核心模块详解

JL_BLEKit —— 连接与健康数据核心库

JL_BLEKit.xcframework 是 SDK 的基石，承担两类职责：

1. 连接层：设备扫描、连接管理、RCSP（杰理自研通信协议）基础协议交互，是所有上层能力（OTA、表盘、音频、文件传输等）共用的通道；
2. 数据层：运动健康数据模型（心率、血氧、血压、体温、睡眠等）与同步逻辑。

设计意图：把"如何与设备通信"与"设备提供什么能力"解耦。连接层向上层提供稳定的协议交互接口，上层功能库无需关心 BLE 细节；数据层则把设备上报的原始数据解析为结构化模型，供业务层直接消费。集成该库即可完成健康监测类应用的主体功能。

JL_OTALib —— OTA 升级库

JL_OTALib.xcframework 封装固件空中升级的完整流程控制：固件升级、4G 模块 OTA、差分升级以及资源文件传输。升级属于高风险操作，独立成库的好处是：

• 升级状态机、断点续传、版本校验等逻辑与业务代码隔离，降低误用风险；
• 升级流程与健康数据业务互不干扰，可单独发布修复而不影响其他模块。

JLDialUnit —— 表盘管理库

JLDialUnit.xcframework 提供表盘文件浏览、插入、删除、切换以及自定义背景等功能。表盘资源以文件形式下发到设备，因此该库依赖 JL_BLEKit 的文件传输通道，并与 JLBmpConvertKit（表盘图片转码）、JLPackageResKit（表盘 res 资源打包）协同完成"资源准备 → 传输 → 生效"链路。

JLAudioUnitKit —— 音频编解码库

JLAudioUnitKit.xcframework 负责音频数据的编码与解码，支撑音乐文件传输、播放控制与 ID3 信息显示等场景。独立成库便于按需集成——纯健康监测应用无需引入音频相关代码。

JLBmpConvertKit —— 图像转码库

JLBmpConvertKit.xcframework 提供 BMP/JPEG/PNG 图像的编解码转换，典型用途是自定义表盘图像的预处理（把通用图片格式转换为设备可识别的位图格式），是表盘定制链路的图像处理底座。

JLPackageResKit —— 资源打包库

JLPackageResKit.xcframework 负责将音频数据、表盘 res 资源等打包为符合设备协议的资源文件，供 OTA/表盘/音乐等模块传输使用。该库与 JLAudioUnitKit、JLDialUnit 的传输环节配合，实现"资源封装 → 文件传输"的标准化流程。

AIKIT —— AI 云服务能力库

AIKIT.framework 承载 AI 云服务与 AI 表盘能力，位于 code/JL_Health/AIKIT.framework/ 目录，是仓库中唯一直接可见源码头文件的框架。其公开头文件按职责可分为几组：

头文件清单来源：code/JL_Health/AIKIT.framework/Headers/ 与 code/JL_Health/AIKIT.framework/PrivateHeaders/ 目录。具体 API 签名请直接查阅对应头文件原文。

设计意图：AI 能力走云服务链路而非设备链路，因此独立成库；其接口采用"Builder 构造请求 + 参数/输入数据对象 + 数据模型回传"的结构，与业务代码解耦，便于后续替换或扩展底层大模型服务（如 Spark）。

模块依赖关系

flowchart LR
    subgraph sg_AppLayer["应用层"]
        App["宿主 App"]
    end

    subgraph sg_Special["专项能力库"]
        OTA["JL_OTALib"]
        Dial["JLDialUnit"]
        Audio["JLAudioUnitKit"]
        Bmp["JLBmpConvertKit"]
        Res["JLPackageResKit"]
    end

    subgraph sg_Base["基础连接库"]
        BLE["JL_BLEKit"]
    end

    subgraph sg_Cloud["云服务"]
        AI["AIKIT"]
    end

    App --> OTA
    App --> Dial
    App --> Audio
    App --> Bmp
    App --> Res
    App --> BLE
    App --> AI
    OTA -->|"连接/传输"| BLE
    Dial -->|"连接/传输"| BLE
    Audio -->|"连接/传输"| BLE
    Bmp -->|"图片预处理"| Dial
    Res -->|"资源封装"| OTA
    Res -->|"资源封装"| Dial

• 实线依赖：JL_BLEKit 是唯一的基础连接依赖，OTA/表盘/音频都建立在其通道之上；
• 协同依赖：JLBmpConvertKit 为表盘提供图片预处理，JLPackageResKit 为 OTA/表盘提供资源打包；
• 独立能力：AIKIT 依赖云服务，不与设备连接强耦合，可独立集成。

核心调用流程

无论使用哪个功能模块，SDK 的整体调用范式都是统一的四步链路：设备连接 → 协议交互 → 功能调用 → 数据回调（见 README.md 快速集成步骤）。

sequenceDiagram
    participant App as 宿主 App
    participant BLE as JL_BLEKit
    participant Dev as 杰理穿戴设备
    participant Mod as 专项功能库<br/>(OTA/表盘/音频...)

    App->>BLE: 1. 初始化 SDK / 配置权限
    BLE->>BLE: 2. 扫描并连接设备 (RCSP)
    BLE->>Dev: 3. BLE 连接建立
    Dev-->>BLE: 4. 连接成功回调
    BLE-->>App: 5. 设备句柄/状态回调
    App->>Mod: 6. 调用功能接口 (如开始 OTA)
    Mod->>BLE: 7. 通过连接通道下发协议指令
    BLE->>Dev: 8. 协议指令传输
    Dev-->>BLE: 9. 设备响应/数据上报
    BLE-->>Mod: 10. 原始数据解析
    Mod-->>App: 11. 业务数据回调 (进度/结果/健康数据)

各步骤要点：

1. 初始化与权限：集成时需在 Info.plist 配置蓝牙使用权限描述（Privacy - Bluetooth Peripheral/Always Usage Description），否则系统会拒绝 BLE 访问；
2. 连接：JL_BLEKit 负责扫描、配对与 RCSP 协议握手，连接成功后向 App 回调设备状态；
3. 功能调用：App 调用专项库接口，专项库复用 JL_BLEKit 的连接通道下发指令，自身不重复实现通信；
4. 数据回调：设备响应经 JL_BLEKit 解析后，由专项库转换为业务模型（进度、结果或健康/运动数据）回调给 App。

Usage Examples

示例一：克隆仓库

git clone https://github.com/Jieli-Tech/iOS-JL_Health.git
cd iOS-JL_Health

Source: README.md

示例二：集成 SDK 四步法

1. 导入框架：将 libs/ 目录下的 XCFramework 添加到项目中（设置 Embed & Sign）
2. 配置权限：在 Info.plist 中添加蓝牙使用权限描述
3. 初始化 SDK：参考示例工程的初始化代码进行集成
4. 开始开发：使用 SDK 提供的 API 进行健康功能开发

Source: README.md

示例三：按功能选择参考库

蓝牙连接   -> JL_BLEKit.xcframework   设备扫描与连接、基础协议交互
健康数据   -> JL_BLEKit.xcframework   运动健康数据模型、睡眠监测
OTA 升级   -> JL_OTALib.xcframework   固件升级流程控制、资源文件传输
表盘功能   -> JLDialUnit.xcframework  表盘切换与自定义
音频编解码 -> JLAudioUnitKit.xcframework 音频数据编码与解码
图片转码   -> JLBmpConvertKit.xcframework 自定义表盘图像转换
资源打包   -> JLPackageResKit.xcframework 音频数据、表盘 res 资源打包

Source: README.md

示例四：示例工程依赖管理

仓库中的示例工程位于 code/JL_Health/ 目录，通过 Podfile / Podfile.lock 管理依赖，AI 能力库 AIKIT.framework 即存放于此目录下。示例工程源码是理解各模块初始化和调用方式的最佳参考入口。

示例工程路径来源：code/JL_Health/Podfile、code/JL_Health/Podfile.lock、code/JL_Health/AIKIT.framework/。

Configuration Options

SDK 的运行环境与集成配置要求如下（来源：README.md 运行环境）：

集成时的关键点：

• 按需裁剪：并非所有场景都需要全部库。纯健康监测应用只需 JL_BLEKit；需要升级则追加 JL_OTALib；需要表盘定制则追加 JLDialUnit + JLBmpConvertKit + JLPackageResKit。这种模块化设计显著降低了集成包体积与维护成本。
• 权限先行：蓝牙权限描述缺失是集成初期最常见的失败原因，系统会直接拒绝 BLE 授权。
• 版本配套：Podfile.lock 锁定了示例工程的依赖版本，生产环境集成时建议以官方发布的 Tag 版本为准（见 README.md 版本历史）。

Failure Modes, Edge Cases & Concurrency

以下失败模式与边界情况基于 README 与仓库结构推断，具体处理逻辑需查阅对应框架头文件与示例工程：

• 蓝牙权限缺失：Info.plist 未配置 Privacy - Bluetooth Peripheral/Always Usage Description 时，iOS 系统拒绝 BLE 授权，设备扫描/连接必然失败。属于集成期最高频问题。
• 硬件协议不匹配：SDK 依赖杰理 RCSP 协议，非杰理穿戴设备或旧协议固件无法建立完整交互；芯片型号（AC701N/AC707N/AC695N 等）需与 SDK 版本匹配。
• 连接中断与并发：多模块（OTA、表盘、音频）共用 JL_BLEKit 连接通道，若并发下发指令可能产生协议竞争。设计上应通过串行队列/任务状态机管理指令发送，避免同时进行升级与文件传输等互斥操作。
• OTA 中断：升级过程断连会导致设备进入异常状态，JL_OTALib 独立封装状态机与断点处理，业务层应监听升级回调并在失败时引导重连重试。
• 大文件传输：音乐/表盘等大文件传输耗时较长，期间蓝牙链路稳定性直接影响成功率，建议在传输期间避免切换后台或打断连接。
• AI 云服务网络依赖：AIKIT 走云服务链路，弱网/离线场景下 AI 功能不可用，业务层需处理网络错误（AIKITError.h 定义错误信息）并提供降级策略。

Performance & Operational Considerations

• 按需集成控制体积：每个 XCFramework 独立打包，业务只链接所需库，避免无谓的内存占用与启动加载开销。
• 连接通道复用：专项库复用 JL_BLEKit 的通道而非各自建立连接，减少 BLE 连接数，降低功耗与协议开销——这对电池供电的穿戴设备场景尤为重要。
• 资源预处理：表盘图片先经 JLBmpConvertKit 转码、再经 JLPackageResKit 打包，可显著降低传输数据量，缩短传输时间并减少失败概率。
• 升级安全：OTA 属于高功耗、高风险的长时间操作，建议在电量充足、设备在旁的条件下进行，并展示明确的进度与失败重试路径。

Extension Points

• 自定义命令：SDK 明确支持客户拓展功能（"自定义命令"是官方功能清单之一），业务方可基于 JL_BLEKit 的协议交互能力扩展私有指令。
• AIKIT 库抽象：PrivateHeaders/ILibrary.h 定义库抽象接口，AIKITDataBuilder/AIKITAudioBuilder 等构建器允许构造自定义请求数据，为扩展 AI 能力（如新增模型/对话场景）预留了接口空间。
• 示例工程作为模板：code/JL_Health/ 示例工程展示了完整的模块组合与初始化方式，可作为新业务集成的起点模板。

Tests

仓库当前未在源码目录中发现独立的单元测试工程；示例工程（code/JL_Health/）本身即为各模块的集成验证载体。功能验证建议以真机（杰理穿戴设备）联调为主：BLE、RCSP 协议交互与设备端行为无法在模拟器中完整复现。具体测试覆盖情况以官方后续发布的测试工程为准（实现细节未在源码中体现）。

Related Links

• README.md（中文主文档）
• README_EN.md（英文文档）
• code/JL_Health/Podfile（示例工程依赖）
• code/JL_Health/AIKIT.framework/Headers/AIKIT.h（AIKIT 统一入口头文件）
• code/JL_Health/AIKIT.framework/PrivateHeaders/ILibrary.h（库抽象接口）
• 官方文档中心：https://doc.zh-jieli.com/Apps/iOS/health/zh-cn/master/index.html
• 相关目录页（如存在）：设备连接与协议交互、健康数据模型、OTA 升级流程、表盘定制、AI 表盘服务等页面分别展开对应模块的详细实现。