运行环境与SDK版本

本文档说明 Android-JL_Health 健康 SDK 示例工程（HealthAide）的运行环境要求、SDK 版本（V1.14.0）、Android 构建工具链版本以及全部依赖库清单，帮助开发者在接入前完成环境准备与版本核对。

Purpose and Scope

本页面向运行环境与 SDK 版本这一主题，涵盖以下内容：

• 操作系统 / 硬件 / 开发平台的最低要求（源自 README.md）
• 仓库内示例工程对应的 SDK 版本号（V1.14.0）与应用版本号（V1.1.0）
• Android Gradle 构建工具链版本：AGP 8.10.0、compileSdk 36、buildToolsVersion 36.0.0、minSdk 21、targetSdk 35
• JL SDK 核心 AAR 库清单（JL_Watch、jl_rcsp、jl_bluetooth_connect 等）及第三方依赖版本
• 构建环境相关的注意事项（NDK ABI、仓库镜像、多 dex 等）

以下内容属于其他页面的主题，不在本页展开：具体接入步骤请参见"快速开始"；工程目录结构参见"工程结构"；鉴权与参数配置参见"配置说明"。

Overview

Android-JL_Health 是珠海市杰理科技股份有限公司为蓝牙穿戴类产品提供的健康数据与设备管理开发平台，基于 RCSP 协议（远程控制系统协议） 实现。仓库以示例工程形式交付，其中：

• code/app/HealthAide_V1.1.0_SDK_V1.14.0/ —— 主示例应用 HealthAide，应用版本 1.1.0，内置 SDK V1.14.0
• code/tool/WatchTestTool_V0.9.0_SDK_V1.14.0/ —— 配套测试工具，同样基于 SDK V1.14.0

SDK 以 AAR 文件形式提供（放置在工程 libs/ 目录下），通过 implementation fileTree(include: ['*.aar'], dir: 'libs') 引入。运行 SDK 需要 Android 5.1+（支持 BLE）的设备，以及内置支持 RCSP 功能的杰理芯片固件（如 AC701N、AC707N、AC695N 等）。

版本选择上，示例工程刻意将 compileSdk（36）与 targetSdk（35）分离：compileSdk 决定编译时可用 API 面，targetSdk 决定运行时系统行为兼容模式，这是 Android 生态中常见的"新编译、旧行为"策略，避免高 targetSdk 的系统行为变更（如后台限制、分区存储）影响现有业务。

Architecture

下图展示 HealthAide 示例应用的运行环境分层：从设备层（BLE + RCSP 固件）到操作系统层、应用层、JL SDK 层与第三方依赖，完整呈现一条数据从穿戴设备到应用的链路。

flowchart TD
    subgraph sg_Device["设备层 (BLE)"]
        Device1["AC701N / AC707N / AC695N 穿戴设备"]
        Device2["RCSP 协议固件"]
    end

    subgraph sg_OS["操作系统层"]
        Android51["Android 5.1+ (API 21+)"]
        BLE["BLE 蓝牙栈"]
    end

    subgraph sg_App["应用层 (HealthAide V1.1.0)"]
        App["com.jieli.healthaide"]
        UI["Activity / Fragment / ViewModel"]
        Biz["业务逻辑 (健康/运动/消息/OTA)"]
    end

    subgraph sg_SDK["JL SDK 层 (V1.14.0)"]
        WatchSDK["JL_Watch SDK (核心)"]
        BTConnect["jl_bluetooth_connect"]
        RCSP["jl_rcsp (协议)"]
        OTA["jl_bt_ota"]
        HTTP["jl_health_http"]
    end

    subgraph sg_Third["第三方依赖"]
        Retrofit["Retrofit / OkHttp"]
        Room["Room 数据库"]
        Glide["Glide 图片加载"]
        MQTT["Eclipse Paho MQTT"]
    end

    Device1 -->|"BLE 广播/连接"| BLE
    Device2 -->|"RCSP 指令"| Device1
    BLE --> Android51
    Android51 --> App
    App --> UI
    App --> Biz
    Biz --> WatchSDK
    WatchSDK --> BTConnect
    WatchSDK --> RCSP
    WatchSDK --> OTA
    WatchSDK --> HTTP
    BTConnect --> BLE
    Biz --> Retrofit
    Biz --> Room
    Biz --> Glide
    Biz --> MQTT

各层职责说明：

设计意图：SDK 层将"BLE 连接细节 + RCSP 协议编解码"与"业务 API"解耦，应用层开发者只需面向 JL_Watch 的业务接口编程，无需关心协议字节序与 GATT 服务；而协议层（jl_rcsp）与连接层（jl_bluetooth_connect）的拆分，则允许 OTA、文件传输等高带宽场景独立演进。

SDK 版本与工程目录

仓库以"应用版本 + SDK 版本"命名示例工程目录，直接反映版本配套关系：

settings.gradle 将 HealthAide 定义为由 app 与 wheelview 两个模块组成的多模块工程，wheelview 是仓库内自带的滚轮选择器组件，被 app 以 implementation project(path: ':wheelview') 方式引用：

Source: settings.gradle

include ':wheelview'
include ':app'
rootProject.name = "HealthAide"

构建工具链版本

顶层 build.gradle 声明 Android Gradle Plugin 版本为 8.10.0，并配置了覆盖 mavenCentral、google、jitpack 以及国内阿里云镜像的仓库集合。仓库镜像（aliyun）的引入是为了在国内网络环境下加速依赖下载，这是面向国内开发者的关键可运维性设计：

Source: build.gradle

buildscript {
    repositories {
        mavenCentral()
        //国内镜像
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        maven { url 'https://maven.aliyun.com/repository/apache-snapshotse' }

        google()
        maven { url 'https://maven.google.com' }
        maven { url 'https://jitpack.io' }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.10.0'
    }
}

app 模块的 Android 配置是环境要求的核心：

Source: app/build.gradle

android {
    namespace 'com.jieli.healthaide'
    compileSdk 36
    buildToolsVersion '36.0.0'

    defaultConfig {
        applicationId "com.jieli.healthaide"
        minSdk 21
        targetSdk 35
        versionCode 909
        versionName "1.1.0"
        multiDexEnabled true
        ndk {
            // 设置支持的SO库架构
            abiFilters 'armeabi-v7a', 'arm64-v8a'
        }
    }
}

构建工具链关系如下图所示：

flowchart LR
    subgraph sg_Env["开发环境"]
        AS["Android Studio (建议最新版)"]
        JDK["JDK (source/target 1.8)"]
        Gradle["Gradle + AGP 8.10.0"]
    end

    subgraph sg_Sdk["Android SDK"]
        Compile["compileSdk 36 / BuildTools 36.0.0"]
        Min["minSdk 21 (Android 5.0)"]
        Target["targetSdk 35"]
    end

    subgraph sg_Mod["工程模块"]
        App["app (com.jieli.healthaide)"]
        Wheel["wheelview"]
    end

    AS --> Gradle
    JDK --> Gradle
    Gradle --> Compile
    Compile --> Min
    Compile --> Target
    Gradle --> App
    Gradle --> Wheel

关键点解读：

• compileSdk 36 / targetSdk 35 分离：编译使用最新 API 面，运行时保持 targetSdk 35 的兼容行为，降低系统行为变更风险。
• minSdk 21（Android 5.0）：与 README 宣称的"Android 5.1+"基本对齐（BLE 功能完整可用从 5.1 起）；multiDexEnabled true 表明方法数已超过 64K 单 dex 上限，需 multidex 支持。
• ABI 过滤：仅保留 armeabi-v7a 与 arm64-v8a，覆盖绝大多数 Android 手机，同时显著减小 APK 体积——这是穿戴类 APP 面向存量 32 位设备与主流 64 位设备的务实取舍。
• Java 8 兼容：sourceCompatibility/targetCompatibility VERSION_1_8 保证低版本 Android 设备上的字节码兼容。

JL SDK 核心 AAR 依赖

README 明确列出 SDK 以 AAR 形式交付的 8 个核心库，xxx 为版本号（本仓库配套 V1.14.0）：

接入方式：将 AAR 放入模块 libs/ 目录，并在 build.gradle 声明 implementation fileTree(include: ['*.aar'], dir: 'libs') 与 implementation fileTree(include: ['*.jar'], dir: 'libs')，同时通过 sourceSets.main.jniLibs.srcDirs = ['libs'] 声明 so 库目录（见 app/build.gradle）。

第三方依赖清单

app/build.gradle 的 dependencies 块（见 app/build.gradle）按功能域整理如下：

设计说明：网络层选用 Retrofit + OkHttp 支撑健康数据上报与杰理健康服务器交互（jl_health_http）；MQTT 用于设备消息的实时通道；Room 负责本地健康数据缓存。这些第三方库与 JL SDK 之间无强耦合，可按需替换。

Core Flow：从环境就绪到数据同步

下图展示在满足运行环境后，一次典型的"设备连接 → RCSP 数据交互 → 健康数据上报"完整链路。理解这条链路有助于定位环境问题：例如连接失败往往发生在 jl_bluetooth_connect 与 BLE 栈之间，而协议解析异常则集中在 jl_rcsp 层。

sequenceDiagram
    participant App as HealthAide 应用
    participant SDK as JL_Watch SDK (V1.14.0)
    participant BT as jl_bluetooth_connect
    participant Device as 穿戴设备 (RCSP 固件)
    participant Svr as jl_health_http 服务器

    App->>SDK: 初始化 SDK / 注册回调
    SDK->>BT: 开始扫描 / 发起 BLE 连接
    BT->>Device: BLE GATT 连接
    Device-->>BT: 连接成功
    BT-->>SDK: 设备上线通知
    SDK->>Device: RCSP 命令 (健康/运动/OTA/表盘)
    Device-->>SDK: RCSP 应答与数据回调
    SDK-->>App: 业务回调 onNotify / 数据同步
    App->>Svr: 健康数据上报 (Retrofit/HTTP)

各阶段与运行环境的对应关系：

1. 初始化：应用启动时初始化 JL_Watch SDK 并注册回调，要求 minSdk 21 以上环境；
2. BLE 连接：jl_bluetooth_connect 通过系统 BLE 栈与设备建立 GATT 连接，依赖 Android 5.1+ 的稳定 BLE 实现；
3. 协议交互：连接建立后，SDK 通过 jl_rcsp 层封装 RCSP 指令与设备交互，指令集覆盖健康数据、运动、消息、OTA、表盘、闹钟、文件传输等（详见 README 功能表）；
4. 数据上报：业务层将同步到的健康数据经 jl_health_http / Retrofit 上报杰理健康服务器，或经 MQTT 通道推送实时消息。

硬件与协议环境

Source: README.md

RCSP（远程控制系统协议）是杰理私有协议，承载设备发现、配对、命令下发与数据上报。SDK 将协议细节封装在 jl_rcsp AAR 内，因此固件必须与 SDK 版本配套：仓库以 SDK_V1.14.0 命名工程，暗示固件/协议版本与 SDK 1.14.0 匹配的穿戴设备为预期目标。若接入时使用不同版本的 JL_Watch AAR，需要同步核对固件协议版本，避免命令字不兼容导致的静默失败。

Usage Examples

示例 1：添加 SDK AAR 依赖

将 JL_Watch_V1.14.0-release.aar 等 AAR 放入模块 libs/ 目录后，在 build.gradle 中声明依赖与 so 库路径：

dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
    implementation fileTree(include: ['*.aar'], dir: 'libs')
}

android {
    sourceSets {
        main {
            jniLibs.srcDirs = ['libs']
        }
    }
}

Sources:

• app/build.gradle
• app/build.gradle

示例 2：按渠道注入敏感配置（BuildConfig）

讯飞语音相关密钥通过 local.properties 读取并注入 BuildConfig，未配置时回退为空字符串，保证 CI/新环境可无密钥编译：

buildTypes {
    release {
        minifyEnabled false
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        buildConfigField("String", "IFLYTEK_APP_ID", getProps("IFLYTEK_APP_ID"))
        buildConfigField("String", "IFLYTEK_API_KEY", getProps("IFLYTEK_API_KEY"))
        buildConfigField("String", "IFLYTEK_API_SECRET", getProps("IFLYTEK_API_SECRET"))
    }
    debug {
        signingConfig signingConfigs.debug
        buildConfigField("String", "IFLYTEK_APP_ID", getProps("IFLYTEK_APP_ID"))
        buildConfigField("String", "IFLYTEK_API_KEY", getProps("IFLYTEK_API_KEY"))
        buildConfigField("String", "IFLYTEK_API_SECRET", getProps("IFLYTEK_API_SECRET"))
    }
}

Source: app/build.gradle

def getProps(String propName) {
    def propsFile = rootProject.file('local.properties')
    if (propsFile.exists()) {
        def props = new Properties()
        props.load(new FileInputStream(propsFile))
        return props.getProperty(propName, "\"\"")
    } else {
        return "\"\""
    }
}

Source: app/build.gradle

示例 3：Room 数据库 schema 导出配置

通过 annotationProcessorOptions 指定 Room schema 输出目录，便于版本迁移时维护数据库结构变更记录：

defaultConfig {
    //指定room.schemaLocation生成的文件路径
    javaCompileOptions {
        annotationProcessorOptions {
            arguments = ["room.schemaLocation": "$projectDir/schemas".toString()]
        }
    }
}

Source: app/build.gradle

Configuration Options

以下为 app 模块 build.gradle 中与环境、版本相关的全部关键配置项：

环境变量与本地配置约定：

• local.properties：存放 IFLYTEK_APP_ID、IFLYTEK_API_KEY、IFLYTEK_API_SECRET（不入库），getProps() 读取不到时回退空字符串；
• resValue：user_agreement_url、app_privacy_policy、icp_number 在构建期注入资源（见 app/build.gradle）；
• 仓库镜像：阿里云镜像与 xiaomi-passport、oss.sonatype.org 快照仓库已预置，网络受限环境无需额外配置。

失败模式、边界与注意事项

• minSdk 21 vs Android 5.1：minSdk 21 允许安装到 Android 5.0 设备，但 README 要求 Android 5.1+ 以保证 BLE 功能稳定。在 5.0 设备上可能出现扫描/连接异常，属预期边界。
• targetSdk 35 行为变更：若开发者擅自将 targetSdk 提升至 36，可能触发 Android 16 的隐私与后台限制（如前台服务类型、BLE 扫描后台限制），导致原有连接逻辑失败；保持 targetSdk 35 是当前工程的兼容性约定。
• 固件与 SDK 版本配套：RCSP 为私有协议，命令字随版本演进。混用不同版本的 jl_rcsp 与设备固件会造成"连接成功但命令无响应/数据解析错误"的静默失败，排查时应优先核对固件协议版本与 SDK_V1.14.0 的一致性。
• ABI 缺失：abiFilters 仅含 armeabi-v7a/arm64-v8a，x86 模拟器（如部分 Android Studio 模拟器镜像）上运行会因缺少 so 库崩溃；建议使用 ARM 镜像或真机调试。
• 密钥缺失的降级：IFLYTEK 密钥读取失败时回退为空字符串，构建可成功但运行时语音功能不可用——属于"编译通过、功能缺失"类问题，需检查 local.properties。
• debug 签名硬编码：debug 签名使用固定的 debug.keystore（密码 android），仅用于开发调试，不得用于发布。

并发与一致性说明

• Room 数据库（room 2.3.0）与多线程数据同步：健康数据通过 SDK 回调写入本地库时，建议在单一 Executor/Coroutine 上下文中串行写入，避免并发事务冲突；room.schemaLocation 导出 schema 便于版本迁移的并发演进。
• BLE 连接状态机：jl_bluetooth_connect 内部维护连接状态，业务层应避免在回调中直接发起重连（可能造成状态机竞争），应通过 SDK 提供的能力队列串行下发命令。

性能与运维提示

• 多 dex 与构建体积：multiDexEnabled true 已开启，release 未启用 minify（minifyEnabled false），正式发布建议按需开启混淆并保持 AAR 中 so 的 ABI 过滤以控制体积。
• 镜像与缓存：国内环境优先命中阿里云镜像；CI 构建建议开启 Gradle 构建缓存与配置缓存，加速多模块（app + wheelview）编译。

Extension Points

• 多模块结构：settings.gradle 采用模块化组织，新功能可新增独立 Gradle 模块并以 project() 方式引入，与 wheelview 模式一致。
• 依赖注入点：Retrofit、Room、Glide 均为可替换的第三方组件，若需替换网络栈或持久化方案，只需修改 dependencies 块，不影响 JL SDK 层。
• 自定义命令：README 功能表明确 SDK 支持"自定义命令"扩展，客户可在 RCSP 协议框架下扩展私有指令（详见 SDK API 文档）。

Related Links

• README.md（运行环境与快速开始）
• HealthAide app/build.gradle
• HealthAide 顶层 build.gradle
• HealthAide settings.gradle
• WatchTestTool 工程（SDK V1.14.0 配套工具）
• 相邻页面：快速开始（工程导入与依赖添加）、工程结构（目录组织）、配置说明（业务参数与鉴权）