版本历史与兼容性

本文档梳理 Android-JL_Health 仓库（杰理健康 SDK for Android）的版本体系：SDK/示例工程的命名规则、当前交付快照的组件版本清单、系统与硬件兼容性矩阵，以及版本号如何驱动构建产物命名。

Purpose and Scope

本页面聚焦于版本与兼容性这一主题，涵盖：

• SDK 与示例工程的版本命名规范（AAR 名称、快照目录、构建产物名）
• 当前仓库快照（HealthAide V1.1.0 / WatchTestTool V0.9.0 / SDK V1.14.0）的完整组件版本清单
• 系统（Android API）、ABI、硬件芯片与 RCSP 协议的兼容性矩阵
• 版本号在 Gradle 构建中的实际作用（versionCode/versionName/archivesBaseName）

不在此页面范围：SDK 具体功能接口的接入方法（见“配置说明”页）、工程导入与权限配置（见“快速开始”页）、调试与常见问题（见“调试技巧”页）。SDK 的完整发布记录以仓库根目录的 Jieli_Health_SDK_Android_Releases.pdf 为准，本页只保证与当前代码快照一致。

Overview

Android-JL_Health 是珠海杰理科技为蓝牙穿戴类产品提供的健康数据与设备管理开发平台，基于 RCSP（远程控制系统协议） 实现设备控制。仓库以"版本快照目录"的方式组织交付物，这是理解本仓库版本历史的关键：

code/app/HealthAide_V1.1.0_SDK_V1.14.0/     # 宜动健康（HealthAide）示例工程 V1.1.0，配套 SDK V1.14.0
code/tool/WatchTestTool_V0.9.0_SDK_V1.14.0/  # 手表测试工具 V0.9.0，配套 SDK V1.14.0

每个快照目录内，libs/ 下携带与工程配套锁定版本的 AAR 库，例如核心库 JL_Watch_V1.14.0_11307-release.aar。因此，查看某个示例工程使用的 SDK 版本，只需读其目录名与 app/libs/ 文件名即可，无需猜版本。

版本标识的载体有三层：

1. AAR 文件名：组件名_V主.次.修_构建号[-debug/-release].aar，如 jl_bt_ota_V1.11.0_11015-release.aar；
2. Gradle 版本属性：versionCode（整数，单调递增）+ versionName（可读字符串），并经由 archivesBaseName 拼出 APK/AAR 产物名；
3. 快照目录名：工程名_V工程版本_SDK_VSDK版本，如 HealthAide_V1.1.0_SDK_V1.14.0。

Architecture

下图展示版本化交付物在整体架构中的位置：上层示例工程依赖中间层 SDK 组件，中间层通过 RCSP/蓝牙协议栈与底层硬件交互。

flowchart TD
    subgraph sg_Apps["示例应用层（携带版本快照）"]
        App["HealthAide V1.1.0<br/>(versionCode 909)"]
        Tool["WatchTestTool V0.9.0<br/>(versionCode 619)"]
    end

    subgraph sg_SDK["SDK 组件层（V1.14.0 快照，AAR 内嵌版本号）"]
        Watch["JL_Watch V1.14.0<br/>核心健康库"]
        Bt["jl_bluetooth_connect V2.0.0<br/>蓝牙连接"]
        Ota["jl_bt_ota V1.11.0<br/>OTA 升级"]
        Rcsp["jl_rcsp V0.8.0<br/>RCSP 基础协议"]
        Http["jl_health_http V1.4.0<br/>健康服务器"]
        Media["BmpConvert V1.6.0 /<br/>jl_audio_decode V2.1.0"]
    end

    subgraph sg_Base["协议与硬件层"]
        BLE["BLE / 经典蓝牙"]
        RCSP_PROTO["RCSP 协议"]
        Chip["AC701N / AC707N / AC695N 等<br/>支持 RCSP 的芯片"]
    end

    App --> Watch
    App --> Bt
    App --> Ota
    App --> Http
    Tool --> Bt
    Tool --> Rcsp
    Watch --> Rcsp
    Watch --> Bt
    Bt --> BLE
    Rcsp --> RCSP_PROTO
    RCSP_PROTO --> Chip
    Media --> App

架构解读：JL_Watch 是核心健康库，提供穿戴设备的主要功能；它依赖 jl_bluetooth_connect（数据收发通道）与 jl_rcsp（RCSP 报文编解码）。jl_bt_ota 提供固件空中升级，jl_health_http 提供云端服务接入，BmpConvert/jl_audio_decode 等提供媒体编解码能力。示例应用（HealthAide、WatchTestTool）各自声明对这些 AAR 的依赖并内置在快照目录中，保证"示例可复现、版本可追溯"。

版本命名规范

AAR 库命名规则

杰理 SDK 的所有 AAR 均遵循统一的文件名模板，版本号直接暴露在文件名中：

例如 jl_rcsp_V0.8.0_705-release.aar 表示 RCSP 基础协议库 V0.8.0、构建号 705。这种"文件名即版本表"的设计让集成方无需额外文档即可核对依赖版本。

构建产物命名规则

示例工程通过 archivesBaseName 将版本信息写入 APK 文件名，方便发布与追溯：

Source: build.gradle

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}"
}

设计意图：正式版（versionName 不含 beta）的产物名固定为 前缀_V版本_版本号（如 JLHealthAide_V1.1.0_909）；beta 版本会追加当日日期（GMT+08:00 时区），从而避免同一天多次构建的 beta 包互相覆盖。这保证了每个构建产物在文件名层面即可区分版本与构建日期。

当前版本快照

仓库当前交付的快照包含两个示例工程，均配套 SDK V1.14.0：

版本属性在 build.gradle 的 defaultConfig 中声明：

Source: build.gradle

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"
    ...
}

Source: build.gradle

defaultConfig {
    ...
    targetSdk 34
    versionCode 619
    versionName "0.9.0"
    archivesBaseName = getAppName("WatchTestTool", versionName, versionCode)
    ...
}

SDK 组件版本清单

以下为 code/app/HealthAide_V1.1.0_SDK_V1.14.0/app/libs/ 中实际交付的 AAR 版本清单（来自快照目录文件列表）：

版本匹配原则：AAR 文件名中的 SDK 版本（如 JL_Watch_V1.14.0）应与快照目录名中的 SDK_V1.14.0 一致。集成方自行接入时，应按 README 的依赖清单成组替换 AAR，避免核心库与附属库（蓝牙连接、OTA、RCSP）版本错配。核心库依赖关系参见上文架构图。

兼容性矩阵

系统与工具链兼容性

硬件与协议兼容性

关键兼容性说明

• targetSdk 35 与 34 的差异：HealthAide 已升至 35，WatchTestTool 仍为 34。升级 targetSdk 后需重点回归蓝牙扫描、后台定位、通知权限等 Android 15 行为变更；
• minSdk 21 意味着 5.0 及以下系统不受支持：仓库选择 Android 5.1+ 作为下限，因为这是 BLE 能力稳定的分界点；
• 仅保留 ARM ABI：abiFilters 'armeabi-v7a', 'arm64-v8a' 剔除了 x86/x86_64，减小包体但导致模拟器（x86 镜像）上无法直接运行，需使用 ARM 镜像或真机。

核心流程：版本号解析与构建产物命名

版本号从声明到产物落盘的控制流如下：

flowchart TD
    Start([Gradle 构建]) --> Read["读取 defaultConfig<br/>versionCode / versionName"]
    Read --> Check{"versionName<br/>包含 beta?"}
    Check -->|"是"| Beta["产物名 = 前缀_V版本_版本号_yyyyMMdd<br/>如 JLHealthAide_V1.1.1beta_910_20250601"]
    Check -->|"否"| Stable["产物名 = 前缀_V版本_版本号<br/>如 JLHealthAide_V1.1.0_909"]
    Beta --> Output["archivesBaseName 生效<br/>生成 APK/AAR 文件"]
    Stable --> Output
    Output --> End([发布/归档])

执行说明：

1. Gradle 解析 defaultConfig 中声明的 versionCode（如 909）与 versionName（如 1.1.0）；
2. archivesBaseName = getAppName("JLHealthAide", versionName, versionCode) 触发命名函数（见上文代码）；
3. getAppName 依据 versionName.contains("beta") 分支：正式版直接拼接；beta 版调用 getSystemTime()（GMT+08:00 的 yyyyMMdd）追加日期后缀；
4. 产物文件名携带完整版本信息，配合快照目录名 HealthAide_V1.1.0_SDK_V1.14.0，实现"目录名=工程版本，文件名=构建版本，libs=SDK 版本"的三重可追溯。

第三方依赖版本

HealthAide 工程声明的关键第三方依赖（app/build.gradle dependencies 块）：

Source: build.gradle

版本锁定注意点：alipaysdk-android 使用 +@aar 动态版本，其余均为固定版本——升级依赖时建议优先固定该支付宝 SDK 版本，避免构建结果漂移；wheelview 是仓库内本地模块，其 versionCode 33 / versionName 4.1.1 与主工程版本相互独立。

Usage Examples

集成方添加 AAR 依赖

按版本配套原则，将快照 libs/ 下的 AAR 拷入工程并在模块级 build.gradle 声明：

Source: README.md

dependencies {
    //1.将上面的aar文件放入工程目录中的对应moudle的lib文件夹下
    //2.在moudlu的build.gradle中添加
    implementation fileTree(include: ['*.aar'], dir: 'libs')

    implementation 'com.google.code.gson:gson:2.13.1'
}

fileTree 会将该目录下全部 AAR 一并引入——因此务必保证 libs/ 中的 AAR 版本配套（参考上文 SDK 组件版本清单），避免出现两个版本的 JL_Watch 同时被编译。

初始化健康管理类（SDK 版本相关入口）

版本升级时，WatchOpImpl 的构造参数 func 决定 SDK 启用的功能集，是兼容性行为的分水岭：

Source: README.md

//实现健康管理类
public class WatchManager extends WatchOpImpl{

   private BluetoothDevice mTargetDevice;

   public static WatchManager getInstance() {
       if (null == instance) {
           synchronized (WatchManager.class) {
              if (null == instance) {
                  instance = new WatchManager(FUNC_WATCH);
               }
            }
        }
        return instance;
   }

   //func FUNC_WATCH:手表功能
   //FUNC_RCSP：仅仅使用rcsp协议
   //FUNC_FILE_BROWSE：使用rcsp协议和目录浏览功能
    public WatchManager(int func) {
        super(func);
    }
     /**
      * 获取当前连接的设备，sdk的操作都是基于该设备
      * @return 目标设备
      */
    @Override
    public BluetoothDevice getConnectedDevice() {
        //TODO: 客户重写实现功能
         return mTargetDevice;
    }
    ...
}

兼容性提示：SDK 各版本的 func 常量（FUNC_WATCH/FUNC_RCSP/FUNC_FILE_BROWSE）定义于核心库 JL_Watch。升级 SDK V1.14.0 之前，请确认目标版本仍支持当前使用的 func 取值。

Configuration Options

以下为与版本、兼容性直接相关的 Gradle 配置项（defaultConfig/ndk 块）：

API Reference

getAppName(String prefix, String versionName, int versionCode): String

生成构建产物基名（archivesBaseName）。

参数：

• prefix（String）：产物名前缀，如 JLHealthAide、WatchTestTool；
• versionName（String）：来自 defaultConfig.versionName；
• versionCode（int）：来自 defaultConfig.versionCode。

返回：

• 若 versionName 含 beta："${prefix}_V${versionName}_${versionCode}_${getSystemTime()}"；
• 否则："${prefix}_V${versionName}_${versionCode}"。

设计意图： 正式版名称稳定可预测；beta 版追加构建日期（GMT+08:00），防止同日多次构建相互覆盖，也便于测试人员按日期区分包。

getSystemTime(): String

返回当前日期字符串 yyyyMMdd（时区固定为 GMT+08:00）。用于 beta 产物名的时间戳。

getProps(String propName): String

从根目录 local.properties 读取属性（如 IFLYTEK_APP_ID/IFLYTEK_API_KEY/IFLYTEK_API_SECRET），文件不存在或属性缺失时返回空字符串 ""。用于在不把密钥提交进仓库的前提下注入 BuildConfig 字段——release 与 debug 构建类型均通过 buildConfigField("String", key, getProps(key)) 注入。

Source: build.gradle

Failure Modes、边界情况与并发

版本错配（最典型的集成故障）

若将 JL_Watch_V1.14.0 与旧版 jl_rcsp/jl_bluetooth_connect 混用，可能出现运行时 NoSuchMethodError、蓝牙数据解析异常或 RCSP 命令不识别。规避方式：按快照目录整组替换 AAR；升级 SDK 前对照 Jieli_Health_SDK_Android_Releases.pdf 确认配套版本。这也是仓库采用"快照目录携带 libs"结构的根本原因——工程内 AAR 版本天然与工程版本绑定。

targetSdk 升级引发的行为变更

• 34 → 35（Android 15）：前台服务类型、蓝牙相关权限提示、PackageManager 可见性等行为变化可能影响连接流程；
• Android 12+ 蓝牙权限：BLUETOOTH_CONNECT 属运行时权限，且受 neverForLocation 标志影响，未正确申请会导致扫描不到设备（README 已提示需在 Manifest 声明）。

ABI 缺失导致 so 加载失败

abiFilters 仅打包 armeabi-v7a/arm64-v8a。若在 x86 模拟器上运行，UnsatisfiedLinkError 会抛出；排查时应确认设备 ABI 与 APK 内 so 架构一致。

beta 产物命名的时间边界

getAppName 使用构建当日日期而非 UTC 日期（固定 GMT+08:00）。跨时区 CI 构建时，beta 包日期可能不同于本地预期；正式版不受影响。另外 versionCode 需单调递增——若回退版本号，应用市场将拒绝覆盖安装。

multidex 与动态版本

• multiDexEnabled true 是为方法数超限准备的；新增重依赖（如二维码 OpenCV 全 ABI）时应关注分包后的启动性能；
• alipaysdk-android:+@aar 为动态版本，不同时间构建可能解析到不同版本，导致"相同代码、不同产物"——正式发布建议锁定具体版本。

并发与状态一致性

SDK 的 WatchManager 采用双重检查锁单例（synchronized (WatchManager.class)）保证全局唯一实例，所有设备操作基于 getConnectedDevice() 返回的当前设备。版本升级时若连接状态机有变，需注意：

• 单例持有旧版本初始化状态，热替换 AAR 不会生效，必须冷启动；
• sendDataToDevice(BluetoothDevice, byte[]) 由 SDK 回调、业务线程实现发送，多线程调用时发送队列的串行化由连接库保证——升级 jl_bluetooth_connect 版本时需回归验证并发发送。

Performance 与运维

• 产物命名即版本追溯：archivesBaseName 让 APK 文件名携带 V版本_版本号，配合快照目录名，可在无版本数据库的情况下精确定位构建产物对应的代码快照；
• ABI 裁剪：仅保留两个 ARM ABI 显著减小包体，适合穿戴配套 App 的分发场景；
• Room schema 版本管理：room.schemaLocation 输出到 $projectDir/schemas，Room 数据库升级（version 递增）时必须保留旧 schema 文件以支持迁移验证；
• 发布记录文档：仓库根目录 Jieli_Health_SDK_Android_Releases.pdf 是官方 SDK 发布记录，升级前应先查阅目标版本的新增功能与破坏性变更。

Extension Points

• 自定义产物命名：getAppName(prefix, versionName, versionCode) 是 archivesBaseName 的唯一入口，可按发布渠道定制命名规则（如追加渠道号），无需改动版本体系；
• 密钥注入：getProps() + buildConfigField 模式可扩展到任意密钥/环境配置，通过 local.properties 按机器注入，保持仓库无敏感信息；
• 功能集开关：WatchManager(int func) 的 func（FUNC_WATCH/FUNC_RCSP/FUNC_FILE_BROWSE）是 SDK 层面的扩展点，按需裁剪启用功能；
• 本地模块 wheelview：以 project(path: ':wheelview') 方式内嵌，可随主工程一并版本化。

Tests

• 单元测试：testImplementation 'junit:junit:4.+'，测试类位于 app/src/test 与 app/src/androidTest（如 ExampleInstrumentedTest.java，基于 androidx.test.ext:junit + Espresso）；
• 网络模拟：mockwebserver:4.10.0 同时被 testImplementation 与 implementation 引入，用于模拟杰理健康服务器接口；
• 版本相关行为（命名、权限、ABI）主要由构建配置保证，建议在 CI 中对 versionCode 单调性、archivesBaseName 输出命名做断言校验。

Related Links

• README.md（仓库总览、运行环境、版本历史索引）
• README_en.md（英文版说明）
• HealthAide 工程 build.gradle
• WatchTestTool 工程 build.gradle
• 手表测试工具说明文档
• 官方文档中心：https://doc.zh-jieli.com/Apps/Android/health/zh-cn/master/index.html