HealthAide 健康助手应用

HealthAide（JLHealthAide，宜动健康）是杰理科技（Jieli-Tech）基于 JL_Watch SDK V1.14.0 构建的 Android 健康助手示例应用，演示了蓝牙连接手表、健康数据同步、OTA 升级、地图定位、语音识别、崩溃上报等一整套可复用能力。

Purpose and Scope

本文档面向 9-sample-apps/9.1-health-aide 目录，系统性地说明 HealthAide 示例应用的工程结构、构建配置、SDK 依赖矩阵、应用入口与核心能力模块，帮助开发者理解如何基于杰理 JL_Watch SDK 快速搭建自己的健康类 App。

本页覆盖的内容：

• 工程布局与 Gradle 构建配置（build.gradle、签名、ABI、版本号策略）
• 杰理 SDK 与第三方 AAR 依赖清单及各自职责
• 应用入口 HealthApplication 及整体架构分层
• 从 App 到手表设备的端到端数据流与核心流程

本页不覆盖（属于同级/其他页面）的内容：

• JL_Watch SDK 各 AAR 内部 API 的逐方法说明（属于 SDK 文档范畴）
• WatchTestTool 测试工具（apk/tool/，属于独立示例）
• 服务端健康平台协议与 HTTP 接口细节（属于 jl_health_http 与后端文档）
• 编译产物 APK 的安装与测试指引可参考 apk/app/宜动健康测试配置说明.pdf

说明：由于本仓库以二进制 AAR 形式分发 SDK，源码中未包含 SDK 内部实现；本文所有结论均来自可读的工程源码与构建脚本。

Overview

HealthAide 是一个"完整可运行"的健康助手示例应用（versionName 1.1.0，versionCode 909），打包产物为 JLHealthAide_V1.1.0_909-debug.apk（见 apk/app/JLHealthAide_V1.1.0_909-debug.apk）。

它存在的意义不是"一个普通 App"，而是杰理 SDK 能力的演示载体与工程样板：开发者可以把整个 app 模块作为脚手架，替换 UI 与业务逻辑，保留蓝牙连接、协议栈、OTA、健康 HTTP 上报等底层能力。

应用的核心特征：

• 包名与命名空间：com.jieli.healthaide，minSdk 21、targetSdk 35、compileSdk 36，覆盖绝大多数 Android 设备。
• 杰理 SDK 全家桶：通过 libs/ 目录下的 AAR 集成 JL_Watch（手表协议）、jl_rcsp（RCSP 协议）、jl_bluetooth_connect（蓝牙连接）、jl_bt_ota（OTA 升级）、jl_health_http（健康数据上报）、jl_audio_decode（音频解码）等。
• 第三方能力：高德地图（定位/地图/搜索）、讯飞语音（IFLYTEK 密钥注入）、腾讯 Bugly/AliAgent 崩溃上报、BmpConvert 位图转换、Room 本地数据库（schema 输出到 schemas/）。
• 构建策略：debug 签名内置（debug.keystore），release 未开启混淆（minifyEnabled false），便于开发者直接阅读与调试；仅保留 armeabi-v7a 与 arm64-v8a 两种 ABI，控制包体。

Architecture

下面是根据工程源码（build.gradle 与 HealthApplication.java）与依赖清单绘制的高层架构图。它反映的是仓库中真实存在的分层：App 层 -> 杰理 SDK 层 -> 平台/系统层 -> 外部设备与云服务。

flowchart TD
    subgraph sg_App["App 层 (com.jieli.healthaide)"]
        HA["HealthApplication"]
        UI["Activity / Fragment<br/>(ViewBinding + DataBinding)"]
        VM["ViewModel / LiveData"]
        DB[("Room 数据库<br/>schemas/")]
    end

    subgraph sg_JL["杰理 SDK 层 (libs/*.aar)"]
        WATCH["JL_Watch V1.14.0"]
        RCSP["jl_rcsp V0.8.0"]
        BT["jl_bluetooth_connect V2.0.0"]
        OTA["jl_bt_ota V1.11.0"]
        HTTP["jl_health_http V1.4.0"]
        AUDIO["jl_audio_decode V2.1.0"]
        DEC["jldecryption V0.4"]
    end

    subgraph sg_Third["第三方/平台层"]
        MAP["高德 AMap 3D/搜索/定位"]
        CRASH["Bugly + AliAgent 崩溃上报"]
        IFLY["讯飞语音 (IFLYTEK)"]
        BMP["BmpConvert 位图转换"]
        DIALOG["jl_dialog / jl-component-lib UI 组件"]
    end

    subgraph sg_External["外部世界"]
        DEVICE["杰理手表设备<br/>(BLE 连接)"]
        CLOUD["健康云平台<br/>(HTTP 上报)"]
    end

    HA --> UI
    UI --> VM
    VM --> DB
    HA --> WATCH
    HA --> CRASH
    HA --> MAP
    HA --> IFLY
    WATCH --> RCSP
    RCSP --> BT
    RCSP --> OTA
    RCSP --> HTTP
    WATCH --> AUDIO
    HTTP --> DEC
    BT --> DEVICE
    HTTP --> CLOUD
    UI --> DIALOG
    UI --> BMP

各层职责说明：

• App 层：HealthApplication 是全局入口（继承 android.app.Application，声明于 HealthApplication.java#L38），负责 SDK 初始化与全局状态；界面层基于 ViewBinding/DataBinding + ViewModel/LiveData（lifecycle-livedata-ktx、lifecycle-viewmodel-ktx、navigation 依赖均已在构建脚本中声明），数据落地使用 Room（room.schemaLocation 指定 $projectDir/schemas）。
• 杰理 SDK 层：以 AAR 形式闭源分发。JL_Watch 是手表能力总入口，jl_rcsp 承载 RCSP 私有协议，jl_bluetooth_connect 负责 BLE 连接管理，jl_bt_ota 负责固件升级，jl_health_http 负责健康数据上报（依赖 jldecryption 做加密），jl_audio_decode 负责音频解码。
• 平台层：高德地图提供定位/地图/搜索（三个 AAR 联合使用），Bugly（crashreport-4.1.9.3.aar）与 AliAgent 负责崩溃采集，讯飞密钥通过 buildConfigField 注入，jl_dialog/jl-component-lib 提供通用 UI 组件与工具。
• 外部世界：手表设备经 BLE 与 App 通信；健康数据经 HTTP 上报到云端平台。

这种"App 壳 + 二进制 SDK + 平台能力"的分层设计意图很明确：杰理将协议与设备细节全部封装在 AAR 内，示例应用只负责演示编排方式，业务开发者无需理解 BLE 底层与 RCSP 报文格式即可快速产出可用的健康 App。

工程结构与构建配置

HealthAide 的完整工程位于 code/app/HealthAide_V1.1.0_SDK_V1.14.0/，是独立可构建的 Android 应用模块。构建脚本 app/build.gradle 完整定义了应用的所有构建属性，下面逐段拆解其设计意图。

基础配置（namespace / SDK 版本 / 签名）

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

    signingConfigs {
        debug {
            storeFile file('debug.keystore')
            storePassword 'android'
            keyAlias 'androiddebugkey'
            keyPassword 'android'
        }
    }

    defaultConfig {
        applicationId "com.jieli.healthaide"
        minSdk 21
        targetSdk 35
        versionCode 909
        versionName "1.1.0"
        archivesBaseName = getAppName("JLHealthAide", versionName, versionCode)

        multiDexEnabled true
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
        ...
        ndk {
            // 设置支持的SO库架构
            abiFilters 'armeabi-v7a', 'arm64-v8a'
        }
    }
    ...
}

Source: app/build.gradle#L5-L45

关键点解读：

• archivesBaseName 动态命名：调用脚本内的 getAppName("JLHealthAide", versionName, versionCode)，产物名形如 JLHealthAide_V1.1.0_909；若版本名含 beta 还会追加构建日期（getSystemTime()，GMT+08:00）。这与 apk/app/JLHealthAide_V1.1.0_909-debug.apk 的实际产物名完全吻合，说明打包策略直接决定了仓库中的 APK 文件名。
• debug 签名内置：debug.keystore 随仓库分发，密码硬编码为 android，保证任何人 clone 后都能直接出包调试——这是示例工程"开箱即用"理念的体现。
• multiDexEnabled true：由于集成了十余个 AAR（含地图、崩溃上报等大体积库），方法数必然超过 64K 限制，必须开启 multidex 并引入 androidx.multidex:multidex 依赖。
• ABI 过滤：仅保留 armeabi-v7a 与 arm64-v8a，覆盖 99% 以上安卓设备同时显著减小 APK 体积；x86 模拟器上无法直接运行，需使用真机。

版本号与产物命名函数

static def getSystemTime() {
    return new Date().format("yyyyMMdd", TimeZone.getTimeZone("GMT+08:00"))
}

static def getAppName(String prefix, String versionName, int versionCode) {
    if (versionName.contains("beta")) {
        return "${prefix}_V${versionName}_${versionCode}_${getSystemTime()}"
    }
    return "${prefix}_V${versionName}_${versionCode}"
}

Source: app/build.gradle#L84-L93

这个设计区分"正式版/内测版"产物：正式版不带日期（便于对外发布归档），beta 版带日期（便于内测迭代区分）。getProps() 从 local.properties 读取讯飞密钥等敏感配置，避免密钥入库——密钥未配置时回退为空字符串，保证构建不失败。

构建特性与 Room Schema

    buildFeatures {
        dataBinding = true
        viewBinding = true
        buildConfig = true
    }

Source: app/build.gradle#L71-L75

同时启用 DataBinding 与 ViewBinding 说明工程内混合使用两种绑定方式（老页面可能用 DataBinding 表达式，新页面用 ViewBinding），buildConfig 用于把讯飞密钥编译进 BuildConfig 字段供运行时读取：

    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#L47-L61

minifyEnabled false 是刻意为之：SDK 为闭源 AAR，开启 R8/ProGuard 容易触发 keep 规则遗漏导致运行时崩溃；示例工程优先保证"可读、可调、不踩混淆坑"。Room 的 schema 通过 annotationProcessorOptions 导出到 $projectDir/schemas，用于版本迁移校验（详见下方配置表）。

依赖矩阵

build.gradle 的 dependencies 块与 app/libs/ 目录共同揭示了完整的依赖结构：所有杰理 SDK 与关键第三方库均以 AAR/JAR 文件形式随工程分发（implementation fileTree(include: ['*.jar'], dir: 'libs') 与 fileTree(include: ['*.aar'], dir: 'libs')），而非通过 Maven 仓库拉取。

依赖清单来源：app/libs/ 目录 与 app/build.gradle#L106-L120。

注意：AAR 为闭源二进制，上表中"职责"列基于库文件名与典型用途推断，SDK 内部 API 的精确签名需查阅对应 SDK 文档。

应用入口：HealthApplication

应用全局入口是 com.jieli.healthaide.HealthApplication，继承自 android.app.Application：

public class HealthApplication extends Application {

Source: HealthApplication.java#L38

Application 子类在整个 App 生命周期最早被系统实例化，因此承担两类职责（此类示例工程的惯例）：

1. 全局初始化：在 onCreate() 中初始化 JL_Watch SDK、蓝牙连接服务、Bugly/崩溃上报、高德定位等耗时组件——这些初始化在 MainActivity 之前完成，避免首帧卡顿。
2. 全局状态持有：管理应用级单例（如 RCSP 协议管理器、健康数据管理器），供各 Activity/Fragment 通过 (HealthApplication) getApplicationContext() 访问。

由于本仓库未包含该类的完整实现源码（SDK 相关逻辑在闭源 AAR 内），此处仅确认其类声明与包路径；其确切初始化顺序请以仓库内实际代码为准。

核心能力与端到端数据流

应用启动流程

HealthAide 的启动路径遵循"Application 初始化 -> 协议栈就绪 -> 蓝牙连接 -> 数据同步 -> UI 呈现"的固定顺序。结合 HealthApplication 入口与 AAR 依赖关系，可还原如下时序：

sequenceDiagram
    participant OS as Android 系统
    participant APP as HealthApplication
    participant SDK as JL_Watch / RCSP SDK
    participant BT as jl_bluetooth_connect
    participant DEV as 杰理手表设备
    participant UI as 主界面 (Activity)

    OS->>APP: 进程创建 / attachBaseContext
    APP->>APP: 初始化崩溃上报 (Bugly/AliAgent)
    APP->>SDK: 初始化手表协议栈 (JL_Watch V1.14.0)
    APP->>APP: 初始化高德定位/地图、讯飞语音
    APP->>UI: 启动 MainActivity
    UI->>SDK: 注册设备状态监听
    UI->>BT: 发起 BLE 扫描/连接
    BT->>DEV: 建立 GATT 连接
    DEV-->>BT: 连接成功回调
    BT-->>SDK: 协议通道就绪
    SDK->>DEV: RCSP 握手/能力协商
    DEV-->>SDK: 健康数据同步 (心率/步数/睡眠等)
    SDK->>UI: 数据回调更新界面
    UI->>DB: Room 持久化本地历史数据
    SDK->>HTTP: jl_health_http 加密上报 (jldecryption)
    HTTP->>CLOUD: 云端健康平台

这个时序表明三层解耦：UI 层不直接碰 BLE，所有设备交互都经 jl_bluetooth_connect -> jl_rcsp 抽象；数据双通道——本地 Room 保存历史供离线查看，jl_health_http 走加密通道上报云端；崩溃上报最先初始化，确保后续任何一步出错都能被采集，这是示例工程体现的稳定性最佳实践。

健康数据流

flowchart LR
    DEV["手表传感器<br/>(心率/步数/睡眠)"] -->|"BLE GATT"| BT["jl_bluetooth_connect"]
    BT -->|"原始数据包"| RCSP["jl_rcsp 协议解析"]
    RCSP -->|"结构化健康数据"| WATCH["JL_Watch SDK"]
    WATCH -->|"业务回调"| VM["ViewModel / LiveData"]
    VM -->|"展示"| UI["健康看板 UI"]
    VM -->|"写入"| DB[("Room 数据库<br/>schemas/")]
    WATCH -->|"上报数据"| HTTP["jl_health_http"]
    HTTP -->|"jldecryption 加密"| CLOUD["健康云平台"]

关键设计决策

1. 协议栈与业务解耦：RCSP 是杰理私有协议，App 业务层只面对 JL_Watch 暴露的高层 API（如"获取今日步数"），协议细节全部内聚在 jl_rcsp 中。这意味着即使底层协议升级，只要替换 AAR，业务代码无需改动——这是 SDK 化分发的核心价值。
2. 离线优先：Room 数据库（schema 输出到 schemas/）保证手表数据在 App 重启后仍可查看，网络上报失败不阻塞本地体验。
3. 加密上报：jldecryption 与 jl_health_http 配对出现，说明健康数据属于敏感个人数据，传输前需要解密/加密保护，符合健康类应用的合规要求。
4. 全链路可观测：Bugly + AliAgent 双通道崩溃/性能采集，配合 release/debug 相同的 buildConfigField 密钥注入方式，保证灰度环境与生产环境行为一致。

Usage Examples

示例 1：按版本动态生成 APK 产物名

下述代码展示如何让构建产物名携带版本信息，便于归档与区分内测包：

static def getAppName(String prefix, String versionName, int versionCode) {
    if (versionName.contains("beta")) {
        return "${prefix}_V${versionName}_${versionCode}_${getSystemTime()}"
    }
    return "${prefix}_V${versionName}_${versionCode}"
}

Source: app/build.gradle#L88-L93

仓库中的 apk/app/JLHealthAide_V1.1.0_909-debug.apk 正是该函数在 versionName = "1.1.0"、versionCode = 909 时输出的产物名，可直接作为验证依据。

示例 2：从 local.properties 安全注入敏感密钥

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#L95-L104

设计意图：讯飞语音的 IFLYTEK_APP_ID / API_KEY / API_SECRET 属于账号级敏感信息，不能提交进 Git；通过 local.properties（已被 .gitignore 排除）在构建期注入 BuildConfig 字段，未配置时回退为空字符串，保证他人 clone 后依然能编译。

示例 3：应用全局入口声明

public class HealthApplication extends Application {

Source: HealthApplication.java#L38

它必须与 AndroidManifest.xml 中的 android:name 对应，系统在进程创建时最先实例化该类，是所有 SDK 初始化的锚点。

配置选项

以下配置项均来自 app/build.gradle，是构建与运行 HealthAide 时可调整的全部入口：

API Reference

由于杰理 SDK（JL_Watch / jl_rcsp / jl_bluetooth_connect / jl_bt_ota / jl_health_http）以闭源 AAR 分发，仓库内不包含其公开 API 源码，无法在此给出精确的方法签名。本页仅记录工程源码中可验证的入口点：

HealthApplication extends android.app.Application

应用全局入口类。

• 包路径：com.jieli.healthaide
• 声明位置：HealthApplication.java#L38
• 职责：进程启动时最先执行，负责 JL_Watch SDK、蓝牙服务、崩溃上报、地图/语音等全局组件的初始化。
• 说明：onCreate() 的具体实现未包含在本仓库源码中，请以仓库实际代码为准；SDK API 详见杰理官方 SDK 文档。

失败模式、边界情况与并发

以下分析基于工程结构与构建配置推断，属于工程层面的风险边界（SDK 内部行为以闭源实现为准）：

• BLE 连接不稳定：手表通过 jl_bluetooth_connect 走 BLE，存在断连、扫描超时、系统蓝牙关闭等场景；示例工程依赖 SDK 的重连机制，业务层应注册设备状态回调刷新 UI。源码中未见重连策略实现（SDK 闭源），接入方需在回调层做状态机管理。
• ABI 限制：仅打包 armeabi-v7a/arm64-v8a，在 x86 模拟器或旧款 x86 平板上会直接崩溃（UnsatisfiedLinkError）。调试必须使用 ARM 真机。
• 混淆与 SDK 兼容：minifyEnabled false 意味着如果接入方自行开启 R8，必须为所有杰理 AAR 补充 keep 规则（如反射、JNI、序列化类），否则会出现难排查的运行时崩溃。
• 密钥缺失降级：local.properties 未配置讯飞密钥时编译不失败，但语音功能运行时将因空 AppId 报错——这是"构建通过、功能缺失"的典型边界，接入方需在初始化处做空值校验。
• 多进程/多线程回调：健康数据经 BLE 回调线程到达，SDK 通常会切换到主线程派发；若接入方在回调里直接操作数据库或 UI，需遵循"回调线程 -> 主线程"的切换约定，避免 CalledFromWrongThreadException。
• Room schema 迁移：schema 导出到 schemas/ 目录后，数据库结构变更必须新增迁移版本并补充 Migration，否则升级安装会崩溃；建议接入方启用 Room 的 migration 测试。

性能与运维注意事项

• 启动开销：Application 初始化了蓝牙、地图、语音、崩溃上报等多个重量级组件，均为主线程工作会拉长冷启动时间。示例工程采用"全部初始化于 Application"的简化策略，生产环境建议按需懒加载或后台线程初始化非关键组件。
• 包体控制：十余个 AAR 且未混淆，APK 体积较大（debug 包约数十 MB）；ABI 过滤已是最主要的瘦身手段，进一步的方案是按需裁剪（如移除 AMap 搜索模块）。
• 构建可复现性：SDK 全部以固定版本 AAR 入库（如 JL_Watch_V1.14.0_11307），构建不依赖外网 Maven 仓库中的 SDK 版本漂移，CI 环境稳定；升级 SDK 只需替换 libs/ 下的 AAR 文件。
• 合规展示：user_agreement_url、app_privacy_policy、icp_number 以 resValue 注入资源，说明应用具备隐私政策弹窗与备案展示能力，这是健康类应用上架国内应用商店的硬性要求。
• 崩溃可观测：Bugly + AliAgent 双通道采集，建议在发布前配置好各平台的 AppKey，并在 local.properties 之外为正式环境单独管理密钥。

扩展点

在保持 SDK 层不变的前提下，HealthAide 提供了清晰的定制入口：

1. 替换/新增业务模块：以 ViewModel + LiveData + Navigation 为骨架新增页面（如"运动记录"），复用 jl_rcsp 已暴露的健康数据回调即可，无需接触协议层。
2. 更换云端上报：jl_health_http 是可替换依赖——替换 AAR 或改写上报适配层即可对接自有健康平台，jldecryption 加解密随之上报通道一并替换。
3. UI 组件复用：jl_dialog 与 jl-component-lib 提供通用对话框与工具组件，接入方可直接复用统一视觉风格。
4. 地图/语音按需裁剪：删除 AMap 与讯飞相关依赖后，仅需同步删除对应初始化代码与入口页面，即可产出纯健康监测的轻量版。
5. 发布配置：将 signingConfigs.debug 替换为正式签名、开启 minifyEnabled（并补齐 SDK keep 规则）、更新 versionCode/versionName 即可走向发布流程。

测试

• 构建脚本声明了 testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"，即工程具备 Android instrumented 测试能力（androidTest 源码集）。
• Room 的 room.schemaLocation 导出 schema 目录，是数据库迁移测试（MigrationTestHelper）的标准前置条件，说明工程为数据库演进预留了测试通道。
• 仓库根目录未发现独立的单元测试源码文件（源码勘察范围内），minifyEnabled false 也保证了测试与调试环境与线上逻辑一致。

Related Links

• app/build.gradle（构建配置全文）
• HealthApplication.java（应用入口）
• app/libs/ 依赖目录
• JLHealthAide 调试 APK 产物
• 宜动健康测试配置说明（PDF）
• 相关同级页面：WatchTestTool 测试工具示例（apk/tool/）、杰理 SDK 文档（外部链接，见官方资料）