iotsaas/docs/tuya-android-sdk-integration-guide.md

# 涂鸦智能 Android SDK 对接分析

## 一、SDK 版本信息

| 项目 | 版本/内容 |
|------|-----------|
| SDK版本 | **ThingSmart Home SDK v7.5.1** (本地文件7.5.0, Maven最新7.5.1) |
| Maven坐标 | `com.thingclips.smart:thingsmart:6.11.1` → 建议升级到 `7.5.1` |
| 安全组件 | `security-algorithm-1.0.0-beta.aar` |
| 最低Android版本 | Android 6.0 (API 23) |
| 目标SDK | Android 14 (API 35) |
| 构建要求 | 必须使用 AndroidX |
| 支持ABI | armeabi-v7a, arm64-v8a |

---

## 二、SDK 核心能力分析

### 2.1 功能模块清单（来自 module_app.json）

| 模块 | 功能 | 对接优先级 |
|------|------|-----------|
| **家庭管理** | 家庭创建/切换/设置/成员管理/房间管理 | ⭐⭐⭐ 必须 |
| **设备配网** | Wi-Fi配网/蓝牙配网/Mesh配网/Matter配网/Zigbee配网 | ⭐⭐⭐ 必须 |
| **设备控制** | 设备面板/数据点控制/状态查询/指令下发 | ⭐⭐⭐ 必须 |
| **设备详情** | 设备信息/网络信息/固件升级/设备移除 | ⭐⭐⭐ 必须 |
| **场景智能** | 场景创建/编辑/执行/自动化/条件触发 | ⭐⭐ 重要 |
| **消息中心** | 告警消息/设备消息/推送设置 | ⭐⭐ 重要 |
| **设备分享** | 设备分享/群组分享/分享链接 | ⭐⭐ 重要 |
| **群组管理** | 群组创建/编辑/WiFi群组/BLE群组/Mesh群组 | ⭐ 一般 |
| **摄像头/IPC** | 实时视频/回放/云存储/门铃/对讲 | ⭐⭐ 重要 |
| **定时任务** | 定时器/倒计时/闹钟 | ⭐⭐ 重要 |
| **Matter设备** | Matter设备发现/配网/控制 | ⭐⭐⭐ 必须 |
| **蓝牙Mesh** | Mesh网络/蓝牙设备管理 | ⭐ 一般 |
| **OTA升级** | 固件升级/批量升级 | ⭐ 一般 |
| **地图/地理围栏** | 位置设置/地理围栏 | ⭐ 一般 |
| **社交账号** | Google/Amazon/WeChat绑定 | ⭐ 一般 |
| **小程序** | MiniApp运行/调试 | ⭐ 一般 |

### 2.2 核心 API 清单

```java
// ===== 初始化 =====
ThingHomeSdk.init(application);                    // SDK初始化
ThingHomeSdk.setDebugMode(true);                   // 调试模式
ThingHomeSdk.onDestroy();                          // 销毁连接

// ===== 用户管理 =====
ThingHomeSdk.getUserInstance();                     // 用户实例
  .loginWithPhonePassword()                        // 手机号登录
  .loginWithEmail()                                // 邮箱登录
  .registerAccountWithPhone()                      // 手机号注册
  .registerAccountWithEmail()                      // 邮箱注册
  .sendVerifyCodeWithUserName()                    // 发送验证码
  .resetPasswordWithPhone()                        // 重置密码
  .logout()                                        // 退出登录

// ===== 家庭管理 =====
ThingHomeSdk.getHomeManagerInstance();              // 家庭管理实例
  .createHome()                                    // 创建家庭
  .queryHomeList()                                 // 查询家庭列表
  .getHomeDetail()                                 // 获取家庭详情
  .updateHome()                                    // 更新家庭
  .dismissHome()                                   // 解散家庭
  .addRoom()                                       // 添加房间
  .updateRoom()                                    // 更新房间
  .removeRoom()                                    // 删除房间

// ===== 设备配网 =====
ThingHomeSdk.getActivatorInstance();                // 配网实例
  .newTuyaActivator()                              // Wi-Fi配网
  .newTuyaSmartActivator()                         // 快连配网
  .newTuyaQrActivator()                            // 二维码配网
  .newTuyaBLEActivator()                           // 蓝牙配网
  .newTuyaMeshActivator()                          // Mesh配网
  .newTuyaMatterActivator()                        // Matter配网

// ===== 设备控制 =====
ThingHomeSdk.getDataInstance();                     // 数据实例
  .getDeviceBean()                                 // 获取设备信息
  .getDeviceStat()                                 // 获取设备状态
  .publishDps()                                    // 下发控制指令

IThingDevice mDevice = ThingHomeSdk.newDeviceInstance(devId);
mDevice.registerDeviceListener();                   // 注册设备监听
mDevice.publishDps();                               // 下发数据点
mDevice.unRegisterDeviceListener();                 // 取消监听

// ===== 场景智能 =====
ThingHomeSdk.getSceneManagerInstance();             // 场景管理实例
  .createScene()                                   // 创建场景
  .getSceneList()                                  // 获取场景列表
  .executeScene()                                  // 执行场景
  .modifyScene()                                   // 修改场景
  .deleteScene()                                   // 删除场景

// ===== 设备详情 =====
ThingHomeSdk.getDeviceDetailInstance();             // 设备详情实例
  .getDeviceDetail()                               // 获取设备详情
  .removeDevice()                                  // 移除设备
  .renameDevice()                                  // 重命名设备
  .checkFirmwareUpgrade()                          // 检查固件升级

// ===== 群组管理 =====
ThingHomeSdk.getGroupManagerInstance();             // 群组管理实例
  .createGroup()                                   // 创建群组
  .renameGroup()                                   // 重命名群组
  .dismissGroup()                                  // 解散群组
```

---

## 三、与物联网平台的对接架构

### 3.1 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                     移动端 APP (Android)                         │
│  ┌─────────────────────┐  ┌──────────────────────────────────┐  │
│  │  涂鸦 Home SDK       │  │  你的 IoT 平台 SDK (自研)        │  │
│  │  - 设备配网           │  │  - 规则引擎                      │  │
│  │  - 设备控制           │  │  - 告警通知                      │  │
│  │  - 家庭管理           │  │  - 数据分析                      │  │
│  │  - 场景联动           │  │  - 权限管理                      │  │
│  │  - Matter支持         │  │  - 多租户                        │  │
│  └─────────┬───────────┘  └──────────┬───────────────────────┘  │
│            │                           │                         │
│            ▼                           ▼                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              统一数据桥接层 (Bridge Layer)                │    │
│  │  - 设备数据同步  - 状态映射  - 事件转发  - 指令桥接      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
             │                              │
             ▼                              ▼
┌──────────────────────┐    ┌──────────────────────────────┐
│  涂鸦云平台            │    │  你的 IoT 后端服务            │
│  - 设备管理            │    │  - iot-device (设备管理)      │
│  - 数据存储            │    │  - iot-data (数据采集)        │
│  - 场景执行            │    │  - iot-rule (规则引擎)        │
│  - OTA升级             │    │  - iot-alarm (告警服务)       │
└──────────────────────┘    └──────────────────────────────┘
```

### 3.2 两种对接模式

#### 模式A：SDK直连模式（推荐，简单快速）
```
APP → 涂鸦SDK → 涂鸦云 → 设备
APP → IoT平台API → 你的后端 → 自有设备
```
**适用场景**：涂鸦设备由涂鸦SDK直接管理，自有设备走你的IoT平台

#### 模式B：后端桥接模式（统一管理）
```
APP → 涂鸦SDK → 涂鸦云 → 设备
                    ↓ 数据同步
APP → IoT平台API → 你的后端 → 统一数据/告警/规则
```
**适用场景**：需要统一的数据分析、告警、规则引擎

**推荐：先采用模式A快速上线，后续逐步迁移到模式B**

---

## 四、详细对接步骤

### Step 1: 涂鸦平台准备（1天）

1. **登录涂鸦IoT平台** → https://iot.tuya.com
2. **创建智能App** → 获取 AppKey 和 AppSecret
3. **配置Android应用信息**：
   - 包名（必须与APP包名一致）
   - SHA256证书指纹
   - 下载 security-algorithm.aar
4. **创建产品** → 定义设备功能（DP点）
5. **获取面板ID** → 用于设备控制面板渲染

### Step 2: Android项目集成（2天）

#### 2.1 创建Android项目
```groovy
// app/build.gradle
android {
    defaultConfig {
        applicationId "com.yourcompany.iotsaas"  // 必须与涂鸦平台一致
        minSdkVersion 23
        targetSdkVersion 35
        
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }
    packagingOptions {
        pickFirst 'lib/*/libc++_shared.so'
    }
}

dependencies {
    // 涂鸦核心SDK
    implementation 'com.alibaba:fastjson:1.1.67.android'
    implementation 'com.squareup.okhttp3:okhttp-urlconnection:3.14.9'
    implementation 'com.thingclips.smart:thingsmart:7.5.1'
    
    // 安全组件
    implementation fileTree(include: ['*.aar'], dir: 'libs')
    
    // 你的IoT平台SDK
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
}
```

#### 2.2 根目录 build.gradle 配置Maven仓库
```groovy
allprojects {
    repositories {
        maven { url 'https://maven-other.tuya.com/repository/maven-releases/' }
        maven { url 'https://maven-other.tuya.com/repository/maven-commercial-releases/' }
        google()
        mavenCentral()
    }
}
```

#### 2.3 AndroidManifest.xml 配置
```xml
<application
    android:name=".IotApplication"
    ...>
    
    <!-- 涂鸦SDK配置 -->
    <meta-data
        android:name="THING_SMART_APPKEY"
        android:value="你的AppKey" />
    <meta-data
        android:name="THING_SMART_SECRET"
        android:value="你的AppSecret" />
</application>
```

#### 2.4 混淆配置
```proguard
# fastJson
-keep class com.alibaba.fastjson.**{*;}
-dontwarn com.alibaba.fastjson.**

# OkHttp3
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**

# Tuya SDK
-keep class com.thingclips.**{*;}
-dontwarn com.thingclips.**
```

### Step 3: SDK初始化与用户体系（2天）

```kotlin
// IotApplication.kt
class IotApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // 1. 初始化涂鸦SDK
        ThingHomeSdk.init(this)
        ThingHomeSdk.setDebugMode(BuildConfig.DEBUG)
        
        // 2. 初始化你的IoT平台SDK
        IoTPlatformSdk.init(
            baseUrl = "https://your-iot-api.com",
            apiKey = "your-api-key"
        )
    }
}
```

#### 用户登录流程
```
┌─────────────┐    ┌───────────────┐    ┌──────────────┐
│ 用户输入      │───→│ 你的认证服务    │───→│ 涂鸦用户系统  │
│ 手机号/邮箱   │    │ JWT Token生成  │    │ UID获取       │
└─────────────┘    └───────────────┘    └──────────────┘
                          │                      │
                          ▼                      ▼
                   ┌──────────────────────────────────┐
                   │  APP 本地存储                      │
                   │  - IoT Platform Token             │
                   │  - Tuya Session                   │
                   └──────────────────────────────────┘
```

```kotlin
// 登录管理器 - 双平台登录
class LoginManager {
    
    // 涂鸦登录
    fun loginWithPhone(countryCode: String, phone: String, password: String,
                       callback: IResultCallback) {
        ThingHomeSdk.getUserInstance().loginWithPhonePassword(
            countryCode, phone, password,
            object : ILoginCallback {
                override fun onSuccess(user: User) {
                    // 涂鸦登录成功，获取uid
                    val tuyaUid = user.uid
                    
                    // 同步到你的IoT平台
                    syncToIoTPlatform(tuyaUid, phone, callback)
                }
                override fun onError(code: String, error: String) {
                    callback.onError(code, error)
                }
            }
        )
    }
    
    // 同步到IoT平台
    private fun syncToIoTPlatform(tuyaUid: String, phone: String,
                                   callback: IResultCallback) {
        // 调用你的后端API，关联涂鸦账号
        IoTPlatformApi.login(tuyaUid, phone, object : ApiCallback {
            override fun onSuccess(token: String) {
                // 保存双平台token
                TokenManager.saveIoTToken(token)
                callback.onSuccess()
            }
            override fun onError(code: String, msg: String) {
                callback.onError(code, msg)
            }
        })
    }
}
```

### Step 4: 家庭与设备管理（3天）

```kotlin
// 家庭管理 - 统一管理涂鸦家庭和你的平台家庭
class HomeManager {
    
    // 获取家庭列表（涂鸦）
    fun getHomeList(callback: (List<HomeBean>) -> Unit) {
        ThingHomeSdk.getHomeManagerInstance()
            .queryHomeList(object : IThingHomeResultCallback {
                override fun onSuccess(homeBeans: MutableList<HomeBean>?) {
                    callback(homeBeans ?: emptyList())
                }
                override fun onError(errorCode: String?, error: String?) {
                    callback(emptyList())
                }
            })
    }
    
    // 创建家庭（涂鸦）
    fun createHome(name: String, rooms: List<String>, 
                   callback: (Boolean) -> Unit) {
        val map = HashMap<String, Any>()
        map["name"] = name
        map["rooms"] = rooms
        map["lon"] = 0.0
        map["lat"] = 0.0
        
        ThingHomeSdk.getHomeManagerInstance()
            .createHome(map, object : IResultCallback {
                override fun onSuccess() {
                    // 同步到IoT平台
                    syncHomeToPlatform(name, callback)
                }
                override fun onError(errorCode: String?, error: String?) {
                    callback(false)
                }
            })
    }
}

// 设备管理
class DeviceManager {
    
    // 获取家庭下的设备列表
    fun getDeviceList(homeId: Long, callback: (List<DeviceBean>) -> Unit) {
        val homeDetail = ThingHomeSdk.getDataInstance().getHomeBean(homeId)
        callback(homeDetail?.deviceList ?: emptyList())
    }
    
    // 设备控制 - 下发数据点
    fun publishDps(devId: String, dps: Map<String, Any>, 
                   callback: (Boolean) -> Unit) {
        val device = ThingHomeSdk.newDeviceInstance(devId)
        device.publishDps(JSONObject(dps), object : IResultCallback {
            override fun onSuccess() {
                // 同步状态到IoT平台
                syncDeviceState(devId, dps, callback)
            }
            override fun onError(errorCode: String?, error: String?) {
                callback(false)
            }
        })
    }
    
    // 监听设备状态变化
    fun registerDeviceListener(devId: String, 
                                listener: IDeviceListener) {
        val device = ThingHomeSdk.newDeviceInstance(devId)
        device.registerDeviceListener(listener)
    }
}
```

### Step 5: 设备配网（3天）

```kotlin
// 配网管理器 - 支持多种配网方式
class ActivatorManager {
    
    // Wi-Fi EZ配网（快连）
    fun startEZActivator(ssid: String, password: String, 
                          homeId: Long, callback: (Boolean) -> Unit) {
        val activator = ThingHomeSdk.getActivatorInstance()
            .newTuyaActivator(ActivatorBuilder()
                .setSsid(ssid)
                .setPassword(password)
                .setHomeId(homeId)
                .setContext(context)
                .setActivatorModel(ActivatorModelEnum.TY_EZ)
                .setTimeOut(100)
                .setListener(object : ITuyaSmartActivatorListener {
                    override fun onError(errorCode: String?, errorMsg: String?) {
                        callback(false)
                    }
                    override fun onActiveSuccess(devId: String?) {
                        // 配网成功，同步到IoT平台
                        syncNewDevice(devId!!, callback)
                    }
                    override fun onStep(step: String?, data: Any?) {}
                })
            )
        activator.start()
    }
    
    // Wi-Fi AP配网（热点）
    fun startAPActivator(ssid: String, password: String,
                          homeId: Long, callback: (Boolean) -> Unit) {
        val activator = ThingHomeSdk.getActivatorInstance()
            .newTuyaActivator(ActivatorBuilder()
                .setSsid(ssid)
                .setPassword(password)
                .setHomeId(homeId)
                .setContext(context)
                .setActivatorModel(ActivatorModelEnum.TY_AP)
                .setTimeOut(100)
                .setListener(object : ITuyaSmartActivatorListener {
                    override fun onError(errorCode: String?, errorMsg: String?) {
                        callback(false)
                    }
                    override fun onActiveSuccess(devId: String?) {
                        syncNewDevice(devId!!, callback)
                    }
                    override fun onStep(step: String?, data: Any?) {}
                })
            )
        activator.start()
    }
    
    // 蓝牙配网
    fun startBLEActivator(homeId: Long, callback: (Boolean) -> Unit) {
        // BLE配网逻辑
    }
    
    // Matter配网
    fun startMatterActivator(homeId: Long, callback: (Boolean) -> Unit) {
        // Matter配网逻辑
    }
}
```

### Step 6: 场景与联动（2天）

```kotlin
// 场景管理器 - 对接涂鸦场景 + 你的规则引擎
class SceneManager {
    
    // 获取场景列表
    fun getSceneList(homeId: Long, callback: (List<SceneBean>) -> Unit) {
        ThingHomeSdk.getSceneManagerInstance()
            .getSceneList(homeId, object : IThingResultCallback<SceneBean> {
                override fun onSuccess(result: SceneBean?) {
                    callback(listOfNotNull(result))
                }
                override fun onError(errorCode: String?, errorMsg: String?) {
                    callback(emptyList())
                }
            })
    }
    
    // 执行场景
    fun executeScene(homeId: Long, sceneId: String, 
                     callback: (Boolean) -> Unit) {
        ThingHomeSdk.getSceneManagerInstance()
            .executeScene(homeId, sceneId, object : IResultCallback {
                override fun onSuccess() {
                    callback(true)
                }
                override fun onError(errorCode: String?, errorMsg: String?) {
                    callback(false)
                }
            })
    }
    
    // 同时触发你的规则引擎
    fun executeSceneWithRule(sceneId: String, callback: (Boolean) -> Unit) {
        // 1. 执行涂鸦场景
        executeScene(homeId, sceneId) { success ->
            if (success) {
                // 2. 同步到你的规则引擎
                IoTPlatformApi.triggerRule(sceneId, callback)
            } else {
                callback(false)
            }
        }
    }
}
```

### Step 7: 数据同步桥接层（3天）

```kotlin
// 数据桥接 - 将涂鸦设备数据同步到你的IoT平台
class DataBridge {
    
    private val scope = CoroutineScope(Dispatchers.IO)
    
    // 初始化设备监听
    fun startDeviceMonitoring(homeId: Long) {
        val homeBean = ThingHomeSdk.getDataInstance().getHomeBean(homeId)
        homeBean?.deviceList?.forEach { device ->
            registerDeviceListener(device.devId)
        }
    }
    
    // 注册设备状态监听
    private fun registerDeviceListener(devId: String) {
        val device = ThingHomeSdk.newDeviceInstance(devId)
        device.registerDeviceListener(object : IDeviceListener {
            override fun onDpUpdate(devId: String?, dpStr: String?) {
                // 设备数据点更新 → 同步到IoT平台
                scope.launch {
                    syncDeviceData(devId, dpStr)
                }
            }
            override fun onRemoved(devId: String?) {
                // 设备被移除
                scope.launch { handleDeviceRemoved(devId) }
            }
            override fun onStatusChanged(devId: String?, online: Boolean) {
                // 设备在线状态变化
                scope.launch { handleDeviceStatusChange(devId, online) }
            }
            override fun onNetworkStatusChanged(devId: String?, status: Boolean) {}
            override fun onDevInfoUpdate(devId: String?) {}
        })
    }
    
    // 同步设备数据到IoT平台
    private suspend fun syncDeviceData(devId: String?, dpStr: String?) {
        if (devId == null || dpStr == null) return
        
        val dataPoint = DeviceDataPoint(
            deviceId = devId,
            data = JSONObject(dpStr).toMap(),
            timestamp = System.currentTimeMillis(),
            source = "tuya"
        )
        
        // 调用IoT平台数据采集API
        IoTPlatformApi.reportDeviceData(dataPoint)
    }
    
    // 同步设备在线状态
    private suspend fun handleDeviceStatusChange(devId: String?, online: Boolean) {
        if (devId == null) return
        IoTPlatformApi.updateDeviceStatus(devId, online)
    }
    
    // 处理设备移除
    private suspend fun handleDeviceRemoved(devId: String?) {
        if (devId == null) return
        IoTPlatformApi.removeDevice(devId)
    }
}
```

### Step 8: 告警通知对接（2天）

```kotlin
// 告警桥接 - 涂鸦告警 + 你的告警服务
class AlarmBridge {
    
    // 监听涂鸦设备告警
    fun startAlarmMonitoring(homeId: Long) {
        // 方式1：监听设备状态异常
        val homeBean = ThingHomeSdk.getDataInstance().getHomeBean(homeId)
        homeBean?.deviceList?.forEach { device ->
            monitorDeviceAlarm(device)
        }
        
        // 方式2：轮询你的告警服务
        startAlarmPolling()
    }
    
    // 监听设备告警
    private fun monitorDeviceAlarm(device: DeviceBean) {
        val deviceInstance = ThingHomeSdk.newDeviceInstance(device.devId)
        deviceInstance.registerDeviceListener(object : IDeviceListener {
            override fun onDpUpdate(devId: String?, dpStr: String?) {
                // 检查是否触发告警规则
                checkAlarmRules(devId, dpStr)
            }
            // ...其他方法
        })
    }
    
    // 检查告警规则
    private fun checkAlarmRules(devId: String?, dpStr: String?) {
        scope.launch {
            // 调用IoT平台告警检测API
            val result = IoTPlatformApi.checkAlarm(devId, dpStr)
            if (result.hasAlarm) {
                showAlarmNotification(result)
            }
        }
    }
    
    // 显示告警通知
    private fun showAlarmNotification(alarm: AlarmResult) {
        val notification = NotificationCompat.Builder(context, CHANNEL_ID)
            .setContentTitle("设备告警")
            .setContentText(alarm.message)
            .setSmallIcon(R.drawable.ic_alarm)
            .setAutoCancel(true)
            .build()
        
        NotificationManagerCompat.from(context)
            .notify(alarm.id.hashCode(), notification)
    }
}
```

---

## 五、项目目录结构

```
app/
├── src/main/
│   ├── java/com/iotsaas/
│   │   ├── IotApplication.kt                    # Application初始化
│   │   ├── bridge/                               # 桥接层
│   │   │   ├── DataBridge.kt                     # 数据同步桥接
│   │   │   ├── AlarmBridge.kt                    # 告警桥接
│   │   │   └── DeviceSyncBridge.kt               # 设备同步桥接
│   │   ├── tuya/                                 # 涂鸦SDK封装
│   │   │   ├── TuyaManager.kt                    # 涂鸦SDK管理器
│   │   │   ├── TuyaLoginHelper.kt                # 登录帮助类
│   │   │   ├── TuyaHomeHelper.kt                 # 家庭管理帮助类
│   │   │   ├── TuyaDeviceHelper.kt               # 设备管理帮助类
│   │   │   ├── TuyaActivatorHelper.kt            # 配网帮助类
│   │   │   ├── TuyaSceneHelper.kt                # 场景帮助类
│   │   │   └── TuyaMatterHelper.kt               # Matter帮助类
│   │   ├── platform/                              # IoT平台SDK封装
│   │   │   ├── IoTPlatformApi.kt                 # 平台API
│   │   │   ├── IoTPlatformConfig.kt              # 平台配置
│   │   │   └── model/                            # 数据模型
│   │   ├── ui/                                    # UI层
│   │   │   ├── login/                            # 登录页
│   │   │   ├── home/                             # 首页
│   │   │   ├── device/                           # 设备管理
│   │   │   ├── scene/                            # 场景管理
│   │   │   ├── alarm/                            # 告警管理
│   │   │   └── profile/                          # 个人中心
│   │   └── util/                                  # 工具类
│   ├── res/                                       # 资源文件
│   └── assets/                                    # 涂鸦SDK资源
│       ├── configList.json                        # 涂鸦配置
│       ├── thing_plugin_config.json               # 插件配置
│       └── module_app.json                        # 模块配置
├── libs/
│   └── security-algorithm-1.0.0-beta.aar          # 安全组件
└── build.gradle
```

---

## 六、开发排期

| 阶段 | 内容 | 工期 | 优先级 |
|------|------|------|--------|
| **Phase 1** | 涂鸦平台准备 + SDK集成 + 初始化 | 3天 | ⭐⭐⭐ |
| **Phase 2** | 用户登录 + 双平台账号关联 | 2天 | ⭐⭐⭐ |
| **Phase 3** | 家庭管理 + 设备列表 | 3天 | ⭐⭐⭐ |
| **Phase 4** | 设备配网（Wi-Fi/BLE） | 3天 | ⭐⭐⭐ |
| **Phase 5** | 设备控制 + 状态监听 | 3天 | ⭐⭐⭐ |
| **Phase 6** | 数据同步桥接层 | 3天 | ⭐⭐ |
| **Phase 7** | 场景联动 + 规则引擎对接 | 2天 | ⭐⭐ |
| **Phase 8** | 告警通知对接 | 2天 | ⭐⭐ |
| **Phase 9** | Matter设备配网 | 2天 | ⭐⭐ |
| **Phase 10** | UI优化 + 测试 | 3天 | ⭐ |
| **合计** | | **26天** | |

---

## 七、注意事项与风险

### 7.1 关键注意点

1. **包名一致性**：APP的 `applicationId` 必须与涂鸦平台配置完全一致
2. **SHA256指纹**：签名文件的SHA256必须在涂鸦平台配置
3. **安全组件**：`security-algorithm.aar` 必须与AppKey/AppSecret配套使用
4. **试用版限制**：试用版SDK启动时会弹出位置权限和Toast提示
5. **版本升级**：本地SDK 7.5.0 → 建议升级到 Maven 最新 7.5.1

### 7.2 风险与应对

| 风险 | 可能性 | 应对措施 |
|------|--------|----------|
| 涂鸦SDK版本升级导致API变更 | 中 | 关注更新日志，锁定SDK版本 |
| 涂鸦云服务不稳定 | 低 | 本地缓存 + 重试机制 |
| 双平台数据同步延迟 | 中 | WebSocket实时推送 + 定时轮询 |
| Matter设备兼容性 | 中 | 充分测试，关注官方更新 |
| 安全组件校验失败 | 中 | 严格检查AppKey/包名/SHA256 |

### 7.3 参考资源

- 涂鸦官方文档: https://developer.tuya.com/cn/docs/app-development/preparation
- 涂鸦Demo(Kotlin): https://github.com/tuya/tuya-home-android-sdk-sample-kotlin
- 涂鸦论坛: https://www.tuyaos.com/
- 更新日志: https://developer.tuya.com/cn/docs/app-development/changelog

---

**文档版本**: v1.0  
**创建日期**: 2026-04-27  
**作者**: IoT Platform Team