xiaomihome/miot/migration/03-miot-cloud.md

03 - miot_cloud.py 移植计划

概览

项目	内容
Python 文件	py-miot/miot_cloud.py (270行)
Go 文件	❌ 缺失
状态	❌ 完全缺失
优先级	🔴 P0
预计工作量	10-14 小时

Python 版本分析

核心类

MIoTOauthClient（OAuth 客户端）

位置：第 73-228 行

主要职责：

• OAuth 认证流程管理
• 生成授权 URL
• 获取和刷新 access token
• 管理 token 过期时间

核心方法：

方法名	行号	功能	Go 状态
__init__	83	初始化 OAuth 客户端	❌ 缺失
gen_auth_url	121	生成授权 URL	❌ 缺失
get_access_token_async	193	使用授权码获取 access token	❌ 缺失
refresh_access_token_async	212	使用 refresh token 刷新 access token	❌ 缺失
deinit_async	112	清理资源	❌ 缺失

MIoTHttpClient（HTTP 客户端）

位置：第 231-538 行

主要职责：

• 封装小米 IoT 云端 API 调用
• 处理设备查询、属性读写、动作调用
• 管理 HTTP 请求和响应
• 处理 token 过期和刷新

核心方法：

方法名	行号	功能	Go 状态
__init__	246	初始化 HTTP 客户端	❌ 缺失
update_http_header	284	更新 HTTP 请求头	❌ 缺失
get_user_info_async	365	获取用户信息	❌ 缺失
get_central_cert_async	386	获取中央证书	❌ 缺失
get_homeinfos_async	459	获取家庭信息	❌ 缺失
get_separated_shared_devices_async	448	获取共享设备	❌ 缺失

Go 版本现状

缺失的功能

整个 miot_cloud.py 模块在 Go 版本中完全缺失。

Go 版本中相关的云端调用分散在：

• miot_client_api.go - 部分 API 调用
• http_client.go - HTTP 客户端

但是缺少统一的云端客户端封装。

移植建议

第一批任务（核心功能）

1. 创建 miot_cloud.go 文件 (1小时)

   • 定义 MIoTCloud 结构体
   • 实现构造函数

2. 实现登录功能 (2小时)

   • 实现 Login 方法
   • 集成 OAuth token 管理
   • 处理 token 过期和刷新

3. 实现设备查询 (2小时)

   • 实现 GetDevices 方法
   • 实现 GetDeviceInfo 方法
   • 解析设备列表 JSON

4. 实现属性读写 (2小时)

   • 实现 GetDeviceProp 方法
   • 实现 SetDeviceProp 方法
   • 处理批量读写

5. 实现动作调用 (2小时)

   • 实现 CallDeviceAction 方法
   • 处理同步和异步调用
   • 解析返回结果

第二批任务（辅助功能）

6. 实现 LAN 命令转发 (2小时)

   • 实现 SendLanCommand 方法
   • 通过云端转发 LAN 命令

7. 优化 HTTP 客户端 (1小时)

   • 集成 http_client.go
   • 实现重试机制
   • 实现错误处理

8. 实现请求签名 (2小时)

   • 实现 _build_url 功能
   • 实现请求签名算法
   • 处理 API 版本

技术难点

1. OAuth Token 管理

问题：需要处理 token 的存储、读取、刷新

建议：

type MIoTCloud struct {
    // ...
    oauthClient *MIoTOAuth
    token       *OAuthToken
}

func (c *MIoTCloud) Login() error {
    // 尝试从存储加载 token
    token, err := c.storage.LoadToken()
    if err == nil && !token.IsExpired() {
        c.token = token
        return nil
    }
    
    // 刷新 token
    token, err = c.oauthClient.RefreshToken(token)
    if err != nil {
        return err
    }
    
    c.token = token
    return c.storage.SaveToken(token)
}

2. API 请求签名

问题：小米 IoT 云端 API 需要签名

建议：

• 参考 Python 版本的 _build_url 实现
• 实现签名算法（MD5、nonce、timestamp）
• 处理 API 版本差异

3. 错误处理

问题：云端 API 可能返回各种错误

建议：

type CloudError struct {
    Code    int
    Message string
}

func (e *CloudError) Error() string {
    return fmt.Sprintf("cloud error: code=%d, message=%s", e.Code, e.Message)
}

func (c *MIoTCloud) handleResponse(resp *http.Response) (interface{}, error) {
    // 解析响应
    // 检查错误码
    // 返回结果或错误
}

测试计划

单元测试

1. 登录测试

   • 测试 token 加载
   • 测试 token 刷新
   • 测试登录失败

2. 设备查询测试

   • 测试获取设备列表
   • 测试获取设备信息
   • 测试解析错误

3. 属性读写测试

   • 测试获取属性
   • 测试设置属性
   • 测试批量操作

4. 动作调用测试

   • 测试调用动作
   • 测试参数验证
   • 测试结果解析

集成测试

1. 端到端测试
   • 使用真实账号测试
   • 测试完整流程：登录 → 查询 → 控制

依赖关系

依赖文件	关系	说明
miot_oauth.py	强依赖	OAuth 认证
miot_storage.py	强依赖	Token 存储
http_client.go	强依赖	HTTP 客户端

移植优先级

任务	优先级	理由
创建基础结构	🔴 高	基础框架
实现登录功能	🔴 高	核心功能，其他功能依赖
实现设备查询	🔴 高	核心功能
实现属性读写	🔴 高	核心功能
实现动作调用	🔴 高	核心功能
实现 LAN 命令转发	🟡 中	高级功能
优化 HTTP 客户端	🟡 中	优化功能
实现请求签名	🟡 中	必要功能

进度跟踪

• 创建 miot_cloud.go 文件 (预计 1小时)
• 实现登录功能 (预计 2小时)
• 实现设备查询 (预计 2小时)
• 实现属性读写 (预计 2小时)
• 实现动作调用 (预计 2小时)
• 实现 LAN 命令转发 (预计 2小时)
• 优化 HTTP 客户端 (预计 1小时)
• 实现请求签名 (预计 2小时)
• 单元测试 (预计 4小时)
• 集成测试 (预计 2小时)

总计：20小时

---

创建时间：2026-06-28 最后更新：2026-06-28 负责人：待定