505 lines
13 KiB
Markdown
505 lines
13 KiB
Markdown
# 蓝牙开发实施方案
|
||
|
||
日期：2026-07-09
|
||
|
||
## 1. 开发目标
|
||
|
||
在新项目 `F:\zdCode\tongli` 上开发蓝牙功能，使蓝牙业务交互、需求和 UI 与旧项目 `F:\zdCode\tongli_old` 保持一致。
|
||
|
||
用户要求：
|
||
|
||
```text
|
||
业务逻辑一样，UI 和需求跟老项目一致，代码可以不参考。
|
||
```
|
||
|
||
因此开发策略是：
|
||
|
||
```text
|
||
旧项目 = 需求基线和验收标准
|
||
新项目 = 实现架构和平台能力
|
||
```
|
||
|
||
不建议搬旧代码，不建议重写底层蓝牙栈。应优先使用新项目已有 `YX_BluetoothSDK`、ViewModel、Activity、Service 架构补齐业务和 UI。
|
||
|
||
## 2. 总体开发原则
|
||
|
||
### 2.1 老项目只做业务参考
|
||
|
||
老项目重点参考：
|
||
|
||
- 页面入口
|
||
- 操作路径
|
||
- 通话状态机
|
||
- 联系人/通话记录同步流程
|
||
- 蓝牙音乐控制
|
||
- 蓝牙设置和设备管理
|
||
- 三方通话/第二路来电行为
|
||
- 空状态、加载状态、弹窗和提示
|
||
|
||
不直接复制：
|
||
|
||
- 老项目 `BtAdapterManager` 底层实现
|
||
- 老项目老式 Activity/Fragment 结构
|
||
- 老项目 Android 4.4 平台兼容写法
|
||
|
||
### 2.2 新项目保持现有架构
|
||
|
||
新项目优先使用：
|
||
|
||
| 能力 | 新项目承接 |
|
||
| -------- | ---------------------------------------------------- |
|
||
| 蓝牙电话 | `YX_BlueTooth` |
|
||
| 蓝牙 SDK | `YX_BluetoothSDK` |
|
||
| 蓝牙音乐 | `YX_BtMusic` 或 `YX_BlueTooth\BluetoothMusicActivity` |
|
||
| 桌面卡片 | `YX_Launcher` |
|
||
| 状态栏/快捷开关 | `YX_SystemUI` |
|
||
|
||
核心调用应走：
|
||
|
||
| 功能 | 控制类 |
|
||
| ---------------- | ----------------------------- |
|
||
| 拨号/接听/挂断/拒接/DTMF | `BtPhoneControlManager` |
|
||
| 联系人 | `BtContactsControlManager` |
|
||
| 通话记录 | `BtCallRecordsControlManager` |
|
||
| 蓝牙音乐 | `BtMusicControlManager` |
|
||
| 蓝牙设置/设备连接 | `BtSettingControlManager` |
|
||
| 已配对设备 | `BtPairedControlManager` |
|
||
|
||
### 2.3 先页面后底层
|
||
|
||
开发顺序不应从底层 SDK 开始大改，而应：
|
||
|
||
```text
|
||
页面结构对齐
|
||
-> 状态和交互对齐
|
||
-> ViewModel 调用补齐
|
||
-> SDK 缺口验证
|
||
-> 系统联动验收
|
||
```
|
||
|
||
## 3. 模块拆分
|
||
|
||
蓝牙功能按以下模块推进：
|
||
|
||
| 模块 | 目标 |
|
||
|---|---|
|
||
| 主界面导航 | 对齐旧项目/截图入口结构 |
|
||
| 蓝牙拨号 | 数字输入、拨号、删除、未连接提示 |
|
||
| 通话记录 | 记录列表、分类、同步、空状态、点击拨号 |
|
||
| 联系人 | 同步、搜索、重新下载、点击拨号 |
|
||
| 通话界面 | 来电、拨出、通话中、静音、音频切换、DTMF |
|
||
| 三方通话 | 第二路来电、等待、保持、释放当前接听另一通 |
|
||
| 蓝牙音乐 | 歌曲信息、进度、播放控制、未连接状态 |
|
||
| 蓝牙设置 | 自动接听、开关、名称、配对、扫描、连接/断开 |
|
||
| Launcher 联动 | 蓝牙电话卡片、蓝牙音乐卡片 |
|
||
| SystemUI 联动 | 状态栏图标、快捷蓝牙开关 |
|
||
|
||
## 4. 推荐开发顺序
|
||
|
||
### 阶段 1：冻结页面资产和需求
|
||
|
||
先产出并确认以下清单：
|
||
|
||
- 页面清单
|
||
- 弹窗清单
|
||
- 图标清单
|
||
- 按钮清单
|
||
- 空状态清单
|
||
- 加载状态清单
|
||
- 错误状态清单
|
||
- 路由/入口清单
|
||
- Launcher/SystemUI 联动清单
|
||
|
||
阶段目标：
|
||
|
||
```text
|
||
开发前知道每个页面长什么样、有哪些状态、点击后去哪里。
|
||
```
|
||
|
||
### 阶段 2：主界面 UI 结构对齐
|
||
|
||
旧项目和截图里的主入口更接近：
|
||
|
||
```text
|
||
蓝牙拨号
|
||
联系人
|
||
蓝牙音乐
|
||
蓝牙设置
|
||
```
|
||
|
||
新项目当前主界面更接近：
|
||
|
||
```text
|
||
左侧拨号键盘 + 右侧通话记录/通讯录二级切换
|
||
```
|
||
|
||
这里需要先做产品决策：
|
||
|
||
1. 如果要求 UI 完全跟老项目/截图一致，应把新项目 `MainActivity` 的入口视觉改成四项左侧菜单。
|
||
2. 如果只要求业务一致，当前结构可以保留，但必须补齐蓝牙音乐和蓝牙设置入口。
|
||
|
||
建议：
|
||
|
||
```text
|
||
优先按截图恢复四个左侧入口。
|
||
通话记录可以作为蓝牙拨号页右侧区域或拨号页内二级状态。
|
||
```
|
||
|
||
涉及文件：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\main\MainActivity.java` | 主界面控制 |
|
||
| `YX_BlueTooth\src\main\res\layout\activity_main.xml` | 主界面布局 |
|
||
| `YX_BlueTooth\src\main\res\layout\fragment_call_logs.xml` | 通话记录 |
|
||
| `YX_BlueTooth\src\main\res\layout\fragment_contacts.xml` | 联系人 |
|
||
|
||
### 阶段 3：电话核心流程
|
||
|
||
先保证最基础电话链路可用：
|
||
|
||
```text
|
||
输入号码
|
||
-> 点击拨号
|
||
-> 进入拨号中
|
||
-> 对方接听
|
||
-> 通话中
|
||
-> 挂断
|
||
-> 返回/关闭通话页
|
||
```
|
||
|
||
再补：
|
||
|
||
- 来电接听
|
||
- 来电拒接
|
||
- 通话中静音
|
||
- 车机/手机音频切换
|
||
- DTMF 小键盘
|
||
- 未连接时禁止拨号并提示
|
||
|
||
涉及文件：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `BluetoothPhoneActivity.java` | 通话全屏页 |
|
||
| `BluetoothPhoneViewModel.java` | 电话动作和状态 |
|
||
| `TelephoneWindowControl.java` | 电话窗口 |
|
||
| `view_keyboard_dial.xml` | 拨号键盘 |
|
||
| `view_keyboard_dtmf.xml` | DTMF 键盘 |
|
||
| `view_control_calling.xml` | 通话控制按钮 |
|
||
|
||
验收重点：
|
||
|
||
- 来电显示号码/联系人名称
|
||
- 拨出显示号码/联系人名称
|
||
- 通话计时正确
|
||
- 静音图标状态正确
|
||
- 车机/手机音频图标状态正确
|
||
- DTMF 按键能发出
|
||
- 断开蓝牙时通话页正确关闭或提示
|
||
|
||
### 阶段 4：联系人和通话记录
|
||
|
||
联系人：
|
||
|
||
- 未同步状态
|
||
- 一键同步
|
||
- 正在同步
|
||
- 同步成功
|
||
- 同步失败
|
||
- 空联系人
|
||
- 搜索联系人
|
||
- 搜索无结果
|
||
- 重新下载联系人确认弹窗
|
||
- 点击联系人拨号
|
||
|
||
通话记录：
|
||
|
||
- 未同步状态
|
||
- 一键同步
|
||
- 正在同步
|
||
- 同步成功
|
||
- 暂无记录
|
||
- 全部/拨出/已接/未接分类
|
||
- 点击通话记录拨号
|
||
|
||
涉及文件：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `ContactsFragment.java` | 联系人 UI |
|
||
| `ContactListViewModel.java` | 联系人业务 |
|
||
| `CallLogsFragment.java` | 通话记录 UI |
|
||
| `CallHistoryViewModel.java` | 通话记录业务 |
|
||
| `listitem_phonebook.xml` | 联系人条目 |
|
||
| `listitem_phonerecord.xml` | 通话记录条目 |
|
||
|
||
验收重点：
|
||
|
||
- 蓝牙未连接时显示正确状态
|
||
- 手机未授权 PBAP 时提示合理
|
||
- 同步中不能重复触发多次
|
||
- 搜索支持名称、号码、拼音/首字母
|
||
- 点击条目拨号行为一致
|
||
|
||
### 阶段 5：三方通话专项
|
||
|
||
老项目明确支持第二路来电/三方通话相关行为：
|
||
|
||
- `SECOND_PHONE_IN`
|
||
- `SECOND_PHONE_PICKUP_OR_REJECT`
|
||
- `STATUS_WAITING`
|
||
- `STATUS_HELD`
|
||
- `EnhancedCallCtrl`
|
||
- `RELEASE_ACTIVE_AND_ACCEPT_OTHER`
|
||
|
||
新项目已有承接：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `ThirdCallingControl.java` | 三方通话/第二路来电控制 |
|
||
| `ThirdCallControlView.java` | 三方通话控制视图 |
|
||
| `BluetoothPhoneViewModel.java` | 多通话状态处理 |
|
||
| `BluetoothPhoneActivity.java` | 通话状态显示 |
|
||
|
||
必须单独验收以下场景：
|
||
|
||
1. 无通话时来电。
|
||
2. 通话中第二路来电。
|
||
3. 拒接第二路来电。
|
||
4. 接听第二路并挂断当前。
|
||
5. 接听第二路并保持当前。
|
||
6. 当前一路 active，另一路 held。
|
||
7. 挂断 active 后 held 是否恢复。
|
||
8. 第二路来电号码/名称显示是否正确。
|
||
|
||
风险：
|
||
|
||
```text
|
||
三方通话最依赖手机、HFP 协议栈和平台蓝牙实现，不能只靠静态代码判断。
|
||
必须用真实手机或稳定蓝牙测试设备验证。
|
||
```
|
||
|
||
### 阶段 6：蓝牙音乐
|
||
|
||
需要先统一入口：
|
||
|
||
```text
|
||
蓝牙音乐入口到底打开 YX_BtMusic，还是 YX_BlueTooth 内的 BluetoothMusicActivity？
|
||
```
|
||
|
||
建议：
|
||
|
||
- 如果项目已有独立 `YX_BtMusic` 桌面入口，主入口可以跳转 `YX_BtMusic`。
|
||
- 如果要求完全贴近老项目“蓝牙 App 内四项菜单”，可以在 `YX_BlueTooth` 内保留音乐页面或 Activity。
|
||
- 不建议两个入口长期并存不同逻辑，应统一 ViewModel 和 SDK 状态来源。
|
||
|
||
功能验收：
|
||
|
||
- 未连接 A2DP 时显示未连接状态
|
||
- 点击连接按钮进入设置或连接流程
|
||
- 标题/歌手/封面刷新
|
||
- 播放/暂停状态刷新
|
||
- 上一首/下一首可用
|
||
- 进度和总时长显示
|
||
- 手机端切歌后车机 UI 同步
|
||
|
||
涉及文件：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `YX_BtMusic\src\main\java\com\yaxon\btmusic\main\MainActivity.java` | 独立蓝牙音乐页 |
|
||
| `YX_BtMusic\src\main\java\com\yaxon\btmusic\mvvm\BtMusicViewModel.java` | 独立音乐业务 |
|
||
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\main\BluetoothMusicActivity.java` | 蓝牙模块内音乐页 |
|
||
| `BtMusicControlManager` | 蓝牙音乐控制 |
|
||
|
||
### 阶段 7：蓝牙设置和设备管理
|
||
|
||
截图里的蓝牙设置是页面式：
|
||
|
||
- 自动接听
|
||
- 蓝牙开关
|
||
- 蓝牙名称
|
||
- 已配对设备
|
||
- 可用设备
|
||
- 修改名称
|
||
|
||
新项目当前主要承接是 `BtSettingDialog`。
|
||
|
||
建议：
|
||
|
||
```text
|
||
如果 UI 必须跟截图一致，应做成完整设置页面或主界面右侧设置页。
|
||
如果只要求功能一致，可以先保留 BtSettingDialog，再统一视觉。
|
||
```
|
||
|
||
功能验收：
|
||
|
||
- 蓝牙开关可打开/关闭
|
||
- 本机蓝牙名称显示正确
|
||
- 本机蓝牙名称可修改
|
||
- 已配对设备显示正确
|
||
- 可用设备扫描和刷新
|
||
- 点击设备可配对/连接
|
||
- 已连接设备可断开
|
||
- 连接中、连接失败、连接成功状态正确
|
||
- 自动接听开关生效
|
||
|
||
涉及文件：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `BtSettingDialog.java` | 设置 UI |
|
||
| `BtSettingViewModel.java` | 设置业务 |
|
||
| `dialog_bt_setting.xml` | 设置弹窗布局 |
|
||
| `item_btdev_forum.xml` | 已配对设备条目 |
|
||
| `item_btdev_scaned.xml` | 可用设备条目 |
|
||
|
||
### 阶段 8：Launcher/SystemUI 联动
|
||
|
||
需要纳入最终验收，而不是蓝牙 App 做完就结束。
|
||
|
||
Launcher：
|
||
|
||
- 蓝牙电话卡片显示连接/未连接
|
||
- 蓝牙音乐卡片显示播放状态
|
||
- 点击卡片打开正确 App
|
||
|
||
SystemUI：
|
||
|
||
- 状态栏蓝牙图标显示已连接/未连接
|
||
- 下拉快捷蓝牙开关可打开/关闭
|
||
- 快捷开关状态和蓝牙 App 状态一致
|
||
|
||
涉及文件：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `YX_Launcher\src\main\res\layout\card_bluetooth.xml` | 蓝牙电话卡片 |
|
||
| `YX_Launcher\src\main\res\layout\card_bluetoothmusic.xml` | 蓝牙音乐卡片 |
|
||
| `YX_Launcher\src\main\java\com\yaxon\launcher\card\BluetoothCardView.java` | 蓝牙卡片 |
|
||
| `YX_Launcher\src\main\java\com\yaxon\launcher\card\BluetoothMusicCardView.java` | 蓝牙音乐卡片 |
|
||
| `YX_SystemUI` | 状态栏和快捷开关 |
|
||
|
||
## 5. 关键风险
|
||
|
||
| 风险 | 说明 | 建议 |
|
||
|---|---|---|
|
||
| UI 入口结构不一致 | 新项目入口结构和旧项目不同 | 先确认四项左侧菜单是否必须恢复 |
|
||
| 蓝牙音乐双入口 | `YX_BtMusic` 和 `BluetoothMusicActivity` 并存 | 统一入口和状态来源 |
|
||
| 设置形态不一致 | 截图是页面式，新项目是弹窗式 | 先确认产品要求 |
|
||
| 三方通话复杂 | 依赖手机、协议栈、平台实现 | 单独实测 |
|
||
| PBAP 授权 | 手机可能未授权联系人/通话记录 | 做未授权和同步失败提示 |
|
||
| SystemUI 状态同步 | 蓝牙开关和连接状态可能不同步 | 最后做系统级联动验收 |
|
||
| 旧项目编码/架构老 | 直接搬代码风险高 | 只抽业务行为 |
|
||
|
||
## 6. 开发验收清单
|
||
|
||
### 6.1 蓝牙拨号
|
||
|
||
- 输入号码显示正确
|
||
- 删除号码正确
|
||
- 点击拨号进入拨出页
|
||
- 未连接时不拨号并提示
|
||
- 联系人匹配显示正确
|
||
|
||
### 6.2 通话流程
|
||
|
||
- 来电可接听
|
||
- 来电可拒接
|
||
- 拨出可挂断
|
||
- 通话中可挂断
|
||
- 通话中计时正确
|
||
- 静音可切换
|
||
- 车机/手机音频可切换
|
||
- DTMF 可发送
|
||
|
||
### 6.3 三方通话
|
||
|
||
- 第二路来电能显示
|
||
- 第二路来电可拒接
|
||
- 第二路来电可接听
|
||
- 当前通话可保持
|
||
- 当前通话可释放并接听另一通
|
||
- held/active 状态显示正确
|
||
|
||
### 6.4 联系人
|
||
|
||
- 未同步状态正确
|
||
- 同步中状态正确
|
||
- 同步成功列表正确
|
||
- 同步失败提示正确
|
||
- 搜索正确
|
||
- 重新下载弹窗正确
|
||
- 点击联系人拨号正确
|
||
|
||
### 6.5 通话记录
|
||
|
||
- 未同步状态正确
|
||
- 同步中状态正确
|
||
- 暂无记录状态正确
|
||
- 记录列表正确
|
||
- 记录类型图标正确
|
||
- 点击记录拨号正确
|
||
|
||
### 6.6 蓝牙音乐
|
||
|
||
- 未连接状态正确
|
||
- 播放/暂停正确
|
||
- 上一首/下一首正确
|
||
- 标题/歌手/封面正确
|
||
- 进度/总时长正确
|
||
- 手机端状态变化能同步
|
||
|
||
### 6.7 蓝牙设置
|
||
|
||
- 蓝牙开关正确
|
||
- 蓝牙名称显示正确
|
||
- 蓝牙名称可修改
|
||
- 已配对设备列表正确
|
||
- 可用设备扫描正确
|
||
- 连接/断开正确
|
||
- 连接失败/超时提示正确
|
||
- 自动接听生效
|
||
|
||
### 6.8 系统联动
|
||
|
||
- 桌面蓝牙卡片状态正确
|
||
- 桌面蓝牙音乐卡片状态正确
|
||
- 状态栏蓝牙图标正确
|
||
- 下拉快捷蓝牙开关正确
|
||
- 开机后蓝牙服务正常启动
|
||
|
||
## 7. 建议下一步
|
||
|
||
下一步不要直接改代码，建议先输出两份更细文档：
|
||
|
||
1. `蓝牙页面资产清单`
|
||
- 页面
|
||
- 弹窗
|
||
- 图标
|
||
- 按钮
|
||
- 空状态
|
||
- 加载状态
|
||
- 错误状态
|
||
|
||
2. `蓝牙新旧功能缺口表`
|
||
- 老项目能力
|
||
- 新项目现状
|
||
- 缺口
|
||
- 影响文件
|
||
- 优先级
|
||
- 验收方式
|
||
|
||
确认后再进入代码开发。
|
||
|
||
## 8. 开发前必须确认
|
||
|
||
进入代码修改前，需要再次确认：
|
||
|
||
1. 是否备份。
|
||
2. 是否要求 UI 像素级复刻截图。
|
||
3. 蓝牙音乐入口以哪个模块为准。
|
||
4. 蓝牙设置使用页面式还是弹窗式。
|
||
5. 是否必须覆盖方向盘、语音、ITS/EasyConn 外部控制。
|