📚 课程目录第1章课程介绍

1. 课程导学与环境搭建

本章为课程奠定技术基础与开发环境。学习完本章后，你将理解Room数据库+蓝牙多设备数据管理的整体技术栈，完成Android Studio工程配置、必要依赖引入与权限声明，为后续各章的编码实战做好准备。

1.1 课程目标

掌握Room数据库核心概念及其在Android中的定位。
了解蓝牙多设备数据采集的典型场景与架构选择。
独立搭建包含Room + 蓝牙功能的最小可运行工程。
理解蓝牙权限声明策略与Room依赖配置的最佳实践。

1.2 前置知识

领域	必备知识	建议掌握度
Android基础	Activity / Fragment生命周期、布局XML、Intent	熟练
Java / Kotlin	类、接口、协程（Kotlin）或线程（Java）	熟练
数据库	SQLite基本语法、CRUD操作	了解
蓝牙	经典蓝牙（RFCOMM）与BLE概念	基本了解
Gradle	依赖管理、版本冲突解决	基本了解

💡 提示： 如果你对BLE（低功耗蓝牙）完全陌生，建议先花30分钟阅读官方《BLE开发概览》。本课程会从基础开始，但默认你已经理解服务和特征值的概念。

1.3 开发工具安装清单

工具	版本要求	说明
Android Studio	Hedgehog (2023.1.1) 或更高	建议使用最新稳定版
JDK	11 或 17（LTS）	Android Studio自带，也可单独安装
Android SDK	API 26+	Room与BLE均需要最低API 18，为兼容新特性建议目标API 33+
Kotlin	1.9.0+	课程代码示例使用Kotlin，推荐Kotlin DSL构建脚本
Gradle	8.2+	AGP（Android Gradle Plugin）8.2+

1.4 Android Studio 配置要点

创建新项目：选择Empty Views Activity模板，语言选Kotlin，最低SDK API 26。
启用Jetpack：确保项目使用android.useAndroidX=true（默认已开启）。
SDK管理：在SDK Manager中安装Android 13（API 33）或更高系统映像，用于BLE模拟或真机调试。
虚拟设备：若使用模拟器，创建Pixel 5或Nexus 6P设备映像（需支持BLE）。部分模拟器不支持BLE扫描，建议真机调试。

1.5 蓝牙权限声明（AndroidManifest.xml）

蓝牙操作需要运行时权限与清单静态权限。以下为完整的权限声明片段（适用于Android 12+ / API 31+）：

<!-- 蓝牙基础权限（必须） -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- Android 12+ 新增的扫描与连接声明 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

<!-- 经典蓝牙与BLE通常在清单中声明使用权限，方便Google Play过滤 -->
<uses-feature android:name="android.hardware.bluetooth" android:required="true" />
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

<!-- 扫描需要位置权限（Android 11及以下），本课程采用Android 12+新权限模型 -->
<!-- 若需兼容Android 11以下，需添加： -->
<!-- <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> -->

⚠️ 注意： 从Android 12开始，BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 属于运行时权限，需要在代码中动态申请。本课程后续章节会演示运行时权限请求的完整流程。仅声明清单权限而不申请，蓝牙扫描将直接失败。

1.6 Room 依赖引入（build.gradle.kts）

使用Kotlin Symbol Processing (KSP) 作为Room的注解处理器，相比kapt速度更快。在项目级build.gradle.kts中添加KSP插件，然后在模块级build.gradle.kts中引入Room依赖。

// 项目级 build.gradle.kts
plugins {
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

// 模块级 build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    // ... 其他配置
}

dependencies {
    // Room 基本依赖
    val roomVersion = "2.6.1"
    implementation("androidx.room:room-runtime:$roomVersion")
    implementation("androidx.room:room-ktx:$roomVersion") // 协程支持
    ksp("androidx.room:room-compiler:$roomVersion")       // KSP 注解处理器

    // Kotlin 协程（Room 常用）
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
}

  📌 关键检查点：添加依赖后，执行Sync Now，确认编译无红色波浪线。若出现Unresolved reference: ksp，请在项目级build.gradle中加入KSP插件版本，并检查AGP与KSP版本兼容性。

1.7 环境搭建概览：Room + 蓝牙多设备数据管理架构

下方SVG图展示了本课程的核心架构层次：蓝牙设备层→ 扫描/连接服务 → 数据解析 → Room数据库 → UI层。箭头表示数据流方向。图中的每个模块将在后续章节中详细实现。

1.8 常见错误与前置检查列表

现象	可能原因	快速解决
KSP 编译失败：unresolved reference	KSP插件版本与AGP不兼容	检查KSP版本表，确保与AGP版本匹配
蓝牙扫描无回调	未动态申请运行时权限	添加BLUETOOTH_SCAN/BLUETOOTH_CONNECT运行时请求
Room @Entity 错误	未添加ksp或kapt依赖	确认已配置room-compiler处理器
模拟器无法扫描蓝牙	模拟器不支持BLE	改用真机或Android Studio最新模拟器（需启用Bluetooth）

  ✅ 环境验证步骤：
  新建空白项目后，先添加Room依赖并Sync，编写一个最小Entity类（如DeviceData），执行Build → Rebuild Project，确认编译通过。
在MainActivity中添加延时权限申请（仅模拟蓝牙权限），确认弹出授权对话框。
启动应用至真机，打开蓝牙，观察Logcat输出无异常。

环境搭建完成后，你就可以放心进入第2章——Room实体定义与DAO基础操作，开始编写真正的数据模型层代码。