first commit

2026-11-05 14:35:04 +08:00
commit 669f49b1d6
@@ -0,0 +1,297 @@
+# 徐工项目蓝牙模块流程概览
+
+> 整理目的：帮助快速理解蓝牙模块架构和核心流程
+
+---
+
+## 一、整体架构
+
+### 1.1 模块组成
+
+| 模块 | 说明 |
+|------|------|
+| **YX_BlueTooth** | 上层应用，蓝牙电话、音乐界面 |
+| **YX_BluetoothSDK** | SDK模块，封装蓝牙协议 |
+| **Frameworks中间件** | android.bluetooth API |
+| **系统蓝牙应用** | packages/apps/Bluetooth/ |
+| **蓝牙协议栈** | system/bt，底层协议实现 |
+| **第三方SDK** | 顾凯芯片商提供 |
+
+### 1.2 调用层级（从上到下）
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  YX_Bluetooth (上层应用)                                  │
+│     ↓ android.bluetooth API                              │
+│  Frameworks中间件                                         │
+│     ↓ Binder IPC                                         │
+│  Bluetooth Process (系统蓝牙应用)                          │
+│     ↓ JNI                                                │
+│  蓝牙协议栈 (system/bt)                                   │
+│     ↓ HIDL                                               │
+│  供应商实现 (顾凯SDK)                                      │
+│     ↓ HCI                                                │
+│  蓝牙芯片                                                 │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、蓝牙电话流程
+
+### 2.1 电话状态（7种）
+
+| 状态值 | 名称 | 说明 |
+|--------|------|------|
+| 0 | ACTIVE | 通话中 |
+| 1 | HELD | 保持中 |
+| 2 | DIALING | 正在拨号 |
+| 3 | ALERTING | 正在响铃 |
+| 4 | INCOMING | 正在来电 |
+| 5 | WAITING | 等待中 |
+| 7 | TERMINATED | 已挂断 |
+
+### 2.2 状态变化图
+
+```
+          来电                        拨号
+    ┌─────────→ INCOMING ─────────→ DIALING
+    │              │                  │
+    │          接听来电            对方接通
+    │              ↓                  ↓
+IDLE ─────────── ACTIVE ───────────────┘
+    │              │
+    │            挂断
+    │              ↓
+    └─────── TERMINATED
+```
+
+### 2.3 拨号调用流程
+
+```
+BluetoothHfpClient.dial()          ← 上层应用入口
+    ↓
+BluetoothHeadsetClient.dial()      ← Frameworks API
+    ↓ Binder
+BluetoothHeadsetClientBinder.dial()
+    ↓
+HeadsetClientService.dial()        ← 系统蓝牙服务(中转)
+    ↓
+HeadsetClientStateMachine.Connected.dial()
+    ↓
+NativeInterface.dial()             ← JNI接口
+    ↓
+com_android_bluetooth_hfpclient.dialNative()
+    ↓
+第三方SDK → 蓝牙芯片
+```
+
+### 2.4 数据回调流程（反向）
+
+```
+蓝牙芯片 → 第三方SDK
+    ↓ JNI回调
+NativeInterface (事件上报)
+    ↓
+HeadsetClientService (中转分发)
+    ↓ Event.type判断
+HeadsetClientStateMachine (业务处理)
+    ↓ 广播
+上层应用 BroadcastReceiver
+```
+
+---
+
+## 三、蓝牙音乐流程
+
+### 3.1 核心功能
+
+| 功能 | 说明 |
+|------|------|
+| 播放控制 | 播放/暂停/上一曲/下一曲 |
+| 音频焦点 | 与语音、导航、视频竞争焦点 |
+| 状态同步 | 播放状态同步给Launcher/投屏 |
+| 方控控制 | 方向盘按键控制音乐 |
+
+### 3.2 焦点竞争场景
+
+| 场景 | 处理 |
+|------|------|
+| 语音唤醒 | 蓝牙音乐暂停，释放焦点 |
+| 导航播报 | 蓝牙音乐降低音量/暂停 |
+| 视频播放 | 蓝牙音乐暂停 |
+| 倒车状态 | 蓝牙音乐暂停 |
+
+---
+
+## 四、通讯录同步流程
+
+### 4.1 核心协议
+
+| 协议 | 说明 |
+|------|------|
+| **PBAP** | Phone Book Access Profile，通讯录访问协议 |
+| **HFP** | Hands-Free Profile，电话免提协议 |
+
+### 4.2 同步限制
+
+| 类型 | 限制 |
+|------|------|
+| 通讯录 | 2500条，超出截断 |
+| 通话记录 | 50条 |
+
+### 4.3 同步流程
+
+```
+1. 连接蓝牙 → 触发PBAP连接请求
+2. 手机授权 → 开始拉取通讯录
+3. 分批接收 → 存入数据库
+4. 完成回调 → isPhoneBookPulling=false
+5. UI刷新 → 显示通讯录列表
+```
+
+### 4.4 核心类
+
+| 类名 | 作用 |
+|------|------|
+| BluetoothPbapClient | PBAP协议入口 |
+| BtContactsManager | 通讯录管理 |
+| isPhoneBookPulling | 同步状态标志 |
+
+---
+
+## 五、语音与蓝牙交互
+
+### 5.1 语音控制蓝牙功能
+
+| 功能 | 入口类 |
+|------|------|
+| 语音拨打电话 | VoiceEventHelper |
+| 语音拒接来电 | VoiceEventHelper |
+| 语音播放蓝牙音乐 | MediaProtocol |
+| 语音同步通讯录状态 | VoiceNewProtocolConst |
+
+### 5.2 状态同步给语音
+
+| 状态 | 同步方式 |
+|------|----------|
+| 蓝牙连接状态 | 广播通知语音 |
+| 来电状态 | 电话信息同步 |
+| 通讯录同步状态 | 页面打开/关闭状态 |
+
+---
+
+## 六、ACC电源处理
+
+### 6.1 处理策略
+
+| 场景 | 处理 |
+|------|------|
+| ACC OFF | 不主动断开蓝牙，保持原状态 |
+| ACC ON | 恢复连接状态，校验播放状态 |
+| 下电上电 | 播放按钮状态需重新同步 |
+
+### 6.2 常见问题
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| 上电后显示播放但实际没播 | 状态未校验 | 检查实际播放状态 |
+| 进蓝牙音乐界面会暂停 | 状态未同步 | 延迟校验播放状态 |
+
+---
+
+## 七、核心代码类索引
+
+### 7.1 电话相关
+
+| 类名                        | 路径           | 作用     |
+| ------------------------- | ------------ | ------ |
+| BluetoothHfpClient        | YX_Bluetooth | 电话功能入口 |
+| HeadsetClientService      | 系统应用         | 电话服务中转 |
+| HeadsetClientStateMachine | 系统应用         | 电话状态机  |
+
+### 7.2 音乐相关
+
+| 类名     | 作用                |
+| ------ | ----------------- |
+| 音频焦点管理 | AudioManager，焦点竞争 |
+| 投屏数据格式 | JSON格式传输给仪表       |
+
+### 7.3 语音交互
+
+| 类名                    | 作用          |
+| --------------------- | ----------- |
+| VoiceEventHelper      | 语音事件处理入口    |
+| MediaProtocol         | 媒体协议，蓝牙音乐状态 |
+| VoiceNewProtocolConst | TXZ语音协议常量   |
+
+---
+
+## 八、常见问题快速定位
+
+| 问题类型 | 关键类/方法 | 日志关键字 |
+|----------|-------------|------------|
+| 通讯录不同步 | BluetoothPbapClient.phoneBookPullRequest() | BtContactsManager, onContactsPullCompleted |
+| 音乐状态异常 | 音频焦点处理 | AudioManager, onFocusChange |
+| 语音拒接失败 | VoiceEventHelper拒接逻辑 | 蓝牙拒接, HFP |
+| ACC状态处理 | 电源状态监听 | ACC_OFF, ACC_ON |
+| 投屏数据异常 | JSON数据传输 | 投屏, DataCenter |
+| ANR问题 | 主线程阻塞 | ANR, SQLiteCursor |
+
+---
+
+## 九、开发注意事项
+
+### 9.1 通讯录同步
+
+- 完成后必须设置 `isPhoneBookPulling = false`
+- 同步过程需异步处理，避免阻塞UI
+- 通讯录超过2500条会截断
+
+### 9.2 音频焦点
+
+- 语音唤醒时蓝牙音乐必须释放焦点
+- 导航播报后需恢复播放状态
+- 倒车暂停需在倒车结束后恢复
+
+### 9.3 ACC电源
+
+- 不要在ACC OFF时主动断开蓝牙
+- 上电后需校验实际播放状态，避免状态不同步
+
+### 9.4 UI适配
+
+- 深色模式：联系人字母颜色需适配
+- 右舵项目：需单独布局资源
+- 12.3寸屏幕：需单独适配
+
+---
+
+## 十、参考文档
+
+| 文档 | 说明 |
+|------|------|
+| [[蓝牙框架原理以及数据通讯交互流程.pdf]] | 蓝牙框架层级详解 |
+| [[蓝牙电话交互流程解析.pdf]] | 电话状态和调用流程 |
+| [[徐工项目蓝牙模块主流程.xlsx]] | 主流程表格 |
+| [[徐工项目蓝牙模块交接说明.docx]] | 交接说明文档 |
+| [[bluetooth_git_summary.md]] | Git提交记录汇总 |
+
+---
+
+## 十一、Git提交统计
+
+> 统计时间: 2024-01-01 ~ 2026-05-06
+> 提交总数: 230条
+
+| 功能模块 | 提交数 | 主要内容 |
+|----------|--------|----------|
+| 语音与蓝牙交互 | 35条 | 语音控制、状态同步、音频焦点 |
+| 蓝牙音乐 | 25条 | 播放状态、投屏、焦点控制 |
+| 蓝牙电话 | 40条 | 来电/去电、通话状态、投屏 |
+| 通讯录同步 | 30条 | 同步流程、UI交互 |
+| 连接状态管理 | 20条 | ACC处理、可见性、配对 |
+| UI适配 | 35条 | 深色模式、右舵、国际化 |
+| 国际化 | 15条 | 翻译、多语言 |
+| 代码优化 | 15条 | 工具类统一、构建优化 |
+| Bug修复 | 15条 | ANR、崩溃、空指针 |