SDKTestHelper 测试工具

SDKTestHelper 是杰理科技 iOS 蓝牙 SDK（JL_SDK）发布包中随附的示例测试工程，用于演示、验证和调试 JL_BLEKit、JL_AdvParse、JL_OTALib 等核心 SDK 框架在 iOS 平台上的集成方式与核心功能。

Purpose and Scope

本页面介绍 SDKTestHelper 在整个 JL_SDK 发布包中的定位、工程结构、依赖关系、构建要求与使用方式，内容包括：

SDKTestHelper 与发布包其他目录（Libs/、Docs/）的关系
示例工程的组成（Podfile、Pods 依赖、R.swift 生成资源）
如何将该示例工程作为 SDK 集成与功能验证的测试工具使用
工程对 Xcode 版本与最低系统版本的要求

以下内容属于同目录下的其他主题，不在本页面展开：SDK 各框架（JL_BLEKit、JL_AdvParse、JL_OTALib）的 API 细节、SDK 的接入与部署流程，请参见对应的框架文档与 Docs/ 下的技术文档。

Overview

SDKTestHelper 是"测试工具"性质的工程，而不是 SDK 本体。它的价值在于：

集成示范：工程通过 CocoaPods 引入 SDK 依赖，展示了标准的框架接入方式；
功能验证：开发者可以在真机上运行该工程，借助它对蓝牙扫描、连接、解析、OTA 升级等能力做冒烟测试；
调试基线：当 SDK 行为异常时，可以用该工程排除业务代码干扰，快速定位是 SDK 问题还是宿主 App 问题。

根据发布包说明（README.md），发布包由三部分组成：

Code/：核心代码，其中 SDKTestHelper 是示例工程；
Libs/：预编译框架（JL_AdvParse.xcframework、JL_BLEKit.xcframework、JL_OTALib.xcframework 等）；
Docs/：开发文档（APP说明书.md、翻译传输功能说明.md）。

工程使用 Objective-C 生态常见的 CocoaPods 管理依赖，并采用 R.swift 生成类型安全的资源访问代码（R.generated.swift），属于典型的 iOS 示例工程模板。

Architecture

下图展示 SDKTestHelper 在 JL_SDK 发布包中的架构位置及其与各框架、文档的依赖关系：

flowchart TD
    subgraph sg_Release["JL_SDK 发布包 Release/"]
        subgraph sg_Code["Code/ 核心代码"]
            SDKTestHelper["SDKTestHelper 示例工程"]
            Podfile["Podfile / Podfile.lock"]
            RGen["R.generated.swift (R.swift 生成)"]
            Pods["Pods/ 第三方依赖"]
        end

        subgraph sg_Libs["Libs/ 预编译框架"]
            BLEKit["JL_BLEKit.xcframework"]
            AdvParse["JL_AdvParse.xcframework"]
            OTALib["JL_OTALib.xcframework"]
            Others["...其他框架"]
        end

        subgraph sg_Docs["Docs/ 开发文档"]
            AppDoc["APP说明书.md"]
            TransDoc["翻译传输功能说明.md"]
        end
    end

    SDKTestHelper -->|"CocoaPods 集成"| Podfile
    SDKTestHelper -->|"link & embed"| BLEKit
    SDKTestHelper -->|"link & embed"| AdvParse
    SDKTestHelper -->|"link & embed"| OTALib
    SDKTestHelper -->|"link & embed"| Others
    SDKTestHelper --> RGen
    SDKTestHelper --> Pods
    BLEKit -.->|"API 说明"| AppDoc
    OTALib -.->|"升级说明"| TransDoc

架构解读：

SDKTestHelper 是发布包中唯一随附的 Xcode 工程，是开发者验证 SDK 能力的入口；
它通过 Podfile（CocoaPods）声明依赖，生成 Pods/ 目录；同时直接链接 Libs/ 下的预编译 xcframework，覆盖"框架 + 源码依赖"两种常见集成形态；
R.generated.swift 是 R.swift 工具生成的资源索引，工程内用它访问图片、字符串等资源，避免硬编码字符串；
Docs/ 与工程无编译期依赖，但提供 API 使用说明，是配合该测试工具查阅的手册。

工程运行环境要求（来自发布包说明）：Xcode 14.3+，最低支持 iOS 10.0。

工程目录结构

SDKTestHelper 工程位于发布包的 Code/SDKTestHelper 目录下，仓库中的实际布局如下（来自发布包说明文档的目录结构）：

Release/
├── Code/             # 核心代码
│   └── SDKTestHelper  # 示例工程
├── Libs/             # 预编译框架
│   ├── JL_AdvParse.xcframework
│   ├── JL_BLEKit.xcframework
│   ├── JL_OTALib.xcframework
│   └── ...其他框架
└── Docs/             # 开发文档
    ├── APP说明书.md
    └── 翻译传输功能说明.md

Source: README.md

仓库内该工程实际包含的关键文件（通过文件检索确认）：

路径	作用
`code/SDKTestHelper/README.md`	发布包总说明（本页信息的权威来源）
`code/SDKTestHelper/Code/SDKTestHelper/Podfile`	CocoaPods 依赖声明
`code/SDKTestHelper/Code/SDKTestHelper/Podfile.lock`	锁定依赖版本
`code/SDKTestHelper/Code/SDKTestHelper/R.generated.swift`	R.swift 生成的类型安全资源索引
`code/SDKTestHelper/Code/SDKTestHelper/SDKTestHelper.xcodeproj`	Xcode 工程文件（含共享 scheme）
`code/SDKTestHelper/Code/SDKTestHelper/Pods/`	CocoaPods 生成的依赖目录（含 `Pods-SDKTestHelper` target 的构建脚本、xcconfig、modulemap、umbrella 头等）

依赖与集成方式

预编译框架依赖（Libs/）

SDKTestHelper 面向的 SDK 核心能力由三个主要 xcframework 提供，它们是示例工程要验证的对象：

JL_BLEKit.xcframework：蓝牙核心能力框架（扫描、连接、服务/特征交互、设备管理），是 SDK 主体；
JL_AdvParse.xcframework：广播数据解析框架，用于解析杰理设备广播包；
JL_OTALib.xcframework：OTA 升级库，负责设备固件升级流程。

这些框架以 .xcframework 形态分发，意味着一个包内同时包含模拟器与真机（可能含多架构）的二进制，工程在 Debug/Release 下都能直接链接，无需按架构切换。

CocoaPods 工程依赖（Pods/）

工程使用 CocoaPods 管理自身依赖。Pods 目录中与 SDKTestHelper 相关的 target 产物包括：

Pods-SDKTestHelper 的 debug.xcconfig / release.xcconfig：编译配置；
Pods-SDKTestHelper.modulemap 与 umbrella.h：模块化导入支持；
Pods-SDKTestHelper-frameworks.sh / -resources.sh：链接与资源拷贝脚本；
Pods-SDKTestHelper-acknowledgements.markdown：依赖许可声明。

CocoaPods 通过生成 Pods-SDKTestHelper 这个聚合 target，把第三方依赖编译、链接、资源拷贝全部托管，示例工程源码本身只需关心业务代码，这是 iOS 示例工程最常见的依赖管理形态。

R.swift 资源管理

工程根目录存在 R.generated.swift，这是 R.swift 工具生成的资源索引文件。设计意图是：把图片、字体、字符串等资源的访问从"字符串字面量"（易拼写错误、无编译期检查）升级为"类型安全属性"（编译期即校验资源是否存在）。示例工程内的资源访问统一通过 R.xxx 形式进行，规避硬编码字符串在资源被删除后导致的运行时崩溃。

构建与运行流程

SDKTestHelper 作为测试工具的使用流程如下：

sequenceDiagram
    participant Dev as 开发者
    participant Xcode as Xcode 14.3+
    participant Pods as CocoaPods
    participant Proj as SDKTestHelper 工程
    participant Libs as Libs/ xcframework
    participant Device as iOS 真机 (iOS 10.0+)

    Dev->>Xcode: 打开 SDKTestHelper.xcodeproj
    Xcode->>Pods: 执行 pod install（首次或依赖变更时）
    Pods-->>Proj: 生成/更新 Pods-SDKTestHelper target
    Dev->>Proj: 将 Libs/ 下 xcframework 拖入工程并 link/embed
    Xcode->>Proj: 编译（R.swift 生成 R.generated.swift）
    Proj->>Libs: 链接 JL_BLEKit / JL_AdvParse / JL_OTALib
    Xcode->>Device: 部署到真机运行
    Device-->>Dev: 验证蓝牙扫描/连接/解析/OTA 等 SDK 功能

关键步骤说明：

打开工程：直接打开 SDKTestHelper.xcodeproj（共享 scheme 已配置，可在 scheme 列表中直接选择）；
安装依赖：依赖变更时执行 pod install，由 Podfile 生成/更新 Pods 工程；日常构建直接使用 Xcode 即可；
接入框架：按发布包说明将 Libs/ 下所有 .xcframework 添加到工程（link + embed）；
构建运行：Xcode 14.3+ 编译，最低部署目标 iOS 10.0；蓝牙能力需要真机运行，模拟器无法提供完整的 BLE 外设交互；
验证功能：在工程中触发 SDK 各模块功能，配合 Docs/APP说明书.md 对照预期行为。

使用示例（来自发布包说明）

集成指引原文

以下代码块摘自发布包 README 的"使用指引"章节，是使用 SDKTestHelper 及整个发布包的官方步骤：

## 使用指引
1. 将Libs目录下所有.xcframework添加到Xcode工程
2. Code目录包含完整的示例实现供参考
3. 开发前请仔细阅读Docs目录下的技术文档

Source: README.md

环境与合规要求

## 注意事项
⚠️ 要求Xcode 14.3+ 
⚠️ 最低支持iOS 10.0

Source: README.md

配置选项

配置项	类型	默认值/要求	说明
Xcode 版本	构建环境	14.3+	低于该版本无法保证工程可编译
最低部署目标	工程设置	iOS 10.0	低于 iOS 10.0 的设备不支持
依赖管理	CocoaPods	Podfile + Podfile.lock	`Pods-SDKTestHelper` target 由 pod install 生成
框架形态	二进制	.xcframework	需将 `Libs/` 下框架 link + embed 到工程
Debug/Release	xcconfig	由 Pods 生成	`Pods-SDKTestHelper.debug/release.xcconfig` 分别配置两套构建
资源访问	R.swift	R.generated.swift	资源引用类型安全，资源变更后需重新生成

失败模式与边界情况

根据已读取的发布包说明，SDKTestHelper 作为测试工具的已知约束与常见问题如下：

模拟器限制：BLE 功能依赖真实蓝牙硬件，模拟器上无法完整验证扫描/连接/OTA 流程，必须在真机（iOS 10.0+）运行；
框架缺失：若未将 Libs/ 下全部 .xcframework 添加进工程（或未 embed），链接阶段会失败；这是集成时最高频的错误来源；
依赖未同步：Podfile 与 Podfile.lock 不一致、或直接改动 Pods/ 目录而未重新执行 pod install，会导致编译错误或运行时符号缺失；
R.generated.swift 过期：工程内资源（图片/字符串）增删后若未重新生成该文件，类型安全引用将无法编译通过；
工具链版本：低于 Xcode 14.3 时工程可能无法编译（例如 xcframework 支持、Swift 工具链版本要求）。

说明：示例工程内部的具体业务逻辑源码（如 BLE 连接管理类、OTA 调用代码）未包含在仓库中（检索到的仅有工程配置与 Pods 生成物），因此本页对功能实现的深入剖析以发布包说明、工程配置与目录结构为依据。若后续源码补充到仓库，可在此基础上扩展 API 级文档。

运维与性能注意事项

构建缓存：Pods-SDKTestHelper 为聚合 target，首次构建耗时较长，后续增量编译由 Xcode 管理；
真机调试：建议使用 iOS 14+ 真机以获得完整的 BLE 调试日志与 xcframework 的 arm64 支持；
日志排查：作为测试工具，SDK 打印的日志是定位问题的主要手段，配合 Docs/APP说明书.md 对照设备行为。

扩展点

SDKTestHelper 的扩展方式主要有三种：

新增测试页面/用例：在示例工程中为各 SDK 框架（JL_BLEKit、JL_AdvParse、JL_OTALib）添加对应的功能验证页面，形成完整的 SDK 自测清单；
替换/升级框架版本：将 Libs/ 下的 xcframework 替换为新版本，即可回归验证 SDK 兼容性——这正是"测试工具"定位的核心用途；
接入方式演示：工程同时示范了"Podfile 依赖"与"直接链接 xcframework"两种形态，可作为宿主 App 集成方案的参考模板。

发布包说明 README
Podfile（依赖声明）
Podfile.lock（版本锁定）
R.generated.swift（R.swift 资源索引）
Pods-SDKTestHelper 构建配置（xcconfig）
相关主题：JL_BLEKit 框架文档、JL_AdvParse 广播解析、JL_OTALib 固件升级（分别见对应目录页与 Docs/ 技术文档）