# StarCloud Flutter SDK 示例

本示例用于验证 `flutter_sdk` 的移动端集成流程，包含 SDK 认证、测试云账户、蓝牙扫描/配对、基础锁控制、网关 WiFi 配网，以及视频对讲监控与来电处理。

> 示例用于联调和能力演示。生产项目必须自行实现账号体系、密钥保护、错误提示、权限说明与日志脱敏。

## 环境

- Flutter 3.19.6（项目通过 FVM 管理）
- Android 真机或 iOS 真机
- 已按根目录 [README](../README.md) 配置蓝牙、定位、网络、麦克风和相机权限
- 需要 `flutter_sdk`、`starlock_ble`、`starcloud`、`starchart` 及 `video_decode_plugin` 位于当前相对路径所指向的位置

安装依赖并运行：

```bash
fvm use 3.19.6
fvm flutter pub get
fvm flutter run
```

不需要先进入 `../../video_decode_plugin` 执行 `fvm flutter pub get`：本示例的 `pubspec.yaml` 已以 `path: ../../video_decode_plugin` 声明该插件，执行本目录的 `fvm flutter pub get` 会递归解析其依赖。只有修改插件源码或运行插件自身示例时，才进入插件目录单独执行该命令。

若只做代码检查：

```bash
fvm dart analyze
```

## 使用流程

### 1. 登录

在“登录”页填写在星云平台注册后获得的 `client_id` 与 `client_secret`，点击：

```text
第1步：注册星云账号得到client_id和client_secret初始化SDK
```

环境地址已写在示例代码中：

```text
https://cloud.skychip.top/sdk
```

随后点击“第2步：仅测试创建新的 SDK 星云账户”。生产环境请替换为业务后台下发的 `CloudUserInfo`，不要将测试账户创建逻辑直接发布。

如需网关配网，再输入锁主账号/管理员账号并点击：

```text
第3步：填写app登录账号支持WIFI授权账号
```

该账号的授权令牌仅用于 WiFi 网关配网，不能代替 SDK 云账户。

### 2. 设备扫描与配对

进入“设备扫描”页，点击“扫描”。每条扫描结果会直接显示：

- `配对`：可对该设备发起配对；
- `已配对`：当前设备已匹配本地配对锁，不会重复配对。

配对成功后可在“蓝牙控锁”页验证基础开锁、关锁能力。

### 3. WiFi 配网

进入“WiFi配网”页，按顺序操作：

1. 点击“第1步：初始化视频对讲”，生成 App PeerID；
2. 输入 WiFi SSID、密码；
3. 点击“第2步：wifi配网”。

配网下发成功后，锁仍可能需要 30–60 秒联网。示例会查询网关状态并轮询云端锁信息；在锁的 `isOnline` 为 `true` 且 `peerId` 非空之前，不能保证监控可用。

### 4. 视频对讲

“视频对讲”页不再提供初始化入口；请先在“WiFi配网”页完成第 1 步。该页提供：

- 锁 PeerID 自动回填与手动输入；
- `监控`、`挂断`；
- 来电接听/拒绝卡片；
- H264 视频 Texture 渲染、状态与诊断日志。

示例通过 `video_decode_plugin` 选择 FFmpeg 解码后端。启动监控时日志应包含：

```text
[DIAG] recreateDecoder preferred=ffmpeg selected=ffmpeg
[DIAG] decoder active engine=ffmpeg
```

若日志显示 `mediacodec`，说明运行的不是当前 FFmpeg 配置；请检查本地 `video_decode_plugin` 路径、重新构建 APK，并确认未使用旧产物。

## 示例配置位置

| 配置 | 文件 | 说明 |
| --- | --- | --- |
| 星云环境地址 | `lib/tabs/auth_tab.dart` | 示例固定为测试环境地址；按已授权环境修改 |
| 视频对讲服务地址 | `lib/services/video_talk_initializer.dart` | 示例固定地址；生产按服务分配修改 |
| WiFi SSID/密码 | 页面输入 | 不设默认值，也不会保存 |
| FFmpeg 视频渲染 | `lib/tabs/video_talk_tab.dart` | 初始化前后校验活动引擎为 `ffmpeg` |

## 重要说明

- 请不要向代码仓库提交真实 `client_secret`、账号密码、访问令牌、蓝牙密钥或视频凭据。
- Android 模拟器不适合测试蓝牙扫描、配对和 WiFi 配网；请使用真机。
- 监控超时通常由锁未联网、锁端 `peerId` 未上报、网关未完成配网或锁端未回复对讲协商造成。
- 示例目前不包含生产级账号持久化、异常恢复、埋点或 UI 设计，应按业务要求实现。

## 目录

```text
lib/
├── tabs/                         # 登录、扫描、锁控、WiFi、视频对讲页面
├── services/
│   ├── cat_eye_monitor_service.dart
│   └── video_talk_initializer.dart
├── global.dart                   # 跨页面的锁、PeerID、授权状态
└── main.dart                     # 页面导航与 SDK bootstrap
```