仓库概览

iOS-JL_Health 是珠海市杰理科技股份有限公司为杰理蓝牙穿戴类产品（智能手表、健康手环等）提供的 iOS 功能集成 SDK 仓库。本仓库包含完整的 XCFramework 二进制库、iOS 示例工程源码及开发文档，覆盖 OTA 升级、表盘管理、健康数据同步、音频编解码等核心能力。

Purpose and Scope

本页面从整体视角介绍 iOS-JL_Health 仓库的构成与定位，帮助开发者快速建立对仓库的全局认知，包括：

• 仓库顶层目录结构（libs/、code/、docs/）及各自职责
• 核心 SDK 库（XCFramework）的功能划分与依赖关系
• 示例工程 code/JL_Health/ 的 MVVM 架构与模块组织
• 从零开始的 SDK 集成流程、配置要求与常见注意事项

本页面不深入单个业务功能（如 OTA 升级流程、表盘下载、音频编解码）的实现细节，这些内容由各自独立的专题页面覆盖；本页面仅提供功能地图与入口指引，并在"相关链接"中给出跳转方向。

概述

iOS-JL_Health 是一个典型的"二进制 SDK + 示例应用"形态的仓库。SDK 本体以 XCFramework 格式预编译交付，示例应用则演示了如何调用这些库完成真实业务。这种交付方式的设计意图在于：屏蔽底层 BLE 协议与编解码算法复杂度，让集成方只需关注业务 API 调用与数据回调处理。

仓库支持的硬件平台为支持杰理 RCSP 协议的芯片（如 AC701N、AC707N、AC695N 等），最低系统要求为 iOS 10.0+，支持 Objective-C 与 Swift 两种语言调用。

核心功能地图

功能与库的对应关系整理自 README.md 的功能模块表。

架构

仓库总体构成

flowchart TD
    subgraph sg_Root["iOS-JL_Health 仓库根目录"]
        subgraph sg_Libs["libs/ — 核心 SDK 二进制库"]
            BLE["JL_BLEKit.xcframework<br/>主业务库（基础协议）"]
            OTA["JL_OTALib.xcframework<br/>OTA 升级业务库"]
            DIAL["JLDialUnit.xcframework<br/>表盘相关库"]
            AUDIO["JLAudioUnitKit.xcframework<br/>音频编解码库"]
            BMP["JLBmpConvertKit.xcframework<br/>图片转码库"]
            RES["JLPackageResKit.xcframework<br/>资源打包库"]
            ADV["JL_AdvParse.xcframework<br/>广播包解析库"]
            HASH["JL_HashPair.xcframework<br/>设备认证库"]
            LOG["JLLogHelper.xcframework<br/>日志助手库"]
        end

        subgraph sg_Code["code/ — 示例工程源码"]
            DEMO["JL_Health<br/>宜动健康完整示例"]
            TEST["SDKTestHelper<br/>简单功能测试"]
            AUDIODEMO["JLAudioUnitKitDemo<br/>音频编解码示例"]
            ALIDEMO["HealthAide_ALi_IOT<br/>支付宝集成示例"]
            ENCDEMO["杰理iOS音频编解码V1.1.0<br/>录音数据编解码示例"]
        end

        subgraph sg_Docs["docs/ — 文档资源"]
            PDF["Jieli_Health_SDK_iOS_Releases.pdf<br/>版本发布记录"]
            URL1["杰理OTA升级(iOS)开发说明.url"]
            URL2["杰理健康SDK开发说明.url"]
            URL3["自定义蓝牙接入方式.url"]
        end
    end

    DEMO --> BLE
    DEMO --> DIAL
    DEMO --> OTA
    DEMO --> AUDIO
    DEMO --> BMP
    DEMO --> RES
    ALIDEMO --> BLE
    ENCDEMO --> AUDIO
    AUDIODEMO --> AUDIO
    BLE --> ADV
    BLE --> HASH
    BLE --> LOG

架构说明： 仓库遵循"库–示例–文档"三段式结构。libs/ 中的 JL_BLEKit 是主业务库，承担蓝牙协议交互与健康数据模型；其余库在功能上依赖它或与其协同（如 JLDialUnit 依赖 JL_BLEKit 的协议通道，JL_AdvParse 与 JL_HashPair 是 JL_BLEKit 的支撑库）。code/ 下的示例工程演示了不同业务场景下如何组合这些库，其中 JL_Health（宜动健康）是最完整的参考实现。

示例工程分层架构

code/JL_Health/JieliJianKang 示例应用采用 MVVM + RxSwift 分层：

flowchart TD
    subgraph sg_View["View 层"]
        VC["ViewControllers<br/>（如 DialMarketViewController）"]
        V["Views<br/>（如 AgreementView）"]
    end

    subgraph sg_ViewModel["ViewModel 层"]
        VM["ViewModels<br/>（如 DialVcViewModel / DialBaseViewModel）"]
    end

    subgraph sg_Service["服务层"]
        HTTP["httpClient<br/>（如 DialMarketHttp）"]
        UTIL["Utilities<br/>（如 JLAudioToolbox / AutoProductIcon）"]
    end

    subgraph sg_Model["Model 层"]
        M["Model 数据模型<br/>（如 ProductInfoModel）"]
    end

    subgraph sg_SDK["SDK 层"]
        SDK["JL_BLEKit / JLDialUnit 等<br/>XCFramework"]
    end

    VC --> VM
    V --> VC
    VM --> HTTP
    VM --> UTIL
    HTTP --> M
    VM --> SDK
    HTTP --> SDK

设计意图： 视图控制器（BaseViewController）只负责页面生命周期与 UI 装配，业务逻辑收敛到 ViewModel，网络请求统一封装在 httpClient 单例中（如 DialMarketHttp.shared），底层设备能力通过 SDK 库暴露。这种分层让示例代码既贴近真实产品，又便于集成方对照理解"哪一层对应自己 App 中的哪个职责"。

分层依据来自 code/JL_Health/JieliJianKang 下的实际目录（ViewControllers / ViewModels / Views / httpClient / Utilities / Model）。

核心 SDK 库详解

必选库（基础运行依赖）

可选库（按需引入）

必选/可选划分依据 README.md 配置说明。

库之间的依赖关系

JL_BLEKit 是整个 SDK 的中枢：它向上为业务库（OTA、表盘、音频）提供统一的设备连接与协议收发通道，向下依赖 JL_AdvParse（广播解析）与 JL_HashPair（设备认证）完成设备发现与安全握手。JLLogHelper 为所有库提供统一的日志出口。理解这条依赖链对排查问题很有帮助——例如 OTA 失败时，应先确认 JL_BLEKit 层的连接状态与 JLLogHelper 输出的协议日志，再定位 JL_OTALib 的升级流程。

示例工程结构

code/ 目录总览

宜动健康（JL_Health）模块组织

code/JL_Health/JieliJianKang 内部按职责划分目录：

• ViewControllers/ — 页面控制器，如 DialMarketViewController（表盘市场）、DialPayViewController（支付）、ICPViewController（WebView 容器）、BaseViewController（公共基类）
• ViewModels/DialViewModel/ — 表盘业务视图模型，如 DialBaseViewModel、DialFreeViewModel（免费表盘）、DialPayViewModel（付费表盘）、DialHistoryViewModel（历史表盘）
• Views/ — 可复用视图组件，如 AgreementView（协议弹窗）
• httpClient/ — 网络层，如 DialMarketHttp（表盘市场接口单例）、Model/ProductInfoModel（产品信息模型）
• Utilities/ — 工具库，如 JLAudioToolbox/AudioManager（音频管理）、AutoProductIcon（产品图标自动匹配）
• UnitTester/ — 单元测试辅助，如 DataTester

基础控制器设计

BaseViewController 是所有页面的公共基类，统一了导航栏、背景色、前后台切换监听与返回手势控制：

class BaseViewController: UIViewController {
    open var navigationView = NaviView()
    open var disposeBag = DisposeBag()
    open var canNotPushBack: Bool = false

    override func viewDidLoad() {
        super.viewDidLoad()
        view.addSubview(navigationView)
        view.backgroundColor = .eHex("#F6F7F8")
        let window = UIApplication.shared.windows.first
        navigationView.snp.makeConstraints { make in
            make.top.equalTo(self.view.snp.top).inset(0)
            make.height.equalTo(44 + (window?.safeAreaInsets.top ?? 20))
            make.left.right.equalTo(view).inset(0)
        }

        initData()
        initUI()
    }

来源：BaseViewController.swift

设计意图： 基类通过 initData() / initUI() 两个 open 方法约定子类的初始化顺序，并用 RxSwift 的 disposeBag 统一管理订阅生命周期；canNotPushBack 标志用于在特定页面（如支付流程）禁用边缘返回手势，避免流程中断。

核心集成流程

SDK 集成步骤

sequenceDiagram
    participant Dev as 开发者
    participant Proj as iOS 工程
    participant SDK as JL SDK（XCFramework）
    participant Device as 杰理穿戴设备

    Dev->>Proj: 1. 导入 libs/ 下 XCFramework 并设置 Embed & Sign
    Dev->>Proj: 2. Info.plist 配置蓝牙权限描述
    Dev->>Proj: 3. 按需引入可选库（OTA/表盘/音频等）
    Proj->>SDK: 4. 初始化 SDK / 开始扫描
    SDK->>Device: 5. BLE 广播包扫描（JL_AdvParse 解析）
    Device-->>SDK: 6. 广播响应
    SDK->>Device: 7. 连接并完成认证（JL_HashPair）
    Device-->>SDK: 8. RCSP 协议通道建立
    Proj->>SDK: 9. 调用业务 API（健康/表盘/OTA）
    SDK->>Device: 10. 协议指令下发
    Device-->>SDK: 11. 数据回调
    SDK-->>Proj: 12. 业务回调 / JLLogHelper 日志输出

流程要点： 设备连接是全部业务的前置条件。广播解析（JL_AdvParse）决定设备能否被发现，认证（JL_HashPair）决定连接是否合法，协议通道（JL_BLEKit）决定后续指令能否正确收发。示例工程中 httpClient 层的接口调用与 SDK 的设备回调相互配合，构成"请求–响应"闭环。

示例网络调用流程

DialMarketHttp 展示了示例应用中网络层与 SDK 日志系统的配合方式。以查询表盘产品信息为例：

/// 根据pid、vid查询表盘产品信息
/// - Parameters:
///   - pid: pid
///   - vid: vid
///   - completion: 回调
func getProductInfo(_ pid:String,_ vid:String, completion:@escaping (_ product:ProductInfoModel?)->()) {
    let url = baseUrl + "/health/v1/api/watch/shop/onebypidvid?pid=" + pid + "&vid=" + vid
    let request = NSMutableURLRequest(url: URL(string: url)!,cachePolicy: .useProtocolCachePolicy,timeoutInterval: 10)
    request.httpMethod = "POST"
    request.allHTTPHeaderFields = [
        "jwt-token":User_Http.shareInstance().token,
        "Content-Type": "application/json",
    ]
    let dataTask = makeTask(request){ (data, err) in
        if let data = data {
            if let dict = try? JSONSerialization.jsonObject(with: data, options: .mutableContainers) as? [String:Any] {
                if let code = dict["code"] as? Int,code == 0,let data = dict["data"] as? [String:Any] {
                    let product = ProductInfoModel(data)
                    completion(product)
                }else{
                    JLLogManager.logLevel(.DEBUG, content: "url:\\(url)\\ngetProductInfo error: \\(dict)")
                    completion(nil)
                }
            }
        }
    }
    dataTask.resume()
}

来源：DialMarketHttp.swift

要点解读：

• DialMarketHttp 采用单例（static let shared）设计，统一管理 URLSession 与 URLCache（10 MB 内存 / 100 MB 磁盘缓存），避免多个页面各自创建网络栈。
• 请求通过 jwt-token 头携带登录态，业务码约定 code == 0 为成功。
• 失败路径统一通过 JLLogManager.logLevel(.DEBUG, content:) 输出日志——这正是 JLLogHelper.xcframework 在示例工程中的典型用法，便于联调时定位网络问题。
• 网络层与设备功能解耦：产品信息来自云端 HTTP 接口，而表盘文件本身则通过 SDK 的蓝牙通道传输到设备。

初始化代码结构

示例工程的网络层同样展示了初始化阶段如何配置基础地址与用户态：

配置选项

工程级配置

权限配置（Info.plist）

集成时必须添加蓝牙权限描述，否则系统不会弹出授权弹窗，导致扫描失败：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要使用蓝牙功能连接杰理设备</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要作为蓝牙外设连接杰理设备</string>

来源：README.md 权限配置

运行时配置

故障模式与注意事项

• 未导入必选库：缺少 JL_AdvParse / JL_BLEKit / JL_HashPair / JLLogHelper 时，设备扫描、连接、认证、日志全部不可用。这是最常见的集成错误，应首先检查 libs/ 依赖是否完整。
• 缺少蓝牙权限：Info.plist 未配置 NSBluetoothAlwaysUsageDescription 时，系统不会弹出授权，扫描结果为空。注意 iOS 10+ 还需 NSBluetoothPeripheralUsageDescription。
• 功能与库不匹配：使用 OTA / 表盘 / 音频功能却未引入对应可选库，会导致运行期符号缺失。功能启用前先核对"功能模块 → 参考库"对照表。
• 网络与设备通道混淆：表盘产品信息走 HTTP（DialMarketHttp），表盘文件传输走蓝牙协议通道。排查问题时需分清数据路径，结合 JLLogManager 日志定位。
• 版本兼容：SDK 版本迭代较快（如 V1.14.0(Beta) 于 2026/03 发布），升级库时务必核对 docs/ 下的版本发布记录（Jieli_Health_SDK_iOS_Releases.pdf）中的兼容性说明。

扩展点

• 自定义命令：SDK 支持客户自定义命令扩展，可在基础协议之上拓展私有功能（见 README 功能列表）。
• 自定义表盘：通过 JLBmpConvertKit 图像转码 + JLDialUnit 表盘管理组合，支持兼容 AC707N 的自定义表盘图像转换。
• AI 表盘 / AI 云服务：V1.9.0 起引入 AI 云服务、V1.10.0 起引入 AI 表盘，为上层产品提供差异化能力。
• 示例工程扩展：code/ 下多个示例覆盖了音频、支付宝等独立场景，可作为新功能集成的模板。

性能与运维提示

• DialMarketHttp 使用 URLCache（10 MB 内存 / 100 MB 磁盘）缓存网络响应，表盘市场图片等资源可复用，减少重复流量；clearCache() 提供缓存清理入口。
• 大文件传输（音乐、表盘资源）历史上出现过分包与超时问题（V1.8.0 修复），涉及大文件场景时应参考对应版本的发布说明与 OTA/资源传输开发文档。
• 调试时利用 Xcode Console 查看 JLLogHelper 输出的蓝牙连接状态与数据交互日志，可显著缩短问题定位时间。

相关链接

• README.md（仓库总览与快速开始）
• README_EN.md（英文版说明）
• LICENSE（Apache 2.0 开源协议）
• BaseViewController.swift（示例基类控制器）
• DialMarketHttp.swift（表盘市场网络层）
• 在线文档中心：https://doc.zh-jieli.com/Apps/iOS/health/zh-cn/master/index.html