From ae7a68aad1520becbfc2af8679bbc9de4acc0914 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9C=E8=99=9E=E6=B8=A0=E6=88=90=E2=80=9D?= <“yuqucheng2006@qq.com”> Date: Mon, 7 Sep 2026 09:13:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99README=E8=A1=A5?= =?UTF-8?q?=E5=85=85=E6=9E=B6=E6=9E=84=E8=AF=B4=E6=98=8E=E4=B8=8E=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E5=A4=87=E5=BF=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 项目概况/技术栈/启动流程/目录结构/核心模块(蓝牙/网络/数据/UI/热更)/构建发布备忘 --- README.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5f5f7c3..857eb49 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,141 @@ -# killapp +# killapp —— 激光灭蚊设备控制 App -灭蚊app \ No newline at end of file +控制「激光灭害虫设备」（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_` 等。 +- `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（场景内字段）。 + +## 已知问题与开发状态 + +- 进行中分支：`feature/ble-config-notification` —— BLE 配置变更通知 + 毫米波雷达状态支持（最新提交 320ece4）。 +- 未完成的调试记录：根目录 [debug-ble-write-block.md](debug-ble-write-block.md)。 + 真机日志出现 `UnityBluetoothLE write characteristic block` 后触发 Loom 报错， + 待验证假设：30 秒一次的硬件状态轮询（0xA1）与首次全量状态查询并发，导致 BLE 写特征阻塞。