工程结构与目录导航

iOS-JL_Health 是珠海市杰理科技股份有限公司为杰理蓝牙穿戴类产品提供的 iOS 功能集成 SDK 仓库。本页面向首次接触该仓库的开发者，系统介绍仓库顶层目录划分、各目录职责、SDK 功能模块与库的对应关系，以及如何在庞大的 SDK 体系中快速定位所需代码、文档与配置。

Purpose and Scope

本页讲解 iOS-JL_Health 仓库本身的组织方式：顶层目录（code/、libs/、docs/）各自的职责、SDK 功能模块与 XCFramework 库的映射关系、集成时的库依赖与权限配置，以及按"功能 → 库 → 示例 → 文档"的导航路径。

以下主题属于其他目录页面的范围，本页仅提供入口指引：

• SDK 具体 API 的使用（蓝牙连接、健康数据、OTA 升级、表盘管理等）：请参考各功能对应的开发文档与示例工程（如"杰理健康SDK开发说明"在线文档）。
• 版本发布记录：docs/Jieli_Health_SDK_iOS_Release.pdf 与 README「版本历史」章节。
• 资源打包库的使用：docs/JLPackageResKit.md 是仓库内唯一独立的 Markdown 开发文档，属于资源打包主题。

概述

iOS-JL_Health SDK 面向杰理蓝牙穿戴类产品（智能手表、健康手环、智能徽章、智能戒指等），提供完整的健康数据管理、OTA 升级、表盘定制、音频编解码等功能。仓库本身由三部分构成：

这种"示例 + 二进制库 + 文档"三位一体的仓库布局，是 SDK 类项目的典型组织方式：二进制库按功能拆分（JL_BLEKit、JL_OTALib、JLDialUnit……），使集成方可以按需导入，避免引入不需要的功能体积；示例工程则作为每个库的"活文档"，弥补二进制库无法直接阅读源码的不足。

架构

仓库顶层结构

flowchart TD
    subgraph sg_Repo["iOS-JL_Health 仓库根目录"]
        README["README.md<br/>中/英文说明与工程结构"]
        LICENSE["LICENSE<br/>Apache 2.0 开源协议"]
        subgraph sg_Code["code/ 示例程序源码"]
            JL_Health["JL_Health<br/>宜动健康完整示例"]
            SDKTest["SDKTestHelper<br/>简单功能测试"]
            AudioDemo["JLAudioUnitKitDemo<br/>音频编解码示例"]
            ALI["HealthAide_ALi_IOT<br/>阿里/支付宝集成示例"]
            AudioV1["杰理iOS音频编解码V1.1.0<br/>手表录音数据编解码"]
        end
        subgraph sg_Libs["libs/ 核心 SDK 库"]
            Adv["JL_AdvParse"]
            BLE["JL_BLEKit"]
            Hash["JL_HashPair"]
            Log["JLLogHelper"]
            OTA["JL_OTALib"]
            Audio["JLAudioUnitKit"]
            Bmp["JLBmpConvertKit"]
            Dial["JLDialUnit"]
            Pkg["JLPackageResKit"]
        end
        subgraph sg_Docs["docs/ 文档资源"]
            Release["Jieli_Health_SDK_iOS_Release.pdf"]
            PkgDoc["JLPackageResKit.md"]
            Links["在线文档 .url 链接"]
        end
    end

注意：上图 libs/ 与 code/ 下的部分子目录以 README.md 的工程结构章节 为准。经仓库文件列表验证，当前快照中 code/ 实际只包含 HealthAide_ALi_IOT_V0.1.2(iOS).zip，libs/（XCFramework 二进制库）未出现在文件索引中，推测通过 Git LFS 或发布渠道单独分发，集成时请以实际下载产物为准。

SDK 功能模块与库的依赖关系

flowchart LR
    subgraph sg_App["集成方 iOS App"]
        App["App 工程<br/>Embed & Sign 导入"]
    end
    subgraph sg_Required["必需导入的库"]
        Adv["JL_AdvParse<br/>广播包解析"]
        BLE["JL_BLEKit<br/>主业务库"]
        Hash["JL_HashPair<br/>设备认证"]
        Log["JLLogHelper<br/>日志助手"]
    end
    subgraph sg_Optional["按需导入的可选库"]
        OTA["JL_OTALib<br/>OTA 升级"]
        Dial["JLDialUnit<br/>表盘管理"]
        Audio["JLAudioUnitKit<br/>音频编解码"]
        Bmp["JLBmpConvertKit<br/>图片转码"]
        Pkg["JLPackageResKit<br/>资源打包"]
    end
    App --> Adv
    App --> BLE
    App --> Hash
    App --> Log
    App -.-> OTA
    App -.-> Dial
    App -.-> Audio
    App -.-> Bmp
    App -.-> Pkg

该依赖关系体现了 SDK 的分层设计意图：JL_BLEKit 承担最核心的蓝牙连接与基础协议交互，任何功能都离不开它，因此是必选；而 OTA、表盘、音频、图片转码、资源打包等能力被拆分为独立库，只有真正使用该功能的集成方才需导入，从而控制 App 体积并降低功能间的耦合。从 V1.8.0 版本起，官方明确"对 SDK 库进行功能模块分离"，这一拆分正是仓库结构演进的直接结果。

顶层目录结构详解

README 的「工程结构」章节给出了完整的目录树，是理解仓库布局的第一手资料：

iOS-JL_Health/
├── code/                           # 示例程序源码
│   ├── JL_Health/                  #   宜动健康源码
│   ├── SDKTestHelper/              #   简单功能源码
│   ├── JLAudioUnitKitDemo/         #   音频编解码业务库示例
│   ├── HealthAide_ALi_IOT_V0.1.2(iOS)/ #   阿里支付宝集成示例
│   └── 杰理iOS音频编解码V1.1.0/      #   手表录音数据编解码示例
├── libs/                           # 核心 SDK 库 (XCFramework 格式)
│   ├── JL_AdvParse.xcframework     #   广播包解析库
│   ├── JL_BLEKit.xcframework       #   主业务库（基础协议相关）
│   ├── JL_HashPair.xcframework     #   设备认证库
│   ├── JL_OTALib.xcframework       #   OTA 升级业务库
│   ├── JLAudioUnitKit.xcframework  #   音频编解码业务库
│   ├── JLBmpConvertKit.xcframework #   图片转码业务库
│   ├── JLDialUnit.xcframework      #   表盘相关库
│   ├── JLLogHelper.xcframework     #   日志助手库
│   └── JLPackageResKit.xcframework #   健康功能业务库
└── docs/                           # 文档资源
    ├── Jieli_Health_SDK_iOS_Releases.pdf #   版本发布记录
    ├── 杰理OTA升级(iOS)开发说明.url      #   在线文档：OTA开发说明
    ├── 杰理健康SDK开发说明.url           #   在线文档：开发说明
    └── 自定义蓝牙接入方式.url             #   在线文档：接入方式介绍

Source: README.md

code/ — 示例程序源码

示例工程是 SDK 的"活文档"，每个示例对应一类典型集成场景：

实际仓库快照中 code/ 仅保留了 HealthAide_ALi_IOT_V0.1.2(iOS).zip 压缩包，其余示例源码目录可能未随当前快照分发；如需其他示例，请通过发布渠道获取完整工程。

libs/ — 核心 SDK 库（XCFramework）

所有库均为 Xcode 12+ 主推的 XCFramework 格式，可同时包含真机与模拟器架构，集成时直接拖入工程并设置 Embed & Sign 即可。按依赖关系分为两层：

• 必需库：JL_AdvParse（广播包解析）、JL_BLEKit（主业务库）、JL_HashPair（设备认证）、JLLogHelper（日志助手）。
• 可选库：JL_OTALib、JLAudioUnitKit、JLBmpConvertKit、JLDialUnit、JLPackageResKit。

当前文件索引中未检索到 libs/ 目录内容，此处的库清单与职责描述以 README 文档为准；集成时请从发布渠道获取实际的 .xcframework 产物。

docs/ — 文档资源

经文件列表验证，docs/ 目录实际包含：

.url 文件是 Windows Internet 快捷方式格式，双击可在浏览器中打开对应在线文档页；在线文档中心为 https://doc.zh-jieli.com/。

导航指南：按功能定位代码与文档

面对功能众多的 SDK，推荐的导航路径是 功能需求 → 功能库 → 对应示例 → 开发文档。README 提供了功能模块与参考库的映射表：

Source: README.md

使用该表的要点：

1. 先查功能、再选库：蓝牙连接与健康数据都落在 JL_BLEKit，说明它们是基础能力；OTA、表盘等是上层能力，依赖基础库工作。
2. 示例与库一一对应：如音频功能可对照 code/JLAudioUnitKitDemo/ 与 docs/杰理iOS音频编码库开发说明.pdf；资源打包可对照 docs/JLPackageResKit.md。
3. 版本影响：V1.12.0 起图像转换工具被分离为独立模块库（JLBmpConvertKit），早期资料中的集成方式可能已过时，务必核对 SDK 版本。

核心集成流程

从仓库结构到可运行的 App，集成方需要经过"导入库 → 配置权限 → 初始化 → 连接 → 功能调用 → 回调"的完整链路：

sequenceDiagram
    participant Dev as 开发者
    participant App as iOS 工程
    participant SDK as JL_BLEKit SDK
    participant Dev2 as 杰理设备

    Dev->>App: 导入必需 XCFramework 并 Embed & Sign
    Dev->>App: Info.plist 配置蓝牙权限描述
    Dev->>App: 参考示例工程初始化 SDK
    App->>SDK: 初始化并扫描设备
    App->>SDK: 发起连接
    SDK->>Dev2: BLE 连接 (RCSP 协议)
    Dev2-->>SDK: 连接建立
    SDK-->>App: 连接状态回调
    App->>SDK: 功能调用（健康数据/OTA/表盘等）
    SDK->>Dev2: 协议交互
    Dev2-->>SDK: 数据返回
    SDK-->>App: 功能数据回调

Source: README.md

流程设计要点：

• Embed & Sign 是硬性要求：XCFramework 需嵌入目标并签名，否则真机运行时会因动态库未签名而崩溃。
• 权限声明前置：iOS 10+ 要求 App 首次访问蓝牙前必须在 Info.plist 声明用途，未声明会直接导致蓝牙不可用。
• 回调驱动：SDK 以回调（Block/Delegate）方式返回连接状态与数据，业务层需在回调中更新 UI 与状态机，避免在主线程做耗时操作。

配置说明

库依赖配置

Source: README.md

权限配置

在 Info.plist 中添加蓝牙权限描述（示例文案可自定义，但键名必须精确匹配）：

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

Source: README.md

其中 NSBluetoothAlwaysUsageDescription 对应 iOS 13+ 的"始终允许"蓝牙权限模型，NSBluetoothPeripheralUsageDescription 是兼容旧系统的声明。两者都配置可覆盖 iOS 10 ~ 最新系统的蓝牙权限弹窗场景。

运行环境

Source: README.md

使用示例

克隆仓库

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

Source: README.md

按文档目录树定位资源

README「工程结构」章节本身就是最常用的导航工具：需要示例看 code/，需要二进制库看 libs/，需要版本记录与开发说明看 docs/。结合功能映射表（见"导航指南"一节）即可在两分钟内定位到目标文件。

读取资源打包开发文档

docs/JLPackageResKit.md 是仓库中唯一的独立 Markdown 开发文档，涉及音频数据与表盘 res 资源打包，使用 JLPackageResKit.xcframework 时请直接阅读该文件：JLPackageResKit.md。

版本历史与结构演进

README「版本历史」章节记录了 SDK 的结构演进脉络，理解它有助于解释当前目录布局的形成原因：

Source: README.md

设计意图：V1.8.0 的"功能模块分离"是仓库结构的分水岭——在此之前 SDK 可能以单体库形式分发，之后逐步演变为"必需库 + 可选库"的多 XCFramework 布局。V1.12.0 的图像转换分离则是这一策略的延续。因此，查阅旧版本资料时需注意库名与功能归属可能已发生变化；详细的迭代记录请见 docs/ 下的发布记录 PDF。

注意事项、边界情况与故障排查

• libs/ 目录缺失：当前仓库快照的文件索引中未包含 libs/（XCFramework 产物），这是最常见的困惑点。请通过 SDK 发布渠道（Tag 发布页、文档中心）获取二进制库，而不是期望直接从本仓库检出。
• 示例工程以 zip 形式分发：code/ 下实际可见的是 HealthAide_ALi_IOT_V0.1.2(iOS).zip，其他示例目录（JL_Health/ 等）未在当前快照中，需从完整发布包获取。
• .url 文件依赖网络：docs/ 下的 .url 快捷方式指向在线文档，离线环境下无法打开；PDF 与 .md 文件可直接离线阅读。
• 权限缺失导致连接失败：未配置 NSBluetoothAlwaysUsageDescription 时，iOS 会拒绝弹出权限框或直接返回 CBManagerState.unauthorized，排查蓝牙问题时优先检查 Info.plist。
• 版本不匹配：示例工程与 SDK 库版本不一致可能导致 API 找不到或行为差异，集成时尽量使用同一发布 Tag 下的示例与库。
• 日志定位：JLLogHelper.xcframework 提供日志管理能力，可通过相关接口控制日志输出与存储；真机调试时结合 Xcode Console 观察蓝牙连接状态与数据交互日志（见 README「调试技巧」章节）。

扩展点

SDK 为集成方预留了以下扩展空间：

• 自定义命令：SDK 支持客户拓展功能（自定义命令模块），集成方可在标准 API 之外与设备进行私有协议交互。
• 按库裁剪：可选库机制允许集成方只保留所需功能，自定义"最小集成集"；当业务扩展需要新能力时，按需追加导入对应 XCFramework 即可，无需改动既有代码。
• 示例工程二次开发：code/JL_Health/（宜动健康）作为完整应用参考，可直接在其基础上改造为自有产品。

相关链接

• README.md（仓库总览与工程结构）
• README_EN.md（英文版说明）
• docs/JLPackageResKit.md（资源打包开发文档）
• docs/Jieli_Health_SDK_iOS_Release.pdf（版本发布记录）
• LICENSE（Apache 2.0）
• 在线文档中心：https://doc.zh-jieli.com/
• 问题反馈：https://github.com/Jieli-Tech/iOS-JL_Health/issues