134 lines
9.2 KiB
Markdown
134 lines
9.2 KiB
Markdown
# killapp —— 激光灭蚊设备控制 App
|
||
|
||
控制「激光灭害虫设备」（photonmatrix）的配套手机 App，Unity 制作，Android + iOS 双平台。
|
||
用户通过 App 完成设备绑定（BLE 扫描 + 扫码）、配网、日常控制（工作模式 / FOV / 透镜 / 补光灯 / 定时任务）、
|
||
杀蚊数据统计（柱状图 / 雷达热力图 / 杀蚊视频）、固件 OTA 升级、设备共享等。
|
||
|
||
---
|
||
|
||
## 技术栈与环境
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| Unity | 2022.3.62f3c1 |
|
||
| 应用包名 | `com.photonmatrix.photonmatrix`（Android / iOS 相同） |
|
||
| 当前版本 | bundleVersion 1.0.7，AndroidBundleVersionCode 4（均在 `ProjectSettings/ProjectSettings.asset`） |
|
||
| UI 方案 | UGUI + DOTween，无 Addressables |
|
||
| 热更方案 | 自研 AssetBundle 热更（`LoadRes` + `NetworkCtrl`） |
|
||
| 第三方 | Firebase SDK（仅 Auth）、apple-signin-unity、Shatalmic BLE 插件、zxing、NativeGallery、ExternalDependencyManager |
|
||
| 主场景 | `Assets/Scenes/MainScene.unity`（唯一业务场景）；`BlueToothTest.unity` 为蓝牙调试场景 |
|
||
|
||
`Packages/manifest.json` 非常精简（ugui、timeline、visualscripting、assetbundlebrowser、android-logcat 等），
|
||
Firebase 是以 Assets 方式导入而非 UPM。
|
||
|
||
## 整体架构
|
||
|
||
**单场景 + 常驻 Manager + AssetBundle 动态页面**：
|
||
|
||
- `MainScene` 的 `Manager` 节点挂载全部管理器：`NetworkCtrl`、`DataManager`、`UIManager`、`LoadRes`、`LanguageManager`、`FirebaseAuthManager`。
|
||
- `Canvas/bg` 是页面容器，页面按 prefab 从 AssetBundle 动态加载实例化（旧的销毁、新的实例化）。
|
||
- 页面逻辑全部写在 prefab 挂的 Ctrl 类里，各单例之间直接互相引用（`HomePageCtrl.Instance`、`DataManager.Instance` 等）。
|
||
|
||
**启动流程**（`NetworkCtrl.Init()`）：
|
||
`LoadRes.Init`（AB 环境）→ 创建 `HttpRequestManager` / `RequestQueueManager` / `NetworkStateManager` →
|
||
从服务器查 AB 版本并差量热更下载（MD5 校验）→ `DataManager.Init`（token 自动登录）→ `UIManager.Init`（有 token 进主页，否则进登录页）。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
Assets/
|
||
├── Scenes/ MainScene（主场景）、BlueToothTest（蓝牙调试）
|
||
├── Scripts/
|
||
│ ├── Bluetooth/ BLE 核心（当前开发重点）
|
||
│ │ ├── BluetoothManager.cs Shatalmic 插件封装：扫描/连接/断开事件
|
||
│ │ ├── BLECommunicationManager.cs 协议层：指令收发、事件分发（全项目最大文件）
|
||
│ │ ├── BLEDeviceState.cs 按 MAC 隔离的设备运行状态模型
|
||
│ │ ├── OTAManager.cs 固件版本解析与升级传输
|
||
│ │ ├── Protocol/ 帧结构体 BLEProtocolStructs.cs + CRC16.cs
|
||
│ │ └── BLE通信方案V2.2.md BLE 协议文档（App ↔ BLE 透传 ↔ STM32H7 MCU）
|
||
│ ├── Core/ Loom（BLE 回调线程切主线程）、状态栏沉浸、安卓文件选择
|
||
│ ├── Managers/ DataManager / DataBase(DTO) / FirebaseAuthManager / LanguageManager / LoadRes / FireBaseCtrl(死代码)
|
||
│ ├── Network/ NetworkCtrl(门面+启动编排) / HttpRequestManager / RequestQueueManager / NetworkStateManager
|
||
│ ├── UI/
|
||
│ │ ├── UIManager.cs 页面管理、安卓返回键、token 自动登录
|
||
│ │ ├── Pages/ 各页面逻辑（Home / Login / ConnectDevice / DeviceInfo / Video / Self / Rank / Safetylearning）
|
||
│ │ └── Components/ Toast / Loading / Barchart / RadarHeatmap / SectorScanEffect / QRCode 等通用控件
|
||
│ └── Utils/ MainThread、ValidationUtils、iOSWiFiHelper
|
||
├── Res/ AB 包源资源（bluetooth / common / language / ui）
|
||
├── StreamingAssets/ 首包 AB：common.ab、language.ab、ui_common.ab + list.json
|
||
├── Plugins/ Shatalmic 运行脚本、NativeGallery、DOTween、zxing、iOS 原生桥(.mm)
|
||
├── AppleAuth/ Sign in with Apple
|
||
└── Firebase/ Firebase SDK（实际只用 Auth）
|
||
```
|
||
|
||
## 核心模块备忘
|
||
|
||
### 蓝牙 BLE（开发重点）
|
||
|
||
- 链路：App ↔ BLE 模块（透传，Service `FFE0`，读/写/Notify 均走 `FFE1`）↔ MCU（UART9）。
|
||
- `BLECommunicationManager` 是几十条指令的收发与事件分发中心：
|
||
注册/指纹认证、定时任务、语言、LCD/RGB、WiFi 配网、补光灯、激光、角度/距离、
|
||
毫米波雷达、视觉检测、工作模式、硬件状态、统计数据、蚊子数据等。
|
||
每条指令对应 `XxxRead` / `XxxWrite` 方法 + `OnXxxReceived` 事件。
|
||
- 设备**主动通知**（状态变化 0x01 / 错误 0x02 / 参数变化 0x06 / 蓄能 0x08 / 补光灯连接 0x09 等）
|
||
汇入 `OnDeviceNotificationReceived`，再**按设备 MAC 隔离**后广播；分支名
|
||
`feature/ble-config-notification` 即指这套「配置变更主动上报」机制。
|
||
- 设备状态保存在 `BLEDeviceState`（按 MAC 为边界），统一通过
|
||
`OnDeviceStateChanged(BLEDeviceState, BLEDeviceStateField)` 通知 UI。
|
||
- Shatalmic 回调来自非主线程，UI 相关处理必须 `Loom.QueueOnMainThread` 切回主线程。
|
||
- Android/iOS 无法直接取 BLE 真实 MAC，设备 MAC 通过 BLE 命令从设备端获取（设备序列号用于绑定）。
|
||
|
||
### 网络与后端
|
||
|
||
- **服务器地址**（配置在 MainScene 里 `NetworkCtrl.serverBaseUrls`）：
|
||
测试 `https://nextreal.cn/photon-matrix-api`，正式 `https://api.photonmatrixlab.com`。
|
||
**切换后门**：首页左下角连点 5 次（`enableServerBackdoor` 控制开关，发布前应置 0）；
|
||
环境持久化在 PlayerPrefs `network_server_env`。
|
||
- `HttpRequestManager`：UnityWebRequest 封装，重试（指数退避）、**SSE 流式**（WiFi OTA 进度）、多平台超时。
|
||
- `RequestQueueManager`：优先级请求队列，并发上限 5。
|
||
- `NetworkStateManager`：每 3 秒轮询 `internetReachability`，发连接/断开事件。
|
||
- `ResponseCode`：业务码统一处理，**601 = Token 失效 → 全局登出**。
|
||
- 主要接口（`{Base}/api/v1/...`）：认证（login/register/email-code/token-login/firebase-bind）、
|
||
设备（bind/list/config/schedule-tasks/fingerprints/share/command）、统计上报与查询
|
||
（kill-count/records/videos/heatmap/leaderboard）、通知、OTA（latest/push/transfer 进度 SSE）、
|
||
考试、反馈、`app/version/bundle`（AB 热更清单）。
|
||
|
||
### 数据与账号
|
||
|
||
- `DataManager`：运行时数据中枢（token、用户信息、自有/共享设备、当前选中设备、设备配置、指纹、定时任务）。
|
||
PlayerPrefs 持久化：`token`、`userData`、`selectedDeviceMac`、设备列表缓存 `ownedDevicesCache_<userId>` 等。
|
||
- `DataBase.cs`：纯 DTO 定义（登录/用户/设备/配置/OTA/消息/统计/考试…），非 Mono。
|
||
- 第三方登录：`FirebaseAuthManager`（Google 用 FederatedOAuthProvider，Apple 用 apple-signin-unity + nonce），
|
||
结果换自家后端 token（`auth/firebase/bind`）。旧版 `FireBaseCtrl.cs` 已无任何引用，属死代码。
|
||
|
||
### UI 框架
|
||
|
||
- `UIManager.PageName` 枚举 8 个主页面：login / safetylearning / home / connectDevice / deviceInfo / self / video / rank。
|
||
- 页面 prefab 按 bundle 名 `ui_xxxpage` 从 AB 加载（配置在 MainScene 的 UIManager `pages` 列表）。
|
||
- 设置类子弹窗不走 UIManager，由各 Ctrl 自己 Instantiate + `RegisterBackAction`（返回键栈，双击退出）。
|
||
- 首页 `HomePageCtrl` 是功能核心：蓝牙/WiFi 双通道控制、状态订阅、
|
||
**锁扣防误触（LockButtonPlane，180 秒无操作自动上锁）**、下拉刷新、统计上报、跳转子页面。
|
||
|
||
### 资源与热更
|
||
|
||
- `LoadRes`：编辑器「本地」模式直读 `Assets/Res/`；真机「资源包」模式优先 `persistentDataPath/*.ab`（热更落盘），
|
||
回退 StreamingAssets 首包；bundle 缓存在内存字典。
|
||
- 热更清单来自 `app/version/bundle`，由 `NetworkCtrl` 做差量下载 + MD5 校验，进度显示在 `updateLoading`。
|
||
- 语言词条也在 AB 里：`language/language.json`、`country.json`（`LanguageManager` 读取，PlayerPrefs `LanguageType`）。
|
||
|
||
### 其他关键组件
|
||
|
||
- `Loom`：线程池 + 主线程队列派发（BLE 回调切主线程用）。`Utils/MainThread.cs` 功能重复，并存。
|
||
- `RadarHeatmap`：按角度(0-180)+距离换算极坐标摆放热力点（数据来自 `stats/device/heatmap`）。
|
||
- `SectorScanEffect`：首页扇形扫描波纹动画（fillAmount 表现 FOV、缩放表现探测距离）。
|
||
- `iOSWiFiHelper`：iOS14+ 取当前 WiFi SSID（需定位权限），配网页自动填 SSID；Android 直接读。
|
||
- `NativeGallery`：杀蚊视频保存到系统相册。
|
||
|
||
## 构建与发布备忘
|
||
|
||
- 版本号：`ProjectSettings/ProjectSettings.asset` 的 `bundleVersion` / `AndroidBundleVersionCode`。
|
||
- Android 签名：`user.keystore`（项目根目录）。
|
||
- iOS：`ITSAppUsesNonExemptEncryption` 已配置，避免每次手动答加密问卷（commit 457fee5）。
|
||
- 根目录的 `*.apk` / `*_mapping.txt` 为历史构建产物（含 Release 符号表），命名习惯如
|
||
`photonmatrix_1.0.7_0903.apk`；测试构建会带后缀如 `ota蓝牙优先`。
|
||
- 打正式包前检查：`NetworkCtrl.enableServerBackdoor` 应为 0（场景内字段）。 |