Obsidian/项目文档/同力/蓝牙/蓝牙业务迁移梳理_2026-07-09.md

# 蓝牙业务迁移梳理

日期：2026-07-09

## 1. 背景

目标是让新项目 `F:\zdCode\tongli` 的蓝牙业务交互、需求和 UI，与旧项目 `F:\zdCode\tongli_old` 保持一致。

用户强调：

```text
业务逻辑一样，代码可以不参考。
```

因此本次迁移不能只看代码能不能跑，而要按旧项目和截图确认：

- 用户入口是否一致
- 页面结构是否一致
- 操作路径是否一致
- 空状态/加载状态/错误状态是否一致
- 通话状态机是否一致
- 蓝牙音乐、设置、桌面卡片、状态栏是否联动一致

## 2. 已确认截图范围

截图里覆盖了以下 UI 和业务状态：

| 模块 | 页面/状态 |
|---|---|
| 蓝牙拨号 | 左侧菜单、数字键盘、拨号按钮、右侧通话记录列表 |
| 通话记录 | 正常列表、暂无记录、未同步、一键同步、正在同步 |
| 联系人 | 联系人列表、搜索、下载/同步、重新下载联系人弹窗 |
| 通话态 | 来电中、正在拨号、通话中、通话中键盘 |
| 三方通话 | 第二路来电、保持中、三方通话中 |
| 蓝牙音乐 | 歌曲信息、封面、进度、上一首、播放/暂停、下一首 |
| 蓝牙设置 | 自动接听、蓝牙开关、蓝牙名称、已配对设备、可用设备、修改名称 |
| 桌面联动 | 蓝牙电话卡片、蓝牙音乐卡片、状态栏蓝牙状态 |

## 3. 旧项目业务基线

旧项目路径：

```text
F:\zdCode\tongli_old
```

旧蓝牙模块：

```text
F:\zdCode\tongli_old\YX_BlueTooth
```

旧项目主入口：

```text
F:\zdCode\tongli_old\YX_BlueTooth\src\main\java\com\yaxon\bluetooth\main\MainActivity.java
```

旧项目四个一级入口：

| Tab | 常量 | 业务 |
|---|---|---|
| 蓝牙拨号 | `TAB_KEYBOARD = 0` | 数字拨号、拨出电话 |
| 联系人 | `TAB_PHONEBOOK = 1` | 联系人列表、搜索、同步 |
| 蓝牙音乐 | `TAB_BLUETOOTHMUSIC = 2` | A2DP/AVRCP 音乐播放 |
| 蓝牙设置 | `TAB_SETTING = 3` | 蓝牙开关、名称、配对、扫描 |
| 通话记录 | `TAB_PHONERECORD = 4` | 通话记录列表和分类 |

旧项目 Manifest 关键入口：

| 类型 | 名称 |
|---|---|
| 主界面 | `MainActivity` |
| 通话界面 | `PhoningActivity` |
| 语音/外部控制 | `VoiceSwitchReceiver`、`VoiceRecognizeReceiver`、`ExternalControlReceiver` |
| 蓝牙音乐控制 | `BluetoothMusicReceiver` |
| 联系人数据 | `BluetoothPhonebookProvider` |

旧通话状态：

| 常量 | 值 | 含义 |
|---|---:|---|
| `STATUS_ACTIVE` | 0 | 通话中 |
| `STATUS_HELD` | 1 | 保持中 |
| `STATUS_DIALING` | 2 | 正在拨号 |
| `STATUS_ALERTING` | 3 | 对方振铃 |
| `STATUS_INCOMING` | 4 | 来电 |
| `STATUS_WAITING` | 5 | 等待来电/三方来电 |

旧通话动作：

- 拨号
- 挂断
- 接听
- 拒接
- 麦克风静音
- 车机/手机音频切换
- DTMF 小键盘
- 三方增强通话控制

旧联系人/通话记录能力：

- 联系人同步
- 重新下载联系人确认弹窗
- 联系人搜索
- 通话记录同步
- 通话记录分类：全部、拨出、已接、未接
- 点击联系人/通话记录拨号

旧音乐能力：

- 标题
- 歌手
- 时长
- 当前进度
- 上一首
- 播放/暂停
- 下一首

旧设置能力：

- 自动接听
- 蓝牙开关
- 蓝牙名称
- 已配对设备
- 附近/可用设备
- 搜索设备
- 连接/断开/删除设备

## 4. 新项目承接点

新项目路径：

```text
F:\zdCode\tongli
```

### 4.1 蓝牙电话 App

模块：

```text
F:\zdCode\tongli\YX_BlueTooth
```

关键文件：

| 文件 | 作用 |
|---|---|
| `YX_BlueTooth\src\main\AndroidManifest.xml` | 蓝牙电话模块入口 |
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\main\MainActivity.java` | 主拨号/通话记录/联系人页面 |
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\main\BluetoothPhoneActivity.java` | 通话界面 |
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\fragment\CallLogsFragment.java` | 通话记录 |
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\fragment\ContactsFragment.java` | 联系人 |
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\dialog\BtSettingDialog.java` | 蓝牙设置弹窗 |
| `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\service\BluetoothService.java` | 后台服务和来电窗口联动 |

新项目主界面当前 Tab：

| Tab | 常量 | 当前业务 |
|---|---|---|
| 通话记录 | `TAB_CALL_LOGS = 0` | 右侧通话记录 |
| 联系人 | `TAB_CONTACTS = 1` | 右侧通讯录 |
| 拨号键盘 | `TAB_KEYBOARD = 2` | 左侧拨号键盘 |

说明：

新项目主界面已经不是旧项目四个一级 Tab 结构，而是左侧拨号键盘 + 右侧通话记录/联系人切换。后续要确认 UI 是否必须完全恢复旧截图里的左侧菜单结构：

```text
蓝牙拨号 / 联系人 / 蓝牙音乐 / 蓝牙设置
```

### 4.2 通话状态

新项目通话状态：

| 新常量 | 值 | 对应旧状态 |
|---|---:|---|
| `CALL_STATE_ACTIVE` | 0 | `STATUS_ACTIVE` |
| `CALL_STATE_HELD` | 1 | `STATUS_HELD` |
| `CALL_STATE_DIALING` | 2 | `STATUS_DIALING` |
| `CALL_STATE_ALERTING` | 3 | `STATUS_ALERTING` |
| `CALL_STATE_INCOMING` | 4 | `STATUS_INCOMING` |
| `CALL_STATE_WAITING` | 5 | `STATUS_WAITING` |
| `CALL_STATE_TERMINATED` | 7 | 旧项目无显式同名常量，表示结束 |

关键承接文件：

| 文件 | 作用 |
|---|---|
| `BluetoothPhoneActivity.java` | 全屏通话界面 |
| `BluetoothPhoneViewModel.java` | 通话状态和动作控制 |
| `TelephoneWindowControl.java` | 通话窗口控制 |
| `ThirdCallingControl.java` | 三方通话/等待来电控制 |
| `ThirdCallControlView.java` | 三方通话控制视图 |

### 4.3 蓝牙 SDK

模块：

```text
F:\zdCode\tongli\YX_BluetoothSDK
```

关键管理类：

| 类 | 作用 |
|---|---|
| `BtPhoneManager` | HFP 电话状态管理 |
| `BtContactsManager` | 联系人/PBAP |
| `BtCallRecordsManager` | 通话记录 |
| `BtMusicManager` | 蓝牙音乐 |
| `BtSettingManager` | 蓝牙开关、名称、设备状态 |
| `BtInfoPushManager` | 状态推送 |
| `BtVoiceManager` | 语音控制 |

关键控制类：

| 类 | 作用 |
|---|---|
| `BtPhoneControlManager` | 拨号、接听、挂断、拒接、DTMF 等 |
| `BtContactsControlManager` | 联系人控制 |
| `BtCallRecordsControlManager` | 通话记录控制 |
| `BtMusicControlManager` | 播放、暂停、上一首、下一首 |
| `BtSettingControlManager` | 蓝牙开关、连接、断开、配对 |
| `BtPairedControlManager` | 已配对设备 |

结论：新平台应优先使用 SDK 的 manager/control manager，不建议搬旧项目底层实现。

### 4.4 蓝牙音乐

新项目有两个承接点：

| 模块 | 文件 | 说明 |
|---|---|---|
| `YX_BtMusic` | `YX_BtMusic\src\main\java\com\yaxon\btmusic\main\MainActivity.java` | 独立蓝牙音乐 App |
| `YX_BlueTooth` | `YX_BlueTooth\src\main\java\com\yaxon\bluetooth\main\BluetoothMusicActivity.java` | 蓝牙电话模块内也存在音乐 Activity |

当前需要确认：

```text
点击截图左侧“蓝牙音乐”时，是在蓝牙 App 内切换，还是跳转独立 YX_BtMusic？
```

### 4.5 Launcher / SystemUI 联动

桌面卡片：

| 文件 | 作用 |
|---|---|
| `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` | 状态栏蓝牙图标、快捷开关 |
| `YX_SystemUISDK` | SystemUI 控制器 |

需要验收：

- 蓝牙开关状态是否同步到下拉快捷栏。
- 已连接/未连接状态是否同步到桌面卡片。
- 蓝牙音乐播放状态是否同步到桌面音乐卡片。

## 5. 业务交互基线表

| 模块 | 页面/状态 | 用户动作 | 期望结果 | 新项目承接 | 风险 |
|---|---|---|---|---|---|
| 蓝牙拨号 | 数字键盘 | 点击数字 | 输入框追加号码 | `MainActivity` + `KeyBoardView` | UI 结构需对齐截图 |
| 蓝牙拨号 | 删除号码 | 点击删除 | 删除最后一位 | `KeyBoardView` | 长按清空是否支持待查 |
| 蓝牙拨号 | 发起呼叫 | 点击绿色拨号 | 进入正在拨号页 | `BtPhoneControlManager` / `BluetoothPhoneActivity` | 未连接时提示需统一 |
| 通话记录 | 正常列表 | 点击记录 | 使用该号码拨号 | `CallLogsFragment` | 记录合并/分类需验收 |
| 通话记录 | 暂无记录 | 无记录 | 显示暂无记录 | `CallLogsFragment` | 空状态文案/图标需对齐 |
| 通话记录 | 未同步 | 未下载记录 | 显示一键同步 | `CallHistoryViewModel` | 是否自动同步需确认 |
| 通话记录 | 正在同步 | 点击同步 | 显示同步中 | `CallLogsFragment` | 超时/失败状态需补齐 |
| 联系人 | 正常列表 | 点击联系人 | 拨打联系人号码 | `ContactsFragment` | 多号码联系人行为待确认 |
| 联系人 | 搜索 | 输入关键字 | 按名称/号码/拼音搜索 | `ContactListViewModel` | 需验中文、拼音、数字 |
| 联系人 | 重新下载 | 点击下载图标 | 弹出确认框 | `ContactsFragment` | 弹窗样式需对齐截图 |
| 来电 | 来电中 | 接听 | 进入通话中 | `BluetoothPhoneActivity` | 倒车/AVM 场景窗口策略需验收 |
| 来电 | 来电中 | 拒接 | 结束来电 | `BluetoothPhoneViewModel` | 单路/三方状态不同 |
| 拨出 | 正在拨号 | 挂断 | 结束拨号 | `BluetoothPhoneActivity` | alerting/dialing 显示需统一 |
| 通话中 | 静音 | 点击麦克风 | 麦克风静音/取消静音 | `BluetoothPhoneViewModel` | 状态图标需对齐 |
| 通话中 | 音频切换 | 点击车机/手机 | SCO 在车机/手机间切换 | `BluetoothPhoneViewModel` | 需实车或蓝牙设备验证 |
| 通话中 | DTMF | 打开小键盘 | 发送 DTMF 按键 | `BluetoothPhoneViewModel` | DTMF 兼容性需验收 |
| 三方通话 | 第二路来电 | 接听/拒接/保持 | 状态正确切换 | `ThirdCallingControl` | 高风险，必须实测 |
| 蓝牙音乐 | 播放页 | 播放/暂停 | AVRCP 控制手机音乐 | `BtMusicViewModel` | 有两个音乐 Activity，入口需确认 |
| 蓝牙音乐 | 歌曲信息 | 手机切歌 | 标题/歌手/进度刷新 | `BtMusicControlManager` | 部分手机元数据为空 |
| 蓝牙设置 | 蓝牙开关 | 打开/关闭 | 蓝牙状态变化 | `BtSettingDialog` | 截图是页面式，当前是弹窗式 |
| 蓝牙设置 | 修改名称 | 输入新名称 | 本机蓝牙名更新 | `BtSettingViewModel` | 修改名称入口需对齐 |
| 蓝牙设置 | 可用设备 | 搜索/点击设备 | 配对或连接 | `BtSettingViewModel` | 连接超时/失败提示需统一 |
| 桌面卡片 | 蓝牙电话卡片 | 点击卡片 | 进入蓝牙电话 | `BluetoothCardView` | 状态同步需验收 |
| 桌面卡片 | 蓝牙音乐卡片 | 点击卡片 | 进入蓝牙音乐 | `BluetoothMusicCardView` | 包名/入口需确认 |
| 状态栏 | 快捷蓝牙 | 点击开关 | 打开/关闭蓝牙 | `YX_SystemUI` | 与蓝牙 App 状态需同步 |

## 6. 当前初步缺口

### 6.1 入口结构缺口

旧项目左侧一级入口是：

```text
蓝牙拨号 / 联系人 / 蓝牙音乐 / 蓝牙设置
```

新项目主界面当前更像：

```text
拨号键盘 + 通话记录/通讯录二级切换
```

要确认是否需要把新项目 UI 改回截图结构，至少视觉上应保持一致。

### 6.2 设置形态缺口

截图里的蓝牙设置是完整页面区域：

- 自动接听
- 蓝牙开关
- 蓝牙名称
- 已配对设备
- 可用设备

新项目目前主要是 `BtSettingDialog` 弹窗式承接。

需要确认：

```text
设置必须做成截图里的完整页面，还是弹窗也可接受？
```

### 6.3 蓝牙音乐入口缺口

新项目同时存在：

- `YX_BtMusic`
- `YX_BlueTooth\BluetoothMusicActivity`

必须统一入口和状态来源，避免一个入口播放状态正常，另一个入口不同步。

### 6.4 三方通话高风险

三方通话是最容易出现状态错乱的地方：

- 单路来电
- 通话中第二路来电
- 一路保持一路激活
- 接听第二路并挂断第一路
- 挂断当前保留保持中通话

这一块必须实测，不能只靠 UI 静态对齐。

## 7. 建议开发顺序

### 第一阶段：冻结需求和页面资产

输出并确认：

- 页面清单
- 弹窗清单
- 图标清单
- 状态清单
- 入口跳转清单
- Launcher/SystemUI 联动清单

### 第二阶段：主流程 UI 对齐

优先对齐：

1. 蓝牙拨号
2. 通话记录
3. 联系人
4. 来电/拨号/通话中

### 第三阶段：高风险业务对齐

重点处理：

1. 三方通话
2. 联系人/通话记录同步状态
3. 蓝牙设置设备连接状态
4. 蓝牙音乐播放状态同步

### 第四阶段：系统级联动

验证：

1. 桌面蓝牙电话卡片
2. 桌面蓝牙音乐卡片
3. 状态栏蓝牙图标
4. 下拉快捷蓝牙开关
5. 开机自启动服务

## 8. 明天继续时优先做什么

建议下一步直接做两件事：

1. 输出《蓝牙页面资产清单》
   - 页面
   - 弹窗
   - 空状态
   - 加载状态
   - 错误状态
   - 按钮状态
   - 图标状态

2. 输出《新旧项目功能缺口表》
   - 已具备，需验收
   - 已具备，但 UI 不一致
   - 业务可能缺失
   - 高风险必须实测
   - 可以延后处理

## 9. 后续开发前需要确认的问题

1. 新项目蓝牙主界面是否必须恢复旧截图的四个左侧入口？
2. 蓝牙设置是做完整页面，还是保留当前弹窗式？
3. 蓝牙音乐入口以 `YX_BtMusic` 为准，还是以 `YX_BlueTooth\BluetoothMusicActivity` 为准？
4. 是否需要完全复刻截图背景、图标和尺寸，还是只对齐交互和业务？
5. 是否需要兼容方向盘按键、语音控制、ITS/EasyConn 外部控制？

## 10. 重要提醒

进入开发阶段前，需要再次确认是否备份。

当前文档只是梳理，不代表已经完成代码修改。