Obsidian/项目文档/同力/蓝牙/蓝牙开发实施方案_2026-07-09.md

蓝牙开发实施方案

日期：2026-07-09

1. 开发目标

在新项目 F:\zdCode\tongli 上开发蓝牙功能，使蓝牙业务交互、需求和 UI 与旧项目 F:\zdCode\tongli_old 保持一致。

用户要求：

业务逻辑一样，UI 和需求跟老项目一致，代码可以不参考。

因此开发策略是：

旧项目 = 需求基线和验收标准
新项目 = 实现架构和平台能力

不建议搬旧代码，不建议重写底层蓝牙栈。应优先使用新项目已有 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 开始大改，而应：

页面结构对齐
-> 状态和交互对齐
-> ViewModel 调用补齐
-> SDK 缺口验证
-> 系统联动验收

3. 模块拆分

蓝牙功能按以下模块推进：

模块	目标
主界面导航	对齐旧项目/截图入口结构
蓝牙拨号	数字输入、拨号、删除、未连接提示
通话记录	记录列表、分类、同步、空状态、点击拨号
联系人	同步、搜索、重新下载、点击拨号
通话界面	来电、拨出、通话中、静音、音频切换、DTMF
三方通话	第二路来电、等待、保持、释放当前接听另一通
蓝牙音乐	歌曲信息、进度、播放控制、未连接状态
蓝牙设置	自动接听、开关、名称、配对、扫描、连接/断开
Launcher 联动	蓝牙电话卡片、蓝牙音乐卡片
SystemUI 联动	状态栏图标、快捷蓝牙开关

4. 推荐开发顺序

阶段 1：冻结页面资产和需求

先产出并确认以下清单：

• 页面清单
• 弹窗清单
• 图标清单
• 按钮清单
• 空状态清单
• 加载状态清单
• 错误状态清单
• 路由/入口清单
• Launcher/SystemUI 联动清单

阶段目标：

开发前知道每个页面长什么样、有哪些状态、点击后去哪里。

阶段 2：主界面 UI 结构对齐

旧项目和截图里的主入口更接近：

蓝牙拨号
联系人
蓝牙音乐
蓝牙设置

新项目当前主界面更接近：

左侧拨号键盘 + 右侧通话记录/通讯录二级切换

这里需要先做产品决策：

1. 如果要求 UI 完全跟老项目/截图一致，应把新项目 MainActivity 的入口视觉改成四项左侧菜单。
2. 如果只要求业务一致，当前结构可以保留，但必须补齐蓝牙音乐和蓝牙设置入口。

建议：

优先按截图恢复四个左侧入口。
通话记录可以作为蓝牙拨号页右侧区域或拨号页内二级状态。

涉及文件：

文件	说明
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：电话核心流程

先保证最基础电话链路可用：

输入号码
-> 点击拨号
-> 进入拨号中
-> 对方接听
-> 通话中
-> 挂断
-> 返回/关闭通话页

再补：

• 来电接听
• 来电拒接
• 通话中静音
• 车机/手机音频切换
• 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. 第二路来电号码/名称显示是否正确。

风险：

三方通话最依赖手机、HFP 协议栈和平台蓝牙实现，不能只靠静态代码判断。
必须用真实手机或稳定蓝牙测试设备验证。

阶段 6：蓝牙音乐

需要先统一入口：

蓝牙音乐入口到底打开 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。

建议：

如果 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 外部控制。