feat: 初始化小米 IoT (MIoT) 智能家居 Go 库

- 实现 MIoT 客户端核心功能（MQTT 连接、设备管理、属性读写） - 支持云端 API 调用与局域网设备发现（mDNS） - 集成国际化（i18n）多语言支持 - 添加 MIoT 设备规约解析器（spec_parser） - 包含单元测试与使用示例
2026-06-28 22:05:49 +08:00
parent ac442812b4
commit 3a44cb9e6a
118 changed files with 31630 additions and 0 deletions
@@ -0,0 +1,165 @@
+# 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 需要其他方案
+
+**建议**：
+```go
+// 方案1：不使用表达式（推荐）
+// 在 Go 版本中不支持 expr，直接返回原值
+
+// 方案2：使用表达式求值库
+// 使用 github.com/expr-lang/expr
+```
+
+### 2. 多语言翻译
+
+**问题**：需要管理多语言描述
+
+**建议**：
+```go
+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
+**负责人**：待定