xiaomihome/miot/migration/09-miot-spec.md

09 - miot_spec.py 移植计划

概览

项目	内容
Python 文件	py-miot/miot_spec.py (939行)
Go 文件	spec_parser.go
状态	⚠️ 部分实现
优先级	🟡 P1
预计工作量	16-20 小时

Python 版本核心类

数据结构类

类名	行号	功能	Go 状态
MIoTSpecValueRange	65	数值范围（min/max/step）	❌ 缺失
MIoTSpecValueListItem	101	值列表项	❌ 缺失
MIoTSpecValueList	145	值列表	❌ 缺失

SPEC 基类

类名	行号	功能	Go 状态
_SpecStdLib	209	SPEC 标准库（多语言翻译）	❌ 缺失
_MIoTSpecBase	436	SPEC 基类	⚠️ 部分
MIoTSpecProperty	482	SPEC 属性	⚠️ 部分
MIoTSpecEvent	644	SPEC 事件	⚠️ 部分
MIoTSpecAction	672	SPEC 动作	⚠️ 部分
MIoTSpecService	704	SPEC 服务	⚠️ 部分
MIoTSpecInstance	731	SPEC 实例（设备）	⚠️ 部分

核心功能

功能	行号	说明	Go 状态
SPEC 解析	754	从 JSON 加载 SPEC	⚠️ 部分
标准库管理	296	从云端刷新标准库	❌ 缺失
多语言翻译	244-284	描述翻译	❌ 缺失
值格式化	599	值格式转换	⚠️ 部分
值精度处理	611	浮点数精度	❌ 缺失

Go 版本现状

已实现的功能

• SpecInstance 结构体（对应 MIoTSpecInstance）
• SpecService 结构体（对应 MIoTSpecService）
• 基本的 SPEC 解析

缺失的功能

1. 值范围和处理

   • MIoTSpecValueRange
   • MIoTSpecValueList

2. 标准库管理

   • 从云端下载标准库
   • 多语言翻译

3. 属性处理

   • 表达式求值（eval_expr）
   • 值精度处理（value_precision）

移植建议

第一批任务（核心数据结构）

1. 实现值范围类 (2小时)

   • MIoTSpecValueRange → SpecValueRange
   • MIoTSpecValueList → SpecValueList

2. 实现标准库管理 (4小时)

   • _SpecStdLib → SpecStdLib
   • 实现云端下载
   • 实现多语言翻译

第二批任务（属性处理）

3. 增强属性处理 (3小时)

   • 实现 eval_expr
   • 实现 value_precision
   • 实现 value_format

4. 实现序列化 (2小时)

   • dump() 方法
   • JSON 导出

第三批任务（优化和测试）

5. 优化性能 (2小时)

   • 缓存翻译结果
   • 优化 SPEC 解析

6. 单元测试 (3小时)

   • 测试值范围
   • 测试属性处理
   • 测试序列化

技术难点

1. 表达式求值

问题：Python 使用 eval()，Go 需要其他方案

建议：

// 方案1：不使用表达式（推荐）
// 在 Go 版本中不支持 expr，直接返回原值

// 方案2：使用表达式求值库
// 使用 github.com/expr-lang/expr

2. 多语言翻译

问题：需要管理多语言描述

建议：

type SpecStdLib struct {
    lang     string
    devices  map[string]map[string]string
    services map[string]map[string]string
    // ...
}

func (s *SpecStdLib) DeviceTranslate(key string) string {
    if translations, ok := s.devices[key]; ok {
        if desc, ok := translations[s.lang]; ok {
            return desc
        }
        // 回退到默认语言
        return translations[defaultLang]
    }
    return ""
}

依赖关系

依赖文件	关系	说明
miot_error.py	强依赖	错误定义
miot_storage.py	强依赖	标准库缓存
common.py	强依赖	HTTP 请求

进度跟踪

• 实现值范围类 (预计 2小时)
• 实现标准库管理 (预计 4小时)
• 增强属性处理 (预计 3小时)
• 实现序列化 (预计 2小时)
• 优化性能 (预计 2小时)
• 单元测试 (预计 3小时)

总计：16小时

---

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