71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
# observer
|
||
|
||
动物实时识别 App（Flutter 版）。Android / iOS 一套代码，后端接口与支付见
|
||
[`docs/PaymentApi.md`](docs/PaymentApi.md)。
|
||
|
||
## Android 打包
|
||
|
||
```bash
|
||
./build_apk.sh # 用当前 pubspec 版本构建，产物 build/app/outputs/flutter-apk/observer-x.y.z.apk
|
||
./build_apk.sh --bump # 自动递增 patch+1、build+1 后构建
|
||
./build_apk.sh 1.0.7 # 用指定版本(versionName)构建，build+1
|
||
```
|
||
|
||
产物命名 `observer-x.y.z.apk`（管理端上传版本号从文件名识别）；构建的
|
||
`app-release.apk` 中间产物由脚本清理，只保留规范命名文件。
|
||
|
||
## iOS 真机部署（iPhone）
|
||
|
||
### 构建与安装
|
||
|
||
```bash
|
||
# 生产包直接构建即可：默认 API_BASE_URL 为线上域名（lib/config/app_config.dart），无需传参
|
||
flutter build ios --release
|
||
# 仅本地联调（后端跑在 Mac 上、手机连同一 Wi-Fi）时才覆盖为 Mac 局域网 IP：
|
||
# flutter build ios --release --dart-define=API_BASE_URL=http://<Mac局域网IP>:8080
|
||
|
||
# 安装到真机（UDID 可用 `xcrun devicectl list devices` 查询）
|
||
xcrun devicectl device install app --device <UDID> build/ios/iphoneos/Runner.app
|
||
|
||
# 启动并抓控制台日志（--terminate-existing 先杀掉旧实例）
|
||
xcrun devicectl device process launch --console --terminate-existing \
|
||
--device <UDID> com.observer.app
|
||
```
|
||
|
||
### 注意事项（踩过的坑）
|
||
|
||
- **debug 构建不能在真机上从桌面图标启动**：iOS 14+ 会提示
|
||
"In iOS 14+, debug mode Flutter apps can only be launched from Flutter tooling"。
|
||
debug 调试必须用 `flutter run -d <设备ID>` 或 Xcode IDE 启动（`flutter devices` 查设备ID）；
|
||
从图标启动只对 release 构建有效。
|
||
## 模型热更新（多数据集模型）
|
||
|
||
模型与 APK 更新走**独立通道**：启动时拉取 `GET /api/v1/app/update` 随附的
|
||
`models` 目录（公开接口，无需登录），与 `UpdateChecker` 的 APK 检查并行。
|
||
|
||
- **目录条目**：`{datasetId, datasetName, version, labels[], sizeBytes, sha256,
|
||
downloadUrl, coverUrl}`；服务器未发布模型时不返回 `models` 字段，App 无模型可用，
|
||
相机页仅预览不识别。
|
||
- **下载入口**：相机页设置弹层「模型清单」按需下载/使用（封面缩略图 2 列网格，
|
||
未下载点击「使用」显示进度，完成自动激活；已激活再次点击取消；下载中可取消）。
|
||
- **存储**：应用私有目录 `models/<datasetId>/`，含 `model.tflite`、
|
||
`labels.json`、`meta.json`（meta 记录 `{version, sha256}`）。版本与摘要都
|
||
未变化时跳过下载；变化则下载到 `.part` 临时文件、sha256 校验通过后
|
||
原子 rename 替换，失败重试一次并保留旧模型，下次启动再试。
|
||
- **清理**：服务器下线的数据集下次同步时删除本地对应目录。
|
||
- **并行推理合并**：识别时加载全部已激活模型（`DetectorWorker` isolate 内
|
||
逐模型加载，单个失败不影响其他），同帧各模型独立推理后按类别分组做
|
||
**跨模型 NMS**（同类别不同模型检出同一目标取高分去重，不同类别互不压制），
|
||
结果叠加 `modelName` 标注来源。
|
||
|
||
实现：`lib/models/model_manager.dart`（下载/校验/持久化，`ModelManager`
|
||
单例 + ChangeNotifier）、`lib/detection/detector_worker.dart`（多模型并行
|
||
推理与 `mergeAcrossModels`）、`lib/camera/camera_screen.dart`（启动同步 +
|
||
诊断行展示模型列表）。
|
||
|
||
- **模型输入是 NHWC**：训练导出的模型需做字节级手术（开头 TRANSPOSE→RESHAPE，
|
||
输入 [1,320,320,3]）再发布给 App，否则 iOS 报
|
||
"Node number 0 (TRANSPOSE) failed to prepare"。
|
||
- **模拟器黑屏**：本机 iOS 模拟器 Impeller 渲染黑屏，验证 UI 用 VM service
|
||
（`flutter run` 输出里的 DevTools 地址），或直接真机验证。
|