# 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
**负责人**：待定