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（场景内字段）。