4566704
3a44cb9e6a
- 实现 MIoT 客户端核心功能（MQTT 连接、设备管理、属性读写） - 支持云端 API 调用与局域网设备发现（mDNS） - 集成国际化（i18n）多语言支持 - 添加 MIoT 设备规约解析器（spec_parser） - 包含单元测试与使用示例
249 lines
6.0 KiB
Markdown
249 lines
6.0 KiB
Markdown
# 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 的存储、读取、刷新
|
||
|
||
**建议**：
|
||
```go
|
||
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 可能返回各种错误
|
||
|
||
**建议**：
|
||
```go
|
||
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
|
||
**负责人**：待定
|