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