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 版本现状

已实现的结构体

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 实现：

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 实现：

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 文件查询服务和属性定义

建议：

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. 动作调用的异步支持

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

建议：

// 同步调用
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 负责人：待定