# 修改记录 2026-09-03：迁移 uni-app vue3，蓝牙去第三方插件改 uni 内置 API

## 背景

- 原工程为 uni-app x（uvue/uts），蓝牙依赖第三方插件 `uni_modules/android-ble`。
- 先尝试过"uni-app x 下去插件改 uni 内置 BLE API"：不可行——uni-app x 官方未内置
  蓝牙 API（官方文档明确"蓝牙：见插件市场"），全量编译确认
  `createBLEConnection` 等接口在 app-android 平台不存在。
- 因对渲染性能要求不高，改为**整体迁移到 uni-app vue3（vue/ts）**：
  vue3 App 端内置完整 BLE API，蓝牙彻底去插件化；且标准基座即可运行，无需自定义基座。

## 工程骨架

- `main.uts` → `main.js`；`App.uvue` → `App.vue`（`onLastPageBackPress` 中
  `uni.exit()` 改 `plus.runtime.quit()`；globalData 保留 `setBleNotity`/`ConnectBle`，
  改走新 `src/BluetoothManager.ts`，流程不变：connect → scanServices → 订阅 notify）。
- `manifest.json`：删除 `"uni-app-x": {}`；`app-android`/`app-ios` 合并为 vue3 的
  `app-plus` 结构；Android permissions 补 `BLUETOOTH`/`BLUETOOTH_ADMIN`/
  `BLUETOOTH_SCAN`(neverForLocation)/`BLUETOOTH_CONNECT`；iOS 蓝牙隐私描述并入
  `app-plus.distribute.ios.privacyDescription`。
- `pages.json` 内容不变（globalStyle 标题改为 smartAssister）。
- 删除 `platformConfig.json`（uni-app x 专用）。
- uni_modules：删除 `android-ble`、`lime-*`（8 个，页面未使用且为 uts 组件）、
  `uni-wifi`（未使用）；保留 `uni-icons`（自带 vue 版本组件）、`uni-scss`。

## 蓝牙：`src/BluetoothManager.ts`（替代插件）

- 基于 uni 内置 BLE API：`openBluetoothAdapter` / `startBluetoothDevicesDiscovery` /
  `createBLEConnection` / `getBLEDeviceServices` / `getBLEDeviceCharacteristics` /
  `notifyBLECharacteristicValueChange` / `writeBLECharacteristicValue` /
  `setBLEMTU` / `getBLEDeviceRSSI` / `closeBLEConnection`。
- 保持原插件的对外约定：`MyApiResult.type==0` 成功；1000=订阅成功 1001=订阅失败；
  10000=连接失败 10001=已断开 10002=蓝牙未开 10003=无权限；
  notify 数据包装为 `{type:0, data:{data:number[], mac}}` 经 `uni.$emit("bleData")` 分发；
  意外断开经 `uni.$emit("bleState", 10001)` 广播（主动断开不广播）。
- `sendDataBytes` 用 `writeType:"writeNoResponse"`（下行特征仅支持无响应写）。
- 自动重连未实现（业务恒传 false），`setBtAutoConnectTime`/`cancelAutoConnectBt` 为空实现。

## uts → ts 移植

- `src/commonFunctions`、`src/mcm/*`（Crc/FrameCodec/McmChannel/McmCommands/McmInfo/
  OtaManager）、`api/*`、`common/*`：机械移植，去 `.uts` import 后缀；
  `UTSJSONObject` → `Record<string, any>`（httpInstance 统一定义 `JSONObject`）。
- **vue3 的 `uni.getStorageSync` 无 key 返回 `""` 而非 null**：`common/auth.ts`、
  `common/bleInfo.ts` 统一经 `getStorageStr()` 读取（空串转 null）。

## 页面 .uvue → .vue（7 个）

- template 不动；`script setup lang="ts"`；显式 `import { ref } from 'vue'`、
  生命周期钩子 `import { onLoad, onShow, ... } from '@dcloudio/uni-app'`。
- `pages/tabbar/ota.vue` 固件读取由 java.io 改为 `plus.io`（FileReader.readAsDataURL →
  base64 → `uni.base64ToArrayBuffer` → number[]），`#ifdef APP-PLUS` 包裹。
- `getApp().globalData.ConnectBle` 调用处加 `as any` 断言。

## 验证与注意事项

- HBuilderX CLI `launch app-android --compile true` 编译通过（编译器识别为 vue3 工程）。
- 运行用**标准基座**即可（vue3 基座内置 BLE）；原自定义基座配置不再适用。
- 真机回归重点：扫描/连接/notify/MTU 247、home 轮询与设备信息、CLI 收发与 rssi、
  **OTA 全流程**（高频无响应写，丢包风险最高）。
- OTA 固件路径 `/sdcard/Download/embeddedSrc.bin` 在 Android 11+ 分区存储下可能读不到
  （与原 java.io 行为一致，未劣化）；如不可用，改用应用私有目录或加文件选择器。