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,174 @@
+# 13 - miot_mdns.py 移植计划
+
+## 概览
+
+| 项目 | 内容 |
+|------|------|
+| **Python 文件** | `py-miot/miot_mdns.py` (286行) |
+| **Go 文件** | ❌ 缺失 |
+| **状态** | ❌ 完全缺失 |
+| **优先级** | 🟢 P2 |
+| **预计工作量** | 6-8 小时 |
+
+## Python 版本核心类
+
+### 数据类
+
+| 类名 | 行号 | 功能 | Go 状态 |
+|------|------|------|---------|
+| `MipsServiceState` | 76 | 服务状态枚举（ADDED/REMOVED/UPDATED） | ❌ 缺失 |
+| `MipsServiceData` | 82 | 服务数据（profile 解析） | ❌ 缺失 |
+
+### 主类
+
+| 类名 | 行号 | 功能 | Go 状态 |
+|------|------|------|---------|
+| `MipsService` | 147 | mDNS 服务发现 | ❌ 缺失 |
+
+### 核心方法
+
+| 方法名 | 行号 | 功能 | Go 状态 |
+|--------|------|------|---------|
+| `init_async` | 167 | 初始化 Zeroconf 浏览器 | ❌ 缺失 |
+| `deinit_async` | 176 | 清理资源 | ❌ 缺失 |
+| `get_services` | 181 | 获取服务列表 | ❌ 缺失 |
+| `sub_service_change` | 208 | 订阅服务变化 | ❌ 缺失 |
+| `unsub_service_change` | 216 | 取消订阅 | ❌ 缺失 |
+| `__on_service_state_change` | 223 | 状态变化回调 | ❌ 缺失 |
+| `__request_service_info_async` | 243 | 请求服务信息 | ❌ 缺失 |
+
+## Go 版本现状
+
+整个 `miot_mdns.py` 模块在 Go 版本中完全缺失。
+
+### 缺失的核心功能
+
+1. **mDNS 服务发现**
+   - 基于 Zeroconf/bonjour 协议
+   - 发现 MIoT 中央 hub 网关
+
+2. **服务数据解析**
+   - 解析 mDNS profile 数据
+   - 提取设备 ID、组 ID、角色等信息
+
+3. **服务状态管理**
+   - 服务添加/更新/删除
+   - 订阅和通知机制
+
+## 移植建议
+
+### 第一批任务（数据解析）
+
+1. **实现服务数据解析** (2小时)
+   - `MipsServiceData` → `MipsServiceData`
+   - Profile 解析（Base64 解码）
+   - 提取 did、group_id、role、suite_mqtt
+
+2. **实现服务状态管理** (1小时)
+   - `MipsServiceState` → `MipsServiceState` 枚举
+   - 状态变化通知
+
+### 第二批任务（服务发现）
+
+3. **实现 mDNS 客户端** (2小时)
+   - 使用 Go 的 mDNS 库（如 `github.com/hashicorp/mdns`）
+   - 实现服务发现和监听
+
+4. **实现订阅管理** (1小时)
+   - `sub_service_change` → `SubscribeServiceChange`
+   - `unsub_service_change` → `UnsubscribeServiceChange`
+
+### 第三批任务（测试）
+
+5. **单元测试** (1小时)
+   - 测试服务数据解析
+   - 测试服务发现（需要网络环境）
+
+## 技术难点
+
+### 1. mDNS 库选择
+
+**问题**：Python 使用 `python-zeroconf`，Go 需要选择对应的库
+
+**建议**：
+```go
+// 使用 github.com/hashicorp/mdns
+import "github.com/hashicorp/mdns"
+
+type MipsService struct {
+    server *mdns.Server
+    services map[string]*MipsServiceData
+}
+
+func (s *MipsService) Init() error {
+    // 创建 mDNS 浏览器
+    entriesCh := make(chan *mdns.ServiceEntry, 32)
+    go func() {
+        for entry := range entriesCh {
+            s.handleServiceEntry(entry)
+        }
+    }()
+    
+    return mdns.Lookup("_miot-central._tcp.local.", entriesCh)
+}
+```
+
+### 2. Profile 解析
+
+**问题**：需要解析二进制 profile 数据
+
+**建议**：
+```go
+import "encoding/binary"
+
+type MipsServiceData struct {
+    Name      string
+    Addresses []string
+    Port      int
+    Did       string
+    GroupID   string
+    Role      int
+    SuiteMQTT bool
+}
+
+func ParseProfile(profileB64 string) (*MipsServiceData, error) {
+    profileBin, err := base64.StdEncoding.DecodeString(profileB64)
+    if err != nil {
+        return nil, err
+    }
+    // 解析 did (1-8 bytes, big-endian)
+    did := binary.BigEndian.Uint64(profileBin[1:9])
+    // 解析 group_id (9-16 bytes, little-endian)
+    groupID := hex.EncodeToString(reverseBytes(profileBin[9:17]))
+    // 解析 role (byte 20, upper 4 bits)
+    role := int(profileBin[20] >> 4)
+    // 解析 suite_mqtt (byte 22, bit 1)
+    suiteMQTT := ((profileBin[22] >> 1) & 0x01) == 0x01
+    
+    return &MipsServiceData{...}, nil
+}
+```
+
+## 依赖关系
+
+| 依赖文件 | 关系 | 说明 |
+|---------|------|------|
+| `miot_error.py` | 强依赖 | 错误定义 |
+| `github.com/hashicorp/mdns` | 强依赖 | mDNS 库 |
+| `net` | 强依赖 | 网络操作 |
+
+## 进度跟踪
+
+- [ ] 实现服务数据解析 (预计 2小时)
+- [ ] 实现服务状态管理 (预计 1小时)
+- [ ] 实现 mDNS 客户端 (预计 2小时)
+- [ ] 实现订阅管理 (预计 1小时)
+- [ ] 单元测试 (预计 1小时)
+
+**总计**：7小时
+
+---
+
+**创建时间**：2026-06-28
+**最后更新**：2026-06-28
+**负责人**：待定