xiaomihome/miot/migration/02-miot-device.md

# 02 - miot_device.py 移植计划

## 概览

| 项目 | 内容 |
|------|------|
| **Python 文件** | `py-miot/miot_device.py` (469行) |
| **Go 文件** | `go-miot/miot_device.go` |
| **状态** | ⚠️ 部分实现 |
| **优先级** | 🔴 P0 |
| **预计工作量** | 6-10 小时 |

## Python 版本分析

### 核心类

#### MIoTDevice

**位置**：第 18-469 行

**主要职责**：
- 表示单个小米 IoT 设备
- 管理设备的属性、方法、事件
- 提供设备控制和查询接口

**核心方法**：

| 方法名 | 行号 | 功能 | Go 状态 |
|--------|------|------|---------|
| `__init__` | 18 | 初始化设备对象 | ✅ 已完成 |
| `from_dict` | 45 | 从字典创建设备对象 | ✅ 已完成 |
| `to_dict` | 78 | 转换为字典 | ✅ 已完成 |
| `get_property` | 112 | 获取属性值 | ✅ 已完成 |
| `set_property` | 139 | 设置属性值（本地缓存） | ✅ 已完成 |
| `call_action` | 167 | 调用设备动作 | ⚠️ 部分实现 |
| `get_service` | 223 | 获取服务定义 | ❌ 缺失 |
| `get_property_def` | 251 | 获取属性定义 | ❌ 缺失 |
| `get_action_def` | 279 | 获取动作定义 | ❌ 缺失 |
| `refresh` | 307 | 从云端刷新属性 | ⚠️ 部分实现 |
| `to_string` | 365 | 转换为可读字符串 | ✅ 已完成 |
| `to_json` | 401 | 转换为 JSON | ✅ 已完成 |

### 辅助类

#### DeviceProperty

**位置**：第 415-450 行

**功能**：表示设备属性的元数据

**Go 状态**：✅ 已完成（对应 `Property` 结构体）

#### DeviceService

**位置**：第 451-469 行

**功能**：表示设备服务的元数据

**Go 状态**：❌ 缺失

## Go 版本现状

### 已实现的结构体

```go
type MIoTDevice struct {
    DID          string
    Name         string
    Model        string
    Token        string
    IPAddress    string
    Port         int
    Properties   map[string]interface{}
    PropertyDefs map[string]*Property
    // ...
}
```

### 缺失的功能

#### 1. 服务定义查询 (`get_service`, `get_property_def`, `get_action_def`)

**Python 实现**：
```python
def get_service(self, service_id: str) -> dict:
    """获取服务定义"""
    spec = self._get_spec()
    return spec.get_service(service_id)

def get_property_def(self, siid: int, piid: int) -> dict:
    """获取属性定义"""
    spec = self._get_spec()
    return spec.get_property(siid, piid)
```

**Go 缺失**：
- ❌ 服务定义查询
- ❌ 属性定义查询
- ❌ 动作定义查询
- ❌ SPEC 集成

#### 2. 完整的 `call_action` 实现

**Python 实现**：
- 支持同步和异步调用
- 支持参数验证
- 支持结果解析

**Go 缺失**：
- ⚠️ 参数验证
- ⚠️ 结果解析
- ❌ 异步调用支持

#### 3. `DeviceService` 类

**Python 实现**：
```python
class DeviceService:
    """设备服务元数据"""
    def __init__(self, siid: int, type: str):
        self.siid = siid
        self.type = type
```

**Go 缺失**：
- ❌ `DeviceService` 结构体
- ❌ 服务元数据管理

## 移植建议

### 第一批任务（核心功能）

1. **集成 SPEC 查询** (3小时)
   - 实现 `GetService` 方法
   - 实现 `GetPropertyDef` 方法
   - 实现 `GetActionDef` 方法
   - 集成 `spec_parser.go`

2. **补全 `CallAction`** (2小时)
   - 实现参数验证
   - 实现结果解析
   - 实现异步调用支持（可选）

### 第二批任务（辅助功能）

3. **实现 `DeviceService` 结构体** (1小时)
   - 定义结构体
   - 实现构造函数
   - 实现查询方法

4. **优化属性管理** (2小时)
   - 改进属性缓存机制
   - 实现属性变更通知
   - 实现属性历史记录（可选）

## 技术难点

### 1. SPEC 集成

**问题**：需要从 SPEC 文件查询服务和属性定义

**建议**：
```go
type MIoTDevice struct {
    // ...
    specParser *SpecParser
}

func (d *MIoTDevice) GetService(serviceID string) (*Service, error) {
    if d.specParser == nil {
        return nil, errors.New("spec parser not initialized")
    }
    return d.specParser.GetService(serviceID)
}
```

### 2. 属性缓存同步

**问题**：本地缓存的属性值需要与云端同步

**建议**：
- 实现 `Refresh` 方法，从云端刷新属性
- 实现属性变更通知机制
- 使用时间戳判断属性是否过期

### 3. 动作调用的异步支持

**问题**：某些设备动作可能需要较长时间执行

**建议**：
```go
// 同步调用
func (d *MIoTDevice) CallAction(siid, aiid int, params map[string]interface{}) (map[string]interface{}, error)

// 异步调用
func (d *MIoTDevice) CallActionAsync(siid, aiid int, params map[string]interface{}) <-chan ActionResult
```

## 测试计划

### 单元测试

1. **设备创建测试**
   - 测试从字典创建
   - 测试转换为字典
   - 测试属性管理

2. **属性查询测试**
   - 测试 `GetProperty`
   - 测试 `SetProperty`
   - 测试 `Refresh`

3. **动作调用测试**
   - 测试 `CallAction`
   - 测试参数验证
   - 测试结果解析

### 集成测试

1. **端到端测试**
   - 使用真实设备测试
   - 测试完整流程：创建 → 查询 → 控制

## 依赖关系

| 依赖文件 | 关系 | 说明 |
|---------|------|------|
| `miot_spec.py` | 强依赖 | SPEC 查询 |
| `miot_client.py` | 弱依赖 | 客户端调用 |

## 移植优先级

| 任务 | 优先级 | 理由 |
|------|--------|------|
| 集成 SPEC 查询 | 🔴 高 | 核心功能，影响属性查询 |
| 补全 `CallAction` | 🔴 高 | 核心功能，影响设备控制 |
| 实现 `DeviceService` | 🟡 中 | 辅助功能，提升可用性 |
| 优化属性管理 | 🟢 低 | 优化功能，可选 |

## 进度跟踪

- [ ] 集成 SPEC 查询 (预计 3小时)
- [ ] 补全 `CallAction` (预计 2小时)
- [ ] 实现 `DeviceService` 结构体 (预计 1小时)
- [ ] 优化属性管理 (预计 2小时)
- [ ] 单元测试 (预计 3小时)
- [ ] 集成测试 (预计 2小时)

**总计**：13小时

---

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