Wx_BLWConfigTools_V02_Prod/Document/BLV_RQ蓝牙通信控制页面实施文档.md

# BLV_RQ 蓝牙通信控制页面实施文档

- 归档日期：2026年3月19日
- 适用项目：`Wx_BLWConfigTools_V02_Prod`
- 参考协议：`Document/RF_RQ2603 蓝牙通讯协议.md`
- 当前状态：已确认，待进入代码实现

---

## 一、实施目标

为 `BLV_RQ` 设备新增独立的蓝牙通信控制页面，用于完成以下能力：

1. 展示 BLE 连接信息
2. 读取设备版本信息
3. 设置蓝牙名称
4. 读取按键配置
5. 设置按键功能与按键映射
6. 基于映射关系执行按键控制
7. 查看、清空、导出通信日志

页面采用**从上到下的单屏结构**，页面自身不做上下滚动；若日志区需要展示更多内容，仅允许日志内容区内部滚动。

---

## 二、已确认实施约束

1. **单独新建一个新页面路径**
2. **设备型号固定写死为 `BLV_RQ`**
3. **按键支持映射设置**
4. **蓝牙名称输入规则为 ASCII + 最多 8 字节自定义名，仅允许数字和英文字符**
5. **允许按键类型由用户先选，读取配置后再按设备返回结果自动修正**
6. **允许通信日志导出**
7. **未配置映射的按键允许继续下发（方案 B）**
8. **采纳建议：未配置映射项下发时，优先“保持设备当前返回值不变”**

---

## 三、页面路径规划

建议新增页面路径：

`pages/basics/BluetoothDebugging/BLVRQPage/`

页面文件包括：

- `BLVRQPage.js`
- `BLVRQPage.wxml`
- `BLVRQPage.wxss`
- `BLVRQPage.json`

该页面仅服务于 `BLV_RQ` 设备，不复用 `W13` 页面逻辑。

---

## 四、页面结构设计

## 1. 页面总结构

页面自上而下分为三大区域：

1. 蓝牙信息栏
2. 设备管理框
3. 通信日志框组

页面整体不滚动，建议通过高度配比保证三块区域稳定展示：

- 蓝牙信息栏：约 26%
- 设备管理框：约 46%
- 通信日志框组：约 28%

---

## 2. 蓝牙信息栏

### 展示内容

- 蓝牙名称
- MAC / DeviceId
- ServiceId
- Tx 特征值
- Rx 特征值
- 连接状态
- 蓝牙信号 / RSSI

### 交互内容

- `断开` 按钮
- `重连` 按钮
- 蓝牙名称输入框
- `设置蓝牙名称` 按钮

### 交互规则

#### 蓝牙名称输入限制

输入内容必须满足：

- 仅允许数字和英文字符
- 长度为 1~8 字节
- ASCII 编码

建议使用如下校验规则：

`^[A-Za-z0-9]{1,8}$`

#### 设置蓝牙名称按钮启用条件

仅当同时满足以下条件时可点击：

- 当前已连接设备
- 输入内容非空
- 输入内容满足校验规则

#### 设置蓝牙名称交互流程

1. 用户输入新名称
2. 点击 `设置蓝牙名称`
3. 下发 `0x05` 指令
4. 回包成功后刷新显示名称
5. 记录 TX / RX / UI 日志

---

## 3. 设备管理框

设备管理框分为两部分：

### 3.1 设备信息栏

包含：

- 设备型号：`BLV_RQ`（固定写死）
- 软件版本
- 硬件版本
- `读取版本` 按钮
- 按键类型下拉框
- `读取按键配置` 按钮
- `设置按键配置` 按钮

### 3.2 设备按键栏

根据按键类型动态生成按键卡片。

布局要求：

- 一行 2 个卡片
- Z 型排列
- 奇数卡片时最后一个左对齐

每个按键卡片包含：

- 按键序号（表示硬件按键位置）
- 按键控制按钮
- 按键功能下拉框
- 映射下拉框

建议标题展示方式：

- `按键1（硬件）`
- `按键2（硬件）`
- ...

可附加展示小字：

- `当前映射：键值X`

---

## 五、按钮与控件启用逻辑

### 1. 读取版本按钮

启用条件：

- 已连接设备

### 2. 读取按键配置按钮

启用条件：

- 已连接设备
- 已选择按键类型（1~8键）

### 3. 设置按键配置按钮

启用条件：

- 已连接设备
- 已选择按键类型（1~8键）

### 4. 按键控制按钮

启用条件：

- 已连接设备
- 当前按键存在有效映射

### 5. 设置蓝牙名称按钮

启用条件：

- 已连接设备
- 名称输入合法

---

## 六、按键类型、功能与映射设计

## 1. 按键类型下拉框

选项：

- 请选择按键类型
- 1键
- 2键
- 3键
- 4键
- 5键
- 6键
- 7键
- 8键

### 规则

- 用户先选择按键类型后，才允许读取/设置按键配置
- 读取设备配置后，如果设备返回键数与当前选择不同：
  - 页面提示：`设备返回为 X 键，已按设备实际值修正`
  - 页面自动修正下拉框与卡片数量

---

## 2. 按键功能下拉框

依据协议中的功能码 `0x00 ~ 0x0F`：

- 不设置（0x00）
- 普通按键（0x01）
- 清理按键（0x02）
- 投诉按键（0x03）
- 预留（0x04）
- 预留（0x05）
- ...
- 预留（0x0F）

页面展示建议使用：

- `普通按键 (0x01)`
- `投诉按键 (0x03)`

---

## 3. 映射下拉框

映射选项需根据当前按键类型动态生成。

例如：

- 当前为 4 键：只允许映射 `键值1 ~ 键值4`
- 当前为 8 键：允许映射 `键值1 ~ 键值8`

### 映射校验规则

根据协议要求：

- 不同硬件位置不能映射到相同键值
- 映射值必须落在当前按键类型范围内

因此页面在设置前必须校验：

1. 是否存在重复映射
2. 是否存在越界映射
3. 是否存在未配置映射

---

## 七、协议交互设计

---

## 1. 读取版本号（0x01）

### 发送

- `Frame_Type = 0x01`
- `P0 = 0x01`

### 回包

- `P0 = 软件版本号`
- `P1 = 硬件版本号`

### 页面交互

- 点击 `读取版本`
- 成功回包后更新：
  - 软件版本
  - 硬件版本

---

## 2. 设置蓝牙名称（0x05）

### 发送

- `Frame_Type = 0x05`
- `P0 = 名称长度`
- `P1~Pn = ASCII字符`

### 回包

- `P0 = 0x01`：设置成功
- `P0 = 0x02`：设置失败

### 页面交互

- 输入名称
- 点击 `设置蓝牙名称`
- 成功后提示并刷新名称显示

---

## 3. 读取按键配置（0x04）

### 前置条件

- 已连接设备
- 已选择按键类型

### 发送

- `Frame_Type = 0x04`
- `P0 = 0x01`

### 回包

- `P0 = 硬件按键总数`
- `P1~P8 = 各硬件按键配置字节`

### 配置字节解析规则

每个配置字节：

- Bit0~3：映射键值
- Bit4~7：按键功能

### 页面处理

- 自动解析并回填每张卡片的：
  - `mappedKey`
  - `functionCode`

---

## 4. 设置按键配置（0x02）

协议规定 `0x02` 分为两个子命令：

### 子命令 1：设置按键功能

- `P0 = 0x01`
- `P1~P8 = 逻辑键值功能码`

### 子命令 2：设置按键映射

- `P0 = 0x02`
- `P1~P8 = 硬件位置映射到的键值`

### 页面交互流程

用户点击 `设置按键配置` 后，执行以下步骤：

#### 第一步：前端校验

检查：

1. 是否已选择按键类型
2. 是否存在重复映射
3. 是否存在越界映射
4. 是否存在未配置映射
5. 功能配置是否完整

#### 第二步：弹出二次确认框

##### 场景 A：存在未配置映射按键

弹窗提示示例：

> 以下按键未配置映射：按键2、按键5  
> 若继续下发，将保持这些按键当前设备返回值不变。  
> 是否继续？

##### 场景 B：无缺失项

弹窗提示示例：

> 确认下发当前按键功能与映射配置？

#### 第三步：用户确认后继续下发（方案 B）

执行顺序建议为：

1. 先下发功能配置（`P0 = 0x01`）
2. 再下发映射配置（`P0 = 0x02`）

#### 第四步：未配置映射项处理策略（采纳建议）

对于未配置映射的按键，不直接写入空值或 `0x00`，而是：

- **保持设备当前返回值不变**

即：

- 页面在成功读取配置后缓存设备原始映射值
- 用户未配置映射的项，设置时继续带上原设备返回值

该策略的优点：

- 最稳妥
- 避免把设备有效映射误清空
- 与“允许继续”的方案 B 兼容

#### 第五步：结果反馈

- 两条命令都成功：提示 `设置成功`
- 任一命令失败：提示 `设置失败`
- 日志中记录失败发生在功能设置还是映射设置阶段

---

## 5. 按键控制（0x06）

### 交互逻辑

用户通过映射下拉框配置卡片映射值后，点击某个按键卡片中的控制按钮时：

- 发送的不是硬件按键序号
- 而是该卡片当前映射到的**逻辑键值**

### 示例

- 硬件按键1 当前映射为键值3
- 点击“按键1”的控制按钮
- 实际发送键值3的模拟触发命令

### 发送

- `Frame_Type = 0x06`
- `P0 = 1`
- `P1 = 1 << (mappedKey - 1)`

### 回包

- `P0 = 0x01`：成功
- `P0 = 0x02`：失败

### 限制

- 未连接不可触发
- 未配置映射不可触发
- 点击未映射按键时提示：`当前按键未配置映射`

---

## 八、日志设计

## 1. 日志分类

建议日志类型：

- `UI`：用户操作
- `CFG`：状态变化
- `TX`：发送命令
- `RX`：接收回包
- `WARN`：警告
- `ERR`：错误

## 2. 日志内容建议

每条日志包含：

- 时间戳
- 日志类型
- 命令字
- Hex 内容
- 文本说明

### 示例

- `[TX][0x04] 读取按键配置`
- `[RX][0x04] 返回4键配置`
- `[WARN] 未配置映射：按键2、按键5，继续按原设备值下发`
- `[TX][0x06] 触发键值3`

## 3. 日志功能

顶部功能按钮：

- `清空日志`
- `导出日志`

## 4. 导出格式

允许导出为 `txt` 文件。

建议文件名：

`BLV_RQ_Log_yyyyMMdd_HHmmss.txt`

导出内容建议包含：

- 当前设备信息
- 当前连接参数
- 全量日志内容

---

## 九、推荐数据模型

```js
data: {
  bleInfo: {
    devName: '',
    mac: '',
    serviceId: '',
    txCharId: '',
    rxCharId: '',
    connected: false,
    rssi: null,
    signalText: '-'
  },

  deviceInfo: {
    model: 'BLV_RQ',
    softwareVersion: '-',
    hardwareVersion: '-'
  },

  keyConfig: {
    selectedKeyCount: 0,
    keyCountOptions: ['请选择按键类型', '1键', '2键', '3键', '4键', '5键', '6键', '7键', '8键'],
    keys: [
      {
        hwIndex: 1,
        mappedKey: 1,
        functionCode: 1,
        functionLabel: '普通按键',
        originalMappedKey: 1
      }
    ]
  },

  logs: []
}
```

其中：

- `hwIndex`：硬件按键位置
- `mappedKey`：当前界面配置映射值
- `originalMappedKey`：设备读取回来的原始映射值，用于方案 B 放行时保留原值

---

## 十、测试范围

## 1. 蓝牙信息栏

- 能显示蓝牙名称、MAC、特征值、连接状态、信号
- 断开按钮有效
- 重连按钮有效

## 2. 蓝牙名称设置

- 非英文数字不可通过
- 超过 8 字节不可通过
- 合法名称可设置成功
- 成功失败提示正确

## 3. 版本读取

- 可正常读取软件版本、硬件版本

## 4. 按键配置读取

- 未选按键类型时按钮禁用
- 选定后可读取
- 返回值可正确解析
- 设备返回键数与页面选择不一致时可自动修正

## 5. 按键配置设置

- 功能可正确下发
- 映射可正确下发
- 重复映射必须拦截
- 越界映射必须拦截
- 未配置映射时弹窗提示并允许继续
- 未配置映射项按原设备值下发

## 6. 按键控制

- 点击卡片时基于映射后的逻辑键值发送命令
- 未配置映射不可触发

## 7. 日志

- TX / RX / WARN / ERR 记录完整
- 清空日志可用
- 导出日志可用

---

## 十一、首版实施范围

首版实施包含：

1. 新建 `BLVRQPage`
2. BLE 信息展示
3. 断开 / 重连
4. 读取版本
5. 设置蓝牙名称
6. 选择按键类型
7. 读取按键配置
8. 设置按键功能
9. 设置按键映射
10. 按映射执行单键控制
11. 日志显示 / 清空 / 导出

首版暂不做：

1. 多键同时触发
2. 批量压测模式
3. 原始报文自由编辑器

---

## 十二、建议实施顺序

### 第 1 阶段：页面骨架

- 新建 `BLVRQPage`
- 搭建静态页面结构
- 接收 BLE 上下文参数

### 第 2 阶段：基础蓝牙能力

- 连接信息展示
- 断开 / 重连
- RSSI 刷新
- 蓝牙名称设置
- 版本读取

### 第 3 阶段：按键配置能力

- 按键类型下拉
- 配置读取
- 卡片渲染
- 功能与映射编辑
- 二次确认弹窗
- 方案 B 放行逻辑

### 第 4 阶段：控制与日志增强

- 单键触发
- 日志导出
- 异常处理优化

---

## 十三、结论

本实施文档已完成以下关键决策固化：

- `BLV_RQ` 单独新建页面
- 设备型号固定为 `BLV_RQ`
- 页面支持按键功能与映射双配置
- 设置时采用二次确认
- 未配置映射按键采用 **方案 B：允许继续**
- 继续时采纳建议：**未配置映射项保持设备当前返回值不变**
- 页面整体不滚动，仅日志区允许内部滚动

该文档可作为后续代码实现的直接依据。