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

# 蓝牙开发实施方案

日期：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 外部控制。